Editing OpenSimulator Internals/Connector Architecture (section)

= 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 ==

{| class="wikitable"
! 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:
* [[OpenSimulator Internals/Code Map/HGEntityTransferModule]]
* [[OpenSimulator Internals/Code Map/InventoryAccessModule]]

----

== 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.

----

== See Also ==

* [[OpenSimulator Internals/Code Map/ROBUST]]
* [[OpenSimulator Internals/ROBUST Services]]
* [[OpenSimulator Internals/Reading the Code]]
* [[OpenSimulator Internals/Code Map]]