streaming-http-subscription-2021.bs

<pre class='metadata'>
Title: Solid StreamingHTTPSubscription2021
Boilerplate: issues-index no
Shortname: solid-streaming-http-subscription-2021
Level: 1
Status: CG-DRAFT
Group: solidcg
ED: https://solid.github.io/notifications/streaming-http-subscription-2021
Repository: https://github.com/solid/notifications
Inline Github Issues: title
Markup Shorthands: markdown yes
Max ToC Depth: 2
Editor: [elf Pavlik](https://elf-pavlik.hackers4peace.net/)
!Version: 0.1
Abstract:
  The [[!Solid.Notifications]] defines a set of interaction patterns for agents to establish subscriptions to resources in a Solid Storage.

  This specification defines a subscription type that applies these patterns to the Fetch API.
</pre>

# Introduction # {#introduction}

*This section is non-normative.*

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

This document describes a Solid Notifications subscription type that makes use of the Fetch 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.

## Terminology ## {#terminology}

**This section is non-normative.**

This document uses terminology from the Solid Notification Protocol, including "subscription API", "gateway API".
This document also uses terms from The OAuth 2.0 Authorization Framework specification,
including "resource server", "authorization server", "access token", and "client",
as well as terms from the WebSub specification, including "topic".


# StreamingHTTPSubscription2021 Type # {#subscription-type}

This specification defines the StreamingHTTPSubscription2021 type for use with Solid Notifications subscriptions.
that use the Fetch API.

An StreamingHTTPSubscription2021 API MUST conform to the [Solid Notifications Protocol](https://solid.github.io/notifications/protocol#discovery).

An StreamingHTTPSubscription2021 API SHOULD support the [Solid Notifications Features](https://solid.github.io/notifications/protocol#notification-features).

The StreamingHTTPSubscription2021 type defines the following properties:

: source
:: The source property is used in the body of the subscription response.
    The value of source property MUST be a URI, using the `https` scheme.
    A JavaScript client would use the entire value as input to the `fetch` function.

A client establishes a subscription using the StreamingHTTPSubscription2021 type by sending an authenticated
subscription request to the hypermedia API retrieved via Solid Notifications discovery.

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

<script type="text/turtle">
PREFIX doap: <http://usefulinc.com/ns/doap#>
PREFIX spec: <http://www.w3.org/ns/spec#>

<>
  a doap:Specification ;
  spec:requirement
        <#req1> ,
        <#req2> ,
        <#req3> .
<#req1>
  spec:requirementSubject <#subscription-request> ;
  spec:requirementLevel spec:MUST ;
  spec:statement "The type field MUST contain the type of subscription being requested."@en .
<#req2>
  spec:requirementSubject <#subscription-request> ;
  spec:requirementLevel spec:MUST ;
  spec:statement "The topic field MUST contain the URL of the resource a client wishes to subscribe to changes."@en .
<#req3>
  spec:requirementSubject <#subscription-response> ;
  spec:requirementLevel spec:MUST ;
  spec:statement "The value of source property MUST be a URI, using the https scheme."@en .

</script>

## Subscription Example ## {#example}

*This section is non-normative.*

An example `POST` request using a `DPoP` bound access token is below:

```http
POST /subscription
Authorization: DPoP <token>
DPoP: <proof>
Content-Type: application/ld+json
```
```jsonld
{
  "@context": ["https://www.w3.org/ns/solid/notification/v1"],
  "type": "StreamingHTTPSubscription2021",
  "topic": "https://storage.example/resource",
  "state": "opaque-state",
  "expiration": "2021-12-23T12:37:15Z",
  "rate": "PT10s"
}
```
> POST request including type and topic targeting the Notification Subscription API.

Issue(36):

A successful response will contain a URL to the subscription API that can be used directly with a JavaScript client.

```http
Content-Type: application/ld+json
```
```jsonld
{
  "@context": "https://www.w3.org/ns/solid/notification/v1",
  "type": "StreamingHTTPSubscription2021",
  "source": "https://fetch.example/?auth=Ys3KiUq"
}
```
> Response to the POST request, including subscription type and the notifications source.

In JavaScript, a client can use the data in the response to establish a connection to the Fetch API.
And define how to handle notifications

```js
const response = await fetch('https://fetch.example/?auth=Ys3KiUq')
const textStream = response.body.pipeThrough(new TextDecoderStream());
for await (const notificationText of textStream) {
  parseAndHandle(notificationText)
}
```

Issue(46):

# Authentication and Authorization # {#auth}

Streaming HTTP Subscription has the advantage of being able to authenticate with the Subscription API
as well as the notifications source. The same *access token* can be used with both resources.
This doesn't just rely on the notifications source being a [Capability URL](https://www.w3.org/TR/capability-urls/) as many other subscriptions types do.

As described by the Solid Notifications Protocol section on Authorization,
the Streaming HTTP subscription API requires authorization and follows the guidance of the Solid Protocol
sections on Authentication and Authorization [[!Solid.Protocol]].

It is beyond the scope of this document to describe how a client fetches an access token.
Solid-OIDC is one example of an authentication mechanism that could be used with Solid Notifications [[!Solid.OIDC]].

<pre class=biblio>
{
    "Solid.Protocol": {
        "authors": [
            "Sarven Capadisli",
            "Tim Berners-Lee",
            "Ruben Verborgh",
            "Kjetil Kjernsmo"
        ],
        "href": "https://solidproject.org/TR/protocol",
        "title": "Solid Protocol",
        "publisher": "W3C Solid Community Group"
    },
    "Solid.Notifications": {
        "authors": [
            "Aaron Coburn",
            "Sarven Capadisli"
        ],
        "href": "https://solid.github.io/notifications/protocol",
        "title": "Solid Notifications Protocol",
        "publisher": "W3C Solid Community Group"
    },
    "Solid.OIDC": {
        "authors": [
            "Aaron Coburn",
            "elf Pavlik",
            "Dmitri Zagidulin"
        ],
        "href": "https://solid.github.io/solid-oidc",
        "title": "Solid-OIDC",
        "publisher": "W3C Solid Community Group"
    }
}
</pre>