genropy-asgi for Dummies

Quick Start

Install

pip install genropy-asgi                              # from PyPI
pip install git+https://github.com/genropy/genropy-asgi.git  # latest from GitHub

genro-asgi is pulled in automatically. GenroPy itself must be installed and configured at runtime (the usual ~/.gnr/environment.xml plus an existing site) — genropy-asgi runs your site, it does not create one.

Run your site (single process)

gnrasgiserve mysite # the same instance name you use with gnrwsgiserve
# → site on http://0.0.0.0:8080/index

That is the whole drop-in. Your site now runs on uvicorn. Common options:

gnrasgiserve mysite -p 9000              # a different port
gnrasgiserve mysite -H 127.0.0.1 -p 9000 # host + port
gnrasgiserve mysite --reload             # auto-restart on file changes
gnrasgiserve mysite --nodebug            # debug off

Run it as a pool

gnrasgiserve mysite --workers 2 -p 8080

Same command, one extra flag. Now a commander routes each user to a stable worker and the pool grows under load.

The "aha": watch it live

The server exposes a JSON snapshot of the pool. Curl it and you see the workers, their status and how many users each holds:

curl -s http://127.0.0.1:8080/_server/monitor_state | python3 -m json.tool

"workers": [
  {"id": "default_01", "status": "running", "users": 5},
  {"id": "default_02", "status": "running", "users": 6},
  {"id": "default_03", "status": "running", "users": 4}
]

Single vs. Pool

genropy-asgi has two shapes, chosen at launch. Here is exactly how they differ.

One process hosts the site and is the commander of itself. Right for development, for a handful of concurrent users, and as the exact drop-in for gnrwsgiserve. Simple to run, simple to debug.

A commander supervises N worker processes, each hosting the same site with its own in-process register and its own thread pool. Because a synchronous GenroPy site saturates one process at a few users, running it in several processes multiplies throughput. Each user is pinned to one worker, so the session state that lives in that worker's register stays coherent.

How a request flows

No sticky_cid cookie yet (a fresh visitor)? The commander sends them to the welcome worker, which mints the cookie on first connection. From then on every request from that user lands on the same worker.

How the Pool Scales

The commander starts with the configured number of workers and grows the pool under load. Two rules govern it — both simpler than they sound.

Placement: fill the idle ones first

A just-logged-in user goes to the first worker with room. "Room" means strictly under the worker's user cap; a worker at cap is full. Idle workers fill before the pool ever grows.

Scaling: grow only when the whole group is full

The pool spawns a new worker only when every routable worker is at or above 80% of its cap — the group as a whole has no room. One hot worker with idle capacity elsewhere never triggers a spawn. A spawn already in flight is waited for, not stacked on top of another.

This is the observed behaviour of a real run: 15 distinct users settle onto three workers, not twelve. Idle workers fill before new ones spawn.

The one timing caveat

A fresh worker takes a few seconds to boot a full GnrWsgiSite. Under a genuine burst — many logins arriving faster than a worker can announce — the extra logins pile onto the last full worker until the new one is ready, then routing resumes. The commander deliberately never stacks a second spawn while one is in flight. At a realistic login rate the pool simply settles to the expected size.

Guests and the welcome worker

Not-yet-logged-in visitors are always served by the first worker of the default group — the welcome worker — which also mints the sticky_cid cookie. Because it carries guests too, its logged-user cap (max_users_first) is usually set lower than the others' (max_users_other).

Groups: Run Several Versions at Once

So far the pool has been one group of interchangeable workers. But a group is more than a pool — a group is a runtime. Each group declares its own Python interpreter, so different groups can run different versions of the same site side by side, behind one commander, on one address.

Declaring groups in the config

Groups are a groups child of the application. Each group has a code, a workers count, and an optional python — the interpreter path for that group's worker processes. Omit python and the group runs on the current interpreter.

class ServerConfiguration(AsgiConfigBuilder):
    def main(self, root):
        root.server(host="127.0.0.1", port=8080)
        root.middleware()
        apps = root.applications(default="site")
        app = apps.application(
            code="site",
            app_class=GenropyCommanderApplication,
            worker_app_class="genropy_asgi.spa.genropy_worker_application:GenropyWorkerApplication",
            app_args={"source": "mysite", "debug": ""},
            commander_url="http://127.0.0.1:8080",
        )
        # default = the welcome group: guests and unrecognized xgroups land here
        groups = app.groups(default="green")
        groups.group(code="green",  workers=2, python="/venvs/stable/bin/python")
        groups.group(code="canary", workers=1, python="/venvs/next/bin/python")

How a user reaches a group

A user is routed to a group by the xgroup field of their avatar. The commander reads it at login (it rides the change_connection_user event). An avatar with no xgroup, or one naming a group that is not declared, falls back to the default group — the welcome/base version. When a user's xgroup differs from the worker currently holding them, the commander migrates the session to the right group's worker, live (the source ships an opaque session package, the destination installs it).

venv, Podman, Docker

The lever the framework gives you is one interpreter path per group (python=). That maps directly onto isolation strategies:

One Server, Many Apps

The legacy site is not the only thing the server can host. It is a multi-app ASGI server: you mount the site on the root and any number of other apps beside it, each on its own path prefix. One process, one port, one origin — and every app can talk to the same GenroPy database.

A REST / OpenAPI endpoint on the same database

GenropyProxyOpenApiApplication hosts a GnrApp behind an OpenApiApplication: your routing class exposes plain methods as REST, and the mixin closes the db connection on the right (executor) thread after each call. Point it at the same instance the site serves — same database, different surface.

from genropy_asgi.proxy import GenropyProxyOpenApiApplication

# mounted on /api/ — REST + Swagger UI, backed by the "mysite" GnrApp
api = GenropyProxyOpenApiApplication(
    instance="mysite",               # same GenroPy instance as the site
    routing_class=MyApi(),          # your @route-decorated methods
    docs="swagger",               # swagger | redoc | off
)
server.mount("api", api)

The same class as MCP, for AI agents

The same routing class can be exposed as an MCP endpoint with McpOpenApiApplication: the MCP engine points at the same router, so one set of methods serves both a REST client and an AI agent — no second implementation.

from genro_asgi.applications.openapi_application import McpOpenApiApplication

server.mount("mcp", McpOpenApiApplication(routing_class=MyApi(), api_name="tools"))

Why "same origin" is the whole point

Because every app lives under one host and port, the browser sees one origin: no CORS to configure, and the legacy session cookie is sent to every path. A legacy GenroPy page can therefore reach a new ASGI endpoint directly — a fetch("/api/…") from page code, or an <iframe src="/live/…"> embedding a modern async view inside the classic UI — with the user's session already authenticated. New surfaces grow next to the old pages without a second deployment, a second domain, or a token dance.

The Daemon Is Gone

A GenroPy site talks to its register for every piece of shared state: which connections and pages exist, who is logged in, the pending datachanges to push to the browser, the page/user/connection/global stores. It reaches it through site.register, one command at a time.

Historically that register was a daemon — a separate process on a wire (Pyro4, later the genro-nodaemon TCP daemon). Every command was serialised onto that wire.

How the legacy still finds it

The package provides the gnr.web:daemon entry point. The legacy gnr.web.daemon switcher imports the module named by that entry point and installs it as gnr.web.daemon, so the legacy imports resolve to genropy-asgi — with nothing behind them. The GnrWsgiSite builds the register directly at site.register, no connection at construction.

# pyproject.toml — this is what wires the daemonless register in
[project.entry-points."gnr.web"]
daemon = "genropy_asgi.siteregister"

The switch model (datachanges)

GenroPy pushes datachanges to browsers: a record edited by one user must reach every page subscribed to that table — possibly on another worker. genropy-asgi handles this with the switch model:

• a datachange queue lives locally on the worker that owns the page;
• a page drains its own pending list on its own worker — no pull RPC back to a central daemon;
• when a change must cross to a page on another worker, the commander forwards it to that worker's /datachange_in endpoint, where it lands on the local queue like any other.

Over-notifying a worker that does not subscribe is harmless — it is dropped at the fan-out. A page reads its pending list where the page lives, never over the network.

Config & CLI

Every gnrasgiserve option

When you need a config file

The CLI's --workers starts a pool but uses the framework's default per-worker caps. To set the caps (max_users_first / max_users_other) or a max_workers ceiling, use a config file — a ServerConfiguration subclassing genro-asgi's AsgiConfigBuilder:

import os
from genro_asgi.config import AsgiConfigBuilder
from genropy_asgi.spa.genropy_commander_application import GenropyCommanderApplication

SITE = os.environ.get("GNR_ASGI_PATH") or "mysite"
PORT = int(os.environ.get("GNR_ASGI_PORT") or 8081)

class ServerConfiguration(AsgiConfigBuilder):
    def main(self, root):
        root.server(host="127.0.0.1", port=PORT)
        root.middleware()
        apps = root.applications(default="site")
        apps.application(
            code="site",
            app_class=GenropyCommanderApplication,
            worker_app_class="genropy_asgi.spa.genropy_worker_application:GenropyWorkerApplication",
            app_args={"source": SITE, "debug": ""},
            workers=1,               # start with one; the pool grows under load
            max_users_first=6,       # the first worker also hosts guests
            max_users_other=6,       # every other worker
            commander_url=f"http://127.0.0.1:{PORT}",
        )

Launch it either way — the config brings the pool shape, the CLI instance wins:

gnrasgiserve mysite --config pool_config.py -p 8081  # via gnrasgiserve
python -m genro_asgi serve pool_config.py            # via the genro-asgi core CLI

Environment variables (read by the built-in recipe)

Cheat Sheet

I want to…

The moving parts

Gotchas