mud_server.api.routes
=====================

.. py:module:: mud_server.api.routes

.. autoapi-nested-parse::

   API route definitions for the MUD server.

   This module defines all HTTP API endpoints using FastAPI. The routes are organized
   into several categories:

   Public Endpoints (No Authentication):
       - GET / - Root endpoint
       - POST /login - User login with password
       - POST /register - New account registration

   Authenticated Endpoints (Require Session):
       - POST /logout - User logout
       - POST /command - Execute game commands (movement, chat, inventory, etc.)
       - GET /chat/{session_id} - Get room chat messages
       - GET /status/{session_id} - Get player status
       - POST /change-password - Change current user's password

   Admin Endpoints (Require Specific Permissions):
       - GET /admin/database/players - View all players (VIEW_LOGS)
       - GET /admin/database/sessions - View all sessions (VIEW_LOGS)
       - GET /admin/database/chat-messages - View all chat (VIEW_LOGS)
       - POST /admin/user/manage - Manage users (MANAGE_USERS)
       - POST /admin/server/stop - Stop server (STOP_SERVER)

   Health Check:
       - GET /health - Server health status

   Command Parsing:
       Commands can be sent with or without "/" prefix. The following commands are supported:
       - Movement: north/n, south/s, east/e, west/w
       - Actions: look/l, inventory/inv/i, get/take <item>, drop <item>
       - Chat: say <message>, yell <message>, whisper/w <player> <message>
       - Info: who, help/?

   Design Notes:
       - All routes use Pydantic models for request/response validation
       - Sessions validated at start of each protected endpoint
       - Errors raised as HTTPException with appropriate status codes
       - Game logic delegated to GameEngine class
       - All database operations through database module



Functions
---------

.. autoapisummary::

   mud_server.api.routes.register_routes


Module Contents
---------------

.. py:function:: register_routes(app, engine)

   Register all API routes with the FastAPI app.

   This function is called once at server startup to register all endpoints.
   It creates closures over the app and engine instances so routes can access
   the game engine.

   :param app: FastAPI application instance
   :param engine: GameEngine instance for game logic