router

package
v0.16.0 Latest Latest
Warning

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

Go to latest
Published: Aug 24, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package router routes a command to drop/host/sandbox and executes it, independent of any transport (MCP, CLI). Output is written to the caller's io.Writers.

Index

Constants

View Source
const SandboxNotRunningHint = "command broker is not available; run Claude via `agent-sandbox claude`, which starts it automatically"

SandboxNotRunningHint is the actionable message shown when a command is routed to the sandbox but the command broker is not available. It is exported because the same situation is detected before Run is ever reached: `agent-sandbox exec` and `agent-sandbox command-router` fail to build a broker client when AGENT_SANDBOX_BROKER_SOCKET is unset, and must print this rather than a raw dial error.

Variables

View Source
var ErrSandboxNotRunning = errors.New("sandbox is not running")

ErrSandboxNotRunning signals that a command was routed to the sandbox but the broker could not run it there. A CommandRunner returns it (possibly wrapped) so the router can print an actionable message instead of a raw broker error. Detect it with errors.Is.

View Source
var ErrUnterminatedQuote = errors.New("unterminated quote")

ErrUnterminatedQuote is returned by ParseLine when a quote is never closed.

Functions

func Route

func Route(cmd string, allow []string, drop []DropRule) (decision, matched, message string)

Route decides where cmd runs. Allow is checked before drop, so a command matching both an allow and a drop pattern runs on the host. On a drop, matched is the pattern and message is the rule's custom message (empty for the default).

func Run added in v0.9.2

func Run(ctx context.Context, req Request) (int, error)

Run routes req.Command per segment and executes the resulting pipelines in sequence, honoring && / || / ; operators between pipelines.

func RunHost added in v0.9.2

func RunHost(ctx context.Context, args []string, stdin io.Reader, stdout, stderr io.Writer) (int, error)

func RunHostShell added in v0.9.2

func RunHostShell(ctx context.Context, raw string, stdin io.Reader, stdout, stderr io.Writer) (int, error)

RunHostShell runs raw via "bash -c" on the host. Used for segments that contain a redirect (which the shell-free argv path cannot express).

Types

type CommandRunner added in v0.15.0

type CommandRunner interface {
	RunSandboxed(ctx context.Context, argv []string, stdin io.Reader, stdout, stderr io.Writer) (int, error)
}

CommandRunner executes an argv inside the sandbox.

type Config added in v0.9.2

type Config struct {
	AllowPatterns []string
	DropRules     []DropRule
	CommandRunner CommandRunner // nil allowed (host/drop-only lines)
}

Config holds routing patterns and the optional command runner.

type DropRule added in v0.14.3

type DropRule struct {
	Pattern string
	Message string
}

DropRule is a drop pattern with an optional custom refusal message. An empty Message means the caller should print the default "dropped: ..." line.

type Line added in v0.9.2

type Line struct {
	Raw       string
	Pipelines []PipelineNode
	Seps      []string // "&&" | "||" | ";"  (len == len(Pipelines)-1)
	Fallback  bool
}

Line is a parsed command line: a sequence of pipelines joined by sequential operators. When Fallback is true the line contains a construct we do not split (command substitution or background &) and must run whole.

func ParseLine added in v0.9.2

func ParseLine(raw string) (Line, error)

ParseLine tokenizes raw into a structured Line. It returns ErrUnterminatedQuote for an unclosed quote.

type PipelineNode added in v0.9.2

type PipelineNode struct {
	Raw      string
	Segments []Segment
}

PipelineNode is a sequence of segments joined by "|".

type Request added in v0.9.2

type Request struct {
	Command       string
	AllowPatterns []string
	DropRules     []DropRule
	CommandRunner CommandRunner
	Stdout        io.Writer
	Stderr        io.Writer
}

Request carries everything Run needs for a single command.

type Result added in v0.9.2

type Result struct {
	Stdout   []byte
	Stderr   []byte
	ExitCode int
}

Result is the buffered outcome of RunBuffered.

type Router added in v0.9.2

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

Router routes and runs command lines.

func New added in v0.9.2

func New(cfg Config) *Router

New builds a Router from cfg.

func (*Router) NeedsSandbox added in v0.15.0

func (s *Router) NeedsSandbox(command string) (bool, error)

NeedsSandbox reports whether running command requires a command runner. It uses ParseLine to check each segment individually, so a pipeline with any sandbox-routed segment returns true, and a Fallback line always returns true.

func (*Router) Run added in v0.9.2

func (s *Router) Run(ctx context.Context, command string, stdout, stderr io.Writer) (int, error)

Run routes command and streams output to stdout/stderr, returning the exit code. The error is non-nil only on host-execution infrastructure failure.

func (*Router) RunBuffered added in v0.9.2

func (s *Router) RunBuffered(ctx context.Context, command string) (Result, error)

RunBuffered runs command and captures stdout/stderr into memory.

type Segment added in v0.9.2

type Segment struct {
	Raw         string
	Args        []string
	HasRedirect bool
}

Segment is a simple command, possibly carrying a redirect.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL