GuidesRuntime
Serve an application¶
From the project directory:
hinoki dev
hinoki serve
hinoki dev reloads on every change while you work; hinoki serve runs without
reload, with the workers your settings ask for. Both read the application from
project.application in hinoki.toml. To run another application, pass its
target: module:app, such as hinoki dev notes.main:app. A function callable
without arguments that returns an application (a factory) is also accepted.
Each worker imports the target, then opens what the application owns (database pool, modules) in its lifespan and closes it on shutdown. Importing your code never opens a connection. See database connection ownership.
Choose a server¶
Both commands run on Kiso, Hinoki's own Rust server, unless you choose Granian:
| Kiso (default) | Granian | |
|---|---|---|
| What it is | Hinoki's HTTP server in the native extension (Rust: hyper, tokio, rustls) | A general-purpose ASGI server, installed with the server extra |
| Runs on the native lane | Eligible routes skip Python routing and binding (details) | Every request goes through the ASGI pipeline |
| Access log | Kiso's own, with access_log_format, access_log_skip, server_timing |
Granian's |
| Hinoki middleware | Yes; the route runs in Python instead of the native lane | Yes, identical |
| ASGI wrapper around the app | Not possible: there is no ASGI boundary | Yes, run the wrapper with granian (metrics) |
| WSGI | --interface wsgi: Python threads behind Kiso's listener, not native (WSGI) |
--interface wsgi |
Choose per run with a flag, or per project in settings:
hinoki serve --server granian
# notes/settings.py
from hinoki import settings
class ProjectSettings(settings.AppSettings, prefix="NOTES_", dotenv=".env"):
server: settings.ServerSettings = settings.ServerSettings(server="granian")
hinoki new --server granian (or the server question of hinoki new) writes the
same choice to settings.toml; NOTES_SERVER__SERVER=kiso overrides it for one
environment. What Kiso runs natively, its limits, signals and proxy handling are
on Kiso server.
Set host, port and workers¶
They come from the application's server settings group; flags override them:
| Setting | Variable | Default | Flag |
|---|---|---|---|
server.host |
NOTES_SERVER__HOST |
127.0.0.1 |
--host |
server.port |
NOTES_SERVER__PORT |
8000 |
--port |
server.workers |
NOTES_SERVER__WORKERS |
1 |
--workers (serve) |
server.runtime_threads |
NOTES_SERVER__RUNTIME_THREADS |
1 |
|
server.backlog |
NOTES_SERVER__BACKLOG |
1024 |
|
server.access_log |
NOTES_SERVER__ACCESS_LOG |
unset | Unset logs in hinoki dev only (or whenever access_log_format is set); true or false decides for both |
server.access_log_skip |
NOTES_SERVER__ACCESS_LOG_SKIP |
unset | Kiso only: comma-separated paths the log leaves out (health checks); exact, or a prefix when the entry ends with * |
server.server_timing |
NOTES_SERVER__SERVER_TIMING |
unset | Kiso only: add a Server-Timing header (kiso;dur=3.2;desc="native": milliseconds the server took and the serving lane, with the same values as the access log's lane); unset means hinoki dev only |
server.recent_requests |
NOTES_SERVER__RECENT_REQUESTS |
unset | Kiso only: file that also receives each request as a JSON line, read by the recent_requests tool of hinoki mcp; rotated near 1 MiB |
server.access_log_slow_ms |
NOTES_SERVER__ACCESS_LOG_SLOW_MS |
unset | Kiso only: keep only answers at least this slow, in milliseconds |
server.access_log_format |
NOTES_SERVER__ACCESS_LOG_FORMAT |
unset | Kiso only: pretty, plain, json or logger. Unset is pretty on a colour terminal and plain otherwise |
server.server |
NOTES_SERVER__SERVER |
kiso |
--server |
The connection limits and timeouts (max_connections, header_read_timeout, body_read_timeout, write_timeout), native_dispatch, the TLS files and http2, and trusted_proxies are described under Kiso and in the settings table. Left unset, they are None in hinoki settings and Kiso applies its own defaults (for example 10000 connections and a 10-second header timeout), so that Granian can refuse the Kiso-only ones only when you set them.
dev always runs one worker with reload. hinoki settings shows what is in
effect (Inspect an application).
Before serving a deployment, narrow allowed_hosts
to the names it answers to (NOTES_ALLOWED_HOSTS=app.example.com). While it is
the default * and debug is off, each worker logs allowed_hosts is '*' and
debug is off: ... at startup, on every server.
Settings that apply to one server only¶
hinoki serve refuses a setting the chosen server cannot honour, by name, and exits with status 2; it never ignores it or falls back to the other server.
| Setting | Kiso | Granian |
|---|---|---|
host, port, workers, runtime_threads, backlog, access_log, trusted_proxies, request_id_header, trust_request_id, tls_cert_file, tls_key_file, http2 |
applied | applied |
max_connections, header_read_timeout, body_read_timeout, write_timeout, native_dispatch, access_log_format, access_log_skip, access_log_slow_ms, recent_requests, server_timing |
applied when set | refused when set |
If the native extension of a build has no Kiso, --server kiso fails with an error that says so.
Optional startup probe¶
Hinoki(startup_url="/health") reserves one public, fixed GET/HEAD endpoint and returns {"status":"ok"} after that worker's lifespan startup has completed. The setting is off by default. Its path must be a literal ASCII path; query strings, fragments, parameters, percent escapes and dot segments are rejected. It must not match an application route or an enabled OpenAPI/docs path. The endpoint is not an application route and does not appear in OpenAPI or generated CRUD/MCP tools.
This is a startup probe, not a general readiness or liveness check. A 200 says that startup completed (and, on Kiso, its request wake reader was installed); it does not check database availability, downstream services, request capacity, or whether the Python event loop continues to make progress. It answers independently of the Python request queue when Kiso can apply the response directly. Before readiness it returns 503 not_ready; during shutdown readiness is cleared before graceful draining begins.
ASGI/Granian and WSGI answer it in the Python pipeline after host, CORS and HTTPS-redirect checks. Kiso checks host restrictions, answers CORS preflights and redirects plain HTTP requests on its Tokio thread before it considers the probe. GET and HEAD negotiate application/json and validate query syntax; other methods return 405 with Allow: GET, HEAD, unless CORS answers a preflight first. WSGI reads request bodies before the pipeline, so its body-size behavior differs from Kiso for a body sent to this GET/HEAD endpoint. WSGI also starts lazily on the first request and uses its adapter-level 503 if startup fails. Since WSGI exposes a decoded PATH_INFO rather than the raw request path, percent-encoded aliases may be indistinguishable from the literal probe path there.
Other runners¶
dev and serve are conveniences. The application is a plain ASGI app, so any
ASGI server can run it directly; the server settings group is then ignored,
because only hinoki serve applies it:
granian --interface asgi notes.main:app
Metrics and tracing¶
Hinoki ships no metrics registry, exporter or tracing integration, and no health route besides the optional startup probe. On an ASGI server the application is a plain ASGI callable, so wrap it with the instrumentation you already use, or with a few lines of your own:
# notes/metrics.py
import time
class Timing:
"""Report each request's method, status and duration to ``record``."""
def __init__(self, app, record):
self.app, self.record = app, record
async def __call__(self, scope, receive, send):
if scope["type"] != "http":
await self.app(scope, receive, send)
return
started, status = time.monotonic(), None
async def watch(message):
nonlocal status
if message["type"] == "http.response.start":
status = message["status"]
await send(message)
try:
await self.app(scope, receive, watch)
finally: # status stays None when the request was aborted before a response began
self.record(scope["method"], status, time.monotonic() - started)
from notes.main import app as notes_app
app = Timing(notes_app, record=my_metrics.observe) # serve with any ASGI server
What this measures is the time from the ASGI call to the last byte handed to the server, not what a client perceives. Keep method and status as labels; do not label by scope["path"] (it holds ids and has unbounded cardinality), the request ID (it is for correlating logs: logging.include_request_id adds it to each Hinoki log line) or the caller. Hinoki does not currently expose the matched route template to a wrapper, so per-route metrics need an application-level counter inside the handler or a gap report so a hook can be designed.
Kiso has no ASGI boundary, so this wrapper does not apply to it and it has no instrumentation seam today. Use the server's own limits and access log and the request log of your proxy, or serve with Granian when you need to wrap the application.
WSGI¶
ASGI is the intended way to serve Hinoki. When a deployment can only run WSGI, wrap the application:
# wsgi.py
from hinoki.wsgi import WSGIAdapter
from notes.main import app
wsgi_app = WSGIAdapter(app)
hinoki serve wsgi:wsgi_app --interface wsgi # Kiso
hinoki serve wsgi:wsgi_app --interface wsgi --server granian # Granian
--interface wsgi (or server.interface = "wsgi" on the application the
WSGIAdapter wraps) tells hinoki serve that the target is a WSGI callable
rather than a Hinoki application; the default is asgi. The target may be a
WSGIAdapter or any (environ, start_response) callable, but not a factory
and not a Hinoki application (the error names WSGIAdapter). A project
whose server.interface is wsgi refuses an ASGI target unless you pass
--interface asgi. granian --interface wsgi wsgi:wsgi_app still works for a
deployment that runs Granian directly.
WSGI on Kiso¶
Kiso owns the listener and calls the callable from a fixed pool of Python
threads (execution.sync_workers) with a queue of execution.sync_queue
waiting requests; beyond both the answer is 503 with Retry-After: 1. This
path is not native: the application, the environment and every response chunk
are Python objects, and the request crosses the interpreter lock. Rust owns the
sockets, TLS, the access log, the limits and the end of the response.
- Request body. Read in full before the call, up to
execution.max_body_bytes:413above it,408if it stalls,400if malformed. Kiso therefore answers413for a body Granian's WSGI interface would pass on (Granian has no limit). - Response. Streamed: the head goes out with the first piece, a slow client slows the application down (a bounded buffer), and a client that leaves makes the next write fail and closes the iterable. An exception before the head answers
500with an empty body and the traceback in the log; after it, the stream is reset instead of ending as complete. - Timeout.
execution.request_timeoutbounds the time until the response starts (504). A running sync call cannot be stopped; it keeps its thread until it returns. - Applies: TLS and HTTP/2,
access_logandaccess_log_format,server_timing,max_connections, header and body timeouts,--workersand graceful shutdown (lifecycle.shutdown_timeout). - Does not apply: the native lane (
native_dispatchis refused), host, CORS and redirect policies of the server (a wrapped Hinoki application still applies its own), andtrusted_proxies(refused: the client address is the TCP peer). - Lifespan. A plain callable has none. A
WSGIAdapterstarts its application's modules when the worker starts, not on the first request, and stops them on a graceful stop.
The adapter itself buffers its responses, so streaming reaches the client only from a plain callable. Its other specifics below apply on both servers.
The adapter drives the same ASGI callable on a background event loop that it owns, so routing, binding, access, errors, limits and the OpenAPI document behave as under ASGI. Specifics:
- Startup is lazy under Granian (Kiso starts them with the worker). Modules (including the database pool) start on the first request of each worker process, so a pre-forking server can import the file in its master process. If startup fails, every request answers
503withnot_readyand the error is logged. - Shutdown runs on
WSGIAdapter.close()or, otherwise, at interpreter exit. A server that kills workers without exiting normally skips it, as it would anyatexithook. - Async handlers run on the adapter's loop and sync handlers on the bounded executor, as under ASGI. Each WSGI server thread blocks for the duration of its request, so concurrency is the server's thread count rather than the event loop.
- Bodies are buffered. Request bodies are read up to
max_body_bytesplus one byte, so an oversized upload still answers413. Responses are complete before they are sent; streaming responses are not available, and a client disconnect is not reported to the handler. - Paths. The server decodes the path once and the adapter passes it on without decoding again, so a client's
%2520reaches the handler as%20, as under ASGI. A percent-encoded slash (%2F) cannot be told apart from a real one in WSGI and is not available inside a path parameter. A badContent-Lengthanswers400. - One protocol per process. Do not serve the same application object over ASGI and WSGI in one process; the adapter owns its own loop and module lifespan. Run two processes if you need both.
The path is checked against Kiso and Granian (--interface wsgi, with one and two workers) by a parity test, not against every WSGI server.
Errors and edge cases¶
error: X is neither an application nor a factory: the target names something else, for example an ASGI wrapper; run wrappers withgranian.error: Granian is not installed; install the server extra: runuv syncin a generated project (it depends onhinoki[server]), or use Kiso.hinoki devreloads withwatchfiles, also part of theserverextra, on either server; without itdevexits with that message andservestill works.--workersoutside the supported range is refused on Kiso;0means "useserver.workers".--interface wsgiwithserver.native_dispatchorserver.trusted_proxiesset on Kiso exits with status2and names the setting.--interface wsgiwith aHinokiapplication, a factory or a non-callable exits with an error that points toWSGIAdapter.- A Kiso-only setting under
--server granianexits with status2and names the setting.