Subscribe to WebSocket Notifications

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 Read 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://storage.inrupt.com/<some identifier>/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://storage.inrupt.com/<some identifier>/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 Inrupt’s PodSpaces.

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"
   ],
   "object":{
      "id":"https://storage.inrupt.com/<some identifier>/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"
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:

• Read/Write Structured Data for storing structured data.

• Read/Write Files (Non-RDF Resources) for storing regular files.