errors

Documentation

Overview

Package errors provides typed error handling for evidence pack operations.

Error Code Stability

Error codes are stable strings that form part of the public API. They are suitable for programmatic handling, test assertions, and machine parsing. Breaking changes to error codes follow semantic versioning:

• New codes may be added in minor releases
• Existing codes will not be removed or renamed without a major version bump
• Error messages may change; code on the Code field, not message text

Creating Errors

Use the E function to create errors with a code, message, and optional cause:

return errors.E(errors.InvalidManifest, "missing required field: stream", nil)

Errors can wrap underlying causes for context:

return errors.E(errors.DigestMismatch, "artifact digest mismatch", originalErr)

Handling Errors

Use CodeOf to extract the error code, or errors.As for full access:

code := errors.CodeOf(err)
if code == errors.DigestMismatch {
    // Handle integrity failure
}

var e *errors.Error
if errors.As(err, &e) {
    switch e.Code {
    case errors.DigestMismatch:
        // Handle integrity failure
    case errors.InvalidManifest:
        // Handle malformed pack
    }
}

Error Categories

Codes are grouped by category:

• JSON/Parsing: duplicate_keys, invalid_json, missing_required_field
• Manifest: invalid_manifest, invalid_timestamp, unsupported_spec_version
• Pack Structure: zip_bomb, too_many_artifacts, duplicate_path, artifact_too_large, invalid_path, missing_entry
• Attestation: invalid_attestation, attestation_too_large
• Signature: signature_invalid, identity_mismatch
• Integrity: digest_mismatch, size_mismatch, pack_digest_mismatch
• Filesystem: symlink_not_allowed, path_traversal, permission_denied
• Operations: timeout, network_error
• Collector: lockfile_invalid, binary_not_found, insecure_install
• Input: invalid_input

Package errors defines typed errors for the evidence-pack library.

Error codes are stable strings suitable for test-vector matching. Use E() to create errors and CodeOf() to extract codes through wrapped errors.

Index

• Variables
• func DocURLFor(code Code) string
• func E(code Code, msg string, cause error) error
• func HasDocs(code Code) bool
• func WithDocs(code Code, exit int, msg, hint string, cause error) error
• func WithHint(code Code, exit int, msg, hint string, cause error) error
• type Code
  • func CodeOf(err error) Code
• type Error
  • func (e *Error) Error() string
  • func (e *Error) ExitCode() int
  • func (e *Error) Unwrap() error

Variables

var DocsBaseURL = "https://docs.epack.dev/errors"

DocsBaseURL is the base URL for error documentation. Set this at init time to enable doc links in error messages.

Functions

func DocURLFor

func DocURLFor(code Code) string

DocURLFor returns the documentation URL for an error code, or empty string if no documentation is available.

func E

func E(code Code, msg string, cause error) error

E creates a new Error with the given code, message, and optional cause. Pass nil for cause if there is no underlying error. For errors that need hints or explicit exit codes, use WithHint instead.

func HasDocs

func HasDocs(code Code) bool

HasDocs returns true if the error code has documentation available.

func WithDocs

func WithDocs(code Code, exit int, msg, hint string, cause error) error

WithDocs creates an Error with a hint and documentation URL. The doc URL is automatically generated from DocsBaseURL and the error code.

func WithHint

func WithHint(code Code, exit int, msg, hint string, cause error) error

WithHint creates an Error with an explicit exit code and user-facing hint. This replaces the previous sync.LockError, sync.DigestError, etc. types. The exit code should come from internal/exitcode constants.

Types

type Code

type Code string

Code identifies the category of error. These are stable strings suitable for test-vector matching.

const (
	// JSON parsing/shape errors.
	DuplicateKeys        Code = "duplicate_keys"
	InvalidJSON          Code = "invalid_json"
	MissingRequiredField Code = "missing_required_field"

	// Manifest validation errors
	InvalidManifest        Code = "invalid_manifest"
	InvalidTimestamp       Code = "invalid_timestamp"
	UnsupportedSpecVersion Code = "unsupported_spec_version"

	// Zip/pack validation errors
	ZipBomb          Code = "zip_bomb"
	TooManyArtifacts Code = "too_many_artifacts"
	DuplicatePath    Code = "duplicate_path"
	ArtifactTooLarge Code = "artifact_too_large"
	InvalidPath      Code = "invalid_path"
	MissingEntry     Code = "missing_entry"

	// Attestation validation errors
	InvalidAttestation  Code = "invalid_attestation"
	AttestationTooLarge Code = "attestation_too_large"

	// Signature verification errors
	SignatureInvalid Code = "signature_invalid"
	IdentityMismatch Code = "identity_mismatch"

	// Integrity verification errors
	DigestMismatch     Code = "digest_mismatch"
	SizeMismatch       Code = "size_mismatch"
	PackDigestMismatch Code = "pack_digest_mismatch"

	// Input validation errors
	InvalidInput Code = "invalid_input"

	// Filesystem errors
	SymlinkNotAllowed Code = "symlink_not_allowed"
	PathTraversal     Code = "path_traversal"
	PermissionDenied  Code = "permission_denied"

	// Operation errors
	Timeout      Code = "timeout"
	NetworkError Code = "network_error"

	// Collector errors
	LockfileInvalid Code = "lockfile_invalid"
	BinaryNotFound  Code = "binary_not_found"
	InsecureInstall Code = "insecure_install"

	// Remote adapter errors
	RemoteNotFound    Code = "remote_not_found"
	AdapterNotFound   Code = "adapter_not_found"
	AdapterExecFailed Code = "adapter_exec_failed"
	ProtocolMismatch  Code = "protocol_mismatch"
	UploadFailed      Code = "upload_failed"
	AuthRequired      Code = "auth_required"
	RemoteForbidden   Code = "remote_forbidden"
	RemoteConflict    Code = "remote_conflict"

	// Catalog errors
	CatalogNotFound     Code = "catalog_not_found"
	CatalogMetaNotFound Code = "catalog_meta_not_found"
	CircularDependency  Code = "circular_dependency"
	DependencyNotFound  Code = "dependency_not_found"
	ComponentNotFound   Code = "component_not_found"

	// Component errors
	AlreadyExists Code = "already_exists"
	InvalidName   Code = "invalid_name"
)

func CodeOf

func CodeOf(err error) Code

CodeOf extracts the Code from an error. It unwraps through error chains to find the first *Error. Returns empty string if no *Error is found.

type Error

type Error struct {
	Code    Code   // Stable string code for programmatic handling
	Exit    int    // CLI exit code override (0 = derive from Code)
	Message string // Human-readable error message
	Hint    string // Actionable hint for CLI users (optional)
	DocURL  string // URL to documentation for this error (optional)
	Cause   error  // Wrapped error for error chains
}

Error is a typed error carrying a stable Code, message, and optional cause. It unifies the previous errors.Error, exitcode.ExitError, and sync.*Error types.

func (*Error) Error

func (e *Error) Error() string

Error implements the error interface. If Hint is set, it's appended on a new line for CLI display. If DocURL is set, it's appended after the hint.

func (*Error) ExitCode

func (e *Error) ExitCode() int

ExitCode returns the CLI exit code for this error. If Exit is explicitly set (> 0), returns that value. Otherwise, maps the Code to an appropriate exit code.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap returns the underlying cause, enabling errors.Is and errors.As.