Jump to content

OpenSimulator Internals/Connector Architecture: Difference between revisions

From Open Simulator Technical Help
← Older editNewer edit →
undoJwbshaw (talk | contribs)
120 edits
Jwbshaw (talk | contribs)
120 edits
Configuration examples updated to RegionAssetConnector, and Asset Connector added to See Also.
Jwbshaw (talk | contribs)
120 edits
more stuff
Line 1: Line 1:


= OpenSimulator Internals/Connector Architecture =
= OpenSimulator Internals/Connector Architecture =
Line 4: Line 5:
== Overview ==
== 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.
See [[OpenSimulator Internals/ROBUST Services]] for the server-side service implementations.


----
----


== The Five Components ==
== Connector Pattern ==


Up to five components are involved in connecting simulator code to a grid service.
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"
{| class="wikitable"
! Component !! Location !! Description
! Connector !! Service Interface !! Notes
|-
| [[OpenSimulator Internals/Connector Architecture/Asset Connector]] || IAssetService || Includes server-side handler detail. HG variant wraps with foreign asset server logic.
|-
| [[OpenSimulator Internals/Connector Architecture/GridUser Connector]] || IGridUserService || Tracks last position, login/logout timestamps, home region.
|-
|-
| Simulator code || OpenSimulator core or a module || Makes the initial service call to get or set data.
| [[OpenSimulator Internals/Connector Architecture/Presence Connector]] || IPresenceService || Online status, session tracking, region assignment.
|-
|-
| 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/UserAccount Connector]] || IUserAccountService || User account CRUD. Known bug: CreateUser() sends first name as email value.
|-
|-
| 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/Inventory Connector]] || IInventoryService || XInventory protocol. UpdateFolder() URL-encodes Name; AddFolder() does not.
|-
|-
| 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/Authentication Connector]] || IAuthenticationService || Password and token authentication, impersonation mechanism.
|-
|-
| The service || OpenSim/Services/[ServiceName] (e.g. OpenSim/Services/AssetService) || Actually services the call and returns data.
| [[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.
 
=== Standalone ===
 
Connectors and service in the same process:


[Modules]
HyperGrid introduces additional connectors that wrap or replace the standard ones:
AssetServices = "RegionAssetConnector"
[AssetService]
LocalGridAssetService = "OpenSim.Services.AssetService.dll:AssetService"


=== Grid ===
* 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).


Service runs remotely on ROBUST:
These are documented in the individual connector pages above and in:
 
* [[OpenSimulator Internals/Code Map/HGEntityTransferModule]]
[Modules]
* [[OpenSimulator Internals/Code Map/InventoryAccessModule]]
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 93:
== See Also ==
== See Also ==


* [[OpenSimulator Internals/Code Map/ROBUST]]
* [[OpenSimulator Internals/ROBUST Services]]
* [[OpenSimulator Internals/ROBUST Services]]
* [[OpenSimulator Internals/Data Dictionaries]]
* [[OpenSimulator Internals/Reading the Code]]
* [[OpenSimulator Internals/Asset Connector]]
* [[OpenSimulator Internals/Code Map]]

Revision as of 12:31, 7 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).

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

Connector Pattern

All remote connectors follow the same pattern:

  1. Constructor receives IConfigSource and reads the service URL from config.
  2. Each method serialises parameters to a REST or XMLRPC request.
  3. Sends HTTP POST/GET/DELETE to the ROBUST handler endpoint.
  4. 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 Includes server-side handler detail. HG variant wraps with foreign asset server logic.
OpenSimulator Internals/Connector Architecture/GridUser Connector IGridUserService Tracks last position, login/logout timestamps, home region.
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.
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).

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.

See Also

Retrieved from "http://osimdev.org/wiki/index.php?title=OpenSimulator_Internals/Connector_Architecture&oldid=81"