Roland HussandDrew Newberry
8dc55e21ee
* 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: #2044 Signed-off-by: Roland Huß <rhuss@redhat.com> * feat(sdk/go): add gateway client options for logger, timeout, and retry Add WithLogger, WithTimeout, and WithRetryPolicy options to the gateway package's NewClient function. These forward the corresponding Config fields (Logger, Timeout, RetryPolicy) through to the underlying SDK client, giving callers full control over observability, connection timeouts, and retry behavior when constructing clients from on-disk gateway configurations. Also adds RetryPolicy type to types package and extends Config with the three new fields. * fix(mise): sync sccache lock entry Signed-off-by: Drew Newberry <anewberry@nvidia.com> --------- Signed-off-by: Roland Huß <rhuss@redhat.com> Signed-off-by: Drew Newberry <anewberry@nvidia.com> Co-authored-by: Drew Newberry <anewberry@nvidia.com>
3.1 KiB
Quick Start
This guide walks you through installing the OpenShell Go SDK, connecting to a gateway, creating a sandbox, running a command, and cleaning up. You should be up and running in under 5 minutes.
Prerequisites
- Go 1.25 or later
- Access to an OpenShell gateway (address and authentication token)
Installation
Add the SDK to your Go module:
go get github.com/NVIDIA/OpenShell/sdk/go@latest
Connect to the Gateway
Create a client by providing the gateway address and authentication credentials:
package main
import (
"context"
"fmt"
"log"
v1 "github.com/NVIDIA/OpenShell/sdk/go/openshell/v1"
)
func main() {
client, err := v1.NewClient(v1.Config{
Address: "gateway.example.com:443",
Auth: v1.StaticToken("my-token"),
})
if err != nil {
log.Fatal(err)
}
defer client.Close()
For production use, load the token from an environment variable instead of hardcoding it:
v1.StaticToken(os.Getenv("OPENSHELL_TOKEN"))
The Config struct accepts optional fields for TLS configuration and retry policies. For development against a local gateway without TLS, use v1.NoAuth() and set TLS to skip verification.
Check Gateway Health
Verify the gateway is reachable:
ctx := context.Background()
health, err := client.Health().Check(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Gateway healthy: %v\n", health.Healthy)
Create a Sandbox
Create a sandbox with a Python image:
sandbox, err := client.Sandboxes().Create(ctx, "default", "my-sandbox", &v1.SandboxSpec{
Template: &v1.SandboxTemplate{Image: "python:3.12"},
Environment: map[string]string{"LANG": "en_US.UTF-8"},
}, nil)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Created sandbox: %s\n", sandbox.Name)
Wait for the Sandbox to be Ready
Sandboxes take a moment to provision. Use WaitReady to block until the sandbox is ready to accept commands:
sandbox, err = client.Sandboxes().WaitReady(ctx, "default", sandbox.Name)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Sandbox is ready (phase: %s)\n", sandbox.Status.Phase)
Run a Command
Execute a command inside the sandbox:
result, err := client.Exec().Run(ctx, "default", sandbox.Name, []string{"echo", "hello from OpenShell"})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Output: %s", result.Stdout)
fmt.Printf("Exit code: %d\n", result.ExitCode)
For long-running commands, use Stream to receive output incrementally, or Interactive for terminal-like sessions.
Clean Up
Delete the sandbox when you are done:
err = client.Sandboxes().Delete(ctx, "default", sandbox.Name)
if err != nil {
log.Fatal(err)
}
fmt.Println("Sandbox deleted")
}
Next Steps
- Browse the API Overview to see all available interfaces
- Learn about Error Handling for production code
- Set up Testing with the fake client for your test suites
- Explore the Architecture to understand the SDK design