warmstart

func AsOSPermission ¶

func AsOSPermission(err error) bool

AsOSPermission checks if the error chain contains a permission error.

func CloneWithFallback ¶

func CloneWithFallback(
	repoURL string,
	gitDir string,
	fetchWarmstart func() ([]byte, error),
	coldClone func(url string, dir string) error,
) error

CloneWithFallback attempts warmstart incremental fetch, falling back to cold clone on error.

This function demonstrates the recommended pattern for integrating warmstart with fallback to full git clone. It handles all warmstart error types appropriately:

- Truncated, MissingMember, CorruptPack: Fall back to cold clone - IO with permission/disk errors: Fail immediately (local infrastructure issue) - IO with network errors: Fall back to cold clone - Other with NotAGitRepo: Fail immediately (invalid target directory) - Other unknown errors: Fall back to cold clone for robustness

Parameters:

• repoURL: Git repository URL (e.g., "https://github.com/user/repo")
• gitDir: Target directory for git repository (must be empty or non-existent)
• fetchWarmstart: Function to fetch warmstart artifact from storage
• coldClone: Function to perform full git clone

Returns:

• error: nil on success, error if both warmstart and cold clone fail

Example usage:

err := CloneWithFallback(repoURL, gitDir,
	func() ([]byte, error) { return fetchFromARMOR(repoURL) },
	func(url, dir string) error { return execGitClone(url, dir) })
if err != nil {
	log.Fatalf("Clone failed: %v", err)
}

func CloneWithFallbackAndMetrics ¶

func CloneWithFallbackAndMetrics(
	repoURL string,
	gitDir string,
	correlationID string,
	fetchWarmstart func() ([]byte, error),
	coldClone func(url string, dir string) error,
	metrics MetricEmitter,
) error

CloneWithFallbackAndMetrics is a production-ready version that includes metrics and observability.

This extends CloneWithFallback with: - Structured logging with correlation IDs - Metrics emission for monitoring - Detailed error context propagation

See docs/runbooks/warmstart-error-handling.md for recommended metrics.

func CollectMissingIdxFiles ¶

func CollectMissingIdxFiles(members []TarballMember) []string

CollectMissingIdxFiles collects all missing .idx files across all pack files. It iterates over each pack file in the members list, checks if the corresponding .idx file exists, and collects the names of missing .idx files.

Parameters:

• members: Slice of TarballMember representing files in the tarball

Returns:

• []string: List of missing .idx file names (empty if all present)

Example:

members := []TarballMember{
    {Name: "objects/pack/pack-abc.pack", Data: ...},
    {Name: "objects/pack/pack-def.pack", Data: ...},
    {Name: "objects/pack/pack-abc.idx", Data: ...},
}
missing := CollectMissingIdxFiles(members) // returns ["objects/pack/pack-def.idx"]

func CollectMissingRefFiles ¶

func CollectMissingRefFiles(members []TarballMember) []string

CollectMissingRefFiles collects all missing .ref files across all pack files. It iterates over each pack file in the members list, checks if the corresponding .ref file exists, and collects the names of missing .ref files.

Parameters:

• members: Slice of TarballMember representing files in the tarball

Returns:

• []string: List of missing .ref file names (empty if all present)

Example:

members := []TarballMember{
    {Name: "objects/pack/pack-abc.pack", Data: ...},
    {Name: "objects/pack/pack-def.pack", Data: ...},
    {Name: "objects/pack/pack-abc.ref", Data: ...},
}
missing := CollectMissingRefFiles(members) // returns ["objects/pack/pack-def.ref"]

func ComputeSHA256 ¶

func ComputeSHA256(data []byte) string

ComputeSHA256 computes the SHA256 hash of data and returns the hex-encoded string. This is a test helper function for byte-for-byte verification tests.

func ExtractWarmStart ¶

func ExtractWarmStart(tarballPath, targetDir string, commitSHAs ...string) (returnErr error)

ExtractWarmStart extracts a warm-start tarball to a target directory.

This function combines git directory initialization, tarball reading, parsing, and materialization into a single operation. It creates a minimal empty git directory structure at targetDir, then extracts and materializes the warm-start snapshot from the tarball file at tarballPath.

Parameters:

• tarballPath: Path to the warm-start tarball file on disk
• targetDir: Path where the git directory should be created/initialized

Returns:

• error: nil if extraction succeeds, error otherwise

Error types returned:

• *Error with Kind=IO: file I/O errors (reading tarball, creating directories)
• *Error with Kind=Truncated: tarball is truncated or corrupted
• *Error with Kind=MissingMember: required tarball members are missing
• ErrInvalidTarball: tarball format is invalid
• ErrMissingConfig, ErrMissingRef, ErrMissingPackFiles: validation failures

Example:

if err := ExtractWarmStart("/path/to/snapshot.tar", "/path/to/repo.git"); err != nil {
    return fmt.Errorf("warm-start extraction failed: %w", err)
}

No network access: This function performs only local filesystem operations. It does not make any HTTP requests or network calls.

func IdxFileExistsInTarball ¶

func IdxFileExistsInTarball(packFilename string, members []TarballMember) bool

IdxFileExistsInTarball checks if a .idx file exists in the tarball for a given .pack file. It uses IdxFilenameFromPackFilename to construct the expected .idx filename and searches the provided member list for a matching file.

Parameters:

• packFilename: The .pack file name (e.g., "objects/pack/pack-abc123.pack")
• members: Slice of TarballMember representing files in the tarball

Returns:

• true if the corresponding .idx file is found in the member list, false otherwise

Example:

packFile := "objects/pack/pack-abc123.pack"
members := []TarballMember{{Name: "objects/pack/pack-abc123.idx", Data: ...}}
found := IdxFileExistsInTarball(packFile, members) // returns true

func IdxFilenameFromPackFilename ¶

func IdxFilenameFromPackFilename(packFilename string) string

IdxFilenameFromPackFilename constructs the expected .idx filename from a .pack filename. It strips the .pack extension and appends .idx. For example: "pack-abc123.pack" becomes "pack-abc123.idx" Edge cases handled:

• No .pack extension: appends .idx to the input as-is
• Multiple dots: only the final .pack extension is stripped

func IsOsPermissionError ¶

func IsOsPermissionError(err error) bool

IsOsPermissionError checks if an error is an OS permission error.

func Materialize ¶

func Materialize(gitDir string, snapshot *WarmStartSnapshot, commitSHAs ...string) (returnErr error)

Materialize writes the warm-start snapshot to a git directory.

The target directory must be an empty git repository (initialized with `git init --bare` or `git init`). After materialization, the repository will be ready for incremental fetch via `git fetch origin`.

Validation approach: Ref and pack file validation is performed upstream in ParseTarball, not here. By the time Materialize is called, the snapshot has already been validated to ensure all required companion files (.idx, .ref) exist for each .pack file. This separation of concerns allows ParseTarball to fail fast on corrupted input before any filesystem writes occur.

This function focuses solely on idempotent filesystem operations: writing pack files to objects/pack/, creating ref directories, and writing the ref file and git config values. It assumes the snapshot is well-formed.

func RefFileExistsInTarball ¶

func RefFileExistsInTarball(packFilename string, members []TarballMember) bool

RefFileExistsInTarball checks if a .ref file exists in the tarball for a given .pack file. It uses RefFilenameFromPackFilename to construct the expected .ref filename and searches the provided member list for a matching file.

Parameters:

• packFilename: The .pack file name (e.g., "objects/pack/pack-abc123.pack")
• members: Slice of TarballMember representing files in the tarball

Returns:

• true if the corresponding .ref file is found in the member list, false otherwise

Example:

packFile := "objects/pack/pack-abc123.pack"
members := []TarballMember{{Name: "objects/pack/pack-abc123.ref", Data: ...}}
found := RefFileExistsInTarball(packFile, members) // returns true

func RefFilenameFromPackFilename ¶

func RefFilenameFromPackFilename(packFilename string) string

RefFilenameFromPackFilename constructs the expected .ref filename from a .pack filename. It strips the .pack extension and appends .ref. For example: "pack-abc123.pack" becomes "pack-abc123.ref" Edge cases handled:

• No .pack extension: appends .ref to the input as-is
• Multiple dots: only the final .pack extension is stripped
• Double extensions: "pack-abc123.pack.promisor" would become "pack-abc123.pack.promisor.ref"

func RunSanityChecks ¶

func RunSanityChecks(gitDir string, commitSHAs ...string) (returnErr error)

RunSanityChecks runs both git fsck and git log verification on a materialized directory.

This is a convenience function that runs both sanity checks in sequence. It ensures the repository is fully functional after materialization.

Parameters:

• gitDir: Path to the git directory (e.g., "/path/to/repo.git")

Returns:

• error: nil if all checks pass, first error encountered if any check fails

Example:

if err := Materialize(gitDir, snapshot); err != nil {
    return err
}
if err := RunSanityChecks(gitDir); err != nil {
    return fmt.Errorf("sanity checks failed: %w", err)
}

func SetLogger ¶

func SetLogger(logger *Logger)

SetLogger replaces the default package-level logger with a custom implementation. This allows callers to configure custom logging destinations or disable logging entirely.

func ShouldFallbackToColdClone ¶

func ShouldFallbackToColdClone(err error) (fallback bool, fatalErr error)

ShouldFallbackToColdClone evaluates whether a warmstart error should trigger fallback to cold clone.

This function implements the error handling logic from docs/runbooks/warmstart-error-handling.md. It distinguishes between:

1. Fallback-appropriate errors: Truncated, MissingMember, CorruptPack, most IO and Other errors 2. Fatal errors: Permission errors, disk space errors, NotAGitRepo (should NOT fall back)

Parameters:

• err: Error from ParseTarball or Materialize

Returns:

• fallback: true if caller should fall back to cold clone
• fatalErr: non-nil if error is fatal (do NOT fall back, fail the job)

Error handling rules:

Fallback to cold clone (fallback=true, fatalErr=nil): - Truncated: Artifact is corrupt, unusable - MissingMember: Artifact is incomplete - CorruptPack: Pack data is corrupted - IO (network): Temporary I/O failure - IO (unknown): Other I/O issues - Other (unknown): Unexpected errors

Fail immediately, do NOT fall back (fallback=false, fatalErr=err): - IO (permission): Local infrastructure issue, cold clone will also fail - IO (disk space): Disk full, cold clone will also fail - Other (NotAGitRepo): Invalid target directory

func UnwrapError ¶

func UnwrapError(err error) error

UnwrapError recursively unwraps errors to find underlying causes.

func ValidateRefFiles ¶

func ValidateRefFiles(packFiles []string) []string

ValidateRefFiles validates .ref file existence for a given list of .pack files. For each .pack file, it constructs the expected .ref filename and checks if it exists on the filesystem using os.Stat.

Parameters:

• packFiles: List of .pack file paths (e.g., []string{"objects/pack/pack-abc123.pack"})

Returns:

• []string: List of missing .ref file names (empty if all present)

Edge cases handled:

• Empty input: returns empty slice
• Duplicate pack names: each is checked independently (duplicate .ref entries possible)
• Files with non-.pack extensions: still processed (constructs .ref by appending if no .pack suffix)
• Filesystem errors: treats non-existence as missing; other errors are ignored

Example:

packFiles := []string{"objects/pack/pack-abc.pack", "objects/pack/pack-def.pack"}
// If only pack-abc.ref exists on filesystem:
missing := ValidateRefFiles(packFiles) // returns ["objects/pack/pack-def.ref"]

func ValidateRefPath ¶

func ValidateRefPath(path string) error

ValidateRefPath validates a git ref path according to git ref naming rules.

Git ref naming rules (from git-check-ref-format(1)): - Ref names can contain slash (/) for hierarchical naming - Ref name components must not begin with a dot (.) - Ref name components must not contain consecutive dots (..) - Ref names must not contain null bytes - Ref names must not contain question mark (?), asterisk (*), open bracket ([), or backslash (\) - Ref names must not begin or end with a slash - Ref names must not end with a dot (.) - Ref names must not contain consecutive slashes (//) - Ref names must not contain the sequence @{ (used for reflogs) - Ref names must not be the single character @ - Ref names must not contain :\\ (Windows paths)

Parameters:

• path: The ref path to validate (e.g., "refs/heads/main")

Returns:

• error: nil if valid, ValidationError with details if invalid

func ValidateSHA ¶

func ValidateSHA(sha string) error

ValidateSHA validates a git SHA string. Returns nil if the SHA is valid (exactly 40 hexadecimal characters).

func ValidateSymbolicRefTarget ¶

func ValidateSymbolicRefTarget(target string) error

ValidateSymbolicRefTarget validates the target of a symbolic ref.

func VerifyGitFsck ¶

func VerifyGitFsck(gitDir string, commitSHAs ...string) (returnErr error)

VerifyGitFsck runs git fsck to verify repository integrity without network access.

This function runs 'git fsck --no-full --no-progress' to verify the integrity of the repository object database. It does not require or perform any network operations.

Parameters:

• gitDir: Path to the git directory (e.g., "/path/to/repo.git")

Returns:

• error: nil if fsck passes, error with clear message if corruption detected

Error types returned:

• ErrNotAGitRepo: if gitDir is not a valid git repository
• Error with Kind=CorruptPack: if git fsck detects corruption

Example:

if err := VerifyGitFsck(gitDir); err != nil {
    return fmt.Errorf("repository integrity check failed: %w", err)
}

func VerifyGitLog ¶

func VerifyGitLog(gitDir string, commitSHAs ...string) (returnErr error)

VerifyGitLog runs git log to verify commit history is accessible without network access.

This function runs 'git log --oneline -n 1' to verify that git can read commit history. It performs only a local read operation and does not fetch from remotes.

Parameters:

• gitDir: Path to the git directory (e.g., "/path/to/repo.git")

Returns:

• error: nil if log succeeds, error if commit history is inaccessible

Error types returned:

• ErrNotAGitRepo: if gitDir is not a valid git repository
• Error with Kind=CorruptPack: if git cannot read commit history due to corruption

Example:

if err := VerifyGitLog(gitDir); err != nil {
    return fmt.Errorf("commit history verification failed: %w", err)
}

func VerifyLooseRefFormat ¶

func VerifyLooseRefFormat(gitDir string, refPath string, commitSHAs ...string) (returnErr error)

VerifyLooseRefFormat verifies that a loose ref file on disk has the correct format.

For direct refs, the file content must be exactly 41 bytes: 40 hexadecimal characters followed by a newline. For symbolic refs (starting with "ref:"), the content must not have a trailing newline.

This function is useful for testing and validation to ensure ref files are written correctly by WriteLooseRef.

Parameters:

• gitDir: Path to the git directory (e.g., "/path/to/repo.git")
• refPath: Relative ref path (e.g., "refs/heads/main")

Returns:

• error: nil if format is correct, error otherwise

Error types returned:

• *Error with Kind=IO: file read failures
• *Error with Kind=Other: incorrect format (wrong size, invalid SHA, etc.)

Example:

if err := warmstart.VerifyLooseRefFormat("/path/to/repo.git", "refs/heads/main"); err != nil {
    t.Fatalf("ref format validation failed: %v", err)
}

func WriteLooseRef ¶

func WriteLooseRef(gitDir string, ref Ref, commitSHAs ...string) (returnErr error)

WriteLooseRef writes a single ref as a loose file to the git directory.

The function creates the ref file at the correct loose path (e.g., .git/refs/heads/main) with the content formatted as exactly 40 hex characters followed by a newline (41 bytes total) for direct refs. Symbolic refs (starting with "ref:") are written without a trailing newline.

Parent directories are created automatically if they do not exist (e.g., refs/heads/).

Parameters:

• gitDir: Path to the git directory (e.g., "/path/to/repo.git")
• ref: Ref struct containing Path and SHA fields

Returns:

• error: nil on success, error on failure

Error types returned:

• *Error with Kind=IO: filesystem write failures (permission denied, disk full, etc.)
• *Error with Kind=Other: invalid ref path or SHA format

Example:

ref := warmstart.Ref{Path: "refs/heads/main", SHA: "abc123...def"}
if err := warmstart.WriteLooseRef("/path/to/repo.git", ref); err != nil {
    return fmt.Errorf("failed to write ref: %w", err)
}