Skip to content

feat(sdk): route Python SDK exec to the sandbox owner replica - #4918

Open
FrostGod wants to merge 1 commit into
NVIDIA:mainfrom
FrostGod:feat/4223-python-sdk-replica-routing/FrostGod
Open

FrostGod wants to merge 1 commit into
NVIDIA:mainfrom
FrostGod:feat/4223-python-sdk-replica-routing/FrostGod

Conversation

@FrostGod

Copy link
Copy Markdown
Collaborator

Summary

The Python SDK now sends exec calls straight to the gateway replica that owns the sandbox's supervisor session, as the CLI already does. Behind an edge proxy with replica routing enabled, this skips the relay hop through a peer replica; without one, the header is ignored and behavior is unchanged.

Related Issue

Part of #4223 (the "Every SDK asks for the owner and sends the replica hint, like the CLI" item, Python portion). Rust is #4790, Go is #4852, TypeScript is #4877.

Changes

  • exec_stream (and so exec, exec_python, and the session helpers) looks up the owner with GetSandbox and caches it per workspace and sandbox for 30 seconds, like the Rust SDK. A failed lookup leaves the call unrouted.
  • ExecSandbox carries x-openshell-replica and retries once without it when Envoy reports the owner's route has no ready endpoints (same rule as the CLI), forgetting the cached owner.
  • Calls are unchanged when the gateway reports no owner.

Release Notes

Python SDK exec calls now take the direct route to the sandbox's owner replica when replica routing is enabled.

Testing

  • Checks appropriate to the affected code and behavior pass (mise run python:lint, python:format:check, python:typecheck, test:python)
  • Unit tests added/updated (in-process gRPC gateway that answers routed calls with a trailers-only UNAVAILABLE: routing to the owner with one cached lookup, no hint without an owner, one unrouted retry for empty and "no healthy upstream" messages, no retry on gateway errors)
  • E2E tests added/updated (if applicable). Manual check on a local k3s VM (Ubuntu 26.04, Landlock-capable kernel) with Envoy Gateway and two StatefulSet replicas, using a real sandbox and supervisor session: 10 exec calls (with and without stdin) landed on the owner replica after one GetSandbox (unhinted baseline split 5/5), still succeeded via unrouted retry and peer relay when the owner's route had no endpoints, and followed the owner to the other replica after a gateway restart.

Checklist

  • Follows Conventional Commits
  • Commits are signed off (DCO)
  • Architecture docs updated (if applicable)

Ask GetSandbox for the owner replica, cache it for 30 seconds, and send
it as x-openshell-replica on ExecSandbox. Retry once without the hint
when the per-replica route has no healthy endpoint, forgetting the
cached owner.

Part of NVIDIA#4223

Signed-off-by: divesh <dgude@nvidia.com>
@copy-pr-bot

copy-pr-bot Bot commented Oct 26, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant