refactor: introduce cobra CLI and externalize sandbox configuration

koki-develop · claude · koki-develop · commit 99e827ce4449 · 2026-03-01T19:49:14.000+09:00
Replace the hardcoded server entrypoint with a cobra-based CLI exposing
a `serve` subcommand with `--addr`, `--timeout`, and `--output-limit`
flags. Extract sandbox configuration into an explicit Config struct
passed through the call chain instead of relying on package-level
init() and constants.

Co-Authored-By: Claude &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -36,7 +36,7 @@ jobs:
         with:
           persist-credentials: false
       - uses: jdx/mise-action@6d1e696aa24c1aa1bcc1adea0212707c71ab78a8 # v3.6.1
-      - run: go build -o server ./cmd/server
+      - run: go build -o sandbox .
 
   unit-test:
     name: Unit Test
diff --git a/.gitignore b/.gitignore
@@ -1 +1 @@
-/server
+/sandbox
diff --git a/Dockerfile b/Dockerfile
@@ -36,13 +36,13 @@ COPY . .
 RUN CGO_ENABLED=0 go build \
       -trimpath \
       -ldflags="-w -s" \
-      -o /out/server \
-      ./cmd/server
+      -o /out/sandbox \
+      .
 
 # ---
 
 FROM base
 
-COPY --from=builder /out/server /usr/local/bin/server
+COPY --from=builder /out/sandbox /usr/local/bin/sandbox
 EXPOSE 8080
-ENTRYPOINT ["/usr/local/bin/server"]
+ENTRYPOINT ["/usr/local/bin/sandbox", "serve"]
diff --git a/cmd/root.go b/cmd/root.go
@@ -0,0 +1,17 @@
+package cmd
+
+import (
+	"os"
+
+	"github.com/spf13/cobra"
+)
+
+var rootCmd = &cobra.Command{
+	Use: "sandbox",
+}
+
+func Execute() {
+	if err := rootCmd.Execute(); err != nil {
+		os.Exit(1)
+	}
+}
diff --git a/cmd/serve.go b/cmd/serve.go
@@ -0,0 +1,58 @@
+package cmd
+
+import (
+	"time"
+
+	"github.com/codize-dev/sandbox/internal/handler"
+	"github.com/codize-dev/sandbox/internal/sandbox"
+	"github.com/labstack/echo/v5"
+	"github.com/labstack/echo/v5/middleware"
+	"github.com/spf13/cobra"
+)
+
+var serveCmd = &cobra.Command{
+	Use:  "serve",
+	RunE: runServe,
+}
+
+func init() {
+	rootCmd.AddCommand(serveCmd)
+
+	serveCmd.Flags().String("addr", ":8080", "TCP address to listen on")
+	serveCmd.Flags().Int("timeout", 30, "sandbox run timeout in seconds")
+	serveCmd.Flags().Int("output-limit", 1<<20, "maximum combined output bytes")
+}
+
+func runServe(cmd *cobra.Command, _ []string) error {
+	addr, err := cmd.Flags().GetString("addr")
+	if err != nil {
+		return err
+	}
+
+	timeout, err := cmd.Flags().GetInt("timeout")
+	if err != nil {
+		return err
+	}
+
+	outputLimit, err := cmd.Flags().GetInt("output-limit")
+	if err != nil {
+		return err
+	}
+
+	cfg := sandbox.Config{
+		RunTimeout:  timeout,
+		ExecTimeout: time.Duration(timeout+10) * time.Second,
+		OutputLimit: outputLimit,
+	}
+
+	h := &handler.Handler{Config: cfg}
+
+	e := echo.New()
+	e.Use(middleware.RequestLogger())
+	e.POST("/v1/run", h.RunHandler)
+
+	if err := e.Start(addr); err != nil {
+		e.Logger.Error("failed to start server", "error", err)
+	}
+	return nil
+}
diff --git a/cmd/server/main.go b/cmd/server/main.go
diff --git a/compose.yml b/compose.yml
@@ -4,7 +4,6 @@ services:
       context: .
       dockerfile: Dockerfile
     privileged: true
-    environment:
-      - SANDBOX_RUN_TIMEOUT=5
+    command: ["serve", "--timeout", "5"]
     ports:
       - "8080:8080"
diff --git a/go.mod b/go.mod
@@ -11,7 +11,10 @@ require (
 
 require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/spf13/cobra v1.10.2 // indirect
+	github.com/spf13/pflag v1.0.9 // indirect
 	golang.org/x/time v0.14.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
diff --git a/go.sum b/go.sum
@@ -1,11 +1,20 @@
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/labstack/echo/v5 v5.0.4 h1:ll3I/O8BifjMztj9dD1vx/peZQv8cR2CTUdQK6QxGGc=
 github.com/labstack/echo/v5 v5.0.4/go.mod h1:SyvlSdObGjRXeQfCCXW/sybkZdOOQZBmpKF0bvALaeo=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
+github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
+github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
+github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 go.yaml.in/yaml/v4 v4.0.0-rc.4 h1:UP4+v6fFrBIb1l934bDl//mmnoIZEDK0idg1+AIvX5U=
 go.yaml.in/yaml/v4 v4.0.0-rc.4/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
 golang.org/x/net v0.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o=
diff --git a/internal/handler/handler.go b/internal/handler/handler.go
@@ -28,7 +28,12 @@ type RunResponse struct {
 	Run sandbox.Result `json:"run"`
 }
 
-func RunHandler(c *echo.Context) error {
+// Handler holds dependencies for the HTTP handler.
+type Handler struct {
+	Config sandbox.Config
+}
+
+func (h *Handler) RunHandler(c *echo.Context) error {
 	var req RunRequest
 	if err := c.Bind(&req); err != nil {
 		return c.JSON(http.StatusBadRequest, map[string]string{
@@ -73,7 +78,7 @@ func RunHandler(c *echo.Context) error {
 		}
 	}
 
-	result, err := sandbox.Run(c.Request().Context(), rt, tmpDir, req.Files[0].Name)
+	result, err := sandbox.Run(c.Request().Context(), h.Config, rt, tmpDir, req.Files[0].Name)
 	if err != nil {
 		if errors.Is(err, context.DeadlineExceeded) {
 			return c.JSON(http.StatusGatewayTimeout, map[string]string{
diff --git a/internal/sandbox/sandbox.go b/internal/sandbox/sandbox.go
@@ -7,10 +7,8 @@ import (
 	"errors"
 	"fmt"
 	"io"
-	"log"
 	"os"
 	"os/exec"
-	"strconv"
 	"strings"
 	"syscall"
 	"time"
@@ -20,24 +18,6 @@ import (
 
 const nsjailPath = "/bin/nsjail"
 
-const defaultRunTimeout = 30
-
-var (
-	nsjailTimeLimit = defaultRunTimeout
-	execTimeout     = time.Duration(defaultRunTimeout+10) * time.Second
-)
-
-func init() {
-	if v := os.Getenv("SANDBOX_RUN_TIMEOUT"); v != "" {
-		sec, err := strconv.Atoi(v)
-		if err != nil || sec <= 0 {
-			log.Fatalf("invalid SANDBOX_RUN_TIMEOUT: %q (must be a positive integer)", v)
-		}
-		nsjailTimeLimit = sec
-		execTimeout = time.Duration(sec+10) * time.Second
-	}
-}
-
 type Runtime string
 
 const (
@@ -55,7 +35,12 @@ const (
 
 var errOutputLimitExceeded = errors.New("output limit exceeded")
 
-const outputLimit = 1 << 20 // 1 MiB
+// Config holds runtime-configurable parameters for the sandbox.
+type Config struct {
+	RunTimeout  int
+	ExecTimeout time.Duration
+	OutputLimit int
+}
 
 type runtimeConfig struct {
 	binaryPath string
@@ -101,16 +86,16 @@ func resolveSignal(exitCode int, logOutput string) *string {
 	return nil
 }
 
-func Run(ctx context.Context, rt Runtime, tmpDir, entryFile string) (Result, error) {
-	ctx, cancel := context.WithTimeout(ctx, execTimeout)
+func Run(ctx context.Context, cfg Config, rt Runtime, tmpDir, entryFile string) (Result, error) {
+	ctx, cancel := context.WithTimeout(ctx, cfg.ExecTimeout)
 	defer cancel()
 
 	tmpHome, err := os.MkdirTemp("", "sandbox-tmp-*")
 	if err != nil {
 		return Result{}, fmt.Errorf("failed to create tmp directory: %w", err)
 	}
 	defer func() { _ = os.RemoveAll(tmpHome) }()
-	cfg := runtimes[rt]
+	rtCfg := runtimes[rt]
 
 	args := []string{
 		"-Mo",
@@ -127,19 +112,19 @@ func Run(ctx context.Context, rt Runtime, tmpDir, entryFile string) (Result, err
 	}
 
 	args = append(args,
-		"-R", cfg.installDir+":"+cfg.installDir,
+		"-R", rtCfg.installDir+":"+rtCfg.installDir,
 		"-R", "/dev/null:/dev/null",
 		"-R", "/dev/urandom:/dev/urandom",
 		"-B", tmpDir+":/code",
 		"-B", tmpHome+":/tmp",
 		"-m", "none:/proc:proc:ro",
 		"-s", "/proc/self/fd:/dev/fd",
 		"--rlimit_as", "hard",
-		"--time_limit", fmt.Sprintf("%d", nsjailTimeLimit),
-		"-E", "PATH="+cfg.pathEnv,
+		"--time_limit", fmt.Sprintf("%d", cfg.RunTimeout),
+		"-E", "PATH="+rtCfg.pathEnv,
 		"-E", "HOME=/tmp",
 		"--",
-		cfg.binaryPath,
+		rtCfg.binaryPath,
 		"/code/"+entryFile,
 	)
 
@@ -195,7 +180,7 @@ func Run(ctx context.Context, rt Runtime, tmpDir, entryFile string) (Result, err
 
 	var stdoutBuf, stderrBuf, combined bytes.Buffer
 
-	drainErr := drainPipes(ctx, cmd.Process, stdoutR, stderrR, &stdoutBuf, &stderrBuf, &combined)
+	drainErr := drainPipes(ctx, cmd.Process, stdoutR, stderrR, &stdoutBuf, &stderrBuf, &combined, cfg.OutputLimit)
 	if drainErr != nil && !errors.Is(drainErr, errOutputLimitExceeded) {
 		_ = cmd.Wait()
 		_ = stdoutR.Close()
@@ -270,7 +255,7 @@ func Run(ctx context.Context, rt Runtime, tmpDir, entryFile string) (Result, err
 // pipes are ready simultaneously, stdout is processed first. The poll
 // timeout is derived from ctx's deadline so that the execution timeout
 // and client disconnects are respected promptly.
-func drainPipes(ctx context.Context, proc *os.Process, stdoutR, stderrR *os.File, stdoutBuf, stderrBuf, combined *bytes.Buffer) error {
+func drainPipes(ctx context.Context, proc *os.Process, stdoutR, stderrR *os.File, stdoutBuf, stderrBuf, combined *bytes.Buffer, outputLimit int) error {
 	type pipe struct {
 		file *os.File
 		buf  *bytes.Buffer
diff --git a/main.go b/main.go
@@ -0,0 +1,7 @@
+package main
+
+import "github.com/codize-dev/sandbox/cmd"
+
+func main() {
+	cmd.Execute()
+}
