From 9ef6fc8489d4bca9f1b118a9899d8c2f0f53096d Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Thu, 12 Nov 2026 20:49:41 -0500 Subject: [PATCH] fix(worker): send the Write2/WriteSecured2 time argument as box-local time (#228) MXAccess reads the VT_DATE time argument of Write2, WriteSecured2 and their bulk forms as box-local time and converts it to UTC itself. The worker passed the proto Timestamp's UTC clock fields (the COM marshaler ignores DateTime.Kind), so on vd03 (UTC-5) a Write2 sent at 01:33:00Z was stored at 06:33:00Z. VariantConverter.ConvertToComTimestamp converts a timestamp_value instant with TimeZoneInfo.ConvertTimeFromUtc into the worker's zone (TimeZoneInfo.Local by default, DST included; an injectable zone for tests). The executor uses it for the time argument only: value conversion is unchanged, and the read direction (MXAccess reports UTC; ToTimestamp treats it as UTC) is unchanged. The one residual loss is MXAccess-side: the repeated fall-back hour cannot be told apart in an offset-less VT_DATE. Tests: VariantConverterTimestampTests (UTC-5, US-Eastern DST both edges, UTC+05:30, UTC, fall-back ambiguity, value path unchanged); the four executor forwarding tests inject a fixed UTC-5 zone; the windev live Write2 smoke now sends a past whole-second timestamp and asserts the stored one when applied. Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi --- .../LiveGatewayWrite2Tests.cs | 5 +- docs/GatewayTesting.md | 8 +- docs/WorkerConversion.md | 11 ++ gateway.md | 7 + .../WorkerLiveMxAccessSmokeTests.cs | 45 ++++- .../VariantConverterTimestampTests.cs | 156 ++++++++++++++++++ .../MxAccess/MxAccessCommandExecutorTests.cs | 20 ++- .../TestSupport/TestTimeZones.cs | 44 +++++ .../Conversion/VariantConverter.cs | 88 ++++++++++ .../MxAccess/MxAccessCommandExecutor.cs | 10 +- .../MxAccess/MxAccessSession.cs | 28 +++- .../MxAccess/MxAccessStaSession.cs | 12 +- 12 files changed, 415 insertions(+), 19 deletions(-) create mode 100644 src/ZB.MOM.WW.MxGateway.Worker.Tests/Conversion/VariantConverterTimestampTests.cs create mode 100644 src/ZB.MOM.WW.MxGateway.Worker.Tests/TestSupport/TestTimeZones.cs diff --git a/clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/LiveGatewayWrite2Tests.cs b/clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/LiveGatewayWrite2Tests.cs index cce6fb07..5290301c 100644 --- a/clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/LiveGatewayWrite2Tests.cs +++ b/clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/LiveGatewayWrite2Tests.cs @@ -27,8 +27,9 @@ public sealed class LiveGatewayWrite2Tests(ITestOutputHelper output) } /// - /// The source timestamp after Write2 equals the timestamp sent. On a host whose clock is not - /// UTC this fails until mxaccessgw#228 is fixed (MXAccess reads the VT_DATE as local time). + /// The source timestamp after Write2 equals the timestamp sent. MXAccess reads the VT_DATE + /// time argument as box-local time; a worker without the mxaccessgw#228 fix sends UTC clock + /// fields, so on a host whose clock is not UTC this fails by the host's UTC offset. /// /// A task that represents the asynchronous operation. [LiveGatewayWriteFact(requireTimestampOptIn: true)] diff --git a/docs/GatewayTesting.md b/docs/GatewayTesting.md index d5e055d6..efa2e194 100644 --- a/docs/GatewayTesting.md +++ b/docs/GatewayTesting.md @@ -141,7 +141,7 @@ so it is skipped unless all of these are set: | `MXGATEWAY_LIVE_GATEWAY_ENDPOINT` | Gateway gRPC endpoint, e.g. `http://:5120`. | | `MXGATEWAY_LIVE_GATEWAY_API_KEY_FILE` | File (mode 0600) holding the `mxgw_...` key. `MXGATEWAY_LIVE_GATEWAY_API_KEY` works too, but the file keeps the key out of the environment. The key needs `session:open`, `session:close`, `invoke:read`, `invoke:write`, `events:read`; a `Write tag globs` constraint scoped to the test item is enough. | | `MXGATEWAY_LIVE_GATEWAY_WRITE_ITEM` | A test-only, writable **Int32** attribute. No default on purpose. On the DEV box use a Z28062 receiver attribute such as `MESReceiver_025.MoveInBatchID`, never anything on Z28061. | -| `MXGATEWAY_LIVE_GATEWAY_ASSERT_WRITE2_TIMESTAMP` | `1` also runs `Write2_SupervisoryAdvise_KeepsSentTimestamp`. On a host whose clock is not UTC it fails until #228 is fixed. | +| `MXGATEWAY_LIVE_GATEWAY_ASSERT_WRITE2_TIMESTAMP` | `1` also runs `Write2_SupervisoryAdvise_KeepsSentTimestamp`. On a host whose clock is not UTC it fails against a worker older than the #228 fix (the stored time is off by the host's UTC offset). | Each test does Register, AddItem, **AdviseSupervisory**, reads the original value from the first `OnDataChange`, `Write2`s a different value with a timestamp 30 s in the past, waits for the @@ -158,6 +158,12 @@ dotnet test clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests --filter FullyQualif Run on the DEV box (vd03, gateway `2b13564e`) on 2026-11-12: the value test passed, and the timestamp test failed with exactly the #228 shift (sent `01:36:51Z`, stored `06:36:51Z`; vd03 is UTC-5). +The worker fix for #228 converts the time argument to box-local time; rerun the timestamp test +with `MXGATEWAY_LIVE_GATEWAY_ASSERT_WRITE2_TIMESTAMP=1` after that worker is deployed to the box. + +The windev smoke `WorkerLiveMxAccessSmokeTests.GatewaySession_WithLiveWorker_Write2ValueWithTimestampToAdvisedItem` +also sends a whole-second timestamp 30 s in the past and, when the completion is `Ok`, asserts the +stored source timestamp equals it. It logs the box's zone, because on a UTC box the check cannot fail. ## Dev-rig Probes diff --git a/docs/WorkerConversion.md b/docs/WorkerConversion.md index 9be993fd..343f62ea 100644 --- a/docs/WorkerConversion.md +++ b/docs/WorkerConversion.md @@ -119,6 +119,17 @@ default: `GetVariantTypeName` maps CLR types to canonical `VT_*` strings (`VT_BOOL`, `VT_I4`, `VT_BSTR`, `VT_DATE`, and so on). Unmapped CLR types fall back to `CLR:` so the wire format never silently invents a `VT_*` tag it cannot justify. Array element tags are wrapped as `SAFEARRAY()` by `CreateArrayVariantType`. +### Timestamps: the two directions differ + +MXAccess does not use one time convention for both directions, so the worker does not either. + +- **Read (OnDataChange source timestamps, `VT_DATE` values).** MXAccess hands the worker UTC clock fields. `ToTimestamp` treats an unspecified-kind `DateTime` as UTC and converts a local-kind one with `ToUniversalTime`. A plain `Write` on vd03 (UTC-5) reports the current UTC time as its source timestamp, which confirms this. +- **Write time argument (`Write2`, `WriteSecured2`, `Write2Bulk`, `WriteSecured2Bulk`).** MXAccess reads the `VT_DATE` time argument as **box-local** time and converts it to UTC itself. A `VT_DATE` has no offset field, and the COM marshaler ignores `DateTime.Kind`, so passing the UTC clock fields stored the source timestamp shifted by the box's UTC offset. On vd03 a `Write2` sent at `01:33:00Z` was stored at `06:33:00Z` (#228). `ConvertToComTimestamp` therefore converts the `timestamp_value` instant with `TimeZoneInfo.ConvertTimeFromUtc` into the worker box's zone (`TimeZoneInfo.Local`, DST rules included) before the COM call. The command executor uses it for the time argument only; `ConvertToComValue` still renders a timestamp *value* as UTC, because whether a `Time`-typed attribute value write follows the same rule has not been proven. + +UTC to local is always defined: every UTC instant has exactly one local wall-clock time, and the conversion never produces a local time that does not exist (the skipped spring-forward hour). The one loss is on the MXAccess side. In the hour that repeats when DST ends, two UTC instants an hour apart share one local wall-clock time, and the offset-less `VT_DATE` cannot say which one is meant, so MXAccess may store an instant from that hour 1 h off. Run the worker box on UTC if exact timestamps across the fall-back hour matter. On a UTC box the conversion is the identity, which is why #228 could not be seen there. + +A time argument of another kind (a string or a number) carries no zone and is passed through unchanged; its meaning is the caller's. Consumers must send `timestamp_value` as a UTC instant, as the proto `Timestamp` already is. + ### Why lossless preservation matters The MXAccess engine returns values whose semantic type only fully resolves after consulting the engine's own attribute metadata. Clients that round-trip these values through the gateway (replay, parity fixtures, diagnostics) need the original `VT_*` tag, the engine-declared `MxDataType`, and any conversion diagnostic; otherwise edge cases such as decimal-to-double rounding, ulong overflow, or an unknown SAFEARRAY element type become invisible bugs. Storing both the typed projection and the raw fields in the same `MxValue`/`MxArray` lets cross-language clients recover the original observation byte-for-byte where possible and detect lossy cases where it is not. diff --git a/gateway.md b/gateway.md index 13e2771f..ff05894b 100644 --- a/gateway.md +++ b/gateway.md @@ -1366,6 +1366,13 @@ Known important parity areas from existing captures: `AuthenticateUser` → `WriteSecured`/`WriteSecured2` path must send `AdviseSupervisory` for the item before a user id on a plain write is recorded; otherwise the user id is ignored. +- MXAccess reads the `Write2`/`WriteSecured2` time argument as box-local + time, while it reports source timestamps as UTC. Clients send + `timestamp_value` as a UTC instant; the worker converts it to the box's + local wall-clock time (DST included) before the COM call, so the stored + source timestamp equals the instant sent (#228). In the hour that repeats + when DST ends, the offset-less `VT_DATE` cannot distinguish the two + instants, so MXAccess may store one 1 h off. See `docs/WorkerConversion.md`. - Writing an array attribute replaces the whole array — it is not an element-wise patch. To change a subset of elements the caller must send the full array (unchanged elements included); sending only the changed elements diff --git a/src/ZB.MOM.WW.MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs b/src/ZB.MOM.WW.MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs index d5f3f588..9e732563 100644 --- a/src/ZB.MOM.WW.MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs +++ b/src/ZB.MOM.WW.MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs @@ -319,11 +319,21 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output) LogEvent(initialValue); originalValue = initialValue.Value; + // A whole-second instant 30 s in the past, so a stored source timestamp + // can be compared exactly and cannot be confused with the write time. + DateTime sentTimestampUtc = DateTime.UtcNow.AddSeconds(-30); + sentTimestampUtc = new DateTime( + sentTimestampUtc.Ticks - (sentTimestampUtc.Ticks % TimeSpan.TicksPerSecond), + DateTimeKind.Utc); + output.WriteLine( + $"Write2 timestamp sent={sentTimestampUtc:O} box zone={TimeZoneInfo.Local.Id} offset={TimeZoneInfo.Local.GetUtcOffset(sentTimestampUtc)}"); + MxCommandReply writeReply = await fixture.Service.Invoke( CreateWrite2Request( sessionId, registerReply.Register.ServerHandle, - addItemReply.AddItem.ItemHandle), + addItemReply.AddItem.ItemHandle, + sentTimestampUtc), new TestServerCallContext()).ConfigureAwait(false); LogReply("Write2", writeReply); @@ -362,6 +372,34 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output) output.WriteLine($"Write2 completion category={status.Category} detail={status.Detail}"); } + // #228: MXAccess reads the Write2 time argument as box-local time, so + // the worker must convert the UTC instant before the COM call. When the + // provider applied the write, the source timestamp it reports must be + // the instant sent. On a UTC box this cannot fail either way, so the + // zone is logged above. A refused write (no data change) is logged, + // not asserted, as before. + bool applied = writeComplete.Statuses.Count > 0 + && writeComplete.Statuses.All(status => status.Category == MxStatusCategory.Ok); + if (applied) + { + MxEvent writtenValue = await eventWriter + .WaitForMessageAsync( + candidate => candidate.Family == MxEventFamily.OnDataChange + && candidate.ItemHandle == addItemReply.AddItem.ItemHandle + && candidate.WorkerSequence > initialValue.WorkerSequence, + IntegrationTestEnvironment.LiveMxAccessEventTimeout, + streamCancellation.Token) + .ConfigureAwait(false); + LogEvent(writtenValue); + DateTime? storedTimestampUtc = writtenValue.SourceTimestamp?.ToDateTime(); + output.WriteLine($"Write2 timestamp stored={storedTimestampUtc:O}"); + Assert.Equal(sentTimestampUtc, storedTimestampUtc); + } + else + { + output.WriteLine("Write2 timestamp not checked: the completion was not Ok, so nothing was applied."); + } + // Restore the original value with a plain Write on the same supervisory advise. MxCommandReply restoreReply = await fixture.Service.Invoke( CreateWriteRequest( @@ -1666,7 +1704,8 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output) private static MxCommandRequest CreateWrite2Request( string sessionId, int serverHandle, - int itemHandle) + int itemHandle, + DateTime timestampUtc) { return new MxCommandRequest { @@ -1688,7 +1727,7 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output) { DataType = MxDataType.Time, VariantType = "VT_DATE", - TimestampValue = Timestamp.FromDateTime(DateTime.UtcNow), + TimestampValue = Timestamp.FromDateTime(timestampUtc), }, }, }, diff --git a/src/ZB.MOM.WW.MxGateway.Worker.Tests/Conversion/VariantConverterTimestampTests.cs b/src/ZB.MOM.WW.MxGateway.Worker.Tests/Conversion/VariantConverterTimestampTests.cs new file mode 100644 index 00000000..1f4aaa69 --- /dev/null +++ b/src/ZB.MOM.WW.MxGateway.Worker.Tests/Conversion/VariantConverterTimestampTests.cs @@ -0,0 +1,156 @@ +using System; +using System.Globalization; +using ZB.MOM.WW.MxGateway.Contracts.Proto; +using ZB.MOM.WW.MxGateway.Worker.Conversion; +using ZB.MOM.WW.MxGateway.Worker.Tests.TestSupport; +using ProtobufTimestamp = Google.Protobuf.WellKnownTypes.Timestamp; + +namespace ZB.MOM.WW.MxGateway.Worker.Tests.Conversion; + +/// +/// Tests for the Write2/WriteSecured2 time-argument conversion (#228): MXAccess +/// reads the VT_DATE time argument as box-local time, so the worker must +/// hand it the UTC instant as local wall-clock time. Every zone is injected, so +/// the results do not depend on the zone of the machine running the tests. +/// +public sealed class VariantConverterTimestampTests +{ + /// + /// Verifies the UTC-to-local conversion across zones and DST boundaries. + /// The first row is the live vd03 case from #228: sent 01:33:00Z, which + /// MXAccess stored as 06:33:00Z before the fix. + /// + /// Zone name in . + /// UTC instant sent on the wire (ISO 8601). + /// Expected local wall-clock time handed to MXAccess. + [Theory] + // UTC-5 in November (EST): the #228 live case. + [InlineData("Eastern", "2026-11-13T01:33:00", "2026-11-12T20:33:00")] + // UTC-4 in July (EDT). + [InlineData("Eastern", "2026-07-15T12:00:00", "2026-07-15T08:00:00")] + // Spring forward (2026-03-08 07:00Z): the last EST second, then the first EDT + // instant. Local 02:xx does not exist that night and is never produced. + [InlineData("Eastern", "2026-03-08T06:59:59", "2026-03-08T01:59:59")] + [InlineData("Eastern", "2026-03-08T07:00:00", "2026-03-08T03:00:00")] + // Fall back (2026-11-01 06:00Z): the last EDT second, then the first EST instant. + [InlineData("Eastern", "2026-11-01T05:59:59", "2026-11-01T01:59:59")] + [InlineData("Eastern", "2026-11-01T06:00:00", "2026-11-01T01:00:00")] + // Fixed negative and positive (non-whole-hour) offsets. + [InlineData("UTC-5", "2026-11-13T01:33:00", "2026-11-12T20:33:00")] + [InlineData("UTC+05:30", "2026-11-13T01:33:00", "2026-11-13T07:03:00")] + [InlineData("UTC+05:30", "2026-12-31T20:00:00", "2027-01-01T01:30:00")] + // A UTC box: the conversion is the identity, which is why #228 cannot be seen there. + [InlineData("UTC", "2026-11-13T01:33:00", "2026-11-13T01:33:00")] + public void ConvertToComTimestamp_WithTimestampValue_ReturnsBoxLocalWallClockTime( + string zone, + string utc, + string expectedLocal) + { + VariantConverter converter = new(ResolveZone(zone)); + + object? result = converter.ConvertToComTimestamp(CreateTimestampValue(ParseUtc(utc))); + + DateTime local = Assert.IsType(result); + Assert.Equal(ParseUnspecified(expectedLocal), DateTime.SpecifyKind(local, DateTimeKind.Unspecified)); + } + + /// + /// Verifies the documented fall-back ambiguity: two UTC instants an hour + /// apart become the same local wall-clock time, which the offset-less + /// VT_DATE cannot tell apart. The conversion itself is exact; the + /// 1 h loss is on the MXAccess side. + /// + [Fact] + public void ConvertToComTimestamp_InRepeatedFallBackHour_MapsTwoInstantsToOneWallClockTime() + { + VariantConverter converter = new(TestTimeZones.Eastern); + + DateTime daylight = Assert.IsType( + converter.ConvertToComTimestamp(CreateTimestampValue(ParseUtc("2026-11-01T05:30:00")))); + DateTime standard = Assert.IsType( + converter.ConvertToComTimestamp(CreateTimestampValue(ParseUtc("2026-11-01T06:30:00")))); + + Assert.Equal(ParseUnspecified("2026-11-01T01:30:00"), DateTime.SpecifyKind(daylight, DateTimeKind.Unspecified)); + Assert.Equal(daylight.Ticks, standard.Ticks); + Assert.True(TestTimeZones.Eastern.IsAmbiguousTime(DateTime.SpecifyKind(daylight, DateTimeKind.Unspecified))); + } + + /// Verifies the default converter uses the worker box's own zone. + [Fact] + public void ConvertToComTimestamp_WithDefaultConverter_UsesTimeZoneInfoLocal() + { + DateTime utc = ParseUtc("2026-11-13T01:33:00"); + + object? result = new VariantConverter().ConvertToComTimestamp(CreateTimestampValue(utc)); + + Assert.Equal(TimeZoneInfo.ConvertTimeFromUtc(utc, TimeZoneInfo.Local), Assert.IsType(result)); + } + + /// + /// Verifies the conversion is limited to the time argument: a timestamp + /// written as an attribute value is unchanged, because whether a + /// Time-typed value write follows the same local-time rule is unproven. + /// + [Fact] + public void ConvertToComValue_WithTimestampValue_StaysUtcEvenWithZoneInjected() + { + DateTime utc = ParseUtc("2026-11-13T01:33:00"); + VariantConverter converter = new(TestTimeZones.FixedUtcMinus5); + + object? result = converter.ConvertToComValue(CreateTimestampValue(utc)); + + Assert.Equal(utc, Assert.IsType(result)); + } + + /// Verifies a non-timestamp time argument carries no zone and passes through unchanged. + [Fact] + public void ConvertToComTimestamp_WithStringValue_PassesThroughUnchanged() + { + VariantConverter converter = new(TestTimeZones.FixedUtcMinus5); + + object? result = converter.ConvertToComTimestamp(new MxValue { StringValue = "2026-11-13 01:33:00" }); + + Assert.Equal("2026-11-13 01:33:00", Assert.IsType(result)); + } + + /// Verifies an MXAccess-null time argument stays a CLR null. + [Fact] + public void ConvertToComTimestamp_WithNull_ReturnsNull() + { + VariantConverter converter = new(TestTimeZones.FixedUtcMinus5); + + Assert.Null(converter.ConvertToComTimestamp(new MxValue { IsNull = true })); + } + + /// Verifies an unspecified-kind input is treated as UTC, the rule the proto timestamp follows. + [Fact] + public void ToMxAccessLocalTime_WithUnspecifiedKind_TreatsInputAsUtc() + { + VariantConverter converter = new(TestTimeZones.FixedUtcMinus5); + + DateTime result = converter.ToMxAccessLocalTime(ParseUnspecified("2026-11-13T01:33:00")); + + Assert.Equal(ParseUnspecified("2026-11-12T20:33:00"), DateTime.SpecifyKind(result, DateTimeKind.Unspecified)); + } + + private static TimeZoneInfo ResolveZone(string zone) => zone switch + { + "Eastern" => TestTimeZones.Eastern, + "UTC-5" => TestTimeZones.FixedUtcMinus5, + "UTC+05:30" => TestTimeZones.FixedUtcPlus0530, + "UTC" => TimeZoneInfo.Utc, + _ => throw new ArgumentOutOfRangeException(nameof(zone), zone, "Unknown test zone."), + }; + + private static MxValue CreateTimestampValue(DateTime utc) => new() + { + DataType = MxDataType.Time, + VariantType = "VT_DATE", + TimestampValue = ProtobufTimestamp.FromDateTime(utc), + }; + + private static DateTime ParseUtc(string value) => DateTime.SpecifyKind(ParseUnspecified(value), DateTimeKind.Utc); + + private static DateTime ParseUnspecified(string value) => + DateTime.ParseExact(value, "yyyy-MM-ddTHH:mm:ss", CultureInfo.InvariantCulture, DateTimeStyles.None); +} diff --git a/src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/MxAccessCommandExecutorTests.cs b/src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/MxAccessCommandExecutorTests.cs index 5ee79648..6221da43 100644 --- a/src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/MxAccessCommandExecutorTests.cs +++ b/src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/MxAccessCommandExecutorTests.cs @@ -554,6 +554,9 @@ public sealed class MxAccessCommandExecutorTests FakeMxAccessComObjectFactory factory = new(fakeComObject); using StaRuntime runtime = CreateRuntime(); using MxAccessStaSession session = new(runtime, factory, new NoopEventSink()); + // #228: MXAccess reads the time argument as box-local time. Inject a + // fixed UTC-5 zone so the expected shift does not depend on this machine. + session.MxAccessLocalTimeZone = TestTimeZones.FixedUtcMinus5; await session.StartAsync(workerProcessId: 1234); DateTime timestamp = new(2026, 5, 19, 12, 0, 0, DateTimeKind.Utc); @@ -567,7 +570,7 @@ public sealed class MxAccessCommandExecutorTests Assert.True(result.WasSuccessful); Assert.Equal(811, result.ItemHandle); Assert.Equal(100, fakeComObject.WriteValue); - Assert.Equal(timestamp, fakeComObject.WriteTimestamp); + Assert.Equal(timestamp.AddHours(-5).Ticks, Assert.IsType(fakeComObject.WriteTimestamp).Ticks); Assert.Equal(7, fakeComObject.WriteUserId); Assert.Contains("Write2:81:811", fakeComObject.OperationNames); } @@ -606,6 +609,9 @@ public sealed class MxAccessCommandExecutorTests FakeMxAccessComObjectFactory factory = new(fakeComObject); using StaRuntime runtime = CreateRuntime(); using MxAccessStaSession session = new(runtime, factory, new NoopEventSink()); + // #228: MXAccess reads the time argument as box-local time. Inject a + // fixed UTC-5 zone so the expected shift does not depend on this machine. + session.MxAccessLocalTimeZone = TestTimeZones.FixedUtcMinus5; await session.StartAsync(workerProcessId: 1234); DateTime timestamp = new(2026, 5, 19, 13, 30, 0, DateTimeKind.Utc); @@ -620,7 +626,7 @@ public sealed class MxAccessCommandExecutorTests Assert.Equal(33, fakeComObject.WriteCurrentUserId); Assert.Equal(44, fakeComObject.WriteVerifierUserId); Assert.Equal(999, fakeComObject.WriteValue); - Assert.Equal(timestamp, fakeComObject.WriteTimestamp); + Assert.Equal(timestamp.AddHours(-5).Ticks, Assert.IsType(fakeComObject.WriteTimestamp).Ticks); Assert.Contains("WriteSecured2:83:831", fakeComObject.OperationNames); } @@ -1027,6 +1033,9 @@ public sealed class MxAccessCommandExecutorTests using MxAccessStaSession session = new(runtime, factory, new NoopEventSink()); // Same rationale as the Write forwarding test above. session.WriteCompletionTimeout = TimeSpan.Zero; + // #228: MXAccess reads the time argument as box-local time. Inject a + // fixed UTC-5 zone so the expected shift does not depend on this machine. + session.MxAccessLocalTimeZone = TestTimeZones.FixedUtcMinus5; await session.StartAsync(workerProcessId: 1234); DateTime timestamp = new(2026, 5, 19, 12, 0, 0, DateTimeKind.Utc); @@ -1037,7 +1046,7 @@ public sealed class MxAccessCommandExecutorTests Assert.Equal(MxCommandKind.Write2, reply.Kind); Assert.Equal(710, fakeComObject.WriteItemHandle); Assert.Equal(456, fakeComObject.WriteValue); - Assert.Equal(timestamp, fakeComObject.WriteTimestamp); + Assert.Equal(timestamp.AddHours(-5).Ticks, Assert.IsType(fakeComObject.WriteTimestamp).Ticks); Assert.Equal(6, fakeComObject.WriteUserId); } @@ -1077,6 +1086,9 @@ public sealed class MxAccessCommandExecutorTests using MxAccessStaSession session = new(runtime, factory, new NoopEventSink()); // Same rationale as the WriteSecured forwarding test above. session.WriteCompletionTimeout = TimeSpan.Zero; + // #228: MXAccess reads the time argument as box-local time. Inject a + // fixed UTC-5 zone so the expected shift does not depend on this machine. + session.MxAccessLocalTimeZone = TestTimeZones.FixedUtcMinus5; await session.StartAsync(workerProcessId: 1234); DateTime timestamp = new(2026, 5, 19, 13, 30, 0, DateTimeKind.Utc); @@ -1087,7 +1099,7 @@ public sealed class MxAccessCommandExecutorTests Assert.Equal(ProtocolStatusCode.Ok, reply.ProtocolStatus.Code); Assert.Equal(MxCommandKind.WriteSecured2, reply.Kind); Assert.Equal(1011, fakeComObject.WriteValue); - Assert.Equal(timestamp, fakeComObject.WriteTimestamp); + Assert.Equal(timestamp.AddHours(-5).Ticks, Assert.IsType(fakeComObject.WriteTimestamp).Ticks); Assert.Equal(33, fakeComObject.WriteCurrentUserId); Assert.Equal(44, fakeComObject.WriteVerifierUserId); } diff --git a/src/ZB.MOM.WW.MxGateway.Worker.Tests/TestSupport/TestTimeZones.cs b/src/ZB.MOM.WW.MxGateway.Worker.Tests/TestSupport/TestTimeZones.cs new file mode 100644 index 00000000..4f68b396 --- /dev/null +++ b/src/ZB.MOM.WW.MxGateway.Worker.Tests/TestSupport/TestTimeZones.cs @@ -0,0 +1,44 @@ +using System; + +namespace ZB.MOM.WW.MxGateway.Worker.Tests.TestSupport; + +/// +/// Custom time zones built in code, so tests of the #228 Write2 time-argument +/// conversion behave the same on every machine whatever its own zone or its +/// registry time-zone data. +/// +internal static class TestTimeZones +{ + /// + /// Gets a US-Eastern-shaped zone: UTC-5 standard, UTC-4 daylight, DST from + /// the second Sunday of March 02:00 to the first Sunday of November 02:00 + /// (the vd03 zone). In 2026 DST starts at 2026-03-08T07:00Z and ends at + /// 2026-11-01T06:00Z. + /// + public static TimeZoneInfo Eastern { get; } = CreateEastern(); + + /// Gets a fixed UTC-5 zone with no DST. + public static TimeZoneInfo FixedUtcMinus5 { get; } = TimeZoneInfo.CreateCustomTimeZone( + "Test UTC-5", TimeSpan.FromHours(-5), "Test UTC-5", "Test UTC-5"); + + /// Gets a fixed UTC+05:30 zone with no DST (a positive, non-whole-hour offset). + public static TimeZoneInfo FixedUtcPlus0530 { get; } = TimeZoneInfo.CreateCustomTimeZone( + "Test UTC+05:30", new TimeSpan(5, 30, 0), "Test UTC+05:30", "Test UTC+05:30"); + + private static TimeZoneInfo CreateEastern() + { + TimeZoneInfo.TransitionTime dstStart = TimeZoneInfo.TransitionTime.CreateFloatingDateRule( + new DateTime(1, 1, 1, 2, 0, 0), month: 3, week: 2, DayOfWeek.Sunday); + TimeZoneInfo.TransitionTime dstEnd = TimeZoneInfo.TransitionTime.CreateFloatingDateRule( + new DateTime(1, 1, 1, 2, 0, 0), month: 11, week: 1, DayOfWeek.Sunday); + TimeZoneInfo.AdjustmentRule rule = TimeZoneInfo.AdjustmentRule.CreateAdjustmentRule( + new DateTime(2007, 1, 1), DateTime.MaxValue.Date, TimeSpan.FromHours(1), dstStart, dstEnd); + return TimeZoneInfo.CreateCustomTimeZone( + "Test Eastern", + TimeSpan.FromHours(-5), + "Test Eastern", + "Test Eastern Standard", + "Test Eastern Daylight", + new[] { rule }); + } +} diff --git a/src/ZB.MOM.WW.MxGateway.Worker/Conversion/VariantConverter.cs b/src/ZB.MOM.WW.MxGateway.Worker/Conversion/VariantConverter.cs index 8d7c4a7c..810fc877 100644 --- a/src/ZB.MOM.WW.MxGateway.Worker/Conversion/VariantConverter.cs +++ b/src/ZB.MOM.WW.MxGateway.Worker/Conversion/VariantConverter.cs @@ -9,6 +9,31 @@ namespace ZB.MOM.WW.MxGateway.Worker.Conversion; public sealed class VariantConverter { + private readonly TimeZoneInfo? mxAccessLocalTimeZone; + + /// + /// Initializes a converter that renders timestamped-write time arguments in + /// the worker box's local zone (). + /// + public VariantConverter() + : this(mxAccessLocalTimeZone: null) + { + } + + /// + /// Initializes a converter with an explicit zone for the timestamped-write + /// time argument. Tests inject a fixed zone so they do not depend on the + /// zone of the machine that runs them. + /// + /// + /// Zone MXAccess reads the Write2/WriteSecured2 time argument in, + /// or for resolved per call. + /// + public VariantConverter(TimeZoneInfo? mxAccessLocalTimeZone) + { + this.mxAccessLocalTimeZone = mxAccessLocalTimeZone; + } + /// /// Converts an object value to an MxValue without a specified data type. /// @@ -157,6 +182,69 @@ public sealed class VariantConverter }; } + /// + /// Converts the time argument of a timestamped write (Write2, + /// WriteSecured2 and their bulk forms) into the CLR object MXAccess + /// expects. Unlike , a + /// timestamp_value instant is rendered as box-local wall-clock time. + /// + /// + /// + /// MXAccess reads the VT_DATE time argument as local time on the worker + /// box and converts it to UTC itself, while a VT_DATE carries no + /// offset and the COM marshaler ignores . Passing + /// the UTC clock fields therefore stored the source timestamp shifted by the + /// box's UTC offset (+5 h on a UTC-5 box, #228). The read direction is the + /// opposite and stays as it is: MXAccess hands OnDataChange timestamps over + /// as UTC, and ToTimestamp treats them as UTC. + /// + /// + /// The UTC-to-local step uses + /// with the zone's DST rules, so it is exact and never yields an invalid + /// local time. The one residual loss is on the MXAccess side: in the hour + /// that repeats when DST ends, two UTC instants share one local wall-clock + /// time, and the offset-less VT_DATE cannot say which one is meant, + /// so MXAccess may store an instant from that hour 1 h off. Clients that + /// need exact timestamps across the fall-back hour should run the worker + /// box on UTC. + /// + /// + /// Only the timestamp_value kind is converted. Any other kind (a + /// string or a number) carries no zone, so it is passed through unchanged + /// as before and its meaning is the caller's. + /// + /// + /// Protobuf time argument of a timestamped write. + /// A COM-marshalable value for the MXAccess time argument. + public object? ConvertToComTimestamp(MxValue timestamp) + { + if (timestamp is null) + { + throw new ArgumentNullException(nameof(timestamp)); + } + + if (!timestamp.IsNull && timestamp.KindCase == MxValue.KindOneofCase.TimestampValue) + { + return ToMxAccessLocalTime(timestamp.TimestampValue.ToDateTime()); + } + + return ConvertToComValue(timestamp); + } + + /// + /// Converts a UTC instant to the wall-clock time MXAccess expects for a + /// timestamped-write time argument. See . + /// + /// UTC instant ( or unspecified). + /// The same instant as wall-clock time in the MXAccess zone. + public DateTime ToMxAccessLocalTime(DateTime utcDateTime) + { + DateTime utc = utcDateTime.Kind == DateTimeKind.Local + ? utcDateTime.ToUniversalTime() + : DateTime.SpecifyKind(utcDateTime, DateTimeKind.Utc); + return TimeZoneInfo.ConvertTimeFromUtc(utc, mxAccessLocalTimeZone ?? TimeZoneInfo.Local); + } + private static Array ConvertToComArray(MxArray array) { return array.ValuesCase switch diff --git a/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessCommandExecutor.cs b/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessCommandExecutor.cs index 4d542ae0..bf6c759d 100644 --- a/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessCommandExecutor.cs +++ b/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessCommandExecutor.cs @@ -497,7 +497,7 @@ public sealed class MxAccessCommandExecutor : IStaCommandExecutor write2Command.ServerHandle, write2Command.ItemHandle, variantConverter.ConvertToComValue(write2Command.Value), - variantConverter.ConvertToComValue(write2Command.TimestampValue), + variantConverter.ConvertToComTimestamp(write2Command.TimestampValue), write2Command.UserId); MxCommandReply reply = CreateOkReply(command); @@ -580,7 +580,7 @@ public sealed class MxAccessCommandExecutor : IStaCommandExecutor writeSecured2Command.CurrentUserId, writeSecured2Command.VerifierUserId, variantConverter.ConvertToComValue(writeSecured2Command.Value), - variantConverter.ConvertToComValue(writeSecured2Command.TimestampValue)); + variantConverter.ConvertToComTimestamp(writeSecured2Command.TimestampValue)); MxCommandReply reply = CreateOkReply(command); AwaitWriteCompletion( @@ -726,7 +726,8 @@ public sealed class MxAccessCommandExecutor : IStaCommandExecutor session.Write2Bulk( write2BulkCommand.ServerHandle, write2BulkCommand.Entries, - value => variantConverter.ConvertToComValue(value))); + value => variantConverter.ConvertToComValue(value), + timestamp => variantConverter.ConvertToComTimestamp(timestamp))); } private MxCommandReply ExecuteWriteSecuredBulk(StaCommand command) @@ -785,7 +786,8 @@ public sealed class MxAccessCommandExecutor : IStaCommandExecutor session.WriteSecured2Bulk( writeSecured2BulkCommand.ServerHandle, writeSecured2BulkCommand.Entries, - value => variantConverter.ConvertToComValue(value))); + value => variantConverter.ConvertToComValue(value), + timestamp => variantConverter.ConvertToComTimestamp(timestamp))); } private MxCommandReply ExecuteReadBulk(StaCommand command) diff --git a/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessSession.cs b/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessSession.cs index 31576d8c..c3c37b38 100644 --- a/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessSession.cs +++ b/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessSession.cs @@ -793,11 +793,16 @@ public sealed class MxAccessSession : IDisposable /// The MXAccess server handle. /// The write2 entries to process. /// Converts protobuf MxValue to COM-compatible variant. + /// + /// Converts the per-entry time argument; it differs from + /// because MXAccess reads the time argument as box-local time (#228). + /// /// The per-entry write results, in the order the entries were provided. public IReadOnlyList Write2Bulk( int serverHandle, IReadOnlyList entries, - Func convertValue) + Func convertValue, + Func convertTimestamp) { ThrowIfDisposed(); if (entries is null) @@ -810,6 +815,11 @@ public sealed class MxAccessSession : IDisposable throw new ArgumentNullException(nameof(convertValue)); } + if (convertTimestamp is null) + { + throw new ArgumentNullException(nameof(convertTimestamp)); + } + List results = new(entries.Count); foreach (Write2BulkEntry entry in entries) { @@ -820,7 +830,7 @@ public sealed class MxAccessSession : IDisposable serverHandle, entry.ItemHandle, convertValue(entry.Value), - convertValue(entry.TimestampValue), + convertTimestamp(entry.TimestampValue), entry.UserId))); } @@ -869,11 +879,16 @@ public sealed class MxAccessSession : IDisposable /// The MXAccess server handle. /// The WriteSecured2 entries to process. /// Converts protobuf MxValue to COM-compatible variant. + /// + /// Converts the per-entry time argument; it differs from + /// because MXAccess reads the time argument as box-local time (#228). + /// /// The per-entry write results, in the order the entries were provided. public IReadOnlyList WriteSecured2Bulk( int serverHandle, IReadOnlyList entries, - Func convertValue) + Func convertValue, + Func convertTimestamp) { ThrowIfDisposed(); if (entries is null) @@ -886,6 +901,11 @@ public sealed class MxAccessSession : IDisposable throw new ArgumentNullException(nameof(convertValue)); } + if (convertTimestamp is null) + { + throw new ArgumentNullException(nameof(convertTimestamp)); + } + List results = new(entries.Count); foreach (WriteSecured2BulkEntry entry in entries) { @@ -898,7 +918,7 @@ public sealed class MxAccessSession : IDisposable entry.CurrentUserId, entry.VerifierUserId, convertValue(entry.Value), - convertValue(entry.TimestampValue)))); + convertTimestamp(entry.TimestampValue)))); } return results; diff --git a/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessStaSession.cs b/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessStaSession.cs index 505c533e..bc8997d4 100644 --- a/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessStaSession.cs +++ b/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessStaSession.cs @@ -229,6 +229,16 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession /// internal TimeSpan WriteCompletionTimeout { get; set; } = ResolveWriteCompletionTimeout(); + /// + /// Zone the command executor renders the Write2/WriteSecured2 time + /// argument in, handed over at . + /// (the production value) means + /// . Internal-settable as a test seam so + /// Worker.Tests assert the #228 conversion independently of the zone of + /// the machine that runs them. + /// + internal TimeZoneInfo? MxAccessLocalTimeZone { get; set; } + /// /// Cadence the alarm poll loop waits between polls. Resolved from the /// launcher environment; internal-settable as a test seam (set before @@ -362,7 +372,7 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession staRuntime, new MxAccessCommandExecutor( session, - new VariantConverter(), + new VariantConverter(MxAccessLocalTimeZone), alarmCommandHandler, // ReadBulk and the write-completion wait need to pump // Windows messages while they wait for the inbound COM