Skip to content

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

fix(sdk-go): stop retrying non-idempotent writes by default

JasonBuildAI7662cbc72a56
diff --git a/sdks/sandbox/go/http.go b/sdks/sandbox/go/http.go
index f8dc65787..094f935d8 100644
--- a/sdks/sandbox/go/http.go
+++ b/sdks/sandbox/go/http.go
@@ -301,7 +301,7 @@ func (c *Client) doRequest(ctx context.Context, method, path string, body any, r
// non-nil. It exists for callers that need server-reported response metadata
// (e.g. the OPEN-SANDBOX-ORIGIN header) that is not part of the JSON body.
func (c *Client) doRequestCapture(ctx context.Context, method, path string, body, result any, capture func(http.Header)) error {
- return c.withRetry(ctx, func() error {
+ return c.withRetryMethod(ctx, method, func() error {
var reused bool
err := c.doRequestOnce(ctx, method, path, body, result, &reused, capture)
if err != nil && reused && c.shouldRetryOnFreshConn(ctx, method, err) {
@@ -415,13 +415,13 @@ func (c *Client) doRequestOnce(ctx context.Context, method, path string, body an
}
// doStreamRequest builds an HTTP request, executes it, and streams SSE events
-// through handler. Connection setup is retried on transient errors; once
-// streaming begins, errors are not retried (partial data may have been
-// delivered to the handler).
+// through handler. Connection setup follows the method-aware retry policy; once
+// streaming begins, errors are not retried (partial data may have been delivered
+// to the handler).
func (c *Client) doStreamRequest(ctx context.Context, method, path string, body any, handler EventHandler) error {
var resp *http.Response
- connectErr := c.withRetryWake(ctx, false, func() error {
+ connectErr := c.withRetryWake(ctx, false, method, func() error {
var bodyReader io.Reader
if body != nil {
buf, err := json.Marshal(body)
diff --git a/sdks/sandbox/go/retry.go b/sdks/sandbox/go/retry.go
index 32b1a0d4e..ff8c25caf 100644
--- a/sdks/sandbox/go/retry.go
+++ b/sdks/sandbox/go/retry.go
@@ -48,10 +48,17 @@ type RetryConfig struct {
Jitter float64
// RetryableStatusCodes optionally overrides which HTTP status codes are
- // treated as transient for retry decisions. When empty, SDK defaults are
- // used (429, 502, 503, 504).
+ // treated as transient for idempotent requests (GET, HEAD, PUT, DELETE,
+ // and OPTIONS). When empty, SDK defaults are used (429, 502, 503, 504).
RetryableStatusCodes []int
+ // RetryableStatusCodesNonIdempotent lists HTTP status codes that may be
+ // retried for POST and PATCH requests. It is empty by default because a
+ // repeated write can duplicate its side effects. Set this only when the
+ // operation is idempotent at the application layer or duplicate execution
+ // is acceptable.
+ RetryableStatusCodesNonIdempotent []int
+
// WakeRetryEnabled controls automatic retry of gateway wake-timeout
// responses (OSEP-0024): a 503 carrying the "OpenSandbox-Wake: expired"
// marker proves the request was never forwarded, so the original request
@@ -138,8 +145,12 @@ func DefaultRetryConfig() RetryConfig {
}
// WithRetry enables automatic retry with exponential backoff for transient
-// errors and network failures. By default, transient status codes are
-// 429/502/503/504; override RetryConfig.RetryableStatusCodes to customize.
+// errors and network failures. Idempotent requests retry 429/502/503/504 by
+// default; override RetryConfig.RetryableStatusCodes to customize. POST and
+// PATCH retry only transport failures provably raised before any request bytes
+// are sent (currently dial failures), unless
+// RetryConfig.RetryableStatusCodesNonIdempotent opts into specific status
+// codes.
func WithRetry(cfg RetryConfig) Option {
return func(c *Client) {
c.retry = &cfg
@@ -168,7 +179,25 @@ func isTransientStatus(code int) bool {
}
}
-func (r *RetryConfig) isRetryableStatus(code int) bool {
+func isIdempotentMethod(method string) bool {
+ switch strings.ToUpper(method) {
+ case http.MethodGet, http.MethodHead, http.MethodPut, http.MethodDelete, http.MethodOptions:
+ return true
+ default:
+ return false
+ }
+}
+
+func (r *RetryConfig) isRetryableStatus(method string, code int) bool {
+ if !isIdempotentMethod(method) {
+ for _, c := range r.RetryableStatusCodesNonIdempotent {
+ if c == code {
+ return true
+ }
+ }
+ return false
+ }
+
codes := r.RetryableStatusCodes
if len(codes) == 0 {
return isTransientStatus(code)
@@ -181,18 +210,35 @@ func (r *RetryConfig) isRetryableStatus(code int) bool {
return false
}
-// isTransientError checks whether err should trigger a retry. It handles
-// *APIError (HTTP status classification) and net.Error (network-level).
-func isTransientError(err error, cfg *RetryConfig) bool {
+// isPreSendError reports whether err proves that no request bytes reached the
+// server. Go surfaces dial failures (including DNS and TCP connect failures)
+// as *net.OpError with Op == "dial"; OSEP-0017 requires classifying those as
+// safe to retry for any method.
+func isPreSendError(err error) bool {
+ var opErr *net.OpError
+ return errors.As(err, &opErr) && opErr.Op == "dial"
+}
+
+// isTransientErrorForMethod checks whether err should trigger a generic retry
+// for method. Status-code retries are method-specific, pre-send transport
+// failures are safe for every method, and ambiguous transport failures are
+// retried only for idempotent methods.
+func isTransientErrorForMethod(err error, cfg *RetryConfig, method string) bool {
if err == nil {
return false
}
var apiErr *APIError
if errors.As(err, &apiErr) {
if cfg != nil {
- return cfg.isRetryableStatus(apiErr.StatusCode)
+ return cfg.isRetryableStatus(method, apiErr.StatusCode)
}
- return apiErr.IsTransient()
+ return isIdempotentMethod(method) && apiErr.IsTransient()
+ }
+ if isPreSendError(err) {
+ return true
+ }
+ if !isIdempotentMethod(method) {
+ return false
}
var netErr net.Error
return errors.As(err, &netErr)
@@ -276,9 +322,9 @@ func retrySleep(ctx context.Context, d time.Duration) error {
}
}
-// withRetry executes fn, retrying on transient errors per the client's
-// RetryConfig. If retry is nil, or both MaxRetries and the wake contract are
-// inactive, fn is called once.
+// withRetry executes an idempotent operation, retrying on transient errors per
+// the client's RetryConfig. Callers issuing POST or PATCH must use
+// withRetryMethod so that method-aware retry safety applies.
//
// The OSEP-0024 wake contract is enforced on top of the generic policy: a
// marked wake-timeout error (503 + "OpenSandbox-Wake: expired") is retried
@@ -286,7 +332,12 @@ func retrySleep(ctx context.Context, d time.Duration) error {
// always safe — under its own attempt count and wall-clock budget. Bare 503
// responses follow the generic rules untouched.
func (c *Client) withRetry(ctx context.Context, fn func() error) error {
- return c.withRetryWake(ctx, true, fn)
+ return c.withRetryMethod(ctx, http.MethodGet, fn)
+}
+
+// withRetryMethod executes fn with the generic retry policy tailored to method.
+func (c *Client) withRetryMethod(ctx context.Context, method string, fn func() error) error {
+ return c.withRetryWake(ctx, true, method, fn)
}
// withRetryWake is withRetry with control over the wake contract. Streaming
@@ -295,7 +346,7 @@ func (c *Client) withRetry(ctx context.Context, fn func() error) error {
// falls back to the generic policy's bare-503 rules (retried only when the
// method/status qualify), matching the other official SDKs, which leave their
// streaming transports unwrapped.
-func (c *Client) withRetryWake(ctx context.Context, wakeEnabled bool, fn func() error) error {
+func (c *Client) withRetryWake(ctx context.Context, wakeEnabled bool, method string, fn func() error) error {
if c.retry == nil || (c.retry.MaxRetries == 0 && !(wakeEnabled && c.retry.wakeEnabled())) {
return fn()
}
@@ -356,7 +407,7 @@ func (c *Client) withRetryWake(ctx context.Context, wakeEnabled bool, fn func()
continue
}
- if !isTransientError(lastErr, c.retry) {
+ if !isTransientErrorForMethod(lastErr, c.retry, method) {
return lastErr
}
if retriesUsed >= c.retry.MaxRetries {
diff --git a/sdks/sandbox/go/retry_non_idempotent_test.go b/sdks/sandbox/go/retry_non_idempotent_test.go
new file mode 100644
index 000000000..8cf8016cc
--- /dev/null
+++ b/sdks/sandbox/go/retry_non_idempotent_test.go
@@ -0,0 +1,153 @@
+// 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 opensandbox
+
+import (
+ "context"
+ "fmt"
+ "io"
+ "net"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "sync/atomic"
+ "testing"
+ "time"
+)
+
+func TestRetry_NonIdempotentStatusCodesNotRetriedByDefault(t *testing.T) {
+ t.Run("POST CreateSession", func(t *testing.T) {
+ srv, attempts := newRetryFailureServer(http.StatusServiceUnavailable)
+ defer srv.Close()
+
+ client := NewExecdClient(srv.URL, "token", WithRetry(RetryConfig{
+ MaxRetries: 1,
+ InitialBackoff: time.Millisecond,
+ }))
+
+ _, err := client.CreateSession(context.Background())
+ requireStatusError(t, err, http.StatusServiceUnavailable)
+ require.Equal(t, int32(1), attempts.Load())
+ })
+
+ t.Run("PATCH PatchSandboxMetadata", func(t *testing.T) {
+ srv, attempts := newRetryFailureServer(http.StatusServiceUnavailable)
+ defer srv.Close()
+
+ client := NewLifecycleClient(srv.URL, "key", WithRetry(RetryConfig{
+ MaxRetries: 1,
+ InitialBackoff: time.Millisecond,
+ }))
+
+ _, err := client.PatchSandboxMetadata(context.Background(), "sbx-1", MetadataPatch{})
+ requireStatusError(t, err, http.StatusServiceUnavailable)
+ require.Equal(t, int32(1), attempts.Load())
+ })
+}
+
+func TestRetry_NonIdempotentStatusOptIn(t *testing.T) {
+ var attempts atomic.Int32
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if attempts.Add(1) == 1 {
+ w.WriteHeader(http.StatusServiceUnavailable)
+ _, _ = w.Write([]byte(`{"code":"UNAVAILABLE","message":"try again"}`))
+ return
+ }
+ jsonResponse(w, http.StatusOK, Session{ID: "session-1"})
+ }))
+ defer srv.Close()
+
+ client := NewExecdClient(srv.URL, "token", WithRetry(RetryConfig{
+ MaxRetries: 1,
+ InitialBackoff: time.Millisecond,
+ RetryableStatusCodesNonIdempotent: []int{http.StatusServiceUnavailable},
+ }))
+
+ session, err := client.CreateSession(context.Background())
+ require.NoError(t, err)
+ require.Equal(t, "session-1", session.ID)
+ require.Equal(t, int32(2), attempts.Load())
+}
+
+func TestRetry_NonIdempotentTransportFailures(t *testing.T) {
+ tests := []struct {
+ name string
+ op string
+ wantAttempts int32
+ wantSuccess bool
+ }{
+ {"pre-send dial retried", "dial", 2, true},
+ {"post-send read not retried", "read", 1, false},
+ }
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ var attempts atomic.Int32
+ transport := retryRoundTripFunc(func(*http.Request) (*http.Response, error) {
+ if attempts.Add(1) == 1 || !tt.wantSuccess {
+ return nil, &net.OpError{Op: tt.op, Net: "tcp", Err: fmt.Errorf("transport failure")}
+ }
+ return retryJSONResponse(`{"session_id":"session-1"}`), nil
+ })
+ client := NewExecdClient("http://example.invalid", "token",
+ WithHTTPClient(&http.Client{Transport: transport}),
+ WithRetry(RetryConfig{MaxRetries: 1, InitialBackoff: time.Millisecond}),
+ )
+
+ session, err := client.CreateSession(context.Background())
+ if tt.wantSuccess {
+ require.NoError(t, err)
+ require.Equal(t, "session-1", session.ID)
+ } else {
+ require.Error(t, err)
+ var netErr net.Error
+ require.ErrorAs(t, err, &netErr)
+ }
+ require.Equal(t, tt.wantAttempts, attempts.Load())
+ })
+ }
+}
+
+type retryRoundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f retryRoundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+ return f(req)
+}
+
+func retryJSONResponse(body string) *http.Response {
+ return &http.Response{
+ StatusCode: http.StatusOK,
+ Status: "200 OK",
+ Header: make(http.Header),
+ Body: io.NopCloser(strings.NewReader(body)),
+ }
+}
+
+func newRetryFailureServer(status int) (*httptest.Server, *atomic.Int32) {
+ var attempts atomic.Int32
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ attempts.Add(1)
+ w.WriteHeader(status)
+ _, _ = w.Write([]byte(`{"code":"UNAVAILABLE","message":"try again"}`))
+ }))
+ return srv, &attempts
+}
+
+func requireStatusError(t *testing.T, err error, status int) {
+ t.Helper()
+ require.Error(t, err)
+ var apiErr *APIError
+ require.ErrorAs(t, err, &apiErr)
+ require.Equal(t, status, apiErr.StatusCode)
+}
diff --git a/sdks/sandbox/go/retry_test.go b/sdks/sandbox/go/retry_test.go
index 8955858fa..08c80526c 100644
--- a/sdks/sandbox/go/retry_test.go
+++ b/sdks/sandbox/go/retry_test.go
@@ -24,8 +24,10 @@ import (
"crypto/x509"
"fmt"
"math/big"
+ "net"
"net/http"
"net/http/httptest"
+ "strings"
"sync/atomic"
"testing"
"time"
@@ -57,6 +59,16 @@ func TestIsTransient(t *testing.T) {
}
}
+func TestIsIdempotentMethod(t *testing.T) {
+ for _, method := range []string{http.MethodGet, http.MethodHead, http.MethodPut, http.MethodDelete, http.MethodOptions} {
+ require.True(t, isIdempotentMethod(method), method)
+ require.True(t, isIdempotentMethod(strings.ToLower(method)), "case-insensitive "+method)
+ }
+ for _, method := range []string{http.MethodPost, http.MethodPatch, http.MethodTrace} {
+ require.Equal(t, false, isIdempotentMethod(method), method)
+ }
+}
+
func TestRetry_TransientThenSuccess(t *testing.T) {
var attempts atomic.Int32
@@ -262,7 +274,7 @@ func TestRetry_RateLimit429(t *testing.T) {
}
}
-func TestRetry_StreamingConnection(t *testing.T) {
+func TestRetry_StreamingConnectionNotRetried(t *testing.T) {
var attempts atomic.Int32
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -290,13 +302,12 @@ func TestRetry_StreamingConnection(t *testing.T) {
events = append(events, event)
return nil
})
- require.NoErrorf(t, err, "expected success after stream retry, got")
- if len(events) != 1 || events[0].Data != "hello" {
- assert.Fail(t, fmt.Sprintf("events = %+v, want [{Event:stdout Data:hello}]", events))
- }
- if attempts.Load() != 2 {
- assert.Fail(t, fmt.Sprintf("attempts = %d, want 2", attempts.Load()))
- }
+ require.Error(t, err, "a POST stream must not be replayed after a 503")
+ require.Len(t, events, 0)
+ require.Equal(t, int32(1), attempts.Load())
+ var apiErr *APIError
+ require.ErrorAs(t, err, &apiErr)
+ require.Equal(t, http.StatusServiceUnavailable, apiErr.StatusCode)
}
func TestBackoff(t *testing.T) {
@@ -586,24 +597,58 @@ func TestParseRetryAfter_NilResponse(t *testing.T) {
}
func TestIsTransientError(t *testing.T) {
+ idempotentOnlyOptIn := &RetryConfig{
+ RetryableStatusCodes: []int{http.StatusTooManyRequests},
+ }
+ nonIdempotentOptIn := &RetryConfig{
+ RetryableStatusCodesNonIdempotent: []int{http.StatusServiceUnavailable},
+ }
tests := []struct {
name string
+ method string
err error
+ cfg *RetryConfig
transient bool
}{
- {"nil", nil, false},
- {"api 503", &APIError{StatusCode: 503}, true},
- {"api 429", &APIError{StatusCode: 429}, true},
- {"api 404", &APIError{StatusCode: 404}, false},
- {"api 400", &APIError{StatusCode: 400}, false},
- {"api 502", &APIError{StatusCode: 502}, true},
- {"api 504", &APIError{StatusCode: 504}, true},
- {"api 500", &APIError{StatusCode: 500}, false},
+ {"nil", http.MethodGet, nil, nil, false},
+ {"api 503 GET", http.MethodGet, &APIError{StatusCode: 503}, nil, true},
+ {"api 429 GET", http.MethodGet, &APIError{StatusCode: 429}, nil, true},
+ {"api 404 GET", http.MethodGet, &APIError{StatusCode: 404}, nil, false},
+ {"api 400 GET", http.MethodGet, &APIError{StatusCode: 400}, nil, false},
+ {"api 502 GET", http.MethodGet, &APIError{StatusCode: 502}, nil, true},
+ {"api 504 GET", http.MethodGet, &APIError{StatusCode: 504}, nil, true},
+ {"api 500 GET", http.MethodGet, &APIError{StatusCode: 500}, nil, false},
+ {"api 503 POST default", http.MethodPost, &APIError{StatusCode: 503}, nil, false},
+ {"api 503 PATCH default", http.MethodPatch, &APIError{StatusCode: 503}, nil, false},
+ {"api 503 POST opt-in", http.MethodPost, &APIError{StatusCode: 503}, nonIdempotentOptIn, true},
+ {"api 429 POST not opted in", http.MethodPost, &APIError{StatusCode: 429}, nonIdempotentOptIn, false},
+ {"api 429 POST ignores idempotent opt-in", http.MethodPost, &APIError{StatusCode: 429}, idempotentOnlyOptIn, false},
+ {
+ "dial failure POST",
+ http.MethodPost,
+ &net.OpError{Op: "dial", Net: "tcp", Err: fmt.Errorf("connection refused")},
+ nil,
+ true,
+ },
+ {
+ "read failure POST",
+ http.MethodPost,
+ &net.OpError{Op: "read", Net: "tcp", Err: fmt.Errorf("connection reset")},
+ nil,
+ false,
+ },
+ {
+ "read failure GET",
+ http.MethodGet,
+ &net.OpError{Op: "read", Net: "tcp", Err: fmt.Errorf("connection reset")},
+ nil,
+ true,
+ },
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
- if got := isTransientError(tt.err, nil); got != tt.transient {
- assert.Fail(t, fmt.Sprintf("isTransientError(%v) = %v, want %v", tt.err, got, tt.transient))
+ if got := isTransientErrorForMethod(tt.err, tt.cfg, tt.method); got != tt.transient {
+ assert.Fail(t, fmt.Sprintf("isTransientErrorForMethod(%v, %s) = %v, want %v", tt.err, tt.method, got, tt.transient))
}
})
}
diff --git a/sdks/sandbox/go/wake_retry_test.go b/sdks/sandbox/go/wake_retry_test.go
index 8883eb11d..77a6284fd 100644
--- a/sdks/sandbox/go/wake_retry_test.go
+++ b/sdks/sandbox/go/wake_retry_test.go
@@ -529,7 +529,8 @@ func boolPtr(v bool) *bool { return &v }
func TestWakeRetry_StreamConnectDoesNotParkOnWake(t *testing.T) {
// The other SDKs leave streaming transports unwrapped: a marked 503 while
// establishing a stream must fail fast instead of parking the connect for
- // up to the wake budget. Generic retries still apply.
+ // up to the wake budget. The POST stream is not replayed by the generic
+ // policy either, so the caller receives the marked error.
var attempts atomic.Int32
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
n := attempts.Add(1)
@@ -558,7 +559,10 @@ func TestWakeRetry_StreamConnectDoesNotParkOnWake(t *testing.T) {
events = append(events, event)
return nil
})
- require.NoErrorf(t, err, "expected success after generic stream retry, got")
- require.Equal(t, 2, int(attempts.Load()))
- require.Len(t, events, 1)
+ require.Error(t, err, "a marked wake 503 on a POST stream must fail fast")
+ var apiErr *APIError
+ require.ErrorAs(t, err, &apiErr)
+ require.True(t, apiErr.WakeExpired)
+ require.Equal(t, 1, int(attempts.Load()))
+ require.Len(t, events, 0)
}