Skip to content

Dependencies

rn_forge.fastapi.dependencies

FastAPI dependencies for pagination and conditional request headers.

Factories keep endpoint-specific limits and header names in scope for FastAPI without relying on closure variables in evaluated annotations.

conditional_get(request, etag)

Return the 304 to send for request's If-None-Match, or None.

Call once the resource's current ETag is known. None means the caller proceeds with its normal 200 response; a non-None result is a :class:~fastapi.responses.Response to return as-is — 304, no body, the ETag repeated (RFC 9110 §13.1.2, §15.4.5).

Parameters:

Name Type Description Default
request Request

The inbound request.

required
etag str

The resource's current ETag validator.

required

order_by_param(*, allowed)

Return a dependency yielding the parsed AIP-132 orderBy terms.

The value is a comma-separated list of terms. A term outside allowed, a malformed one, or a repeated field is a 400 before it reaches a query. Pass the result and the decoded cursor to :func:rn_forge.web.check_cursor_order, and the canonical order from :func:rn_forge.web.format_order_by to :func:rn_forge.web.encode_cursor.

Parameters:

Name Type Description Default
allowed Collection[str]

The field names the endpoint can sort by, as they appear on the wire.

required

page_params(*, cap, default)

Return a dependency yielding (page_size, cursor) from pageSize/pageToken.

The size is clamped, never rejected (AIP-158), so the parameter carries no le= bound — that would be a 422 — and states the cap in its description instead. The token is decoded eagerly, so a tampered one is a 400 before it reaches a query.

Parameters:

Name Type Description Default
cap int

The largest page this endpoint serves.

required
default int

The page size when the client asks for none.

required

require_idempotency_key(*, header=IDEMPOTENCY_KEY_HEADER)

Return a dependency yielding the idempotency key, or raising a 400 without one.

Parameters:

Name Type Description Default
header str

The request header carrying the key.

IDEMPOTENCY_KEY_HEADER

require_if_match(*, codec=None)

Return a dependency yielding the raw If-Match value of a write.

Absent → 428, unparseable → 400, both before the route runs. The value is returned verbatim for a later :func:rn_forge.web.check_precondition call.

Parameters:

Name Type Description Default
codec ETagCodec | None

The validator format. Defaults to :class:rn_forge.web.EntityVersionETagCodec.

None