Skip to content

Commit f4f489b

Browse files
committed
feat(sdk): route Go SDK exec and forward to the sandbox owner replica
The Go SDK now does what the CLI already does for long-lived sandbox calls. The GetSandbox check that Exec.Run, Exec.Stream, Exec.Interactive, TCP.Forward and SSH.Tunnel already make also asks the gateway for the owner replica. The call then sends it in the x-openshell-replica header and retries once without the header when the edge proxy reports that the owner's route has no ready endpoints. No extra round trip is added. Without a reported owner the calls are unchanged. Part of NVIDIA#4223 Signed-off-by: divesh <[email protected]>
1 parent f07127e commit f4f489b

6 files changed

Lines changed: 335 additions & 33 deletions

File tree

‎sdk/go/openshell/v1/exec_client.go‎

Lines changed: 26 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,8 @@ func (e *execClient) Run(ctx context.Context, workspace, sandboxName string, com
2727
if sandboxName == "" {
2828
return nil, &StatusError{Code: ErrorInvalidArgument, Message: "sandbox name must not be empty"}
2929
}
30-
if _, err := e.sandboxes.Get(ctx, workspace, sandboxName); err != nil {
30+
owner, err := sandboxOwner(ctx, e.sandboxes, workspace, sandboxName)
31+
if err != nil {
3132
return nil, err
3233
}
3334
var opt *ExecOptions
@@ -37,7 +38,9 @@ func (e *execClient) Run(ctx context.Context, workspace, sandboxName string, com
3738
req := converter.ExecRequestToProto(sandboxName, command, opt)
3839
req.WorkspaceScope = namedWorkspaceScope(workspace)
3940

40-
stream, err := e.client.ExecSandbox(ctx, req)
41+
stream, err := openRouted(ctx, owner, func(ctx context.Context) (grpc.ServerStreamingClient[pb.ExecSandboxEvent], error) {
42+
return e.client.ExecSandbox(ctx, req)
43+
})
4144
if err != nil {
4245
return nil, converter.FromGRPCError(err)
4346
}
@@ -61,7 +64,8 @@ func (e *execClient) Stream(ctx context.Context, workspace, sandboxName string,
6164
if sandboxName == "" {
6265
return nil, &StatusError{Code: ErrorInvalidArgument, Message: "sandbox name must not be empty"}
6366
}
64-
if _, err := e.sandboxes.Get(ctx, workspace, sandboxName); err != nil {
67+
owner, err := sandboxOwner(ctx, e.sandboxes, workspace, sandboxName)
68+
if err != nil {
6569
return nil, err
6670
}
6771
var opt *ExecOptions
@@ -72,7 +76,9 @@ func (e *execClient) Stream(ctx context.Context, workspace, sandboxName string,
7276
req.WorkspaceScope = namedWorkspaceScope(workspace)
7377

7478
streamCtx, cancel := context.WithCancel(ctx)
75-
stream, err := e.client.ExecSandbox(streamCtx, req)
79+
stream, err := openRouted(streamCtx, owner, func(ctx context.Context) (grpc.ServerStreamingClient[pb.ExecSandboxEvent], error) {
80+
return e.client.ExecSandbox(ctx, req)
81+
})
7682
if err != nil {
7783
cancel()
7884
return nil, converter.FromGRPCError(err)
@@ -85,30 +91,35 @@ func (e *execClient) Interactive(ctx context.Context, workspace, sandboxName str
8591
if sandboxName == "" {
8692
return nil, &StatusError{Code: ErrorInvalidArgument, Message: "sandbox name must not be empty"}
8793
}
88-
if _, err := e.sandboxes.Get(ctx, workspace, sandboxName); err != nil {
94+
owner, err := sandboxOwner(ctx, e.sandboxes, workspace, sandboxName)
95+
if err != nil {
8996
return nil, err
9097
}
9198
var opt *ExecOptions
9299
if len(opts) > 0 {
93100
opt = &opts[0]
94101
}
95102

103+
startReq := converter.ExecInteractiveRequestToProto(sandboxName, command, cols, rows, opt)
104+
startReq.WorkspaceScope = namedWorkspaceScope(workspace)
105+
96106
streamCtx, cancel := context.WithCancel(ctx)
97-
stream, err := e.client.ExecSandboxInteractive(streamCtx)
107+
stream, err := openRouted(streamCtx, owner, func(ctx context.Context) (grpc.BidiStreamingClient[pb.ExecSandboxInput, pb.ExecSandboxEvent], error) {
108+
s, err := e.client.ExecSandboxInteractive(ctx)
109+
if err != nil {
110+
return nil, err
111+
}
112+
// io.EOF means the stream already ended; its status comes from Recv.
113+
if err := s.Send(&pb.ExecSandboxInput{Payload: &pb.ExecSandboxInput_Start{Start: startReq}}); err != nil && err != io.EOF {
114+
return s, err
115+
}
116+
return s, nil
117+
})
98118
if err != nil {
99119
cancel()
100120
return nil, converter.FromGRPCError(err)
101121
}
102122

103-
startReq := converter.ExecInteractiveRequestToProto(sandboxName, command, cols, rows, opt)
104-
startReq.WorkspaceScope = namedWorkspaceScope(workspace)
105-
if sendErr := stream.Send(&pb.ExecSandboxInput{
106-
Payload: &pb.ExecSandboxInput_Start{Start: startReq},
107-
}); sendErr != nil {
108-
cancel()
109-
return nil, converter.FromGRPCError(sendErr)
110-
}
111-
112123
return newInteractiveSession(streamCtx, cancel, stream), nil
113124
}
114125

‎sdk/go/openshell/v1/routing.go‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
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+
"io"
9+
"strings"
10+
11+
pb "github.com/NVIDIA/OpenShell/sdk/go/proto/openshellv1"
12+
"google.golang.org/grpc"
13+
"google.golang.org/grpc/codes"
14+
"google.golang.org/grpc/metadata"
15+
"google.golang.org/grpc/status"
16+
)
17+
18+
// Metadata that lets an edge proxy send a sandbox's long-lived calls straight
19+
// to the gateway replica holding its supervisor session.
20+
const (
21+
ownerReplicaHeader = "x-openshell-owner"
22+
ownerRequestHeader = "x-openshell-want-owner"
23+
routeReplicaHeader = "x-openshell-replica"
24+
)
25+
26+
// ownerGetter is implemented by the gateway-backed sandbox client.
27+
type ownerGetter interface {
28+
getWithOwner(ctx context.Context, workspace, name string) (*Sandbox, string, error)
29+
}
30+
31+
// sandboxOwner checks that the sandbox exists and returns the replica that
32+
// owns its supervisor session, or "" when the gateway reports none.
33+
func sandboxOwner(ctx context.Context, sandboxes SandboxInterface, workspace, name string) (string, error) {
34+
if g, ok := sandboxes.(ownerGetter); ok {
35+
_, owner, err := g.getWithOwner(ctx, workspace, name)
36+
return owner, err
37+
}
38+
_, err := sandboxes.Get(ctx, workspace, name)
39+
return "", err
40+
}
41+
42+
// openRouted opens a stream tagged with the owner replica. It opens once more
43+
// untagged when the proxy reports that the owner's route has no ready endpoints.
44+
// A stale owner is safe: any replica relays the call to the real owner.
45+
func openRouted[S grpc.ClientStream](ctx context.Context, owner string, open func(context.Context) (S, error)) (S, error) {
46+
if owner == "" {
47+
return open(ctx)
48+
}
49+
stream, err := open(metadata.AppendToOutgoingContext(ctx, routeReplicaHeader, owner))
50+
if err == nil {
51+
// Header blocks until the proxy answers; nil metadata means the stream
52+
// ended without headers, and RecvMsg then returns its status.
53+
var md metadata.MD
54+
if md, err = stream.Header(); err == nil && md == nil {
55+
err = stream.RecvMsg(nil)
56+
}
57+
}
58+
if retryUnrouted(err) {
59+
return open(ctx)
60+
}
61+
return stream, err
62+
}
63+
64+
// openForward opens a ForwardTcp stream routed to owner and sends its init frame.
65+
func openForward(ctx context.Context, client pb.OpenShellClient, owner string, init *pb.TcpForwardFrame) (grpc.BidiStreamingClient[pb.TcpForwardFrame, pb.TcpForwardFrame], error) {
66+
return openRouted(ctx, owner, func(ctx context.Context) (grpc.BidiStreamingClient[pb.TcpForwardFrame, pb.TcpForwardFrame], error) {
67+
s, err := client.ForwardTcp(ctx)
68+
if err != nil {
69+
return nil, err
70+
}
71+
// io.EOF means the stream already ended; its status comes from Recv.
72+
if err := s.Send(init); err != nil && err != io.EOF {
73+
return s, err
74+
}
75+
return s, nil
76+
})
77+
}
78+
79+
// retryUnrouted matches what Envoy Gateway answers for a replica route with no
80+
// ready endpoints: UNAVAILABLE with no message. Gateway errors always carry one.
81+
func retryUnrouted(err error) bool {
82+
s, ok := status.FromError(err)
83+
if !ok || s.Code() != codes.Unavailable {
84+
return false
85+
}
86+
msg := s.Message()
87+
return msg == "" || strings.Contains(msg, "no healthy upstream") || strings.Contains(msg, "connection failure")
88+
}
Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
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+
"io"
9+
"net"
10+
"sync"
11+
"testing"
12+
13+
pb "github.com/NVIDIA/OpenShell/sdk/go/proto/openshellv1"
14+
"github.com/stretchr/testify/assert"
15+
"github.com/stretchr/testify/require"
16+
"google.golang.org/grpc"
17+
"google.golang.org/grpc/codes"
18+
"google.golang.org/grpc/credentials/insecure"
19+
"google.golang.org/grpc/metadata"
20+
"google.golang.org/grpc/status"
21+
"google.golang.org/grpc/test/bufconn"
22+
)
23+
24+
// routingServer reports owner from GetSandbox and records the replica header
25+
// of every streaming call ("" when unrouted). Routed calls fail with routedErr.
26+
type routingServer struct {
27+
pb.UnimplementedOpenShellServer
28+
owner string
29+
routedErr error
30+
31+
mu sync.Mutex
32+
wantedBy []string
33+
routes []string
34+
}
35+
36+
func (s *routingServer) GetSandbox(ctx context.Context, _ *pb.GetSandboxRequest) (*pb.SandboxResponse, error) {
37+
md, _ := metadata.FromIncomingContext(ctx)
38+
s.mu.Lock()
39+
s.wantedBy = append(s.wantedBy, firstValue(md, ownerRequestHeader))
40+
s.mu.Unlock()
41+
if s.owner != "" {
42+
_ = grpc.SetHeader(ctx, metadata.Pairs(ownerReplicaHeader, s.owner))
43+
}
44+
return &pb.SandboxResponse{Sandbox: &pb.Sandbox{}}, nil
45+
}
46+
47+
// route records the call and returns the error a routed call should fail with.
48+
func (s *routingServer) route(ctx context.Context) error {
49+
md, _ := metadata.FromIncomingContext(ctx)
50+
replica := firstValue(md, routeReplicaHeader)
51+
s.mu.Lock()
52+
defer s.mu.Unlock()
53+
s.routes = append(s.routes, replica)
54+
if replica != "" {
55+
return s.routedErr
56+
}
57+
return nil
58+
}
59+
60+
func (s *routingServer) ExecSandbox(_ *pb.ExecSandboxRequest, stream grpc.ServerStreamingServer[pb.ExecSandboxEvent]) error {
61+
if err := s.route(stream.Context()); err != nil {
62+
return err
63+
}
64+
return stream.Send(exitEvent())
65+
}
66+
67+
func (s *routingServer) ExecSandboxInteractive(stream grpc.BidiStreamingServer[pb.ExecSandboxInput, pb.ExecSandboxEvent]) error {
68+
if _, err := stream.Recv(); err != nil {
69+
return err
70+
}
71+
if err := s.route(stream.Context()); err != nil {
72+
return err
73+
}
74+
return stream.Send(exitEvent())
75+
}
76+
77+
func (s *routingServer) ForwardTcp(stream grpc.BidiStreamingServer[pb.TcpForwardFrame, pb.TcpForwardFrame]) error { //nolint:revive // proto-generated method name
78+
if _, err := stream.Recv(); err != nil {
79+
return err
80+
}
81+
if err := s.route(stream.Context()); err != nil {
82+
return err
83+
}
84+
return stream.Send(&pb.TcpForwardFrame{Payload: &pb.TcpForwardFrame_Data{Data: []byte("pong")}})
85+
}
86+
87+
func exitEvent() *pb.ExecSandboxEvent {
88+
return &pb.ExecSandboxEvent{Payload: &pb.ExecSandboxEvent_Exit{Exit: &pb.ExecSandboxExit{}}}
89+
}
90+
91+
func firstValue(md metadata.MD, key string) string {
92+
if v := md.Get(key); len(v) > 0 {
93+
return v[0]
94+
}
95+
return ""
96+
}
97+
98+
func routingClients(t *testing.T, srv *routingServer) (*execClient, *tcpClient) {
99+
t.Helper()
100+
lis := bufconn.Listen(bufSize)
101+
gs := grpc.NewServer()
102+
pb.RegisterOpenShellServer(gs, srv)
103+
go func() { _ = gs.Serve(lis) }()
104+
conn, err := grpc.NewClient("passthrough:///bufconn",
105+
grpc.WithContextDialer(func(context.Context, string) (net.Conn, error) { return lis.Dial() }),
106+
grpc.WithTransportCredentials(insecure.NewCredentials()),
107+
)
108+
require.NoError(t, err)
109+
t.Cleanup(func() {
110+
_ = conn.Close()
111+
gs.Stop()
112+
})
113+
sandboxes := newSandboxClient(conn)
114+
return newExecClient(conn, sandboxes), newTCPClient(conn, sandboxes, nil)
115+
}
116+
117+
func TestExecRoutesToOwner(t *testing.T) {
118+
srv := &routingServer{owner: "openshell-1"}
119+
exec, _ := routingClients(t, srv)
120+
121+
_, err := exec.Run(context.Background(), "default", "box", []string{"true"})
122+
require.NoError(t, err)
123+
124+
assert.Equal(t, []string{"1"}, srv.wantedBy)
125+
assert.Equal(t, []string{"openshell-1"}, srv.routes)
126+
}
127+
128+
func TestExecWithoutOwnerIsUnrouted(t *testing.T) {
129+
srv := &routingServer{}
130+
exec, _ := routingClients(t, srv)
131+
132+
_, err := exec.Run(context.Background(), "default", "box", []string{"true"})
133+
require.NoError(t, err)
134+
135+
assert.Equal(t, []string{""}, srv.routes)
136+
}
137+
138+
func TestRoutedCallsRetryOnceWithoutHintWhenOwnerHasNoEndpoints(t *testing.T) {
139+
srv := &routingServer{owner: "openshell-1", routedErr: status.Error(codes.Unavailable, "")}
140+
exec, tcp := routingClients(t, srv)
141+
ctx := context.Background()
142+
143+
_, err := exec.Run(ctx, "default", "box", []string{"true"})
144+
require.NoError(t, err)
145+
146+
stream, err := exec.Stream(ctx, "default", "box", []string{"true"})
147+
require.NoError(t, err)
148+
code, err := stream.ExitCode()
149+
require.NoError(t, err)
150+
assert.Zero(t, code)
151+
152+
session, err := exec.Interactive(ctx, "default", "box", []string{"sh"}, 80, 24)
153+
require.NoError(t, err)
154+
_, err = session.ExitCode()
155+
require.NoError(t, err)
156+
157+
conn, err := tcp.Forward(ctx, "default", "box", 8080)
158+
require.NoError(t, err)
159+
buf := make([]byte, 4)
160+
_, err = io.ReadFull(conn, buf)
161+
require.NoError(t, err)
162+
assert.Equal(t, "pong", string(buf))
163+
_ = conn.Close()
164+
165+
// Each call is attempted routed, then once unrouted.
166+
assert.Equal(t, []string{
167+
"openshell-1", "", "openshell-1", "", "openshell-1", "", "openshell-1", "",
168+
}, srv.routes)
169+
}
170+
171+
func TestRoutedCallDoesNotRetryOnGatewayError(t *testing.T) {
172+
srv := &routingServer{owner: "openshell-1", routedErr: status.Error(codes.Unavailable, "supervisor not connected")}
173+
exec, tcp := routingClients(t, srv)
174+
ctx := context.Background()
175+
176+
_, err := exec.Run(ctx, "default", "box", []string{"true"})
177+
require.Error(t, err)
178+
_, err = tcp.Forward(ctx, "default", "box", 8080)
179+
require.Error(t, err)
180+
181+
assert.Equal(t, []string{"openshell-1", "openshell-1"}, srv.routes)
182+
}
183+
184+
func TestRetryUnrouted(t *testing.T) {
185+
assert.True(t, retryUnrouted(status.Error(codes.Unavailable, "")))
186+
assert.True(t, retryUnrouted(status.Error(codes.Unavailable, "no healthy upstream")))
187+
assert.True(t, retryUnrouted(status.Error(codes.Unavailable, "upstream connect error: connection failure")))
188+
assert.False(t, retryUnrouted(status.Error(codes.Unavailable, "supervisor not connected")))
189+
assert.False(t, retryUnrouted(status.Error(codes.NotFound, "")))
190+
assert.False(t, retryUnrouted(io.EOF))
191+
assert.False(t, retryUnrouted(nil))
192+
}

0 commit comments

Comments
 (0)