When a TUNNEL channel is started, the listener expects a "tunnel"
element from the initiator, either in the "start" element on channel
zero or on the new channel created. As usual, if it arrives on
channel zero, it is processed before the reply is returned.
In either case, the outermost "tunnel" element is examined. If it
has no attributes, then this peer is hosting the BEEP service that
the initiator wishes to use. In this case, the listener performs a
tuning reset:
o All channels, including channel zero, are implicitly closed.
o Any previously cached information about the BEEP session is
discarded.
o A new plaintext greeting is sent.
If the outermost element has a "port" attribute and an "fqdn"
attribute but no "srv" attribute, then "fqdn" is looked up as an A
record via DNS for translation to an IP number. An "ip4" attribute
is interpreted as the dotted-quad representation of an IPv4 address.
An "ip6" attribute is interpreted as a text representation of an IPv6
address. In each of these cases, a transport connection is
established to the so-identified server. If the outermost element
has a "srv" attribute, the concatenation of the "srv" attribute and
the "fqdn" attribute (with a period between) is looked up in the DNS
for a SRV record [6], and the appropriate server is contacted; if
that lookup fails and a "port" attribute is present, the connection
is attempted as if the "srv" attribute were not specified.
Alternately, if the outermost element has a "profile" attribute, then
it must have no nested elements. The proxy processing this element
is responsible for determining the appropriate routing to reach a
peer serving the BEEP profile indicated by the URI in the attribute's
value. Rather than source routing, this provides a hop-by-hop
routing mechanism to a desired service.
Similarly, if the outermost element has an "endpoint" attribute, then
it must have no nested elements. The proxy processing this element
is responsible for determining the appropriate routing to reach a
peer indicated by the value of the "endpoint" attribute. Rather than
source routing, this provides a hop-by-hop routing mechanism to a
desired machine. There are no restrictions on how machines are
identified.
Then, if the outermost element has no nested elements, but it does
have attributes other than "profile" or "endpoint", then this peer is
the final BEEP hop. (This corresponds to "proxy2" in the "Non-BEEP"
example above.) In this case, as soon as the final underlying
transport connection is established, an "ok" element is returned over
the listening session, and the tunneling of data starts. No BEEP
greeting (or indeed any data) from the final hop is expected.
Starting with the octet following the END(CR)(LF) trailer of the
frame with the completion flag set (more=".") of the RPY carrying the
"ok" element, the proxy begins copying octets directly and without
any interpretation between the two underlying transport connections.
If the identified server cannot be contacted, an "error" element is
returned over the listening channel and any connection established as
an initiator is closed. If there is a nested "tunnel" element, and
the server that has been contacted does not offer a BEEP greeting, or
the BEEP greeting offered does not include the TUNNEL profile, then
this too is treated as an error: the initiating transport connection
is closed, and an error is returned.
If there is a nested "tunnel" element, and the identified server is
contacted and offers a BEEP greeting including the TUNNEL profile,
then the outermost element from the "tunnel" element received is
stripped off, a new TUNNEL channel is started on the initiating
session, and the stripped (inner) element is sent to start the next
hop. In this case, the peer is considered a "proxy" (meaning that
the next paragraph is applicable).
Once the proxy has passed the "tunnel" element on the TUNNEL channel,
it awaits an "error" or an "ok" element in response. If it receives
an "error" element, it closes the initiated session and its
underlying transport connection. It then passes the "error" element
unchanged back on the listening session. If, on the other hand, it
receives an "ok" element, it passes the "ok" element back on the
listening session. Starting with the octet following the END(CR)(LF)
trailer of the frame with the completion flag set (more=".") of the
RPY carrying the "ok" element, the proxy begins copying octets
directly and without any interpretation between the two underlying
transport connections.
