Add Solid Notifications proposal #3
Conversation
|
Great! Looks good on a high level; shall we just version and/or date it, and perhaps also have a clear inline "status: proposal (no consensus)" or something? For people who stumble upon it via various channels. |
Yes, there are some different ways to do this -- let's talk about it at the panel meeting (or in this thread)
Very good idea. I added a |
| 1. **Time-bound subscriptions** - occasionally, a client only needs a subscription to be in effect for a limited period of time. While a client may easily close a WebSocket itself, subscriptions for other, more asynchronous forms of notifications, such as LDN alerts or WebHook operations, may be more difficult to terminate. | ||
| 1. **Avoiding missing updates** - for WebSockets and protocols that rely on an active, live connection to a notification server, the notification protocol needs to make sure that clients do not miss notifications in the event of a dropped connection. | ||
| 1. **Protocol negotiation** - a given Solid Notification server may support certain technologies (e.g. WebSockets and LDN) but not others (e.g. EventSource and WebSub). Likewise, a client may not support the same set of protocols that are implemented by a server. As such, there needs to be a mechanism for clients and servers to agree on a mutually supported protocol. In addition to simply determining the set of protocols that work for client and server, there may be particular features (e.g. notification aggregation, notification filtering) that are required for the client. This could be used to further filter the protocol selection. | ||
| 1. **Security** - a client should not be able to subscribe to resources to which it does not have read access. |
There was a problem hiding this comment.
It may also be worth mentioning that a client should be able to trust that the notifications it receives aren't forged.
|
|
||
| **Note**: the notification panel should define a particular JSON-LD @context for use with JSON-LD serializations. | ||
|
|
||
| **Note**: the use of a well-known resource is based on suggestions to avoid too many link headers, but that is not a settled issue. |
There was a problem hiding this comment.
Just a general comment that I like this use of .well-known as a discovery mechanism for server support. It has broad adoption in other protocols, fits nicely here, and would useful for other things, like whether a server supports / enforces data validation, etc.
|
|
||
| The Subscription API requires authorization. This document does not define the specific technology used to authorize requests; rather, it defers to the Solid Protocol sections on Authentication and Authorization. It is out of scope for this document to describe how a client fetches an authorization token. Solid-OIDC is one example of an authentication mechanism that could be used with Solid Notifications. | ||
|
|
||
| Resource-based Access controls MUST be enforced for every subscription. A client MUST be permitted to read the resource to which it subscribes. |
There was a problem hiding this comment.
| Resource-based Access controls MUST be enforced for every subscription. A client MUST be permitted to read the resource to which it subscribes. | |
| Resource-based Access controls MUST be enforced for every subscription. A client MUST be permitted to read the resources to which it subscribes. |
Suggest pluralizing, since we should be able to subscribe eventually to topics that apply to multiple resources.
There was a problem hiding this comment.
The challenge of subscribing to multiple resources on a single channel is that other features of this interaction fall apart.
For instance, if state refers to the last state of a resource, what does it mean for multiple resources?
If a client accepts updates at only a certain rate, what happens if two messages appear from different resources? Is one dropped?
At the underlying TCP layer (when HTTP/2 is used), all of the interactions occur over a single TCP socket, so there isn't additional network overhead when opening multiple such connections.
|
|
||
| { | ||
| "@context": ["https://www.w3.org/ns/solid/notification/v1"], | ||
| "type": "WebSocketSubscription2021", |
There was a problem hiding this comment.
For clarification, I assume the server will only respond with a(?) subscription channel that is supported by the client. What happens if there are none? Or if there is multiple? (In the latter case, I assume it will then be up to the client to decide which one to use).
There was a problem hiding this comment.
A server responds with either a single subscription channel or returns a 4xx error.
There was a problem hiding this comment.
OK. As only a single channel will be returned, I would suggest that the request lists the types in preferred order just in case there is multiple overlap.
| * `WebHookSubscription2021` | ||
|
|
||
| **Note**: the naming convention used here follows a pattern used by the Verifiable Credentials community, making it possible to distinguish between different versions of these subscription types. Other naming conventions can achieve the same end. | ||
|
|
There was a problem hiding this comment.
To hide some of the complexity, would there be any advantage of having a universal notifications layer that will handle common elements of the different subscription types (similar in idea as solid/authorization-panel#253 for authorization)?
| Much of the Solid Protocol is built on a RESTful API. This allows Solid to make use of well-understood interactions with resources on the Web, and this satisfies many use cases for client applications in the Solid ecosystem. However, for interactive client applications with multiple participants, chat-apps being just one such example, a RESTful API is too limited, as clients need to rely on polling in order to discover changes in the underlying data. | ||
|
|
||
| A notification API for Solid would complement the core RESTful API so that clients can listen for updates to particular resources. In addition, a notification-based mechanism may reduce latency and load on a Pod server. | ||
|
|
There was a problem hiding this comment.
Add a mention that existing Sold servers and clients implementing a notification protocol based on web sockets, and this being used for example for chat applications, collaborative editors, etc. It is disingenuous to write as though this is not currently already running. This protocol serves to provide a more secure and more modular version of the same functionality.
There was a problem hiding this comment.
Noted. The introduction text will likely be completely rewritten. Does this concern block merging this PR in its present form?
|
|
||
| ## Authentication and Authorization | ||
|
|
||
| The Subscription API requires authorization. This document does not define the specific technology used to authorize requests; rather, it defers to the Solid Protocol sections on Authentication and Authorization. It is out of scope for this document to describe how a client fetches an authorization token. Solid-OIDC is one example of an authentication mechanism that could be used with Solid Notifications. |
There was a problem hiding this comment.
The solid spec must define the whole protocol, including how the auth plugs into the notification. Propose that this document does define that. Otherwise we need another parallel document alongside this. The spec must completely define exactly ow to build a solid server.
There was a problem hiding this comment.
Noted. Authorization is a topic that will need quite a bit of discussion in the panel and deserves its own dedicated thread. Does this concern block merging this PR in its present form?
| "actor":[ | ||
| "<WebID>" | ||
| ], | ||
| "object":{ |
There was a problem hiding this comment.
Suggest a level 2 protocol in which the triples which changed in an RDF resource are included in the notification.
There was a problem hiding this comment.
Noted. The contents of a notification will be discussed and deserves its own thread of conversation. Does this concern block merging this PR in its present form?
|
I already created issue #7 on the proposal from this PR. I would like to encourage everyone who can't make simple inline suggestions on this PR to create an issue to track what should be addressed in future PRs. |
|
I see @kevin-inrupt already created all the issues to track feedback from this PR. I understand it's ready to be merged as we discussed yesterday. |
A rendered version of this proposal is available at https://github.com/acoburn/notifications-panel/blob/notification-proposal/proposals/solid-notifications.md
This PR includes an initial proposal for Solid-Notifications. This is based on a design implemented by the Inrupt Enterprise Solid Server. The modifications from that design are largely cosmetic, converting JSON-based flows into JSON-LD.
If this seems like an acceptable starting point, the text would need to be converted into another format (e.g. bikeshed), and the language tightened to fit within general patterns for specification writing. Other formatting and naming changes will surely be discussed.
There are various Note sections where I am identifying areas that clearly need further discussion.