genropy-asgi for Dummies

Up and Running in 2 Minutes

Install

# From the genro-asgi repository
pip install -e /path/to/genro-asgi
pip install -e /path/to/genro-asgi/contrib/genropy_asgi

This gives you the gnrasgiserve command. GenroPy must already be installed and configured (~/.gnr/environment.xml must exist).

Run your site

# Exactly like gnrwsgiserve — same name, same options
gnrasgiserve mysite

Open http://localhost:8080/index in your browser. That's it. Your site is running on ASGI.

Common variations

# Custom port
gnrasgiserve mysite -p 9000

# Auto-reload on file changes (development)
gnrasgiserve mysite --reload

# Open browser automatically
gnrasgiserve mysite -o

# Remote database (via gnrdaemon SSH tunnel)
gnrasgiserve mysite --remotedb myremote

# All together
gnrasgiserve mysite -p 9000 --reload -o

Verify it works

# Your GenroPy pages
curl http://localhost:8080/index

# Server meta endpoint (new, ASGI-native)
curl http://localhost:8080/_server/info

Core Concepts

genropy-asgi has three moving parts. Understanding how they connect is all you need.

The two worlds

The gateway is transparent. GenroPy never knows it's running behind ASGI. It receives a standard WSGI environ dict and returns a standard WSGI response. The conversion happens entirely inside the middleware.

gnrasgiserve Command Reference

The command-line interface is a drop-in replacement for gnrwsgiserve. If you've used the GenroPy development server before, you already know how to use it.

gnrasgiserve <site_name> [options]

All options

Option resolution order

When the same option is set in multiple places, the highest priority wins:

1. CLI arguments         # -p 9000
2. Environment variables  # GNR_WSGI_OPT_port=9000
3. Site siteconfig        # wsgi?port in siteconfig.xml
4. Defaults               # host=0.0.0.0, port=8080, debug=true

Remote database

To develop locally while connecting to a remote database (e.g. production on Hetzner):

# gnrdaemon must be running (it creates the SSH tunnel)
gnrasgiserve mysite --remotedb myremote

The remote DB must be configured in ~/.gnr/instanceconfig/default.xml:

<GenRoBag>
    <remote_db>
        <myremote ssh_host="1.2.3.4" ssh_user="root"
                  host="127.0.0.1" port="5432"
                  dbname="mydb" user="dbuser"
                  password="secret"/>
    </remote_db>
</GenRoBag>

Environment variable shortcut

# Set once, then omit the site name
export GNR_CURRENT_SITE=mysite
gnrasgiserve          # uses "mysite"

Configuration

genropy-asgi supports two modes: CLI mode (gnrasgiserve, for existing GenroPy sites) and config.yaml mode (for new ASGI-native projects with GenroPy databases).

CLI mode (gnrasgiserve)

No config.yaml needed. The command reads your existing GenroPy configuration (~/.gnr/environment.xml, siteconfig) exactly like gnrwsgiserve.

gnrasgiserve mysite -p 9000

Config.yaml mode (GenropyAsgiServer)

When building a project that combines GenroPy databases with ASGI-native apps (REST APIs, MCP endpoints), use config.yaml:

# config.yaml
server:
  host: "0.0.0.0"
  port: 8082

databases:
  default:
    genropy_app: "sourcerer"    # creates GnrApp("sourcerer")
  analytics:
    genropy_app: "analytics"    # second database

middleware:
  cors: on
  errors: on

apps:
  api:
    module: "my_project.api:MyAPI"
    db_name: default
    docs: swagger

Minimal Python script

# run.py — fully declarative, config.yaml does everything
from genropy_asgi import GenropyAsgiServer

server = GenropyAsgiServer(server_dir=".")
server.run()

databases section reference

Each key under databases becomes a name in the server's db_registry. Apps access it via server.get_db("default") or request.db.

apps section — db_name

Declare which database an app uses:

apps:
  api:
    module: "my_project.api:MyAPI"
    db_name: default          # resolved from db_registry
    docs: swagger             # swagger | redoc | off

When request.db is accessed, it looks up the app's db_name in the registry.

The WSGI Gateway

This is the core innovation of genropy-asgi: a middleware that transparently bridges the WSGI and ASGI worlds. Understanding how it decides where to send requests helps you reason about your application's behavior.

Decision logic

What counts as an "ASGI prefix"

The gateway builds the list of ASGI prefixes lazily (once, on first request) by scanning:

• All mounted apps where app_protocol == "asgi"
• All children of the server's main router

If you mount an app named "api", then any request starting with /api/... goes to ASGI. Everything else goes to GenroPy.

ASGI → WSGI conversion

When a request goes to the WSGI side, the gateway:

# 1. Read the full request body from ASGI
body = await _read_body(receive)

# 2. Build a PEP 3333 environ dict
environ = _build_environ(scope, body)
#   REQUEST_METHOD, PATH_INFO, QUERY_STRING,
#   SERVER_NAME/PORT, wsgi.input, HTTP_* headers...

# 3. Run the WSGI callable in a thread (non-blocking)
status, headers, body = await smartasync(_run_wsgi)(wsgi_app, environ)

# 4. Send ASGI response
await send({"type": "http.response.start", ...})
await send({"type": "http.response.body", ...})

Database Integration

When you need GenroPy's GnrApp database in your ASGI apps (REST APIs, MCP endpoints), GenropyAsgiServer handles the setup.

How it flows

Three ways to access the database

Script mode (no config.yaml)

from gnr.app.gnrapp import GnrApp
from genro_asgi import AsgiServer, OpenApiApplication
from my_project.api import MyAPI

gnr_app = GnrApp("myapp")
api = MyAPI(gnr_app.db)

server = AsgiServer()
app = OpenApiApplication(routing_class=api, docs="swagger")
server.mount("api", app)
server.run()

Config mode (recommended)

# config.yaml handles database creation
from genropy_asgi import GenropyAsgiServer

server = GenropyAsgiServer(server_dir=".")
server.run()  # databases, apps, middleware all from config

Multiple databases

databases:
  main:
    genropy_app: "myapp"
  reporting:
    genropy_app: "reports"

apps:
  api:
    module: "my_project.api:MyAPI"
    db_name: main
  reports:
    module: "my_project.reports:ReportsAPI"
    db_name: reporting

Advanced Usage

GenropyProxy — mount GenroPy on a prefix

If you don't want GenroPy at root but on a specific path (e.g. /legacy/), use GenropyProxy as a mountable ASGI application:

from genropy_asgi.genropy_proxy import GenropyProxy
from genro_asgi import AsgiServer

server = AsgiServer()

# Mount GenroPy site on /legacy/
proxy = GenropyProxy(site_name="mysite")
server.mount("legacy", proxy)

# Mount your ASGI API on /api/
server.mount("api", my_api_app)

server.run()

GenropyProxy sets app_protocol = "wsgi", so the gateway knows not to intercept requests for it.

Subclassing GenropyAsgiServer

For project-specific needs (custom auth, shared resources):

from genropy_asgi import GenropyAsgiServer

class MyServer(GenropyAsgiServer):
    __slots__ = ("api_key",)

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.api_key = self._load_api_key()

    def authenticate(self, scope):
        # Custom auth using GenroPy database
        db = self.get_db("default")
        token = extract_token(scope)
        return validate(db, token)

Startup flow internals

Cheat Sheet

I want to…

Architecture at a glance

Files at a glance

Troubleshooting