Serving

ucall.Server takes the interfaces to answer on, and backend and cpu_class keywords naming a ucall.Backend and a ucall.CPUClass, by member or by name such as “linux-epollaio”. Its log= callable receives each line the server writes as a ucall.LogLevel and a str, on whichever thread wrote it and holding the interpreter lock, filtered by log_level= and shaped by log_format=, and metrics=ucall.Metrics(address, sample_rate, prefix, tags, interval_microseconds) sends StatsD datagrams from every event loop. An Interface also takes max_request_bytes=, past which a request is answered 413, and reply_directories=, the directories a ucall.Path part names by position. descriptor= takes a listening socket, or its descriptor, that systemd or a supervisor opened, TCP or AF_UNIX, in place of an address; the server accepts on duplicates and never closes it. Without interfaces it answers on ucall.DEFAULT_ADDRESS, “127.0.0.1:8545”. An Interface is an address, optionally pinned to a Linux device, with its own security and admission limits, so one server answers plaintext on loopback and Noise on the wire at once. It admits 1024 connections by default, reads one request per connection at a time unless pipelined_requests allows more, and replies still leave in request order. At its connection budget a new peer evicts the idle keep-alive connection that progressed least recently. Port zero binds a free port, which server.addresses reports.

import ucall

public = ucall.Interface("0.0.0.0:0", event_loops=4, connections=16_384, pipelined_requests=16)
health = ucall.Interface("127.0.0.1:0", connections=4)
server = ucall.Server(public, health, backend="automatic", cpu_class=ucall.CPUClass.SERIAL)
print(f"{server.event_loops} event loops on {server.backend.name} with {server.cpu_class.name} kernels")


@server.get("/users/{user}/files/{*path}")
def listing(user: str, path: str, limit: int = 10, hidden: bool = False):
    return {"user": user, "path": path, "limit": limit, "hidden": hidden}


@server.post("/scale")
def scale(value: float, factor: float = 2.0):
    return value * factor


@server.route("/anything", ucall.Verb.ANY)
def anything(request: ucall.Request):
    request.reply_error(501, f"{request.verb.name} is not served\n")

Endpoints register before any loop is polled, with route taking any Verb and get, post, put, delete and patch naming one. Each decorator registers the function through add_endpoint and returns it unchanged, so it stays callable from Python. Templates capture {name} segments and a greedy {*name} tail, literal segments match before captures, and registering one template and verb twice raises ucall.Error with Status.ALREADY_EXISTS. Routing is exact: an empty segment is a segment, so /users and /users/ are different paths. A path no endpoint matches answers 404, one whose endpoints take other verbs answers 405 with an allow header, a GET endpoint also serves HEAD, and OPTIONS answers 204 with the same allow list. A request that cannot be parsed answers 400, 413 or 501 before reaching any handler.

Registration reads a handler’s signature once. A handler taking one parameter annotated ucall.Request receives the request itself. Any other handler takes parameters annotated str, int, float, bool or bytes, or left bare, and each binds by name from the first place that has it:

• a placeholder of the template, as sent;
• the query, percent-decoded with ”+” as a space, a ”%” without two hexadecimal digits answering 400;
• a JSON object body, parsed once in C and only when an earlier place missed a parameter, with integers of any width kept exact;
• the parameter’s default.

Text converts as int(text) and float(text) do, bool reads “1”, “true”, “yes” and “on” or “0”, “false”, “no” and “off” in any case, and bytes takes the raw bytes. A JSON value must already have the annotated type, except that an integer widens to float and a string encodes to bytes. A missing or malformed value answers 400 with the reason as plain text, such as “missing parameter ‘limit’”, without calling the handler. Registration raises TypeError for *args, **kwargs, more than 16 parameters, or an annotation outside that list. It refuses an async def handler with TypeError too, since handlers run on the polling thread; a coroutine application registers a plain function, calls request.detach(), and replies from its own event loop.

What a handler returns becomes the reply: bytes, bytearray and memoryview as application/octet-stream, str as UTF-8 text/plain, and anything else as application/json, written in C, or through json.dumps for a value C does not write, such as a dict keyed by numbers. None from a typed handler answers 204, and None from a handler taking the request means it replies itself. A handler’s exception reaches sys.unraisablehook and answers 500, and the loop keeps serving.

server.event_loop_statistics(loop) copies one loop’s counters as a dict, from any thread while the loop runs: polls, system calls, submissions and completions, accepted connections, requests, and the bytes received, sent and copied. Divided by requests, they price one call.