Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

17.5 KB
Raw Blame
// Copyright 2026 The OpenSandbox Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package controller

import (
	"context"
	"errors"
	"net/http"
	"strconv"
	"strings"
	"sync"
	"time"

	"github.com/alibaba/opensandbox/internal/safego"
	"github.com/gin-gonic/gin"

	"github.com/alibaba/opensandbox/execd/pkg/isolation"
	"github.com/alibaba/opensandbox/execd/pkg/jupyter/execute"
	"github.com/alibaba/opensandbox/execd/pkg/runtime"
	"github.com/alibaba/opensandbox/execd/pkg/telemetry"
	"github.com/alibaba/opensandbox/execd/pkg/web/model"
)

var isolatedRunner *runtime.IsolatedRunner

var isolatedProbeResult *isolation.ProbeResult

func InitIsolatedRunner(r *runtime.IsolatedRunner) {
	isolatedRunner = r
}

func InitIsolatedProbe(p *isolation.ProbeResult) {
	isolatedProbeResult = p
}

type IsolatedSessionController struct {
	*basicController
}

func NewIsolatedSessionController(ctx *gin.Context) *IsolatedSessionController {
	return &IsolatedSessionController{
		basicController: newBasicController(ctx),
	}
}

func (c *IsolatedSessionController) probed() bool {
	return isolatedRunner != nil && isolatedRunner.Available()
}

func (c *IsolatedSessionController) initialized() bool {
	return isolatedRunner != nil
}

func (c *IsolatedSessionController) Create() {
	if !c.probed() {
		c.RespondError(http.StatusServiceUnavailable, model.ErrorCodeServiceUnavailable, "isolation unavailable")
		return
	}

	var req model.CreateIsolatedSessionRequest
	if err := c.bindJSON(&req); err != nil {
		c.RespondError(http.StatusBadRequest, model.ErrorCodeInvalidRequest, err.Error())
		return
	}
	if err := req.Validate(); err != nil {
		c.RespondError(http.StatusBadRequest, model.ErrorCodeInvalidRequest, err.Error())
		return
	}

	binds := make([]isolation.BindMount, 0, len(req.Binds))
	for _, b := range req.Binds {
		binds = append(binds, isolation.BindMount{
			Source:   b.Source,
			Dest:     b.Dest,
			ReadOnly: b.ReadOnly,
		})
	}

	overlays := make([]runtime.IsolatedOverlayOptions, 0, len(req.Overlays)+1)
	for _, ov := range req.EffectiveOverlays() {
		overlays = append(overlays, runtime.IsolatedOverlayOptions{
			Path:    ov.Path,
			Mode:    ov.Mode,
			Persist: ov.Persist,
		})
	}

	opts := &runtime.IsolatedSessionOptions{
		Profile:            req.Profile,
		Overlays:           overlays,
		ExtraWritable:      req.ExtraWritable,
		Binds:              binds,
		ShareNet:           req.ShareNet,
		EnvPassthroughMode: req.EnvPassthrough.Mode,
		EnvPassthroughKeys: req.EnvPassthrough.Keys,
		Uid:                req.Uid,
		Gid:                req.Gid,
		UidMode:            req.UidMode,
		IdleTimeoutSeconds: req.IdleTimeoutSeconds,
	}

	sessionID, err := isolatedRunner.CreateIsolatedSession(opts)
	if err != nil {
		status, code := classifyIsolatedCreateError(err)
		c.RespondError(status, code, err.Error())
		return
	}

	c.ctx.JSON(http.StatusCreated, model.IsolatedCreateSessionResponse{
		SessionID: sessionID,
		CreatedAt: time.Now(),
	})
}

func classifyIsolatedCreateError(err error) (int, model.ErrorCode) {
	if errors.Is(err, runtime.ErrUidModeUnavailable) ||
		errors.Is(err, runtime.ErrSessionPrivateNetUnavailable) {
		return http.StatusServiceUnavailable, model.ErrorCodeNotSupported
	}
	if errors.Is(err, runtime.ErrSessionNamespaceUnavailable) ||
		errors.Is(err, runtime.ErrIsolatedRunnerClosed) {
		return http.StatusServiceUnavailable, model.ErrorCodeServiceUnavailable
	}
	if strings.Contains(err.Error(), "not in allowlist") ||
		strings.Contains(err.Error(), "not allowed") ||
		strings.Contains(err.Error(), "unknown isolation profile") ||
		strings.Contains(err.Error(), "must be an existing path") ||
		strings.Contains(err.Error(), "must be an absolute path") ||
		strings.Contains(err.Error(), "duplicate overlay path") ||
		strings.Contains(err.Error(), "source is required") {
		return http.StatusBadRequest, model.ErrorCodeRuntimeError
	}
	return http.StatusInternalServerError, model.ErrorCodeRuntimeError
}

// Get handles GET /v1/isolated/session/:sessionId.
func (c *IsolatedSessionController) Get() {
	if !c.initialized() {
		c.RespondError(http.StatusServiceUnavailable, model.ErrorCodeServiceUnavailable, "isolation unavailable")
		return
	}

	sessionID := c.ctx.Param("sessionId")
	state, err := isolatedRunner.GetIsolatedSession(sessionID)
	if err != nil {
		if errors.Is(err, runtime.ErrContextNotFound) {
			c.RespondError(http.StatusNotFound, model.ErrorCodeSessionNotFound, "session not found")
			return
		}
		c.RespondError(http.StatusInternalServerError, model.ErrorCodeRuntimeError, err.Error())
		return
	}

	resp := model.SessionState{
		Status:               state.Status,
		CreatedAt:            state.CreatedAt,
		LastRunAt:            state.LastRunAt,
		IdleRemainingSeconds: state.IdleRemainingSeconds,

		Profile:       state.Profile,
		ExtraWritable: state.ExtraWritable,
		ShareNet:      state.ShareNet,
		Uid:           state.Uid,
		Gid:           state.Gid,
		UidMode:       state.UidMode,
	}
	if len(state.Overlays) > 0 {
		resp.Overlays = make([]model.OverlaySpec, 0, len(state.Overlays))
		for _, ov := range state.Overlays {
			spec := model.OverlaySpec{Path: ov.Path, Mode: ov.Mode}
			if ov.Persist != nil {
				persist := *ov.Persist
				spec.Persist = &persist
			}
			resp.Overlays = append(resp.Overlays, spec)
		}
		// The legacy workspace echo applies to single-overlay sessions only.
		if len(state.Overlays) == 1 {
			resp.Workspace = &model.WorkspaceSpec{
				Path: state.Overlays[0].Path,
				Mode: state.Overlays[0].Mode,
			}
		}
	}
	if len(state.Binds) > 0 {
		resp.Binds = make([]model.BindMount, 0, len(state.Binds))
		for _, b := range state.Binds {
			resp.Binds = append(resp.Binds, model.BindMount{
				Source:   b.Source,
				Dest:     b.Dest,
				ReadOnly: b.ReadOnly,
			})
		}
	}
	if state.EnvPassthroughMode != "" || len(state.EnvPassthroughKeys) > 0 {
		resp.EnvPassthrough = &model.EnvPassthroughSpec{
			Mode: state.EnvPassthroughMode,
			Keys: state.EnvPassthroughKeys,
		}
	}
	// Echo idle_timeout_seconds unconditionally. A value of 0 is meaningful:
	// it means the session was created with idle GC disabled — the exact
	// configuration a stateless caller doing long-window recovery needs to
	// see. Older execd builds that don't set this field are distinguished
	// by the pointer being nil.
	idle := state.IdleTimeoutSeconds
	resp.IdleTimeoutSeconds = &idle
	c.RespondSuccess(resp)
}

func (c *IsolatedSessionController) List() {
	if !c.initialized() {
		c.RespondError(http.StatusServiceUnavailable, model.ErrorCodeServiceUnavailable, "isolation unavailable")
		return
	}

	sessions := isolatedRunner.ListIsolatedSessions()
	items := make([]model.IsolatedSessionSummary, 0, len(sessions))
	for _, s := range sessions {
		items = append(items, model.IsolatedSessionSummary{
			SessionID:            s.SessionID,
			Status:               s.Status,
			CreatedAt:            s.CreatedAt,
			LastRunAt:            s.LastRunAt,
			IdleRemainingSeconds: s.IdleRemainingSeconds,
		})
	}

	c.RespondSuccess(model.ListIsolatedSessionsResponse{Sessions: items})
}

func (c *IsolatedSessionController) Run() {
	if !c.initialized() {
		c.RespondError(http.StatusServiceUnavailable, model.ErrorCodeServiceUnavailable, "isolation unavailable")
		return
	}

	sessionID := c.ctx.Param("sessionId")

	var req model.IsolatedRunRequest
	if err := c.bindJSON(&req); err != nil {
		c.RespondError(http.StatusBadRequest, model.ErrorCodeInvalidRequest, err.Error())
		return
	}
	if err := req.Validate(); err != nil {
		c.RespondError(http.StatusBadRequest, model.ErrorCodeInvalidRequest, err.Error())
		return
	}

	var ctx context.Context
	var cancel context.CancelFunc
	if req.TimeoutSeconds > 0 {
		ctx, cancel = context.WithTimeout(c.ctx.Request.Context(), time.Duration(req.TimeoutSeconds)*time.Second)
	} else {
		ctx, cancel = context.WithCancel(c.ctx.Request.Context())
	}
	defer cancel()

	// Unknown-session runs must stay JSON 404s, so probe before the SSE
	// headers below are committed.
	if _, err := isolatedRunner.GetIsolatedSession(sessionID); err != nil {
		if errors.Is(err, runtime.ErrContextNotFound) {
			c.RespondError(http.StatusNotFound, model.ErrorCodeSessionNotFound, "session not found")
			return
		}
		c.RespondError(http.StatusInternalServerError, model.ErrorCodeRuntimeError, err.Error())
		return
	}

	// Background mode: submit detached, return a run handle, let the client
	// poll status/logs. Deliberately independent of this request's context so
	// a client disconnect cannot cancel detached work. 202 Accepted keeps the
	// JSON handle distinguishable from the foreground SSE 200 stream in
	// generated clients.
	if req.Background {
		runID, startedAt, err := isolatedRunner.RunInIsolatedSessionBackground(sessionID, req.Code, req.Envs)
		if err != nil {
			c.respondRunError(err)
			return
		}
		c.ctx.JSON(http.StatusAccepted, model.IsolatedBackgroundRunResponse{
			SessionID: sessionID,
			RunID:     runID,
			StartedAt: startedAt,
		})
		return
	}

	// Commit SSE headers up front and ping periodically so gateway idle
	// timeouts cannot reap the stream while a silent command runs.
	c.setupSSEResponse()

	pingCtx, pingCancel := context.WithCancel(ctx)
	var pingWg sync.WaitGroup
	pingWg.Add(1)
	safego.Go(func() {
		defer pingWg.Done()
		c.ping(pingCtx)
	})

	onStdout := func(line string) {
		if line == "" {
			return
		}
		event := model.ServerStreamEvent{
			Type:      model.StreamEventTypeStdout,
			Text:      line,
			Timestamp: time.Now().UnixMilli(),
		}
		c.writeSingleEvent("IsolatedStdout", event.ToJSON(), false, event.Summary())
	}

	startTime := time.Now()
	err := isolatedRunner.RunInIsolatedSession(ctx, sessionID, req.Code, req.Envs, onStdout)
	durationMs := float64(time.Since(startTime)) / float64(time.Millisecond)

	// Stop pinging before the final event and handler return.
	pingCancel()
	pingWg.Wait()

	if err != nil {
		if errors.Is(err, runtime.ErrContextNotFound) {
			// The session vanished after the probe (e.g. concurrent delete).
			// SSE headers are already committed, so the failure must go out
			// as a terminal stream event, not a JSON body.
			telemetry.RecordIsolatedRun(ctx, "error", durationMs)
			c.writeIsolatedRunError("SessionNotFound", "session not found")
			return
		}
		telemetry.RecordIsolatedRun(ctx, "error", durationMs)
		ename := "RuntimeError"
		evalue := err.Error()
		if strings.HasPrefix(evalue, "command exited with code ") {
			ename = "ExitError"
			evalue = strings.TrimPrefix(evalue, "command exited with code ")
		}
		c.writeIsolatedRunError(ename, evalue)
		return
	}
	telemetry.RecordIsolatedRun(ctx, "success", durationMs)
	event := model.ServerStreamEvent{
		Type:      model.StreamEventTypeComplete,
		Timestamp: time.Now().UnixMilli(),
	}
	c.writeSingleEvent("IsolatedComplete", event.ToJSON(), true, event.Summary())
}

// writeIsolatedRunError emits a terminal IsolatedError SSE event; only call
// after the SSE headers are committed.
func (c *IsolatedSessionController) writeIsolatedRunError(ename, evalue string) {
	event := model.ServerStreamEvent{
		Type:      model.StreamEventTypeError,
		Text:      evalue,
		Timestamp: time.Now().UnixMilli(),
		Error: &execute.ErrorOutput{
			EName:  ename,
			EValue: evalue,
		},
	}
	c.writeSingleEvent("IsolatedError", event.ToJSON(), true, event.Summary())
}

func (c *IsolatedSessionController) respondRunError(err error) {
	if errors.Is(err, runtime.ErrContextNotFound) {
		c.RespondError(http.StatusNotFound, model.ErrorCodeSessionNotFound, "session not found")
		return
	}
	if errors.Is(err, runtime.ErrSessionNotActive) {
		c.RespondError(http.StatusBadRequest, model.ErrorCodeInvalidRequest, err.Error())
		return
	}
	c.RespondError(http.StatusBadRequest, model.ErrorCodeInvalidRequest, err.Error())
}

func (c *IsolatedSessionController) GetRunStatus() {
	if !c.initialized() {
		c.RespondError(http.StatusServiceUnavailable, model.ErrorCodeServiceUnavailable, "isolation unavailable")
		return
	}

	sessionID := c.ctx.Param("sessionId")
	runID := c.ctx.Param("runId")
	snapshot, err := isolatedRunner.GetIsolatedBackgroundRun(sessionID, runID)
	if err != nil {
		c.respondRunError(err)
		return
	}

	resp := model.IsolatedRunStatus{
		SessionID: snapshot.SessionID,
		RunID:     snapshot.RunID,
		Running:   snapshot.Running,
		ExitCode:  snapshot.ExitCode,
		Error:     snapshot.Error,
		StartedAt: snapshot.StartedAt,
	}
	if snapshot.FinishedAt != nil {
		resp.FinishedAt = snapshot.FinishedAt
	}
	c.RespondSuccess(resp)
}

// The body is the combined stdout/stderr of the run as plain text; the
// EXECD-ISOLATED-TAIL-CURSOR response header carries the next byte cursor for
// incremental polling.
func (c *IsolatedSessionController) GetRunLogs() {
	if !c.initialized() {
		c.RespondError(http.StatusServiceUnavailable, model.ErrorCodeServiceUnavailable, "isolation unavailable")
		return
	}

	sessionID := c.ctx.Param("sessionId")
	runID := c.ctx.Param("runId")
	cursorRaw := c.ctx.Query("cursor")
	var cursor int64
	if cursorRaw != "" {
		parsed, err := strconv.ParseInt(cursorRaw, 10, 64)
		if err != nil {
			c.RespondError(http.StatusBadRequest, model.ErrorCodeInvalidRequest, "cursor must be an integer")
			return
		}
		cursor = parsed
	}
	if cursor < 0 {
		c.RespondError(http.StatusBadRequest, model.ErrorCodeInvalidRequest, "cursor cannot be negative")
		return
	}
	output, lastCursor, err := isolatedRunner.SeekIsolatedBackgroundOutput(sessionID, runID, cursor)
	if err != nil {
		c.respondRunError(err)
		return
	}

	c.ctx.Header("EXECD-ISOLATED-TAIL-CURSOR", strconv.FormatInt(lastCursor, 10))
	c.ctx.Header("Content-Type", "text/plain; charset=utf-8")
	c.ctx.String(http.StatusOK, "%s", output)
}

func (c *IsolatedSessionController) Delete() {
	if !c.initialized() {
		c.RespondError(http.StatusServiceUnavailable, model.ErrorCodeServiceUnavailable, "isolation unavailable")
		return
	}

	sessionID := c.ctx.Param("sessionId")
	if err := isolatedRunner.DeleteIsolatedSession(sessionID); err != nil {
		status, code := classifyIsolatedDeleteError(err)
		if status == http.StatusNotFound {
			c.RespondError(http.StatusNotFound, model.ErrorCodeSessionNotFound, "session not found")
			return
		}
		c.RespondError(status, code, err.Error())
		return
	}

	c.RespondSuccess(nil)
}

func classifyIsolatedDeleteError(err error) (int, model.ErrorCode) {
	if errors.Is(err, runtime.ErrContextNotFound) {
		return http.StatusNotFound, model.ErrorCodeSessionNotFound
	}
	if errors.Is(err, runtime.ErrSessionNamespaceCleanup) {
		return http.StatusServiceUnavailable, model.ErrorCodeServiceUnavailable
	}
	return http.StatusInternalServerError, model.ErrorCodeRuntimeError
}

func (c *IsolatedSessionController) Diff() {
	c.RespondError(http.StatusServiceUnavailable, model.ErrorCodeNotSupported, "diff not implemented yet (phase 2)")
}

func (c *IsolatedSessionController) Commit() {
	c.RespondError(http.StatusServiceUnavailable, model.ErrorCodeNotSupported, "commit not implemented yet (phase 2)")
}

func (c *IsolatedSessionController) Capabilities() {
	hardeningReport := runtime.ReportHardening()
	hardening := &model.HardeningStatus{
		InitMode:     hardeningReport.InitMode,
		SignalShield: hardeningReport.SignalShield,
		CapDrop: &model.HardeningLayerState{
			State:   hardeningReport.CapDrop.State,
			Message: hardeningReport.CapDrop.Message,
		},
		Seccomp: &model.HardeningLayerState{
			State:   hardeningReport.Seccomp.State,
			Message: hardeningReport.Seccomp.Message,
		},
		Landlock: &model.HardeningLayerState{
			State:   hardeningReport.Landlock.State,
			Message: hardeningReport.Landlock.Message,
		},
		Ebpf: &model.HardeningLayerState{
			State:   hardeningReport.Ebpf.State,
			Message: hardeningReport.Ebpf.Message,
		},
	}
	runtimeInit := &model.RuntimeInitStatus{Version: 1}
	if isolatedRunner == nil {
		resp := model.CapabilitiesResponse{
			Available:       false,
			CommitSupported: false,
			DiffSupported:   false,
			Hardening:       hardening,
			RuntimeInit:     runtimeInit,
		}
		if isolatedProbeResult != nil {
			resp.Isolator = isolatedProbeResult.Isolator
			resp.Version = isolatedProbeResult.Version
			resp.Message = isolatedProbeResult.Message
			resp.SetprivAvailable = isolatedProbeResult.SetprivAvailable
			resp.UsernsAvailable = isolatedProbeResult.UsernsAvailable
			resp.SetprivNetAvailable = isolatedProbeResult.SetprivNetAvailable
			resp.UsernsNetAvailable = isolatedProbeResult.UsernsNetAvailable
		}
		c.RespondSuccess(resp)
		return
	}
	caps := isolatedRunner.Capabilities()
	resp := model.CapabilitiesResponse{
		Available:           caps.Available,
		Isolator:            caps.Isolator,
		Version:             caps.Version,
		Message:             caps.Message,
		SetprivAvailable:    caps.SetprivAvailable,
		UsernsAvailable:     caps.UsernsAvailable,
		SetprivNetAvailable: caps.SetprivNetAvailable,
		UsernsNetAvailable:  caps.UsernsNetAvailable,
		CommitSupported:     caps.CommitSupported,
		DiffSupported:       caps.DiffSupported,
		Hardening:           hardening,
		RuntimeInit:         runtimeInit,
	}
	// Probe results indicate overlay capability, not diff/commit implementation.
	// Diff and commit are Phase 2; do not advertise them as supported.
	resp.CommitSupported = false
	resp.DiffSupported = false
	c.RespondSuccess(resp)
}

// Filesystem proxy handlers are in isolated_session_files.go.