[APMSVLS-501] refactor(bottlecap): preparatory work for a new "test-mode" binary

[lucaspimentel]

TL;DR: refactoring here first to prepare for #1216 and keep that PR slightly smaller.

NOTE: The original version of this PR was #1201. I've made several changes after feedback, so starting fresh to reduce baggage.

Part of a PR stack:

1. [APMSVLS-501] refactor(bottlecap): preparatory work for a new "test-mode" binary #1344 👈🏽 this PR
2. [APMSVLS-501] feat(bottlecap): add bottlecap-test-mode binary #1216

Overview

Preparatory refactors for the upcoming bottlecap-testmode binary (APMSVLS-501), which reuses TraceAgent / handle_traces but has no Lambda lifecycle to drive. Two logical changes:

The bottlecap::startup extraction (build_trace_agent and the public startup module) lands in #1216 alongside the bottlecap-test-mode binary that consumes it, where it has a caller; this PR keeps its scope to the two seams below and leaves main.rs and lib.rs untouched.

1. InvocationProcessorHandle::noop()

Constructor backed by a background task that acknowledges every ProcessorCommand with a sensible default so callers never block on their response oneshots:

• Request-response commands (GetReparentingInfo, UpdateReparenting, SetColdStartSpanTraceId, PlatformRuntimeDone, PlatformReport) reply with empty/default values.
• Fire-and-forget commands are dropped silently.

The match is exhaustive: adding a new ProcessorCommand variant will cause a compile error here, forcing test-mode behavior to be decided explicitly. A response-carrying variant placed in the fire-and-forget arm would silently drop its sender, causing the caller to receive ProcessorError::ChannelReceive instead of the intended default.

The noop channel capacity matches the real InvocationProcessorService to avoid backpressure surprises.

2. RouterExtension seam on TraceAgent

Adds a generic extension point that lets a caller merge additional axum routes into the trace-agent's HTTP router without TraceAgent knowing what those routes do. When no caller attaches an extension (the Lambda binary case), the HTTP surface on port 8126 is unchanged.

• New pub trait RouterExtension: Send + Sync { fn extend(&self, router: Router) -> Result<Router, Box<dyn Error>>; } defined in traces::trace_agent. Returning Err aborts agent startup and surfaces the error in the existing log path, preventing silent failures from a panicking or misconfigured extension.
• TraceAgent holds router_extension: Option<Arc<dyn RouterExtension>> with a consuming builder method with_router_extension(self, ext: Arc<dyn RouterExtension>) -> Self.
• make_router calls extension.extend(router)? when the field is set, before applying the outer fallback and body-limit layers.
• A #[cfg(test)]-only SpyExtension validates the seam end-to-end: the trait shape compiles, state is carried via Arc, and merged routes are reachable through the composed Router returned by make_router.

Any concrete flush/drain/diagnostic endpoint lives behind an impl of this trait in the consumer crate, not in trace_agent.rs.

Testing

• cargo check --bin bottlecap
• cargo check --lib
• cargo test --lib
• cargo clippy --workspace --all-targets --features default -- -D warnings
• cargo fmt --all -- --check
• cargo nextest run --workspace (532/532 passed)
• New unit tests on InvocationProcessorHandle::noop(): noop_request_response_methods_return_defaults, noop_fire_and_forget_commands_do_not_panic, noop_platform_runtime_done_and_report_respond_without_blocking, noop_request_response_variants_complete_within_timeout
• New unit tests on the RouterExtension seam: with_router_extension_adds_reachable_route_to_make_router, make_router_returns_404_for_extension_route_when_none_attached

[datadog-prod-us1-5]

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 1976b21 | Docs | View more details | Give us feedback!}

[Copilot]

Pull request overview

Prepares Bottlecap for a future lifecycle-free test-mode binary.

Changes:

• Adds a feature-gated no-op invocation processor with default responses.
• Adds an extensible TraceAgent router seam.
• Adds focused unit tests for both additions.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
bottlecap/Cargo.toml	Defines the test-mode feature.
bottlecap/src/lifecycle/invocation/processor_service.rs	Adds and tests the no-op processor handle.
bottlecap/src/traces/trace_agent.rs	Adds and tests router extensions.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[lucaspimentel]

@codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-03T16:54:06.156144Z	abb35a3	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Delightful!

Reviewed commit: abb35a3f19

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".