Skip to content

Commit 5935449

Browse files
committed
Add brainstorm: Go SDK Create() params struct
Captures design exploration for NVIDIA#2807 - bundling positional parameters into a CreateSandboxParams struct. Evaluates three approaches (struct, full separation, functional options) plus k8s client-go reference. Decision: creation params struct matching existing SDK conventions. Signed-off-by: Roland Huß <[email protected]>
1 parent 592df3e commit 5935449

1 file changed

Lines changed: 58 additions & 0 deletions

File tree

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Brainstorm: Go SDK Create() params struct
2+
3+
**Date:** 2026-09-04
4+
**Status:** active
5+
**Issue:** [#2807](https://github.com/NVIDIA/OpenShell/issues/2807)
6+
7+
## Problem Framing
8+
9+
The Go SDK's `SandboxInterface.Create()` takes 7 positional parameters plus variadic opts after the sandbox templates refactor in PR #2781. Four consecutive nilable parameters of different types make call sites unreadable (`client.Sandboxes().Create(ctx, "default", "my-sandbox", nil, nil, nil, nil)`). The underlying cause is that Go reuses `SandboxSpec` for both creation input and resolved state, leaking gateway-only fields like `DriverConfig` into the caller surface. Rust and TypeScript already solved this with distinct creation-only types.
10+
11+
## Approaches Considered
12+
13+
### A: Creation params struct (Chosen)
14+
15+
Introduce `CreateSandboxParams` that bundles the optional positional args (workload, policy, providers, labels). Keep the existing `SandboxSpec` as-is for the resolved output. This matches the existing SDK convention where `ProviderInterface.Create` and `ConfigInterface.Update` already pass typed structs.
16+
17+
- Pros: Small diff, solves readability, prevents callers from setting `DriverConfig`, consistent with existing SDK patterns
18+
- Cons: Doesn't rename or restructure the resolved `SandboxSpec`, so the "same name, different concept" issue across SDKs persists
19+
20+
### B: Full separation (creation and resolved types)
21+
22+
Introduce `CreateSandboxParams` AND restructure the output side so creation vs. resolved are clearly distinct types. Ensure `SandboxSpec` is documented as gateway-resolved-only.
23+
24+
- Pros: Clean semantic model matching Rust/TS, future-proof
25+
- Cons: Larger diff, touches more call sites, scope creep risk
26+
27+
### C: Functional options pattern
28+
29+
Replace positional params with Go-idiomatic functional options (`WithWorkload()`, `WithPolicy()`, etc.).
30+
31+
- Pros: Most Go-idiomatic in general, infinitely extensible
32+
- Cons: Would be the only creation method in the SDK using this pattern. All existing mutation/creation methods use either struct params or positional args. Functional options exist only on read/query paths (`LogOption`, `GetDraftOption`). Doesn't address the `SandboxSpec` dual-use problem.
33+
34+
### Reference: Kubernetes client-go pattern
35+
36+
K8s uses the same type for creation input and output (`*v1.Pod` goes in, `*v1.Pod` comes back), but it works because of the strict Spec/Status separation convention within every resource type. OpenShell's `SandboxSpec` doesn't have that split, so achieving the same clarity requires a separate creation type.
37+
38+
## Decision
39+
40+
Approach A: introduce `CreateSandboxParams` struct. This follows the established SDK convention (struct params for complex creation, matching `ProviderInterface.Create`) while solving the concrete readability and type-safety problems. The k8s functional options pattern was considered but rejected because no existing creation method in the SDK uses it, making it an outlier.
41+
42+
This is an independent improvement, not tied to PR #2781's timeline. The templates PR can adjust to this pattern if it lands first.
43+
44+
## Key Requirements
45+
46+
- Introduce `CreateSandboxParams` struct with workload, policy, providers, labels fields
47+
- Change `SandboxInterface.Create()` signature: `Create(ctx, workspace, name string, params CreateSandboxParams, opts ...CreateOptions)`
48+
- Apply the same pattern to `CreateFromTemplate()` if it has a similar positional parameter list
49+
- Update all call sites (tests, examples, internal usage)
50+
- Keep existing `SandboxSpec` unchanged for resolved output
51+
- Ensure `CreateSandboxParams` excludes gateway-resolved fields (`DriverConfig`)
52+
53+
## Open Questions
54+
55+
- Exact field list for `CreateSandboxParams` needs verification against current `Create()` signature and the proto `CreateSandboxRequest`
56+
- Should `name` and `workspace` be pulled into the params struct (like Rust/TS do) or stay as positional args (like k8s client-go)?
57+
- Whether to file a separate issue for `ServiceInterface.Expose` which has a similar positional args smell
58+
- Whether to file a separate issue for Python's missing curated creation type

0 commit comments

Comments
 (0)