Documentation
¶
Index ¶
- func IsContainerCreateEvent(event StreamEvent) bool
- func IsContainerRemoveEvent(event StreamEvent) bool
- func IsHeartbeatEvent(event StreamEvent) bool
- func IsOutputEvent(event StreamEvent) bool
- func IsProcessEndEvent(event StreamEvent) bool
- func IsProcessErrorEvent(event StreamEvent) bool
- func IsProcessLifecycleEvent(event StreamEvent) bool
- func IsProcessStartEvent(event StreamEvent) bool
- func IsProgramStatusEvent(event StreamEvent) bool
- func IsTerminalResizeEvent(event StreamEvent) bool
- func ToAscicastV3(events iter.Seq2[Event, error], metadata AscicastV3Metadata) iter.Seq2[AscicastV3Line, error]
- func WriteAscicastV3(events iter.Seq2[Event, error], metadata AscicastV3Metadata, ...) error
- type AscicastV3Event
- type AscicastV3Header
- type AscicastV3Line
- type AscicastV3Metadata
- type BufferWriter
- type Cancellor
- type ContainerCreate
- type ContainerMount
- type ContainerProcess
- type ContainerProcessOption
- func WithContainerEnv(env []string) ContainerProcessOption
- func WithContainerEnvMap(envMap map[string]string) ContainerProcessOption
- func WithContainerFlushInterval(interval time.Duration) ContainerProcessOption
- func WithContainerHeartbeatInterval(interval time.Duration) ContainerProcessOption
- func WithContainerImage(image string) ContainerProcessOption
- func WithContainerMaxBufferSize(size int) ContainerProcessOption
- func WithContainerMeter(meter metric.Meter) ContainerProcessOption
- func WithContainerMount(source, target string, readOnly bool) ContainerProcessOption
- func WithContainerProgramStatus() ContainerProcessOption
- func WithContainerRuntime(runtime string) ContainerProcessOption
- func WithContainerWorkingDir(dir string) ContainerProcessOption
- type ContainerRemove
- type Event
- type EventType
- type HeartbeatEvent
- type ImagePullComplete
- type ImagePullProgress
- type ImagePullStart
- type LocalCancellor
- type OutputData
- type OutputSegment
- type Process
- type ProcessEnd
- type ProcessError
- type ProcessInfo
- type ProcessMode
- type ProcessOption
- func WithCancellor(cancellor Cancellor) ProcessOption
- func WithEnv(env []string) ProcessOption
- func WithEnvMap(envMap map[string]string) ProcessOption
- func WithEnvVar(key, value string) ProcessOption
- func WithFlushInterval(interval time.Duration) ProcessOption
- func WithHeartbeatInterval(interval time.Duration) ProcessOption
- func WithMaxBufferSize(size int) ProcessOption
- func WithMeter(meter metric.Meter) ProcessOption
- func WithPTYMode() ProcessOption
- func WithPTYSize(size *pty.Winsize) ProcessOption
- func WithPipeMode() ProcessOption
- func WithProgramStatus() ProcessOption
- func WithWorkingDir(dir string) ProcessOption
- type ProcessStart
- type ProcessStartError
- type ProcessStats
- func (s *ProcessStats) GetSnapshot() ProcessStatsSnapshot
- func (s *ProcessStats) RecordError(ctx context.Context, eventType string)
- func (s *ProcessStats) RecordEvent(ctx context.Context, eventType string)
- func (s *ProcessStats) RecordOutput(ctx context.Context, dataSize int64)
- func (s *ProcessStats) SetExitCode(code int)
- func (s *ProcessStats) Start(ctx context.Context)
- func (s *ProcessStats) Stop(ctx context.Context)
- type ProcessStatsSnapshot
- type ProgramStatus
- type StreamEvent
- type TermInfo
- type TermTheme
- type TerminalResizeEvent
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsContainerCreateEvent ¶ added in v0.4.0
func IsContainerCreateEvent(event StreamEvent) bool
func IsContainerRemoveEvent ¶ added in v0.4.0
func IsContainerRemoveEvent(event StreamEvent) bool
func IsHeartbeatEvent ¶
func IsHeartbeatEvent(event StreamEvent) bool
func IsOutputEvent ¶ added in v0.3.0
func IsOutputEvent(event StreamEvent) bool
func IsProcessEndEvent ¶
func IsProcessEndEvent(event StreamEvent) bool
func IsProcessErrorEvent ¶
func IsProcessErrorEvent(event StreamEvent) bool
func IsProcessLifecycleEvent ¶
func IsProcessLifecycleEvent(event StreamEvent) bool
func IsProcessStartEvent ¶
func IsProcessStartEvent(event StreamEvent) bool
func IsProgramStatusEvent ¶ added in v0.6.0
func IsProgramStatusEvent(event StreamEvent) bool
func IsTerminalResizeEvent ¶
func IsTerminalResizeEvent(event StreamEvent) bool
func ToAscicastV3 ¶
func ToAscicastV3(events iter.Seq2[Event, error], metadata AscicastV3Metadata) iter.Seq2[AscicastV3Line, error]
ToAscicastV3 transforms a stream of console-stream events into asciicast v3 format
func WriteAscicastV3 ¶
func WriteAscicastV3(events iter.Seq2[Event, error], metadata AscicastV3Metadata, writeFunc func([]byte) error) error
WriteAscicastV3 is a convenience function to write asciicast v3 to any writer
Types ¶
type AscicastV3Event ¶
type AscicastV3Event [3]any
AscicastV3Event represents an event line in asciicast v3 format: [interval, code, data]
func NewExitEvent ¶
func NewExitEvent(interval float64, exitCode int) AscicastV3Event
NewExitEvent creates an asciicast exit event
func NewMarkerEvent ¶ added in v0.5.0
func NewMarkerEvent(interval float64, label string) AscicastV3Event
NewMarkerEvent creates an asciicast marker event
func NewOutputEvent ¶
func NewOutputEvent(interval float64, data string) AscicastV3Event
NewOutputEvent creates an asciicast output event
func NewResizeEvent ¶
func NewResizeEvent(interval float64, cols, rows uint16) AscicastV3Event
NewResizeEvent creates an asciicast resize event
func (AscicastV3Event) MarshalJSON ¶
func (e AscicastV3Event) MarshalJSON() ([]byte, error)
MarshalJSON implements AscicastV3Line interface for events
type AscicastV3Header ¶
type AscicastV3Header struct {
Version int `json:"version"`
AscicastV3Metadata
}
AscicastV3Header represents the first line of an asciicast v3 file
func (AscicastV3Header) MarshalJSON ¶
func (h AscicastV3Header) MarshalJSON() ([]byte, error)
MarshalJSON implements AscicastV3Line interface for headers
type AscicastV3Line ¶
AscicastV3Line represents either a header or event line in asciicast v3 format
type AscicastV3Metadata ¶
type AscicastV3Metadata struct {
Term TermInfo `json:"term"`
Timestamp *int64 `json:"timestamp,omitempty"`
Command string `json:"command,omitempty"`
Title string `json:"title,omitempty"`
Env map[string]string `json:"env,omitempty"`
Tags []string `json:"tags,omitempty"`
}
AscicastV3Metadata contains the metadata for the asciicast header
type BufferWriter ¶ added in v0.2.0
type BufferWriter struct {
// contains filtered or unexported fields
}
BufferWriter wraps buffer operations and implements io.WriteCloser This can be used by both PipeProcess and PTYProcess for consistent buffer management
func NewBufferWriter ¶ added in v0.2.0
func NewBufferWriter(flushChan chan<- struct{}, maxBufferSize int) *BufferWriter
func (*BufferWriter) Close ¶ added in v0.2.0
func (w *BufferWriter) Close() error
func (*BufferWriter) FlushAndClear ¶ added in v0.2.0
func (w *BufferWriter) FlushAndClear() []byte
FlushAndClear returns the current buffer contents and clears it (including segments)
func (*BufferWriter) FlushSegments ¶ added in v0.5.0
func (w *BufferWriter) FlushSegments() ([]byte, []OutputSegment)
FlushSegments returns copies of the buffer contents and their read segments, clearing both (and any pending statuses). It returns nil, nil when the buffer is empty.
func (*BufferWriter) Len ¶ added in v0.2.0
func (w *BufferWriter) Len() int
Len returns the current buffer length (thread-safe)
type ContainerCreate ¶ added in v0.4.0
ContainerCreate represents container creation
func (*ContainerCreate) String ¶ added in v0.4.0
func (c *ContainerCreate) String() string
func (*ContainerCreate) Type ¶ added in v0.4.0
func (c *ContainerCreate) Type() EventType
type ContainerMount ¶ added in v0.4.0
ContainerMount represents a volume mount for container processes
type ContainerProcess ¶ added in v0.4.0
type ContainerProcess struct {
// contains filtered or unexported fields
}
ContainerProcess represents a process running inside a container
func NewContainerProcess ¶ added in v0.4.0
func NewContainerProcess(cmd string, args []string, opts ...ContainerProcessOption) *ContainerProcess
NewContainerProcess creates a new container process with functional options
func (*ContainerProcess) ExecuteAndStream ¶ added in v0.4.0
ExecuteAndStream starts a container and returns an iterator over Event objects
type ContainerProcessOption ¶ added in v0.4.0
type ContainerProcessOption func(*containerProcessConfig)
ContainerProcessOption represents a functional option for configuring container processes
func WithContainerEnv ¶ added in v0.4.0
func WithContainerEnv(env []string) ContainerProcessOption
WithContainerEnv sets environment variables as a slice of "KEY=value" strings
func WithContainerEnvMap ¶ added in v0.4.0
func WithContainerEnvMap(envMap map[string]string) ContainerProcessOption
WithContainerEnvMap sets environment variables from a map for convenience
func WithContainerFlushInterval ¶ added in v0.4.0
func WithContainerFlushInterval(interval time.Duration) ContainerProcessOption
WithContainerFlushInterval sets the output batch interval (default 1s): how often buffered output is delivered as an OutputData event. It bounds live delivery latency and event volume. It does not affect timing accuracy: each event's Segments record when output was read.
func WithContainerHeartbeatInterval ¶ added in v0.5.1
func WithContainerHeartbeatInterval(interval time.Duration) ContainerProcessOption
WithContainerHeartbeatInterval sets the heartbeat interval (default 1s). On each interval tick, a HeartbeatEvent is emitted if no output was delivered or buffered since the previous tick, so the first heartbeat follows one to two intervals of silence and repeats every interval. Independent of the batch interval.
func WithContainerImage ¶ added in v0.4.0
func WithContainerImage(image string) ContainerProcessOption
WithContainerImage sets the container image to use (REQUIRED for container processes)
func WithContainerMaxBufferSize ¶ added in v0.4.0
func WithContainerMaxBufferSize(size int) ContainerProcessOption
WithContainerMaxBufferSize sets the maximum batch size (default 10MB): output is delivered as soon as the buffer reaches it, without waiting for the interval.
func WithContainerMeter ¶ added in v0.4.0
func WithContainerMeter(meter metric.Meter) ContainerProcessOption
WithContainerMeter sets an OpenTelemetry meter for metrics collection for container processes
func WithContainerMount ¶ added in v0.4.0
func WithContainerMount(source, target string, readOnly bool) ContainerProcessOption
WithContainerMount adds a volume mount to the container
func WithContainerProgramStatus ¶ added in v0.6.0
func WithContainerProgramStatus() ContainerProcessOption
WithContainerProgramStatus enables parsing of OSC 7501 program status reports in the container output. Each report yields a ProgramStatus event, ordered exactly against OutputData. The report bytes still pass through unchanged in OutputData.
func WithContainerRuntime ¶ added in v0.4.0
func WithContainerRuntime(runtime string) ContainerProcessOption
WithContainerRuntime sets the container runtime ("docker" or "podman")
func WithContainerWorkingDir ¶ added in v0.4.0
func WithContainerWorkingDir(dir string) ContainerProcessOption
WithContainerWorkingDir sets the working directory for the container process
type ContainerRemove ¶ added in v0.4.0
type ContainerRemove struct {
ContainerID string
}
ContainerRemove represents container cleanup
func (*ContainerRemove) String ¶ added in v0.4.0
func (c *ContainerRemove) String() string
func (*ContainerRemove) Type ¶ added in v0.4.0
func (c *ContainerRemove) Type() EventType
type Event ¶
type Event struct {
Timestamp time.Time
Event StreamEvent
}
type HeartbeatEvent ¶
HeartbeatEvent represents a keep-alive signal when no output is generated
func (*HeartbeatEvent) String ¶
func (h *HeartbeatEvent) String() string
func (*HeartbeatEvent) Type ¶
func (h *HeartbeatEvent) Type() EventType
type ImagePullComplete ¶ added in v0.4.0
ImagePullComplete represents successful completion of an image pull
func (*ImagePullComplete) String ¶ added in v0.4.0
func (i *ImagePullComplete) String() string
func (*ImagePullComplete) Type ¶ added in v0.4.0
func (i *ImagePullComplete) Type() EventType
type ImagePullProgress ¶ added in v0.4.0
type ImagePullProgress struct {
Image string
Status string
PercentComplete int
BytesDownloaded int64
BytesTotal int64
}
ImagePullProgress represents progress during an image pull
func (*ImagePullProgress) String ¶ added in v0.4.0
func (i *ImagePullProgress) String() string
func (*ImagePullProgress) Type ¶ added in v0.4.0
func (i *ImagePullProgress) Type() EventType
type ImagePullStart ¶ added in v0.4.0
type ImagePullStart struct {
Image string
}
ImagePullStart represents the beginning of an image pull operation
func (*ImagePullStart) String ¶ added in v0.4.0
func (i *ImagePullStart) String() string
func (*ImagePullStart) Type ¶ added in v0.4.0
func (i *ImagePullStart) Type() EventType
type LocalCancellor ¶
type LocalCancellor struct {
// contains filtered or unexported fields
}
LocalCancellor implements process cancellation for local processes.
Cancel signals the whole process group led by pid (kill(-pid)), so grandchildren spawned by the process are terminated with it. Processes started by this library are group leaders (Setpgid for pipes, Setsid for PTYs). If pid is not a group leader, Cancel falls back to signalling pid alone.
Limitation: PTY children that create their own job-control process groups (for example interactive shells) have descendants outside the group, which the group kill does not reach.
func NewLocalCancellor ¶
func NewLocalCancellor(terminateTimeout time.Duration) *LocalCancellor
type OutputData ¶ added in v0.3.0
type OutputData struct {
Data []byte
// Segments carries per-read timing for Data; may be nil for events not
// produced by this library.
Segments []OutputSegment
}
OutputData represents output data from the process (combined stdout/stderr)
func (*OutputData) String ¶ added in v0.3.0
func (o *OutputData) String() string
func (*OutputData) Type ¶ added in v0.3.0
func (o *OutputData) Type() EventType
type OutputSegment ¶ added in v0.5.0
OutputSegment marks where a write into the output buffer began and when it was read. Segment i covers Data[Offset_i:Offset_{i+1}] (the last runs to len(Data)).
type Process ¶ added in v0.3.0
type Process struct {
// contains filtered or unexported fields
}
Process represents a unified process that can run in either PTY or pipe mode
func NewProcess ¶ added in v0.3.0
func NewProcess(cmd string, args []string, opts ...ProcessOption) *Process
NewProcess creates a new unified process with functional options. Children run in their own process group (pipe: Setpgid, PTY: Setsid) and so do not receive terminal-generated signals; cancel the ExecuteAndStream context on SIGINT/SIGTERM (e.g. signal.NotifyContext) to stop them.
func (*Process) ExecuteAndStream ¶ added in v0.3.0
ExecuteAndStream starts a process and returns an iterator over Event objects.
The child runs in its own process group (pipe mode: Setpgid; PTY mode: Setsid), so it does not receive terminal-generated signals such as Ctrl-C. Callers should cancel ctx on SIGINT/SIGTERM (e.g. signal.NotifyContext) so the Cancellor can stop the child and its descendants.
Breaking out of the loop or cancelling ctx stops the child via the Cancellor and waits for all goroutines to finish before the iterator returns.
func (*Process) GetStats ¶ added in v0.3.0
func (p *Process) GetStats() ProcessStatsSnapshot
GetStats returns a copy of the current process statistics
type ProcessEnd ¶
ProcessEnd represents the completion of process execution
func (*ProcessEnd) String ¶
func (p *ProcessEnd) String() string
func (*ProcessEnd) Type ¶
func (p *ProcessEnd) Type() EventType
type ProcessError ¶
ProcessError represents an error during process execution
func (*ProcessError) String ¶
func (p *ProcessError) String() string
func (*ProcessError) Type ¶
func (p *ProcessError) Type() EventType
type ProcessInfo ¶ added in v0.2.1
ProcessInfo contains process information for metrics attributes
type ProcessMode ¶ added in v0.3.0
type ProcessMode int
processConfig holds configuration options for processes ProcessMode defines whether to use PTY or pipe mode for process execution
const ( PipeMode ProcessMode = iota PTYMode )
func (ProcessMode) String ¶ added in v0.3.0
func (m ProcessMode) String() string
type ProcessOption ¶
type ProcessOption func(*processConfig)
ProcessOption represents a functional option for configuring processes
func WithCancellor ¶
func WithCancellor(cancellor Cancellor) ProcessOption
WithCancellor sets a custom cancellor for the process
func WithEnv ¶
func WithEnv(env []string) ProcessOption
WithEnv sets environment variables as a slice of "KEY=value" strings
func WithEnvMap ¶
func WithEnvMap(envMap map[string]string) ProcessOption
WithEnvMap sets environment variables from a map for convenience
func WithEnvVar ¶
func WithEnvVar(key, value string) ProcessOption
WithEnvVar sets a single environment variable
func WithFlushInterval ¶
func WithFlushInterval(interval time.Duration) ProcessOption
WithFlushInterval sets the output batch interval (default 1s): how often buffered output is delivered as an OutputData event. It bounds live delivery latency and event volume. It does not affect timing accuracy: each event's Segments record when output was read.
func WithHeartbeatInterval ¶ added in v0.5.1
func WithHeartbeatInterval(interval time.Duration) ProcessOption
WithHeartbeatInterval sets the heartbeat interval (default 1s). On each interval tick, a HeartbeatEvent is emitted if no output was delivered or buffered since the previous tick, so the first heartbeat follows one to two intervals of silence and repeats every interval. Independent of the batch interval.
func WithMaxBufferSize ¶
func WithMaxBufferSize(size int) ProcessOption
WithMaxBufferSize sets the maximum batch size (default 10MB): output is delivered as soon as the buffer reaches it, without waiting for the interval.
func WithMeter ¶ added in v0.2.1
func WithMeter(meter metric.Meter) ProcessOption
WithMeter sets an OpenTelemetry meter for metrics collection
func WithPTYMode ¶ added in v0.3.0
func WithPTYMode() ProcessOption
WithPTYMode sets the process to use a pseudo-terminal
func WithPTYSize ¶
func WithPTYSize(size *pty.Winsize) ProcessOption
WithPTYSize sets a custom terminal size for PTY processes
func WithPipeMode ¶ added in v0.3.0
func WithPipeMode() ProcessOption
WithPipeMode sets the process to use standard pipes (stdout/stderr)
func WithProgramStatus ¶ added in v0.6.0
func WithProgramStatus() ProcessOption
WithProgramStatus enables parsing of OSC 7501 program status reports in the child output. Each report yields a ProgramStatus event, ordered exactly against OutputData. The report bytes still pass through unchanged in OutputData.
func WithWorkingDir ¶ added in v0.3.2
func WithWorkingDir(dir string) ProcessOption
WithWorkingDir sets the working directory for the process
type ProcessStart ¶
ProcessStart represents the beginning of process execution
func (*ProcessStart) String ¶
func (p *ProcessStart) String() string
func (*ProcessStart) Type ¶
func (p *ProcessStart) Type() EventType
type ProcessStartError ¶
Error types for different process failure scenarios
func (ProcessStartError) Error ¶
func (e ProcessStartError) Error() string
type ProcessStats ¶ added in v0.3.0
type ProcessStats struct {
// contains filtered or unexported fields
}
ProcessStats manages comprehensive metrics during process execution
func NewProcessStats ¶ added in v0.3.0
func NewProcessStats(meter metric.Meter, processInfo ProcessInfo) (*ProcessStats, error)
NewProcessStats creates a new ProcessStats instance with OpenTelemetry metrics
func (*ProcessStats) GetSnapshot ¶ added in v0.3.0
func (s *ProcessStats) GetSnapshot() ProcessStatsSnapshot
GetSnapshot returns a thread-safe snapshot of the current statistics
func (*ProcessStats) RecordError ¶ added in v0.3.0
func (s *ProcessStats) RecordError(ctx context.Context, eventType string)
RecordError increments the error count
func (*ProcessStats) RecordEvent ¶ added in v0.3.0
func (s *ProcessStats) RecordEvent(ctx context.Context, eventType string)
RecordEvent records a general event
func (*ProcessStats) RecordOutput ¶ added in v0.3.0
func (s *ProcessStats) RecordOutput(ctx context.Context, dataSize int64)
RecordOutput records output data and metrics
func (*ProcessStats) SetExitCode ¶ added in v0.3.0
func (s *ProcessStats) SetExitCode(code int)
SetExitCode sets the process exit code
func (*ProcessStats) Start ¶ added in v0.3.0
func (s *ProcessStats) Start(ctx context.Context)
Start initializes the stats and records process start
func (*ProcessStats) Stop ¶ added in v0.3.0
func (s *ProcessStats) Stop(ctx context.Context)
Stop finalizes the stats and records process stop
type ProcessStatsSnapshot ¶ added in v0.3.0
type ProcessStatsSnapshot struct {
// Basic execution stats
StartTime time.Time
EventCount int
ErrorCount int
ExitCode *int
Duration time.Duration
}
ProcessStatsSnapshot represents a point-in-time view of process statistics
type ProgramStatus ¶ added in v0.6.0
type ProgramStatus struct {
State string // e.g. working, blocked, done
ID string
Kind string
App string
Title string // decoded
Msg string // decoded
Progress int // 0-100, or -1 if indeterminate
}
ProgramStatus is a typed OSC 7501 program status report found in the child output. It is yielded after the OutputData holding all preceding bytes and before any following bytes. Timestamp is when the report was read.
func (*ProgramStatus) String ¶ added in v0.6.0
func (p *ProgramStatus) String() string
func (*ProgramStatus) Type ¶ added in v0.6.0
func (p *ProgramStatus) Type() EventType
type StreamEvent ¶
StreamEvent represents different types of events that can occur during process execution
type TermInfo ¶
type TermInfo struct {
Cols int `json:"cols"`
Rows int `json:"rows"`
Type string `json:"type,omitempty"`
Version string `json:"version,omitempty"`
Theme *TermTheme `json:"theme,omitempty"`
}
TermInfo represents terminal dimensions for asciicast header
type TermTheme ¶ added in v0.5.0
type TermTheme struct {
Fg string `json:"fg"`
Bg string `json:"bg"`
Palette string `json:"palette"`
}
TermTheme describes terminal colours. Palette is a colon-separated list of hex colours, as asciinema writes it.
type TerminalResizeEvent ¶
type TerminalResizeEvent struct {
Rows uint16
Cols uint16
X uint16 // Width in pixels
Y uint16 // Height in pixels
}
TerminalResizeEvent represents a terminal window size change
func (*TerminalResizeEvent) String ¶
func (t *TerminalResizeEvent) String() string
func (*TerminalResizeEvent) Type ¶
func (t *TerminalResizeEvent) Type() EventType
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
runner
command
Package main provides a pretty slog handler for human-readable colored terminal output.
|
Package main provides a pretty slog handler for human-readable colored terminal output. |
|
tester
command
|
|
|
example
|
|
|
asciicast
command
|
|
|
buffering
command
|
|
|
burst
command
|
|
|
container
command
|
|
|
logging
command
|
|
|
pty
command
|
|
|
simple
command
|
|
|
stream
command
|
|
|
internal
|
|
|
osc7501
Package osc7501 parses the OSC 7501 "program status" terminal protocol (rev 0.4, https://www.superlogical.com/rex/docs/build/program-status).
|
Package osc7501 parses the OSC 7501 "program status" terminal protocol (rev 0.4, https://www.superlogical.com/rex/docs/build/program-status). |