Re: [discovery-api] Draft spec updates

Hi Cathy,

I've added my responses to your feedback in-line below.

The latest specification with the changes described below is available @ 
http://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/Overview.html

Cathy.Chan@nokia.com wrote:
> Below please find my comments on the updated spec.
>
> 1. At the beginning of Section 7, there's discussion on when the UA might
> perform the service discovery mechanisms.
> [[It is expected that user agents will perform these service discovery
> mechansisms asynchronously and periodically update the list of networked
> devices as required. The timing of any service discovery mechanisms is an
> implementation detail left to the discretion of the implementer (e.g. once
> on user agent start-up, every X seconds during user agent execution or on
> invocation of this API from a Web page).]]
> It's unclear to me what exactly "service discovery mechanism" encompasses,
> especially in the UPnP case. Does it refer only to issuing a search request
> for UPnP root devices? Or does it also include the *continuous* monitoring of
> the
> standard UPnP address and port for incoming requests and responses? To me,
> it doesn't make sense for a UA to issue a search at start-up but not follow
> up by continuously monitoring the standard address+port for new/updated
> announcements and disconnection messages (byebye messages).

Me neither.

> Such an
> implementation is bound to return either stale or useless information to web
> pages on invocations of the getNetworkServices API as time goes by.

It wouldn't be in anyone's interest to implement the service discovery 
mechanisms in this way. FWIW, "Service Discovery Mechanisms" is intended 
to encompass everything currently included in Section 7 of the 
specification. I've included a definition to that effect in the 
specification.

The text is written as-is since the exact strategy to obtain network 
service records is intended to be left up to the discretion of the 
implementer. The specification gives detailed descriptions of what to do 
with particular service discovery protocols but is not prescriptive on 
exactly when things need to occur in any given strategy.

I've re-worded this statement in the specification (and added a 
definition of 'service discovery mechanisms'). If you have ideas for 
further improvements in this area of the specification that would be 
interesting.

> This
> also affects whether the definition of the list of available service records
> as " track all the services that have been discovered and are available in
> the current network *at any given time*" is accurate or not.

I've updated this to 'at the current time'. The previous text could have 
been implied to only apply to the continuous monitoring strategy.

> Secondly, if the UA only performs discovery on invocation of the
> getNetworkServices API, does it still issue the search looking for all
> device types (using "_services._dns-sd._udp" with Zeroconf or
> "upnp:rootdevice" with UPnP, as described in 7.1 and 7.2), or should it
> issue the search based on the requested types?

Since a search for all devices on the local network is going to yield a 
super-set of the requested services, and since the current web page or 
another web page may re-invoke getNetworkServices at some point in the 
near future with an entirely different set of requested service types, I 
believe it makes sense to issue more generic searches and for the UA to 
maintain a more holistic overview of the services available in the 
current network at all times*.

* Note the general caveat included in the spec: "Conformance 
requirements phrased as algorithms or specific steps may be implemented 
in any manner, so long as the end result is equivalent". If the result 
is equivalent (I get the network services I asked for), the means is 
unimportant (how the UA has actually accumulated those records).

>
> 2. With respect to the "list of authorized service records", "each record in
> the list of authorized service records is associated with a services manager
> object that is assigned as part of the getNetworkServices() algorithm". Is
> it possible for a record to be associated with multiple Services Manager
> objects? I would imagine that if two separate web pages both invoked the
> getNetworkServices API with the same service type, there would only be one
> record for each matching service, and each of those records would be
> associated with both Service Manager objects.
> Thus, s/a services manager object that is/services manager objects that are/
> ?

I've switched around how this algorithm is presented in the 
specification by removing the 'list of authorized service records' and 
adding in its place 'list of active service managers'. In effect, it's 
now more top-down in its directives than bottom-up but the outcome is 
intended to be identical (hopefully easier to read).

So now we maintain a 'list of active service managers' that each contain 
one or more NetworkService objects. The algorithms have been updated and 
this should have removed any ambiguity here and improved the general 
structure of the spec. Let me know what you think or if you have other 
suggestions here.

> 3. In the rule for "adding an available service"...
> 3.1 In step 4.2, if multiple matching active records are associated with a
> Services
> Manager object, the servicesAvailable attribute of the Services Manager object
> would incorrectly be incremented multiple times. For example, if a Services
> Manager object was associated with two UPnP ContentDirectory service records,
> and a new UPnP ContentDirectory service is being added, the servicesAvailable
> attribute of the Services Manager would be incremented by 2, and two
> serviceavailable events would be dispatched. Thus, the algorithm needs to be
> modified to ensure that step 4.2 is only done once for each Services Manager
> object.

Hopefully the change noted in my previous comment should have addressed 
this.

> 3.2. Step 4.3 is missing the necessary conditions: 1) if the new service
> registration
> flag is set to false, 2) the id of the "network service record" (i.e. the one
> being
> added) matches that of the current active service object, and 3) the online
> attribute of the current active service object was previously false (before
> being replaced in step 2.3).
> Both of these comments also apply to the rule for "removing an available
> service".

Good catch. I've added these in to the algorithm (now Step 4.2.3 in 
'adding an available service' and Step 1.3.2.3 in 'removing an available 
service').

>
> 5. In 7.1, step 2.7, why is an expiration time of 120 seconds mandated? My
> understanding is that DNS-SD/mDNS allows the expiration time to be specified
> in either the PTR or TXT record. Even if it's not available from there, this
> value should be left up to the implementation.

120 seconds is the default and servers shouldn't have any need to change 
this value. Having said this, I do intend to review the Zeroconf section 
in detail soon and allow services to set their own expiration times in 
an upcoming edit.

>
> 6. In 7.2, "advertisement for UPnP root device" should be "search request
> for UPnP root device" throughout.

Changed.

>
> 7. In 7.2, "The user agent must listen for incoming requests and process any
> incoming responses to any advertisement for UPnP root devices on the
> standard UPnP address and port, on all current local network interface
> addresses with the port 1900, according to the rules defined in this
> section." This is not completely accurate. Incoming *requests* arrive on the
> standard UPnP address and port, but incoming *responses* arrive on
> whatever port the UA used to send the initial search request, which *must
> not* be 1900. The sentence should be split into two, one addressing requests
> and one addressing responses. Additionally, for readability and clarity, I
> would put the sentence about incoming requests to just before the steps that
> begin with "For each HTTP Request received ...".
> Thus,
> The user agent must listen for and process any incoming responses to any
> search request for UPnP root devices according to the rules defined in this
> section.
> For each HTTP Response following ...
> [algorithm]
> The user agent must listen for and process incoming requests on the standard
> UPnP address and port, on all current local network interface addresses with
> the port 1900, according to the rules defined in this section.
> For each HTTP Request received ...
> [algorithm]

Fixed.

> 8. In 7.2, in the steps for processing HTTP Responses...
> 8.1 We can add that the UA may stop listening after the max wait time has been
> exceeded.

Done.

> 8.2 In Step 5, the value of the CACHE-CONTROL header begins with the string
> "max-age=". It needs to be removed before passing the content as the device
> expiry argument.
> Thus, s/ CACHE-CONTROL from ssdp device/CACHE-CONTROL from ssdp device
> (minus the leading string of "max-age=")/

Done.

>
> 9. In 7.2, in the steps for processing HTTP Requests...
> 9.1 In Step 1, s/return a HTTP 200 OK response,//.

Done.

> 9.2 Step 3 applies only to ssdp:alive messages. It should start with "If the
> value of the NTS entry of the ssdp device is 'ssdp:alive'". Also, s/return a
> 400 Bad Request response,//.
> 9.3 In step 4, there is no need to process ssdp:update messages, which are
> bound to be followed by ssdp:alive messages. (Besides, ssdp:update messages
> do not have the LOCATION header.) I brought up ssdp:update messages in my
> previous comments because in the previous drafts, anything that is not an
> ssdp:alive message is assumed to be an ssdp:byebye message and triggers
> device removal. In the new draft, device removal is explicitly associated
> with ssdp:byebye messages (instead of "non ssdp:alive" messages), so my
> concern has been addressed.

I've removed 'ssdp:update' processing (and the HTTP 400 Bad Request) 
from the specification.

> 9.4 In Step 4, same as 8.2 above.

Done.

>
> 10. In 7.2, in the rule for obtaining a UPnP Device Description File...
> 10.1 Step 2 "root device descriptor file" should be "device descriptor file".

Typo fixed.

> 10.2 Step 4 describes processing of embedded devices. Since embedded devices
> may further contain a deviceList of embedded devices, this step should be
> moved to the end of the rule for processing a UPnP Device Description File.
> That way, processing of embedded devices is done recursively without extra
> efforts.

An excellent idea and done.

>
> 11. In 7.2, in the rule for processing a UPnP Description File...
> 11.1 The algorithm uses the USN header value from the SSDP message as the
> device identifier. The device identifier is then used for two purposes - in
> 2.2 for creating a<unique>  id attribute for the service (by combining the
> device identifier with the UPnP serviceId), and in 2.3 for subsequently
> identifying services that belong to the device in the device removal process.
> The identifier works fine for the second purpose. However, for the first
> purpose, if a root device contains embedded devices, this could easily result
> in duplicate ids among service records. For example, the MediaServer spec
> requires that a ContentDirectory service always has a serviceId of
> "urn:upnp-org:serviceId:ContentDirectory". If a device contains two embedded
> MediaServer devices (which might be odd but entirely legitimate, and may
> enable some special use cases), then the algorithm would result in two service
> records with the same id attribute. My suggestion is to use the UDN element
> (a unique ID for each device, and each embedded devices) within the (current)
> device description file in composing the id attribute to ensure uniqueness.

You're totally right. I think we've also implemented this incorrectly in 
our current internal prototype..

Fixed in the spec.

>
> 12. In the steps for setting up a UPnP Events Subscription...
> 12.1 In Step 5.4.4, with a valid 200 OK response, in addition to updating
> callback ID, it is also necessary to update the timeout date, and return to
> Step 5.4. (It might be simpler to just go straight back to Step 5.1 if the
> response is a 200 OK.)

I believe this is now fixed in the spec but it may need a little more 
tweaking in a next edit.

> 12.2 In Step 5.5, there also needs to be a step to send a 200 OK response back
> to the event publisher. (UDA11 Section 4.3.2)

Added as Step 5.5 in 'setup a UPnP Events Subscription'.

>
> I'd add that I really like the organization changes and clarifications made to
> this revision. Kudos!

Thanks! The credit is really yours for providing all this hq feedback ;)

- Rich

>
> Regards, Cathy.
>
>
>> -----Original Message-----
>> From: ext Rich Tibbett [mailto:richt@opera.com]
>> Sent: Tuesday, September 25, 2012 7:43 AM
>> To: W3C Device APIs WG
>> Subject: [discovery-api] Draft spec updates
>>
>> 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

Received on Wednesday, 3 October 2012 01:08:13 UTC