WebSocket Notification Service#

Added in version 1.1.

ESS provides a secure implementation of a WebSockets notification protocol. The ESS WebSocket service publishes asynchronous notifications upon create/update/delete operations on a Resource, including a Container.

Disambiguation

The ESS WebSocket service is not an implementation of the draft Solid WebSockets API Spec (version solid-0.1).

The ESS WebSocket service is based on an earlier version of the Solid Notifications Protocol.

Client Subscriptions#

To receive notifications, a client subscribes to a particular Resource or Resources. A client can subscribe to a Resource that does not yet exist.

Using the @inrupt/solid-client-notifications library, applications can subscribe to WebSocket notifications.

Important

To subscribe to a resource, the authenticated user must have Read access to the resource.

import { getDefaultSession, fetch } from "@inrupt/solid-client-authn-browser";
import {
  WebsocketNotification,
} from "@inrupt/solid-client-notifications";

const resourceURL = ...;  // URL of the Resource to which to subscribe

// ... authentication logic has been omitted

const websocket = new WebsocketNotification(
  resourceURL,
  { fetch: fetch } // Authenticated fetch of a user with Read access
);

websocket.on("message", console.log);

websocket.connect();

For more information, see:

The process for establishing a WebSocket connection starts at the Notification Gateway endpoint for ESS (e.g., https://notification.<DOMAIN>/). This endpoint allows clients to identify the protocols they support along with any particular features that are required.

To determine your Notification Gateway endpoint, see /.well-known/solid.

Clients can POST the following JSON document to the ESS Notification Gateway; no authentication is required:
```
{ "protocols": ["ws"] }
```
The response JSON contains the WebSocket endpoint that clients can access for login; for example:
```
{ "endpoint": "https://websocket.<DOMAIN>/", "features":[], "protocol":"ws" }
```
Clients can use the returned endpoint to subscribe to a resource. Authentication is required.

Important

To subscribe to a resource, the authenticated user must have Read access to the resource.

To subscribe, clients can POST (using standard Solid authentication headers) a JSON document that specifies the Resource to which to subscribe:
```
{ "topic": "<URL of the resource to which to subscribe>" }
```
The response JSON returns the endpoint to establish the actual WebSocket connection:
```
{
  "endpoint": "wss://websocket.<DOMAIN>/?s=<session token>",
  "protocol": "ws",
  "subprotocol": "solid-0.2"
}
```
Using the returned endpoint and subprotocol, a client can connect to the WebSocket service, passing in the entire endpoint string and subprotocol string into the JavaScript WebSocket constructor):
```
var ws = new WebSocket("<endpoint>", "<subprotocol>");
```
You must specify the subprotocol. Otherwise, the connection is dropped.

Note

The subprotocol string is subject to change as the ESS WebSocket notification protocol undergoes the Solid panel process.

Once the connection is established, all the standard WebSocket methods can be used from the JavaScript API.

When subscribed to a particular Resource, the client sees all create/update/delete events for that particular Resource.

If a client subscribes to a Container, the client receives events for the Container as well as for the Container’s child Resource; specifically, if a child Resource is created or deleted but not if a child Resource is modified.

Clients should expect long-lived WebSocket connections to be terminated at any point in time. It is important that client code watch for WebSocket.onclose events and handle them by restarting the connection flow.

Notification Event#

The ESS WebSocket service publishes each notification as a W3C ActivityStream message, serialized as JSON-LD:

{
  "@context": [
     "https://www.w3.org/ns/activitystreams",
     {
        "state": {
           "@id": "http://www.w3.org/2011/http-headers#etag"
        }
     }
  ],
  "id": "urn:uuid:<random>",
  "type": [
     "http://www.w3.org/ns/prov#Activity",
     "<Action>"
  ],
  "object": {
    "id": "<resource URL>",
    "type": [
       "<LDP Resource Type>",
       ...
       "http://www.w3.org/ns/ldp#Resource"
    ]
  },
  "published": "<YYYY-MM-DDThh:mm:ss.sTZD>"
}

Field

Description

id

String that contains an identifier for the event.

type

An array identifying the event type:

[
   "http://www.w3.org/ns/prov#Activity",
   "<Action>"
]

Where "<Action>" can be one of the following values:

"Create"
"Delete"
"Update"

object

The resource object:

`object.id`	String indicating the Resource URL.
`object.type`	An array indicating the Resource type(s). Note Because a Container object is also an RDF Resource, to determine if the object is a non-Container RDF Resource, check that neither `http://www.w3.org/ns/ldp#Container` nor `http://www.w3.org/ns/ldp#BasicContainer` appear as elements of `object.type`.

published

The date and time the event is published.

@context

An array containing the JSON-LD contexts for the notification event itself.

Configuration#

As part of the installation process, Inrupt provides base Kustomize overlays and associated files that require deployment-specific configuration inputs.

The following configuration options are available for the service and may be set as part of updating the inputs for your deployment. The Inrupt-provided base Kustomize overlays may be using updated configuration values that differ from the default values.

Required#

INRUPT_WEBSOCKET_BASE_URI#: The URI of the service; e.g., wss://websocket.example/

QUARKUS_GRPC_CLIENTS_AUTHZ_HOST#: The host where the ESS Authorization Service is running.

SMALLRYE_JWT_SIGN_KEY_LOCATION#: The path to the signing key used for negotiating subscriptions.

Kafka Configuration#

Tip

Optional#

INRUPT_JWT_ALLOWED_SIGNATURE_ALGORITHMS#

Default: ES256, RS256

A comma-separated list that specifies the allowed encryption algorithms used to sign ID tokens.

INRUPT_JWT_ISSUER_ALLOW_LIST#

A comma-separated list of trusted Solid-OIDC issuers (i.e., identity providers).

If unset, the service accepts all Solid-OIDC issuers with the exception of those in the INRUPT_JWT_ISSUER_DENY_LIST.
If set, the service accepts only those Solid-OIDC issuers in the list with the following exception:
- If an issuer is in both INRUPT_JWT_ISSUER_ALLOW_LIST and INRUPT_JWT_ISSUER_DENY_LIST, the INRUPT_JWT_ISSUER_DENY_LIST supersedes the INRUPT_JWT_ISSUER_ALLOW_LIST and the issuer is not accepted by ESS.

WebSocket Notification Service#

Client Subscriptions#

Notification Event#

Configuration#

Required#

Kafka Configuration#

Optional#

Additional Information#