Extend the WoT API with provisioning and discovery introduction/exploration

[zolkis]

Based on the comment in https://github.com/w3c/wot-scripting-api/issues/545#issuecomment-2220314305, this issue discusses a proposal to handle multi-solution support, provisioning and discovery mechanisms.

The algorithm drafted here looks more like an internal implementation detail. It is hard to standardize it in order to expose these details to scripts. Or, in other words, it's hard to distillate simple APIs that cover the programmatic side of discovery, without going too much into protocol details -- since then a script could just use the network/REST API.

I am thinking if we could make examples on how to fetch TD directories using the Discovery spec / network API, as depicted here. Those will help figuring out if we can distillate a good programmatic API on top of that.

Currently the WoT Discovery introduction mechanisms are definitely encapsulated in the Scripting implementation.

Moreover, the Authentication layer and the Exploration layer, too, are encapsulated. The Scripting API presents another (programmatic) exploration API that connects to the middleman (the Scripting implementation), provisioned as an endpoint in the given WoT solution, and maybe represented (in the future) as an internal slot to the implementation (to the WoT API object). True, we are missing a standard provisioning API, but more about this later.

Since currently we are not co-hosting multiple solutions in a single WoT runtime (Scripting implementation, i.e. WoT API object), this works quite well, separating the complexities of the underlying WoT Discovery spec.

We can specify a separate API for implementing the details of the WoT Discovery spec, and that should be in a different conformance class, with its own Security section, same level as WoT Provisioning. In my view, these belong to the next level down in the stack. If we were to standardize these (Provisioning, Discovery introduction + exploration), I would support it, but eventually in a separate deliverable (spec, impl + tests) in the WG.

If we were to co-host and support multiple WoT/IoT solutions with a single runtime and WoT object and API, then it needs to be transparent from identification/authentication point of view as well, therefore pulling the need for more low level configuration functions -- therefore going one level down as mentioned above.

Another way to do that is to expose multiple WoT objects for multiple solutions, i.e. we need an additional root-level API to create (async) a WoT API object, with the given provisioning/initialization routines, including discovery introduction and exploration, resulting in a configured discovery "middleman" internal slot. We could use the WoT object which exposes the current API functionality the same way as now, making this proposal backwards compatible, but also (re)configurable wrt provisioning, discovery etc.

I can draft an experimental API for this in a separate issue.

[zolkis]

The current API (collated the partial definitions):

typedef object ThingDescription;
typedef object ExposedThingInit;

[SecureContext, Exposed=(Window,Worker)]
namespace WOT {
  Promise<ConsumedThing> consume(ThingDescription td);
  Promise<ExposedThing> produce(ExposedThingInit init);
  Promise<ThingDiscoveryProcess> discover(optional ThingFilter filter = {});
  Promise<ThingDiscoveryProcess> exploreDirectory(USVString url,
      optional ThingFilter filter = {});
  Promise<ThingDescription> requestThingDescription(USVString url);
};

[SecureContext, Exposed=(Window,Worker)]
interface ThingDiscoveryProcess {
  constructor(optional ThingFilter filter = {});
  readonly attribute boolean done;
  readonly attribute Error? error;
  undefined stop();
  async iterable<ThingDescription>;
};

dictionary ThingFilter {
  object? fragment;
};

I propose another top level API to obtain the WoT object, given configuration.

[SecureContext, Exposed=(Window,Worker)]
namespace WOT {  // separate conformance class
    Promise<WoT> createWotEndpoint(optional WotEndpointInit init);
    Promise<void> decommissionWotEndpoint(WoT wot);

    Promise<void> provision(WoT wot, WotProvisioningInit init);  // (re)provision
    Promise<void> configure(WoT wot, WotConfigurationInit init);  // (re)configure
    Promise<void> initDiscovery(WoT wot, WoTDiscoveryInit init);  // (re)init discovery
    Promise<void> addDiscoveryDirectory(WoT wot, USVString url);
    // add other methods operating on WoT
}

[SecureContext, Exposed=(Window,Worker)]
interface WoT {
  Promise<ConsumedThing> consume(ThingDescription td);
  Promise<ExposedThing> produce(ExposedThingInit init);
  Promise<ThingDiscoveryProcess> discover(optional ThingFilter filter = {});
  Promise<ThingDescription> requestThingDescription(USVString url);
  // internal slots will include the entities configured in WOT, 
  // e.g. provisioning object, discovery object, configuration object etc
}

We could discuss whether the WoT.discover() method should just provide Thing TDs, based on directories and other discovery methods configured for the WoT object in the WOT namespace.

Alternative names for WoT could be WotContext, WotEndpoint etc, basically the same as the current WOT namespace, just made an interface object. It could also be constructible (with defaults) and (re)initialized later. Like this.

[SecureContext, Exposed=(Window,Worker)]
namespace WOT {  // separate conformance class
    Promise<void> provision(WoT wot, WotProvisioningInit init);  // (re)provision
    Promise<void> configure(WoT wot, WotConfigurationInit init);  // (re)configure
    Promise<void> initDiscovery(WoT wot, WoTDiscoveryInit init);  // (re)init discovery
    Promise<void> addDiscoveryDirectory(WoT wot, USVString url);
    // add other methods operating on WoT objects
}

[SecureContext, Exposed=(Window,Worker)]
interface WoT {
  constructor();
  Promise<ConsumedThing> consume(ThingDescription td);
  Promise<ExposedThing> produce(ExposedThingInit init);
  Promise<ThingDiscoveryProcess> discover(optional ThingFilter filter = {});
  Promise<ThingDescription> requestThingDescription(USVString url);
  // internal slots will include the entities configured in WOT, 
  // e.g. provisioning object, discovery object, configuration object etc
}

It would be possible to experiment with moving directory exploration (back) to WoT, but this is a good starting point.

[zolkis]

The discussion in #535 is relevant to this issue.

[relu91]

I think that it is great to start talking about a broader scope of the scripting API. One question: is this discussion also framed inside https://github.com/w3c/wot-scripting-api/issues/298 ? I know that this proposal is concerning only Discovery but I see how that could be extended also to other aspects like security schemas, protocol bindings, and security data.

[zolkis]

@relu91 I think script management is a different topic. This one only addresses configuration/provisioning (including that of discovery) and kind of assumes that it's done for a(ny) single given script run in the environment.

Managing multiple scripts is a different API from this point of view, which in background might (or might not) spawn a new instance of the runtime, depending on policy of co-hosting or isolation. That part will also need its own provisioning, i.e. will need to include also data that may be relevant to script management, as an incremental feature (additional provisioning and config items related to script management).