Detailed description

The SSE Server Hub allows for HTTP Client Requests (through a Rest Expose API) to be persisted for Event Streaming as per protocol¹. This is accomplished by switching the mime-type response to the appropriate text/event-stream and flushing the messages complying to the event source format².

The SSE Client implements the Event Source JS Interface containing the Server Sent Event API, also per protocol³.

Effectively, no third parties are required for Server Push/Messaging.

¹ https://html.spec.whatwg.org/multipage/server-sent-events.html

² https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events

³ https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events

Related Components

• SSE Hub
• Reactive SSE Client Lib (Includes Example Apps) 
• Traditional SSE Client Lib (Includes Example Apps)
• Mobile Chat Example App
• Chess Example App

Notes

• SSE are not web-sockets (they are a one way channel from server to client), nor polling mechanisms (it is an HTTP protocol implementation). 
• Use one of the above Client Libs at your User-End module
• This is a work in progress, any help/suggestions are welcomed. Please read the Examples Sections on the Module, and have a look around :)

Current Issues

• Scaling the Module of the Hub is not possible out of the box. This means that multiple front-end servers will spawn multiple Hub instances which this component does not support. There is however an un-tested alternative that you can check in the Example App included in this module, and its high level diagram view at the end of these docs. As an alternative, a dedicated non-scalable zone is needed. 
• The hub currently logs a "Slow Extension" log on Service Center when a client disconnects. The reason is that the Hub needs to check the client connections to keep them alive and this is "seen" as a slow extension method. There might be a way to suppress these logs at the Service Center, but I currently don't know how. 
• Background Notifications on both Mobile and PWA are not supported. If this is a deal breaker, please use Apple's APN/ Google's FCM approaches (Firebase, OneSignal, etc...) There is now the possibility to address this in PWA apps using Microsoft's Fetch Event Source but it has not been tested/worked on.
• There have been reports of issues on IOS mobile apps after the MABS 6.0 update. I have still not addressed this issue, so be aware if specifically targeting IOS.
• On Personal Environments(PE), there seems to be a cap of 100 concurrent API live connections per Hub Module. 

Hub Hello World

1- Create a new module(service is fine) inside your Application - HelloWorld_Hub.

It is recommended that a single Hub Module serves a single purpose/application, but any combination is possible, even a single SSE Hub for the entire Outsystems Environment.

2- Open the module dependencies (ctrl+q), search for SSE_IS and add both the "Broadcast" and "OpenStream" server actions.

3- Create a new *Service Action* named "Broadcast2HelloWorld" with a Message Input(text) variable. 

Add the imported SSE_IS "Broadcast" to the flow and fill in Message variable, and the Channel - "HelloWorld". 

That's it to Broadcast to every client subscribed to a Channel.

4- Create an Exposed Rest API  named "SSESubscribe". Add a new GET REST API Method - HelloWorldChannel and add the imported SSE_IS "OpenStream" action.

Fill in the Channel variable with "HelloWorld". 

That's it, your Hub is now able to add new Http Clients to the "HelloWorld" channel.

Take note of the Rest's Endpoint URL, e.g: "/HelloWorld_Hub/rest/SSESubscribe/HelloWorldChannel"

5- Install one of the SSE Clients from forge - Reactive / Traditional. In your Client Module (React, Mobile, Traditional),  open the module dependencies (ctrl+q), search for the SSE_LIB / SSE_Traditional_Lib and add the EventSource WebBlock to your Screen. 

Fill in the SSE URL from above:

"/HelloWorld_Hub/rest/SSESubscribe/HelloWorldChannel". 

Also, create the mandatory event handler for the receiving messages.

That's all for the simplest setup! Whenever the "Broadcast" *Service Action* in the HUB is called by any agent, all clients will receive the issued message.

Please try any of the SSE Clients (Reactive / Traditional) to connect to your Hub, and check their example apps.

SSE_IS - HUB Integration Layer

• An HUB Instance is an independent, isolated, server-sent events (SSE) connection manager. It holds HTTP connections grouped by channels.
• Whenever an SSE_IS Module (this module) is consumed, a new HUB is created. *This is Important to understand*. 
• A Typical scenario (recommended) is: 

    * create a new module on the application where the SSE is needed

    * consume the SSE_IS "Broadcast" and "OpenStream" actions

    * wrap and expose the Broadcast via a Service Action with the appropriate auth if applicable

    * expose a new rest endpoint for the OpenStream action with the appropriate auth if applicable

       This will be responsible to add new client http connections to the hub

• The HUB automatically cleans any disconnected client. If the Hub DLL instance is recycled (on the IIS), the clients will automatically reconnect and the hub will transparently add these connections.
• The HUB *Does Not* validate any channels. It will create one if it doesn't exist internally so please validate and implement your channel logic when using the hub.
• The HUB *Does Not* enforce or validate any Auth mechanisms. Please use proper Outsystems mechanisms to apply authentication and authorization to both the REST Expose actions (for the OpenStream action) and the SSE_IS (Broadcast through a wrapped service action).
• Please refer to the Hello World tutorial and also to the examples module for further examples.

SSE Hub for Multiple Frontends POC (not tested)

Detailed description

The SSE Server Hub allows for HTTP Client Requests (through a Rest Expose API) to be persisted for Event Streaming as per protocol¹. This is accomplished by switching the mime-type response to the appropriate text/event-stream and flushing the messages complying to the event source format².

The SSE Client implements the Event Source JS Interface containing the Server Sent Event API, also per protocol³.

Effectively, no third parties are required for Server Push/Messaging.

¹ https://html.spec.whatwg.org/multipage/server-sent-events.html

² https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events

³ https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events

Notes

• SSE are not web-sockets (they are a one way channel from server to client), nor polling mechanisms (it is an HTTP protocol implementation). 
• Further examples will be published
• This is a work in progress, any help/suggestions are welcomed. Please read the Examples Sections on the Module, and have a look around :)

Current Issues

• Scaling the Module where the Hub is instantiated is not possible yet. This means that multiple front-end servers will spawn multiple Hub instances which this component does not support. A dedicated non-scalable zone is needed in such cases. 
• Background Notifications on both Mobile and PWA are not supported. If this is a deal breaker, please use Apple's APN/ Google's FCM approaches (Firebase, OneSignal, etc...)
• There have been reports of issues on IOS mobile apps after the MABS 6.0 update. I have still not addressed this issue, so be aware if specifically targeting IOS.
• On Personal Environments(PE), there seems to be a cap of 100 concurrent API live connections per Hub Module. 

Next

• Traditional Web SSE component
• Multiple Frontends support - broadcast signal repeater tutorial
• IOS MABS 6.0 issue fix
• Queuing

*(There is no particular order for the above)

Hub Hello World

1- Create a new module(service is fine) inside your Application - HelloWorld_Hub.

It is recommended that a single Hub Module serves a single purpose/application, but any combination is possible, even a single SSE Hub for the entire Outsystems Environment.

2- Open the module dependencies (ctrl+q), search for SSE_IS and add both the "Broadcast" and "OpenStream" server actions.

3- Create a new *Service Action* named "Broadcast2HelloWorld" with a Message Input(text) variable. 

Add the imported SSE_IS "Broadcast" to the flow and fill in Message variable, and the Channel - "HelloWorld". 

That's it to Broadcast to every client subscribed to a Channel.

4- Create an Exposed Rest API  named "SSESubscribe". Add a new GET REST API Method - HelloWorldChannel and add the imported SSE_IS "OpenStream" action.

Fill in the Channel variable with "HelloWorld". 

That's it, your Hub is now able to add new Http Clients to the "HelloWorld" channel.

Take note of the Rest's Endpoint URL, e.g: "/HelloWorld_Hub/rest/SSESubscribe/HelloWorldChannel"

5- In your Client Module (React, Mobile) open the module dependencies (ctrl+q), search for the SSE_LIB and add the SSEEventListener WebBlock to your Screen. 

Fill in the SSE URL from above:

"/HelloWorld_Hub/rest/SSESubscribe/HelloWorldChannel". 

Also, create the mandatory event handler for the receiving messages.

That's all for the simplest setup! Whenever the "Broadcast" *Service Action* in the HUB is called by any agent, all clients will receive the issued message.

SSE_IS - HUB Integration Layer

• An HUB Instance is an independent, isolated, server-sent events (SSE) connection manager. It holds HTTP connections grouped by channels.
• Whenever an SSE_IS Module (this module) is consumed, a new HUB is created. *This is Important to understand*. 
• A Typical scenario (recommended) is: 

    * create a new module on the application where the SSE is needed

    * consume the SSE_IS "Broadcast" and "OpenStream" actions

    * wrap and expose the Broadcast via a Service Action with the appropriate auth if applicable

    * expose a new rest endpoint for the OpenStream action with the appropriate auth if applicable

       This will be responsible to add new client http connections to the hub

• The HUB automatically cleans any disconnected client. If the Hub DLL instance is recycled (on the IIS), the clients will automatically reconnect and the hub will transparently add these connections.
• The HUB *Does Not* validate any channels. It will create one if it doesn't exist internally so please validate and implement your channel logic when using the hub.
• The HUB *Does Not* enforce or validate any Auth mechanisms. Please use proper Outsystems mechanisms to apply authentication and authorization to both the REST Expose actions (for the OpenStream action) and the SSE_IS (Broadcast through a wrapped service action).
• Please refer to the Hello World tutorial and also to the examples module for further examples.

SSE_LIB - SSE Event Listener

• This block listens to a specific HUB Channel 
• It is possible to further filter the Channel by its events
• A Token GUID is issued every time a new connection is established and it uniquely identifies the connection
• The block is initiated when the SSESubscribeURL is populated. Please refer to further examples @ the SSE examples module
• Authentication can be implemented by passing a token together with the URL as a parameter, and validating it either on the onRequest hook or with the custom onAuthentication hook, using SSL. The EventSource API does not, at the moment, support adding headers to the initial client-server request thus voiding a normal Bearer / Basic Auth.
• The SSE EventStream interface ensures resilience through an auto-connect on disconnect, so everything is handled in case of disconnection. Have in mind though, that the same URL will be used.