Jonathan Robie wrote:
For consistency with HTML URLs, I prefer ; to ,
http://www.w3.org/TR/1999/REC-html401-19991224/appendix/notes.html#h-B.2.2
As clarified by IRC this is referring to the use of "&: as an option separator
in the query section rather than the use of "," as an address separator in the
authority section. I've switched from & to ; in the query section as per
Jonathan's suggestion. I've left "," in the address section to avoid needless
changes to the existing AMQP 0-10 spec.
* Proposal to unify Qpid and AMQP URL addressing.
The Qpid M4 Java and C++ clients use different URL formats.
Java uses: http://cwiki.apache.org/qpid/connection-url-format.html
C++ uses the AMQP 0-10 format:
http://jira.amqp.org/confluence/download/attachments/720900/amqp.0-10.pdf?version=1
section 9.1.2
The AMQP 0-10 format only provides protocol address information for a
(list of) brokers. The Qpid M4 Java format provides additional options
for connection properties (user, password, vhost etc.)
* Proposed URL syntax
This following proposal combines the features of both formats,
intended to be a unified format for Qpid and the basis of a proposal
to the AMQP working group.
Note: terms not defined below (uric, pchar, digit, alpha, host, scheme) are
taken from http://tools.ietf.org/html/rfc3986
<code>
; URL begins with optional user identification and list of protocol addresses.
amqp_url = "amqp://" [ userpass ] broker_addr [ vhost ]
userpass = user [ ":" pass ] "@"
user = *pchar
pass = *pchar
broker_addr = addr *( "," addr )
addr = prot_addr [ options ]
prot_addr = tcp_prot_addr | other_prot_addr
vhost = "/" *pchar [ options ]
; TCP is the default protocol
tcp_prot_addr = tcp_id tcp_addr
tcp_id = "tcp:" / "" ; tcp is the default
tcp_addr = [ host [ ":" port ] ]
host = ; see http://tools.ietf.org/html/rfc3986
port = *DIGIT
; Other protcol address formats can be specified by the standard or by
implementations.
; They must conform to this grammar:
other_prot_addr= other_prot_id ":" *pchar
other_prot_id = scheme
; Options can be added to individual addresses or to the vhost.
options = "?" option *( ";" option )
option = name "=" value
name = *pchar
value = *pchar
</code>
Options can be applied to the entire connection or to a specific
protocol addresses, providing a flexible way to extend the URL
syntax. The AMQP standard will define some options, implementations
may define proprietary options. Implementations should ignore any
option they do not recognize.
Reserved characters in option values must be percent-encoded as per
http://tools.ietf.org/html/rfc3986.
The meaning of the userpass information depends on the security mechanism
in use. Security mechanisms should use the userpass information from the
URL if it is appropriate but may ignore it and acquire authentication
information in some other way. If there is no security mechanism the
userpass information is ignored.
TODO need to define:
- protocol address formats and options for other transports - ssl/tsl,
infiniband, vm...
- standard options for values in the standard connection negotiation.
- qpid proprietary options (e.g. JMS clientid?)
* Examples
# Connect to default vhost and default AMQP port on host1 via TCP.
amqp://host1
# Connect to port 1234, virtual host "vhost" passing username "foo",
# password "bar" and a Qpid JMS client-id.
amqp://foo:b...@tcp:host1:1234/vhost?clientid=baz
# Connect to the first of host1,host2,host3 that succeeds, retry each twice.
# retry property at connection level is applied to all addresses.
amqp://host1,host2,host3/?retry=2
# Connect to the first of host1, host2, host3 that succeeds, retry host2 twice.
amqp://host1,host2?retry=2,host3
* Differences from current formats
** Differences from AMQP 0-10 format
AMQP 0-10 did not have an initial // after amqp: The justification was
that that the // form is only used for URIs with hierarchical
structure as per http://tools.ietf.org/html/rfc2718
This proposal does use amqp:// because in fact the URL does specify a
simple 1-level hierarchy of address/vhost. In the future this
hierarchy could be extended to address objects within a vhost such as
queues, exchanges etc. The // syntax is also more familiar for a URL.
A parser for the above format can also parse AMQP 0-10 URLs by
relaxing the grammer as follows:
amqp_url = "amqp:" [ "//" ] [ userpass ] broker_addr [ vhost ]
** Differences from Qpid Java format
Addresses are at the start of the URL rather than in the "brokerlist" option.
Option format is ?foo=bar;x=y rather than ?foo='bar'&x='y'. The use of
"'" quotes is not common for URI query strings, see
http://en.wikipedia.org/wiki/Query_string.
The use of "&" as a separator creates problems, see
http://www.w3.org/TR/1999/REC-html401-19991224/appendix/notes.html#h-B.2.2
user, pass and clientid are options rather than having a special place at the
front of the URL.
clientid is a Qpid proprietary property and user/pass are not relevant in all
authentication schemes.
Qpid M4 Java URLs requires the brokerlist option, so this is an easy
way to detect a Qpid M4 URL vs. a URL as defined here and parse
accordingly.
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscr...@qpid.apache.org
