Documentation
¶
Index ¶
- Constants
- Variables
- func GetStackServices(ctx context.Context, dockerCLI command.Cli, stack string) ([]dockerswarmtypes.Service, error)
- func IsLifecycleCancellation(err error) bool
- func NormalizeRunStatus(value string) (string, error)
- func NormalizeRunTrigger(value string) (string, error)
- func RemoveStack(ctx context.Context, dockerCLI command.Cli, stack string, log *slog.Logger) error
- type Dependencies
- type Deployment
- type DeploymentDependencies
- type DeploymentError
- type DeploymentRequest
- type DestroyProjectResult
- type DockerContextResolver
- type PollConfigValidationError
- type PollDependencies
- type PollRunner
- type PollRunsFailedError
- type ProjectAction
- type ProjectActionResult
- type ProjectLookupError
- type Reconciler
- type Run
- type RunExecution
- type RunFunc
- type RunMetadata
- type RunMode
- type RunResult
- type RunStatus
- type RunTarget
- type RunTrigger
- type Runs
- func (c *Runs) Accept(jobID string, trigger RunTrigger, metadata RunMetadata) string
- func (c *Runs) AddDeployment(jobID, stack, contextName string)
- func (c *Runs) CloseAndWait()
- func (c *Runs) DeploymentTargetObserver(jobID string) func(string, string)
- func (c *Runs) Execute(requestCtx context.Context, jobID string, execution RunExecution, run RunFunc) error
- func (c *Runs) Get(jobID string) (Run, bool)
- func (c *Runs) List(limit int, trigger, status string) []Run
- func (c *Runs) ListScheduledJobs(ctx context.Context, contextName, stackName string) ([]scheduler.JobInfo, error)
- func (c *Runs) MarkFailed(jobID, message string)
- func (c *Runs) MarkRunning(jobID string)
- func (c *Runs) MarkSkipped(jobID, message string)
- func (c *Runs) RunConfiguredPoll(ctx context.Context, pollConfig poll.Config, log *slog.Logger, ...) (string, error)
- func (c *Runs) SetMetadata(jobID string, metadata RunMetadata)
- func (c *Runs) TriggerPoll(ctx context.Context, configs []poll.Config, wait bool, jobLog *slog.Logger) (string, error)
- func (c *Runs) TriggerScheduledJob(ctx context.Context, jobID string, contextName string, jobName string, ...) (string, error)
- type ScheduledJobOperations
- type SourcePreparer
- type StackActionResult
- type StackServiceActionError
- type StackServiceNotFoundError
Constants ¶
const ( // DefaultProjectActionTimeout is the default timeout, in seconds, for project actions. DefaultProjectActionTimeout = 30 // MaxProjectActionTimeout is the largest whole-second timeout representable as time.Duration. MaxProjectActionTimeout = math.MaxInt64 / int64(time.Second) )
const (
// MaxTriggerPollConfigs limits the number of poll configurations accepted per request.
MaxTriggerPollConfigs = 32
)
Variables ¶
var ( // ErrNoPollConfiguration indicates an empty poll-trigger request. ErrNoPollConfiguration = errors.New("no poll configuration provided in request body") // ErrTooManyPollConfigurations indicates that a request exceeds MaxTriggerPollConfigs. ErrTooManyPollConfigurations = errors.New("too many poll configurations: maximum is 32") // ErrPollRunPanicked is recorded when a poll callback panics. ErrPollRunPanicked = errors.New("poll run panicked") )
var ( // ErrProjectNotFound indicates that no containers belong to the requested project. ErrProjectNotFound = errors.New("project not found") // ErrInvalidProjectTimeout indicates a timeout outside the supported duration range. ErrInvalidProjectTimeout = errors.New("invalid project timeout") )
var ( // ErrStackNotFound indicates that the requested stack has no services. ErrStackNotFound = errors.New("stack not found") // ErrNoApplicableStackServices indicates that all matched services were skipped. ErrNoApplicableStackServices = errors.New("no applicable services found") )
var ( // ErrInvalidRunStatus indicates an unsupported run status filter. ErrInvalidRunStatus = errors.New("invalid deployment run status") // ErrInvalidRunTrigger indicates an unsupported run trigger filter. ErrInvalidRunTrigger = errors.New("invalid deployment run trigger") )
var ErrBackgroundWorkClosed = errors.New("application is shutting down")
ErrBackgroundWorkClosed indicates that shutdown has stopped accepting work.
var ErrScheduledJobRunPanicked = errors.New("scheduled job run panicked")
ErrScheduledJobRunPanicked is recorded when a scheduled-job callback panics.
Functions ¶
func GetStackServices ¶
func GetStackServices(ctx context.Context, dockerCLI command.Cli, stack string) ([]dockerswarmtypes.Service, error)
GetStackServices returns the services belonging to a named Swarm stack.
func IsLifecycleCancellation ¶
IsLifecycleCancellation reports whether err represents context cancellation or timeout.
func NormalizeRunStatus ¶
NormalizeRunStatus validates and canonicalizes a run status filter.
func NormalizeRunTrigger ¶
NormalizeRunTrigger validates and canonicalizes a run trigger filter.
Types ¶
type Dependencies ¶
type Dependencies struct {
MaxRunsPerTrigger map[RunTrigger]int `validate:"omitempty,dive,keys,oneof=webhook poll scheduled_job,endkeys,min=1"`
ScheduledJobs ScheduledJobOperations `validate:"required,nostructlevel"`
SecretProvider secretprovider.SecretProvider
Poll PollDependencies
}
Dependencies contains the operations and limits used by the run coordinator.
type Deployment ¶
type Deployment struct {
// contains filtered or unexported fields
}
Deployment is the protocol-neutral deployment operation shared by the webhook and poll transports.
func NewDeployment ¶
func NewDeployment(dependencies DeploymentDependencies) (*Deployment, error)
NewDeployment validates dependencies and creates a Deployment operation.
func (*Deployment) Deploy ¶
func (d *Deployment) Deploy(ctx context.Context, req DeploymentRequest) error
Deploy runs a single protocol-neutral deployment: it validates req, prepares the source, adapts the result into a reconciliation.DeployRequest (notifying the deployment target observer for each resolved deploy config), and runs the reconciliation.
Errors are returned as DeploymentError so callers can preserve the exact HTTP status/message mapping the pre-refactor handler used. A For webhook requests, stages.ErrSkipDeployment from the reconciler is returned unwrapped so callers can report a skipped (not failed) deployment.
type DeploymentDependencies ¶
type DeploymentDependencies struct {
SourcePreparer SourcePreparer `validate:"required"`
Reconciler Reconciler `validate:"required"`
Contexts DockerContextResolver `validate:"required"`
DataMountPoint container.MountPoint `validate:"required"`
}
DeploymentDependencies configures the source preparer, reconciler, and data mount point used by the protocol-neutral deployment operation.
type DeploymentError ¶
DeploymentError pairs a Deployment.Deploy failure with the HTTP status code transport layers (the webhook/poll handlers) should use to report it, preserving the exact message/status mapping the pre-refactor handler used.
func (DeploymentError) Error ¶
func (e DeploymentError) Error() string
func (DeploymentError) Unwrap ¶
func (e DeploymentError) Unwrap() []error
type DeploymentRequest ¶
type DeploymentRequest struct {
Logger *slog.Logger `validate:"required,nostructlevel"`
JobTrigger stages.JobTrigger `validate:"required,oneof=webhook poll"`
SourceType config.SourceType
SourceRef string `validate:"required"`
Ref string
Private bool
Metadata notification.Metadata
CustomTarget string
TestName string
PollConfig poll.Config
Payload webhook.ParsedPayload
}
DeploymentRequest bundles Deployment.Deploy's per-call, per-deployment-request input: the source location and its trigger/reference/visibility, notification metadata, an optional custom deploy target, an optional test identity, poll configuration (used only for poll-triggered requests), and the parsed webhook payload (zero value for non-webhook triggers).
type DestroyProjectResult ¶
DestroyProjectResult describes a successful project removal.
type DockerContextResolver ¶
type DockerContextResolver interface {
Get(ctx context.Context, name string) (docker.ContextClient, error)
}
DockerContextResolver is the capability-aware Docker context surface used by Deployment.
type PollConfigValidationError ¶
PollConfigValidationError identifies a malformed poll configuration by request index.
func (*PollConfigValidationError) Error ¶
func (e *PollConfigValidationError) Error() string
Error identifies the invalid poll configuration by request index.
func (*PollConfigValidationError) Unwrap ¶
func (e *PollConfigValidationError) Unwrap() error
Unwrap exposes the underlying poll configuration validation error.
type PollDependencies ¶
type PollDependencies struct {
AppConfig *app.Config `validate:"required,nostructlevel"`
DataMountPoint container.MountPoint
DockerCLI command.Cli
Contexts *docker.ContextRegistry
Runner PollRunner `validate:"required"`
}
PollDependencies contains the services required to execute poll configurations.
type PollRunner ¶
type PollRunner func(ctx context.Context, pollConfig poll.Config, appConfig *app.Config, dataMountPoint container.MountPoint, dockerCli command.Cli, contexts *docker.ContextRegistry, logger *slog.Logger, metadata notification.Metadata, secretProvider secretprovider.SecretProvider, triggerReason string, ) error
PollRunner executes one validated poll configuration with application dependencies.
type PollRunsFailedError ¶
PollRunsFailedError summarizes failures from a batch of poll configurations.
func (*PollRunsFailedError) Error ¶
func (e *PollRunsFailedError) Error() string
Error reports the number of failed poll runs.
func (*PollRunsFailedError) Unwrap ¶
func (e *PollRunsFailedError) Unwrap() error
Unwrap exposes the first poll-run failure.
type ProjectAction ¶
type ProjectAction struct {
// contains filtered or unexported fields
}
ProjectAction is a validated project operation ready to execute.
func ResolveProjectAction ¶
func ResolveProjectAction(ctx context.Context, dockerCLI command.Cli, projectName, action string) (ProjectAction, error)
ResolveProjectAction validates a project and prepares its requested lifecycle action.
type ProjectActionResult ¶
ProjectActionResult describes a successful project lifecycle action.
func ExecuteProjectAction ¶
func ExecuteProjectAction(ctx context.Context, operation ProjectAction, timeoutSeconds int, log *slog.Logger) (ProjectActionResult, error)
ExecuteProjectAction runs a previously resolved project action with a validated timeout.
type ProjectLookupError ¶
type ProjectLookupError struct {
// contains filtered or unexported fields
}
ProjectLookupError wraps a Docker lookup failure with the requested project name.
func (*ProjectLookupError) Error ¶
func (e *ProjectLookupError) Error() string
Error reports the project lookup failure.
func (*ProjectLookupError) Unwrap ¶
func (e *ProjectLookupError) Unwrap() error
Unwrap exposes the underlying Docker lookup error.
type Reconciler ¶
type Reconciler interface {
Deploy(ctx context.Context, req reconciliation.DeployRequest) error
}
Reconciler is the minimal reconciliation surface the Deployment operation depends on. Satisfied by *reconciliation.Manager.
type Run ¶
type Run struct {
JobID string `json:"job_id"`
Trigger RunTrigger `json:"trigger"`
Status RunStatus `json:"status"`
Repository string `json:"repository,omitempty"`
Target string `json:"target,omitempty"`
Revision string `json:"revision,omitempty"`
Deployments []RunTarget `json:"deployments,omitempty"`
Message string `json:"message,omitempty"`
CreatedAt time.Time `json:"created_at"`
StartedAt *time.Time `json:"started_at,omitempty"`
FinishedAt *time.Time `json:"finished_at,omitempty"`
UpdatedAt time.Time `json:"updated_at"`
}
Run is the serializable lifecycle record for one control-plane operation.
type RunExecution ¶
RunExecution configures lifecycle behavior and panic reporting for one run.
type RunMetadata ¶
RunMetadata describes the source and deployment target recorded for a run.
type RunMode ¶
type RunMode uint8
RunMode controls whether a run blocks its caller and whether request cancellation propagates.
const ( // RunSynchronous runs inline and stops when either the request or application is cancelled. RunSynchronous RunMode = iota // RunSynchronousDetached runs inline but ignores request cancellation. RunSynchronousDetached // RunAsynchronous runs in the background under the application lifecycle. RunAsynchronous )
type RunResult ¶
RunResult describes the terminal status and optional message produced by a run.
func SkippedRun ¶
SkippedRun creates a skipped terminal result.
func SucceededRun ¶
SucceededRun creates a successful terminal result.
type RunStatus ¶
type RunStatus string
RunStatus is the lifecycle state recorded for a control-plane run.
const ( // RunStatusAccepted indicates that a run has been admitted but not started. RunStatusAccepted RunStatus = "accepted" // RunStatusRunning indicates that a run is executing. RunStatusRunning RunStatus = "running" // RunStatusSucceeded indicates that a run completed successfully. RunStatusSucceeded RunStatus = "succeeded" // RunStatusFailed indicates that a run completed with an error. RunStatusFailed RunStatus = "failed" // RunStatusSkipped indicates that a run intentionally performed no work. RunStatusSkipped RunStatus = "skipped" )
type RunTrigger ¶
type RunTrigger string
RunTrigger identifies the entry point that created a control-plane run.
const ( // RunTriggerWebhook identifies runs accepted from webhook requests. RunTriggerWebhook RunTrigger = "webhook" // RunTriggerPoll identifies runs accepted from poll operations. RunTriggerPoll RunTrigger = "poll" // RunTriggerScheduledJob identifies runs accepted from scheduled-job requests. RunTriggerScheduledJob RunTrigger = "scheduled_job" )
type Runs ¶
type Runs struct {
// contains filtered or unexported fields
}
Runs coordinates control-plane run admission and lifecycle while delegating storage and draining to their focused components.
func (*Runs) Accept ¶
func (c *Runs) Accept(jobID string, trigger RunTrigger, metadata RunMetadata) string
Accept records a run in accepted state, generating a job ID when needed.
func (*Runs) AddDeployment ¶
AddDeployment records a stack and Docker context observed during a run.
func (*Runs) CloseAndWait ¶
func (c *Runs) CloseAndWait()
CloseAndWait rejects new work, cancels active runs, and waits for them to finish.
func (*Runs) DeploymentTargetObserver ¶
DeploymentTargetObserver returns a callback that records deployments for jobID.
func (*Runs) Execute ¶
func (c *Runs) Execute( requestCtx context.Context, jobID string, execution RunExecution, run RunFunc, ) error
Execute runs accepted work in the configured lifecycle mode.
func (*Runs) ListScheduledJobs ¶
func (c *Runs) ListScheduledJobs(ctx context.Context, contextName, stackName string) ([]scheduler.JobInfo, error)
ListScheduledJobs returns scheduled jobs for an optional Docker context and stack.
func (*Runs) MarkFailed ¶
MarkFailed transitions a tracked run to failed with a message.
func (*Runs) MarkRunning ¶
MarkRunning transitions a tracked run to running.
func (*Runs) MarkSkipped ¶
MarkSkipped transitions a tracked run to skipped with a message.
func (*Runs) RunConfiguredPoll ¶
func (c *Runs) RunConfiguredPoll( ctx context.Context, pollConfig poll.Config, log *slog.Logger, triggerReason string, ) (string, error)
RunConfiguredPoll executes one prevalidated scheduled poll under the shared lifecycle.
func (*Runs) SetMetadata ¶
func (c *Runs) SetMetadata(jobID string, metadata RunMetadata)
SetMetadata updates source and target metadata for a tracked run.
type ScheduledJobOperations ¶
type ScheduledJobOperations interface {
ListJobs(context.Context, string, string) ([]scheduler.JobInfo, error)
TriggerNow(context.Context, string, string, string, secretprovider.SecretProvider) (string, error)
}
ScheduledJobOperations is the scheduler surface required by the control plane.
type SourcePreparer ¶
type SourcePreparer interface {
Prepare(ctx context.Context, req source.Request) (source.Result, error)
}
SourcePreparer is the minimal source-preparation surface the Deployment operation depends on: resolving a deployment's source (Git repository or OCI artifact) into a ready-to-deploy local checkout. Satisfied by *source.Preparer.
type StackActionResult ¶
type StackActionResult struct {
Service string `json:"service"`
Status string `json:"status"`
Reason string `json:"reason,omitempty"`
}
StackActionResult reports the outcome for one service targeted by a stack action.
func RunStackAction ¶
func RunStackAction( ctx context.Context, dockerCLI command.Cli, stack string, action string, service string, replicas int, wait bool, log *slog.Logger, ) ([]StackActionResult, error)
RunStackAction resolves a stack and applies an action to its matching services.
func RunStackActionOnServices ¶
func RunStackActionOnServices( ctx context.Context, dockerCLI command.Cli, services []dockerswarmtypes.Service, stack string, action string, service string, replicas int, wait bool, log *slog.Logger, ) ([]StackActionResult, error)
RunStackActionOnServices applies an action and preserves partial results on failure.
type StackServiceActionError ¶
StackServiceActionError wraps an operational failure with its service name.
func (*StackServiceActionError) Error ¶
func (e *StackServiceActionError) Error() string
Error reports the failed service action.
func (*StackServiceActionError) Unwrap ¶
func (e *StackServiceActionError) Unwrap() error
Unwrap exposes the underlying service action error.
type StackServiceNotFoundError ¶
type StackServiceNotFoundError struct {
Service string
}
StackServiceNotFoundError identifies a requested service absent from its stack.
func (*StackServiceNotFoundError) Error ¶
func (e *StackServiceNotFoundError) Error() string
Error reports the missing service.