Re: [discovery-api] Draft spec updates

Hi Greg,

On Sep 26, 2012, at 6:21 PM, Greg Billock <gbillock@google.com> wrote:

> A couple of questions.
> 
> 1.
> How are onserviceavailable/onserviceunavailable on NetworkServices
> different from onserviceonline/onserviceoffline on the NetworkService
> objects themselves?

servicesAvailable returns the total number of services found in the network that match the service type requested. If a user provides e.g. 2 from a total of 4 matching services found in the network to the web page then servicesAvailable will be 4 (NetworkServices.length will be 2). If a new service is detected in the network at any time then servicesAvailable will become 5. It's a fairly generic indicator to whether re-requesting getNetworkServices with the same service types might be worthwhile or not for the web page to perform.

The online attribute relates to individual NetworkService objects. When it is false it means that the NetworkService's service advertisement is stale or that service can no longer be observed by the user agent on the local network. When true it means a fresh service advertisement exists for the given service and therefore that the service should be capable of responding to service messages sent to it.

I'm not married to the naming here :)

> It'd be nice to get rid of "NetworkServices" and
> just return an array of "NetworkService".

The success callback from getNetworkServices does, in some basic respects, resemble an array object.

You can for example do services[index], that returns the indexth element in that object. You can also do services.length that allows you e.g. iterate over the services returned in a for loop.

What we drop is the additional ECMA array methods which i don't think really make sense in the context of an immutable object.

What we add is management events such as servicesAvailable.

> Also, shouldn't the interaction with the service URLs themselves
> provide these signals? That is, if I have the url, shouldn't this
> online/offline available/unavailable status be reachable by using
> messaging APIs directly with the url? If there out-of-band channels by
> which the UA can receive availability information, wouldn't it be
> better to have the UA inject that information into the messaging API
> directly?

> For example, if the client does new
> EventSource(service.url), then availability information would be
> reflected in the readyState of EventSource, and notified through its
> eventing mechanism.

It's clear the only way to actually check that a URL is accessible or not is by trying to access it directly. XHR, Web Sockets and Server-sent events all have readyState + eventing that are capable of reporting if the target URL is inaccessible at the point it is actually invoked.

It just so happens that we also get cues about a service's availability from the network service discovery protocols themselves so we also expose these in this API. The general premise for this is that if, as a web developer, I've been informed that a service is offline (because its advertisement expired, the service gracefully left the network or the user dropped or changed networks) then I don't have to block my in-page UI and rely on waiting for a URL request to timeout via the XHR, Web Sockets or Server-sent events APIs to know that fact (...though you could if you really wanted to by just ignoring the discovery protocol availability cues and querying the URL regardless of the cues provided).

> 
> 2.
> What purpose does the id of the returned service have? I see
> NetworkServices can get a service by ID, but wouldn't I have to
> iterate through the array and read the IDs anyway? Is this useful when
> using the url? I don't see the utility of the getServiceById API.

The use case is where I've previously obtained a set of NetworkService objects via getNetworkServices and I've now re-requested a new set of services via the same API. The second set of NetworkService objects is not necessarily ordered in the same way as the first set and may or may not contain some or all of the same set of objects from the first request.

getServiceById was a way to quickly lookup if a service obtained in the first lookup is still present in the second lookup.

Admittedly though, getServiceById is not one of the 80% use cases and could be achieved by iterating through the services returned in the second success callback and matching up the services from there. IIRC, we were trying to maintain feature parity here with other similar HTML APIs e.g. [Audio|Video]TrackList:

http://www.whatwg.org/specs/web-apps/current-work/multipage/the-video-element.html#audiotracklist-and-videotracklist-objects

> 
> In a similar vein, what purpose does the returned |config| have? Is
> this just extra data the service is telling the client, which may be
> helpful in navigating the control protocol?

Yes. Mostly it's meta information about the device associated with the current NetworkService. That's typically things like friendlyName, make, model, unique device identifier, etc (Device descriptor document <device> elements) in UPnP and unique device identifier (DNS TXT records) in Zeroconf.

None of that information is completely essential for API operation but does allow a web page to provide a richer in-page UI. There are obviously some concerns around providing that kind of information but having that information behind a user opt-in seems reasonable.

> 
> I can see why it is nice for the client to have a user-friendly name
> -- it can be used to indicate to the user the device they are
> interacting with.
> 
> 3.
> The user verification steps are good as a semantic point, I think, but
> the spec seems too insistent that the user be prompted for every
> discovery interaction. If they have a TV they are controlling, why not
> enable that to be used by default?

That's a good point. The spec doesn't yet have wording to this effect. I expect we could add it at Step 13 of the getNetworkServices algorithm, changing it to something like "Optionally, e.g. based on a previously-established user preference, for security reasons, or due to platform limitations, the user agent may "... return a pre-defined successCallback or throw an errorCallback. The wording here would need some work ;)

> I think the thinking from comparing 
> web intents and registerProtocolHandler will prevail -- the set of
> APIs that allow users to select handlers, services, etc. will be
> presented to the user in a uniform way by UAs, and so the same
> defaulting policies should apply to all.

Based on our current thinking this API should allow a user to select multiple devices in a single getNetworkServices request (resulting in multiple NetworkService objects returned in the NetworkServices callback). I think that's different from the thinking for rPH and WebIntents (interaction is with one item at a time due to the provider page loading overhead required), though otherwise the interfaces could likely be almost identical.

> 
> ---
> 
> It looks to me like the only additional ingredient here above what
> could be provided by a web intents-based "discover" intent is to add
> the returned urls to the cross-site accept list. That's obviously an
> important ingredient, but I don't think that's a big obstacle for
> using web intents for url discovery. We've done a similar
> implementation in Chromium for passing Filesystem objects through
> intents -- they need to be special-cased to provide the right sandbox
> permissions. Special-casing a hypothetical "discover" action type
> would be about the same code path.
> 
> It looks to me like this method of connecting clients to service urls
> differs in character to the work Claes &co are doing with the UPnP
> web-intents-based service discovery addendum [1] in that this supposes
> the client will understand how to use the returned url "natively" (or
> perhaps when given a config string for guidance), whereas the addendum
> allows for higher-level controls, like "view", which pass control
> directly to the equipment. But couldn't we augment the addendum with
> something like:
> 
> startActivity({"action": "discover", "type": typelist},
> function(services) { attachToService(services[0]); });
> 
> to provide for direct control url discovery? This looks like a pretty
> direct translation, and would get presented to the user in essentially
> the same manner. This mechanism has the advantage of being able to
> interoperate with non-local services as well -- discovering an
> endpoint url that controls a remote videoconference camera, for
> instance, or a tele-operated piece of equipment.

I think both mechanisms are worth discussing some more since there are some subtle differences (e.g. the multiple services selection allowed via this API's UI component as I briefly mentioned above). I should note at this point that Android released a Network Service Discovery API in Android Jelly Bean that bears a striking resemblance to the API that we're discussing here [1]. We are proposing an API that does one thing and one thing well, is tied directly to the DOM and that doesn't require changes to existing network services.

I've made previous arguments around this general topic of when Web Intents or DOM APIs make sense that I believe equally apply in the context of this discussion [2].

Thanks for taking the time to provide this feedback and let me know if anything here requires more discussion :)

br/ Rich

[1] <http://developer.android.com/reference/android/net/nsd/NsdManager.html#discoverServices(java.lang.String,%20int,%20android.net.nsd.NsdManager.DiscoveryListener)>

[2] <http://lists.w3.org/Archives/Public/public-device-apis/2012Sep/0027.html>

> 
> [1] http://w3c-test.org/dap/wi-addendum-local-services/
> 
> 
> 
> On Tue, Sep 25, 2012 at 4:42 AM, Rich Tibbett <richt@opera.com> wrote:
>> A new version of the Networking and Service Discovery & Messaging
>> specification is now available as an ED update.
>> 
>> This update incorporates all of the (excellent) feedback previously
>> submitted to this list by Cathy [1] [2]. The net result is a major rewrite
>> and clarification of the underlying rules and algorithms included in the
>> draft specification. This update does not affect the operation of the API
>> interfaces previously included but is instead more targeted at clarifying
>> low-level implementation details of working with different network discovery
>> protocols.
>> 
>> The latest draft of this specification is available in the usual place:
>> 
>> http://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/Overview.html
>> 
>> Any further feedback you have would be very helpful in moving this
>> specification forward.
>> 
>> Best regards,
>> 
>> Rich
>> 
>> [1] http://lists.w3.org/Archives/Public/public-device-apis/2012Aug/0017.html
>> 
>> [2] http://lists.w3.org/Archives/Public/public-device-apis/2012Aug/0095.html
>>