GitHub

Adopting in an asyncio app

Moving an existing asyncio service, such as a FastAPI app, to pyfect one function at a time.

An existing asyncio app doesn't have to move to pyfect all at once. Its handlers can stay coroutines that run effects through one ManagedRuntime, then its routes can move to pyfect's router mounted inside the app, and at the end pyfect can serve the app, with whatever hasn't moved yet mounted as an ASGI app.

One runtime for the app's life

fx.ManagedRuntime.make(layer) builds the layer once and runs effects with its services. Make it in the app's lifespan, so the layer is built at startup and released at shutdown, and run each handler's effect with await runtime.run_async(...). Effects keep calling the app's own coroutines through fx.from_async (or fx.try_async, which turns a raise into a typed error).

The effects' fibers run on the event loop's thread, between the app's own tasks, so a fiber that computes for a while holds up the whole app as a blocking coroutine would. Put CPU-heavy work in fx.blocking or another process; Threads and throughput explains.

lifespan.py
import asyncio
from collections.abc import AsyncGenerator
from contextlib import asynccontextmanager
from dataclasses import dataclass, field
from types import SimpleNamespace

import pyfect as fx
from pyfect import layer
from pyfect.scope import acquire_release


@dataclass
class Store:
    """What the app already has: a store its handlers use."""

    rows: dict[str, str] = field(default_factory=lambda: {"1": "Ada"})
    closed: bool = False

    async def get(self, user_id: str) -> str | None:
        await asyncio.sleep(0)
        return self.rows.get(user_id)


class Users(fx.Tag[Store]): ...


def open_store() -> Store:
    print("store opened")
    return Store()


def close_store(store: Store) -> fx.Effect[None]:
    return fx.sync(lambda: print("store closed"))


UsersLive = layer.effect(
    Users, acquire_release(fx.sync(open_store), lambda store, _exit: close_store(store))
)


@fx.fn
def user_name(user_id: str):
    store = yield from Users()
    name = yield from fx.from_async(lambda: store.get(user_id))
    return name or "unknown"


# FastAPI(lifespan=lifespan) calls this with the app: the layer is built at startup,
# shared by every request, and released at shutdown.
@asynccontextmanager
async def lifespan(app: SimpleNamespace) -> AsyncGenerator[None]:
    async with fx.ManagedRuntime.make(UsersLive) as runtime:
        app.state = runtime
        yield


# A handler of the existing app, still a coroutine.
async def get_user(app: SimpleNamespace, user_id: str) -> dict[str, str]:
    runtime: fx.ManagedRuntime[Users] = app.state
    return {"name": await runtime.run_async(user_name(user_id))}


async def main() -> None:
    app = SimpleNamespace()
    async with lifespan(app):
        print(await asyncio.gather(get_user(app, "1"), get_user(app, "2")))


asyncio.run(main())

Errors at the seam

run_async takes only an effect with no typed errors left (Effect[A, Never, ...]), and the runtime's layer must not fail either, so pyright flags a handler that forgets an error. Recover each typed error where the effect meets the app: into a value with catch_tag, or run with run_async_exit and turn the error into what the app raises, such as FastAPI's HTTPException. pyfect.run.unwrap(exit) gives the value, or raises a defect or an interruption as an exception.

seam_errors.py
import asyncio
from dataclasses import dataclass

import pyfect as fx
from pyfect import layer
from pyfect.run import unwrap


@dataclass
class NotFound(fx.TaggedError):
    user_id: str


class HTTPException(Exception):
    """FastAPI's, here a stand-in: what the app's handlers raise."""

    def __init__(self, status_code: int, detail: str) -> None:
        super().__init__(status_code, detail)
        self.status_code = status_code


class Users(fx.Tag[dict[str, str]]): ...


@fx.fn
def find_user(user_id: str):
    rows = yield from Users()
    if user_id not in rows:
        return (yield from NotFound(user_id))
    return rows[user_id]


# find_user(...) is an Effect[str, NotFound, Users]. run_async takes only an effect whose
# errors are all handled (Never), so each typed error is mapped where pyfect meets the app:
async def user_or_none(runtime: fx.ManagedRuntime[Users], user_id: str) -> str | None:
    # Either recover it into a value...
    found = find_user(user_id).pipe(fx.catch_tag(NotFound, lambda _: fx.succeed(None)))
    return await runtime.run_async(found)


async def get_user(runtime: fx.ManagedRuntime[Users], user_id: str) -> str:
    # ...or run for an Exit and turn the error into what the app raises.
    exit = await runtime.run_async_exit(find_user(user_id))
    match exit.find_error():
        case fx.Ok(value=NotFound() as error):
            raise HTTPException(404, f"no user {error.user_id}")
        case _:
            return unwrap(exit)  # the value; a defect or an interruption raises


async def main() -> None:
    async with fx.ManagedRuntime.make(layer.succeed(Users, {"1": "Ada"})) as runtime:
        print(await get_user(runtime, "1"), await user_or_none(runtime, "2"))
        try:
            await get_user(runtime, "2")
        except HTTPException as error:
            print(error.status_code, error)


asyncio.run(main())

A request decoded with a pydantic model (from_model) fails with the first problem it finds, as every Effect schema does by default (errors: "first"). Decode with errors="all" to report every problem, as FastAPI's own validation does.

Sharing layers between runtimes

Runtimes made with one layer.MemoMap() share the layers they have in common: such a layer is built by the first runtime that needs it and released when the last runtime using it is disposed, as with Effect's ManagedRuntime.make(layer, { memoMap }). router.to_asgi takes one too (memo_map=), so routes mounted in the app use the same database pool as the handlers that still run effects themselves.

memo_map.py
import asyncio

import pyfect as fx
from pyfect import layer
from pyfect.scope import acquire_release


class Pool(fx.Tag[str]): ...


PoolLive = layer.effect(
    Pool,
    acquire_release(
        fx.sync(lambda: print("pool opened")).as_("pool"),
        lambda _pool, _exit: fx.sync(lambda: print("pool closed")),
    ),
)


async def main() -> None:
    # Two runtimes, say one for the app's handlers and one for its background worker,
    # built from one memo map: a layer both use is built once, the first time, and released
    # when the last runtime using it is disposed.
    memo_map = layer.MemoMap()
    handlers = fx.ManagedRuntime.make(PoolLive, memo_map=memo_map)
    worker = fx.ManagedRuntime.make(PoolLive, memo_map=memo_map)
    print(await handlers.run_async(Pool()), await worker.run_async(Pool()))
    await handlers.dispose_async()
    print("handlers disposed")
    await worker.dispose_async()


asyncio.run(main())

Context variables

An effect reads its caller's contextvars, as Effect's runs follow Node's AsyncLocalStorage, so a request id set by the app's middleware reaches pyfect code, however many requests run at once:

  • run_async and run_fork run the effect in a copy of the caller's context. A variable the effect sets stays inside the run.
  • A forked fiber starts in a copy of its parent's context.
  • A coroutine awaited with from_async or try_async runs in a copy of the fiber's context, as an asyncio task does.
  • fx.run_sync and fx.run_blocking run in the caller's own context, so a variable set by the effect is still set after it. A ManagedRuntime's run_sync and run_blocking run in a copy, as its run_async does. Effect has no such difference, since Node has one thread.
contextvars_seam.py
import asyncio
import contextvars
from typing import Never

import pyfect as fx
from pyfect import layer

request_id: contextvars.ContextVar[str] = contextvars.ContextVar("request_id", default="-")


async def legacy_lookup() -> str:
    """Code of the existing app, which reads the request id itself."""
    await asyncio.sleep(0.01)
    return request_id.get()


@fx.fn
def handle():
    seen = [request_id.get()]  # in the effect
    seen.append((yield from fx.from_async(legacy_lookup)))  # in a coroutine it awaits
    child = yield from fx.sync(request_id.get).delay("10 millis").fork()
    seen.append((yield from child.join()))  # in a fiber it forks
    request_id.set("changed inside")  # stays inside the run
    return seen


async def request(runtime: fx.ManagedRuntime[Never], rid: str) -> list[str]:
    request_id.set(rid)  # what a request id middleware does
    seen = await runtime.run_async(handle())
    assert seen == [rid, rid, rid]
    assert request_id.get() == rid
    return seen


async def main() -> None:
    async with fx.ManagedRuntime.make(layer.empty) as runtime:
        # However many requests run at once, each run reads its own caller's value.
        for seen in await asyncio.gather(*(request(runtime, f"r{i}") for i in range(3))):
            print(seen)


asyncio.run(main())

Routes mounted in the app

router.to_asgi(routes) is an ASGI app, so pyfect routes can be mounted inside the existing app while the rest of it stays as it is. A route's handler can ask for services; the layer's type then holds Requires[Service], and to_asgi only accepts routes whose requirements its layer builds, so a missing service is a pyright error rather than a 500 on every request.

routes.pipe(router.provide_request(services)) builds services once, when the app starts, and gives them to every request of those routes, as Effect's HttpRouter.provideRequest. layer.provide(services) builds them only for the routes' layer, not for its requests, so to_asgi refuses it. layer.provide_merge(services) works too, since the requests run with the services the layer builds. Pyright removes a Requires only when it can see that the layer builds that service: in a helper generic in its services' type, such as def app_routes[RO](services: Layer[RO]), it can't, the Requires stay and to_asgi refuses the routes. Name the services in the helper's parameter (services: Layer[Users | Db, E]), or apply provide_request outside the helper, where the layer's type is known.

A server sends no lifespan to a mounted app: give the host app lifespan=lambda _app: pyfect_app.lifespan(), or the mounted app's layers are built by the first request and never released.

mounted.py
import asyncio

import httpx

import pyfect as fx
from pyfect import layer
from pyfect.http import router, server_response
from pyfect.scope import acquire_release


class Users(fx.Tag[dict[str, str]]): ...


UsersLive = layer.effect(
    Users,
    acquire_release(
        fx.sync(lambda: print("users opened")).as_({"1": "Ada"}),
        lambda _users, _exit: fx.sync(lambda: print("users closed")),
    ),
)


@fx.fn
def get_user():
    params = yield from router.params
    users = yield from Users()
    return (yield from server_response.json({"name": users.get(params["id"], "unknown")}))


# The route needs Users for each request (Requires[Users]); provide_request builds UsersLive
# once and gives it to every request. layer.provide would build it for the route's layer
# only, and to_asgi rejects that: pyright reports the Requires[Users] left over.
Routes = router.add("GET", "/users/:id", get_user()).pipe(router.provide_request(UsersLive))

pyfect_app = router.to_asgi(Routes, disable_logger=True)
# In FastAPI:
#   app = FastAPI(lifespan=lambda _app: pyfect_app.lifespan())
#   app.mount("/api", pyfect_app)
# A server sends no lifespan to a mounted app, so the host's lifespan builds the layers at
# startup and releases them at shutdown; without it they are built by the first request
# and never released.


async def main() -> None:
    async with pyfect_app.lifespan():
        transport = httpx.ASGITransport(app=pyfect_app)
        async with httpx.AsyncClient(transport=transport, base_url="http://app") as client:
            for path in ("/users/1", "/users/2", "/nowhere"):
                response = await client.get(path)
                print(path, response.status_code, response.text)


asyncio.run(main())

Serving with hypercorn

Once most routes have moved, pyfect can serve the app and mount the rest: asgi.from_asgi(legacy_app) as a "*" route on "/*" answers every path the router doesn't have. To mount an app under a path, such as a FastAPI admin app at /admin, add its route with router.prefix_route("/admin"): the app gets /admin as its root_path, so its own routes still match. On a plain "/admin/*" route the root_path is empty and every route of the app answers 404. from_asgi passes on HTTP requests only, as Effect's fromWebHandler does: a WebSocket upgrade reaches the mounted app as an http request, which a FastAPI WebSocket route answers with 404, so serve WebSockets from pyfect routes (WebSockets). The other way, router.to_asgi does bridge WebSocket connections to pyfect routes.

hypercorn_server.layer(host=..., port=...) serves on hypercorn (the pyfect-dev[http2] extra), which speaks HTTP/2 in cleartext as well as HTTP/1.1. hypercorn logs no startup line of its own: the "Listening on" line is serve's, which disable_listen_log=True leaves out.

Each request is logged by serve, unless disable_logger=True, with the loggers of the context requests run in, as in Effect, where both use HttpMiddleware.logger. For serve, that is what the server's layer is provided with, as logger.layer(...) below; for to_asgi, it is the layer to_asgi builds, so provide the loggers to that layer.

served.py
import pyfect as fx
from pyfect import logger
from pyfect.http import asgi, hypercorn_server, router, server_response
from pyfect.http.asgi import Receive, Scope, Send
from pyfect.http.client import HttpClient
from pyfect.logger import CurrentLogAnnotations


async def legacy(scope: Scope, receive: Receive, send: Send) -> None:
    """The routes not migrated yet: any ASGI app, such as the FastAPI one."""
    await send({"type": "http.response.start", "status": 200, "headers": []})
    await send({"type": "http.response.body", "body": f"legacy {scope['path']}".encode()})


async def admin(scope: Scope, receive: Receive, send: Send) -> None:
    """An app mounted under a prefix, such as a FastAPI admin app."""
    body = f"admin root_path={scope['root_path']} path={scope['path']}"
    await send({"type": "http.response.start", "status": 200, "headers": []})
    await send({"type": "http.response.body", "body": body.encode()})


@fx.fn
def get_user():
    params = yield from router.params
    return (yield from server_response.json({"id": params["id"]}))


@fx.fn
def add_routes(routes: router.HttpRouterService):
    yield from routes.add("GET", "/users/:id", get_user())
    # Under a prefix the mounted app gets it as its root_path, so its own routes still match.
    mounted = router.route("*", "*", asgi.from_asgi(admin)).pipe(router.prefix_route("/admin"))
    yield from routes.add_all([mounted])
    # Every other path goes to the legacy app.
    yield from routes.add("*", "/*", asgi.from_asgi(legacy))


def request_log(entry: logger.Options) -> None:
    notes = entry.fiber.get_ref(CurrentLogAnnotations)
    print(*entry.message, notes["http.method"], notes["http.url"], notes["http.status"])


@fx.fn
def requests():
    http = yield from HttpClient()
    for path in ("/users/7", "/admin/health", "/healthz"):
        response = yield from http.get(path)
        print(response.status, (yield from response.text))


# serve logs each request with the loggers of the server's layer (with to_asgi, those of
# the layer it builds); disable_listen_log leaves out the "Listening on" line.
App = router.serve(router.use(add_routes), disable_listen_log=True)
program = requests().pipe(fx.provide(App)).pipe(fx.provide(hypercorn_server.layer_test()))
fx.run_main(program.pipe(fx.provide(logger.layer([logger.Logger.make(request_log)]))))

Serving over TLS

Each server takes its own TLS settings in config, which passes them to the engine, so their names differ: hypercorn's config holds hypercorn.Config attributes, certfile and keyfile, and then negotiates HTTP/2 with ALPN; uvicorn's holds uvicorn.Config arguments, ssl_certfile and ssl_keyfile. Stopping a server closes its idle keep-alive connections at once, over TLS too, as Node's server does.

tls.py
import datetime as dt
import ipaddress
import ssl
import tempfile
from pathlib import Path

from cryptography import x509
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.x509.oid import NameOID

import pyfect as fx
from pyfect.http import httpx_client, hypercorn_server, router, server_response, uvicorn_server
from pyfect.http.client import HttpClient
from pyfect.http.server import HttpServer
from pyfect.net.net_address import UnixPathAddress


def self_signed(directory: Path) -> tuple[str, str]:
    """A certificate for 127.0.0.1 and its key, as PEM files (use real ones in production)."""
    key = ec.generate_private_key(ec.SECP256R1())
    name = x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, "127.0.0.1")])
    now = dt.datetime.now(dt.UTC)
    ski = x509.SubjectKeyIdentifier.from_public_key(key.public_key())
    cert = (
        x509.CertificateBuilder()
        .subject_name(name)
        .issuer_name(name)
        .public_key(key.public_key())
        .serial_number(x509.random_serial_number())
        .not_valid_before(now - dt.timedelta(minutes=1))
        .not_valid_after(now + dt.timedelta(hours=1))
        .add_extension(x509.BasicConstraints(ca=True, path_length=None), critical=True)
        .add_extension(
            x509.SubjectAlternativeName([x509.IPAddress(ipaddress.ip_address("127.0.0.1"))]),
            critical=False,
        )
        .add_extension(ski, critical=False)
        .add_extension(
            x509.AuthorityKeyIdentifier.from_issuer_subject_key_identifier(ski), critical=False
        )
        .sign(key, hashes.SHA256())
    )
    certfile, keyfile = directory / "cert.pem", directory / "key.pem"
    certfile.write_bytes(cert.public_bytes(serialization.Encoding.PEM))
    keyfile.write_bytes(
        key.private_bytes(
            serialization.Encoding.PEM,
            serialization.PrivateFormat.PKCS8,
            serialization.NoEncryption(),
        )
    )
    return str(certfile), str(keyfile)


@fx.fn
def get_over_tls(engine: str):
    server = yield from HttpServer()
    http = yield from HttpClient()
    address = server.address
    assert not isinstance(address, UnixPathAddress)
    response = yield from http.get(f"https://127.0.0.1:{address.port}/")
    print(engine, response.status, (yield from response.text))


App = router.serve(
    router.add("GET", "/", server_response.text("over TLS")),
    disable_logger=True,
    disable_listen_log=True,
)

with tempfile.TemporaryDirectory() as directory:
    certfile, keyfile = self_signed(Path(directory))
    # hypercorn's config takes hypercorn.Config attributes: certfile and keyfile.
    hypercorn_tls = hypercorn_server.layer(
        host="127.0.0.1", config={"certfile": certfile, "keyfile": keyfile}
    )
    # uvicorn's takes uvicorn.Config arguments, named differently: ssl_certfile and ssl_keyfile.
    uvicorn_tls = uvicorn_server.layer(
        host="127.0.0.1", config={"ssl_certfile": certfile, "ssl_keyfile": keyfile}
    )
    # A client that trusts the self-signed certificate, closed before the server stops.
    trusting = httpx_client.layer_with(verify=ssl.create_default_context(cafile=certfile))
    for engine, served_on in (("hypercorn", hypercorn_tls), ("uvicorn", uvicorn_tls)):
        program = get_over_tls(engine).pipe(fx.provide(trusting))
        fx.run_main(program.pipe(fx.provide(App)).pipe(fx.provide(served_on)))

Reference: pyfect.managed_runtime, pyfect.http.router, pyfect.http.asgi, pyfect.http.hypercorn_server, pyfect.http.uvicorn_server.