Latest revision as of 07:14, 9 July 2026

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.

@@ Line 1: / Line 1: @@
 = OpenSimulator Internals/Connector Architecture =
 == Overview ==
-The connector handles network calls transparently. Calling code does not need to know whether the service is local (standalone) or remote (grid mode) -- the connector abstracts that distinction.
+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).
-In standalone mode the connector calls the service directly in-process. In grid mode it makes an HTTP call to ROBUST. Same interface either way.
+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.
 ----
-== The Five Components ==
+== 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.
+----
-Up to five components are involved in connecting simulator code to a grid service.
+== Individual Connector Pages ==
 {| class="wikitable"
-! Component !! Location !! Description
+! Connector !! Service Interface !! Notes
 |-
-| Simulator code || OpenSimulator core or a module || Makes the initial service call to get or set data.
+| [[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.
 |-
-| Simulator service connector || OpenSim/Region/CoreModules/ServiceConnectorsOut (outbound), ServiceConnectorsIn (inbound) || Two flavours: local (same process, standalone -- calls service directly) and remote (grid mode -- delegates to remote service connector for network call).
+| [[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.
 |-
-| Remote service connector || OpenSim/Services/Connectors || Marshals data and makes the network call to the remote service. Not used for in-process connections.
+| [[OpenSimulator Internals/Connector Architecture/Presence Connector]] || IPresenceService || Online status, session tracking, region assignment.
 |-
-| Remote service handler || OpenSim/Server/Handlers || Unpacks the incoming network call and passes it to the service. Not used for in-process connections.
+| [[OpenSimulator Internals/Connector Architecture/UserAccount Connector]] || IUserAccountService || User account CRUD. Known bug: CreateUser() sends first name as email value.
 |-
-| The service || OpenSim/Services/[ServiceName] (e.g. OpenSim/Services/AssetService) || Actually services the call and returns data.
+| [[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.
 |}
 ----
-== Configuration ==
+== HG Connectors ==
-Note: In OpenSimulator 0.9.2, LocalAssetServiceConnector, RemoteAssetServiceConnector, and HGAssetBroker were replaced by a single module RegionAssetConnector. The examples below reflect the current architecture.
+HyperGrid introduces additional connectors that wrap or replace the standard ones:
-=== Standalone ===
+* 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.
-Connectors and service in the same process:
+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.
- [Modules]
+These are documented in the individual connector pages above and in:
- AssetServices = "RegionAssetConnector"
+* [[OpenSimulator Internals/Code Map/HGEntityTransferModule]]
+* [[OpenSimulator Internals/Code Map/InventoryAccessModule]]
- [AssetService]
- LocalGridAssetService = "OpenSim.Services.AssetService.dll:AssetService"
-=== Grid ===
-Service runs remotely on ROBUST:
- [Modules]
- AssetServices = "RegionAssetConnector"
- [AssetService]
- LocalGridAssetService = "OpenSim.Services.AssetService.dll:AssetService"
- AssetServerURI = "http://myassetserver.com:8003"
 ----
-== Example: Asset Get ==
+== Configuration ==
-=== Standalone path ===
-# Simulator calls Scene.AssetService.Get()
-# Routes to RegionAssetConnector.Get()
-# Checks cache
-# On miss, calls AssetService.Get() directly in-process
-# AssetService retrieves from persistent storage
-=== Grid path ===
-# Simulator calls Scene.AssetService.Get()
+Connectors are selected in the [Architecture] ini include files:
-# Routes to RegionAssetConnector.Get()
-# Delegates to AssetServicesConnector (OpenSim/Services/Connectors)
-# Makes HTTP GET to http://yourassetserver/assets/assetId
-# Received by OpenSim/Server/Handlers/Asset/AssetServerConnector
-# AssetServerGetHandler unpacks request, calls AssetService
-# Returns asset as XML on success, 404 on miss
-=== HyperGrid path ===
+* 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.
-# Simulator calls Scene.AssetService.Get()
+The [ServiceList] section of Robust.ini selects which ROBUST handlers are loaded. The [Modules] section of OpenSim.ini selects which connectors the simulator loads.
-# Routes to RegionAssetConnector.Get()
-# RegionAssetConnector determines if asset is local or foreign grid
-# Foreign: instantiates GridAssetClient for the foreign grid
-# Makes HTTP GET to foreign asset server
-# Asset copied to local asset table on retrieval -- same UUID, no link back
 ----
@@ Line 90: / Line 100: @@
 == See Also ==
+* [[OpenSimulator Internals/Code Map/ROBUST]]
 * [[OpenSimulator Internals/ROBUST Services]]
-* [[OpenSimulator Internals/Data Dictionaries]]
+* [[OpenSimulator Internals/Reading the Code]]
-* [[OpenSimulator Internals/Asset Connector]]
+* [[OpenSimulator Internals/Code Map]]