Editing OpenSimulator Internals/Connector Architecture/GridUser Connector

= OpenSimulator Internals/Connector Architecture/Asset Connector =

== Overview ==

The asset connector is the path between the region simulator and the ROBUST AssetService. It has two sides: the simulator-side modules that make outbound calls, and the ROBUST-side HTTP handlers that receive them.

----

== ROBUST Side ==

=== AssetServiceConnector ===

 OpenSim/Server/Handlers/Asset/AssetServerConnector.cs

The connector loaded by ROBUST from [ServiceList]. Instantiates the asset service implementation and registers all HTTP handlers.

Config section defaults to "AssetService"; overridden by the configName argument from the connector string.

Required config:
* LocalServiceModule -- DLL:class of the IAssetService implementation; throws if missing

Optional config:

{| class="wikitable"
! Key !! Default !! Notes
|-
| AllowRemoteDelete || false || If false, remote DELETE requests always return false
|-
| AllowRemoteDeleteAllTypes || false || If true (and AllowRemoteDelete = true), all asset types can be deleted remotely. If false, only Maptile assets
|-
| RedirectURL || (none) || If set, 404 GET responses redirect to this URL instead
|}

Handlers registered:

{| class="wikitable"
! Handler !! Method !! Path
|-
| AssetServerGetHandler || GET || /assets
|-
| AssetServerPostHandler || POST || /assets
|-
| AssetServerDeleteHandler || DELETE || /assets
|-
| AssetsExistHandler || POST || /get_assets_exist
|}

All handlers except AssetsExistHandler receive an IServiceAuth instance. AssetsExistHandler has no auth.

Console commands registered:
* show asset <ID> -- displays metadata and first 80 bytes as hex
* delete asset <ID> -- deletes asset via IAssetService.Delete()
* dump asset <ID> -- writes raw asset data to a file named after the ID; refuses to overwrite existing files

----

=== AssetServerGetHandler ===

 OpenSim/Server/Handlers/Asset/AssetServerGetHandler.cs

Handles: GET /assets

URL patterns:

{| class="wikitable"
! Path !! Calls !! Response
|-
| /assets/{id} || IAssetService.Get(id) || XML-serialized AssetBase; Content-Type: text/xml
|-
| /assets/{id}/data || IAssetService.GetData(id) || Raw binary data; Content-Type: application/octet-stream
|-
| /assets/{id}/metadata || IAssetService.GetMetadata(id) || XML-serialized AssetMetadata; Content-Type: SLUtil.SLAssetTypeToContentType(type)
|}

404 handling: if RedirectURL is configured and the asset is not found, the response is an HTTP redirect to RedirectURL + original path rather than a 404. This allows chaining to a fallback asset server.

Unknown path segments (anything other than "data" or "metadata" as the second segment) return 400 Bad Request.

Note: the commented-out Content-Type line for the full asset GET shows the original intent was to use SLAssetTypeToContentType, but it was changed to always return "text/xml".

----

=== AssetServerPostHandler ===

 OpenSim/Server/Handlers/Asset/AssetServerPostHandler.cs

Handles: POST /assets

Two behaviors depending on whether an ID is present in the path:

{| class="wikitable"
! Path !! Behavior !! Calls !! Returns
|-
| POST /assets || Store new asset || IAssetService.Store(asset) || XML-serialized string (the assigned ID)
|-
| POST /assets/{id} || Update existing asset data || IAssetService.UpdateContent(id, asset.Data) || XML-serialized bool
|}

Request body: XML-serialized AssetBase in both cases. Returns 400 Bad Request if deserialization fails.

The update path (with ID) only uses asset.Data from the deserialized body -- the rest of the AssetBase fields are ignored.

----

=== AssetServerDeleteHandler ===

 OpenSim/Server/Handlers/Asset/AssetServerDeleteHandler.cs

Handles: DELETE /assets

AllowedRemoteDeleteTypes enum controls what can be deleted:

{| class="wikitable"
! Value !! Behavior
|-
| None || Always returns false; no delete attempted
|-
| MapTile || Fetches asset first; deletes only if AssetFlags.Maptile is set
|-
| All || Deletes any asset type
|}

Sequence:
# If allowedTypes == None: skip, return false
# Fetch asset via IAssetService.Get(id) -- if not found, return false
# If allowedTypes == All OR asset has Maptile flag: call IAssetService.Delete(id)
# Otherwise: log debug message and return false

Always returns XML-serialized bool.

----

=== AssetsExistHandler ===

 OpenSim/Server/Handlers/Asset/AssetsExistHandler.cs

Handles: POST /get_assets_exist

Request body: XML-serialized string[] of asset IDs.
Response: XML-serialized bool[] -- one entry per ID, true if the asset exists.

Calls IAssetService.AssetsExist(ids) directly. Returns 400 Bad Request if deserialization fails.

No auth -- AssetsExistHandler is constructed without an IServiceAuth argument.

----

== Simulator Side ==

=== RegionAssetConnectorModule ===

 OpenSim/Region/CoreModules/ServiceConnectorsOut/Asset/RegionAssetConnectorModule.cs

The single region module replacing LocalAssetServiceConnector, RemoteAssetServiceConnector, and HGAssetBroker as of 0.9.2. Implements ISharedRegionModule.

Acquires the asset cache in RegionLoaded(), not in AddRegion(). This is required because the cache module must be loaded first.

Two worker queues:
* m_localRequestsQueue -- for local (non-HG) asset requests, 2 threads, capacity 2000
* m_remoteRequestsQueue -- for HG asset requests, 2 threads, capacity 2000

Request deduplication via m_AssetHandlers dictionary -- multiple callers requesting the same ID share a single in-flight request.

IsHG(id) check: inspects the first character of the asset ID. If 'h' or 'H', the ID is an HTTP URI and the asset is foreign (HyperGrid). All other IDs are treated as local.

----

=== AssetServicesConnector ===

 OpenSim/Services/Connectors/Asset/AssetServicesConnector.cs

The remote connector used for non-HG asset requests. Makes HTTP calls to the ROBUST asset service.

URI pattern: m_ServerURI + "/assets/" + id

Store() assigns a UUID client-side before sending if the asset has no ID. Routing is determined by the ID, so the UUID must be assigned before the request is dispatched.

MaxAssetRequestConcurrency defaults to 8 -- limits parallel outbound GET requests.

----

=== HGAssetServiceConnector ===

 OpenSim/Services/Connectors/Asset/HGAssetServiceConnector.cs

Wraps multiple AssetServicesConnector instances, one per foreign grid URL. Connectors are pooled and expire after 60 seconds of inactivity.

IsHG(id) -- same first-character check as RegionAssetConnectorModule.

AssetsExistHandler grouping: groups requested IDs by server URL, queries each foreign server separately.

UpdateContent() and Delete() always return false -- foreign assets cannot be modified.

----

== HTTP API Summary ==

{| class="wikitable"
! Method !! Path !! Purpose !! Auth
|-
| GET || /assets/{id} || Get full asset (metadata + data) as XML || Yes
|-
| GET || /assets/{id}/data || Get raw asset binary data || Yes
|-
| GET || /assets/{id}/metadata || Get asset metadata as XML || Yes
|-
| POST || /assets || Store new asset; returns assigned ID || Yes
|-
| POST || /assets/{id} || Update asset binary data || Yes
|-
| DELETE || /assets/{id} || Delete asset (subject to AllowedRemoteDeleteTypes) || Yes
|-
| POST || /get_assets_exist || Bulk existence check; returns bool[] || No
|}

----

== See Also ==

* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/Code Map/ROBUST]]
* [[OpenSimulator Internals/Code Map/Shared]]