apibase

type Authenticator interface {
	// Claims identifies the caller behind a request.
	Claims(*http.Request) (tenancy.Claims, error)
	// Mount registers the authentication routes — signing in, refreshing, keys
	// — through the same router the resource routes went through, so they land
	// on one mux and are traced on the same terms.
	Mount(httpx.Router)
}

type Request[Path, Query, Body any] struct {
	// Claims describe the caller. They are always present: a handler does
	// not run without them.
	Claims tenancy.Claims

	Path  Path
	Query Query
	Body  Body
	// contains filtered or unexported fields
}

type RequestContext struct {
	// RequestID correlates this request with the server's logs. Always set on a
	// request the server served — see [RequestContextOf] for where it comes from
	// — and empty only on a context somebody built by hand.
	RequestID string
	Method    string
	Path      string
	// Route is the pattern that matched, so a metric can be labelled by
	// endpoint rather than by every distinct identifier.
	Route      string
	RemoteAddr string
	UserAgent  string
	// ClientRevision is the raw header, kept for a log line that wants to
	// count what callers are sending. Empty when the caller said nothing, and
	// unparseable prose when it said something that is not a revision — a
	// hand-rolled client and a curl will not say, and that is a normal thing
	// for a caller to be. Compare with [RequestContext.BuiltBefore] rather
	// than with this.
	ClientRevision string

	// ServerRevision is what this server was generated from, so that
	// [RequestContext.Stale] has both sides of the comparison in hand.
	//
	// A field rather than a package-level value, because this package serves
	// every project rather than one. [RequestContextOf] fills it from
	// [Server.Revision] on every request; a context built by hand in a test has
	// it unset, and an unset one is unknown — so Stale answers false rather than
	// inventing a distance.
	ServerRevision apirev.Revision
}

type Server struct {
	// Auth wires the whole authentication foundation in one field.
	//
	// Setting it does two things that otherwise have to be remembered separately:
	// GetClaims comes from it, and its routes are mounted on the mux Register
	// returns. Wiring the claims from one thing and mounting another is a mistake
	// this makes unavailable.
	//
	// Nil for a project with no authentication, which then has to supply GetClaims
	// itself.
	Auth Authenticator

	// GetClaims establishes who is calling. A handler does not run without it, so
	// a route cannot accidentally be left unauthenticated.
	//
	// Auth supplies it. Set this instead for a project that authenticates its own
	// way, or has no auth routes to mount.
	GetClaims func(*http.Request) (tenancy.Claims, error)

	// RequestID labels a request for the logs and for the error body it may end
	// in.
	//
	// Nil is the ordinary case and does not mean nothing: it means
	// [CallerRequestID] — the caller's own [Server.RequestIDHeader], if it sent one worth
	// trusting — then this request's trace, and a fresh identifier when there is
	// neither. Set this only to answer the question differently; the default is
	// already the answer every route in this package gives, including the
	// authentication ones.
	//
	// A hook replaces only the first of those three. One that returns "" for some
	// requests leaves them to the trace and then to a fresh identifier, exactly
	// as a caller that sent no header is left — so "every request has an
	// identifier" is true rather than usually true, and a traced project whose
	// hook declines a request still labels it with that request's trace. A hook
	// is how the answer is chosen, not how it is opted out of.
	RequestID func(*http.Request) string

	// Logger is where this server says what it did and why a request failed. Nil
	// uses [log/slog.Default].
	//
	// Nil means the default logger and not silence, which is the whole point: the
	// one line worth having is the cause of a 500, and a server that drops it
	// because nobody configured logging is a server whose error bodies say
	// "something went wrong" and mean it literally. Set this to route the lines
	// somewhere, not to turn them on.
	//
	// What comes out: an error line per failed request carrying the whole error,
	// and, at [log/slog.LevelDebug], a line per request with its status and size.
	//
	// There is still no logger on the context and no way to reach this one from a
	// service: a service is constructed by the application and handed a logger
	// there. What it is handed is already request-aware, though. The generated
	// Mount wraps [github.com/simonjanss/rig/runtime/serve.App.Logger] in
	// [LogHandler] before the application's own wiring sees it, so every line a
	// service writes inside a request carries the same request group these two
	// lines do, without the call site saying so.
	//
	// This field is not wrapped, because it is a value the application set.
	// [LogFailure] and [LogRequest] put the request on their lines themselves,
	// so they read the same whoever configured the logger. [RequestContextFrom]
	// is still how anything reaches the fields rather than the group.
	Logger *slog.Logger

	// MinRevision refuses a caller built against an API revision older than this
	// one. The zero value, the default, refuses nothing.
	//
	//	MinRevision: apirev.MustParse("2026-04-30"),
	//
	// This is the end of the story [Revision] starts: you removed a field, you
	// waited, the logs said nobody old was left, and now you close the door. Until
	// somebody decides to, the revision is telemetry and nothing else.
	//
	// Only a caller that sends a revision older than this is refused. One that
	// sends none is served — an unknown client is not the same as an old one,
	// and turning every curl and every hand-written integration into a 426 is not
	// a door closing, it is an outage.
	MinRevision apirev.Revision

	// OnError turns a service error into a response. Nil uses DefaultErrorMapper,
	// which is the right behavior for almost everyone.
	OnError func(w http.ResponseWriter, r *http.Request, rc RequestContext, err error)

	// LogLevel chooses the level a failure is written at. Nil is [LevelFor],
	// which is rig's own table and what almost every project wants.
	//
	// It is the only field here that changes what the log says rather than what
	// the client gets, and it is deliberately narrow. It cannot turn a line off:
	// the lowest level it can return is still a level, and the one line that says
	// why a 500 happened is the reason this package writes anything at all. What
	// it is for is a project that knows something rig cannot — that a particular
	// route should never 404, so a 404 there is worth a warning, or that its
	// public API takes enough hand-written requests that a 400 is noise.
	//
	// It is asked about the code, not the error, so it cannot see the two rows of
	// the table that have no code. A request whose caller went away is debug and a
	// timeout is [rigerr.CodeUnavailable] before this is consulted.
	LogLevel func(code rigerr.Code) slog.Level

	// PreHooks run before anything else, in order. A hook that writes a response
	// stops the request.
	PreHooks []func(w http.ResponseWriter, r *http.Request) bool

	// Context lets a hook attach values a service will read.
	Context func(ctx context.Context, r *http.Request) context.Context

	// DB is what a write carrying an Idempotency-Key is recorded in, so that a
	// client which had to send the same write twice gets one row and the same
	// answer both times. Pass the pool: `DB: app.Pool`.
	//
	// Required, and Register panics without it. A nil one would mean the header
	// was quietly ignored, and a client that thinks its retry is safe when it is
	// not is worse off than one that knows it is not — this is the one failure
	// mode worth a startup panic rather than a runtime surprise.
	//
	// It costs nothing until a caller sends the header: a write without one takes
	// the path it always took, with no transaction and no extra round trip. See
	// [github.com/simonjanss/rig/runtime/idempotency].
	DB dbx.Beginner

	// Revision is what this server's API surface was generated from, announced
	// on the way out of every response and compared against MinRevision on the
	// way in. The generated Register fills it in; the zero value is a project
	// that has never generated with a revision recorded, and it announces
	// nothing rather than announcing a wrong answer.
	Revision apirev.Revision

	// RevisionHeader is the header the revision travels in, both ways. Empty
	// means [DefaultRevisionHeader], which is what `api.revision_header` leaves
	// it at.
	RevisionHeader string

	// RequestIDHeader is the header a caller may name its own request in. Empty
	// means [DefaultRequestIDHeader], which is what `request_id_header` leaves it
	// at.
	RequestIDHeader string

	// Tracer is where this API's spans come from. Nil is a project that does not
	// trace, and then none of its methods is called.
	//
	// [Tracing] is what opens the request span from it, and a generated Register
	// registers every route through that — so setting this by hand on a server
	// built by hand traces nothing on its own. What it does reach either way is
	// the request identifier, which falls back to the trace, and [LogFailure],
	// which reddens the span a refusal happened in.
	Tracer Tracer

	// Throttle is the rate limiter, or nil for a project with no `throttle:`
	// block. A nil Gate allows, so this costs one nil check rather than a
	// limiter nobody configured.
	Throttle *throttle.Gate

	// TrustedProxies are the networks whose X-Forwarded-For this server
	// believes, for the one case Throttle has to key on an address: an
	// unidentified caller. Empty trusts nothing, which is the safe default — an
	// address read from a header the client controls is an address the client
	// chooses, and a limit keyed on one of those is decorative.
	TrustedProxies []netip.Prefix
}

type Tracer interface {
	// Server opens the span for one request and returns the request carrying it,
	// along with the function that ends it.
	//
	// The route is the matched pattern rather than the path, so a trace has one
	// span name per endpoint instead of one per identifier anybody ever fetched.
	// status is how the span learns what was answered.
	Server(r *http.Request, route string, status func() int) (*http.Request, func())

	// TraceID names the trace this request belongs to, or empty when there is
	// none. It is what a request that sent no identifier of its own is labelled
	// with, so that the one in an error body and the trace in a collector are one
	// string.
	TraceID(r *http.Request) string

	// Fail records why a request is being refused, on whatever span the context
	// is in. It ends nothing: the span belongs to the handler.
	//
	// Not called at all when the caller went away. Nothing failed, so there is
	// nothing to put on the span — see [LogFailure], which is the only thing that
	// calls this.
	Fail(ctx context.Context, status int, err error)
}