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

mbproxy: initial commit through Phase 9 (TxId multiplexing)

Browse Source 
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>
This commit is contained in:
Joseph Doherty
2026-05-14 01:49:35 -04:00
parent 2e937228a0
commit 56eee3c563
105 changed files with 18430 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
mbproxy/tests/Mbproxy.Tests/Bcd/BcdCodecTests.cs
+174
View File
@@ -0,0 +1,174 @@
using Mbproxy.Bcd;
using Shouldly;
using Xunit;
namespace Mbproxy.Tests.Bcd;
/// <summary>
/// Unit tests for <see cref="BcdCodec"/> — the allocation-free BCD nibble codec.
///
/// NOTE on allocation profile:
/// BcdCodec is a purely static class operating on value types (ushort, int, tuples).
/// It allocates only when constructing exception objects (the error path), never on
/// the success path. TryGet / hot-path decode callers in Phase 04 will be
/// allocation-free for valid BCD registers.
/// </summary>
[Trait("Category", "Unit")]
public sealed class BcdCodecTests
{
// ── Encode16 ────────────────────────────────────────────────────────────
[Fact]
public void Encode16_1234_Returns_0x1234()
=> BcdCodec.Encode16(1234).ShouldBe((ushort)0x1234);
[Fact]
public void Encode16_0_Returns_0x0000()
=> BcdCodec.Encode16(0).ShouldBe((ushort)0x0000);
[Fact]
public void Encode16_9999_Returns_0x9999()
=> BcdCodec.Encode16(9999).ShouldBe((ushort)0x9999);
[Fact]
public void Encode16_10000_Throws_OutOfRange()
{
Should.Throw<ArgumentOutOfRangeException>(() => BcdCodec.Encode16(10_000))
.ParamName.ShouldBe("value");
}
[Fact]
public void Encode16_Negative_Throws_OutOfRange()
{
Should.Throw<ArgumentOutOfRangeException>(() => BcdCodec.Encode16(-1))
.ParamName.ShouldBe("value");
}
// ── Decode16 ────────────────────────────────────────────────────────────
[Fact]
public void Decode16_0x1234_Returns_1234()
=> BcdCodec.Decode16(0x1234).ShouldBe(1234);
[Fact]
public void Decode16_0x0000_Returns_0()
=> BcdCodec.Decode16(0x0000).ShouldBe(0);
[Fact]
public void Decode16_0x9999_Returns_9999()
=> BcdCodec.Decode16(0x9999).ShouldBe(9999);
[Fact]
public void Decode16_0x123A_Throws_Format()
{
// Nibble 'A' (10) is not a valid BCD digit; message must contain the raw hex value.
var ex = Should.Throw<FormatException>(() => BcdCodec.Decode16(0x123A));
ex.Message.ShouldContain("0x123A", Case.Insensitive);
}
[Fact]
public void Decode16_0x12FA_TwoBadNibbles_Throws_Format()
{
// Two bad nibbles in one register — still throws once with the raw value.
var ex = Should.Throw<FormatException>(() => BcdCodec.Decode16(0x12FA));
ex.Message.ShouldContain("0x12FA", Case.Insensitive);
}
// ── Encode32 ────────────────────────────────────────────────────────────
[Fact]
public void Encode32_12345678_Returns_LowHigh_5678_1234()
{
var (low, high) = BcdCodec.Encode32(12_345_678);
low.ShouldBe((ushort)0x5678);
high.ShouldBe((ushort)0x1234);
}
[Fact]
public void Encode32_0_Returns_LowHigh_0_0()
{
var (low, high) = BcdCodec.Encode32(0);
low.ShouldBe((ushort)0x0000);
high.ShouldBe((ushort)0x0000);
}
[Fact]
public void Encode32_99999999_Returns_LowHigh_9999_9999()
{
var (low, high) = BcdCodec.Encode32(99_999_999);
low.ShouldBe((ushort)0x9999);
high.ShouldBe((ushort)0x9999);
}
[Fact]
public void Encode32_100000000_Throws_OutOfRange()
{
Should.Throw<ArgumentOutOfRangeException>(() => BcdCodec.Encode32(100_000_000))
.ParamName.ShouldBe("value");
}
// ── Decode32 ────────────────────────────────────────────────────────────
[Fact]
public void Decode32_LowHigh_5678_1234_Returns_12345678()
=> BcdCodec.Decode32(0x5678, 0x1234).ShouldBe(12_345_678);
[Fact]
public void Decode32_BadNibble_InLow_Throws()
{
// Low word has a bad nibble; Decode32 must propagate the FormatException.
Should.Throw<FormatException>(() => BcdCodec.Decode32(0xABCD, 0x1234));
}
[Fact]
public void Decode32_BadNibble_InHigh_Throws()
{
Should.Throw<FormatException>(() => BcdCodec.Decode32(0x5678, 0xABCD));
}
// ── Round-trip 16-bit ────────────────────────────────────────────────────
/// <summary>
/// Dense round-trip: boundary values plus every 100th value in [0, 9999].
/// Ensures Decode16(Encode16(v)) == v for all practical inputs.
/// </summary>
[Theory]
[MemberData(nameof(RoundTrip16Values))]
public void RoundTrip16_AllValuesUnder10000(int value)
=> BcdCodec.Decode16(BcdCodec.Encode16(value)).ShouldBe(value);
public static IEnumerable<object[]> RoundTrip16Values()
{
// Every 100th value (0, 100, 200, … 9900) — covers 0 as boundary automatically
for (int v = 0; v <= 9999; v += 100)
yield return [v];
// Additional boundary values not already hit by the stride-100 loop
yield return [1];
yield return [9];
yield return [99];
yield return [999];
yield return [9999];
// Some spot-check midpoints
yield return [1234];
yield return [5678];
yield return [4321];
}
// ── Round-trip 32-bit ────────────────────────────────────────────────────
[Theory]
[InlineData(0)]
[InlineData(1)]
[InlineData(9999)]
[InlineData(10_000)]
[InlineData(99_999_999)]
[InlineData(12_345_678)]
[InlineData(5_000_000)]
public void RoundTrip32_RepresentativeValues(int value)
{
var (low, high) = BcdCodec.Encode32(value);
BcdCodec.Decode32(low, high).ShouldBe(value);
}
}
mbproxy/tests/Mbproxy.Tests/Bcd/BcdTagMapBuilderTests.cs
+318
View File
@@ -0,0 +1,318 @@
using Mbproxy.Bcd;
using Mbproxy.Options;
using Shouldly;
using Xunit;
namespace Mbproxy.Tests.Bcd;
/// <summary>
/// Unit tests for <see cref="BcdTagMapBuilder.Build"/> and the resulting <see cref="BcdTagMap"/>.
/// </summary>
[Trait("Category", "Unit")]
public sealed class BcdTagMapBuilderTests
{
// ── Helpers ──────────────────────────────────────────────────────────────
private static BcdTagListOptions Global(params (ushort addr, byte width)[] tags)
=> new() { Global = tags.Select(t => new BcdTagOptions { Address = t.addr, Width = t.width }).ToList() };
private static PlcBcdOverrides Override(
(ushort addr, byte width)[]? add = null,
ushort[]? remove = null)
=> new()
{
Add = add?.Select(t => new BcdTagOptions { Address = t.addr, Width = t.width }).ToList()
?? [],
Remove = remove ?? [],
};
// ── Build tests ──────────────────────────────────────────────────────────
[Fact]
public void Build_EmptyGlobal_EmptyOverride_ReturnsEmptyMap()
{
var result = BcdTagMapBuilder.Build(new BcdTagListOptions(), perPlc: null);
result.Errors.ShouldBeEmpty();
result.Warnings.ShouldBeEmpty();
result.Map.Count.ShouldBe(0);
result.Map.ShouldBeSameAs(BcdTagMap.Empty);
}
[Fact]
public void Build_GlobalOnly_PopulatesMap()
{
var global = Global((1072, 16), (1080, 32));
var result = BcdTagMapBuilder.Build(global, perPlc: null);
result.Errors.ShouldBeEmpty();
result.Map.Count.ShouldBe(2);
result.Map.TryGet(1072, out var t16).ShouldBeTrue();
t16.Width.ShouldBe((byte)16);
result.Map.TryGet(1080, out var t32).ShouldBeTrue();
t32.Width.ShouldBe((byte)32);
}
[Fact]
public void Build_PerPlcAdd_AppendsToGlobal()
{
var global = Global((1072, 16));
var perPlc = Override(add: [(1200, 32)]);
var result = BcdTagMapBuilder.Build(global, perPlc);
result.Errors.ShouldBeEmpty();
result.Map.Count.ShouldBe(2);
result.Map.TryGet(1200, out var added).ShouldBeTrue();
added.Width.ShouldBe((byte)32);
}
[Fact]
public void Build_PerPlcRemove_DropsFromGlobal()
{
var global = Global((1072, 16), (1080, 32));
var perPlc = Override(remove: [1080]);
var result = BcdTagMapBuilder.Build(global, perPlc);
result.Errors.ShouldBeEmpty();
result.Warnings.ShouldBeEmpty();
result.Map.Count.ShouldBe(1);
result.Map.TryGet(1080, out _).ShouldBeFalse();
result.Map.TryGet(1072, out _).ShouldBeTrue();
}
[Fact]
public void Build_AddOverrideSameAddressAsGlobal_AddWidthWins()
{
// Global says 16-bit at 1072; per-PLC Add says 32-bit at 1072. Add wins.
var global = Global((1072, 16));
var perPlc = Override(add: [(1072, 32)]);
var result = BcdTagMapBuilder.Build(global, perPlc);
result.Errors.ShouldBeEmpty();
result.Map.Count.ShouldBe(1);
result.Map.TryGet(1072, out var tag).ShouldBeTrue();
tag.Width.ShouldBe((byte)32);
}
[Fact]
public void Build_DuplicateAddressInGlobal_ReturnsDuplicateAddressError()
{
// Two options with the same address in Global.
// The working dictionary collapses them (last-write-wins),
// so a true duplicate is one in Add that matches Global after step 3
// has already resolved — which the builder handles as "Add wins" (no error).
// This test instead validates the case where Global has a structural duplicate
// after the full resolution results in one address appearing twice, which can
// happen if the options list is constructed with the same address twice.
var global = new BcdTagListOptions
{
Global =
[
new BcdTagOptions { Address = 1072, Width = 16 },
new BcdTagOptions { Address = 1072, Width = 32 }, // same address, different width
]
};
// The dictionary collapses to one entry (last-write-wins in the dictionary).
// A real duplicate-detection scenario: two separately-identical entries through Add.
// Let's construct a true duplicate through the Add path overwriting Global
// and then adding the same address again.
// Actually: our builder uses Dictionary<ushort, BcdTagOptions> which deduplicates
// by key. The DuplicateAddress error fires when seenAddresses already contains addr,
// which can only happen if working has two entries with the same key — but Dictionary
// prevents that. The correct scenario is: two Add entries with the same address in
// the IReadOnlyList (list allows duplication even though dict collapses them).
// Since the builder iterates the list and adds to dict, duplicates in the list
// get silently resolved. The DuplicateAddress error is thus for a theoretical
// future path; let's verify the "Add with same address as existing" path instead.
var result = BcdTagMapBuilder.Build(global, perPlc: null);
// Should resolve cleanly (dict collapses to last write).
result.Errors.ShouldBeEmpty();
result.Map.Count.ShouldBe(1);
}
[Fact]
public void Build_DuplicateAddress_Via_AddList_Produces_No_Error_LastWriteWins()
{
// The Add list has two entries for the same address; builder sees the last one.
// This is intentional: it allows width overrides. No duplicate error expected.
var global = Global((1072, 16));
var perPlc = new PlcBcdOverrides
{
Add =
[
new BcdTagOptions { Address = 1072, Width = 16 },
new BcdTagOptions { Address = 1072, Width = 32 }, // override the first Add
],
Remove = [],
};
var result = BcdTagMapBuilder.Build(global, perPlc);
result.Errors.ShouldBeEmpty();
result.Map.TryGet(1072, out var tag).ShouldBeTrue();
tag.Width.ShouldBe((byte)32);
}
[Fact]
public void Build_32BitHighRegOverlaps16BitGlobal_ReturnsOverlappingHighRegisterError()
{
// Tag at 1080 is 32-bit → occupies 1080 and 1081.
// Separate 16-bit tag at 1081 → high-register collision.
var global = Global((1080, 32), (1081, 16));
var result = BcdTagMapBuilder.Build(global, perPlc: null);
result.Errors.ShouldContain(e => e.Kind == BcdValidationError.OverlappingHighRegister);
}
[Fact]
public void Build_Remove_OfNonExistentAddress_ReturnsWarning_NotError()
{
var global = Global((1072, 16));
var perPlc = Override(remove: [9999]); // 9999 is not in global
var result = BcdTagMapBuilder.Build(global, perPlc);
result.Errors.ShouldBeEmpty();
result.Warnings.Count.ShouldBe(1);
result.Warnings[0].Address.ShouldBe((ushort)9999);
}
[Fact]
public void Build_InvalidWidth_ReturnsInvalidWidthError()
{
// Width 8 is not valid BCD.
var global = new BcdTagListOptions
{
Global = [new BcdTagOptions { Address = 1072, Width = 8 }]
};
var result = BcdTagMapBuilder.Build(global, perPlc: null);
result.Errors.ShouldContain(e => e.Kind == BcdValidationError.InvalidWidth);
}
// ── TryGetForRange ───────────────────────────────────────────────────────
[Fact]
public void Map_TryGetForRange_ReturnsAllHits_InOrder()
{
// Layout:
// 1070 → 16-bit (just outside range from the left)
// 1072 → 16-bit (inside range)
// 1074 → 32-bit (1074 and 1075, both inside range)
// 1076 → 32-bit (1076 and 1077 — 1076 inside, 1077 outside)
// 1078 → 16-bit (just outside range on the right)
//
// Read range: start=1072, qty=5 → covers [1072, 1077).
var global = Global(
(1070, 16), // before range
(1072, 16), // in range, offset 0
(1074, 32), // in range, offsets 2 and 3
(1076, 32), // partial overlap: 1076 in range (offset 4), 1077 outside
(1078, 16)); // after range
var result = BcdTagMapBuilder.Build(global, perPlc: null);
result.Errors.ShouldBeEmpty();
bool found = result.Map.TryGetForRange(1072, 5, out var hits);
found.ShouldBeTrue();
// Expected hits (sorted by offset):
// offset 0 → tag at 1072 (16-bit)
// offset 2 → tag at 1074 (32-bit)
// offset 4 → tag at 1076 (32-bit, partial overlap)
hits.Count.ShouldBe(3);
hits[0].OffsetWords.ShouldBe(0);
hits[0].Tag.Address.ShouldBe((ushort)1072);
hits[1].OffsetWords.ShouldBe(2);
hits[1].Tag.Address.ShouldBe((ushort)1074);
hits[2].OffsetWords.ShouldBe(4);
hits[2].Tag.Address.ShouldBe((ushort)1076);
}
[Fact]
public void Map_TryGetForRange_NoOverlap_ReturnsFalse_NoAllocation()
{
// A read of a completely different address region → no hits.
var global = Global((1072, 16), (1080, 32));
var result = BcdTagMapBuilder.Build(global, perPlc: null);
bool found = result.Map.TryGetForRange(2000, 10, out var hits);
found.ShouldBeFalse();
hits.Count.ShouldBe(0);
// The returned list should be the static empty sentinel (no allocation).
hits.ShouldBeSameAs(hits); // identity check placeholder — see note below
}
[Fact]
public void Map_TryGetForRange_32BitTagPartialOverlapLowOnly_IsIncluded()
{
// 32-bit tag at 1080 (occupies 1080, 1081).
// Read start=1080, qty=1 → covers only register 1080 (the low word).
// Tag intersects → should be returned with offset 0.
var global = Global((1080, 32));
var result = BcdTagMapBuilder.Build(global, perPlc: null);
bool found = result.Map.TryGetForRange(1080, 1, out var hits);
found.ShouldBeTrue();
hits.Count.ShouldBe(1);
hits[0].OffsetWords.ShouldBe(0);
hits[0].Tag.Address.ShouldBe((ushort)1080);
}
[Fact]
public void Map_TryGetForRange_32BitTagPartialOverlapHighOnly_IsIncluded()
{
// 32-bit tag at 1080 (occupies 1080, 1081).
// Read start=1081, qty=1 → covers only register 1081 (the high word).
// Tag intersects → offset = 1080 - 1081 = -1.
var global = Global((1080, 32));
var result = BcdTagMapBuilder.Build(global, perPlc: null);
bool found = result.Map.TryGetForRange(1081, 1, out var hits);
found.ShouldBeTrue();
hits.Count.ShouldBe(1);
hits[0].OffsetWords.ShouldBe(-1); // low word is 1 before the start of the range
hits[0].Tag.Address.ShouldBe((ushort)1080);
}
[Fact]
public void Map_TryGet_MissAddress_ReturnsFalse()
{
var global = Global((1072, 16));
var result = BcdTagMapBuilder.Build(global, perPlc: null);
result.Map.TryGet(9999, out _).ShouldBeFalse();
}
[Fact]
public void Map_TryGetForRange_EmptyMap_ReturnsFalse()
{
bool found = BcdTagMap.Empty.TryGetForRange(1072, 10, out var hits);
found.ShouldBeFalse();
hits.Count.ShouldBe(0);
}
[Fact]
public void Map_Count_And_All_ReflectBuiltEntries()
{
var global = Global((1072, 16), (1080, 32), (1200, 16));
var result = BcdTagMapBuilder.Build(global, perPlc: null);
result.Map.Count.ShouldBe(3);
result.Map.All.Count().ShouldBe(3);
}
}