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.goindex 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 boolerr := 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.Readerif body != nil {buf, err := json.Marshal(body)diff --git a/sdks/sandbox/go/retry.go b/sdks/sandbox/go/retry.goindex 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.RetryableStatusCodesif 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 *APIErrorif 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.Errorreturn 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.gonew file mode 100644index 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.goindex 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.Int32srv := 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 stringerr error+ cfg *RetryConfigtransient 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.goindex 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.Int32srv := 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)}