Messenger Addressing and Routing

Addressing

An address has the following form:

[ amqp[s]:// ] [user[:password]@] domain [/[name]]

Where domain can be one of:

host | host:port | ip | ip:port | name

The following are valid examples of addresses:

* example.org
* example.org:1234
* amqp://example.org
* amqps://example.org
* example.org/incoming
* amqps://example.org/outgoing
* amqps://fred:trustno1@example.org
* 127.0.0.1:1234
* amqps://127.0.0.1:1234

The “/name” part of the address, that optionally follows the domain, is not used by the Messenger library. For example, if a receiver subscribes to

    amqp://~0.0.0.0:5678

Then it will receive messages sent to

    amqp://~0.0.0.0:5678

as well as amqp://~0.0.0.0:5678/foo

Likewise, if the receiver subscribes to

    amqp://~0.0.0.0:5678/foo

it will receive messages addressed to

    amqp://~0.0.0.0:5678/foo
    amqp://~0.0.0.0:5678

and

    amqp://~0.0.0.0:5678/bar

Routing

Pattern Matching, Address Translation, and Message Routing

The Messenger library provides message routing capability with an address translation table. Each entry in the table consists of a pattern and a translation.

You store a new route entry in the table with the call:

    pn_messenger_route(messenger, pattern, translation);

The address of each outgoing message is compared to the table's patterns until the first matching pattern is found, or until all patterns have failed to match.

If no pattern matches, then Messenger will send (or attempt to send) your message with the address as given.

If a pattern does match your outgoing message‘s address, then Messenger will create a temporary address by transforming your message’s address. Your message will be sent to the transformed address, but (note!) the address on your outgoing message will not be changed. The receiver will see the original, not the transformed address.

Two Translation Mechanisms

Messenger uses two mechanisms to translate addresses. The first is simple string substitution.

    pattern:     COLOSSUS
    translation: amqp://0.0.0.0:6666
    input addr:  COLOSSUS
    result:      amqp://0.0.0.0:6666

The second mechanism is wildcard/variable substitution. A wildcard in the pattern matches all or part of your input address. The part of your input address that matched the wildcard is stored. The matched value is then inserted into your translated address in place of numbered variables: $1, $2, and so on, up to a maximum of 64.

There are two wildcards: * and % . The rules for matching are:

    * matches anything
    % matches anything but a /
    other characters match themselves
    the whole input addr must be matched

Examples of wildcard matching:

    pattern:      /%/%/%
    translation:  $1x$2x$3
    input addr:   /foo/bar/baz
    result:       fooxbarxbaz

    pattern:      *
    translation:  $1
    inout addr:   /foo/bar/baz
    result:       /foo/bar/baz

    pattern:      /*
    translation:  $1
    input addr:   /foo/bar/baz
    result:       foo/bar/baz

    pattern:      /*baz
    translation:  $1
    input addr:   /foo/bar/baz
    result:       foo/bar/

    pattern:      /%baz
    translation:  $1
    input addr:   /foo/bar/baz
    result:       FAIL

    pattern:      /%/baz
    translation:  $1
    input addr:   /foo/bar/baz
    result:       FAIL

    pattern:      /%/%/baz
    translation:  $1
    input addr:   /foo/bar/baz
    result:       foo

    pattern:      /*/baz
    translation:  $1
    input addr:   /foo/bar/baz
    result:       foo/bar

Examples of route translation usage:

    pattern:     foo
    translation: amqp://foo.com
    explanation: Any message sent to "foo" will be routed to "amqp://foo.com"


    pattern:     bar/*
    translation: amqp://bar.com/$1
    explanation: Any message sent to bar/<path> will be routed to the corresponding path within the amqp://bar.com domain.


    pattern:     amqp:*
    translation: amqps:$1
    explanation: Route all messages over TLS.


    pattern:     amqp://foo.com/*
    translation: amqp://user:password@foo.com/$1
    explanation: Supply credentials for foo.com.


    pattern:     amqp://*
    translation: amqp://user:password@$1
    explanation: Supply credentials for all domains.


    pattern:     amqp://%/*
    translation: amqp://user:password@proxy/$1/$2
    explanation: Route all addresses through a single proxy while preserving the
     original destination.


    pattern:     *
    translation: amqp://user:password@broker/$1
    explanation: Route any address through a single broker.

First Match Wins

If you create multiple routing rules, each new rule is appended to your Messenger‘s list. At send-time, Messenger looks down the list, and the first rule that matches your outgoing message’s address wins. Thus, when creating your routing rules, you should create them in order of most specific first, most general last.