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

docs(audit): apply per-cluster judgment fixes across living docs

Browse Source 
Resolve audit findings: correct WorkerEnvelope proto/route/metric/session
facts; rewrite auth (ZB.MOM.WW.Auth migration), dashboard (ZB.MOM.WW.Theme),
and StyleGuide (foreign-project copy-paste); document alarm subsystem, Ldap
options, and gateway alarm broker; fix client CLI flags and package paths.
This commit is contained in:
Joseph Doherty
2026-06-03 16:01:28 -04:00
parent f84e0c3474
commit e541339c07
29 changed files with 1102 additions and 432 deletions
Download Patch File Download Diff File Expand all files Collapse all files
StyleGuide.md
+76 -55
View File
@@ -1,42 +1,48 @@
# Documentation Style Guide
This guide defines writing conventions and formatting rules for all ScadaBridge documentation.
This guide defines writing conventions and formatting rules for all MXAccess
Gateway (`mxaccessgw`) 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.
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.
> The `SessionManager` launches one worker per session and tracks it through the
> session state machine.
**Avoid:**
> The ScadaGatewayActor is a really powerful component that helps manage all your SCADA connections efficiently!
> The SessionManager is a really powerful component that helps manage all your
> MXAccess 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.
> The worker pumps Windows messages on its STA thread because a plain blocking
> queue does not let MXAccess COM events deliver.
**Avoid:**
> Health checks use a 5-second timeout.
> The worker pumps Windows messages on its STA thread.
### Use Present Tense
Describe what the code does, not what it will do.
**Good:**
> The actor validates the message before processing.
> The gateway terminates orphaned workers on startup.
**Avoid:**
> The actor will validate the message before processing.
> The gateway will terminate orphaned workers on startup.
### No Marketing Language
This is internal technical documentation. Avoid superlatives and promotional language.
This is internal technical documentation. Avoid superlatives and promotional
language.
**Avoid:** "powerful", "robust", "cutting-edge", "seamless", "blazing fast"
@@ -45,10 +51,10 @@ This is internal technical documentation. Avoid superlatives and promotional lan
### File Names
Use `PascalCase.md` for all documentation files:
- `Overview.md`
- `HealthChecks.md`
- `StateMachines.md`
- `SignalR.md`
- `Sessions.md`
- `GatewayConfiguration.md`
- `WorkerSta.md`
- `Diagnostics.md`
### Headings
@@ -58,11 +64,11 @@ Use `PascalCase.md` for all documentation files:
- **H4+ (`####`):** Rarely needed, Sentence case
```markdown
# Actor Health Checks
# Gateway Configuration
## Configuration Options
## Session Options
### Setting the timeout
### Setting the lease timeout
#### Default values
```
@@ -73,40 +79,43 @@ Always specify the language:
````markdown
```csharp
public class MyActor : ReceiveActor { }
public sealed class GatewaySession { }
```
```json
{
"Setting": "value"
"MxGateway": { "Sessions": { "MaxConcurrent": 8 } }
}
```
```bash
dotnet build
```powershell
dotnet build src/ZB.MOM.WW.MxGateway.slnx
```
````
Supported languages: `csharp`, `json`, `bash`, `xml`, `sql`, `yaml`, `html`, `css`, `javascript`
Supported languages: `csharp`, `json`, `bash`, `powershell`, `xml`, `sql`,
`text`, `rust`, `python`, `go`, `proto`, `html`, `css`, `toml`.
### Code Snippets
**Length:** 5-25 lines is typical. Shorter for simple concepts, longer for complete examples.
**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 sealed class GatewaySession
{
public TemplateInstanceActor(TemplateInstanceConfig config)
public GatewaySession(SessionId sessionId, WorkerPipeSession pipe)
{
Receive<StartProcessing>(Handle);
_sessionId = sessionId;
_pipe = pipe;
}
}
// Avoid - orphaned snippet
Receive<StartProcessing>(Handle);
_pipe = pipe;
```
**Accuracy:** Only use code that exists in the codebase. Never invent examples.
@@ -134,34 +143,34 @@ Use tables for structured reference information:
```markdown
| Option | Default | Description |
|--------|---------|-------------|
| `Timeout` | `5000` | Milliseconds to wait |
| `RetryCount` | `3` | Number of retry attempts |
| `MaxConcurrent` | `8` | Maximum simultaneous sessions |
| `LeaseTimeoutSeconds` | `60` | Idle lease before sweep |
```
### Inline Code
Use backticks for:
- Class names: `ScadaGatewayActor`
- Method names: `HandleMessage()`
- Class names: `SessionManager`
- Method names: `KillWorkerAsync()`
- File names: `appsettings.json`
- Configuration keys: `ScadaBridge:Timeout`
- Configuration keys: `MxGateway:Sessions:MaxConcurrent`
- Command-line commands: `dotnet build`
### Links
Use relative paths for internal documentation:
```markdown
[See the Actors guide](../Akka/Actors.md)
[Configuration options](./Configuration.md)
[See the architecture overview](./gateway.md)
[Configuration options](./docs/GatewayConfiguration.md)
```
Use descriptive link text:
```markdown
<!-- Good -->
See the [Actor Health Checks](../Akka/HealthChecks.md) documentation.
See the [Gateway Configuration](./docs/GatewayConfiguration.md) documentation.
<!-- Avoid -->
See [here](../Akka/HealthChecks.md) for more.
See [here](./docs/GatewayConfiguration.md) for more.
```
## Structure Conventions
@@ -173,9 +182,10 @@ Every document starts with:
2. 1-2 sentence description of purpose
```markdown
# Actor Health Checks
# Worker STA Thread
Health checks monitor actor responsiveness and report status to the ASP.NET Core health check system.
The worker owns one MXAccess COM instance on a dedicated STA thread and pumps
Windows messages so MXAccess events deliver.
```
### Section Organization
@@ -194,15 +204,15 @@ Organize content from general to specific:
Place code examples immediately after the concept they illustrate:
```markdown
## Message Handling
## Session Close
Actors process messages using `Receive<T>` handlers:
The gateway closes a session by killing its worker behind the close gate:
```csharp
Receive<MyMessage>(msg => HandleMyMessage(msg));
await session.KillWorkerWithCloseGateAsync(cancellationToken);
```
Each handler processes one message type...
The close gate serializes concurrent close attempts...
```
### Related Documentation Section
@@ -212,9 +222,9 @@ End each document with links to related topics:
```markdown
## Related Documentation
- [Actor Patterns](./Patterns.md)
- [Health Checks](../Operations/HealthChecks.md)
- [Configuration](../Configuration/Akka.md)
- [Sessions](./docs/Sessions.md)
- [Worker STA Thread](./docs/WorkerSta.md)
- [Gateway Configuration](./docs/GatewayConfiguration.md)
```
## Naming Conventions
@@ -222,30 +232,33 @@ End each document with links to related topics:
### 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"
- `MxStatusProxy` not "MX status proxy"
- `SessionManager` not "session manager"
- `OrphanWorkerTerminator` not "orphan worker terminator"
### Acronyms
Spell out on first use, then use acronym:
> OPC Unified Architecture (OPC UA) provides industrial communication standards. OPC UA servers expose...
> Single-threaded apartment (STA) threads serialize COM calls. STA message
> pumping lets MXAccess events deliver...
Common acronyms that don't need expansion:
- API
- JSON
- SQL
- HTTP/HTTPS
- REST
- JWT
- COM
- gRPC
- IPC
- STA
- UI
### File Paths
Use forward slashes and backticks:
- `src/Infrastructure/Akka/Actors/`
- `src/ZB.MOM.WW.MxGateway.Server/`
- `appsettings.json`
- `Documentation/Akka/Overview.md`
- `docs/GatewayConfiguration.md`
## What to Avoid
@@ -260,13 +273,14 @@ 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.
The constructor accepts a `WorkerPipeSession`, which must be connected before
the session transitions out of `Handshaking`.
```
### 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.
> See `SessionManager.cs` for the open-failure rollback order.
### Don't Include Temporary Information
@@ -278,5 +292,12 @@ Assume readers know:
- Dependency injection
- async/await
- LINQ
- Entity Framework basics
- ASP.NET Core middleware pipeline
- gRPC service basics
## Related Documentation
- [Architecture overview](./gateway.md)
- [Gateway Configuration](./docs/GatewayConfiguration.md)
- [C# Style Guide](./docs/style-guides/CSharpStyleGuide.md)
- [Go Style Guide](./docs/style-guides/GoStyleGuide.md), [Java Style Guide](./docs/style-guides/JavaStyleGuide.md), [Python Style Guide](./docs/style-guides/PythonStyleGuide.md), [Rust Style Guide](./docs/style-guides/RustStyleGuide.md), [Protobuf Style Guide](./docs/style-guides/ProtobufStyleGuide.md)