pull

Documentation

Index

• type ClientReceipt
• type DownloadProgressCallback
• type Options
• type PackReceipt
• type Receipt
  • func NewReceipt(remoteName string, target remote.TargetConfig, outputPath string, ...) *Receipt
• type ReceiptWriter
  • func (w *ReceiptWriter) Write(receipt *Receipt) (string, error)
• type Result
  • func Pull(ctx context.Context, opts Options) (*Result, error)
• type StepCallback

Types

type ClientReceipt

type ClientReceipt struct {
	EpackVersion string `json:"epack_version"`
	OS           string `json:"os"`
	Arch         string `json:"arch"`
}

ClientReceipt contains epack client metadata in the receipt.

type DownloadProgressCallback

type DownloadProgressCallback func(read, total int64)

DownloadProgressCallback is called periodically during download with bytes read and total.

type Options

type Options struct {
	// Remote is the name of the remote to pull from (required).
	Remote string

	// Ref specifies which pack to pull (required).
	// Exactly one of Digest, ReleaseID, Version, or Latest should be set.
	Ref remote.PackRef

	// OutputPath is the destination path for the downloaded pack.
	// If empty, defaults to ./<stream>.pack
	OutputPath string

	// Force allows overwriting an existing file.
	Force bool

	// Environment is the environment override (optional).
	// Applies configuration from environments.<env> section.
	Environment string

	// Workspace overrides the target workspace (optional).
	Workspace string

	// Verify enables pack integrity verification after download.
	Verify bool

	// Frozen requires all adapters to be pinned with digests (CI mode).
	// SECURITY: When true, adapters must be verified against lockfile digests.
	Frozen bool

	// InsecureAllowUnpinned allows execution of adapters not pinned in lockfile.
	// SECURITY WARNING: This bypasses digest verification for source-based adapters.
	InsecureAllowUnpinned bool

	// Stderr is where adapter stderr output is written.
	// If nil, os.Stderr is used.
	Stderr io.Writer

	// OnStep is called when each step of the pull workflow starts/completes.
	// Optional; if nil, no callbacks are made.
	OnStep StepCallback

	// OnDownloadProgress is called periodically during download.
	// Optional; if nil, no progress is reported.
	OnDownloadProgress DownloadProgressCallback

	// PromptInstallAdapter is called when the adapter is not installed.
	// If it returns true, the adapter will be installed automatically.
	// If nil, no prompt is shown and an error is returned instead.
	PromptInstallAdapter func(remoteName, adapterName string) bool
}

Options configures a pull operation.

type PackReceipt

type PackReceipt struct {
	OutputPath string    `json:"output_path"`
	Digest     string    `json:"digest"`
	SizeBytes  int64     `json:"size_bytes"`
	Stream     string    `json:"stream"`
	CreatedAt  time.Time `json:"created_at"`
	ReleaseID  string    `json:"release_id,omitempty"`
	Version    string    `json:"version,omitempty"`
	Labels     []string  `json:"labels,omitempty"`
}

PackReceipt contains pack metadata in the receipt.

type Receipt

type Receipt struct {
	// ReceiptVersion is the receipt format version.
	ReceiptVersion int `json:"receipt_version"`

	// CreatedAt is when the receipt was created.
	CreatedAt time.Time `json:"created_at"`

	// Remote is the remote name used for the pull.
	Remote string `json:"remote"`

	// Target contains the workspace/environment.
	Target remote.TargetConfig `json:"target"`

	// Pack contains pack metadata.
	Pack PackReceipt `json:"pack"`

	// Verified indicates whether the pack was verified after download.
	Verified bool `json:"verified"`

	// Client contains epack client metadata.
	Client ClientReceipt `json:"client"`
}

Receipt records the result of a pull operation for audit purposes.

func NewReceipt

func NewReceipt(
	remoteName string,
	target remote.TargetConfig,
	outputPath string,
	packMeta *remote.PackMetadata,
	verified bool,
) *Receipt

NewReceipt creates a new receipt from pull result data.

type ReceiptWriter

type ReceiptWriter struct {
	// BaseDir is the base directory for receipts.
	// Defaults to .epack/receipts/pull if empty.
	BaseDir string
}

ReceiptWriter writes pull receipts to disk.

func (*ReceiptWriter) Write

func (w *ReceiptWriter) Write(receipt *Receipt) (string, error)

Write writes a receipt to disk. Returns the path to the written receipt file.

SECURITY: This function validates the remote name to prevent path traversal attacks and uses TOCTOU-safe file operations to prevent symlink attacks.

type Result

type Result struct {
	// OutputPath is the path to the downloaded pack file.
	OutputPath string

	// Pack contains metadata about the pulled pack.
	Pack *remote.PackMetadata

	// Verified indicates whether the pack was verified after download.
	Verified bool

	// ReceiptPath is the path to the written receipt file.
	ReceiptPath string
}

Result contains the result of a pull operation.

func Pull

func Pull(ctx context.Context, opts Options) (*Result, error)

Pull downloads a pack from a remote registry.

SECURITY: This function performs TOCTOU-safe execution for source-based adapters. The adapter binary is verified against the lockfile digest before execution, preventing attacks where an attacker modifies the binary between resolution and execution.

type StepCallback

type StepCallback func(step string, started bool)

StepCallback is called when a pull step starts or completes. step is the step name, started indicates whether the step is starting (true) or done (false).