Editing OpenSimulator Internals/Code Map/ROBUST/GridUserService (section)

== Overview ==

GridUserService tracks per-user grid state: online/offline status, login/logout timestamps, home location, and last known position. It is used by LoginService on login and logout, and by simulators to update position as the avatar moves.

Source files:

 OpenSim/Services/UserAccountService/GridUserService.cs
 OpenSim/Services/UserAccountService/GridUserServiceBase.cs

Note: despite the name, these files live in the UserAccountService directory, not a GridUserService directory.

----

=== Constructor and Config Loading ===

 GridUserServiceBase(IConfigSource config)

Config is read in two layers; [GridUserService] overrides [DatabaseService]:

{| class="wikitable"
! Section !! Key !! Default !! Notes
|-
| [DatabaseService] || StorageProvider || (none) || DLL name -- fallback
|-
| [DatabaseService] || ConnectionString || (none) || DB connection string -- fallback
|-
| [GridUserService] || StorageProvider || (inherited) || Overrides [DatabaseService]
|-
| [GridUserService] || ConnectionString || (inherited) || Overrides [DatabaseService]
|-
| [GridUserService] || Realm || GridUser || Table name
|}

Note: the comment in GridUserServiceBase.cs misspells the section name as [GridUsetService]. The actual section key read is "GridUserService".

Throws if StorageProvider is empty or if the plugin cannot be loaded.

The loaded plugin is stored as m_Database (IGridUserData).

Console commands are registered once only (m_Initialized static flag prevents re-registration on multiple instantiations):

* show grid user <ID> -- displays all fields for a user ID (prefix match via GetAll)
* show grid users online -- counts users marked Online whose last login is less than 5 days ago

----

=== Data Model ===

GridUserData stores one row per user. Fields stored in the Data dictionary:

{| class="wikitable"
! Field !! Type !! Notes
|-
| Online || bool string || "True" or "False"
|-
| Login || int string || Unix timestamp of last login
|-
| Logout || int string || Unix timestamp of last logout
|-
| HomeRegionID || UUID string || Region UUID of home location
|-
| HomePosition || Vector3 string || Position within home region
|-
| HomeLookAt || Vector3 string || Look-at direction at home
|-
| LastRegionID || UUID string || Region UUID of last known position
|-
| LastPosition || Vector3 string || Last known position within region
|-
| LastLookAt || Vector3 string || Last known look-at direction
|}

UserID is stored directly on GridUserData, not in the Data dictionary.

UserID may be longer than 36 characters (HyperGrid user IDs include a URI suffix). All cache and lookup operations truncate to the first 36 characters for the cache key.

----

=== Cache ===

 private static ExpiringCacheOS<string, GridUserData> cache

Static cache shared across all instances. TTL is 300000ms (5 minutes). Cache key is the first 36 characters of userID.

GetGridUserData() checks the cache first. On cache miss, calls m_Database.GetAll(userID). All write operations (LoggedIn, LoggedOut, SetHome, SetLastPosition) update the cache after a successful Store().

If GetAll() returns multiple records for the same userID (should not happen in a healthy database), GetGridUserData() selects the record with the most recent Login or Logout timestamp. Parse failures during this selection are silently swallowed via empty catch.

Null results are cached for 300000ms to avoid repeated database hits for unknown users.

----

=== GetGridUserInfo ===

 public virtual GridUserInfo GetGridUserInfo(string userID)
 public virtual GridUserInfo[] GetGridUserInfo(string[] userIDs)

Single-user: calls GetGridUserData(), returns null if not found, otherwise converts via ToInfo().

Batch: iterates the array and calls the single-user method for each. No batch database query -- each ID hits the cache or database individually.

ToInfo() maps GridUserData fields to GridUserInfo:
* Missing or unparseable fields are left as default values (zero UUID, zero Vector3, UnixEpoch for timestamps)
* Login and Logout are converted from Unix int to DateTime via Util.ToDateTime()

----

=== LoggedIn ===

 public GridUserInfo LoggedIn(string userID)

# Fetches existing record or creates a new GridUserData if none exists
# Sets Online = "True"
# Sets Login = current Unix timestamp
# Stores to database
# Updates cache
# Returns GridUserInfo via ToInfo()

----

=== LoggedOut ===

 public bool LoggedOut(string userID, UUID sessionID, UUID regionID, Vector3 lastPosition, Vector3 lastLookAt)

sessionID parameter is accepted but not used.

# Fetches existing record or creates a new GridUserData if none exists
# Sets Online = "False"
# Sets Logout = current Unix timestamp
# Sets LastRegionID, LastPosition, LastLookAt from parameters
# Stores to database -- returns false on Store() failure
# Updates cache on success
# Returns true on success, false on Store() failure

----

=== SetHome ===

 public bool SetHome(string userID, UUID homeID, Vector3 homePosition, Vector3 homeLookAt)

# Fetches existing record or creates a new GridUserData if none exists
# Sets HomeRegionID, HomePosition, HomeLookAt from parameters
# Stores to database -- returns false on Store() failure
# Updates cache on success

----

=== SetLastPosition ===

 public bool SetLastPosition(string userID, UUID sessionID, UUID regionID, Vector3 lastPosition, Vector3 lastLookAt)

sessionID parameter is accepted but not used.

# Fetches existing record or creates a new GridUserData if none exists
# Sets LastRegionID, LastPosition, LastLookAt from parameters
# Stores to database -- returns false on Store() failure
# Updates cache on success

The debug log line for this method is commented out in the source.

----

=== Console Commands ===

show grid user <ID>:
* Calls m_Database.GetAll(ID) -- prefix match
* Displays all fields for each matching record via ConsoleDisplayList
* Prints count of matching entries

show grid users online:
* Iterates all records via m_Database.GetAll("")
* Counts records where Online == "True" AND login timestamp is less than 5 days ago
* The 5-day cutoff exists because crashed or unclean-shutdown simulators may leave users marked online indefinitely
* The commented-out code shows a total online count was originally planned alongside the recent count

----

=== Notes ===

* The comment in GridUserServiceBase.cs misspells [GridUserService] as [GridUsetService] -- the code reads the correct key name regardless.
* sessionID is accepted by LoggedOut() and SetLastPosition() but never used.
* The batch GetGridUserInfo(string[]) does not batch database queries -- it calls the single-user path per ID.
* Multiple records per userID are handled defensively but should not occur in a healthy database.

----