Secure, Fast, and Extensible Sandbox runtime for AI agents.
docs(sdk-go): document write retry migration
JasonBuildAI1d7c63369d62
diff --git a/docs/sdks/go.md b/docs/sdks/go.mdindex c5bc01faa..152d54a86 100644--- a/docs/sdks/go.md+++ b/docs/sdks/go.md@@ -489,6 +489,20 @@ sandbox, err := opensandbox.CreateSandbox(ctx, config, opensandbox.SandboxCreate})```+### Retry policy++`ConnectionConfig.Retry` and `WithRetry` retry transient failures with exponential backoff. Idempotent methods (`GET`, `HEAD`, `PUT`, `DELETE`, `OPTIONS`) retry `429`, `502`, `503`, and `504` by default. `POST` and `PATCH` retry only dial, proxy-connect, and TLS-handshake failures that are provably pre-send by default; status-code retries for writes are opt-in because a replay can duplicate a sandbox, session, command, or file mutation. Set `RetryableStatusCodesNonIdempotent` only when the operation is idempotent at the application layer or duplicate execution is acceptable:++```go+config.Retry = &opensandbox.RetryConfig{+ MaxRetries: 3,+ InitialBackoff: 500 * time.Millisecond,+ RetryableStatusCodesNonIdempotent: []int{http.StatusServiceUnavailable},+}+```++SSE bootstraps do not use the generic retry loop, even when a write status code is opted in.+### Wake retryA request to a paused sandbox may arrive while its restore is still in progress. The gateway answers `503` with the `OpenSandbox-Wake: expired` marker; the client recognizes it and resends the original request after the `Retry-After` delay (safe for any method — the marker proves the request was never forwarded). The wake budget defaults to 5 attempts / 60 seconds across all wake cycles; when it is exhausted the client returns a `*SandboxWakeTimeoutError` (carrying `Attempts` and `Waited`) while the server-side resume continues in the background. Bare `503` responses follow the existing retry rules untouched. Wake retry is active whenever a `WithRetry` config is set (`WakeRetryEnabled` defaults to enabled even for hand-built configs; pass `WakeRetryDisabled()` to opt out); streaming connections bypass wake retry — a waking sandbox fails fast with the marked 503 instead of parking the connect — matching the other official SDKs, and established streams are never re-executed.diff --git a/sdks/sandbox/go/config.go b/sdks/sandbox/go/config.goindex 93a5b1693..a6acbbb46 100644--- a/sdks/sandbox/go/config.go+++ b/sdks/sandbox/go/config.go@@ -59,9 +59,11 @@ type ConnectionConfig struct {AuthHeader string// Retry enables automatic retry with exponential backoff for transient- // errors. Defaults to retrying 429/502/503/504; override- // RetryConfig.RetryableStatusCodes for custom policies. If nil, requests- // are not retried.+ // errors. Idempotent methods default to 429/502/503/504; override+ // RetryConfig.RetryableStatusCodes for custom idempotent policies. POST+ // and PATCH do not retry status codes unless listed in+ // RetryConfig.RetryableStatusCodesNonIdempotent. If nil, requests are not+ // retried.// Use DefaultRetryConfig() for sensible defaults.Retry *RetryConfig