feat(gateway): implement wake-on-traffic for paused sandboxes

[furykerry]

Ⅰ. Describe what this PR does

This PR implements wake-on-traffic for paused sandboxes in the sandbox-gateway. When a paused sandbox receives incoming traffic, the gateway automatically resumes it and forwards the request once the sandbox is running again.

Key changes:

1. Wake-on-traffic in filter (pkg/sandbox-gateway/filter/filter.go): When a paused sandbox with WakeOnTraffic=true receives traffic, the filter launches wake in a goroutine with a detached context and returns api.Running to suspend Envoy request processing. The wakeAndContinue goroutine calls Continue(api.Continue) on success or SendLocalReply(503) on failure. Thread-safe completion state machine (mutex-protected) prevents double-reply when async goroutine and Destroy race.
2. New wake package (pkg/sandbox-gateway/wake/wake.go): Implements Waker with retry logic for transient states (e.g., SandboxIsPausing). Calls sandbox.Resume() to patch the spec and waits for the sandbox to reach Running state via the cache wait reconciler. Uses errors.Is() with sentinel errors for error classification (not string matching). Singleflight deduplication: concurrent Wake calls for the same sandbox are coalesced via singleflight.Group so only one Resume is issued to the API server. Uses DoChan + select pattern so callers can bail out independently while shared work continues under a detached context.
3. E2B pause with spec patch (pkg/servers/e2b/pause_resume.go): Adds Pause() that sets Spec.DesiredState=Paused (instead of deleting the sandbox), enabling the wake-on-traffic flow. updateWakeAnnotations patches wake annotations as a separate API call after Resume.
4. Registry route lifecycle (pkg/sandbox-gateway/server/server.go): handleRefresh retains routes for all states except dead and empty string. This ensures the filter has full visibility (including paused, creating, available) for routing and wake decisions.
5. Sentinel error classification (pkg/utils/utils.go, pkg/sandbox-manager/errors/error.go): Exports sentinel errors (ErrSandboxIsPausing, ErrSandboxIsTerminating, ErrShutdownTimeReached, ErrSandboxPhaseNotAllowed) from IsSandboxResumable. Adds Unwrap() + NewErrorWrap() to managererrors.Error to enable errors.Is() through wrapped errors.
6. Gateway cache optimization (pkg/cache/cache.go): Restricts the gateway's informer cache to only Sandbox resources via ByObject filtering, reducing memory usage and API server load.
7. Configuration: Adds ENABLE_WAKE_ON_TRAFFIC env var and wakeTimeoutSeconds config to the gateway filter.

Ⅱ. Does this pull request fix one issue?

NONE

Ⅲ. Describe how to verify it

1. Run unit tests:

   go test ./pkg/sandbox-gateway/... ./pkg/cache/... ./pkg/servers/e2b/... ./pkg/utils/...

2. Run E2E test:

   pytest test/e2b/test_wake_on_traffic.py

3. Manual verification:
   • Create a sandbox, pause it via POST /sandboxes/{id}/pause
   • Send traffic to the paused sandbox
   • Verify the sandbox is automatically resumed and the request is forwarded

Ⅳ. Special notes for reviews

• Async wake: DecodeHeaders returns api.Running when wake is triggered, launching wakeAndContinue in a goroutine. The goroutine uses a detached context (not tied to the Envoy filter lifecycle). On completion, it calls Continue(api.Continue) or SendLocalReply. The Destroy() method cancels the in-flight wake context when Envoy destroys the filter (stream reset). A mutex-protected completion state machine prevents double-reply races.
• Singleflight: Waker.Wake() uses singleflight.Group with DoChan() to coalesce concurrent calls for the same sandbox. The shared Resume runs under a detached context, and callers can bail out via select on their own context.
• handleRefresh: Only dead and empty-state routes are deleted from the registry. All other states (running, paused, creating, available) are retained for full filter visibility.
• The Waker.Wake() retry loop only retries on ErrSandboxIsPausing (transient state). Other errors like ErrSandboxIsTerminating are non-retryable and return immediately.
• The cache optimization (SandboxOnly mode) adds nil guards on GetSandboxController() and GetSandboxSetController() since controller handlers are not set up in that mode.

Ⅴ. Test coverage

Package	Coverage
pkg/sandbox-gateway/filter	81.8%
pkg/sandbox-gateway/wake	95.6%
pkg/servers/e2b	87.7%
pkg/proxy	90.2%

Added tests:

• TestIsEnvoyStreamGonePanic: table-driven test for panic detection (7 cases)
• TestDestroyCancelsContext: verify Destroy cancels in-flight wake context
• TestWakeAndContinueSuccess: verify async wake success path with Continue callback and upstream metadata
• TestWakeSingleflight*: tests for singleflight deduplication
• E2E test annotation lifecycle verification (test_wake_on_traffic.py)

[kruise-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please ask for approval from furykerry by writing /assign @furykerry in a comment. For more information see:The Kubernetes Code Review Process.

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

Details

Needs approval from an approver in each of these files:

• OWNERS

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

[codecov]

Codecov Report

❌ Patch coverage is 71.30802% with 68 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.95%. Comparing base (6c7643a) to head (c6ab485).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
pkg/sandbox-gateway/filter/filter.go	63.35%	36 Missing and 12 partials ⚠️
...g/sandbox-gateway/controller/gateway_controller.go	0.00%	4 Missing ⚠️
pkg/cache/cache.go	40.00%	2 Missing and 1 partial ⚠️
pkg/cache/index.go	25.00%	2 Missing and 1 partial ⚠️
pkg/sandbox-gateway/server/server.go	0.00%	3 Missing ⚠️
pkg/sandbox-gateway/wake/wake.go	94.44%	2 Missing and 1 partial ⚠️
pkg/cache/cachetest/cachetest.go	0.00%	1 Missing ⚠️
...controller/sandboxclaim/sandboxclaim_controller.go	0.00%	1 Missing ⚠️
pkg/sandbox-manager/core.go	0.00%	1 Missing ⚠️
pkg/servers/e2b/routes.go	66.66%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #586      +/-   ##
==========================================
- Coverage   80.04%   79.95%   -0.09%     
==========================================
  Files         229      230       +1     
  Lines       17826    18031     +205     
==========================================
+ Hits        14268    14417     +149     
- Misses       2975     3019      +44     
- Partials      583      595      +12     

Flag	Coverage Δ
unittests	79.95% <71.30%> (-0.09%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.