OpenSpeak/openspec/specs/003-channel-management.md

Feature Specification: Channel Management

ID: CHANNEL-001 Version: 1.0 Status: Planned Priority: Critical

Overview

Channel management system for creating, updating, deleting, and organizing voice communication spaces.

Channel Model

Channel Entity

message Channel {
  string id = 1;                    // Unique identifier (UUID)
  string name = 2;                  // Display name
  string description = 3;           // Optional description
  bool is_public = 4;              // Public or private
  string owner_id = 5;             // User who created the channel
  repeated string member_ids = 6;  // List of member IDs
  int32 max_users = 7;             // Max concurrent users (0 = unlimited)
  int64 created_at = 8;            // Unix timestamp
  int64 updated_at = 9;            // Unix timestamp
  ChannelStatus status = 10;       // Active, archived, deleted
}

enum ChannelStatus {
  ACTIVE = 0;
  ARCHIVED = 1;
  DELETED = 2;
}

Channel Properties

• ID: UUID v4, immutable
• Name: 1-50 characters, alphanumeric + spaces/hyphens
• Description: Optional, max 500 characters
• Public: Anyone can join (requires authentication only)
• Private: Admin only, membership by invitation
• Max Users: Unlimited by default, configurable per channel
• Status: Active by default, can be archived (soft-delete) or deleted (hard-delete)

Channel Lifecycle

Creation

Requirements:

• User must be authenticated
• User must have channels:create permission
• Name must be unique (case-insensitive)
• At least 2 characters, max 50

Process:

Client requests CreateChannel
    ↓
Server validates permissions
    ↓
Server validates name uniqueness and format
    ↓
Server creates channel with unique ID
    ↓
Server marks creator as owner
    ↓
Server broadcasts ChannelCreated event
    ↓
Return channel object to client

Joining

Requirements:

• User must be authenticated
• Channel must exist and be active
• For public channels: user must be authenticated
• For private channels: user must be invited or owner

Process:

Client requests JoinChannel(channel_id)
    ↓
Server validates channel exists
    ↓
Server validates access permissions
    ↓
Check max_users capacity
    ↓
Add user to channel members list
    ↓
Broadcast UserJoined event to channel
    ↓
Return success and list of current members

Leaving

Requirements:

• User must be in channel

Process:

User requests LeaveChannel or disconnects
    ↓
Server removes user from channel members
    ↓
Broadcast UserLeft event to channel
    ↓
Clean up user's audio streams
    ↓
Confirm departure

Updates

Allowed Updates:

• Name (must remain unique)
• Description
• Public/Private status
• Max users capacity
• Owner reassignment

Requirements:

• Only channel owner or admin can update
• Name must remain unique
• Validation of new values

Deletion

Soft Delete (Archive):

• Channel marked as archived
• Existing members can still access
• New users cannot join
• Data preserved for recovery
• Used for channels that may return

Hard Delete:

• Permanently removed from system
• All associated data deleted
• Cannot be recovered
• Used for spam/abuse

Presence & Status

User Presence

User State in Channel:

Connected: User is in channel voice call
Inactive: User is in channel but no audio activity (15+ seconds)
Typing: User has text input focus (future)
Away: User idle for >5 minutes (future)

Channel Activity Feed (Future)

• User joined
• User left
• User muted/unmuted
• Channel created/updated
• Admin actions

Permissions Model

Channel Owner

• Can modify channel settings
• Can kick members
• Can delete channel
• Can transfer ownership
• Can make channel private/public

Channel Member

• Can join/leave
• Can speak in channel
• Can see member list
• Can see channel info

Server Admin

• Can manage all channels
• Can override any permission
• Can archive/delete channels
• Can view audit logs

API Endpoints (gRPC)

Channel Service

service ChannelService {
  rpc CreateChannel(CreateChannelRequest) returns (CreateChannelResponse);
  rpc GetChannel(GetChannelRequest) returns (Channel);
  rpc ListChannels(ListChannelsRequest) returns (ListChannelsResponse);
  rpc UpdateChannel(UpdateChannelRequest) returns (Channel);
  rpc DeleteChannel(DeleteChannelRequest) returns (DeleteChannelResponse);
  rpc JoinChannel(JoinChannelRequest) returns (JoinChannelResponse);
  rpc LeaveChannel(LeaveChannelRequest) returns (LeaveChannelResponse);
  rpc ListMembers(ListMembersRequest) returns (ListMembersResponse);
  rpc KickMember(KickMemberRequest) returns (KickMemberResponse);
}

Data Persistence (Phase 2)

Initially, channels are in-memory and lost on server restart.

Future: Persistent storage

• Channel metadata in database
• Member lists persisted
• Activity logs
• Backup/restore capability

Configuration

• Max channels allowed on server
• Max members per channel (default)
• Channel name validation rules
• Soft delete retention period (before hard delete)
• Archive auto-cleanup policy

Error Handling

• Duplicate channel name: Return AlreadyExists error
• Channel not found: Return NotFound error
• Access denied: Return PermissionDenied error
• Channel full: Return ResourceExhausted error
• User already in channel: Return AlreadyExists error

Notifications

Events Broadcast to Channel:

• UserJoined(user_id, timestamp)
• UserLeft(user_id, timestamp)
• ChannelUpdated(channel, updater_id)
• ChannelDeleted(channel_id, timestamp)

Testing Strategy

• Unit tests for channel creation with various inputs
• Unit tests for permission validation
• Integration tests for join/leave operations
• Concurrency tests for multiple users joining simultaneously
• Tests for max capacity enforcement
• Soft delete and restore functionality tests
• Event broadcast verification