HTTP middleware (Effect's HttpMiddleware): functions from an app to
an app.
logger: logs each response (with_logger_disabledopts out)tracer: a server span per request (TracerDisabledWhen,SpanNameGenerator,TracerHeaderFilter)x_forwarded_headers: the client address behind trusted proxiessearch_params_parser: providesParsedSearchParamscors,compression,decompression
Types#
| Type | Definition | Description |
|---|---|---|
TrustedProxies | type 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) -> strVary with dimension added, unless it (or *) is there.
| Parameter | Type | Description |
|---|---|---|
headers | Mapping[str, str] | |
dimension | str |
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.
| Parameter | Type | Description |
|---|---|---|
algorithms | Sequence[CompressionAlgorithm] = _DEFAULT_ALGORITHMS | |
min_size | int = 1024 | |
compressible | Callable[[str], bool] = default_compressible | |
levels | Mapping[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 middlewaredefault_compressible#
default_compressible(content_type) -> boolText, JSON, JavaScript, XML, SVG and WebAssembly.
| Parameter | Type | Description |
|---|---|---|
content_type | str |
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 | NoneThe first of preferred the platform supports and the client
accepts (its q-values decide acceptability only).
| Parameter | Type | Description |
|---|---|---|
header | str | None | |
preferred | Sequence[CompressionAlgorithm] | |
supported | frozenset[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 Noneparse_accept_encoding#
parse_accept_encoding(header) -> dict[str, float] | NoneEach coding's quality (empty members skipped); None for a
malformed header.
| Parameter | Type | Description |
|---|---|---|
header | str |
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 acceptedcors#
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).
| Parameter | Type | Description |
|---|---|---|
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 |
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 middlewaredecompression#
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.
| Parameter | Type | Description |
|---|---|---|
max_decompressed_size | ByteSizeInput | 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 middlewareparse_content_encoding#
parse_content_encoding(header) -> tuple[Coding, ...] | NoneThe 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.
| Parameter | Type | Description |
|---|---|---|
header | str |
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 Nonex_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.
| Parameter | Type | Description |
|---|---|---|
trusted_proxies | TrustedProxies |
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 middlewarelogger#
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.
| Parameter | Type | Description |
|---|---|---|
app | Effect[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) -> strurl without its query and fragment.
| Parameter | Type | Description |
|---|---|---|
url | str |
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 urlwith_logger_disabled#
with_logger_disabled[A, E, R](eff) -> Effect[A, E, R | HttpServerRequest]eff, and the request it runs in is not logged.
| Parameter | Type | Description |
|---|---|---|
eff | Effect[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).
| Parameter | Type | Description |
|---|---|---|
app | Effect[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| Parameter | Type | Description |
|---|---|---|
fiber | Fiber[Any, Any] | |
request | ServerRequest |
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.
| Parameter | Type | Description |
|---|---|---|
urls | Sequence[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.
| Parameter | Type | Description |
|---|---|---|
app | Effect[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)))