detection

type AuditEvent struct {
	Action string
	AppID  string
	Detail map[string]any
}

type Auditor interface {
	Write(ctx context.Context, e AuditEvent) error
}

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

type ImageBuilder interface {
	BuildImages(ctx context.Context, s *spec.AppSpec, checkout *source.Checkout, sink io.Writer, tag string) (string, map[string]string, error)
	BuiltImageAuth(ctx context.Context, image string) *api.RegistryAuth
}

type Installation interface {
	// Defaults returns the install's adapters, routing mode and limits. The
	// routing mode comes from the routing adapter's own declared default
	// (R-162): adding an app uses it without asking.
	Defaults(ctx context.Context) spec.Defaults
}

type PortAllocator interface {
	Allocate(ctx context.Context, adapterRef, appID string, from, to int) (int, error)
}

type Queue struct {
	Detections *state.Detections

	// Detect runs one claimed detection to completion. In production,
	// Runner.RunQueued.
	Detect func(ctx context.Context, appID string) (state.Detection, error)

	// Limit is how many detections this replica runs at once.
	// DefaultConcurrency when zero.
	Limit int

	// Poll is how often to look for detections another replica queued. Two
	// seconds when zero.
	Poll time.Duration

	// Timeout overrides the package Timeout. Zero is the default.
	Timeout time.Duration

	Logger *zap.Logger
	// contains filtered or unexported fields
}

type RegistryInstallation struct {
	Registry *api.Registry

	// BaseDomain is what a subdomain is carved out of, in subdomain mode.
	BaseDomain string

	// Fallback supplies the values that come from neither an adapter nor host
	// policy — the [P] defaults in the requirements.
	Fallback spec.Defaults
}

type RegistryScreeners struct{ Registry *api.Registry }

type Runner struct {
	Apps       *state.Apps
	Detections *state.Detections
	Job        *detect.Job

	// Sources fetches the source detection reads, including an uploaded one
	// (R-262).
	Sources source.Sources

	// Policy is checked again here, not only at app creation. The allowlist can
	// change between the two, and a re-detection (R-022) of an app whose source
	// is no longer allowed must not clone it.
	Policy SourcePolicy

	// Install fills in everything the repository cannot answer. Without it a
	// detected spec describes the app and says nothing about where it runs,
	// which is a spec that cannot be planned — the gap that made detection
	// produce proposals nobody could deploy.
	Install Installation

	// Ports assigns a host port in port-mode routing. Only consulted when the
	// routing adapter's default mode is `port`, which the loopback adapter that
	// ships as the laptop default is.
	Ports PortAllocator

	// PortRange bounds that allocation.
	PortRangeStart int
	PortRangeEnd   int

	// Screeners says which AI adapter performs each function, and on which
	// model (R-259). Nil is the ordinary case: an install with no AI adapter
	// configured is not a degraded install, because everything the auction
	// produced is there either way (R-106, R-335).
	Screeners Screeners

	// Screener, when Screeners is nil, performs every function under
	// ScreenerRef. For an embedding with one adapter and nothing to assign.
	Screener     screening.Screener
	ScreenerRef  string
	ScreenPolicy ScreenPolicy

	// Auditor records that a repository's contents left the host (R-337).
	Auditor Auditor

	// Screening budget (R-339). Zero means the package default.
	ScreenMaxFiles int
	ScreenMaxBytes int64
	ScreenTimeout  time.Duration

	// Clock stamps conversation turns. Nil is the system clock.
	Clock clock.Clock

	// Scanner scores the checkout while it is still on disk (R-312).
	//
	// Detection is the first and, for a while, the only moment Pando holds an
	// app's source: an app that has been added and not yet deployed has no
	// image to look at, and waiting for one means the first thing anybody sees
	// about a new app is "not scanned yet". A committed key or a vulnerable
	// lockfile is exactly what somebody wants to know *before* deciding to
	// deploy it.
	//
	// Optional, and never fatal. An installation with no scanner detects
	// exactly as before, and a scanner that fails does not fail a detection —
	// the proposal is the thing being produced here.
	Scanner SourceScanner

	// Builder builds what the app would deploy, so the plan can show the
	// score of the image that will run (R-311). Nil builds nothing: the plan
	// shows the source's findings and waits for the deploy to score the
	// image.
	Builder ImageBuilder

	// NewBuildTag names a detection's build. Nil is a time-based name.
	NewBuildTag func() string

	// Background runs a rebuild after an answer (Rebuild). Nil is a
	// goroutine.
	Background func(func())

	// Egress resolves the rules the trial run is held to (R-097): the app's
	// own, from its current spec where it has one, against host policy. Nil
	// restricts nothing, and is for tests and embeddings with no policy.
	Egress TrialEgresser
}

type ScreenPolicy interface {
	// AllowsScreening returns a reason when host policy forbids it, and an
	// empty string when it does not. A reason, not an error: this is not a
	// failure, it is a posture, and it is shown in the review as one.
	AllowsScreening(ctx context.Context) string
}

type Screeners interface {
	ScreenerFor(fn api.AIFunction) (s screening.Screener, ref, model string, ok bool)
}

type SourcePolicy interface {
	AllowsSource(ctx context.Context, src spec.Source) error
	IsolationFloors(ctx context.Context) (build, runtime spec.IsolationClass, err error)
}

type SourceScanner interface {
	// Scans reports whether there is a scanner to scan with.
	Scans() bool

	// ScanSource scans and records in one call.
	ScanSource(ctx context.Context, req api.ScanRequest)

	// ScanPart scans one part, the source or the image, recording nothing;
	// RecordParts records the parts as one scan of both (R-311).
	ScanPart(ctx context.Context, req api.ScanRequest) (api.ScanResult, error)
	RecordParts(ctx context.Context, req api.ScanRequest, parts []api.ScanResult, failed error)
}

type TrialEgresser interface {
	TrialEgress(ctx context.Context, s *spec.AppSpec) (api.EgressRules, error)
}