mbproxy: initial commit through Phase 9 (TxId multiplexing)

Adds the mbproxy service end-to-end. Phases 00-08 implement the production-ready single-listener / 1:1-backend transparent Modbus TCP proxy with bidirectional BCD rewriting for the ~54-PLC DL205/DL260 fleet. Phase 9 replaces the connection layer with a single backend socket per PLC plus MBAP TxId rewriting, lifting the H2-ECOM100's 4-concurrent-client cap as an operational ceiling. Phase 9 additions of note: - PlcMultiplexer + UpstreamPipe + TxIdAllocator + CorrelationMap - InFlightRequest with IReadOnlyList<InterestedParty> (load-bearing for Phase 10 read coalescing — do not collapse to a single field) - Per-request watchdog: surfaces Modbus exception 0x0B to upstream on BackendRequestTimeoutMs, defending against lost responses, dead-PLC paths, and pymodbus 3.13.0's concurrent-multiplexed- request bug (its ServerRequestHandler.last_pdu state race) - Status DTO + HTML gain inFlight / maxInFlight / txIdWraps / disconnectCascades / queueDepth (Tier 1.6 in docs/kpi.md) Tests: 263 unit + 38 E2E. Multiplexer correctness under truly concurrent backend traffic is proved against a stub backend in PlcMultiplexerTests; MultiplexerE2ETests paces requests so pymodbus 3.13's single-PDU framer stays in known-good mode. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-14 01:49:35 -04:00
parent 2e937228a0
commit 56eee3c563
105 changed files with 18430 additions and 0 deletions
@@ -0,0 +1,282 @@
+# Documentation Style Guide
+
+This guide defines writing conventions and formatting rules for all ScadaBridge documentation.
+
+## Tone and Voice
+
+### Be Technical and Direct
+
+Write for developers who are familiar with .NET. Don't explain basic concepts like dependency injection or async/await unless they're used in an unusual way.
+
+**Good:**
+> The `ScadaGatewayActor` routes messages to the appropriate `ScadaClientActor` based on the client ID in the message.
+
+**Avoid:**
+> The ScadaGatewayActor is a really powerful component that helps manage all your SCADA connections efficiently!
+
+### Explain "Why" Not Just "What"
+
+Document the reasoning behind patterns and decisions, not just the mechanics.
+
+**Good:**
+> Health checks use a 5-second timeout because actors under heavy load may take several seconds to respond, but longer delays indicate a real problem.
+
+**Avoid:**
+> Health checks use a 5-second timeout.
+
+### Use Present Tense
+
+Describe what the code does, not what it will do.
+
+**Good:**
+> The actor validates the message before processing.
+
+**Avoid:**
+> The actor will validate the message before processing.
+
+### No Marketing Language
+
+This is internal technical documentation. Avoid superlatives and promotional language.
+
+**Avoid:** "powerful", "robust", "cutting-edge", "seamless", "blazing fast"
+
+## Formatting Rules
+
+### File Names
+
+Use `PascalCase.md` for all documentation files:
+- `Overview.md`
+- `HealthChecks.md`
+- `StateMachines.md`
+- `SignalR.md`
+
+### Headings
+
+- **H1 (`#`):** Document title only, Title Case
+- **H2 (`##`):** Major sections, Title Case
+- **H3 (`###`):** Subsections, Sentence case
+- **H4+ (`####`):** Rarely needed, Sentence case
+
+```markdown
+# Actor Health Checks
+
+## Configuration Options
+
+### Setting the timeout
+
+#### Default values
+```
+
+### Code Blocks
+
+Always specify the language:
+
+````markdown
+```csharp
+public class MyActor : ReceiveActor { }
+```
+
+```json
+{
+  "Setting": "value"
+}
+```
+
+```bash
+dotnet build
+```
+````
+
+Supported languages: `csharp`, `json`, `bash`, `xml`, `sql`, `yaml`, `html`, `css`, `javascript`
+
+### Code Snippets
+
+**Length:** 5-25 lines is typical. Shorter for simple concepts, longer for complete examples.
+
+**Context:** Include enough to understand where the code lives:
+
+```csharp
+// Good - shows class context
+public class TemplateInstanceActor : ReceiveActor
+{
+    public TemplateInstanceActor(TemplateInstanceConfig config)
+    {
+        Receive<StartProcessing>(Handle);
+    }
+}
+
+// Avoid - orphaned snippet
+Receive<StartProcessing>(Handle);
+```
+
+**Accuracy:** Only use code that exists in the codebase. Never invent examples.
+
+### Lists
+
+Use bullet points for unordered items:
+```markdown
+- First item
+- Second item
+- Third item
+```
+
+Use numbers for sequential steps:
+```markdown
+1. Do this first
+2. Then do this
+3. Finally do this
+```
+
+### Tables
+
+Use tables for structured reference information:
+
+```markdown
+| Option | Default | Description |
+|--------|---------|-------------|
+| `Timeout` | `5000` | Milliseconds to wait |
+| `RetryCount` | `3` | Number of retry attempts |
+```
+
+### Inline Code
+
+Use backticks for:
+- Class names: `ScadaGatewayActor`
+- Method names: `HandleMessage()`
+- File names: `appsettings.json`
+- Configuration keys: `ScadaBridge:Timeout`
+- Command-line commands: `dotnet build`
+
+### Links
+
+Use relative paths for internal documentation:
+```markdown
+[See the Actors guide](../Akka/Actors.md)
+[Configuration options](./Configuration.md)
+```
+
+Use descriptive link text:
+```markdown
+<!-- Good -->
+See the [Actor Health Checks](../Akka/HealthChecks.md) documentation.
+
+<!-- Avoid -->
+See [here](../Akka/HealthChecks.md) for more.
+```
+
+## Structure Conventions
+
+### Document Opening
+
+Every document starts with:
+1. H1 title
+2. 1-2 sentence description of purpose
+
+```markdown
+# Actor Health Checks
+
+Health checks monitor actor responsiveness and report status to the ASP.NET Core health check system.
+```
+
+### Section Organization
+
+Organize content from general to specific:
+1. Overview/introduction
+2. Key concepts (if needed)
+3. Basic usage
+4. Advanced usage
+5. Configuration
+6. Troubleshooting
+7. Related documentation
+
+### Code Example Placement
+
+Place code examples immediately after the concept they illustrate:
+
+```markdown
+## Message Handling
+
+Actors process messages using `Receive<T>` handlers:
+
+```csharp
+Receive<MyMessage>(msg => HandleMyMessage(msg));
+```
+
+Each handler processes one message type...
+```
+
+### Related Documentation Section
+
+End each document with links to related topics:
+
+```markdown
+## Related Documentation
+
+- [Actor Patterns](./Patterns.md)
+- [Health Checks](../Operations/HealthChecks.md)
+- [Configuration](../Configuration/Akka.md)
+```
+
+## Naming Conventions
+
+### Match Code Exactly
+
+Use the exact names from source code:
+- `TemplateInstanceActor` not "Template Instance Actor"
+- `ScadaGatewayActor` not "SCADA Gateway Actor"
+- `IRequiredActor<T>` not "required actor interface"
+
+### Acronyms
+
+Spell out on first use, then use acronym:
+> OPC Unified Architecture (OPC UA) provides industrial communication standards. OPC UA servers expose...
+
+Common acronyms that don't need expansion:
+- API
+- JSON
+- SQL
+- HTTP/HTTPS
+- REST
+- JWT
+- UI
+
+### File Paths
+
+Use forward slashes and backticks:
+- `src/Infrastructure/Akka/Actors/`
+- `appsettings.json`
+- `Documentation/Akka/Overview.md`
+
+## What to Avoid
+
+### Don't Document the Obvious
+
+```markdown
+<!-- Avoid -->
+## Constructor
+
+The constructor creates a new instance of the class.
+
+<!-- Better - only document if there's something notable -->
+## Constructor
+
+The constructor accepts an `IActorRef` for the gateway actor, which must be resolved before actor creation.
+```
+
+### Don't Duplicate Source Code Comments
+
+If code has good comments, reference the file rather than copying:
+> See `ScadaGatewayActor.cs` lines 45-60 for the message routing logic.
+
+### Don't Include Temporary Information
+
+Avoid dates, version numbers, or "coming soon" notes that will become stale.
+
+### Don't Over-Explain .NET Basics
+
+Assume readers know:
+- Dependency injection
+- async/await
+- LINQ
+- Entity Framework basics
+- ASP.NET Core middleware pipeline