// The CLI's sidecar provisioning API: the verbs that turn "run a member's
// bot" into a data write in the deployment bucket, so an app process holding
// no AWS credentials and no box access can provision one per enrolled member
// in seconds. The record it writes is the whole authorization; the agent's
// sidecar reconcile pass (internal/provision/sidecar_reconcile.go) is what
// turns it into a route, on its own box only.
//
// Everything structural here is the instance family's, deliberately: the
// GATE is instanceGate verbatim (apiinstances.go), so the SAME two bearer
// shapes reach it — a member's user token, or an APP token bound to one
// account and one app at mint time — with the same ordering (principal,
// budget, readiness) and the same byte-identical 404 on every refusal before
// the principal is proven. That reuse is the point rather than a shortcut:
// Eleven's process calls this door with the CARLOS_INSTANCE_TOKEN it already
// holds, and a second hand-rolled gate would be a second place for the
// ordering to drift. `apidomains.go` shares it for the identical reason.
//
// Three things are NOT the instance family's, and each is a consequence of
// what a sidecar is (design: sidecar members):
//
//   - There is no host in the request and no domain in the manifest. A
//     sidecar's host is DERIVED — provision.SidecarHost(name, app, sqid),
//     under the reserved, never-resolvable .sidecar.internal suffix — so
//     there is no namespace for a caller to reach into and no sibling-apex
//     hazard to refuse: the app and account are IN the host. The only thing
//     the request names is one DNS label.
//   - There is no PATCH. A sidecar has no upstream set to repoint, which is
//     the one thing an instance record's update verb exists for. The family
//     is create-only plus delete, which is also what makes CreateSidecarRecord's
//     lost race a 409 rather than a silent overwrite.
//   - CHANNEL is stamped on every record, always. Task 9's reconcile pass
//     PROTECTS a channel-less sidecar record — it is deliberately never
//     minted, because a route with no channel cannot resolve a release and
//     so has no build to exec. A record written without one would be
//     silently inert: minted by nothing, with no error anywhere. That makes
//     this door load-bearing for it (see handleAPISidecarCreate).
//
// Spec: docs/superpowers/specs/2026-08-17-sidecar-members-design.md §11 (the
// verbs), §4 (the shapes), §7.4 (the wake), §8 (placement).
package console

import (
	"context"
	"errors"
	"log"
	"net/http"
	"os"
	"slices"
	"strings"
	"time"

	"github.com/carlosframework/platform/internal/hostops"
	"github.com/carlosframework/platform/internal/provision"
	"github.com/carlosframework/platform/internal/release"
)

// sidecarListMax caps one list answer, the instance family's number for the
// same reason: a sidecar fleet is one row per enrolled member and can be
// large, and the response says `truncated` rather than silently serving a
// prefix.
const sidecarListMax = 500

// The manifest's argv bounds (design §4.1). Args becomes the argv the
// activator execs the app's OWN binary with, so the bound here is manifest
// hygiene rather than privilege — the caller already controls that binary
// via ship — but a manifest is read forever, and an unbounded argv written
// once would be permanent. Same numbers as instanceSeedMaxArgs for the same
// reason, kept as their own constants so a change to one family's bound is
// never silently a change to the other's.
const (
	sidecarArgsMax   = 16
	sidecarArgMaxLen = 256
)

// sidecarMaxSeconds bounds the two duration knobs. Thirty days is far past
// any honest idle or max-run and short of the values that read as "never" —
// a manifest is read forever, so a nonsense value written once outlives
// whoever typed it.
const sidecarMaxSeconds = 30 * 24 * 60 * 60

// sidecarManifest reads the app's sidecar manifest and answers the caller
// itself when it cannot be had. ok=false means a response has already been
// written.
//
// CREATE is its only caller, exactly as instanceManifest's is: the manifest
// is policy about what may be BROUGHT INTO existence, and reads, wakes and
// deletes are about what already exists, which no version of it can retract.
//
// The two failures are kept apart on purpose. ABSENCE is an answer — the
// feature does not exist for this app — while a read failure is the bucket
// being unreachable. Reporting a hiccup as "sidecars are not enabled" would
// tell an app its feature had been switched off. The 409 names SIDECARS' own
// enable verb: an app with instances enabled and sidecars not is the ordinary
// state, so pointing at the other family's verb would be actively wrong.
func (s *Server) sidecarManifest(ctx context.Context, w http.ResponseWriter, acct *Account, app string) (*provision.SidecarManifest, bool) {
	m, err := provision.GetSidecarManifest(ctx, s.cfg.Releases, acct.Sqid, app)
	switch {
	case err == nil:
		return m, true
	case errors.Is(err, os.ErrNotExist):
		// Membership (or binding) is already proven, so this may name its
		// cause and the act that fixes it.
		jsonError(w, http.StatusConflict,
			"sidecars are not enabled for "+app+" — enable them first (carlos sidecars enable -app "+app+")")
		return nil, false
	default:
		log.Printf("console: api sidecars manifest %s/%s: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway, "could not read sidecar settings")
		return nil, false
	}
}

// sidecarListRecord wraps provision.SidecarRecord with the console's own
// running-version join, kept OFF the record for the same reason
// instanceListRecord keeps staged_version off provision.Record: the record is
// the wire shape CreateSidecarRecord persists to the bucket, this field is
// never written there, and giving the record the field would risk a future
// write path serializing a stale value into stored bytes the join was never
// meant to touch.
type sidecarListRecord struct {
	provision.SidecarRecord
	// RunningVersion is the build the agent last started for the sidecar
	// (registry ServingVersion, zero-downtime plan 5), read from whichever
	// box carries its route via status/boxes/<label>.json's RouteServing,
	// under loadBoxJoin's staleness rule. NOT RouteVersions: since plan 4
	// that is root's install stamp, which can name a build nothing runs yet,
	// and the worker's own /v1/ready report is display metadata only. A
	// sidecar that has not started anywhere reads EMPTY and is rendered
	// "unknown", never as the channel's desired version.
	RunningVersion string `json:"running_version"`
}

// handleAPISidecarList answers `carlos sidecars ls`: this app's records,
// name-sorted, capped and honest about the cap, each carrying its
// best-effort running version.
func (s *Server) handleAPISidecarList(w http.ResponseWriter, r *http.Request) {
	_, acct, app, ok := s.instanceGateFor(w, r, "sidecar")
	if !ok {
		return
	}
	ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	recs, truncated, err := provision.ListSidecarRecords(ctx, s.cfg.Releases, acct.Sqid, app, sidecarListMax)
	if err != nil {
		log.Printf("console: api sidecars list %s/%s: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway, "could not list sidecars")
		return
	}
	join := loadBoxJoin(ctx, s.cfg.Releases, time.Now())
	out := make([]sidecarListRecord, 0, len(recs))
	for _, rec := range recs {
		out = append(out, sidecarListRecord{SidecarRecord: rec, RunningVersion: join.serving[rec.Host]})
	}
	if s.cfg.HostClaim {
		pending, err := s.claimPendingViews(ctx, acct.Sqid, app, "sidecar")
		if err != nil {
			writeClaimResponseError(w, err)
			return
		}
		writeJSON(w, http.StatusOK, map[string]any{"sidecars": out, "truncated": truncated, "operations": pending})
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"sidecars": out, "truncated": truncated})
}

// handleAPISidecarGet answers one record. A name with no record is the
// byte-identical 404 — a sidecar's existence is not a thing to probe for
// either, and this way "no such sidecar" and "no such app" read alike.
func (s *Server) handleAPISidecarGet(w http.ResponseWriter, r *http.Request) {
	_, acct, app, ok := s.instanceGateFor(w, r, "sidecar")
	if !ok {
		return
	}
	name := r.PathValue("name")
	// Shape-checked before the key builder, not after. A {name} segment
	// arrives percent-decoded, so "..%2f..%2fsidecars.json" reaches this
	// handler as a path with separators in it; SidecarRecordKey would happily
	// join it. A name that cannot name a record is simply not found — the
	// same answer a name that names no record gets.
	if !provision.ValidSidecarName(name) {
		http.NotFound(w, r)
		return
	}
	ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	rec, err := provision.GetSidecarRecord(ctx, s.cfg.Releases, acct.Sqid, app, name)
	if errors.Is(err, os.ErrNotExist) {
		http.NotFound(w, r)
		return
	}
	if err != nil {
		log.Printf("console: api sidecars get %s/%s/%s: %v", acct.Sqid, app, name, err)
		jsonError(w, http.StatusBadGateway, "could not read the sidecar")
		return
	}
	writeJSON(w, http.StatusOK, rec)
}

// handleAPISidecarCreate is the point of the feature: one create-only write
// to the bucket, in the family's refusal order — gate, budget, readiness
// (instanceGate), manifest, name, region, channel, shape, pause
// (sidecarsgate.go), write.
//
// Every field policy governs is stamped from the MANIFEST, never from the
// request. The body has no pool field to lie in, no host field (the host is
// derived), and no placement field — that last one deliberately, and it is
// worth stating why: a record that restated the manifest's placement would
// pin itself against a later RELAXATION of it (sidecarPlacement takes the
// most restrictive of the two), so Task 9's placement evacuation — flip the
// manifest and the rows move — would stop working in one direction for every
// record this door ever wrote. Leaving the field empty keeps the manifest
// authoritative, which is what app-wide policy means. The other direction,
// an app token stating "any" under a no-inbound manifest to place a bot on
// boxes the operator meant to keep it off, is refused HERE and again in the
// reconciler (sidecarPlacement's most-restrictive rule): both doors hold the
// invariant, neither trusts the other.
func (s *Server) handleAPISidecarCreate(w http.ResponseWriter, r *http.Request) {
	principal, acct, app, ok := s.instanceGateFor(w, r, "sidecar")
	if !ok {
		return
	}
	if s.refuseTemporary(w, acct, app, "serve anything but a static site at "+app+"'s own platform address") {
		return
	}
	ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	m, ok := s.sidecarManifest(ctx, w, acct, app)
	if !ok {
		return
	}
	var req struct {
		Name    string `json:"name"`
		Region  string `json:"region"`
		Channel string `json:"channel"`
	}
	if !readJSON(w, r, &req) {
		return
	}
	name := strings.TrimSpace(req.Name)
	// Path-traversal defence stated as such: this name becomes a bucket key
	// segment here and, on the box, a segment of the derived host — which is
	// itself the <host>.db and cgroup path segment. Nothing below runs until
	// it is one DNS label.
	if !provision.ValidSidecarName(name) {
		jsonError(w, http.StatusBadRequest,
			"invalid name — a sidecar name is a single DNS label (lowercase a-z, 0-9, hyphen, 1-63 chars)")
		return
	}
	// A fleet-placed app governs every one of its records' Region uniformly —
	// handleAPIInstanceCreate's rule, mirrored here because Eleven, the
	// customer this whole family exists for, places its app onto a fleet. When
	// a placement exists it OVERRIDES whatever the request body sent, and the
	// ordinary region/allow-list validation below never runs at all: a
	// "fleet/<name>" value would fail provision.ValidRegion's shape anyway,
	// which is exactly why this has to be a check made BEFORE that validation
	// rather than alongside it. A placed app's region is not user input.
	reg, err := openRegistry(s.cfg.Registry)
	if err != nil {
		log.Printf("console: api sidecars create %s/%s: open registry: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway, "could not check this app's placement")
		return
	}
	placed, err := s.appPlacement(reg, acct, app)
	if err != nil {
		log.Printf("console: api sidecars create %s/%s: check placement: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway, "could not check this app's placement")
		return
	}
	region := strings.TrimSpace(req.Region)
	if placed != "" {
		region = placed
	} else if !provision.ValidRegion(region) || !instanceRegionAllowed(m.Regions, region) {
		msg := "invalid region"
		if len(m.Regions) > 0 {
			msg = "region " + region + " is not one this app's sidecars run in — allowed: " + strings.Join(m.Regions, ", ")
		}
		jsonError(w, http.StatusBadRequest, msg)
		return
	}
	// The channel, resolved request -> manifest -> documented default, and
	// NEVER left empty. See this file's package comment: the reconcile pass
	// protects a channel-less record and never mints it, so an empty channel
	// here is a sidecar that silently never runs.
	channel := strings.TrimSpace(req.Channel)
	if channel == "" {
		if channel = strings.TrimSpace(m.Channel); channel == "" {
			channel = "stable"
		}
	}
	if !release.ValidChannel(channel) {
		jsonError(w, http.StatusBadRequest, "invalid channel name")
		return
	}
	rec := provision.SidecarRecord{
		Schema:  1,
		Name:    name,
		Host:    provision.SidecarHost(name, app, acct.Sqid),
		App:     app,
		Account: acct.Sqid,
		Pool:    m.Pool,
		Region:  region,
		Channel: channel,
		// UTC, like every other timestamp written to the bucket: these
		// records are read on boxes in other regions.
		CreatedAt: time.Now().UTC(),
		CreatedBy: principal,
	}
	// The shape rails, at the door — the same door the box's reconcile pass
	// re-checks them at, because neither side trusts the other about what is
	// in the bucket. The message is ValidateSidecarShape's own.
	if err := provision.ValidateSidecarShape(rec); err != nil {
		jsonError(w, http.StatusBadRequest, err.Error())
		return
	}
	// The sidecar pause (sidecarsgate.go): after every check above, so a
	// stranger still meets the 404 and a bad request its 400, and before
	// the cap's listing, the leftover rail and either write arm.
	if s.refuseSidecarsPaused(w, acct, app, "create") {
		return
	}
	// Plans 3a: the plan caps workers per app, under the account lock.
	defer s.planLock(acct)()
	if err := s.checkSidecars(r.Context(), acct, app); err != nil {
		if isPlanCap(err) {
			writeJSON(w, http.StatusConflict, map[string]any{"error": err.Error(), "code": "cap"})
			return
		}
		log.Printf("console: api sidecars create %s/%s: plan cap: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway, "could not create the sidecar — try again")
		return
	}
	if m.Hibernate != nil && !*m.Hibernate {
		if err := s.checkAlwaysOnCreate(acct, app); err != nil {
			if isPlanCap(err) {
				writeJSON(w, http.StatusConflict, map[string]any{"error": err.Error(), "code": "cap"})
				return
			}
			log.Printf("console: api sidecars create %s/%s: plan: %v", acct.Sqid, app, err)
			jsonError(w, http.StatusBadGateway, planCheckFailedCopy)
			return
		}
	}
	// The leftover-replica rail (#199, createleftovers.go): a sidecar's host
	// is derived from its name, so a name reused after a delete lands on the
	// deleted sidecar's replica. Refused, after every validation above.
	if ref := s.leftoverReplicaRefusal(r.Context(), leftoverCreate{
		logTag: "api sidecars create " + acct.Sqid + "/" + app,
		host:   rec.Host, region: region, pool: rec.Pool,
		exists: func(ctx context.Context) (bool, error) {
			_, err := provision.GetSidecarRecord(ctx, s.cfg.Releases, acct.Sqid, app, name)
			if errors.Is(err, os.ErrNotExist) {
				return false, nil
			}
			return err == nil, err
		},
		// The same two answers the CreateSidecarRecord call below gives.
		duplicate:  doorRefusal{http.StatusConflict, "sidecar " + name + " already exists"},
		readFailed: doorRefusal{http.StatusBadGateway, "could not create the sidecar — try again"},
		taken:      "the name " + name + " still holds data from a deleted sidecar. Choose another name, or ask an operator to purge it.",
		unsure:     "could not check whether the name " + name + " is free. Try again.",
	}); ref != nil {
		jsonError(w, ref.Status, ref.Msg)
		return
	}
	// A fresh budget for the write: validation and the rail's listings may
	// have spent most of the original one.
	cancel()
	ctx, cancel = context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	var recordWriteErr error
	if s.cfg.HostClaim {
		request, err := s.beginClaimCreate(r.Context(), acct, app, rec.Host, principal, func(now time.Time, acquisition string) (hostops.Record, error) {
			rec.CreatedAt = time.Time{}
			rec.Acquisition = acquisition
			region := s.cfg.claimPlacementRegion(rec.Region)
			prepared, err := hostops.PrepareSidecar(rec, now, region)
			if err == nil {
				rec.CreatedAt = now
			}
			return prepared, err
		})
		if err != nil {
			writeClaimResponseError(w, err)
			return
		}
		defer request.Close()
		if !s.finishClaimCreate(w, request) {
			return
		}
	} else {
		recordWriteErr = provision.CreateSidecarRecord(ctx, s.cfg.Releases, rec)
	}
	if err := recordWriteErr; err != nil {
		if errors.Is(err, release.ErrCASConflict) {
			// A lost race against a second create for the same name, or a
			// plain duplicate. Either way the winner's record stands.
			jsonError(w, http.StatusConflict, "sidecar "+name+" already exists")
			return
		}
		log.Printf("console: api sidecars create %s/%s/%s: %v", acct.Sqid, app, name, err)
		jsonError(w, http.StatusBadGateway, "could not create the sidecar — try again")
		return
	}
	s.audit(acct, app, principal, "sidecar-create", "created sidecar "+name+" (cli)")
	// The record is what a box's sidecar reconcile leg mints a route from, so
	// this is a box-consumed write (carlos-deploy §3): announce it, and the
	// sidecar is running seconds after signup instead of on the hour.
	s.bumpSerial(ctx)
	writeJSON(w, http.StatusCreated, rec)
}

// handleAPISidecarDelete retires a sidecar's provisioning authorization. The
// record is deleted; the parked database and blobs are deliberately
// untouched, exactly as an instance delete leaves them — retiring a member's
// bot is not destroying that member's data. Idempotent: the caller's goal is
// "not there", and a second delete has reached it.
func (s *Server) handleAPISidecarDelete(w http.ResponseWriter, r *http.Request) {
	principal, acct, app, ok := s.instanceGateFor(w, r, "sidecar")
	if !ok {
		return
	}
	name := r.PathValue("name")
	ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	// SHAPE ONLY, always — and the manifest is not read here at all. Policy
	// is CREATE-time ("may this app have sidecars"), and deletion has to
	// outlive every version of it: an app that retired its manifest still has
	// records, and those are exactly the records that must be deletable, or
	// provisioned rows are stranded with nothing left able to retire them.
	// What deletion actually needs from validation is the traversal defence:
	// a {name} arrives percent-decoded, so "..%2f..%2fsidecars.json" reaches
	// here with separators in it and SidecarRecordKey would happily join it.
	if !provision.ValidSidecarName(name) {
		jsonError(w, http.StatusBadRequest, "invalid name")
		return
	}
	if err := s.retireHostRecord(ctx, provision.RetireRef{Family: "sidecar", Account: acct.Sqid, App: app, Host: provision.SidecarHost(name, app, acct.Sqid), Name: name, By: principal}); err != nil {
		// An accepted delete is this principal's durable request: audit it
		// and announce it before answering 202 with the operation.
		if accepted, ok := claimRetireAcceptedOf(err); ok {
			s.audit(acct, app, principal, "sidecar-delete", "delete of sidecar "+name+" accepted, operation "+accepted.operation+" (cli)")
			s.bumpSerial(ctx)
		}
		if s.writeClaimPending(w, err) {
			return
		}
		log.Printf("console: api sidecars delete %s/%s/%s: %v", acct.Sqid, app, name, err)
		jsonError(w, http.StatusBadGateway, "could not delete the sidecar — try again")
		return
	}
	// The wake object is this record's, and it goes with it — best effort,
	// AFTER the authorization is gone and never able to fail the request. An
	// app shaped like Eleven's has one sidecar per enrolled member, so
	// leaving these behind would accrue one object per retired member in the
	// bucket forever. A leftover is harmless in itself (the box's first sight
	// of a wake object is recorded silently and never replayed —
	// host/sidecarwake.go), which is exactly why a failure here is logged
	// rather than reported: the caller's goal is reached either way.
	if err := s.deleteLegacySidecarWake(ctx, acct.Sqid, app, name); err != nil {
		log.Printf("console: api sidecars delete %s/%s/%s: wake object: %v", acct.Sqid, app, name, err)
	}
	// Audited whether or not an object was actually there to remove:
	// idempotency makes "deleted" and "already gone" indistinguishable from
	// the store, and the fact worth recording is that this principal asked
	// for this sidecar to stop existing.
	s.audit(acct, app, principal, "sidecar-delete", "deleted sidecar "+name+" (cli)")
	// Retiring the row is reconcile's work too, and the direction people want
	// FAST: the announcement is what stops the process in seconds.
	s.bumpSerial(ctx)
	writeJSON(w, http.StatusOK, map[string]any{"result": "deleted"})
}

// handleAPISidecarWake asks every box serving this sidecar to wake it
// (design §7.4's second wake source). A sidecar has no socket and nothing
// dials it, so unlike an instance it has no "next request" to wake on: the
// signal has to be an object a pull-based box notices on its own.
//
// The write goes through release.TouchSidecarWake and nowhere else. Two
// writers for one generation counter is how that counter ends up written two
// different ways; the object is CAS-guarded, a lost race is success (the
// signal has already fired), and change detection downstream is by ETAG, not
// by the counter's value.
//
// A name with no record is the byte-identical 404, and the record read is
// what stands between an app token and an unbounded write: without it, any
// name at all would mint a wake object for a sidecar that does not exist.
func (s *Server) handleAPISidecarWake(w http.ResponseWriter, r *http.Request) {
	principal, acct, app, ok := s.instanceGateFor(w, r, "sidecar")
	if !ok {
		return
	}
	name := r.PathValue("name")
	if !provision.ValidSidecarName(name) {
		http.NotFound(w, r)
		return
	}
	ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	rec, err := provision.GetSidecarRecord(ctx, s.cfg.Releases, acct.Sqid, app, name)
	if errors.Is(err, os.ErrNotExist) {
		http.NotFound(w, r)
		return
	}
	if err != nil {
		log.Printf("console: api sidecars wake read %s/%s/%s: %v", acct.Sqid, app, name, err)
		jsonError(w, http.StatusBadGateway, "could not read the sidecar")
		return
	}
	if err := s.touchSidecarWake(ctx, acct.Sqid, app, name,
		principal, "carlos sidecars wake"); err != nil {
		log.Printf("console: api sidecars wake %s/%s/%s: %v", acct.Sqid, app, name, err)
		jsonError(w, http.StatusBadGateway, "could not request the wake — try again")
		return
	}
	s.audit(acct, app, principal, "sidecar-wake", "requested a wake for sidecar "+name+" (cli)")
	// The wake object is watched on the fast convergence path, which a serial
	// move is what drives: without this the box would not look until its next
	// ordinary tick.
	s.bumpSerial(ctx)
	writeJSON(w, http.StatusOK, map[string]any{
		"result": "waking", "name": name, "host": rec.Host,
	})
}

// handleAPISidecarEnable is the member-facing half of `carlos sidecars
// enable`: the app's opt-in to sidecar provisioning, and the policy every
// record is checked against.
//
// Gated by apiAccountApp DIRECTLY, not the instance gate: enabling is
// policy, a human act — an app token meets cliUser's 401 here, exactly as it
// does at the instance token mint and the instances-manifest door. Budgeted
// on the address-keyed write limiter for the same reason: the principal an
// enable belongs to is a person.
//
// It has NO domain to pin, which is the one security check its instances
// counterpart is mostly made of. A sidecar host is derived
// (provision.SidecarHost) under a reserved suffix nothing resolves, so there
// is no hostname namespace for this door to hand out and no operator-written
// custom domain for it to overwrite. What it can still do wrong is rewrite
// operator policy, so POOL and REGIONS ride through untouched in both
// directions — store mode (`carlos sidecars enable` against the bucket) is
// where those are set, exactly as with instances.
func (s *Server) handleAPISidecarEnable(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.cli.write.allow(addr, time.Now()) {
		jsonError(w, http.StatusTooManyRequests, "too many requests — wait a minute and try again")
		return
	}
	if s.cfg.Releases == nil {
		jsonError(w, http.StatusServiceUnavailable,
			"no deployment bucket on this host — the console is running without one")
		return
	}
	// Every field is a POINTER because "absent" and "empty" are different
	// requests on the wire (the apiConfigApply precedent): an omitted field
	// preserves what the manifest already carries, an explicit value replaces
	// it — including args' explicit [] meaning "clear" and hibernate's
	// explicit false, which must win over HibernateOrDefault's true.
	var req struct {
		Channel       *string   `json:"channel"`
		Args          *[]string `json:"args"`
		Placement     *string   `json:"placement"`
		IdleSeconds   *int      `json:"idle_seconds"`
		MaxRunSeconds *int      `json:"max_run_seconds"`
		Hibernate     *bool     `json:"hibernate"`
	}
	if !readJSON(w, r, &req) {
		return
	}
	if req.Channel != nil && !release.ValidChannel(*req.Channel) {
		jsonError(w, http.StatusBadRequest, "invalid channel name")
		return
	}
	if req.Placement != nil &&
		!slices.Contains([]string{"", provision.PlacementAny, provision.PlacementNoInbound}, *req.Placement) {
		jsonError(w, http.StatusBadRequest,
			`invalid placement — want "any" or "no-inbound"`)
		return
	}
	if req.Args != nil {
		if len(*req.Args) > sidecarArgsMax {
			jsonError(w, http.StatusBadRequest, "args takes at most 16 arguments")
			return
		}
		for _, arg := range *req.Args {
			if arg == "" || len(arg) > sidecarArgMaxLen {
				jsonError(w, http.StatusBadRequest, "each argument must be 1-256 bytes")
				return
			}
		}
	}
	for _, d := range []struct {
		what string
		v    *int
	}{{"idle_seconds", req.IdleSeconds}, {"max_run_seconds", req.MaxRunSeconds}} {
		if d.v != nil && (*d.v < 0 || *d.v > sidecarMaxSeconds) {
			jsonError(w, http.StatusBadRequest, d.what+" must be between 0 and 2592000 (30 days); 0 means the default")
			return
		}
	}
	// The sidecar pause (sidecarsgate.go): after authentication, membership
	// and validation, before the manifest read and its write.
	if s.refuseSidecarsPaused(w, acct, app, "enable") {
		return
	}
	ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	// Read WITH the etag and write guarded by it below: a read-modify-write
	// through the upsert (PutSidecarManifest re-reads inside) would silently
	// swallow an operator's store-mode write landing in the same window,
	// which is exactly the pool/regions policy this door promises not to
	// touch.
	// Plans 3b: no plan offers workers that never sleep. Only a request that
	// asks for hibernate:false is refused; one that omits the field leaves an
	// existing manifest as it was.
	if req.Hibernate != nil && !*req.Hibernate {
		if err := s.checkAlwaysOn(ctx, acct, app); err != nil {
			if isPlanCap(err) {
				writeJSON(w, http.StatusConflict, map[string]any{"error": err.Error(), "code": "cap"})
				return
			}
			log.Printf("console: api sidecars enable %s/%s: plan: %v", acct.Sqid, app, err)
			jsonError(w, http.StatusBadGateway, planCheckFailedCopy)
			return
		}
	}
	m, etag, err := provision.GetSidecarManifestETag(ctx, s.cfg.Releases, acct.Sqid, app)
	switch {
	case errors.Is(err, os.ErrNotExist):
		m, etag = &provision.SidecarManifest{Schema: 1, App: app}, ""
	case err != nil:
		log.Printf("console: api sidecars enable read %s/%s: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway, "could not read sidecar settings")
		return
	}
	// Recorded debt, the same the instances enable door carries: fields ADDED
	// to schema 1 after this binary would be dropped by this
	// read-modify-write, so an additive manifest field needs the console
	// upgraded before members enable through it.
	if req.Channel != nil {
		m.Channel = *req.Channel
	}
	if req.Args != nil {
		m.Args = *req.Args
	}
	if req.Placement != nil {
		m.Placement = *req.Placement
	}
	if req.IdleSeconds != nil {
		m.IdleSeconds = *req.IdleSeconds
	}
	if req.MaxRunSeconds != nil {
		m.MaxRunSeconds = *req.MaxRunSeconds
	}
	if req.Hibernate != nil {
		m.Hibernate = req.Hibernate
	}
	// App is stamped from the PATH, never from the body — there is no field
	// for it above, and a manifest whose App disagreed with its own key would
	// be a record family that lies about its identity.
	m.Schema, m.App = 1, app
	if err := provision.PutSidecarManifestIfMatch(ctx, s.cfg.Releases, acct.Sqid, app, *m, etag); err != nil {
		if errors.Is(err, release.ErrCASConflict) {
			jsonError(w, http.StatusConflict,
				"sidecar settings changed while this request was in flight — try again")
			return
		}
		log.Printf("console: api sidecars enable %s/%s: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway, "could not enable sidecars — try again")
		return
	}
	s.audit(acct, app, addr, "sidecar-enable", "enabled sidecars for "+app+" (cli)")
	// The manifest is what the reconcile pass converges args, ceilings,
	// hibernate and placement from on every pass, so a change here changes
	// what boxes do — announce it.
	s.bumpSerial(ctx)
	writeJSON(w, http.StatusOK, map[string]any{
		"app": app, "pool": m.Pool, "channel": m.Channel, "args": m.Args,
		"placement": m.PlacementOrDefault(), "regions": m.Regions,
		"idle_seconds": m.IdleSeconds, "max_run_seconds": m.MaxRunSeconds,
		"hibernate": m.HibernateOrDefault(),
	})
}