e2b-code-path-analysis

E2B Code Path Analysis

Overview

This skill turns a single E2B usage scenario (e.g. "create sandbox", "pause sandbox") into a rigorous, written code-path analysis that downstream E2E coverage work can build on directly.

It is an interactive, multi-phase analysis workflow, not a one-shot report generator. You verify the real E2B contract, read the real implementation, expand the scenario space with the user, enumerate every execution path and its trigger conditions, score each path, and only then write the document.

Three principles drive everything:

1. Verify before you reason. Never describe E2B behavior from memory. Fetch the current E2B Python SDK docs via context7 and confirm with the user (see [[feedback_verify_e2b_spec]]).
2. Trust only sandbox-manager. Treat every other component (API Server, scheduler, controllers, gateway, informer cache, kubelet/CSI, cloud infra) — and all user input — as unreliable and adversarial.
3. Confirm the scenario set before analyzing. Path analysis is only as good as the scenario list. Expand broadly, then STOP and get the user to confirm before doing the heavy path enumeration.

When to Use

Trigger when the user:

• Names an E2B usage scenario and wants its code paths analyzed for robustness / risk.
• Wants to plan or prioritize E2E coverage for an E2B-compatible endpoint.
• Asks to assess what could break a sandbox-manager E2B handler under concurrency, bad input, or a degraded cluster.
• Says "分析 E2B 调用路径" / "E2B 代码路径分析" / "E2E 覆盖分析" / "code path analysis".

When NOT to Use

• The user wants the analysis for a non-E2B server (pkg/proxy, pkg/sandbox-gateway, controllers). The trust-boundary framing still helps, but the endpoint→handler map and context7 verification step do not apply.
• The user only wants a quick code read of one handler with no path enumeration / scoring / doc output. Just read it.
• The user wants you to write or run E2E tests. This skill produces the analysis input; it does not write tests. (E2E tests live under test/; never run them. Handler unit tests are the *_test.go siblings — read them as evidence of existing coverage, do not run the full suite.)

Core Principles (hard rules, no exceptions)

Trust Boundary (the mental model)

                 ┌─────────────────────────── TRUSTED ───────────────────────────┐
   user / SDK ──▶ │  sandbox-manager replica (handler logic, in-process state)     │
   (UNTRUSTED)    └───────┬───────────────────────────────────────────────┬───────┘
                          │ everything below is UNTRUSTED                  │
        ┌─────────────────┼──────────────────┬──────────────┬─────────────┼───────────────┐
        ▼                 ▼                  ▼              ▼             ▼               ▼
   API Server        scheduler          controllers      gateway     informer cache   peers/memberlist
   (latency,         (slow/failed       (reconcile lag,  (misroute,  (staleness,      (gossip lag,
   conflict, 5xx)     scheduling)        crash, restart)  replica     read-after-write  split view)
                                                          skew)        gap)
                          ▼
                 other sandbox-manager replicas (NOT in-process shared; only K8s + gossip)

When analyzing a path, for every arrow crossing the boundary ask: what if it is slow / fails / returns stale / returns a conflict / returns a different replica? Each answer is a candidate execution path.

Workflow

E2B scenario (from user)
   │
   ▼
[1] Verify E2B semantics via context7  ──▶ confirm Python API + HTTP endpoint with user
   │
   ▼
[2] Locate implementation              ──▶ routes.go → handler → read handler + deps
   │
   ▼
[3] Brainstorm scenario space          ──▶ 6 dimensions → STOP, confirm scenario list with user
   │
   ▼
[4] Enumerate execution paths          ──▶ single-request / same-replica / cross-replica / side-effects / delayed
   │
   ▼
[5] Score importance + risk            ──▶ per-path Impact level + Risk level + E2E priority
   │
   ▼
[6] Write Markdown doc                 ──▶ default docs/analysis/<scenario>.md

---

Phase 1 — Verify E2B Semantics (context7)

Do this before reading any Go code.

1. Resolve the E2B library: resolve-library-id with libraryName: "E2B" (and try "e2b code interpreter" / the E2B Python SDK if the first match is thin).
2. query-docs for the exact scenario, e.g. "create sandbox", "pause/resume sandbox", "set sandbox timeout", "connect to running sandbox", "create snapshot". Capture:
   • The Python method(s) and their signature / parameters / defaults / which are required.
   • The documented behavior, return shape, and any documented error conditions.
   • The underlying HTTP request the SDK issues (method + path), so you can map to routes.go.
3. If context7 is missing detail, fall back to fetching https://e2b.dev/docs for the relevant page — still do not answer from memory.
4. Present what you found to the user and confirm the scenario, the exact Python API, and the HTTP endpoint before continuing.

Record the context7 library id and the doc source — they go in the output doc's metadata.

Phase 2 — Locate the Implementation

1. Read pkg/servers/e2b/routes.go and find the route whose method+path matches the HTTP request from Phase 1. The route maps to a handler method on *Controller (registered for both the native path and the adapters.CustomPrefix + "/api" path — note both are live).
2. Note the middleware chain. CheckApiKey runs on every sandbox route and, when a {sandboxID} is present, resolves ownership via sc.manager.GetOwnerOfSandbox(sandboxID) — a cross-replica routing concern. API-key routes add CheckCreateAPIKeyPermission / CheckDeleteAPIKeyPermission.
3. Locate the handler implementation by grepping for the method name (e.g. func (sc *Controller) PauseSandbox). See the Quick Reference table for the likely file, but confirm by grep.
4. Read the handler and its key dependencies: the manager/infra calls it makes, models it decodes, adapters it uses, and any shared state it touches. Read the sibling *_test.go to see what is already covered.

Phase 3 — Brainstorm the Scenario Space (interactive)

Expand the single scenario across all of these dimensions. For each, propose concrete cases:

1. Single-endpoint concurrency — same endpoint called N times concurrently, same or different params (e.g. 50 concurrent create; double pause on the same sandbox; resume racing resume).
2. Multi-endpoint concurrency — any combination/order/count across endpoints (e.g. pause racing delete; connect during resume; timeout during pause).
3. Parameter combinations — hostile/boundary/malformed input: missing required fields, oversized values, wrong types, duplicate IDs, unknown template, cross-team IDs, injection-y strings. Never trust the SDK to be the only caller.
4. Cluster/environment variation — distrust every external component: API Server latency/conflict/5xx, thousands of existing sandboxes, slow/failed scheduling, gateway misrouting or replica skew, controller reconcile lag or crash/restart, stale informer cache, node/CSI/cloud faults.
5. Side effects from other endpoints — endpoints not in this scenario that, when called concurrently, change shared state and affect this path (e.g. a DeleteSandbox invalidating an in-flight connect; TTL/timeout expiry firing mid-request; template deletion during create).
6. Delayed / timing sequences — create then immediate connect; connect then idle 5 min then command run; pause then resume after hibernation; request arriving after timeout expiry; read immediately after a write (informer/gossip propagation gap).

Present the expanded list grouped by dimension. STOP and ask the user to confirm, trim, or extend the scenario set. Do not proceed to Phase 4 until the user confirms.

Phase 4 — Enumerate Execution Paths

For each confirmed scenario, walk the handler branch-by-branch. Treat every if / early return / error return / external call outcome as a potential distinct path. Organize paths into five buckets:

4.1 Single-request paths

Every branch a single request can take. For each path record: trigger condition, external deps crossed, result / side effect (status code, CR mutation, in-memory mutation), and recoverability (auto-retry? controller self-heals? manual ops? unrecoverable?).

4.2 Same-replica concurrent paths

Identify in-process shared mutable state: routing/owner tables, expectations (pkg/utils/expectations), caches, per-controller maps, locks. Look for TOCTOU (check-then-act) windows and idempotency gaps. Ask: two concurrent requests on the same replica — does the second corrupt/duplicate/lose the first's effect?

4.3 Cross-replica concurrent paths

Only K8s (and memberlist gossip) is shared; in-process state is not. Ask: requests landing on different replicas — conflicting CR writes (resourceVersion conflict), owner-table divergence, gateway routing to a replica that does not yet know the sandbox, read-after-write across replicas. sandbox-manager is multi-replica; treat split state as the default, not the exception.

4.4 Side-effect paths from other endpoints

Concurrent calls to endpoints outside the scenario that mutate shared state and alter this path's outcome.

4.5 Delayed / timing paths

Paths gated on elapsed time or propagation lag: TTL/timeout expiry, hibernation transitions, informer/gossip read-after-write gaps, stale-cache reads.

Give each path a stable ID (e.g. P1, C2, X3) so scoring and the doc can reference it.

Phase 5 — Score Importance and Risk

Score every path on two orthogonal axes.

Importance (Impact) — consequence severity, adjusted for recoverability

Recoverability rule: if a path self-heals via automatic retry or controller reconcile, drop it one level.

Risk (Fragility) — probability of causing a future production incident

E2E coverage priority matrix

Phase 6 — Write the Markdown Document

Output one document per analyzed scenario. Default directory: docs/analysis/ (create it if absent); honor any directory the user specifies. Suggested filename: e2b-<scenario-slug>.md (e.g. e2b-pause-sandbox.md). Use the Write tool — never sed/cat/redirection.

Document template

# E2B Code Path Analysis: <Scenario>

## Metadata
- Scenario:
- E2B Python API (verified via context7):
- HTTP endpoint / route:
- Handler / implementation file:
- sandbox-manager commit:
- Analyst / date:

## 1. E2B Contract (verified)
- Python call example:
- Parameters (defaults / required):
- Expected behavior & return:
- Documented errors:
- Source (context7 library id / e2b.dev URL):

## 2. Implementation Overview
- Request flow: middleware chain → handler main path
- External components crossed (outside trust boundary):
- Shared mutable state (in-process / cross-replica):

## 3. Confirmed Scenario Set
| # | Scenario | Dimension | Notes |
|---|----------|-----------|-------|

## 4. Execution Paths
### 4.1 Single-request
| Path ID | Trigger condition | Deps crossed | Result / side effect | Recoverability |
|---------|-------------------|--------------|----------------------|----------------|
### 4.2 Same-replica concurrent
### 4.3 Cross-replica concurrent
### 4.4 Side effects from other endpoints
### 4.5 Delayed / timing

## 5. Scoring & Risk
| Path ID | Importance | Risk | Consequence | E2E priority | Rationale |
|---------|-----------|------|-------------|--------------|-----------|

## 6. E2E Coverage Recommendations
- High-priority cases to write:
- Failure-injection points needed (which external dep to perturb):
- Existing coverage (handler *_test.go / under test/):
- Coverage gaps:

## 7. Open Questions / Follow-ups

After writing, summarize the highest-priority paths to the user and point to the file.

---

Quick Reference: E2B endpoint → handler map

Verified from routes.go at time of writing. Re-read routes.go and grep the handler to confirm; the file column is a hint, not authority (handlers have moved between files in recent refactors).

Every route is registered twice (native + <CustomPrefix>/api prefix). API-key routes only register when sc.keyCfg != nil.

Red Flags — STOP if you catch yourself doing these

• "I know how E2B create behaves" → No. Verify via context7 first (rule 1).
• "I'll just analyze the obvious happy path" → No. Enumerate every branch + the 5 concurrency/timing buckets.
• "sandbox-manager is single-replica, skip cross-replica" → No. It is multi-replica; cross-replica is required.
• "The gateway/scheduler/API Server will behave correctly" → No. Everything outside sandbox-manager is untrusted.
• "The SDK validates input, so params are safe" → No. Distrust all input; the SDK is not the only caller.
• "I'll jump straight to writing paths" → No. Confirm the scenario set with the user first (rule 4).
• "I'll score later / leave a few paths unscored" → No. Every path gets Importance + Risk.

Common Mistakes

• Reasoning about E2B from memory instead of context7 → wrong contract, wrong endpoint mapping.
• Trusting the snapshot route table instead of re-reading routes.go → analyzing a moved/renamed handler.
• Only analyzing single-request paths → missing the concurrency and timing bugs E2E most needs to catch.
• Treating external components as reliable → missing exactly the env/ops-driven incidents that hit production.
• Skipping user confirmation of the scenario set → analyzing the wrong scenarios, wasted depth.
• Importance without recoverability adjustment → over-rating retryable paths.
• Conflating Importance and Risk → they are orthogonal; a P1 path can be Low risk and vice versa.
• Running E2E tests or the full unit suite → read tests as evidence; never run test/, keep unit scope tight.
• Compound Bash (&& / > / xargs) or sed -i → see global CLAUDE.md Bash rules; use Write/Edit and split calls.