cliwrap

package
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: Apr 10, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package cliwrap re-exports the canonical types from internal/cwtypes via Go type aliases, so the public API surface is unchanged.

Index

Constants

View Source 
const (
	RestartNever     = cwtypes.RestartNever
	RestartOnFailure = cwtypes.RestartOnFailure
	RestartAlways    = cwtypes.RestartAlways

	ExceedWarn     = cwtypes.ExceedWarn
	ExceedThrottle = cwtypes.ExceedThrottle
	ExceedKill     = cwtypes.ExceedKill

	StdinNone    = cwtypes.StdinNone
	StdinPipe    = cwtypes.StdinPipe
	StdinInherit = cwtypes.StdinInherit

	StatePending    = cwtypes.StatePending
	StateStarting   = cwtypes.StateStarting
	StateRunning    = cwtypes.StateRunning
	StateStopping   = cwtypes.StateStopping
	StateStopped    = cwtypes.StateStopped
	StateCrashed    = cwtypes.StateCrashed
	StateRestarting = cwtypes.StateRestarting
	StateFailed     = cwtypes.StateFailed
)

Re-exported constants.

Variables

View Source 
var (
	ErrProcessNotFound         = errors.New("cliwrap: process not found")
	ErrProcessAlreadyExists    = errors.New("cliwrap: process already exists")
	ErrProcessNotRunning       = errors.New("cliwrap: process not running")
	ErrProcessAlreadyRunning   = errors.New("cliwrap: process already running")
	ErrManagerShuttingDown     = errors.New("cliwrap: manager is shutting down")
	ErrManagerClosed           = errors.New("cliwrap: manager is closed")
	ErrSandboxProviderNotFound = errors.New("cliwrap: sandbox provider not registered")
	ErrAgentSpawnFailed        = errors.New("cliwrap: failed to spawn agent")
	ErrHandshakeTimeout        = errors.New("cliwrap: handshake timeout")
	ErrStopTimeout             = errors.New("cliwrap: stop timeout")

	// ErrInvalidSpec is re-exported from cwtypes so that
	// SpecValidationError.Is(ErrInvalidSpec) works across both packages.
	ErrInvalidSpec = cwtypes.ErrInvalidSpec
)

Sentinel errors.

Functions

This section is empty.

Types

type ExceedAction 

type ExceedAction = cwtypes.ExceedAction

Type aliases — these are transparent to callers. Users continue to write cliwrap.State, cliwrap.Spec, etc.

type LogChunk added in v0.2.0 

type LogChunk = cwtypes.LogChunk

LogChunk is an alias for cwtypes.LogChunk, re-exported so public callers of pkg/cliwrap see a cliwrap.LogChunk type while the canonical definition lives in the leaf cwtypes package (which internal/mgmt can import without creating a cycle).

type LogOptions 

type LogOptions = cwtypes.LogOptions

Type aliases — these are transparent to callers. Users continue to write cliwrap.State, cliwrap.Spec, etc.

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager is the top-level library entry point.

func NewManager 

func NewManager(opts ...ManagerOption) (*Manager, error)

NewManager constructs a Manager with the given options.

func (*Manager) ChildPIDs 

func (m *Manager) ChildPIDs() map[string]int

ChildPIDs returns a snapshot of running (process ID -> child PID) pairs. Processes that are not in StateRunning are omitted.

func (*Manager) Events 

func (m *Manager) Events() event.Bus

Events returns the Manager's event bus. Subscribers receive lifecycle, log, and reliability events. The bus is lazily created on first call.

func (*Manager) List 

func (m *Manager) List() []mgmt.ListEntry

List returns a snapshot of every registered process for the mgmt API.

func (*Manager) LogsSnapshot added in v0.2.0 

func (m *Manager) LogsSnapshot(id string, stream uint8) []byte

LogsSnapshot is the mgmt API entry that returns the current ring-buffer contents for a (process, stream) pair. Returns nil if no logs have been recorded for that pair yet.

func (*Manager) Register 

func (m *Manager) Register(spec Spec) (ProcessHandle, error)

Register validates and registers a process spec.

func (*Manager) Shutdown 

func (m *Manager) Shutdown(ctx context.Context) error

Shutdown stops every process and releases resources.

func (*Manager) StatusOf 

func (m *Manager) StatusOf(id string) (mgmt.ListEntry, error)

StatusOf returns the status of a specific process for the mgmt API.

func (*Manager) Stop 

func (m *Manager) Stop(ctx context.Context, id string) error

Stop is the mgmt API entry that routes a stop request to the handle.

func (*Manager) WatchLogs added in v0.2.0 

func (m *Manager) WatchLogs(processID string) (chunks <-chan LogChunk, unregister func())

WatchLogs registers a follow-mode subscription. The returned channel receives LogChunk values for every subsequent call to emitLogChunk whose processID matches the filter. An empty processID filter matches every process.

The caller MUST invoke the returned unregister function exactly once when done — this is typically done via defer. Failing to unregister leaks the subscription and the goroutine that reads from it.

The channel is buffered; emit-side fan-out is non-blocking, so slow consumers lose chunks rather than backpressuring the producer.

type ManagerOption 

type ManagerOption func(*Manager)

ManagerOption mutates a Manager during construction.

func WithAgentPath 

func WithAgentPath(path string) ManagerOption

WithAgentPath sets the absolute path to the cliwrap-agent binary.

func WithRuntimeDir 

func WithRuntimeDir(path string) ManagerOption

WithRuntimeDir sets the directory for per-process state (WAL, logs).

type ProcessHandle 

type ProcessHandle interface {
	ID() string
	Spec() Spec
	Status() Status
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
	Close(ctx context.Context) error
}

ProcessHandle is the user-facing handle to a managed process.

type ResourceLimits 

type ResourceLimits = cwtypes.ResourceLimits

Type aliases — these are transparent to callers. Users continue to write cliwrap.State, cliwrap.Spec, etc.

type RestartPolicy 

type RestartPolicy = cwtypes.RestartPolicy

Type aliases — these are transparent to callers. Users continue to write cliwrap.State, cliwrap.Spec, etc.

type SandboxSpec 

type SandboxSpec = cwtypes.SandboxSpec

Type aliases — these are transparent to callers. Users continue to write cliwrap.State, cliwrap.Spec, etc.

type Spec 

type Spec = cwtypes.Spec

Type aliases — these are transparent to callers. Users continue to write cliwrap.State, cliwrap.Spec, etc.

type SpecBuilder 

type SpecBuilder struct {
	// contains filtered or unexported fields
}

SpecBuilder is a fluent constructor for Spec. Errors surface only from Build.

func NewSpec 

func NewSpec(id, cmd string, args ...string) *SpecBuilder

NewSpec starts a new SpecBuilder for the given ID, command, and arguments.

func (*SpecBuilder) Build 

func (b *SpecBuilder) Build() (Spec, error)

Build validates and returns the Spec.

func (*SpecBuilder) WithEnv 

func (b *SpecBuilder) WithEnv(k, v string) *SpecBuilder

WithEnv sets a single environment variable.

func (*SpecBuilder) WithLogOptions 

func (b *SpecBuilder) WithLogOptions(o LogOptions) *SpecBuilder

WithLogOptions attaches log storage options.

func (*SpecBuilder) WithMaxRestarts 

func (b *SpecBuilder) WithMaxRestarts(n int) *SpecBuilder

WithMaxRestarts limits how many restarts will be attempted.

func (*SpecBuilder) WithResourceLimits 

func (b *SpecBuilder) WithResourceLimits(l ResourceLimits) *SpecBuilder

WithResourceLimits attaches resource caps.

func (*SpecBuilder) WithRestart 

func (b *SpecBuilder) WithRestart(p RestartPolicy) *SpecBuilder

WithRestart sets the restart policy.

func (*SpecBuilder) WithRestartBackoff 

func (b *SpecBuilder) WithRestartBackoff(d time.Duration) *SpecBuilder

WithRestartBackoff sets the initial backoff delay between restarts.

func (*SpecBuilder) WithSandbox 

func (b *SpecBuilder) WithSandbox(s *SandboxSpec) *SpecBuilder

WithSandbox attaches a sandbox spec.

func (*SpecBuilder) WithStdin 

func (b *SpecBuilder) WithStdin(m StdinMode) *SpecBuilder

WithStdin selects how the child's stdin is wired.

func (*SpecBuilder) WithStopTimeout 

func (b *SpecBuilder) WithStopTimeout(d time.Duration) *SpecBuilder

WithStopTimeout sets the SIGTERM → SIGKILL grace period.

func (*SpecBuilder) WithWorkDir 

func (b *SpecBuilder) WithWorkDir(path string) *SpecBuilder

WithWorkDir sets the working directory for the child process.

type SpecValidationError 

type SpecValidationError = cwtypes.SpecValidationError

Type aliases — these are transparent to callers. Users continue to write cliwrap.State, cliwrap.Spec, etc.

type State 

type State = cwtypes.State

Type aliases — these are transparent to callers. Users continue to write cliwrap.State, cliwrap.Spec, etc.

type Status 

type Status = cwtypes.Status

Type aliases — these are transparent to callers. Users continue to write cliwrap.State, cliwrap.Spec, etc.

type StdinMode 

type StdinMode = cwtypes.StdinMode

Type aliases — these are transparent to callers. Users continue to write cliwrap.State, cliwrap.Spec, etc.

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.