Server

Core ASGI server classes.

AsgiServer

ASGI Server - main entry point for genro-asgi applications.

Classes:

AsgiServer – central coordinator: loads config (YAML), mounts apps,

builds middleware chain, handles lifespan, routes via genro-routes Router.

Inherits BasicAuthMixin and RoutingClass. Run with AsgiServer(server_dir).run().

WebSocket connections are handled by WsxHandler (WSX protocol over WebSocket).

class genro_asgi.server.server.AsgiServer(server_dir=None, host=None, port=None, reload=None, argv=None, parent=None)

Bases: BasicAuthMixin, RoutingClass

Base ASGI server with routing via genro_routes.

config

ServerConfig for configuration.

router

genro_routes Router for dispatch.

dispatcher

Dispatcher handling request routing.

lifespan

ServerLifespan for startup/shutdown.

server_application

ServerApplication with system endpoints.

sys_apps

Dict for system apps (mounted at /_sys/).

apps

Dict for user apps.

logger

Server logger instance.

request_registry

RequestRegistry for tracking requests.

request

Current request (from ContextVar).

response

Current response builder.

__init__(server_dir=None, host=None, port=None, reload=None, argv=None, parent=None)

Initialize AsgiServer.

Composes BasicAuthMixin (auth) and RoutingClass (routing). Loads config, builds middleware chain, mounts apps.

Parameters:

• server_dir (str | Path | None) – Path to server directory with config.yaml.

• host (str | None) – Override host from config.

• port (int | None) – Override port from config.

• reload (bool | None) – Override reload from config.

• argv (list[str] | None) – CLI arguments for config override.

• parent (Any) – Optional parent object with shared resources and logic.

app_loader

app_middleware_chains: dict[str, Any]

apply_persisted_config()

Apply plugin_config.json to the current router tree.

Called at boot after plugins are attached.

Return type:

None

apps: dict[str, RoutingClass]

base_dir: Path

config

create_session(auth=None)

Create a new session in the session store.

Parameters:

auth (dict[str, Any] | None) – Auth dict snapshot to store in session.

Return type:

Session

Returns:

New Session instance with unique token.

property db: Any

Default database (shortcut for get_db(“default”)).

db_registry: dict[str, Any]

dispatcher

get_db(name)

Return a registered database by name.

Parameters:

name (str) – Logical name used in register_db().

Raises:

KeyError – If no database registered with that name.

Return type:

Any

get_plugin_config(router_path='', entry='')

Read live plugin configuration for a router/entry.

Uses routing.configure(“?”) for introspection via genro-routes public API.

Parameters:

• router_path (str) – Slash-separated path to the router (empty = all).

• entry (str) – Specific entry/handler name to filter (empty = all).

Return type:

dict[str, Any]

Returns:

Dict with router_path, plugin_info. Error dict if router not found.

lifespan

logger

mount(name, app)

Mount an application on the server.

Parameters:

• name (str) – Mount name (becomes the URL prefix).

• app (Any) – Application instance (AsgiApplication or RoutingClass).

Return type:

None

openapi_info: dict[str, Any]

parent

property plugin_config_file: Path

Path to plugin_config.json in server_dir.

register_db(name, db)

Register a database connection in the registry.

Parameters:

• name (str) – Logical name for this database (e.g. “sourcerer”, “default”).

• db (Any) – Database connection or pool object.

Return type:

None

property request: BaseRequest | None

Current request from registry.

request_registry

resource_loader

property response: Response | None

Current response from request.

revert_plugin_config()

Revert runtime config to what is saved in plugin_config.json.

Returns:

True. Includes “message” if no saved config exists.

Return type:

dict[str, Any]

router

run()

Run the server using Uvicorn.

Return type:

None

save_plugin_config()

Persist current runtime plugin config to plugin_config.json.

Uses routing.configure(“?”) to snapshot the full tree via genro-routes public API.

Returns:

True and “file” path on success.

Return type:

dict[str, Any]

server_application

session_store

set_plugin_config(router_path='', plugin_name='', target='_all_', **config_values)

Apply a plugin config change at runtime without persisting.

Delegates to routing.configure() via genro-routes public API.

Parameters:

• router_path (str) – Slash-separated path to the router (empty = root).

• plugin_name (str) – Name of the plugin to configure.

• target (str) – Target slot (“_all_” or specific entry name).

• **config_values (Any) – Plugin configuration key-value pairs.

Returns:

True on success, or “error” key on failure.

Return type:

dict[str, Any]

storage

sys_apps: dict[str, RoutingClass]

wsgi_app: Any

wsx_handler

ServerConfig

Server configuration - handles all config loading and app instantiation.

class genro_asgi.server.server_config.ServerConfig(server_dir=None, host=None, port=None, reload=None, argv=None)

Bases: object

Handles server configuration loading and app instantiation.

__init__(server_dir=None, host=None, port=None, reload=None, argv=None)

Build merged configuration from YAML file, env vars, and overrides.

Parameters:

• server_dir (str | Path | None) – Directory containing config.yaml. Defaults to cwd.

• host (str | None) – Override for server host (takes precedence over YAML).

• port (int | None) – Override for server port (takes precedence over YAML).

• reload (bool | None) – Override for uvicorn reload flag.

• argv (list[str] | None) – Command-line arguments for additional overrides.

property apps: SmartOptions | None

Apps configuration.

get_app_specs_raw()

Return {name: (module_name, class_name, middleware_config, kwargs)} for all apps.

Returns raw config data without importing. Server uses AppLoader to import.

Return type:

dict[str, tuple[str, str, dict[str, Any] | None, dict[str, Any]]]

get_plugin_specs()

Return {plugin_name: opts_dict} for all configured plugins.

Return type:

dict[str, dict[str, Any]]

get_sys_app_specs_raw()

Return {name: (module_name, class_name, middleware_config, kwargs)} for system apps.

Same format as get_app_specs_raw but for sys_apps config section.

Return type:

dict[str, tuple[str, str, dict[str, Any] | None, dict[str, Any]]]

property middleware: list[Any]

Middleware configuration list.

property openapi: dict[str, Any]

OpenAPI info as plain dict.

property plugins: SmartOptions | None

Plugins configuration.

property server: SmartOptions

Server options (host, port, reload, server_dir).

property server_dir: Path

Return resolved server directory path.

property sys_apps: SmartOptions | None

System apps configuration.