Skip to content

PanelSession

The PanelSession table tracks active administrator sessions on the QS-Bridge web panel. Each row represents a currently connected admin, providing session metadata used for authorization, activity monitoring, and audit context.

Scope

🌍 Global — Panel sessions are visible to the gateway and all panel subscribers. This enables features like showing which admins are currently online and detecting stale sessions.

Schema

Column Type Constraints Description
player_id String Primary Key Platform-wide player identifier of the admin
display_name String — Human-readable name of the admin
admin_level AdminLevel — Admin's authorization level for this session
connected_at Timestamp — When the admin connected to the panel
last_activity Timestamp — Timestamp of the admin's most recent panel action

Rust Definition

#[spacetimedb::table(public, name = panel_session)]
pub struct PanelSession {
    #[primary_key]
    pub player_id: String,
    pub display_name: String,
    pub admin_level: AdminLevel,
    pub connected_at: Timestamp,
    pub last_activity: Timestamp,
}

AdminLevel Enum

#[derive(SpacetimeType, Clone, Debug, PartialEq)]
pub enum AdminLevel {
    Owner,
    Admin,
    Moderator,
    Viewer,
}

Note: AdminLevel (used in PanelSession) is distinct from AdminRoleLevel (used in AdminRole). AdminLevel includes a Viewer tier for read-only panel access, while AdminRoleLevel defines persistent platform roles. The session's admin_level is typically derived from the player's AdminRoleLevel at session creation time.

Usage Patterns

Session Lifecycle

Panel sessions follow a defined lifecycle managed by three reducers:

  1. Registration: When an admin opens the panel, panel_register_session inserts a new PanelSession row.
  2. Activity Updates: Each panel action updates the last_activity timestamp.
  3. Termination: When the admin disconnects or logs out, panel_end_session deletes the row.
Admin opens panel
  → panel_register_session → INSERT PanelSession
  → Admin performs actions → UPDATE last_activity
  → Admin closes panel
  → panel_end_session → DELETE PanelSession

Authorization Context

Panel wrapper reducers use the PanelSession to identify who is performing an action. Since all panel requests arrive through the gateway (with the gateway's owner_identity), the PanelSession provides the crucial link between the gateway request and the specific admin:

// The gateway includes the admin's player_id in the reducer call
pub fn panel_ban_player(
    ctx: &ReducerContext,
    actor_player_id: String,  // Identifies which admin
    target_player_id: String,
    reason: String,
) {
    // Verify the actor has an active session
    let session = PanelSession::filter_by_player_id(&actor_player_id);
    if session.is_none() {
        return; // No active session — reject
    }
    // ... check admin_level, proceed
}

Stale Session Detection

The last_activity timestamp enables detection of abandoned sessions. If an admin's browser crashes or loses connectivity without triggering panel_end_session, the gateway can identify the stale session (e.g., no activity for 30 minutes) and clean it up.

Online Admins Display

The panel UI subscribes to PanelSession and renders a list of currently active administrators. This provides visibility into who else is managing the cluster in real time.

Reducer Operation
panel_register_session Inserts a new session row
panel_end_session Deletes the session row
panel_log_action May update last_activity as a side effect
Subscriber Query Purpose
Admin Panel SELECT * FROM panel_session Online admins display, session management
Gateway SELECT * FROM panel_session Stale session cleanup, session validation

For full subscription architecture, see Subscriptions.

  • AdminRole — Persistent role assignments (source of admin_level)
  • PanelAuditLog — Audit trail for actions performed during sessions
  • Reducers — Panel session management reducers