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 calls Waker.Wake() to resume it. Returns 503 if wake fails, 502 if not wakeable. Per-request diagnostic logs (Wake eligibility check) are at Debug level to reduce noise.
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).
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. buildWakeAnnotations defers map allocation until annotations are actually needed.
4. Atomic annotation writes (pkg/sandbox-manager/infra/sandboxcr/sandbox.go): Wake annotations are passed via ResumeOptions.Annotations and written atomically in Resume's retryUpdate, reducing API server writes. updateConnectTimeout only handles timeout with ExtendOnly policy.
5. 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.
6. 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. Replaces strings.Contains() in wake.go with proper errors.Is().
7. 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. Adds NewCacheOptions.SandboxOnly, BuildGatewayCacheConfig(), and SetupSandboxCacheControllersWithManager().
8. 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

• Atomic annotation writes: Wake annotations are now passed via ResumeOptions.Annotations and written atomically in Resume's retryUpdate. updateConnectTimeout no longer accepts annotations — it only handles timeout with ExtendOnly policy. This reduces the number of API server writes from 3 to 1-2 in the ConnectSandbox (paused) path.
• Sentinel errors: IsSandboxResumable now returns (bool, error) instead of (bool, string). Callers use errors.Is() for classification. The managererrors.Error type gains Unwrap() to support errors.Is() through NewErrorWrap.
• 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.
• The E2B Pause() now uses spec patch (Spec.DesiredState=Paused) instead of deleting the sandbox, which is required for the wake-on-traffic feature.
• Log levels: Per-request diagnostic logs ("Wake eligibility check", "skip resetting timeout for never-timeout sandbox") are at Debug level (.V(utils.DebugLogLevel)) to reduce noise in production.

---

Appendix: Incidental Changes

• hack/run-e2b-e2e-test.sh: Added wake-on-traffic test to the E2B test suite
• pkg/proxy/routes.go: Minor route handling adjustments
• pkg/utils/proxyutils/route.go: Added HasWakeAnnotation helper

[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 67.85714% with 72 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.66%. Comparing base (bfa04b5) to head (eacd10c).
⚠️ Report is 4 commits behind head on master.

Files with missing lines	Patch %	Lines
pkg/cache/cache.go	45.45%	6 Missing and 6 partials ⚠️
pkg/sandbox-manager/infra/sandboxcr/sandbox.go	50.00%	10 Missing and 2 partials ⚠️
pkg/sandbox-gateway/filter/filter.go	78.00%	10 Missing and 1 partial ⚠️
...g/sandbox-gateway/controller/gateway_controller.go	0.00%	10 Missing ⚠️
pkg/sandbox-gateway/wake/wake.go	76.74%	9 Missing and 1 partial ⚠️
pkg/sandbox-manager/errors/error.go	0.00%	6 Missing ⚠️
pkg/cache/index.go	20.00%	3 Missing and 1 partial ⚠️
pkg/sandbox-gateway/server/server.go	66.66%	3 Missing ⚠️
pkg/cache/controllers/cache_controllers.go	0.00%	2 Missing ⚠️
pkg/cache/tasks.go	0.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #586      +/-   ##
==========================================
- Coverage   79.82%   79.66%   -0.16%     
==========================================
  Files         202      203       +1     
  Lines       14791    14971     +180     
==========================================
+ Hits        11807    11927     +120     
- Misses       2553     2608      +55     
- Partials      431      436       +5     

Flag	Coverage Δ
unittests	79.66% <67.85%> (-0.16%)	⬇️

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.