Arandu API

Do not

• Encode JSON onto the response writer or write a status by hand: json-written-by-hand. Every domain answer passes through a Resource.
• Hand ctx.JSON the entity, or a map: the entity answers every field it will ever have, the tenant and the next secret column included.
• Write an error format of your own. Two formats are two things every client parses.
• Read a token from a query string or a cookie, or fall back to the session on an API route: a cookie is what CSRF reaches.
• Mount Idempotent before the guard: it panics without a subject rather than keep one caller's answer where another could replay it.

Extending it

A computed field, or one only some readers see, goes in the custom block of ToArray. Metadata about the answer -- the next page, a total -- goes in With. A second representation of the same record is a second Resource, not a flag on the first.

Wiring

aru make:resource needs no wiring: the controller imports the Resource. A token route needs nothing new either: bootstrap/app.go already builds the token service (App.Tokens), its resolver and the idempotency store, and hands the last two to the routes as Deps.Tokens and Deps.Idempotency. The store is the cache store CACHE_STORE names -- set it to the shared one when there are replicas, because a key one process remembers is run again by the next.

Acceptance test

• The Resource's unit test: the keys answered are exactly the listed ones.
• A feature test as a JSON client: 200 with the fields and Vary: Accept, and a problem document (Content-Type: application/problem+json, status, title) for a missing row, a refusal, a conflict and a rejected input -- TestAJSONClientIsAnsweredThroughTheNoteResource and TestAJSONClientIsRefusedWithProblemDocuments.
• For a token route, as tests/Feature/NotesAPI_test.go does: a write with the token and no session answers 2xx and is the token's account in its tenant; another member's record is still 403; an unknown and a revoked token answer the same 401 with WWW-Authenticate: Bearer; a write the browser reports cross-site is 403, and one riding a session cookie without the CSRF token is 419.
• For an idempotent write: a retry with the same key answers Idempotent-Replayed: true and changes nothing twice.

Limits

This project issues tokens through the service and has no screen for it: a page that lists an account's tokens, shows a new one once and revokes them is application code to write, on the service that is already here. A token acts as its account in the tenant every sign-in of the deployment belongs to; an application whose accounts live in several tenants decides how a token's tenant is told apart -- never from the request -- and that is an arandu-ecosystem question first.

A token carries the account's stored roles and no narrower scope of its own; the policies decide every record. The generated Resource has no knowledge of who reads it; a field only some readers may see is a decision written in the custom block.

Gates

Run them all, in this order, as AGENTS.md lists them:

export GOWORK=off
aru model:build --check
aru view:build
gofmt -l $(find . -name '*.go' -not -path '*/testdata/*' -not -name '*.kyse.go')
go vet ./...
bash tests/test-layout-guard.sh
go test -race ./...
go build ./...
aru doctor

<!-- arandu:begin custom -->

<!-- arandu:end custom -->