Secure, Fast, and Extensible Sandbox runtime for AI agents.
docs(execd): tighten comments in isolated run keepalive/signal fix
高然c3b6fef72c04
diff --git a/components/execd/pkg/runtime/isolated_session_ctrl.go b/components/execd/pkg/runtime/isolated_session_ctrl.goindex 947d1dfd3..61f7d26af 100644--- a/components/execd/pkg/runtime/isolated_session_ctrl.go+++ b/components/execd/pkg/runtime/isolated_session_ctrl.go@@ -42,14 +42,11 @@ import (const isolatedRunEndMarkerPrefix = "__ISOLATED_RUN_END__"// isolatedInterruptEscalationTimeout bounds how long a cancelled run waits-// after SIGINT before escalating to SIGKILL. It gives a well-behaved command-// time to wind down while guaranteeing a SIGINT-immune command cannot hold-// the session's run mutex forever.+// for its end marker before the session process group is SIGKILLed.var isolatedInterruptEscalationTimeout = 10 * time.Second-// isolatedInterruptRepeatInterval is the SIGINT re-send period during the-// escalation window. Repeated SIGINTs drain a no-envs script tail statement-// by statement without harming the trapped shell.+// isolatedInterruptRepeatInterval is the SIGINT re-send period used while+// draining a cancelled no-envs script tail.var isolatedInterruptRepeatInterval = 500 * time.Millisecond// IsolatedRunner is the concrete isolated session runner.@@ -653,16 +650,14 @@ func (r *IsolatedRunner) RunInIsolatedSession(ctx context.Context, id string, coreturn fmt.Errorf("session not started")}- // Prepend env exports before user code.+ // The per-run UUID makes it impossible for user output to forge this+ // run's end marker.runMarker := fmt.Sprintf("%s_%s", isolatedRunEndMarkerPrefix, uuid.New().String())- // trap : INT keeps the persistent shell alive when the session process- // group is signalled: the shell catches SIGINT (the trap runs after the- // foreground child exits) while the running command dies with the default- // disposition. When envs are supplied the code already runs in a subshell,- // so an interrupt ends the whole run; without envs the code must stay in- // the main shell to keep user exports visible to later runs, and an- // interrupt then stops the currently executing line only.+ // trap : INT makes the cancellation SIGINT kill the running command, not+ // the persistent shell. Envs runs are subshell-wrapped so an interrupt+ // aborts the whole script; no-envs runs stay in the main shell to keep+ // cross-run exports working.var script strings.Builderscript.WriteString("trap : INT\n")if len(envs) > 0 {@@ -680,16 +675,12 @@ func (r *IsolatedRunner) RunInIsolatedSession(ctx context.Context, id string, co}script.WriteString(fmt.Sprintf("echo %s $?\n", runMarker))- // On timeout/cancel, send SIGINT to interrupt the running command- // without killing the persistent shell session. Closing stdin would- // terminate the shell entirely.done := make(chan struct{})watcherDone := make(chan struct{})defer func() {close(done)- // Keep runMu held until the watcher has either observed done or- // completed its SIGINT. Otherwise a delayed cancellation from this Run- // can interrupt the next serialized Run.+ // Hold runMu until the watcher's final signal completes, so a late+ // cancellation cannot interrupt the next serialized run.<-watcherDone}()go func() {@@ -697,15 +688,10 @@ func (r *IsolatedRunner) RunInIsolatedSession(ctx context.Context, id string, coselect {case <-ctx.Done():_ = s.signalProcessGroupIfRunning(syscall.SIGINT)- // Without envs the script is not subshell-wrapped: after the- // first SIGINT the persistent shell advances to the remaining- // buffered statements of the cancelled run. Repeating SIGINT- // kills each newly started statement (the trap keeps the shell- // alive) so the tail drains to the end marker quickly instead- // of running to completion. Only if the marker still has not- // arrived after the escalation window is the command assumed- // to ignore SIGINT; SIGKILL then ends the wedged run (and the- // session) deterministically instead of hanging forever.+ // No-envs scripts queue their remaining statements in the shell+ // after the interrupt; repeated SIGINT kills each as it starts+ // (the trap keeps the shell alive). A marker still missing after+ // the deadline means SIGINT is being ignored: escalate.ticker := time.NewTicker(isolatedInterruptRepeatInterval)defer ticker.Stop()deadline := time.After(isolatedInterruptEscalationTimeout)diff --git a/components/execd/pkg/runtime/isolated_session_interrupt_test.go b/components/execd/pkg/runtime/isolated_session_interrupt_test.goindex 4a890614b..c62130b9c 100644--- a/components/execd/pkg/runtime/isolated_session_interrupt_test.go+++ b/components/execd/pkg/runtime/isolated_session_interrupt_test.go@@ -37,10 +37,9 @@ func newInterruptTestSession(t *testing.T) (*IsolatedRunner, string) {return runner, id}-// TestRunInIsolatedSession_InterruptKeepsSessionAlive verifies the public-// contract that a cancelled run (client disconnect or timeout_seconds expiry)-// interrupts the running command without killing or deregistering the-// persistent session, so the next run on the same session succeeds.+// TestRunInIsolatedSession_InterruptKeepsSessionAlive verifies that a+// cancelled run interrupts the command but leaves the session alive and+// usable for the next run.func TestRunInIsolatedSession_InterruptKeepsSessionAlive(t *testing.T) {runner, id := newInterruptTestSession(t)@@ -75,9 +74,8 @@ func TestRunInIsolatedSession_InterruptKeepsSessionAlive(t *testing.T) {}// TestRunInIsolatedSession_InterruptedRunDoesNotLeakIntoNext verifies that an-// interrupt ends the whole run when the code is wrapped in a subshell (envs-// supplied): later lines of the interrupted code must never execute and must-// not pollute the next run's output.+// interrupt aborts a subshell-wrapped (envs) script before its later lines+// run, without polluting the next run's output.func TestRunInIsolatedSession_InterruptedRunDoesNotLeakIntoNext(t *testing.T) {runner, id := newInterruptTestSession(t)@@ -109,10 +107,8 @@ func TestRunInIsolatedSession_InterruptedRunDoesNotLeakIntoNext(t *testing.T) {}// TestRunInIsolatedSession_CancelledScriptTailDoesNotKillSession verifies-// that a cancelled no-envs run whose remaining statements execute after the-// interrupt cannot trip the SIGKILL escalation: repeated SIGINTs drain the-// buffered tail statement by statement while the trapped shell survives, so-// the session stays alive and accepts follow-up runs.+// that repeated SIGINTs drain a cancelled no-envs script tail without+// tripping the SIGKILL escalation, so the session survives follow-up runs.func TestRunInIsolatedSession_CancelledScriptTailDoesNotKillSession(t *testing.T) {runner, id := newInterruptTestSession(t)@@ -127,9 +123,8 @@ func TestRunInIsolatedSession_CancelledScriptTailDoesNotKillSession(t *testing.Tt.Fatalf("interrupted run error = %v, want context.DeadlineExceeded", err)}- // Stay past the escalation deadline (300ms cancel + 1500ms grace). With- // only a single SIGINT the second statement would still be running and- // the watcher would have SIGKILLed the whole session by now.+ // Past the escalation deadline: a single-SIGINT watcher would have+ // SIGKILLed the session by now.time.Sleep(2 * time.Second)s := runner.lookup(id)@@ -148,9 +143,8 @@ func TestRunInIsolatedSession_CancelledScriptTailDoesNotKillSession(t *testing.T}// TestRunInIsolatedSession_EscalatesWhenInterruptIgnored verifies that a-// command which ignores SIGINT cannot wedge the session's run mutex forever:-// the watcher escalates to SIGKILL, the run fails, and the wedged session is-// torn down so the failure is observable instead of a silent hang.+// SIGINT-immune command cannot wedge the session forever: the watcher+// escalates to SIGKILL and the session reports dead.func TestRunInIsolatedSession_EscalatesWhenInterruptIgnored(t *testing.T) {runner, id := newInterruptTestSession(t)@@ -169,9 +163,8 @@ func TestRunInIsolatedSession_EscalatesWhenInterruptIgnored(t *testing.T) {t.Fatalf("escalated run took %v; SIGINT-immune command was not killed", elapsed)}- // The SIGKILL reaps the session process, so the session must turn dead- // and reject further work. (The test isolator's lifecycle only drains on- // explicit delete, so registry removal is not asserted here.)+ // SIGKILL reaps the session process; the registry entry only goes away+ // on explicit delete, so assert dead() instead.deadline := time.Now().Add(5 * time.Second)for {s := runner.lookup(id)diff --git a/components/execd/pkg/web/controller/isolated_session.go b/components/execd/pkg/web/controller/isolated_session.goindex a3ae64586..676f593df 100644--- a/components/execd/pkg/web/controller/isolated_session.go+++ b/components/execd/pkg/web/controller/isolated_session.go@@ -267,9 +267,8 @@ func (c *IsolatedSessionController) Run() {}defer cancel()- // Fail fast on an unknown session while the response is still JSON:- // once SSE headers are committed below, errors can only be delivered as- // stream events.+ // 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")@@ -298,10 +297,8 @@ func (c *IsolatedSessionController) Run() {return}- // Foreground mode: stream via SSE. Commit the response headers up front- // and keep the stream alive with periodic pings so gateway idle timeouts- // cannot reap the connection while a silent command (e.g. pip install)- // produces no stdout for long stretches.+ // 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)@@ -328,20 +325,15 @@ func (c *IsolatedSessionController) Run() {err := isolatedRunner.RunInIsolatedSession(ctx, sessionID, req.Code, req.Envs, onStdout)durationMs := float64(time.Since(startTime)) / float64(time.Millisecond)- // Stop the ping goroutine before the final event and before the handler- // returns, so nothing writes to the response writer after Go's net/http- // closes it.+ // Stop pinging before the final event and handler return.pingCancel()pingWg.Wait()if err != nil {if errors.Is(err, runtime.ErrContextNotFound) {- // The session can vanish between the pre-flight probe and the- // run's internal lookup (concurrent DELETE, exited-session- // cleanup). SSE headers are already committed at this point, so- // the status code can no longer change — surface the failure as- // a terminal stream event instead of appending a JSON body- // mid-stream.+ // 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@@ -364,6 +356,8 @@ func (c *IsolatedSessionController) Run() {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,diff --git a/components/execd/pkg/web/controller/sse.go b/components/execd/pkg/web/controller/sse.goindex 2d8d251a1..d183eefc7 100644--- a/components/execd/pkg/web/controller/sse.go+++ b/components/execd/pkg/web/controller/sse.go@@ -37,9 +37,8 @@ var sseHeaders = map[string]string{"X-Accel-Buffering": "no",}-// ssePingInterval is the keepalive period for SSE streams. It must stay well-// below downstream gateway/proxy idle timeouts so a silent command (e.g. a-// long pip install producing no stdout) cannot get the stream reaped.+// ssePingInterval is the SSE keepalive period; it must stay well below+// gateway idle timeouts so silent commands cannot get the stream reaped.var ssePingInterval = 3 * time.Second// setupSSEResponse is idempotent: once headers are committed, subsequent calls