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
------------

.. code-block:: bash

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

Quick Start
-----------

.. code-block:: python

   from genro_asgi import AsgiServer

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

Contents
--------

.. toctree::
   :maxdepth: 2
   :caption: Architecture

   architecture/00-overview
   architecture/01-server
   architecture/02-request-system
   architecture/03-response-system
   architecture/04-executors
   architecture/05-lifespan
   architecture/06-wsx-protocol
   architecture/07-streaming
   architecture/08-routing
   architecture/09-auth-context

.. toctree::
   :maxdepth: 2
   :caption: API Reference

   api/index

License
-------

Copyright 2025-2026 Softwell S.r.l.

Licensed under the Apache License, Version 2.0.

Indices and tables
------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`