api

type Envelope[R any] struct {
	Data  []R    `json:"data"`
	Meta  *Meta  `json:"meta,omitempty"`
	Links *Links `json:"links,omitempty"`
}

type IdempotencyOptions struct {
	// Methods guarded (default POST and PATCH).
	Methods []string
	// Required answers 400 when the header is missing.
	Required bool
	// TTL keeps completed responses (default 24h).
	TTL time.Duration
	// LockTTL bounds an in-flight request (default 1 minute).
	LockTTL time.Duration
	// MaxBody bounds the body of a keyed request (default 1 MiB). The body
	// is read whole to fingerprint it, so a larger one is refused with 413
	// before the handler runs, whatever a route-level body limit allows.
	// Raise it for keyed routes that accept bigger bodies; requests without
	// a key are not affected.
	MaxBody int64
	// ReplayHeaders lists the response headers stored and replayed besides
	// Content-Type. Default: the headers describing the stored
	// representation (Content-Language, Content-Disposition,
	// Content-Location, Location, ETag, Last-Modified, Link); a non-nil list
	// replaces it. Set-Cookie, Authorization, Proxy-Authorization,
	// Proxy-Authenticate and WWW-Authenticate are never replayed, even when
	// listed. Every other header is written fresh by the middleware of the
	// repeat request (X-Request-ID, RateLimit-*, security headers) or
	// dropped, so a replay never carries the first request's per-request
	// values or credentials.
	ReplayHeaders []string
	// Scope separates callers so one cannot replay another's response.
	// Default: the authenticated principal (auth.Principal: guard and user
	// id) when an auth middleware ran before Idempotency, else a SHA-256 of
	// the Authorization header. Place Idempotency after auth.Required so
	// a revoked token is refused before any replay. A request with a key
	// whose scope is empty is refused with 400; return a constant to share
	// keys on purpose.
	Scope func(r *http.Request) string
}

type Links struct {
	Self string  `json:"self"`
	Next *string `json:"next"`
	Prev *string `json:"prev"`
}

type Meta struct {
	Page       int    `json:"page,omitempty"`
	PerPage    int    `json:"per_page"`
	Total      *int64 `json:"total,omitempty"`
	LastPage   int    `json:"last_page,omitempty"`
	NextCursor string `json:"next_cursor,omitempty"`
}

type Op struct {
	// Name is the route name (and the OpenAPI operationId).
	Name        string
	Summary     string
	Description string
	Tags        []string
	// Status is the success status; default 201 for POST, 204 when the
	// output type is struct{}, 200 otherwise.
	Status     int
	Deprecated bool
	// Security lists the security schemes the OpenAPI document declares
	// (e.g. "bearer"). It is documentation only and does not authenticate
	// the route: add auth.Required (and auth.Ability) to the route or group.
	Security []string
	// ValidateResponse checks the output against its `validate` tags
	// (z.For[Out]) before writing it, when web.Services.CheckResponses is
	// on: the app sets it whenever APP_ENV is not production, so a staging
	// deployment with APP_ENV=development or test runs the check too. A
	// mismatch is a server bug: it is logged and answered with a generic 500
	// instead of sending data that breaks the documented contract. Out must
	// be a struct; Register panics otherwise.
	ValidateResponse bool
}

type Operation struct {
	Op
	Method string
	Path   string
	Params []string
	In     reflect.Type
	Out    reflect.Type
}

type Option func(*spec)

type Registrar interface {
	Match(methods []string, path string, h web.HandlerFunc) []*router.Route
}

type Request[T any] struct {
	// Query has the filters, sort, fields and relation includes applied.
	Query   orm.Query[T]
	Page    int
	PerPage int
	Cursor  string
	// Includes lists the allowlisted ?include names the client sent, as
	// sent.
	Includes []string
	// contains filtered or unexported fields
}