3.2 Tenants and mounts (routing and path safety)

1.2 introduced tenants and mounts as nouns. This section covers the mechanics you can actually rely on: how a request finds its tenant, then its mount, and the path rules enforced before any service runs.

Step 1 — resolving the tenant

Single-tenant nodes assign every request to the one configured tenant.
Multi-tenant nodes resolve from the Host header: an explicit domain map is checked first (api.acme.com → acme), then a {tenant}.{mainDomain} subdomain rule. Details and config are in Part 10.

The health endpoints (/healthz, /readyz) are the exception — they're tenant-independent.

Step 2 — matching the mount

Within the tenant, the request path is matched against the mount table by longest prefix on segment boundaries. "Segment boundaries" matters: /data matches /data/orders but never /database. If both /data and /data/orders are mounted, a request to /data/orders/42 goes to the more specific /data/orders mount.

Duplicate mount paths are rejected at config-build time, so there's never an ambiguous match at runtime.

Step 3 — path safety (before routing)

Every path is safety-validated before it reaches a service, for all services. Rejected with 400 path_unsafe:

traversal sequences (.. and percent-encoded variants),
null bytes and control characters,
backslashes,
drive letters.

This is enforced by the host, so no service — prebuilt or custom — can be tricked into escaping its storage area through a crafted path. You don't write this check; you can rely on it.

What a service receives

By the time your service (or a prebuilt one) runs, the host has already: resolved the tenant, matched the mount, validated the path, applied auth and admission, and pre-scoped the service's capabilities to that tenant (3.5). The service sees a clean message and a set of handles it's allowed to use — nothing more.

This division — the host owns routing, safety, and scoping; the service owns behavior — is the throughline of the whole runtime. The next section looks at the most common service shape that division produces: the store pattern.

← Previous: 3.1 Messages and bodies · Manual home · Next: 3.3 The store pattern →