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)
	}
}

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 {
	Recent(ctx context.Context, key string, window time.Duration) (int, error)
	// Wait is how long until the oldest failure within window leaves it.
	Wait(ctx context.Context, key string, window time.Duration) (time.Duration, error)
	Record(ctx context.Context, key string, window time.Duration) 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
	Tokens   *state.Tokens
	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

	// 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

	// 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

	// 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

	// 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 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"`
}

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"`
}