OpenSpeak/openspec/specs/004-user-presence.md

Feature Specification: User Presence & Status Tracking

ID: PRESENCE-001 Version: 1.0 Status: Planned Priority: High

Overview

System for tracking online status, location (which channel users are in), and user availability information across the server.

User Presence Model

User Presence State

message UserPresence {
  string user_id = 1;
  PresenceStatus status = 2;
  string current_channel_id = 3;     // Which channel they're in (if any)
  int64 last_seen = 4;               // Unix timestamp
  bool is_microphone_muted = 5;      // Audio input status
  bool is_speaker_muted = 6;         // Audio output status
  string client_version = 7;         // Client app version
  string platform = 8;               // Windows, Mac, Linux
  int64 connected_at = 9;            // When user connected
}

enum PresenceStatus {
  OFFLINE = 0;
  ONLINE = 1;
  IDLE = 2;           // No activity for 5+ minutes
  DO_NOT_DISTURB = 3; // User set status (future)
  AWAY = 4;          // Inactive (future)
}

Presence States

Online

• User is connected to server
• User has active gRPC connection
• Subscribed to events

Idle

• User is connected but inactive
• No keyboard/mouse input for 5+ minutes
• Still receives events but marked as idle
• Returns to Online on activity

Offline

• User is not connected
• Server has no active connection
• User not visible in online user list

Do Not Disturb (Future)

• User explicitly set this status
• Still marked as online
• May suppress notifications

Tracking Mechanism

Connection Lifecycle

Client connects to server
    ↓
Server creates UserSession
    ↓
Server broadcasts UserOnline event
    ↓
All clients update online user list
    ↓
[User activity in channel]
    ↓
Client disconnects (graceful or timeout)
    ↓
Server marks user as offline
    ↓
Server broadcasts UserOffline event
    ↓
All clients update online user list

Session Management

User Session Object:

message UserSession {
  string user_id = 1;
  string session_id = 2;        // Unique session ID
  string connection_id = 3;     // gRPC connection ID
  int64 connected_at = 4;
  int64 last_activity = 5;
  string current_channel = 6;
  bool microphone_active = 7;
  bool speaker_active = 8;
  string client_version = 9;
  map<string, string> metadata = 10;
}

Idle Detection

• Track last activity timestamp
• Background task checks every 30 seconds
• Mark users idle after 5 minutes no activity
• Activity events: join/leave channel, toggle mute, send message (future)
• Return to online on next activity

Connection Timeout

• If no heartbeat for 30 seconds: assume disconnected
• Clean up session
• Broadcast UserOffline
• Remove from channel members list

Presence Events

Events Broadcast Across Server

message UserOnlineEvent {
  UserPresence presence = 1;
  int64 timestamp = 2;
}

message UserOfflineEvent {
  string user_id = 1;
  int64 timestamp = 2;
}

message UserStatusChanged {
  string user_id = 1;
  PresenceStatus old_status = 2;
  PresenceStatus new_status = 3;
  int64 timestamp = 4;
}

message UserChannelChanged {
  string user_id = 1;
  string old_channel_id = 2;
  string new_channel_id = 3;
  int64 timestamp = 4;
}

message UserMuteStateChanged {
  string user_id = 1;
  bool microphone_muted = 2;
  bool speaker_muted = 3;
  int64 timestamp = 4;
}

Event Distribution

• UserOnline/Offline: Broadcast to all connected clients
• UserChannelChanged: Broadcast to clients in both channels
• UserMuteStateChanged: Broadcast to clients in same channel

API Endpoints (gRPC)

Presence Service

service PresenceService {
  // Get current user's presence
  rpc GetMyPresence(GetPresenceRequest) returns (UserPresence);

  // Get another user's presence
  rpc GetUserPresence(GetPresenceRequest) returns (UserPresence);

  // List all online users
  rpc ListOnlineUsers(ListOnlineUsersRequest) returns (ListOnlineUsersResponse);

  // List users in specific channel
  rpc ListChannelMembers(ListChannelMembersRequest) returns (ListChannelMembersResponse);

  // Set/Update user status
  rpc SetPresenceStatus(SetPresenceStatusRequest) returns (UserPresence);

  // Subscribe to presence events (streaming)
  rpc SubscribePresenceEvents(PresenceSubscriptionRequest) returns (stream PresenceEvent);

  // Report user activity (heartbeat)
  rpc ReportActivity(ReportActivityRequest) returns (ActivityResponse);
}

Mute Status Tracking

Microphone Mute

• User toggles microphone on/off
• Status tracked in UserPresence
• Broadcast to channel members
• Voice packets not sent when muted
• Visual indicator for other users

Speaker Mute

• User mutes speaker output
• Audio packets received but discarded locally
• No bandwidth saved (packets still transmitted)
• Other users don't know user is speaker-muted

Data Storage (Phase 2)

Currently in-memory, future persistent storage:

• User presence snapshots every 5 minutes
• Activity history for audit/analytics
• Login/logout timestamps
• Channel visit history

Configuration

• Idle timeout: 5 minutes (configurable)
• Heartbeat interval: 30 seconds
• Presence update interval: When status changes
• Max online users tracking: Unlimited initially
• Presence event retention: None (real-time only)

Scalability Considerations

• In-memory presence map for fast lookups
• Efficient pub/sub for event distribution
• Goroutine per connection for heartbeat handling
• Channel-scoped events to reduce broadcast traffic
• Consider Redis for multi-server deployments (phase 2+)

Error Handling

• User not found: Return NotFound
• Session expired: Return Unauthenticated
• Invalid status transition: Return InvalidArgument
• Broadcast failures: Log and continue

Testing Strategy

• Unit tests for idle detection
• Unit tests for presence state transitions
• Integration tests for session creation/destruction
• Tests for event broadcasting to correct clients
• Concurrency tests with many simultaneous connections
• Tests for connection timeout detection
• Performance tests with large number of online users