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.
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.
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.
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_asyncandrun_forkrun 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_asyncortry_asyncruns in a copy of the fiber's context, as an asyncio task does. fx.run_syncandfx.run_blockingrun in the caller's own context, so a variable set by the effect is still set after it. AManagedRuntime'srun_syncandrun_blockingrun in a copy, as itsrun_asyncdoes. Effect has no such difference, since Node has one thread.
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.
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.
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.
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.