Skip to content

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.go
index 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, co
return 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.Builder
script.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, co
select {
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.go
index 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.T
t.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.go
index 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.go
index 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