4.3 · Concepts
Structuring a Hinoki application: pattern and best practices¶
Opinionated, with reasons. It describes how the framework's features fit together; each rule is something the framework either enforces, can check with an optional rule, or leaves to review (marked enforced, rule or convention). The reference blog (examples/blog) and the small notes example (examples/notes) show the parts; examples/tracker is the layered example: 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 API classes / functions shapes, status codes, access policy, atomic=True
│ (hinoki.routing, Access, Schema)
▼
Operations plain async functions one business operation each; no Request, no HTTP types
│ (commands/queries)
▼
Persistence Model / QuerySet tables, relations, explicit loading
- HTTP layer turns a request into typed values (
Schema, path/query parameters,Caller) and an operation's result into a response schema. It contains no business rules and no SQL. - Operations hold the rules ("an editor may publish only their own draft"). They take plain arguments (
principal, aSchema, ids) so they can be called from an action, a CLI, a test, an admin hook (ModelAdmin.save) or an MCP tool. Why: an action that reads cookies or headers cannot be reused; an operation can. - Persistence never imports the HTTP layer. Rule:
Imports.forbid(source="shop.models", target="shop.api")(and the same for operations → api). - Small apps may skip the middle layer (the notes example does). Add it when an action contains a rule you would want to call from somewhere else.
2. Where each concern lives¶
| Concern | Put it | Why |
|---|---|---|
| Authentication | An auth provider (BearerAuth, JWTAuth, …) returning a Caller |
One path, identical for HTTP, admin and MCP |
| Coarse permission | Access(auth=…, permissions=[…]) on the action (or once for a function group: tasks = RouteGroup("/tasks", access=member_only, atomic=True), then @tasks.get("/")). Public is the default: protect on purpose. Rule: Actions.require_access |
A forgotten policy is the most common hole |
| Row permission (ownership, tenant) | Prefer the statement: scope aupdate/adelete by owner so the check and write are one operation. |
Avoids a check-then-write race. Hidden rows usually look missing (404). If the API promises a distinct 403 for another owner's row, preserve that contract with a conditional write and explicit fallback classification; document the information 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 the action (writes) |
Commit after the response is encoded, rollback before the error becomes HTTP. Rule: Transactions.require_atomic |
| Errors | Raise APIError subclasses and declare them on the action: @http.post(..., errors=(PostAlreadyPublished, errors.Forbidden)). A database UniqueViolation is already a 409 unique_conflict; answer exceptions you cannot change once with @app.error_handler(...) |
Failures are exceptions. The declaration (status and code come from the class) feeds OpenAPI, the MCP tool description and, in tests, ASGIClient(app, strict_errors=True), which fails on an error answer the action did not declare. A returned Response commits the transaction |
| Secrets | Settings/environment, passed to JWTKey, Admin(secret=…), never defaults |
Nothing to leak from the repository |
3. Schema classes and models¶
- Models describe tables;
Schemaclasses describe the API. Never return a model. Name them by role:PostIn/PostCreate(what a client may set),PostPatch(every fieldUNSETby default),PostOut(what a client may see). Rules:Actions.forbid_model_responses()refuses an action whose return type is aModel(also insidelist/Page/unions);Schemas.forbid_exposure("password_hash", …)keeps columns out of responses even 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 over the client's). Update withawait row.aupdate_from(patch)(writes only what was sent). Respond withPostOut.from_model(row, author_name=row.author.name). - A server-assigned field must not exist in the input schema at all; the keyword override is a second line of defence.
- Constraints and patterns belong on the
Schema, using 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 same place that builds the response, so the cost is visible in one function. - Paginate every list (
pagination=…+PageParams). Never return an unbounded list; neverawaita whole table to count or aggregate (useacount(), filters, or SQL). - Filter and order only by names you choose; never pass client-supplied column names to
filterororder_by(the admin only sorts by its displayed columns for this reason).
5. Sync and async¶
Prefer async handlers. A sync handler runs on a bounded thread pool and may use the sync model methods (Model.get, create, …) through the worker's event loop; it must not block for long, and the queue is bounded (overloaded → 503). CPU-heavy work (password hashing) goes through PasswordHasher, which has its own bounded pool and releases the GIL. Never call blocking code from an async handler.
6. Modules¶
An application is a set of modules with explicit dependencies and a lifespan (DatabaseModule, your own Module). Importing a module registers nothing and opens nothing. Resources are created in the worker's lifespan, once per worker; migrations are applied by a deploy step, never at startup, never from every worker. A standalone maintenance script such as examples/blog/seed.py owns and closes its short-lived database connection directly because it runs outside a server lifecycle.
7. Migrations¶
hinoki migrations plan writes reviewable SQL and a state file; destructive operations are flagged and need --allow-destructive; adding a NOT NULL column without a default is flagged. Review the SQL like code, apply with migrations apply against a disposable database first.
8. Testing¶
- Run the database tests against disposable servers for the backends you support: PostgreSQL uses
HINOKI_TEST_DATABASE_URL, with separate migration conformance runs for MySQL (HINOKI_TEST_MYSQL_URL) and MariaDB (HINOKI_TEST_MARIADB_URL). Without a URL, tests that require that backend are skipped; read the skip summary and do not treat another backend's green run as conformance for it. - Drive the application through the ASGI harness (no sockets) for HTTP behaviour; test operations directly.
- For security code, use independent test vectors and known expected outputs; inject the clock (
JWTAuth.now) so tests do not depend on elapsed time. - Look at rendered UI in real browsers (
tests/browser/verify.py) before calling it done.
9. Security defaults to keep¶
HTTPS terminates somewhere you control (set 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); strict CSP; passwords with Argon2id only; JWT keys with a fixed algorithm and a kid; no token, password or hash in logs or error bodies; uploads held within the 1 MiB body cap unless you add streaming; real personal data never in tests or fixtures.
10. Rules to turn on from day one¶
hinoki new generates a project with HNK-ACC-001, HNK-TXN-001 and HNK-SCH-001 enabled. Add Imports.forbid for the layer direction in section 1. Waivers live in hinoki-rules.toml, are decided by the owner, have a reason and a bounded target, and are never edited by tools or agents to make a check pass.
11. Anti-patterns¶
- Returning a
Modelor a dict built from one. - For a distinct 403 response on a write that can race, make the conditional write and fallback explicit.
- A business rule inside an action that another entry point also needs.
Response(4xx)inside aatomic=Trueaction (it commits).- Client-supplied column names reaching
filter/order_by. - Applying migrations at startup; creating a pool at import time.
- 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.
12. More than one service¶
Split a system only for a reason you can name (independent deploys, different scaling, a team boundary), because 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 what it returns as a snapshot. A write that must touch two services is a sequence of calls that can half-fail: make each step idempotent (a client-supplied key, or a natural unique constraint) and decide what a retry does before writing the code.
- Each service owns its tables. Other services call its API; they never read its database. Migrations belong to the owner 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 narrowpermissions, verified byJWTAuth); 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 mapped failure (a 502/503 you chose), never letting a client library's exception become the response.
- Share contracts, not models. Publish the response
Schemaclasses (or the OpenAPI document) that other services depend on; keepModels private.
Not covered yet: a runnable two-service example and a client helper.