Subscribe to WebSocket Notifications

Alpha Release

solid-client-notifications is available as an Alpha release. Subscribing to changes is currently only supported by Inrupt’s Enterprise Solid Server.

Solid Server can publish WebSocket notifications for create/update/delete operations on a Resource. Using the @inrupt/solid-client-notifications library, applications can subscribe to WebSocket notifications for a Resource.

Subscribe to Changes

To subscribe to WebSocket notifications for a particular Resource:

  • Use the WebsocketNotification constructor to create a WebsocketNotification object. The constructor accepts the following:

    • Resource URL, and

    • An options object with an authenticated fetch() function.

    Important

    To subscribe to a Resource, you must authenticate as a user with access to the Resource. For details on user authentication, see Authentication.

  • Use the on function to listen for events. The function accepts the following:

    • The event type (e.g., "message"), and

    • A callback function to process the event.

  • Use the connect function to connect to the WebSocket server.

  • Use the disconnect function to disconnect from the WebSocket server.

When subscribing to a Container, the application receives notifications when files are added or deleted from the Container as well as when the Container itself is created or deleted.

When subscribing to SolidDataset files or regular files (e.g., .jpg, .json), the application receives notifications when the target files are modified or deleted.

Example

The following example subscribes to change notifications for a Container https://pod.inrupt.com/<user>/some-container/ and logs the event messages to your console.

Note

  • When subscribing to a Container, the application receives notifications when files are added or removed from the Container as well as creation/deletion of the Container itself.

  • For brevity, the authentication logic has been omitted. For details on user authentication, see Authentication.

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

const containerUrl = "https://pod.inrupt.com/<user>/some-container/";

// ... authentication logic has been omitted

const websocket = new WebsocketNotification(
  containerUrl,
  { fetch: fetch }
);

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

websocket.connect();

Sample Event

The following is a sample event emitted by the Pod Server https://pod.inrupt.com.

Note

The event message emitted by your Pod Server may differ.

{
   "@context":[
      "https://www.w3.org/ns/activitystreams",
      {
         "state":{
            "@id":"http://www.w3.org/2011/http-headers#etag"
         }
      }
   ],
   "id":"urn:uuid:<uuid>",
   "type":[
      "http://www.w3.org/ns/prov#Activity",
      "Update"
   ],
   "actor":[
      "<WebID>"
   ],
   "object":{
      "id":"https://pod.inrupt.com/<user>/some-container/",
      "type":[
         "http://www.w3.org/ns/ldp#BasicContainer",
         "http://www.w3.org/ns/ldp#Container",
         "http://www.w3.org/ns/ldp#RDFSource",
         "http://www.w3.org/ns/ldp#Resource"
      ]
   },
   "published":"2021-03-30T01:01:49.550044Z"
}

Field

Description

@context

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

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

Tip

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.

Additional Information

For information on writing data to Solid Pods, see:

Manage Access to Data (WAC) Vocabulary