Skip to content

refactor(router): add dynamo-router-protocol, the wire vocabulary crate - #111

Closed
ishandhanani wants to merge 1 commit into
mainfrom
idhanani/dyn-170-router-protocol
Closed

ishandhanani wants to merge 1 commit into
mainfrom
idhanani/dyn-170-router-protocol

Conversation

@ishandhanani

Copy link
Copy Markdown
Owner

Step 1 of the router split v2 (DYNO-170). Fork draft; upstream slicing follows the plan.

Summary

Adds dynamo-router-protocol (lib/router/protocol): the identities and worker-facing wire vocabulary every router crate names, extracted from lib/kv-router with pub use shims left at every old path so no other crate's imports change.

What moved, by module:

  • worker: WorkerId, DpRank, WorkerWithDpRank, WorkerAffinityTarget
  • identity: RoutingPartitionId/Ref, IdentitySource, CacheSemanticsId, RoutingScopeId, StableDpSlotId, IndexerDomainId, ClusterId, PoolId, CacheOwnerId, IdentityParseError, DEFAULT_ROUTING_GROUP (the indexer identity spec, map, and canonical material stay in kv-router)
  • residency: StorageTier, ResidencyDomain, ResidencyOwner, ResidencyOwnerKey, ResetScope, WireResidencyDomain, UnsupportedResidencyDomain
  • block_hash: LocalBlockHash, ExternalSequenceBlockHash (the functions that compute them stay in kv-router)
  • load: SchedulerLoad, SchedulerGroup, ActiveLoad
  • metadata: RouterHintSourceMetadata
  • kv_hints: the KV_HINT_* runtime-config keys, KvHint, KvHintAction, KvSourceLocationsPayload
  • session: SessionContext, WorkerSelectionInputTrigger
  • worker_type: WorkerType, ParseWorkerTypeError
  • attempt: AttemptId and the new AttemptIdMinter

Two deliberate non-moves:

  • AttemptId loses its #[doc(hidden)] pub fn new. The only way to obtain one is AttemptIdMinter::mint, which yields fresh monotonic ids and never a chosen value; the slot tracker's RequestIndex holds the one minter. Tests use AttemptId::for_testing behind the testing feature, benches for_benchmark behind bench. This restores the property the single crate had through pub(crate).
  • ResidencyOwner::compact_key (BLAKE3) is hashing, not wire. It becomes the ResidencyOwnerKeyExt extension trait in dynamo_kv_router::protocols; call sites gain one use line, including one in lib/llm/src/kv_router/indexer/recovery/state_agent.rs.

The crate's dependency contract is exactly serde, serde_json, thiserror, and the new fail-closed scripts/router_layering_check.sh enforces it by set equality plus a grep that forbids dyn, async, std::fs, anyhow, tracing, derive_builder, and hidden-pub items in the crate. scripts/router_move_diff.py is the review artifact that shows the move is a move.

Design and plan: minamo design notes, SPLIT_V2.md and PLAN.md section 11.

Validation

  • cargo tree -p dynamo-router-protocol -e normal --depth 1: direct deps serde, serde_json, thiserror; full closure 14 crates.
  • cargo test -p dynamo-router-protocol: 10 passed.
  • cargo check -p dynamo-kv-router: clean, no warnings.
  • cargo test -p dynamo-kv-router: 1,127 passed, 0 failed, 3 ignored (lib 1,126 + integration 1); the protocols test module alone 42 passed.
  • cargo check -p dynamo-llm -p dynamo-mocker -p dynamo-bench -p dynamo-custom-policy-builtin --tests: clean (one warning fixed: the lib/llm extension-trait import belongs in its test module); cargo check -p dynamo-llm --tests clean.
  • scripts/router_layering_check.sh: 5 checks, 0 failures; --host mode 21 checks, 0 failures (dynamo-llm, dynamo-ext-proc, dynamo-mocker against prometheus, axum, hyper, reqwest, zmq).
  • scripts/router_move_diff.py (base 91a64d9e14 -> worktree): 3,858 normalized lines found; 45 new (the minter, the extension trait, ResidencyOwnerKey::from_digest, is_missing made public, one minter test); 9 dropped (the replaced AttemptId::new and inherent compact_key paths). Per-file fractions: protocols.rs 0.999, identity.rs 1.000, worker_type.rs 1.000, kv_hints.rs 1.000, scheduling/types.rs 0.996, request_maps.rs 0.981.
  • cargo clippy -p dynamo-router-protocol -p dynamo-kv-router --all-targets -- -D warnings: clean; cargo fmt applied.
  • CODEOWNERS: lib/router/ and lib/router/protocol/ claimed under the router area; build_codeowners.py --strict and emit_codeowners.py regenerated; validate_agent_instructions.py: 45 scopes OK.
  • Identity tests remain in lib/kv-router/src/identity.rs (they exercise id and spec types together) and run through the shim.

Extract the identities and worker-facing vocabulary every router crate
names into lib/router/protocol: worker and rank ids, partition, pool,
owner, and domain identities, WorkerType, the residency vocabulary, the
block-hash newtypes, worker load and metadata wire types, KV hint wire
types, SessionContext, and AttemptId. lib/kv-router keeps pub use shims at
every old path, so no other crate's imports change.

AttemptId has no public constructor any more. AttemptIdMinter::mint is the
only way to obtain one and yields fresh ids only; the slot tracker's
RequestIndex holds the one minter. Tests use for_testing behind the
testing feature, benches for_benchmark behind bench. ResidencyOwner's
BLAKE3 compact_key is hashing, not wire, so it becomes the
ResidencyOwnerKeyExt extension trait in dynamo_kv_router::protocols.

The crate depends on exactly serde, serde_json, and thiserror.
scripts/router_layering_check.sh enforces that by set equality, forbids
behavior in the crate, and fails closed; it runs in pre-commit and, with
--host, in the Rust CI job. scripts/router_move_diff.py shows the move is
a move: 3,858 lines found, 45 new (minter, extension trait, one test),
9 dropped (the replaced constructor paths).

Step 1 of the router split v2 plan. DYNO-170.

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 — 7663c316 Deployed Nov 2, 2026 by ishandhanani via ok-to-test #513
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant