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
This commit is contained in:
Joseph Doherty
32
.gitignore
vendored
32
.gitignore
vendored
@@ -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
|
||||
|
||||
3
.gitmodules
vendored
Normal file
3
.gitmodules
vendored
Normal 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
61
CLAUDE.md
Normal 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.
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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:
|
||||
|
||||
```
|
||||
dotnet/
|
||||
ZB.MOM.NatsNet.sln
|
||||
src/
|
||||
NATS.Server/ # Main server library (all core logic)
|
||||
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
|
||||
...
|
||||
NATS.Server.Host/ # Host/entry point (Program.cs, DI, config)
|
||||
ZB.MOM.NatsNet.Server.Host/ # Host/entry point (Program.cs, DI, config)
|
||||
|
||||
tests/
|
||||
NATS.Server.Tests/ # Unit tests for NATS.Server
|
||||
ZB.MOM.NatsNet.Server.Tests/ # Unit tests for ZB.MOM.NatsNet.Server
|
||||
Protocol/
|
||||
Subscriptions/
|
||||
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
|
||||
|
||||
@@ -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 <id> \
|
||||
--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 <module_
|
||||
|
||||
# Map a feature
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature map <id> \
|
||||
--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 <module_id>
|
||||
|
||||
# Map a test
|
||||
dotnet run --project tools/NatsNet.PortTracker -- test map <id> \
|
||||
--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<T>`, `ConcurrentDictionary<K,V>` built-in |
|
||||
| Build tags / `_test.go` helpers specific to Go test infra | Replaced by xUnit attributes and test fixtures |
|
||||
|
||||
@@ -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 <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 |
|
||||
|-------|---------|
|
||||
| `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 <id> \
|
||||
- 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
|
||||
|
||||
@@ -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 <id> --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 <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
|
||||
|
||||
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:
|
||||
|
||||
```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.
|
||||
|
||||
@@ -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
|
||||
|
||||
318
documentation_rules.md
Normal file
318
documentation_rules.md
Normal 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
1
golang/nats-server
Submodule
Submodule golang/nats-server added at 66e9bbc7f8
34
reports/generate-report.sh
Executable file
34
reports/generate-report.sh
Executable 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"
|
||||
Reference in New Issue
Block a user