sextile.middleware

Middleware: what wraps every page, and the two the framework ships.

Middleware is the type and CallNext the rest of the chain it is handed; chained composes a sequence of them round a page builder. Middleware answers what is true of every page, where a handler answers what one page says. The framework ships the two that every service turns out to want and nothing else: what a service should log about itself is not a question a framework can answer, but that it should log something is not in doubt.

log_pages writes to the machine’s log, for whoever runs the service. record_visits writes to a log the service can read back, for whoever reads it – a list of what has been looked at lately is a page, not a diagnostic.

Written as functions returning middleware rather than as classes, because each of them is one closure over one setting and a class would be four lines of ceremony round it.

type sextile.middleware.CallNext = Callable[[PageRequest], Awaitable[Page | None]]

The rest of the chain, handed to a middleware to call or to answer instead of.

type sextile.middleware.Middleware = Callable[[PageRequest, CallNext], Awaitable[Page | None]]

Something wrapped round every page a service builds.

Given the request and CallNext, the rest of the chain. It may read the request, call CallNext and change what comes back, or answer instead and never call it. A handler answers what one page builds; middleware answers what is true of every page – who is asking, how long it took, whether they may.

sextile.middleware.log_pages(logger=None, *, slow=1.0, clock=<built-in function monotonic>)

Return middleware that logs every page a service builds and its build time.

Parameters:

• logger (Logger | None) – Where to write, or the sextile.serving logger by default.

• slow (float) – Seconds past which a build is logged as a warning rather than info. It separates a slow build from a slow wire, which the far end of a telephone line cannot tell apart.

• clock (Callable[[], float]) – What reads the time, for a test to control.

Return type:

Callable[[PageRequest, Callable[[PageRequest], Awaitable[Page | None]]], Awaitable[Page | None]]

Returns:

A Middleware. A page that is not there is logged too, so the count is not quietly short of the numbers nobody could reach.

sextile.middleware.record_visits(visits, *, token=<function _token>)

Return middleware that records every page built, for the readership pages.

Parameters:

• visits (StateKey[Visits]) – The StateKey the log is held under, the same key handlers.recent/popular/callers read. The log is read from request.state per page, not held here, so a service can open it in its lifespan where a thing that must be closed belongs.

• token (Callable[[], str]) – What mints a caller’s opaque name, for a test to control. Minted the first time a session is seen and kept in it after, so a count of readers says how many and nothing about who.

Return type:

Callable[[PageRequest, Callable[[PageRequest], Awaitable[Page | None]]], Awaitable[Page | None]]

Returns:

A Middleware. A page that was not there is recorded too, and left out of what is read back rather than out of the log.