OpenSpeak/openspec/specs/006-server-core.md

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:

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:

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:

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:

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:

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:

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

// 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

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

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