WebSocket Notification Service#

New in version 1.1.

ESS provides a secure implementation of a WebSockets notification protocol. The ESS WebSocket service publishes 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 notification protocol will be proposed for inclusion into the Solid specifications.

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.

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 }
);

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 Discovery.

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" }
```
Using the returned endpoint, clients can negotiate an authenticated session. That is, 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>"
}
```
Using the returned endpoint, a client can connect to the WebSocket service, by pass the entire endpoint string into the JavaScript WebSocket constructor):
```
var ws = new WebSocket("<endpoint>", "solid-0.2");
```
You must specify the subprotocol of "solid-0.2". 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.

Sample Interface#

ESS provides a sample interface to the WebSocket service https://websockets.<DOMAIN>/notifications.html.

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>"
  ],
  "actor": [
     "<WebID>"
  ],
  "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"

actor

An array containing the WebID of the agent that made the change to the Resource.

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.