rest

type CommandOptions struct {
	// Auth is who may run this command. The zero value is the Spec's own write
	// permission, which is right for a command that moves a row an
	// administrator owns and wrong for one somebody runs on their own thing:
	// adding an item to a basket is httpx.SignedIn(), and the alternative was a
	// second permission every tenant would have to grant to every shopper.
	Auth httpx.Auth

	// Collection mounts the command on the collection rather than on a row —
	// POST {Path}/{verb} — and run is handed uuid.Nil.
	//
	// The id is the whole difference, and it was a second exported function
	// until the review counted the lines: twenty-eight of its thirty-two were
	// this one's. A command about a row somebody names — resolve this task —
	// carries the id; a command about the collection, where the row is what the
	// command finds or produces, cannot. Redeeming a code is the example: the
	// caller knows the code and not the row it belongs to, so {id} in the path
	// would be asking them for the answer.
	Collection bool
}

type Item[T any] struct {
	Body T
}

type Page[T any] struct {
	Body struct {
		Items  []T   `json:"items"`
		Total  int64 `json:"total"`
		Limit  int   `json:"limit"`
		Offset int   `json:"offset"`
	}
}

type Singleton[T crud.Entity] struct {
	// Module and Entity name it, as they do on a Spec: the operation ids, the
	// tag and the generated screen's path come from them.
	Module, Entity string
	// Path is the resource: "/api/v1/site/settings". There is no item path.
	Path string
	// Read guards the read; Write guards the PUT. An empty Write mounts no PUT
	// at all, which is the shape of a singleton whose changes are commands —
	// billing's subscription is moved by subscribe and cancel, and a PUT would
	// be a caller writing its own period.
	Read, Write string
	// Public mounts GET {Path}/public, unauthenticated. Face is what it
	// answers with, and it is required when Public is set: what a visitor may
	// see is a smaller thing than what an administrator configured, and a
	// public route that served the whole row would be an admin screen anybody
	// could read.
	Public bool
	Face   func(T) any
	// Event is what the PUT declares it publishes. Save is what publishes it;
	// this is the declaration kit/app's boot gate reads.
	Event string

	// Load is the tenant's row. Save writes it and returns what was stored.
	Load func(ctx context.Context, tx db.Tx[db.Tenant]) (T, error)
	Save func(ctx context.Context, tx db.Tx[db.Tenant], in T) (T, error)
}

type Spec[T crud.Entity] struct {
	// Module is the manifest's name. It prefixes the events, so the events a
	// Spec publishes are namespaced by the module that mounts it.
	Module string
	// Entity is this resource's name, lower-case: "task". It is the middle of
	// the event name and the noun in the operation ids.
	Entity string
	// Path is the collection's path: "/api/tasks". The item is Path + "/{id}".
	Path string
	// Read guards the list and the read; Write guards create, update and
	// delete. Both are permissions some module has to define, or the app
	// refuses to start.
	Read, Write string
	// OperatorWrite declares Write with httpx.OperatorPermission rather than
	// httpx.Permission: the rows are the installation's and every tenant reads
	// them, but only the operator's own tenant writes them.
	//
	// It exists because the alternative is a module hand-writing five routes to
	// change one declaration, and one of them did. A price list is the case: it
	// is read by every tenant, so it is not a control-plane resource in the way
	// the tenant registry is, and it is written by the operator alone, because
	// a customer that could add a plan could price itself. The manifest has to
	// declare the same permission Operator: true, or kit/app refuses to start.
	OperatorWrite bool
	// SoftDelete keeps deleted rows, hidden, instead of removing them.
	SoftDelete bool
	// Immutable names, by json field name, the fields a PATCH refuses because
	// a route of their own owns them: a task's assigneeId belongs to Assign,
	// which also moves the status and publishes task.assigned, so a caller who
	// could set it through the generic update would move the field alone and
	// tell nobody, and a content author belongs to the create that stamped it.
	// The refusal is a 422 naming the field, so the caller is told which door
	// to use rather than left wondering why nothing happened.
	//
	// This is not ReadOnly. ReadOnly is the four fields Base contributes — the
	// server owns those at every door, and the create route discards whatever
	// a caller sent for them. An immutable field is writable, by exactly one
	// route. Every name here is checked against the entity's schema at mount,
	// so a misspelled one panics where it is written instead of silently
	// guarding nothing.
	Immutable []string

	// HookEvents names the events the hooks below publish. They are appended
	// to the create, update and delete operations' x-platformkit-events, so
	// the OpenAPI document says what a write can emit and kit/app's boot gate
	// sees it.
	//
	// It closes one direction and it is worth being plain about which. The
	// gate compares what the routes declare against what the manifests
	// declare; nothing reads what a handler actually publishes. So an event
	// named here and missing from a manifest fails startup, and an event a
	// hook publishes that nobody named here is still invisible to everything
	// but the outbox.
	HookEvents []string

	// The hooks run inside the request's transaction, after the write and
	// after the event, so a hook can publish more events or write more rows and
	// all of it commits together.
	//
	// There is no AfterUpdate, and the absence is a decision rather than an
	// omission: nothing in three repositories ever set one, and a hook nobody
	// writes is a parameter every reader of this struct has to rule out. A
	// module that needs one adds it back in the commit that uses it.
	AfterCreate func(ctx context.Context, tx db.Tx[db.Tenant], e T) error
	AfterDelete func(ctx context.Context, tx db.Tx[db.Tenant], e T) error
}