OpenSimulator Internals/Code Map/HGEntityTransferModule

Overview

OpenSim/Region/CoreModules/Framework/EntityTransfer/HGEntityTransferModule.cs

Extends EntityTransferModule. Replaces it when HyperGrid is enabled ([Modules] EntityTransferModule = HGEntityTransferModule). Overrides the key virtual methods to handle cross-grid agent transfer, foreign user logout, appearance restriction, and incoming attachment asset fetching.

Also registers as IUserAgentVerificationModule -- verifies HG client tokens on connection.

Configuration

[EntityTransfer] section

Key	Default	Purpose
LevelHGTeleport	0	Minimum user level required to HG teleport (local users only)
RestrictAppearanceAbroad	false	If true, enforce exported appearance before HG TP
AccountForAppearance	(empty)	Comma-separated "First Last" account names whose appearance is the allowed export set

GetFinalDestination() Override

Called during DoTeleportInternal() to resolve the true destination.

Calls GridService.GetRegionFlags() to check if the destination region has the Hyperlink flag.
If Hyperlink: calls GatekeeperServiceConnector.GetHyperlinkRegion() -- HTTP request to the foreign grid's Gatekeeper service.
- Gatekeeper returns the actual destination GridRegion on the foreign grid.
If not Hyperlink: returns the region unchanged (same as base class).

This is the step that resolves a local hyperlink stub into a real foreign region descriptor.

NeedsClosing() Override

Returns true (source agent should be fully closed after transfer) if:

OutViewRange is true, OR
The destination region has the Hyperlink flag or is unknown (flags == -1).

HG teleports always close the source agent regardless of view distance.

CreateAgent() Override

Called during DoTeleportInternal() to create the agent at the destination.

Calls GridService.GetRegionFlags() to check if destination is a Hyperlink region.
If Hyperlink (HG teleport):
- Checks if local user has sufficient UserLevel (>= LevelHGTeleport). Refuses if not.
- Reads HomeURI from agentCircuit.ServiceURLs.
- Gets or creates a UserAgentServiceConnector for the home grid.
- Calls UserAgentService.LoginAgentToGrid() -- HTTP POST to home grid's UserAgent service.
  Home grid's UserAgent service calls the foreign Gatekeeper to create the agent there.
- Sets logout = true -- flags that this agent should be logged out of the source grid after transfer.
- Fires TriggerTeleportStart on success.
If not Hyperlink: calls base.CreateAgent() -- normal SimulationService.CreateAgent().

AgentHasMovedAway() Override

Called after the agent has successfully moved to destination.

Calls base.AgentHasMovedAway() (currently a no-op in base).
If logout == true (HG teleport):
- Calls PresenceService.LogoutAgent() -- marks agent offline in source grid's presence table.
- Calls GridUserService.LoggedOut() -- updates source grid's griduser table with last position.

This is the HG-specific grid logout. The agent is now on the foreign grid and is no longer a presence on the source grid.

DB writes (source grid, HG teleport only)

presence -- UPDATE: Online=0, session cleared
griduser -- UPDATE: LastPosition, Logout timestamp

ValidateGenericConditions() Override

Called before teleport proceeds. For HG teleports with RestrictAppearanceAbroad=true:

Checks if destination is a Hyperlink region.
For local grid users going HG:
- Checks each wearable slot against the exported appearance (ExportedAppearance property).
- Checks each attachment against the exported attachment list.
- Returns false (rejects teleport) if any item is not in the allowed set.

ExportedAppearance: lazy-loaded on first access. Loads appearance for each account in AccountForAppearance from AvatarService, resolves attachment ItemIDs to AssetIDs via InventoryService.

OnConnectionClosed() Override

Called when viewer disconnects.

For local grid users: calls IUserAgentService.LogoutAgent() -- notifies home UserAgent service.

For foreign (HG) users:

Gets HomeURI from AgentCircuitData.ServiceURLs.
Creates UserAgentServiceConnector for the home grid.
Calls security.LogoutAgent() -- HTTP POST to foreign home grid's UserAgent service.
Calls base.OnConnectionClosed() -- handles abort-in-transit case.

TeleportHome() Override

For local grid users: delegates to base.TeleportHome() which uses GridUserService to find home region.

For foreign (HG) users:

Gets HomeURI from AgentCircuitData.ServiceURLs.
Calls UserAgentService.GetHomeRegion() -- HTTP request to foreign home grid.
Constructs a Gatekeeper GridRegion from the HomeURI.
Calls DoTeleport() with ViaHome flag.

HandleIncomingSceneObject() Override

Called when an object crosses into this region from another.

For foreign-user attachments arriving via HGLogin (ViaHGLogin flag set):

Adds object to scene immediately.
Queues an async job on m_incomingSceneObjectEngine (JobEngine, 30s timeout).
Job: creates HGUuidGatherer with the foreign AssetServerURI from AgentCircuitData.
- Gathers all referenced asset UUIDs from the SOG recursively.
- Fetches each asset from the foreign grid's asset server.
- 30-second timeout per gather/fetch step -- removes all jobs for that owner on timeout.
After fetch: calls base.HandleIncomingSceneObject().

For non-HGLogin foreign user attachments (already fetched by first local grid region): calls base directly.

For local user attachments: calls base directly.

HandleIncomingAttachments() Override

Same pattern as HandleIncomingSceneObject() but for the attachment list transferred in AgentData during crossing/teleport.

For foreign HGLogin users:

Queues async job.
HGUuidGatherer fetches all attachment assets from foreign AssetServerURI.
On completion: calls base.HandleIncomingAttachments().

Includes sp.IsDeleted check in fetch loop -- aborts if avatar departed during the fetch.

VerifyClient()

IUserAgentVerificationModule implementation. Called by Scene.CheckClient() for HG arrivals.

Gets HomeURI from AgentCircuitData.
Creates UserAgentServiceConnector.
Calls security.VerifyClient(SessionID, token) -- HTTP POST to foreign home grid.
Returns true/false.

Incoming Attachment Processing

m_incomingSceneObjectEngine: JobEngine with 30-second stall timeout. One engine per region. Processes HG attachment asset fetches serially per owner (CommonId = OwnerID).

RemoveIncomingSceneObjectJobs(commonId): drains the queue and reinserts all jobs except those matching the given owner UUID. Used on timeout to cancel stuck fetches.

Stat registered: "HGIncomingAttachmentsWaiting" -- pull stat showing queue depth.