EventSourceChannel2023

The Solid Notifications Protocol defines a set of interaction patterns for agents to establish subscriptions to resources.

This specification defines a channel type that applies these patterns to the EventSource Web API.

This section describes the status of this document at the time of its publication.

This document was published by the Solid Community Group as an Editor’s Draft. The sections that have been incorporated have been reviewed following the Solid process. However, the information in this document is still subject to change. You are invited to contribute any feedback, comments, or questions you might have.

Publication as an Editor’s Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

This section is non-normative.

The Solid Notifications Protocol describes a general pattern by which agents can be notified when a Solid Resource changes. In the context of a Web Browser, the EventSource API provides a convenient mechanism for a Solid Storage to alert a subscribing client of these changes.

This document describes a Solid Notifications channel type that makes use of the EventSource Web API.

This specification is for:

• Resource server developers who wish to enable clients to listen for updates to particular resources.
• Application developers who wish to implement a client to listen for updates to particular resources.

Overview

This section is non-normative.

The following diagram shows the high-level interactions involved in this flow. How a client retrieves an access token for step 5 is outside the scope of this document.

This specification defines the EventSourceChannel2023 type for use with Solid Notifications Protocol's subscriptions that use the EventSource Web API. The URI of the channel type is http://www.w3.org/ns/solid/notification#EventSourceChannel2023.

An EventSourceChannel2023 API MUST conform to the Solid Notifications Protocol. [SOLID-NOTIFICATIONS]

A client establishes a subscription using the EventSourceChannel2023 type by sending an authenticated subscription request to the subscription resource based on Solid Notifications Protocol discovery.

For EventSourceChannel2023 interactions, the client sends a JSON-LD payload to the appropriate subscription resource via POST. The only required fields in this interaction are type and topic. The type field MUST contain the EventSourceChannel2023 type. The topic field MUST contain the URL of the resource a client wishes to subscribe to changes.

POST /subscription
Authorization: DPoP <token>
DPoP: <proof>
Content-Type: application/ld+json

{
  "@context": ["https://www.w3.org/ns/solid/notification/v1"],
  "type": "EventSourceChannel2023",
  "topic": "https://storage.example/resource",
  "state": "opaque-state",
  "endAt": "2023-01-11T12:37:15Z",
  "rate": "PT10s"
}

HTTP/2
Content-Type: application/ld+json

{
  "@context": "https://www.w3.org/ns/solid/notification/v1",
  "type": "EventSourceChannel2023",
  "topic": "https://storage.example/data/resource",
  "receiveFrom": "https://eventsource.example/?auth=Ys3KiUq"
}

const es = new EventSource("https://eventsource.example/?auth=Ys3KiUq");

es.onerror(evt => reconnect(evt));
es.onmessage(evt => console.log("Message received: ", evt))

As described by the Solid Notifications Protocol section on Authorization, the EventSource subscription request requires authorization and follows the guidance of the Solid Protocol sections on Authentication and Authorization [SOLID-PROTOCOL].