feat(sdk/go): bundle Create() positional parameters into options struct

Summary

SandboxInterface.Create() now takes 7 positional parameters plus variadic opts after the sandbox templates refactor in PR #2781:

Create(ctx context.Context, workspace, name string, workload *SandboxWorkloadConfig,
       policy *SandboxPolicy, providers []string, labels map[string]string,
       opts ...CreateOptions) (*Sandbox, error)

Four consecutive nilable parameters of different types makes call sites unreadable:

client.Sandboxes().Create(ctx, "default", "my-sandbox", nil, nil, nil, nil)

Proposed Change

Bundle the creation parameters into a CreateSandboxParams struct:

type CreateSandboxParams struct {
    Workload  *SandboxWorkloadConfig
    Policy    *SandboxPolicy
    Providers []string
    Labels    map[string]string
}

The interface becomes:

Create(ctx context.Context, workspace, name string, params CreateSandboxParams, opts ...CreateOptions) (*Sandbox, error)

This follows the k8s client-go pattern this SDK models, where creation parameters are bundled into typed structs rather than passed as positional arguments. Since PR #2781 is already a breaking change, the migration cost for this improvement is minimal.

The same pattern should apply to CreateFromTemplate() if it has a similar parameter list.

Context

Identified during PR #2781 code review (comment). The parameter list grew from 5 to 7+opts when policy and providers were promoted to top-level request fields.

📋 triage-agent

Triage Assessment

Classification: validated-feature

Summary

The readability problem is confirmed in the current head of #2781. Go is the only curated SDK that represents the optional sandbox-creation fields as a sequence of positional arguments: Python uses keyword-only arguments, while Rust and TypeScript use structured inputs.

Investigation

This also exposes a broader consistency issue. Go already has a SandboxSpec, but it represents the resolved state returned by the gateway and includes DriverConfig. Direct creation must not accept DriverConfig; an earlier version of #2781 risked silently discarding it.

Rust and TypeScript currently use SandboxSpec for caller creation intent instead. The SDKs therefore use the same name for different concepts.

The resolution should establish a uniform semantic model across the curated SDKs while retaining language-idiomatic APIs:

distinguish creation input from the resolved SandboxSpec;

provide separate inline-workload and template-based creation inputs;

align the supported fields, defaults, validation, and errors;

use keyword arguments, object parameters, or typed structs as appropriate for each language.

For Go, this likely means introducing a create-specific type such as SandboxCreateSpec or CreateSandboxParams, plus a distinct template-creation type, rather than accepting the existing resolved SandboxSpec.

Recommendation

Coordinate this with #2680 and #2781 and document the intended creation model across Go, Rust, Python, and TypeScript before finalizing the breaking API. Addressing the Go signature before #2781 merges would avoid a second breaking migration.

If #2781 changes direction and no longer introduces these signatures, reassess whether this issue remains applicable.

Human Decision Required

Decide whether the shared SDK creation model should be part of the #2781 acceptance criteria. If accepted, record that separately with state:accepted.

The triage assessment correctly identifies the deeper problem: Go reuses SandboxSpec for both creation input and resolved state, which leaks gateway-only fields like DriverConfig into the caller surface.

That said, Rust and TypeScript already solved this. Both have a creation-only type (SandboxSpec) that is distinct from the resolved output (SandboxRef). The Go fix should follow that established pattern rather than requiring a coordinated cross-SDK design effort.

Proposed scoping:

This issue (Go): Introduce a creation-specific struct (e.g. CreateSandboxParams) that excludes gateway-resolved fields. Fold this into feat(sandbox)!: introduce reusable sandbox templates #2781 before it merges to avoid a second breaking change.
Separate issue (Python): Python currently passes the raw proto SandboxSpec with no curated creation type at all. That's a distinct gap worth its own tracking issue.
Cross-SDK naming: The invariant that matters is semantic: creation input types must not include gateway-resolved fields. Exact naming can follow language idiom (CreateSandboxParams in Go, SandboxSpec in Rust/TS) rather than requiring string-identical names across SDKs.

Alignment happens by convergence on the same separation pattern, not by blocking on a formal specification document. Rust and TS are already there; Go joining them is the fix.

Revised Analysis

After deeper investigation, the original premise needs correction:

DriverConfig is a user-provided field, not a gateway-resolved leak. It lives on SandboxTemplate (proto field 11) and is intentionally part of CreateSandboxRequest. The gateway routes the matching block to the active compute driver. Callers should be able to set it.

This means the current Create() signature on main is actually fine:

Create(ctx, workspace, name string, spec *SandboxSpec, labels map[string]string, opts ...CreateOptions)

The problem only arises in PR #2781, which decomposes *SandboxSpec into individual positional parameters:

Create(ctx, workspace, name string, workload *SandboxWorkloadConfig, policy *SandboxPolicy, providers []string, labels map[string]string, opts ...CreateOptions)

Proposed approach (revised):

Keep *SandboxSpec as the single creation input for Create(). Don't decompose it into positional params.
CreateFromTemplate() takes a template name + *SandboxSpec for optional overrides (policy, providers, etc.).
Move labels and annotations into functional options (WithLabels(), WithAnnotations()) to keep the positional parameter list short.

This gives:

Create(ctx, workspace, name string, spec *SandboxSpec, opts ...CreateOption)
CreateFromTemplate(ctx, workspace, name, templateName string, opts ...CreateOption)

// Options for resource metadata
func WithLabels(labels map[string]string) CreateOption
func WithAnnotations(annotations map[string]string) CreateOption
// Optional overrides for template-based creation
func WithPolicy(policy *SandboxPolicy) CreateOption
func WithProviders(providers []string) CreateOption

A dedicated CreateSandboxParams struct is unnecessary since *SandboxSpec already represents creation intent correctly. The only fields outside the spec (labels, annotations) are better served by functional options.

Closing our earlier PR #3197 since it was based on the incorrect premise. The fix should be coordinated with #2781.

Add brainstorm: Go SDK Create() params struct

feat(sdk/go)!: replace positional labels with functional Create options

Reopening this to get working on the Go SDK.

feat(sdk/go)!: replace positional labels with functional Create options

feat(sdk/go)!: replace positional labels with functional Create optio…

Navigation Menu

Repository navigation

feat(sdk/go): bundle Create() positional parameters into options struct #2807

Summary

Proposed Change

Context

Triage Assessment

Summary

Investigation

Recommendation

Human Decision Required

Revised Analysis

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

feat(sdk/go): bundle Create() positional parameters into options struct #2807

Description

Summary

Proposed Change

Context

Activity

elezar commented on Aug 20, 2026

Triage Assessment

Summary

Investigation

Recommendation

Human Decision Required

rhuss commented on Sep 4, 2026

rhuss commented on Sep 5, 2026

Revised Analysis

elezar commented on Oct 16, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions