// The CLI's doors onto the platform STUN/TURN relay (relay spec §5):
// `carlos relay enable|status|disable|adopted` for a member, and
// `carlos relay rotate` for a deployment operator. Every write here is a
// thin shell over internal/console/relayops.go's operations — the record,
// the lease, the walk and the reconcile all live there; this file's whole
// job is the door: gate the caller, decode the request, translate the
// operation's sentinel errors into HTTP, and answer with the ONE reply
// shape every member-facing door shares (storeReply's pattern, apistore.go).
//
// FOUR DOORS ARE APP-SCOPED, ONE IS NOT. enable, status, disable and adopted
// sit under .../apps/{account}/{app}/relay, behind apiAccountApp exactly
// like the store doors: an unknown account, someone else's account and an
// app that was never claimed are one byte-identical 404 (apiAccountApp's own
// doc comment). rotate has no account or app in its path at all — it moves a
// REGION's issuer pointer and re-issues every app enabled there, so its gate
// is apiRelayOperator, not apiAccountApp, and its refusal is a byte-identical
// 404 rather than the 403 the store's grant door gives a non-operator MEMBER
// (apistore.go's handleAPIStoreGrant): that 403 is safe to speak only because
// apiAccountApp has already proven the caller belongs to the account it
// named, so it teaches them only what THEY lack. rotate proves no membership
// at all before answering, so a 403 here would confirm to any valid token
// that this deployment runs a relay a caller might rotate — the same
// reasoning apiSystemRoller's family already applies to `carlos system`.
//
// DELIVERY READS THE PER-ROUTE CONFIG-ACK. Spec §5 describes five delivery
// states a route can be in; most of them come from a per-route config-ack
// (`control/config-ack/<box>/<route host>.json`, internal/appconfig/
// configack.go) config sync writes after it converges a route. There is no
// per-host box list to narrow that read by (relayHeartbeats' own doc
// comment says the same for control/relay-ack/<box>.json), so relayReply
// reads every ack that exists (relayConfigAcks, relayops.go) and matches by
// Host. An ack counts only when its RelaySuffixes equal exactly what the
// record currently has issued — the same freshness rule relayCutoverFor's
// maps.Equal already applies to a member's `carlos relay adopted`: an ack
// that named an OLDER incarnation's identities must not read as "this route
// runs what was just issued", so a stale ack falls back to "written,
// awaiting delivery" rather than reporting an adoption that never happened
// under the current keys.
//
// syncExecHost's ack (the socket-exec and tcp-exec-file shapes) always
// leaves Restarted false and RestartError empty — its bounce is
// best-effort and fire-and-forget, and a tcp-exec-file route's process is
// never restarted by this platform at all — so "adopted at <time>,
// restarted" is reachable only for a unit-backed route today; a
// socket-exec route with a matching ack stays "written, awaiting delivery"
// until its own restart signal exists to report.
//
// Spec: docs/superpowers/specs/2026-09-07-relay-stun-turn-design.md §2, §5.
package console

import (
	"context"
	"errors"
	"fmt"
	"log"
	"maps"
	"net/http"
	"strings"
	"time"

	"github.com/carlosframework/platform/internal/appconfig"
	"github.com/carlosframework/platform/internal/relay"
)

// relayTimeout bounds a single relay round trip: one GET status, one adopted
// ack. The same 15s storeTimeout uses, for the same reason (apistore.go).
const relayTimeout = 15 * time.Second

// relayOpTimeout bounds enable and disable: each is relayops.go's three-step
// walk (record, config, aggregate) rather than one object read, so it gets
// storeGrantTimeout's ceiling rather than storeTimeout's.
const relayOpTimeout = 60 * time.Second

// relayRotateTimeout bounds rotate: the issuer pointer move plus a
// re-issue of every app enabled in the region, one at a time.
const relayRotateTimeout = 60 * time.Second

// relayNoBucket is the 503 every relay door gives when this console has no
// deployment bucket — storeNoBucket's exact reasoning (apistore.go): the
// record IS a bucket object, and answering as if the relay were simply off
// would be a lie a member could act on.
func relayNoBucket(w http.ResponseWriter) {
	jsonError(w, http.StatusServiceUnavailable, errRelayNoBucket.Error())
}

// relayDoorError turns one of relayops.go's errors into the door's answer.
// The sentinels each name a configuration fact or a genuine 404; anything
// else is logged (a relay error can carry bucket paths and request ids, the
// same reasoning storeGrant's own %v log line gives) and answered with a
// generic retry.
//
// A few of relayops.go's refusals are not sentinels — relayResolveRegions
// and relayRotate build fmt.Errorf sentences for "no such region" and "the
// staged master is not loaded yet" because they always name the specific
// region or kid at fault, which a sentinel compared by value cannot do. They
// are still the CALLER's mistake or something for the operator to fix by
// re-running the runbook, not this console failing, so they are matched by
// their own stable wording rather than left to read as a 502.
func relayDoorError(w http.ResponseWriter, verb string, err error) {
	switch {
	case errors.Is(err, errRelayNoRegions), errors.Is(err, errRelayNoSealKey),
		errors.Is(err, errRelayNotHeld), errors.Is(err, errRelayNoBucket):
		jsonError(w, http.StatusServiceUnavailable, err.Error())
	case errors.Is(err, errRelayUnknownHost), errors.Is(err, errRelayNotEnabled):
		jsonError(w, http.StatusNotFound, err.Error())
	case errors.Is(err, errRelayUndelivered), errors.Is(err, errRelayNotMemberRoute),
		relayLooksLikeClientError(err):
		jsonError(w, http.StatusBadRequest, err.Error())
	default:
		log.Printf("console: api relay %s: %v", verb, err)
		jsonError(w, http.StatusBadGateway, "the relay could not complete that — try again")
	}
}

// relayLooksLikeClientError matches the handful of relayResolveRegions' and
// relayRotate's own sentences that name something the CALLER typed wrong or
// the OPERATOR has not finished staging — never this console's own failure.
func relayLooksLikeClientError(err error) bool {
	msg := err.Error()
	for _, s := range []string{
		"runs no relay in",            // relayResolveRegions, relayRotate: unarmed region named
		"no new master is staged",     // relayRotate: nothing new in CARLOS_RELAY_MASTERS_<REGION>
		"has not loaded kid",          // relayRotate: a box has not picked up the staged master yet
		"has heartbeated in the last", // relayRotate: no live relay in the region at all
	} {
		if strings.Contains(msg, s) {
			return true
		}
	}
	return false
}

// ---- the reply shape ---------------------------------------------------------

// apiRelayRoute is one of an app's routes as `carlos relay status` reports
// it: which of spec §5's delivery shapes it is, and what the console can say
// about whether its key has arrived.
type apiRelayRoute struct {
	Host string `json:"host"`
	// One of the relayShape* constants below: the first three are spec §5's
	// delivery shapes, "no-delivery" is a route a key can never reach, and
	// "unknown" is the fail-closed answer for a route this console cannot
	// describe.
	Shape    string `json:"shape"`
	Delivery string `json:"delivery"`
	// AckedAt and Cutover are both empty/false until a member has run
	// `carlos relay adopted --host` for this route (relay.RouteCutover).
	AckedAt string `json:"acked_at,omitempty"`
	Cutover bool   `json:"cutover"`
	// ConfigAckAt and ConfigAckShape echo config sync's own per-route
	// acknowledgement (control/config-ack/<box>/<route host>.json) when one
	// exists naming exactly the identities this record currently has
	// issued — empty until then, and left empty for a stale ack (one
	// naming an older incarnation's identities) exactly like AckedAt above.
	// Distinct from AckedAt/Cutover: those describe a MEMBER's `carlos
	// relay adopted`, this describes what the PLATFORM'S OWN config sync
	// last rendered and, where it could, restarted.
	ConfigAckAt    string `json:"config_acked_at,omitempty"`
	ConfigAckShape string `json:"config_ack_shape,omitempty"`
}

// apiRelayRegion is one region's health as this app's status sees it, built
// from a single armed relay's own heartbeat (control/relay-ack/<box>.json).
// A region with several relays gets one row per box — Box is the reader's
// only way to tell them apart, since Region alone is not unique across them.
type apiRelayRegion struct {
	Region       string   `json:"region"`
	Box          string   `json:"box"`
	HeartbeatAge string   `json:"heartbeat_age"` // "never", or a Go duration string
	Current      bool     `json:"current"`       // this box's authority copy is the latest published
	LeaseLive    bool     `json:"lease_live"`    // relay.Lease still armed to serve (15-minute ceiling)
	Listeners    []string `json:"listeners"`
	Kids         []string `json:"kids"`
	// Retiring is kid -> RFC3339 retire_at for the masters this box loaded
	// that carry one. It answers the operator's mid-rotation question —
	// when may the old key leave /etc/carlos/relay-masters — from the CLI,
	// per box, which is the only place the answer is true: a region is only
	// done with a key once EVERY relay there has stopped loading it
	// (discussion #120).
	Retiring map[string]string `json:"retiring,omitempty"`
	// Stale mirrors relayRotate's own gate: a heartbeat whose last successful
	// authority read is older than relayHeartbeatFresh (five minutes) cannot
	// be read as current, so a dead relay cannot look alive by silence.
	Stale bool `json:"stale"`
	// The relay's own last two errors, verbatim (relay.Heartbeat): the
	// masters file it could not reload, and the authority record it could not
	// read. Either one is the REASON a row is stale, and printing the state
	// without the reason leaves a member with nothing to act on.
	MastersError   string `json:"masters_error,omitempty"`
	AuthorityError string `json:"authority_error,omitempty"`
}

// apiRelayReply is the one answer shape enable, status, disable and adopted
// all give — storeReply's pattern (apistore.go): describing the SAME record
// from four different doors in one function is what keeps them from
// describing it differently. rotate is not app-scoped and does not produce
// one of these at all; see apiRelayRotateReply below.
type apiRelayReply struct {
	App         string   `json:"app"`
	Enabled     bool     `json:"enabled"`
	Incarnation string   `json:"incarnation,omitempty"`
	Regions     []string `json:"regions,omitempty"`
	Op          int64    `json:"op"`
	Phase       string   `json:"phase,omitempty"`
	// Issued is the username suffix the console last issued per region —
	// relay.Record.IssuedSuffixes, echoed verbatim. Not a secret: it is the
	// same account/app/incarnation/kid identity §2's CARLOS_RELAY carries,
	// never the key.
	Issued       map[string]string `json:"issued,omitempty"`
	Routes       []apiRelayRoute   `json:"routes,omitempty"`
	RegionStatus []apiRelayRegion  `json:"region_status,omitempty"`
	// DisablePending names the regions where the aggregate publish that
	// removed this app has not yet been confirmed by every armed relay's own
	// heartbeat (spec §5, "when a disable is complete") — present only while
	// the record is disabled and at least one region has not caught up.
	DisablePending []string `json:"disable_pending,omitempty"`
	// There is deliberately NO retire-no-earlier-than here. That time is a
	// property of a ROTATION, not of an app: relayRotate computes it from the
	// moment the issuer pointer moved and hands it to the operator who moved
	// it (apiRelayRotateReply), and nothing persists it. Reporting a per-region
	// retirement date on an app's status would mean either inventing state the
	// console does not keep or recomputing it from a clock, which would tell a
	// member a retirement deadline that drifts every time they ask.
	//
	// apiRelayRegion.Retiring is NOT that value and is not a softening of this
	// rule (discussion #120). It is the retire_at a relay actually loaded out
	// of its own masters file, reported per box and echoed verbatim: state the
	// operator wrote, not state this console computed, so it cannot drift
	// between two reads.
}

// apiRelayRotateReply is what `carlos relay rotate` answers with — a region
// and a kid, not an app's record, so it does not try to fit apiRelayReply's
// shape.
type apiRelayRotateReply struct {
	Region              string `json:"region"`
	Kid                 string `json:"kid"`
	Apps                int    `json:"apps"`
	RetireNoEarlierThan string `json:"retire_no_earlier_than"` // RFC3339
}

// The five shapes `carlos relay status` reports a route as. The first three
// are spec §5's delivery shapes; relayShapeNone is a route the config sync
// can never reach at all, and relayShapeUnknown is the fail-closed answer for
// a route that matches none of them.
const (
	relayShapeUnit    = "unit"
	relayShapeSocket  = "socket-exec"
	relayShapeFile    = "tcp-exec-file"
	relayShapeNone    = "no-delivery"
	relayShapeUnknown = "unknown"
)

// relayRouteShape names which shape a route is, in relayDeliverable's OWN
// branch order (relayops.go), so that "what status calls this route" and
// "what enable refused, or did not refuse, about it" can never disagree:
//
//  1. a named UNIT is a unit whatever else the row carries — the config sync
//     restarts it, so the key arrives without anyone being asked;
//  2. a unix SOCKET is a socket-exec, restarted the same way;
//  3. an `instance` route (Kind "" reads as instance) is the platform's OWN,
//     restarted by the config sync even though its record also carries the
//     TCP address the router dials. This branch sits ABOVE the address one
//     deliberately: reading that address as a foreign process would tell a
//     member to run `carlos relay adopted` for a route they must not adopt;
//  4. only what is left — a TCP address belonging to a process this platform
//     never spawned — is the shape a member has to restart and acknowledge.
//
// Whether that last shape can receive the file at all is a SEPARATE question
// this function cannot answer (it needs the route's config bundle):
// relayReply asks relayNoDelivery and downgrades the row to relayShapeNone.
//
// The default is relayShapeUnknown, not "unit". A route with no unit, no
// socket, no address and a kind this code does not recognise is something
// this console cannot describe, and calling it a unit would promise a
// restart-on-write that nothing is going to perform.
func relayRouteShape(rt relayRoute) string {
	switch {
	case rt.Unit != "":
		return relayShapeUnit
	case rt.Socket != "":
		return relayShapeSocket
	case rt.Kind == "" || rt.Kind == "instance":
		return relayShapeUnit
	case rt.Addr != "":
		return relayShapeFile
	default:
		return relayShapeUnknown
	}
}

// relayCutoverFor finds host's cutover in rec, nil if a member has never
// acknowledged it.
func relayCutoverFor(rec *relay.Record, host string) *relay.RouteCutover {
	for i := range rec.Cutovers {
		if rec.Cutovers[i].Host == host {
			return &rec.Cutovers[i]
		}
	}
	return nil
}

// relayMatchingAck finds the freshest config-ack among acks naming host
// whose RelaySuffixes equal issued exactly — nil if none does. The equality
// check is the same freshness rule relayCutoverFor's caller applies to a
// member's Cutover (maps.Equal against rec.IssuedSuffixes): an ack written
// before a rotation names the identities that rotation retired, and
// reporting it as current would tell a member their route runs a key it
// has never actually seen. "Freshest" (latest At) only matters if more than
// one box's ack somehow matches, which config sync's own per-(box,host) key
// makes rare in practice but not impossible across a route migration.
//
// phase and issued are checked FIRST, and deliberately: maps.Equal(nil,
// nil) is true, so without this guard an enabled record still at phase
// "config" — IssuedSuffixes not written yet, a state an interrupted enable
// can persist in indefinitely — would match ANY route's ordinary pre-relay
// ack (RelaySuffixes nil, no CARLOS_RELAY entry at all) and print an
// adoption for identities the console has never actually issued. Only a
// record that finished an operation (phase done) with something to show
// for it (len(issued) > 0) can have an ack legitimately match it at all
// (review finding 2026-09-07).
func relayMatchingAck(acks []appconfig.ConfigAck, host string, issued map[string]string, phase string) *appconfig.ConfigAck {
	if phase != relayPhaseDone || len(issued) == 0 {
		return nil
	}
	var best *appconfig.ConfigAck
	for i := range acks {
		a := &acks[i]
		if a.Host != host || !maps.Equal(a.RelaySuffixes, issued) {
			continue
		}
		if best == nil || a.At.After(best.At) {
			best = a
		}
	}
	return best
}

// relayReply assembles apiRelayReply from a record that has already been
// read or just been written. rec is never nil here — the callers that could
// see one (handleAPIRelayGet) answer their own 404 first.
func (s *Server) relayReply(ctx context.Context, acct *Account, app string, rec *relay.Record) (apiRelayReply, error) {
	out := apiRelayReply{
		App: app, Enabled: rec.Enabled, Incarnation: rec.Incarnation,
		Regions: rec.Regions, Op: rec.Op, Phase: rec.Phase, Issued: rec.IssuedSuffixes,
	}

	routes, err := s.relayAppRoutes(ctx, acct.Sqid, app)
	if err != nil {
		return apiRelayReply{}, err
	}
	// Read once for the whole reply, not once per route — and skipped
	// entirely when there is nothing for an ack to say anything about: a
	// disabled record has no key delivered (relayReply's own switch below
	// never reads an ack for it), and no routes means no hosts to match.
	// relayConfigAcks itself narrows the underlying List to just THIS
	// app's route hosts before issuing any Get (review finding
	// 2026-09-07: this used to cost a Get per ack in the whole fleet on
	// every status call).
	var acks []appconfig.ConfigAck
	if rec.Enabled && len(routes) > 0 {
		hosts := make(map[string]bool, len(routes))
		for _, rt := range routes {
			hosts[rt.Host] = true
		}
		acks, err = s.relayConfigAcks(ctx, hosts)
		if err != nil {
			return apiRelayReply{}, err
		}
	}
	for _, rt := range routes {
		if rt.Kind == "static" {
			// A static route runs no process at all — relayDeliverable
			// (relayops.go) ignores it for the same reason: there is nothing
			// here for a relay key to ever reach.
			continue
		}
		shape := relayRouteShape(rt)
		// A route can be ADDED after an enable, and nothing re-runs enable's
		// refusal when it is. Asked here, every status answer names such a
		// route instead of reporting it as fine — which is the whole point of
		// spec §5's "a route added without delivery after enable shows 'no
		// config delivery'": it blocks the next retirement, and the member is
		// the only one who can fix it.
		if shape == relayShapeFile {
			none, err := s.relayNoDelivery(ctx, acct.Sqid, app, rt)
			if err != nil {
				return apiRelayReply{}, err
			}
			if none {
				shape = relayShapeNone
			}
		}
		row := apiRelayRoute{Host: rt.Host, Shape: shape}
		switch {
		case !rec.Enabled:
			// A disabled record has no key to deliver: relayDisable removed
			// the variable from the bundle. "Written, awaiting delivery"
			// would name a write that has been UNDONE, and a member reading
			// it would go looking for a key that is on its way out.
			row.Delivery = "the relay key was removed from this app's config"
		case shape == relayShapeNone:
			row.Delivery = "no config delivery: relay will not reach this route; " +
				"opt it into exec_delivery file or move it to a unit"
		default:
			row.Delivery = "written, awaiting delivery"
			// A config-ack counts only when it names EXACTLY the identities
			// this record has issued now (relayMatchingAck) — the same
			// freshness rule the member-Cutover comparison just below makes
			// for `carlos relay adopted`. No match at all (never synced yet,
			// or a stale ack left over from before a rotation) leaves the
			// route at the base "written, awaiting delivery" rather than
			// reporting an adoption under keys the route may never have run.
			if ca := relayMatchingAck(acks, rt.Host, rec.IssuedSuffixes, rec.Phase); ca != nil {
				row.ConfigAckAt = ca.At.UTC().Format(time.RFC3339)
				row.ConfigAckShape = ca.Shape
				switch {
				case shape == relayShapeFile:
					// The ONE shape whose process this platform cannot
					// bounce: the ack proves the FILE landed, but adoption
					// itself is still the member's move (below).
					row.Delivery = "file delivered, awaiting `carlos relay adopted --host " + rt.Host + "` after you restart it"
				case ca.RestartError != "":
					row.Delivery = "restart failed: " + ca.RestartError
				case ca.Hibernating:
					row.Delivery = "hibernating, delivered on wake"
				case ca.Restarted:
					row.Delivery = "adopted at " + row.ConfigAckAt + ", restarted"
				}
			}
			if cut := relayCutoverFor(rec, rt.Host); cut != nil {
				row.AckedAt = cut.At.UTC().Format(time.RFC3339)
				// An ack counts only for the identities it NAMED. relayAdopted
				// stamps the record's issued suffixes into the cutover for
				// exactly this comparison: a rotation since then re-issued the
				// app under a new kid, and reporting the older acknowledgement
				// as current would say a route runs a key it has never seen.
				if maps.Equal(cut.Suffixes, rec.IssuedSuffixes) {
					row.Cutover = true
					row.Delivery = "adopted by member at " + row.AckedAt
				} else {
					row.Delivery = "acknowledged at " + row.AckedAt +
						", but the identities have changed since — re-run `carlos relay adopted --host " + rt.Host + "`"
				}
			}
		}
		out.Routes = append(out.Routes, row)
	}

	hbs, err := s.relayHeartbeats(ctx)
	if err != nil {
		return apiRelayReply{}, err
	}
	auth, _, err := relay.ReadAuthority(ctx, s.cfg.Releases)
	if err != nil {
		return apiRelayReply{}, err
	}
	now := s.relayTime()
	for _, region := range rec.Regions {
		for _, hb := range hbs {
			if hb.Region != region {
				continue
			}
			row := apiRelayRegion{
				Region: region, Box: hb.Box, Listeners: hb.Listeners, Kids: hb.Kids,
				LeaseLive: !hb.ReadAt.IsZero() && now.Sub(hb.ReadAt) <= relay.LeaseMaxAge,
				Stale:     hb.ReadAt.IsZero() || now.Sub(hb.ReadAt) > relayHeartbeatFresh,
				Current:   auth != nil && !hb.WrittenAt.IsZero() && !hb.WrittenAt.Before(auth.WrittenAt),
				// The two "why has this relay stopped moving" fields, carried
				// straight through. A stale row without them tells a member
				// their calls will fail and nothing about who fixes it: a
				// masters error is the operator's staging, an authority error
				// is this console's bucket.
				MastersError:   hb.MastersError,
				AuthorityError: hb.AuthorityError,
			}
			for kid, at := range hb.Retiring {
				if row.Retiring == nil {
					row.Retiring = map[string]string{}
				}
				row.Retiring[kid] = at.UTC().Format(time.RFC3339)
			}
			if hb.ReadAt.IsZero() {
				row.HeartbeatAge = "never"
			} else {
				row.HeartbeatAge = now.Sub(hb.ReadAt).Round(time.Second).String()
			}
			out.RegionStatus = append(out.RegionStatus, row)
		}
	}

	// "When a disable is complete" (spec §5): the app is out of a region's
	// authority once the aggregate has been published without it AND that
	// region's own armed relay has heartbeated an authority record written at
	// or after that publish. The published record's OWN written_at is the
	// timestamp to compare against — the same one the Current field above
	// uses — because it is the object the relays actually read. rec.DisabledAt
	// is only this console's note of when it started the walk, and it stands
	// in when the aggregate has never been published at all (in which case no
	// relay can possibly have caught up, so every region is pending).
	if !rec.Enabled && !rec.DisabledAt.IsZero() {
		publishedAt := rec.DisabledAt
		if auth != nil && !auth.WrittenAt.IsZero() {
			publishedAt = auth.WrittenAt
		}
		for _, region := range rec.Regions {
			revoked := false
			for _, hb := range hbs {
				if hb.Region == region && !hb.WrittenAt.IsZero() && !hb.WrittenAt.Before(publishedAt) {
					revoked = true
					break
				}
			}
			if !revoked {
				out.DisablePending = append(out.DisablePending, region)
			}
		}
	}
	return out, nil
}

// ---- the app-scoped doors: enable, status, disable, adopted -----------------

// handleAPIRelayEnable answers `carlos relay enable`. The doors, in order,
// mirror handleAPIStoreCreate's (apistore.go): token 401 (cliRoute), then
// apiAccountApp's byte-identical 404, then Releases nil (503), the write
// budget, and only then the body — a malformed request from a stranger must
// not distinguish itself from one that was never a member to begin with.
func (s *Server) handleAPIRelayEnable(w http.ResponseWriter, r *http.Request) {
	addr, acct, app, ok := s.apiAccountApp(w, r)
	if !ok {
		return
	}
	if s.refuseTemporary(w, acct, app, "serve anything but a static site at "+app+"'s own platform address") {
		return
	}
	if s.cfg.Releases == nil {
		relayNoBucket(w)
		return
	}
	p, _ := principalFrom(r.Context())
	if !s.allowWrite(p, time.Now()) {
		jsonError(w, http.StatusTooManyRequests, "too many requests — wait a minute and try again")
		return
	}
	var req struct {
		Regions []string `json:"regions,omitempty"`
	}
	if !readJSON(w, r, &req) {
		return
	}
	ctx, cancel := context.WithTimeout(r.Context(), relayOpTimeout)
	defer cancel()
	rec, err := s.relayEnable(ctx, acct, app, req.Regions, addr)
	if err != nil {
		relayDoorError(w, "enable", err)
		return
	}
	s.audit(acct, app, addr, "relay-enable",
		"enabled the relay in "+strings.Join(rec.Regions, ",")+" (cli)")
	out, err := s.relayReply(ctx, acct, app, rec)
	if err != nil {
		log.Printf("console: api relay reply %s/%s: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway,
			"the relay was enabled, but its status could not be read — try `carlos relay status`")
		return
	}
	writeJSON(w, http.StatusOK, out)
}

// handleAPIRelayGet answers `carlos relay status` — the one sight a member
// with no box access has of delivery per route and health per region,
// handleAPIStoreGet's exact reasoning (apistore.go): the 404 here speaks only
// after apiAccountApp has already proven membership, so it teaches a
// stranger nothing. Not rate limited, matching every other read door.
func (s *Server) handleAPIRelayGet(w http.ResponseWriter, r *http.Request) {
	_, acct, app, ok := s.apiAccountApp(w, r)
	if !ok {
		return
	}
	if s.cfg.Releases == nil {
		relayNoBucket(w)
		return
	}
	ctx, cancel := context.WithTimeout(r.Context(), relayTimeout)
	defer cancel()
	rec, _, err := relay.GetRecord(ctx, s.cfg.Releases, acct.Sqid, app)
	if err != nil {
		log.Printf("console: api relay status %s/%s: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway, "could not read the relay record — try again")
		return
	}
	if rec == nil {
		// A state, not a failure — objstore's same choice (handleAPIStoreGet):
		// "never enabled" and "enabled with nothing filled in" would
		// otherwise be indistinguishable to the CLI.
		jsonError(w, http.StatusNotFound, "the relay has never been enabled for this app — run `carlos relay enable`")
		return
	}
	out, err := s.relayReply(ctx, acct, app, rec)
	if err != nil {
		log.Printf("console: api relay delivery %s/%s: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway, "could not read the relay's delivery status — try again")
		return
	}
	writeJSON(w, http.StatusOK, out)
}

// handleAPIRelayDisable answers `carlos relay disable`.
func (s *Server) handleAPIRelayDisable(w http.ResponseWriter, r *http.Request) {
	addr, acct, app, ok := s.apiAccountApp(w, r)
	if !ok {
		return
	}
	if s.cfg.Releases == nil {
		relayNoBucket(w)
		return
	}
	p, _ := principalFrom(r.Context())
	if !s.allowWrite(p, time.Now()) {
		jsonError(w, http.StatusTooManyRequests, "too many requests — wait a minute and try again")
		return
	}
	ctx, cancel := context.WithTimeout(r.Context(), relayOpTimeout)
	defer cancel()
	rec, err := s.relayDisable(ctx, acct, app, addr)
	if err != nil {
		relayDoorError(w, "disable", err)
		return
	}
	s.audit(acct, app, addr, "relay-disable", "disabled the relay (cli)")
	out, err := s.relayReply(ctx, acct, app, rec)
	if err != nil {
		log.Printf("console: api relay reply %s/%s: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway,
			"the relay was disabled, but its status could not be read — try `carlos relay status`")
		return
	}
	writeJSON(w, http.StatusOK, out)
}

// handleAPIRelayAdopted answers `carlos relay adopted --host <route>`: a
// member telling the platform that a TCP-address route they restarted by
// hand now runs the identities the console last issued (spec §5, step 5).
func (s *Server) handleAPIRelayAdopted(w http.ResponseWriter, r *http.Request) {
	addr, acct, app, ok := s.apiAccountApp(w, r)
	if !ok {
		return
	}
	if s.cfg.Releases == nil {
		relayNoBucket(w)
		return
	}
	p, _ := principalFrom(r.Context())
	if !s.allowWrite(p, time.Now()) {
		jsonError(w, http.StatusTooManyRequests, "too many requests — wait a minute and try again")
		return
	}
	var req struct {
		Host string `json:"host"`
	}
	if !readJSON(w, r, &req) {
		return
	}
	host := strings.TrimSpace(req.Host)
	if host == "" {
		jsonError(w, http.StatusBadRequest, "host is required")
		return
	}
	ctx, cancel := context.WithTimeout(r.Context(), relayTimeout)
	defer cancel()
	rec, err := s.relayAdopted(ctx, acct, app, host, addr)
	if err != nil {
		relayDoorError(w, "adopted", err)
		return
	}
	s.audit(acct, app, addr, "relay-adopted", "acknowledged the relay key on "+host+" (cli)")
	out, err := s.relayReply(ctx, acct, app, rec)
	if err != nil {
		log.Printf("console: api relay reply %s/%s: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway,
			"the acknowledgement was recorded, but status could not be read — try `carlos relay status`")
		return
	}
	writeJSON(w, http.StatusOK, out)
}

// ---- the operator door: rotate -----------------------------------------------

// apiRelayOperator is rotate's whole gate. RelayRegions/RelayOperators name a
// deployment-wide authority (RelayOperators' own doc comment, server.go) with
// no account or app to check membership against — POST /api/cli/relay/rotate
// carries neither segment, the same shape `carlos system`'s doors answer for
// (apiSystemRoller, apisystemupdate.go; apiSystemOperator, apisystem.go).
//
// Unlike those two — and unlike the store's grant door, which gives a
// member-but-not-operator caller a 403 (apistore.go's storeOperator) — a
// failed check here is a byte-identical 404, because there is no membership
// proof for a 403 to be safe AFTER: this door proves nothing about the
// caller before answering, so a 403 naming CARLOS_RELAY_OPERATORS would tell
// any valid token holder that this deployment runs a relay at all. A
// non-person principal (a service credential, or a request that never
// reached cliRoute) gets the identical answer, never a distinguishing one.
func (s *Server) apiRelayOperator(w http.ResponseWriter, r *http.Request) (string, bool) {
	p, ok := principalFrom(r.Context())
	if !ok || p.Kind != PrincipalUser || !s.relayOperator(p.Address) {
		http.NotFound(w, r)
		return "", false
	}
	return p.Address, true
}

// relayOperator reports whether addr may drive `carlos relay rotate` —
// storeOperator's exact-match rule, verbatim (apistore.go's doc comment
// explains why EqualFold is wrong for a gate like this one: the ſ homoglyph
// folds to a lowercase "s" that already survived every ToLower on the way
// in). Its own list rather than StoreOperators', for RelayOperators' own
// reason (server.go): rotating a region's master is authority over the
// deployment's key material, not over spending its cloud bill, and a
// deployment may grant the two to different people.
func (s *Server) relayOperator(addr string) bool {
	for _, op := range s.cfg.RelayOperators {
		if strings.ToLower(strings.TrimSpace(op)) == addr {
			return true
		}
	}
	return false
}

// handleAPIRelayRotate answers `carlos relay rotate --region <r>` (spec §5,
// step 4): move the region's issuer pointer to the master the operator
// staged, and re-issue every app enabled there. Not rate limited on the
// address the way the member doors are — apiRelayOperator's own 404 already
// bounds who reaches this far, and a rotation the caller is entitled to
// start must not be delayed by a shared write budget spent by other doors.
func (s *Server) handleAPIRelayRotate(w http.ResponseWriter, r *http.Request) {
	addr, ok := s.apiRelayOperator(w, r)
	if !ok {
		return
	}
	if s.cfg.Releases == nil {
		relayNoBucket(w)
		return
	}
	var req struct {
		Region string `json:"region"`
	}
	if !readJSON(w, r, &req) {
		return
	}
	region := strings.TrimSpace(req.Region)
	if region == "" {
		jsonError(w, http.StatusBadRequest, "region is required")
		return
	}
	ctx, cancel := context.WithTimeout(r.Context(), relayRotateTimeout)
	defer cancel()
	res, err := s.relayRotate(ctx, region)
	if err != nil {
		relayDoorError(w, "rotate", err)
		return
	}
	s.auditSystem(addr, "relay-rotate",
		fmt.Sprintf("rotated %s to kid %s (%d app(s) re-issued, cli)", res.Region, res.Kid, res.Apps))
	writeJSON(w, http.StatusOK, apiRelayRotateReply{
		Region: res.Region, Kid: res.Kid, Apps: res.Apps,
		RetireNoEarlierThan: res.RetireNoEarlierThan.UTC().Format(time.RFC3339),
	})
}