feat(sdk): add Go workspace service discovery client

Signed-off-by: Taylor Mutch <taylormutch@gmail.com>

Author: TaylorMutch

sdk/go/docs/src/SUMMARY.md

@@ -21,6 +21,7 @@
 - [Profiles](api/profiles.md)
 - [Refresh](api/refresh.md)
 - [Services](api/services.md)
+- [Service discovery](api/service-discovery.md)
 - [Files](api/files.md)
 - [Health](api/health.md)
 - [SSH](api/ssh.md)

sdk/go/docs/src/api/service-discovery.md

@@ -0,0 +1,45 @@
+# Service discovery
+
+Accessor: `client.ServiceRoutes()` on the concrete SDK client. Consumers can
+accept the narrow `ServiceDiscoveryInterface`; existing `ClientInterface` mocks
+are unchanged. Discovery reads accepted supervisor installations for one explicit
+workspace and requires the same workspace read authorization as the gateway API.
+
+```go
+snapshot, err := client.ServiceRoutes().Snapshot(ctx, "default")
+if err != nil {
+    return err
+}
+for _, route := range snapshot.Routes {
+    fmt.Println(route.Hostname, route.Endpoint, route.ExpiresAt)
+}
+
+watch, err := client.ServiceRoutes().Watch(ctx, "default")
+if err != nil {
+    return err
+}
+defer watch.Close()
+for {
+    replacement, err := watch.Recv()
+    if errors.Is(err, io.EOF) {
+        break // reconnect and relist after normal bounded stream completion
+    }
+    if err != nil {
+        return err // an error is not an empty replacement
+    }
+    _ = replacement // atomically replace the complete cached workspace view
+}
+```
+
+The SDK returns complete replacement snapshots without background prefetch or
+implicit reconnect. A caller must expire cached entries at `ExpiresAt` even when
+discovery is unavailable, reconnect/relist after stream termination, and clear
+routes when authorization is revoked. `Close` cancels the RPC and is safe to call
+concurrently with one receiving goroutine. Derive a cancelable watch context and
+choose snapshot deadlines appropriate for the consumer.
+
+Preserve `Hostname` as TLS SNI and HTTP authority when dialing `Endpoint`.
+`InstallationVersion` stays stable across lease-only renewal; `Revision` changes
+with expiry and is only an equality token. Installation is neither application
+health nor proof of external ingress acceptance. Platform-wide discovery-only
+identities and all-workspaces queries are separate work.

sdk/go/openshell/v1/client.go

@@ -56,6 +56,7 @@ type Client struct {
 	templates      SandboxTemplateInterface
 	providers      ProviderInterface
 	services       ServiceInterface
+	serviceRoutes  ServiceDiscoveryInterface
 	exec           ExecInterface
 	files          FileInterface
 	health         HealthInterface
@@ -102,6 +103,7 @@ func NewClient(cfg Config) (*Client, error) {
 	c.templates = newSandboxTemplateClient(conn)
 	c.providers = newProviderClient(conn)
 	c.services = newServiceClient(conn)
+	c.serviceRoutes = newServiceDiscoveryClient(conn)
 	c.exec = newExecClient(conn, c.sandboxes)
 	c.files = newFileClient(conn, c.sandboxes)
 	c.health = newHealthClient(conn)
@@ -132,6 +134,10 @@ func (c *Client) Providers() ProviderInterface { return c.providers }
 // Services returns the service sub-client.
 func (c *Client) Services() ServiceInterface { return c.services }
 
+// ServiceRoutes returns the read-only workspace discovery client. This additive
+// accessor has its own narrow consumer interface to preserve ClientInterface mocks.
+func (c *Client) ServiceRoutes() ServiceDiscoveryInterface { return c.serviceRoutes }
+
 // Exec returns the exec sub-client.
 func (c *Client) Exec() ExecInterface { return c.exec }
 

sdk/go/openshell/v1/internal/converter/service_discovery.go

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package converter
+
+import (
+	"github.com/NVIDIA/OpenShell/sdk/go/openshell/v1/types"
+	pb "github.com/NVIDIA/OpenShell/sdk/go/proto/openshellv1"
+)
+
+// ServiceRouteSnapshotFromProto validates and copies a full discovery view.
+func ServiceRouteSnapshotFromProto(snapshot *pb.ServiceRouteSnapshot, workspace string) (*types.ServiceRouteSnapshot, error) {
+	invalid := func() (*types.ServiceRouteSnapshot, error) {
+		return nil, &types.StatusError{Code: types.ErrorInternal, Message: "invalid service discovery snapshot"}
+	}
+	if snapshot == nil || snapshot.GetRevision() == "" || len(snapshot.GetRoutes()) > 4096 {
+		return invalid()
+	}
+	result := &types.ServiceRouteSnapshot{Revision: snapshot.GetRevision(), Routes: make([]types.DiscoveredServiceRoute, 0, len(snapshot.GetRoutes()))}
+	hostnames := make(map[string]bool, len(snapshot.GetRoutes()))
+	for _, route := range snapshot.GetRoutes() {
+		if route == nil || route.GetWorkspace() != workspace || route.GetHostname() == "" || route.GetInstallationVersion() == "" || route.GetEndpoint() == nil || route.GetEndpoint().GetHost() == "" || route.GetEndpoint().GetPort() == 0 || route.GetEndpoint().GetPort() > 65535 || route.GetExpiresAt() == nil || route.GetExpiresAt().CheckValid() != nil || hostnames[route.GetHostname()] {
+			return invalid()
+		}
+		hostnames[route.GetHostname()] = true
+		result.Routes = append(result.Routes, types.DiscoveredServiceRoute{
+			Workspace: route.GetWorkspace(), Sandbox: route.GetSandbox(), Name: route.GetName(), Hostname: route.GetHostname(),
+			Endpoint:            types.ServiceRouteEndpoint{Host: route.GetEndpoint().GetHost(), Port: route.GetEndpoint().GetPort()},
+			InstallationVersion: route.GetInstallationVersion(), DeclarationRevision: route.GetDeclarationRevision(), ExpiresAt: route.GetExpiresAt().AsTime(),
+		})
+	}
+	return result, nil
+}

sdk/go/openshell/v1/internal/converter/service_discovery_test.go

@@ -0,0 +1,32 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package converter
+
+import (
+	pb "github.com/NVIDIA/OpenShell/sdk/go/proto/openshellv1"
+	"github.com/stretchr/testify/require"
+	"google.golang.org/protobuf/types/known/timestamppb"
+	"testing"
+	"time"
+)
+
+func TestDiscoverySnapshotCopiesAndRejectsIncompleteViews(t *testing.T) {
+	wire := &pb.ServiceRouteSnapshot{Revision: "revision", Routes: []*pb.DiscoveredServiceRoute{{
+		Workspace: "default", Sandbox: "demo", Hostname: "demo.example.com", InstallationVersion: "owner-1",
+		Endpoint: &pb.ServiceRouteEndpoint{Host: "10.0.0.1", Port: 9443}, ExpiresAt: timestamppb.New(time.Now()),
+	}}}
+	snapshot, err := ServiceRouteSnapshotFromProto(wire, "default")
+	require.NoError(t, err)
+	snapshot.Routes[0].Endpoint.Host = "changed"
+	require.Equal(t, "10.0.0.1", wire.Routes[0].Endpoint.Host)
+	wire.Routes[0].Hostname = "different.example.com"
+	require.Equal(t, "demo.example.com", snapshot.Routes[0].Hostname)
+	_, err = ServiceRouteSnapshotFromProto(wire, "other")
+	require.Error(t, err)
+	wire.Routes[0].ExpiresAt = nil
+	_, err = ServiceRouteSnapshotFromProto(wire, "default")
+	require.Error(t, err)
+	_, err = ServiceRouteSnapshotFromProto(nil, "default")
+	require.Error(t, err)
+}

sdk/go/openshell/v1/service_discovery.go

@@ -0,0 +1,94 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package v1
+
+import (
+	"context"
+	"io"
+	"sync"
+
+	"github.com/NVIDIA/OpenShell/sdk/go/openshell/v1/internal/converter"
+	"github.com/NVIDIA/OpenShell/sdk/go/openshell/v1/types"
+	pb "github.com/NVIDIA/OpenShell/sdk/go/proto/openshellv1"
+	"google.golang.org/grpc"
+)
+
+// ServiceRouteSnapshot is a complete replacement view of workspace installations.
+type ServiceRouteSnapshot = types.ServiceRouteSnapshot
+
+// DiscoveredServiceRoute identifies an installed service and its current supervisor.
+type DiscoveredServiceRoute = types.DiscoveredServiceRoute
+
+// ServiceRouteEndpoint is the trusted supervisor TLS endpoint.
+type ServiceRouteEndpoint = types.ServiceRouteEndpoint
+
+// ServiceRouteWatch delivers full replacements. Call Recv from one goroutine;
+// Close is safe concurrently. EOF is normal bounded stream completion: reconnect
+// and relist. Errors are not empty replacements. Expire cached routes independently.
+type ServiceRouteWatch interface {
+	Recv() (*ServiceRouteSnapshot, error)
+	Close()
+}
+
+// ServiceDiscoveryInterface is a narrow interface for external discovery consumers.
+// It supports one explicit workspace and does not request all-workspaces grants.
+type ServiceDiscoveryInterface interface {
+	Snapshot(ctx context.Context, workspace string) (*ServiceRouteSnapshot, error)
+	Watch(ctx context.Context, workspace string) (ServiceRouteWatch, error)
+}
+
+type serviceDiscoveryClient struct{ client pb.OpenShellClient }
+
+func newServiceDiscoveryClient(conn grpc.ClientConnInterface) *serviceDiscoveryClient {
+	return &serviceDiscoveryClient{client: pb.NewOpenShellClient(conn)}
+}
+
+func (s *serviceDiscoveryClient) Snapshot(ctx context.Context, workspace string) (*ServiceRouteSnapshot, error) {
+	if workspace == "" {
+		return nil, &StatusError{Code: ErrorInvalidArgument, Message: "explicit workspace is required"}
+	}
+	response, err := s.client.GetServiceRouteSnapshot(ctx, &pb.GetServiceRouteSnapshotRequest{WorkspaceScope: namedWorkspaceScope(workspace)})
+	if err != nil {
+		return nil, converter.FromGRPCError(err)
+	}
+	return converter.ServiceRouteSnapshotFromProto(response.GetSnapshot(), workspace)
+}
+
+func (s *serviceDiscoveryClient) Watch(ctx context.Context, workspace string) (ServiceRouteWatch, error) {
+	if workspace == "" {
+		return nil, &StatusError{Code: ErrorInvalidArgument, Message: "explicit workspace is required"}
+	}
+	ctx, cancel := context.WithCancel(ctx)
+	stream, err := s.client.WatchServiceRoutes(ctx, &pb.WatchServiceRoutesRequest{WorkspaceScope: namedWorkspaceScope(workspace)})
+	if err != nil {
+		cancel()
+		return nil, converter.FromGRPCError(err)
+	}
+	return &serviceRouteWatch{stream: stream, cancel: cancel, workspace: workspace}, nil
+}
+
+type serviceRouteWatch struct {
+	stream    grpc.ServerStreamingClient[pb.WatchServiceRoutesResponse]
+	cancel    context.CancelFunc
+	workspace string
+	once      sync.Once
+}
+
+func (w *serviceRouteWatch) Close() { w.once.Do(w.cancel) }
+
+func (w *serviceRouteWatch) Recv() (*ServiceRouteSnapshot, error) {
+	response, err := w.stream.Recv()
+	if err != nil {
+		w.Close()
+		if err == io.EOF {
+			return nil, io.EOF
+		}
+		return nil, converter.FromGRPCError(err)
+	}
+	result, err := converter.ServiceRouteSnapshotFromProto(response.GetSnapshot(), w.workspace)
+	if err != nil {
+		w.Close()
+	}
+	return result, err
+}

sdk/go/openshell/v1/service_discovery_test.go

@@ -0,0 +1,134 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package v1
+
+import (
+	"context"
+	"io"
+	"net"
+	"testing"
+	"time"
+
+	dm "github.com/NVIDIA/OpenShell/sdk/go/proto/datamodelv1"
+	pb "github.com/NVIDIA/OpenShell/sdk/go/proto/openshellv1"
+	"github.com/stretchr/testify/require"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/credentials/insecure"
+	"google.golang.org/grpc/status"
+	"google.golang.org/grpc/test/bufconn"
+	"google.golang.org/protobuf/types/known/timestamppb"
+)
+
+type discoveryServer struct {
+	pb.UnimplementedOpenShellServer
+	views    []*pb.ServiceRouteSnapshot
+	terminal error
+	block    bool
+	canceled chan struct{}
+}
+
+func discoveryView(revision string, expires time.Time) *pb.ServiceRouteSnapshot {
+	return &pb.ServiceRouteSnapshot{Revision: revision, Routes: []*pb.DiscoveredServiceRoute{{
+		Workspace: "default", Sandbox: "demo", Name: "web", Hostname: "demo.example.com",
+		Endpoint:            &pb.ServiceRouteEndpoint{Host: "10.0.0.1", Port: 9443},
+		InstallationVersion: "owner-1", DeclarationRevision: 7, ExpiresAt: timestamppb.New(expires),
+	}}}
+}
+
+func (s *discoveryServer) GetServiceRouteSnapshot(_ context.Context, req *pb.GetServiceRouteSnapshotRequest) (*pb.GetServiceRouteSnapshotResponse, error) {
+	if req.GetWorkspaceScope().GetWorkspace() != "default" {
+		return nil, status.Error(codes.PermissionDenied, "workspace denied")
+	}
+	return &pb.GetServiceRouteSnapshotResponse{Snapshot: s.views[0]}, nil
+}
+func (s *discoveryServer) WatchServiceRoutes(req *pb.WatchServiceRoutesRequest, stream grpc.ServerStreamingServer[pb.WatchServiceRoutesResponse]) error {
+	if _, ok := req.GetWorkspaceScope().GetSelection().(*dm.WorkspaceSelector_Workspace); !ok {
+		return status.Error(codes.InvalidArgument, "explicit workspace required")
+	}
+	for _, view := range s.views {
+		if err := stream.Send(&pb.WatchServiceRoutesResponse{Snapshot: view}); err != nil {
+			return err
+		}
+	}
+	if s.block {
+		<-stream.Context().Done()
+		close(s.canceled)
+		return status.FromContextError(stream.Context().Err()).Err()
+	}
+	return s.terminal
+}
+
+func discoveryClientForTest(t *testing.T, mock *discoveryServer) *serviceDiscoveryClient {
+	t.Helper()
+	listener := bufconn.Listen(bufSize)
+	server := grpc.NewServer()
+	pb.RegisterOpenShellServer(server, mock)
+	go func() { _ = server.Serve(listener) }()
+	conn, err := grpc.NewClient("passthrough:///bufconn", grpc.WithContextDialer(func(context.Context, string) (net.Conn, error) { return listener.Dial() }), grpc.WithTransportCredentials(insecure.NewCredentials()))
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = conn.Close(); server.Stop(); _ = listener.Close() })
+	return newServiceDiscoveryClient(conn)
+}
+
+func TestDiscoverySnapshotAndWatchPreserveRenewalWithdrawalAndEOF(t *testing.T) {
+	expiry := time.Now().Add(10 * time.Second).UTC()
+	initial := discoveryView("revision-1", expiry)
+	renewal := discoveryView("revision-2", expiry.Add(4*time.Second))
+	empty := &pb.ServiceRouteSnapshot{Revision: "revision-3"}
+	client := discoveryClientForTest(t, &discoveryServer{views: []*pb.ServiceRouteSnapshot{initial, renewal, empty}})
+	snapshot, err := client.Snapshot(context.Background(), "default")
+	require.NoError(t, err)
+	require.Equal(t, "demo.example.com", snapshot.Routes[0].Hostname)
+	require.Equal(t, expiry, snapshot.Routes[0].ExpiresAt)
+	watch, err := client.Watch(context.Background(), "default")
+	require.NoError(t, err)
+	defer watch.Close()
+	first, err := watch.Recv()
+	require.NoError(t, err)
+	second, err := watch.Recv()
+	require.NoError(t, err)
+	require.NotEqual(t, first.Revision, second.Revision)
+	require.Equal(t, first.Routes[0].InstallationVersion, second.Routes[0].InstallationVersion)
+	require.NotEqual(t, first.Routes[0].ExpiresAt, second.Routes[0].ExpiresAt)
+	withdrawn, err := watch.Recv()
+	require.NoError(t, err)
+	require.Empty(t, withdrawn.Routes)
+	none, err := watch.Recv()
+	require.ErrorIs(t, err, io.EOF)
+	require.Nil(t, none)
+	_, err = client.Snapshot(context.Background(), "")
+	require.True(t, IsInvalidArgument(err))
+	_, err = client.Watch(context.Background(), "")
+	require.True(t, IsInvalidArgument(err))
+	_, err = client.Snapshot(context.Background(), "other")
+	require.True(t, IsPermissionDenied(err))
+}
+
+func TestDiscoveryErrorsAreNotEmptySnapshotsAndCloseCancelsRPC(t *testing.T) {
+	view := discoveryView("revision", time.Now().Add(time.Second))
+	client := discoveryClientForTest(t, &discoveryServer{views: []*pb.ServiceRouteSnapshot{view}, terminal: status.Error(codes.PermissionDenied, "revoked")})
+	watch, err := client.Watch(context.Background(), "default")
+	require.NoError(t, err)
+	_, err = watch.Recv()
+	require.NoError(t, err)
+	next, err := watch.Recv()
+	require.Nil(t, next)
+	require.True(t, IsPermissionDenied(err))
+	mock := &discoveryServer{views: []*pb.ServiceRouteSnapshot{view}, block: true, canceled: make(chan struct{})}
+	client = discoveryClientForTest(t, mock)
+	watch, err = client.Watch(context.Background(), "default")
+	require.NoError(t, err)
+	_, err = watch.Recv()
+	require.NoError(t, err)
+	watch.Close()
+	watch.Close()
+	_, err = watch.Recv()
+	require.True(t, IsCancelled(err))
+	select {
+	case <-mock.canceled:
+	case <-time.After(time.Second):
+		t.Fatal("watch cancellation did not reach server")
+	}
+}