Skip to main content

fancy-http-guard

Request guards for Starlette and FastAPI, checked before the body is parsed, and one error envelope with a request id on every response. Pure ASGI, zero runtime dependencies.

from fastapi import FastAPI, Request
import fancy_http_guard as guard

app = FastAPI()
guard.install(app)  # 1 MiB, depth 32, 10,000 members, finite numbers


@app.post("/imports")
@guard.guard(profile="upload")  # 10 MiB for this route only
async def imports(request: Request):
    data = await request.body()
    sheet = request.state.fancy_guard.read_workbook(data, field="file")
    ...

For agents. This package is not listed on the Fancy MCP catalog server yet. The server, https://ui.particle.academy/mcp (streamable HTTP, no API key; MCP id fancy-ui), lists the released Fancy packages with install commands and docs. How an agent installs and uses this package is in AGENTS.md.

Why middleware

FastAPI reads the body BEFORE it resolves dependencies, so a dependency that checks the body runs after the parse it was meant to prevent. Python's json.loads also ACCEPTS NaN and Infinity by default, so a FastAPI model with a float field takes them today. The guard sits in front:

Check Answer
Content-Length over the route's cap 413, and not one body byte is read
a missing or lying Content-Length 413 once maxBodyBytes + 1 bytes have arrived; the rest is never pulled
a malformed Content-Length (letters, a sign, two values) 400
nesting deeper than maxDepth 422 too_deep, naming the field; the scan stops there
an array or object with more than maxListLength members 422 list_too_long; the scan stops there
NaN, Infinity, -Infinity, 1e400, a 310-digit integer 422 not_finite, naming the field: items.3.price
not JSON at all 400 malformed_body

JSON bodies, and bodies with no Content-Type (FastAPI parses those as JSON), are scanned in one pass with no tree built, then replayed to your app byte for byte. Uploads are not buffered: they are counted as the app reads them.

The envelope

Every error is one shape, with the request id in the body and the X-Request-Id header (on every response, a pass included):

{"error": "body_too_large", "message": "This request is 12.4 MB, over this endpoint's limit of 10 MB.",
 "limit": {"name": "maxBodyBytes", "max": 10485760, "actual": 13002342}, "requestId": "4f8c2a9e-..."}
  • a 422 carries errors: [{error, message, field?}], with FastAPI's own validation errors converted to it;
  • a 429 or 503 carries retryAfter and Retry-After;
  • a crash is a fixed 500, in every environment, debug included: "Something went wrong on our side. If it keeps happening, quote reference 4f8c2a9e-...". The exception goes to the fancy_http_guard logger under that id, never to the response;
  • a deliberate 4xx keeps your sentence (HTTPException(410, "This invite has expired.")); a deliberate 5xx never does, unless you raise HttpError(503, "Back at 14:00 UTC.", error="maintenance", public=True);
  • responses your app RETURNS are never rewritten. Only the request-id header is added, so Inertia's 409s pass through.

@particle-academy/fancy-http-errors turns any of these, or anything else a server sends, into one sentence for the UI.

Settings: every limit is a setting

guard.install(
    app,
    limits={
        "maxBodyBytes": 1_048_576,
        "maxDepth": 32,
        "maxListLength": 10_000,
        "maxErrors": 20,
        "finiteNumbers": True,
        "workbook": {"maxRows": 100_000, "maxColumns": 1_000, "maxCells": 100_000},
    },
    profiles={"bulk": {"maxListLength": 100_000}},
    routes={"import_rows": "bulk"},  # by route name
    request_id_header="x-request-id",
    trust_incoming_request_id=False,  # True only behind a proxy that sets it
)

A bad key or value is refused when the app starts, never on the first request. Per route: @guard.guard(profile="upload"), @guard.guard(maxDepth=8), or the routes mapping. Mounted sub-apps are resolved.

Without Starlette, wrap any ASGI app: GuardMiddleware(app, limits=...). Raise HttpError and ValidationFailed([{"field", "message"}]) there instead of a framework's exceptions.

Workbooks

Rows x columns cannot be checked from the raw bytes: an xlsx's <dimension> is a claim the file makes about itself. So the guard sets the limits and holy-sheet counts them, streaming each part before one cell exists. request.state.fancy_guard.workbook_limits is holy-sheet's limits option for the route. The archive cap is the route's body cap, and the part caps follow maxCells at 64 bytes per cell. read_workbook(data, limits, field="file") reads under those limits. A refusal becomes a 413 workbook_too_large with holy-sheet's numbers, and a file that is not a spreadsheet becomes a 422 naming the field. holy-sheet is optional and only imported when you use this.

Contract

The rules are fancy-conformance suites/http/SPEC.md. This package runs all 88 rows of http/request-guards in CI, through a raw ASGI app and through FastAPI, and the Laravel guard runs the same rows. MIT.

Metadata

Release files for fancy-http-guard 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fancy-http-guard 0.1.0
File Size Uploaded Provenance Actions
fancy_http_guard-0.1.0.tar.gz 30.2 kB With provenance Details for fancy_http_guard-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fancy-http-guard 0.1.0
File Interpreter ABI Platform Actions
fancy_http_guard-0.1.0-py3-none-any.whl Python 3 none any Details for fancy_http_guard-0.1.0-py3-none-any.whl

Total release size: 51.4 kB

Release files / fancy_http_guard-0.1.0.tar.gz

Download URL fancy_http_guard-0.1.0.tar.gz
Size 30.2 kB
Tags Source
SHA-256 checksum
How to use checksums
51ebc65b159dff90d3d6294bff9d63996b4c44087e3b3cf9a53218e38e67af46
BLAKE2b-256 checksum
How to use checksums
f181d205d6dda983672c3ed2a997f50af728077cd037bc7235c5bc0441251427
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / fancy_http_guard-0.1.0-py3-none-any.whl

Download URL fancy_http_guard-0.1.0-py3-none-any.whl
Size 21.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ea5e6aacc7d28ca5444bd9ccb0c4d31dfd949cb8f9e7d82e4d887907a727996d
BLAKE2b-256 checksum
How to use checksums
f0f21603055591619f4c40017ad11824849b653e371b37987b5b668d1098f3a2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for fancy-http-guard 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for fancy_http_guard-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page