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:

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.