Skip to content

Commit 091d2cb

Browse files
committed
feat(sdk/go): complete Go SDK with domain clients, auth, and hardening
Add the Go SDK implementation covering all gateway RPC services with domain-typed clients, comprehensive OIDC authentication flows, fake test doubles, and proto converters. Domain clients: Sandbox, Provider, Exec, File, TCP, SSH, Policy, Profile, Health, Service, Config, Workspace, Inference, Refresh. Each client validates inputs, resolves sandboxes by name, and converts between domain types and proto at the boundary. Auth: OIDC authorization code (PKCE), device code (RFC 8628), and client credentials (RFC 6749 Section 4.4) flows with gateway config auto-resolution. Token refresh with singleflight deduplication and exponential backoff. Edge tunnel proxy for gRPC-over-WebSocket. Gateway: On-disk gateway discovery with user/system directory precedence, lazy token loading, and auth mode mapping. Testing: In-memory fake client with deep-copy isolation, watch broadcasting with filtering, and workspace-scoped object stores. Bufconn-based gRPC tests for all domain clients. Ref: NVIDIA#2044 Signed-off-by: Roland Huß <[email protected]>
1 parent c825b1f commit 091d2cb

210 files changed

Lines changed: 33938 additions & 746 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎mise.lock‎

Lines changed: 2 additions & 12 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎sdk/go/.golangci.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
version: "2"
5+
6+
run:
7+
timeout: 5m
8+
9+
linters:
10+
enable:
11+
- govet
12+
- errcheck
13+
- staticcheck
14+
- unused
15+
- ineffassign
16+
- revive
17+
- goheader
18+
exclusions:
19+
rules:
20+
- path: "proto/"
21+
linters:
22+
- goheader
23+
- revive
24+
25+
linters-settings:
26+
goheader:
27+
template: |-
28+
SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
29+
SPDX-License-Identifier: Apache-2.0
30+
revive:
31+
rules:
32+
- name: blank-imports
33+
- name: exported
34+
- name: var-naming
35+
- name: indent-error-flow
36+
- name: range
37+
- name: error-return
38+
- name: error-naming
39+
- name: error-strings
40+
- name: receiver-naming
41+
- name: increment-decrement
42+
- name: superfluous-else
43+
- name: unreachable-code

‎sdk/go/README.md‎

Lines changed: 320 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,320 @@
1+
# OpenShell SDK for Go
2+
3+
[![Go Reference](https://pkg.go.dev/badge/github.com/NVIDIA/OpenShell/sdk/go.svg)](https://pkg.go.dev/github.com/NVIDIA/OpenShell/sdk/go)
4+
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](../../LICENSE)
5+
6+
> [!IMPORTANT]
7+
> **[Read the full documentation](https://ro14nd.de/openshell-sdk-go/)** for guides, API reference with gRPC mapping, and testing patterns.
8+
9+
A Go SDK for interacting with [OpenShell](https://github.com/NVIDIA/OpenShell)
10+
servers, providing idiomatic Go bindings for shell session management, command
11+
execution, provider configuration, and service exposure.
12+
13+
## Why a Go SDK?
14+
15+
Go is the language of the Kubernetes ecosystem. If you want to build an
16+
operator, controller, or any automation that manages OpenShell resources as
17+
native Kubernetes objects, you need a Go client.
18+
19+
This SDK is modeled after
20+
[`k8s.io/client-go`](https://github.com/kubernetes/client-go), the standard
21+
Kubernetes client library that every Go operator developer already knows. The
22+
patterns will look familiar:
23+
24+
- **Typed sub-clients per resource**: `client.Sandboxes()`, `client.Providers()`,
25+
`client.Exec()`, just like `clientset.CoreV1().Pods()`
26+
- **Domain types separated from wire formats**: clean Go structs in a `types`
27+
package, no proto leakage into the public API (like `k8s.io/api`)
28+
- **Watch primitives**: channel-based watchers with `ResultChan()` and `Stop()`,
29+
identical to `watch.Interface` in client-go
30+
- **Functional options**: variadic option patterns for list filtering,
31+
pagination, and watch configuration
32+
- **Composable auth with token refresh**: wraps `oauth2.TokenSource` for
33+
automatic token caching and coalesced refresh, following the k8s client-go
34+
`cachingTokenSource` pattern
35+
- **Fake client for testing**: an in-memory implementation of the full client
36+
interface (like `k8s.io/client-go/kubernetes/fake`), so operators can be tested
37+
without a real gateway
38+
39+
## Quick Start
40+
41+
```go
42+
import v1 "github.com/NVIDIA/OpenShell/sdk/go/openshell/v1"
43+
44+
// Connect to a gateway
45+
client, err := v1.NewClient(v1.Config{
46+
Address: "gateway.example.com:443",
47+
Auth: v1.StaticToken("my-token"),
48+
})
49+
if err != nil {
50+
log.Fatal(err)
51+
}
52+
defer client.Close()
53+
54+
// Create a sandbox and wait until it's ready
55+
sandbox, err := client.Sandboxes().Create(ctx, "default", "my-sandbox", &v1.SandboxSpec{
56+
Template: &v1.SandboxTemplate{Image: "python:3.12"},
57+
}, nil)
58+
if err != nil {
59+
log.Fatal(err)
60+
}
61+
sandbox, err = client.Sandboxes().WaitReady(ctx, "default", sandbox.Name)
62+
if err != nil {
63+
log.Fatal(err)
64+
}
65+
66+
// Run a command
67+
result, err := client.Exec().Run(ctx, "default", sandbox.Name,
68+
[]string{"python3", "-c", "print('hello from sandbox')"},
69+
v1.ExecOptions{},
70+
)
71+
if err != nil {
72+
log.Fatal(err)
73+
}
74+
fmt.Println(string(result.Stdout))
75+
```
76+
77+
### With automatic token refresh
78+
79+
For OIDC gateways, use `RefreshableToken` to wrap any `oauth2.TokenSource` with
80+
automatic caching and coalesced refresh:
81+
82+
```go
83+
import "golang.org/x/oauth2"
84+
85+
tokenSource := oauth2Config.TokenSource(ctx, initialToken)
86+
auth, err := v1.RefreshableToken(tokenSource,
87+
v1.WithLeeway(30*time.Second),
88+
)
89+
if err != nil {
90+
log.Fatal(err)
91+
}
92+
client, err := v1.NewClient(v1.Config{
93+
Address: "gateway.example.com:443",
94+
Auth: auth,
95+
})
96+
if err != nil {
97+
log.Fatal(err)
98+
}
99+
defer client.Close()
100+
```
101+
102+
Concurrent callers share a single refresh call. If the token source fails, the
103+
SDK falls back to the cached token with a logged warning. See the
104+
[Auth](https://ro14nd.de/openshell-sdk-go/api/auth.html) docs for details.
105+
106+
### With edge proxy headers
107+
108+
When a gateway sits behind a zero-trust reverse proxy, use `WithExtraHeaders` to
109+
attach proxy-specific headers alongside standard auth:
110+
111+
```go
112+
base := v1.StaticToken("my-gateway-token")
113+
auth, err := v1.WithExtraHeaders(base, map[string]string{
114+
"x-proxy-auth": "proxy-secret",
115+
})
116+
if err != nil {
117+
log.Fatal(err)
118+
}
119+
client, err := v1.NewClient(v1.Config{
120+
Address: "gateway.example.com:443",
121+
Auth: auth,
122+
})
123+
```
124+
125+
For Cloudflare Access, use the convenience constructor in the `edge` package:
126+
127+
```go
128+
import "github.com/NVIDIA/OpenShell/sdk/go/openshell/v1/edge"
129+
130+
auth, err := edge.CloudflareAccess(base, os.Getenv("CF_ACCESS_TOKEN"))
131+
```
132+
133+
For gRPC behind edge proxies that reject HTTP/2, use the WebSocket tunnel:
134+
135+
```go
136+
tunnel, err := edge.NewTunnelProxy(
137+
"wss://gateway.example.com/ws",
138+
os.Getenv("CF_ACCESS_TOKEN"),
139+
)
140+
if err != nil {
141+
log.Fatal(err)
142+
}
143+
defer tunnel.Close()
144+
145+
client, err := v1.NewClient(v1.Config{
146+
Address: tunnel.Addr(),
147+
Auth: v1.StaticToken("my-token"),
148+
TLS: &v1.TLSConfig{Insecure: true}, // local tunnel, no TLS
149+
})
150+
```
151+
152+
### OIDC Login
153+
154+
The `oidc` package provides gateway-aware OIDC authentication with browser,
155+
keyboard, device code, and client credentials flows:
156+
157+
```go
158+
import "github.com/NVIDIA/OpenShell/sdk/go/openshell/v1/oidc"
159+
160+
// Gateway-aware login: reads OIDC config from gateway metadata
161+
token, err := oidc.Login(ctx, "my-gateway")
162+
if err != nil {
163+
log.Fatal(err)
164+
}
165+
166+
// Use the token with the SDK client
167+
client, err := v1.NewClient(v1.Config{
168+
Address: "gateway.example.com:443",
169+
Auth: v1.StaticToken(token.AccessToken),
170+
})
171+
```
172+
173+
For headless environments, use the device code flow:
174+
175+
```go
176+
token, err := oidc.DeviceLogin(ctx,
177+
oidc.WithIssuer("https://auth.example.com"),
178+
oidc.WithClientID("my-app"),
179+
)
180+
```
181+
182+
For service accounts, use client credentials:
183+
184+
```go
185+
token, err := oidc.ClientCredentials(ctx,
186+
oidc.WithGateway("my-gateway"),
187+
oidc.WithClientSecret("service-secret"),
188+
)
189+
```
190+
191+
See the [oidc package docs](https://pkg.go.dev/github.com/NVIDIA/OpenShell/sdk/go/openshell/v1/oidc) for all options and flows.
192+
193+
See the [Getting Started](https://ro14nd.de/openshell-sdk-go/getting-started.html) guide for the full walkthrough.
194+
195+
## Migrating from v0.0.101
196+
197+
The pre-1.0 SDK intentionally includes source-incompatible API corrections:
198+
199+
- `TCP.Listen` returns a `ForwardListener` lifecycle handle. The SDK owns the
200+
accept loop; callers dial `Addr()` and call `Close()` instead of calling
201+
`Accept()` or passing the handle to `http.Serve`.
202+
- Resource operations take an explicit workspace, and workspace-bearing domain
203+
types preserve that scope.
204+
- Several public struct field orders changed. Use keyed struct literals.
205+
- Initialisms use Go spelling, including `JSONRPCMaxBodyBytes`.
206+
207+
These changes are intentional while the module remains below v1. Update callers
208+
as one migration rather than relying on the v0.0.101 API shape.
209+
210+
### Inference Route Management
211+
212+
Configure how inference requests are routed for a workspace:
213+
214+
```go
215+
// Set an inference route
216+
route, err := client.Inference().SetRoute(ctx, "my-workspace", &v1.InferenceRouteConfig{
217+
ProviderName: "openai",
218+
ModelID: "gpt-4",
219+
RouteName: "", // empty string = default route
220+
TimeoutSecs: 120,
221+
})
222+
if err != nil {
223+
log.Fatal(err)
224+
}
225+
fmt.Printf("Route v%d: %s/%s\n", route.Version, route.ProviderName, route.ModelID)
226+
227+
// Retrieve the route
228+
route, err = client.Inference().GetRoute(ctx, "my-workspace", "")
229+
if err != nil {
230+
log.Fatal(err)
231+
}
232+
233+
// Delete the route
234+
err = client.Inference().DeleteRoute(ctx, "my-workspace", "")
235+
if err != nil {
236+
log.Fatal(err)
237+
}
238+
```
239+
240+
## Architecture
241+
242+
```
243+
Client
244+
├── Sandboxes() → SandboxInterface (create, get, list, delete, watch, wait, logs)
245+
├── Exec() → ExecInterface (run, stream, interactive)
246+
├── Files() → FileInterface (upload, download)
247+
├── Health() → HealthInterface (health check, gateway info, current user)
248+
├── Services() → ServiceInterface (expose, get, list, delete)
249+
├── Providers() → ProviderInterface (CRUD + ensure)
250+
│ ├── Profiles() → ProfileInterface (list, get, import, update, lint, delete)
251+
│ └── Refresh() → RefreshInterface (configure, status, rotate, delete)
252+
├── Workspaces() → WorkspaceInterface (create, get, list, delete, members)
253+
├── Inference() → InferenceInterface (set, get, delete inference routes)
254+
└── Policy() → PolicyInterface (draft review, approve, reject, merge, status)
255+
```
256+
257+
All domain types live in `openshell/v1/types/`. Proto-to-Go conversions happen in
258+
an internal converter layer. The public API surface uses type aliases so
259+
consumers import a single package. See the [Architecture](https://ro14nd.de/openshell-sdk-go/architecture.html) overview for details.
260+
261+
## Features
262+
263+
| Feature | Interface | Docs |
264+
|---------|-----------|------|
265+
| Sandbox lifecycle (create, get, list, delete, watch, wait) | `SandboxInterface` | [Sandboxes](https://ro14nd.de/openshell-sdk-go/api/sandboxes.html) |
266+
| Command execution (collected, streamed, interactive PTY) | `ExecInterface` | [Exec](https://ro14nd.de/openshell-sdk-go/api/exec.html) |
267+
| Provider management (CRUD + idempotent ensure) | `ProviderInterface` | [Providers](https://ro14nd.de/openshell-sdk-go/api/providers.html) |
268+
| Provider profiles (list, import, lint, update) | `ProfileInterface` | [Profiles](https://ro14nd.de/openshell-sdk-go/api/profiles.html) |
269+
| Credential refresh (configure, rotate, status) | `RefreshInterface` | [Refresh](https://ro14nd.de/openshell-sdk-go/api/refresh.html) |
270+
| Service exposure (expose, list, delete) | `ServiceInterface` | [Services](https://ro14nd.de/openshell-sdk-go/api/services.html) |
271+
| File transfer API (transport capability-gated) | `FileInterface` | [Files](https://ro14nd.de/openshell-sdk-go/api/files.html) |
272+
| Policy management (draft review, approve, reject, merge, global policy) | `PolicyInterface` | [Policy](https://ro14nd.de/openshell-sdk-go/api/policy.html) |
273+
| Sandbox logs (streaming retrieval) | `SandboxInterface` | [Sandboxes](https://ro14nd.de/openshell-sdk-go/api/sandboxes.html) |
274+
| Workspace management (create, get, list, delete, members) | `WorkspaceInterface` | [Workspaces](https://ro14nd.de/openshell-sdk-go/api/workspaces.html) |
275+
| Inference route management (set, get, delete) | `InferenceInterface` | [Inference](https://ro14nd.de/openshell-sdk-go/api/inference.html) |
276+
| Gateway info and current user identity | `HealthInterface` | [Health](https://ro14nd.de/openshell-sdk-go/api/health.html) |
277+
| Health checking | `HealthInterface` | [Health](https://ro14nd.de/openshell-sdk-go/api/health.html) |
278+
| SSH tunneling and TCP forwarding | `SSHInterface`, `TCPInterface` | [SSH](https://ro14nd.de/openshell-sdk-go/api/ssh.html), [TCP](https://ro14nd.de/openshell-sdk-go/api/tcp.html) |
279+
| Auth: static token, refreshable token (oauth2.TokenSource) | `AuthProvider` | [Auth](https://ro14nd.de/openshell-sdk-go/api/auth.html) |
280+
| Edge auth: extra headers, Cloudflare Access, WebSocket tunnel | `AuthProvider`, `edge.TunnelProxy` | [Edge](https://ro14nd.de/openshell-sdk-go/api/edge.html) |
281+
| Typed errors (`IsNotFound`, `IsAlreadyExists`, `IsConflict`, ...) | `StatusError` | [Error Handling](https://ro14nd.de/openshell-sdk-go/error-handling.html) |
282+
| Real-time watch with auto-stop on terminal phase | `WatchInterface[T]` | [Sandboxes](https://ro14nd.de/openshell-sdk-go/api/sandboxes.html) |
283+
| Fake client for testing (no gRPC server needed) | `fake.Client` | [Testing](https://ro14nd.de/openshell-sdk-go/testing.html) |
284+
| OIDC login (browser, keyboard, device code, client credentials) | `oidc.Login`, `oidc.DeviceLogin`, `oidc.ClientCredentials` | [OIDC](https://pkg.go.dev/github.com/NVIDIA/OpenShell/sdk/go/openshell/v1/oidc) |
285+
| Gateway config convenience (load CLI gateway configs, auto-wire auth) | `gateway.NewClient`, `gateway.LoadConfig` | [Gateway](https://ro14nd.de/openshell-sdk-go/api/gateway.html) |
286+
287+
## Prerequisites
288+
289+
- Go 1.25 or later
290+
- [mise](https://mise.jdx.dev) (recommended for reproducible builds)
291+
292+
## Build and Test
293+
294+
```bash
295+
git clone https://github.com/NVIDIA/OpenShell.git
296+
cd OpenShell/sdk/go
297+
298+
mise run test # Run tests with coverage
299+
mise run lint # Run golangci-lint
300+
mise run ci # Full CI pipeline (lint + build + test)
301+
```
302+
303+
Build commands use [mise](https://mise.jdx.dev) for reproducible tool management.
304+
305+
## Documentation
306+
307+
Full API documentation is available at the [OpenShell Go SDK Docs](https://ro14nd.de/openshell-sdk-go/) site.
308+
309+
To build the docs locally:
310+
311+
```bash
312+
cargo install mdbook
313+
mdbook serve docs
314+
```
315+
316+
## License
317+
318+
Apache-2.0. See [LICENSE](../../LICENSE) for details.
319+
320+
Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.

0 commit comments

Comments
 (0)