From 49ed601e34547f816d98db936458389c652c4fe5 Mon Sep 17 00:00:00 2001 From: Ruben Verborgh Date: Tue, 17 Mar 2020 20:54:30 +0100 Subject: [PATCH 1/7] Indicate draft status and version. --- api-websockets.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/api-websockets.md b/api-websockets.md index 5e92d27..a45c716 100644 --- a/api-websockets.md +++ b/api-websockets.md @@ -4,6 +4,10 @@ [Solid specification](README.md); the parent spec and all its components are versioned as a whole. +## Status +This is a _draft_ protocol. +This specific version is identified by the string `solid-ws-draft/v0.1.0-alpha`. + ## Subscribing Live updates are currently only supported through WebSockets. This describes a From 403c9aa8c8f7d389f79f8ec9f3711596a8bae902 Mon Sep 17 00:00:00 2001 From: Ruben Verborgh Date: Tue, 17 Mar 2020 21:00:48 +0100 Subject: [PATCH 2/7] Order instructions chronologically. --- api-websockets.md | 36 ++++++++++++++++++++++++++---------- 1 file changed, 26 insertions(+), 10 deletions(-) diff --git a/api-websockets.md b/api-websockets.md index a45c716..9f61532 100644 --- a/api-websockets.md +++ b/api-websockets.md @@ -8,20 +8,20 @@ versioned as a whole. This is a _draft_ protocol. This specific version is identified by the string `solid-ws-draft/v0.1.0-alpha`. -## Subscribing +## Protocol description Live updates are currently only supported through WebSockets. This describes a subscription mechanism through which clients can be notified in real time of changes affecting a given resource. -The PubSub system is very basic. Clients only need to open a WebSocket -connection and *sub*(scribe) to a given resource URI. If any change occurs in -that resource, a *pub*(lish) event will be sent to all the subscribed clients. - -The WebSocket server URI is the same for any resource located on a given data -space (same hostname). To discover the URI of the WebSocket server, clients can -send an HTTP OPTIONS request. The server will then include an `Updates-Via` header in -the response: +### Discovery +The PubSub system is very basic. +First, a client needs to obtain the URI of the WebSocket. +The WebSocket server URI is the same for any resource +located on a given data space (same hostname). +To discover the URI of the WebSocket server, +clients can send an HTTP `OPTIONS` request. +The server will then include an `Updates-Via` header in the response: REQUEST: @@ -35,9 +35,24 @@ RESPONSE: ```http HTTP/1.1 200 OK ... -Updates-Via: wss://example.org/ +Updates-Via: wss://example.org ``` +### Connection +Then, the client needs to open a WebSocket connection +to that URI. + +For example, in JavaScript, this could be done as follows: + +``` +const socket = new WebSocket('wss://example.org'); +``` + +### Subscription +Then, the client needs to *sub*(scribe) to a given resource URI. +If any change occurs in that resource, +a *pub*(lish) event will be sent to all the subscribed clients. + To subscribe to a resource, clients will need to send the keyword `sub` followed by an empty space and then the URI of the resource: @@ -81,6 +96,7 @@ Then the following notification message will be sent: pub https://example.org/data/ ``` +### Example Here is a Javascript example on how to subscribe to live updates for a `test` resource at `https://example.org/data/test`: From cbc18c911594d2a965a4b9aa6930ef2b65b0002b Mon Sep 17 00:00:00 2001 From: Ruben Verborgh Date: Tue, 17 Mar 2020 21:03:13 +0100 Subject: [PATCH 3/7] Let clients indicate the protocol version. --- api-websockets.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/api-websockets.md b/api-websockets.md index 9f61532..8d60a62 100644 --- a/api-websockets.md +++ b/api-websockets.md @@ -41,11 +41,13 @@ Updates-Via: wss://example.org ### Connection Then, the client needs to open a WebSocket connection to that URI. +The client _SHOULD_ include the protocol version `solid-ws-draft/v0.1.0-alpha` +in the `Sec-WebSocket-Protocol` header. For example, in JavaScript, this could be done as follows: ``` -const socket = new WebSocket('wss://example.org'); +const socket = new WebSocket('wss://example.org', ['solid-ws-draft/v0.1.0-alpha']); ``` ### Subscription @@ -101,7 +103,7 @@ Here is a Javascript example on how to subscribe to live updates for a `test` resource at `https://example.org/data/test`: ```js -var socket = new WebSocket('wss://example.org/'); +var socket = new WebSocket('wss://example.org/', ['solid-ws-draft/v0.1.0-alpha']); socket.onopen = function() { this.send('sub https://example.org/data/test'); }; From 1fe5de9b81d9d59423d0a2b558d0adffad222bcb Mon Sep 17 00:00:00 2001 From: Ruben Verborgh Date: Tue, 17 Mar 2020 21:22:56 +0100 Subject: [PATCH 4/7] Let servers indicate the protocol version. --- api-websockets.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/api-websockets.md b/api-websockets.md index 8d60a62..b770494 100644 --- a/api-websockets.md +++ b/api-websockets.md @@ -50,6 +50,14 @@ For example, in JavaScript, this could be done as follows: const socket = new WebSocket('wss://example.org', ['solid-ws-draft/v0.1.0-alpha']); ``` +Upon connection, +the server SHOULD indicate the protocol version as follows: + +``` +protocol solid-ws-draft/v0.1.0-alpha +warning Unstandardized protocol version, proceed with care +``` + ### Subscription Then, the client needs to *sub*(scribe) to a given resource URI. If any change occurs in that resource, From 87099031a2682649900e99e777b1c081df3ec764 Mon Sep 17 00:00:00 2001 From: Ruben Verborgh Date: Tue, 17 Mar 2020 21:23:14 +0100 Subject: [PATCH 5/7] Warn on missing client protocol. --- api-websockets.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/api-websockets.md b/api-websockets.md index b770494..b3f8709 100644 --- a/api-websockets.md +++ b/api-websockets.md @@ -58,6 +58,13 @@ protocol solid-ws-draft/v0.1.0-alpha warning Unstandardized protocol version, proceed with care ``` +If the client did not specify a `Sec-WebSocket-Protocol` header, +the server SHOULD warn the client as follows: + +``` +warning Missing Sec-WebSocket-Protocol header, expected value 'solid-ws-draft/v0.1.0-alpha' +``` + ### Subscription Then, the client needs to *sub*(scribe) to a given resource URI. If any change occurs in that resource, From db3844d4267c924742869b9100c122cb6ba4f009 Mon Sep 17 00:00:00 2001 From: Ruben Verborgh Date: Tue, 17 Mar 2020 21:23:50 +0100 Subject: [PATCH 6/7] Close on unsupported client protocol. --- api-websockets.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/api-websockets.md b/api-websockets.md index b3f8709..711e488 100644 --- a/api-websockets.md +++ b/api-websockets.md @@ -65,6 +65,16 @@ the server SHOULD warn the client as follows: warning Missing Sec-WebSocket-Protocol header, expected value 'solid-ws-draft/v0.1.0-alpha' ``` +Otherwise, if the set of values obtained +from parsing the `Sec-WebSocket-Protocol` header +does not contain `solid-ws-draft/v0.1.0-alpha`, +then the server SHOULD emit a warning +and SHOULD close the connection: + +``` +error Client does not support protocol solid-ws-draft/v0.1.0-alpha +``` + ### Subscription Then, the client needs to *sub*(scribe) to a given resource URI. If any change occurs in that resource, From ddebf4872ca530c3092b950c1e2ec67be36e906a Mon Sep 17 00:00:00 2001 From: Ruben Verborgh Date: Wed, 18 Mar 2020 11:03:43 +0100 Subject: [PATCH 7/7] Simplified version string. --- api-websockets.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/api-websockets.md b/api-websockets.md index 711e488..cab7ce9 100644 --- a/api-websockets.md +++ b/api-websockets.md @@ -6,7 +6,7 @@ versioned as a whole. ## Status This is a _draft_ protocol. -This specific version is identified by the string `solid-ws-draft/v0.1.0-alpha`. +This specific version is identified by the string `solid/0.1.0-alpha`. ## Protocol description @@ -41,20 +41,20 @@ Updates-Via: wss://example.org ### Connection Then, the client needs to open a WebSocket connection to that URI. -The client _SHOULD_ include the protocol version `solid-ws-draft/v0.1.0-alpha` +The client _SHOULD_ include the protocol version `solid/0.1.0-alpha` in the `Sec-WebSocket-Protocol` header. For example, in JavaScript, this could be done as follows: ``` -const socket = new WebSocket('wss://example.org', ['solid-ws-draft/v0.1.0-alpha']); +const socket = new WebSocket('wss://example.org', ['solid/0.1.0-alpha']); ``` Upon connection, the server SHOULD indicate the protocol version as follows: ``` -protocol solid-ws-draft/v0.1.0-alpha +protocol solid/0.1.0-alpha warning Unstandardized protocol version, proceed with care ``` @@ -62,17 +62,17 @@ If the client did not specify a `Sec-WebSocket-Protocol` header, the server SHOULD warn the client as follows: ``` -warning Missing Sec-WebSocket-Protocol header, expected value 'solid-ws-draft/v0.1.0-alpha' +warning Missing Sec-WebSocket-Protocol header, expected value 'solid/0.1.0-alpha' ``` Otherwise, if the set of values obtained from parsing the `Sec-WebSocket-Protocol` header -does not contain `solid-ws-draft/v0.1.0-alpha`, +does not contain `solid/0.1.0-alpha`, then the server SHOULD emit a warning and SHOULD close the connection: ``` -error Client does not support protocol solid-ws-draft/v0.1.0-alpha +error Client does not support protocol solid/0.1.0-alpha ``` ### Subscription @@ -128,7 +128,7 @@ Here is a Javascript example on how to subscribe to live updates for a `test` resource at `https://example.org/data/test`: ```js -var socket = new WebSocket('wss://example.org/', ['solid-ws-draft/v0.1.0-alpha']); +var socket = new WebSocket('wss://example.org/', ['solid/0.1.0-alpha']); socket.onopen = function() { this.send('sub https://example.org/data/test'); };