[boeboe]

Summary

modbusctl 3.1.0: record and replay every read function of the Modbus specification on go-modbus v1.7.1 and go-modbus-capture (MBCAP). Vendor and unknown function codes are not supported anywhere. The mcap command group becomes capture, and MCAP v1 references are removed.

Dependencies: go-modbus v1.7.1 (v1.7.1 removes RawRequestHandler, which this PR does not use) and go-modbus-capture v0.0.2. Its capture.CheckPDUs accepts only the spec read functions in every reader and writer; capfile.IsSpecRead builds on capture.IsReadFunction with the same FC08/FC43 rules. A file the library rejects for a sample's function code is still reported as capture_unsupported_function (exit 3), not as a corrupt file.

Record and replay

• client record takes a plan (--blocks-file). Entries with function may use FC01–04, FC07, FC08 (data-returning sub-functions 0x00, 0x02, 0x0B–0x12), FC11, FC12, FC17, FC20, FC24 or FC43/14. Plain address blocks work as before. Anything else is refused before it is sent (internal/plan). Each request uses the retry loop of reads.
• server static / server replay serve FC08, FC17, FC20 and FC24 through go-modbus v1.7.1's typed handlers, alongside FC01–04, FC07, FC11, FC12 and FC43. No RawRequestHandler: go-modbus answers every other function code, vendor and unknown ones included, with Illegal Function.
• Loading rejects a capture holding a non-spec sample (capture_unsupported_function, exit 3), and the recorder never writes one.
• --listen on both servers (default: every interface). The "🚀 Serving" line is printed once the listener is bound.

MCAP v1 removal

• Commands: modbusctl mcap … → modbusctl capture … (decode, extract, strings, frequencies). info, verify and convert are removed because they duplicate mbcapctl; the README points to it. internal/mcap → internal/analysis.
• JSON and error codes: mcap_output_path → capture_output_path; mcap_load_failed / mcap_write_failed → capture_load_failed / capture_write_failed.
• Files: Docker volume /captures; docker-compose.yml, Makefile and .gitignore name .mbcap. ALGOS, CONTRIBUTING, SECURITY and docs updated. The README says once that 2.x .mcap files are not read.
• Docs: the README links go-modbus-capture's FORMAT.md and mbcapctl instead of repeating them, and documents the plan format. RELEASE.md has a v3.1.0 entry with the CLI renames listed as breaking.

The intermittent internal/modbus failure

Root cause: a port race in the test helpers. They bound 127.0.0.1:0, closed it, and started the server on 0.0.0.0:N. Under load another test's socket took N in between. Then either the bind failed (address already in use), or, on macOS, the wildcard bind succeeded next to another test's 127.0.0.1:N listener: the readiness probe connected to that listener and the test client talked to the wrong device (unexpected EOF).

Evidence: -race -count=50 -cpu 1,2,8 on the old code under load gave 4 failures, all this race (two address already in use, two unexpected EOF).

Fix:

• Test servers listen on 127.0.0.1 exactly (--listen).
• Readiness is the server's own "Serving" line after the bind, not a probe connection.
• Only a bind that fails with EADDRINUSE moves to another port.
• TestCollServer_portTakenOnLoopback pins this down.

Tests

• TestRoundTrip_everyFunction: record → file → replay for every supported function. Sources: a go-modbus v1.7.1 server, and mbtest over tcp, rtuovertcp and udp. Each file passes mbcapctl verify; static and replay servers answer byte for byte.
• TestRoundTrip_textEncodings: mbcapctl convert to .mbcap.jsonl and .mbcap.csv serves the same.
• TestChaosRoundTrip_everyFunction: busy, dropped, closed, truncated and late answers over tcp and rtuovertcp. Only valid answers the device actually sent are recorded.
• TestParallelRoundTrip_everyFunction: four devices recorded at once, then 8 clients per recording against static and replay servers.
• mbtest: RTU framing for every spec read function.
• tcp+tls: not covered, because modbusctl's client has no TLS certificate settings (tcp+tls is not usable from the CLI today).
• Checks: make check passes (fmt, staticcheck, golangci-lint 0 issues, vet, -race tests, coverage 96.4%).

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 89.54424% with 39 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/modbus/server.go	75.00%	8 Missing and 10 partials ⚠️
internal/modbus/client.go	86.81%	10 Missing and 2 partials ⚠️
internal/validate/validate.go	75.00%	2 Missing and 2 partials ⚠️
internal/capfile/functions.go	90.00%	2 Missing and 1 partial ⚠️
internal/plan/plan.go	98.00%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!