Samhammer.SocketServer.Server 8.0.4

Samhammer.SocketServer

Note: The implementation is currently uni directional and only ment for communication from the server to the client.

Note2: This repo is private for multiple reasons, even though the server project would be reusable:

• To not disclose infrastructure information over the appsettings of the api
• Because the api docker image is in our private docker registry

Samhammer.SocketServer.Api

This is an entire api project that uses Samhammer.SocketServer.Server to provide endpoints for it's functionality. The project is provided as docker image.

How to use

Take a look at appsettings because there are a few settings that need to be overwritten via env vars. (at least the Elastic index and both AuthOptions blocks)

Docker images are pushed to registry.samhammer.oncloudandheat.com. See project "samhammer-socket-server" there.

The following API endpoints are provided:

• /ws ⇒ Websocket endpoint
• GET api/client ⇒ Get all active client ids
• POST api/notification/<clientid> ⇒ Send a message to a specific client
• POST api/notification/broadcast ⇒ Send a message to all clients

Samhammer.SocketServer.ApiClient

Contains the HTTP-Calls to access the "Samhammer.SocketServer.Api" project.

Install the nuget package "Samhammer.SocketServer.ApiClient".

Then you can Inject "ISocketServerApiClient". (it is registered in ioc by Samhammer.DependencyInjection)

Also register a matching http client like that:

    builder.Services
        .AddHttpClient<ISocketServerApiClient, SocketServerApiClient>(options =>
            options.BaseAddress = new Uri(builder.Configuration["SocketServerApiOptions:Url"]))
        .AddClientCredentialsTokenHandler(ApiAuthOptions.DefaultClientName); // https://github.com/DuendeSoftware/Duende.AccessTokenManagement

Samhammer.SocketServer.ApiClient.JS

Contains the HTTP-Calls to access the "Samhammer.SocketServer.Api" from javascript. This client is provided as npm package.

Install the npm package "@samhammer/socketserver-apiclient-js".

Implement the abstract class like that:

class MyProjectWebsocketNotificationService extends WebsocketNotificationService {
    public init() {
        const myUrl = "...";
        const myDeviceId = "...";
        super.init(socketUrl, deviceId.value);
    }

    protected async onSendPushToken(token: PushTokenContract): Promise<void> {
        // There you can do logic as soon as the clients got a push token
        // e.g. calling your api to save it
    }

    protected async onDeletePushToken(deviceId: string): Promise<void> {
        // There you can do logic if the push token needs to be deleted
        // e.g. calling your api to delete it
    }

    protected onPushMessage(socketJson: unknown): Promise<void> {
        // This function is called as soon as a push message
        // is received. The content depends on what you send from the server
    }

    protected onConnectionStatusChanged(isConnected: boolean): Promise<void> {
        // This method is called if the connection status changes.
        // If you need to know the status in your application, you can put your logic here.
        // e.g. saving the state to a pinia store
    }
}

Samhammer.SocketServer.Server

A library to integrate websocket technology into an existing api project.

What can it do:

• Provide endpoint of a socket server
• Establish and keep open connections
• Send messages from the server to one or multiple clients
• Handles clientId stuff (first message sent to the client is the clientId)

How to use

Install the nuget package "Samhammer.SocketServer.Server".

Adjust jour Program.cs like that:

    builder.Services.AddSocketServer(builder.Configuration); // There are overloads for different scenarios 

    var app = builder.Build();

    app.MapSocketServer("/ws"); // Endpoint under which the socket server runs

If you use "AddSocketServer(builder.Configuration)" add this config block to appsettings:

  "SocketServerOptions": {
    "HeartbeatIntervalSeconds": 300,
    "MaxBufferSizeInKb": 500
  },

• HeartbeatIntervalSeconds: Configure how often keep alive messages should be transfered
• MaxBufferSizeInKb: Max message lengt. Everything langer will be cut off

Inject IWebsocketService to use the server:

• Task<bool> SendText(string clientId, string text) ⇒ Send a message to a specific client (returns true in case of success)
• Task BroadcastText(string text) ⇒ Send a message to all connected clients
• List<string> GetActiveClients() ⇒ Get a list of active client ids

How to publish

• Create & Push a tag with new version number
• The CICD actions will take this version number for nuget, npm, docker automatically
• Check github action to validated, that package was released to npm registry, nuget registriy, docker registry