Concepts
Structure an application¶
Opinionated, with reasons. Each practice below is enforced by the framework, checkable with an optional rule, or a convention left to review. The Tracker example shows them together: api → operations → models, row permission in the statements, the direction enforced by Imports.forbid, operations tested without HTTP.
1. Three layers, one direction¶
HTTP layer actions (functions or API classes) shapes, status codes, access, atomic=True
│
▼
Operations plain async functions one business operation each; no HTTP types
│
▼
Persistence Model / QuerySet tables, relations, explicit loading
- HTTP layer turns a request into typed values (
Schema, path and query parameters,Caller) and an operation's result into a responseSchema. No business rules, no SQL. - Operations hold the rules ("an editor may publish only their own draft"). They take plain arguments (
principal, aSchema, IDs), so an action, a CLI command, a test, an admin hook or an MCP tool can call them. An action that reads cookies or headers cannot be reused; an operation can. - Persistence never imports the HTTP layer. Rule:
Imports.forbid(source="notes.apps.billing.models", target="notes.apps.billing.api"), and the same for operations → api. - Small apps may skip the middle layer. Add it when an action holds a rule another entry point needs.
2. Where each concern lives¶
Actions are functions by default, grouped in a RouteGroup that states shared options once; an API class earns its place for crud(...) resources with hooks or inherited actions.
| Concern | Put it | Why |
|---|---|---|
| Routes | Each app's routes.py; prefixes only in hinoki.toml (register routes). Convention |
One place to read the map; one source per path segment |
| Authentication | A provider (BearerAuth, JWTAuth, …) returning a Caller |
One path for HTTP, admin and MCP |
| Coarse permission | access= on the action, or once on its RouteGroup. Public is the default: protect on purpose. Rule: Actions.require_access |
A forgotten policy is the most common hole |
| Row permission (owner, tenant) | The statement: scope aupdate/adelete by owner so check and write are one operation |
No check-then-write race; hidden rows look missing (404). If the API promises a distinct 403, make the conditional write and its fallback explicit, and document what it reveals |
| Input validation | The Schema (types, constraints, patterns) |
Strict, no coercion, validated in Rust before your code runs |
| Business rules | Operations | Testable without HTTP |
| Transactions | atomic=True on every write. Rule: Transactions.require_atomic |
Commit after the response is encoded; rollback before the error becomes HTTP |
| Errors | Raise APIError subclasses and declare them: errors=(InvoiceAlreadyPaid,). Translate exceptions you cannot change once with @app.error_handler(...) |
The declaration feeds OpenAPI, MCP and ASGIClient(app, strict_errors=True). A database UniqueViolation is already 409 unique_conflict. A returned Response commits the transaction |
| Secrets | Settings and the environment, never defaults | Nothing to leak from the repository |
3. Schema classes and models¶
- Models describe tables;
Schemaclasses describe the API. Never return a model: respond withInvoiceOut.from_model(row). Name classes by role:InvoiceIn(what a client may set),InvoicePatch(every fieldUNSETby default),InvoiceOut(what a client may see, often@derive(Invoice)). Rules:Actions.forbid_model_responses()refuses aModelreturn type, also insidelist,Pageand unions;Schemas.forbid_exposure("password_hash", …)keeps columns out of responses through nesting and subclasses. - Create from a
Schemaand add what only the server knows:await Post.acreate(data, author_id=principal.user.id); server values win. Update withawait row.aupdate_from(patch), which writes only what was sent. - A server-assigned field does not exist in the input
Schemaat all; the keyword override is a second line of defence. - Constraints and patterns belong on the
Schema, in the Rust pattern syntax (whole value, no look-around).
4. Relations and queries¶
- Relations are never lazy. Load what the response shows (
select_relatedfor single values,prefetch_relatedfor collections) in the function that builds the response, so the cost is visible in one place. - Paginate every list (
pagination=+PageParams+Page[...]). Never return an unbounded list; never load a whole table to count or aggregate (useacount(), filters or SQL). Rule:Actions.require_pagination. - Filter and order only by names you choose; never pass client-supplied column names to
filterororder_by.
5. Sync and async¶
Prefer async handlers. A sync handler runs on a bounded pool and uses the sync model methods; it must not block for long, and a full queue answers 503 overloaded. Password hashing has its own bounded pool. Never call blocking code from an async handler. See sync and async code.
6. Modules¶
An application is a set of modules with explicit dependencies and a lifespan (DatabaseModule, your own Module). Importing a module registers and opens nothing. Resources are created once per worker, in its lifespan. Migrations are a deploy step, never run at startup or from every worker. A standalone script owns and closes its own short-lived connection.
7. Migrations¶
hinoki migrations plan billing
hinoki migrations apply
plan writes reviewable SQL and a state file; destructive operations are flagged and need --allow-destructive, and a new NOT NULL column without a default is flagged. Review the SQL like code and apply it to a disposable database first. See migrations.
8. Testing¶
- Run database tests against disposable servers for each backend you support:
HINOKI_TEST_DATABASE_URL(PostgreSQL),HINOKI_TEST_MYSQL_URL,HINOKI_TEST_MARIADB_URL. Without a URL those tests are skipped: read the skip summary; one backend's green run is not conformance for another. - Drive HTTP behaviour through the ASGI client (no sockets); test operations directly.
- For security code, use independent test vectors and inject the clock (
JWTAuth.now).
9. Security defaults to keep¶
HTTPS terminates somewhere you control (Admin(secure_cookies=True) behind a proxy); access= on everything that is not public on purpose; CSRF on every cookie-authenticated form (the admin does it); a strict CSP; Argon2id passwords; JWT keys with a fixed algorithm and a kid; no token, password or hash in logs or error bodies; uploads within the 1 MiB body limit; no real personal data in tests or fixtures.
10. Rules to turn on from day one¶
hinoki new enables eight rules (HNK-ACC-001, HNK-ACC-002, HNK-API-001, HNK-API-002, HNK-API-003, HNK-TXN-001, HNK-SCH-001, HNK-SCH-002) and leaves the model rules HNK-DB-001 and HNK-DB-002 commented out until the first model exists. Turn those on then, and add Imports.forbid (HNK-IMP-001) for the direction in section 1. Waivers live in hinoki-rules.toml, are the owner's decision, carry a reason and a bounded target, and are never edited by tools or agents to pass a check.
11. Anti-patterns¶
- Returning a
Model, or a dict built from one. - A business rule inside an action that another entry point also needs.
Response(4xx)from anatomic=Trueaction: it commits.- Client-supplied column names reaching
filterororder_by. - Applying migrations at startup; creating a pool at import.
- A broad waiver (
*), or editing waivers to silence a rule. - Catching
Exceptionin an action to "keep going": let the framework translate it and roll back. app.include(...)in a project withhinoki.toml: list the routes inroutes.py.
12. More than one service¶
Split a system only for a reason you can name (independent deploys, different scaling, a team boundary); every split costs something the framework cannot hide.
- No joins, no shared transaction. A foreign key never crosses a service. Store the other service's ID as a plain value and treat its answers as snapshots. A write across two services is a sequence of calls that can half-fail: make each step idempotent and decide what a retry does before writing the code.
- Each service owns its tables. Others call its API, never its database. Its migrations belong to it and are applied by its deploy step (section 7).
- The caller is a
Callertoo. Service-to-service calls authenticate like any client (a JWT with a service identity and narrow permissions); do not forward the end user's token unless the callee must act as that user. - Wrap every remote call in an operation (section 1) with a timeout and a failure you chose (
502or503), never a client library's exception. - Share contracts, not models. Publish the response
Schemaclasses or the OpenAPI document; keep models private.
A runnable two-service example and a client helper do not exist yet.