OpenSimulator Internals/Connector Architecture/Gatekeeper Connector

Overview

GatekeeperServiceConnector is the client-side connector used to talk to a foreign grid's GatekeeperService. It handles HG region linking, map tile retrieval, and region lookup. It extends SimulationServiceConnector, inheriting the agent and object transfer paths with overridden URL prefixes.

Source file:

OpenSim/Services/Connectors/Hypergrid/GatekeeperServiceConnector.cs

Inheritance

Extends SimulationServiceConnector. Overrides:

AgentPath() -- returns "foreignagent/" instead of "agent/"
ObjectPath() -- returns "foreignobject/" instead of "object/"

This means CreateAgent() from the parent sends to destination.ServerURI + "foreignagent/" + agentID + "/" when called through this connector.

Initialisation

Two constructors:

Default (no args) -- no asset service; GetMapImage() will return the default HG map tile UUID
IAssetService argument -- asset service used by GetMapImage() to store downloaded map tiles

No config file reading. The destination URI comes from GridRegion.ServerURI per call.

Transport

All non-inherited methods use XML-RPC via Nwc.XmlRpc over HTTP POST to the gatekeeper's ServerURI. 10-second timeout on all XML-RPC calls.

Agent and object transfer methods are inherited from SimulationServiceConnector and use WebUtil OSD/REST.

LinkRegion()

public bool LinkRegion(GridRegion info, out UUID regionID, out ulong realHandle,
    out string externalName, out string imageURL, out string reason, out int sizeX, out int sizeY)

XML-RPC method: "link_region"

Sends: region_name

On success parses: uuid, handle (as ulong), region_image, external_name, size_x, size_y. All fields checked for null before parsing. Default sizeX/sizeY is Constants.RegionSize if not provided.

Returns false on connection error, XML-RPC fault, or parse exception.

GetMapImage()

public UUID GetMapImage(UUID regionID, string imageURL, string storagePath)

Downloads and stores a foreign region's map tile as an asset.

Sequence:

If no AssetService: returns m_HGMapImage (00000000-0000-1111-9999-000000000013) immediately
Builds filename: storagePath + regionID + ".jpg"
If file not on disk: downloads from imageURL via WebClient.DownloadFile()
Opens as Bitmap, encodes to JPEG2000 via OpenJPEG.EncodeFromImage()
Stores as AssetType.Texture with random UUID, name "region {regionID}", creator = regionID
Returns the stored asset UUID

Exception handling: entire sequence wrapped in bare catch -- logs "probably already in the cache" and returns m_HGMapImage. This catches OpenJPEG p/invoke failures specifically (comment says "LEGIT").

m_HGMapImage (00000000-0000-1111-9999-000000000013) is the fallback UUID returned on any failure.

GetHyperlinkRegion()

public GridRegion GetHyperlinkRegion(GridRegion gatekeeper, UUID regionID, UUID agentID,
    string agentHomeURI, out string message)

XML-RPC method: "get_region"

Sends: region_uuid; optionally agent_id and agent_home_uri if agentID is non-zero.

On success parses full GridRegion: uuid, x, y, size_x, size_y, region_name, hostname, http_port, internal_port, server_uri. All fields null-checked before parsing.

message handling:

If hash["message"] present: use it
If success and no message: set message = null
If failure and no message: set message = "The teleport destination could not be found." (comment notes this is for old grids that don't send message)

Returns null on connection error, XML-RPC fault, parse exception, or result == false.

Notes

GetMapImage() uses the deprecated WebClient class for download. The comment "LEGIT" on the bare catch is the only documentation for why all exceptions are swallowed there.
The fallback map tile UUID (00000000-0000-1111-9999-000000000013) is a static field -- the same UUID is returned for all failed map tile fetches regardless of region.
Agent transfer uses "foreignagent/" path rather than "agent/" -- this is what distinguishes inbound HG agent traffic from local teleport traffic on the receiving simulator.