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.
Types ¶
type Dependencies ¶
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.
func (*Preparer) Prepare ¶
Prepare resolves req's source (Git repository or OCI artifact) into a ready-to-deploy local checkout: it normalizes/validates the source type, computes safe internal/external filesystem paths, clones/updates the Git repository (or resolves/verifies/pulls the OCI artifact), resolves the webhook/poll deployment configuration, applies the OCI reference override and custom target propagation, and returns the result.
On a Git clone or deploy-configuration resolution failure, Prepare also reports the failure as an early commit status (before reconciliation ever starts), mirroring the pre-refactor handler's behavior.
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
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 (used only for poll-triggered requests), 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)
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
}
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