serve

type App struct {
	// Pool is the database, already connected and pinged.
	Pool *pgxpool.Pool

	// Logger is the server's, so a request line, a shutdown step and anything
	// a dependency says all land in the same place. Run always sets it, to
	// Config.Logger or the default.
	//
	// A rig-generated Mount replaces it with the same logger wrapped in
	// [github.com/simonjanss/rig/runtime/apibase.LogHandler] before the
	// application's own wiring is called, so that everything built out of it
	// says which request a line belongs to. This package does none of that and
	// knows nothing about it; it is noted here because this is the field the
	// substitution is visible on.
	Logger *slog.Logger
	// contains filtered or unexported fields
}

type Config struct {
	// DatabaseURL is the connection string. Empty means $DATABASE_URL, and
	// failing that the server refuses to start rather than guessing.
	DatabaseURL string

	// Addr is the listen address. Empty means $ADDR, and refused after that.
	Addr string

	// Monitor is served on a listener of its own, at MonitorAddr, in this same
	// process. Nil — the default — opens no second listener.
	//
	// It is an http.Handler and not rig's monitoring page, because this package
	// is imported by every generated server and rig/observe brings
	// OpenTelemetry with it. Pass observe's:
	//
	//	Monitor:     page.Handler(),
	//	MonitorAddr: page.Addr(),
	//
	// which are both zero when the page is unarmed, so a deployment with no
	// monitoring password opens no port rather than one that refuses.
	//
	// A separate listener rather than a route on the handler below, because a
	// bind address is a boundary the kernel keeps and a path is not: bound to
	// loopback, the page is reachable by this machine and by nothing else, in
	// every deployment and behind every proxy. Anything else that should be
	// reachable on those terms and not on the API's — a pprof mux, an operator
	// endpoint — belongs here too.
	Monitor http.Handler

	// MonitorAddr is where Monitor listens, as host:port. Required when Monitor
	// is set, and refused when it is not: the two say one thing together, and
	// either one alone is a monitoring page somebody believes is running.
	//
	// There is no default and no environment fallback here, unlike Addr. What
	// fills it in is observe's own $RIG_MONITOR_ADDR, resolved before the page
	// is built, so that the address and the page's own idea of it cannot
	// disagree.
	MonitorAddr string

	// LivenessPath answers whether the process is running, and nothing else.
	//
	// Required, like ReadinessPath: a path this package chose would be one an
	// orchestrator has to be told about anyway. [NoProbe] is how a project says
	// it wants none.
	// It never touches the database, and that is the whole point: a liveness
	// probe that fails when a dependency does turns one database blip into
	// every replica being killed at once, which is the outage the restart was
	// supposed to prevent.
	//
	// Empty registers nothing.
	LivenessPath string

	// ReadinessPath answers whether this instance should be sent traffic. It
	// pings the database, runs Ready if there is one, and turns false the
	// moment a shutdown begins — so a load balancer stops sending work before
	// the server stops accepting it.
	//
	// Empty registers nothing.
	ReadinessPath string

	// Ready is checked by ReadinessPath after the database, for a dependency
	// this package knows nothing about. An error means not ready, and its text
	// goes to the caller: a readiness probe is read by whoever is debugging the
	// deployment, not by the public.
	Ready func(ctx context.Context) error

	// DrainDelay is how long to keep serving after readiness turns false and
	// before the shutdown starts. Zero is none, which is a real answer here
	// rather than an absent one. It comes out of MaxShutdown either way.
	//
	// It exists because removing an instance from a load balancer is not
	// instant: the probe has to fail, and the change has to propagate. Requests
	// sent during that window arrive at a server that has already stopped
	// accepting them. A delay of a few seconds is what turns a rolling deploy
	// with dropped requests into one without.
	DrainDelay time.Duration

	// Logger receives the two lines this package has to say. Nil uses the
	// default logger.
	Logger *slog.Logger

	// Pool tunes the pool before it is opened — MaxConns, an AfterConnect
	// hook, a tracer.
	Pool func(*pgxpool.Config) error

	// Tasks are subcommands: an argument that names one runs it against an
	// open pool and exits, instead of starting the server.
	//
	//	Tasks: map[string]serve.Task{"migrate": migrate.Apply(migrations, opt)}
	//
	// It is here rather than in every main function because the alternative is
	// everybody writing the same three lines against os.Args, and because a
	// task and a server that must connect identically should be reading one
	// configuration.
	//
	// Only Main dispatches them. Run always serves.
	Tasks map[string]Task

	// Migrate runs before the server listens, with the pool already open. An
	// error stops the process before it has served anything.
	//
	// This package does not know what a migration is; rig/migrate does, and
	// keeping the two apart is why an application that migrates some other way
	// carries no dependency on it.
	//
	// Whether this should apply migrations or only refuse to start without them
	// is a real decision with a wrong answer at scale. rig/migrate's package
	// documentation lays out the three places migrations can run and what each
	// costs; migrate.Require is the one to reach for by default, and
	// migrate.Apply the one for a single instance.
	Migrate Task

	// MaxStartup is the longest the process may take between Run being called
	// and the server listening: opening the pool, the Migrate hook, and the
	// mount function.
	//
	// The counterpart of MaxShutdown, and for the same reason. A boot that
	// hangs on something slow is not obviously different from a boot that is
	// merely slow, and the difference matters most at three in the morning. A
	// project that migrates on the way up should raise this: the migration is
	// inside the budget.
	MaxStartup time.Duration

	// ConnectTimeout bounds the first connection, inside MaxStartup — soon
	// enough to say "the database" rather than "startup" when that is what went
	// wrong.
	//
	// Setting it longer than MaxStartup is refused: connecting alone would use
	// the whole budget.
	ConnectTimeout time.Duration

	// Hint is what to tell somebody whose database is not there — most often
	// how to start one:
	//
	//	Hint: "run `rig db up` to start a local Postgres, or set $DATABASE_URL"
	//
	// It is said as soon as the first connection attempt fails rather than at
	// the end of ConnectTimeout, and again with the error if the wait runs out.
	// The reason it is a field and not a sentence in this package is that only
	// the project knows how its database is meant to be started: a container in
	// development, a managed instance in production, and printing the wrong one
	// is worse than printing nothing.
	Hint string

	// ProbeTimeout bounds what a readiness check is allowed to wait for: a probe
	// that hangs is a probe that has already failed.
	ProbeTimeout time.Duration

	// ReadHeaderTimeout bounds how long a client may take to send its headers.
	// Worth stating rather than turning off: without it one open connection
	// sending nothing occupies a goroutine forever.
	ReadHeaderTimeout time.Duration
	// ReadTimeout bounds the whole request.
	ReadTimeout time.Duration
	// WriteTimeout bounds the response. Its clock starts when the request's
	// headers were read rather than when the body starts going out.
	//
	// It is the bound for an ordinary route. A route that legitimately outlives
	// it lifts it for its own request through http.NewResponseController — the
	// file transfers and the shape proxy both do — rather than this field being
	// raised to suit the slowest thing in the application, which would weaken
	// every other route to do it. That is why there is no per-route timeout
	// here and should not be one.
	WriteTimeout time.Duration
	// IdleTimeout bounds a kept-alive connection between requests.
	IdleTimeout time.Duration

	// MaxShutdown is the longest the whole stop sequence may take, from the
	// signal to the process being gone: the drain delay, the drain steps, the
	// requests in flight, and every dependency registered with App.Close.
	//
	// Required. It is the only field here with no default, because it is the
	// only one that leaves the program: this is the number that belongs in
	// Kubernetes' terminationGracePeriodSeconds, and a default would be a value
	// nobody wrote deciding how long something outside this process waits before
	// sending SIGKILL. A server that is stopped faster than its own budget does
	// not drain, it is killed mid-flight.
	//
	// It is a stated maximum rather than the sum of its parts so that it can be
	// read off and copied — adding up whatever the mount function happened to
	// register is not something anybody will do twice. The parts are checked
	// against it before the server listens, so the two cannot drift apart
	// quietly, and a config that states nothing is refused there with the total
	// and each part named. That refusal is where the number to write comes from.
	MaxShutdown time.Duration

	// Shutdown sizes the individual steps inside MaxShutdown, for a deployment
	// that wants numbers other than the ones they were registered with.
	//
	// The generated api package's Shutdown is what fills it, and it is a struct
	// with a field per step this project actually registers:
	//
	//	Shutdown: api.Shutdown{
	//		Notifications: 10 * time.Second,
	//		Presence:      2 * time.Second,
	//	},
	//
	// Optional, and the ordinary case is to leave it out: the numbers a step is
	// registered with are rig's answer to what that step costs, and MaxShutdown
	// is already the sum of them. This is for the deployment those numbers do
	// not suit — most often one whose terminationGracePeriodSeconds was decided
	// by somebody else, which is exactly the fact rig.yaml cannot carry because
	// the same build runs where it is thirty seconds and where it is five.
	//
	// A number here replaces the limit a step was registered with rather than
	// giving one to a step that has none — see [Step]. What that leaves alone is
	// the drain half of the notification engine, which stops it claiming more
	// work and is deliberately bounded only by what is left of the budget.
	//
	// It does not raise MaxShutdown. The parts are checked against the whole
	// before the server listens either way, so a set that outgrows the budget is
	// a process that refuses to start and names what no longer fits, and a step
	// named here that nothing registers a limit for is refused there too.
	Shutdown Shutdown

	// OnListen is called with the address actually bound, which is the only
	// way to learn it when Addr asks for port zero.
	OnListen func(net.Addr)

	// OnMonitorListen is OnListen for MonitorAddr, and is not called at all
	// when there is no second listener.
	//
	// A second callback rather than a role argument on the first, so that a
	// test waiting for one port cannot be handed the other and block until it
	// times out.
	OnMonitorListen func(net.Addr)

	// OnExit runs last, on every way out of Main, including the ones that exit
	// non-zero.
	//
	// It exists because `defer` does not survive os.Exit, and Main exits: a
	// flush written as a deferred call in a main function runs when the server
	// stopped cleanly and is skipped on the three paths where something went
	// wrong — a task that failed, a boot that failed, a subcommand that does
	// not exist. Those are the runs whose spans and logs somebody actually
	// wants.
	//
	// Only Main calls it. Run returns, so a caller using Run directly still has
	// its own defers.
	OnExit func()
}

type Mount func(ctx context.Context, app *App) (http.Handler, error)

type Shutdown interface {
	// Steps is the set, and only the steps it names are affected.
	Steps() []Step
}

type ShutdownError struct{ Err error }

type Step struct {
	// Name is the step this is about, and a name no step here has a limit for is
	// refused before the server listens rather than silently doing nothing.
	Name string

	// Timeout is how long that step may take. Zero leaves it alone, which is
	// what makes a partly-filled set mean "these, and the rest as generated".
	Timeout time.Duration
}

type Task func(ctx context.Context, pool *pgxpool.Pool) error