The Hypergrid Reference Guide

Overview

Typical Interactions

Helo Service

Gatekeeper Service

Instant Message Service

Main Types and Data Structures

PLEASE NOTE: this is a work in progress. Some of the elements described here may still change as other people implement this independently, and as we strengthen the security of the Hypergrid.

Last update: Dec. 7, 2011

Overview

The Hypergrid is a federation architecture and protocol for Second Life and OpenSimulator virtual worlds that supports the seamless transfer of user agents and assets between them. This Reference Guide explains the Hypergrid for implementers.

One core design principle of the Hypergrid is that it is entirely a server-side-to-server-side federation. Clients are assumed to be relatively passive elements that interact only with the server side authority that the user is currently visiting. All interactions between a client and another virtual world are proxied by the virtual world that the client is currently connected to. This is opposed to other architectures where clients play a more active role in maintaining connections to several server-sides. This design decision comes as a pragmatic necessity given the clients that the Hypergrid is designed for - the Linden Lab Second life viewers and Web browsers.

Hypergrid Services:

Helo Service

Gatekeeper Service

User Agents Service

Inventory Service

Asset Service

Friends Service

Instant Message Service

HGComponents

The Hypergrid consists of a number of services that can be added to a virtual world, each one establishing a federation for that particular kind of service. In the Hypergrid, interoperation between virtual worlds is triggered by the use of Universal Unique Identifiers which include a domain of origin. These UUIs are given to the virtual worlds either explicitly by direct input from users or implicitly as user agents move from one virtual world to another. User agents carry with them "bags of references" to entities that may be outside the virtual world that they are currently visiting.

Typical Interactions

(click to enlarge)

Hypergrid Teleport:

Hypergrid Friends:

Hypergrid IM:

Helo Service

Purpose: this is a protocol discovery service. In principle, this is the only service whose network API must be agreed upon throughout the Hypergrid; all other services' network APIs can, in principle, be different for the same types of services. This gives a lot of flexibility to each virtual world implementer and the Federation itself, as there is no need to establish network-level standards, only abstract service interface standards. Authorities invoke this service upon needing to interact with a new authority for the first time in order to discover the mechanism by which the interaction can take place. The Helo service plays a similar role to that of Web Services Description Languages (WSDL), but it is a much more concise, and consequently less flexible, mechanism than WSDL.

Relevant OpenSimulator Elements

Reference Network API: HeloServiceConnector (requester), HeloServiceInConnector (provider)

Detailed Description

Helo

Discovers the Hypergrid network protocol used by a virtual world

Operation:

Protocol	HTTP
URI	/helo
Method	GET (see NOTE below)

Request Elements:

None

Response Elements:

None

Response Headers:

X-Handlers-Provided

identifier of a protocol

Required

Example request:

GET /helo

Host: vw-example.com

Example response:

HTTP/1.1 200 OK

X-Handlers-Provided: opensim-robust

Content-Length: 0

NOTE: The method should be HEAD, not GET. As of 12/2011, the Robust infrastructure in OpenSimulator already serves HEAD, but the sims are still calling GET - to be changed in a couple of releases.

Gatekeeper Service

Purpose: this service is the single entry point of hyperlinks and user agents into a grid. It can be thought of as a grid-login service. When grids run the Hypergrid, all hyperlink requests as well as all user agents launched at the grid's regions MUST go through the Gatekeeper first. Specifically, for users coming from foreign worlds, the gatekeeper is the service that posts the user's session into the local presence service -- a piece of data that is then verified by the simulators, and without which the simulators refuse service. With the Gatekeeper service in place, virtual worlds have one single point of control for user agents entry; policies for access control based on a variety of criteria become possible.

Relevant OpenSimulator Elements

Interface: IGatekeeperService

Reference Service Implementation: GatekeeperService

Reference Network API: GatekeeperServiceConnector (requester), HypergridHandlers (provider), GatekeeperAgentHandler (provider)

Detailed Description

LinkRegion

Returns information about a region on the grid given the region's name.

Operation:

Protocol	XMLRPC
Method	link_region

Request Elements:

region_name

a region name

Type: String

Response Elements:

result	indicates success or failure to link Type: Stringified Boolean Required
uuid	UUID of the region Type: Stringified UUID
handle	64-bit handle of the region Type: Stringified 64 bit number
region_image	URI of the map tile Type: URI
external_name	the target grid's published name for the region Type: String

GetHyperlinkRegion

Returns the complete information about a region on the grid.

Operation:

Protocol	XMLRPC
Method	get_region

Request Elements:

region_uuid

a region UUID

Type: Stringified UUID

Response Elements:

result	indicates success or failure of the operation Type: Stringified Boolean Required
uuid	UUID of the region Type: Stringified UUID
x	32-bit integer of X coordinate in target grid Type: Stringified 32-bit integer
y	32-bit integer of Y coordinate in target grid Type: Stringified 32-bit integer
region_name	the target grid's published name for the region Type: String
hostname	the external hostname of the simulator where the region runs Type: String
http_port	the external http port of the simulator where the region runs Type: Stringified integer
internal_port	the internal port of the simulator where the region runs Type: Stringified integer
server_uri	the URI of the simulator where the region runs Type: String

CreateAgent /

LoginAgent

Creates a user agent on this grid. Main entry point for incoming Hypergrid teleports.

Operation:

Protocol	HTTP
Method	POST
URI	/foreignagent/<Agent_UUID>/

Request Elements:

Content-Type	application/x-gzip or application/json
Body	Data representing the agent and the destination region. Can be plain or gzipped. See CreateForeignAgentRequestData.

Response Elements:

Content-Type

application/json

Response

A JSON object containing the following fields:

success: Boolean representing success/failure of creating the agent

reason: in case of failure, the reason why it failed

your_ip: a string representing the caller's IP as seen by this Gatekeeper

Example request:

POST /foreignagent/5745cd8c-33df-403f-8d3d-da489ea1022b

Host: vw-example.com

Content-Type: application/x-gzip

Content-Length: 203

<data: see CreateForeignAgentRequestData>

Example response:

HTTP/1.1 200 OK

Content-Length: 42

Content-Type: application/json

{"success":true,"your_ip":"75.32.137.188"}

User Agent Service

Purpose: this service controls the launching of user agents into grids, working closely with an identification service bundle (UserAccounts and Authentication). When enabled, all user agent transfers among independent, possibly untrusted, domains MUST be realized by the user's User Agents service. Its main goal is to provide a means for grids to verify identity of user agents launched at them from other grids. In its current incarnation, the most important information it keeps in order to verify identity is the user's IP address.

Relevant OpenSimulator Elements

Interface: IUserAgentService

Reference Service Implementation: UserAgentService

Reference Network API: UserAgentServiceConnector (requester), UserAgentServerConnector (provider), HomeAgentHandler (provider)

Detailed Description

CreateAgent /

LoginAgentToGrid

Creates a user agent on some grid on behalf of the caller.

Operation:

Protocol	HTTP
Method	POST
URI	/homeagent/<Agent_UUID>/

Request Elements:

Content-Type	application/json
Body	Data representing the agent and the destination region. See CreateHomeAgentRequestData.

Response Elements:

Content-Type

application/json

Response

A JSON object containing the following fields:

success: Boolean representing success/failure of creating the agent

reason: in case of failure, the reason why it failed

Example request:

POST /homeagent/5745cd8c-33df-403f-8d3d-da489ea1022b

Host: vw-example.com

Content-Type: application/json

Content-Length: 203

<data: see CreateHomeAgentRequestData>

Example response:

HTTP/1.1 200 OK

Content-Length: 42

Content-Type: application/json

{"reason":"","success":true}

GetHomeRegion

Returns the home region and home state of a user.

Operation:

Protocol	XMLRPC
Method	get_home_region

Request Elements:

userID

a user UUID

Type: Stringified UUID

Response Elements:

result	indicates success or failure of the operation Type: Stringified Boolean Required
uuid	UUID of the region Type: Stringified UUID
x	32-bit integer of X coordinate in target grid Type: Stringified 32-bit integer
y	32-bit integer of Y coordinate in target grid Type: Stringified 32-bit integer
region_name	the target grid's published name for the region Type: String
hostname	the external hostname of the simulator where the region runs Type: String
http_port	the external http port of the simulator where the region runs Type: Stringified integer
internal_port	the internal port of the simulator where the region runs Type: Stringified integer
position	the position of the user in the home region Type: Stringified Vector3
lookAt	the rotation of the user in the home region Type: Stringified Vector3

VerifyAgent

Verifies the validity of an agent's session credentials. This operation is intended to be invoked by Gatekeepers that receive a CreateAgent/LoginAgent request and wish to verify that the agent that they are receiving was, indeed, created by this User Agent Service. This prevents against false agents (impersonations) launched at Gatekeepers.

Operation:

Protocol	XMLRPC
Method	verify_agent

Request Elements:

sessionID

a session UUID

Type: Stringified UUID

token

service key

Type: String (service key)

Response Elements:

result

indicates success or failure of the operation

Type: Stringified Boolean

Required

VerifyClient

Verifies the identity of the user. Currently this is done by verifying the user's client IP address. This operation is intended to be invoked by simulators upon first TCP-based contact from the clients, and asserts that the client that they are interacting with on behalf of a user is, indeed, the original client with which the user logged in.

This prevents against rogue clients (impersonations) launched at simulators.

Operation:

Protocol	XMLRPC
Method	verify_client

Request Elements:

sessionID

a session UUID

Type: Stringified UUID

token

currently an IP address

Type: String

Response Elements:

result

indicates success or failure of the operation

Type: Stringified Boolean

Required

LogoutAgent

Logs out a session of a user.

Operation:

Protocol	XMLRPC
Method	logout_agent

Request Elements:

sessionID

a session UUID

Type: Stringified UUID

userID

a user UUID

Type: Stringified UUID

Response Elements:

result

indicates success or failure of the operation

Type: Stringified Boolean

Required

StatusNotification

Sends Online/Offline status notifications from a foreign user to that user's friends who are within the domain of this User Agent Service; if this is an online notification, the method returns the list of friends within this domain who are online. For example: alice@A logs in, and her friends Bob@B and Carol@B are notified of that through this method in User Agents Service @B; in the case that only Bob@B is online, the return of this method is the UUID of Bob.

Operation:

Protocol	XMLRPC
Method	status_notification

Request Elements:

userID

a user UUID

Type: Stringified UUID

online

the status (online/offline = true/false)

Type: Stringified Boolean

friend_<n> (1 or more)

the friend UUI

Type: Stringified UUI

Response Elements:

result

if no friends are online, or nothing to report, only this element is returned. The value can be anything.

Type: String

friend_<n> (1 or more)

the online friend UUID

Type: Stringified UUID

GetServerURLs

Returns all the URLs of services associated with a user within this domain.

Operation:

Protocol	XMLRPC
Method	get_server_urls

Request Elements:

userID

a user UUID

Type: Stringified UUID

Response Elements:

SRV_<serviceName> (0 or more)

the URL of the service

Type: String

GetUUI

Returns the UUI of a friend of a user within this domain given the friend's UUID. This is intended to be called by simulators the user is visiting them and presents a friend's UUID that they can't resolve. So they try to look it up in the user's friends list of this domain.

Operation:

Protocol	XMLRPC
Method	get_uui

Request Elements:

userID

a user UUID

Type: Stringified UUID

targetUserID

the potential friend UUID

Type: Stringified UUID

Response Elements:

UUI	the UUI or empty Type: Stringified UUI

Inventory Service

Purpose: this service controls the access to a user's inventory from another virtual world. Its main goal is to give minimum access to inventory items while protecting the user's inventory from abusive behavior on the part of untrusted authorities.

Relevant OpenSimulator Elements

Interface: IInventoryService

Reference Service Implementation: HGInventoryService

Reference Network API: XInventoryConnector, XInventoryInConnector

Detailed Description

GetRootFolder

Returns the special Suitcase folder for the given user, not the actual Root folder. This is so that the user's inventory does not get unnecessarily exposed.

Operation:

Protocol	HTTP
Method	POST
URI	/xinventory

Request Elements:

Content-Type	application/x-www-form-urlencoded
METHOD	GETROOTFOLDER
PRINCIPAL	The user UUID

Response Elements:

Content-Type	text/xml
Response	A XML encoding of a folder

GetFolderForType

Always returns the special Suitcase folder for the given user, and not any other folders.

GetInventorySkeleton

Always a no-op returning an empty inventory skeleton.

DeleteFolders

Always a no-op returning false.

PurgeFolder

Always a no-op returning false.

GetItem

Returns the complete information about an inventory item given its UUID, as normal. Further filtering and content transformations may be performed.

All other inventory operations are served as normal, as they include folder and item UUIDs provided by the user. However, this is not mandatory. More restrictive Hypergrid inventory services may chose not to serve additional inventory operations.

Asset Service

Purpose: this service provides access to an asset storage. Its main goal is to serve get/post asset requests while protecting the integrity of the assets from abusive behavior on the part of untrusted authorities. Hypergrid asset services may perform content-type-based access control and content transformation on the assets. This specification does not mandate any particular access control or content transformation. The reference Hypergrid asset service in OpenSimulator transforms all user UUIDs into UUIs, as assets are sent outside the virtual worlds.

Relevant OpenSimulator Elements

Interface: IAssetService

Reference Service Implementation: HGAssetService

Reference Network API: HGAssetServiceConnector (requester), AssetServerConnector (provider), AssetServerGetHandler (provider), AssetServerPostHandler (provider), AssetServerDeleteHandler (provider)

Detailed Description

Get

Returns an asset given a UUID.

Operation:

Protocol	HTTP
Method	GET
URI	/assets/<UUID>

Request Elements:

None

Response Elements:

Content-Type	text/xml
Response	A XML encoding of an asset

Store

Stores a given asset.

Operation:

Protocol	HTTP
Method	POST
URI	/assets

Request Elements:

Content-Type	text/xml
Body	A XML encoding of an asset

Response Elements:

Content-Type	text/xml
Response	A XML encoding of a UUID

Delete

This method is highly discouraged for Hypergrid asset services.

GetMetadata

Returns an asset metadata given a UUID.

Operation:

Protocol	HTTP
Method	GET
URI	/assets/<UUID>/metadata

Request Elements:

None

Response Elements:

Content-Type	text/xml
Response	A XML encoding of an asset's metadata

GetData

Returns an asset data given a UUID.

Operation:

Protocol	HTTP
Method	GET
URI	/assets/<UUID>/data

Request Elements:

None

Response Elements:

Content-Type	application/octet-stream
Response	The asset's data

Friends Service

Purpose: this service provides the means for establishing and deleting friendships between users in different domains.

Relevant OpenSimulator Elements

Reference Network API: HGFriendsServiceConnector (requester), HGFriendsServerConnector (provider), HGFriendsServerPostHandler (provider)

Detailed Description

NewFriendship

Establishes a new friendship for a user in this domain. The service SHOULD verify with the User Agent Service that the service key is valid for user; if it's valid it means that the user is, indeed, visiting the virtual world that is issuing the request.

Operation:

Protocol	HTTP
Method	POST
URI	/hgfriends

Request Elements:

Content-Type	application/x-www-form-urlencoded
METHOD	newfriendship
PrincipalID	The user's ID Type: Stringified UUID
Friend	The friend's UUI Type: UUI
KEY	service key, as carried by the user agent Type: service key
SESSIONID	a user's session UUID Type: Stringified UUID

Response Elements:

Content-Type	text/xml
Response	A XML encoding of the result

Example request data:

PrincipalID=5745cd8c-33df-403f-8d3d-da489ea1022b&Friend=66a12589-860f-4e34-

ac1b-0921cc5407a9%3bhttp%3a%2f%2fucigrid01.nacs.uci.edu%3a9001%2f%3b

Test+User%3ba41abc7e&METHOD=newfriendship&KEY=http%3a%2f%2f

ucigrid01.nacs.uci.edu%3a9001%2f%3bde91c218-1a10-48f3-8bcf-

72806d486f93&SESSIONID=87d62ddd-1f34-481c-beae-a63f0add59df

Example response:

<ServerResponse><Result>Success</Result></ServerResponse>

DeleteFriendship

Deletes a friendship for a user in this domain. The service SHOULD verify in its own data that the secret is valid, meaning that the requester had access to the original friendship data. The only authorities that know the secret are the domain of the friend and the virtual world where the friendship was established.

Operation:

Protocol	HTTP
Method	POST
URI	/hgfriends

Request Elements:

Content-Type	application/x-www-form-urlencoded
METHOD	deletefriendship
PrincipalID	The user's ID Type: Stringified UUID
Friend	The friend's UUID Type: Stringified UUID
SECRET	the secret stamp associated with a friendship -- authorization token Type: String

Response Elements:

Content-Type	text/xml
Response	A XML encoding of the result

Instant Message Service

Purpose: this service provides IM peering.

Relevant OpenSimulator Elements

Reference Service Implementation: HGInstantMessageService

Reference Network API: InstantMessageServiceConnector (requester), InstantMessageServerConnector (provider)

Detailed Description

SendInstantMessage

Receives an IM from some other grid and forwards it to a user that is either (a) foreigner, visiting this grid or (b) a user in this user agents' domain that is either in the grid or elsewhere. The implementation of this service is a bit complex, because it needs to locate users and it needs to cache those locations for faster service. Then it needs to update the cache when IM deliveries fail due to users having moved elsewhere.

Note to implementers: please look carefully at the reference implementation of this service in HGInstantMessageService.

Operation:

Protocol	XMLRPC
Method	grid_instant_message

Request Elements:

from_agent_id	UUID of the sender agent Type: Stringified UUID
from_agent_session	UUID of the sender's session Type: Stringified UUID
from_agent_name	name of the sender Type: String
to_agent_id	UUID of the receiver agent Type: Stringified UUID
im_session_id	UUID of the IM session Type: Stringified UUID
timestamp	Type: unsigned integer
message	The message itself Type: String
dialog	Dialog type Type: Stringified 64-bit-base byte (!)
from_group	is it a group IM? Type: Stringified Boolean
offline	Unclear what this is for Type: Stringified 64-bit number
parent_estate_id	Unclear what this is for Type: Stringified unsigned integer
position_x	Type: Strinfigied 32-bit float
position_y	Type: Strinfigied 32-bit float
position_z	Type: Strinfigied 32-bit float
region_id	Type: Stringified Guid
binary_bucket	Unclear what this is for Type: Stringified 64-bit number

Response Elements:

success

indicates success or failure of the operation

Type: Stringified Boolean

Required

Main Types and Data Structures

Here are some examples of the main identifiers and data structures exchanged during Hypergrid interactions. NOTE: the '.' in the beginning of each line denote indentation.

Service Key

Purpose: generated by User Agent Service for every grid that the user interacts with.

Syntactic Form: <TargetGatekeeperURI>;<random token>

Example: http://divacanto.dyndns.org:9000/;c87d7e92-55d2-4360-9bfd-c955dac4fb8b

Universal User Identifier (UUI)

Purpose: identifies a user in the entire federation. Used, for example, to represent foreign friends.

Syntactic form: <UUID>[;HomeURI[;name[;secret]]]

Example: 76ee17d4-1d71-490f-95dc-5594eaf42863;http://ucigrid03.nacs.uci.edu:9000;Test User;5bb79d57

CreateForeignAgentRequestData

{"agent_id":"5745cd8c-33df-403f-8d3d-da489ea1022b",

."destination_x":"256000",

."destination_y":"256000",

."destination_name":"Kali Test 9",

."destination_uuid":"4468513f-d06a-4df6-b91c-252f5a8f4489",

."teleport_flags":"128"

."base_folder":"00000000-0000-0000-0000-000000000000",

."caps_path":"f9063cbd-d46c-46bb-86b0-21695c4086cf",

."child":false,

."circuit_code":"30135740",

."first_name":"Test",

. "last_name":"User",

."inventory_folder":"00000000-0000-0000-0000-000000000000",

."secure_session_id":"e4e1d7b1-1ba1-48a5-b9dd-5f5572e6ec16",

."session_id":"b98a6f87-25b5-4fe7-b72f-ab6ffe44a8e5",

."service_session_id":"http://divacanto.dyndns.org:9000/;3a215745-7791-4248-a267-a621d96f78d1",

."start_pos":"<128.116, 128.5049, 22.5>",

."client_ip":"192.168.1.64",

."viewer":"Second Life Release 1.23.5.136262",

."channel":"Second Life Release",

."mac":"b3030425213724e88f6bdc231caa337d",

."id0":"587eb48351713620ff2d9ec06b32f116",

."appearance_serial":1,

."packed_appearance":{

..."serial":1,

..."height":1.69099903106689,

..."wearables":[

.....[{"item":"6d813df9-530f-42ad-b908-9e6d1b4fbe6a","asset":"d1cee383-90d5-85be-515c-b52e89043002"}],

.....[{"item":"f2333861-d598-4244-9d91-4ef03e943c3e","asset":"b6739e6c-4969-4696-8085-3e20f97a6689"}],

.....[{"item":"44d4e931-0faa-4a4a-be6f-5421225873c5","asset":"e024c8bf-21c4-4c63-b767-089b75ae8720"}],

.....[{"item":"7a6d71e1-9a48-414d-8694-d961a29556a1","asset":"c985e848-4ad3-4f16-cac2-94123729c8e1"}],

.....[{"item":"02f80857-3791-40c8-8d46-8370492c9e82","asset":"269b94c8-8f02-5edb-84e8-42000d6c3f5b"}],

.....[{"item":"8edb92c8-9ca3-4a11-bdf9-7bba43dbd24a","asset":"1d6d2c60-20ac-80ed-f799-56f395371d74"}],

.....[{"item":"58fb1276-3065-48e6-bf39-c79115a3b00d","asset":"f4fd2015-5463-e53a-1f76-4e5eea576a87"}],

.....[],

.....[{"item":"55f43dd7-5343-4d1c-97fe-f53bfd57cd9a","asset":"4351e4cc-b9a8-4c1c-9320-801dc4ea1de8"}],

.....[],[],[],[],[],[]],

..."textures":["c228d1cf-4b5d-4ba8-84f4-899a0796aa97","c228d1cf-4b5d-4ba8-84f4-899a0796aa97",

....."c228d1cf-4b5d-4ba8-84f4-899a0796aa97","c228d1cf-4b5d-4ba8-84f4-899a0796aa97",

....."c228d1cf-4b5d-4ba8-84f4-899a0796aa97"],

..."visualparams":[33,61,85,...],

..."attachments":[{"point":2,

....."item":"e26286b7-08f1-4d12-9d7d-8b945b72700d","asset":"00000000-0000-0000-0000-000000000000"}]

.},

."serviceurls":{"HomeURI":"http://divacanto.dyndns.org:9000/",

..."GatekeeperURI":" http://divacanto.dyndns.org:9000/",

..."InventoryServerURI":"http://divacanto.dyndns.org:9000/",

..."AssetServerURI":"http://divacanto.dyndns.org:9000/",

..."FriendsServerURI":"http://divacanto.dyndns.org:9000/",

..."ProfileServerURI":"http://divacanto.dyndns.org:9000/profiles/", ..."IMServerURI":"http://divacanto.dyndns.org:9000/"}

}

CreateHomeAgentRequestData

{"agent_id":"5745cd8c-33df-403f-8d3d-da489ea1022b", ."gatekeeper_serveruri":"http://ucigrid01.nacs.uci.edu:9001/",

."gatekeeper_host":"ucigrid01.nacs.uci.edu",

."gatekeeper_port":"9001",

."destination_x":"275456",

."destination_y":"275456",

."destination_name":"Diva's Office 1",

."destination_uuid":"5e6d615b-c7b0-40b4-9868-87924d533d62",

."destination_serveruri":"http://ucigrid01.nacs.uci.edu:9001/",

."base_folder":"00000000-0000-0000-0000-000000000000",

...rest is the same as in CreateForeignAgentData...

}

The Hypergrid Reference Guide

Table of Contents

Relevant OpenSimulator Elements

Detailed Description

Relevant OpenSimulator Elements

Detailed Description

Relevant OpenSimulator Elements

Detailed Description

Relevant OpenSimulator Elements

Detailed Description

Relevant OpenSimulator Elements

Detailed Description

Relevant OpenSimulator Elements

Detailed Description

Relevant OpenSimulator Elements

Detailed Description