mud_server.config

Server configuration management.

This module handles loading and accessing server configuration from multiple sources with a clear priority order:

1. Environment variables (highest priority) - for containerized deployments

2. Config file (config/server.ini) - for static deployments

3. Built-in defaults (lowest priority) - sensible fallbacks

Configuration is loaded once at module import time and cached. The ServerConfig dataclass provides typed access to all settings.

Usage:

from mud_server.config import config

# Access settings print(config.server.host) print(config.security.cors_origins) print(config.is_production)

Environment Variable Mapping:

MUD_HOST -> server.host MUD_PORT -> server.port MUD_PRODUCTION -> security.production MUD_CORS_ORIGINS -> security.cors_origins MUD_DB_PATH -> database.path MUD_LOG_LEVEL -> logging.level MUD_SESSION_TTL_MINUTES -> session.ttl_minutes MUD_SESSION_SLIDING_EXPIRATION -> session.sliding_expiration MUD_SESSION_ALLOW_MULTIPLE -> session.allow_multiple_sessions MUD_SESSION_ACTIVE_WINDOW_MINUTES -> session.active_window_minutes MUD_CHAR_DEFAULT_SLOTS -> characters.default_slots MUD_CHAR_MAX_SLOTS -> characters.max_slots MUD_ENTITY_STATE_ENABLED -> integrations.entity_state_enabled MUD_ENTITY_STATE_BASE_URL -> integrations.entity_state_base_url MUD_ENTITY_STATE_TIMEOUT_SECONDS -> integrations.entity_state_timeout_seconds MUD_ENTITY_STATE_INCLUDE_PROMPTS -> integrations.entity_state_include_prompts MUD_NAMEGEN_ENABLED -> integrations.namegen_enabled MUD_NAMEGEN_BASE_URL -> integrations.namegen_base_url MUD_NAMEGEN_TIMEOUT_SECONDS -> integrations.namegen_timeout_seconds MUD_REGISTRATION_MODE -> registration.account_registration_mode MUD_GUEST_REGISTRATION_ENABLED -> registration.guest_registration_enabled MUD_PLAYER_SELF_CREATE_ENABLED -> character_creation.player_self_create_enabled MUD_CHAR_CREATE_DEFAULT_MODE -> character_creation.default_creation_mode MUD_CHAR_CREATE_DEFAULT_NAMING -> character_creation.default_naming_mode MUD_CHAR_CREATE_DEFAULT_SLOT_LIMIT -> character_creation.default_world_slot_limit MUD_TRANSLATION_ENABLED -> ollama_translation.enabled MUD_TRANSLATION_OLLAMA_URL -> ollama_translation.base_url MUD_TRANSLATION_TIMEOUT -> ollama_translation.timeout_seconds

Attributes

PROJECT_ROOT
CONFIG_DIR
CONFIG_FILE
CONFIG_EXAMPLE
config

Classes

ServerSettings	Network server configuration.
SecuritySettings	Security-related configuration.
SessionSettings	Session management configuration.
DatabaseSettings	Database configuration.
LoggingSettings	Logging configuration.
RateLimitSettings	Rate limiting configuration.
CharacterSettings	Character slot limits and defaults.
RegistrationSettings	Account-registration policy controls.
WorldCharacterPolicy	Character-creation policy for a specific world.
CharacterCreationSettings	Global character-creation policy and world-level overrides.
FeatureSettings	Feature flags.
WorldSettings	Multi-world configuration settings.
IntegrationSettings	Optional integration settings for provisioning and name generation.
OllamaTranslationSettings	Server-level controls for the OOC→IC translation layer.
ServerConfig	Complete server configuration.
use_test_database	Context manager for using a temporary test database.

Functions

load_config()	Load configuration from all sources with proper priority.
reload_config()	Reload configuration from disk and environment.
get_config_status()	Get configuration status for diagnostics.
print_config_summary(*[, resolved_host, resolved_port])	Print a summary of current configuration to stdout.

Module Contents

mud_server.config.PROJECT_ROOT

mud_server.config.CONFIG_DIR

mud_server.config.CONFIG_FILE

mud_server.config.CONFIG_EXAMPLE

class mud_server.config.ServerSettings

Network server configuration.

host: str = '0.0.0.0'

port: int = 8000

class mud_server.config.SecuritySettings

Security-related configuration.

production: bool = False

cors_origins: list[str] = ['http://localhost:7860']

cors_allow_credentials: bool = True

cors_allow_methods: list[str] = ['*']

cors_allow_headers: list[str] = ['*']

docs_enabled: Literal['auto', 'enabled', 'disabled'] = 'auto'

class mud_server.config.SessionSettings

Session management configuration.

ttl_minutes: int = 480

sliding_expiration: bool = True

allow_multiple_sessions: bool = False

active_window_minutes: int = 30

class mud_server.config.DatabaseSettings

Database configuration.

path: str = 'data/mud.db'

property absolute_path: pathlib.Path

Get absolute path to database file.

class mud_server.config.LoggingSettings

Logging configuration.

level: str = 'INFO'

format: Literal['simple', 'detailed', 'json'] = 'detailed'

class mud_server.config.RateLimitSettings

Rate limiting configuration.

enabled: bool = False

login_per_minute: int = 5

register_per_minute: int = 5

api_per_second: int = 30

class mud_server.config.CharacterSettings

Character slot limits and defaults.

default_slots: int = 2

max_slots: int = 10

class mud_server.config.RegistrationSettings

Account-registration policy controls.

account_registration_mode: Literal['open', 'closed'] = 'open'

guest_registration_enabled: bool = True

class mud_server.config.WorldCharacterPolicy

Character-creation policy for a specific world.

creation_mode

open allows account holders to self-create in the world. invite requires explicit world permission.

naming_mode

generated means the server mints names. manual is currently reserved for admin/superuser workflows.

slot_limit_per_account

Maximum characters an account may own in this world.

creation_mode: Literal['open', 'invite'] = 'invite'

naming_mode: Literal['generated', 'manual'] = 'generated'

slot_limit_per_account: int = 10

class mud_server.config.CharacterCreationSettings

Global character-creation policy and world-level overrides.

The defaults define baseline behavior for all worlds. Per-world sections in INI ([world_policy.<world_id>]) can override individual fields.

player_self_create_enabled: bool = True

default_creation_mode: Literal['open', 'invite'] = 'invite'

default_naming_mode: Literal['generated', 'manual'] = 'generated'

default_world_slot_limit: int = 10

world_policy_overrides: dict[str, WorldCharacterPolicy]

resolve_world_policy(world_id)

Resolve effective character policy for world_id.

Resolution order:

1. [world_policy.<world_id>] override

2. Global defaults from [character_creation]

class mud_server.config.FeatureSettings

Feature flags.

ollama_enabled: bool = True

verbose_errors: bool = False

class mud_server.config.WorldSettings

Multi-world configuration settings.

worlds_root: str = 'data/worlds'

default_world_id: str = 'pipeworks_web'

allow_multi_world_characters: bool = False

class mud_server.config.IntegrationSettings

Optional integration settings for provisioning and name generation.

entity_state_enabled: bool = True

entity_state_base_url: str = 'https://entity-state-api.luminal.local'

entity_state_timeout_seconds: float = 3.0

entity_state_include_prompts: bool = False

namegen_enabled: bool = True

namegen_base_url: str = 'https://namegen-api.luminal.local'

namegen_timeout_seconds: float = 3.0

class mud_server.config.OllamaTranslationSettings

Server-level controls for the OOC→IC translation layer.

Acts as the master switch and provides server-wide defaults. Per-world config in world.json is checked second; both must be enabled for translation to activate.

enabled: bool = True

base_url: str = 'http://localhost:11434'

timeout_seconds: float = 10.0

class mud_server.config.ServerConfig

Complete server configuration.

This is the main configuration object that aggregates all settings sections. Access via the module-level config singleton.

server: ServerSettings

security: SecuritySettings

session: SessionSettings

database: DatabaseSettings

logging: LoggingSettings

rate_limit: RateLimitSettings

characters: CharacterSettings

registration: RegistrationSettings

character_creation: CharacterCreationSettings

features: FeatureSettings

worlds: WorldSettings

integrations: IntegrationSettings

ollama_translation: OllamaTranslationSettings

property is_production: bool

Convenience property for production mode check.

property docs_should_be_enabled: bool

Determine if API docs should be enabled based on settings.

resolve_world_character_policy(world_id)

Resolve world-level character-creation policy for world_id.

mud_server.config.load_config()

Load configuration from all sources with proper priority.

Priority (highest wins):

1. Environment variables

2. config/server.ini

3. config/server.example.ini (fallback for development)

4. Built-in defaults

Returns:

Fully populated configuration object.

Return type:

ServerConfig

mud_server.config.reload_config()

Reload configuration from disk and environment.

This updates the module-level config singleton. Use sparingly as it doesn’t update already-running server middleware.

Returns:

The newly loaded configuration.

Return type:

ServerConfig

mud_server.config.config

mud_server.config.get_config_status()

Get configuration status for diagnostics.

Returns a dictionary with configuration source information, useful for debugging and admin dashboards.

mud_server.config.print_config_summary(*, resolved_host=None, resolved_port=None)

Print a summary of current configuration to stdout.

class mud_server.config.use_test_database(db_path)

Context manager for using a temporary test database.

This is the recommended way to set up test databases. It properly configures the config system to use a temporary database path.

Usage:

from mud_server.config import use_test_database

def test_something(tmp_path):

db_path = tmp_path / “test.db” with use_test_database(db_path):

# Database operations will use db_path database.init_database()

Parameters:

db_path (pathlib.Path | str) – Path to the test database file

db_path

original_path: str | None = None