engine

Documentation

Index

• type CommandCache
  • func NewCommandCache(maxSize int) *CommandCache
  • func (cc *CommandCache) Clear()
  • func (cc *CommandCache) Get(cmd string, args []string) (*CommandResult, bool)
  • func (cc *CommandCache) Invalidate(cmd string, args []string)
  • func (cc *CommandCache) InvalidateAllWithPrefix(prefix string)
  • func (cc *CommandCache) Put(cmd string, args []string, result *CommandResult)
  • func (cc *CommandCache) Stats() (hits, misses int64, size int)
• type CommandResult
• type ExecutionEngine
  • func NewExecutionEngine(envManager *environment.EnvironmentManager, stdlib *stdlib.StdLib, ...) *ExecutionEngine
  • func (ee *ExecutionEngine) Execute(ctx context.Context, script *types.ScriptNode) (*ExecutionResult, error)
  • func (ee *ExecutionEngine) ExecuteBackground(ctx context.Context, bgNode *types.BackgroundNode) (*CommandResult, error)
  • func (ee *ExecutionEngine) ExecuteCommand(ctx context.Context, cmd *types.CommandNode) (*CommandResult, error)
  • func (ee *ExecutionEngine) ExecuteCommandWithInput(ctx context.Context, cmd *types.CommandNode, input string) (*CommandResult, error)
  • func (ee *ExecutionEngine) ExecuteFor(ctx context.Context, forNode *types.ForNode) (*ExecutionResult, error)
  • func (ee *ExecutionEngine) ExecuteIf(ctx context.Context, ifNode *types.IfNode) (*ExecutionResult, error)
  • func (ee *ExecutionEngine) ExecutePipeline(ctx context.Context, pipeline *types.PipeNode) (*PipelineResult, error)
  • func (ee *ExecutionEngine) ExecuteWhile(ctx context.Context, whileNode *types.WhileNode) (*ExecutionResult, error)
  • func (ee *ExecutionEngine) GetMetrics() *metrics.Metrics
  • func (ee *ExecutionEngine) ResetMetrics()
• type ExecutionMode
• type ExecutionResult
• type PipelineResult
• type ProcessEntry
  • func (pe *ProcessEntry) Close()
• type ProcessPool
  • func NewProcessPool(maxSize int, idleTimeout time.Duration) *ProcessPool
  • func (pp *ProcessPool) Close()
  • func (pp *ProcessPool) Get(cmd string, args []string) (*ProcessEntry, error)
  • func (pp *ProcessPool) Put(entry *ProcessEntry)

Types

type CommandCache

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

CommandCache caches command execution results

func NewCommandCache

func NewCommandCache(maxSize int) *CommandCache

NewCommandCache creates a new command cache

func (*CommandCache) Clear

func (cc *CommandCache) Clear()

Clear removes all entries from cache

func (*CommandCache) Get

func (cc *CommandCache) Get(cmd string, args []string) (*CommandResult, bool)

Get retrieves a command result from cache Optimized: Reduce lock contention by checking expiration before incrementing counters

func (*CommandCache) Invalidate

func (cc *CommandCache) Invalidate(cmd string, args []string)

Invalidate invalidates a specific command from cache

func (*CommandCache) InvalidateAllWithPrefix

func (cc *CommandCache) InvalidateAllWithPrefix(prefix string)

InvalidateAllWithPrefix invalidates all commands with a given prefix

func (*CommandCache) Put

func (cc *CommandCache) Put(cmd string, args []string, result *CommandResult)

Put stores a command result in cache

func (*CommandCache) Stats

func (cc *CommandCache) Stats() (hits, misses int64, size int)

Stats returns cache statistics

type CommandResult

type CommandResult struct {
	Command  *types.CommandNode
	Success  bool
	ExitCode int
	Output   string
	Error    string
	Duration time.Duration
	Mode     ExecutionMode
}

CommandResult represents the result of a single command execution

type ExecutionEngine

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

ExecutionEngine is the core engine for executing shell commands

func NewExecutionEngine

func NewExecutionEngine(
	envManager *environment.EnvironmentManager,
	stdlib *stdlib.StdLib,
	moduleMgr *module.ModuleManager,
	security *sandbox.SecurityChecker,
) *ExecutionEngine

NewExecutionEngine creates a new execution engine

func (*ExecutionEngine) Execute

func (ee *ExecutionEngine) Execute(ctx context.Context, script *types.ScriptNode) (*ExecutionResult, error)

Execute executes a complete script and returns the execution result.

The method processes all nodes in the script sequentially, handling commands, pipelines, control flow statements, and function calls. It checks for context cancellation to support timeout handling.

Parameters:

• ctx: Context for cancellation and timeout support
• script: The script AST to execute

Returns:

• ExecutionResult: Contains success status, exit code, output, and command results
• error: Returns error if execution fails or context is cancelled

Example:

script := &types.ScriptNode{
    Nodes: []types.Node{
        &types.CommandNode{Name: "echo", Args: []string{"hello"}},
    },
}
result, err := ee.Execute(ctx, script)

func (*ExecutionEngine) ExecuteBackground

func (ee *ExecutionEngine) ExecuteBackground(ctx context.Context, bgNode *types.BackgroundNode) (*CommandResult, error)

ExecuteBackground executes a command in the background

func (*ExecutionEngine) ExecuteCommand

func (ee *ExecutionEngine) ExecuteCommand(ctx context.Context, cmd *types.CommandNode) (*CommandResult, error)

ExecuteCommand executes a single command and returns the result.

The method performs security checks, determines execution mode (interpreted, process, or hybrid), and executes the command accordingly. Results are cached for performance when appropriate.

Parameters:

• ctx: Context for cancellation and timeout support
• cmd: The command node to execute

Returns:

• CommandResult: Contains command output, exit code, and execution metadata
• error: Returns error if execution fails

Example:

cmd := &types.CommandNode{
    Name: "echo",
    Args: []string{"hello", "world"},
}
result, err := ee.ExecuteCommand(ctx, cmd)

func (*ExecutionEngine) ExecuteCommandWithInput

func (ee *ExecutionEngine) ExecuteCommandWithInput(ctx context.Context, cmd *types.CommandNode, input string) (*CommandResult, error)

ExecuteCommandWithInput executes a command with input data

func (*ExecutionEngine) ExecuteFor

func (ee *ExecutionEngine) ExecuteFor(ctx context.Context, forNode *types.ForNode) (*ExecutionResult, error)

ExecuteFor executes a for loop

func (*ExecutionEngine) ExecuteIf

func (ee *ExecutionEngine) ExecuteIf(ctx context.Context, ifNode *types.IfNode) (*ExecutionResult, error)

ExecuteIf executes an if-then-else statement

func (*ExecutionEngine) ExecutePipeline

func (ee *ExecutionEngine) ExecutePipeline(ctx context.Context, pipeline *types.PipeNode) (*PipelineResult, error)

ExecutePipeline executes a pipeline of commands with proper data flow

func (*ExecutionEngine) ExecuteWhile

func (ee *ExecutionEngine) ExecuteWhile(ctx context.Context, whileNode *types.WhileNode) (*ExecutionResult, error)

ExecuteWhile executes a while loop

func (*ExecutionEngine) GetMetrics

func (ee *ExecutionEngine) GetMetrics() *metrics.Metrics

GetMetrics returns a snapshot of the current execution metrics.

The metrics include command execution statistics, cache performance, process pool usage, error counts, and performance percentiles.

Returns:

• *metrics.Metrics: Current metrics snapshot, or nil if metrics collection is disabled

Example:

m := ee.GetMetrics()
if m != nil {
    fmt.Printf("Commands executed: %d\n", m.CommandExecutions)
    fmt.Printf("Success rate: %.2f%%\n", m.SuccessRate)
    fmt.Printf("Cache hit rate: %.2f%%\n", m.CacheHitRate)
}

func (*ExecutionEngine) ResetMetrics

func (ee *ExecutionEngine) ResetMetrics()

ResetMetrics resets all collected metrics to their initial state.

This is useful for starting a new metrics collection period or clearing metrics after a test run.

Example:

ee.ResetMetrics()
// Execute commands...
metrics := ee.GetMetrics()

type ExecutionMode

type ExecutionMode int

ExecutionMode represents the execution mode for commands

const (
	ModeInterpreted ExecutionMode = iota // Interpret built-in functions
	ModeProcess                          // Execute external processes
	ModeHybrid                           // Smart hybrid execution
)

type ExecutionResult

type ExecutionResult struct {
	Success      bool
	ExitCode     int
	Output       string
	Error        string
	Duration     time.Duration
	Commands     []*CommandResult
	BreakFlag    bool // Set to true if break statement was encountered
	ContinueFlag bool // Set to true if continue statement was encountered
}

ExecutionResult represents the result of executing an AST

type PipelineResult

type PipelineResult struct {
	Success  bool
	ExitCode int
	Output   string
	Error    string
	Results  []*CommandResult
}

PipelineResult represents the result of pipeline execution

type ProcessEntry

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

ProcessEntry represents a process in the pool

func (*ProcessEntry) Close

func (pe *ProcessEntry) Close()

Close closes the process and releases resources

type ProcessPool

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

ProcessPool manages a pool of reusable processes

func NewProcessPool

func NewProcessPool(maxSize int, idleTimeout time.Duration) *ProcessPool

NewProcessPool creates a new process pool

func (*ProcessPool) Close

func (pp *ProcessPool) Close()

Close closes all processes in the pool

func (*ProcessPool) Get

func (pp *ProcessPool) Get(cmd string, args []string) (*ProcessEntry, error)

Get gets a process from the pool or creates a new one

func (*ProcessPool) Put

func (pp *ProcessPool) Put(entry *ProcessEntry)

Put returns a process to the pool