Skip to content

DEPRECATION NOTICE

This implementation plan has been completed. The checkboxes below were not updated during implementation and do not reflect current status. Please refer to the actual codebase for the current implementation state. Key implemented features include:

  • SSL/TLS Support (packages/maid-engine/src/maid_engine/net/ssl_context.py)
  • HTTPS Redirect Middleware (packages/maid-engine/src/maid_engine/net/web/server.py - _add_https_redirect_middleware())
  • External Bridges (packages/maid-engine/src/maid_engine/bridges/)
  • REST API v1 (packages/maid-engine/src/maid_engine/api/v1/)
  • API Authentication (packages/maid-engine/src/maid_engine/api/auth.py)
  • RSS Feed (packages/maid-engine/src/maid_engine/bridges/rss_feed.py)

Network Protocol Enhancements - Implementation Plan

Summary

This plan implements three major network layer enhancements to achieve feature parity with Evennia:

  1. SSL/TLS Support - Encrypted connections for Telnet (TLS) and WebSocket (WSS/HTTPS), protecting player credentials and game data in transit
  2. External Service Bridges - Bidirectional integration with Discord, IRC, and RSS feeds for community engagement
  3. Enhanced REST API - Comprehensive API with authentication, rate limiting, player/world CRUD, and real-time event streaming

These features address gaps in secure connections, external service integration, and web API capabilities.

Phase 1: SSL/TLS Support (P0 - Foundation)

1.1 Configuration & Settings

  • [x] Add SSLSettings Pydantic model to packages/maid-engine/src/maid_engine/config/settings.py
  • Fields: enabled, cert_path, key_path, key_password, ca_path, min_version, verify_client, client_ca_path, ciphers
  • Path validators for certificate files
  • [x] Extend TelnetSettings with ssl: SSLSettings and ssl_port: int | None
  • [x] Extend WebSettings with ssl: SSLSettings, https_port: int | None, and redirect_http_to_https: bool
  • [x] Document environment variables in README/config docs (MAID_TELNET__SSL__*, MAID_WEB__SSL__*)

1.2 SSL Context Builder

  • [x] Create packages/maid-engine/src/maid_engine/net/ssl_context.py
  • [x] Implement SSLError exception class
  • [x] Implement SSLInfo dataclass for connection info (version, cipher, bits, client cert)
  • [x] Implement SSLContextBuilder.create_server_context() method
  • TLS version configuration (1.2/1.3 minimum)
  • Certificate chain loading
  • Client verification support
  • Cipher suite configuration
  • [x] Implement SSLContextBuilder.get_connection_info() for logging SSL details
  • [x] Implement CertificateReloader class for hot-reload support
  • File modification time tracking
  • Automatic context refresh on certificate change

1.3 Telnet Server Integration

  • [x] Modify packages/maid-engine/src/maid_engine/net/server.py
  • [x] Add CertificateReloader instance management
  • [x] Implement _start_telnet_servers() to start both plain and TLS servers
  • Depends on: 1.1, 1.2
  • [x] Modify _handle_telnet_connection() to detect and log TLS connections
  • [x] Add ssl_info attribute to TelnetSession

1.4 Web Server Integration

  • [x] Modify packages/maid-engine/src/maid_engine/net/web/server.py
  • [x] Update _create_uvicorn_config() to include SSL parameters
  • Depends on: 1.1
  • [x] Implement _add_https_redirect_middleware() using Starlette's HTTPSRedirectMiddleware

1.5 SSL Testing

  • [x] Unit tests for SSLContextBuilder (valid certs, invalid certs, missing files)
  • [x] Unit tests for CertificateReloader (file change detection, reload)
  • [x] Unit tests for settings validation (path existence, error messages)
  • [x] Integration test: Telnet+TLS with openssl s_client
  • [x] Integration test: WebSocket over HTTPS with browser
  • [x] Integration test: Mixed mode (plain + TLS simultaneously)

Phase 2: External Service Bridges (P0/P1 - Community Features)

2.1 Bridge Protocol & Manager

  • [x] Create packages/maid-engine/src/maid_engine/bridges/ package with __init__.py
  • [x] Create packages/maid-engine/src/maid_engine/bridges/protocol.py
  • [x] Implement BridgeState enum (DISCONNECTED, CONNECTING, CONNECTED, RECONNECTING, ERROR)
  • [x] Implement ExternalUser dataclass
  • [x] Implement BridgeMessage dataclass
  • [x] Implement ChannelMapping dataclass
  • [x] Implement ExternalBridge abstract base class
  • Properties: service_name
  • Methods: connect(), disconnect(), send_message(), send_embed(), on_message(), _dispatch_message()
  • [x] Implement BridgeManager class
  • Bridge registration and lifecycle
  • Channel mapping management
  • relay_to_external() method
  • _handle_external_message() method for incoming relay

2.2 Bridge Configuration

  • [x] Add DiscordBridgeSettings to settings.py
  • [x] Add IRCBridgeSettings to settings.py
  • [x] Add RSSFeedSettings to settings.py
  • [x] Add BridgeSettings composite model with channel_mappings
  • [x] Document environment variables (MAID_BRIDGES__DISCORD__*, MAID_BRIDGES__IRC__*, MAID_BRIDGES__RSS__*)

2.3 Discord Bridge

  • [x] Create packages/maid-engine/src/maid_engine/bridges/discord_bridge.py
  • [x] Implement DiscordBridgeConfig class
  • [x] Implement DiscordBridge class extending ExternalBridge
  • Depends on: 2.1
  • [x] Handle optional discord.py import with DISCORD_AVAILABLE flag
  • [x] Implement connect() with bot startup in background task
  • [x] Implement disconnect() with graceful shutdown
  • [x] Implement send_message() with markdown escaping
  • [x] Implement send_embed() for rich embeds
  • [x] Implement send_webhook() for one-way notifications (P1)
  • [x] Implement _on_ready(), _on_message(), _on_disconnect() event handlers
  • [x] Implement _strip_discord_formatting() for MUD display
  • [x] Handle Discord rate limits gracefully

2.4 IRC Bridge

  • [x] Create packages/maid-engine/src/maid_engine/bridges/irc_bridge.py
  • [x] Implement IRCBridgeConfig class
  • [x] Implement IRCBridge class extending ExternalBridge
  • Depends on: 2.1
  • [x] Handle optional irc3 import with IRC_AVAILABLE flag
  • [x] Implement connect() with bot startup
  • [x] Implement disconnect() with quit message
  • [x] Implement send_message() with message splitting (400 char limit)
  • [x] Implement send_embed() as formatted text (IRC has no embeds)
  • [x] Implement _handle_irc_message() for incoming messages
  • [x] Implement _split_message() utility
  • [x] Handle reconnection on disconnect

2.5 RSS Feed

  • [x] Create packages/maid-engine/src/maid_engine/bridges/rss_feed.py
  • [x] Implement FeedItem dataclass with auto-generated GUID
  • [x] Implement FeedConfig dataclass
  • [x] Implement RSSFeedManager class
  • add_item(), add_announcement(), add_world_event() methods
  • generate_rss() for RSS 2.0 XML
  • generate_atom() for Atom 1.0 XML (P1)
  • check_cache() for ETag/If-Modified-Since support
  • [x] Create create_rss_router() FastAPI router factory
  • /feeds/rss.xml endpoint
  • /feeds/atom.xml endpoint
  • Cache headers (ETag, Cache-Control)

2.6 Bridge Integration

  • [x] Integrate BridgeManager into GameEngine
  • [x] Add bridge startup to engine start() lifecycle
  • [x] Add bridge shutdown to engine stop() lifecycle
  • [x] Wire game channel events to relay_to_external()
  • [x] Register RSS router with web server
  • [x] Add optional dependencies to pyproject.toml: discord.py, irc3, aiohttp

2.7 Bridge Testing

  • [x] Unit tests for DiscordBridge (connection, message relay, formatting)
  • [x] Unit tests for IRCBridge (connection, message relay, splitting)
  • [x] Unit tests for RSSFeedManager (item add, feed generation, caching)
  • [x] Integration test: Discord full flow (game → Discord → game)
  • [x] Integration test: IRC full flow
  • [x] Validate RSS 2.0 and Atom 1.0 output with feed validators

Phase 3: Enhanced REST API (P0/P1 - Developer Platform)

3.1 API Authentication System

  • [x] Create packages/maid-engine/src/maid_engine/api/ package with __init__.py
  • [x] Create packages/maid-engine/src/maid_engine/api/auth.py
  • [x] Implement APIPermission enum (READ_PUBLIC, READ_PLAYERS, WRITE_PLAYERS, READ_WORLD, WRITE_WORLD, ADMIN)
  • [x] Implement APIKey dataclass
  • [x] Implement APIUser dataclass
  • [x] Implement APIKeyStore class
  • generate_key() with secure token generation
  • validate_key() with SHA-256 hash verification
  • revoke_key()
  • [x] Implement RateLimiter class with sliding window algorithm
  • [x] Create FastAPI dependencies: api_key_header, bearer_scheme
  • [x] Implement get_api_user() dependency
  • [x] Implement require_permission() dependency factory

3.2 API Router Structure

  • [x] Create packages/maid-engine/src/maid_engine/api/v1/ package
  • [x] Create packages/maid-engine/src/maid_engine/api/v1/__init__.py with router aggregation
  • [x] Wire v1 router to web server application

3.3 Players API

  • [x] Create packages/maid-engine/src/maid_engine/api/v1/players.py
  • Depends on: 3.1
  • [x] Implement Pydantic models: PlayerSummary, PlayerDetail, PlayerListResponse, PlayerUpdateRequest
  • [x] Implement GET /players with pagination, filtering, sorting
  • [x] Implement GET /players/{player_id} for detail view
  • [x] Implement PATCH /players/{player_id} for updates
  • [x] Implement POST /players/{player_id}/kick (ADMIN)
  • [x] Implement POST /players/{player_id}/ban (ADMIN)
  • [x] Implement DELETE /players/{player_id}/ban (ADMIN)

3.4 World API

  • [x] Create packages/maid-engine/src/maid_engine/api/v1/world.py
  • Depends on: 3.1
  • [x] Implement Pydantic models: RoomSummary, RoomDetail, NPCSummary, ItemSummary
  • [x] Implement GET /world/rooms with area filter and pagination
  • [x] Implement GET /world/rooms/{room_id} for detail view
  • [x] Implement GET /world/rooms/{room_id}/contents for players/NPCs/items
  • [x] Implement GET /world/npcs with filters
  • [x] Implement GET /world/items with filters
  • [x] Implement GET /world/areas for area listing

3.5 Statistics API

  • [x] Create packages/maid-engine/src/maid_engine/api/v1/stats.py
  • Depends on: 3.1
  • [x] Implement Pydantic models: ServerStats, PlayerStats, EconomyStats, CombatStats
  • [x] Implement GET /stats/server
  • [x] Implement GET /stats/players
  • [x] Implement GET /stats/economy
  • [x] Implement GET /stats/combat
  • [x] Implement GET /stats/commands (ADMIN)

3.6 Admin API

  • [x] Create packages/maid-engine/src/maid_engine/api/v1/admin.py
  • Depends on: 3.1
  • [x] Implement POST /admin/broadcast (extend existing)
  • [x] Implement POST /admin/shutdown
  • [x] Implement POST /admin/reload-config
  • [x] Implement GET /admin/api-keys for key management
  • [x] Implement POST /admin/api-keys for key generation
  • [x] Implement DELETE /admin/api-keys/{key_id} for revocation

3.7 Real-Time Events WebSocket

  • [x] Create packages/maid-engine/src/maid_engine/api/v1/events_ws.py
  • Depends on: 3.1
  • [x] Implement EventType enum
  • [x] Implement GameEvent Pydantic model
  • [x] Implement EventSubscription class
  • [x] Implement EventBroadcaster class
  • Subscription management
  • Event broadcasting to matching subscribers
  • Dead connection cleanup
  • [x] Implement @router.websocket("/events") endpoint
  • API key validation via query param
  • Event type filtering
  • Ping/pong keepalive
  • [x] Create create_event_hooks() to wire game events to broadcaster
  • [x] Integrate with GameEngine event system

3.8 API Documentation & Middleware

  • [x] Verify OpenAPI docs at /docs and /redoc
  • [x] Add API audit logging middleware
  • [x] Configure CORS for production (restrict origins)
  • [x] Add response time logging

3.9 API Testing

  • [x] Unit tests for APIKeyStore (generation, validation, expiration, revocation)
  • [x] Unit tests for RateLimiter (allow/deny, window sliding)
  • [x] Unit tests for permission dependencies
  • [x] Integration tests for player CRUD operations
  • [x] Integration tests for world query endpoints
  • [x] Integration tests for statistics endpoints
  • [x] Integration test for WebSocket event streaming
  • [x] Performance benchmarks (authentication < 5ms, rate limit < 0.1ms)

Phase 4: Integration & Documentation

4.1 CLI Commands

  • [x] Add maid api generate-key command for API key generation
  • [x] Add maid api list-keys command for viewing active keys
  • [x] Add maid api revoke-key command

4.2 Documentation

  • [x] Document SSL configuration in admin guide
  • [x] Document bridge setup (Discord, IRC, RSS) with examples
  • [x] Document REST API usage with examples
  • [x] Create API authentication guide
  • [x] Update CHANGELOG

4.3 Final Integration Testing

  • [x] End-to-end test: SSL + API + Bridges all enabled
  • [x] Performance test under load
  • [x] Security audit of all new endpoints
  • [x] Verify backward compatibility (all features disabled by default)

Dependencies Summary

Phase 1 (SSL):
  1.1 Settings → 1.2 SSL Context → 1.3 Telnet Integration
                                 → 1.4 Web Integration
                                 → 1.5 Testing

Phase 2 (Bridges):
  2.1 Protocol → 2.3 Discord Bridge
              → 2.4 IRC Bridge
              → 2.5 RSS Feed
  2.2 Config (parallel with 2.1)
  2.6 Integration (after 2.3, 2.4, 2.5)
  2.7 Testing (after 2.6)

Phase 3 (API):
  3.1 Auth → 3.2 Router → 3.3 Players API
                        → 3.4 World API
                        → 3.5 Stats API
                        → 3.6 Admin API
                        → 3.7 WebSocket Events
  3.8 Docs (parallel)
  3.9 Testing (after 3.3-3.7)

Phase 4: After all phases complete

Priority Legend

  • P0: Must have for MVP
  • P1: Should have, delivers significant value
  • P2: Nice to have, can defer

Estimated Effort

Phase Estimated Days Priority
Phase 1: SSL/TLS 3-4 days P0
Phase 2: Bridges 5-7 days P0/P1
Phase 3: REST API 5-7 days P0/P1
Phase 4: Integration 2-3 days P0
Total 15-21 days