refactor(go-client): adopt handle pattern

Author: wllbo

clients/go/README.md

@@ -15,7 +15,7 @@ The client operates in three modes:
 1. **Production (Gateway Mode):** Traffic flows from the Client -> Cloud Load Balancer (Gateway)
    -> Router Service -> Sandbox Pod. The client watches the Gateway resource for an external IP.
 2. **Development (Port-Forward Mode):** Traffic flows from the Client -> SPDY tunnel -> Router
-   Service -> Sandbox Pod. Uses `client-go/tools/portforward` natively — no `kubectl` required.
+   Service -> Sandbox Pod. Uses `client-go/tools/portforward` natively, no `kubectl` required.
 3. **Advanced / Internal Mode:** The client connects directly to a provided `APIURL`, bypassing
    discovery. Useful for in-cluster agents or custom domains.
 
@@ -25,7 +25,7 @@ The client operates in three modes:
 - The [**Agent Sandbox Controller**](https://github.com/kubernetes-sigs/agent-sandbox?tab=readme-ov-file#installation) installed.
 - The **Sandbox Router** deployed in the target namespace (`sandbox-router-svc`).
 - A `SandboxTemplate` created in the target namespace.
-- Go 1.26+.
+- Go 1.26.1+.
 
 ## Installation
 
@@ -41,7 +41,7 @@ Use this when running against a cluster with a public Gateway IP. The client aut
 discovers the Gateway address.
 
 ```go
-client, err := sandbox.NewClient(sandbox.Options{
+client, err := sandbox.New(ctx, sandbox.Options{
     TemplateName:     "my-sandbox-template",
     GatewayName:      "external-http-gateway",
     GatewayNamespace: "default",
@@ -64,7 +64,7 @@ Use this for local development or CI. If you omit `GatewayName` and `APIURL`, th
 automatically establishes an SPDY port-forward tunnel to the Router Service.
 
 ```go
-client, err := sandbox.NewClient(sandbox.Options{
+client, err := sandbox.New(ctx, sandbox.Options{
     TemplateName: "my-sandbox-template",
     Namespace:    "default",
 })
@@ -87,7 +87,7 @@ Use `APIURL` to bypass discovery entirely. Useful for:
 - **Custom Domains:** Connecting via HTTPS (e.g., `https://sandbox.example.com`).
 
 ```go
-client, err := sandbox.NewClient(sandbox.Options{
+client, err := sandbox.New(ctx, sandbox.Options{
     TemplateName: "my-sandbox-template",
     APIURL:       "http://sandbox-router-svc.default.svc.cluster.local:8080",
     Namespace:    "default",
@@ -108,7 +108,7 @@ fmt.Println(entries)
 If your sandbox runtime listens on a port other than 8888, specify `ServerPort`.
 
 ```go
-client, err := sandbox.NewClient(sandbox.Options{
+client, err := sandbox.New(ctx, sandbox.Options{
     TemplateName: "my-sandbox-template",
     ServerPort:   3000,
 })
@@ -117,8 +117,8 @@ client, err := sandbox.NewClient(sandbox.Options{
 ### File Operations
 
 ```go
-// Write a file (only the base filename is sent; directory components are discarded).
-// Paths like "", ".", "..", and "/" are rejected with an error.
+// Write a file (must be a plain filename, no directory separators).
+// Paths like "dir/script.py" are rejected with an error.
 err := client.Write(ctx, "script.py", []byte("print('hello')"))
 
 // Read a file
@@ -128,13 +128,15 @@ data, err := client.Read(ctx, "script.py")
 exists, err := client.Exists(ctx, "script.py")
 ```
 
+`Run()` responses are capped at 16 MB; `List()`/`Exists()` at 8 MB.
+
 ### 5. Custom TLS / Transport
 
 If your Gateway uses HTTPS with a private CA, provide a custom transport:
 
 ```go
 tlsConfig := &tls.Config{RootCAs: myCAPool}
-client, err := sandbox.NewClient(sandbox.Options{
+client, err := sandbox.New(ctx, sandbox.Options{
     TemplateName:  "my-sandbox-template",
     GatewayName:   "external-https-gateway",
     GatewayScheme: "https",
@@ -147,37 +149,89 @@ client, err := sandbox.NewClient(sandbox.Options{
 All options are documented on the `Options` struct in
 [options.go](sandbox/options.go). Key fields:
 
-- `TemplateName` *(required)* — name of the `SandboxTemplate`.
-- `GatewayName` — set to enable Gateway mode.
-- `APIURL` — set for Direct URL mode (takes precedence over `GatewayName`).
-- `EnableTracing` / `TracerProvider` — OpenTelemetry integration.
+- `TemplateName` *(required)*: name of the `SandboxTemplate`.
+- `GatewayName`: set to enable Gateway mode.
+- `APIURL`: set for Direct URL mode (takes precedence over `GatewayName`).
+- `EnableTracing` / `TracerProvider`: OpenTelemetry integration.
 
-Any operation accepts `WithTimeout` to override the default request timeout:
+Any operation accepts `WithTimeout` to override the default request timeout,
+or `WithMaxAttempts` to control retry behavior:
 
 ```go
 result, err := client.Run(ctx, "make build", sandbox.WithTimeout(10*time.Minute))
 ```
 
 ## Retry Behavior
 
-Operations are automatically retried on 5xx responses and connection errors with
-exponential backoff. See constants in [transport.go](sandbox/transport.go) for details.
+File operations (`Read`, `Write`, `List`, `Exists`) are automatically retried (up to
+6 attempts) on 500/502/503/504 responses and connection errors with exponential backoff.
+
+**Important:** `Run()` defaults to a single attempt (no retries) because command
+execution is not idempotent. Use `WithMaxAttempts` to opt in to retries for
+idempotent commands:
+
+```go
+result, err := client.Run(ctx, "cat /etc/hostname", sandbox.WithMaxAttempts(6))
+```
+
+## Disconnect / Reconnect
+
+`Disconnect()` closes the transport connection **without deleting** the
+SandboxClaim. The sandbox stays alive on the server. Call `Open()` to
+reconnect to the same sandbox:
+
+```go
+client.Disconnect(ctx) // transport closed, claim preserved
+// ... later ...
+client.Open(ctx)       // reconnects to the same sandbox
+```
+
+This is useful for suspending a session (e.g., between user requests in a
+web service) while keeping the sandbox warm. `Close()` deletes the claim;
+`Disconnect(ctx)` preserves it.
+
+## Timeouts and Context
+
+`Open()` executes several sequential phases (claim creation, sandbox
+readiness, transport connection), each bounded by its own timeout
+(`SandboxReadyTimeout`, `GatewayReadyTimeout`, `PortForwardReadyTimeout`).
+**Pass a context with a deadline** to bound the total `Open()` duration:
+
+```go
+ctx, cancel := context.WithTimeout(context.Background(), 3*time.Minute)
+defer cancel()
+if err := client.Open(ctx); err != nil { ... }
+```
+
+| Option | Default | Governs |
+|--------|---------|---------|
+| `SandboxReadyTimeout` | 180 s | Waiting for the sandbox to become ready |
+| `GatewayReadyTimeout` | 180 s | Waiting for the gateway IP |
+| `PortForwardReadyTimeout` | 30 s | Establishing the SPDY tunnel |
+| `CleanupTimeout` | 30 s | Claim deletion during rollback / Close |
+| `RequestTimeout` | 180 s | Total timeout per SDK method call (Run, Read, …) |
+| `PerAttemptTimeout` | 60 s | Time to receive response headers per attempt |
+| `MaxUploadSize` | 256 MB | Maximum content size for `Write()` |
+| `MaxDownloadSize` | 256 MB | Maximum response body size for `Read()` |
 
 ## Port-Forward Recovery
 
 In port-forward mode, a background monitor detects tunnel death and clears the
 client's ready state. Subsequent operations fail immediately with `ErrNotReady`
 (wrapping `ErrPortForwardDied`) instead of timing out.
 
-To recover, call `Open()` again — the client will verify the claim and sandbox
+To recover, call `Open()` again. The client will verify the claim and sandbox
 still exist, then establish a new tunnel:
 
 ```go
 result, err := client.Run(ctx, "echo hi")
 if errors.Is(err, sandbox.ErrNotReady) {
     // Port-forward died; reconnect.
     if reconnErr := client.Open(ctx); reconnErr != nil {
-        if errors.Is(reconnErr, sandbox.ErrOrphanedClaim) {
+        if errors.Is(reconnErr, sandbox.ErrSandboxDeleted) {
+            // Claim was deleted externally; start fresh.
+            reconnErr = client.Open(ctx)
+        } else if errors.Is(reconnErr, sandbox.ErrOrphanedClaim) {
             // Sandbox no longer ready or verification failed; clean up and start fresh.
             client.Close(ctx)
             reconnErr = client.Open(ctx)
@@ -194,7 +248,7 @@ If `Close()` fails to delete the claim (e.g., API server unavailable), the clien
 preserves the claim name so `Close()` can be retried to clean up the orphaned claim.
 Calling `Open()` on a client with an orphaned claim returns `ErrOrphanedClaim`.
 
-## Error Sentinel Reference
+## Error Reference
 
 | Error | Meaning |
 |-------|---------|
@@ -208,20 +262,31 @@ Calling `Open()` on a client with an orphaned claim returns `ErrOrphanedClaim`.
 | `ErrSandboxDeleted` | The Sandbox was deleted before becoming ready. |
 | `ErrGatewayDeleted` | The Gateway was deleted during address discovery. |
 
+Non-OK HTTP responses are wrapped in `*HTTPError`, which can be extracted
+with `errors.As` to inspect the status code:
+
+```go
+var httpErr *sandbox.HTTPError
+if errors.As(err, &httpErr) {
+    fmt.Printf("status %d: %s\n", httpErr.StatusCode, httpErr.Body)
+}
+```
+
 ## Testing / Mocking
 
 The package exports two interfaces:
 
-- **`Client`** — the core API (`Open`, `Close`, `Run`, `Read`, `Write`, `List`,
-  `Exists`, `IsReady`). Accept this in your APIs to enable testing with fakes.
-- **`SandboxInfo`** — read-only identity accessors (`ClaimName`, `SandboxName`,
-  `PodName`, `Annotations`). These are on the concrete `*SandboxClient` (and the
-  `SandboxInfo` interface) rather than `Client`, so adding new accessors is not
+- **`Handle`**: the core API (`Open`, `Close`, `Disconnect(ctx)`, `Run`, `Read`, `Write`,
+  `List`, `Exists`, `IsReady`). Accept this in your APIs to enable testing with fakes. For
+  sub-object access (`Commands()`, `Files()`), use the concrete `*Sandbox` type directly.
+- **`Info`**: read-only identity accessors (`ClaimName`, `SandboxName`,
+  `PodName`, `Annotations`). These are on the concrete `*Sandbox` (and the
+  `Info` interface) rather than `Handle`, so adding new accessors is not
   a breaking change for mock implementors.
 
 ```go
-// Accept the narrow Client interface for testability.
-func ProcessInSandbox(ctx context.Context, sb sandbox.Client) error {
+// Accept the narrow Handle interface for testability.
+func ProcessInSandbox(ctx context.Context, sb sandbox.Handle) error {
     if err := sb.Open(ctx); err != nil {
         return err
     }
@@ -230,8 +295,8 @@ func ProcessInSandbox(ctx context.Context, sb sandbox.Client) error {
     // ...
 }
 
-// When you need identity metadata, accept the concrete type or SandboxInfo.
-func LogSandboxIdentity(info sandbox.SandboxInfo) {
+// When you need identity metadata, accept the concrete type or Info.
+func LogSandboxIdentity(info sandbox.Info) {
     log.Printf("claim=%s sandbox=%s pod=%s", info.ClaimName(), info.SandboxName(), info.PodName())
 }
 ```

clients/go/examples/basic/main.go

@@ -25,7 +25,7 @@ import (
 )
 
 func main() {
-	client, err := sandbox.NewClient(sandbox.Options{
+	client, err := sandbox.New(context.Background(), sandbox.Options{
 		TemplateName: "my-sandbox-template",
 		Namespace:    "default",
 	})

clients/go/examples/gateway/main.go

@@ -25,7 +25,7 @@ import (
 )
 
 func main() {
-	client, err := sandbox.NewClient(sandbox.Options{
+	client, err := sandbox.New(context.Background(), sandbox.Options{
 		TemplateName:     "my-sandbox-template",
 		Namespace:        "default",
 		GatewayName:      "external-http-gateway",