Skip to main content

SSE Stream connector

Connects to and receives messages from an SSE (Server-sent events) server.

component image

In-ports​

url String (required) — URL of the SSE server that provides the event stream. The URL can include query or path parameters.

params JSON — query or path parameters to be included in the request URL.

data JSON, String — The body of the initial HTTP request.

headers JSON — The headers of the initial HTTP request.

subscribe any — triggers the initial HTTP request and subscribes to an event stream.

unsubscribe any — unsubscribes from an event stream.

config JSON (dynamic) — accepts a JSON object with configuration properties that can be set at runtime.

Out-ports​

events JSON— emits data events and comments received from the server.

errors JSON — emits any errors events, including subscription failure.

status JSON — emits subscription status events.

Overview​

The SSE Connector component allows you to subscribe to and receive Server-sent events (SSE). Note that server-sent events are unidirectional, meaning that data messages are delivered from the server to the client (the user's web browser), and cannot be used to send events from an application to the server.

To use this connector, provide the SSE server URL to the url port. The component will connect to the Kelp Data Gateway (DGW) and trigger the initial HTTP request to open a persistent connection to the SSE server. The initial HTTP request can be either a GET or POST. For GET requests, pass query and path parameters as JSON object to the params port. If you specified query or path placeholders in the URL, these placeholders will be replaced with the values from the params object. Remaining parameters in the params object will be automatically added to the request URL as query parameters. For POST requests, pass the request body to the data port. Use the headers input port to provide the required headers for the initial HTTP request.

Once the connection is successfully opened, a SUBSCRIBED status will be emitted on the status port. This indicates that the component is ready to receive events from the server. Server-sent events will be emitted on the events port.

If the subscribe input port is connected, the component will wait to establish a connection until an event is received on the subscribe port. The component will automatically retry the subscription every time an event is received on the subscribe port. To unsubscribe, simply pass any event to the unsubscribe input port. The component emits an UNSUBSCRIBED status on the status port when the connection with the SSE server is closed.

If any errors occur during the subscription or while the connection is active, the corresponding error message will be emitted on the errors output port.

Configuration​

The component supports dynamic configuration. You can specify the required settings either in settings dialog or through a configuration object. To enable the config port for runtime configuration, turn on the “Enable realtime config port” setting.

Settings​

Authentication​

Configure authentication to the target service. Select one of the existing connections from the drop-down list, or configure a new connection.

Enable realtime config port​

If this setting is enabled, the component can be configured through the config port. This port accepts a configuration object as input and allows you to set dynamic properties at runtime. Note that using this port does not cause the component to reinitialize, but it may cause some previous state of the component to be lost.

HTTP method (httpMethod)​

The type of HTTP request that the SSE connector sends to the server to establish the connection and initiate the data stream.

  • GET (get) — This is the default method and is typically used when no additional payload is required to initialize the connection.
  • POST (post) — This method is used when additional data is needed to initialize the connection. The initialization data can be passed to the data port.
  • HEAD (head)
  • PUT (put)
  • PATCH (patch)
  • DELETE (delete)

Type: String
Default: get
Required: Yes

Last event ID (lastEventId)​

The ID value of the last event that was received by the client. The lastEventId is sent with the initial subscription request. If the server supports this feature, it will start sending events immediately following the event with lastEventId ID.

Type: String
Required: No

Connections reuse strategy (connectionsReuseStrategy)​

This setting lets you manage how the connections to the SSE server are reused between multiple SSE Stream components in your application. The connections are uniquely identified by application ID, user ID and component configuration object. The strategy is used by DGW to decide if an existing connection should be reused or the new one created. The following strategies are supported:

  • Always new (alwaysNew) — This strategy ensures that upstream server connections are never reused. Each time a subscription request is made, DGW will try to create a new connection to the upstream server. This approach can be useful when there are security concerns or data isolation requirements.
  • Reuse within application (reuseWithinApp) — With this strategy, an upstream server connection will be created once per user and application, and then reused for any subsequent subscription requests made from any user device. This means that the connection will be kept open while user has application running on any device, and will be reused for any new subscription requests made during that time. This approach can improve performance by reducing the overhead associated with creating a new connection for each request.

Type: String
Default: reuseWithinApp
Required: No

Server disconnect policy (serverDisconnectPolicy)​

This setting lets you manage how the DGW should behave if connection to the SSE server is closed.

  • Reconnect (reconnect) — This policy enables the DGW to automatically reconnect to the SSE server if the connection is disrupted. Every time the DGW tries to reconnect, an error message is emitted.
  • Shutdown (shutdown) — This policy instructs DGW to disconnect from the SSE server if the connection is disrupted or closed by the server. Use this policy when you expect the SSE server to end the stream. Once the connection is closed, the component will emit an UNSUBSCRIBED status.

Type: String
Default: reconnect
Required: No

Include comment messages (includeCommentMessages)​

Include comment messages (lines starting with a “:”) sent by the server.

Type: Boolean
Default: false
Required: No

Keep always active​

Determines whether the component will remain active even if it is not connected to a visible widget or another active component.

Configuration object​

Here is an example of a configuration object that you can use as a template:

{
  "httpUri": "https://sse.example.com/stream",
  "httpMethod": "get",
  "includeCommentMessages": false,
  "lastEventId": "1234",
  "connectionsReuseStrategy": "reuseWithinApp",
  "serverDisconnectPolicy": "reconnect"
}