Query on discovery algoritm for LRDD (draft-hammer-discovery-04)

[John Panzer <[e-mail]>]

 All,

This is my attempt to translate *
http://tools.ietf.org/html/draft-hammer-discovery-04* into an actionable
algorithm, as a first step in attempting to write a truly general resource
discovery library that matches the latest spec.  It is written under the
assumption that a client may wish to query for sets of links with a given
relvalue, and is not going to wish to retrieve and re-parse host-meta files
any more often than necessary.  Feedback welcomed!

*Definitions*

   - *startURI*: Starting point for discovery; input into the discovery
   process.  Discovery produces metadata for *startURI.*
   - *meta data:*A collection of links and properties for the resource.
   - *link*: An abstract edge between the*startURI*resource and another
   resource identified by a field *href.  *Has a*rel*field indicating the
   relationship from *startURI *to *href.* Has a *lrdd_pri *field indicating
   ordering within the *rel *value.  Has a *secure *boolean field indicating
   whether it was retrieved securely.  Can be annotated with arbitrary *
   properties*.
   - *property*: A piece of metadata about a resource less structured than
   a *link.* Only present for XRD-derived data.  Has a *secure *boolean
   field indicating whether it was retrieved securely.



*Algorithm*

   1. Determine priority order (Host-priority or Resource-priority):
      1. lookup HostMetaLRDD(startURI)
      2. if above lookup fails because Host(startURI) is not available,
      priority = Resource (goto step 2)
      3. Else, does result contain XRD/Property@type=
      http://lrdd.net/priority/resource?
      4. If yes, then priority = Resource (goto step 2)
      5. Otherwise, priority = Host (goto step 2)
   2. If priority = Host:  *// priority order is host-meta, HTTP Link,
   <Link> elements*
      1. metadata = lookup HostMetaLRDD(startURI, 1)
      2. augment metadata with result of lookup HeaderLinks(startURI, 2)
      3. augment metadata with lookup ResourceLinks(startURI, 3)
   3. If priority = Resource:*// priority order is <Link> elements, HTTP
   Link, host-meta*
      1. metadata = lookup ResourceLinks(startURI, 1)
      2. augment metadata with result of lookup HeaderLinks(startURI, 2)
      3. augment metadata with lookup HostMetaLRDD(startURI, 3)


*where*

HostMetaLRDD(uri, pri) is:

   1. Revalidate local XRD data cache for hostof(*uri*
   )/.well-known/host-meta.
   2. Find*the first link*with rel=”lrdd” in host-meta document (call the
   href value *lrdd_url*)
   3. Revalidate local XRD data cache for *lrdd_url,*annotating each link
   with *lrdd_pri*=pri
   4. Return metadata (non-lrdd links and properties) for *lrdd_uri*



HeaderLinks(uri, pri) is:

   1. If uri is not dereferenceable (e.g., acct:) return empty set
   2. Revalidate local resource link cache for *uri*
   3. Retrieve Link: headers for resource from cache, annotating each link
   with *lrdd_pri*=pri
   4. Return links to caller



ResourceLinks(uri, pri) is:

   1. If uri is not dereferenceable (e.g., acct:) return empty set
   2. Revalidate local resource link cache for *uri*, annotating each link
   with *lrddsrc =*resource
   3. Retrieve MIME-type-specific set of links known for resource,
   annotating each link with *lrdd_pri=*pri
   4. Return links to caller



augment X with Y with priority pri is:

   1. For each set of links y in Y sharing link relation r:
      1. if r==”lrdd”, and X does not already contain a link with
      rel=”lrdd”:, augment X with results of:
         1. Revalidate local XRD data cache for first *href *for rel=”lrdd”,
         annotating each link with *lrdd_pri*= pri
         2. Augment X with resulting metadata from *href*
      2. else, add list of links y to X.
   2. Add all properties in Y to X.



NB: Some link types can contain space-separated rel values, which are
interpreted as a series of links with each of the space-separated rel value
names in the above algorithm.

NB: Ordering of links and properties from each source with the same rel/type
values is retained throughout, with the caveat that HTTP headers do not have
a guaranteed stable order.

Security is not shown here, but is based on either TLS used throughout the
retrievals or (for XRD) the XRD signature specification.  Content type
specific security may also be used to verify links within content (e.g.,
Magic Signatures over link elements).  When set, the *secure *boolean
indicates that a specific link or property was retrieved securely; when not
set, it indicates that the retrieval path contained one or more insecure
steps.  The algorithm will also reject data that is red-flagged (e.g., if a
CRL check shows that a certificate has been revoked as opposed to merely
expiring).  (?)

*Result*:

An ordered collection of metadata, consisting of links and properties, each
of which is annotated with its*lrddsrc*provenance.  There is at most one
rel=”lrdd” link in the collection which identifies the specific LRDD
document used, if any.

A client which wishes to coalesce links and properties found in all three
places within a given rel or type value can just query the collection for
the desired rel or type and retrieve collections of links or properties.

Once retrieved, the set of metadata can be queried.  An important/useful
query is to retrieve the list of links with a given rel value:

get_links(metadata, rel)  # Get sequence of links with given rel value, or
empty list if not found.

Sometimes you may require that only the first set of links found count:

get_top_priority_links(metadata, rel)  # Get sequence of links with given
rel value, ignoring all but the first set found

...and of course you can do a similar query for properties.