Initialize roxyd base code structure

[sae-bom]

Based on #496

Initialize the codebase for roxyd inside the existing crate. It includes entrypoints, config, logging, and review-protocol connection skeletons, and dual-path coexistence with the legacy implementation, but it does not port any existing handler logic yet.

The structure should be friendly to AI coding agents (small, focused modules; clear naming; minimal hidden coupling).

---

Tasks

1. Add a new binary target inside the existing crate

• Add a new binary entrypoint (e.g. src/bin/roxyd.rs)
  • Only if it proves to be strictly necessary during implementation, introduce a feature flag that allows selecting between the legacy implementation and the new roxyd implementation.
• Define a minimal main that:
  • Parse and load CLI args and/or config path.
  • Initialize tracing
  • Start the main async runtime (e.g. via #[tokio::main]).
• Add a short README section that explains:
  • This is a new implementation path that coexists with the legacy one.
  • Existing code must not be removed while legacy mode is still in use.
  • Current limitations (skeleton only; no real handlers yet).

2. Define configuration for the QUIC/mTLS connection

• Add config fields for QUIC/mTLS connection to Manager
  • QUIC endpoint / Manager address.
  • mTLS / certificate paths or references.

3. Set up review-protocol client skeleton

• Add a review_protocol integration module that exposes a function like run_connection_loop(config: &Config) -> Result<()> that will:
  • Establish QUIC/mTLS connection.
  • Perform the initial handshake.
  • Enter a request/response loop.
  • Receive and route RequestCodes.
• For now, do not implement real handlers:
  • Provide a generic handle_request stub that logs the RequestCode and fails with unimplemented!()
  • Add TODO: comments where individual handler families will be plugged in later.

4. Internal module layout for handlers

• Create a directory structure like:

  • roxyd/handlers/
    • service_control.rs
    • hostname.rs
    • ntp.rs
    • syslog.rs
    • power.rs
    • observation.rs
    • (… follow predefined design doc)

• In each handler module:

  • Define public function signatures only.
  • Leave bodies as unimplemented!() to be filled in by follow-up issues.

5. Logging, tracing, and error types

• Reuse the crate’s existing tracing subscriber setup instead of introducing a new logging framework.
• Plug in tracing with:
  • Basic subscriber setup in main.
  • Startup and shutdown.
  • Connection lifecycle (connect/reconnect).
  • Incoming RequestCode + handler dispatch.
• Ensure logs are compatible with the existing stack:
  • Use existing log formats / levels where possible.
  • Avoid introducing a different logging framework.

6. Tests and examples

• Add at least one example unit test or component test.
• Add an example configuration to the README to illustrate how to run the new binary.

7. CI / build integration

• Update the workspace and CI so that:
  • The new roxyd binary target is included in cargo build / cargo test.
  • Existing lint, fmt, and coverage jobs run against the new code.
• Verify that CI still passes with:
  • Legacy-only configuration.
  • New binary enabled but with stub handlers.

---

Acceptance Criteria

• New binary target compiles and passes tests with stub handlers only.
• QUIC/mTLS + review-protocol skeleton is in place (handshake + request loop).
• Old implementation remains fully functional and is still the only path used in production code; switching logic is isolated behind feature flags.
• CI is green: build, lint, tests.
• The module layout makes it clear where follow-up issues should plug in handler logic, observability, and deployment specifics.

[sophie-cluml]

Thank you for the proposal. I have a few questions before we discuss this with Kone:

Add a feature flag that allows selecting between the legacy implementation and the new roxyd implementation.

Could you share a bit more context on the motivation for the feature flag? Since bin/roxyd would be a separate binary target from the existing one, I was wondering whether the distinction at the target level might already be sufficient, and what additional benefit the feature flag is intended to provide.

Optional: per-node identity (AgentInfo) fields.

This seems slightly beyond the current scope of roxy and the initial skeleton. Would it be reasonable to defer this for now and introduce it later if we find a concrete need for it?

[sae-bom]

Thanks for the questions — both are fair points.

On the feature flag:
The original intent was simply to ensure a clean separation between the legacy path and the new roxyd path during the migration period, rather than to strictly require a feature-flag-based switch.
I agree that, at least initially, having roxyd as a separate binary target can be sufficient to achieve that separation. My current thinking is to start with the target-level distinction, and only introduce a feature flag later if we run into concrete cases where build-time gating or tighter integration becomes necessary during implementation.

On the optional AgentInfo fields:
I agree with this point as well. Including per-node identity fields at this stage is likely premature for the initial skeleton, and we can defer this until we have a clearer, concrete need for it.

I’ll adjust the proposal accordingly to reflect these changes.

[sophie-cluml]

Thank you for making the adjustments.

I personally think the following points might help AI agents better understand and work from the scaffolding:

• The review-protocol repository is here: https://github.com/petabi/review-protocol. Just to help AI agents spend less time figuring out what it is.
• The “2. Target Architecture with roxyd” section in this comment is the most relevant reference for this discussion.