Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Describe Gateway /things websocket endpoint #142

Open
wants to merge 2 commits into
base: gh-pages
from

Conversation

@hobinjk
Copy link

hobinjk commented Aug 22, 2019

Mirrors current gateway implementation and documents optional addition
of id to WS messages.

Also replaces mythingserver with mywebthingserver for consistency

Fixes #46

hobinjk added 2 commits Aug 22, 2019
In some places it would switch mid example so this replaces all
instances of mythingserver with mywebthingserver since the latter was
more common.
Fix #46

Mirrors current gateway implementation. Also documents optional addition
of `id` to WS messages.
@hobinjk hobinjk requested a review from benfrancis Aug 22, 2019
@hobinjk hobinjk self-assigned this Aug 22, 2019
@mrstegeman mrstegeman added this to Review in WebThings Aug 22, 2019
Copy link
Collaborator

benfrancis left a comment

Thanks very much for drafting this, this is a much needed optimisation!

I recommend that we take a slightly different approach in order to make the gateway-wide WebSocket endpoint dynamically discoverable by WoT clients rather than a hard coded path (explained in the comments). This is dependent on creating a new gateway capability schema and will also require changes to the Web Thing REST API to replace the Things resource with links in a gateway's own Thing Description.

@@ -917,6 +923,37 @@ <h3><code>event</code> message</h3>
</div>
</section>
</section>
<section>
<h2>Gateway WebSocket API</h2>

This comment has been minimized.

Copy link
@benfrancis

benfrancis Aug 29, 2019

Collaborator

I don't think this should be a separate section of the specification. It should all be part of the Web Thing WebSocket API section, which may eventually become a separate W3C "Web Thing Protocol" specification to define a webthing WebSocket sub-protocol.

<p>The Gateway WebSocket API acts as a broader version of the <a href="#web-thing-websocket-api">Web Thing WebSocket API</a> by allowing the client to open one WebSocket connection per Gateway instead of per Thing. The connection then acts as a multiplex of all the Gateway's Things' WebSocket connections. The <code>id</code> member is required for this channel to allow both the Gateway and the WebSocket client to determine with which Thing each message is associated.
<section>
<h3>Protocol Handshake</h3>
<p>To open a WebSocket on a Gateway, an HTTP GET request is upgraded to a WebSocket using a standard <a href="https://tools.ietf.org/html/rfc6455">WebSocket protocol</a> handshake and the "webthing" subprotocol. The WebSocket URL for a Gateway is the "/things" endpoint.</p>

This comment has been minimized.

Copy link
@benfrancis

benfrancis Aug 29, 2019

Collaborator

Note that in section 3 it says "The specific URLs and URL structure of resources are defined by the Thing Description. This specification does not define a fixed URL structure."

It's important that the specification does not rely on hard coded paths like "/things" but instead has endpoints which can be dynamically discovered by a WoT client using any URL structure.

This section makes me realise that while WebSocket endpoints for individual devices can be discovered through the links section of a Thing resource, and a Thing resource can be discovered through links in the Things resource, there is no explicit mechanism for discovering the Things resource itself. We are assigning special behaviour to a resource just because it is called /things.

In Whistler we discussed an alternative approach to this where we treat the gateway itself as a web thing, with a gateway capability schema, and link to the things it manages via its own links member.

If we took this approach we could also provide a gateway-wide WebSocket endpoint in the links member of the gateway's Thing Description. This would ensure that once a client has the URL of the gateway's Thing Description it can discover the WebSocket endpoint directly, without having to rely on a hard coded path.

This approach also has the benefit of being able to define actions on the gateway itself such as "pair", "unpair" and "reboot".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
WebThings
  
Review
2 participants
You can’t perform that action at this time.