Help us shape the future of Go! Take the 2026 Go Developer Survey

executionenv

package
v0.0.45 Latest Latest
Warning

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

 Go to latest Published: Oct 7, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package executionenv defines the private, versioned host-side execution-provider protocol. It is intentionally not part of the public Harness API.

Index

Constants

View Source 
const (
	ProtocolVersion  = "execution-grpc/1"
	MaxMessageBytes  = 8 << 20
	MaxJSONBody      = 8 << 20 // credential-free provider-to-workload stdin framing only
	MaxFileBytes     = 5 << 20
	MaxCommandBytes  = 1 << 20
	MaxPathBytes     = 4096
	MaxIdentityBytes = 1024
	MaxBindingBytes  = 253
	MaxGrantBytes    = 16 << 10
	MaxListEntries   = 10_000
)

Private protocol bounds.

View Source 
const (
	MinRunTTL            = 30 * time.Second
	MaxRunTTL            = 5 * time.Minute
	DefaultRunTTL        = time.Minute
	DefaultRenewInterval = 20 * time.Second
)
View Source 
const PurposeSession = "session"

PurposeSession is the supported attachment purpose.

Variables

View Source 
var (
	// ErrGrantExpired identifies the only grant failure eligible for a read-only refresh.
	ErrGrantExpired = errors.New("grant expired")
	// ErrGrantNotYetValid identifies a grant whose validity window has not started.
	ErrGrantNotYetValid = errors.New("grant not yet valid")
)

Functions

func DecodeStrict 

func DecodeStrict(data []byte, dst any) error

DecodeStrict decodes exactly one bounded JSON value for the credential-free provider-to-workload stdin protocol, without unknown or duplicate fields.

func SignGrant 

func SignGrant(key ed25519.PrivateKey, c GrantClaims) (string, error)

SignGrant validates and signs claims with Ed25519.

Types

type AttachEnvironmentRequest 

type AttachEnvironmentRequest struct {
	Context RequestContext `json:"context"`
	Purpose string         `json:"purpose"`
}

AttachEnvironmentRequest requests exact reattachment to an existing environment.

type AttachEnvironmentResponse 

type AttachEnvironmentResponse struct {
	Environment     EnvironmentRef `json:"environment"`
	Epoch           uint64         `json:"epoch"`
	Ready           bool           `json:"ready"`
	GrantGeneration uint64         `json:"grant_generation"`
	Grant           string         `json:"grant"`
	GrantExpiresAt  time.Time      `json:"grant_expires_at"`
}

AttachEnvironmentResponse returns exact attachment state and a refreshed grant.

type CommandQueryRequest 

type CommandQueryRequest struct {
	Context   RequestContext `json:"context"`
	CommandID string         `json:"command_id"`
	Offset    int64          `json:"offset,omitempty"`
}

CommandQueryRequest identifies one command for status or cancellation.

type CommandStartRequest 

type CommandStartRequest struct {
	Context       RequestContext `json:"context"`
	Command       string         `json:"command"`
	TimeoutMillis int64          `json:"timeout_ms,omitempty"`
}

CommandStartRequest starts one bounded foreground shell command.

type CommandStartResponse 

type CommandStartResponse struct {
	CommandID string                `json:"command_id"`
	State     CommandState          `json:"state"`
	Result    CommandStatusResponse `json:"result"`
}

CommandStartResponse returns the command identity and terminal result.

type CommandState 

type CommandState string

CommandState classifies command lifecycle and fencing outcomes. 

const (
	CommandRunning      CommandState = "running"
	CommandSucceeded    CommandState = "succeeded"
	CommandFailed       CommandState = "failed"
	CommandCancelled    CommandState = "cancelled"
	CommandFenceUnknown CommandState = "fence_unknown"
)

Command states.

type CommandStatusResponse 

type CommandStatusResponse struct {
	CommandID       string       `json:"command_id"`
	State           CommandState `json:"state"`
	ExitCode        int          `json:"exit_code,omitempty"`
	Stdout          []byte       `json:"stdout,omitempty"`
	Stderr          []byte       `json:"stderr,omitempty"`
	NextOffset      int64        `json:"next_offset,omitempty"`
	Truncated       bool         `json:"truncated,omitempty"`
	TerminalReceipt string       `json:"terminal_receipt,omitempty"`
}

CommandStatusResponse carries bounded output and terminal proof.

type EmptyResponse 

type EmptyResponse struct{}

EmptyResponse is the successful response for operations without a payload.

type EnsureEnvironmentRequest 

type EnsureEnvironmentRequest struct {
	BindingID string `json:"binding_id"`
	Profile   string `json:"profile"`
	Owner     Owner  `json:"owner"`
}

EnsureEnvironmentRequest requests an idempotent environment allocation.

type EnsureEnvironmentResponse 

type EnsureEnvironmentResponse struct {
	Environment     EnvironmentRef `json:"environment"`
	Epoch           uint64         `json:"epoch"`
	Ready           bool           `json:"ready"`
	GrantGeneration uint64         `json:"grant_generation"`
	Grant           string         `json:"grant"`
	GrantExpiresAt  time.Time      `json:"grant_expires_at"`
}

EnsureEnvironmentResponse returns allocation identity, readiness, and a short-lived grant.

type EnvironmentRef 

type EnvironmentRef struct {
	ID       string `json:"id"`
	Revision string `json:"revision"`
}

EnvironmentRef is the provider-private durable environment identity.

type Error 

type Error struct {
	Code      ErrorCode `json:"code"`
	Message   string    `json:"message"`
	Retryable bool      `json:"retryable,omitempty"`
}

Error is a bounded structured private-protocol failure.

func (*Error) Error 

func (e *Error) Error() string

type ErrorCode 

type ErrorCode string

ErrorCode is a stable private-protocol error classification. 

const (
	CodeInvalidArgument   ErrorCode = "invalid_argument"
	CodeUnauthenticated   ErrorCode = "unauthenticated"
	CodePermissionDenied  ErrorCode = "permission_denied"
	CodeNotFound          ErrorCode = "not_found"
	CodeAlreadyExists     ErrorCode = "already_exists"
	CodeConflict          ErrorCode = "conflict"
	CodeVersionMismatch   ErrorCode = "version_mismatch"
	CodeDirectoryNotEmpty ErrorCode = "directory_not_empty"
	CodeNotReady          ErrorCode = "not_ready"
	CodeFenceUnknown      ErrorCode = "fence_unknown"
	CodeResourceExhausted ErrorCode = "resource_exhausted"
	CodeInternal          ErrorCode = "internal"
)

Private-protocol error codes.

func (ErrorCode) Valid 

func (c ErrorCode) Valid() bool

Valid reports whether c is part of the closed private-protocol vocabulary.

type ExecutorEnvelope 

type ExecutorEnvelope struct {
	Response *ExecutorResponse `json:"response,omitempty"`
	Error    *Error            `json:"error,omitempty"`
}

ExecutorEnvelope provides a terminal, credential-free result over pods/exec.

type ExecutorRequest 

type ExecutorRequest struct {
	Operation     Operation `json:"operation"`
	Path          string    `json:"path,omitempty"`
	Destination   string    `json:"destination,omitempty"`
	Pattern       string    `json:"pattern,omitempty"`
	Data          []byte    `json:"data,omitempty"`
	Version       string    `json:"version,omitempty"`
	Limit         int       `json:"limit,omitempty"`
	Command       string    `json:"command,omitempty"`
	CommandID     string    `json:"command_id,omitempty"`
	TimeoutMillis int64     `json:"timeout_ms,omitempty"`
}

ExecutorRequest is the credential-free provider-to-workload stdin protocol. It deliberately cannot select an environment, root, Pod, image, argv, or process environment.

type ExecutorResponse 

type ExecutorResponse struct {
	FileResponse
	Command *CommandStatusResponse `json:"command,omitempty"`
}

ExecutorResponse carries one credential-free helper result.

type FileInfo 

type FileInfo struct {
	Name    string    `json:"name"`
	Size    int64     `json:"size"`
	Mode    uint32    `json:"mode"`
	ModTime time.Time `json:"mod_time"`
	IsDir   bool      `json:"is_dir"`
}

FileInfo is bounded filesystem metadata returned by the helper.

type FileRequest 

type FileRequest struct {
	Context     RequestContext `json:"context"`
	Operation   Operation      `json:"operation"`
	Path        string         `json:"path"`
	Destination string         `json:"destination,omitempty"`
	Pattern     string         `json:"pattern,omitempty"`
	Data        []byte         `json:"data,omitempty"`
	Version     string         `json:"version,omitempty"`
	Limit       int            `json:"limit,omitempty"`
}

FileRequest carries one bounded, authorized filesystem operation.

type FileResponse 

type FileResponse struct {
	Data               []byte      `json:"data,omitempty"`
	Version            string      `json:"version,omitempty"`
	Info               *FileInfo   `json:"info,omitempty"`
	Entries            []FileInfo  `json:"entries,omitempty"`
	Paths              []string    `json:"paths,omitempty"`
	Matches            []GrepMatch `json:"matches,omitempty"`
	AuthorityTarget    string      `json:"authority_target,omitempty"`
	AuthorityWorkspace string      `json:"authority_workspace,omitempty"`
}

FileResponse carries the result of one filesystem operation.

type GrantClaims 

type GrantClaims struct {
	KeyID           string         `json:"-"`
	Issuer          string         `json:"iss"`
	Audience        string         `json:"aud"`
	Client          string         `json:"client"`
	OwnerHash       string         `json:"owner"`
	BindingID       string         `json:"binding_id"`
	RunID           string         `json:"run_id"`
	ClaimID         string         `json:"claim_id"`
	Environment     EnvironmentRef `json:"environment"`
	Epoch           uint64         `json:"epoch"`
	GrantGeneration uint64         `json:"grant_generation"`
	Operations      []Operation    `json:"operations"`
	NotBefore       time.Time      `json:"not_before"`
	ExpiresAt       time.Time      `json:"expires_at"`
	Nonce           string         `json:"nonce"`
}

GrantClaims binds a short-lived capability to one client, owner, environment, and epoch.

type GrantExpectation 

type GrantExpectation struct {
	Client          string
	OwnerHash       string
	BindingID       string
	RunID           string
	ClaimID         string
	Environment     EnvironmentRef
	Epoch           uint64
	GrantGeneration uint64
	Operation       Operation
}

GrantExpectation defines the exact binding and operation required by a request.

type GrantVerifier 

type GrantVerifier struct {
	Keys          map[string]ed25519.PublicKey
	RevokedKeys   map[string]struct{}
	RevokedNonces map[string]struct{}
	Issuer        string
	Audience      string
	MaxLifetime   time.Duration
	Now           func() time.Time
}

GrantVerifier verifies signed grants against configured trust and revocation state.

func (GrantVerifier) Verify 

func (v GrantVerifier) Verify(token string, e GrantExpectation) (GrantClaims, error)

Verify validates a grant and its exact request binding.

type GrepMatch 

type GrepMatch struct {
	Path string `json:"path"`
	Line int    `json:"line"`
	Text string `json:"text"`
}

GrepMatch is one bounded textual grep result.

type Operation 

type Operation string

Operation identifies one provider or workload-helper operation. 

const (
	OpAttach                 Operation = "attach"
	OpAcquireRun             Operation = "run.acquire"
	OpRenewRun               Operation = "run.renew"
	OpReleaseRun             Operation = "run.release"
	OpReferenceCommit        Operation = "reference.commit"
	OpReferenceAbort         Operation = "reference.abort"
	OpReferenceReserve       Operation = "reference.reserve"
	OpReferenceDeletePrepare Operation = "reference.delete.prepare"
	OpReferenceDeleteConfirm Operation = "reference.delete.confirm"
	OpReferenceDeleteCancel  Operation = "reference.delete.cancel"
	OpReferenceRelease       Operation = "reference.release"
	OpRetire                 Operation = "retire"
	OpFileRead               Operation = "file.read"
	OpFileResolveAuthority   Operation = "file.resolve_authority"
	OpFileStat               Operation = "file.stat"
	OpFileCreate             Operation = "file.create"
	OpFileReplace            Operation = "file.replace"
	OpFileList               Operation = "file.list"
	OpFileRemove             Operation = "file.remove"
	OpFileRename             Operation = "file.rename"
	OpFileCopy               Operation = "file.copy"
	OpFileGlob               Operation = "file.glob"
	OpFileGrep               Operation = "file.grep"
	OpCommandStart           Operation = "command.start"
	OpCommandStatus          Operation = "command.status"
	OpCommandCancel          Operation = "command.cancel"
	OpCommandStream          Operation = "command.stream"
)

Supported private-protocol operations.

func (Operation) Valid 

func (o Operation) Valid() bool

Valid reports whether the operation belongs to the closed protocol vocabulary.

type Owner 

type Owner struct {
	Issuer  string `json:"issuer"`
	Subject string `json:"subject"`
}

Owner is an authenticated principal attestation.

type ReferenceIntent 

type ReferenceIntent struct {
	Environment     EnvironmentRef
	Owner           Owner
	BindingID       string
	State           ReferenceState
	OperationID     string
	SourceBindingID string
	CreatedAt       time.Time
}

type ReferenceReleaseRequest 

type ReferenceReleaseRequest struct {
	Context RequestContext `json:"context"`
}

ReferenceReleaseRequest releases one durable binding reference.

type ReferenceRequest 

type ReferenceRequest struct {
	Environment     EnvironmentRef
	Owner           Owner
	BindingID       string
	SourceBindingID string
	OperationID     string
}

type ReferenceState 

type ReferenceState string
const (
	ReferencePendingCreate ReferenceState = "PendingCreate"
	ReferencePublished     ReferenceState = "Published"
	ReferencePendingDelete ReferenceState = "PendingDelete"
)

type RequestContext 

type RequestContext struct {
	Environment     EnvironmentRef `json:"environment"`
	Owner           Owner          `json:"owner"`
	BindingID       string         `json:"binding_id"`
	RunID           string         `json:"run_id"`
	ClaimID         string         `json:"claim_id"`
	Epoch           uint64         `json:"epoch"`
	GrantGeneration uint64         `json:"grant_generation"`
	Grant           string         `json:"grant"`
}

RequestContext carries the exact authorization binding for an operation.

type RetireEnvironmentRequest 

type RetireEnvironmentRequest struct {
	Environment    EnvironmentRef `json:"environment"`
	Owner          Owner          `json:"owner"`
	ExpectedEpoch  uint64         `json:"expected_execution_epoch"`
	ExpectedPodUID string         `json:"expected_pod_uid"`
	ExpectedPVCUID string         `json:"expected_pvc_uid"`
	OperationID    string         `json:"operation_id"`
}

RetireEnvironmentRequest requests controlled retirement without PVC deletion.

type RunClaim 

type RunClaim struct {
	Environment     EnvironmentRef
	BindingID       string
	RunID           string
	ClaimID         string
	Epoch           uint64
	GrantGeneration uint64
	Grant           string
	ExpiresAt       time.Time
}

type RunClaimRequest 

type RunClaimRequest struct {
	Environment     EnvironmentRef
	Owner           Owner
	BindingID       string
	RunID           string
	ClaimID         string
	Epoch           uint64
	GrantGeneration uint64
	OperationID     string
	TTL             time.Duration
}

type ValidateProfileRequest 

type ValidateProfileRequest struct {
	Profile string `json:"profile"`
}

ValidateProfileRequest selects an operator-defined profile for validation.

type ValidateProfileResponse 

type ValidateProfileResponse struct {
	Profile                  string   `json:"profile"`
	Digest                   string   `json:"digest"`
	Capabilities             []string `json:"capabilities"`
	MaxFileBytes             int64    `json:"max_file_bytes"`
	MaxCommandBytes          int64    `json:"max_command_bytes"`
	MaxCommandDurationMillis int64    `json:"max_command_duration_ms"`
}

ValidateProfileResponse reports immutable profile capabilities and bounds.

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.