WebSocket Notification Service#

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

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.

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/

SMALLRYE_JWT_SIGN_KEY_LOCATION#

The path to the signing key used for negotiating subscriptions.

QUARKUS_GRPC_CLIENTS_AUTHZ_HOST#

The host where the ESS Authorization Service is running.

Kafka Configuration#

KAFKA_BOOTSTRAP_SERVERS#

Default: localhost:9092

Comma-delimited list of Kafka broker servers for use by ESS services, including this service.

Setting KAFKA_BOOTSTRAP_SERVERS configures ESS to use the same Kafka instance(s) for all its Kafka message channels (e.g., solidresource and auditv1out message channels). This service uses the solidresource and auditv1out channels.

Note

Inrupt-provided overlays default to using KAFKA_BOOTSTRAP_SERVERS.

To use a different Kafka instance for the solidresource and auditv1out channels, use specific message channel configuration.

See also ESS’ Kafka Configuration.

MP_MESSAGING_INCOMING_SOLIDRESOURCE_SSL_TRUSTSTORE_LOCATION#

The location of the Kafka connection truststore

MP_MESSAGING_INCOMING_SOLIDRESOURCE_SSL_TRUSTSTORE_PASSWORD#

The password for the Kafka connection truststore.

MP_MESSAGING_INCOMING_SOLIDRESOURCE_VALUE_DESERIALIZER#

Default: org.apache.kafka.common.serialization.StringDeserializer

The deserializer to use to consume Kafka messages sent by the Pod services.

Supported values are:

  • org.apache.kafka.common.serialization.StringDeserializer

    Set to this value to consume notification messages sent by services that use org.apache.kafka.common.serialization.StringSerializer as their MP_MESSAGING_OUTGOING_SOLIDRESOURCE_VALUE_SERIALIZER

  • com.inrupt.components.kafka.encryption.DecryptMessageDeserializer

    Set to this value to consume encrypted notification messages sent by services that use com.inrupt.components.kafka.encryption.EncryptMessageSerializer as their MP_MESSAGING_OUTGOING_SOLIDRESOURCE_VALUE_SERIALIZER

INRUPT_KAFKA_SOLIDRESOURCE_CIPHER_PASSWORD#

The symmetric key to use when decrypting messages (see MP_MESSAGING_INCOMING_SOLIDRESOURCE_VALUE_DESERIALIZER).

Warning

Set to a strong password.

INRUPT_KAFKA_AUDITV1EVENTSENCRYPTED_CIPHER_PASSWORD#

The strong cipher key to use when running auditing with encrypted messages.

MP_MESSAGING_OUTGOING_AUDITV1OUT_BOOTSTRAP_SERVERS#

Default: localhost:9092

Comma-delimited list of Kafka broker servers used for the outgoing audit v1 messages.

These messages are sent over the auditv1out message channel.

Note

To configure ESS to use the same Kafka instances for all its Kafka message channels, use KAFKA_BOOTSTRAP_SERVERS option instead. Inrupt-provided overlays default to using KAFKA_BOOTSTRAP_SERVERS.

Optional#

QUARKUS_LOG_LEVEL#

Default: INFO

Logging level.

INRUPT_JWT_ISSUER_ALLOW_LIST#

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

See also INRUPT_JWT_ISSUER_DENY_LIST.

INRUPT_JWT_ISSUER_DENY_LIST#

A comma-separated list of disallowed Solid-OIDC issuers.