Skip to content

chore(router): deprecate kv-router's shim paths for one release - #157

Closed
ishandhanani wants to merge 1 commit into
idhanani/dyn-180-kv-router-owner-importsfrom
idhanani/dyn-180-shim-deprecations
Closed

ishandhanani wants to merge 1 commit into
idhanani/dyn-180-kv-router-owner-importsfrom
idhanani/dyn-180-shim-deprecations

Conversation

@ishandhanani

Copy link
Copy Markdown
Owner

Step 7d-2 of the router split v2 (DYNO-180). Stacked on #156. kv-router's shim paths carry #[deprecated] for one release; the crate's non-deprecated surface is the composition: config, plugins (with prelude), services (the adapters and SelectionService), tracking_hash, and test_utils.

Summary

  • Deprecated (since = "1.7.0", each note names the owner and points at the README table): the root re-exports of stage and kernel items (21 pub use groups in lib.rs), the shim modules conditional_disagg, identity, indexer, kv_hints, protocols, recovery, worker_type, the aliases sequences, session_prefix_index, zmq_wire, concurrent_radix_tree_compressed, nested_map, approx, radix_tree, queue, selector, multi_worker_sequence, sequence; in scheduling, the kernel re-export submodules and lines and the TODO(v1.7) plugin compatibility blocks; in services::selection, the kernel and session-affinity re-exports and its TODO(v1.7) block; services::overlap.
  • Two consequences of deprecating the shims: (1) the root aliases queue and selector pointed at the deprecated scheduling::{queue, selector} shim submodules, and rustc lints the path inside a deprecated use; they now alias the kernel modules directly (pub use dynamo_scheduler::{queue, selector};), so every dynamo_kv_router::queue::X / selector::X path still resolves. The snapshot records this as two pub mod + glob pairs becoming two module aliases (1392 -> 1390 lines; no path a consumer can name changes). (2) The protocols shim carried five tests of types it only re-exports (two block-hash serialization tests, three SharedCacheHits tests); a deprecated module cannot hold tests (the harness references them), so they move verbatim to their owners, lib/router/protocol/src/block_hash.rs and lib/router/worker-selection/src/shared_cache.rs (two stale comment blocks describing fixtures that had already left this module are dropped).
  • Not deprecated: config (the flat configuration, its env readers, the policy YAML forms), plugins and plugins::prelude, services::{indexer, slot_tracker, selection::{SelectionService, SelectionServiceBuilder, SelectionServiceConfig, warn_for_unserved_worker_selection_policies, local_selection_core, ZmqDirectIngress, AppState, run_server}}, tracking_hash, test_utils, scheduling::{config, policy_config}.
  • Nothing in this tree uses a deprecated path: the workspace builds with -D warnings. Two test-only opt-ins: the frozen pre-prelude test tests/plugin_api_compat.rs (#![allow(deprecated)], by design) and the selection service's HTTP test module (#[allow(deprecated)] on mod tests: it glob-imports the module with use super::* and so reaches the compatibility re-exports; splitting its 1.9k-line import surface is not worth a move-only PR). lib/kv-router/public-api.txt regenerated (the simplified snapshot does not record #[deprecated]; the only change is the alias form above); README gains a "Deprecated paths" table (old path -> owner). The standalone-* feature aliases stay one more release as 7b documented; runtime-protocols is already empty (8f).

Validation

  • kv-router: cargo clippy --all-targets -- -D warnings for none, the full set, the standalone-* aliases, and each adapter alone; cargo test under the full set.
  • Workspace: cargo clippy --workspace --all-targets -- -D warnings (default features) clean, so no in-tree code reaches a deprecated path; cargo test -p dynamo-router-protocol block_hash (2) and cargo test -p dynamo-worker-selection shared_cache (3) run the relocated tests in their owners.
  • Each host alone (cargo check --all-targets, which surfaces deprecation warnings per host): dynamo-llm, dynamo-mocker, dynamo-bench, dynamo-ext-proc, dynamo-custom-policy-builtin, dynamo-worker-selection-policy-catalog, dynamo-sglang-sidecar, dynamo-sglang-mocker, dynamo-vllm-mocker, the two examples: none; Python bindings cargo clippy --features kv-indexer,slot-tracker,select-service -- -D warnings; C bindings clippy.
  • scripts/router_features_check.sh (cargo hack, 15 configurations); scripts/router_public_api_check.sh: matches the regenerated snapshot (1390 items); scripts/router_layering_check.sh --host: 42 checks, 0 failures; codeowners strict 7530/7530; cargo fmt --all -- --check; RUSTDOCFLAGS="-D warnings" cargo doc -p dynamo-kv-router.

Iterations recorded in the plan: the first pass left the root queue/selector aliases pointing at deprecated shim submodules (rustc lints the path inside a deprecated use) and left five tests inside the deprecated protocols module (the test harness references them); both fixed as described above.

Step 7d-2 of the router split (DYNO-180). dynamo-kv-router is the
composition crate: the flat configuration and its parsers, the plugin
registry and plugins::prelude, SelectionService and its builder, and the
adapters behind features. Every other path it still exposes is a shim
over a stage or the kernel, kept so that callers outside this tree have
one release to move. Those paths now carry #[deprecated] notes naming
the owner: the root re-exports of stage and kernel items, the shim
modules (scheduling's kernel re-exports and submodules, protocols,
identity, indexer, kv_hints, sequences and its aliases, recovery,
worker_type, conditional_disagg, zmq_wire, session_prefix_index, the
indexer aliases), and services::selection's kernel re-exports with its
TODO(v1.7) compatibility block. Nothing in this tree uses a deprecated
path (the workspace builds with -D warnings); the frozen
tests/plugin_api_compat.rs and the selection service's HTTP test
module (which glob-imports the module) allow them on purpose. Two
consequences: the root `queue` and `selector` aliases now name the
kernel modules directly instead of the deprecated shim submodules
(same paths for every consumer), and the five tests the protocols shim
carried for types it only re-exports move verbatim to their owners
(protocol's block_hash.rs, worker-selection's shared_cache.rs). The
public-api snapshot and the README's path table follow. The
standalone-* feature aliases stay one more release, as 7b documented.

Validation: kv-router clippy -D warnings --all-targets over seven
feature sets and its full-feature tests; workspace clippy --all-targets
-D warnings (no deprecation warning anywhere in tree); eleven hosts and
examples checked alone with --all-targets; Python and C bindings
clippy; cargo hack --each-feature on kv-router (15 configurations); the
five relocated tests pass in their owners; public-api snapshot
regenerated (1390 items: the two root module aliases change form, no
consumer path changes); layering gate --host 42 checks; codeowners
strict; fmt; rustdoc -D warnings.

Signed-off-by: Ishan Dhanani <ishandhanani@gmail.com>
@ishandhanani

Copy link
Copy Markdown
Owner Author

Landed upstream as ai-dynamo#18055 (squash commit 79692cf on main, 2026-11-11). Closing this fork review unit.

This branch had an error being deployed

1 failed deployment
external_collaborator — 81ace25c Deployed Nov 2, 2026 by ishandhanani via ok-to-test #525
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

chore documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant