Skip to content

Commit ee31d96

Browse files
committed
feat(sdk/go): add Go SDK foundation, types, and sandbox client (A)
Module setup, all domain types, full ClientInterface with 10 sub-client accessors, shared infrastructure (errors, auth, gRPC transport, logging), and sandbox CRUD client with converter and tests. Stub clients for all other resources return Unimplemented errors until subsequent drops replace them. Includes proto generation via buf, proto-converter field coverage detection tests, and ObjectMeta fields (annotations, workspace, deletion_timestamp). Part of the 6-PR Go SDK contribution plan: NVIDIA#2270 Assisted-By: 🤖 Claude Code
1 parent d0f9301 commit ee31d96

82 files changed

Lines changed: 27675 additions & 0 deletions

Some content is hidden

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

‎buf.yaml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
# Repo-level buf module. Declares proto/ as the single module so buf generate,
5+
# buf lint, buf breaking, and the editor LSP all resolve imports the same way.
6+
# Code generation lives with each consumer (see sdk/go/buf.gen.yaml,
7+
# sdk/typescript/buf.gen.yaml); this file owns the module boundary and proto
8+
# validation policy.
9+
version: v2
10+
modules:
11+
- path: proto
12+
lint:
13+
use:
14+
- STANDARD
15+
except:
16+
# Flat proto/ layout: all files live in one directory with nested
17+
# packages (openshell.v1, openshell.sandbox.v1, ...). Adopting these
18+
# would require restructuring the tree into openshell/<svc>/v1/ and
19+
# updating every Rust/Python/TS codegen path and import.
20+
- DIRECTORY_SAME_PACKAGE
21+
- PACKAGE_DIRECTORY_MATCH
22+
# Established API shape: services are unsuffixed (OpenShell, not
23+
# OpenShellService) and RPCs reuse shared request/response messages with
24+
# short names. Renaming these is a breaking change across the codebase.
25+
- RPC_REQUEST_RESPONSE_UNIQUE
26+
- RPC_REQUEST_STANDARD_NAME
27+
- RPC_RESPONSE_STANDARD_NAME
28+
- SERVICE_SUFFIX
29+
breaking:
30+
use:
31+
- FILE

‎mise.lock‎

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

‎mise.toml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,11 @@ node = "24.15.0"
2525
kubectl = "1.36.1"
2626
uv = "0.10.12"
2727
protoc = "29.6"
28+
go = "1.26"
29+
"go:github.com/golangci/golangci-lint/v2/cmd/golangci-lint" = "2.12"
30+
"go:google.golang.org/protobuf/cmd/protoc-gen-go" = "1.36.11"
31+
"go:google.golang.org/grpc/cmd/protoc-gen-go-grpc" = "1.6.2"
32+
buf = "1.72.0"
2833
helm = "4.2.0"
2934
helm-docs = "1.14.2"
3035
skaffold = "2.20.0"

‎sdk/go/Makefile‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
MISE := $(shell command -v mise 2>/dev/null)
2+
3+
.PHONY: test test-integration lint fmt build ci docs-check proto
4+
5+
test:
6+
ifndef MISE
7+
$(error mise is not installed. Install from https://mise.jdx.dev)
8+
endif
9+
mise run go:test
10+
11+
test-integration:
12+
ifndef MISE
13+
$(error mise is not installed. Install from https://mise.jdx.dev)
14+
endif
15+
mise run go:test:integration
16+
17+
lint:
18+
ifndef MISE
19+
$(error mise is not installed. Install from https://mise.jdx.dev)
20+
endif
21+
mise run go:lint
22+
23+
fmt:
24+
ifndef MISE
25+
$(error mise is not installed. Install from https://mise.jdx.dev)
26+
endif
27+
mise run go:fmt
28+
29+
build:
30+
ifndef MISE
31+
$(error mise is not installed. Install from https://mise.jdx.dev)
32+
endif
33+
mise run go:build
34+
35+
ci:
36+
ifndef MISE
37+
$(error mise is not installed. Install from https://mise.jdx.dev)
38+
endif
39+
mise run go:ci
40+
41+
docs-check:
42+
ifndef MISE
43+
$(error mise is not installed. Install from https://mise.jdx.dev)
44+
endif
45+
mise run go:docs:check
46+
47+
proto:
48+
ifndef MISE
49+
$(error mise is not installed. Install from https://mise.jdx.dev)
50+
endif
51+
mise run go:proto:gen

‎sdk/go/buf.gen.yaml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
# Code generation for the Go SDK. The proto module boundary and validation
5+
# policy live in the repo-level buf.yaml; this template only drives generation.
6+
# buf compiles the module with its own compiler and runs protoc-gen-go /
7+
# protoc-gen-go-grpc from mise-managed binaries. Limited to the client-surface
8+
# closure (openshell, datamodel, sandbox, options); well-known types resolve
9+
# through google.golang.org/protobuf and are not generated.
10+
version: v2
11+
12+
inputs:
13+
- directory: ../../proto
14+
paths:
15+
- ../../proto/openshell.proto
16+
- ../../proto/datamodel.proto
17+
- ../../proto/sandbox.proto
18+
- ../../proto/options.proto
19+
20+
plugins:
21+
- local: protoc-gen-go
22+
out: .
23+
opt:
24+
- module=github.com/NVIDIA/OpenShell/sdk/go
25+
- Mopenshell.proto=github.com/NVIDIA/OpenShell/sdk/go/proto/openshellv1
26+
- Mdatamodel.proto=github.com/NVIDIA/OpenShell/sdk/go/proto/datamodelv1
27+
- Msandbox.proto=github.com/NVIDIA/OpenShell/sdk/go/proto/sandboxv1
28+
- Moptions.proto=github.com/NVIDIA/OpenShell/sdk/go/proto/optionsv1
29+
- local: protoc-gen-go-grpc
30+
out: .
31+
opt:
32+
- module=github.com/NVIDIA/OpenShell/sdk/go
33+
- Mopenshell.proto=github.com/NVIDIA/OpenShell/sdk/go/proto/openshellv1
34+
- Mdatamodel.proto=github.com/NVIDIA/OpenShell/sdk/go/proto/datamodelv1
35+
- Msandbox.proto=github.com/NVIDIA/OpenShell/sdk/go/proto/sandboxv1
36+
- Moptions.proto=github.com/NVIDIA/OpenShell/sdk/go/proto/optionsv1

‎sdk/go/go.mod‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
module github.com/NVIDIA/OpenShell/sdk/go
2+
3+
go 1.24.0
4+
5+
toolchain go1.26.4
6+
7+
require (
8+
github.com/stretchr/testify v1.11.1
9+
golang.org/x/oauth2 v0.35.0
10+
google.golang.org/grpc v1.80.0
11+
google.golang.org/protobuf v1.36.11
12+
)
13+
14+
require (
15+
github.com/davecgh/go-spew v1.1.1 // indirect
16+
github.com/pmezard/go-difflib v1.0.0 // indirect
17+
golang.org/x/net v0.49.0 // indirect
18+
golang.org/x/sys v0.41.0 // indirect
19+
golang.org/x/text v0.33.0 // indirect
20+
google.golang.org/genproto/googleapis/rpc v0.0.0-20260120221211-b8f7ae30c516 // indirect
21+
gopkg.in/yaml.v3 v3.0.1 // indirect
22+
)

‎sdk/go/go.sum‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
2+
github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
3+
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
4+
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
5+
github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
6+
github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
7+
github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
8+
github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
9+
github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
10+
github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
11+
github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
12+
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
13+
github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
14+
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
15+
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
16+
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
17+
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
18+
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
19+
go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
20+
go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
21+
go.opentelemetry.io/otel v1.39.0 h1:8yPrr/S0ND9QEfTfdP9V+SiwT4E0G7Y5MO7p85nis48=
22+
go.opentelemetry.io/otel v1.39.0/go.mod h1:kLlFTywNWrFyEdH0oj2xK0bFYZtHRYUdv1NklR/tgc8=
23+
go.opentelemetry.io/otel/metric v1.39.0 h1:d1UzonvEZriVfpNKEVmHXbdf909uGTOQjA0HF0Ls5Q0=
24+
go.opentelemetry.io/otel/metric v1.39.0/go.mod h1:jrZSWL33sD7bBxg1xjrqyDjnuzTUB0x1nBERXd7Ftcs=
25+
go.opentelemetry.io/otel/sdk v1.39.0 h1:nMLYcjVsvdui1B/4FRkwjzoRVsMK8uL/cj0OyhKzt18=
26+
go.opentelemetry.io/otel/sdk v1.39.0/go.mod h1:vDojkC4/jsTJsE+kh+LXYQlbL8CgrEcwmt1ENZszdJE=
27+
go.opentelemetry.io/otel/sdk/metric v1.39.0 h1:cXMVVFVgsIf2YL6QkRF4Urbr/aMInf+2WKg+sEJTtB8=
28+
go.opentelemetry.io/otel/sdk/metric v1.39.0/go.mod h1:xq9HEVH7qeX69/JnwEfp6fVq5wosJsY1mt4lLfYdVew=
29+
go.opentelemetry.io/otel/trace v1.39.0 h1:2d2vfpEDmCJ5zVYz7ijaJdOF59xLomrvj7bjt6/qCJI=
30+
go.opentelemetry.io/otel/trace v1.39.0/go.mod h1:88w4/PnZSazkGzz/w84VHpQafiU4EtqqlVdxWy+rNOA=
31+
golang.org/x/net v0.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o=
32+
golang.org/x/net v0.49.0/go.mod h1:/ysNB2EvaqvesRkuLAyjI1ycPZlQHM3q01F02UY/MV8=
33+
golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ=
34+
golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
35+
golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
36+
golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
37+
golang.org/x/text v0.33.0 h1:B3njUFyqtHDUI5jMn1YIr5B0IE2U0qck04r6d4KPAxE=
38+
golang.org/x/text v0.33.0/go.mod h1:LuMebE6+rBincTi9+xWTY8TztLzKHc/9C1uBCG27+q8=
39+
gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
40+
gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
41+
google.golang.org/genproto/googleapis/rpc v0.0.0-20260120221211-b8f7ae30c516 h1:sNrWoksmOyF5bvJUcnmbeAmQi8baNhqg5IWaI3llQqU=
42+
google.golang.org/genproto/googleapis/rpc v0.0.0-20260120221211-b8f7ae30c516/go.mod h1:j9x/tPzZkyxcgEFkiKEEGxfvyumM01BEtsW8xzOahRQ=
43+
google.golang.org/grpc v1.80.0 h1:Xr6m2WmWZLETvUNvIUmeD5OAagMw3FiKmMlTdViWsHM=
44+
google.golang.org/grpc v1.80.0/go.mod h1:ho/dLnxwi3EDJA4Zghp7k2Ec1+c2jqup0bFkw07bwF4=
45+
google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
46+
google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
47+
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
48+
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
49+
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
50+
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

‎sdk/go/openshell/v1/auth.go‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
package v1
5+
6+
import (
7+
"context"
8+
9+
"github.com/NVIDIA/OpenShell/sdk/go/openshell/v1/types"
10+
)
11+
12+
// AuthProvider supplies per-RPC credentials. It implements the
13+
// grpc credentials.PerRPCCredentials interface.
14+
type AuthProvider = types.AuthProvider
15+
16+
type noAuth struct{}
17+
18+
// NoAuth returns an AuthProvider that sends no credentials.
19+
func NoAuth() AuthProvider {
20+
return &noAuth{}
21+
}
22+
23+
func (n *noAuth) GetRequestMetadata(_ context.Context, _ ...string) (map[string]string, error) {
24+
return nil, nil
25+
}
26+
27+
func (n *noAuth) RequireTransportSecurity() bool {
28+
return false
29+
}
30+
31+
type staticToken struct {
32+
token string
33+
}
34+
35+
// StaticToken returns an AuthProvider that sends a fixed Bearer token.
36+
func StaticToken(token string) AuthProvider {
37+
return &staticToken{token: token}
38+
}
39+
40+
func (s *staticToken) GetRequestMetadata(_ context.Context, _ ...string) (map[string]string, error) {
41+
return map[string]string{
42+
"authorization": "Bearer " + s.token,
43+
}, nil
44+
}
45+
46+
func (s *staticToken) RequireTransportSecurity() bool {
47+
return true
48+
}

‎sdk/go/openshell/v1/auth_extra.go‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
package v1
5+
6+
import (
7+
"context"
8+
"errors"
9+
"maps"
10+
"strings"
11+
12+
"github.com/NVIDIA/OpenShell/sdk/go/openshell/v1/types"
13+
)
14+
15+
// extraHeadersAuth wraps a base AuthProvider with additional static headers
16+
// that are merged into every GetRequestMetadata call. Extra headers take
17+
// precedence over base headers on key collision (case-insensitive).
18+
type extraHeadersAuth struct {
19+
base types.AuthProvider
20+
headers map[string]string // keys already lowercase, empty values filtered out
21+
}
22+
23+
// WithExtraHeaders wraps base with additional per-RPC headers. Keys are
24+
// normalized to lowercase per HTTP/2 (RFC 9113). Empty-string values are
25+
// silently dropped. The headers map is deep-copied at construction time,
26+
// so later mutations to the caller's map have no effect.
27+
//
28+
// Returns an error if base is nil or if headers is nil, empty, or contains
29+
// only empty-string values.
30+
func WithExtraHeaders(base AuthProvider, headers map[string]string) (AuthProvider, error) {
31+
if base == nil {
32+
return nil, errors.New("base auth provider must not be nil")
33+
}
34+
if len(headers) == 0 {
35+
return nil, errors.New("headers must not be nil or empty")
36+
}
37+
38+
// Deep-copy and normalize: lowercase keys, skip empty values.
39+
normalized := make(map[string]string, len(headers))
40+
for k, v := range headers {
41+
if v == "" {
42+
continue
43+
}
44+
normalized[strings.ToLower(k)] = v
45+
}
46+
47+
if len(normalized) == 0 {
48+
return nil, errors.New("headers must contain at least one non-empty value")
49+
}
50+
51+
return &extraHeadersAuth{
52+
base: base,
53+
headers: normalized,
54+
}, nil
55+
}
56+
57+
// GetRequestMetadata merges base metadata with extra headers. Extra headers
58+
// win on key collision because they are applied after the base metadata.
59+
func (e *extraHeadersAuth) GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error) {
60+
baseMD, err := e.base.GetRequestMetadata(ctx, uri...)
61+
if err != nil {
62+
return nil, err
63+
}
64+
65+
// Start with base metadata (may be nil for NoAuth).
66+
// Normalize base keys to lowercase for case-insensitive collision.
67+
merged := make(map[string]string, len(baseMD)+len(e.headers))
68+
for k, v := range baseMD {
69+
merged[strings.ToLower(k)] = v
70+
}
71+
// Extra headers overwrite base on collision.
72+
maps.Copy(merged, e.headers)
73+
74+
return merged, nil
75+
}
76+
77+
// RequireTransportSecurity delegates to the base auth provider.
78+
func (e *extraHeadersAuth) RequireTransportSecurity() bool {
79+
return e.base.RequireTransportSecurity()
80+
}

0 commit comments

Comments
 (0)