Extended return type of invokeAction()

[danielpeintner]

I started to work on a PR to show a possible solution how the extended return type ActionInteractionOutput for invokeAction() may look like.

resolves #555

---

Preview | Diff

[danielpeintner]

I started with a function but I start thinking an attribute should be sufficient..

[zolkis]

An action is supposed to be always polled? Or could a script subscribe just for changes in status?

[danielpeintner]

I think observing state changes would be nice but I am not sure whether that is actually necessary...

[danielpeintner]

Mhh, I tend to think now that a a function for reporting the status would be more powerful and useful. What do people think? Other ideas?

[JKRhb]

Mhh, I tend to think now that a a function for reporting the status would be more powerful and useful. What do people think? Other ideas?

Hmm, if I see it correctly, we could also treat the attribute as a getter and add more logic to that if needed, right?

Or could a script subscribe just for changes in status?

If we wanted to that, what would be the best way to model that? Adding a way for registering a callback function?

[danielpeintner]

Mhh, maybe we should decide what we need/want from the status

• is it likely that requesting the status may take a while? (or put differently do we need a Promise)
• do we need a way to observe a status change (would be nice but adds complexity)

My take is that having a promise function for status() is fine while I am not 100% sure we should allow for listening status changes...

Are there opinions/proposals?

[JKRhb]

Should we coordinate in some way with the Profile TF to align the terms that are being used? Or is it no problem if they differ, since they are operating on a different level anyway?

[danielpeintner]

Good point. Once we feel comfortable with our choices we should definitely reach out. Most of the status terms are 1:1 matches. What seems different is pending.

[danielpeintner]

FYI: Profile has 4 terms

• pending --> we don't have a corresponding term!
• running -> same ✅
• completed -> we use success instead
• failed -> we use error instead

What can we do with aligning the terms? Use the ones from profile or talk to them? Any opinion?

[JKRhb]

Hmm, their terminology actually sounds quite good to me, so from my side we could also adopt what they are using.

[danielpeintner]

I am fine withe the Profile terms also. The question remains if it is fine dropping "pending" then... (same same but different 🙃)
Other opinions?

[danielpeintner]

We have some inline discussions which need some more feedback. Please chime in with your opinion!

[JKRhb]

Mhh, I tend to think now that a a function for reporting the status would be more powerful and useful. What do people think? Other ideas?

Hmm, if I see it correctly, we could also treat the attribute as a getter and add more logic to that if needed, right?

Or could a script subscribe just for changes in status?

If we wanted to that, what would be the best way to model that? Adding a way for registering a callback function?

[JKRhb]

Hmm, their terminology actually sounds quite good to me, so from my side we could also adopt what they are using.

[danielpeintner]

@JKRhb seems to be fine with using the terms used by the profile.
@zolkis you were proposing the current terms. Any opinions?

[danielpeintner]

Scripting Call 2024/12/11
Note: I try to summarize the decision which were made in the call yesterday.

• we use the terms defined by the WoT profile ("pending", "running", "completed", "failed" )
• we need a 5th parameter to indicate that an action has been cancelled
  • --> "pending", "running", "completed", "failed", "cancelled"
  • Question: shall we use cancelled or canceled (the difference seems to be British English vs American English)
• No need for error attribute (the status provides already a mean to indicate an error)
• we use EventEmitter for each event
  • Q: How to model EventEmitters in WebIDL? @zolkis may be able to help (I found this)
  • there was the alternative mentioned that we could have one event like change that reports the actual type of the change
  • what I envision is that the new interface looks somehow like this (I think that should work in TypeScript)

   interface ActionInteractionOutput extends InteractionOutput, EventEmitter {
        // cancel a pending/running action
        cancel(): Promise<void>
        // possible events
        'pending': () => void;
        'running': () => void;
        'completed': () => void;
        'failed': (error: Error) => void;
        'cancelled': () => void;
        // Note: value() function will only work after completed state has been reached
    }

Please comment!
If there are no further comments/changes, I can try to implement it in this PR.

[zolkis]

Nowadays the use of Promises is encouraged instead of events wherever possible (which tend to be misused). Promise are also easier to use from client code. I liked more the original design with status query returning a Promise. The latest status terms look good.

[zolkis]

Cancelling operations should be done using AbortSignal, but in our case a dedicated function is fine, since it's scope is strictly the referred action.

[danielpeintner]

@zolkis Thanks for your feedback!

Nowadays the use of Promises is encouraged instead of events wherever possible (which tend to be misused). Promise are also easier to use from client code. I liked more the original design with status query returning a Promise.

I may be wrong in my thinking, but I think from a developer point of use, events seem simpler.
I can do something like the following

action.on('completed', () => console.log("Action completed, inform user"));
action.on('failed', (err) => console.log("Error happened: " + err));

Note: The only thing I am not sure about is whether we can miss events. Why am I saying that.

let action = await thing.invokeAction("doFoo"));
// register handlers (could it be that action is done before?)
action.on('completed', ...);

I think it might be possible that the emit() call comes before Í registered the handlers?

Anyhow, in the case of a status() promise I need to pull regularly, don't I?

do {
  let status = await action.status();
  if (status === "failed") {
     console.log("Action failed"));
  } else if (status === "completed" ) {
     console.log("Action completed"));
  } else {
     console.log("Action not yet done..."));
  }
} while(...);

I don't think there is a easy way to register for an event?
Maybe I am just not seeing the solution 🙈

@relu91 @JKRhb any opinion?

[zolkis]

We won't miss events, JS is single threaded, the event loop will check for events and dispatch.

In my latest experience, devs preferred Promises to events, no setup is needed, and most interactions can be modeled with one-off transactions.

What are the main dev use cases with this API?

• canceling action is one - needs a function
• display completion %: in this use case the client wants to control the loop and update frequency. That is easier than reacting to (and skipping some of the) events, and the loop is not spared, either. Events also need setting up. Impl already set up everything when the action started, the spec should just expose that in the control object returned by invoking the action. So I think polling the status for % is more efficient (doesn't even need Promise, just the last know status as an attribute). See also https://www.w3.org/TR/design-principles/#synchronous
• know when the action has completed (with success or error): since it's a one-off, a Promise covers it.
  But we can experiment with implementing both, and see how they fulfill the dev use cases.

[TallTed]

• This **MAY** not offer is likely to be confused with **MAY NOT** offer, despite formatting, casing, etc.
• Further, I'm not sure what sensible is contributing here.
• I'm also left wondering whether there should be some indication of what other interactions (sensible or not) might be offered (if the action does offer more than those in {{InteractionOutput}})?

Perhaps this rephrasing is acceptable, for the first two points above? Something additional might be needed for the last.

Suggested change

	Note: a synchronous action MAY not offer any <emph>additional</emph> sensible interaction beyond the ones from {{InteractionOutput}}.
	Note: A synchronous action MAY offer only the interactions found in {{InteractionOutput}} and no others.

[JKRhb]

I've tried to cover the third aspect that you've mentioned by rephrasing the sentence as follows – hope that it is a bit clearer than it was before:

Suggested change

	Note: a synchronous action MAY not offer any <emph>additional</emph> sensible interaction beyond the ones from {{InteractionOutput}}.
	Note: The output of a synchronous action MAY be limited to the functionality of a regular {{InteractionOutput}} object, e.g., invoking the `cancel()` method might not have an effect.

[TallTed]

Suggested change

	Reports the status of an <a>Action</a> (one of <code>running</code>, <code>success</code> or <code>error</code>) or rejects on error. The method MUST run the following steps:
	Reports the status of an <a>Action</a> (one of <code>running</code>, <code>success</code>, or <code>error</code>), or rejects on error. The method MUST run the following steps: