opensandbox-group--opensandbox/components/execd/DEVELOPMENT.md

Development Guide - execd

Getting Started

Prerequisites

• Go 1.24+ — match go.mod
• Make — build automation
• Docker/Podman — containerized testing (optional)
• Jupyter Server — required for integration tests

Setup

cd components/execd
go mod download
make build        # → bin/execd

Project Structure

execd/
├── main.go                 # Entry point
├── Makefile                # Build automation
├── Dockerfile              # Container image
├── pkg/
│   ├── flag/               # CLI flag parsing
│   ├── web/
│   │   ├── router.go       # Gin route registration
│   │   ├── controller/     # Request handlers
│   │   └── model/          # API request/response models
│   ├── runtime/            # Execution engine
│   │   ├── ctrl.go         # Main controller
│   │   ├── jupyter.go      # Jupyter kernel execution
│   │   ├── command.go      # Shell command execution
│   │   └── bash_session.go # Pipe-based bash sessions
│   ├── jupyter/            # Jupyter HTTP/WebSocket client
│   ├── telemetry/          # OTLP metrics
│   ├── clone3compat/       # Linux clone3 seccomp workaround
│   └── log/                # Structured logger wrapper
└── tests/                  # Integration test scripts

Key Patterns

• Controller pattern (pkg/web/controller): thin Gin handlers that parse requests, validate, delegate to runtime, and stream responses via SSE.
• Runtime controller (pkg/runtime): dispatches to Jupyter, Command, or SQL executors; manages session lifecycle.
• Hook-based streaming: execution results flow through hooks, decoupling runtime events from SSE serialization.

Testing

Unit Tests

go test ./pkg/...
go test -v -cover ./pkg/...

Integration Tests

Require a running Jupyter server:

export JUPYTER_URL=http://localhost:8888
export JUPYTER_TOKEN=your-token
go test -v ./pkg/jupyter/...

Common Tasks

Adding a New API Endpoint

1. Define request/response model in pkg/web/model/.

2. Add controller method in pkg/web/controller/:

func (c *MyController) NewFeature() {
    var req model.NewFeatureRequest
    if err := c.Ctx.ShouldBindJSON(&req); err != nil {
        c.Ctx.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    // ...
}

3. Register route in pkg/web/router.go:

myGroup := r.Group("/my-feature")
{
    myGroup.POST("", withMyController(func(c *controller.MyController) { c.NewFeature() }))
}

Adding a Configuration Flag

1. Declare variable in pkg/flag/flags.go.
2. In pkg/flag/parser.go, read env var first, then register flag.*Var with current value as default — flag overrides env.
3. Update README.md CLI Flags and Environment Variables tables.

Debugging SSE Streams

curl -N -H "Content-Type: application/json" \
  -d '{"language":"python","code":"print(\"test\")"}' \
  http://localhost:44772/code

-N disables buffering for real-time events.

Useful Commands

make fmt      # gofmt
make golint   # lint
make test     # all tests
make build    # binary → bin/execd