Skip to content

Commit 6e04422

Browse files
zolkiszolkis
committed
Update WoT runtime related text based on discussion in #2
Signed-off-by: Zoltan Kis <[email protected]>
1 parent 786fe60 commit 6e04422

File tree

1 file changed

+107
-78
lines changed

1 file changed

+107
-78
lines changed

‎index.html

Lines changed: 107 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -107,26 +107,23 @@
107107
This document defines conformance criteria that apply to a single product: the <dfn>UA</dfn> (user agent) that implements the interfaces it contains.
108108
</p>
109109
<p>
110-
The UA may be implemented in the browser, or in a separate runtime environment.
110+
This specification can be used for implementing the WoT Scripting API in multiple language bindings. Currently ECMAScript and TypeScript definitions are described in this document. For specifying bindings in other languages, extensions of this document may be created later.
111111
</p>
112112
<p>
113-
This specification can be used for implementing the WoT Scripting API in multiple language bindings. Currently ECMAScript and TypeScript definitions are described in this document. For specifying bindings in other languages, extensions of this document may be created later.
113+
The UA may be implemented in the browser, or in a separate runtime environment, such as [Node.js](https://nodejs.org/en/) or small embedded runtimes such as the [JavaScript Runtime for Zephyr OS](https://www.zephyrproject.org/community/blog/introducing-javascript-runtime-zephyr-os).
114114
</p>
115115
<p>
116116
Implementations that use ECMAScript executed in a browser to implement the APIs defined in this document MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]].
117117
</p>
118118
<p>
119-
Implementations that use TypeScript or ECMAScript in a <a>RunTime</a> to implement the APIs defined in this document MUST implement them in a manner consistent with the TypeScript Bindings defined in the TypeScript specification [[!TYPESCRIPT]].
119+
Implementations that use TypeScript or ECMAScript in a runtime to implement the APIs defined in this document MUST implement them in a manner consistent with the TypeScript Bindings defined in the TypeScript specification [[!TYPESCRIPT]].
120120
</p>
121121
<p>
122122
This document serves a general description of the WoT Scripting API. Language and runtime specific issues are discussed in separate extensions of this document.
123123
</p>
124124
</section>
125125

126126
<section> <h2>Terminology and conventions</h2>
127-
<p>
128-
A <dfn>WoT runtime</dfn> or simply <dfn>Runtime</dfn> is defined as a software stack that manages the lifecycle of WoT application scripts (see also the [Wikipedia definition](https://en.wikipedia.org/wiki/Runtime_system)). In the case of ECMAScript and TypeScript scripts, it consists of an ECMAScript interpreter, script lifecycle management, and an operating system API that provides access to local and remote resources. A Runtime can be modeled as a virtual machine in the sense that it should be completely isolated from other execution environments on memory address space, storage address space (file system), network namespace, etc. A runtime may be for instance a Node.js environment, an embedded runtime based on a small JavaScript engine, or provided by a browser.
129-
</p>
130127
<p>
131128
The following terms are defined in [[!WOT-PRACTICES]]:
132129
</p>
@@ -145,11 +142,19 @@
145142

146143
<dt><dfn>JSON-LD</dfn></dt>
147144
<dd>A JSON document that is augmented with support for Linked Data by providing an <code>@context</code> property with a defining URI [[!JSON-LD]].</dd>
148-
149145
</dl>
150146
<p>
151147
<dfn data-lt="consume|consume a TD|consuming a TD">Consuming a Thing Description</dfn> means parsing the <a>Thing Description</a> and building a resource model with the use of <a>Protocol Bindings</a> that can be used in a script for accessing and controlling the Thing. A <a>Thing</a> when starts up, consumes its own <a>TD</a>, then it exposes its <a>WoT interface</a> as a server. Note that a script on a <a>Thing</a> may consume other <a>TD</a>s and expose a combined interface of the consumed <a>Things</a>.
152148
</p>
149+
<p>
150+
A <dfn>WoT Runtime</dfn> or <dfn>WR</dfn> is defined as a software stack that manages the lifecycle of WoT application scripts, implements a script interpreter, an event loop, a security enforcement point for access management and uses an operating system API that provides access to local and remote resources. A <a>WR</a> should be isolated from other execution environments on memory address space, storage address space (file system), network namespace, etc. For instance, a <a>WR</a> may be implemented in a Node.js environment, or in an embedded runtime based on a small JavaScript engine, or in a browser.
151+
</p>
152+
<p class="note">
153+
In this version of the specification, a <a>WR</a> MAY run either an idle event loop, or a script that has been deployed to it by a method that is out of scope of this document. However, new <a>Thing</a>s can be added<a> and Thing</a>s running in the <a>WR</a> can be updated by using the methods of this API from a script run in another <a>WR</a>.
154+
</p>
155+
<p>
156+
A <a>Thing</a> is represented either as a <a>ConsumedThing</a> (for remote <a>Things</a> obtained by discovery) or <a>ExposedThing</a> (local <a>Thing</a>s created with this API inside a <a>WR</a>). All <a>ExposedThing</a>s contained in a <a>WR</a> are serving external requests through the same event loop, and are said to be <dfn>local Things</dfn> to each other. All other <a>Thing</a>s that run in a different <a>WR</a>, even if on the same physical hardware, are said to be <dfn>remote Things</dfn> to each other.
157+
</p>
153158
<p>
154159
The terms <a href="http://www.w3.org/TR/url-1/"><dfn>URL</dfn></a> and
155160
<a href="https://url.spec.whatwg.org/#concept-url-path">
@@ -255,7 +260,7 @@
255260
<ul>
256261
<li>Discover <a>Thing</a>s by filters defined on <a>Thing Description</a>s</li>
257262
<li>Discover <a>Thing</a>s by semantic filters</li>
258-
<li><a>Fetch and consume a TD</a> of a remote <a>Thing</a>.</li>
263+
<li>Fetch and <a>consume a TD</a> of a remote <a>Thing</a>.</li>
259264
<li>On a consumed <a>Thing</a>,
260265
<ul>
261266
<li>Get the value of a property or set of properties.</li>
@@ -307,97 +312,66 @@
307312
</p>
308313
</section>
309314

310-
<section> <h2 id="security">Security and Privacy</h2>
311-
<p>
312-
The trust model, attacker model, threat model and possible mitigation
313-
proposals for the Wot Scripting API are presented in the [Security and Privacy document](http://w3c.github.io/wot-scripting-api/security-privacy.html). This section presents the chosen
314-
security and privacy model through normative requirements to implementations.
315-
</p>
316-
317-
<section> <h3>Chain of Trust</h3>
318-
<p>
319-
Things discoverable and accessible in a WoT network SHOULD be identified and authenticated.
320-
</p>
321-
<p>
322-
The integrity of WoT communication SHOULD be ensured by implementations.
323-
</p>
324-
</section>
325-
326-
<section> <h3>Threat Model</h3>
327-
<p>
328-
The main threats are summarized in the [Security and Privacy document](http://w3c.github.io/web-nfc/security-privacy.html#threats-and-possible-solutions).
329-
</p>
330-
<p>
331-
In this specification the following threats are considered of the highest priority:
332-
<ul>
333-
<li>
334-
Unauthorized gathering of user-sensitive information.
335-
</li>
336-
<li>
337-
Vulnerability of the underlying protocols.
338-
</li>
339-
<li>
340-
Protect the integrity of <a>Thing</a>s and <a>Thing Description</a>s.
341-
</li>
342-
</ul>
343-
</p>
344-
</section>
345-
346-
<section> <h3>Security Mechanisms</h3>
347-
<section> <h4>Identification, Authentication, Authorization</h4>
348-
</section>
349-
350-
<section> <h4>Transport-level security</h4>
351-
</section>
352-
353-
<section> <h4>Application-level security</h4>
354-
</section>
355-
</section>
356-
357-
<section class="informative"> <h3>Security policies</h3>
358-
<p>
359-
This section summarizes the security policies which are specified as
360-
normative requirements in the respective algorithms of this
361-
specification.
362-
</p>
363-
</section>
364-
</section>
365-
366315
<section> <h2>WoT Data Representation</h2>
367316
<p>
368317
</p>
369318
</section>
370319

371320
<section> <h2>The WoT API</h2>
372321
<p>
373-
The API object provides access obtain <a>Thing</a>s by discovery or creation. A <a>Thing</a> is represented either as a <a>ConsumedThing</a> or <a>ExposedThing</a>.
322+
The API object represents an implementation of the <a>WoT Runtime</a> and provides functionality to obtain <a>Thing</a>s by discovery or creation.
374323
</p>
375324
<p>
376325
The <dfn>WoT object</dfn> exposes only functions and has no internal state.
377326
</p>
378-
<p class="issue">
379-
Because of this, implementations MAY use a global object, or provide a constructor, or provide the API object, or by other means (e.g. by `require()`). Since the common denominator across various <a>Runtime</a> types would be to use a constructor, this would be recommended. As a consequence, the <a>ConsumedThing</a> and <a>ExposedThing</a> objects could also be constructed, complete with an asynchronous fetch functionality.
380-
</p>
381327
<p class="note">
382-
The WebIDL interfaces presented in this initial version of the document are based on the [[!WOT-PRACTICES]]. It is expected to be updated soon.
328+
Browser implementations SHOULD use a namespace object such as `wot`, and [Node.js](https://nodejs.org/en/)-like runtimes MAY provide the API object through the [`require()`](https://nodejs.org/api/modules.html) mechanism.
383329
</p>
384330
<pre class="idl">
331+
// [SecureContext]
332+
// [NamespaceObject]
385333
interface WoT {
386-
Promise&lt;void&gt; discover(ThingFilter filter, ThingDiscoveryCallback onfound);
334+
Observable&lt;ConsumedThing&gt; discover(optional ThingFilter filter);
387335

388-
Promise&lt;ConsumedThing&gt; retrieve((USVString or Dictionary) thingReference);
336+
Promise&lt;ConsumedThing&gt; retrieve(USVString url);
389337

390338
Promise&lt;ExposedThing&gt; createThing(ThingInit init);
391339
};
392340

393-
dictionary ThingInit {
341+
dictionary ThingDescription {
342+
USVString url;
343+
};
344+
345+
dictionary ThingInit: ThingDescription {
346+
DOMString name;
347+
USVString url;
348+
};
349+
350+
dictionary ThingFilter: ThingDescription {
351+
boolean local;
394352
DOMString name;
395353
USVString url;
396-
object description;
397354
};
398355

399-
callback ThingDiscoveryCallback = void (ConsumedThing thing);
400356
</pre>
357+
358+
<p>
359+
The <code>discover()</code> method returns an [Observable](https://github.com/tc39/proposal-observable) object that can be subscribed and unsubscribed to.
360+
</p>
361+
<pre class="example">
362+
let subscription = wot.discover().subscribe(
363+
thing => { console.log("Found Thing " + thing.url); },
364+
error => { console.log("Discovery finished because an error: " + error.message); },
365+
() => { console.log("Discovery finished successfully");}
366+
);
367+
368+
setTimeout(
369+
() => { subscription.unsubscribe(); console.log("Discovery timeout"); },
370+
5000);
371+
</pre>
372+
<p class="note">
373+
Note that canceling a discovery (through unsubscribe) may not be successful in all cases, for instance when discovery is based on open ended broadcast requests. However, once `unsubscribe()` has been called, implementations MUST suppress further event handling ( i.e. further discoveries and errors) on the Observable. Also, a discovery error may not mean the end of the discovery process. However, in order to respect Observable semantics (error always terminates processing), implementations MUST close or suppress further event handling on the Observable.
374+
</p>
401375
</section>
402376

403377
<section> <h2>The Thing Client API</h2>
@@ -484,6 +458,62 @@
484458
</pre>
485459
</section>
486460

461+
<section> <h2 id="security">Security and Privacy</h2>
462+
<p>
463+
The trust model, attacker model, threat model and possible mitigation
464+
proposals for the Wot Scripting API are presented in the WoT Security and Privacy document.
465+
This section presents the chosen security and privacy model through normative requirements to implementations.
466+
</p>
467+
468+
<section> <h3>Chain of Trust</h3>
469+
<p>
470+
Things discoverable and accessible in a WoT network SHOULD be identified and authenticated.
471+
</p>
472+
<p>
473+
The integrity of WoT communication SHOULD be ensured by implementations.
474+
</p>
475+
</section>
476+
477+
<section> <h3>Threat Model</h3>
478+
<p>
479+
The main threats are summarized in the WoT Security and Privacy document.
480+
</p>
481+
<p>
482+
In this specification the following threats are considered of the highest priority:
483+
<ul>
484+
<li>
485+
Unauthorized gathering of user-sensitive information.
486+
</li>
487+
<li>
488+
Vulnerability of the underlying protocols.
489+
</li>
490+
<li>
491+
Protect the integrity of <a>Thing</a>s and <a>Thing Description</a>s.
492+
</li>
493+
</ul>
494+
</p>
495+
</section>
496+
497+
<section> <h3>Security Mechanisms</h3>
498+
<section> <h4>Identification, Authentication, Authorization</h4>
499+
</section>
500+
501+
<section> <h4>Transport-level security</h4>
502+
</section>
503+
504+
<section> <h4>Application-level security</h4>
505+
</section>
506+
</section>
507+
508+
<section class="informative"> <h3>Security policies</h3>
509+
<p>
510+
This section summarizes the security policies which are specified as
511+
normative requirements in the respective algorithms of this
512+
specification.
513+
</p>
514+
</section>
515+
</section>
516+
487517
<section class="appendix" id="Changes"><h2>Changes</h2>
488518
<p>
489519
The following is a list of major changes to the document. For a complete list of changes, see the [github change log](https://github.com/w3c/wot-scripting-api/commits/master). You can also view the [recently closed bugs](https://github.com/w3c/wot-scripting-api/issues?page=1&amp;state=closed).
@@ -494,16 +524,15 @@
494524
<p>
495525
The following problems are being discussed and need most attention:
496526
<ul>
497-
<li> Issue [1](https://github.com/w3c/wot-scripting-api/issues) </li>
498-
<li> Issue [2](ghttps://github.com/w3c/wot-scripting-api/issues) </li>
527+
<li> Issue [1](https://github.com/w3c/wot-scripting-api/issues/2) </li>
528+
<li> Issue [2](ghttps://github.com/w3c/wot-scripting-api/issues/17) </li>
499529
</ul>
500530
</p>
501531
</section>
502532

503533
<section> <h2>Acknowledgements</h2>
504534
<p>
505-
The editors would like to thank Dave Raggett, Matthias Kovatsch, and Michael Koster for their
506-
comments and guidance to this document.
535+
The editors would like to thank Dave Raggett, Matthias Kovatsch, and Michael Koster for their comments and guidance to this document.
507536
</p>
508537
</section>
509538

0 commit comments

Comments
 (0)