worker

type BuilderConfig struct {
	// Image is the buildkitd container image. Defaults to DefaultBuilderImage.
	Image string

	// ConfigPath is a host file path to a buildkitd.toml that will be bind-
	// mounted at /etc/buildkit/buildkitd.toml inside the sidecar. Empty means
	// the sidecar uses its image's built-in defaults.
	ConfigPath string

	// RegistryAuthPath is a host file path to a docker registry auth file
	// (config.json format) mounted into the sidecar at /root/.docker/config.json.
	// Buildkit uses this when pulling base images. Push credentials are
	// typically supplied client-side by the job via buildctl.
	RegistryAuthPath string

	// CacheVolume is an optional named docker volume (or k8s PVC name) mounted
	// at buildkit's state dir for cross-job layer cache. Empty means no cache
	// volume — each sidecar starts clean.
	CacheVolume string
}

type CheckoutSpec struct {
	Mode string `json:"mode" yaml:"mode"`
}

type ContainerdRunner struct {
	// contains filtered or unexported fields
}

type DockerRunner struct {
	// contains filtered or unexported fields
}

type InvalidTriggerError struct {
	// contains filtered or unexported fields
}

type JobConfig struct {
	// Container image to use (e.g., "reactorcide/runner:latest")
	Image string

	// Command to execute in the container. The container's entrypoint is
	// cleared, so this is the full command (e.g., ["sh", "-c", "make build"])
	Command []string

	// Environment variables to inject into the container
	Env map[string]string

	// WorkspaceDir is the host directory to mount into the container at /job
	WorkspaceDir string

	// SourceDir is an optional host directory to mount at /job/src in the
	// container. Used by run-local to mount user's source into the standard
	// production layout.
	SourceDir string

	// SourceMountPath is the container path where SourceDir is mounted.
	// Defaults to /job/src when empty.
	SourceMountPath string

	// WorkingDir is the working directory inside the container (default:
	// /job)
	WorkingDir string

	// Capabilities declares what the job needs from the runtime environment.
	// Each runner interprets these appropriately for its environment. See
	// CapabilityDocker, CapabilityGPU constants.
	Capabilities []string

	// ImagePullSecrets lists names of Kubernetes Secrets the job requested
	// for pulling its image. Names only, never values. KubernetesRunner
	// enforces its allowlist and adds approved names to the pod spec's
	// imagePullSecrets; other runners preserve the field and never read a
	// Kubernetes Secret.
	ImagePullSecrets []string

	// RunAsUser optionally overrides the container user ("uid:gid"). When
	// empty, runners default to RunnerUser. Capabilities provision runtime
	// services/privileges but do not implicitly change the job user.
	// run-local sets this to the host uid so bind-mounted sources are
	// writable.
	RunAsUser string

	// ExtraMounts are additional bind mounts in "hostpath:containerpath[:ro]"
	// format. Used by run-local to inject a synthetic /etc/passwd and
	// /etc/group for the host uid so tools like ssh find a valid user entry.
	ExtraMounts []string

	// VCSAuth contains per-job checkout credential files. Docker/containerd
	// jobs read these from WorkspaceDir; Kubernetes jobs materialize them as
	// a short-lived Secret copied into an emptyDir.
	VCSAuth *VCSAuthConfig

	// Timeout for the job execution (0 = no timeout)
	TimeoutSeconds int

	// Resource requests/limits. Values are Kubernetes-style quantity strings
	// (https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/,
	// validated by k8s.io/apimachinery/pkg/api/resource -- see
	// internal/resources.ParseResources): "1", "2", "500m" for CPU; "4Gi",
	// "512Mi" for memory. Memory is limit-only -- there is no MemoryRequest,
	// mirroring the Job model and DB schema (memory is a pure ceiling, not a
	// reservation). CPURequest is advisory for runners that have no native
	// CPU reservation concept (see DockerRunner: mapped to --cpu-shares);
	// KubernetesRunner sets it as a real requests.cpu.
	CPURequest  string // e.g., "1" or "500m"; advisory outside Kubernetes
	CPULimit    string // e.g., "1", "2", or "500m"
	MemoryLimit string // e.g., "512Mi" or "4Gi"

	// Job metadata (for labeling/tagging)
	JobID     string
	QueueName string
}

type JobRunner interface {
	// SpawnJob creates and starts a job container with the specified
	// configuration Returns a unique job ID/handle and any error encountered
	SpawnJob(ctx context.Context, config *JobConfig) (string, error)

	// StreamLogs streams stdout/stderr from a running job container Returns
	// separate readers for stdout and stderr
	StreamLogs(ctx context.Context, jobID string) (stdout io.ReadCloser, stderr io.ReadCloser, err error)

	// WaitForCompletion blocks until the job container exits Returns the exit
	// code and any error encountered
	WaitForCompletion(ctx context.Context, jobID string) (int, error)

	// Stop requests a graceful shutdown of a running job: SIGTERM to the
	// container's PID 1 (giving runnerlib's SIGTERM trap a chance to run
	// PluginPhase.CLEANUP/ON_ERROR and cleanup_vcs_auth), then a forced kill
	// if the container/pod hasn't exited within grace. Stop does not remove
	// the container/pod — callers still call Cleanup afterward
	// (WaitForCompletion unblocking is what tells the caller it's safe to do
	// so).
	//
	// grace == 0 requests immediate forced termination (no SIGTERM wait) —
	// used by the admin "kill" path when it needs an unambiguous immediate
	// stop rather than going through Cleanup directly (e.g. to unblock a
	// stuck WaitForCompletion caller). Cleanup remains the primary "kill"
	// primitive at the caller layer — Stop(grace=0) exists so runner backends
	// have a single, testable primitive for "terminate now".
	//
	// Calling Stop on a container/pod that has already exited or been removed
	// must be a safe no-op (implementations should tolerate "not found" style
	// errors rather than returning them as failures), since the worker's
	// cancel-poll and the container's own natural completion can race.
	Stop(ctx context.Context, jobID string, grace time.Duration) error

	// Cleanup removes the job container and associated resources Should be
	// called after the job completes (success or failure)
	Cleanup(ctx context.Context, jobID string) error

	// SampleResources returns one resource snapshot for a running job. A
	// backend omits unavailable values and returns safe availability reasons.
	SampleResources(ctx context.Context, jobID string, options ResourceSampleOptions) (ResourceSnapshot, error)
}

type JobSpec struct {
	// Name is a human-readable name for the job
	Name string `json:"name" yaml:"name"`

	// Command is the full command to execute. Single-line commands are parsed
	// and split on whitespace. Multiline commands are wrapped with "sh -c" by
	// default (see CommandPrefix).
	Command string `json:"command" yaml:"command"`

	// CommandPrefix overrides the default shell wrapper for multiline
	// commands. Default is "sh -c". Examples: "bash -c", "zsh -c", "/bin/ash
	// -c" Only applies to multiline commands that don't already start with a
	// shell invocation.
	CommandPrefix string `json:"command_prefix" yaml:"command_prefix"`

	// Image is the container image to use (defaults to DefaultRunnerImage)
	Image string `json:"image" yaml:"image"`

	// Environment variables to set in the container Values can contain
	// ${secret:path:key} references that get resolved
	Environment map[string]string `json:"environment" yaml:"environment"`

	// Source defines how to prepare the source code
	Source *SourceSpec `json:"source" yaml:"source"`

	// Checkout selects the runnerlib checkout layout. It is also supported by
	// overlay files. Isolated keeps separate clones. Shared uses one filtered
	// object store for pull-request evaluation.
	Checkout *CheckoutSpec `json:"checkout" yaml:"checkout"`

	// WorkingDir is the working directory inside the container (default: /job)
	WorkingDir string `json:"working_dir" yaml:"working_dir"`

	// CodeDir is where source code is expected inside the job container.
	// run-local mounts local code here; runnerlib checks out remote source
	// here.
	CodeDir string `json:"code_dir" yaml:"code_dir"`

	// JobDir is the directory runnerlib treats as the job working directory.
	// Defaults to CodeDir when empty.
	JobDir string `json:"job_dir" yaml:"job_dir"`

	// Capabilities declares what the job needs from the runtime environment.
	// The runner interprets these based on its environment:
	//   - "docker": Access to build/push container images
	//               DockerRunner: mounts /var/run/docker.sock
	//               KubernetesRunner: uses DinD sidecar or hostPath
	//   - "gpu": Access to GPU resources (future - not yet implemented)
	//            DockerRunner: --gpus all
	//            KubernetesRunner: nvidia.com/gpu resource request
	Capabilities []string `json:"capabilities" yaml:"capabilities"`

	// ImagePullSecrets lists the NAMES of Kubernetes Secrets (type
	// kubernetes.io/dockerconfigjson, in the job namespace) the job pod may
	// use to pull its image. Names only — never credentials. The worker
	// enforces its operator allowlist before Kubernetes Job creation; the
	// Docker/containerd/local runners preserve the field but never read a
	// Kubernetes Secret.
	ImagePullSecrets []string `json:"image_pull_secrets" yaml:"image_pull_secrets"`

	// Timeout in seconds (0 = no timeout)
	TimeoutSeconds int `json:"timeout_seconds" yaml:"timeout_seconds"`

	// Resource limits
	CPULimit    string `json:"cpu_limit" yaml:"cpu_limit"`
	MemoryLimit string `json:"memory_limit" yaml:"memory_limit"`

	// RunAs controls the container user for deployed workers. run-local uses
	// this only as a fallback after run_local and CLI overrides.
	RunAs *RunAsSpec `json:"run_as" yaml:"run_as"`

	// DisableRunLocal marks this job as remote-only. run-local refuses to
	// execute jobs with this set — used for jobs that fundamentally need CI
	// state (PR diff base, push-back-to-remote with a PAT, etc.).
	DisableRunLocal bool `json:"disable_run_local" yaml:"disable_run_local"`

	// RunLocal holds settings that only affect `reactorcide run-local`. The
	// worker ignores this block entirely (ToJobConfig never reads it), so
	// it's the place to pin local-only behavior — e.g. the container uid —
	// without changing how the job runs in CI. Defining it here makes a job
	// behave consistently across local invocations without per-command flags.
	RunLocal *RunLocalSpec `json:"run_local" yaml:"run_local"`

	// Characteristics routes this job to a queue when submitted remotely; raw
	// map, validated by internal/characteristics.ParseJobCharacteristics at
	// submit time. Not consumed by run-local/ToJobConfig -- queue routing
	// only applies to jobs submitted through the coordinator API (see
	// cmd/submit.go).
	Characteristics map[string]interface{} `json:"characteristics" yaml:"characteristics"`

	WorkerClass string `json:"worker_class" yaml:"worker_class"`

	// Resources declares per-job compute resource cpu.request/cpu.limit/
	// memory.limit; raw map, validated by internal/resources.ParseResources
	// at submit time. Not consumed by run-local/ToJobConfig -- see the flat
	// CPULimit/MemoryLimit fields above for that path.
	Resources map[string]interface{} `json:"resources" yaml:"resources"`
}

type KubernetesRunner struct {
	// contains filtered or unexported fields
}

type KubernetesRunnerConfig struct {
	Namespace        string   // Namespace for job pods (default: current namespace)
	ServiceAccount   string   // Service account for job pods (default: "default")
	RunnerImage      string   // Default runner image if job doesn't specify one
	DindImage        string   // Docker-in-Docker sidecar image (default: "docker:27-dind")
	ImagePullSecrets []string // Image pull secrets added to every job pod
	// AllowedJobImagePullSecrets lists Secret names a job may request via
	// image_pull_secrets in addition to ImagePullSecrets above.
	AllowedJobImagePullSecrets []string
	NodeName                   string // Node to schedule job pods on (for workspace sharing via HostPath)
}

type LogEntry struct {
	Timestamp string `json:"timestamp"`
	Stream    string `json:"stream"`
	Level     string `json:"level,omitempty"`
	Message   string `json:"message"`
}

type PodStartupError struct {
	Reason  string
	Message string
}

type ResourceSampleOptions struct {
	IncludeStorage bool
}

type ResourceSnapshot struct {
	ObservedAt  time.Time
	Series      []jobtelemetry.SeriesDefinition
	Values      []jobtelemetry.Value
	Unavailable []jobtelemetry.Unavailable
}

type RetryConfig struct {
	MaxRetries     int           // Maximum number of retry attempts
	InitialDelay   time.Duration // Initial delay between retries
	MaxDelay       time.Duration // Maximum delay between retries
	BackoffFactor  float64       // Exponential backoff factor (e.g., 2.0)
	JitterFraction float64       // Fraction of delay to add as random jitter (0.0-1.0)
}

type RetryableError struct {
	Err       error
	Retryable bool
	Reason    string
}

type RunAsSpec struct {
	// User accepts "runner", "root", or numeric "uid[:gid]". "host" is
	// intentionally run-local-only and is not accepted by deployed workers.
	User string `json:"user" yaml:"user"`
}

type RunLocalSpec struct {
	// AsRunner runs the job container as the image's conventional runner uid
	// (1001:1001), matching the worker, instead of the host uid. This gives
	// sudo and HOME parity for jobs that rely on the image's runner user.
	AsRunner bool `json:"as_runner" yaml:"as_runner"`

	// User pins an explicit uid[:gid] for the job container (e.g.
	// "1001:1001"). Takes precedence over AsRunner when both are set. Empty
	// means unset.
	User string `json:"user" yaml:"user"`
}

type RunnerBackend string

type SecretGrantStore interface {
	ListSecretGrantsForJob(ctx context.Context, userID string, projectID *string, jobName string) ([]models.SecretGrant, error)
}

type SecretOverride struct {
	Key         string
	OldValue    string // The ${secret:...} reference
	NewValue    string // The plaintext value
	OverlayFile string
}

type SecretResolutionResult struct {
	// Resolved contains all environment variables with secrets resolved
	Resolved map[string]string
	// SecretValues contains the actual secret values for masking
	SecretValues []string
	// SecretEnvNames contains the names of env vars that contained secret references
	SecretEnvNames []string
}

type SourceSpec struct {
	Type string `json:"type" yaml:"type"` // git, copy, none
	URL  string `json:"url" yaml:"url"`
	Ref  string `json:"ref" yaml:"ref"`
	Path string `json:"path" yaml:"path"` // for copy type
}

type TriggerProcessingResult struct {
	CreatedJobIDs []string                 `json:"created_job_ids"`
	Workflows     []TriggerWorkflowOutcome `json:"workflows,omitempty"`
}

type TriggerProcessor struct {
	// contains filtered or unexported fields
}

type TriggerWorkflowOutcome struct {
	WorkflowID         string   `json:"workflow_id"`
	WorkflowSecurityID string   `json:"workflow_security_id,omitempty"`
	Name               string   `json:"name"`
	Status             string   `json:"status"`
	Disposition        string   `json:"disposition"`
	Reason             string   `json:"reason,omitempty"`
	CreatedJobIDs      []string `json:"created_job_ids"`
}

type VCSAuthConfig struct {
	ContainerDir string
	GitConfig    string
	Credentials  string
	SecretValues []string
}

type VMConfig struct {
	// ImageSource selects the ImageSource implementation: "local" (default,
	// vmrunner.LocalImageSource) or "oci" (vmrunner.OCIImageSource, pulling
	// base images from an OCI registry).
	ImageSource string

	// ImageDir is the directory relative image references resolve under
	// when ImageSource is "local" (see vmrunner.LocalImageSource).
	ImageDir string

	// OCIImageCacheDir is the local content-addressed cache directory
	// vmrunner.OCIImageSource pulls base images into when ImageSource is
	// "oci" (see vmrunner.NewOCIImageSource).
	OCIImageCacheDir string

	// OCIRegistryAuthFile is a Docker-compatible credential file. One file can
	// hold credentials for several registry hosts.
	OCIRegistryAuthFile string

	// OCIPlainHTTPRegistries lists registry hosts (as they appear in an
	// image reference, e.g. "registry.internal:5000") to reach over plain
	// HTTP instead of HTTPS when ImageSource is "oci". Each host must come
	// from an explicit command-line option.
	OCIPlainHTTPRegistries []string

	// SSHUser is the guest OS account SSHTransport authenticates as.
	SSHUser string

	// SSHPassword authenticates via SSH password auth when set.
	SSHPassword string

	// SSHPrivateKeyPEM authenticates via SSH public-key auth when set,
	// taking precedence over SSHPassword. Loaded from the file at
	// REACTORCIDE_VM_SSH_PRIVATE_KEY_FILE, never itself taken directly from
	// an env var so its contents can't leak into a printed environment.
	SSHPrivateKeyPEM []byte

	// SSHHostPublicKey pins the guest SSH server key when configured.
	SSHHostPublicKey []byte

	MetricsDir      string
	MetricsInterval time.Duration
}

type VMImageCacheManager interface {
	PrefetchImages(ctx context.Context, imageRefs []string) error
	PruneImages(ctx context.Context, maxUnused time.Duration, now time.Time) (int, error)
}

type WorkflowOutputReader interface {
	TakeWorkflowOutput(jobID string) (string, bool)
}