addressing summary

[Rafael Schloming <rafaels@redhat.com>]

Please see the attached summary of the current state of addressing.

--Rafael

As promised at the TC meeting, here is a summary of where the global
addressing spec stands currently. What is contained below are
summaries of the key definitions and examples. This should cover the
full scope of the addressing spec, however it is obviously not
complete in detail, use cases, examples, so forth.

Definitions:

 - Address syntax:

               address = address-atom
                      / address-atom ";" address

         address-atom = address-literal
                      / address-space

        address-space = global-address "/*"
                      / global-address "/%"
                      / "//*." reg-name             ; reg-name is from RFC3986
                      / "//%." reg-name             ; reg-name is from RFC3986

      address-literal = global-address
                      / container-address

       global-address = "/" domain [ "/" path ]

    container-address = reg-name                    ; reg-name is from RFC3986

               domain = unregistered-domain
                      / registered-domain

    registered-domain = "/" srv-literal

          srv-literal = [ "_" service "._" proto "." ] host [ ":" port ]
              service = [a-zA-Z_]+
                proto = [a-zA-Z_]+
                 port = *DIGIT
                 host = IP-literal / IPv4address / reg-name    ; IP-literal, IPv4address, and reg-name are from RFC3986

  unregistered-domain = name

                 path = name [ "/" path ]
                 name = [^/*%;]+

 - Newly defined connection properties/capabilities:

   where-i-am: <address-space>

     Identifies a container's subspace within the global address
     space. Peers can define their own subspace within this, but it is
     the responsibility of the peer to use a unique subspace. This
     permits the peer to reuse stable subspaces or to simply make up a
     new one each time.

     A given address in this space is leased when a link endpoint is
     established. The lease expires when all matching link endpoints
     are terminated.

     For the period that the lease is held, the intermediary will
     route any globally addressed messages matching the leased address
     to the endpoint(s) holding the lease. (Need to clarify routing
     semantics when multiple link endpoints match.)

   who-i-am: <address> (container internal addresses not allowed)

     Advertizes a global address for a given container. Intermediaries
     or peers with the router capability (defined below) MUST route
     any messages that match this address and not a more specific one
     to the advertizing container. This could happen via the anonymous
     relay or direct addressing.

     This implies the advertizing container MUST accept incoming links
     where the source side is an anonymous relay.

   router: capability (True/False)

     If present indicates that the peer is capable of routing messages
     based on the who-i-am of connected partners.

     Existing links SHOULD be used to make delivery. If no existing
     links match, then a new link MAY be created either to the exact
     address, to an address pattern (e.g. //who-i-am/*), or to the
     anonymous relay.

 - In addition to the connection properties, we are defining the
   behaviour of the anonymous relay.

   The anonymous relay routes messages onto outgoing links based on
   matching the message address to the outgoing link target. Links
   from the anonymous relay to a container-address are not permitted.

   Messages from all links into the anonymous relay are routed.
   Messages from links established to other addresses MAY be routed
   depending on the semantics associated with those addresses. In
   other words, many addresses may be considered aliases for the
   anonymous relay, but some addresses may resolve directly to other
   kinds of nodes like queues.

   Success/failure of links to the anonymous terminus establishes
   whether a container is capable of relaying or routing messages
   through the anonymous terminus.

Examples:

  - The general mechanism for request response is to A) determine a
    suitable reply address and B) set the reply-to in your request to
    that address. The following scenarios cover some of the different
    ways you can determine a suitable reply address without creating a
    temporary queue and indicate some of the semantic differences
    betweeen each case.

    1. If partners support router capability: advertise who-i-am and
       simply set reply-to to an address matching who-i-am. Partners
       will initiate link(s) as needed to deliver replies.

       Message properties define the quality of service.

    2. Establish link from partner's anonymous relay ---> my-address
       (my-address may or may not match who-i-am). If link succeeds
       simply set reply-to to an address matching my-address and
       partner will respond via the relay.

       The link establishes the quality of service for addresses that
       do not match who-i-am or where the partner isn't a router.

    3. Establish direct link from service-node ---> my-address
       (my-address may or may not match who-i-am). Set reply-to to an
       address matching my-address and partner will respond via the
       established link.

       The link establishes the quality of service for addresses that
       do not match who-i-am or where the partner isn't a router.

       If the service node doesn't support matching, it can refuse
       links to address spaces and/or address lists.

       Note that my-address may be a container-address.