Jwbshaw: update with more info

2026-06-22T08:59:00Z

update with more info

Jwbshaw: first

2026-06-21T17:47:06Z

first

New page

= OpenSimulator Internals/Asset Connector =

== Overview ==

The asset connector chain connects simulator code to the asset service. It handles local, grid, and HyperGrid asset retrieval transparently through a single interface.

In OpenSimulator 0.9.2, LocalAssetServiceConnector, RemoteAssetServiceConnector, and HGAssetBroker were consolidated into a single module: RegionAssetConnector.

See [[OpenSimulator Internals/Connector Architecture]] for the general connector pattern.

----

== Source Files ==

{| class="wikitable"
! File !! Location
|-
| RegionAssetConnectorModule.cs || OpenSim/Region/CoreModules/ServiceConnectorsOut/Asset/
|-
| LocalAssetServiceConnector.cs || OpenSim/Region/CoreModules/ServiceConnectorsOut/Asset/ (tests only)
|}

----

== Configuration ==

RegionAssetConnector is selected via [Modules] in OpenSim.ini:

[Modules]
AssetServices = "RegionAssetConnector"

[AssetService]
LocalGridAssetService = "OpenSim.Services.AssetService.dll:AssetService"
HypergridAssetService = "OpenSim.Services.AssetService.dll:HGAssetService"

LocalGridAssetService is required -- connector throws on startup if missing.

HypergridAssetService is optional -- HyperGrid asset transfer is disabled if not configured.

HyperGrid import/export permissions are configured in [HGAssetService].

----

== Initialisation Sequence ==

# Reads AssetServices from [Modules] -- exits if name does not match
# Loads LocalGridAssetService plugin -- throws if missing or fails to load
# Loads HypergridAssetService plugin -- optional, skipped if not configured
# Loads AssetPermissions from [HGAssetService] if HyperGrid enabled
# Creates two worker queues:
#* m_localRequestsQueue ("GetAssetsWorkers", 2 threads, 2000 capacity)
#* m_remoteRequestsQueue ("GetRemoteAssetsWorkers", 2 threads, 2000 capacity)
# Cache (m_Cache) is acquired in RegionLoaded(), not Initialise(). Must implement ISharedRegionModule or is rejected.

----

== HyperGrid ID Detection ==

private bool IsHG(string id)
{
return id.Length > 0 && (id[0] == 'h' || id[0] == 'H');
}

HyperGrid asset IDs are HTTP URIs. IsHG() checks only the first character. All routing decisions flow from this check.

----

== Call Paths ==

=== Synchronous Get -- local asset ===

# Scene.AssetService.Get(id)
# IsHG(id) = false
# Check m_Cache.Get() -- return asset if hit, return null if negatively cached
# GetFromLocal(id) -- calls m_localConnector.Get(id) directly (inlined)
# On miss: m_Cache.CacheNegative(id)
# On hit: m_Cache.Cache(asset), return asset

=== Synchronous Get -- HyperGrid asset ===

# Scene.AssetService.Get(id)
# IsHG(id) = true
# GetForeign(id):
#* Util.ParseForeignAssetID(id) -- extracts URI and UUID string
#* Check m_Cache.GetCached(uuidstr)
#* GetFromLocal(uuidstr) -- check local store first
#* If not found locally: GetFromForeign(uuidstr, uri) via m_HGConnector
# Check m_AssetPerms.AllowedImport() -- return null if not permitted
# Store(asset) -- persist to local grid if permitted
# Return asset

=== Synchronous Get -- with known foreign service URI ===

# Get(id, ForeignAssetService, StoreOnLocalGrid)
# Check m_Cache.GetCached(id)
# GetFromLocal(id)
# On local miss: GetFromForeign(id, ForeignAssetService)
#* Check AssetPerms.AllowedImport() -- CacheNegative and return null if denied
#* StoreLocal(asset) if StoreOnLocalGrid=true
#* Cache(asset)
# On foreign miss: CacheNegative(id)

=== Asynchronous Get -- local ===

# Get(id, sender, callBack)
# Check m_Cache.GetFromMemory() -- invoke callback immediately if found or negatively cached
# UUID.Zero check -- invoke callback with null and return false
# Lock m_AssetHandlers:
#* If request already in-flight for this id: append callback to handler list, return
#* Otherwise: create handler list, add to m_AssetHandlers, enqueue id to m_localRequestsQueue
# AssetRequestProcessor dequeues, calls Get(id), notifies all handlers via FireAndForget

=== Asynchronous Get -- HyperGrid ===

# Get(id, ForeignAssetService, StoreOnLocalGrid, callBack)
# Same cache and deduplication logic as async local
# If ForeignAssetService is empty: enqueue to m_localRequestsQueue
# Otherwise: enqueue ForeignAssetServiceGetData struct to m_remoteRequestsQueue
# AssetRequestProcessor calls Get(id, ForeignAssetService, StoreOnLocalGrid)

----

== Request Deduplication ==

m_AssetHandlers (Dictionary<string, List<SimpleAssetRetrieved>>) prevents duplicate in-flight requests for the same asset ID. If a second async request arrives for an asset already being fetched, its callback is appended to the existing handler list. When the fetch completes, all waiting callbacks are notified via FireAndForget.

----

== Store Paths ==

{| class="wikitable"
! Condition !! Behaviour
|-
| HyperGrid asset, Local or Temporary flag set || Return null -- not stored
|-
| HyperGrid asset, export not permitted by AssetPermissions || Return empty string
|-
| HyperGrid asset, permitted || StoreForeign() via m_HGConnector, cache on success
|-
| Local asset, Local or Temporary flag set || Cache only, not persisted to database
|-
| Local asset, normal || Cache and StoreLocal() via m_localConnector
|}

UpdateContent() and Delete() always return false for HyperGrid assets.

AssetsExist() routes entirely to m_localConnector if no HG IDs present, entirely to m_HGConnector if any HG IDs present.

----

== Shutdown ==

Close() disposes both worker queues and sets them to null.

----

== See Also ==

* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/AssetService]]
* [[OpenSimulator Internals/Data Dictionaries#assets|assets table]]

OpenSimulator Internals/Asset Connector - Revision history

Jwbshaw: update with more info

Jwbshaw: first