WebSocket Notification Service

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.

solid-client-notifications JS API

Using the @inrupt/solid-client-notifications library, applications can subscribe to WebSocket notifications.

To subscribe to a resource, the authenticated user must have Read access to the resource.

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 } // Authenticated fetch of a user with Read access
);
websocket.on("message", console.log);
websocket.connect();

For more information, see:

• Subscribe to WebSocket Notifications

• solid-client-notifications API

General Javascript API

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 /.well-known/solid.

1. Clients can POST the following JSON document to the ESS Notification Gateway; no authentication is required:

   json { "protocols": ["ws"] }

   The response JSON contains the WebSocket endpoint that clients can access for login; for example:

   json { "endpoint": "https://websocket.<DOMAIN>/", "features":[], "protocol":"ws" }

2. Clients can use the returned endpoint to subscribe to a resource. Authentication is required.

To subscribe to a resource, the authenticated user must have Read access to the resource.

To subscribe, 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>",
  "protocol": "ws",
  "subprotocol": "solid-0.2"
}

3. Using the returned endpoint and subprotocol , a client can connect to the WebSocket service, passing in the entire endpoint string and subprotocol string into the JavaScript WebSocket constructor):

var ws = new WebSocket("<endpoint>", "<subprotocol>");

You must specify the subprotocol. 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.

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 types. 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.
object.id	String indicating the Resource URL.
object.type	An array indicating the Resource types. 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.
object.id	String indicating the Resource URL.
object.type	An array indicating the Resource types. 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.
object.id	String indicating the Resource URL.
object.type	An array indicating the Resource types. 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.
object.id	String indicating the Resource URL.
object.type	An array indicating the Resource types. 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/

QUARKUS_GRPC_CLIENTS_AUTHZ_HOST

The host where the ESS Authorization Service is running.

SMALLRYE_JWT_SIGN_KEY_LOCATION

The path to the signing key used for negotiating subscriptions.

Kafka Configuration

Tip

See also ESS’ Kafka Configuration .

Note Whitespaces are preserved when parsing comma-delimited lists (i.e., the parsed string values are not trimmed). For example, when parsed, "value1, value2,value3 " results in "value1" , " value2" , "value3 " .

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.

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

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

Configuration Logging

ESS services log their startup configuration.

INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW

Default : inrupt,smallrye.jwt.sign.key.location

A comma-separated list of configuration property prefixes ( case-sensitive ) that determine which configurations are logged:

• If the list is empty, NO configuration property is logged.

• If a configuration property starts with a listed prefix ( case-sensitive ), the configuration property and its value are logged unless the configuration also matches a prefix in INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY (which acts as a filter on INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW list). As such, if the configuration matches prefix in both INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW and INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY , the INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY takes precedence and the configuration is not logged. For example, if inrupt. is an allow prefix, but inrupt.kafka. is a deny prefix, all configurations that start with inrupt.kafka. are excluded from the logs.

When specifying the prefixes, you can specify the prefixes using one of two formats:

• using dot notation (e.g., inrupt.foobar. ), or

• using the MicroProfile Config environmental variables conversion value (e.g., INRUPT_FOOBAR_ ).

Warning Use the same format for both INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW and INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY .

For example, if you change the format of INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW , change the format of INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY as well.

Tip

To avoid allowing more than desired configurations, specify as much of the prefix as possible. If the prefix specifies the complete prefix term, include the term delineator. For example:

• If using dot-notation, if you want to match configuration properties of the form foobar.<xxxx>... , specify foobar. (including the dot **. ) instead of, for example, foo or foobar .

• If using converted form, if you want to match configuration properties of the form FOOBAR_<XXXX>... , specify FOOBAR_ (including the underscore _ ) instead of, for example, FOO or FOOBAR .

INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY

Default: inrupt.kafka

A comma-separated list of configuration name prefixes ( case-sensitive ) that determines which configurations (that would otherwise match the INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW ) are not logged. That is, INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY acts as a filter on INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW . For example:

• If foobar. is an allowed prefix, to suppress foobar.private.<anything> , you can specify foobar.private. to the deny list.

• If foobar. is not an allowed prefix, no property starting with foobar. is logged. As such, you do not need to specify foobar.private to the deny list.

When specifying the prefixes, you can specify the prefixes using one of two formats:

• using dot notation (e.g., inrupt.foobar. ), or

• using the MicroProfile Config environmental variables conversion value (e.g., INRUPT_FOOBAR_ ).

Warning Use the same format for both INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW and INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY .

For example, if you change the format of INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW , change the format of INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY as well.

Logging Redaction

INRUPT_LOGGING_REDACTION_{NAME}_ACTION

Default : REPLACE

Type of the redaction to perform. Supported values are:

Action	Description
REPLACE	Default. Replaces the matching text with a specified replacement.
PLAIN	Leaves the matching field unprocessed. Only available if the redaction target is a field (i.e., INRUPT_LOGGING_REDACTION_{NAME}_FIELD).
DROP	Suppresses the matching field. Only available if the redaction target is a field (i.e., INRUPT_LOGGING_REDACTION_{NAME}_FIELD).
PRIORITIZE	Changes the log level of the matching message.
SHA256	Replaces the matching text with its hash.

• If the action is REPLACE ( default ), see also INRUPT_LOGGING_REDACTION_{NAME}_REPLACEMENT .

• If the action is to PRIORITIZE , see also INRUPT_LOGGING_REDACTION_{NAME}_LEVEL .

For more information on log redaction, see Logging Redaction.

INRUPT_LOGGING_REDACTION_{NAME}_ENABLED

Default : true

A boolean that determines whether the redaction configurations with the specified INRUPT_LOGGING_REDACTION_{NAME}_ prefix is enabled.

For more information on log redaction, see Logging Redaction.

INRUPT_LOGGING_REDACTION_{NAME}_EXCEPTION

Fully qualified name of the exception class to match in the log messages (includes inner exception). Configure to target an exception message class.

For more information on log redaction, see Logging Redaction.

INRUPT_LOGGING_REDACTION_{NAME}_FIELD

Exact name of the field to match in the log messages. Configure to target a specific log message field for redaction.

For more information on log redaction, see Logging Redaction.

INRUPT_LOGGING_REDACTION_{NAME}_LEVEL

Default : DEBUG

A new log level to use for the log message if the INRUPT_LOGGING_REDACTION_{NAME}_ACTION is PRIORITIZE .

INRUPT_LOGGING_REDACTION_{NAME}_PATTERN

A regex (see Java regex pattern ) to match in the log messages. Configure to target log message text that matches a specified pattern.

For more information on log redaction, see Logging Redaction.

INRUPT_LOGGING_REDACTION_{NAME}_REPLACEMENT

Default : [REDACTED] Replacement text to use if the INRUPT_LOGGING_REDACTION_{NAME}_ACTION is REPLACE.

If unspecified, defaults to [REDACTED] .

For more information on log redaction, see Logging Redaction.

Application-Defined Metadata Propagation

INRUPT_AUDIT_PRODUCER_REQUEST_METADATA_ALLOW

A comma-separated list of application-defined properties that can be included in the associated audit events (unless specified in the corresponding INRUPT_AUDIT_PRODUCER_REQUEST_METADATA_DENY ).

This configuration is case-sensitive to the propagated properties in the baggage.

Tip

To include a propagated property that was added via the INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW configuration, ensure that the cases of these properties match.

See:

• Manage Application-Defined Metadata Propagation to configure.

• Application-Defined Metadata for more information.

INRUPT_AUDIT_PRODUCER_REQUEST_METADATA_DENY

A comma-separated list of application-defined properties to exclude from the associated audit messages. This setting takes precedence over INRUPT_AUDIT_PRODUCER_REQUEST_METADATA_ALLOW .

This configuration is case-sensitive to the propagated properties in the baggage.

Tip

To exclude a propagated property that was added via the INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW configuration, ensure that the cases of these properties match.

See:

• Manage Application-Defined Metadata Propagation to configure.

• Application-Defined Metadata for more information.

INRUPT_LOGGING_REQUEST_METADATA_ALLOW

A comma-separated list of application-defined properties that can be included in the associated log messages (unless specified in the corresponding INRUPT_LOGGING_REQUEST_METADATA_DENY ).

This configuration is case-sensitive to the propagated properties in the baggage.

Tip

To include a propagated property that was added via the INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW configuration, ensure that the cases of these properties match.

See:

• Manage Application-Defined Metadata Propagation to configure.

• Application-Defined Metadata for more information.

INRUPT_LOGGING_REQUEST_METADATA_DENY

A comma-separated list of application-defined properties to exclude from the associated log messages. This setting takes precedence over INRUPT_LOGGING_REQUEST_METADATA_ALLOW .

This configuration is case-sensitive to the propagated properties in the baggage.

Tip

To exclude a propagated property that was added via the INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW configuration, ensure that the cases of these properties match.

See:

• Manage Application-Defined Metadata Propagation to configure.

• Application-Defined Metadata for more information.

INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW

A comma-separated list of non-baggage request headers to add to the baggage (unless specified in the corresponding INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_DENY ); i.e., include these non-baggage request headers as application-defined properties.

The configuration is case-insensitive; i.e., the listed headers do not need to match the case of the client request headers. For example, a list that includes x-correlation-id can match x-correlation-id header, X-CoRrElAtIoN-Id header, etc.

See:

• Manage Application-Defined Metadata Propagation to configure.

• Application-Defined Metadata for more information.

INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_DENY

A comma-separated list of non-baggage request headers to exclude from being added to the baggage ; i.e., excludes these headers as application-defined properties. This setting takes precedence over INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW .

The configuration is case-insensitive; i.e., the listed headers do not need to match the case of the client request headers. For example, a list that includes x-correlation-id can match (and exclude) x-correlation-id header, X-CoRrElAtIoN-Id header, etc.

See:

• Manage Application-Defined Metadata Propagation to configure.

• Application-Defined Metadata for more information.

INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_OVERRIDES

A flag that determines ESS behavior when metadata property is defined both as a header and as a baggage entry:

• If true ESS updates/overrides the baggage entry with the header value.

• If false (the default), ESS keeps the baggage entry.

For details, Duplicate Property Definition

INRUPT_REQUEST_METADATA_REFLECTOR_HEADER_ALLOW

A comma-separated list of application-defined properties that can return as response headers (unless specified in the corresponding INRUPT_REQUEST_METADATA_REFLECTOR_HEADER_DENY ).

This configuration is case-sensitive to the propagated properties in the baggage.

Tip

• To return a propagated property that was added via the INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW configuration, ensure that the cases of these properties match.

• You may need to update QUARKUS_HTTP_CORS_EXPOSED_HEADERS to extend the list of CORS-safelisted response headers .

See:

• Manage Application-Defined Metadata Propagation to configure.

• Application-Defined Metadata for more information.

INRUPT_REQUEST_METADATA_REFLECTOR_HEADER_DENY

A comma-separated list of application-defined properties to exclude from returning as response headers. This setting takes precedence over INRUPT_REQUEST_METADATA_REFLECTOR_HEADER_ALLOW .

This configuration is case-sensitive to the propagated properties in the baggage.

Tip

To exclude a propagated property that was added via the INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW configuration, ensure that the cases of these properties match.

See:

• Manage Application-Defined Metadata Propagation to configure.

• Application-Defined Metadata for more information.

General

INRUPT_JWT_ALLOWED_SIGNATURE_ALGORITHMS

Default: ES256, RS256

A comma-separated list that specifies the allowed encryption algorithms used to sign ID tokens.

INRUPT_JWT_ISSUER_ALLOW_LIST

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

• If unset, the service accepts all Solid-OIDC issuers with the exception of those in the INRUPT_JWT_ISSUER_DENY_LIST.

• If set, the service accepts only those Solid-OIDC issuers in the list with the following exception:

  • If an issuer is in both INRUPT_JWT_ISSUER_ALLOW_LIST and INRUPT_JWT_ISSUER_DENY_LIST, the INRUPT_JWT_ISSUER_DENY_LIST supersedes the INRUPT_JWT_ISSUER_ALLOW_LIST and the issuer is not accepted by ESS.

See also INRUPT_JWT_ISSUER_DENY_LIST.

INRUPT_JWT_ISSUER_DENY_LIST

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

• If unset, the service accepts all Solid-OIDC issuers unless INRUPT_JWT_ISSUER_ALLOW_LIST is set, in which case, the service only accepts those in the INRUPT_JWT_ISSUER_ALLOW_LIST .

• If set, the service disallows the Solid-OIDC issuers in the list. If INRUPT_JWT_ISSUER_ALLOW_LIST is also set, issuers not in the INRUPT_JWT_ISSUER_ALLOW_LIST are also disallowed.

QUARKUS_LOG_LEVEL

Default: INFO

Logging level.

Additional Information

See also Quarkus Configuration Options