git.iko.soy/crush
on 2faa467 help sign in
crush/internal/shell/run.go
158 lines 5.6 kB history raw
1package shell
3import (
4 "context"
5 "fmt"
6 "io"
7 "strings"
9 "mvdan.cc/sh/moreinterp/coreutils"
10 "mvdan.cc/sh/v3/expand"
11 "mvdan.cc/sh/v3/interp"
12 "mvdan.cc/sh/v3/syntax"
15// RunOptions configures a single stateless shell execution via [Run].
16//
17// The zero value is not useful; at minimum Command must be set. Stdin,
18// Stdout, and Stderr may be nil (nil readers/writers are treated as
19// empty/discard). BlockFuncs may be nil to disable block-list enforcement —
20// hooks use this to run user-authored commands with the same trust level as
21// a shell alias.
22type RunOptions struct {
23 // Command is the shell source to parse and execute.
24 Command string
25 // Cwd is the working directory for the execution. Required: callers
26 // must supply a non-empty value. Run does not silently fall back to
27 // the Crush process cwd — hooks and the bash tool have different
28 // notions of "default" and each owns that decision.
29 Cwd string
30 // Env is the full environment visible to the command. The caller is
31 // responsible for inheriting from os.Environ() if that's desired.
32 Env []string
33 // Stdin is the command's standard input. nil is equivalent to an empty
34 // input stream.
35 Stdin io.Reader
36 // Stdout receives the command's standard output. nil discards output.
37 Stdout io.Writer
38 // Stderr receives the command's standard error. nil discards output.
39 Stderr io.Writer
40 // BlockFuncs is an optional list of deny-list matchers applied before
41 // each command reaches the exec layer. nil disables blocking entirely.
42 BlockFuncs []BlockFunc
45// Run parses and executes a shell command using the same mvdan.cc/sh
46// interpreter stack that the stateful [Shell] type uses (builtins,
47// optional block list, optional Go coreutils). It is safe to call
48// concurrently from multiple goroutines: each call builds its own
49// [interp.Runner] and shares no state with other callers or with any
50// [Shell] instance.
51//
52// Errors returned from the command itself (non-zero exit, context
53// cancellation, parse failures) follow the same conventions as
54// [Shell.Exec]: inspect with [IsInterrupt] and [ExitCode].
55func Run(ctx context.Context, opts RunOptions) (err error) {
56 defer func() {
57 if r := recover(); r != nil {
58 err = fmt.Errorf("command execution panic: %v", r)
59 }
60 }()
62 if opts.Cwd == "" {
63 return fmt.Errorf("shell.Run: Cwd is required")
64 }
66 stdout := opts.Stdout
67 if stdout == nil {
68 stdout = io.Discard
69 }
70 stderr := opts.Stderr
71 if stderr == nil {
72 stderr = io.Discard
73 }
75 line, err := syntax.NewParser().Parse(strings.NewReader(opts.Command), "")
76 if err != nil {
77 return fmt.Errorf("could not parse command: %w", err)
78 }
80 runner, err := newRunner(opts.Cwd, opts.Env, opts.Stdin, stdout, stderr, opts.BlockFuncs)
81 if err != nil {
82 return fmt.Errorf("could not run command: %w", err)
83 }
85 return runner.Run(ctx, line)
88// newRunner constructs an [interp.Runner] configured with the standard
89// Crush handler stack. Shared by the stateless [Run] entrypoint and the
90// stateful [Shell] so the two surfaces cannot drift.
91func newRunner(cwd string, env []string, stdin io.Reader, stdout, stderr io.Writer, blockFuncs []BlockFunc) (*interp.Runner, error) {
92 return interp.New(
93 interp.StdIO(stdin, stdout, stderr),
94 interp.Interactive(false),
95 interp.Env(expand.ListEnviron(env...)),
96 interp.Dir(cwd),
97 interp.ExecHandlers(standardHandlers(blockFuncs)...),
98 )
101// standardHandlers returns the exec-handler middleware chain used by both
102// [Run] and [Shell]. Order matters:
103// 1. builtins first (so Crush's in-process jq wins over any PATH binary);
104// 2. script dispatch (shebang / binary / shell-source for path-prefixed
105// argv[0], no-op for bare commands) — runs before the block list so
106// that deny rules see the already-resolved argv of anything the
107// script exec's rather than the outer path-prefixed wrapper;
108// 3. block list;
109// 4. optional Go coreutils (only when useGoCoreUtils is on).
110func standardHandlers(blockFuncs []BlockFunc) []func(next interp.ExecHandlerFunc) interp.ExecHandlerFunc {
111 handlers := []func(next interp.ExecHandlerFunc) interp.ExecHandlerFunc{
112 builtinHandler(),
113 scriptDispatchHandler(blockFuncs),
114 blockHandler(blockFuncs),
115 }
116 if useGoCoreUtils {
117 handlers = append(handlers, coreutils.ExecHandler)
118 }
119 return handlers
122// builtinHandler returns middleware that dispatches recognized Crush
123// builtins to their in-process Go implementations. Currently: jq.
124func builtinHandler() func(next interp.ExecHandlerFunc) interp.ExecHandlerFunc {
125 return func(next interp.ExecHandlerFunc) interp.ExecHandlerFunc {
126 return func(ctx context.Context, args []string) error {
127 if len(args) == 0 {
128 return next(ctx, args)
129 }
130 switch args[0] {
131 case "jq":
132 hc := interp.HandlerCtx(ctx)
133 return handleJQ(ctx, args, hc.Stdin, hc.Stdout, hc.Stderr)
134 default:
135 return next(ctx, args)
136 }
137 }
138 }
141// blockHandler returns middleware that rejects commands matched by any of
142// the provided [BlockFunc]s before they reach the underlying exec path.
143// A nil or empty blockFuncs slice is a no-op.
144func blockHandler(blockFuncs []BlockFunc) func(next interp.ExecHandlerFunc) interp.ExecHandlerFunc {
145 return func(next interp.ExecHandlerFunc) interp.ExecHandlerFunc {
146 return func(ctx context.Context, args []string) error {
147 if len(args) == 0 {
148 return next(ctx, args)
149 }
150 for _, blockFunc := range blockFuncs {
151 if blockFunc(args) {
152 return fmt.Errorf("command is not allowed for security reasons: %q", args[0])
153 }
154 }
155 return next(ctx, args)
156 }
157 }