remote

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 24, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package remote implements the Remote Adapter Protocol for epack push/pull operations.

Remote adapters are external binaries that handle communication with remote registries. They follow a JSON-over-stdin/stdout protocol, similar to how Git credential helpers work.

Adapter Naming

Adapters are named epack-remote-<name>, for example:

  • epack-remote-locktivity
  • epack-remote-s3
  • epack-remote-filesystem

Discovery

Adapters are discovered from multiple locations:

  1. Project lockfile: Source-based remotes are installed to .epack/remotes/<name>/<version>/
  2. External binary: Configured via binary: field in epack.yaml
  3. System PATH: For adapter-only remotes (adapter: field without source/binary)

Protocol

The protocol uses newline-delimited JSON. Requests are sent on stdin, responses on stdout. Stderr is used for human-readable log messages.

Commands:

  • --capabilities: Returns adapter capabilities (synchronous, no stdin)
  • push.prepare: Get presigned upload URL
  • push.finalize: Finalize upload and create release
  • runs.sync: Sync run ledgers to remote (optional)
  • auth.login: Authenticate with remote (optional)
  • auth.whoami: Query current identity (optional)

Security

Adapters are external binaries and should be treated with appropriate caution:

  • Source-based adapters are verified via Sigstore and lockfile digests (epack.lock.yaml)
  • External binary adapters have their digest pinned in the lockfile
  • PATH-only adapters are unverified and should be used with caution
  • Authentication is managed by the adapter, not epack

Example Usage 

// Find and probe adapter capabilities
adapter := remote.FindAdapter(ctx, "locktivity", remote.DiscoverOptions{
    ProbeManaged: true,
})
if adapter == nil {
    // Adapter not installed
}

// Execute push workflow
exec := remote.NewExecutor(adapter.BinaryPath, adapter.Name)
prepResp, err := exec.Prepare(ctx, &remote.PrepareRequest{
    Remote: "locktivity",
    Target: remote.TargetConfig{Workspace: "acme", Environment: "prod"},
    Pack:   remote.PackInfo{Path: "pack.epack", Digest: "sha256:...", SizeBytes: 1234},
})
// Upload to prepResp.Upload.URL
// Then call exec.Finalize(...)

Package remote implements the Remote Adapter Protocol v1 for epack push/pull operations.

Remote adapters are external binaries (epack-remote-<name>) that handle communication with remote registries. The protocol uses JSON over stdin/stdout for all commands.

Commands:

  • --capabilities: Returns adapter capabilities (required)
  • push.prepare: Get presigned upload URL
  • push.finalize: Finalize upload and create release
  • pull.prepare: Get presigned download URL
  • pull.finalize: Confirm download completion
  • runs.sync: Sync run ledgers to remote
  • auth.login: Authenticate with remote (adapter-managed)
  • auth.whoami: Show current identity

Package remote provides remote adapter resolution and execution.

This file contains shared resolution logic for push/pull workflows, including adapter path resolution, config merging, and auto-install.

Index

Constants

View Source 
const (
	// DefaultAdapterRateLimit caps adapter invocations to prevent
	// overwhelming remote services or exhausting API quotas.
	DefaultAdapterRateLimit = 10 // requests per second

	// DefaultAdapterRateBurst permits short bursts for batch operations
	// while maintaining the average rate over time.
	DefaultAdapterRateBurst = 5
)

Rate limiting constants for adapter invocations.

View Source 
const (
	CommandCapabilities = "--capabilities"
	CommandPushPrepare  = "push.prepare"
	CommandPushFinalize = "push.finalize"
	CommandPullPrepare  = "pull.prepare"
	CommandPullFinalize = "pull.finalize"
	CommandRunsSync     = "runs.sync"
	CommandAuthLogin    = "auth.login"
	CommandAuthWhoami   = "auth.whoami"
)

Command types for adapter invocation.

View Source 
const (
	TypePushPrepare  = "push.prepare"
	TypePushFinalize = "push.finalize"
	TypePullPrepare  = "pull.prepare"
	TypePullFinalize = "pull.finalize"
	TypeRunsSync     = "runs.sync"
	TypeAuthLogin    = "auth.login"
	TypeAuthWhoami   = "auth.whoami"
)

Request type strings.

View Source 
const (
	TypePushPrepareResult  = "push.prepare.result"
	TypePushFinalizeResult = "push.finalize.result"
	TypePullPrepareResult  = "pull.prepare.result"
	TypePullFinalizeResult = "pull.finalize.result"
	TypeRunsSyncResult     = "runs.sync.result"
	TypeAuthLoginResult    = "auth.login.result"
	TypeAuthWhoamiResult   = "auth.whoami.result"
	TypeError              = "error"
)

Response type strings.

View Source 
const (
	ErrCodeUnsupportedProtocol = "unsupported_protocol"
	ErrCodeInvalidRequest      = "invalid_request"
	ErrCodeAuthRequired        = "auth_required"
	ErrCodeForbidden           = "forbidden"
	ErrCodeNotFound            = "not_found"
	ErrCodeConflict            = "conflict"
	ErrCodeRateLimited         = "rate_limited"
	ErrCodeServerError         = "server_error"
	ErrCodeNetworkError        = "network_error"
)

Error codes returned by adapters.

View Source 
const DefaultTimeout = 5 * time.Minute

DefaultTimeout is the default timeout for adapter commands.

View Source 
const ProtocolVersion = 1

ProtocolVersion is the current version of the Remote Adapter Protocol.

Variables

This section is empty.

Functions

func CheckAdapterSecurity 

func CheckAdapterSecurity(remoteName, binaryPath string, digestInfo AdapterDigestInfo, opts VerificationOptions) error

CheckAdapterSecurity performs security checks before adapter execution. Validates:

  1. Insecure install marker (adapter was installed with --insecure-skip-verify)
  2. Source-based adapters have digests pinned (unless explicitly allowed)
  3. External adapters are pinned in lockfile (unless explicitly allowed)
  4. Frozen mode requirements (all adapters must be pinned)

Returns nil if execution is allowed, or an error describing the security violation.

func LookupAdapterPath 

func LookupAdapterPath(name string) string

LookupAdapterPath finds the binary path for a named adapter. It checks managed directory, project-local, and PATH in order. Returns empty string if not found.

func PrepareAdapterExecutor 

func PrepareAdapterExecutor(
	ctx context.Context,
	projectRoot string,
	remoteName string,
	cfg *config.JobConfig,
	remoteCfg *config.RemoteConfig,
	opts AdapterExecutorOptions,
) (*Executor, *Capabilities, error)

PrepareAdapterExecutor resolves, verifies, and probes a remote adapter.

This is the shared setup path for push/pull workflows:

  1. Resolve adapter path (with optional auto-install)
  2. Load lockfile and digest metadata
  3. Enforce adapter security policy
  4. Create executor (verified when digest is pinned)
  5. Query adapter capabilities

Callers must call Close() on the returned executor.

func ResolveAdapterPath 

func ResolveAdapterPath(projectRoot, remoteName string, cfg *config.RemoteConfig) (string, error)

ResolveAdapterPath resolves the adapter binary path for a remote.

Remotes must be configured with either source: or binary: in epack.yaml. There is no PATH discovery fallback (matching the collector model).

For source-based remotes, the binary must be installed via 'epack sync' first. For external remotes, the configured absolute path is returned directly.

SECURITY: External binary paths MUST be absolute to prevent PATH injection.

func ResolveAdapterPathWithInstall 

func ResolveAdapterPathWithInstall(
	ctx context.Context,
	projectRoot string,
	remoteName string,
	cfg *config.JobConfig,
	remoteCfg *config.RemoteConfig,
	promptInstall PromptInstallFunc,
	step StepCallback,
	stderr io.Writer,
) (string, error)

ResolveAdapterPathWithInstall resolves the adapter path, offering to install if missing. If resolution fails and the remote has a source configured, prompts to install. On acceptance, installs via sync and retries resolution.

SECURITY: Source-based adapters are installed via sync which performs Sigstore verification and digest pinning (unless --insecure-skip-verify was used at sync time).

func ResolveRemoteConfig 

func ResolveRemoteConfig(cfg *config.JobConfig, remoteName, envName string) (*config.RemoteConfig, error)

ResolveRemoteConfig resolves the remote configuration with environment overrides.

Environment overrides allow different target workspaces, endpoints, and settings for different deployment environments (staging, production, etc.) while sharing the same base remote configuration.

Types

type ActionHint 

type ActionHint struct {
	Type    string `json:"type"` // run_command, open_url, etc.
	Command string `json:"command,omitempty"`
	URL     string `json:"url,omitempty"`
}

ActionHint provides guidance on how to resolve an error.

type AdapterDigestInfo 

type AdapterDigestInfo struct {
	// Digest is the expected SHA256 digest from the lockfile (empty if not pinned).
	Digest string

	// NeedsVerification is true if the adapter should be verified before execution.
	NeedsVerification bool

	// IsSourceAdapter is true if this is a source-based adapter (installed via sync).
	IsSourceAdapter bool

	// IsExternalBinary is true if this is an external adapter (binary path in config).
	IsExternalBinary bool

	// MissingDigest is true if the adapter is in the lockfile but has no digest.
	MissingDigest bool
}

AdapterDigestInfo contains information about an adapter's digest and verification state.

func GetAdapterDigestInfo 

func GetAdapterDigestInfo(remoteName string, remoteCfg *config.RemoteConfig, lf *lockfile.LockFile, platform string) AdapterDigestInfo

GetAdapterDigestInfo retrieves digest information for an adapter from the lockfile.

SECURITY: This function determines whether TOCTOU-safe verification is required for the adapter. Source-based adapters should always have a digest pinned in the lockfile for secure execution.

Note: Remotes must be configured with either source: or binary: in epack.yaml. There is no PATH discovery fallback (matching the collector model).

type AdapterError 

type AdapterError struct {
	AdapterName string      // Adapter that returned the error
	Code        string      // Machine-readable error code (e.g., "auth_required")
	Message     string      // Human-readable description
	Retryable   bool        // Whether the operation may succeed if retried
	Action      *ActionHint // Optional guidance for resolution (may be nil)
}

AdapterError represents a structured error from a remote adapter. Check IsAuthRequired to determine if re-authentication is needed. Check IsRetryable to determine if the operation can be retried.

func (*AdapterError) Error 

func (e *AdapterError) Error() string

func (*AdapterError) HasAction 

func (e *AdapterError) HasAction() bool

HasAction returns true if the error includes an action hint.

func (*AdapterError) IsAuthRequired 

func (e *AdapterError) IsAuthRequired() bool

IsAuthRequired returns true if authentication is required.

func (*AdapterError) IsRetryable 

func (e *AdapterError) IsRetryable() bool

IsRetryable returns true if the error is retryable.

type AdapterExecutorOptions 

type AdapterExecutorOptions struct {
	// PromptInstall is called when the adapter is not installed.
	// If it returns true, adapter installation is attempted automatically.
	PromptInstall PromptInstallFunc

	// Step receives workflow step start/complete events.
	Step StepCallback

	// Stderr is where adapter stderr output is written.
	// If nil, adapter stderr is discarded by default.
	Stderr io.Writer

	// Verification configures adapter security checks.
	Verification VerificationOptions
}

AdapterExecutorOptions controls shared adapter setup behavior.

type AdapterStatus 

type AdapterStatus string

AdapterStatus indicates the verification status of a remote adapter. 

const (
	// StatusVerified means the adapter is in epack.lock.yaml with a valid digest.
	StatusVerified AdapterStatus = "verified"
	// StatusUnverified means the adapter is in PATH but not in lockfile.
	StatusUnverified AdapterStatus = "unverified"
	// StatusManaged means the adapter is managed (in lockfile) but not yet installed.
	StatusManaged AdapterStatus = "managed"
	// StatusNotFound means the adapter was configured but not found anywhere.
	StatusNotFound AdapterStatus = "not_found"
)

type AuthHints 

type AuthHints struct {
	Mode   string            `json:"mode,omitempty"`   // oidc_token, api_key, etc.
	Token  string            `json:"token,omitempty"`  // For OIDC mode
	Claims map[string]string `json:"claims,omitempty"` // OIDC claims
}

AuthHints contains authentication hints for adapter requests. This is passed to adapters to help them authenticate with remotes.

type AuthLoginInstructions 

type AuthLoginInstructions struct {
	UserCode        string `json:"user_code"`
	VerificationURI string `json:"verification_uri"`
	ExpiresInSecs   int    `json:"expires_in_seconds"`
}

AuthLoginInstructions provides device code flow instructions.

type AuthLoginRequest 

type AuthLoginRequest struct {
	Type            string `json:"type"` // "auth.login"
	ProtocolVersion int    `json:"protocol_version"`
	RequestID       string `json:"request_id"`
}

AuthLoginRequest initiates authentication with the remote.

type AuthLoginResponse 

type AuthLoginResponse struct {
	OK           bool                  `json:"ok"`
	Type         string                `json:"type"` // "auth.login.result"
	RequestID    string                `json:"request_id"`
	Instructions AuthLoginInstructions `json:"instructions"`
}

AuthLoginResponse is returned from auth.login.

type AuthWhoamiRequest 

type AuthWhoamiRequest struct {
	Type            string `json:"type"` // "auth.whoami"
	ProtocolVersion int    `json:"protocol_version"`
	RequestID       string `json:"request_id"`
}

AuthWhoamiRequest queries the current authentication state.

type AuthWhoamiResponse 

type AuthWhoamiResponse struct {
	OK        bool           `json:"ok"`
	Type      string         `json:"type"` // "auth.whoami.result"
	RequestID string         `json:"request_id"`
	Identity  IdentityResult `json:"identity"`
}

AuthWhoamiResponse is returned from auth.whoami.

type Capabilities 

type Capabilities struct {
	// Name is the adapter name (e.g., "locktivity").
	Name string `json:"name"`

	// Kind identifies this as a deploy adapter.
	Kind string `json:"kind"` // "remote_adapter"

	// DeployProtocolVersion is the protocol version supported by this adapter.
	DeployProtocolVersion int `json:"deploy_protocol_version"`

	// Features indicates which optional features are supported.
	Features CapabilityFeatures `json:"features"`

	// Auth describes authentication options.
	Auth CapabilityAuth `json:"auth,omitempty"`

	// Limits describes operational limits.
	Limits CapabilityLimits `json:"limits,omitempty"`

	// Extensions contains adapter-specific capabilities.
	Extensions map[string]any `json:"extensions,omitempty"`
}

Capabilities describes what features a remote adapter supports. This is returned by the --capabilities command.

func QueryCapabilities 

func QueryCapabilities(ctx context.Context, binaryPath string) (*Capabilities, error)

QueryCapabilities queries the adapter's capabilities without digest verification.

SECURITY WARNING: This function does NOT verify the binary digest. It should only be used for PATH-based adapters or when verification is handled separately. For source-based adapters, use QueryCapabilitiesVerified instead.

func QueryCapabilitiesVerified 

func QueryCapabilitiesVerified(ctx context.Context, binaryPath, expectedDigest string) (*Capabilities, error)

QueryCapabilitiesVerified queries capabilities using TOCTOU-safe execution.

SECURITY: This function verifies the binary against the expected digest before executing it, preventing TOCTOU attacks where an attacker modifies the binary between resolution and execution.

The verification creates a temporary copy of the binary, hashes it during copy, verifies the hash matches, then executes the verified copy.

func (*Capabilities) SupportsAuthLogin 

func (c *Capabilities) SupportsAuthLogin() bool

SupportsAuthLogin returns true if the adapter supports interactive authentication.

func (*Capabilities) SupportsAuthMode 

func (c *Capabilities) SupportsAuthMode(mode string) bool

SupportsAuthMode returns true if the adapter supports the given auth mode.

func (*Capabilities) SupportsPrepareFinalize 

func (c *Capabilities) SupportsPrepareFinalize() bool

SupportsPrepareFinalize returns true if the adapter uses the two-phase upload protocol.

func (*Capabilities) SupportsProtocolVersion 

func (c *Capabilities) SupportsProtocolVersion(version int) bool

SupportsProtocolVersion returns true if the adapter supports the given protocol version.

func (*Capabilities) SupportsPull 

func (c *Capabilities) SupportsPull() bool

SupportsPull returns true if the adapter supports the two-phase download protocol.

func (*Capabilities) SupportsRunsSync 

func (c *Capabilities) SupportsRunsSync() bool

SupportsRunsSync returns true if the adapter supports run syncing.

func (*Capabilities) SupportsWhoami 

func (c *Capabilities) SupportsWhoami() bool

SupportsWhoami returns true if the adapter supports identity query.

type CapabilityAuth 

type CapabilityAuth struct {
	// Modes lists supported authentication methods.
	// Values: "device_code", "oidc_token", "api_key"
	Modes []string `json:"modes,omitempty"`

	// TokenStorage describes how tokens are stored.
	// Values: "os_keychain", "encrypted_file", "env_var"
	TokenStorage string `json:"token_storage,omitempty"`
}

CapabilityAuth describes authentication options.

type CapabilityFeatures 

type CapabilityFeatures struct {
	// PrepareFinalize indicates support for the two-phase upload protocol.
	// If true, adapter supports push.prepare + push.finalize.
	// If false, adapter uses direct upload (not recommended).
	PrepareFinalize bool `json:"prepare_finalize"`

	// DirectUpload indicates the adapter handles upload itself.
	// Mutually exclusive with PrepareFinalize for primary upload mode.
	DirectUpload bool `json:"direct_upload"`

	// Pull indicates support for the two-phase download protocol.
	// If true, adapter supports pull.prepare + pull.finalize.
	Pull bool `json:"pull"`

	// RunsSync indicates support for run ledger syncing.
	RunsSync bool `json:"runs_sync"`

	// AuthLogin indicates support for interactive authentication.
	AuthLogin bool `json:"auth_login"`

	// Whoami indicates support for identity query.
	Whoami bool `json:"whoami"`
}

CapabilityFeatures indicates which protocol features are supported.

type CapabilityLimits 

type CapabilityLimits struct {
	// MaxPackBytes is the maximum pack size supported (0 = unlimited).
	MaxPackBytes int64 `json:"max_pack_bytes,omitempty"`

	// MaxRunsPerSync is the maximum runs per sync request (0 = unlimited).
	MaxRunsPerSync int `json:"max_runs_per_sync,omitempty"`
}

CapabilityLimits describes operational limits.

type DiscoverOptions 

type DiscoverOptions struct {
	// ProbePATH enables probing --capabilities from PATH adapters.
	// SECURITY: PATH adapters are untrusted; probing executes arbitrary code.
	// This should only be enabled with explicit user opt-in.
	ProbePATH bool

	// ProbeManaged enables probing --capabilities from managed adapters.
	// When false, capabilities must come from registry metadata.
	ProbeManaged bool

	// WorkDir is the working directory to search from.
	// If empty, uses current working directory.
	WorkDir string
}

DiscoverOptions configures adapter discovery.

type DiscoveredAdapter 

type DiscoveredAdapter struct {
	// Name is the adapter name without prefix (e.g., "locktivity").
	Name string `json:"name"`

	// BinaryName is the full binary name (e.g., "epack-remote-locktivity").
	BinaryName string `json:"binary_name"`

	// BinaryPath is the full path to the binary (empty if not found).
	BinaryPath string `json:"binary_path,omitempty"`

	// Capabilities are the adapter capabilities (nil if not probed or failed).
	Capabilities *Capabilities `json:"capabilities,omitempty"`

	// Error contains the error message if capability probing failed.
	Error string `json:"error,omitempty"`

	// Status indicates verification status.
	Status AdapterStatus `json:"status"`

	// Source indicates where the adapter was found.
	// Values: "managed", "path", "both"
	Source string `json:"source"`
}

DiscoveredAdapter represents a remote adapter found on the system.

func DiscoverAdapters 

func DiscoverAdapters(ctx context.Context, opts DiscoverOptions) []DiscoveredAdapter

DiscoverAdapters finds remote adapters from managed directory and PATH. By default, no adapters are probed (requires explicit opt-in).

func FindAdapter 

func FindAdapter(ctx context.Context, name string, opts DiscoverOptions) *DiscoveredAdapter

FindAdapter finds a specific adapter by name. Returns nil if not found.

type DownloadInfo 

type DownloadInfo struct {
	Method    string            `json:"method"`
	URL       string            `json:"url"`
	Headers   map[string]string `json:"headers,omitempty"`
	ExpiresAt *time.Time        `json:"expires_at,omitempty"`
}

DownloadInfo contains presigned download details.

type ErrorInfo 

type ErrorInfo struct {
	Code      string      `json:"code"`
	Message   string      `json:"message"`
	Retryable bool        `json:"retryable"`
	Action    *ActionHint `json:"action,omitempty"`
}

ErrorInfo contains error details.

func (*ErrorInfo) IsAuthRequired 

func (e *ErrorInfo) IsAuthRequired() bool

IsAuthRequired returns true if authentication is required.

func (*ErrorInfo) IsRetryable 

func (e *ErrorInfo) IsRetryable() bool

IsRetryable returns true if the error is retryable.

type ErrorResponse 

type ErrorResponse struct {
	OK        bool      `json:"ok"`   // Always false
	Type      string    `json:"type"` // "error"
	RequestID string    `json:"request_id"`
	Error     ErrorInfo `json:"error"`
}

ErrorResponse is returned when an operation fails.

type Executor 

type Executor struct {
	// BinaryPath is the path to the adapter binary.
	// For verified execution, this is the path to the verified copy.
	BinaryPath string

	// AdapterName is the adapter name (for error messages).
	AdapterName string

	// Timeout is the command timeout (defaults to DefaultTimeout).
	Timeout time.Duration

	// Stderr is where adapter stderr output is written.
	// If nil, stderr is discarded.
	Stderr io.Writer
	// contains filtered or unexported fields
}

Executor runs remote adapter commands.

func NewExecutor 

func NewExecutor(binaryPath, adapterName string) *Executor

NewExecutor creates an executor for the given adapter binary.

SECURITY WARNING: This creates an unverified executor. For source-based adapters, use NewVerifiedExecutor instead to ensure TOCTOU-safe execution with digest verification. Unverified executors should only be used for:

  • PATH-based adapters (no source configured)
  • Development/testing scenarios

func NewVerifiedExecutor 

func NewVerifiedExecutor(binaryPath, expectedDigest, adapterName string) (*Executor, error)

NewVerifiedExecutor creates a TOCTOU-safe executor that verifies the adapter binary against the expected digest before execution.

SECURITY: This function provides the same security guarantees as collector/tool execution:

  • Binary is verified against expected digest (TOCTOU-safe via copy-while-hash)
  • A verified copy of the binary is executed (not the original)
  • The verified copy is sealed (read-only directory) to prevent modification

The caller MUST call Close() when done to clean up the verified binary copy.

Example: 

exec, err := NewVerifiedExecutor(binaryPath, expectedDigest, adapterName)
if err != nil {
    return err
}
defer exec.Close()
// ... use exec for adapter operations

func (*Executor) AuthLogin 

func (e *Executor) AuthLogin(ctx context.Context) (*AuthLoginResponse, error)

AuthLogin initiates interactive authentication.

func (*Executor) AuthWhoami 

func (e *Executor) AuthWhoami(ctx context.Context) (*AuthWhoamiResponse, error)

AuthWhoami queries the current authentication state.

func (*Executor) Close 

func (e *Executor) Close()

Close releases resources associated with this executor. For verified executors, this removes the verified binary copy. Safe to call multiple times or on unverified executors.

func (*Executor) Finalize 

func (e *Executor) Finalize(ctx context.Context, req *FinalizeRequest) (*FinalizeResponse, error)

Finalize completes a push operation after upload.

func (*Executor) Prepare 

func (e *Executor) Prepare(ctx context.Context, req *PrepareRequest) (*PrepareResponse, error)

Prepare initiates a push operation and returns upload information.

func (*Executor) PullFinalize 

func (e *Executor) PullFinalize(ctx context.Context, req *PullFinalizeRequest) (*PullFinalizeResponse, error)

PullFinalize completes a pull operation after download.

func (*Executor) PullPrepare 

func (e *Executor) PullPrepare(ctx context.Context, req *PullPrepareRequest) (*PullPrepareResponse, error)

PullPrepare initiates a pull operation and returns download information.

func (*Executor) SyncRuns 

func (e *Executor) SyncRuns(ctx context.Context, req *RunsSyncRequest) (*RunsSyncResponse, error)

SyncRuns syncs run ledgers to the remote.

type FinalizeRequest 

type FinalizeRequest struct {
	Type            string       `json:"type"` // "push.finalize"
	ProtocolVersion int          `json:"protocol_version"`
	RequestID       string       `json:"request_id"`
	Remote          string       `json:"remote"`
	Target          TargetConfig `json:"target"`
	Pack            PackInfo     `json:"pack"`
	FinalizeToken   string       `json:"finalize_token"`
}

FinalizeRequest is sent after successful upload to create the release.

type FinalizeResponse 

type FinalizeResponse struct {
	OK         bool              `json:"ok"`
	Type       string            `json:"type"` // "push.finalize.result"
	RequestID  string            `json:"request_id"`
	Release    ReleaseResult     `json:"release"`
	Links      map[string]string `json:"links,omitempty"`
	Extensions map[string]any    `json:"extensions,omitempty"`
}

FinalizeResponse is returned from push.finalize.

type IdentityResult 

type IdentityResult struct {
	Authenticated bool   `json:"authenticated"`
	Subject       string `json:"subject,omitempty"`
	Issuer        string `json:"issuer,omitempty"`
	ExpiresAt     string `json:"expires_at,omitempty"`
}

IdentityResult contains current authentication identity.

type PackInfo 

type PackInfo struct {
	Path      string `json:"path"`
	Digest    string `json:"digest"`
	SizeBytes int64  `json:"size_bytes"`
}

PackInfo contains pack metadata for push operations.

type PackMetadata 

type PackMetadata struct {
	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"`
}

PackMetadata contains pack information returned from pull.prepare.

type PackRef 

type PackRef struct {
	// Exactly one of these should be set
	Digest    string `json:"digest,omitempty"`     // Pull by exact digest (immutable)
	ReleaseID string `json:"release_id,omitempty"` // Pull by release ID
	Version   string `json:"version,omitempty"`    // Pull by semantic version
	Latest    bool   `json:"latest,omitempty"`     // Pull latest release
}

PackRef specifies how to reference a pack for pull operations.

type PrepareRequest 

type PrepareRequest struct {
	Type            string       `json:"type"` // "push.prepare"
	ProtocolVersion int          `json:"protocol_version"`
	RequestID       string       `json:"request_id"`
	Remote          string       `json:"remote"`
	Target          TargetConfig `json:"target"`
	Pack            PackInfo     `json:"pack"`
	Release         ReleaseInfo  `json:"release"`
	Identity        *AuthHints   `json:"identity,omitempty"`
}

PrepareRequest is sent to initiate a push operation.

type PrepareResponse 

type PrepareResponse struct {
	OK            bool       `json:"ok"`
	Type          string     `json:"type"` // "push.prepare.result"
	RequestID     string     `json:"request_id"`
	Upload        UploadInfo `json:"upload"`
	FinalizeToken string     `json:"finalize_token"`
}

PrepareResponse is returned from push.prepare.

type PromptInstallFunc 

type PromptInstallFunc func(remoteName, adapterName string) bool

PromptInstallFunc prompts the user to install an adapter. Returns true if the adapter should be installed, false otherwise.

type PullFinalizeRequest 

type PullFinalizeRequest struct {
	Type            string       `json:"type"` // "pull.finalize"
	ProtocolVersion int          `json:"protocol_version"`
	RequestID       string       `json:"request_id"`
	Remote          string       `json:"remote"`
	Target          TargetConfig `json:"target"`
	Digest          string       `json:"digest"`
	FinalizeToken   string       `json:"finalize_token"`
}

PullFinalizeRequest is sent after successful download to confirm completion.

type PullFinalizeResponse 

type PullFinalizeResponse struct {
	OK        bool   `json:"ok"`
	Type      string `json:"type"` // "pull.finalize.result"
	RequestID string `json:"request_id"`
}

PullFinalizeResponse is returned from pull.finalize.

type PullPrepareRequest 

type PullPrepareRequest struct {
	Type            string       `json:"type"` // "pull.prepare"
	ProtocolVersion int          `json:"protocol_version"`
	RequestID       string       `json:"request_id"`
	Remote          string       `json:"remote"`
	Target          TargetConfig `json:"target"`
	Ref             PackRef      `json:"ref"`
	Identity        *AuthHints   `json:"identity,omitempty"`
}

PullPrepareRequest is sent to initiate a pull operation.

type PullPrepareResponse 

type PullPrepareResponse struct {
	OK            bool         `json:"ok"`
	Type          string       `json:"type"` // "pull.prepare.result"
	RequestID     string       `json:"request_id"`
	Download      DownloadInfo `json:"download"`
	Pack          PackMetadata `json:"pack"`
	FinalizeToken string       `json:"finalize_token"`
}

PullPrepareResponse is returned from pull.prepare.

type ReleaseInfo 

type ReleaseInfo struct {
	Labels []string    `json:"labels,omitempty"`
	Notes  string      `json:"notes,omitempty"`
	Source *SourceInfo `json:"source,omitempty"`
}

ReleaseInfo contains release metadata for push operations.

type ReleaseResult 

type ReleaseResult struct {
	ReleaseID    string    `json:"release_id"`
	PackDigest   string    `json:"pack_digest"`
	CreatedAt    time.Time `json:"created_at"`
	CanonicalRef string    `json:"canonical_ref"`
}

ReleaseResult contains the result of a successful push.

type RunInfo 

type RunInfo struct {
	RunID        string `json:"run_id"`
	ResultPath   string `json:"result_path"`
	ResultDigest string `json:"result_digest"`
}

RunInfo contains metadata about a single run to sync.

type RunSyncItem 

type RunSyncItem struct {
	RunID  string `json:"run_id"`
	Status string `json:"status"` // accepted, rejected, duplicate
}

RunSyncItem contains the result of syncing a single run.

type RunsSyncRequest 

type RunsSyncRequest struct {
	Type            string       `json:"type"` // "runs.sync"
	ProtocolVersion int          `json:"protocol_version"`
	RequestID       string       `json:"request_id"`
	Target          TargetConfig `json:"target"`
	PackDigest      string       `json:"pack_digest"`
	Runs            []RunInfo    `json:"runs"`
}

RunsSyncRequest is sent to sync run ledgers to the remote.

type RunsSyncResponse 

type RunsSyncResponse struct {
	OK        bool          `json:"ok"`
	Type      string        `json:"type"` // "runs.sync.result"
	RequestID string        `json:"request_id"`
	Accepted  int           `json:"accepted"`
	Rejected  int           `json:"rejected"`
	Items     []RunSyncItem `json:"items"`
}

RunsSyncResponse is returned from runs.sync.

type SourceInfo 

type SourceInfo struct {
	GitSHA   string `json:"git_sha,omitempty"`
	CIRunURL string `json:"ci_run_url,omitempty"`
}

SourceInfo contains source control metadata.

type StepCallback 

type StepCallback func(step string, started bool)

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

type TargetConfig 

type TargetConfig struct {
	Workspace   string `json:"workspace,omitempty"`
	Environment string `json:"environment,omitempty"`
}

TargetConfig specifies the remote target (workspace/environment).

type UploadInfo 

type UploadInfo struct {
	Method    string            `json:"method"`
	URL       string            `json:"url"`
	Headers   map[string]string `json:"headers,omitempty"`
	ExpiresAt *time.Time        `json:"expires_at,omitempty"`
}

UploadInfo contains presigned upload details.

type VerificationOptions 

type VerificationOptions struct {
	// Frozen requires all adapters to be pinned with digests (CI mode).
	Frozen bool

	// AllowInsecure permits execution of adapters installed with --insecure-skip-verify.
	AllowInsecure bool

	// AllowUnverifiedSource permits execution of source-based adapters without digest.
	// SECURITY WARNING: This bypasses TOCTOU protection for source-based adapters.
	AllowUnverifiedSource bool
}

VerificationOptions controls adapter verification behavior.

func DefaultVerificationOptions 

func DefaultVerificationOptions() VerificationOptions

DefaultVerificationOptions returns secure defaults for adapter verification.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.