From 16ce95820e02f1caaa84171846a82972fcb1d794 Mon Sep 17 00:00:00 2001 From: elf Pavlik Date: Wed, 11 Jan 2023 22:22:15 -0600 Subject: [PATCH 1/5] initial WebhookChannel2023 --- .gitignore | 1 + streaming-http-channel-2023.html | 776 +++++++++++++++++++++++++++++++ webhook-channel-2023.bs | 192 ++++++++ 3 files changed, 969 insertions(+) create mode 100644 streaming-http-channel-2023.html create mode 100644 webhook-channel-2023.bs diff --git a/.gitignore b/.gitignore index dc5377e..6ad871a 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ node_modules streaming-http-subscription-2021.html webpush-subscription-2022.html +webhook-channel-2023.html diff --git a/streaming-http-channel-2023.html b/streaming-http-channel-2023.html new file mode 100644 index 0000000..1117552 --- /dev/null +++ b/streaming-http-channel-2023.html @@ -0,0 +1,776 @@ + + + + + Solid StreamingHTTPChannel2023 + + + + + + + + + + + + + + + + +
+

+

Solid StreamingHTTPChannel2023

+

Editor’s Draft,

+
+ More details about this document +
+
+
This version: +
https://solid.github.io/notifications/streaming-http-channel-2023 +
Issue Tracking: +
GitHub +
Editor: +
elf Pavlik +
+
+
+
+

Copyright © 2023 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.

+
+
+
+

Abstract

+

The [Solid.Notifications.Protocol] defines a set of interaction patterns for agents to receive notification + + about changes to resources in a Solid Storage.

+

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

+
+

Status of this document

+
+

+

Version: 0.1

+

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.

+
+
+ +
+

1. Introduction

+

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 Streaming HTTP Channel 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 Fetch API.

+

This specification is for:

+ +

1.1. 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".

+

2. StreamingHTTPChannel2023 Type

+

This specification defines the StreamingHTTPChannel2023 type for use with Solid Notifications channels. +that use the Fetch API.

+

An StreamingHTTPChannel2023 MUST conform to the Solid Notifications Protocol.

+

An StreamingHTTPChannel2023 SHOULD support the Solid Notifications Features.

+

The StreamingHTTPChannel2023 type further constrains following properties properties:

+
+
receiveFrom +
+

The receiveFrom property +is used in the body of the subscription response. +The value of source property MUST be a URI, using the https scheme.

+
+

A client establishes a subscription using the StreamingHTTPChannel2023 type by sending an authenticated +subscription request to the Subscription Resource retrieved via Solid Notifications discovery.

+

For StreamingHTTPChannel2023 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 type of channel being requested: StreamingHTTPChannel2023 The topic field MUST contain the URL of the resource a client wishes to subscribe to changes.

+ +

2.1. Subscription Example

+

This section is non-normative.

+

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

+
POST /subscription
+Authorization: DPoP <token>
+DPoP: <proof>
+Content-Type: application/ld+json
+
+
{
+  "@context": ["https://www.w3.org/ns/solid/notification/v1"],
+  "type": "StreamingHTTPChannel2023",
+  "topic": "https://storage.example/resource",
+  "state": "opaque-state",
+  "endAt": "2023-12-23T12:37:15Z",
+  "rate": "PT10s"
+}
+
+
+

POST request including type and topic targeting the Notification Subscription Resource.

+
+

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

+
Content-Type: application/ld+json
+
+
{
+  "@context": "https://www.w3.org/ns/solid/notification/v1",
+  "type": "StreamingHTTPChannel2023",
+  "receiveFrom": "https://fetch.example/aca3cb0a-fb0a-4091-b9f8-8117d2cdb392"
+}
+
+
+

Response to the POST request, including channel type and the receiveFrom URL.

+
+

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

+
const response = await fetch('https://fetch.example/aca3cb0a-fb0a-4091-b9f8-8117d2cdb392')
+const textStream = response.body.pipeThrough(new TextDecoderStream());
+for await (const notificationText of textStream) {
+  parseAndHandle(notificationText)
+}
+
+ +

3. Authentication and Authorization

+

Streaming HTTP Channel has the advantage of being able to authenticate with the Subscription Resource +as well as the notifications receiveFrom. The same access token can be used with both resources. +This doesn’t just rely on the notifications source being a Capability URL as many other channel types do.

+

As described by the Solid Notifications Protocol section on Authorization, +the Streaming HTTP Channel 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].

+
+
+

Conformance

+

Document conventions

+

Conformance requirements are expressed + with a combination of descriptive assertions + and RFC 2119 terminology. + The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” + in the normative parts of this document + are to be interpreted as described in RFC 2119. + However, for readability, + these words do not appear in all uppercase letters in this specification.

+

All of the text of this specification is normative + except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

+

Examples in this specification are introduced with the words “for example” + or are set apart from the normative text + with class="example", + like this:

+
+ +

This is an example of an informative example.

+
+

Informative notes begin with the word “Note” + and are set apart from the normative text + with class="note", + like this:

+

Note, this is an informative note.

+

Conformant Algorithms

+

Requirements phrased in the imperative as part of algorithms + (such as "strip any leading space characters" + or "return false and abort these steps") + are to be interpreted with the meaning of the key word + ("must", "should", "may", etc) + used in introducing the algorithm.

+

Conformance requirements phrased as algorithms or specific steps + can be implemented in any manner, + so long as the end result is equivalent. + In particular, the algorithms defined in this specification + are intended to be easy to understand + and are not intended to be performant. + Implementers are encouraged to optimize.

+
+ +

References

+

Normative References

+
+
[RFC2119] +
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119 +
[Solid.Notifications.Protocol] +
Aaron Coburn; et al. Solid Notifications Protocol. URL: https://solidproject.org/TR/notifications-protocol +
[Solid.OIDC] +
Aaron Coburn; elf Pavlik; Dmitri Zagidulin. Solid-OIDC. URL: https://solidproject.org/TR/oidc +
[Solid.Protocol] +
Sarven Capadisli; et al. Solid Protocol. URL: https://solidproject.org/TR/protocol +
\ No newline at end of file diff --git a/webhook-channel-2023.bs b/webhook-channel-2023.bs new file mode 100644 index 0000000..9d5406c --- /dev/null +++ b/webhook-channel-2023.bs @@ -0,0 +1,192 @@ +
+Title: Solid WebhookChannel2023
+Boilerplate: issues-index no
+Local Boilerplate: logo yes
+Shortname: solid-webhook-channel-2023
+Level: 1
+Status: w3c/ED
+Group: Solid Community Group
+Favicon: https://solidproject.org/TR/solid.svg
+ED: https://solid.github.io/notifications/webhook-channel-2023
+Repository: https://github.com/solid/notifications
+Inline Github Issues: title
+Markup Shorthands: markdown yes
+Max ToC Depth: 2
+Editor: Jackson Morgan
+Editor: [elf Pavlik](https://elf-pavlik.hackers4peace.net/)
+Abstract:
+  The [[!Solid.Notifications]] defines a set of interaction patterns for agents to receive notification
+  about changes to resources in a Solid Storage.
+
+  This specification defines a channel type that applies these patterns to the Webhooks.
+Status Text:
+  **Version: 0.1**
+  
+  This section describes the status of this document at the time of its publication.
+
+  This document was published by the [Solid Community Group](https://www.w3.org/community/solid/) as
+  an Editor’s Draft. The sections that have been incorporated have been reviewed following the
+  [Solid process](https://github.com/solid/process). However, the information in this document is
+  still subject to change. You are invited to [contribute](https://github.com/solid/solid-oidc/issues)
+  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)](https://www.w3.org/community/about/process/cla/). A human-readable
+  [summary](https://www.w3.org/community/about/process/cla-deed/) is available.
+
+ +# 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. +This specification defines a subscription type that applies these patterns to WebHooks. + +## Specification Goals ## {#goals} + +In addition to the goals set forth by the [[!Solid.Notifications]] , this specification has goals +required by the WebHooks use case: + + 1. **Verifiable requests to a notification receiver** - a notification receiver must be able to confirm + if a request truly came from a specific notification sender. + 2. **Unsubscribing from a WebHook** - Unlike websockets, where sockets can simply be closed by the client, + if a notifications receiver wants to unsubscribe from a webhook, it must alert the subscription server. + +Issue(155): + +Issue(145): + +## Terminology ## {#terminology} + +**This section is non-normative.** + +This specification uses the terms from the [[!Solid.Notifications]] specification. + +# WebhookChannel2023 Type # {#channel-type} + +This specification defines the WebhookChannel2023 type for use with Solid Notifications channels that use the Webhooks. + +An WebhookChannel2023 MUST conform to the [Solid Notifications Protocol](https://solid.github.io/notifications/protocol#discovery). + +An WebhookChannel2023 SHOULD support the [Solid Notifications Features](https://solid.github.io/notifications/protocol#notification-features). + +The WebhookChannel2023 type further constrains following properties properties: + +: sendTo +:: The *sendTo* property + is used in the body of the subscription request. + The value of *sendTo* property MUST be a URI, using the `https` scheme. + +A client establishes a subscription using the WebhookChannel2023 type by sending an authenticated +subscription request to the Subscription Resource retrieved via Solid Notifications discovery. + +For WebhookChannel2023 interactions, the subscription client sends a subscription request to an apropriate +Subscription Resource. The only required fields in the payload are *type*, *topic* and *sendTo*. +* The **type** field MUST contain the type of channel being requested: `WebhookChannel2023` +* The **topic** field MUST contain the URL of the resource a client wishes to subscribe to changes. +* The **sendTo** field MUST contain the `https` URL of the webhook endpoint, where the notification sender + is expected to send notifications. + +For WebhookChannel2023 interactions, the subscription server responds with a subscription response. +The only required fields in the payload are *id*, *type*, *topic*, *sender* +* The **id** field MUST be a URI, which identifies created notification channel. +* The **type** field MUST contain the type of channel created: `WebhookChannel2023` Web +* The **topic** field MUST contain the URL of the resource which notifications will be about. +* The **sender** field MUST contain URI, which identifies the notifications sender + +Issue(134): + +## Subscription Example ## {#example} + +*This section is non-normative.* + +An example `POST` request, including the webhook endpoint, using a `DPoP` bound access token is below: + +```http +POST /subscription +Host: channels.example +Authorization: DPoP +DPoP: +Content-Type: application/ld+json +``` +```jsonld +{ + "@context": ["https://www.w3.org/ns/solid/notification/v1"], + "type": "WebhookChannel2023", + "topic": "https://storage.example/resource", + "sendTo": "https://webhook.example/871b84e7", + "state": "opaque-state", + "expiration": "2023-12-23T12:37:15Z", + "rate": "PT10s" +} +``` +> POST request including type, topic and sendTo targeting the Notification Subscription Resource. + +A successful response will contain a URL identifying the notification sender: + +```http +Content-Type: application/ld+json +``` +```jsonld +{ + "@context": "https://www.w3.org/ns/solid/notification/v1", + "id": "https://channels.example/ea1fcf13-7482-4bbb-a6c1-c168ddd7b0aa" + "type": "WebhookChannel2023", + "sender": "https://sender.example/#it", + "expiration": "2023-12-23T12:37:15Z", + "rate": "PT10s" +} +``` +> Response to the POST request, including channel id, type and the sender identity. + +# Authentication and Authorization # {#auth} + +* Subscription client MUST perform authenticated subscription request. +* Notification Sender MUST perform authenticated request to *sendTo* webhook endpoint, + using identity provided as *sender* in the subscription response. + +As described by the Solid Notifications Protocol section on Authorization, +the WebhookChannel2023 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]]. + +
+{
+    "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"
+    }
+}
+
From 0b65ecf5b087d18c73f32d61a6cee57564e6fc88 Mon Sep 17 00:00:00 2001 From: elf Pavlik Date: Wed, 15 Feb 2023 07:22:02 -0600 Subject: [PATCH 2/5] deleted bikeshed output --- streaming-http-channel-2023.html | 776 ------------------------------- 1 file changed, 776 deletions(-) delete mode 100644 streaming-http-channel-2023.html diff --git a/streaming-http-channel-2023.html b/streaming-http-channel-2023.html deleted file mode 100644 index 1117552..0000000 --- a/streaming-http-channel-2023.html +++ /dev/null @@ -1,776 +0,0 @@ - - - - - Solid StreamingHTTPChannel2023 - - - - - - - - - - - - - - - - -
-

-

Solid StreamingHTTPChannel2023

-

Editor’s Draft,

-
- More details about this document -
-
-
This version: -
https://solid.github.io/notifications/streaming-http-channel-2023 -
Issue Tracking: -
GitHub -
Editor: -
elf Pavlik -
-
-
-
-

Copyright © 2023 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.

-
-
-
-

Abstract

-

The [Solid.Notifications.Protocol] defines a set of interaction patterns for agents to receive notification - - about changes to resources in a Solid Storage.

-

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

-
-

Status of this document

-
-

-

Version: 0.1

-

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.

-
-
- -
-

1. Introduction

-

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 Streaming HTTP Channel 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 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.

    -
-

1.1. 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".

-

2. StreamingHTTPChannel2023 Type

-

This specification defines the StreamingHTTPChannel2023 type for use with Solid Notifications channels. -that use the Fetch API.

-

An StreamingHTTPChannel2023 MUST conform to the Solid Notifications Protocol.

-

An StreamingHTTPChannel2023 SHOULD support the Solid Notifications Features.

-

The StreamingHTTPChannel2023 type further constrains following properties properties:

-
-
receiveFrom -
-

The receiveFrom property -is used in the body of the subscription response. -The value of source property MUST be a URI, using the https scheme.

-
-

A client establishes a subscription using the StreamingHTTPChannel2023 type by sending an authenticated -subscription request to the Subscription Resource retrieved via Solid Notifications discovery.

-

For StreamingHTTPChannel2023 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 type of channel being requested: StreamingHTTPChannel2023 The topic field MUST contain the URL of the resource a client wishes to subscribe to changes.

- -

2.1. Subscription Example

-

This section is non-normative.

-

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

-
POST /subscription
-Authorization: DPoP <token>
-DPoP: <proof>
-Content-Type: application/ld+json
-
-
{
-  "@context": ["https://www.w3.org/ns/solid/notification/v1"],
-  "type": "StreamingHTTPChannel2023",
-  "topic": "https://storage.example/resource",
-  "state": "opaque-state",
-  "endAt": "2023-12-23T12:37:15Z",
-  "rate": "PT10s"
-}
-
-
-

POST request including type and topic targeting the Notification Subscription Resource.

-
-

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

-
Content-Type: application/ld+json
-
-
{
-  "@context": "https://www.w3.org/ns/solid/notification/v1",
-  "type": "StreamingHTTPChannel2023",
-  "receiveFrom": "https://fetch.example/aca3cb0a-fb0a-4091-b9f8-8117d2cdb392"
-}
-
-
-

Response to the POST request, including channel type and the receiveFrom URL.

-
-

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

-
const response = await fetch('https://fetch.example/aca3cb0a-fb0a-4091-b9f8-8117d2cdb392')
-const textStream = response.body.pipeThrough(new TextDecoderStream());
-for await (const notificationText of textStream) {
-  parseAndHandle(notificationText)
-}
-
- -

3. Authentication and Authorization

-

Streaming HTTP Channel has the advantage of being able to authenticate with the Subscription Resource -as well as the notifications receiveFrom. The same access token can be used with both resources. -This doesn’t just rely on the notifications source being a Capability URL as many other channel types do.

-

As described by the Solid Notifications Protocol section on Authorization, -the Streaming HTTP Channel 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].

-
-
-

Conformance

-

Document conventions

-

Conformance requirements are expressed - with a combination of descriptive assertions - and RFC 2119 terminology. - The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” - in the normative parts of this document - are to be interpreted as described in RFC 2119. - However, for readability, - these words do not appear in all uppercase letters in this specification.

-

All of the text of this specification is normative - except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

-

Examples in this specification are introduced with the words “for example” - or are set apart from the normative text - with class="example", - like this:

-
- -

This is an example of an informative example.

-
-

Informative notes begin with the word “Note” - and are set apart from the normative text - with class="note", - like this:

-

Note, this is an informative note.

-

Conformant Algorithms

-

Requirements phrased in the imperative as part of algorithms - (such as "strip any leading space characters" - or "return false and abort these steps") - are to be interpreted with the meaning of the key word - ("must", "should", "may", etc) - used in introducing the algorithm.

-

Conformance requirements phrased as algorithms or specific steps - can be implemented in any manner, - so long as the end result is equivalent. - In particular, the algorithms defined in this specification - are intended to be easy to understand - and are not intended to be performant. - Implementers are encouraged to optimize.

-
- -

References

-

Normative References

-
-
[RFC2119] -
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119 -
[Solid.Notifications.Protocol] -
Aaron Coburn; et al. Solid Notifications Protocol. URL: https://solidproject.org/TR/notifications-protocol -
[Solid.OIDC] -
Aaron Coburn; elf Pavlik; Dmitri Zagidulin. Solid-OIDC. URL: https://solidproject.org/TR/oidc -
[Solid.Protocol] -
Sarven Capadisli; et al. Solid Protocol. URL: https://solidproject.org/TR/protocol -
\ No newline at end of file From f2b27195b8cec4b5f05273c7b6bcd0cf3aaaa802 Mon Sep 17 00:00:00 2001 From: elf Pavlik Date: Wed, 15 Feb 2023 20:55:21 -0600 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Ted Thibodeau Jr --- webhook-channel-2023.bs | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/webhook-channel-2023.bs b/webhook-channel-2023.bs index 9d5406c..5d6d835 100644 --- a/webhook-channel-2023.bs +++ b/webhook-channel-2023.bs @@ -76,27 +76,27 @@ An WebhookChannel2023 SHOULD support the [Solid Notifications Features](https:// The WebhookChannel2023 type further constrains following properties properties: -: sendTo -:: The *sendTo* property +: `sendTo` +:: The *`sendTo`* property is used in the body of the subscription request. - The value of *sendTo* property MUST be a URI, using the `https` scheme. + The value of the *`sendTo`* property MUST be a URI, using the `https` scheme. A client establishes a subscription using the WebhookChannel2023 type by sending an authenticated subscription request to the Subscription Resource retrieved via Solid Notifications discovery. -For WebhookChannel2023 interactions, the subscription client sends a subscription request to an apropriate -Subscription Resource. The only required fields in the payload are *type*, *topic* and *sendTo*. -* The **type** field MUST contain the type of channel being requested: `WebhookChannel2023` -* The **topic** field MUST contain the URL of the resource a client wishes to subscribe to changes. -* The **sendTo** field MUST contain the `https` URL of the webhook endpoint, where the notification sender +For WebhookChannel2023 interactions, the subscription client sends a subscription request to an appropriate +Subscription Resource. The only required fields in the payload are *`type`*, *`topic`*, and *`sendTo`*. +* The **`type`** field MUST contain the type of channel being requested: `WebhookChannel2023`. +* The **`topic`** field MUST contain the URL of the resource to which changes a client wishes to subscribe. +* The **`sendTo`** field MUST contain the `https` URL of the webhook endpoint, where the notification sender is expected to send notifications. -For WebhookChannel2023 interactions, the subscription server responds with a subscription response. -The only required fields in the payload are *id*, *type*, *topic*, *sender* -* The **id** field MUST be a URI, which identifies created notification channel. -* The **type** field MUST contain the type of channel created: `WebhookChannel2023` Web -* The **topic** field MUST contain the URL of the resource which notifications will be about. -* The **sender** field MUST contain URI, which identifies the notifications sender +For `WebhookChannel2023` interactions, the subscription server responds with a subscription response. +The only required fields in the payload are *`id`*, *`type`*, *`topic`*, *`sender`* +* The **`id`** field MUST be a URI, which identifies the created notification channel. +* The **`type`** field MUST contain the type of channel created: `WebhookChannel2023`. +* The **`topic`** field MUST contain the URL of the resource which notifications will be about. +* The **`sender`** field MUST contain a URI which identifies the notifications sender. Issue(134): @@ -124,7 +124,7 @@ Content-Type: application/ld+json "rate": "PT10s" } ``` -> POST request including type, topic and sendTo targeting the Notification Subscription Resource. +> `POST` request including `type`, `topic`, and `sendTo` targeting the Notification Subscription Resource. A successful response will contain a URL identifying the notification sender: @@ -141,7 +141,7 @@ Content-Type: application/ld+json "rate": "PT10s" } ``` -> Response to the POST request, including channel id, type and the sender identity. +> Response to the `POST` request, including `channel id`, `type`, and `sender identity`. # Authentication and Authorization # {#auth} From 4b35766a3649843dfd99e71b3107d1b49ee9e8c5 Mon Sep 17 00:00:00 2001 From: elf Pavlik Date: Thu, 16 Feb 2023 13:06:48 -0600 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Sarven Capadisli --- webhook-channel-2023.bs | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/webhook-channel-2023.bs b/webhook-channel-2023.bs index 5d6d835..5607881 100644 --- a/webhook-channel-2023.bs +++ b/webhook-channel-2023.bs @@ -15,7 +15,7 @@ Max ToC Depth: 2 Editor: Jackson Morgan Editor: [elf Pavlik](https://elf-pavlik.hackers4peace.net/) Abstract: - The [[!Solid.Notifications]] defines a set of interaction patterns for agents to receive notification + The [[!Solid.Notifications.Protocol]] defines a set of interaction patterns for agents to receive notification about changes to resources in a Solid Storage. This specification defines a channel type that applies these patterns to the Webhooks. @@ -43,12 +43,12 @@ Status Text: *This section is non-normative.* -The [[!Solid.Notifications]] describes a general pattern by which agents can be notified when a Solid Resource changes. +The [[!Solid.Notifications.Protocol]] describes a general pattern by which agents can be notified when a Solid Resource changes. This specification defines a subscription type that applies these patterns to WebHooks. ## Specification Goals ## {#goals} -In addition to the goals set forth by the [[!Solid.Notifications]] , this specification has goals +In addition to the goals set forth by the [[!Solid.Notifications.Protocol]] , this specification has goals required by the WebHooks use case: 1. **Verifiable requests to a notification receiver** - a notification receiver must be able to confirm @@ -64,7 +64,7 @@ Issue(145): **This section is non-normative.** -This specification uses the terms from the [[!Solid.Notifications]] specification. +This specification uses the terms from the [[!Solid.Notifications.Protocol]] specification. # WebhookChannel2023 Type # {#channel-type} @@ -169,10 +169,15 @@ Solid-OIDC is one example of an authentication mechanism that could be used with "title": "Solid Protocol", "publisher": "W3C Solid Community Group" }, - "Solid.Notifications": { + "Solid.Notifications.Protocol": { + "editors": [ + "Sarven Capadisli" + ], "authors": [ "Aaron Coburn", - "Sarven Capadisli" + "Sarven Capadisli", + "elf Pavlik", + "Rahul Gupta" ], "href": "https://solid.github.io/notifications/protocol", "title": "Solid Notifications Protocol", From ed58b2be5f95c094ec7fbb9a7ace2d76fdf57ecb Mon Sep 17 00:00:00 2001 From: elf Pavlik Date: Thu, 16 Feb 2023 13:14:35 -0600 Subject: [PATCH 5/5] [WebhookChannel2023] tweek formatting --- webhook-channel-2023.bs | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/webhook-channel-2023.bs b/webhook-channel-2023.bs index 5607881..4af5ae1 100644 --- a/webhook-channel-2023.bs +++ b/webhook-channel-2023.bs @@ -77,26 +77,26 @@ An WebhookChannel2023 SHOULD support the [Solid Notifications Features](https:// The WebhookChannel2023 type further constrains following properties properties: : `sendTo` -:: The *`sendTo`* property +:: The `sendTo` property is used in the body of the subscription request. - The value of the *`sendTo`* property MUST be a URI, using the `https` scheme. + The value of the `sendTo` property MUST be a URI, using the `https` scheme. A client establishes a subscription using the WebhookChannel2023 type by sending an authenticated subscription request to the Subscription Resource retrieved via Solid Notifications discovery. For WebhookChannel2023 interactions, the subscription client sends a subscription request to an appropriate -Subscription Resource. The only required fields in the payload are *`type`*, *`topic`*, and *`sendTo`*. -* The **`type`** field MUST contain the type of channel being requested: `WebhookChannel2023`. -* The **`topic`** field MUST contain the URL of the resource to which changes a client wishes to subscribe. -* The **`sendTo`** field MUST contain the `https` URL of the webhook endpoint, where the notification sender +Subscription Resource. The only required fields in the payload are `type`, `topic`, and `sendTo`. +* The `type` field MUST contain the type of channel being requested: `WebhookChannel2023`. +* The `topic` field MUST contain the URL of the resource to which changes a client wishes to subscribe. +* The `sendTo` field MUST contain the `https` URL of the webhook endpoint, where the notification sender is expected to send notifications. For `WebhookChannel2023` interactions, the subscription server responds with a subscription response. -The only required fields in the payload are *`id`*, *`type`*, *`topic`*, *`sender`* -* The **`id`** field MUST be a URI, which identifies the created notification channel. -* The **`type`** field MUST contain the type of channel created: `WebhookChannel2023`. -* The **`topic`** field MUST contain the URL of the resource which notifications will be about. -* The **`sender`** field MUST contain a URI which identifies the notifications sender. +The only required fields in the payload are `id`, `type`, `topic`, `sender` +* The `id` field MUST be a URI, which identifies the created notification channel. +* The `type` field MUST contain the type of channel created: `WebhookChannel2023`. +* The `topic` field MUST contain the URL of the resource which notifications will be about. +* The `sender` field MUST contain a URI which identifies the notifications sender. Issue(134):