Application Recipes¶

Compact routes for tasks that recur across Kinetis applications. Each recipe names the pages that hold the actual contract and routes to them rather than restating it — read those before writing code. Start at Agent Workflow if a task does not match one of these.

JSON HTTP endpoint with request DTO validation¶

Guides: Routing & Validation, Appendix: Routing & Validation.
Lifecycle/I-O: the request DTO and its controller resolve fresh from the request scope on every request; nothing about one request’s input persists past it.
Security/integrity: validation attributes run before the controller does, so a malformed request never reaches application code — put every constraint on the DTO, not in checks scattered through the controller.
Verification: a Testing TestClient request for a valid payload and for each violation, asserting the 422 and its violation list.
Non-goal: hand-written validation duplicating what a constraint attribute already expresses.

Browser form with session, CSRF, and validation errors¶

Guides: Sessions & CSRF, Routing & Validation, Middleware, Views.
Lifecycle/I-O: the session is request-scoped through SessionMiddleware; see Appendix: Container Lifecycle when a value needs to outlive one request some other way.
Security/integrity: CsrfMiddleware runs after SessionMiddleware in the pipeline; every state-changing form carries csrfToken(), and a missing or mismatched token is refused before the controller runs. A valid submission with an invalid field gets the default 422 application/problem+json response; an application that wants an HTML redirect or a re-rendered form instead must implement and bind its own ValidationExceptionRendererInterface, per Middleware’s “Rendering validation failures”.
Verification: a TestClient submission with a missing or wrong token asserting the refusal, one with a valid token and an invalid field asserting the default 422 problem document, and — only when the application installs a custom renderer — a test of that renderer’s own response instead of assuming automatic form rendering.
Non-goal: a CSRF token as the only protection on a state change that also needs its own authorization check.

Database-backed bounded list with pagination¶

Guides: Query Builder, Database.
Lifecycle/I-O: the link resolves from the shared connection kinetis/database-bridge registers on AppScope — under a persistent worker, its connection pool — not a request-scoped object; a query still suspends the calling Fiber rather than blocking the worker.
Security/integrity: page size and any filter come through the same validated DTO as the rest of the request, and every value binds as a parameter rather than being interpolated into SQL.
Verification: an integration test against a real database asserting the page boundary — the right rows, in order, with a stable cursor across an intervening write.
Non-goal: an unbounded SELECT, or an OFFSET walk over a table the application does not control the size of.

Transactional mutation with explicit failure behavior¶

Guides: Database — “Transactions”, “When a write’s outcome is unknown”, “Unique violations”.
Lifecycle/I-O: one TransactionGuard per unit of work; every statement runs on the transaction it hands the callback, never the outer link.
Security/integrity: a unique key settles a race instead of a read-then-write check, and a COMMIT that throws leaves the outcome unknown — never retried as though it were a rollback.
Verification: a test that fails a statement mid-transaction and asserts nothing committed, plus one that exercises the unique-violation path.
Non-goal: several related writes left as separate, individually committed statements outside one transaction() call.

Queue job with retry/idempotency considerations¶

Guides: Queue, the installed backend’s own page (Queue (Redis), Queue (SQL), Queue (SQS), Queue (RabbitMQ)), Appendix: Queue Contracts.
Lifecycle/I-O: a job’s constructor arguments are its whole state — nothing request-scoped from the code that pushed it survives to the worker that runs it.
Security/integrity: delivery is at least once, so a handler that is not safe to run twice needs a unique key recorded in the same transaction as its effect, per Queue’s “A job can run more than once”.
Verification: run the handler twice with the same identifier and assert one effect, and exercise the permanent-failure path at maxAttempts.
Non-goal: treating delivery as exactly-once. Leaving maxAttempts unset defers to the worker’s QUEUE_MAX_ATTEMPTS, which defaults to 0 and gives up after the first failed attempt — no setting retries a job forever, and a released job is retried immediately with no backoff.

Outbound HTTP integration with deadline/cancellation/uncertain-write semantics¶

Guides: HTTP Client, Appendix: HTTP client contracts.
Lifecycle/I-O: withTimeout() bounds the whole call, below whatever deadline is waiting on it, and withMaxResponseBytes() bounds the reply.
Security/integrity: a Transport or Timeout failure on a non-idempotent write means the request may already have taken effect — look up the result, or use the API’s own idempotency key, rather than resending it blind.
Verification: a test against a mock HTTP client for the timeout and transport-failure branches, asserting the lookup path runs instead of a blind repeat.
Non-goal: withRetries() on an endpoint whose PUT/DELETE is not actually idempotent.

Broadcast update with truthful delivery semantics¶

Guides: Broadcasting.
Lifecycle/I-O: triggering an event suspends the calling Fiber while the request to the broker is in flight; nothing about the broadcast is request-scoped state.
Security/integrity: authorize every private-/presence- channel with #[BroadcastChannel]; an unauthorized subscription is refused before it reaches the broker.
Verification: a test of the authorizer method’s own logic — accept and reject cases — rather than a live broker.
Non-goal: reading the trigger request’s success as proof a subscribed client received the event. This package reports whether the broker accepted the event, not whether, or when, any client saw it.

Application-owned MCP resource or tool¶

Guides: Model Context Protocol (MCP), Appendix: MCP Reference.
Lifecycle/I-O: each message resolves and disposes its own request scope, the same way an HTTP request does, per Model Context Protocol (MCP)’s “Each message is its own request”.
Security/integrity: a tool’s arguments validate exactly like a request DTO’s fields, and nothing about the caller’s identity persists past its own message.
Verification: a unit test of the tool or resource method’s own domain logic, plus a separate test that drives the registered definition through McpServer::handle() (see Appendix: MCP Reference’s “Malformed requests”) to exercise McpDispatcher argument hydration, validation, and the MCP result envelope — a direct method call bypasses both.
Non-goal: this documentation. mcp-docs serves only its own fixed page catalogue, whether reached directly or through Orbitron; an application’s own tools and resources are kinetis/mcp’s job.