OpenSimulator Internals/Connector Architecture/UserAgent Connector

Overview

UserAgentServiceConnector is the remote connector for IUserAgentService. It is used by foreign grids to talk to a home grid's UserAgentService -- verifying agents, getting home region info, and checking online friends. It extends SimulationServiceConnector, inheriting the agent transfer path and overriding the agent URL path.

Source file:

OpenSim/Services/Connectors/Hypergrid/UserAgentServiceConnector.cs

Inheritance

Extends SimulationServiceConnector. Overrides:

AgentPath() -- returns "homeagent/" instead of "agent/"
PackData() -- adds gatekeeper_serveruri, gatekeeper_host, gatekeeper_port, destination_serveruri to the OSD payload

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

Initialisation

Two constructors:

String URL -- validates URI, normalizes to lowercase with trailing slash
IConfigSource -- reads HomeURL from GridInfo; throws if missing or invalid

No config section key -- the URL is taken from GridInfo.HomeURL, which reads from [Const], [Startup], or [Hypergrid] sections.

Transport -- Two Protocols

This connector uses two different transports depending on the method:

Agent transfer (inherited from SimulationServiceConnector):

LoginAgentToGrid() calls CreateAgent() -- uses WebUtil OSD/LLSD over HTTP POST/PUT to "homeagent/" path

All other methods:

Use XML-RPC via Nwc.XmlRpc over HTTP POST to m_ServerURL
CallServer() is the shared helper for XML-RPC calls that return a Hashtable
GetBoolResponse() is the shared helper for XML-RPC calls that return a bool via a "result" key

LoginAgentToGrid()

Two overloads:

public bool LoginAgentToGrid(GridRegion source, AgentCircuitData aCircuit, GridRegion gatekeeper,
    GridRegion destination, bool fromLogin, out string reason)

Constructs a synthetic home GridRegion using m_ServerURL as ServerURI, then calls the parent CreateAgent(). Teleport flag is ViaLogin if fromLogin, ViaHome otherwise. Stores gatekeeper in m_Gatekeeper for use by PackData().

public bool LoginAgentToGrid(GridRegion source, AgentCircuitData aCircuit, GridRegion gatekeeper,
    GridRegion destination, out string reason)

Always passes fromLogin = false. Used by simulators.

XML-RPC Methods

Method	XmlRpc method	Returns	Notes
GetHomeRegion(userID, out position, out lookAt)	"get_home_region"	GridRegion	Parses full GridRegion from Hashtable; returns null on failure
IsAgentComingHome(sessionID, thisGridExternalName)	"agent_is_coming_home"	bool	Via GetBoolResponse()
VerifyAgent(sessionID, token)	"verify_agent"	bool	Via GetBoolResponse()
VerifyClient(sessionID, token)	"verify_client"	bool	Via GetBoolResponse()
LogoutAgent(userID, sessionID)	"logout_agent"	void	Calls GetBoolResponse() but discards result
GetUserInfo(userID)	"get_user_info"	Dictionary<string,object>	All non-null Hashtable entries returned
GetServerURLs(userID)	"get_server_urls"	Dictionary<string,object>	Only SRV_-prefixed keys returned; "SRV_" prefix stripped
LocateUser(userID)	"locate_user"	string	Returns hash["URL"] or empty string
GetUUI(userID, targetUserID)	"get_uui"	string	Returns hash["UUI"] or empty string
GetUUID(first, last)	"get_uuid"	UUID	Throws on missing or unparseable UUID response
StatusNotification(friends, userID, online)	"status_notification"	List<UUID>	[Obsolete]; friends sent as friend_0, friend_1...; returns online UUIDs
GetOnlineFriends(userID, friends)	"get_online_friends"	List<UUID>	[Obsolete]; same encoding as StatusNotification

GetHomeRegion() field parsing: uuid, x, y, size_x, size_y, region_name, hostname, http_port, server_uri, internal_port, position, lookAt. All fields checked for null before parsing. Missing fields silently use zero/default values.

GetServerURLs() strips the "SRV_" prefix from keys, returning just the service type name.

GetUUID() throws on failure -- the only method in this connector that throws instead of returning a sentinel value.

SetClientToken()

No-op. Accepted but does nothing.

Notes

This connector uses XML-RPC for most operations and OSD/REST for agent transfer -- two different protocols in the same class.
StatusNotification() and GetOnlineFriends() are both marked [Obsolete]. Exception catch blocks in both methods silently swallow all exceptions with no logging.
LogoutAgent() discards the bool result from GetBoolResponse() -- callers cannot detect failure.
GetUUID() is the only method that throws on error rather than returning null/empty/false.
The error message in GetBoolResponse() for "THIS IS BAAAAD" is verbatim from the source.