# Feature Specification: Server Core Architecture **ID:** SERVER-001 **Version:** 1.0 **Status:** Planned **Priority:** Critical ## Overview Server application providing voice communication service, handling client connections, channel management, user presence, and voice packet routing. ## Architecture ### Overall Server Architecture ``` ┌─────────────────────────────────────────────────────┐ │ OpenSpeak Server │ ├─────────────────────────────────────────────────────┤ │ gRPC Server (Port 50051) │ │ ┌──────────────────────────────────────────────┐ │ │ │ Authentication Interceptor │ │ │ └────────────────────────────────────────────┬─┘ │ │ │ │ │ ┌─────────────────┬─────────────┬─────────────┴─┐ │ │ ▼ ▼ ▼ ▼ │ │ Auth Service Channel Service Presence Service Voice │ │ Manager Manager Service │ │ │ │ ┌──────────────────────────────────────────────┐ │ │ │ State Management Layer │ │ │ │ • Users & Sessions │ │ │ │ • Channels & Members │ │ │ │ • Presence Data │ │ │ │ • Voice Streams │ │ │ └──────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────┐ │ │ │ Supporting Infrastructure │ │ │ │ • Logging │ │ │ │ • Configuration Management │ │ │ │ • Error Handling │ │ │ │ • Metrics/Monitoring │ │ │ └──────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────┘ ``` ### Package Structure ``` openspeak/ ├── cmd/ │ └── openspeak-server/ │ └── main.go ├── internal/ │ ├── auth/ │ │ ├── token_manager.go │ │ ├── permission_checker.go │ │ └── auth_test.go │ ├── channel/ │ │ ├── manager.go │ │ ├── channel.go │ │ ├── store.go │ │ └── channel_test.go │ ├── presence/ │ │ ├── manager.go │ │ ├── session.go │ │ ├── event_broadcaster.go │ │ └── presence_test.go │ ├── voice/ │ │ ├── router.go │ │ ├── stream.go │ │ ├── packet.go │ │ └── voice_test.go │ ├── config/ │ │ └── config.go │ ├── logger/ │ │ └── logger.go │ └── grpc/ │ ├── server.go │ ├── auth_interceptor.go │ └── handlers/ │ ├── auth_handler.go │ ├── channel_handler.go │ ├── presence_handler.go │ └── voice_handler.go ├── proto/ │ ├── auth.proto │ ├── channel.proto │ ├── presence.proto │ ├── voice.proto │ └── common.proto ├── config/ │ └── config.yaml └── go.mod ``` ## Server Components ### 1. Authentication Manager **File:** `internal/auth/token_manager.go` **Responsibilities:** - Load admin tokens from configuration - Validate tokens on each request - Check token expiration - Manage token rotation (future) - Audit authentication attempts **Interface:** ```go type TokenManager interface { ValidateToken(ctx context.Context, token string) (*TokenInfo, error) RevokeToken(token string) error ListTokens() []*TokenInfo } ``` ### 2. Channel Manager **File:** `internal/channel/manager.go` **Responsibilities:** - Create/delete channels - Manage channel state - Enforce permission rules - Broadcast channel events - Track channel members - Clean up empty channels **Data Structure:** ```go type Manager struct { channels map[string]*Channel mu sync.RWMutex events chan ChannelEvent } ``` ### 3. Presence Manager **File:** `internal/presence/manager.go` **Responsibilities:** - Track user sessions - Manage presence status - Detect idle users - Handle disconnections - Broadcast presence events - Maintain online user list **Key Methods:** ```go type Manager interface { CreateSession(userID string) *Session EndSession(userID string) error UpdatePresence(userID string, status Status) error GetOnlineUsers() []*UserPresence GetChannelMembers(channelID string) []*UserPresence } ``` ### 4. Voice Router **File:** `internal/voice/router.go` **Responsibilities:** - Receive voice packets from clients - Route to appropriate channel - Broadcast to channel members - Handle packet buffering - Drop outdated packets - Monitor stream quality **Packet Flow:** ```go type VoiceRouter interface { PublishVoicePacket(clientID, channelID string, packet *VoicePacket) error SubscribeToChannel(clientID, channelID string) (<-chan *VoicePacket, error) UnsubscribeFromChannel(clientID, channelID string) error } ``` ### 5. gRPC Server **File:** `internal/grpc/server.go` **Responsibilities:** - Manage gRPC server lifecycle - Register service implementations - Handle client connections - Apply authentication interceptor - Handle connection timeouts **Port:** 50051 (configurable) **TLS:** Required for production (configurable for dev) ### 6. Configuration Manager **File:** `internal/config/config.go` **Loads from:** - Environment variables (takes precedence) - `config/config.yaml` - Command-line flags - Defaults in code **Configuration Items:** ```go type Config struct { Server struct { Host string Port int TLSCert string TLSKey string } Auth struct { TokensFile string TokenTTL time.Duration } Audio struct { DefaultBitrate int JitterBuffer int } Logging struct { Level string OutputFormat string } } ``` ### 7. Logging System **File:** `internal/logger/logger.go` **Features:** - Structured logging - Configurable log level (debug, info, warn, error) - File and stdout output - Request ID correlation - Performance metrics logging **Usage:** ```go logger.Info("User connected", "user_id", userID, "channel_id", channelID) logger.Error("Voice routing failed", "error", err, "packet_id", packetID) ``` ## Concurrency Model ### Goroutine Strategy - **Per-Connection Handler:** One goroutine per client connection - Handles incoming RPC requests - Listens for outgoing events - Cleanup on disconnect - **Voice Broadcasting:** One goroutine per channel (future optimization) - Aggregates voice packets - Broadcasts to subscribers - **Presence Tracker:** Background goroutine - Checks for idle users every 30 seconds - Detects stale connections - Updates presence status ### Channel-Based Communication - Unbuffered channels for request/response - Buffered channels for event broadcasting - Select statements for event handling ### Locks & Synchronization ```go // Read-heavy, so use RWMutex for channel/user maps channels map[string]*Channel mu sync.RWMutex // Voice packets: channel-based, no explicit locks voiceChannels map[string]chan *VoicePacket ``` ## Error Handling ### Server-Level Errors ```go const ( ErrUnauthorized = "unauthorized" ErrInvalidRequest = "invalid_request" ErrChannelNotFound = "channel_not_found" ErrChannelFull = "channel_full" ErrUserNotFound = "user_not_found" ErrInternalError = "internal_error" ) ``` ### Error Propagation - Validation errors: Return immediately to client - Internal errors: Log details, return generic message to client - Voice errors: Log, skip packet, continue - Connection errors: Graceful cleanup, retry for client ## Metrics & Monitoring ### Server Metrics (Future) - Connected users count - Active channels count - Voice packets per second - Average latency - Memory usage - CPU usage ### Logging Points - User connection/disconnection - Channel creation/deletion - Authentication failures - Voice packet routing errors - Presence status changes - Server startup/shutdown ## Shutdown Procedure ``` Receive shutdown signal ↓ Set graceful shutdown mode ↓ Stop accepting new connections ↓ Wait up to 30 seconds for active connections to close ↓ Force close remaining connections ↓ Cleanup resources ↓ Exit ``` ## Scalability Considerations (Future) - Horizontal scaling: Multiple server instances with load balancer - Message queue for voice packets (Redis/RabbitMQ) - Distributed session storage (Redis) - Database for persistent data - Voice stream optimization (SFU pattern, not broadcast) ## Configuration Example ```yaml server: host: 0.0.0.0 port: 50051 tls_cert: "" # Empty = no TLS for development tls_key: "" auth: tokens_file: /etc/openspeak/admin_tokens.json token_ttl: 0 # 0 = no expiration audio: default_bitrate: 64 jitter_buffer_ms: 50 logging: level: info output_format: json output_file: /var/log/openspeak/server.log voice: max_broadcast_lag_ms: 100 max_packet_age_ms: 500 ``` ## Testing Strategy - Unit tests for each manager component - Integration tests for gRPC handlers - Concurrency tests with multiple clients - Voice packet loss simulation tests - Connection timeout and cleanup tests - Performance benchmarks for voice routing - Load tests with high concurrency