httpapi

type ACMEChallenges interface {
	KeyAuthorization(ctx context.Context, token string) (string, bool, error)
}

type AnonymousPolicy interface {
	AllowsAnonymousGrant(ctx context.Context, withPasscode bool) error
	PublicSharing(ctx context.Context) (corepolicy.PublicSharing, error)
}

type AppHosts interface {
	IsAppHostname(ctx context.Context, host string) (bool, error)
}

type AuditArchives interface {
	List(ctx context.Context) ([]audit.ArchiveRecord, error)
	Open(ctx context.Context, archiveID string) (audit.ArchiveRecord, io.ReadCloser, error)
}

type AuditReader interface {
	List(ctx context.Context, q audit.Query) ([]audit.Record, error)
}

type AuditSinks interface {
	Statuses(ctx context.Context) ([]auditstream.Status, error)
}

type AuditStream interface {
	ResolveCursor(ctx context.Context, s string) (audit.Cursor, error)
	Wait(ctx context.Context, q audit.StreamQuery, wait time.Duration, c clock.Clock) (audit.StreamPage, error)
	Export(ctx context.Context, q audit.StreamQuery, enc audit.Encoder, write func([]byte) error) (int, error)
	Oldest(ctx context.Context) (time.Time, bool, error)
}

type Authenticator struct {
	Sessions *state.Sessions
	Tokens   *state.Tokens
	Users    *state.Users
	Groups   interface {
		GroupsForUser(ctx context.Context, userID string) ([]string, error)
	}
	// Cookies names the session cookie this install sets, which is the only
	// one read back (cookie.go).
	Cookies CookieScheme

	// TwoFactor says which sessions must set up a second factor before they
	// are anything more (R-405). Nil holds none back.
	TwoFactor interface {
		SetupPending(ctx context.Context, user state.User) (bool, error)
	}
}

type CookieScheme struct {
	// ExternalURL is how a browser reaches this installation (secureCookie).
	ExternalURL *url.URL
}

type DeployLogOwner func(ctx context.Context, deploymentID string) (string, error)

type DetectionQueue interface {
	Enqueue(ctx context.Context, appID string) (state.Detection, error)
}

type Detector interface {
	Detect(ctx context.Context, appID string) (state.Detection, error)

	// Check refuses what Detect would refuse before it starts, without
	// writing anything.
	Check(ctx context.Context, appID string) error

	// Revise changes a finished proposal as a person asked, through the AI
	// adapter, and records the exchange on it (R-336).
	Revise(ctx context.Context, appID, message string) (state.Detection, error)

	// Rebuild builds the proposal's image again, in the background, when
	// what it would build has changed — an answer the build waited on — so
	// the plan shows the score of what will run (R-311). True when it
	// started.
	Rebuild(ctx context.Context, appID string) (bool, error)
}

type FailedAttempts interface {
	Reserve(ctx context.Context, limits ...state.AttemptLimit) (state.Reservation, error)
	Fail(ctx context.Context, res state.Reservation) error
	Release(ctx context.Context, res state.Reservation) error
	Clear(ctx context.Context, key string) error
}

type Health interface {
	Ping(ctx context.Context) error
}

type InstallVerbs interface {
	InstallVerbsFor(ctx context.Context, p authz.Principal) ([]string, error)
}

type PolicyDocument interface {
	Load(ctx context.Context) (corepolicy.Document, error)
	Save(ctx context.Context, doc corepolicy.Document, updatedBy string) error
}

type RegistryCredentials interface {
	SaveCredential(ctx context.Context, appID string, c oci.Credential) error
	RemoveCredential(ctx context.Context, appID string) error
	DescribeCredential(ctx context.Context, appID string) (oci.CredentialSummary, bool, error)
}

type Security interface {
	Report(ctx context.Context, appID, specID string) (security.Report, error)
	Scan(ctx context.Context, req api.ScanRequest, principal audit.Event) (state.Scan, error)
	Place(ctx context.Context, scores map[string]security.Scores) (map[string]security.Placed, error)
}

type Server struct {
	Logger *zap.Logger
	DB     Health

	Identity api.IdentityAdapter
	Users    *state.Users

	// IDP is external identity: providers, redirect sign-in, linking and
	// SCIM (issue #51). Nil leaves password sign-in the only way in.
	IDP      *idp.Service
	Sessions *state.Sessions

	// TwoFactor is local accounts' second factor (R-405). Nil leaves the
	// password the only factor, and the two-factor routes say so.
	TwoFactor *twofactor.Service
	Tokens    *state.Tokens

	// Hosts is the install's cluster: its hosts and join tokens (R-414,
	// R-415). Nil leaves the cluster routes answering that it is not set up.
	Hosts *hosts.Service

	// HostLoss marks a host lost and starts its apps' standbys (R-421). Nil
	// leaves the route answering that the cluster is not set up.
	HostLoss *liveness.Service
	// Joiner joins this Pando to a cluster at setup (POST /setup/join, R-415).
	// Nil answers that joining is not set up.
	Joiner *hosts.Joiner

	// CLISignIn signs the CLI in through the browser (R-406). Nil leaves
	// pando login --username, with a password, the only way.
	CLISignIn *clisignin.Service

	// OAuth signs MCP clients in (R-413): registration, the console's
	// approval, the token endpoint. Nil leaves the MCP endpoint to clients
	// given a token by hand.
	OAuth   *oauth.Service
	Apps    *state.Apps
	Volumes *state.Volumes
	Authz   *authz.Authorizer
	Auditor *audit.Writer
	Authent *Authenticator

	Registry *api.Registry
	Adapters *state.Adapters

	// Observations shares the runtime's answers for /status and /usage between
	// requests asking at the same moment (issue #72). Authorization is checked
	// before it is consulted, every request. Nil asks the runtime every time.
	Observations *observe.Cache

	// ServiceInstances says which dependency a service Pando runs for an app
	// fills, so /status names a provisioned workload by what it is rather
	// than by its handle. Nil leaves that out.
	ServiceInstances observe.ServiceInstances

	// Address resolves changes to where an app is reached (R-162, R-163).
	// Nil means the address cannot be changed after configuration.
	Address *address.Service

	// Edges reports whether each routing adapter's edge is running (R-174).
	// Nil means no adapter's edge is reported.
	Edges *edge.Service

	// AIFunctions is which AI adapter handles each AI function (R-259). Nil
	// means the endpoints say assignment is not set up.
	AIFunctions *assist.Assignments

	// Assist runs the administrative AI functions. Nil means the endpoints
	// say AI assistance is not set up.
	Assist *assist.Service

	// TeardownNow asks for a deleted app's bundle to be torn down now rather
	// than at the collector's next pass. Nil leaves it to the pass.
	TeardownNow func()

	// AdapterKinds are the kinds of adapter this build can run, with the
	// settings each takes (api.KindInfo), for GET /adapters/kinds.
	AdapterKinds []api.KindInfo

	// AdapterCredentials holds adapters' credentials encrypted (O-20). Written
	// by POST /adapters, never read back by any handler.
	AdapterCredentials *state.AdapterCredentials

	// Reconciles is the loop's bookkeeping. The lifecycle handlers touch it
	// for one reason: a person starting an app Pando gave up on is the human
	// intervention R-151 requires, and the failure count has to be cleared for
	// the loop to look at the app again.
	Reconciles  *state.Reconciles
	Planner     *planner.Planner
	Allocations *state.Allocations
	Deployments *state.Deployments

	// Capacity is GET /capacity's runtime readings, refreshed in the
	// background (issue #72).
	Capacity *capacity.Snapshots

	// Security scores apps and answers where one stands (R-310). Nil on an
	// installation with no scanner, where the endpoints say so rather than
	// returning a zero.
	Security Security
	Deployer *deploy.Runner

	// Approvals starts every deploy, and asks for, records and acts on the
	// approval of those that need one (R-154 – R-159).
	Approvals *approval.Service

	// AutoDeploy reads and changes automatic deploy settings and takes the
	// webhooks git hosts send (R-141, R-142).
	AutoDeploy *autodeploy.Service

	// Subscriptions manages event subscriptions and notification
	// preferences (issue #50). Nil answers that they are unavailable.
	Subscriptions *subscription.Service

	// Notices is what an app's Overview asks of somebody, and each person's
	// ignores of them (R-412). Nil answers that notices are unavailable.
	Notices *notice.Service

	// Inbox is the console notifications a person reads (R-377).
	Inbox *subscription.Inbox

	// Notifier sends Pando's own notifications to the people they name, as
	// their preferences allow. Optional.
	Notifier interface {
		Notify(ctx context.Context, n api.Notification) error
	}

	Logs *deploy.LogStore

	// LogStreams shares one live runtime log stream per app part between
	// everyone on this replica watching it (O-51). Nil makes the following
	// endpoints answer that live logs are not available.
	LogStreams *logstream.Hub
	// DeployLogReauthEvery is how often a connected deploy-log stream checks
	// the viewer's access again (R-048). logstream.DefaultReauthEvery when
	// zero; tests shorten it.
	DeployLogReauthEvery time.Duration

	// QueuePollEvery is how often a queued deploy's log stream reads its
	// place in the queue (issue #93). A second when zero.
	QueuePollEvery time.Duration

	// RelayTransport carries a deploy-log request to the replica holding the
	// log. http.DefaultTransport when nil.
	RelayTransport http.RoundTripper
	// LogOwner finds the replica running a deploy, so its live log can be
	// read from any replica (issue #72). Nil with one replica.
	LogOwner DeployLogOwner
	// FailedAttempts is the shared count behind the limits on guessing a
	// passcode (R-075a) and a password (R-404). In memory, for one process,
	// when nil.
	FailedAttempts FailedAttempts

	Secrets    *state.Secrets
	Detections *state.Detections

	// Clock times a detection wait and how long one has been running. Nil is
	// the system clock.
	Clock clock.Clock

	// Detector runs detection for an app. Nil on an install with no builder or
	// runtime configured, in which case the detection endpoints say so rather
	// than returning an empty proposal — R-106's shape: with nothing
	// configured, each step degrades to a question, not a dead end.
	Detector Detector

	// DetectionQueue is where a detection the API starts is queued (issue
	// #72, O-32). Nil, with a Detector, means detection is not started on
	// create and a re-run is refused as not configured.
	DetectionQueue DetectionQueue

	// Sources keeps an uploaded source (R-262) and fetches an app's source for
	// a scan on request.
	Sources source.Sources

	// SourceConnections is the install's source connections (R-091, issue
	// #127): which one a new app's repository is read with, and the
	// repositories each can list. Nil reads every repository anonymously and
	// answers the /sources routes with an error.
	SourceConnections *sourceconn.Service

	// NotifyConnections is the install's notification adapters, built from
	// their rows on each use: connecting Slack, and the channels a
	// subscription to it can choose. Nil answers the /notify routes with an
	// error.
	NotifyConnections *notifyconn.Service

	// Images keeps the credential an image app's image is pulled with (issue
	// #41). Nil on an install that cannot store one, where setting one says so.
	Images RegistryCredentials

	// ImageRegistries builds the install's image registry adapters (R-252,
	// issue #153), which are configured with POST /adapters like any adapter
	// but built from their rows each time they are used, so saving one needs
	// no restart. Nil checks nothing before saving one.
	ImageRegistries *imageregistry.Service

	// Defaults fills in what an author left out of a spec — the install's
	// adapters, its routing shape, and the retention caps R-211 and R-223 set.
	// Nil means a hand-written spec is taken exactly as written, which is how
	// it behaved before and is wrong: an app with no log cap is an app that can
	// fill the host.
	Defaults SpecDefaults

	// Policy is host policy. Nil until phase 3 configures it, in which case the
	// source allowlist check (R-092) is skipped rather than assumed to pass —
	// the call site says so explicitly.
	Policy SourcePolicy

	// ExternalURL is how a browser reaches this installation, when something
	// other than Pando terminates TLS. It decides one thing: whether the
	// session cookie is marked Secure (O-19). Nil falls back to the request,
	// which is right when Pando serves TLS itself and on a localhost install.
	ExternalURL *url.URL

	// Minter publishes the assertion signing keys at /.well-known/jwks.json.
	Minter     *assertion.Minter
	Grants     *state.Grants
	HostPolicy AnonymousPolicy

	// Verbs answers "what may this principal do install-wide" for GET /me.
	// Nil leaves the list empty, which denies nothing — every install-level
	// endpoint checks the verb itself — but it does hide the admin entry.
	Verbs InstallVerbs

	// PolicyStore reads and writes the host policy document (R-274). Distinct
	// from HostPolicy above, which *evaluates* it: one is the document, the
	// other is the decision, and an endpoint that edits the document has no
	// business asking the evaluator anything.
	PolicyStore PolicyDocument

	// PolicyOverlay is the host policy fields set in the startup config
	// (R-271). PolicyStore already reads through it; this is for refusing a
	// change to one of them and for saying where each was set. Nil means none.
	PolicyOverlay *corepolicy.Overlay

	// StartedAt is when this process started. An adapter configured after it
	// is saved but not running, since adapters are loaded at startup (R-253).
	StartedAt time.Time

	// Restart asks the server to shut down cleanly and start again, loading
	// the adapters and the configuration file afresh. It returns at once; the
	// restart follows the response. Nil means this process cannot restart
	// itself, and POST /restart says so.
	Restart func()

	// Startup is the configuration Pando started with, for GET /config: every
	// non-secret setting and where it came from. Nil in tests that do not set it.
	Startup *config.Config

	// AuditLog reads the append-only log (R-227). Nil on an install where the
	// endpoint should 500 rather than quietly return nothing — an empty audit
	// log and an unreadable one are very different answers.
	AuditLog AuditReader

	// AuditArchives lists and serves the months retention has archived
	// (R-347). Nil answers an empty list: an install with nothing archived
	// and one that cannot archive look the same from here, and both are true.
	AuditArchives AuditArchives

	// AuditStream reads the log in commit order, for the stream and exports
	// (R-381, R-387). AuditEncoders turn native lines into other formats, by
	// name — "ocsf" (R-384). AuditSinks reports each audit sink's delivery
	// (R-383). AuditReads decides when a stream read is itself audited
	// (R-388).
	AuditStream   AuditStream
	AuditEncoders map[string]audit.Encoder
	AuditSinks    AuditSinks
	AuditReads    *audit.ReadThrottle

	// AuditSinkCheck configures an audit sink as it would be saved, so one
	// its adapter refuses is refused by POST /adapters (R-382).
	AuditSinkCheck interface {
		Validate(ctx context.Context, id, kind string, config json.RawMessage, given map[string]secret.Value) error
	}

	// Updates is whether a newer Pando is released (R-351). Nil answers that
	// the check is not running, which is true.
	Updates Updates

	// Upgrades is the in-place upgrade (R-355 – R-362). Nil answers that it
	// is not set up.
	Upgrades Upgrades

	// Version is this binary's version, sent to signed-in callers as
	// Pando-Version so a CLI can tell it is out of step (R-353). Never to an
	// anonymous one: a version is a map of which advisories apply.
	Version string

	// Backups records what has been backed up; Backup does the backing up
	// (R-212). Two fields because they are two concerns: the record has to
	// survive the thing it records, which is R-204's whole point.
	Backups *state.Backups
	Backup  *backup.Service

	// Groups and Roles back the identity endpoints (R-078, R-082).
	Groups *state.Groups
	Roles  *state.Roles

	// AppLimits decides how many apps a person may own, and AppLimitStore
	// holds the values set on users and groups (R-244). Nil AppLimits is no
	// limit.
	AppLimits     *applimit.Service
	AppLimitStore *state.AppLimits

	// IdleSettings reads and changes an app's idle settings (R-397).
	IdleSettings *idle.Settings

	// BundleSource supplies what goes into a backup. Held separately from
	// Backups because one records what was taken and the other reads what is
	// being taken — and the record has to outlive the thing (R-204).
	BundleSource *state.BundleSource

	// Idempotency deduplicates retried infrastructure-creating requests. Nil
	// disables replay rather than failing: the cost is a possible duplicate,
	// and refusing to deploy because a deduplication table is missing would be
	// a worse outcome than deploying twice.
	Idempotency *state.Idempotency

	// Console serves the embedded UI on Pando's own paths. Nil when the binary
	// was built without it, in which case those paths 404 like any other and
	// the API is unaffected — the API is the product (R-261), and the console
	// is one of its clients.
	Console http.Handler

	// AppHosts tells the console handler when a request belongs to an app
	// instead. Nil means the console answers on every hostname, which is
	// correct for a path-addressed install and wrong for a subdomain one.
	AppHosts AppHosts

	// PandoHostnames lists the hostnames Pando serves itself on besides the
	// external URL's: a routing adapter's console hostname. With ExternalURL
	// set, a hostname that is neither one of these nor an app's gets no
	// console and no API (unknownHost). Nil means the external URL's alone.
	PandoHostnames func(ctx context.Context) []string

	// ACMEChallenges answers HTTP-01 challenges for the certificates Pando
	// issues for the edge, on every hostname. Nil answers none.
	ACMEChallenges ACMEChallenges

	// AppProxy serves every request to every app (R-023). Mounted last, as the
	// catch-all, so Pando's own routes are reachable and everything else goes
	// through enforcement. There is no path that reaches an app without it.
	AppProxy http.Handler

	// ClientAddr decides which address each request came from for the audit
	// log (R-380). The zero value records the connecting peer.
	ClientAddr clientaddr.Trusted
	// contains filtered or unexported fields
}

type SourcePolicy interface {
	AllowsSource(ctx context.Context, src spec.Source) error
}

type SpecDefaults interface {
	Defaults(ctx context.Context) spec.Defaults
}

type Updates interface {
	Status(ctx context.Context) (update.Status, error)
	// CheckNow asks GitHub now rather than at the next tick (R-349).
	CheckNow(ctx context.Context) (update.Status, error)
}

type Upgrades interface {
	PlanFor(ctx context.Context, version string) (upgrade.Plan, error)
	Start(ctx context.Context, p authz.Principal, req upgrade.Request) (upgrade.Attempt, error)
	Last(ctx context.Context) (*upgrade.Attempt, error)
}

type VolumeUsage struct {
	ID    string `json:"id"`
	Name  string `json:"name"`
	Path  string `json:"path"`
	Bytes int64  `json:"bytes"`
}

type WorkloadService struct {
	SlotKey string `json:"slot_key"`
	Type    string `json:"type"`
}

type WorkloadStatus struct {
	Name    string `json:"name"`
	Primary bool   `json:"primary"`

	Present bool `json:"present"`
	Running bool `json:"running"`

	// Restarting is the crash loop, which is the thing somebody looking at a
	// degraded app most needs to see. A container that exits and is restarted
	// by the runtime is "running" at almost every instant Pando looks at it.
	Restarting   bool `json:"restarting"`
	RestartCount int  `json:"restart_count"`

	// Healthy is null when the workload declares no health check: no signal is
	// not the same as unhealthy (R-221).
	Healthy  *bool  `json:"healthy"`
	ExitCode *int   `json:"exit_code,omitempty"`
	Image    string `json:"image,omitempty"`

	StartedAt *time.Time `json:"started_at,omitempty"`

	// Service is the dependency a workload Pando runs for the app fills
	// (R-131's provisioned), so a reader sees a PostgreSQL where the runtime
	// names a handle such as svc-01h….
	Service *WorkloadService `json:"service,omitempty"`
	// contains filtered or unexported fields
}

type WorkloadUsage struct {
	Name    string `json:"name"`
	Primary bool   `json:"primary"`
	Running bool   `json:"running"`

	CPUMillis      int   `json:"cpu_millis"`
	CPULimitMillis int   `json:"cpu_limit_millis"`
	MemoryBytes    int64 `json:"memory_bytes"`
	MemoryLimit    int64 `json:"memory_limit_bytes"`

	// DiskBytes is written outside the part's volumes; -1 when unknown.
	DiskBytes int64         `json:"disk_bytes"`
	Volumes   []VolumeUsage `json:"volumes"`
}