Skip to content

feat: add traffic token rotation logic to golang SDK - #55

Open
tianhr wants to merge 5 commits into
openkruise:masterfrom
tianhr:feat/golang-sdk-token-rotation
Open

tianhr wants to merge 5 commits into
openkruise:masterfrom
tianhr:feat/golang-sdk-token-rotation

Conversation

@tianhr

@tianhr tianhr commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

What this PR does

Ports the Python SDK's Traffic JWT auto-refresh capability (e2b/python/kruise_agents) to the Go SDK as a native implementation (no monkey-patching). Sandboxes created with metadata "security.agents.kruise.io/enable-jwt-auth": "true" get a short-lived Traffic JWT from sandbox-manager; every data-plane request must carry it in the e2b-traffic-access-token header or the gateway rejects it with 403. The Go SDK now attaches and rotates this token transparently — no caller-side code change required.

Key changes

Token manager (e2b/traffic_token.go)

  • trafficTokenManager: refreshes ahead of expiry (min(300s, max(60s, validity/5)) minus up to 10% random jitter), coalesces concurrent refreshes into one call (single-flight with pre-lock generation/attempts/busy snapshots), retries failures with exponential backoff (1s → 30s, server Retry-After honored), degrades to the still-valid current token on refresh failure, and fails closed with *TrafficAccessTokenExpired once the token has expired instead of sending a request the gateway would reject.
  • Refresh runs detached from the caller's context (context.WithoutCancel): cancelling a data-plane call does not abort an in-flight refresh that other callers depend on.
  • Refresh responses are validated like the Python patch: non-empty token, RFC3339 expiration with timezone, reported expiration must match the JWT exp claim within 5s tolerance, already-expired tokens are rejected.

Data-plane injection (runtime/traffic_token.go, runtime/client.go, runtime/config.go)

  • New runtime.TrafficTokenProvider + WithTrafficTokenProvider option; NewWithConfig wraps the non-streaming and streaming HTTP clients' RoundTripper so every data-plane request (Commands / Files / CodeInterpreter, unary and streaming alike) obtains a valid token right before it is sent — the Go counterpart of the Python patch's envd interceptors, httpx event hooks and Jupyter client hooks.
  • An empty token skips the header entirely, preserving legacy behavior for non-JWT sandboxes.

Sandbox integration (e2b/sandbox.go, e2b/sandbox_api.go, e2b/config.go)

  • Create / Connect seed the manager from the management-API response token; Connect without a token probes sandbox metadata via GetInfo and bootstraps lazily when enable-jwt-auth=true (best-effort: non-JWT deployments are unaffected), mirroring the Python patch's lazy-Connect behavior.
  • New WithTrafficAccessToken(token) sandbox option seeds an externally issued JWT (external identity-provider deployments), the counterpart of the Python Sandbox(traffic_access_token=...) constructor parameter; non-JWT values keep the legacy no-header behavior.
  • New public Sandbox.TrafficAccessToken() (cached token, no refresh) and Sandbox.RefreshTrafficAccessToken(ctx) (forced refresh, concurrent forces coalesce).
  • Hand-written SandboxApi.RefreshTrafficAccessToken endpoint (POST /sandboxes/{id}/traffic-access-token, not emitted by the OpenAPI generator): sends ConnectionConfig.Headers with X-API-Key applied last so the API key wins on collision (matching Python _refresh_headers), never surfaces the response body on failure, preserves status code and Retry-After in *TrafficAccessTokenRefreshError.
  • New WithHeader(key, value) connection option; custom headers now ride on every management request via DefaultHeader.
  • Refresh URL is resolved via the new ConnectionConfig.TrafficAPIBase(): upstream registers the refresh endpoint only under its /kruise/api prefix (web.RegisterRoute, asserted by upstream's TestTrafficAccessTokenRouteIsKruiseOnly), so the SDK always targets {scheme}://{domain}/kruise/api/sandboxes/{id}/traffic-access-token regardless of routing protocol — the default ProtocolNative included, whose https://api.<domain> base would 404. An explicit WithAPIURL override still wins as-is (proxy / port-forwarding escape hatch). This mirrors the Python patch, whose derived api_url always carries the prefix.
  • Legacy opaque (non-JWT) tokens and WithDebug(true) keep the existing behavior: no traffic header, no refresh.

Key compatibility encoding (e2b/keys.go)

  • EncodeForE2BSDK wraps a raw OpenKruise Agents API key into the e2b_-prefixed format enforced by official E2B SDK tooling (e2b_ + magic 6f6b6167 + version 01 + 8-hex length + hex body + salted SHA-256 checksum), byte-for-byte identical to Python keys.py:encode_for_e2b_sdk (golden-value tests).

Testing

  • 24 test functions in e2b/traffic_token_test.go + e2b/keys_test.go: full manager matrix (refresh window, jitter, bootstrap, coalescing incl. concurrent failed forced refreshes, backoff, Retry-After, fail-closed, response validation incl. not-a-JWT branches), HTTP integration against mock management/data-plane servers (header injection, custom headers, seed override, legacy degradation), and TestSandboxApiRefreshTrafficAccessTokenURL pinning the refresh path for native / private / WithAPIURL-override configurations.
  • go build ./..., go vet, go test ./e2b/... ./runtime/... all green.
  • Verified end to end against a real JWT-enabled sandbox-gateway (same Linux environment and parameters as the Python demo_jwt_gateway.py): data-plane calls without a valid JWT are rejected with 403, externally seeded tokens authenticate successfully, and two automatic rotations were observed under a 65s token validity with zero data-plane interruption.

Docs & examples

  • e2b/README.md + README_zh-CH.md: new "Traffic JWT Refresh" section (mechanism, manual-control APIs, refresh-endpoint routing note, rollout guidance — deploy refreshing clients before shortening --traffic-access-token-validity, deploy lazy-Connect before upgrading to a manager that no longer issues tokens from Connect); runtime READMEs document WithTrafficTokenProvider.
  • examples/jwt-gateway-example: Go counterpart of demo_jwt_gateway.py — full flow against a real gateway with an external OIDC issuer, using a local translating proxy for the refresh endpoint so the entire SDK refresh path (headers, Retry-After, response validation) is exercised.
  • examples/e2b-example: adds a pause → connect (resume) → data-plane re-verification segment; examples/runtime-example: adds a TRAFFIC_ACCESS_TOKEN-based provider demo.

Notes

  • Intentional structural differences vs the Python patch (not gaps): no async manager variant (the Go SDK exposes only a synchronous API), no e2b-version compatibility check (native implementation patches no SDK internals), no PTY coverage (the Go runtime has no PTY surface).
  • No breaking changes: without JWT-auth metadata or a traffic token, every path behaves exactly as before.

@kruise-bot

Copy link
Copy Markdown

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@tianhr
tianhr force-pushed the feat/golang-sdk-token-rotation branch from 9b21d62 to c828cf8 Compare September 28, 2026 08:23
@tianhr
tianhr marked this pull request as draft November 11, 2026 05:09
@tianhr
tianhr marked this pull request as ready for review November 11, 2026 05:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants