LDSwiftEventSource

https://launchdarkly.github.io/swift-eventsource
Admin
LDSwiftEventSource is a cross-platform implementation of the EventSource specification written in...
Tokens:3,745
Snippets:57
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install via Carthage

Source: https://launchdarkly.github.io/swift-eventsource/index.html

Add this line to your Cartfile to integrate the library using Carthage.

```text
github "LaunchDarkly/swift-eventsource" ~> 3.2
```

--------------------------------

### Start EventSource Connection

Source: https://launchdarkly.github.io/swift-eventsource/Classes/EventSource.html

Initiates the streaming connection to the configured URL.

```Swift
public func start()
```

--------------------------------

### Install via CocoaPods

Source: https://launchdarkly.github.io/swift-eventsource/index.html

Add this line to your Podfile to integrate the library using CocoaPods.

```ruby
pod 'LDSwiftEventSource', '~> 3.2'
```

--------------------------------

### Install via Swift Package Manager

Source: https://launchdarkly.github.io/swift-eventsource/index.html

Add this dependency to your Package.swift file to include the library in your Swift package.

```swift
dependencies: [
    .package(url: "https://github.com/LaunchDarkly/swift-eventsource.git", .upToNextMajor(from: "3.2.0"))
]
```

--------------------------------

### EventSource Class Methods

Source: https://launchdarkly.github.io/swift-eventsource/Classes/EventSource.html

Methods for initializing, starting, stopping, and retrieving state from the EventSource client.

```APIDOC
## init(config:)

### Description
Initialize the EventSource client with the given configuration.

### Parameters
- **config** (Config) - Required - The configuration for initializing the EventSource client.

## start()

### Description
Start the EventSource client. This will initiate a streaming connection to the configured URL. The application will be informed of received events and state changes using the configured EventHandler.

## stop()

### Description
Shuts down the EventSource client. It is not valid to restart the client after calling this function.

## getLastEventId()

### Description
Get the most recently received event ID, or the value of EventSource.Config.lastEventId if no event IDs have been received.

### Response
- **String?** - The last event ID or nil.
```

--------------------------------

### Handle Stream Opened Event

Source: https://launchdarkly.github.io/swift-eventsource/Protocols/EventHandler.html

Called when the SSE stream connection has been successfully opened. No setup is required beyond implementing this method.

```swift
func onOpened()
```

--------------------------------

### Handle SSE Comment Line

Source: https://launchdarkly.github.io/swift-eventsource/Protocols/EventHandler.html

Called when a comment line (lines starting with ':') is received from the SSE stream. Comments are ignored by default but can be processed if needed.

```swift
func onComment(comment: String)
```

--------------------------------

### Get Last Event ID

Source: https://launchdarkly.github.io/swift-eventsource/Classes/EventSource.html

Retrieves the most recently received event ID or the initial configured ID.

```Swift
public func getLastEventId() -> String?
```

--------------------------------

### Initialize Config

Source: https://launchdarkly.github.io/swift-eventsource/Classes/EventSource/Config.html

Create a new configuration instance with a required handler and URL.

```Swift
public init(handler: EventHandler, url: URL)
```

--------------------------------

### Build and Test with SwiftPM

Source: https://launchdarkly.github.io/swift-eventsource/contributing.html

Use this command to build and run tests for the LDSwiftEventSource library using the Swift Package Manager.

```bash
swift test

```

--------------------------------

### Initialize EventSource

Source: https://launchdarkly.github.io/swift-eventsource/Classes/EventSource.html

Initializes the client with a specific configuration.

```Swift
public init(config: Config)
```

--------------------------------

### Generate API Documentation

Source: https://launchdarkly.github.io/swift-eventsource/contributing.html

Run this command to generate API documentation for the LDSwiftEventSource library using jazzy. Ensure documentation coverage remains at 100%.

```bash
jazzy

```

--------------------------------

### Run Contract Tests

Source: https://launchdarkly.github.io/swift-eventsource/contributing.html

Execute the standardized contract tests for all LaunchDarkly SSE client implementations using this command.

```bash
make contract-tests

```

--------------------------------

### Config Struct Initialization

Source: https://launchdarkly.github.io/swift-eventsource/Classes/EventSource/Config.html

Defines the configuration structure for the EventSource, including required handler and URL parameters.

```APIDOC
## Config Struct

### Description
Struct for configuring the EventSource.

### Properties
- **handler** (EventHandler) - Required - The EventHandler called in response to activity on the stream.
- **url** (URL) - Required - The URL of the request used when connecting to the EventSource API.
- **method** (String) - Optional - The HTTP method to use for the API request.
- **body** (Data?) - Optional - Optional HTTP body to be included in the API request.
- **lastEventId** (String) - Optional - An initial value for the last-event-id header to be sent on the initial request.
- **headers** ([String : String]) - Optional - Additional HTTP headers to be set on the request.
- **headerTransform** (HeaderTransform) - Optional - Transform function to allow dynamically configuring the headers on each API request.
- **reconnectTime** (TimeInterval) - Optional - The minimum amount of time to wait before reconnecting after a failure.
- **maxReconnectTime** (TimeInterval) - Optional - The maximum amount of time to wait before reconnecting after a failure.
- **backoffResetThreshold** (TimeInterval) - Optional - The minimum amount of time for an EventSource connection to remain open before allowing the connection backoff to reset.
- **idleTimeout** (TimeInterval) - Optional - The maximum amount of time between receiving any data before considering the connection to have timed out.
- **urlSessionConfiguration** (URLSessionConfiguration) - Optional - The URLSessionConfiguration used to create the URLSession.
- **connectionErrorHandler** (ConnectionErrorHandler) - Optional - An error handler that is called when an error occurs and can shut down the client in response.

### Initialization
```swift
public init(handler: EventHandler, url: URL)
```
```

--------------------------------

### ReadyState Enumeration Cases

Source: https://launchdarkly.github.io/swift-eventsource/Enums/ReadyState.html

Individual cases representing the various connection states of the EventSource client.

```Swift
case raw
```

```Swift
case connecting
```

```Swift
case open
```

```Swift
case closed
```

```Swift
case shutdown
```

--------------------------------

### ReadyState Enumeration

Source: https://launchdarkly.github.io/swift-eventsource/Enums/ReadyState.html

Defines the possible states of an EventSource client connection.

```APIDOC
## ReadyState Enumeration

### Description
Represents the current state of an EventSource client connection.

### Declaration
`public enum ReadyState : String, Equatable`

### Values
- **raw**: The EventSource client has not been started yet.
- **connecting**: The EventSource client is attempting to make a connection.
- **open**: The EventSource client is active and listening for events.
- **closed**: The connection has been closed or has failed, and the EventSource will attempt to reconnect.
- **shutdown**: The connection has been permanently closed and the EventSource will not reconnect.
```

--------------------------------

### ReadyState Enumeration

Source: https://launchdarkly.github.io/swift-eventsource/Enums.html

Represents the various states of an EventSource connection.

```APIDOC
## ReadyState

### Description
Enum values representing the states of an EventSource.

### Declaration
```swift
public enum ReadyState : String, Equatable
```
```

--------------------------------

### Define Config Struct

Source: https://launchdarkly.github.io/swift-eventsource/Classes/EventSource.html

Configuration structure for the EventSource client.

```Swift
public struct Config
```

--------------------------------

### Initialize UnsuccessfulResponseError

Source: https://launchdarkly.github.io/swift-eventsource/Classes/UnsuccessfulResponseError.html

Constructor for creating an instance of UnsuccessfulResponseError with a specific response code.

```Swift
public init(responseCode: Int)
```

--------------------------------

### Configure EventSource properties

Source: https://launchdarkly.github.io/swift-eventsource/Classes/EventSource/Config.html

Individual properties for configuring the EventSource connection and behavior.

```Swift
public let handler: EventHandler
```

```Swift
public let url: URL
```

```Swift
public var method: String
```

```Swift
public var body: Data?
```

```Swift
public var lastEventId: String
```

```Swift
public var headers: [String : String]
```

```Swift
public var headerTransform: HeaderTransform
```

```Swift
public var reconnectTime: TimeInterval
```

```Swift
public var maxReconnectTime: TimeInterval
```

```Swift
public var backoffResetThreshold: TimeInterval
```

```Swift
public var idleTimeout: TimeInterval
```

```Swift
public var urlSessionConfiguration: URLSessionConfiguration { get set }
```

```Swift
public var connectionErrorHandler: ConnectionErrorHandler
```

--------------------------------

### EventSource Class

Source: https://launchdarkly.github.io/swift-eventsource/Classes.html

Provides an EventSource client for consuming Server-Sent Events.

```APIDOC
## EventSource Class

### Description
Provides an EventSource client for consuming Server-Sent Events. Refer to the Server-Sent Events specification for more details.

### Declaration
Swift
```swift
public class EventSource
```
```

--------------------------------

### MessageEvent Initializer

Source: https://launchdarkly.github.io/swift-eventsource/Structs/MessageEvent.html

Constructor for creating a new MessageEvent instance.

```Swift
public init(data: String, lastEventId: String = "")
```

--------------------------------

### Declare ConnectionErrorAction Enumeration

Source: https://launchdarkly.github.io/swift-eventsource/Enums/ConnectionErrorAction.html

Defines the possible actions for handling connection errors. Use 'proceed' to log and dispatch the error normally, allowing retries. Use 'shutdown' to immediately terminate the connection without retrying or dispatching to the EventHandler.

```swift
public enum ConnectionErrorAction
```

```swift
case proceed
```

```swift
case shutdown
```

--------------------------------

### Define EventSource Class

Source: https://launchdarkly.github.io/swift-eventsource/Classes/EventSource.html

The primary class for consuming Server-Sent Events.

```Swift
public class EventSource
```

--------------------------------

### ReadyState Enum Declaration

Source: https://launchdarkly.github.io/swift-eventsource/Enums.html

Defines the possible states of an EventSource connection. This enum is String convertible and Equatable, useful for tracking connection status.

```swift
public enum ReadyState : String, Equatable
```

--------------------------------

### Define EventHandler Protocol

Source: https://launchdarkly.github.io/swift-eventsource/Protocols/EventHandler.html

Defines the protocol for objects that will receive SSE events. Implement these methods to handle different types of events from the stream.

```swift
public protocol EventHandler
```

--------------------------------

### Stop EventSource Connection

Source: https://launchdarkly.github.io/swift-eventsource/Classes/EventSource.html

Shuts down the client; restarting is not supported after this call.

```Swift
public func stop()
```

--------------------------------

### Define UnsuccessfulResponseError Class

Source: https://launchdarkly.github.io/swift-eventsource/Classes/UnsuccessfulResponseError.html

Defines the error class structure for handling unsuccessful HTTP responses.

```Swift
public class UnsuccessfulResponseError : Error
```

--------------------------------

### EventHandler Protocol

Source: https://launchdarkly.github.io/swift-eventsource/Protocols.html

The EventHandler protocol is designed for objects that will receive Server-Sent Events (SSE).

```APIDOC
## EventHandler Protocol

### Description
Protocol for an object that will receive SSE events.

### Declaration
Swift
```swift
public protocol EventHandler
```
```

--------------------------------

### ConnectionErrorAction Enumeration

Source: https://launchdarkly.github.io/swift-eventsource/Enums.html

Defines the potential actions that a ConnectionErrorHandler can return to manage connection errors.

```APIDOC
## ConnectionErrorAction

### Description
Potential actions a ConnectionErrorHandler can return.

### Declaration
```swift
public enum ConnectionErrorAction
```
```

--------------------------------

### UnsuccessfulResponseError Class

Source: https://launchdarkly.github.io/swift-eventsource/Classes.html

Error class that indicates the remote server returned an unsuccessful HTTP response code.

```APIDOC
## UnsuccessfulResponseError Class

### Description
Error class that indicates the remote server returned an unsuccessful HTTP response code.

### Declaration
Swift
```swift
public class UnsuccessfulResponseError : Error
```
```

--------------------------------

### Handle Network or Protocol Errors

Source: https://launchdarkly.github.io/swift-eventsource/Protocols/EventHandler.html

Called for exceptions occurring on the network connection, including unsuccessful HTTP responses. This is called after any ConnectionErrorHandler has processed the error. Use this for logging or attempting recovery.

```swift
func onError(error: Error)
```

--------------------------------

### Handle Incoming SSE Message

Source: https://launchdarkly.github.io/swift-eventsource/Protocols/EventHandler.html

Called when a new SSE event message is received from the stream. Use this to process the event type and its associated data.

```swift
func onMessage(eventType: String, messageEvent: MessageEvent)
```

--------------------------------

### ConnectionErrorAction Enumeration

Source: https://launchdarkly.github.io/swift-eventsource/Enums/ConnectionErrorAction.html

Defines the possible actions a ConnectionErrorHandler can return to control the lifecycle of the event source connection.

```APIDOC
## ConnectionErrorAction

### Description
An enumeration representing the actions a `ConnectionErrorHandler` can return to dictate how the `LDSwiftEventSource` should respond to a connection error.

### Declaration
`public enum ConnectionErrorAction`

### Cases
- **proceed**: Specifies that the error should be logged normally and dispatched to the `EventHandler`. Connection retrying will proceed normally if appropriate.
- **shutdown**: Specifies that the connection should be immediately shut down and not retried. The error will not be dispatched to the `EventHandler`.
```

--------------------------------

### Access Response Code Property

Source: https://launchdarkly.github.io/swift-eventsource/Classes/UnsuccessfulResponseError.html

Provides the HTTP response code associated with the error.

```Swift
public let responseCode: Int
```

--------------------------------

### MessageEvent Structure Definition

Source: https://launchdarkly.github.io/swift-eventsource/Structs/MessageEvent.html

The primary structure representing a received event.

```Swift
public struct MessageEvent : Equatable, Hashable
```

--------------------------------

### EventHandler Protocol

Source: https://launchdarkly.github.io/swift-eventsource/Protocols/EventHandler.html

The EventHandler protocol defines the interface for objects that will receive Server-Sent Events (SSE) from an EventSource connection.

```APIDOC
## EventHandler Protocol

### Description
Protocol for an object that will receive SSE events.

### Methods

#### `onOpened()`

EventSource calls this method when the stream connection has been opened.

##### Declaration
```swift
func onOpened()
```

#### `onClosed()`

EventSource calls this method when the stream connection has been closed.

##### Declaration
```swift
func onClosed()
```

#### `onMessage(eventType:messageEvent:)`

EventSource calls this method when it has received a new event from the stream.

##### Declaration
```swift
func onMessage(eventType: String, messageEvent: MessageEvent)
```

##### Parameters
- **eventType** (String) - The type of the event.
- **messageEvent** (MessageEvent) - The data for the event.

#### `onComment(comment:)`

EventSource calls this method when it has received a comment line from the stream.

##### Declaration
```swift
func onComment(comment: String)
```

##### Parameters
- **comment** (String) - The comment received.

#### `onError(error:)`

This method will be called for all exceptions that occur on the network connection (including an `UnsuccessfulResponseError` if the server returns an unexpected HTTP status), but only after the ConnectionErrorHandler (if any) has processed it. If you need to do anything that affects the state of the connection, use ConnectionErrorHandler.

##### Declaration
```swift
func onError(error: Error)
```

##### Parameters
- **error** (Error) - The error received.
```

--------------------------------

### MessageEvent Structure

Source: https://launchdarkly.github.io/swift-eventsource/Structs.html

Represents a single event received from a Server-Sent Events stream.

```APIDOC
## MessageEvent Structure

### Description
Struct representing received event from the stream.

### Declaration
Swift
```swift
public struct MessageEvent : Equatable, Hashable
```

### Fields
This structure does not explicitly list fields in the provided documentation.
```

--------------------------------

### MessageEvent Data Property

Source: https://launchdarkly.github.io/swift-eventsource/Structs/MessageEvent.html

Accesses the event data field.

```Swift
public let data: String
```

--------------------------------

### MessageEvent Structure

Source: https://launchdarkly.github.io/swift-eventsource/Structs/MessageEvent.html

Represents a received event from the stream, including its data and last event ID.

```APIDOC
## MessageEvent Structure

### Description
Struct representing received event from the stream.

### Properties
- **data** (String) - The event data of the event.
- **lastEventId** (String) - The last seen event id, or the event id set in the Config if none have been received.

### Constructor
#### init(data:lastEventId:)
Constructor for a `MessageEvent`

#### Parameters
- **data** (String) - The `data` field of the `MessageEvent`.
- **lastEventId** (String) - The `lastEventId` field of the `MessageEvent`.
```

--------------------------------

### ConnectionErrorAction Enum Declaration

Source: https://launchdarkly.github.io/swift-eventsource/Enums.html

Represents potential actions a ConnectionErrorHandler can return. This enum defines the possible outcomes when handling connection errors.

```swift
public enum ConnectionErrorAction
```

--------------------------------

### ConnectionErrorHandler

Source: https://launchdarkly.github.io/swift-eventsource/Typealiases.html

A function type used to handle connection failures and determine whether to continue or stop reconnection attempts.

```APIDOC
## ConnectionErrorHandler

### Description
Type for a function that will be notified when the EventSource client encounters a connection failure. It allows the client to stop reconnecting by returning a ConnectionErrorAction.shutdown.

### Declaration
```swift
public typealias ConnectionErrorHandler = (Error) -> ConnectionErrorAction
```
```

--------------------------------

### Handle Stream Closed Event

Source: https://launchdarkly.github.io/swift-eventsource/Protocols/EventHandler.html

Called when the SSE stream connection has been closed. This method is called regardless of whether the closure was intentional or due to an error.

```swift
func onClosed()
```

--------------------------------

### Define ConnectionErrorHandler Type Alias

Source: https://launchdarkly.github.io/swift-eventsource/Typealiases.html

Type for a function notified on `EventSource` client connection failures. It can signal the client to stop reconnecting by returning `ConnectionErrorAction.shutdown`.

```swift
public typealias ConnectionErrorHandler = (Error) -> ConnectionErrorAction
```

--------------------------------

### HeaderTransform

Source: https://launchdarkly.github.io/swift-eventsource/Typealiases.html

A function type used to modify HTTP headers before connecting or reconnecting to a stream.

```APIDOC
## HeaderTransform

### Description
Type for a function that will take in the current HTTP headers and return a new set of HTTP headers to be used when connecting and reconnecting to a stream.

### Declaration
```swift
public typealias HeaderTransform = ([String : String]) -> [String : String]
```
```

--------------------------------

### MessageEvent LastEventId Property

Source: https://launchdarkly.github.io/swift-eventsource/Structs/MessageEvent.html

Accesses the last seen event ID or the configured default.

```Swift
public let lastEventId: String
```

--------------------------------

### Define HeaderTransform Type Alias

Source: https://launchdarkly.github.io/swift-eventsource/Typealiases.html

Type for a function that modifies HTTP headers used for connecting and reconnecting to a stream. It takes current headers and returns a new set.

```swift
public typealias HeaderTransform = ([String : String]) -> [String : String]
```
Tokens:
Raw