🚧 WIP

docs/spec/software-spec.md

@@ -5,9 +5,9 @@
 | | |
 |---|---|
 | Project | `wago-modbustcp-simulator-py` |
-| Version | 1.2 (Draft for review) |
+| Version | 1.3 (Draft for review) |
 | Date | 2026-10-03 |
-| Status | Framework phase; module addressing implemented (FR-4.3.11); long-duration simulation (§8), bench mode (§9), web UI (§10) and runtime device configuration (§11) requested |
+| Status | Framework phase; module addressing implemented (FR-4.3.11); service/container deployment implemented (§12); plain-text request tracing implemented (NFR-6.4); clean CLI error handling implemented (NFR-6.5 CLI part); long-duration simulation (§8), bench mode (§9), web UI (§10) and runtime device configuration (§11) requested |
 | Target device simulated | WAGO 750-362 / 750-362/0000-0001 FC Modbus TCP (G4) bus coupler |
 | Reference documents | `docs/m07500362_xxxxxxxx_0en.pdf` (750-362 Modbus TCP manual), Modbus TCP specification (modbus.org) |
 
@@ -434,8 +434,23 @@ stateDiagram-v2
 - NFR-6.1 Performance: sustain ≥ 500 requests/s with ≤ 10 ms added latency (typical FAT bench load).
 - NFR-6.2 Portability: Python 3.11+ on Windows/Linux.
 - NFR-6.3 Determinism: two runs of a scenario with identical inputs and timing produce identical verdict logs (except wall-clock stamps).
-- NFR-6.4 Observability: every Modbus transaction logged with timestamps (sim-time + wall-time), PDU hex, connection id.
-- NFR-6.5 Robustness: malformed frames never crash the server; counted in statistics.
+- NFR-6.4 Observability: every Modbus transaction is observable in
+  verbose mode (`-v` / `WAGO_SIM_VERBOSE`) as plain text — decoded
+  `REQ`/`RSP`/`EXC` lines with transaction id, unit, function name,
+  values, and the WAGO 750-362 register-map meaning of each address
+  (process areas with %IW/%QW mapping per Tables 119/120, read-back
+  mirrors, configuration/constant registers, illegal areas); malformed
+  frames are traced as `RAW` lines with PDU hex. *Implemented*
+  (`src/wago_sim/trace.py`).
+- NFR-6.5 Robustness: malformed frames never crash the server; counted in
+  statistics. Invalid operator input — unknown commands or options,
+  non-numeric or out-of-range port numbers (CLI or
+  `WAGO_SIM_PORT`), missing/unparsable node or scenario files,
+  unwritable report paths — yields a one-line
+  `wago-sim: error: …` on stderr and exit code 2, never a Python
+  traceback; missing report directories are auto-created; unexpected
+  internal errors keep the traceback (logged) for debugging.
+  *CLI part implemented* (tested in `tests/test_cli.py`).
 - NFR-6.6 Configurability: port, bind address, node config, firmware identity registers, MAC-ID configurable without code changes.
 
 ---
@@ -1065,7 +1080,56 @@ This feature request closes that gap.
 
 ---
 
-## 12. Roadmap (post-framework)
+## 12. Deployment — Service / Containerized Operation
+
+> **Status: implemented 2026-10-03 (v1.3).** The simulator can run as a
+> long-lived service: docker/compose container, or a systemd unit on bare
+> metal/VM. Verified: image builds, container answers Modbus requests,
+> and `docker stop` (SIGTERM) shuts down gracefully in < 1 s.
+
+### 12.1 Motivation
+
+A FAT bench simulator is infrastructure: it must start on boot, survive
+restarts, log to the platform's log pipeline, and stop cleanly so a
+connected PLC sees a controlled fieldbus-node failure rather than a
+> hung socket — the exact condition watchdog/FAT fault cases test.
+
+### 12.2 Requirements (all implemented)
+
+- FR-12.2.1: **Environment-variable configuration**: `WAGO_SIM_NODE`,
+  `WAGO_SIM_HOST`, `WAGO_SIM_PORT` configure `serve` without CLI arguments
+  (container `CMD ["wago-sim", "serve"]` needs zero arguments).
+  Explicit CLI arguments override environment values.
+- FR-12.2.2: **Graceful shutdown**: on SIGINT/SIGTERM (docker stop,
+  systemctl stop) the server closes all client connections and the
+  listening socket via `server.stop()` before exiting — no forced kill,
+  no lingering sockets. Verified: `docker stop` completes in 0.34 s.
+- FR-12.2.3: **Container image** (`Dockerfile`): `python:3.12-slim`,
+  non-root `wago-sim` user, unbuffered stdout logging, baked-in example
+  config for out-of-the-box startup, TCP health check, ~197 MB image.
+- FR-12.2.4: **Compose service** (`docker-compose.yml`): port mapping
+  (5020→502 default; 502 needs privileges on some hosts), read-only
+  mounts for config/scenarios/plugins, writable `out/` for reports,
+  resource limits, log rotation, `restart: unless-stopped`.
+- FR-12.2.5: **systemd unit** (`deploy/wago-sim.service`): dedicated
+  service user, env-var configuration, `Restart=on-failure`, hardened
+  (NoNewPrivileges, ProtectSystem, CAP_NET_BIND_SERVICE for port 502
+  without root).
+- FR-12.2.6: Logs to stdout/stderr only (docker json-file / journald
+  collect them); single-line format, no ANSI colors.
+
+### 12.3 Acceptance criteria (all verified)
+
+1. `docker build -t wago-sim .` succeeds; image ~197 MB.
+2. `docker run -p <host>:502 -e WAGO_SIM_NODE=... wago-sim` serves
+   Modbus (constants `0x2000–0x2008` read correctly from the container).
+3. `docker stop` completes in < 1 s with clean shutdown logs.
+4. `docker compose up -d` starts a healthy service; `down` tears it down.
+5. CLI tests cover env-var configuration and override precedence.
+
+---
+
+## 13. Roadmap (post-framework)
 
 | Phase | Feature |
 |---|---|
@@ -1077,7 +1141,7 @@ This feature request closes that gap.
 
 ---
 
-## 13. References
+## 14. References
 
 - WAGO 750-362 manual `m07500362_xxxxxxxx_0en.pdf`, sections 7.2–7.3 (process image), 11.2 (Modbus), 12.2 (module data architecture)
 - WAGO I/O System 750 system description `m075xxxxx_xxxxxxxx_0en.pdf`