Documentation
¶
Overview ¶
Package source resolves a deployment's source, either a Git repository or an OCI artifact, into a ready-to-deploy local checkout.
It owns:
- source type normalization/validation
- repository/artifact naming and safe internal/external filesystem paths
- Git clone/update, including the HeadMatchesCommit fast path that skips the network fetch when the local checkout already matches the requested commit, and resolving the immutable revision (commit SHA)
- OCI digest resolution, cosign signature verification, pull/extract, and webhook payload enrichment
- webhook/poll deployment configuration resolution, OCI reference override, and custom target propagation
It intentionally does not depend on internal/controlplane or internal/reconciliation: callers adapt Result into their own deployment request types.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrPrepare indicates an unclassified source preparation failure. ErrPrepare = errors.New("failed to prepare source") // ErrInvalidRequest indicates the Request itself failed validation. ErrInvalidRequest = errors.New("invalid deployment request") // ErrInvalidSourceType indicates an unsupported/invalid SourceType. ErrInvalidSourceType = errors.New("invalid source type") // ErrInvalidRepositoryName indicates a repository/artifact name that is unsafe to use as a path component. ErrInvalidRepositoryName = errors.New("invalid repository name") // ErrInvalidInternalPath indicates the computed internal (in-container) filesystem path escaped the data mount point. ErrInvalidInternalPath = errors.New("failed to verify and sanitize internal filesystem path") // ErrInvalidExternalPath indicates the computed external (host) filesystem path escaped the data mount point. ErrInvalidExternalPath = errors.New("failed to verify and sanitize external filesystem path") // ErrGitClone indicates a Git clone/update failure. ErrGitClone = errors.New("failed to clone repository") // ErrOCIResolveDigest indicates an OCI digest resolution failure. ErrOCIResolveDigest = errors.New("failed to resolve oci artifact digest") // ErrOCIVerify indicates an OCI cosign signature verification failure. ErrOCIVerify = errors.New("failed OCI signature verification") // ErrOCIPull indicates an OCI artifact pull/extract failure. ErrOCIPull = errors.New("failed to pull oci artifact") // ErrDeployConfig indicates a webhook/poll deployment configuration resolution failure. ErrDeployConfig = errors.New("failed to get deploy configuration") // ErrUnsupportedJobTrigger indicates an unrecognized JobTrigger. ErrUnsupportedJobTrigger = errors.New("unsupported job trigger") )
Sentinel errors classify Prepare failures so callers can map them to the right transport response (e.g. an HTTP status code) without string matching. Errors returned by Prepare wrap these sentinels via wrapPrepareError so errors.Is finds both the sentinel and the underlying detail error, while Error() returns only the detail error's message - matching the pre-refactor handler's HTTP response bodies exactly.
Functions ¶
func EntityLabel ¶
func EntityLabel(sourceType config.SourceType) string
EntityLabel returns the log-friendly entity name for sourceType: "artifact" for OCI sources, "repository" otherwise.
func IsInFlight ¶ added in v0.120.0
IsInFlight reports whether revision of repoName is currently marked in-flight by an unreleased MarkInFlight call.
func MarkInFlight ¶ added in v0.120.0
func MarkInFlight(repoName, revision string) func()
MarkInFlight records that revision of repoName is in active use by a Prepare-to-deploy call and returns a function that releases that record. Calls are reference-counted: the same repository/revision pair can be marked in flight by more than one concurrent call at once, and the record is only fully released once every marker has been released.
Callers must defer the returned function immediately, starting right after Prepare succeeds and lasting until the deployment it fed either finishes or fails - the entire span during which a garbage collector could otherwise mistake the freshly published artifact for an unreferenced one.
If repoName or revision is empty, MarkInFlight is a no-op and returns a no-op release function.
Types ¶
type Dependencies ¶
type Dependencies struct {
AppConfig *app.Config `validate:"required,nostructlevel"`
// Contexts resolves configured Docker contexts so Prepare can safely finish migrating a
// legacy Git checkout it finds still un-migrated (see prepareGit). Optional: if nil, Prepare
// skips that on-demand migration attempt and behaves as if the repository were never a
// legacy checkout, which is always correct for a store that has no on-disk data yet.
Contexts *docker.ContextRegistry
}
Dependencies holds the stable services shared by every Preparer.Prepare call.
type Preparer ¶
type Preparer struct {
// contains filtered or unexported fields
}
Preparer resolves sources (Git repositories or OCI artifacts) into a ready-to-deploy local checkout. See the package doc for its responsibilities.
func NewPreparer ¶
func NewPreparer(dependencies Dependencies) (*Preparer, error)
NewPreparer validates dependencies and creates a Preparer.
type Request ¶
type Request 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
CustomTarget string
PollConfig poll.Config
Deployments []*deploy.Config
Payload webhook.ParsedPayload
DataMountPoint container.MountPoint `validate:"required"`
}
Request holds the per-call input for Preparer.Prepare: the source location and its trigger/reference/visibility, an optional custom deploy target, poll configuration, optional centrally supplied deployments, the parsed webhook payload (zero value for non-webhook triggers), and the data mount point used to compute safe internal/external filesystem paths.
type Result ¶
type Result struct {
SourceType config.SourceType // Source backend used for this deployment (git or oci)
RepoName string // Repository/artifact name (e.g., "user/my-repo")
PathInternal string // Path to the repository/artifact inside the container
PathExternal string // Path to the repository/artifact on the host machine
Revision string // Resolved immutable revision (commit SHA or OCI digest)
MirrorDir string // Path of Git's bare mirror clone backing this result; empty for OCI sources
OCITrusted bool // True when the OCI artifact passed trust-policy verification (always true for Git)
DeployConfigs []*deploy.Config // Resolved deployment configurations for this run
Payload webhook.ParsedPayload
// contains filtered or unexported fields
}
Result is the outcome of a successful Preparer.Prepare call: the resolved source identity/paths/revision, the resolved deploy configurations (with custom target propagation and, for OCI, reference override already applied), and the payload (enriched for OCI sources; passed through unchanged for Git sources).
Source Files
Directories