Error Handling

[danielpeintner]

The scripting API makes use of errors being available in ECMAScript (e.g., TypeError).

Moreover, also other errors such as NotSupportedError or NotFoundError are used which are not available in ECMAScript. Instead those errors are defined here.

We need to have a good set of errors that work for JavaScript/Typescript and browser environments.

For example, NotSupportedError and NotFoundError need to be defined in TypeScript definitions before they can be used in TS.

[egekorkan]

I would also imagine that some of these errors can be mapped to protocols that can be then described in the Binding Templates document. This way, when there is a Consumer and an Exposed Thing communicating, even if these new errors are not sent in the application layer, the errors that are actually sent in the application layer can be translated back into these new errors in the scripting layer.

For example, a consumer sends a readproperty request (GET) over HTTP to a non-existing property in the ExposedThing (even if it is shown to be available in the TD), the Exposed Thing responds with 404 Not Found. This is then translated into NotFoundError in the Consumer runtime. I think that even without Scripting there can be inconsistencies, i.e. maybe some implementations return 403 in this case. So we should test in a plugfest whether everyone is sending the appropriate status codes.

Even further, I think that this can be a good motivation for why one should use the Scripting API in the Exposed Thing. If you don't, then you have to know what status code to send for each protocol.

[zolkis]

There is (and should be) a difference between API object errors (SecurityError, TypeError etc) and errors reported by protocols in WoT interaction patterns. We need to track that across the whole API.

IMHO there should NOT be error translation between protocols and Scripting objects for a few reasons:

• data exposed by errors in a browser web API should be minimized against fingerprinting
• browser web API objects should not invent new error types, but as lined out in the TAG design principles, should use ECMAScript errors (exposed as WebIDL Error) or DOMException
• but there are a lot of possible error formats and codes in protocols.

Therefore, errors reported via WoT interactions should not be translated, but should be reported via mechanisms embedded into those interactions.

Then, another problem was that TypeScript lacks some of the error definitions: but in Node and TypeScript those could be defined (the restriction only applies to browser APIs).

[zolkis]

So, we can use the following:

• Simple exceptions:
  https://heycam.github.io/webidl/#idl-exceptions

TypeError, RangeError, EvalError, ReferenceError, URIError

Note that SyntaxError and Error are reserved for the ECMAScript parser.

• DOMExceptions that are not deprecated:
  https://heycam.github.io/webidl/#idl-DOMException
  https://heycam.github.io/webidl/#idl-DOMException-error-names

If you think that is enough to map (most) protocol errors, we could try that. However, I think it would be better if interactions had an embedded mechanism for error reporting.

[egekorkan]

Well generally if someone properly implements a generic HTTP server, it would return the proper HTTP codes. For already existing devices, there should thus be a way to inform in the Consumer script the error codes in a non-HTTP way. Of course, we should not try to map all the errors but the most common ones, i.e. no need to map HTTP 418 I'm a teapot status code

[egekorkan]

A table like the following can be used. Maybe we can group them according to WoT operations?

readProperty( )

WoT Error Type	Protocol Error/Status Code	Description
NotFound	404	the property is not offered by the Thing instance (request sent)

invokeaction( )

WoT Error Type	Protocol Error/Status Code	Description
NotFound	404	the action is not offered by the Thing instance (request sent)
TypeError	403	bad payload content according to DataSchema

[zolkis]

no need to map HTTP 418 I'm a teapot status code

Well, of course we need to map that! Everyone supports it! :)

Would the table above be informative or normative when included in the spec?

[mmccool]

I think we do need a catch-all case if an error code is received for which there is not a definition in the protocol binding. Should this be generic (eg NotFound for any 4xx error code) or should a special error (eg OperationError) for errors which are not defined in the protocol binding?

[zolkis]

Possible error causes currently used in Scripting:

• fetching a TD: error comes from the fetch() API
• consume(): SecurityError and TypeError for failing to validating the TD
• produce(): SecurityError (TD expansion don't throw ATM and no check is done!) - potential issue.
• discover(): SecurityError, NotSupportedError, SyntaxError (fetch), DiscoveryError (and set error.message to the code or message from the protocol binding).
• Consume.read: SecurityError, SyntaxError, error received from protocol bindings
• Consume.readMultiple: SecurityError, SyntaxError, NotSupportedError (issue!)
• Consume.readAll: SecurityError, SyntaxError, NotSupportedError, error received from protocol bindings.
• consume.write: SecurityError, SyntaxError, error received from protocol bindings
• consume.writeMultiple: SecurityError, SyntaxError, NotSupportedError, error received from protocol bindings.
• Consume.observe: SecurityError, TypeError, error received from protocol bindings.
• Consume.unobserve: SecurityError, error received from protocol bindings.
• Consume.invoke: SecurityError, error received from protocol bindings.
• Consume.subscribe: SecurityError, TypeError, error received from protocol bindings.
• Consume.unsubscribe: SecurityError, error received from protocol bindings
• ExposedThing handling write requests may return ReferenceError, NotSupportedError.
• ExposedThing handling read requests may return ReferenceError, NotSupportedError.
• ExposedThing handling action requests may return ReferenceError, NotSupportedError.
• ExposedThing emit may throw SecurityError, NotFoundError.
• ExposedThing expose() may reject with SecurityError, TypeError, error received from protocol bindings.
• ExposedThing.destroy() may reject with SecurityError and error received from protocol bindings.

Some of these need alignment and/or review.
Also, we might factor out an algorithm for reporting an error from protocol bindings.

[egekorkan]

Some feedback to the comment above:

• fetch API: Fetch is mostly used for HTTP but from what I understand, it is not limited to HTTP. There might be a need to extend it?
• NotSupportedError for all Consume.x kind of methods should be added.
• Consume.readMultiple : why there is no "error receuved from protocol bindings"?
• Consume.unsubscribe : There could be also TypeError since it is possible to supply a payload for event unsubscription
• Consume.invoke: There could also be TypeError

[zolkis]

The "fetch a TD" is not part of WoT Scripting API any more: it's "outsourced" to the Fetch API or libraries.

[zolkis]

Fixed by #218, please check.