From 1da2b1dbeb45e516fb91a7e6ed9686a5afe7b3eb Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Fri, 2 Oct 2026 09:01:45 -0600 Subject: [PATCH 1/6] Document local Rust checks Co-Authored-By: GPT-5 Codex Dispatch-Task: symphony-claude-md-cargo-test-note --- CLAUDE.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 29b11af..dfaa450 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -159,7 +159,7 @@ napi `Buffer` contains raw pointers (`*mut napi_env__`, `*mut napi_ref__`) that - All counter decrements use RAII guards (`BalancerGuard`, `ActiveGuard`). Never decrement in a finally-style chain. - `Relaxed` ordering for per-connection counters (active, accepted, errors). `AcqRel` only where cross-thread ordering is required — each such site has a comment explaining why. - Error type: `SymphonyError` → `napi::Error` via `From`. No `unwrap()` on paths reachable from JS. -- `#![deny(clippy::all)]` is set in `lib.rs`. Fix clippy warnings before committing. +- `#![deny(clippy::all)]` is set in `lib.rs`. Fix clippy warnings before committing; run `cargo clippy --all-targets` as listed in Testing. --- @@ -215,12 +215,28 @@ Tests live in `__test__/` and use Node's built-in `node:test` runner. - **`metrics.spec.ts`** — per-listener breakdown and byte counting, `renderPrometheus` output shape, the admin endpoint over UDS + TCP, and stale-socket reclaim after a `SIGKILL` - **`liveness.spec.ts`** — the half-close bound over a real passthrough proxy. Its client uses `allowHalfOpen: true` (otherwise Node answers the proxy's FIN with its own and there is no half-close to bound) and a synthetic `clientHello()` from `util.ts` (otherwise `peek()` blocks for its 5s reassembly timeout and a no-SNI connection resolves to no route) -Build and run: +The Rust toolchain is pinned to `1.94.1` in `rust-toolchain.toml`. Ensure rustup's +`~/.cargo/bin` is on `PATH` ahead of any system-installed `cargo`, including in non-interactive +shells; `cargo --version` should report `1.94.1`. This also applies to `npm run build:debug`, which +invokes Cargo. + +Build the addon before running the Node tests, and repeat the build after Rust changes so the tests +load the current native addon: ```bash npm run build:debug npm test ``` +`npm test` does not run the Rust checks below. For changes to Rust source, Cargo manifests or +lockfiles, or Rust toolchain configuration, run these Rust CI checks before pushing: +```bash +cargo test +cargo clippy --all-targets +cargo fmt --check +``` + +CI runs these Rust checks on Linux. + Tests bind on random high ports (`port: 0`) to avoid conflicts. Suspended-route tests use short `suspendTimeoutMs` (200ms) to keep the suite fast. --- From 2392e5a7501b532bced171c87699007b90ab0cc7 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Fri, 2 Oct 2026 09:10:03 -0600 Subject: [PATCH 2/6] Clarify Rust check requirements Co-Authored-By: GPT-5 Codex Dispatch-Task: symphony-claude-md-cargo-test-note --- CLAUDE.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index dfaa450..b763fd7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -216,9 +216,11 @@ Tests live in `__test__/` and use Node's built-in `node:test` runner. - **`liveness.spec.ts`** — the half-close bound over a real passthrough proxy. Its client uses `allowHalfOpen: true` (otherwise Node answers the proxy's FIN with its own and there is no half-close to bound) and a synthetic `clientHello()` from `util.ts` (otherwise `peek()` blocks for its 5s reassembly timeout and a no-SNI connection resolves to no route) The Rust toolchain is pinned to `1.94.1` in `rust-toolchain.toml`. Ensure rustup's -`~/.cargo/bin` is on `PATH` ahead of any system-installed `cargo`, including in non-interactive -shells; `cargo --version` should report `1.94.1`. This also applies to `npm run build:debug`, which -invokes Cargo. +`~/.cargo/bin` (or `$CARGO_HOME/bin` with a custom Cargo home) is on `PATH` ahead of any +system-installed `cargo`, including in non-interactive shells. From the repository root, +`cargo --version` should report `1.94.1`; if the pinned toolchain is missing, run +`rustup toolchain install` from the repository root. This also applies to `npm run build:debug`, +which invokes Cargo. Build the addon before running the Node tests, and repeat the build after Rust changes so the tests load the current native addon: @@ -227,15 +229,18 @@ npm run build:debug npm test ``` -`npm test` does not run the Rust checks below. For changes to Rust source, Cargo manifests or -lockfiles, or Rust toolchain configuration, run these Rust CI checks before pushing: +`npm test` does not run the Rust checks below. For changes to Rust sources (`src/**`, `build.rs`), +Cargo manifests or lockfiles, or Rust toolchain/formatter configuration (`rust-toolchain.toml`, +`rustfmt.toml`), run these Rust CI checks before pushing: ```bash cargo test cargo clippy --all-targets cargo fmt --check ``` -CI runs these Rust checks on Linux. +CI runs these Rust checks on Linux (`ubuntu-latest`), and its result is authoritative. On macOS, +`cargo test` and Clippy compile different `#[cfg(target_os = "linux")]` branches from Linux CI, +so a clean local run cannot guarantee that CI will pass. Tests bind on random high ports (`port: 0`) to avoid conflicts. Suspended-route tests use short `suspendTimeoutMs` (200ms) to keep the suite fast. From 381b0424fd5f3e58968cb519a0c4394010de9845 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Fri, 2 Oct 2026 09:17:37 -0600 Subject: [PATCH 3/6] Require Linux Rust checks before macOS pushes Co-Authored-By: GPT-5 Codex Dispatch-Task: symphony-claude-md-cargo-test-note --- CLAUDE.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b763fd7..48df4d3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -239,8 +239,9 @@ cargo fmt --check ``` CI runs these Rust checks on Linux (`ubuntu-latest`), and its result is authoritative. On macOS, -`cargo test` and Clippy compile different `#[cfg(target_os = "linux")]` branches from Linux CI, -so a clean local run cannot guarantee that CI will pass. +`cargo test` and Clippy compile different `#[cfg(target_os = "linux")]` branches, so run those two +checks in a Linux environment before pushing; a macOS pass alone does not validate Linux-only code. +`cargo fmt --check` can run on either platform. Tests bind on random high ports (`port: 0`) to avoid conflicts. Suspended-route tests use short `suspendTimeoutMs` (200ms) to keep the suite fast. From c43cc16ecc120d65263fbbe32237185b49002cdf Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Fri, 2 Oct 2026 09:23:57 -0600 Subject: [PATCH 4/6] Link macOS Rust checks to Linux Docker setup Co-Authored-By: GPT-5 Codex Dispatch-Task: symphony-claude-md-cargo-test-note --- CLAUDE.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 48df4d3..9660aa3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -239,9 +239,10 @@ cargo fmt --check ``` CI runs these Rust checks on Linux (`ubuntu-latest`), and its result is authoritative. On macOS, -`cargo test` and Clippy compile different `#[cfg(target_os = "linux")]` branches, so run those two -checks in a Linux environment before pushing; a macOS pass alone does not validate Linux-only code. -`cargo fmt --check` can run on either platform. +run `cargo test` and `cargo clippy --all-targets` in a Linux environment before pushing; the +[README Cross-compilation section](README.md#cross-compilation) documents the Linux Docker images. +macOS compiles different `#[cfg(target_os = "linux")]` branches, so local test/lint passes are +insufficient; `cargo fmt --check` can run on either platform. Tests bind on random high ports (`port: 0`) to avoid conflicts. Suspended-route tests use short `suspendTimeoutMs` (200ms) to keep the suite fast. From 9c07ad26c6915179744fc13c708772c8f3e07c55 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Fri, 2 Oct 2026 09:42:43 -0600 Subject: [PATCH 5/6] Clarify macOS Rust check coverage Co-Authored-By: GPT-5 Codex Dispatch-Task: symphony-claude-md-cargo-test-note --- CLAUDE.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9660aa3..9a5d45f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -239,10 +239,9 @@ cargo fmt --check ``` CI runs these Rust checks on Linux (`ubuntu-latest`), and its result is authoritative. On macOS, -run `cargo test` and `cargo clippy --all-targets` in a Linux environment before pushing; the -[README Cross-compilation section](README.md#cross-compilation) documents the Linux Docker images. -macOS compiles different `#[cfg(target_os = "linux")]` branches, so local test/lint passes are -insufficient; `cargo fmt --check` can run on either platform. +macOS does not compile the Linux-only `#[cfg(target_os = "linux")]` branches. Run `cargo test` +and `cargo clippy --all-targets` in a Linux environment before pushing from macOS. The [README Cross-compilation section](README.md#cross-compilation) documents the Linux Docker images. +`cargo fmt --check` can run on either platform. Tests bind on random high ports (`port: 0`) to avoid conflicts. Suspended-route tests use short `suspendTimeoutMs` (200ms) to keep the suite fast. From bd48172b2dfd82ed10bb5bb3c908b1071b914439 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Fri, 2 Oct 2026 09:48:11 -0600 Subject: [PATCH 6/6] Remove duplicate macOS wording Co-Authored-By: GPT-5 Codex Dispatch-Task: symphony-claude-md-cargo-test-note --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9a5d45f..e2ae8dd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -239,7 +239,7 @@ cargo fmt --check ``` CI runs these Rust checks on Linux (`ubuntu-latest`), and its result is authoritative. On macOS, -macOS does not compile the Linux-only `#[cfg(target_os = "linux")]` branches. Run `cargo test` +the Linux-only `#[cfg(target_os = "linux")]` branches are not compiled. Run `cargo test` and `cargo clippy --all-targets` in a Linux environment before pushing from macOS. The [README Cross-compilation section](README.md#cross-compilation) documents the Linux Docker images. `cargo fmt --check` can run on either platform.