Callbacks need to take Interaction name

[mkovatsc]

For the feature to set a single handler for all Interactions of a time, the Interaction name has to be passed at well.

Should be reflected in the callback listing:

callback PropertyReadHandler = Promise<any> (string propertyName);
callback PropertyWriteHandler = Promise<void> (any value, string propertyName);
callback ActionHandler = Promise<any> (any parameters, string actionName);

The "The ActionHandler callback" section text also needs update. The other two sections look good.

[zolkis]

When a name is provided, the handler is associated with that name.

When no name is provided, the handler is associated with all names of that interaction type (i.e. it is a generic handler).

This simplifies coding a great deal. You can set a generic handler, and then only override the ones you want.

[zolkis]

Actually we have discussed on a past scripting call whether name should be passed to callbacks, and we agreed it's not needed. The invokeAction() is passed the name, not the callback.

[mkovatsc]

My point is that at the moment a single handler cannot know for which Interaction it was called. The current status is:

callback ActionHandler = Promise<any> (any parameters);
callback PropertyReadHandler = Promise<any> ();
callback PropertyWriteHandler = Promise<void> (any value);

[zolkis]

To summarize:

• when a specific handler is provided, the callbacks don't need the interaction name
• when a generic handler is provided, the original idea was that it should be generic, i.e. not bound to interaction name, or it's the common part that is done for all interactions for that type.
• however, this issue is asking for supporting generic handlers which internally dispatch handling to sub-handlers based on the interaction names. In that case, we do need to add interaction names to handler callbacks.

As a result:

1. When the set...Handler() are called without the interaction names (i.e. generic handlers for that interaction type), the callbacks will always have to receive the interaction name from implementations.
2. When the set...Handler() are called with the interaction names bound to the provided function, the callbacks can be provided as functions that do not receive the interaction name.

Now the question is which parameter should the interaction name be: first or last (in order to harmonize with the set...Handler() functions. @mkovatsc proposal was to put them as optional second argument to callbacks.

However, that will create 4 possible combination of rules to handle, which in my opinion can be simplified. Even in case 2., the implementations will know (and provide) the interaction name that was requested by the client. Therefore it is safe to assume the callbacks will always get the interaction names, whether using them or not. Hence, in order to simplify things (and cut combinations) we could indeed say that all provided callback functions do take interaction names (whether they use them or not), i.e. the interface the app gets parameters is:

callback ActionHandler = Promise<any> (DOMString name, any parameters);
callback PropertyReadHandler = Promise<any> (DOMString name);
callback PropertyWriteHandler = Promise<void> (DOMString name, any value);

instead of

callback ActionHandler = Promise<any> (any parameters, optional DOMString name);
callback PropertyReadHandler = Promise<any> (DOMString name);
callback PropertyWriteHandler = Promise<void> (any value, DOMString name);

I think the first one is more intuitive still, even though in the set...Handler() functions we have the names as optional last parameters.

[zolkis]

To further clarify, the use cases are the following:

1. specific handler: add...Handler() specifies name and a callback function. The callback may receive the name, but does not need to use it.
2. parametrized generic handler: add...Handler() does not specify name, but the callback receives it, in order to use it as a parameter to the (same) function for reading/writing a property.
3. multiplexed generic handler: add...Handler() does not specify name, but the callback receives it, in order to dispatch processing to another function that may be different for each property.

While one could argue that 2. is in fact not needed, since it could be part of the implementation by default, we still need to support 1. and 3.

[mkovatsc]

I cannot follow the reasoning here:

create 4 possible combination of rules to handle

What 4 combinations?

2. parametrized generic handler

3. multiplexed generic handler

How are these different? A handler implementation may call as many functions internally as it wishes. That does not make it any different.

Maybe "2." for you is returning the same result for all Properties or all Actions, which to me is a non-use case because why expose multiple Properties in the first place.

Case "2." is exactly the same as 3., just that the handler implementation chose to not multiplex on the name given.

[mkovatsc]

For the callback signature, I prefer the order of first parameters /value and second name.

The main reason is to make it simple for the simple use cases: Actions correspond to functions. In simple use cases they will be attached to a specific Action, so that the developer does not need to take care of multiplexing and state management themselves. Their function signature for implementation will focus on what they want: no arguments or a single argument for the parameters object/any. No argument to get the name that is not needed and irrelevant to the function.

The runtime however will always pass two arguments when calling the handler, whether taken or not. This also means passing (undefined, name) when no Action parameters are received!

This enables the more advanced case of generic handlers, where the developer wants to do multiplexing and state handling themselves. Only here the name becomes relevant and the implementer will be aware and willing to take it.

This also fits the concept and argument order for setting these two types of handlers.

[zolkis]

It is much simpler to always pass name and then the rest of parameters. Implementations can always invoke the provided callback functions with name, so they should do it regardless whether the implementation of the callback functions uses them or not. It is a well defined interface then which does not change depending on how the callback was registered.

[zolkis]

"parametrized" does NOT mean you return the same value for all properties. It is not a logical implication.
It means you use the property name as a parameter for fetching its value from the internal slots associated with the properties.

Multiplexing is a special use case of parametrization, when the app implements dispatching of reading the property. I just meant to provide examples for these use cases, not to have a different API (with or without using name) for each.

[mkovatsc]

Multiplexing is a special use case of parametrization, when the app implements dispatching of reading the property

How is this different from

fetching its value from the internal slots associated with the properties

Whether the fetching is done with a function call or accessing some internal structure is irrelevant.

Implementations can always invoke the provided callback functions with name

If here "implementations" means runtime implementations (it should because only the runtime calls the callback functions), then yes they do always invoke with the name, also in my proposal. I just turn the order around.

[zolkis]

Sigh. With multiplexing you have something like a switch statement with likely different branch implementations, with generic parametrization you have the same impl with indirection from named parameter e.g. iterator. The API is the same, but we can give examples for both.

Invoking function(undefined, name) (for instance an action without arguments) is an anti-pattern.
Since name can always be provided, the signature should be function(name);

"Implementation" in the context of a W3C API spec always refers to the implementation of the API, i.e. the user agent or runtime. The "application", "app implementation" and "script" refer to code that uses the API. "Callback implementation" refers to the "guest code" provided by the app, i.e. it is part of the "app implementation" or "script".

[mkovatsc]

Can someone please help and explain to me why @zolkis is making to different cases out of the "non-specific callback" case, where the callback is set without name and handles multiple Interactions and needs the Interaction name to perform for the Interaction actually requested? (That is the counter-part to the "specific callback" case, where the callback is set for a specific Interaction giving the name. Ergo two cases in total.)

[mkovatsc]

While passing 'undefined' is definitely not a good idea, passing null as the first argument when there is no error made to a NodeJS callback convention. Do you have a good reference, as I would be happy to get good sources on well-founded anti patterns?

[mkovatsc]

I would like to allow this for Action callbacks (please ignore the concrete application, just illustration), where the callbacks' signatures match the functionality:

thing.setActionHandler( () => { /* reset all Property values or whatever */ }, "reset");
thing.setActionHandler( (uri) => { /* fetch new feature from given URI parameter */ }, "update");

With "Zoltan order", it would be:

thing.setActionHandler( () => { /* reset all Property values or whatever */ }, "reset");
thing.setActionHandler( (nameIdontNeed, uri) => { /* fetch new feature from given URI parameter */ }, "update");

With my order, generic handlers would look like:

thing.setActionHandler( (params, name) => {
  switch (name) { 
  case "reset":
    /* knows that params argument is not needed and will not be used */
    /* reset all Property values or whatever */
    break;
  case "update":
    /* needs and uses params argument */
    /* fetch new feature from given URI parameter */
    break;
  }
});

In this generic case, when a request for Action "reset" comes in, the runtime implementation will call the generic handler above with something like (payload, actionName), where payload is probably still undefined or set to null, because there was no payload in the request or it was filtered based on the inputSchema, and actionName is "reset" based on the request-URI in the request.

I don't see any anti-pattern in this.

@danielpeintner , @knimura What do you think?

[zolkis]

With "Zoltan order", it would be:

It's not my order, but the one generally followed in JS and by W3C standards.

Actually it will be the following:

thing.setActionHandler( (name) => { 
    /* reset all Property values or whatever */ }, 
    "reset");
thing.setActionHandler( (name, uri) => { 
   /* fetch new feature from given URI */ }, 
   "update");

Which is fine. It is clear for the reader and developer that callbacks receive the interaction name and optional parameters. And your generic handler will look the same:

thing.setActionHandler( (name, params) => {
  // ...
});

In turn what is not fine is expecting (by spec) the runtime to invoke your callback with so-called "falsy values" like (undefined, "reset") or even (null, "reset") for e.g. the "reset" action that does not have an argument (when you reverse the parameter order in the callback so that optional arguments come first, and name comes second).

Normally when two optional parameters are desired in a function, it is better to use an optional dictionary in which the parameters become properties and where one or both are optional.