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 — all driven by a single config.yaml.

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

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 → per-app middleware (session, cache, ...)
    → handler(**query) → Response → ASGI send

Installation

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

Quick Start

from genro_asgi import AsgiServer

server = AsgiServer(server_dir=".")
server.run()  # Starts uvicorn, reads config.yaml

Contents

Architecture

API Reference

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

License

Licensed under the Apache License, Version 2.0.