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

clarify semantics of actions #213

Closed
mlagally opened this issue Aug 31, 2018 · 10 comments
Closed

clarify semantics of actions #213

mlagally opened this issue Aug 31, 2018 · 10 comments
Labels
ActionAffordance Topic realtated to the Actions Affordance

Comments

@mlagally
Copy link
Contributor

The spec should clarify the semantics of synchronous and asynchronous actions:

How can an asynchronous be monitored? How are execution failures (exceptions) communicated?

@mlagally mlagally changed the title clarify semantics of asynchronous actions clarify semantics of actions Aug 31, 2018
@sebastiankb sebastiankb added the Needs discussion more discussion is needed before getting to a solution label Oct 19, 2018
@sebastiankb
Copy link
Contributor

we need some concrete examples for the error handling.

@draggett
Copy link
Member

One example is where there is an "internal error" when executing the action. In the Arena Web Hub, this is signalled with a 5xx status code when using either HTTP or WebSockets for the protocol, and reported to clients via the Scripting API by rejecting the promise for the action along with a suitable error message. Another example of an error is a timeout when the promise is left hanging for an excess amount of time. In Arena, this too is signalled by rejecting the promise.

I would advise against baking complex semantics into the TD spec as it is better handled at the application layer. The core abstract API should remain as simple as possible.

I know that there are use cases where it is appropriate to have actions that can be cancelled, and use cases that require progress indicators. However, I consider these both to be application level requirements that can be implemented on top of the core notion of asynchronous actions with inputs and outputs. For instance, if an action is cancellable it could output a reference to an ongoing process. Another action can then be used to cancel the process by passing the process ID. Progress for some extended process could be signalled via a sequence of events.

@mlagally can you explain why you are asking for synchronous actions, given the web of things generally speaking involves action at a distance, making the abstract model for actions to be asynchronous/.

@mlagally
Copy link
Contributor Author

@draggett Sorry for my late response.

WoT is defining a generic interface description language (like CORBA did many years ago) that provides an abstraction from devices via properties, actions and events.
As such it needs to be flexible enough to handle operations on devices that can return immediately with a result (e.g. 200 OK in the simplest HTTP case) and operations that just return an "accepted" or "dispatched" status code.
In both cases the action returns immediately, however only in the first (synchronous) case the result is available.
In the asynchronous case, either the caller passes in a listener (callback), which gets called when the action ends, or provides a "handle" (e.g. a URL), that can be used for polling the execution status and getting the result.

See for example the "action" on the Oracle IoT Cloud Service: https://docs.oracle.com/en/cloud/paas/iot-cloud/iotrq/op-iot-api-v2-apps-app-id-devices-device-id-devicemodels-devicemodel-id-actions-action-name-post.html, which returns a status code and a URL for this purpose.

"url":"https://iotserver/iot/api/version/resource/path",
"status":"Request statusOne of [RECEIVED, DISPATCHED, COMPLETED, EXPIRED, FAILED, UNKNOWN]."

The current specification can describe both synchronous and asynchronous ways of using the API, and probably it does not even have to be more specific.

However I think we should extend the current action definition in the TD spec with an additional "response code" and ideally a "response message", which corresponds to the status code in HTTP or a return code of a function call.
I'm hesitant to propose a simple "put the protocol status code into the response code", since it carries protocol specifics (HTTP / 200 = OK) across the abstract API definition, and won't work right for actions with different protocol bindings, so I think we need a common set of response codes (e.g. failed_permanent, failed_temporarily, success) and put the protocol specific details into the response message.

@benfrancis
Copy link
Member

Mozilla has the same use case of action requests which create a new resource that can be polled for action status or cancelled. e.g.

Request:

POST https://mythingserver.com/things/lamp/actions/fade
Accept: application/json

{
  "fade": {
    "input": {
      "level": 50,
      "duration": 2000
    }
  }
}

Response:

201 Created

{
  "fade": {
    "input": {
      "level": 50,
      "duration": 2000
    },
    "href": "/things/lamp/actions/fade/123e4567-e89b-12d3-a456-426655"
    "status": "pending"
  }
}

I've not been able to figure out how to describe this with the current Thing Description specification, see #302

@draggett
Copy link
Member

@mlagally wrote:

WoT is defining a generic interface description language (like CORBA did many years ago) that provides an abstraction from devices via properties, actions and events. As such it needs to be flexible enough to handle operations on devices that can return immediately with a result (e.g. 200 OK in the simplest HTTP case) and operations that just return an "accepted" or "dispatched" status code.

and

However I think we should extend the current action definition in the TD spec with an additional "response code" and ideally a "response message", which corresponds to the status code in HTTP or a return code of a function call.

Do we really need to standardise that? I suspect not as different contexts will involve different categories of responses. You are free to declare an action that returns an object with a numeric code together with a enum, string or JSOB object if that's what your application needs. Some errors will be handled through the platform API, e.g. in Arena, actions return a Promise which is rejected when the server reports an internal error, there is a time out, or when the server rejects the security token passed with the request.

@draggett
Copy link
Member

@benfrancis wrote

Mozilla has the same use case of action requests which create a new resource that can be polled for action status or cancelled

You can model that as an action response, but then need to model how you deal with it. One idea is to model the fade process as a thing it its own right. Another is to return an ID that you can listen for using a status event that contains the ID. A further idea is to declare another action for acting on long lasting processes. I recommend that we keep the core interaction model simple and allow applications to layer more complex interaction patterns on top, perhaps using libraries to simplify this. Otherwise we risk over complicating the Web of Things as more and more people come to us with their own interaction patterns demanding that the TD spec is updated to match.

@mlagally
Copy link
Contributor Author

@draggett wrote:

Do we really need to standardise that? I suspect not as different contexts will involve different categories of responses. You are free to declare an action that returns an object with a numeric code together with a enum, string or JSOB object if that's what your application needs. Some errors will be handled through the platform API, e.g. in Arena, actions return a Promise which is rejected when the server reports an internal error, there is a time out, or when the server rejects the security token passed with the request.

I guess we can get away by adding a response code and a response message to the output data schema, however this is completely up to the implementer.

@sebastiankb
Copy link
Contributor

same situation as discussed here #303

This topic can be covered in a successor version of the TD.

@sebastiankb sebastiankb added Defer to next TD spec version This topic is not covered in this charter, maybe included for the next TD version. and removed Needs discussion more discussion is needed before getting to a solution labels Mar 1, 2019
@sebastiankb sebastiankb added the ActionAffordance Topic realtated to the Actions Affordance label Jan 23, 2020
@sebastiankb
Copy link
Contributor

we will discuss this in today's TD call. Also see #890

@sebastiankb sebastiankb removed the Defer to next TD spec version This topic is not covered in this charter, maybe included for the next TD version. label Dec 2, 2020
@sebastiankb
Copy link
Contributor

close this issue since TD now has synchronous in the action definition which can be used to signalize synchronous and asynchronous based actions

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
ActionAffordance Topic realtated to the Actions Affordance
Projects
None yet
Development

No branches or pull requests

4 participants