OpenSimulator Internals/Connector Architecture

Overview

Connectors are the HTTP client layer that sits between region simulators and ROBUST grid services. Each connector implements a service interface (e.g. IAssetService, IPresenceService) using HTTP calls to the corresponding ROBUST handler.

The same interface may be implemented by:

A local connector -- calls the service directly in-process (standalone mode or co-located services).
A remote connector -- makes HTTP calls to a ROBUST server.
An HG connector -- wraps the remote connector with hypergrid-specific logic.

Region code calls only the interface. Which implementation is loaded depends on configuration ([Architecture] section of the ini files).

Because every ROBUST service is stateless, each can be independently load-balanced or replicated without coordination between instances.

See OpenSimulator Internals/ROBUST Services for the server-side service implementations.

Connector Pattern

All remote connectors follow the same pattern:

Constructor receives IConfigSource and reads the service URL from config.
Each method serialises parameters to a REST or XMLRPC request.
Sends HTTP POST/GET/DELETE to the ROBUST handler endpoint.
Deserialises the response and returns the result.

The HTTP client layer is WebUtil (OpenSim/Framework/WebUtil.cs), which handles serialisation, connection pooling, and error logging.

See OpenSimulator Internals/Connector Architecture/Asset Connector for a fully worked example of the pattern including both client and server-side handler code.

Individual Connector Pages

Connector	Service Interface	Notes
OpenSimulator Internals/Connector Architecture/Asset Connector	IAssetService	As of 0.9.2, the three region-side asset modules (LocalAssetServiceConnector, RemoteAssetServiceConnector, HGAssetBroker) were replaced by a single RegionAssetConnector. LocalAssetServiceConnector is retained for test use only. HGAssetBroker and RemoteAssetServiceConnector are no longer used in production. RegionAssetConnector behaviour is controlled by [AssetService] keys LocalGridAssetService and HypergridAssetService. See individual page for full detail including server-side handler code.
OpenSimulator Internals/Connector Architecture/GridUser Connector	IGridUserService	Tracks last position, login/logout timestamps, home region. Online status in GridUser is less accurate than in Presence, which is updated more frequently.
OpenSimulator Internals/Connector Architecture/Presence Connector	IPresenceService	Online status, session tracking, region assignment.
OpenSimulator Internals/Connector Architecture/UserAccount Connector	IUserAccountService	User account CRUD. Known bug: CreateUser() sends first name as email value.
OpenSimulator Internals/Connector Architecture/Inventory Connector	IInventoryService	XInventory protocol. UpdateFolder() URL-encodes Name; AddFolder() does not.
HGInventoryService	IInventoryService	HG-only. Pre-suitcase implementation. Returns "My Suitcase" folder as root by name lookup. Does not enforce suitcase tree boundaries on operations. Adjusts CreatorData on item fetch to include home grid URL. Deletions and skeleton requests blocked. Present in current code but not recommended for new deployments.
HGSuitcaseInventoryService	IInventoryService	HG-only. Current implementation. Enforces strict suitcase tree boundaries on all folder and item operations. Creates system subfolders under suitcase on first use. Allows access to appearance items outside the suitcase tree. Caches suitcase tree and appearance data (5-minute expiry). Requires AvatarService in config in addition to UserAccountsService. Deletions blocked.
OpenSimulator Internals/Connector Architecture/Authentication Connector	IAuthenticationService	Password and token authentication, impersonation mechanism.
OpenSimulator Internals/Connector Architecture/Avatar Connector	IAvatarService	Appearance storage. ResetAvatar() log erroneously says "SetItems reply".
OpenSimulator Internals/Connector Architecture/Friends Connector	IFriendsService	Friend list, online notifications.
OpenSimulator Internals/Connector Architecture/Grid Connector	IGridService	Region registration, lookup, neighbour queries.
OpenSimulator Internals/Connector Architecture/Simulation Connector	ISimulationService	Inter-simulator agent and object transfer. QueryAccess, CreateAgent, UpdateAgent, CloseAgent, CreateObject.
OpenSimulator Internals/Connector Architecture/UserAgent Connector	IUserAgentService	HG-only. Home region lookup, login to foreign grid, session verification.
OpenSimulator Internals/Connector Architecture/Gatekeeper Connector	IGatekeeperService	HG-only. Foreign grid entry point. GetHyperlinkRegion, LoginAgentToGrid.

HG Connectors

HyperGrid introduces additional connectors that wrap or replace the standard ones:

UserAgent Connector -- used by the source grid to contact the avatar's home grid UserAgent service during HG teleport.
Gatekeeper Connector -- used to contact a foreign grid's Gatekeeper during HG destination resolution.
HGAsset Connector -- used by HGInventoryAccessModule to fetch/push assets between grids (via HGAssetMapper).
HGInventoryService / HGSuitcaseInventoryService -- inventory access for visiting HG users. HGSuitcaseInventoryService is current; HGInventoryService is the pre-suitcase predecessor. Both block deletions.

Note: prior to 0.9.2, the HGAssetBroker region module handled the local/remote/foreign asset routing decision. It was retired in 0.9.2 and replaced by RegionAssetConnector. References to HGAssetBroker in older documentation and config examples are obsolete.

These are documented in the individual connector pages above and in:

Configuration

Connectors are selected in the [Architecture] ini include files:

config-include/StandaloneCommon.ini -- standalone mode, services loaded in-process.
config-include/GridCommon.ini -- grid mode, remote connectors used.
config-include/HGCommon.ini -- hypergrid additions.

The [ServiceList] section of Robust.ini selects which ROBUST handlers are loaded. The [Modules] section of OpenSim.ini selects which connectors the simulator loads.