platform

Declarative cross-cutting concerns (auth, rate limiting, audit):

The default HTTP stack (wagoe.platform.shell.http.interceptors/default-http-interceptors) is applied to every route unless the route opts out with :skip-interceptors? true (used only for internal endpoints such as health checks). In :enter/:leave order:

(http-rate-limit limit window-ms cache) builds a fixed limit to attach per route.

Every JSON error the framework sends has one shape, whatever produced it — the exception mapping, the default-deny 401/403, CSRF, the rate limiter, a malformed body, an unknown route or method:

type and message are always there. details and correlation-id are there when the error has them, and dev (the WGE code, dev only) sits beside them. Everything is inside error, so a client reads one key. The correlation id is also the X-Correlation-ID response header.

type is the :type of the thrown ex-info, looked up in problem-details/default-error-mappings for its status. Anything unmapped is a 500 whose type is internal-error and whose message says nothing more. Build a body of your own with wagoe.platform.core.http.errors/body or response.

The types the framework answers with:

A write that a unique or foreign key refuses is a 409 conflict, on H2, SQLite, PostgreSQL and MySQL alike: wagoe.platform.database throws it, so every generated repository gets it. details names the constraint and the key’s columns: field for one, fields for several. Nothing else of the driver’s text is sent. Where the driver does not name the columns (MySQL, or PostgreSQL with lc_messages other than English) they are read from the catalog, once per key; a key on an expression names none. On PostgreSQL a refusal in a transaction reads them on a separate connection, outside the pool; if none opens within a second, it names no columns.

db/upsert! writes a row by its key on every engine: it updates the row, or inserts it, and retries a writer that lost the race to insert. Outside a transaction it also retries a deadlock. db/ensure-binary-collation! makes a MySQL column compare case-sensitively, as the other engines do; use it for a key such as a file name or a token.

A handler that knows only its status gets its type from errors/status→type: validation-error for a 4xx with no type of its own, internal-error for a 5xx.

Enter phases run in order; leave phases run in reverse order.

To reject a request from :enter, set :halt? true in the context (alongside the :response). The pipeline short-circuits only on :halt? — setting :response by itself does not stop forward execution, so a later interceptor or the route handler would overwrite it. :leave still runs for interceptors that already executed.

http-csrf-protection enforces CSRF for session-authenticated, state-changing requests and issues tokens for rendering. Pure token functions live in wagoe.platform.core.csrf.

A state-changing request (POST/PUT/DELETE/PATCH) is validated — 403 on a missing or invalid token — when CSRF is enabled, the path is not exempt, and the request is either session-authenticated (session-token cookie / X-Session-Token header) or a /web route. This covers /web, /web/admin, and any session-authenticated /api route. Token-auth API clients that send no session cookie are not CSRF-vulnerable and are not checked; safe methods (GET/HEAD/OPTIONS) and :exempt-paths are skipped.

Enforcement is opt-in: the library default is :enabled? false, so upgrading the framework cannot start rejecting requests from a consumer that does not yet emit tokens. An app turns it on with the block above (after emitting tokens in its /web forms); the secret falls back to JWT_SECRET. Startup fails loud — the system wiring throws and the app refuses to boot if CSRF is enabled with a blank secret, rather than letting the interceptor fail open (run unvalidated).

Tokens are emitted with no per-handler wiring. For HTMX, either merge (csrf/hx-headers) onto an element’s attributes (e.g. <body>) so all inherited hx-* requests carry the X-CSRF-Token header, or rely on the shared page layout’s <meta name="csrf-token"> tag plus the global htmx:configRequest listener that attaches the header to every HTMX request. Plain (non-HTMX) forms include a hidden field:

See the authentication guide for the request flow and the unauthenticated (login) pre-session token.

Discovery builds a scaffolded module’s four keys (:wagoe/<name>, -repository, -service, -routes). To add to them, define ig-config in the module’s module_wiring.clj and return only what you add:

Every permission a group can hold is in one registry, built at boot from what the enabled modules declare. A module declares under :authorization in its ig-config; a scaffolded module does so with a def authorization in its wiring namespace:

A module never declares <module>/read and <module>/write: every module has them, and the code roles <module>/viewer and <module>/editor holding them unless it declares its own. Every admin entity has admin.<entity>/read and admin.<entity>/write. The :permissions enum under :wagoe/user :groups is read in as well, until 2.0. bb scaffold gives a new module three code roles: <module>/viewer, <module>/editor and <module>/manager.

The boot fails when two modules declare the same permission or role, or one scope key differently, when a role or a route’s :permission names something outside the registry, and when a code role outside the admin module holds an admin.* permission. Every route a module contributes carries its module as :wagoe/module in its route data.

Read the registry through wagoe.platform.ports.authorization:

A module exports the data it holds about a person, and expires what it keeps, through wagoe.platform.ports.privacy. It contributes implementations by id from its ig-config; no module reads another’s tables.

:wagoe/data-export (IDataExport) collects every exporter’s data about a subject, {:type :user :id …} or {:type :tenant :id …}; an exporter returns nil for a subject it holds nothing about. The user module serves it to a signed-in user at GET /api/v1/me/export and /web/profile/export, and to platform admins at GET /api/v1/users/:id/export, which is recorded in the user’s audit log. The tenant module serves a tenant’s export to platform admins at GET /api/v1/tenants/:id/export, recorded in tenant_audit_log. Either admin export can also run as a background job through IExportJobs, which the storage module provides when the jobs module is on. Sections are keyed by exporter id with its namespace, so :orders and :billing/orders do not collide.

Each route answers JSON. With ?format=zip or Accept: application/zip it answers a zip of data-export.json and the files exporters hold, such as the storage module’s uploads, each under its exporter id (storage/<key>). An exporter with files also implements IFileExporter. A file that is gone is listed under missingFiles in the JSON. For a subject too large to zip during a request, the storage module builds a user’s export as a background job and serves it from file storage (see the storage library).

Retention is off until you name a policy. It then runs as the recurring job :wagoe/retention, so :wagoe/jobs must be on:

A policy no enabled module provides or can run, or a period that is not positive, fails the boot.

wagoe.platform.database/delete-in-batches! deletes in batches of 1000, so a first purge of years of rows does not hold one long lock.