GitHub

middleware

API reference for middleware.

HTTP middleware (Effect's HttpMiddleware): functions from an app to an app.

  • logger: logs each response (with_logger_disabled opts out)
  • tracer: a server span per request (TracerDisabledWhen, SpanNameGenerator, TracerHeaderFilter)
  • x_forwarded_headers: the client address behind trusted proxies
  • search_params_parser: provides ParsedSearchParams
  • cors, compression, decompression

Types

TypeDefinitionDescription
TrustedProxiestype TrustedProxies = Sequence[IpNetwork] | Callable[[IpAddress], bool]

The proxies whose forwarded headers are believed: networks, or a test.

Classes

Functions

vary_with

vary_with(headers, dimension) -> str

Vary with dimension added, unless it (or *) is there.

ParameterTypeDescription
headersMapping[str, str]
dimensionstr

Returns str

def vary_with(headers: Mapping[str, str], dimension: str) -> str:
    """``Vary`` with ``dimension`` added, unless it (or ``*``) is there."""
    vary = headers.get("vary")
    if vary is None:
        return dimension
    members = [member.strip().lower() for member in vary.split(",")]
    return vary if "*" in members or dimension.lower() in members else f"{vary}, {dimension}"

compression

compression(*, algorithms=_DEFAULT_ALGORITHMS, min_size=1024, compressible=default_compressible, levels=None) -> AppMiddleware[HttpServerRequest | HttpPlatform]

Middleware compressing compressible responses of at least min_size bytes with the first of algorithms the client accepts and HttpPlatform supports. Responses that are bodyless, partial, already encoded or no-transform are sent as they are; the others vary by Accept-Encoding.

ParameterTypeDescription
algorithmsSequence[CompressionAlgorithm] = _DEFAULT_ALGORITHMS
min_sizeint = 1024
compressibleCallable[[str], bool] = default_compressible
levelsMapping[CompressionAlgorithm, int] | None = None

Returns AppMiddleware[HttpServerRequest | HttpPlatform]

def compression(
    *,
    algorithms: Sequence[CompressionAlgorithm] = _DEFAULT_ALGORITHMS,
    min_size: int = 1024,
    compressible: Callable[[str], bool] = default_compressible,
    levels: Mapping[CompressionAlgorithm, int] | None = None,
) -> AppMiddleware[HttpServerRequest | HttpPlatform]:
    """Middleware compressing compressible responses of at least
    ``min_size`` bytes with the first of ``algorithms`` the client accepts
    and ``HttpPlatform`` supports. Responses that are bodyless, partial,
    already encoded or ``no-transform`` are sent as they are; the others
    vary by ``Accept-Encoding``."""
    level_of = {**_DEFAULT_LEVELS, **(levels or {})}

    def transform(
        platform: Compression, accept: str | None, response: HttpServerResponse
    ) -> Effect[HttpServerResponse]:
        unchanged = _sent_as_is(response, compressible)
        if unchanged is not None:
            return succeed(unchanged)
        algorithm = negotiate(accept, algorithms, platform.algorithms)
        length = response.body.content_length
        if length is None:
            length = parse_content_length(response.headers.get("content-length"))
        if algorithm is None or (length is not None and length < min_size):
            return succeed(_with_vary(response))
        return platform.compress_response(response, algorithm, level_of.get(algorithm))

    def middleware[E, R](
        app: Effect[HttpServerResponse, E, R],
    ) -> Effect[HttpServerResponse, E, R | HttpServerRequest | HttpPlatform]:
        def body(fiber: Fiber[Any, Any]) -> Effect[HttpServerResponse, E, R]:
            platform = fiber._context.get_unsafe(HttpPlatform).compression

            def pre_response(
                request: ServerRequest, response: HttpServerResponse
            ) -> Effect[HttpServerResponse, HttpServerError]:
                return transform(platform, request.headers.get("accept-encoding"), response)

            append_pre_response_handler_unsafe(fiber._context, pre_response)
            return app

        return _WithFiber(body)

    return middleware

default_compressible

default_compressible(content_type) -> bool

Text, JSON, JavaScript, XML, SVG and WebAssembly.

ParameterTypeDescription
content_typestr

Returns bool

def default_compressible(content_type: str) -> bool:
    """Text, JSON, JavaScript, XML, SVG and WebAssembly."""
    kind = content_type.split(";", 1)[0].strip().lower()
    return kind.startswith("text/") or kind in _COMPRESSIBLE or kind.endswith(("+json", "+xml"))

negotiate

negotiate(header, preferred, supported) -> CompressionAlgorithm | None

The first of preferred the platform supports and the client accepts (its q-values decide acceptability only).

ParameterTypeDescription
headerstr | None
preferredSequence[CompressionAlgorithm]
supportedfrozenset[CompressionAlgorithm]

Returns CompressionAlgorithm | None

def negotiate(
    header: str | None,
    preferred: Sequence[CompressionAlgorithm],
    supported: frozenset[CompressionAlgorithm],
) -> CompressionAlgorithm | None:
    """The first of ``preferred`` the platform supports and the client
    accepts (its q-values decide acceptability only)."""
    if header is None:
        return None
    accepted = parse_accept_encoding(header)
    if accepted is None:
        return None
    for algorithm in preferred:
        if algorithm not in supported:
            continue
        quality = accepted.get(algorithm, accepted.get("*"))
        if quality is not None and quality > 0:
            return algorithm
    return None

parse_accept_encoding

parse_accept_encoding(header) -> dict[str, float] | None

Each coding's quality (empty members skipped); None for a malformed header.

ParameterTypeDescription
headerstr

Returns dict[str, float] | None

def parse_accept_encoding(header: str) -> dict[str, float] | None:
    """Each coding's quality (empty members skipped); ``None`` for a
    malformed header."""
    accepted: dict[str, float] = {}
    for part in header.split(","):
        member = ";".join(piece.strip(" \t") for piece in part.strip().lower().split(";"))
        if not member:
            continue
        match = _ACCEPT_MEMBER.match(member)
        if match is None:
            return None
        quality = match.group(2)
        accepted[match.group(1)] = 1.0 if quality is None else float(quality)
    return accepted

cors

cors(*, allowed_origins=(), allowed_methods=_DEFAULT_METHODS, allowed_headers=(), exposed_headers=(), max_age=None, credentials=False) -> AppMiddleware[HttpServerRequest]

Middleware answering preflight OPTIONS requests (204) and adding the CORS headers to every response. With no allowed_origins every origin is allowed (*); with several (or a test) the request's origin is echoed when allowed, and responses vary by Origin. A request from an origin that is not allowed is still served: only the browser withholds the response, so CORS is no access control. credentials needs allowed_origins without *: browsers refuse credentials with *, so that combination raises ValueError here (Effect sends it).

ParameterTypeDescription
allowed_originsAllowedOrigins = ()
allowed_methodsSequence[str] = _DEFAULT_METHODS
allowed_headersSequence[str] = ()
exposed_headersSequence[str] = ()
max_ageint | None = None
credentialsbool = False

Returns AppMiddleware[HttpServerRequest]

def cors(
    *,
    allowed_origins: AllowedOrigins = (),
    allowed_methods: Sequence[str] = _DEFAULT_METHODS,
    allowed_headers: Sequence[str] = (),
    exposed_headers: Sequence[str] = (),
    max_age: int | None = None,
    credentials: bool = False,
) -> AppMiddleware[HttpServerRequest]:
    """Middleware answering preflight ``OPTIONS`` requests (204) and adding
    the CORS headers to every response. With no ``allowed_origins`` every
    origin is allowed (``*``); with several (or a test) the request's
    origin is echoed when allowed, and responses vary by ``Origin``. A
    request from an origin that is not allowed is still served: only the
    browser withholds the response, so CORS is no access control.
    ``credentials`` needs ``allowed_origins`` without ``*``: browsers refuse
    credentials with ``*``, so that combination raises ``ValueError`` here (Effect
    sends it)."""
    if (
        credentials
        and not callable(allowed_origins)
        and (not allowed_origins or "*" in allowed_origins)
    ):
        raise ValueError("cors(credentials=True) needs allowed_origins; browsers refuse '*'")
    is_allowed: Callable[[str], bool]
    if callable(allowed_origins):
        is_allowed = allowed_origins
        echo = True
        fixed: dict[str, str] = {}
    else:
        origins = tuple(allowed_origins)

        is_allowed = origins.__contains__

        echo = len(origins) > 1
        fixed = (
            {"access-control-allow-origin": "*"}
            if not origins
            else {"access-control-allow-origin": origins[0], "vary": "Origin"}
        )

    def allow_origin(origin: str | None) -> dict[str, str]:
        if not echo:
            return fixed
        if origin is None or not is_allowed(origin):
            return {"vary": "Origin"}
        return {"access-control-allow-origin": origin, "vary": "Origin"}

    allow_credentials = {"access-control-allow-credentials": "true"} if credentials else {}
    allow_methods = (
        {"access-control-allow-methods": ", ".join(allowed_methods)} if allowed_methods else {}
    )
    expose = {"access-control-expose-headers": ",".join(exposed_headers)} if exposed_headers else {}
    max_age_header = {"access-control-max-age": str(max_age)} if max_age else {}

    def allow_headers(requested: str | None) -> dict[str, str]:
        if not allowed_headers and requested:
            return {
                "vary": "Access-Control-Request-Headers",
                "access-control-allow-headers": requested,
            }
        return {"access-control-allow-headers": ",".join(allowed_headers)}

    def from_request(request: ServerRequest) -> Headers:
        return Headers(
            {**allow_origin(request.headers.get("origin")), **allow_credentials, **expose}
        )

    def from_preflight(request: ServerRequest) -> Headers:
        headers = Headers(
            {
                **allow_origin(request.headers.get("origin")),
                **allow_credentials,
                **expose,
                **allow_methods,
                **max_age_header,
            }
        )
        access = allow_headers(request.headers.get("access-control-request-headers"))
        vary = access.get("vary")
        if vary is not None:
            access = {**access, "vary": vary_with(headers, vary)}
        return headers.set_all(access)

    def pre_response(
        request: ServerRequest, response: HttpServerResponse
    ) -> Effect[HttpServerResponse, HttpServerError]:
        headers = from_request(request)
        if "vary" in headers:
            headers = headers.set("vary", vary_with(response.headers, "Origin"))
        return succeed(response.set_headers(headers))

    def middleware[E, R](
        app: Effect[HttpServerResponse, E, R],
    ) -> Effect[HttpServerResponse, E, R | HttpServerRequest]:
        def body(fiber: Fiber[Any, Any]) -> Effect[HttpServerResponse, E, R]:
            request = fiber._context.get_unsafe(HttpServerRequest)
            if request.method == "OPTIONS":
                return succeed(empty(status=204, headers=from_preflight(request)))
            append_pre_response_handler_unsafe(fiber._context, pre_response)
            return app

        return _WithFiber(body)

    return middleware

decompression

decompression(*, max_decompressed_size=None) -> AppMiddleware[HttpServerRequest]

Middleware decoding gzip and deflate request bodies; an unsupported coding is answered with 415 before the app runs.

ParameterTypeDescription
max_decompressed_sizeByteSizeInput | None = None

Returns AppMiddleware[HttpServerRequest]

def decompression(
    *, max_decompressed_size: ByteSizeInput | None = None
) -> AppMiddleware[HttpServerRequest]:
    """Middleware decoding gzip and deflate request bodies; an unsupported
    coding is answered with 415 before the app runs."""
    limit = None if max_decompressed_size is None else from_input_unsafe(max_decompressed_size)

    def middleware[E, R](
        app: Effect[HttpServerResponse, E, R],
    ) -> Effect[HttpServerResponse, E, R | HttpServerRequest]:
        def body(fiber: Fiber[Any, Any]) -> Effect[HttpServerResponse, E, R]:
            request = fiber._context.get_unsafe(HttpServerRequest)
            encoding = request.headers.get("content-encoding")
            if encoding is None or not has_body(request.method):
                return app
            codings = parse_content_encoding(encoding)
            if codings is None:
                return succeed(empty(status=415, headers={"accept-encoding": "gzip, deflate"}))
            if not codings:
                return app
            decompressed = DecompressedRequest(request, codings, limit)
            return _Locally(app, lambda ctx: ctx.add(HttpServerRequest, decompressed))

        return _WithFiber(body)

    return middleware

parse_content_encoding

parse_content_encoding(header) -> tuple[Coding, ...] | None

The codings of a content-encoding header in the order applied (identity dropped); None when one is not supported or more than MAX_CODINGS are stacked.

ParameterTypeDescription
headerstr

Returns tuple[Coding, ...] | None

def parse_content_encoding(header: str) -> tuple[Coding, ...] | None:
    """The codings of a ``content-encoding`` header in the order applied
    (``identity`` dropped); ``None`` when one is not supported or more than
    ``MAX_CODINGS`` are stacked."""
    codings: list[Coding] = []
    for member in header.split(","):
        coding = member.strip().lower()
        if coding in ("", "identity"):
            continue
        if coding not in ("gzip", "deflate"):
            return None
        codings.append("gzip" if coding == "gzip" else "deflate")
    return tuple(codings) if len(codings) <= MAX_CODINGS else None

x_forwarded_headers

x_forwarded_headers(trusted_proxies) -> AppMiddleware[HttpServerRequest]

Middleware taking the client address (and its aligned X-Forwarded-Host / -Proto) from X-Forwarded-For when the transport peer is a trusted proxy: the rightmost hop that is not one, stopping at an entry that is not an address.

ParameterTypeDescription
trusted_proxiesTrustedProxies

Returns AppMiddleware[HttpServerRequest]

def x_forwarded_headers(
    trusted_proxies: TrustedProxies,
) -> AppMiddleware[HttpServerRequest]:
    """Middleware taking the client address (and its aligned
    ``X-Forwarded-Host`` / ``-Proto``) from ``X-Forwarded-For`` when the
    transport peer is a trusted proxy: the rightmost hop that is not one,
    stopping at an entry that is not an address."""
    trusted: Callable[[IpAddress], bool]
    if callable(trusted_proxies):
        trusted = trusted_proxies
    else:
        networks = tuple(trusted_proxies)

        def in_networks(address: IpAddress) -> bool:
            return any(ip_network.contains(network, address) for network in networks)

        trusted = in_networks

    def middleware[E, R](
        app: Effect[HttpServerResponse, E, R],
    ) -> Effect[HttpServerResponse, E, R | HttpServerRequest]:
        def body(fiber: Fiber[Any, Any]) -> Effect[HttpServerResponse, E, R]:
            request = _apply(fiber._context.get_unsafe(HttpServerRequest), trusted)
            return _Locally(app, lambda ctx: ctx.add(HttpServerRequest, request))

        return _WithFiber(body)

    return middleware

logger

logger[E, R](app) -> Effect[HttpServerResponse, E, R | HttpServerRequest]

Log "Sent HTTP response" (or the failure's cause) with the method, path and status, in an http.span log span.

ParameterTypeDescription
appEffect[HttpServerResponse, E, R]

Returns Effect[HttpServerResponse, E, R | HttpServerRequest]

def logger[E, R](
    app: Effect[HttpServerResponse, E, R],
) -> Effect[HttpServerResponse, E, R | HttpServerRequest]:
    """Log ``"Sent HTTP response"`` (or the failure's cause) with the
    method, path and status, in an ``http.span`` log span."""
    require_effect(app, "app")

    def body(fiber: Fiber[Any, Any]) -> Effect[HttpServerResponse, E, R | HttpServerRequest]:
        request = fiber._context.get_unsafe(HttpServerRequest)
        state = _request_state.get(fiber._context)
        path = strip_search_and_hash(request.url)

        def after(exit: Exit[HttpServerResponse, E]) -> Effect[HttpServerResponse, E]:
            if state is not None and state.logger_disabled:
                return from_exit(exit)
            message: object = "Sent HTTP response"
            if isinstance(exit, Failure):
                response, cause = cause_response_stripped(exit.cause)
                if cause is not None and not all(
                    isinstance(reason, Interrupt) and ClientAbort in reason.annotations
                    for reason in cause.reasons
                ):
                    message = cause
                status = response.status
            else:
                status = exit.value.status
            logged = log(message).annotate_logs(
                {"http.method": request.method, "http.url": path, "http.status": status}
            )
            return logged.and_then(from_exit(exit))

        return app.exit().flat_map(after).with_log_span("http.span")

    return _WithFiber(body)

strip_search_and_hash

strip_search_and_hash(url) -> str

url without its query and fragment.

ParameterTypeDescription
urlstr

Returns str

def strip_search_and_hash(url: str) -> str:
    """``url`` without its query and fragment."""
    ends = [index for index in (url.find("?"), url.find("#")) if index != -1]
    return url[: min(ends)] if ends else url

with_logger_disabled

with_logger_disabled[A, E, R](eff) -> Effect[A, E, R | HttpServerRequest]

eff, and the request it runs in is not logged.

ParameterTypeDescription
effEffect[A, E, R]

Returns Effect[A, E, R | HttpServerRequest]

def with_logger_disabled[A, E, R](eff: Effect[A, E, R]) -> Effect[A, E, R | HttpServerRequest]:
    """``eff``, and the request it runs in is not logged."""
    require_effect(eff, "eff")

    def body(fiber: Fiber[Any, Any]) -> Effect[A, E, R]:
        state = _request_state.get(fiber._context)
        if state is not None:
            state.logger_disabled = True
        return eff

    return _WithFiber(body)

search_params_parser

search_params_parser[E, R](app) -> Effect[HttpServerResponse, E, R | HttpServerRequest]

app with ParsedSearchParams: the request URL's query as a record (a repeated key gives a list).

ParameterTypeDescription
appEffect[HttpServerResponse, E, R | ParsedSearchParams]

Returns Effect[HttpServerResponse, E, R | HttpServerRequest]

def search_params_parser[E, R](
    app: Effect[HttpServerResponse, E, R | ParsedSearchParams],
) -> Effect[HttpServerResponse, E, R | HttpServerRequest]:
    """``app`` with ``ParsedSearchParams``: the request URL's query as a
    record (a repeated key gives a list)."""
    require_effect(app, "app")

    def body(fiber: Fiber[Any, Any]) -> Effect[HttpServerResponse, E, R]:
        request = fiber._context.get_unsafe(HttpServerRequest)
        params = search_params_from_url(parse(request.original_url, "http://localhost"))
        return _Locally(app, lambda ctx: ctx.add(ParsedSearchParams, params))

    return _WithFiber(body)

is_tracer_disabled_unsafe

is_tracer_disabled_unsafe(fiber, request) -> bool
ParameterTypeDescription
fiberFiber[Any, Any]
requestServerRequest

Returns bool

def is_tracer_disabled_unsafe(fiber: Fiber[Any, Any], request: ServerRequest) -> bool:
    return not fiber.get_ref(TracerEnabled) or fiber.get_ref(TracerDisabledWhen)(request)

layer_tracer_disabled_for_urls

layer_tracer_disabled_for_urls(urls) -> Layer[TracerDisabledWhen]

No spans for requests to exactly these URLs.

ParameterTypeDescription
urlsSequence[str]

Returns Layer[TracerDisabledWhen]

def layer_tracer_disabled_for_urls(urls: Sequence[str]) -> Layer[TracerDisabledWhen]:
    """No spans for requests to exactly these URLs."""
    disabled = tuple(urls)
    return layer_succeed(TracerDisabledWhen, lambda request: request.url in disabled)

tracer

tracer[E, R](app) -> Effect[HttpServerResponse, E, R | HttpServerRequest]

Run app in a server span named by SpanNameGenerator, a child of the span in the request's trace headers, with the HTTP attributes of the request and response.

ParameterTypeDescription
appEffect[HttpServerResponse, E, R]

Returns Effect[HttpServerResponse, E, R | HttpServerRequest]

def tracer[E, R](
    app: Effect[HttpServerResponse, E, R],
) -> Effect[HttpServerResponse, E, R | HttpServerRequest]:
    """Run ``app`` in a server span named by ``SpanNameGenerator``, a child
    of the span in the request's trace headers, with the HTTP attributes of
    the request and response."""
    require_effect(app, "app")

    def body(
        fiber: Fiber[Any, Any], restore: Restore
    ) -> Effect[HttpServerResponse, E, R | HttpServerRequest]:
        request = fiber._context.get_unsafe(HttpServerRequest)
        if is_tracer_disabled_unsafe(fiber, request):
            return restore(app)
        parent = trace_context.from_headers(request.headers)
        options: SpanOptions = {"kind": "server"}
        if parent is not None:
            options["parent"] = parent
        span = make_span_unsafe(fiber, fiber.get_ref(SpanNameGenerator)(request), options)

        def finish(exit: Exit[HttpServerResponse, E]) -> Effect[None]:
            return sync(lambda: _end(fiber, span, request, exit))

        inner: Effect[HttpServerResponse, E, R | HttpServerRequest] = _Locally(
            app, lambda ctx: ctx.add(ParentSpan, span)
        )
        return restore(inner).on_exit(finish)

    # The span is made and its end registered in one uninterruptible step.
    return uninterruptible_mask(lambda restore: _WithFiber(lambda fiber: body(fiber, restore)))