FastAPI
The FastAPI packages add Datum's server side to your own FastAPI application: form definitions served by id, submissions validated by the same program the page runs, the form and builder assets, PDF render, fill, sign and verify, and an RFC 3161 timestamp server. You include a router for each capability. A router adds a route only when its setting is on (the management router's health routes aside), and who may call it is your own FastAPI dependencies, never a Datum policy. The server hosts page compares the hosts.
Install
Python 3.12 or newer, asyncio. The packages are not published to PyPI yet: build the workspace from the repository, then add its members to your project with the extras you need.
npm run fastapi:assets # the programs and browser files, from the repository root
cd integrations/fastapi && uv sync --all-packages --all-extras --frozen| Extra | Adds |
|---|---|
submissions | The programs, the sandbox runtime (datum-runtime-wasmtime) and the throttle |
ui | submissions, plus the form and builder browser assets |
pdf | submissions, the PDF libraries and the PDF browser assets |
timestamp | The RFC 3161 server and client |
revocation | Offline revocation checking for the PDF trust policy |
sqlalchemy | The library for SQL, see below |
testing | The test helpers and an HTTP client for Test |
all | Every extra but testing |
datum-core is the framework-free core and imports no web framework. datum-fastapi adds the routers. datum-runtime-wasmtime runs the sandbox on wasmtime, which ships native libraries for 64-bit Linux (glibc and musl), macOS and Windows on x86_64 and arm64. datum-programs, the two asset distributions and the WASM runtime distribution carry the built programs, the browser files and the sandbox module. They must all be at one version, and the start refuses a mix.
The smallest application
Put the form definition in forms/, and set DATUM_. The file's id is its key.
from fastapi import FastAPI
from datum_core.submissions import AcceptedSubmission, SubmissionReceipt
from datum_fastapi import DATUM_OPENAPI_TAGS, Datum, DatumSettings, routers
def keep(accepted: AcceptedSubmission) -> SubmissionReceipt:
# a retried attempt may reach the handler twice: store once per (form_key, version, submission_key)
return SubmissionReceipt(id="...", reference="...")
datum = Datum(config=DatumSettings().to_config(), handler=keep)
app = FastAPI(openapi_tags=DATUM_OPENAPI_TAGS)
app.include_router(routers.forms(datum))
app.include_router(routers.submissions(datum))Without a handler the default logs the form, the channel and the receipt id, stores nothing, and the start warns once a route that takes submissions is on. Including a router also starts Datum, through its lifespan. If the application runs with lifespans off, every Datum route but /livez answers 503 server..
Switching routers on
Every endpoint is off by default. Settings are read from environment variables (DATUM_ plus the dotted name in capitals, __ between levels), from a TOML file named by DATUM_, or from keyword arguments to Datum.
export DATUM_WEB__API__ENDPOINTS__SUBMISSIONS=true
export DATUM_WEB__API__ENDPOINTS__VALIDATE=true
export DATUM_WEB__API__ENDPOINTS__DEFINITION=true
export DATUM_WEB__ASSETS__ENABLED=true
export DATUM_BUILDER__ENABLED=true
export DATUM_TSA__ENABLED=trueSettings are read in this order, the first source that names a setting wins: keyword arguments to Datum, then environment variables, then the TOML file. datum. turns the warning about an unknown DATUM_* variable into a refusal to start. Every setting, with its default and bounds, is on FastAPI settings. The ones met most often are datum. (1), datum., datum. (5 s) and memory (32), datum., and datum. (60 per 60 s). A value that cannot work stops the start and names the setting, and an unknown DATUM_* variable is warned about. python -m datum_ writes the JSON Schema of every setting. The routes, bodies and codes behind these switches are on the wire.
Routers and endpoints
| Factory | Endpoints | Setting |
|---|---|---|
routers. | GET /api/, GET /api/, GET /api/ | datum., .data_ |
routers. | POST /api/, POST /api/ | .submissions, .validate |
routers. | POST /api/, POST /api/ | .test, .inspect |
routers. | host., datum-host. and the bundles under /datum/ | datum. |
routers. | POST /api/, PUT /api/, PUT /api/ | datum. |
routers. | POST /api/, /api/, /api/, /api/, GET /api/ | .pdf, .fill, .sign, .verify, .certificate |
routers. | POST /tsa, GET /tsa/, GET /tsa/ | datum. |
routers. | GET /livez, /readyz, /health, /info, and POST /recheck | datum. for /recheck |
The check route takes { document, scope } (and page for a page check): scope is required, and a bare envelope is 400 bad_. It answers 200 { accepted, errors }, with notes for warnings only when there are any. An error or a note has a message when the sandbox or a validator gave one, and none otherwise. A run that fails gives no verdict. The check route, POST /api/, the dry run, the PDF routes and POST /api/ all answer it 503 with the run's code (wasm., outcome_ or, for a registered form nested too deep, definition.) and no Retry-After, because the same run fails the same way. A definition posted to inspect that is nested too deep is the caller's: 422. Only a busy sandbox, 503 server., carries Retry-After. The wire reference has the whole contract.
The dry run answers one flat report, the same on every Datum host. The wire reference lists its members. It has no accepted member and no nested report: read outcome, and the run's time is sandbox..
Every factory takes prefix=, and every one but tsa takes dependencies=. The factories that run work for the caller or write (authoring, builder, pdf, management) require dependencies, so an unprotected router reads dependencies=[] in your source. At start the log lists the routes that are on, and warns (datum.) about a router included with every switch off. datum. makes every router add nothing but the management router's health routes.
Hooks and stores
Everything you plug in is a keyword of Datum(...). A hook is a plain callable, sync or async, and a sequence keeps the order you give it.
| Keyword | Purpose |
|---|---|
handler | Stores the accepted submission and returns the receipt |
pre_ | Refuse before the sandbox runs: (Incoming |
validators | Host-side validation after the sandbox, with errors and warnings |
rules_, context_, host_ | Add host rules, context entries, or per-form run settings |
host_ | Works out the values a form's host. names read, from the request (see below) |
definition_ | Adjust the public copy of a form on its way to a filler |
builder_, builder_ | Adjust or judge a definition before it is stored |
pdf_, pdf_ | Adjust a PDF request, or judge the PDF before it leaves |
form_, snapshot_, translation_, idempotency_ | Where forms, versions, translations and receipts live |
data_ | Providers for option lists |
throttle | Your own rate limiter, in place of the one built from datum. |
pdf_, timestamper | The seal key and where seals get their timestamps |
signature_ | Checks a signed submission's signature (the passkey routes are not served, so a signed wrapper answers 503 signing. by default) |
timestamp_, tsa_, tsa_, tsa_, tsa_, tsa_, tsa_ | The timestamp server's policy hooks, signing key, serial numbers, issue log, clients, clock and the transport of the client |
pdf_, sandbox_, pdf_ | Wrap the PDF program or the sandbox; decide which anchors make a signer trusted |
pre_ | Maps a pre-check's refusal to a status (403 and 429 by default) |
runtime, sandbox, engine_ | Replace the sandbox runtime or the engine's settings, for tests and special hosts |
error_, run_, listeners, now, withheld_ | Extra error answers, the guest's run log, event listeners, the clock, assets the page glue must not serve |
Customizers run in order, each over what the one before left, and the first refusal stops the rest. Validators all run, so every error is reported at once. A refusal is Hook: forbidden answers 403, conflict 409 and invalid 422, with a body of errors. Events follow the effect and never veto it: Submission, Submission, Submission, Submission, Journey, Form, Pdf, Pdf, Timestamp, Timestamp, Datum and Sandbox.
The stores that ship are in memory. The start warns (datum.) when a per-process store is in use, and fails (datum.) when the builder is on with in-memory stores and more than one worker. The timestamp server refuses to start with in-memory serials unless datum. acknowledges a single instance. The store protocols are the seam: implement one over your database and hold it to its contract with the classes in datum_.
The host context
A rule can read a fact about the visit, such as host.. The server judges those rules only with values it works out itself. It never reads them from the request body. Give Datum one host_ provider. It takes the form key and the call's context, and answers a JSON object or None. Read the person from the context's principal, which your principal dependency answers from the request:
from fastapi import Request
from datum_fastapi import Datum
def current_user(request: Request) -> object | None:
return getattr(request.state, "user", None)
def host_context(form_key: str, context) -> dict[str, str] | None:
user = context.principal
return {"role": user.role} if user is not None else None
datum = Datum(principal=current_user, host_context=host_context)With no provider, or a provider that answers None, every rule that reads host. is left unjudged, as before. An object, even an empty one, judges every such rule, and a name it does not hold has no value. The provider is asked for the check route, submissions, the dry run and the PDF routes. A retried submission keeps its first verdict and asks nothing. The handler sees the same values as Accepted, and a PDF is drawn with them. A provider that raises, or answers something that is not a JSON object within the sandbox's bounds (64 levels deep), is a fault in your application: the call answers 503 server. and nothing is judged. Values from the host shows the formulas.
Builder and drafts
datum. adds POST /api/, PUT /api/ and PUT /api/, and the author's copy at GET /api/, which only routers. serves. Protect the router with dependencies=. A save is checked by the sandbox kernel and refused with 409 form. when it builds on an out-of-date version. The bodies and codes are on the wire. With in-memory stores and more than one worker the start refuses a builder (datum.).
The router does not serve draft routes. A server: draft store calls four routes you write yourself: see Drafts.
Serving the form from the host
datum. serves host., the page glue datum-host. and the bundles under their build id. Server hosts shows the page code and lists every Datum method.
Sealing PDFs and timestamps
The seal needs a key. Put it in files and name them.
export DATUM_PDF__SEAL__ENABLED=true
export DATUM_PDF__SIGNING__TYPE=PKCS12
export DATUM_PDF__SIGNING__PKCS12_FILE=/etc/datum/seal.p12
export DATUM_PDF__SIGNING__PKCS12_PASSWORD=...
export DATUM_PDF__SEAL__TIMESTAMP=true
export DATUM_PDF__SIGNING__TSA__URL=https://tsa.example/tsa| Setting | Does |
|---|---|
datum., .layouts, .certify, .reason, .location, .visible | Turn the seal on, limit it to some layouts, and set what the signature says. Without a key the start warns (datum.). |
datum., .pkcs12_, .pkcs12_, .key_, .cert_, .key_ | The key: a PKCS#12 file, or a PEM key and a certificate chain. Or pass your own pdf_. |
datum. | Ask for a token over each seal. With no timestamp source the start warns (datum.). |
datum., .bearer_, .basic_, .basic_, .policy, .timeout | A timestamp server you name. Or pass your own timestamper. |
datum., .retired_ | Anchors the verify route builds a chain to, and the certificates the seal key replaced. |
datum. | Seal the PDFs of posted, unstored answers with the real key. Off, they keep a test seal. |
The host's own timestamp server is datum. with datum., a signing key under datum., and datum.: clients (the default) requires a client key from your tsa_, and open lets anyone ask within the flood limits. Every setting is on FastAPI settings.
Access control
Datum ships no access policy. Pass your own FastAPI dependencies, and they run before Datum's own checks, so a refused caller meets your 401 or 403 first.
from fastapi import Depends
app.include_router(routers.builder(datum, dependencies=[Depends(require_author)]))
app.include_router(routers.management(datum, dependencies=[Depends(require_operator)]))Fast gives your 403 the catalog's access. body. Datum(principal=..., locale=...) take dependencies that name the caller and the language for the hooks. Behind a proxy let the ASGI server decide request. (uvicorn's --proxy-headers), because the throttle never reads X-Forwarded-For itself. FastAPI has no CSRF protection of its own and Datum adds none, but the JSON endpoints accept application/ only. The definition with its server-secret rules is reachable only through routers..
Testing
Starlette's Test as a context manager runs the lifespan, so Datum starts once for the block. Share one app across a module's tests, because the runtime compiles its sandbox module on start. Install the testing extra. To test without the sandbox, pass runtime= or sandbox= to Datum.
datum_ has contract classes that hold a store of your own to its protocol. To check a running deployment against the wire contract, run datum-host-check from the conformance suite.
Health and logs
Requests are named in the logs by the X-Request-ID header, or the trace id. The management router's /health reports the runtime and the stores, and /readyz reads the runtime alone. Datum's own checks log under datum. with stable ids; datum. silences a notice or a warning by id (never an error). FastAPI settings lists every id, its cause and what to do about it.
What is not served
FastAPI serves no passkey routes, so a form cannot require a passkey signature here, and Datum is refused in the page unless you pass an endpoint. No SQL store ships either: the sqlalchemy extra installs the library, and the stores that ship are in memory. To run more than one worker, see Server hosts.
Supported versions
Python 3.12 and later. FastAPI 0.133 or newer and Starlette 1.x. wasmtime-py is held to one tested major at a time.
Every setting is on FastAPI settings, and every route on The wire.