Declare an HTTP API once, then serve it, call it with a typed client and document it with OpenAPI.
An HttpApi is a declaration: groups of endpoints, each with its method, path and the
schemas of its params, query, payload, headers, success and errors. The server's handlers,
the client's methods and the OpenAPI document all come from it, so they can't disagree, and
pyright checks a handler's return value and a client call's arguments against the same
schemas.
Declare and implement an API#
endpoint.get, post, put, patch, delete, ... declare endpoints; a class extending
HttpApiGroup holds them, and HttpApi.make(name).add(Group) collects the groups. An error
schema's http_api_status annotation is the status it is sent with.
A group's own members can't be endpoint attributes: add, annotate, annotate_endpoints,
annotate_endpoints_merge, annotate_merge, annotations, endpoints, identifier, key,
make, method, middleware, origin, prefix and top_level. Naming one fails with a
TypeError as the class is created. Name the attribute add_item and the endpoint itself
what you like: add_item = endpoint.post("add", "/items").
A handler takes an HttpApiRequest with the decoded params, query, payload and
headers, and gives the success value or fails with a declared error.
builder.group(api, Group, ...) is the layer of a group's handlers; building it dies if an
endpoint has no handler. builder.layer(api) adds every group's routes to the
router and needs each group's layer, which pyright checks, so
router.serve serves the API like any other routes.
client.make(api) derives a client: get_group(api_client, Users).get_user(params={"id": 1})
encodes the request, sends it with the HttpClient and decodes the response, failing with
the endpoint's declared errors as values of their own classes. get_group is typed as the
group you name, and a group the API lacks is a pyright error. A method's response_only
gives the raw response; client.decode_response(api, Users, Users.get_user) decodes it
later, as the method would have. Two endpoints with the same method and path are an error
when the routes are built.
from typing import TypedDict
import pyfect as fx
from pyfect import layer
from pyfect import schema as S
from pyfect.http import router, uvicorn_server
from pyfect.http_api import (
HttpApi,
HttpApiGroup,
HttpApiRequest,
builder,
client,
endpoint,
get_group,
)
# The declaration: each endpoint's path, inputs, success and errors are schemas.
class User(S.Class, identifier="User"):
id: int
name: str
class UserParams(TypedDict):
id: int
class NewUser(TypedDict):
name: str
class UserNotFound(S.TaggedError, annotations={"http_api_status": 404}):
id: int
class Users(HttpApiGroup, identifier="users"):
get_user = endpoint.get(
"getUser", "/users/:id", params=S.Struct(UserParams), success=User, error=UserNotFound
)
create_user = endpoint.post("createUser", "/users", payload=S.Struct(NewUser), success=User)
api = HttpApi.make("example").add(Users)
# The implementation: a handler per endpoint, typed by its declaration.
users = {1: User(id=1, name="Ada")}
@fx.fn
def get_user(request: HttpApiRequest[UserParams, None, None, None]):
user = users.get(request.params["id"])
if user is None:
return (yield from UserNotFound(id=request.params["id"]))
return user
@fx.fn
def create_user(request: HttpApiRequest[None, None, NewUser, None]):
user = User(id=len(users) + 1, name=request.payload["name"])
users[user.id] = user
yield from fx.log_debug(f"created user {user.id}")
return user
UsersLive = builder.group(
api,
Users,
lambda handlers: handlers.handle(Users.get_user)(get_user).handle(Users.create_user)(
create_user
),
)
ApiLive = builder.layer(api).pipe(layer.provide(UsersLive))
# The client: derived from the same declaration, so its calls are typed too.
@fx.fn
def program():
api_client = yield from client.make(api)
created = yield from get_group(api_client, Users).create_user(payload={"name": "Grace"})
print("created", created)
print("found", (yield from get_group(api_client, Users).get_user(params={"id": created.id})))
missing = yield from get_group(api_client, Users).get_user(params={"id": 99}).flip()
print("missing", repr(missing))
served = router.serve(ApiLive, disable_logger=True, disable_listen_log=True)
fx.run_main(program().pipe(fx.provide(served)).pipe(fx.provide(uvicorn_server.layer_test())))A request whose params or payload don't match the schemas gets an empty 400 before any
handler runs, and the server logs the HttpApiSchemaError with the schema issue. To tell
the client what was wrong, build the routes with
builder.layer(api, schema_error_details=True): the 400 then carries
{"_tag": "HttpApiSchemaError", "kind": "Payload", "message": "Missing key\n at [\"url\"]"}.
It is off by default, as in Effect, since the message describes your schemas.
Problem details#
error.Problem declares an RFC 9457 error:
class OutOfCredit(Problem, type=..., status=..., title=...) with its own fields as
extensions. An endpoint failing with it answers with that status and an
application/problem+json body, the OpenAPI document lists it so, and the client decodes it
back by its type into an OutOfCredit. detail and instance are optional on every
problem. schema.as_problem(title=...) sends an error class you already have as a problem.
Add the middleware.ProblemDetails middleware to the API and provide
layer_problem_details() to answer requests that don't decode with a BadRequestProblem
instead of the empty 400; include_details=True adds errors, each a path starting with
the slot (query, payload, ...) and a message. A response that fails to encode becomes an
InternalServerErrorProblem, and the schema error is reported once. http.problem_details
has the plain RFC 9457 schema for problems from other servers.
from typing import TypedDict
import pyfect as fx
from pyfect import layer
from pyfect import schema as S
from pyfect.http import client as http_client
from pyfect.http import router, uvicorn_server
from pyfect.http_api import HttpApi, HttpApiGroup, builder, client, endpoint, error, get_group
from pyfect.http_api import middleware as mw
# A typed RFC 9457 problem: its type, status and title are fixed, its fields are extensions.
class OutOfCredit(
error.Problem,
type="https://example.com/probs/out-of-credit",
status=403,
title="You do not have enough credit.",
):
balance: float
class Page(TypedDict):
page: int
class Shop(HttpApiGroup, identifier="shop"):
purchase = endpoint.post(
"purchase", "/purchase", query=S.Struct(Page), success=S.String, error=OutOfCredit
)
# The ProblemDetails middleware answers schema errors with problems too.
api = HttpApi.make("shop").add(Shop).middleware(mw.ProblemDetails)
ShopLive = builder.group(
api,
Shop,
lambda handlers: handlers.handle(Shop.purchase)(
lambda _: fx.fail(OutOfCredit(balance=30, detail="Your balance is 30."))
),
)
ApiLive = (
builder.layer(api)
.pipe(layer.provide(ShopLive))
.pipe(layer.provide(mw.layer_problem_details(include_details=True)))
)
@fx.fn
def program():
shop = get_group((yield from client.make(api)), Shop)
problem = yield from shop.purchase(query={"page": 1}).flip()
print(repr(problem))
raw = yield from shop.purchase.response_only(query={"page": 1})
print(raw.status, raw.headers["content-type"], (yield from raw.text))
invalid = yield from http_client.post("/purchase?page=first")
print(invalid.status, (yield from invalid.text))
served = router.serve(ApiLive, disable_logger=True, disable_listen_log=True)
fx.run_main(program().pipe(fx.provide(served)).pipe(fx.provide(uvicorn_server.layer_test())))Security#
A middleware runs around the handlers of the endpoints it is added to. Declare one as a
class over what it gives the handlers and how it fails:
HttpApiMiddleware[Caller, Unauthorized] provides a Caller and may fail with
Unauthorized, whose schema is the class's error. For several errors give a tuple,
error = (Unauthorized, Forbidden), as for an endpoint's error: each member answers with
its own http_api_status. S.Union(Unauthorized, Forbidden) is one schema with no status of
its own, so either error answers 500 (with its body), unless the union itself is annotated, as
in Effect. With
security={"bearer": security.bearer} it reads a bearer token; security.basic and
security.api_key(key=..., in_="header") read the other kinds. A group declared
HttpApiGroup[Authorization] puts every one of its endpoints behind it, and
endpoint.middleware(Authorization) puts one endpoint behind it.
The implementation is a layer: layer.succeed(Authorization, {"bearer": bearer}) maps each
security name to a function of the handler's effect and a SecurityOptions.
options.credential is the decoded credential, a Redacted string for a token (empty when
the request has none), and the function either fails or runs the handler with what it
provides. Pyright checks that the handler's Caller is provided.
On the client side, middleware.layer_client(Authorization, send) runs send around every
request to the middleware's endpoints: it gets a ClientMiddlewareOptions and sends the
request on with options.next(...), here with the token added. Provide it to client.make.
import pyfect as fx
from pyfect import layer, redacted
from pyfect import schema as S
from pyfect.http import router, uvicorn_server
from pyfect.http.router import Unhandled
from pyfect.http.server_response import HttpServerResponse
from pyfect.http_api import (
HttpApi,
HttpApiGroup,
builder,
client,
endpoint,
get_group,
security,
)
from pyfect.http_api.middleware import (
ClientMiddlewareOptions,
HttpApiMiddleware,
SecurityOptions,
layer_client,
)
from pyfect.redacted import Redacted
class Caller(fx.Tag[str], key="example/Caller"):
"""Who sent the request."""
class Unauthorized(S.TaggedError, annotations={"http_api_status": 401}):
message: str
# Provides a Caller to the handlers, may fail with Unauthorized, reads a bearer token.
class Authorization(
HttpApiMiddleware[Caller, Unauthorized],
key="example/Authorization",
security={"bearer": security.bearer},
):
error = Unauthorized
# HttpApiGroup[Authorization]: every endpoint of the group goes through it.
class Account(HttpApiGroup[Authorization], identifier="account"):
whoami = endpoint.get("whoami", "/whoami", success=S.String)
api = HttpApi.make("example").add(Account)
AccountLive = builder.group(
api, Account, lambda handlers: handlers.handle(Account.whoami)(lambda _: Caller())
)
tokens = {"secret-token": "ada"}
# One function per security name: it gets the handler's effect and the decoded credential.
def bearer(
handler: fx.Effect[HttpServerResponse, Unhandled, Caller], options: SecurityOptions
) -> fx.Effect[HttpServerResponse, Unhandled | Unauthorized]:
credential = options.credential
name = tokens.get(redacted.value(credential)) if isinstance(credential, Redacted) else None
if name is None:
return fx.fail(Unauthorized(message="a valid bearer token is needed"))
return handler.pipe(fx.provide_service(Caller, name))
AuthorizationLive = layer.succeed(Authorization, {"bearer": bearer})
ApiLive = builder.layer(api).pipe(
layer.provide(AccountLive.pipe(layer.provide_merge(AuthorizationLive)))
)
# The client side: a client middleware adds the token to every request of the group.
def with_token(token: str):
def send(options: ClientMiddlewareOptions):
return options.next(options.request.bearer_token(token))
return layer_client(Authorization, send)
@fx.fn
def program():
anonymous = yield from client.make(api)
refused = yield from get_group(anonymous, Account).whoami().flip()
print("without a token:", repr(refused))
authed = yield from client.make(api).pipe(fx.provide(with_token("secret-token")))
print("with a token:", (yield from get_group(authed, Account).whoami()))
served = router.serve(ApiLive, disable_logger=True, disable_listen_log=True)
fx.run_main(program().pipe(fx.provide(served)).pipe(fx.provide(uvicorn_server.layer_test())))The OpenAPI document lists the security scheme and the 401 response. An endpoint behind several security middlewares requires all of them there, while the schemes of one middleware are alternatives.
Uploads and streams#
schema.as_multipart(S.Struct(Upload, file=multipart.SingleFileSchema), max_file_size=...)
declares a multipart/form-data payload. The server writes each file part to a temporary
file before the handler runs, and the handler gets a multipart.PersistedFile with its
name, content_type and path; the file is removed when the request ends.
SingleFileSchema takes exactly one file for the field. A client sends the payload as an
http.body.FormData, built with append(name, value), where a value is a string or a
body.File(content, name, content_type). For uploads too large to keep,
as_multipart_stream gives the handler a stream of parts instead.
schema.StreamSse(data=...) declares a text/event-stream response: the handler gives a
Stream and each element is sent as one event, encoded by the schema. The client method
gives back a Stream of the decoded events, so run_for_each follows them as they arrive.
StreamSse(events=...) sends whole events (with event and id) instead of their data,
and error= encodes a failure of the stream as an event the client fails with. Event data
goes through its schema's JSON codec, so dates and big integers are strings on the wire.
As a payload, StreamNdjson(schema) takes lines of at most 1 MiB; set max_element_bytes=
for another limit. max_bytes= limits the whole body and is unset by default, since a stream
may run for as long as the client sends. A content-length over max_bytes gets a 413
before the handler runs; otherwise the handler's stream fails with HttpApiPayloadTooLarge
when it reaches a limit, whose limit is "maxElementBytes" or "maxBytes" and which
answers 413 unless the handler catches it. StreamUint8Array takes max_bytes= too.
StreamUint8Array and StreamNdjson also take a list of content types,
content_type=["application/jsonl", "application/json"]: a payload is accepted under any of
them, a response is sent with the first unless a declared content-type header picks
another, and the client decodes the stream whatever type arrives.
from pathlib import Path
from typing import TypedDict
import pyfect as fx
from pyfect import layer, stream
from pyfect import schema as S
from pyfect.http import body, multipart, router, uvicorn_server
from pyfect.http_api import (
HttpApi,
HttpApiGroup,
HttpApiRequest,
builder,
client,
endpoint,
get_group,
)
from pyfect.http_api import schema as api_schema
class Upload(TypedDict):
title: str
file: multipart.PersistedFile
class Stored(TypedDict):
title: str
name: str
size: int
class Progress(TypedDict):
done: int
total: int
class Files(HttpApiGroup, identifier="files"):
# A multipart/form-data body: the server writes file parts to disk before the handler
# runs, and SingleFileSchema takes exactly one file for the field.
upload = endpoint.post(
"upload",
"/files",
payload=api_schema.as_multipart(
S.Struct(Upload, file=multipart.SingleFileSchema), max_file_size=1_000_000
),
success=S.Struct(Stored),
)
# A text/event-stream response: each element of the stream is one event's data.
progress = endpoint.get(
"progress", "/progress", success=api_schema.StreamSse(data=S.Struct(Progress))
)
api = HttpApi.make("example").add(Files)
@fx.fn
def upload(request: HttpApiRequest[None, None, Upload, None]):
file = request.payload["file"]
content = yield from fx.blocking(lambda: Path(file.path).read_bytes())
return Stored(title=request.payload["title"], name=file.name, size=len(content))
def progress(_request: HttpApiRequest[None, None, None, None]):
return fx.succeed(stream.make(*(Progress(done=i, total=3) for i in range(1, 4))))
FilesLive = builder.group(
api,
Files,
lambda handlers: handlers.handle(Files.upload)(upload).handle(Files.progress)(progress),
)
ApiLive = builder.layer(api).pipe(layer.provide(FilesLive))
@fx.fn
def program():
files = get_group((yield from client.make(api)), Files)
# The client sends a multipart payload as FormData.
form = (
body.FormData()
.append("title", "Q3 numbers")
.append("file", body.File(b"a,b\n1,2\n", "q3.csv", "text/csv"))
)
print((yield from files.upload(payload=form)))
# An SSE endpoint's client method gives a stream of the decoded events.
events = yield from files.progress()
yield from events.run_for_each(lambda p: fx.sync(lambda: print("progress", p)))
served = router.serve(ApiLive, disable_logger=True, disable_listen_log=True)
fx.run_main(program().pipe(fx.provide(served)).pipe(fx.provide(uvicorn_server.layer_test())))OpenAPI documentation#
openapi.from_api(api) is the API's OpenAPI 3.1 document, with a JSON Schema for each
schema. Annotations add to it: openapi.Title, Version and Description on the API,
Summary, Description and Deprecated on an endpoint. builder.layer(api, openapi_path="/openapi.json") serves the document, and swagger.layer(api) and
scalar.layer(api) serve documentation pages for it, bundled so they need no network.
import json
from typing import TypedDict
import pyfect as fx
from pyfect import layer
from pyfect import schema as S
from pyfect.http import router, uvicorn_server
from pyfect.http.client import HttpClient
from pyfect.http_api import (
HttpApi,
HttpApiGroup,
HttpApiRequest,
builder,
endpoint,
openapi,
swagger,
)
class User(S.Class, identifier="User"):
id: int
name: str
class UserParams(TypedDict):
id: int
class UserNotFound(S.TaggedError, annotations={"http_api_status": 404}):
id: int
class Users(HttpApiGroup, identifier="users"):
get_user = endpoint.get(
"getUser", "/users/:id", params=S.Struct(UserParams), success=User, error=UserNotFound
).annotate(openapi.Summary, "Find a user by id")
api = HttpApi.make("example").add(Users).annotate(openapi.Title, "Users API")
# The OpenAPI 3.1 document, built from the declaration.
spec = openapi.from_api(api)
print(spec["info"])
for path, operations in spec["paths"].items():
for method, operation in operations.items():
responses = sorted(operation["responses"])
print(method.upper(), path, operation["summary"], responses)
print(json.dumps(spec["components"]["schemas"]["UserEncoded"]))
def get_user(request: HttpApiRequest[UserParams, None, None, None]):
return fx.succeed(User(id=request.params["id"], name="Ada"))
UsersLive = builder.group(api, Users, lambda handlers: handlers.handle(Users.get_user)(get_user))
# Serve the document at /openapi.json and Swagger UI at /docs, next to the API.
ApiLive = (
builder.layer(api, openapi_path="/openapi.json")
.pipe(layer.provide(UsersLive))
.pipe(layer.provide_merge(swagger.layer(api, path="/docs")))
)
@fx.fn
def program():
http = yield from HttpClient()
for path in ["/openapi.json", "/docs"]:
res = yield from http.get(path)
body = yield from res.text
print(path, res.status, res.headers["content-type"], "openapi" in body)
served = router.serve(ApiLive, disable_logger=True, disable_listen_log=True)
fx.run_main(program().pipe(fx.provide(served)).pipe(fx.provide(uvicorn_server.layer_test())))Testing handlers#
test.groups(api, (Users,), layer=TestUsers) gives a client whose requests the handlers
answer in memory: no server or port, but the same encoding, decoding and statuses as over the
network. A request the server itself would refuse, such as a body past MaxBodySize, is a
defect of the call holding the server's HttpServerError rather than its status, as in
Effect's HttpApiTest. The handlers' own services come from the layer the test passes, which stays open
until the test's scope closes, so a scoped resource in it (a database pool, a FiberMap)
is still there when a handler runs. Pyright checks that the layer provides every served
group.
Pass the layer to groups rather than piping fx.provide(TestUsers) onto it: that releases
the layer as soon as the client is made, and the handlers then run against closed services.
A FiberMap or Scope used after it closes interrupts the caller and says which one was
closed.
from typing import TypedDict
import pyfect as fx
from pyfect import layer, testing
from pyfect import schema as S
from pyfect.http_api import (
HttpApi,
HttpApiGroup,
HttpApiRequest,
builder,
endpoint,
get_group,
test,
)
class User(S.Class, identifier="User"):
id: int
name: str
class UserParams(TypedDict):
id: int
class UserNotFound(S.TaggedError, annotations={"http_api_status": 404}):
id: int
class Users(HttpApiGroup, identifier="users"):
get_user = endpoint.get(
"getUser", "/users/:id", params=S.Struct(UserParams), success=User, error=UserNotFound
)
api = HttpApi.make("example").add(Users)
class Directory(fx.Tag[dict[int, str]]): ...
@fx.fn
def get_user(request: HttpApiRequest[UserParams, None, None, None]):
names = yield from Directory()
user_id = request.params["id"]
if user_id not in names:
return (yield from UserNotFound(id=user_id))
return User(id=user_id, name=names[user_id])
UsersLive = builder.group(api, Users, lambda handlers: handlers.handle(Users.get_user)(get_user))
def close(names: dict[int, str], _exit: object) -> fx.Effect[None]:
return fx.sync(names.clear)
# The handlers' own services come from a layer the test picks. This one is a scoped
# resource, like a database pool: released, the directory is emptied.
TestDirectory = layer.effect(Directory, fx.acquire_release(fx.sync(lambda: {1: "Ada"}), close))
TestUsers = UsersLive.pipe(layer.provide(TestDirectory))
@fx.fn
def users_client():
"""A client of the API whose requests the handlers answer in memory: no server, no port,
but the same encoding, decoding and status codes. `layer=` keeps the handlers' layer
open until the test's scope closes."""
api_client = yield from test.groups(api, (Users,), layer=TestUsers)
return get_group(api_client, Users)
@testing.effect
def test_finds_a_user():
users = yield from users_client()
assert (yield from users.get_user(params={"id": 1})) == User(id=1, name="Ada")
@testing.effect
def test_a_missing_user_is_a_typed_error():
users = yield from users_client()
error = yield from users.get_user(params={"id": 2}).flip()
assert error == UserNotFound(id=2)Reference: pyfect.http_api,
pyfect.http_api.endpoint,
pyfect.http_api.builder,
pyfect.http_api.client,
pyfect.http_api.openapi,
pyfect.http_api.middleware,
pyfect.http_api.security,
pyfect.http_api.schema.