Clarify multiple requests for subscription/observation

[relu91]

With the latest changes, we introduced a new interface for handling subscriptions/observe changing on a ConsumerThing. However, for the implementer is not clear how the runtime should act when an application is issuing multiple subscriptions/obersevation for the same affordance.

In principle thanks to the new control objection Subscription it's possible to handle multiple functions registered as listeners for an affordance. However, this possibility is never mentioned (or at least I couldn't find it) in the document leaving open to interpretation how the process should look like. Furthermore, the document explicitly says that when the stop method is called on a Subscription this request should be immediately be sent to the protocol layer. As I read this, a vague hint to the fact that in practice you can have just one single Subscription object, because as soon as you stop it you have to cancel the subscription at the protocol level (e.g., closing the connection, unsubscribe request etc. ).

Actions points:

• I remember that we discussed the possibility to have multiple Subscriptions active per affordance, but we discarded it because it would create a more complex API. Should we reconsider this?
• Discuss if this is an implementation detail and should be explicitly left open
• Either way, the document needs few lines discussing the alternatives and, eventually, why we choose one or another.

[zolkis]

We need to add steps to algorithms to clarify this.
Option 1

• subscribing with the same function will do nothing;
• subscribing with a different function will create a new subscription

Option 2

• subscribing with the same function will do nothing
• subscribing with a different function just changes the subscription callback.

I think Option 1 is manageable and cleaner. We need to update the unsubscribe steps as well, to map the API behavior to protocol. Some bindings might allow multiple subscriptions with different client side id, some will just allow one kind of subscription since the notifications are the same. Even in the latter case the API might want to support multiple callback functions (one per client-side subscription).

[danielpeintner]

Question: Is this really a question we as the Scripting API task-force should answer or should that be defined in the TD spec?

[relu91]

Question: Is this really a question we as the Scripting API task-force should answer or should that be defined in the TD spec?

I think is up to us, since is something closely related to how an application would use the subscription/observation APIs.

We need to add steps to algorithms to clarify this. Option 1

• subscribing with the same function will do nothing;
• subscribing with a different function will create a new subscription

Option 2

• subscribing with the same function will do nothing
• subscribing with a different function just changes the subscription callback.

I think Option 1 is manageable and cleaner. We need to update the unsubscribe steps as well, to map the API behavior to protocol. Some bindings might allow multiple subscriptions with different client side id, some will just allow one kind of subscription since the notifications are the same. Even in the latter case the API might want to support multiple callback functions (one per client-side subscription).

What about Option 3 instead of Option 2?:

• subscribing with the same function will do nothing;
• subscribing with another function will throw an exception

I think it is safer than silently changing subscription callbacks 🤔

And about Option 1, we should decide if it creates a new network subscription or just a runtime subscription (i.e., re-use the network subscription but multiplexing events to different functions). Notice that in the case of runtime subscription we should consider the list of active subscriptions in the stop method and close the network subscription only after all runtime subscriptions are stopped.

[danielpeintner]

Scripting API Call 2021-11-15
Should write down the "1 subscription" warning into our document.

@relu91 recalls that re-working the API was based on the assumption to support to multiple subscriptions (we fail to do so).

Other possible Solutions

• unsubscribe first to be able to re-subscribe
• re-consume the TD again (-> different SW object)

[zolkis]

Subscriptions are per ConsumedThing object (for each interaction that can be subscribed to). New subscription should either return error, or replace an old subscription.

[danielpeintner]

Scripting API Call 2021-11-25

• add clarification note to document
• 1 subscription per interaction name
• subscribing an already subscribed interaction should throw error

@relu91 works on a PR

@relu91 suggests to gather developer feedback about "multiple subscription per affordance"

[danielpeintner]

resolved by #356

[relu91]

@danielpeintner I'm closing this, feel free to re-open if anything.