From 8d68f63e6c722ee0ae390b5435ab2f9c105fd0d5 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Thu, 26 Feb 2026 06:38:56 -0500 Subject: [PATCH] chore: update project structure, naming, and add reporting infrastructure - Update all 7 phase docs with source/target location references (golang/ for Go source, dotnet/ for .NET version) - Rename NATS.Server to ZB.MOM.NatsNet.Server in phase 4-7 docs - Update solution layout to dotnet/src/ and dotnet/tests/ structure - Create CLAUDE.md with project summary and phase links - Update .gitignore: track porting.db, add standard .NET patterns - Add golang/nats-server as git submodule - Add reports/generate-report.sh and pre-commit hook - Add documentation_rules.md to version control --- .gitignore | 32 +- .gitmodules | 3 + CLAUDE.md | 61 ++++ docs/plans/phases/phase-1-decomposition.md | 7 + docs/plans/phases/phase-2-verification.md | 7 + docs/plans/phases/phase-3-library-mapping.md | 7 + docs/plans/phases/phase-4-dotnet-design.md | 65 ++-- .../phases/phase-5-mapping-verification.md | 23 +- docs/plans/phases/phase-6-porting.md | 19 +- .../phases/phase-7-porting-verification.md | 33 +- documentation_rules.md | 318 ++++++++++++++++++ golang/nats-server | 1 + reports/generate-report.sh | 34 ++ 13 files changed, 547 insertions(+), 63 deletions(-) create mode 100644 .gitmodules create mode 100644 CLAUDE.md create mode 100644 documentation_rules.md create mode 160000 golang/nats-server create mode 100755 reports/generate-report.sh diff --git a/.gitignore b/.gitignore index dedd23c..6094ae4 100644 --- a/.gitignore +++ b/.gitignore @@ -1,12 +1,29 @@ -# SQLite database (local state) -porting.db +# SQLite transient files (WAL mode) porting.db-journal porting.db-wal porting.db-shm # .NET build output -tools/NatsNet.PortTracker/bin/ -tools/NatsNet.PortTracker/obj/ +**/bin/ +**/obj/ + +# .NET user / IDE integration files +*.user +*.suo +*.userosscache +*.sln.docstates + +# Visual Studio cache/options directory +.vs/ + +# NuGet +*.nupkg +*.snupkg +project.lock.json +project.fragment.lock.json +*.nuget.props +*.nuget.targets +packages/ # Go build output tools/go-analyzer/go-analyzer @@ -14,3 +31,10 @@ tools/go-analyzer/go-analyzer # OS files .DS_Store Thumbs.db + +# IDE files +.idea/ +.vscode/*.code-workspace +.vscode/settings.json +.vscode/tasks.json +.vscode/launch.json diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..bd3664f --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "golang/nats-server"] + path = golang/nats-server + url = https://github.com/nats-io/nats-server.git diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..1955c69 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,61 @@ +# CLAUDE.md + +## Project Summary + +This project is porting the NATS server from Go to .NET 10 C#. The Go source (~130K LOC across 109 non-test files, 85 test files) is at `golang/nats-server/`. The porting process is tracked via an SQLite database (`porting.db`) and managed by two tools: a Go AST analyzer and a .NET PortTracker CLI. + +## Folder Layout + +``` +natsnet/ +├── golang/nats-server/ # Go source (reference) +├── dotnet/ # .NET ported version +│ ├── src/ +│ │ ├── ZB.MOM.NatsNet.Server/ # Main server library +│ │ └── ZB.MOM.NatsNet.Server.Host/ # Host/entry point +│ └── tests/ +│ ├── ZB.MOM.NatsNet.Server.Tests/ # Unit tests +│ └── ZB.MOM.NatsNet.Server.IntegrationTests/ # Integration tests +├── tools/ +│ ├── go-analyzer/ # Go AST analyzer (Phases 1-2) +│ └── NatsNet.PortTracker/ # .NET CLI tool (all phases) +├── docs/plans/phases/ # Phase instruction guides +├── reports/ # Generated porting reports +├── porting.db # SQLite tracking database +├── porting-schema.sql # Database schema +└── documentation_rules.md # Documentation conventions +``` + +## Tools + +### Go AST Analyzer + +```bash +CGO_ENABLED=1 go build -o go-analyzer . && ./go-analyzer --source golang/nats-server --db porting.db --schema porting-schema.sql +``` + +### .NET PortTracker CLI + +```bash +dotnet run --project tools/NatsNet.PortTracker -- --db porting.db +``` + +## Phase Instructions + +- **Phase 1: Go Codebase Decomposition** - `docs/plans/phases/phase-1-decomposition.md` +- **Phase 2: Verification of Captured Items** - `docs/plans/phases/phase-2-verification.md` +- **Phase 3: Library Mapping** - `docs/plans/phases/phase-3-library-mapping.md` +- **Phase 4: .NET Solution Design** - `docs/plans/phases/phase-4-dotnet-design.md` +- **Phase 5: Mapping Verification** - `docs/plans/phases/phase-5-mapping-verification.md` +- **Phase 6: Initial Porting** - `docs/plans/phases/phase-6-porting.md` +- **Phase 7: Porting Verification** - `docs/plans/phases/phase-7-porting-verification.md` + +## Naming Conventions + +.NET projects use the `ZB.MOM.NatsNet.Server` prefix. Namespaces follow the `ZB.MOM.NatsNet.Server.[Module]` pattern. + +## Reports + +- `reports/current.md` always has the latest porting status. +- `reports/report_{commit_id}.md` snapshots are generated on each commit via pre-commit hook. +- Run `./reports/generate-report.sh` manually to regenerate. diff --git a/docs/plans/phases/phase-1-decomposition.md b/docs/plans/phases/phase-1-decomposition.md index 8c9e10c..d489d58 100644 --- a/docs/plans/phases/phase-1-decomposition.md +++ b/docs/plans/phases/phase-1-decomposition.md @@ -26,6 +26,13 @@ sqlite3 --version # optional, any 3.x echo $CGO_ENABLED # should print 1 (or be unset; we set it explicitly below) ``` +## Source and Target Locations + +| Component | Path | +|---|---| +| Go source code | `golang/` (specifically `golang/nats-server/`) | +| .NET ported version | `dotnet/` | + ## Steps ### Step 1: Initialize the porting database diff --git a/docs/plans/phases/phase-2-verification.md b/docs/plans/phases/phase-2-verification.md index 422be2a..b7edd9b 100644 --- a/docs/plans/phases/phase-2-verification.md +++ b/docs/plans/phases/phase-2-verification.md @@ -14,6 +14,13 @@ proceeding to library mapping and porting. analyzer run. If the source was updated, re-run the Phase 1 analyzer first. - `dotnet`, `sqlite3`, `find`, `grep`, and `wc` are available on your PATH. +## Source and Target Locations + +| Component | Path | +|---|---| +| Go source code | `golang/` (specifically `golang/nats-server/`) | +| .NET ported version | `dotnet/` | + ## Steps ### Step 1: Generate the summary report diff --git a/docs/plans/phases/phase-3-library-mapping.md b/docs/plans/phases/phase-3-library-mapping.md index 8b155d8..41815d9 100644 --- a/docs/plans/phases/phase-3-library-mapping.md +++ b/docs/plans/phases/phase-3-library-mapping.md @@ -13,6 +13,13 @@ returns an empty list and every import has a documented .NET migration path. - Familiarity with both the Go standard library and .NET BCL / NuGet ecosystem. - A working `dotnet` CLI for running PortTracker commands. +## Source and Target Locations + +| Component | Path | +|---|---| +| Go source code | `golang/` (specifically `golang/nats-server/`) | +| .NET ported version | `dotnet/` | + ## Steps ### Step 1: List all unmapped libraries diff --git a/docs/plans/phases/phase-4-dotnet-design.md b/docs/plans/phases/phase-4-dotnet-design.md index 2a8f8c8..f5a54c6 100644 --- a/docs/plans/phases/phase-4-dotnet-design.md +++ b/docs/plans/phases/phase-4-dotnet-design.md @@ -11,31 +11,38 @@ Every module, feature, and test in the porting database must have either a .NET - Phases 1-3 complete: all Go items in the DB, all libraries mapped - Verify with: `dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db` +## Source and Target Locations + +- **Go source code** is located in the `golang/` folder (specifically `golang/nats-server/`) +- **.NET ported version** is located in the `dotnet/` folder + ## Solution Structure Define the .NET solution layout following standard conventions: ``` -src/ - NATS.Server/ # Main server library (all core logic) - Protocol/ # Wire protocol parsing, commands - Subscriptions/ # SubList trie, subject matching - JetStream/ # Stream management, consumers - Cluster/ # Routes, gateways, leaf nodes - Auth/ # Authentication, accounts, JWT - ... - NATS.Server.Host/ # Host/entry point (Program.cs, DI, config) +dotnet/ + ZB.MOM.NatsNet.sln + src/ + ZB.MOM.NatsNet.Server/ # Main server library (all core logic) + Protocol/ # Wire protocol parsing, commands + Subscriptions/ # SubList trie, subject matching + JetStream/ # Stream management, consumers + Cluster/ # Routes, gateways, leaf nodes + Auth/ # Authentication, accounts, JWT + ... + ZB.MOM.NatsNet.Server.Host/ # Host/entry point (Program.cs, DI, config) -tests/ - NATS.Server.Tests/ # Unit tests for NATS.Server - Protocol/ - Subscriptions/ - JetStream/ - ... - NATS.Server.IntegrationTests/ # Cross-module and end-to-end tests + tests/ + ZB.MOM.NatsNet.Server.Tests/ # Unit tests for ZB.MOM.NatsNet.Server + Protocol/ + Subscriptions/ + JetStream/ + ... + ZB.MOM.NatsNet.Server.IntegrationTests/ # Cross-module and end-to-end tests ``` -The `NATS.Server` project holds all portable logic. `NATS.Server.Host` is the thin entry point that wires up dependency injection, configuration, and hosting. Tests mirror the source structure. +The `ZB.MOM.NatsNet.Server` project holds all portable logic. `ZB.MOM.NatsNet.Server.Host` is the thin entry point that wires up dependency injection, configuration, and hosting. Tests mirror the source structure. ## Naming Conventions @@ -45,11 +52,11 @@ Follow these rules consistently when mapping Go items to .NET: |--------|-----------|---------| | Classes | PascalCase | `NatsParser`, `SubList`, `JetStreamController` | | Methods | PascalCase | `TryParse`, `Match`, `ProcessMessage` | -| Namespaces | `NATS.Server.[Module]` | `NATS.Server.Protocol`, `NATS.Server.Subscriptions` | +| Namespaces | `ZB.MOM.NatsNet.Server.[Module]` | `ZB.MOM.NatsNet.Server.Protocol`, `ZB.MOM.NatsNet.Server.Subscriptions` | | Test classes | `[ClassName]Tests` | `NatsParserTests`, `SubListTests` | | Test methods | `[Method]_[Scenario]_[Expected]` | `TryParse_ValidInput_ReturnsTrue` | | Interfaces | `I[Name]` | `IMessageRouter`, `ISubListAccess` | -| Projects | `NATS.Server[.Suffix]` | `NATS.Server`, `NATS.Server.Host` | +| Projects | `ZB.MOM.NatsNet.Server[.Suffix]` | `ZB.MOM.NatsNet.Server`, `ZB.MOM.NatsNet.Server.Host` | Avoid abbreviations unless they are universally understood (e.g., `TCP`, `TLS`, `JWT`). Prefer descriptive names over short ones. @@ -65,8 +72,8 @@ dotnet run --project tools/NatsNet.PortTracker -- module list --db porting.db # Map a module to its .NET target dotnet run --project tools/NatsNet.PortTracker -- module map \ - --project "NATS.Server" \ - --namespace "NATS.Server.Protocol" \ + --project "ZB.MOM.NatsNet.Server" \ + --namespace "ZB.MOM.NatsNet.Server.Protocol" \ --class "NatsParser" \ --db porting.db ``` @@ -75,11 +82,11 @@ Work through all modules systematically. Group related Go files into the same na | Go package/file pattern | .NET namespace | |------------------------|----------------| -| `server/parser.go` | `NATS.Server.Protocol` | -| `server/sublist.go` | `NATS.Server.Subscriptions` | -| `server/jetstream*.go` | `NATS.Server.JetStream` | -| `server/route.go`, `server/gateway.go` | `NATS.Server.Cluster` | -| `server/auth.go`, `server/accounts.go` | `NATS.Server.Auth` | +| `server/parser.go` | `ZB.MOM.NatsNet.Server.Protocol` | +| `server/sublist.go` | `ZB.MOM.NatsNet.Server.Subscriptions` | +| `server/jetstream*.go` | `ZB.MOM.NatsNet.Server.JetStream` | +| `server/route.go`, `server/gateway.go` | `ZB.MOM.NatsNet.Server.Cluster` | +| `server/auth.go`, `server/accounts.go` | `ZB.MOM.NatsNet.Server.Auth` | | `server/pse/` | Likely N/A (Go-specific platform code) | ### Step 2: Map features @@ -92,7 +99,7 @@ dotnet run --project tools/NatsNet.PortTracker -- feature list --module \ - --project "NATS.Server" \ + --project "ZB.MOM.NatsNet.Server" \ --class "NatsParser" \ --method "TryParse" \ --db porting.db @@ -115,7 +122,7 @@ dotnet run --project tools/NatsNet.PortTracker -- test list --module # Map a test dotnet run --project tools/NatsNet.PortTracker -- test map \ - --project "NATS.Server.Tests" \ + --project "ZB.MOM.NatsNet.Server.Tests" \ --class "NatsParserTests" \ --method "TryParse_ValidInput_ReturnsTrue" \ --db porting.db @@ -147,7 +154,7 @@ Items that typically do not need a .NET port: |---------|--------| | `pse_darwin.go`, `pse_linux.go`, `pse_windows.go` | Go-specific platform syscall wrappers; use .NET `System.Diagnostics.Process` instead | | `disk_avail_windows.go`, `disk_avail_linux.go` | Go-specific disk APIs; use .NET `System.IO.DriveInfo` instead | -| Custom logger (`logger.go`, `log.go`) | Replaced by Serilog via `NATS.Server.Host` | +| Custom logger (`logger.go`, `log.go`) | Replaced by Serilog via `ZB.MOM.NatsNet.Server.Host` | | Signal handling (`signal.go`) | Replaced by .NET Generic Host `IHostLifetime` | | Go `sync.Pool`, `sync.Map` wrappers | .NET has `ObjectPool`, `ConcurrentDictionary` built-in | | Build tags / `_test.go` helpers specific to Go test infra | Replaced by xUnit attributes and test fixtures | diff --git a/docs/plans/phases/phase-5-mapping-verification.md b/docs/plans/phases/phase-5-mapping-verification.md index 54768ea..7b849d7 100644 --- a/docs/plans/phases/phase-5-mapping-verification.md +++ b/docs/plans/phases/phase-5-mapping-verification.md @@ -11,6 +11,11 @@ Confirm zero unmapped items, validate all N/A justifications, enforce naming con - Phase 4 complete: all items have .NET mappings or N/A status - Verify with: `dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db` +## Source and Target Locations + +- **Go source code** is located in the `golang/` folder (specifically `golang/nats-server/`) +- **.NET ported version** is located in the `dotnet/` folder + ## Steps ### Step 1: Confirm zero unmapped items @@ -71,13 +76,13 @@ dotnet run --project tools/NatsNet.PortTracker -- module list --db porting.db dotnet run --project tools/NatsNet.PortTracker -- feature list --module --db porting.db ``` -**Namespace hierarchy check**: Namespaces must follow `NATS.Server.[Module]` pattern: +**Namespace hierarchy check**: Namespaces must follow `ZB.MOM.NatsNet.Server.[Module]` pattern: | Valid | Invalid | |-------|---------| -| `NATS.Server.Protocol` | `Protocol` (missing root) | -| `NATS.Server.JetStream` | `NATS.Server.jetstream` (wrong case) | -| `NATS.Server.Subscriptions` | `NATSServer.Subscriptions` (wrong root) | +| `ZB.MOM.NatsNet.Server.Protocol` | `Protocol` (missing root) | +| `ZB.MOM.NatsNet.Server.JetStream` | `ZB.MOM.NatsNet.Server.jetstream` (wrong case) | +| `ZB.MOM.NatsNet.Server.Subscriptions` | `NATSServer.Subscriptions` (wrong root) | **Test naming check**: Test classes must end in `Tests`. Test methods must follow `[Method]_[Scenario]_[Expected]` pattern: @@ -115,14 +120,14 @@ If collisions are found, rename one of the conflicting methods. Common resolutio Verify that test mappings reference the correct test project: ```bash -# All tests should target NATS.Server.Tests or NATS.Server.IntegrationTests +# All tests should target ZB.MOM.NatsNet.Server.Tests or ZB.MOM.NatsNet.Server.IntegrationTests dotnet run --project tools/NatsNet.PortTracker -- test list --db porting.db ``` Check that: -- Unit tests point to `NATS.Server.Tests` -- Integration tests (if any) point to `NATS.Server.IntegrationTests` -- No tests accidentally point to `NATS.Server` (the library project) +- Unit tests point to `ZB.MOM.NatsNet.Server.Tests` +- Integration tests (if any) point to `ZB.MOM.NatsNet.Server.IntegrationTests` +- No tests accidentally point to `ZB.MOM.NatsNet.Server` (the library project) ### Step 6: Run phase check @@ -181,7 +186,7 @@ dotnet run --project tools/NatsNet.PortTracker -- feature map \ - Zero items in `not_started` status without a .NET mapping - All N/A items have a documented, valid reason - All `dotnet_class` and `dotnet_method` values follow PascalCase -- All namespaces follow `NATS.Server.[Module]` hierarchy +- All namespaces follow `ZB.MOM.NatsNet.Server.[Module]` hierarchy - No two features map to the same class + method combination - All tests target the correct test project - `phase check 5` passes with no errors diff --git a/docs/plans/phases/phase-6-porting.md b/docs/plans/phases/phase-6-porting.md index bf86373..8454ff8 100644 --- a/docs/plans/phases/phase-6-porting.md +++ b/docs/plans/phases/phase-6-porting.md @@ -10,13 +10,18 @@ Implement every non-N/A module, feature, and test in the porting database. Work - Phase 5 complete: all mappings verified, no collisions, naming validated - .NET solution structure created: - - `src/NATS.Server/NATS.Server.csproj` - - `src/NATS.Server.Host/NATS.Server.Host.csproj` - - `tests/NATS.Server.Tests/NATS.Server.Tests.csproj` - - `tests/NATS.Server.IntegrationTests/NATS.Server.IntegrationTests.csproj` + - `dotnet/src/ZB.MOM.NatsNet.Server/ZB.MOM.NatsNet.Server.csproj` + - `dotnet/src/ZB.MOM.NatsNet.Server.Host/ZB.MOM.NatsNet.Server.Host.csproj` + - `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ZB.MOM.NatsNet.Server.Tests.csproj` + - `dotnet/tests/ZB.MOM.NatsNet.Server.IntegrationTests/ZB.MOM.NatsNet.Server.IntegrationTests.csproj` - Library dependencies (NuGet packages) added per Phase 3 mappings - Verify readiness: `dotnet run --project tools/NatsNet.PortTracker -- phase check 5 --db porting.db` +## Source and Target Locations + +- **Go source code** is located in the `golang/` folder (specifically `golang/nats-server/`) +- **.NET ported version** is located in the `dotnet/` folder + ## Porting Workflow This is the core loop. Repeat until all items are complete. @@ -44,7 +49,7 @@ dotnet run --project tools/NatsNet.PortTracker -- feature update --status s In the .NET project, create the class and method skeleton based on the mapping: 1. Look up the mapping: `dotnet run --project tools/NatsNet.PortTracker -- feature show --db porting.db` -2. Create the file at the correct path under `src/NATS.Server/` following the namespace hierarchy +2. Create the file at the correct path under `dotnet/src/ZB.MOM.NatsNet.Server/` following the namespace hierarchy 3. Add the class declaration, method signature, and a `throw new NotImplementedException()` body For batch scaffolding of an entire module: @@ -95,8 +100,8 @@ dotnet run --project tools/NatsNet.PortTracker -- feature update --status c If tests exist for this feature, run them: ```bash -dotnet test --filter "FullyQualifiedName~NATS.Server.Tests.Protocol" \ - tests/NATS.Server.Tests/ +dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol" \ + dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ ``` Fix any failures before moving on. diff --git a/docs/plans/phases/phase-7-porting-verification.md b/docs/plans/phases/phase-7-porting-verification.md index 20dd70d..3b53da2 100644 --- a/docs/plans/phases/phase-7-porting-verification.md +++ b/docs/plans/phases/phase-7-porting-verification.md @@ -12,6 +12,11 @@ Every ported module passes its targeted tests. Every item in the database reache - All tests ported and compilable - Verify readiness: `dotnet run --project tools/NatsNet.PortTracker -- phase check 6 --db porting.db` +## Source and Target Locations + +- **Go source code** is located in the `golang/` folder (specifically `golang/nats-server/`) +- **.NET ported version** is located in the `dotnet/` folder + ## Verification Workflow Work through modules one at a time. Do not move to the next module until the current one is fully verified. @@ -41,16 +46,16 @@ Run only the tests for this module using `dotnet test --filter`: ```bash # Filter by namespace (matches all tests in the module's namespace) -dotnet test --filter "FullyQualifiedName~NATS.Server.Tests.Protocol" \ - tests/NATS.Server.Tests/ +dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol" \ + dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ # Filter by test class -dotnet test --filter "FullyQualifiedName~NATS.Server.Tests.Protocol.NatsParserTests" \ - tests/NATS.Server.Tests/ +dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol.NatsParserTests" \ + dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ # Filter by specific test method -dotnet test --filter "FullyQualifiedName~NATS.Server.Tests.Protocol.NatsParserTests.TryParse_ValidInput_ReturnsTrue" \ - tests/NATS.Server.Tests/ +dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol.NatsParserTests.TryParse_ValidInput_ReturnsTrue" \ + dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ ``` The `--filter` flag uses partial matching on the fully qualified test name. Use the namespace pattern for module-wide runs, and the class or method pattern for debugging specific failures. @@ -67,13 +72,13 @@ When tests fail: 3. **Compare Go and .NET logic.** Open the Go source at the stored line number. Check for translation errors: off-by-one, missing edge cases, different default values. 4. **Fix and re-run.** After fixing, re-run only the failing test: ```bash - dotnet test --filter "FullyQualifiedName~NATS.Server.Tests.Protocol.NatsParserTests.TryParse_EmptyInput_ReturnsFalse" \ - tests/NATS.Server.Tests/ + dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol.NatsParserTests.TryParse_EmptyInput_ReturnsFalse" \ + dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ ``` 5. **Then re-run the full module.** Confirm no regressions: ```bash - dotnet test --filter "FullyQualifiedName~NATS.Server.Tests.Protocol" \ - tests/NATS.Server.Tests/ + dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol" \ + dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ ``` Common failure causes: @@ -117,7 +122,7 @@ After all modules are individually verified, run integration tests that exercise ### Step 7: Run integration tests ```bash -dotnet test tests/NATS.Server.IntegrationTests/ +dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.IntegrationTests/ ``` Integration tests cover scenarios like: @@ -142,7 +147,7 @@ Run both the Go server and the .NET server with the same workload and compare be ``` 2. Start the .NET server: ```bash - dotnet run --project src/NATS.Server.Host -- --port 4223 + dotnet run --project dotnet/src/ZB.MOM.NatsNet.Server.Host -- --port 4223 ``` **Comparison scenarios:** @@ -221,8 +226,8 @@ The issue is at a module boundary. Check: - All non-N/A modules have status `verified` - All non-N/A features have status `verified` - All non-N/A tests have status `verified` -- All targeted tests pass: `dotnet test tests/NATS.Server.Tests/` -- All integration tests pass: `dotnet test tests/NATS.Server.IntegrationTests/` +- All targeted tests pass: `dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/` +- All integration tests pass: `dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.IntegrationTests/` - Key behavioral scenarios produce equivalent results on Go and .NET servers - `phase check 7` passes with no errors - Final report exported and reviewed diff --git a/documentation_rules.md b/documentation_rules.md new file mode 100644 index 0000000..4c03e7a --- /dev/null +++ b/documentation_rules.md @@ -0,0 +1,318 @@ +# Documentation Rules + +This document defines the documentation system for the NATS .NET server project. It provides guidelines for generating, updating, and maintaining project documentation. + +The documentation is intended for internal team reference — explaining what the system is, how it works, how to extend it, and how to debug it. + +## Folder Structure + +``` +Documentation/ +├── Instructions/ # Guidelines for LLMs (meta-documentation) +│ └── (this file serves as the single instructions reference) +│ +├── GettingStarted/ # Onboarding, prerequisites, first run +├── Protocol/ # Wire protocol, parser, command types +├── Subscriptions/ # SubList trie, subject matching, wildcards +├── Server/ # NatsServer orchestrator, NatsClient handler +├── Configuration/ # NatsOptions, appsettings, CLI arguments +├── Operations/ # Deployment, monitoring, health checks, troubleshooting +└── Plans/ # Design documents and implementation plans +``` + +Future module folders (add as modules are ported): + +``` +├── Authentication/ # Auth mechanisms, NKeys, JWT, accounts +├── Clustering/ # Routes, gateways, leaf nodes +├── JetStream/ # Streams, consumers, storage, RAFT +├── Monitoring/ # HTTP endpoints (/varz, /connz, etc.) +├── WebSocket/ # WebSocket transport +└── TLS/ # TLS configuration and setup +``` + +--- + +## Style Guide + +### Tone and Voice + +- **Technical and direct** — no marketing language. Avoid "powerful", "robust", "seamless", "blazing fast". +- **Assume the reader is a .NET developer** — don't explain dependency injection, async/await, or LINQ basics. +- **Explain "why" not just "what"** — document reasoning behind patterns and decisions. +- **Use present tense** — "The parser reads..." not "The parser will read..." + +### Formatting Rules + +| Aspect | Convention | +|--------|------------| +| File names | `PascalCase.md` | +| H1 (`#`) | Document title only, Title Case | +| H2 (`##`) | Major sections, Title Case | +| H3+ (`###`) | Subsections, Sentence case | +| Code blocks | Always specify language (`csharp`, `json`, `bash`, `xml`) | +| Code snippets | 5-25 lines typical; include class/method context | +| Cross-references | Relative paths: `[See SubList](../Subscriptions/SubList.md)` | +| Inline code | Backticks for code refs: `NatsServer`, `SubList.Match()`, `NatsOptions` | +| Lists | Bullets for unordered, numbers for sequential steps | +| Tables | For structured reference (config options, command formats) | + +### Naming Conventions + +- Match code terminology exactly: `SubList` not "Subject List", `NatsClient` not "NATS Client Handler" +- Use backticks for all code references: `NatsParser`, `appsettings.json`, `dotnet test` +- Spell out acronyms on first use: "NATS Adaptive Edge Messaging (NATS)" — common acronyms that don't need expansion: API, JSON, TCP, HTTP, TLS, JWT + +### Code Snippet Guidelines + +**Do:** +- Copy snippets from actual source files +- Include enough context (class name, method signature) +- Specify the language in code blocks +- Show 5-25 line examples + +```csharp +// Good — shows class context +public sealed class NatsServer : IMessageRouter, ISubListAccess, IDisposable +{ + public async Task StartAsync(CancellationToken ct) + { + _listener = new Socket(AddressFamily.InterNetwork, SocketType.Stream, ProtocolType.Tcp); + _listener.Bind(new IPEndPoint(IPAddress.Parse(_options.Host), _options.Port)); + _listener.Listen(128); + } +} +``` + +**Don't:** +- Invent example code that doesn't exist in the codebase +- Include 100+ line dumps without explanation +- Use pseudocode when real code is available +- Omit the language specifier on code blocks + +### Structure Conventions + +Every documentation file must include: + +1. **Title and purpose** — H1 heading with 1-2 sentence description +2. **Key concepts** — if the topic requires background understanding +3. **Code examples** — embedded snippets from actual codebase +4. **Configuration** — if the component has configurable options +5. **Related documentation** — links to related topics + +Organize content from general to specific: +1. Overview/introduction +2. Key concepts +3. Basic usage +4. Advanced usage / internals +5. Configuration +6. Troubleshooting +7. Related documentation + +End each document with: +```markdown +## Related Documentation + +- [Related Topic](../Component/Topic.md) +``` + +### What to Avoid + +- Don't document the obvious (e.g., "The constructor creates a new instance") +- Don't duplicate source code comments — reference the file instead +- Don't include temporary information (dates, version numbers, "coming soon") +- Don't over-explain .NET basics + +--- + +## Generating Documentation + +### Document Types + +Each component folder should contain these standard files: + +| File | Purpose | +|------|---------| +| `Overview.md` | What the component does, key concepts, architecture | +| `Development.md` | How to add/modify features, patterns to follow | +| `Configuration.md` | All configurable options with defaults and examples | +| `Troubleshooting.md` | Common issues, error messages, debugging steps | + +Create additional topic-specific files as needed (e.g., `Protocol/Parser.md`, `Subscriptions/SubList.md`). + +### Generation Process + +1. **Identify scope** — which component folder does this belong to? (See Component Map below) +2. **Read source code** — understand the current implementation, identify key classes/methods/patterns, note configuration options +3. **Check existing documentation** — avoid duplication, cross-reference rather than repeat +4. **Write documentation** — follow the style guide, use real code snippets +5. **Verify accuracy** — confirm snippets match source, verify file paths and class names, test commands + +### Creating New Component Folders + +1. Create the folder under `Documentation/` +2. Add at minimum `Overview.md` +3. Add other standard files as content warrants +4. Update the Component Map section below +5. Add cross-references from related documentation + +--- + +## Updating Documentation + +### Update Triggers + +| Code Change | Update These Docs | +|-------------|-------------------| +| New protocol command | `Protocol/` relevant file | +| Parser modified | `Protocol/Parser.md` | +| Subject matching changed | `Subscriptions/SubjectMatch.md` | +| SubList trie modified | `Subscriptions/SubList.md` | +| New subscription type | `Subscriptions/Overview.md` | +| NatsServer changed | `Server/Overview.md` | +| NatsClient changed | `Server/Client.md` | +| Config option added/removed | Component's `Configuration.md` | +| NatsOptions changed | `Configuration/Overview.md` | +| Host startup changed | `Operations/Deployment.md` + `Configuration/` | +| New test patterns | Corresponding component docs | +| Auth mechanism added | `Authentication/` (create if needed) | +| Clustering added | `Clustering/` (create if needed) | + +### Update Process + +1. **Identify affected documentation** — use the Component Map to determine which docs need updating +2. **Read current documentation** — understand existing structure before making changes +3. **Make targeted updates** — only modify sections affected by the code change; don't rewrite unaffected sections +4. **Update code snippets** — if the code change affects documented examples, update them to match +5. **Update cross-references** — add links to newly related docs, remove links to deleted content +6. **Add verification comment** — at the bottom: `` + +### Deletion Handling + +- When code is removed, remove corresponding doc sections +- When code is renamed, update all references (docs, snippets, cross-reference links) +- If an entire feature is removed, delete the doc file and update any index/overview docs +- Search all docs for links to removed content + +### What Not to Update + +- Don't reformat documentation that wasn't affected by the code change +- Don't update examples that still work correctly +- Don't add new content unrelated to the code change +- Don't change writing style in unaffected sections + +--- + +## Component Map + +### Source to Documentation Mapping + +| Source Path | Documentation Folder | +|-------------|---------------------| +| `src/NATS.Server/Protocol/NatsParser.cs` | `Protocol/` | +| `src/NATS.Server/Protocol/NatsProtocol.cs` | `Protocol/` | +| `src/NATS.Server/Subscriptions/SubList.cs` | `Subscriptions/` | +| `src/NATS.Server/Subscriptions/SubjectMatch.cs` | `Subscriptions/` | +| `src/NATS.Server/Subscriptions/Subscription.cs` | `Subscriptions/` | +| `src/NATS.Server/Subscriptions/SubListResult.cs` | `Subscriptions/` | +| `src/NATS.Server/NatsServer.cs` | `Server/` | +| `src/NATS.Server/NatsClient.cs` | `Server/` | +| `src/NATS.Server/NatsOptions.cs` | `Configuration/` | +| `src/NATS.Server.Host/Program.cs` | `Operations/` and `Configuration/` | +| `tests/NATS.Server.Tests/` | Document in corresponding component | +| `golang/nats-server/server/` | Reference material (not documented separately) | + +### Component Details + +#### Protocol/ + +Documents the wire protocol and parser. + +**Source paths:** +- `src/NATS.Server/Protocol/NatsParser.cs` — state machine parser +- `src/NATS.Server/Protocol/NatsProtocol.cs` — constants, ServerInfo, ClientOptions + +**Typical files:** +- `Overview.md` — NATS protocol format, command types, wire format +- `Parser.md` — Parser implementation, `TryParse` flow, state machine +- `Commands.md` — Individual command formats (PUB, SUB, UNSUB, MSG, etc.) + +#### Subscriptions/ + +Documents subject matching and the subscription trie. + +**Source paths:** +- `src/NATS.Server/Subscriptions/SubList.cs` — trie + cache +- `src/NATS.Server/Subscriptions/SubjectMatch.cs` — validation and wildcard matching +- `src/NATS.Server/Subscriptions/Subscription.cs` — subscription model +- `src/NATS.Server/Subscriptions/SubListResult.cs` — match result container + +**Typical files:** +- `Overview.md` — Subject namespace, wildcard rules, queue groups +- `SubList.md` — Trie internals, cache invalidation, thread safety +- `SubjectMatch.md` — Validation rules, wildcard matching algorithm + +#### Server/ + +Documents the server orchestrator and client connection handler. + +**Source paths:** +- `src/NATS.Server/NatsServer.cs` — accept loop, message routing +- `src/NATS.Server/NatsClient.cs` — per-connection read/write, subscription tracking + +**Typical files:** +- `Overview.md` — Server architecture, connection lifecycle, message flow +- `Client.md` — Client connection handling, command dispatch, write serialization +- `MessageRouting.md` — How messages flow from PUB to subscribers + +#### Configuration/ + +Documents server configuration options. + +**Source paths:** +- `src/NATS.Server/NatsOptions.cs` — configuration model +- `src/NATS.Server.Host/Program.cs` — CLI argument parsing, Serilog setup + +**Typical files:** +- `Overview.md` — All options with defaults and descriptions +- `Logging.md` — Serilog configuration, log levels, LogContext usage + +#### Operations/ + +Documents deployment and operational concerns. + +**Source paths:** +- `src/NATS.Server.Host/` — host application + +**Typical files:** +- `Overview.md` — Running the server, CLI arguments +- `Deployment.md` — Deployment procedures +- `Troubleshooting.md` — Common issues and debugging + +#### GettingStarted/ + +Documents onboarding and project overview. + +**Typical files:** +- `Setup.md` — Prerequisites, building, running +- `Architecture.md` — System overview, Go reference mapping +- `Development.md` — Development workflow, testing, contributing + +### Ambiguous Cases + +| Code Type | Document In | +|-----------|-------------| +| Logging setup | `Configuration/Logging.md` | +| Integration tests | `Operations/Testing.md` or corresponding component | +| Shared interfaces (`IMessageRouter`, `ISubListAccess`) | `Server/Overview.md` | +| Go reference code | Don't document separately; reference in `.NET` component docs | + +### Adding New Components + +When a new module is ported (Authentication, Clustering, JetStream, etc.): + +1. Create a new folder under `Documentation/` +2. Add at minimum `Overview.md` +3. Add this mapping table entry +4. Update CLAUDE.md documentation index if it has one +5. Cross-reference from related component docs diff --git a/golang/nats-server b/golang/nats-server new file mode 160000 index 0000000..66e9bbc --- /dev/null +++ b/golang/nats-server @@ -0,0 +1 @@ +Subproject commit 66e9bbc7f8684dd1b31c54ef686924e0841f9846 diff --git a/reports/generate-report.sh b/reports/generate-report.sh new file mode 100755 index 0000000..07f0259 --- /dev/null +++ b/reports/generate-report.sh @@ -0,0 +1,34 @@ +#!/bin/bash +# Generate porting tracker reports +# Writes reports/current.md (always) and reports/report_{commit_id}.md (snapshot) + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" + +DB_PATH="$REPO_ROOT/porting.db" +TRACKER_PROJECT="$REPO_ROOT/tools/NatsNet.PortTracker" +CURRENT_REPORT="$SCRIPT_DIR/current.md" + +# Check if DB exists +if [ ! -f "$DB_PATH" ]; then + echo "Warning: $DB_PATH not found, skipping report generation" + exit 0 +fi + +# Generate current.md +dotnet run --project "$TRACKER_PROJECT" -- report export \ + --format md \ + --output "$CURRENT_REPORT" \ + --db "$DB_PATH" 2>/dev/null || { + echo "Warning: report generation failed, skipping" + exit 0 +} + +# Generate commit-specific snapshot +COMMIT_ID=$(git -C "$REPO_ROOT" rev-parse --short HEAD 2>/dev/null || echo "unknown") +COMMIT_REPORT="$SCRIPT_DIR/report_${COMMIT_ID}.md" +cp "$CURRENT_REPORT" "$COMMIT_REPORT" + +echo "Reports generated: current.md, report_${COMMIT_ID}.md"