bsa_sessions design requirements

https://github.com/orgs/Buildstruct/projects/4/views/1?pane=issue&itemId=164151461

Author: blueshank-gh

docs/database/bsa_accounts.md

@@ -11,7 +11,6 @@ A player can have one account per provider.
 CREATE TABLE `bsa_accounts` (
     `account_id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
     `provider_id` BIGINT UNSIGNED NOT NULL,
-    `server_id` BIGINT UNSIGNED NULL,
     `player_id` BIGINT UNSIGNED NOT NULL,
     `identifier` VARCHAR(255) NOT NULL,
     `username` VARCHAR(255) NULL,
@@ -41,12 +40,11 @@ CREATE TABLE `bsa_accounts` (
 
 - account_id - unique id of the account.
 - provider_id - provider that owns this account identity.
-- server_id - server currently reporting this account as active; null means no server affinity.
 - player_id - player that owns the account.
 - identifier - unique provider identifier (`steamid64`, `snowflake`, etc) within a provider.
 - username - provider username at time of record.
 - time - generic time accumulator for the account.
-- heartbeat_at - account heartbeat used to detect stale active sessions.
+- heartbeat_at - account heartbeat used for recent activity.
 - created_at - timestamp for when the account was created.
 
 ## Restrictions
@@ -66,6 +64,7 @@ Triggers prevent update or deletion of these rows.
 
 ## Interlink Behavior
 - Account presence and session ownership are coordinated with periodic `heartbeat_at` updates and `server_id` attach/detach writes.
+- You must apply a `session_id` from `bsa_sessions` to the account data being networked.
 - `database.players:connected(account, secondaries)`
 - `database.players:disconnected(account, secondaries)`
 - `database.players:timeset(account, time_seconds)`

docs/database/bsa_sessions.md

@@ -0,0 +1,52 @@
+# bsa_sessions
+Sessions represent live or recently-live account presence on servers.\
+An account may have multiple session rows at once.
+
+!!! warning
+    This table may incur high reads to the database due to online-state lookups.\
+    Please ensure your platform isn't requesting information so often.
+
+## Structure
+```sql
+CREATE TABLE `bsa_sessions` (
+    `session_id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+    `account_id` BIGINT UNSIGNED NOT NULL,
+    `server_id` BIGINT UNSIGNED NULL,
+    `heartbeat_at` DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+    `created_at` DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+
+    CONSTRAINT fk_conn_server
+        FOREIGN KEY (`server_id`) REFERENCES `bsa_servers`(`server_id`)
+            ON DELETE SET NULL
+            ON UPDATE CASCADE,
+
+    CONSTRAINT fk_conn_account
+        FOREIGN KEY (`account_id`) REFERENCES `bsa_accounts`(`account_id`)
+            ON DELETE CASCADE
+            ON UPDATE CASCADE
+);
+```
+
+- session_id - unique id of the session.
+- account_id - account that owns this session.
+- server_id - server currently attached to the session; null means detached or orphaned from a server record.
+- heartbeat_at - timestamp for the last session heartbeat.
+- created_at - timestamp for when the session row was created.
+
+## Restrictions
+- There are no trigger-protected rows in this table.
+- Multiple sessions per account are allowed by design.
+- Deleting an account cascades and deletes its sessions.
+- Deleting a server does not delete sessions; it sets `server_id` to `NULL`.
+
+## Design Requirements
+- Treat a session as alive only when `heartbeat_at` is within 60 seconds, and the linked server heartbeat in `bsa_servers` is also within 60 seconds.
+- Create a new row when a player/account attaches to a server and no reusable `session_id` is already held locally.
+- Refresh `heartbeat_at` regularly for active sessions, the current platform also refreshes `server_id` on heartbeat.
+- Delete the row on clean disconnect/shutdown rather than keeping indefinite session history.
+- Always propagate `session_id` with replicated account presence so remote caches can update the correct live entry.
+
+## Interlink Behavior
+- `database.players:connected(account, secondaries)` payloads must include `session_id`.
+- `database.players:disconnected(account, secondaries)` payloads must include `session_id`.
+- On interlink reconnect/startup, platforms should clear any stale sessions owned by their current `server_id` and broadcast matching disconnect events.

docs/platforms/garrysmod/database/variables/players.md

@@ -6,8 +6,8 @@ Replicated per-player state and player-facing helper API exposed through `BSA.Pl
 
 ## Runtime Events
 - `#!ts players.initialized(entity: Player)`
-- `#!ts players.connected(steamid64: string, player?: Player)`
-- `#!ts players.disconnected(steamid64: string, player?: Player)`
+- `#!ts players.connected(steamid64: string, session_id: number, player?: Player)`
+- `#!ts players.disconnected(steamid64: string, session_id: number, player?: Player)`
 - `#!ts players.faked(entity: Player, ent_index: number, name?: string, color?: Color)`
 - `#!ts players.disguised(entity: Player, ent_index: number, disguise_name?: string)`
 - `#!ts players.primaried(entity: Player, old_group, new_group)`
@@ -47,6 +47,7 @@ Time + AFK:
 
 - `#!ts player:GetPlayTime(absolute?: boolean): number`
 - `#!ts player:GetSessionTime(): number`
+- `#!ts player:GetSessionID(): number`
 - `#!ts player:SetAFK(state: boolean): void`
 - `#!ts player:GetAFK(): boolean`
 - `#!ts player:GetAFKTime(absolute?: boolean): number`

mkdocs.yml

@@ -22,6 +22,7 @@ nav:
     - Interlink: database/bsa_interlink.md
     - Groups: database/bsa_groups.md
     - Players: database/bsa_players.md
+    - Sessions: database/bsa_sessions.md
     - Player Groups: database/bsa_player_groups.md
     - Permissions: database/bsa_permissions.md
     - Group Permissions: database/bsa_group_permissions.md