Genro ASGI Documentation

Genro ASGI is a minimal ASGI server and application toolkit for building web services. It provides everything needed to run a production server: routing, authentication, sessions, middleware, static files, WebSocket, and MCP support — configured by a Python config.py builder recipe.

What it does

Serves web applications mounted on URL prefixes (/api/, /shop/, etc.)
Authenticates requests via bearer tokens, basic auth, or JWT — with O(1) lookup
Manages sessions with in-memory store, cookies, and user avatars (identity + Bag data)
Applies middleware globally (CORS, errors, auth) and per-app (session, cache)
Routes requests via genro-routes decorator-based router with auth tag filtering
Serves static files with StaticRouter and hierarchical resource loading
Handles WebSocket with the WSX extension protocol for structured messaging
Exposes MCP endpoints via McpApplication for AI tool integration
Configures plugins at runtime via the plugin_config web UI (mounted under /_sys/plugin_config/)

Architecture

The server is an instance with its own state — no global variables. Every component (apps, middleware, sessions) is an isolated instance connected via semantic parent-child references.

Request flow:

uvicorn → AsgiServer → global middleware (errors → cors → auth)
  → Dispatcher (demultiplex on first path segment)
    → app → per-app middleware (session, cache, ...)
      → handle_request → handler(**query) → Response → ASGI send

Installation

pip install genro-asgi            # core
pip install genro-asgi[json]      # + orjson for fast JSON

Quick Start

The server boots from a config.py whose ServerConfiguration (a subclass of AsgiConfigBuilder) is rendered onto it.

from genro_asgi import AsgiServer

server = AsgiServer("config.py")  # the config.py directory is the server dir
server.run()                      # starts uvicorn on the configured host/port

# config.py
from genro_asgi.config import AsgiConfigBuilder
from shop_app import Application as Shop

class ServerConfiguration(AsgiConfigBuilder):
    def main(self, root):
        root.server(host="127.0.0.1", port=8000)
        root.middleware(cors=True, auth=True)
        apps = root.applications(default="shop")
        apps.application(code="shop", app_class=Shop)

Contents

Architecture

API Reference

API Reference
- Server
- Authentication Mixin
- Dispatcher
- Request
- Response
- Session
- Applications
- Routers
- Middleware
- Executors
- Lifespan
- Storage
- Database
- Plugin Configuration
- Exceptions
- WebSocket
- WSX Protocol
- Types

License

Licensed under the Apache License, Version 2.0.