dc3e162608
Generated design docs and implementation plans via Codex for: - Batch 13: FileStore Read/Query - Batch 14: FileStore Write/Lifecycle - Batch 15: MsgBlock + ConsumerFileStore - Batch 18: Server Core - Batch 19: Accounts Core - Batch 20: Accounts Resolvers - Batch 21: Events + MsgTrace - Batch 22: Monitoring All plans include mandatory verification protocol and anti-stub guardrails. Updated batches.md with file paths and planned status.
125 lines
6.0 KiB
Markdown
125 lines
6.0 KiB
Markdown
# Batch 20 Accounts Resolvers Design
|
|
|
|
## Context
|
|
|
|
- Batch: `20` (`Accounts Resolvers`)
|
|
- Scope: `38` features, `98` tests
|
|
- Dependency: Batch `19` (`Accounts Core`)
|
|
- Primary Go reference: `golang/nats-server/server/accounts.go`
|
|
- Primary .NET targets:
|
|
- `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountResolver.cs`
|
|
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Accounts.cs`
|
|
- `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/AccountTypes.cs`
|
|
- `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs`
|
|
|
|
Batch 20 closes resolver-focused account behavior that Batch 19 intentionally deferred: resolver wiring, directory/cache resolver behavior, account-claim refresh paths, service-latency sampling helpers, operator-key validation helpers, and update/list/delete request handling.
|
|
|
|
## Goals
|
|
|
|
1. Port all 38 mapped features from `server/accounts.go` with behavior parity and no placeholders.
|
|
2. Port or verify all 98 mapped tests as real behavioral tests (or keep deferred with explicit blocker reason).
|
|
3. Enforce evidence-based status movement (`deferred/not_started -> stub -> complete -> verified`) with strict guardrails.
|
|
4. Preserve existing .NET architecture (partial `NatsServer`, resolver types, existing account models) and avoid speculative refactors.
|
|
|
|
## Non-Goals
|
|
|
|
- No broad refactor of account architecture into new modules.
|
|
- No cross-batch JetStream/cluster rearchitecture beyond what Batch 20 features require.
|
|
- No status inflation via stubs or placeholder tests.
|
|
|
|
## Approaches Considered
|
|
|
|
### Approach A (Recommended): Incremental in-place port with feature-first then test verification
|
|
|
|
Implement features in existing files grouped by behavior and Go line proximity (2 groups, 19 IDs each), run verification gates after each group, then complete mapped test classes in focused waves.
|
|
|
|
Pros:
|
|
- Lowest merge risk and minimal structural churn.
|
|
- Keeps audit traceability from feature ID -> Go range -> .NET method.
|
|
- Works with existing partial implementations and comments in `AccountResolver.cs` and `NatsServer.Accounts.cs`.
|
|
|
|
Cons:
|
|
- Resolver behavior spans multiple files, so discipline is required to avoid mixed concerns in a single commit.
|
|
|
|
### Approach B: Split resolver code into additional partial classes before feature work
|
|
|
|
Create new files such as `NatsServer.AccountResolver.cs` and `AccountResolver.Sync.cs`, then implement features.
|
|
|
|
Pros:
|
|
- Cleaner long-term separation.
|
|
|
|
Cons:
|
|
- Adds structural churn while behavior is still moving.
|
|
- Harder to compare with existing tracker mappings and current code layout.
|
|
|
|
### Approach C: Signature-first scaffolding, behavior later
|
|
|
|
Add all signatures and minimal bodies quickly, then fill behavior later.
|
|
|
|
Pros:
|
|
- Fast initial check-ins.
|
|
|
|
Cons:
|
|
- Violates anti-stub constraints and verification integrity.
|
|
- Creates false progress.
|
|
|
|
Decision: **Approach A**.
|
|
|
|
## Proposed Design
|
|
|
|
### 1. Feature Implementation Shape
|
|
|
|
Implement Batch 20 features in current target files:
|
|
|
|
- `AccountTypes.cs`: enum/string/latency helpers (`ServiceRespType.String`, `ServiceLatency.merge`, `NewMapDest`, sanitization helpers).
|
|
- `Account.cs`: account-local helpers (`setExportAuth`, sampling/header helpers, service import/export response tracking helpers, `authAccounts`, operator/claim helpers).
|
|
- `NatsServer.Accounts.cs`: resolver integration methods (`SetAccountResolver`, `UpdateAccountClaims`, `updateAccountClaimsWithRefresh`, server fetch/update flows).
|
|
- `AccountResolver.cs`: default resolver store behavior, memory/url/dir/cache resolver fetch/store/reload/start wiring and option handling.
|
|
|
|
### 2. Feature Grouping (Max ~20 IDs Each)
|
|
|
|
- Group 1 (19 IDs): `150,183,197,208,209,215,250,251,252,253,258,259,260,261,306,307,310,316,318`
|
|
- Group 2 (19 IDs): `319,320,326,327,328,330,331,334,335,336,337,338,339,341,343,345,346,347,349`
|
|
|
|
This keeps each implementation wave auditable and within the requested size limit.
|
|
|
|
### 3. Test Strategy (98 IDs)
|
|
|
|
Port tests in existing backlog classes, then gate feature verification on passing related tests:
|
|
|
|
- High-volume classes: `ConfigReloaderTests` (40), `NatsConsumerTests` (16), `JetStreamEngineTests` (12), `JwtProcessorTests` (9).
|
|
- Medium/small classes: `AccountTests` (4), `EventsHandlerTests` (3), `MonitoringHandlerTests` (2), `MqttHandlerTests` (2), and single-test classes (`ConcurrencyTests2`, `GatewayHandlerTests`, `JetStreamBatchingTests`, `JetStreamFileStoreTests`, `MqttExternalTests`, `NatsServerTests`).
|
|
|
|
Tests remain in `ImplBacklog/*.Impltests.cs` unless a mapped test already belongs in an existing non-backlog class.
|
|
|
|
### 4. Status and Evidence Model
|
|
|
|
- Mark active IDs as `stub` only when implementation starts.
|
|
- Promote to `complete` only after per-feature loop + group build gate + related targeted tests.
|
|
- Promote to `verified` only after mapped test gate passes and stub scans are clean.
|
|
- If blocked, keep `deferred` with explicit reason; do not add placeholders.
|
|
|
|
## Error Handling and Concurrency Notes
|
|
|
|
- Preserve lock and lifecycle discipline already present in `NatsServer`/`Account` code.
|
|
- Use existing exception-return conventions for account validation/fetch paths.
|
|
- Keep async resolver API contracts with `CancellationToken`.
|
|
- Avoid introducing blocking waits in newly async paths beyond established project conventions.
|
|
|
|
## Risks and Mitigations
|
|
|
|
- Risk: hidden dependency on not-yet-ported event/system wiring.
|
|
- Mitigation: explicit deferred status with reason and no stubs.
|
|
- Risk: broad regression surface (98 mapped tests across many classes).
|
|
- Mitigation: class-by-class test waves plus mandatory full checkpoint runs.
|
|
- Risk: false positives from legacy TODO comments in untouched files.
|
|
- Mitigation: baseline stub-scan snapshot and fail only on new violations in touched code.
|
|
|
|
## Success Criteria
|
|
|
|
1. All 38 Batch 20 feature IDs are `verified` or `deferred` with explicit blocker notes.
|
|
2. All 98 Batch 20 test IDs are `verified` or `deferred` with explicit blocker notes.
|
|
3. No newly introduced stub patterns in touched source or test files.
|
|
4. Build/test evidence exists for each status-update chunk.
|
|
5. Batch 20 can be completed through PortTracker validation without override except justified blockers.
|