feat(vllm): route RL controls through sidecar

[connorcarpenter15]

Overview:

Route Dynamo vLLM sidecar reinforcement-learning controls and model updates through vLLM's native vllm.Control gRPC API.

The sidecar advertises only capabilities reported by vLLM and preserves vLLM's RL HTTP request schemas at the Dynamo /engine/* boundary.

This is PR 4 of 4 in the vLLM RL-control stack.

Details:

• Decode vLLM RL capability metadata during sidecar discovery.
• Add capability-gated pause/resume, sleep/wake, weight-transfer, draft-update, and weight-version routes.
• Translate Dynamo JSON route payloads to native gRPC requests and preserve lifecycle/status results.
• Validate pause modes before the shared lifecycle layer unregisters healthy capacity.
• Implement the RL RPCs in the focused sidecar fake and cover lifecycle payloads, partial wake behavior, and version state.

GPU smoke validation

The full live-engine matrix passed on ComputeLab H100 job 3609821 using Dynamo dbbba48ba4e5a3dd746b460e930a36d1bc37fa30, vLLM PR #51316 commit 76ebe5a217d7536a5661272c680f0b1e3a62f5be, and Qwen/Qwen3-0.6B as both main and speculative draft models.

• All seven controls passed: pause/resume/status, sleep/wake/status, and weight-version lookup.
• All six update operations passed: transfer-engine initialization, main/draft update start, tensor update, finish, and explicit version update.
• Main and draft updates each transferred 311 CUDA tensors totaling 1,503,264,768 bytes through IPC.
• Inference succeeded before and after both full-model updates.

The latest implementation was revalidated on ComputeLab H200 job 3656592 against vLLM PR #51316 commit a4f166; the explicit-tag control/update matrix passed. Untagged wake after a tagged partial wake remains an upstream vLLM issue tracked in DIS-2674 and is not claimed as passing here.

Local validation

• cargo fmt --all -- --check
• cargo test --locked -p dynamo-vllm-sidecar -p dynamo-vllm-mocker — 21 sidecar tests, 12 mocker tests, 3 sidecar integration tests, and the executable test passed on the final stacked head
• Prior full checks: affected-package cargo check, Python binding cargo check, and affected-package clippy with warnings denied

Where should the reviewer start?

• lib/sidecar/vllm/src/engine.rs for capability discovery and gRPC control/update routing.
• lib/sidecar/vllm/src/model.rs and lib/sidecar/vllm/src/client.rs for capability and client support.
• lib/sidecar/vllm/src/tests.rs for semantic payload and lifecycle coverage.

Stack:

1. #13259 — fix(backend): harden administrative route lifecycle
2. #13260 — feat(backend): add RL route discovery endpoint
3. #13261 — feat(vllm): sync RL control protocol
4. #13066 — feat(vllm): route RL controls through sidecar (this PR)

Related Issues

• DIS-2671: Route and harden RL controls through the vLLM sidecar
• DIS-2674: upstream vLLM partial-wake behavior

🚫 This PR is NOT linked to a GitHub issue:

• Confirmed — no related GitHub issue

AI assistance disclosure

This implementation was prepared with OpenAI Codex assistance and requires human review before merge.

[github-actions]

🌿 Fern Docs Preview: https://nvidia-preview-019ff35a-c13e-7765-b6da-e5779162df7a.docs.buildwithfern.com/dynamo/dev

[coderabbitai]

Walkthrough

Changes

RL control and discovery support

Layer / File(s)	Summary
RL discovery endpoint lib/backend-common/src/args.rs, lib/backend-common/src/rl.rs, lib/backend-common/src/lib.rs	Adds the enable_rl flag and an RL endpoint that validates requests and returns sorted, deduplicated engine routes.
Worker RL wiring and lifecycle lib/backend-common/src/worker.rs, lib/backend-common/examples/mocker/src/engine.rs, lib/sidecar/trtllm/src/engine.rs, lib/bindings/python/rust/backend.rs	Propagates RL configuration, manages endpoint startup and shutdown, preserves serve errors, and updates pause/resume discovery policies.
Control protocol and client contracts lib/sidecar/vllm/proto/control.proto, lib/sidecar/vllm/proto/README.md, lib/sidecar/vllm/src/client.rs, lib/sidecar/vllm/src/model.rs	Adds RL lifecycle and weight-update RPCs, capability metadata, reusable control-client construction, and capability compatibility checks.
vLLM engine control implementation lib/sidecar/vllm/src/engine.rs	Adds capability-gated pause, sleep, weight-update, and weight-version operations with JSON validation and RPC error translation.
Mock services, tests, and documentation lib/mocker/servers/vllm/src/server.rs, lib/sidecar/vllm/src/tests.rs, lib/sidecar/vllm/README.md	Adds unavailable-capability responses, fake control state, integration coverage, and RL workflow documentation.

Estimated code review effort: 4 (Complex) | ~45 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.61% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes routing vLLM reinforcement-learning controls through the sidecar.
Description check	✅ Passed	The description covers the required sections, implementation details, validation results, reviewer guidance, and issue linkage status.

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lib/backend-common/src/rl.rs`:
- Around line 48-57: Update self_host_base_url to bracket IPv6 literal hosts
before interpolating them into the HTTP URL, including configured values such as
::1 while preserving existing handling for wildcard hosts and IPv4/hostname
values.

In `@lib/sidecar/vllm/src/tests.rs`:
- Around line 284-316: Implement the fake handlers for every route advertised by
server_info(), replacing unimplemented_rl_rpc() in resume_generation, is_paused,
sleep, wake_up, is_sleeping, start_weight_update, start_draft_weight_update, and
update_weight_version. Add shared fake state so pause/resume, sleep/wake, and
weight-version updates produce successful responses and persist the
corresponding state across calls, including update_weight_version even without a
capability flag.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 12124258-824f-4281-9385-52b5d1ce377e

📥 Commits

Reviewing files that changed from the base of the PR and between 95c1539 and e3e7154.

📒 Files selected for processing (15)

• lib/backend-common/examples/mocker/src/engine.rs
• lib/backend-common/src/args.rs
• lib/backend-common/src/lib.rs
• lib/backend-common/src/rl.rs
• lib/backend-common/src/worker.rs
• lib/bindings/python/rust/backend.rs
• lib/mocker/servers/vllm/src/server.rs
• lib/sidecar/trtllm/src/engine.rs
• lib/sidecar/vllm/README.md
• lib/sidecar/vllm/proto/README.md
• lib/sidecar/vllm/proto/control.proto
• lib/sidecar/vllm/src/client.rs
• lib/sidecar/vllm/src/engine.rs
• lib/sidecar/vllm/src/model.rs
• lib/sidecar/vllm/src/tests.rs

[devin-ai-integration]

Devin Review found 4 potential issues.

View 1 additional finding in Devin Review.