Skip to content

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

Closed
ishandhanani wants to merge 1 commit into
mainfrom
idhanani/rs2-01-protocol
Closed

ishandhanani wants to merge 1 commit into
mainfrom
idhanani/rs2-01-protocol

Conversation

@ishandhanani

@ishandhanani ishandhanani commented Nov 2, 2026 •

Copy link
Copy Markdown
Owner

Router split v2, unit 01 of 17. Base: main.

Summary

dynamo-router-protocol (lib/router/protocol) is the identities and worker-facing vocabulary every router crate names: worker, rank, partition, pool, owner, and domain ids; WorkerType; the load and metadata wire; the KV hint wire; AttemptId and the new AttemptIdMinter; SessionContext. Its dependency contract is exactly serde, serde_json, thiserror, and it carries no executable behavior; the new fail-closed scripts/router_layering_check.sh enforces both. Rule applied: protocol is counterparty wire and identity only, so everything that computes stays with its producer (the hash functions stay in kv-router here, ResidencyOwner::compact_key becomes the ResidencyOwnerKeyExt extension trait) and AttemptId::new is replaced by a minter so a chosen id can no longer be forged outside the slot tracker. kv-router keeps pub use shims at every old path, so no other crate's imports change. Replaces fork PR #111.

What moves

  • refactor(router): add dynamo-router-protocol, the wire vocabulary crate #111 7663c31682 refactor(router): add dynamo-router-protocol, the wire vocabulary crate: the worker, identity, residency, block_hash, load, metadata, kv_hints, session, worker_type, and attempt modules extracted from lib/kv-router with shims at every old path. Move-diff (its body): 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.

Dependency edges

The layering gate is new in this unit (scripts/router_layering_check.sh: per-crate rows checked by set equality from cargo tree and cargo metadata, the workspace feature check, and --host resolution of dynamo-llm, dynamo-ext-proc, dynamo-mocker against prometheus axum hyper reqwest zmq).

  • dynamo-router-protocol -> serde, serde_json, thiserror (no router crate; dynamo-runtime, dynamo-kv-router, tokio, anyhow, tracing, async-trait, derive_builder, prometheus, axum, hyper, reqwest, zmq forbidden in its tree; lib/router/protocol/src grepped for dyn, async, std::fs, anyhow, tracing, derive_builder, hidden pub)

Validation

Unit-level move-diff, run from the worktree at the unit head 7663c31682: python3 -I scripts/router_move_diff.py 464ff290fe 7663c31682 --from <6 paths> --to <7 paths>, the union of the replaced fork PRs' --from/--to lists filtered to the paths present at each end (full command in the artifact /tmp/rr-split/unit-prs/01-move-diff.txt).

summary from_normalized=3878 to_normalized=3914 common=3869 new=45 dropped=9
result DIFFERS

The 45 new and 9 dropped lines are the set the fork PR recorded: AttemptIdMinter (struct, new, mint, the slot tracker's attempt_ids field, one minter test) replacing AttemptId::new; the ResidencyOwnerKeyExt extension trait replacing the inherent compact_key; ResidencyOwnerKey::from_digest; is_missing made public; the rest are the braces of those items.

New and dropped normalized lines (45 new, 9 dropped).
new 1x #[derive(Debug, Default)]
new 1x #[test]
new 1x AttemptId(self.next.fetch_add(1, Ordering::Relaxed) + 1)
new 1x ResidencyOwnerKey::from_digest(
new 1x Self {
new 1x Self(digest)
new 1x Self(value)
new 1x assert_eq!(first.to_string(), "1");
new 1x assert_eq!(second.to_string(), "2");
new 1x assert_ne!(first, second);
new 1x attempt_ids: AttemptIdMinter,
new 1x fn compact_key(self) -> ResidencyOwnerKey {
new 1x fn compact_key(self) -> ResidencyOwnerKey;
new 1x fn minter_yields_fresh_monotonic_ids_starting_at_one() {
new 1x impl AttemptIdMinter {
new 1x impl ResidencyOwnerKeyExt for ResidencyOwner {
new 2x let attempt_id = self.attempt_ids.mint();
new 1x let first = minter.mint();
new 1x let minter = AttemptIdMinter::new();
new 1x let second = minter.mint();
new 3x mod tests {
new 1x next: AtomicU64,
new 1x next: AtomicU64::new(0),
new 1x pub const fn from_digest(digest: [u8; 16]) -> Self {
new 1x pub const fn new() -> Self {
new 1x pub fn for_testing(value: u64) -> Self {
new 1x pub fn is_missing(&self) -> bool {
new 1x pub fn mint(&self) -> AttemptId {
new 1x pub struct AttemptIdMinter {
new 1x pub trait ResidencyOwnerKeyExt {
new 12x }
dropped 1x AttemptId::new(self.next_attempt_id.fetch_add(1, Ordering::Relaxed) + 1);
dropped 1x ResidencyOwnerKey(
dropped 1x Self::new(value)
dropped 1x fn is_missing(&self) -> bool {
dropped 1x let attempt_id =
dropped 1x let attempt_id = AttemptId::new(self.next_attempt_id.fetch_add(1, Ordering::Relaxed) + 1);
dropped 1x next_attempt_id: AtomicU64,
dropped 1x pub fn compact_key(self) -> ResidencyOwnerKey {
dropped 1x pub(crate) fn new(value: u64) -> Self {

Chain v2, full mode, on the rebased stack head ebd31cdf4d (every unit's commits are ancestors of it; the chain ran once on the head, not per unit), log /tmp/rr-split/srebase-validation.log: stage 1, the 13 router crates (clippy under default and all features, cargo test 1,247 passed / 5 ignored, rustdoc with all features), 1 min 50 s; stage 2, kv-router (clippy, bench check, 229 tests including the prelude test), 1 min 20 s; stage 3, workspace clippy, 4 min 58 s; stage 4, hosts (dynamo-llm lib alone, its kv_router 492 / discovery 275 / pool_relay 261 tests, 13 host crates clippy, bindings clippy; the pre-existing kvbm-consolidator manifest failure is the one non-zero exit), 29 min 21 s; stage 5, gates (every kv-router feature alone and together, 6 public-API snapshots unchanged with kv-router at 918 items, layering gate 47 checks and --host 66 checks with 0 failures, codeowners 7590/7590, fmt, 3 lockfiles --locked), 3 min 06 s; 40 min 35 s total, exit 0.

Each replaced fork PR carried its own validation chain; see its body.

Tickets

Part of DYNO-170

Series

The 17 review units of the router split v2 stack on top of main (464ff290fe), in order; each is stacked on the previous one and the last head is the stack head ebd31cdf4d.

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

Labels

actions documentation Improvements or additions to documentation refactor router

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant