Hypergrid Protocol

=Introduction=

This page begins to describe the protocol level details for Hypergrid. It will apply only to Hypergrid 2.0 and later.

= Components =

Gatekeeper service

 * Provides information to callers about Hypergrid accessible regions on the grid.
 * Controls and manages user agent access to the grid - similar to the login service for non-Hypergrid users.
 * Authenticates an incoming connection with the source grid's User Agent VerifyAgent call.

User Agent service

 * Provides a VerifyAgent call so that the Gatekeeper service can authenticate that an incoming user agent originates from its given source grid.

As source of teleport

 * Initiates teleport process once requested by a viewer.
 * Makes contact with destination grid's gatekeeper service.
 * On approval, signals client to begin teleport and starts hand off to source region.
 * Part of this is sending attachments information over to the foreign region.

As destination of teleport

 * Verify's user agent with source installation's User Agent service.
 * Relays inventory requests to home grid inventory service.
 * On rezzing objects, inspects referenced assets and requests from home grid asset service.
 * If assets can be imported, then copies to local asset service.

Viewer

 * Speaks to the current and target simulators using LLUDP and capabilities.
 * No interation with grid services to complete teleport.

= Protocol Flow =

Teleport of an agent into a foreign grid

 * 1) Gatekeeper service receives a request from the source grid for information about a region with a given UUID.
 * 2) If the gatekeeper can find the region in the grid service, the details are returned to the requester.
 * 3) The most crucial is the ExternalHostName and InternalPort (a misleading name as it is also the external port) as set up in the Regions configuration file.  This is the address (along with the simulators HTTP port) that the viewer will use to transfer to the destination region from its source region.
 * 4) If teleporting direct to regions is disallowed by the grid then the a gateway region may be returned instead.
 * 5) If the region is not found then a failure response is returned.
 * 6) Gatekeeper service receives login request for a given agent (e.g. Joe Bloggs @ http://grid-source.com:8002).
 * 7) Gatekeeper service authenticates with source grid's User Agent service that user agent originates from there.
 * 8) Gatekeeper service notifies destination region that a connection is incoming.
 * 9) Destination region waits for initial client seed capabilities connection.
 * 10) On receipt verifies client with source grid's User Agent service that user agent originates from there.
 * 11) In the simulator this point is indicated in the log with a message such as "[SCENE]: Incoming client Joe Bloggs in region my-region via HG login".
 * 12) Hence, the home grid of the incoming agent must have a UserAgent service that is reachable by the simulator receiving the connection.
 * 13) If verification is successful, then one would see a simulator debug log message such as "[SCENE]: User Client Verification for Joe Bloggs in my-region returned true".
 * 14) If verification fails (often because the home grid's user agent service could not be contacted), then one would see a simulator debug log message such as "[SCENE]: User Client Verification for Joe Bloggs in my-region returned false".  The sending region will log the message "Failed to verify user presence in the grid for Joe Bloggs, access denied to region myregion."
 * 15) Destination region receives incoming attachments for foreign agent.