GitHub

HTTP server

Routes, middleware and a server on uvicorn, with each handler an effect.

A handler is an effect that gives an HttpServerResponse. Routes are added to the HttpRouter by layers, so a route's handler can ask for any service and the layer's type says which ones the server must provide. router.serve(routes) serves them on the HttpServer in the context, and needs whatever else the routes' layer needs (services, and markers such as an RPC group's HandlersFor[Group]), so they can be provided to the server layer; uvicorn_server.layer(port=...) is one on uvicorn (install the pyfect-dev[server] extra), and live_server.layer one on the standard library.

Routes

router.use(f) is a layer that calls f with the router; routes.add(method, path, handler) adds a route. A path matches :name segments and * wildcards; router.params gives the matched values, and router.schema_path_params, schema_params and schema_json decode the path, the query and the JSON body with a schema. schema_json's schema is a struct of the request: body, method, url, headers, cookies, and pathParams and searchParams, spelled in camelCase as in Effect (a params key fails every request with a 400). A request that matches no route gets a 404, and a handler that fails gets a 500 unless it handles the error itself. As in Effect, two failures answer otherwise: a SchemaError (a request that doesn't decode) gets an empty 400 and a NoSuchElementException an empty 404.

A handler returns a response. server_response.text(...) is one, so get_todo below returns it as it is, while server_response.json(...) is an effect, since encoding the value can fail, so the handler runs it with yield from and returns what it gives.

routes.py
from typing import TypedDict
from urllib.parse import urlsplit

import pyfect as fx
from pyfect import schema as S
from pyfect.http import body, router, server_response, uvicorn_server
from pyfect.http.client import HttpClient


class TodoParams(TypedDict):
    id: str


class NewTodo(TypedDict):
    title: str


class CreateRequest(TypedDict):
    body: NewTodo


# schema_json's struct reads the request's keys: body, method, url, headers, cookies, and
# pathParams and searchParams, spelled in camelCase as in Effect.
class RenameRequest(TypedDict):
    pathParams: TodoParams
    body: NewTodo


todos = {"1": "Write docs"}


@fx.fn
def get_todo():
    params = yield from router.schema_path_params(S.Struct(TodoParams))
    title = todos.get(params["id"])
    if title is None:
        return server_response.text("no such todo", status=404)
    return (yield from server_response.json({"id": params["id"], "title": title}))


@fx.fn
def create_todo():
    # The JSON body (and the path and query) decoded by a schema.
    request = yield from router.schema_json(S.Struct(CreateRequest, body=S.Struct(NewTodo)))
    todo_id = str(len(todos) + 1)
    todos[todo_id] = request["body"]["title"]
    return (yield from server_response.json({"id": todo_id}, status=201))


@fx.fn
def rename_todo():
    request = yield from router.schema_json(
        S.Struct(RenameRequest, pathParams=S.Struct(TodoParams), body=S.Struct(NewTodo))
    )
    todo_id = request["pathParams"]["id"]
    if todo_id not in todos:
        return server_response.text("no such todo", status=404)
    todos[todo_id] = request["body"]["title"]
    return (yield from server_response.json({"id": todo_id, "title": todos[todo_id]}))


bad_request = server_response.text("expected {title: string}", status=400)


@fx.fn
def add_routes(routes: router.HttpRouterService):
    yield from routes.add("GET", "/", server_response.text("hello"))
    yield from routes.add("GET", "/todos/:id", get_todo())
    on_bad_body = fx.catch_tag(S.SchemaError, lambda _: fx.succeed(bad_request))
    yield from routes.add("POST", "/todos", create_todo().pipe(on_bad_body))
    yield from routes.add("PUT", "/todos/:id", rename_todo().pipe(on_bad_body))


Routes = router.use(add_routes)


@fx.fn
def requests():
    http = yield from HttpClient()
    for sent in [
        http.get("/"),
        http.get("/todos/1"),
        http.post("/todos", body=body.json_unsafe({"title": "Ship it"})),
        http.get("/todos/2"),
        http.put("/todos/2", body=body.json_unsafe({"title": "Ship it today"})),
        http.post("/todos", body=body.json_unsafe({"name": "Ship it"})),
        http.get("/todos/9"),
        http.get("/nowhere"),
    ]:
        res = yield from sent
        path = urlsplit(res.request.url).path
        print(res.request.method, path, res.status, (yield from res.text))


# layer_test: uvicorn on a free local port, and an HttpClient that sends to it.
served = router.serve(Routes, disable_logger=True, disable_listen_log=True)
fx.run_main(requests().pipe(fx.provide(served)).pipe(fx.provide(uvicorn_server.layer_test())))

uvicorn_server.layer_test() runs the server on a free local port and gives an HttpClient whose relative URLs go to it, so the program above sends real requests.

HTML templates

server_response.html_template(strings, *values) renders a template as a text/html response, and html_stream streams one; template.make gives the text. A value can be an effect or, for html_stream, a stream. As in Effect, values are inserted without HTML escaping, so text from a user or a log line must go through html.escape first.

template.py
from html import escape

import pyfect as fx
from pyfect.http import template

comment = "<script>alert(1)</script>"

# Values go in as they are: this comment would run in the reader's browser.
raw = fx.run_blocking(template.make(["<p>", "</p>"], comment))
assert raw == "<p><script>alert(1)</script></p>"

# Escape text that isn't yours before it goes in.
safe = fx.run_blocking(template.make(["<p>", "</p>"], escape(comment)))
print(safe)

Middleware

A middleware is a function of the handler it wraps. router.middleware(f) makes route middleware, provided to the route layers it should wrap with layer.provide(m.layer), and router.middleware(f, global_=True) a layer that wraps every request. router.cors(...) answers preflight requests and adds the CORS headers. Each request is logged unless disable_logger=True. routes.pipe(router.provide_request(services)) builds services once and gives them to every request of those routes, removing their Requires[...], as Effect's HttpRouter.provideRequest (see Adopting in an asyncio app).

/admin/*/healthno matchrequestglobal middleware: cors,served_byrouter: match method and pathroute middleware: RequireKeyadmin handlerpublic handler404
/admin/*/healthno matchrequestglobal middleware: cors,served_byrouter: match method and pathroute middleware: RequireKeyadmin handlerpublic handler404
middleware.py
from urllib.parse import urlsplit

import pyfect as fx
from pyfect import layer
from pyfect.http import router, server_response, uvicorn_server
from pyfect.http.client import HttpClient
from pyfect.http.server_request import HttpServerRequest
from pyfect.http.server_response import HttpServerResponse


# Route middleware: a function of the handler it wraps.
@fx.fn
def check_key(handler: fx.Effect[HttpServerResponse, router.Unhandled]):
    request = yield from HttpServerRequest()
    if request.headers.get("x-api-key") != "secret":
        return server_response.text("unauthorized", status=401)
    return (yield from handler)


RequireKey = router.middleware(check_key)


@fx.fn
def public(routes: router.HttpRouterService):
    yield from routes.add("GET", "/health", server_response.text("ok"))


@fx.fn
def admin(routes: router.HttpRouterService):
    yield from routes.add("GET", "/admin/stats", server_response.text("42 users"))


def add_header(handler: fx.Effect[HttpServerResponse, router.Unhandled]):
    return handler.map(lambda res: res.set_header("x-served-by", "pyfect"))


# Global middleware wraps every request, matched or not.
served_by = router.middleware(add_header, global_=True)

App = (
    router.use(admin)
    .pipe(layer.provide(RequireKey.layer))  # only the admin routes
    .pipe(layer.provide_merge(router.use(public)))
    .pipe(layer.provide_merge(served_by))
    .pipe(layer.provide_merge(router.cors(allowed_origins=["https://example.com"])))
)


@fx.fn
def requests():
    http = yield from HttpClient()
    for sent in [
        http.get("/health"),
        http.get("/admin/stats"),
        http.get("/admin/stats", headers={"x-api-key": "secret"}),
    ]:
        res = yield from sent
        path = urlsplit(res.request.url).path
        print(path, res.status, (yield from res.text))
        print("  x-served-by:", res.headers["x-served-by"])
        print("  access-control-allow-origin:", res.headers["access-control-allow-origin"])


served = router.serve(App, disable_logger=True, disable_listen_log=True)
fx.run_main(requests().pipe(fx.provide(served)).pipe(fx.provide(uvicorn_server.layer_test())))

Serving with uvicorn

router.serve(routes) is a layer, so a program serves until it is interrupted by launching it: fx.run_main(Main.launch()). On Ctrl-C the server stops accepting connections and gives the requests in flight graceful_shutdown_timeout (20 seconds) before interrupting them. A streamed body still open then, such as an SSE stream, stops where it is, so one open server-sent events response holds shutdown for the full 20 seconds; pass uvicorn_server.layer(port=8000, graceful_shutdown_timeout="3 seconds") to wait 3 seconds instead. disable_preemptive_shutdown=True interrupts the requests in flight at once. router.to_asgi(routes) is the same app as an ASGI application, for uvicorn main:app or any other ASGI server; its layers are built at the server's startup and released at its shutdown, and its requests run with their services, so whatever the routes need its layer must build. hypercorn_server.layer(port=...) serves on hypercorn instead, with HTTP/2 (the pyfect-dev[http2] extra).

The server binds its port when its layer is built, before the layers of the app it serves, so a client can connect while the app is still starting. As with Effect's Node server, its requests wait until the app is served instead of getting an answer. Make readiness checks request a route rather than wait for the port to open: a request on an open port can still wait as long as the slowest layer takes to build. If the server closes before any app is served, the requests still waiting get an empty 503.

main.py
import sys

import pyfect as fx
from pyfect import layer
from pyfect.http import router, server_response, uvicorn_server


@fx.fn
def add_routes(routes: router.HttpRouterService):
    yield from routes.add("GET", "/", server_response.text("hello"))


Routes = router.use(add_routes)

# `python main.py serve`: serve on port 8000 until interrupted (Ctrl-C), then
# give requests in flight up to 20 seconds to finish.
Main = router.serve(Routes).pipe(layer.provide(uvicorn_server.layer(port=8000)))

# `uvicorn main:app`: the same routes as an ASGI application, for any ASGI server.
app = router.to_asgi(Routes)

if sys.argv[1:] == ["serve"]:
    fx.run_main(Main.launch())

asgi.from_asgi(app) goes the other way: it mounts an ASGI application, such as a FastAPI or Starlette one, as a route, for HTTP requests only (WebSocket upgrades reach it as http requests, as with Effect's fromWebHandler). Mounted under a path, its route needs router.prefix_route(...), which makes the path the app's root_path. Adopting in an asyncio app moves such an app to pyfect step by step, and serves over TLS.

WebSockets

A handler serves a WebSocket by upgrading its request: request.upgrade gives a socket (request.upgrade_with(headers=...) adds response headers to the 101, for protocols other than websocket). The socket opens only when its reader is taken, in a scope that closes it: the 101 is sent then, and until then every writer.write waits. So a handler that only sends must still take the reader, or it hangs on its first write. The client's socket from pyfect.socket.make_web_socket(url) works the same way. All of this is as in Effect.

websocket.py
import pyfect as fx
import pyfect.socket as so
from pyfect import stream
from pyfect.http import live_server, router, server_response
from pyfect.http.server import HttpServer, format_address
from pyfect.http.server_request import HttpServerRequest
from pyfect.socket import ws


@fx.fn
def shout(socket: so.SocketService):
    # Taking the reader opens the socket: until then every write waits.
    reader = yield from socket.reader
    writer = yield from socket.writer
    while True:
        # A pull fails with a SocketError once the socket closes.
        for message in (yield from reader.pull):
            text = message if isinstance(message, str) else message.decode()
            yield from writer.write(text.upper())
            if text == "bye":
                yield from writer.write(so.CloseEvent(1000, "done"))


@fx.fn
def handler():
    request = yield from HttpServerRequest()
    socket = yield from request.upgrade
    yield from fx.scoped(shout(socket)).pipe(fx.catch_tag(so.SocketError, lambda _: fx.void))
    return server_response.empty()


@fx.fn
def chat():
    server = yield from HttpServer()
    url = format_address(server.address).replace("http", "ws", 1) + "/shout"
    socket = yield from so.make_web_socket(url)
    writer = yield from socket.writer
    # The client's writes wait for its reader too: the stream below takes it.
    yield from writer.write_all(["hello", "bye"]).fork()
    replies = (
        so.to_stream(socket)
        .map(bytes.decode)
        # A normal close fails the stream with code 1000, as in Effect: end it instead.
        .catch_if(so.is_clean_close, lambda _: stream.empty)
    )
    print((yield from replies.run_collect()))


served = router.serve(
    router.add("GET", "/shout", handler()), disable_logger=True, disable_listen_log=True
)
program = (
    fx.scoped(chat())
    .pipe(fx.provide(ws.layer_web_socket_constructor))
    .pipe(fx.provide(served))
    .pipe(fx.provide(live_server.layer_test()))
)
fx.run_main(program)

Two more rules, also Effect's:

  • Once the reader's scope closes, the socket is gone and a write waits forever: it does not fail. Keep the reader's scope open for as long as the handler writes, as shout does.
  • reader.pull and so.to_stream fail with a SocketError when the socket closes, even with code 1000 (a normal close). catch_if(so.is_clean_close, ...) ends the stream instead.
  • While the reader is open, the server reads whether or not the handler pulls: it answers pings and the client's close, and stops reading only while 64 KiB of messages wait for a pull. A write after the client has gone is dropped, not failed.

When the client leaves, the live server interrupts the handler as a client abort, so one that only writes ends then too. Effect's Node server means to do the same, but ws keeps it from happening, so there a handler that only writes runs until the server shuts down. To end it as soon as the client closes whichever server runs it, race the writes against the reader with race_first (race waits for one side to succeed): messages.run_for_each(writer.write).race_first(reader.pull.forever()).

Security defaults

The server refuses unsafe input without any setting, and each limit can be changed where an app needs more room.

  • A whole-body read (request.text, json, schema_json, HttpApi payloads, multipart) stops at MaxBodySize, 10 MiB by default, with a 413. Provide a larger ByteSize, or None, on the routes that need it. A streamed body (request.stream) is read as far as the handler reads it.
  • live_server.layer answers 431 to a request head (request line and headers) past 16 KiB, as Node does, reads chunk size lines of at most 4 KiB and trailers of at most 16 KiB, and takes WebSocket messages of up to websocket_max_message_size (100 MiB by default, as ws). It closes a connection whose request has not fully arrived after request_timeout (300 seconds). It answers 400 to a Host that is not a host and port, to a request target that is not a path, * or an absolute http(s) URL, to framing headers padded with anything but spaces and tabs, and to malformed trailers or chunk extensions.
  • Behind ASGI, a request URL is built only from a valid Host (else the server's address), and a path that does not start with / is a 400. An app mounted with asgi.from_asgi or from_web_handler keeps %2F encoded and never gets a . or .. segment.
  • WebSocket upgrades from a browser page of another origin get a 403; list more origins with layer.succeed(AllowedOrigins, origin.allow(...)) from pyfect.http.origin. A WebSocket write waits while more than 64 KiB are unsent. live_server.layer accepts permessage-deflate only with websocket_per_message_deflate=True (or a live_server.PerMessageDeflate(...)), and a message's inflated size counts against websocket_max_message_size.
  • The decompression middleware counts every decoded byte against the body limit and accepts at most two stacked codings. router.cors(credentials=True) needs a list of origins without *. A multipart boundary must follow RFC 2046 (1 to 70 characters). A multipart field is at most MaxFieldSize (10 MiB) and a file MaxFileSize (no limit but the body's); a body has at most MaxParts (1000) parts (Effect has no default limit; set None for none). A response header with a control character is never sent.
  • In HttpApi, a body without a Content-Type gets a 415 instead of being read as JSON, and security_set_cookie sets Secure, HttpOnly and SameSite=Lax.
limits.py
import pyfect as fx
from pyfect import byte_size, effect
from pyfect.http import body, router, server_response, uvicorn_server
from pyfect.http.client import HttpClient
from pyfect.http.incoming_message import MaxBodySize
from pyfect.http.server_request import HttpServerRequest


@fx.fn
def upload():
    request = yield from HttpServerRequest()
    text = yield from request.text  # a 413 once the body passes MaxBodySize
    return server_response.text(f"{len(text)} bytes")


@fx.fn
def add_routes(routes: router.HttpRouterService):
    # Every whole-body read is capped at 10 MiB; this route lowers it to 1 KiB.
    small = effect.provide_service(MaxBodySize, byte_size.kibibytes(1))
    yield from routes.add("POST", "/upload", upload().pipe(small))


@fx.fn
def requests():
    http = yield from HttpClient()
    for size in [100, 5000]:
        res = yield from http.post("/upload", body=body.text("x" * size))
        print(size, res.status)


served = router.serve(router.use(add_routes), disable_logger=True, disable_listen_log=True)
fx.run_main(requests().pipe(fx.provide(served)).pipe(fx.provide(uvicorn_server.layer_test())))

Testing routes

A test serves the routes on layer_test and sends requests with the HttpClient it gives. To skip the socket, router.in_memory_client(routes) answers requests in memory and streams response bodies as they are written (see Testing).

test_routes.py
import pyfect as fx
from pyfect import testing
from pyfect.http import router, server_response, uvicorn_server
from pyfect.http.client import HttpClient


@fx.fn
def add_routes(routes: router.HttpRouterService):
    yield from routes.add("GET", "/hello/:name", greet())


@fx.fn
def greet():
    params = yield from router.params
    return server_response.text(f"hello, {params['name']}")


served = router.serve(router.use(add_routes), disable_logger=True, disable_listen_log=True)


def on_server[A, E](requests: fx.Effect[A, E, HttpClient]):
    """Run `requests` against a real server on a free local port."""
    return requests.pipe(fx.provide(served)).pipe(fx.provide(uvicorn_server.layer_test()))


@fx.fn
def get(path: str):
    res = yield from (yield from HttpClient()).get(path)
    return res.status, (yield from res.text)


@testing.effect
def test_greets_by_name():
    assert (yield from on_server(get("/hello/ada"))) == (200, "hello, ada")


@testing.effect
def test_an_unknown_path_is_a_404():
    status, _ = yield from on_server(get("/goodbye"))
    assert status == 404

Reference: pyfect.http.router, pyfect.http.server_response, pyfect.http.middleware, pyfect.http.uvicorn_server, pyfect.http.asgi.