rest

type ActionSpec struct {
	// Name is the verb, used in the operation ID: "complete" gives
	// complete-task.
	Name string

	// Path is the full route, resource path included: "/tasks/{id}/complete".
	// A path with no "{id}" is a collection action.
	Path string

	// Field is the name of this action's field on the generated Actions
	// struct, so that a nil func can be reported as the thing the author has
	// to go and set.
	Field string

	// Summary and Description document the operation.
	Summary     string
	Description string

	// Writes names the columns the envelope persists after the verb returns.
	// Empty means the verb writes nothing through the envelope — it may still
	// write through the transaction, which it has.
	Writes []string

	// HasBody reports whether the action declared any body properties.
	//
	// The input type is generated either way, so that adding the first property
	// later does not change the shape of the func the application wrote. This
	// is what decides whether the *operation* reads a request body, because an
	// empty struct registered as a required body would make
	// POST /tasks/{id}/complete refuse a request that carries nothing — which
	// is the commonest verb there is.
	HasBody bool
}

type Config struct {
	// Title and Version identify the API in its OpenAPI document. They default
	// to "API" and "1.0.0".
	Title   string
	Version string

	// Description is the document's prose summary. Optional.
	Description string

	// Customize, if set, receives the huma.Config after the fields above are
	// applied and before the API is built. It is where a security scheme, a
	// server URL, or a non-default docs path goes — anything this struct does
	// not name — and it may override what the fields above set.
	Customize func(*huma.Config)
}

type CreateBody[T any] interface {
	// Row builds the row to insert. Returning an error rejects the request as
	// a 422, which is where cross-field validation belongs.
	Row() (*T, error)
}

type None[T any] struct{}

type Op uint8

type Options struct {
	// Path is the collection path, e.g. "/posts". Required.
	Path string

	// Ops is the set of exposed operations. Required: a resource exposing
	// nothing is a mistake rather than a way to hide one.
	Ops Op

	// Name is the singular resource name used in operation IDs and summaries,
	// e.g. "post" gives list-posts and get-post. Defaults to the path with its
	// leading slash removed.
	Name string

	// Tag groups the operations in the OpenAPI document. Defaults to Name.
	Tag string

	// Description documents the resource. It comes from the table's comment.
	Description string

	// Pagination and filter limits. Zero means the filter package's default.
	// MaxPageSize is a hard ceiling, not a hint: a client asking for more gets
	// the maximum rather than an error.
	DefaultPageSize int
	MaxPageSize     int
	MaxFilters      int
	MaxSortTerms    int

	// Expandable lists the relation names ?expand may name. Each must be a
	// relation the model declares — a `expands=` field beside an `expand`
	// column — and is checked at startup, because at request time an unknown
	// name would parse cleanly and answer 200 with the relation missing.
	//
	// Leaving it empty offers no ?expand at all, which is the right default: a
	// join is a cost, and a relation the schema happens to declare is not the
	// same thing as one this resource wants to serve.
	Expandable []string

	// DisableSearch rejects ?search even when columns are searchable.
	DisableSearch bool

	// DisableTransactions runs generated writes under autocommit.
	//
	// The default — wrapping each create, update and delete in a transaction —
	// is what makes sqlb.AfterCommit reachable from a generated write. Without
	// it there is no commit for a hook to be after, so a documented feature is
	// unreachable from the writes most applications actually issue
	// ([ADR-0021](../docs/adr/0021-hooks-receive-an-event.md)).
	//
	// The cost is a BEGIN/COMMIT round trip per write, and a server-side
	// connection held for longer. Behind PgBouncer in transaction pooling mode
	// that is a change in occupancy rather than only in latency
	// ([ADR-0019](../docs/adr/0019-pgbouncer-in-the-path.md)), so this exists
	// for anyone who measures it and decides against.
	//
	// Turning it on silently stops any AfterCommit callback the resource's
	// hooks register. Read that as the reason it is phrased as a disable rather
	// than as an enable: the safe value is the zero value.
	DisableTransactions bool

	// Security is the OpenAPI security requirement every operation of this
	// resource carries — the same shape huma.Operation.Security takes, so it is
	// a list of alternatives and each alternative names schemes and their
	// scopes:
	//
	//	Security: []map[string][]string{{"bearerAuth": {}}}
	//
	// It documents; it does not enforce. Authentication is middleware on the
	// router, and it runs whether or not this is set — leaving it empty produces
	// operations that are protected and do not say so, which is what every
	// consumer of the document has to guess about.
	//
	// The generated clients do not read this, and that is not an oversight: they
	// are generated from the schema rather than from the document, and they take
	// the credential from the transport the consuming project supplies. What
	// this is for is /docs, an agent reading the spec, and anything else driven
	// by the document.
	//
	// The scheme itself is declared once on the API, not here:
	//
	//	api.OpenAPI().Components.SecuritySchemes = map[string]*huma.SecurityScheme{
	//	    "bearerAuth": {Type: "http", Scheme: "bearer", BearerFormat: "JWT"},
	//	}
	Security []map[string][]string
}

type Page[T any] struct {
	Items      []row[T] `json:"items" doc:"The rows on this page"`
	Page       int      `json:"page" doc:"1-based page number"`
	PerPage    int      `json:"per_page" doc:"Rows requested per page, after the resource's ceiling was applied"`
	HasMore    bool     `json:"has_more" doc:"Whether a further page exists"`
	NextCursor *string  `json:"next_cursor,omitempty" doc:"Position to resume from; pass it back as ?cursor="`
	Total      *int64   `json:"total,omitempty" doc:"Total matching rows; present only when ?count=exact was given"`
}

type Problem struct {
	// Type is the RFC 9457 problem type URI.
	Type string `json:"type,omitempty" doc:"A URI reference identifying the problem type"`
	// Title is the short, human-readable summary of the problem.
	Title string `json:"title,omitempty" doc:"Short, human-readable summary of the problem"`
	// Status is the HTTP status code.
	Status int `json:"status,omitempty" doc:"HTTP status code"`
	// Detail explains this specific occurrence.
	Detail string `json:"detail,omitempty" doc:"Explanation specific to this occurrence"`
	// Errors lists every problem found, not just the first, so a malformed
	// request takes one round trip to fix rather than one per mistake.
	Errors []*ProblemDetail `json:"errors,omitempty" doc:"Every problem found with the request"`
}

type ProblemDetail struct {
	// Message says what was wrong.
	Message string `json:"message" doc:"What was wrong"`
	// Location is a path-like pointer to the offending input, e.g.
	// `query.sort` or `body.title`.
	Location string `json:"location,omitempty" doc:"Where the problem is, e.g. 'query.sort'"`
	// Value is the rejected value, echoed back.
	Value any `json:"value,omitempty" doc:"The rejected value"`
	// Allowed lists what would have been accepted instead, where there is a
	// finite set. Hidden columns never appear here: the diagnostic must not
	// become an oracle for what a resource is concealing.
	Allowed []string `json:"allowed,omitempty" doc:"What would have been accepted instead"`
}

type Server struct {
	// API is what resources mount on. Pass it to a generated Register, or
	// register hand-written operations on it directly.
	API huma.API

	// Mux is the underlying mux. Mount application routes on it — a health
	// check, authentication — alongside the generated ones.
	Mux *http.ServeMux

	// Handler is Mux. Serve it, or wrap it with application middleware first.
	Handler http.Handler
}

type UpdateBody interface {
	// Changes maps column name to new value for the fields the request
	// carried. An empty map is rejected as a 400 rather than run as a no-op
	// update, because it almost always means the client sent the wrong shape.
	Changes() (map[string]any, error)
}