Skip to content

refactor(rocm): split service_launch.rs into a directory of child modules to get under the module-size limit - #966

Merged
jussielo-amd merged 9 commits into
mainfrom
split-service-launch-module
Nov 9, 2026
Merged

jussielo-amd merged 9 commits into
mainfrom
split-service-launch-module

Conversation

@jussielo-amd

@jussielo-amd jussielo-amd commented Nov 9, 2026 •

Copy link
Copy Markdown
Collaborator

Closes ROCMAI-918.

cargo xtask check-module-size reports apps/rocm/src/service_launch.rs at 2,172 production lines, 672 over the 1,500-line limit, and the file also carried a test module of about 2,750 lines. This change splits it into a service_launch/ directory so that every file is well under the limit. The limit, the counting rules and the gate are untouched.

The seams are the ones the code already had. service_launch.rs now only declares the children and re-exports with pub(crate) use the items other modules call, so serve_cmd.rs, automations.rs, service_control.rs and tool_policy.rs keep their imports unchanged. An item that sibling children share is pub(super) and reached through super::<child>; everything else keeps the visibility it had. Each test moved with the code it covers; the two fixtures that more than one child's tests use live in a test-only test_support module.

File Holds Production lines before Production lines after
service_launch.rs module doc, mod declarations, re-exports 2,172 77
service_launch/endpoint_auth.rs bind-host validation, endpoint API key policy, respawn key guard 169
service_launch/launch_transaction.rs locked port allocation decision, failed-launch cleanup, reuse refusals and the no-usable-GPU wording 295
service_launch/spawn.rs process and stdio plumbing, ManagedLaunchReport, ManagedSpawn, spawn_managed_engine_child, launch_managed_engine_child_locked 561
service_launch/readiness.rs readiness wait, liveness of the tracked process, how a wait ends, the OOM fault-injection seam 345
service_launch/start.rs start_managed_service and the plain output 252
service_launch/helper_autostart.rs starting the background automation helper and its autostart claim 225
service_launch/attach.rs the attached run and its log streaming 431

The after column is the file's own production lines as the gate counts them, so it includes each file's licence header, module doc and imports; the sum is higher than 2,172 for that reason. The largest file with its tests included is spawn.rs at 1,304 lines, so no test file or production file is near the limit. check-module-size now checks 407 files and lists none over.

This is a pure move, and it was checked two ways. First, a script compared the multiset of non-blank source lines of the old file with the union of the new files: the lines that differ are only use/mod lines and re-exports, pub(super) added in front of the 13 production items and the test-only thread-local that siblings share and the two shared test fixtures, #[cfg(...)] gates on the new imports, the new module docs and licence headers, four intra-doc link targets that now need a path, a handful of std::fs:: and similar full paths in readiness.rs where an import would have needed a gate, and the ignored helper test that three cleanup tests re-run the test binary as. That helper used to be spelled out as the string service_launch::tests::managed_launch_cleanup_sleeper_child at each of the three --exact call sites. It now lives in the test-only test_support module with one new test-only function, sleeper_test_name, which reads the name off the helper function itself and asserts it against the module path, so renaming or moving the helper changes the name with it and fails loudly if the function is not updated. Second, a token-level comparison of the old and new sources, ignoring whitespace, comments, use statements and trailing commas, shows only those same differences plus the mod, #[cfg(test)] and pub(...) tokens they imply. The set of 71 tests under service_launch is the same before and after by name (70 pass, 1 #[ignore]d sleeper helper).

The cfg gating of every moved item is unchanged. Imports that were unconditional in the single file but are used only under a gate in their new home (process_is_running and thread on Windows in spawn.rs and start.rs, std::io off Windows, the e2e-oom-fault-injection imports in readiness.rs) carry that gate. In readiness.rs, where the use sites of std::fs and two test imports follow three different gates, the imports are replaced by full paths at the use sites, so no gate has to be kept in step with them. The Windows code paths could not be built here because the cross C build of a dependency does not run on this host; instead the crate was checked with --cfg windows passed to rustc for the rocm crate alone, with target_os = "linux" and cfg(unix) rewritten out of the service_launch files so the non-Linux branches are taken, in check and test profiles with the OOM feature on and off. That type-checks the Windows branches and the unused-import lint, finds no unused import in service_launch/, and the only errors it reports elsewhere are the ones that cannot be avoided without the Windows build of rocm-core. It cannot run the dead-code lint, so that one is left to Windows CI.

docs/architecture.md describes the new layout: the service_launch.rs entry is rewritten and each child has its own entry. The background_helper.rs and shared-type notes that pointed at service_launch.rs now point at the child that owns the item, and a handful of comments (four of them in model_serving.feature) and docs/testing.md that named moved functions name their new file. The launch_transaction.rs entry says it owns types, with the visibility of ManagedPortDecision and ManagedReuseRefusal spelled out. No Phase labels were added.

Commands run, all with a fresh target directory of their own: cargo xtask check-module-size (it reported service_launch.rs at 2,172 on origin/main before the change and reports none over the limit after), cargo fmt --all -- --check, cargo clippy --locked -p rocm --all-targets -- -D warnings (also with --features e2e-oom-fault-injection,e2e-test-hooks), cargo test -q --locked -p rocm service_launch and a full cargo test -q --locked -p rocm (1,686 passed, 9 ignored, none failed), cargo xtask check-architecture-doc, cargo xtask check-crate-edges, and lychee --offline over the two edited docs.

No scenario is added because this is an internal refactor with no observable behaviour change. The existing scenarios that exercise the moved launch path still pass against debug binaries built with rocm/e2e-test-hooks and rocm/e2e-oom-fault-injection: serve-41 (serve-oom-launch-memory-guidance, the OOM seam and the plain summary path), serve-42 (serve-wsl-refusal-names-the-wsl-driver-status, the no-usable-GPU refusal), serve-43 (serve-wait-conflicts-with-attached-modes), networking-03 (networking-public-bind-requires-opt-in, bind-host validation), service-cleanup-07 (service-cleanup-prune-waits-for-a-launch-to-publish, the launch lock) and automations-04 (automations-autostart-defers-during-spawn-window, the autostart claim). The @requires-gpu scenarios that start a real engine (for example serve-30, serve-31 and serve-40) run only on the self-hosted lane and were not run here.

Open pull requests that edit service_launch.rs at the time of writing will need to merge main after this lands, because their hunks now belong in the child files: #960, #859, #854, #817, #724, #723, #709, #437, #299 and #202.

…ules

service_launch.rs held 2,172 production lines, over the 1,500-line limit that cargo xtask check-module-size enforces, plus a test module of about 2,750 lines.

Move the code into service_launch/ along its seams: endpoint_auth (bind-host validation and the endpoint API key policy), launch_transaction (the locked port allocation decision, failed-launch cleanup and the reuse refusals), spawn (the detached engine child, its process and stdio plumbing, ManagedLaunchReport), readiness (waiting on a service and the OOM fault-injection seam), start (the background launch path and its plain output), helper_autostart (starting the background automation helper) and attach (the attached run and its log streaming). service_launch.rs now only declares the children and re-exports, with pub(crate) use, the items other modules call, so no caller changes. Items that siblings share are pub(super); everything else keeps the visibility it had. Each test moves with the code it covers, and the fixtures two or more children share go to a test-only test_support module.

This is a pure move: the code is unchanged apart from visibility keywords, use and mod lines, the cfg gates those imports need so that each platform and feature combination still compiles without unused imports, four intra-doc link targets, and the module path in the three places the cleanup tests re-run themselves by test name. docs/architecture.md describes the new layout, and comments and docs that pointed at moved functions now name the file they live in.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
@jussielo-amd
jussielo-amd marked this pull request as ready for review November 9, 2026 09:20
@jussielo-amd
jussielo-amd requested a review from a team as a code owner November 9, 2026 09:20
@jussielo-amd
jussielo-amd requested review from fredespi and a balanced review from Copilot November 9, 2026 09:20

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Ungated imports in readiness.rs become unused on Windows, causing the build and Clippy CI checks to fail under warnings-as-errors.

2 open issues
What changed in this PR

This PR splits managed-service launch code into focused child modules to meet the module-size limit while preserving caller imports and existing behavior.

Changes:

  • Separates authentication, launch transactions, spawning, readiness, helper autostart, and attached execution.
  • Moves existing tests alongside their implementations and shares common fixtures.
  • Updates architecture documentation and comments to reflect the new locations.
File Description
tests/​e2e-cucumber/​tests/​e2e/​serving_steps.rs Updates the OOM helper location in a comment.
tests/​e2e-cucumber/​tests/​e2e/​automations_steps.rs Updates the autostart constant location in a comment.
docs/​testing.md Updates the reuse-test location.
docs/​architecture.md Documents child-module responsibilities and visibility.
apps/​rocmd/​src/​watchers/​server_recover.rs Updates a cleanup-test reference in a comment.
apps/​rocmd/​src/​supervise.rs Updates a port-lease test reference in a comment.
apps/​rocm/​src/​test_support.rs Updates the helper-test location in documentation.
apps/​rocm/​src/​storage.rs Updates the launch-site location in a comment.
apps/​rocm/​src/​service_records.rs Updates spawn locations in cleanup comments.
apps/​rocm/​src/​service_launch/​test_support.rs Holds shared launch-test fixtures.
apps/​rocm/​src/​service_launch/​start.rs Holds background launch orchestration, plain output, and tests.
apps/​rocm/​src/​service_launch/​readiness.rs Holds readiness waits, liveness checks, OOM simulation, and tests.
apps/​rocm/​src/​service_launch/​launch_transaction.rs Holds port allocation, failed-launch cleanup, reuse checks, and tests.
apps/​rocm/​src/​service_launch/​helper_autostart.rs Holds helper startup, concurrency claims, and tests.
apps/​rocm/​src/​service_launch/​endpoint_auth.rs Holds bind validation, endpoint-key policy, and tests.
apps/​rocm/​src/​service_launch/​attach.rs Holds attached execution, log streaming, stop handling, and tests.
apps/​rocm/​src/​serve_port.rs Updates a port-reuse test reference in a comment.
apps/​rocm/​src/​serve_cmd.rs Updates the plain-output location in a comment.
apps/​rocm/​src/​endpoint_keys.rs Updates the authentication helper location in documentation.
apps/​rocm/​Cargo.toml Updates the OOM feature comment; configuration is unchanged.

Review effort: Balanced

Comment thread apps/rocm/src/service_launch/attach.rs Dismissed
Comment thread apps/rocm/src/service_launch/start.rs Dismissed
Comment thread apps/rocm/src/service_launch/start.rs Dismissed
Comment thread apps/rocm/src/service_launch/start.rs Dismissed
Comment thread apps/rocm/src/service_launch/start.rs Dismissed
…indows

Splitting service_launch.rs gave readiness.rs its own import list, and three of its imports are used only under a platform or feature gate, so they were unused on a Windows build and failed under -D warnings. The single file had hidden this because other code in it used the same names.

In readiness.rs, gate std::fs on any(target_os = "linux", feature = "e2e-oom-fault-injection", test): the zombie probe and the OOM simulation use it in production, and the tests use it on every platform. Gate the two imports of the unreaped-child test, rocm_core::process_is_running and std::thread, on target_os = "linux", like the test itself.

Every other import in the endpoint_auth, launch_transaction, spawn, start, helper_autostart and attach children and in the test_support module was checked against the same combinations (Windows and non-Windows, Linux and non-Linux, test on and off, e2e-oom-fault-injection on and off) and needs no change. Only imports and cfg gates change.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the managed-service launch module refactor.

No open issues 🎉

2 resolved since last review

Review effort: Balanced

@juhovainio juhovainio left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. I checked this as a pure move: comparing the lines removed from service_launch.rs with those added across the new files, the only differences are use/mod/re-exports, pub(super) on the shared items, #[cfg] gates on the new imports, licence headers and module docs, a few intra-doc link rewrites, and the sleeper-test --exact path strings. CI is green (including both Windows lanes), and every new production file has an architecture.md entry. I did not build or run the tests locally.

Non-blocking, take or leave:

  • The three --exact sleeper-test path strings will silently stop matching if the module is renamed. A shared const would tie them together.
  • The fs import gate in readiness.rs is a hand-derived union of use sites, so it is easy to drift when code moves again.
  • A few of the rewritten intra-doc link lines now run past 100 columns.
  • The CodeQL "cleartext api_key" alerts on attach.rs and start.rs are the existing one-time client-config print, flagged as new only because the code moved. They look safe to dismiss.
  • The ~10 other open PRs touching this area will need to merge main after this lands.

… columns

The pointers the split rewrote to name the new files, and the intra-doc links it added in spawn.rs and start.rs, ran past 100 columns. Rewrap them without changing a word. Comment lines the split only moved are left as they were, so that a move stays a move.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
… it three times

Three cleanup tests re-run the test binary with --exact and the module path of an ignored helper test, spelled out as a string each time. Renaming or moving the module would leave all three naming a test that no longer exists, and --exact selects nothing without saying so.

Move the helper to the test-only test_support module next to the fixtures the tests already share, and give it sleeper_test_name, which reads the name off the helper function itself with type_name_of_val and drops the crate segment libtest leaves out. The function also asserts that the result matches the module path plus the function name and that it starts with service_launch::, so a helper that moves or is renamed without that function being updated fails loudly in the tests that use it.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
The import was gated on a hand-derived union of its use sites (the Linux zombie probe, the OOM simulation and the tests), which drifts as soon as a use site changes. Name std::fs by its full path at the three production uses, give the tests module its own unconditional use std::fs, and do the same for the two Linux-only imports of the unreaped-child test (rocm_core::process_is_running and std::thread), which become full paths at their single use. No gate is left to keep in step, and no import is unused in any platform, test or feature combination.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human judgment is needed to weigh an unpublished documentation-citation concern that could allow stale source references to escape link validation.

No open issues 🎉

Review effort: Balanced

@nowycondro nowycondro left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Automated review · review-code · head 0ab94842f93c

Review — no blocking findings

Full review of the whole change (22 files, +5219/-4921).
Implements ROCMAI-918 in full: splits apps/rocm/src/service_launch.rs (2,172 production lines, over the project's 1,500-line module-size limit) into a service_launch/ directory of 8 child files, as a pure code move with no behaviour change. All of that ticket's acceptance criteria (module-size gate clean, tests move unchanged, docs/architecture.md updated, no change to the xtask gate itself) are satisfied by what the diff actually contains.

Blocking

None

Non-blocking

None

Decisions for the author

  • readiness.rs's fs/process_is_running/thread gating is correct today but is a hand-maintained invariant — non-blocking-improvement
    Because the production and test use sites of these items sit under three different cfg combinations (unconditional production use, #[cfg(target_os = "linux")] test use, #[cfg(feature = "e2e-oom-fault-injection")]), the file drops the imports entirely and spells the full path (std::fs::read_to_string, rocm_core::process_is_running, std::thread::sleep) at each call site instead of a single gated use. Verified correct for every current call site and every current platform/feature combination. The next contributor who adds a new call site or a new gate combination in this file has no compiler nudge telling them to keep using the full path rather than reintroducing a use that is unconditional but only used under one gate — a short comment at the top of the file noting why there's no use std::fs/process_is_running/thread would reduce that risk.

Positive signals

  • The PR's own "pure move" verification (a multiset line comparison plus a token-level diff ignoring whitespace/comments/use/commas) is not just asserted — it held up under three independent blind re-derivations of the same claim, one per file group, each walking every moved function/struct/test against its pre-move form in the deleted service_launch.rs and finding byte-for-byte logical identity outside the documented exceptions.
  • The two Windows-only cfg-gating defects an earlier automated review round flagged in readiness.rs (an fs import and two test imports that would go unused on Windows) were independently re-verified fixed by direct inspection of head, not inferred from the "resolved" label or from green CI alone: there is no lingering unconditional use std::fs/use rocm_core::process_is_running/use std::thread anywhere in the file, and every reference to those items goes through a full inline path gated no more broadly than its use.
  • pub(super)/pub(crate)/private visibility on every item that moved was checked against actual cross-module and cross-crate call sites (via repo-wide grep for service_launch::), and in every case matches exactly what a sibling child module or an external caller (serve_cmd.rs, automations.rs, service_control.rs, tool_policy.rs) needs — nothing was widened beyond its actual consumers.
  • The CodeQL "cleartext api_key" alerts on attach.rs/start.rs were independently traced to their print sites rather than taken on trust: both are byte-identical to the pre-move code, including the codeql[rust/cleartext-logging] suppression comment and the guarding condition, so the move does not make the (pre-existing, accepted) print reachable in any new situation.

Deployment notes

No migration or behaviour change for any consumer; this is an internal module layout change only. As the PR itself notes, roughly ten other open PRs that edit service_launch.rs will need to rebase onto this once it merges, since their hunks now belong in the new child files.

What this covered

Every file in the diff, in full, against 3dc4a31a (base) → 0ab94842 (head): the three code-review passes each read their assigned service_launch/ child files completely at head and cross-diffed every production and test item against its pre-move counterpart in the deleted apps/rocm/src/service_launch.rs at base; the remaining 13 peripheral files (doc/comment path updates in callers, docs/architecture.md, docs/testing.md, two e2e step-comment files, Cargo.toml) were read directly and are comment/doc-only. CI at this head is reported green across all 31 checks, including both Windows lanes (build/test and release build), clippy -D warnings, CodeQL, and the Markdown-link checker.

Did not run as separate passes: history (git log/blame) and prior-PR-comment review were not run as dedicated passes beyond what the code passes surfaced in context; given this is a pure, independently-reverified move with green CI, a dedicated history pass was judged unlikely to surface anything the logic-fidelity diff would have missed. Design review (Step 7) was done directly rather than via further sub-agent fan-out, given the consistent clean signal from three independent code passes; it produced only the one forward-looking observation above, no fundamental approach concern. Not reconciled against this PR's own review discussion thread (its automated reviews and the one human approval were read only for the mandatory prior-review/duplicate check, not used to shape or bias the findings above, and nothing from them was carried into this report beyond what this review independently re-derived from the code and from live CI/ticket state).


Not a human review. This is an automated code review; please verify findings independently before acting on them.

@nowycondro nowycondro left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Automated review · review-code · head 0ab94842f93

Outcome: no blocking findings. This is a well-executed mechanical refactor.

I independently verified the "pure move" claim: comparing a normalized line-multiset of the original 4,934-line service_launch.rs against the union of the eight new files (ignoring use/mod/visibility-keyword/cfg-attribute lines) turned up only the differences the PR describes — three --exact test-path literals replaced by the new sleeper_test_name() derivation, a few std::fs::/std::thread::/rocm_core:: full-path substitutions for imports that would otherwise need a 3-way cfg union in readiness.rs, and reformatted multi-line use blocks. No production logic, condition, error message, or statement ordering changed. CI is green across all 31 checks at this head, including both Windows build lanes, clippy, CodeQL, and the link checker. Six independent passes (per-module-group code review ×3, docs/ripple pass, agent-instruction + code-comment compliance, history + prior-review context) corroborate this.

Non-blocking (cleanup, author's call):

  • Three doc comments carried over spatial wording ("above"/"below") that was true in the single file but is now false since the referenced code moved to a sibling file: service_launch/launch_transaction.rs (no_usable_gpu_refusal, "the spawn below" → now in spawn.rs), service_launch/attach.rs (run_attached_service, "print_managed_launch_plain above" → now in start.rs), service_launch/test_support.rs:14 ("each test below" → consumers now live in launch_transaction.rs/readiness.rs). Elsewhere this PR correctly switched to qualified doc-links (e.g. [`x`](super::x)) for the same situation; these three were missed.
  • docs/architecture.md: the launch_transaction.rs entry is labelled as owning "private types", but its two types (ManagedPortDecision, ManagedReuseRefusal) are pub(super)/pub(crate), not private; the general "mechanical relocation" exceptions paragraph also doesn't list ManagedReuseRefusal among them.
  • tests/e2e-cucumber/features/model_serving.feature (not touched by this PR) still has four comments naming service_launch.rs for functions that actually moved to spawn.rs, endpoint_auth.rs, readiness.rs, and launch_transaction.rs respectively — the same class of comment-location fix this PR applied carefully everywhere else, missed in this one file.

What this covered: Full review of the whole diff (base 3dc4a31a…head 0ab94842), every changed file read completely plus the pre-split original and all sibling modules for cross-reference; six independent fan-out passes; CI status read directly from GitHub rather than assumed. Implements the module-split already referenced in the PR's own title/description (ROCMAI-918) — matches its stated scope (pure move, tests relocated unchanged, docs/architecture.md updated), with nothing claimed that the diff doesn't contain.

Not a human review. This is an automated code review; please verify findings independently before acting on them.

A few doc comments still said "above", "below" or "this file" about code that now lives in a sibling child module. Point them at the right place instead: a qualified link to spawn_managed_engine_child from the no-usable-GPU refusal, the start.rs location of print_managed_launch_plain from the attach.rs comment, "each test that uses it" for the reusable_record fixture, the service_launch module instead of this module for the stop-path import note, and "what was then a single file" in the parent module doc.

Also say at the top of readiness.rs why it has no use for std::fs, std::thread or rocm_core::process_is_running: their use sites sit under different cfg combinations, so the full paths stay and no gate has to be kept in step with them.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
The launch_transaction.rs entry said it owns private types, but ManagedPortDecision is pub(super) and ManagedReuseRefusal is pub(crate). Say it owns types, give ManagedReuseRefusal's visibility and the reason for it (the pub(crate) function that returns it), and list it in the general paragraph on the visibility of the types in the service_launch children.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
Four comments in model_serving.feature named service_launch.rs for functions that now live in spawn.rs, endpoint_auth.rs, readiness.rs and launch_transaction.rs. Name the file each one lives in.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The source-file citation in docs/testing.md must use a relative Markdown link as required by AGENTS.md so link checkers can detect broken references.

1 open issue

Review effort: Balanced

Comment thread docs/testing.md Resolved
The citation of the launch_transaction.rs tests in docs/testing.md, and the mentions of service_launch.rs, start.rs and main.rs in the service_launch entries of docs/architecture.md that the split added or rewrote, were code-formatted paths that lychee and the docs-links job cannot check. Make them relative Markdown links, as AGENTS.md asks. Citations the split did not add or rewrite are untouched.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the managed-service launch module reorganization.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

@jussielo-amd
jussielo-amd added this pull request to the merge queue Nov 9, 2026
Merged via the queue into main with commit b2d86a1 Nov 9, 2026
32 checks passed
@jussielo-amd
jussielo-amd deleted the split-service-launch-module branch November 9, 2026 20:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants