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 Broker struct {
	// contains filtered or unexported fields
}

type BrokerOptions struct {
	// History is how many recent events are kept so that a client reconnecting
	// with Last-Event-ID can be caught up rather than told to refetch.
	// Defaults to 256. Zero after defaulting is not reachable; use a negative
	// value to disable replay, which makes every reconnection a reset.
	History int

	// Buffer is how many events may queue for one subscriber before the Broker
	// gives up on it and closes its channel.
	//
	// Defaults to 256, and is raised to History+1 if it is set lower, because
	// a subscription hands its replay to the channel before returning and a
	// buffer that could not hold the replay would deadlock the publisher.
	Buffer int
}

type Change string

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 Delivery struct {
	// ID is the position. It increases by one per event within a Source and is
	// what a reconnecting client asks to resume after.
	ID uint64

	// Event is the change. It is the zero Event when Reset is set.
	Event Event

	// Reset, when non-nil, replaces the events the subscriber missed with an
	// instruction to refetch.
	Reset *Reset
}

type Event struct {
	// Table is the SQL table name, matching what the generated client's
	// keysByTable is keyed by.
	Table string `json:"table" doc:"SQL table the change happened in"`

	// Key is the primary key of the row, rendered as a string the way the URL
	// renders it, so that it concatenates onto the resource path.
	//
	// It is empty when the change was not attributable to one row, which today
	// means every delete: sqlb's AfterDelete hook receives a count rather than
	// the rows it removed. An empty Key means "something in this table
	// changed" — invalidate the collection. That is not a degradation for a
	// delete, because a delete changes the collection whether or not the
	// client held the row.
	Key string `json:"key,omitempty" doc:"Primary key of the row, or empty when the whole table is invalidated"`

	// Op is what happened.
	Op Change `json:"op" enum:"create,update,delete" doc:"What happened to the row"`

	// Scope is the value of the column the model declared `scope`, when it
	// declared one: the tenant the changed row belonged to.
	//
	// It is **not on the wire**. It exists so that [EventsOptions.Filter] can
	// answer the one question a multi-tenant deployment has to answer about
	// this stream — is this event mine — without the endpoint hard-coding what
	// a tenant is. A subscriber gains nothing from being told its own tenant
	// id, and putting it on the wire would enlarge a contract ADR-0045 records
	// as the expensive half to change.
	//
	// It is empty when the model declares no scope, and empty on a delete,
	// which carries no row to read it from. A Filter comparing scopes has to
	// decide what an empty one means; the safe reading is that such an event
	// identifies nothing and may go to everyone, since it names neither a row
	// nor a tenant.
	Scope string `json:"-"`
}

type EventsOptions struct {
	// Source supplies the events. Required.
	Source Source

	// Path is where the stream is served. Defaults to "/events".
	Path string

	// Heartbeat is how often a comment line is written to an idle stream, to
	// keep an intermediary from reclaiming a connection it believes is dead.
	// Defaults to 25 seconds, which is under the 30 seconds that is the
	// shortest idle timeout in common proxy defaults. Negative disables it.
	Heartbeat time.Duration

	// Retry is the reconnection delay the endpoint suggests to the client,
	// sent once when the stream opens. Defaults to 3 seconds.
	Retry time.Duration

	// Filter, if set, decides whether one event reaches this subscriber. It
	// runs per event per subscriber, with the request's context, so it can
	// reach whatever the authentication middleware put there.
	//
	// Read the default — every subscriber receives every event — as the thing
	// to think about before mounting this on a multi-tenant deployment. The
	// events carry no row data, but a primary key is still a fact about what
	// exists, and nothing else on this path is scoped: an Event is published
	// by a write, not read through a query, so the BeforeQuery hook that
	// confines every other read of that table does not run here.
	//
	// One consequence to know about: a filtered event's id is never written,
	// so a subscriber that is filtered out of everything keeps an old
	// Last-Event-ID and will eventually be told to reset when it reconnects.
	// That costs it a refetch, which is the safe direction — the alternative
	// is advancing its position past events it was not shown, and then a
	// genuine gap would be indistinguishable from a filtered one.
	Filter func(ctx context.Context, e Event) bool

	// Summary, Description and Tag document the operation. Each has a default.
	Summary     string
	Description string
	Tag         string

	// Security is the OpenAPI security requirement the operation carries, in
	// the same shape and with the same meaning as Options.Security: it
	// documents, and middleware enforces.
	Security []map[string][]string
}

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
	// MaxOffset bounds how deep ?page= and ?offset= may reach into the result
	// set. Offset paging is the one dimension of a request whose cost grows
	// with the number the client sent, so it has a ceiling like the others; a
	// request past it is refused with a message pointing at ?cursor=.
	MaxOffset 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

	// Computed lists the computed columns this resource selects. Each must be a
	// column the model computes, and it is checked at startup for the reason
	// Expandable is.
	//
	// Leaving it empty offers none, which is the right default for the same
	// reason it is right for Expandable: a computed column is a cost, and one
	// the schema happens to declare is not the same thing as one this resource
	// wants to serve. A model is shared — the same Project is read by a list
	// screen that wants four aggregates and by an existence check that wants
	// none — so projecting every declared column charged every reader for the
	// most expensive one, and a column carrying a Needs bind failed the
	// cheapest readers outright (#92).
	//
	// A column not listed is not reachable from this resource: not in the
	// response, not filterable, not sortable, not nameable in ?select. The
	// obligation follows the selection — a resource that selects a column
	// declaring Needs still refuses to mount without a hook to supply the bind,
	// and one that does not select it no longer has to care.
	Computed []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 Publisher interface {
	Publish(events ...Event)
}

type Reset struct {
	Reason string `json:"reason" doc:"Why the stream could not resume"`
}

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 Source interface {
	// Subscribe returns the channel this subscriber's deliveries arrive on.
	//
	// since is the position the client last saw, from Last-Event-ID, or zero
	// for a fresh connection. A Source that can replay from that position
	// should; one that cannot must open the stream with a Delivery carrying a
	// Reset, so the gap is announced rather than skipped.
	//
	// The channel is closed when ctx is done, and may also be closed by the
	// Source to disconnect a subscriber it can no longer keep up with. A
	// closed channel ends the stream; the client reconnects on its own.
	Subscribe(ctx context.Context, since uint64) (<-chan Delivery, error)
}

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)
}