 |
The Proposed Relay Replacement
This page discusses the specifications for the proposed replacement of the Relay Service. The material is relevant for all JXTA implementations. The contents of this page, once formalized, will be integrated into the JXTA Spec.
 Check out JXTA-C Relay implementation design spec.
Seeding Address
A seeding address is a URI, which when resolved returns a "text/plain" list of seed addresses separated by carriage returns. The returned
list(referred as seeding list) should be treated as an ordered list in the order of preference. If several seeding addresses are provided they should be resolved in random order.
Seed Address
A seed address is a physical transport address of a relay server the client can contact with. Normally seed addresses are not ordered and should be used in random order.
Endpoint Address for Relay
- Service Name: jxta:uuid-CBE0B766C9B211DA97C600E081280BF406
- Service Param: NULL
This new Relay Protocol uses a new ModuleSpecID assigned so that it can co-exist with the earlier JXTA 2.0 relay implementation
 The ID is a uuid based on a ethernet MAC address and time. slowhog@200604111632
Relay service should register that endpoint address during it lifetime.
Relay Client
A relay could be configured with seeding addresses, and seed addresses.
A minimum of two is recommended for failover purposes.
When none is specified, relay service assumes it is in ad-hoc mode and
relys on multicast discovery to find a relay referral.
When a relay client starts, it will try to get a seeding list to probe.
In order to have better knowledge of the network, it prefers to use the
seeding address rather than the configured seed addresses.
For the sake of better distribute the traffic, the seeding addresses and seed
addresses are randomized when they are loaded from the configuration.
Then the relay client will start with the list of seeding address. It
should start with the first entry from the list and move to next only
when the current one failed until it get a seeding list.
For the seeding list the relay clients get(from the seeding
address or configuration), the relay client will start with the first
entry from the list and move to the next only when the first fails.
The relay client then send a relay request to the relay server
identified by the entry. Waiting for response in a configurable
time(default to 30 seconds), if no response was received, move to next
entry.
When a response is received, it MAY contain a lease offer. If there
is a lease, the client SHOULD take the lease. If there is no lease, the
client MAY try to get a lease from one of the referral from the response.
A response MAY have a list of referrals the relay server is aware of, and
the client SHOULD save the list for later use when the relay server is
not offering leases or fails in some other way.
In case there is no referral or none of the referrals are working, the relay client
falls back to use the seeding lists.
Relay Server
A server SHOULD send a response to valid requests it received. The
offeredLease attribute should be the lease period in millisecond. This
value is determined by the server based on it's configuration. The
maximum offeredLease value SHOULD be the requestedLease value the client is asking for.
In case the server does not want to offer a lease to a new client, it should send a
response message without the offeredLease attribute but with referral to
other relay servers unless the server knows no other relay servers.
The number of referrals should be the top 2 choices if the relay knows
more than 2 other relay servers for failover purposes. The client would
fall back to it's seeding list in case no relay lease can be obtained
through this relay server and the referrals.
In case the server want an existing client to disconnect, for example,
when the relay server is going down, it can send a response message with
offeredLease value 0.
Relay server uses discovery services to find other relay servers.
Relaying messages
After a client got a lease from a relay server, it SHOULD update it's own
AccessPointAdvertisement to include the relay server as a hop. So when
other peers trying to send messages to the client, the peer can figure
out whether it can send with direct connection or should go to the relay
server.
The relay server SHOULD know how to send messages back to its clients.
Leasing Protocol XML Schema
The Relay Service uses the newly defined JXTA common leasing protocol and messages in order to coordinate leases between clients and servers. The common leasing protocol is expected to be used by future versions of the Rendezvous service as well.
Lease Request Message
The Lease Request message is sent by a Relay Client in order to request a lease from a Relay Server. Additionally it may also be used by the client to immediately terminate a previously requested lease and also to request referral Relay Servers advertisements.
<xs:complexType name="LeaseRequestMessage">
<xs:sequence>
<xs:element name="credential" minOccurs="0" maxOccurs="1" type="jxta:Cred" />
<xs:element name="options" minOccurs="0" maxOccurs="unbounded" type="xs:anyType" />
</xs:sequence>
<xs:attribute name="clientID" use="required" type="jxta:JXTAID" />
<xs:attribute name="requestedLease" type="xs:unsignedLong" />
<xs:attribute name="serverAdvGen" type="uuid" />
<xs:attribute name="referralAdvs" type="xs:unsignedInt" />
</xs:complexType>
credential [element] : An optional element containing the credential of the relay client.
options [element] : An optional element containing any options and attributes appropriate to the service's use of the Lease Request Message.
clientID [attribute] : The Peer ID of the relay client.
requestedLease [attribute] : The desired duration of the lease the relay client would like to get. Measured in milliseconds. The lease offered in response by the relay server SHOULD be no longer than this value. If 0 then the client wishes to be immediately disconnected. If not present then the client is only looking for referrals.
serverAdvGen [attribute] : The UUID value which was provided by the relay server along with it's advertisement in a previous response. If the Advertisement (and thus the associated UUID) is unchanged the relay server response SHOUD NOT include the relay server advertisement.
referralAdvs [attribute] : The number of referral advertisements requested by the relay client. The relay server SHOULD return no more referrals than requested but MAY return fewer (including none).
Lease Response Message
The Lease Response message is normally returned by the relay server in response to a client Lease Request. It may also be sent by the relay server to a relay client inorder to instruct them to disconnect.
<xs:complexType name="LeaseResponseMessage">
<xs:sequence>
<xs:element name="credential" minOccurs="0" maxOccurs="1" type="jxta:Cred" />
<xs:element name="serverAdv" minOccurs="0" maxOccurs="1">
<xs:complexType>
<xs:complexContent>
<xs:extension base="jxta:PA">
<xs:attribute name="serverAdvGen" use="required" type="uuid" />
<xs:attribute name="expiration" use="required" type="xs:unsignedLong" />
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name="referralAdv" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:complexContent>
<xs:extension base="jxta:PA">
<xs:attribute name="expiration" use="required" type="xs:unsignedLong" />
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
<xs:element name="options" minOccurs="0" maxOccurs="unbounded" type="xs:anyType" />
</xs:sequence>
<xs:attribute name="serverID" use="required" type="jxta:JXTAID" />
<xs:attribute name="offeredLease" type="xs:unsignedLong" />
</xs:complexType>
credential [element] : An optional element containing the credential of the relay server.
serverAdv [element] : The Peer Advertisement used to advertise the relay server. If not present then the serverAdvGen presented by the relay client matched the current UUID value.
serverAdvGen [attribute] : A UUID identifying the current relay server advertisement. This value changes each time the relay server advertisement changes (not normally frequently).
expiration [attribute] : The duration of milliseconds the relay server advertisement remains valid after been received. The advertisement SHOULD expire after the offeredLease.
referralAdv [element] : The Peer Advertisement of another Relay Server.
options [element] : An optional element containing any options and attributes appropriate to the service's use of the Lease Response Message.
expiration [attribute] : The duration of milliseconds the relay server advertisement remains valid after been received.
serverID [attribute] : The ID of the Relay Server.
offeredLease [attribute] : The duration in milliseconds for the lease being offered by the relay server. A value of 0 means that any existing lease which was previously offered to the relay client is immediately terminated. If not present then no lease is offered (with no impact upon existing leases).
|