Event streaming and real-time communication

Event Streaming for Connect is a service which exposes entries and incidents endpoints that enable real-time communication between server and clients. The service is tied to KS Connect and is able to serve only tenants belonging to it.

Three different techniques are supported to handle real-time communication, and are implemented in the official ASP.Net Core SignalR library. Besides library being used on the server, client side is also covered and easy to use client libraries are provided.

Architecture

Public APIs

URLS

Accept: https://eventstreaming-connect-accept.saltoks.com

Production: https://eventstreaming-connect-production.saltoks.com

Real-time endpoints

Endpoint to get site specific entry stream:

• /v1/hub/entries?site_id={siteId}

• site_id - unique identifier of the site, must be defined

Endpoint to get site user specific entry stream:

• /v1/hub/entries?site_id={siteId}&user_id={userId}

• site_id param - unique identifier of the site, must be defined

• user_id param - unique identifier of the site, must be defined

General:

• Endpoints are protected, it requires both authentication and authorization to establish connection to given hubs

• Token retrieved for Connect API communication can be reused, as long as scopes are correctly defined

• Once request is successfully authorized and exchange technique negotiated by SignalR, connection to get the data will be established.

Authentication

Once JWT access token is retrieved from Identity Server, it needs to be passed either in:

• Authorization header with value Bearer {accessToken}

• access_token query parameters with only token value ?access_token={accessToken}

If authentication is successful server will proceed to additionally authorize request.

Invalid or expired tokens, 401 Unauthorized is returned.

Authorization

Allowed Scope: user_api.full_access

• JWT scopes claim

User permissions:

• Site entries: Site Admin, Site Super User

• Site user entries: Site Admin, Site Super User, Site User (own events)

• Site incidents: Site Admin, Site Super User

• Site user incidents: Site Admin, Site Super User, Site User (own events)

If scope or permission authorization fails, 403 Forbidden is returned.

Transport

We currently support only Web Sockets transport with SkipNegotiation = true.

Code Examples

Samle using SignalR .Net Client in C#:

Csusing Microsoft.AspNetCore.SignalR.Client;
var token = "ACCESS_TOKEN";
var siteId = "SITE_ID";
var url = $"{streamingEndpointUrl}/v1/hub/entries?site_id={siteId}" //$"{streamingEndpointUrl}/v1/hub/incidents?site_id={siteId}"
HubConnection connection = new HubConnectionBuilder()
    .WithUrl(url, options =>
    {
      options.AccessTokenProvider = () => token,
      options.SkipNegotiation = true;
      options.Transports=HttpTransportType.WebSockets;
    })
    .Build();
				
connection.On<string>("ReceiveMessage", message =>
{
    // incident or entry message
});
await connection.StartAsync();

Sample using SignalR Javascript Client:

const token = "ACCESS_TOKEN"
const siteId = "SITE_ID"
const url = $"{streamingEndpointUrl}/v1/hub/entries?site_id={siteId}" //$"{streamingEndpointUrl}/v1/hub/incidents?site_id={siteId}" 
const connection = new signalR.HubConnectionBuilder()
    .withUrl(url, {
        accessTokenFactory: () => token,
	   	skipNegotiation: true,
        transport: signalR.HttpTransportType.WebSockets,
    })
    .build();
	
connection.on('ReceiveMessage', (message) =>
{
    // incident or entry message
});
await connection.start();

Samle using Java Client:

String url = "URL";
String token = "ACCESS_TOKEN";
HubConnection hubConnection = HubConnectionBuilder.create(url)
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just(token);
    }))
    .shouldSkipNegotiate(true)
    .build();
hubConnection.on("ReceiveMessage", (message) -> {
    System.out.println("New Message: " + message);
}, String.class);
//This is a blocking call
hubConnection.start().blockingAwait();