OpenSimulator Internals/Asset Connector

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

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

1. Reads AssetServices from [Modules] -- exits if name does not match
2. Loads LocalGridAssetService plugin -- throws if missing or fails to load
3. Loads HypergridAssetService plugin -- optional, skipped if not configured
4. Loads AssetPermissions from [HGAssetService] if HyperGrid enabled
5. Creates two worker queues:
   • m_localRequestsQueue ("GetAssetsWorkers", 2 threads, 2000 capacity)
   • m_remoteRequestsQueue ("GetRemoteAssetsWorkers", 2 threads, 2000 capacity)
6. 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

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

Synchronous Get -- HyperGrid asset

1. Scene.AssetService.Get(id)
2. IsHG(id) = true
3. 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
4. Check m_AssetPerms.AllowedImport() -- return null if not permitted
5. Store(asset) -- persist to local grid if permitted
6. Return asset

Synchronous Get -- with known foreign service URI

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

Asynchronous Get -- local

1. Get(id, sender, callBack)
2. Check m_Cache.GetFromMemory() -- invoke callback immediately if found or negatively cached
3. UUID.Zero check -- invoke callback with null and return false
4. 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
5. AssetRequestProcessor dequeues, calls Get(id), notifies all handlers via FireAndForget

Asynchronous Get -- HyperGrid

1. Get(id, ForeignAssetService, StoreOnLocalGrid, callBack)
2. Same cache and deduplication logic as async local
3. If ForeignAssetService is empty: enqueue to m_localRequestsQueue
4. Otherwise: enqueue ForeignAssetServiceGetData struct to m_remoteRequestsQueue
5. 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

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
• assets table