[ac-pplx]

Summary

crates/libs/internal/api/server/src/data_plane_sessions.rs (1,780 code lines) serves five unrelated ClusterApi RPC families. All of them are called only from adapter.rs:

• data-plane session route resolution;
• process binding and reconnects;
• session and org revocation;
• sandbox runtime access;
• the ECW sandbox service route, with its reset and credential checks.

This moves each family, and the route-row and route-token helpers they share, into its own module. data_plane_sessions.rs drops to 111 code lines; the largest new file is service_route.rs at 388.

This is a pure move, generated by scripts/split_rust_module.py (#562) from the spec below and proved by its verify. It is part of splitting the largest production modules into smaller ones with one job each.

What moved where

Module	Holds	Code lines
session_route	Resolving a data-plane session's route, its transport and route token, and checking ingress and attach authorization.	369
route_rows	Reads and writes of the stored route rows, and the backend endpoint a route resolves to.	232
route_token	Minting the Space API route token a resolved route carries.	58
service_route	The ECW sandbox service route: resolution, its token, and waiting for the sandbox to be command-ready.	388
service_route_reset	Resetting an ECW sandbox service route and enqueueing the desired-state reconcile it needs.	172
ecw_authorization	Authorizing an ECW sandbox service route request against the org's API keys and ECW credentials.	112
process_binding	Binding a session to its process and recording reconnects.	174
revocation	Session and org revocation state.	117
runtime_access	Whether a sandbox's runtime may be accessed now, and the retry advice when it may not.	88
data_plane_sessions.rs (parent)	the shared backend-transport constant, the request-field helpers (required, optional), and the ingress activation helpers session_route and service_route share	111

How to check it

The spec (item names, not lines):

file = "crates/libs/internal/api/server/src/data_plane_sessions.rs"

[[module]]
name = "session_route"
doc = "Resolving a data-plane session's route, its transport and route token, and checking ingress and attach authorization."
items = [
  "struct SessionRouteRow", "fn resolve_session_route", "fn data_plane_session_transport",
  "fn space_api_route_token_for_session", "fn validate_ingress_session", "fn validate_ingress_session_access",
  "fn validate_attach_authorization",
]

[[module]]
name = "route_rows"
doc = "Reads and writes of the stored route rows, and the backend endpoint a route resolves to."
items = [
  "const DEFAULT_NODE_API_PORT", "fn fetch_route_row", "fn update_route_row", "fn node_api_backend_endpoint", "fn resolve_backend_endpoint",
  "fn missing_backend_endpoint_message", "fn fetch_sandbox_service_route_row",
  "fn resolve_sandbox_service_backend_endpoint",
]

[[module]]
name = "route_token"
doc = "Minting the Space API route token a resolved route carries."
items = ["struct SpaceApiRouteTokenParams", "fn space_api_route_token", "fn required_route_generation"]

[[module]]
name = "service_route"
doc = "The ECW sandbox service route: resolution, its token, and waiting for the sandbox to be command-ready."
items = [
  "const SANDBOX_SERVICE_ROUTE_COMMAND_READY_*", "struct SandboxServiceRouteRow",
  "fn unstable_resolve_sandbox_service_route",
  "fn space_api_route_token_for_sandbox_service_route", "fn ensure_sandbox_service_route_command_ready",
  "fn sandbox_service_route_command_ready_status", "fn clear_sandbox_command_ready_pending",
  "fn sandbox_lifecycle_is_started", "fn sandbox_service_route_port", "fn sandbox_service_route_kind",
  "fn sandbox_service_route_transport",
]

[[module]]
name = "service_route_reset"
doc = "Resetting an ECW sandbox service route and enqueueing the desired-state reconcile it needs."
items = [
  "const RESET_ROUTE_DIAGNOSTIC_MAX_CHARS", "struct UnstableResetSandboxServiceRouteRow",
  "fn reset_sandbox_service_route", "fn sandbox_service_route_key_kind",
  "fn enqueue_sandbox_desired_state_reconcile_tx", "fn route_generation_from_wire",
  "fn bounded_reset_route_diagnostic",
]

[[module]]
name = "ecw_authorization"
doc = "Authorizing an ECW sandbox service route request against the org's API keys and ECW credentials."
items = [
  "fn validate_unstable_sandbox_service_route_authorization", "fn credential_proof_sha256",
  "fn api_key_belongs_to_org", "fn token_matches_ecw_credential",
]

[[module]]
name = "process_binding"
doc = "Binding a session to its process and recording reconnects."
items = [
  "struct BoundProcessRow", "struct ExistingProcessBindingRow", "struct ReconnectRow",
  "fn bind_session_process", "fn record_session_reconnect", "fn reconnect_reason",
  "fn reconnect_reason_from_storage", "trait DataPlaneReconnectReasonExt",
  "impl DataPlaneReconnectReasonExt for DataPlaneReconnectReason",
]

[[module]]
name = "revocation"
doc = "Session and org revocation state."
items = [
  "struct RevocationRow", "struct OrgRevocationEpochRow", "fn revocation_state_for_session",
  "fn org_revocation_epoch", "fn revocation_state", "fn revocation_status", "fn i64_to_u64", "fn timestamp",
]

[[module]]
name = "runtime_access"
doc = "Whether a sandbox's runtime may be accessed now, and the retry advice when it may not."
items = [
  "const SANDBOX_RUNTIME_CONVERGENCE_RETRY_AFTER_MS", "const POST_WAKE_LISTENER_REBIND_GRACE_SECS",
  "struct SandboxRuntimeAccessRow", "fn sandbox_runtime_access", "fn fetch_sandbox_runtime_access_row",
  "fn sandbox_runtime_access_from_row", "fn sandbox_runtime_access_decision",
]

The tool is scripts/split_rust_module.py from #562 (not on main yet).

• Regenerate: on main at b9fc395e0, run split_rust_module.py apply spec.toml && cargo fmt --all. This reproduces the first commit.
• Proof: split_rust_module.py verify origin/main → regenerated and compared 10 files from 1 split parents: identical. verify derives the spec from the diff, regenerates the split from the merge base, and requires HEAD's Rust files to equal the rustfmt'd result byte for byte.
• Edits inside moved text: 132 private items, fields or methods → pub(super); 8 pub(super) → pub(crate). Each keeps the reach the item had: one module deeper, pub(super) reaches exactly the old module.

Observable changes

• Log targets: none change; no moved event or span lacks an explicit target:.

• sql! locators: the leading /*module:line*/ comments of 12 moved statements now name the new module path.

• archcheck direct_tables ratchet: all 7 lines that read a Direct-only table move to data_plane_sessions/route_rows.rs. A separate commit re-keys that baseline entry with the same cap, 7. Archcheck reports the re-keyed entry as an advisory no_new_entries finding for a reviewer to accept, as the rule intends for a moved entry.

• Comment: networkpolicy.yaml cited node_api_backend_endpoint in data_plane_sessions.rs; a docs commit points it at data_plane_sessions/route_rows.rs.

• Diagnostics name new locations:

  • panic and backtrace locations of the 2 panic sites (expect, unwrap, unreachable!, asserts) in moved code name the new file and line;
  • std::any::type_name of a moved type names its new module;

  The reviews found nothing in the repository that depends on these.

Validation

Run on a Linux development machine at the PR head:

• cargo check --workspace --all-targets --all-features --locked: pass, no warnings.
• Every clippy invocation in run_clippy_checks with -D warnings: pass.
• cargo check -p pplx-space-internal-api-server --no-default-features --all-targets: pass.
• cargo nextest run -p pplx-space-internal-api-server --all-features with Postgres and SPACE_CI_REQUIRE_TEST_DEPS=1: 332/332 passed, none skipped.
• archcheck as CI runs it: no required findings. Compared with main, there are two new advisory findings: the stale file_size entry below, and the re-keyed direct_tables entry above.

Interactions

No open pull request touches data_plane_sessions.rs.

Follow-ups, kept out of this PR because verify allows no other Rust edits: imports in data_plane_sessions.rs that only the child modules use could move to them.

The archcheck file_size baseline entry for this file is now stale (an advisory finding). Split PRs leave that table alone, so they don't conflict with each other there; one follow-up prunes the stale entries after they land.

Rollback

Revert the commit(s). No data, configuration, wire or public API change.

🤖 Generated with Claude Code

[the-gigi-pplx]

Review

No findings.

Verified against 978be44d3eb3791a995a5493cec97064c79910c4.

What I ran:

• scripts/split_rust_module.py verify origin/main, using the script from PR scripts: add split_rust_module.py for mechanical, verifiable Rust module splits #562's head: identical, exit 0.
• apply with the spec in this PR's body, run on the merge base and rustfmt'd: it reproduces every .rs file at the head byte for byte. So the glob patterns in the published spec select the same items as the expanded spec verify --print-spec derives.
• Each moved child file, grepped for self::/super:: in doc comments. The tool doesn't rewrite comments, so a link like that would point one module off after the move. There are none.
• The non-split files, grepped for comments that name the old file next to a moved item.
• Whether main has touched the split file since the merge base: it hasn't.

The non-Rust edits check out: node_api_backend_endpoint is at data_plane_sessions/route_rows.rs:148, and archcheck passes in CI with the re-keyed direct_tables entry.

What I didn't check: whether the grouping is the right one. That's a design call, and I took the body's word for it. I also didn't rebuild or retest the crate; CI is green on this head.

[the-gigi-pplx]

Approved. No findings; details in the review comment above.