Specify result of writeProperty() method

[danielpeintner]

The specification does not clearly define the result of a writeProperty() method.

Does

return the result

mean returning the the set value in case of success or the HTTP status code of a PUT for example?

Note: the set value might be different to the one given in writeProperty() due to write property handler et cetera

[zolkis]

Well, none of the methods are clearly defined yet. However, the next sentence for writeProperty() is
Returns a Promise that resolves on success or rejects with an Error.
That implies the promise is either resolved (no value specified), or rejects with an error. I guess we can remove the "return the result" part.

[danielpeintner]

@zolkis your comment is meant to align the WebIDL definition for writeProperty()

Promise<void> writeProperty(DOMString name, any value);

with the actual description in prose (which is good) by removing the return value.

I think resolving this inconsistency of writeProperty() should be done differnetly by defining a return value.
Let's use for example HTTP PUT which returns in case of success various response codes (200, 204 etc). We would loose this information given that the promise can just return with no content.

Do you see what I mean?

[danielpeintner]

I have been thinking that many protocol bindings might not have similar HTTP/CoAP response codes (such as MQTT).

Maybe its safer to stick to no result as you proposed and align WebIDL and prose.

Sorry for going back and forth on this issue.

[zolkis]

Well, I think we need to align this with Protocol Bindings and Security TF. I am not sure whether in principle should we expose underlying protocol details in this case, but technically it would be easy resolving with a value or an object that exposes details even on a successful WoT operation (if available).

In the particular case of property update, we might not need that, but in general we should have guidelines for it.

[zolkis]

This is still valid.

[zolkis]

As discussed in https://www.w3.org/2018/09/17-wot-minutes.html,
currently the WebIDL definition of write() specifies void data returned in the Promise, but implementations MAY choose to include error codes from underlying protocols, if the security considerations for the given application allow that. Clients can check on the existence of the provided data and act accordingly.

So the WebIDL should be changed to return Promise<any> (permissive version) or Promise<long> (hardened version) and text that explains this should return either no data, or an error code if allowed.

[zolkis]

Fixed in #174