Repository navigation
refactor(rocm): split service_launch.rs into a directory of child modules to get under the module-size limit - #966
Conversation
…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>
There was a problem hiding this comment.
🟡 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
…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>
juhovainio
left a comment
There was a problem hiding this comment.
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
--exactsleeper-test path strings will silently stop matching if the module is renamed. A shared const would tie them together. - The
fsimport gate inreadiness.rsis 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.rsandstart.rsare 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>
nowycondro
left a comment
There was a problem hiding this comment.
🤖 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'sfs/process_is_running/threadgating 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 differentcfgcombinations (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 gateduse. 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 ausethat is unconditional but only used under one gate — a short comment at the top of the file noting why there's nouse std::fs/process_is_running/threadwould 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 deletedservice_launch.rsand finding byte-for-byte logical identity outside the documented exceptions. - The two Windows-only
cfg-gating defects an earlier automated review round flagged inreadiness.rs(anfsimport and two test imports that would go unused on Windows) were independently re-verified fixed by direct inspection ofhead, not inferred from the "resolved" label or from green CI alone: there is no lingering unconditionaluse std::fs/use rocm_core::process_is_running/use std::threadanywhere 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 forservice_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.rswere independently traced to their print sites rather than taken on trust: both are byte-identical to the pre-move code, including thecodeql[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
left a comment
There was a problem hiding this comment.
🤖 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 inspawn.rs),service_launch/attach.rs(run_attached_service, "print_managed_launch_plainabove" → now instart.rs),service_launch/test_support.rs:14("each test below" → consumers now live inlaunch_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: thelaunch_transaction.rsentry is labelled as owning "private types", but its two types (ManagedPortDecision,ManagedReuseRefusal) arepub(super)/pub(crate), not private; the general "mechanical relocation" exceptions paragraph also doesn't listManagedReuseRefusalamong them.tests/e2e-cucumber/features/model_serving.feature(not touched by this PR) still has four comments namingservice_launch.rsfor functions that actually moved tospawn.rs,endpoint_auth.rs,readiness.rs, andlaunch_transaction.rsrespectively — 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>
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>


Closes ROCMAI-918.
cargo xtask check-module-sizereportsapps/rocm/src/service_launch.rsat 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 aservice_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.rsnow only declares the children and re-exports withpub(crate) usethe items other modules call, soserve_cmd.rs,automations.rs,service_control.rsandtool_policy.rskeep their imports unchanged. An item that sibling children share ispub(super)and reached throughsuper::<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-onlytest_supportmodule.service_launch.rsmoddeclarations, re-exportsservice_launch/endpoint_auth.rsservice_launch/launch_transaction.rsservice_launch/spawn.rsManagedLaunchReport,ManagedSpawn,spawn_managed_engine_child,launch_managed_engine_child_lockedservice_launch/readiness.rsservice_launch/start.rsstart_managed_serviceand the plain outputservice_launch/helper_autostart.rsservice_launch/attach.rsThe 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.rsat 1,304 lines, so no test file or production file is near the limit.check-module-sizenow 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/modlines 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 ofstd::fs::and similar full paths inreadiness.rswhere 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 stringservice_launch::tests::managed_launch_cleanup_sleeper_childat each of the three--exactcall sites. It now lives in the test-onlytest_supportmodule 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,usestatements and trailing commas, shows only those same differences plus themod,#[cfg(test)]andpub(...)tokens they imply. The set of 71 tests underservice_launchis the same before and after by name (70 pass, 1#[ignore]d sleeper helper).The
cfggating 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_runningandthreadon Windows inspawn.rsandstart.rs,std::iooff Windows, thee2e-oom-fault-injectionimports inreadiness.rs) carry that gate. Inreadiness.rs, where the use sites ofstd::fsand 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 windowspassed torustcfor therocmcrate alone, withtarget_os = "linux"andcfg(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 inservice_launch/, and the only errors it reports elsewhere are the ones that cannot be avoided without the Windows build ofrocm-core. It cannot run the dead-code lint, so that one is left to Windows CI.docs/architecture.mddescribes the new layout: theservice_launch.rsentry is rewritten and each child has its own entry. Thebackground_helper.rsand shared-type notes that pointed atservice_launch.rsnow point at the child that owns the item, and a handful of comments (four of them inmodel_serving.feature) anddocs/testing.mdthat named moved functions name their new file. Thelaunch_transaction.rsentry says it owns types, with the visibility ofManagedPortDecisionandManagedReuseRefusalspelled out. No Phase labels were added.Commands run, all with a fresh target directory of their own:
cargo xtask check-module-size(it reportedservice_launch.rsat 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_launchand a fullcargo test -q --locked -p rocm(1,686 passed, 9 ignored, none failed),cargo xtask check-architecture-doc,cargo xtask check-crate-edges, andlychee --offlineover 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-hooksandrocm/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-gpuscenarios 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.rsat 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.