dohertj2/natsnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: update project structure, naming, and add reporting infrastructure

Browse Source 
- 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
This commit is contained in:
Joseph Doherty
2026-02-26 06:38:56 -05:00
parent ca6ed0f09f
commit 8d68f63e6c
13 changed files with 547 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
.gitignore vendored
View File

@@ -1,12 +1,29 @@
# SQLite database (local state) # SQLite transient files (WAL mode)
porting.db
porting.db-journal porting.db-journal
porting.db-wal porting.db-wal
porting.db-shm porting.db-shm
# .NET build output # .NET build output
tools/NatsNet.PortTracker/bin/ **/bin/
tools/NatsNet.PortTracker/obj/ **/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 # Go build output
tools/go-analyzer/go-analyzer tools/go-analyzer/go-analyzer
@@ -14,3 +31,10 @@ tools/go-analyzer/go-analyzer
# OS files # OS files
.DS_Store .DS_Store
Thumbs.db Thumbs.db
# IDE files
.idea/
.vscode/*.code-workspace
.vscode/settings.json
.vscode/tasks.json
.vscode/launch.json

3
.gitmodules vendored Normal file
View File

@@ -0,0 +1,3 @@
[submodule "golang/nats-server"]
path = golang/nats-server
url = https://github.com/nats-io/nats-server.git

61
CLAUDE.md Normal file
View File

@@ -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 -- <command> --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.

7
docs/plans/phases/phase-1-decomposition.md
View File

@@ -26,6 +26,13 @@ sqlite3 --version # optional, any 3.x
echo $CGO_ENABLED # should print 1 (or be unset; we set it explicitly below) 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 ## Steps
### Step 1: Initialize the porting database ### Step 1: Initialize the porting database

7
docs/plans/phases/phase-2-verification.md
View File

@@ -14,6 +14,13 @@ proceeding to library mapping and porting.
analyzer run. If the source was updated, re-run the Phase 1 analyzer first. 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. - `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 ## Steps
### Step 1: Generate the summary report ### Step 1: Generate the summary report

7
docs/plans/phases/phase-3-library-mapping.md
View File

@@ -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. - Familiarity with both the Go standard library and .NET BCL / NuGet ecosystem.
- A working `dotnet` CLI for running PortTracker commands. - 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 ## Steps
### Step 1: List all unmapped libraries ### Step 1: List all unmapped libraries

65
docs/plans/phases/phase-4-dotnet-design.md
View File

@@ -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 - 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` - 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 ## Solution Structure
Define the .NET solution layout following standard conventions: Define the .NET solution layout following standard conventions:
``` ```
src/ dotnet/
NATS.Server/ # Main server library (all core logic) ZB.MOM.NatsNet.sln
Protocol/ # Wire protocol parsing, commands src/
Subscriptions/ # SubList trie, subject matching ZB.MOM.NatsNet.Server/ # Main server library (all core logic)
JetStream/ # Stream management, consumers Protocol/ # Wire protocol parsing, commands
Cluster/ # Routes, gateways, leaf nodes Subscriptions/ # SubList trie, subject matching
Auth/ # Authentication, accounts, JWT JetStream/ # Stream management, consumers
... Cluster/ # Routes, gateways, leaf nodes
NATS.Server.Host/ # Host/entry point (Program.cs, DI, config) Auth/ # Authentication, accounts, JWT
...
ZB.MOM.NatsNet.Server.Host/ # Host/entry point (Program.cs, DI, config)
tests/ tests/
NATS.Server.Tests/ # Unit tests for NATS.Server ZB.MOM.NatsNet.Server.Tests/ # Unit tests for ZB.MOM.NatsNet.Server
Protocol/ Protocol/
Subscriptions/ Subscriptions/
JetStream/ JetStream/
... ...
NATS.Server.IntegrationTests/ # Cross-module and end-to-end tests 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 ## Naming Conventions
@@ -45,11 +52,11 @@ Follow these rules consistently when mapping Go items to .NET:
|--------|-----------|---------| |--------|-----------|---------|
| Classes | PascalCase | `NatsParser`, `SubList`, `JetStreamController` | | Classes | PascalCase | `NatsParser`, `SubList`, `JetStreamController` |
| Methods | PascalCase | `TryParse`, `Match`, `ProcessMessage` | | 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 classes | `[ClassName]Tests` | `NatsParserTests`, `SubListTests` |
| Test methods | `[Method]_[Scenario]_[Expected]` | `TryParse_ValidInput_ReturnsTrue` | | Test methods | `[Method]_[Scenario]_[Expected]` | `TryParse_ValidInput_ReturnsTrue` |
| Interfaces | `I[Name]` | `IMessageRouter`, `ISubListAccess` | | 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. 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 # Map a module to its .NET target
dotnet run --project tools/NatsNet.PortTracker -- module map <id> \ dotnet run --project tools/NatsNet.PortTracker -- module map <id> \
--project "NATS.Server" \ --project "ZB.MOM.NatsNet.Server" \
--namespace "NATS.Server.Protocol" \ --namespace "ZB.MOM.NatsNet.Server.Protocol" \
--class "NatsParser" \ --class "NatsParser" \
--db porting.db --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 | | Go package/file pattern | .NET namespace |
|------------------------|----------------| |------------------------|----------------|
| `server/parser.go` | `NATS.Server.Protocol` | | `server/parser.go` | `ZB.MOM.NatsNet.Server.Protocol` |
| `server/sublist.go` | `NATS.Server.Subscriptions` | | `server/sublist.go` | `ZB.MOM.NatsNet.Server.Subscriptions` |
| `server/jetstream*.go` | `NATS.Server.JetStream` | | `server/jetstream*.go` | `ZB.MOM.NatsNet.Server.JetStream` |
| `server/route.go`, `server/gateway.go` | `NATS.Server.Cluster` | | `server/route.go`, `server/gateway.go` | `ZB.MOM.NatsNet.Server.Cluster` |
| `server/auth.go`, `server/accounts.go` | `NATS.Server.Auth` | | `server/auth.go`, `server/accounts.go` | `ZB.MOM.NatsNet.Server.Auth` |
| `server/pse/` | Likely N/A (Go-specific platform code) | | `server/pse/` | Likely N/A (Go-specific platform code) |
### Step 2: Map features ### Step 2: Map features
@@ -92,7 +99,7 @@ dotnet run --project tools/NatsNet.PortTracker -- feature list --module <module_
# Map a feature # Map a feature
dotnet run --project tools/NatsNet.PortTracker -- feature map <id> \ dotnet run --project tools/NatsNet.PortTracker -- feature map <id> \
--project "NATS.Server" \ --project "ZB.MOM.NatsNet.Server" \
--class "NatsParser" \ --class "NatsParser" \
--method "TryParse" \ --method "TryParse" \
--db porting.db --db porting.db
@@ -115,7 +122,7 @@ dotnet run --project tools/NatsNet.PortTracker -- test list --module <module_id>
# Map a test # Map a test
dotnet run --project tools/NatsNet.PortTracker -- test map <id> \ dotnet run --project tools/NatsNet.PortTracker -- test map <id> \
--project "NATS.Server.Tests" \ --project "ZB.MOM.NatsNet.Server.Tests" \
--class "NatsParserTests" \ --class "NatsParserTests" \
--method "TryParse_ValidInput_ReturnsTrue" \ --method "TryParse_ValidInput_ReturnsTrue" \
--db porting.db --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 | | `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 | | `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` | | Signal handling (`signal.go`) | Replaced by .NET Generic Host `IHostLifetime` |
| Go `sync.Pool`, `sync.Map` wrappers | .NET has `ObjectPool<T>`, `ConcurrentDictionary<K,V>` built-in | | Go `sync.Pool`, `sync.Map` wrappers | .NET has `ObjectPool<T>`, `ConcurrentDictionary<K,V>` built-in |
| Build tags / `_test.go` helpers specific to Go test infra | Replaced by xUnit attributes and test fixtures | | Build tags / `_test.go` helpers specific to Go test infra | Replaced by xUnit attributes and test fixtures |

23
docs/plans/phases/phase-5-mapping-verification.md
View File

@@ -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 - 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` - 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 ## Steps
### Step 1: Confirm zero unmapped items ### 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 <id> --db porting.db dotnet run --project tools/NatsNet.PortTracker -- feature list --module <id> --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 | | Valid | Invalid |
|-------|---------| |-------|---------|
| `NATS.Server.Protocol` | `Protocol` (missing root) | | `ZB.MOM.NatsNet.Server.Protocol` | `Protocol` (missing root) |
| `NATS.Server.JetStream` | `NATS.Server.jetstream` (wrong case) | | `ZB.MOM.NatsNet.Server.JetStream` | `ZB.MOM.NatsNet.Server.jetstream` (wrong case) |
| `NATS.Server.Subscriptions` | `NATSServer.Subscriptions` (wrong root) | | `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: **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: Verify that test mappings reference the correct test project:
```bash ```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 dotnet run --project tools/NatsNet.PortTracker -- test list --db porting.db
``` ```
Check that: Check that:
- Unit tests point to `NATS.Server.Tests` - Unit tests point to `ZB.MOM.NatsNet.Server.Tests`
- Integration tests (if any) point to `NATS.Server.IntegrationTests` - Integration tests (if any) point to `ZB.MOM.NatsNet.Server.IntegrationTests`
- No tests accidentally point to `NATS.Server` (the library project) - No tests accidentally point to `ZB.MOM.NatsNet.Server` (the library project)
### Step 6: Run phase check ### Step 6: Run phase check
@@ -181,7 +186,7 @@ dotnet run --project tools/NatsNet.PortTracker -- feature map <id> \
- Zero items in `not_started` status without a .NET mapping - Zero items in `not_started` status without a .NET mapping
- All N/A items have a documented, valid reason - All N/A items have a documented, valid reason
- All `dotnet_class` and `dotnet_method` values follow PascalCase - 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 - No two features map to the same class + method combination
- All tests target the correct test project - All tests target the correct test project
- `phase check 5` passes with no errors - `phase check 5` passes with no errors

19
docs/plans/phases/phase-6-porting.md
View File

@@ -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 - Phase 5 complete: all mappings verified, no collisions, naming validated
- .NET solution structure created: - .NET solution structure created:
- `src/NATS.Server/NATS.Server.csproj` - `dotnet/src/ZB.MOM.NatsNet.Server/ZB.MOM.NatsNet.Server.csproj`
- `src/NATS.Server.Host/NATS.Server.Host.csproj` - `dotnet/src/ZB.MOM.NatsNet.Server.Host/ZB.MOM.NatsNet.Server.Host.csproj`
- `tests/NATS.Server.Tests/NATS.Server.Tests.csproj` - `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ZB.MOM.NatsNet.Server.Tests.csproj`
- `tests/NATS.Server.IntegrationTests/NATS.Server.IntegrationTests.csproj` - `dotnet/tests/ZB.MOM.NatsNet.Server.IntegrationTests/ZB.MOM.NatsNet.Server.IntegrationTests.csproj`
- Library dependencies (NuGet packages) added per Phase 3 mappings - Library dependencies (NuGet packages) added per Phase 3 mappings
- Verify readiness: `dotnet run --project tools/NatsNet.PortTracker -- phase check 5 --db porting.db` - 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 ## Porting Workflow
This is the core loop. Repeat until all items are complete. This is the core loop. Repeat until all items are complete.
@@ -44,7 +49,7 @@ dotnet run --project tools/NatsNet.PortTracker -- feature update <id> --status s
In the .NET project, create the class and method skeleton based on the mapping: 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 <id> --db porting.db` 1. Look up the mapping: `dotnet run --project tools/NatsNet.PortTracker -- feature show <id> --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 3. Add the class declaration, method signature, and a `throw new NotImplementedException()` body
For batch scaffolding of an entire module: For batch scaffolding of an entire module:
@@ -95,8 +100,8 @@ dotnet run --project tools/NatsNet.PortTracker -- feature update <id> --status c
If tests exist for this feature, run them: If tests exist for this feature, run them:
```bash ```bash
dotnet test --filter "FullyQualifiedName~NATS.Server.Tests.Protocol" \ dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol" \
tests/NATS.Server.Tests/ dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
``` ```
Fix any failures before moving on. Fix any failures before moving on.

33
docs/plans/phases/phase-7-porting-verification.md
View File

@@ -12,6 +12,11 @@ Every ported module passes its targeted tests. Every item in the database reache
- All tests ported and compilable - All tests ported and compilable
- Verify readiness: `dotnet run --project tools/NatsNet.PortTracker -- phase check 6 --db porting.db` - 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 ## Verification Workflow
Work through modules one at a time. Do not move to the next module until the current one is fully verified. 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 ```bash
# Filter by namespace (matches all tests in the module's namespace) # Filter by namespace (matches all tests in the module's namespace)
dotnet test --filter "FullyQualifiedName~NATS.Server.Tests.Protocol" \ dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol" \
tests/NATS.Server.Tests/ dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
# Filter by test class # Filter by test class
dotnet test --filter "FullyQualifiedName~NATS.Server.Tests.Protocol.NatsParserTests" \ dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol.NatsParserTests" \
tests/NATS.Server.Tests/ dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
# Filter by specific test method # Filter by specific test method
dotnet test --filter "FullyQualifiedName~NATS.Server.Tests.Protocol.NatsParserTests.TryParse_ValidInput_ReturnsTrue" \ dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol.NatsParserTests.TryParse_ValidInput_ReturnsTrue" \
tests/NATS.Server.Tests/ 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. 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. 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: 4. **Fix and re-run.** After fixing, re-run only the failing test:
```bash ```bash
dotnet test --filter "FullyQualifiedName~NATS.Server.Tests.Protocol.NatsParserTests.TryParse_EmptyInput_ReturnsFalse" \ dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol.NatsParserTests.TryParse_EmptyInput_ReturnsFalse" \
tests/NATS.Server.Tests/ dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
``` ```
5. **Then re-run the full module.** Confirm no regressions: 5. **Then re-run the full module.** Confirm no regressions:
```bash ```bash
dotnet test --filter "FullyQualifiedName~NATS.Server.Tests.Protocol" \ dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol" \
tests/NATS.Server.Tests/ dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
``` ```
Common failure causes: Common failure causes:
@@ -117,7 +122,7 @@ After all modules are individually verified, run integration tests that exercise
### Step 7: Run integration tests ### Step 7: Run integration tests
```bash ```bash
dotnet test tests/NATS.Server.IntegrationTests/ dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.IntegrationTests/
``` ```
Integration tests cover scenarios like: 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: 2. Start the .NET server:
```bash ```bash
dotnet run --project src/NATS.Server.Host -- --port 4223 dotnet run --project dotnet/src/ZB.MOM.NatsNet.Server.Host -- --port 4223
``` ```
**Comparison scenarios:** **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 modules have status `verified`
- All non-N/A features have status `verified` - All non-N/A features have status `verified`
- All non-N/A tests have status `verified` - All non-N/A tests have status `verified`
- All targeted tests pass: `dotnet test tests/NATS.Server.Tests/` - All targeted tests pass: `dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/`
- All integration tests pass: `dotnet test tests/NATS.Server.IntegrationTests/` - All integration tests pass: `dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.IntegrationTests/`
- Key behavioral scenarios produce equivalent results on Go and .NET servers - Key behavioral scenarios produce equivalent results on Go and .NET servers
- `phase check 7` passes with no errors - `phase check 7` passes with no errors
- Final report exported and reviewed - Final report exported and reviewed

318
documentation_rules.md Normal file
View File

@@ -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: `<!-- Last verified against codebase: YYYY-MM-DD -->`
### 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

1
golang/nats-server Submodule

Submodule golang/nats-server added at 66e9bbc7f8

34
reports/generate-report.sh Executable file
View File

@@ -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"