process

Documentation

Overview

Package process - Log capture and exposure functionality

Package process provides robust subprocess management with health monitoring, output streaming, and lifecycle management following SOLID principles.

Package process - Manager extensions for log capture and exposure

Index

• type Config
• type LogBuffer
  • func NewLogBuffer(capacity int) *LogBuffer
  • func (lb *LogBuffer) Append(entry LogEntry)
  • func (lb *LogBuffer) Clear()
  • func (lb *LogBuffer) Close() error
  • func (lb *LogBuffer) GetAllFromFile() ([]string, error)
  • func (lb *LogBuffer) GetByStream(stream string, n int) []LogEntry
  • func (lb *LogBuffer) GetLogFilePath() string
  • func (lb *LogBuffer) GetRecent(n int) []LogEntry
  • func (lb *LogBuffer) GetSince(since time.Time) []LogEntry
  • func (lb *LogBuffer) GetStats() LogStats
  • func (lb *LogBuffer) ToJSON(n int) ([]byte, error)
• type LogCaptureConfig
  • func DefaultLogCaptureConfig() LogCaptureConfig
• type LogEntry
• type LogStats
• type Manager
  • func NewManager(cfg Config, log *logger.Logger) (*Manager, error)
  • func (m *Manager) GetCommand() []string
  • func (m *Manager) GetPID() int
  • func (m *Manager) GetState() ProcessState
  • func (m *Manager) GetUptime() time.Duration
  • func (m *Manager) GetWorkDir() string
  • func (m *Manager) IsRunning() bool
  • func (m *Manager) Start(ctx context.Context) error
  • func (m *Manager) Stop() error
• type ManagerWithLogs
  • func NewManagerWithLogs(cfg Config, logCfg LogCaptureConfig, log *logger.Logger) (*ManagerWithLogs, error)
  • func (m *ManagerWithLogs) AddErrorLog(message string)
  • func (m *ManagerWithLogs) ClearLogs()
  • func (m *ManagerWithLogs) CloseLogFile() error
  • func (m *ManagerWithLogs) GetAllLogsFromFile() ([]string, error)
  • func (m *ManagerWithLogs) GetLogFilePath() string
  • func (m *ManagerWithLogs) GetLogStats() LogStats
  • func (m *ManagerWithLogs) GetLogsByStream(stream string, n int) []LogEntry
  • func (m *ManagerWithLogs) GetLogsJSON(n int) ([]byte, error)
  • func (m *ManagerWithLogs) GetLogsSince(since time.Time) []LogEntry
  • func (m *ManagerWithLogs) GetRecentLogs(n int) []LogEntry
  • func (m *ManagerWithLogs) StreamLogs(ctx context.Context) <-chan LogEntry
• type OutputHandler
• type ProcessState
• type ReadyChecker

Types

type Config

type Config struct {
	Command       []string          // Command and arguments to execute
	Env           map[string]string // Additional environment variables
	WorkDir       string            // Working directory
	ReadyTimeout  time.Duration     // How long to wait for process to be ready
	ReadyCheck    ReadyChecker      // Function to check if process is ready
	OutputHandler OutputHandler     // Handler for process output
}

Config holds process configuration

type LogBuffer

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

LogBuffer is a thread-safe circular buffer for subprocess logs Keeps the most recent N log entries for user visibility Also writes all logs to a file for persistence

func NewLogBuffer

func NewLogBuffer(capacity int) *LogBuffer

NewLogBuffer creates a new log buffer with the specified capacity Creates a temporary file for persistent log storage

func (*LogBuffer) Append

func (lb *LogBuffer) Append(entry LogEntry)

Append adds a new log entry to the buffer and writes to file

func (*LogBuffer) Clear

func (lb *LogBuffer) Clear()

Clear removes all entries from the buffer

func (*LogBuffer) Close

func (lb *LogBuffer) Close() error

Close closes the log file and cleans up

func (*LogBuffer) GetAllFromFile

func (lb *LogBuffer) GetAllFromFile() ([]string, error)

GetAllFromFile reads all logs from the persistent file This allows retrieving logs even if they've been pushed out of the memory buffer

func (*LogBuffer) GetByStream

func (lb *LogBuffer) GetByStream(stream string, n int) []LogEntry

GetByStream returns recent entries filtered by stream (stdout/stderr)

func (*LogBuffer) GetLogFilePath

func (lb *LogBuffer) GetLogFilePath() string

GetLogFilePath returns the path to the persistent log file

func (*LogBuffer) GetRecent

func (lb *LogBuffer) GetRecent(n int) []LogEntry

GetRecent returns the most recent N log entries If n <= 0 or n > capacity, returns all available entries

func (*LogBuffer) GetSince

func (lb *LogBuffer) GetSince(since time.Time) []LogEntry

GetSince returns all log entries since the given timestamp

func (*LogBuffer) GetStats

func (lb *LogBuffer) GetStats() LogStats

GetStats returns statistics about the log buffer

func (*LogBuffer) ToJSON

func (lb *LogBuffer) ToJSON(n int) ([]byte, error)

ToJSON converts log entries to JSON for easy API responses

type LogCaptureConfig

type LogCaptureConfig struct {
	Enabled    bool // Enable log capture
	BufferSize int  // Number of log lines to keep in memory
}

LogCaptureConfig configures log capture behavior

func DefaultLogCaptureConfig

func DefaultLogCaptureConfig() LogCaptureConfig

DefaultLogCaptureConfig returns sensible defaults

type LogEntry

type LogEntry struct {
	Timestamp time.Time `json:"timestamp"`
	Stream    string    `json:"stream"` // "stdout" or "stderr"
	Line      string    `json:"line"`
	PID       int       `json:"pid"`
}

LogEntry represents a single log line from the subprocess

type LogStats

type LogStats struct {
	TotalLines    int  `json:"total_lines"`    // Total lines captured (lifetime)
	BufferedLines int  `json:"buffered_lines"` // Currently buffered lines
	Capacity      int  `json:"capacity"`       // Buffer capacity
	BufferFull    bool `json:"buffer_full"`    // Whether buffer has wrapped
}

LogStats represents statistics about the log buffer

type Manager

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

Manager manages the lifecycle of a subprocess with production-grade features

func NewManager

func NewManager(cfg Config, log *logger.Logger) (*Manager, error)

NewManager creates a new process manager with the given configuration

func (*Manager) GetCommand

func (m *Manager) GetCommand() []string

GetCommand returns the command being executed

func (*Manager) GetPID

func (m *Manager) GetPID() int

GetPID returns the process ID (thread-safe)

func (*Manager) GetState

func (m *Manager) GetState() ProcessState

GetState returns the current process state (thread-safe)

func (*Manager) GetUptime

func (m *Manager) GetUptime() time.Duration

GetUptime returns how long the process has been running

func (*Manager) GetWorkDir

func (m *Manager) GetWorkDir() string

GetWorkDir returns the working directory

func (*Manager) IsRunning

func (m *Manager) IsRunning() bool

IsRunning returns true if the process is currently running

func (*Manager) Start

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

Start starts the process and waits for it to be ready Returns an error if the process fails to start or ready check fails

func (*Manager) Stop

func (m *Manager) Stop() error

Stop gracefully stops the process with SIGTERM, then SIGKILL if needed

type ManagerWithLogs

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

ManagerWithLogs extends Manager with log capture capabilities

func NewManagerWithLogs

func NewManagerWithLogs(cfg Config, logCfg LogCaptureConfig, log *logger.Logger) (*ManagerWithLogs, error)

NewManagerWithLogs creates a process manager with log capture

func (*ManagerWithLogs) AddErrorLog

func (m *ManagerWithLogs) AddErrorLog(message string)

AddErrorLog adds an error message directly to the log buffer Useful for startup errors that occur before process output pipes are created

func (*ManagerWithLogs) ClearLogs

func (m *ManagerWithLogs) ClearLogs()

ClearLogs clears the log buffer

func (*ManagerWithLogs) CloseLogFile

func (m *ManagerWithLogs) CloseLogFile() error

CloseLogFile closes and cleans up the log file

func (*ManagerWithLogs) GetAllLogsFromFile

func (m *ManagerWithLogs) GetAllLogsFromFile() ([]string, error)

GetAllLogsFromFile returns all logs from the persistent file

func (*ManagerWithLogs) GetLogFilePath

func (m *ManagerWithLogs) GetLogFilePath() string

GetLogFilePath returns the path to the persistent log file

func (*ManagerWithLogs) GetLogStats

func (m *ManagerWithLogs) GetLogStats() LogStats

GetLogStats returns statistics about captured logs

func (*ManagerWithLogs) GetLogsByStream

func (m *ManagerWithLogs) GetLogsByStream(stream string, n int) []LogEntry

GetLogsByStream returns recent logs filtered by stream (stdout/stderr)

func (*ManagerWithLogs) GetLogsJSON

func (m *ManagerWithLogs) GetLogsJSON(n int) ([]byte, error)

GetLogsJSON returns logs in JSON format for API responses

func (*ManagerWithLogs) GetLogsSince

func (m *ManagerWithLogs) GetLogsSince(since time.Time) []LogEntry

GetLogsSince returns all logs since the given timestamp

func (*ManagerWithLogs) GetRecentLogs

func (m *ManagerWithLogs) GetRecentLogs(n int) []LogEntry

GetRecentLogs returns the most recent N log entries Returns empty slice if log capture is disabled

func (*ManagerWithLogs) StreamLogs

func (m *ManagerWithLogs) StreamLogs(ctx context.Context) <-chan LogEntry

StreamLogs returns a channel that streams new log entries in real-time Useful for WebSocket implementations or real-time log tailing

type OutputHandler

type OutputHandler func(stream string, line string)

OutputHandler processes subprocess output lines

type ProcessState

type ProcessState string

ProcessState represents the current state of a managed process

const (
	StateInitializing ProcessState = "initializing"
	StateStarting     ProcessState = "starting"
	StateRunning      ProcessState = "running"
	StateFailed       ProcessState = "failed"
	StateStopped      ProcessState = "stopped"
)

type ReadyChecker

type ReadyChecker func(ctx context.Context) error

ReadyChecker is a function type that checks if a process is ready