fix(worker): send the Write2/WriteSecured2 time argument as box-local time (#228)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 2m28s
ci / portable (push) Failing after 16m55s
ci / java (push) Failing after 17m47s

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
This commit is contained in:
Joseph Doherty
2026-11-12 20:49:41 -05:00
parent 7481b95905
commit 9ef6fc8489
12 changed files with 415 additions and 19 deletions
@@ -27,8 +27,9 @@ public sealed class LiveGatewayWrite2Tests(ITestOutputHelper output)
} }
/// <summary> /// <summary>
/// The source timestamp after Write2 equals the timestamp sent. On a host whose clock is not /// The source timestamp after Write2 equals the timestamp sent. MXAccess reads the VT_DATE
/// UTC this fails until mxaccessgw#228 is fixed (MXAccess reads the VT_DATE as local time). /// 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.
/// </summary> /// </summary>
/// <returns>A task that represents the asynchronous operation.</returns> /// <returns>A task that represents the asynchronous operation.</returns>
[LiveGatewayWriteFact(requireTimestampOptIn: true)] [LiveGatewayWriteFact(requireTimestampOptIn: true)]
+7 -1
View File
@@ -141,7 +141,7 @@ so it is skipped unless all of these are set:
| `MXGATEWAY_LIVE_GATEWAY_ENDPOINT` | Gateway gRPC endpoint, e.g. `http://<host>:5120`. | | `MXGATEWAY_LIVE_GATEWAY_ENDPOINT` | Gateway gRPC endpoint, e.g. `http://<host>: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_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_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 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 `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 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). 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 ## Dev-rig Probes
+11
View File
@@ -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:<FullName>` so the wire format never silently invents a `VT_*` tag it cannot justify. Array element tags are wrapped as `SAFEARRAY(<element>)` by `CreateArrayVariantType`. `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:<FullName>` so the wire format never silently invents a `VT_*` tag it cannot justify. Array element tags are wrapped as `SAFEARRAY(<element>)` 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 ### 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. 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.
+7
View File
@@ -1366,6 +1366,13 @@ Known important parity areas from existing captures:
`AuthenticateUser` → `WriteSecured`/`WriteSecured2` path must send `AuthenticateUser` → `WriteSecured`/`WriteSecured2` path must send
`AdviseSupervisory` for the item before a user id on a plain write is `AdviseSupervisory` for the item before a user id on a plain write is
recorded; otherwise the user id is ignored. 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 - 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 element-wise patch. To change a subset of elements the caller must send the
full array (unchanged elements included); sending only the changed elements full array (unchanged elements included); sending only the changed elements
@@ -319,11 +319,21 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output)
LogEvent(initialValue); LogEvent(initialValue);
originalValue = initialValue.Value; 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( MxCommandReply writeReply = await fixture.Service.Invoke(
CreateWrite2Request( CreateWrite2Request(
sessionId, sessionId,
registerReply.Register.ServerHandle, registerReply.Register.ServerHandle,
addItemReply.AddItem.ItemHandle), addItemReply.AddItem.ItemHandle,
sentTimestampUtc),
new TestServerCallContext()).ConfigureAwait(false); new TestServerCallContext()).ConfigureAwait(false);
LogReply("Write2", writeReply); LogReply("Write2", writeReply);
@@ -362,6 +372,34 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output)
output.WriteLine($"Write2 completion category={status.Category} detail={status.Detail}"); 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. // Restore the original value with a plain Write on the same supervisory advise.
MxCommandReply restoreReply = await fixture.Service.Invoke( MxCommandReply restoreReply = await fixture.Service.Invoke(
CreateWriteRequest( CreateWriteRequest(
@@ -1666,7 +1704,8 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output)
private static MxCommandRequest CreateWrite2Request( private static MxCommandRequest CreateWrite2Request(
string sessionId, string sessionId,
int serverHandle, int serverHandle,
int itemHandle) int itemHandle,
DateTime timestampUtc)
{ {
return new MxCommandRequest return new MxCommandRequest
{ {
@@ -1688,7 +1727,7 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output)
{ {
DataType = MxDataType.Time, DataType = MxDataType.Time,
VariantType = "VT_DATE", VariantType = "VT_DATE",
TimestampValue = Timestamp.FromDateTime(DateTime.UtcNow), TimestampValue = Timestamp.FromDateTime(timestampUtc),
}, },
}, },
}, },
@@ -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;
/// <summary>
/// Tests for the Write2/WriteSecured2 time-argument conversion (#228): MXAccess
/// reads the <c>VT_DATE</c> 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.
/// </summary>
public sealed class VariantConverterTimestampTests
{
/// <summary>
/// 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.
/// </summary>
/// <param name="zone">Zone name in <see cref="ResolveZone(string)"/>.</param>
/// <param name="utc">UTC instant sent on the wire (ISO 8601).</param>
/// <param name="expectedLocal">Expected local wall-clock time handed to MXAccess.</param>
[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<DateTime>(result);
Assert.Equal(ParseUnspecified(expectedLocal), DateTime.SpecifyKind(local, DateTimeKind.Unspecified));
}
/// <summary>
/// Verifies the documented fall-back ambiguity: two UTC instants an hour
/// apart become the same local wall-clock time, which the offset-less
/// <c>VT_DATE</c> cannot tell apart. The conversion itself is exact; the
/// 1 h loss is on the MXAccess side.
/// </summary>
[Fact]
public void ConvertToComTimestamp_InRepeatedFallBackHour_MapsTwoInstantsToOneWallClockTime()
{
VariantConverter converter = new(TestTimeZones.Eastern);
DateTime daylight = Assert.IsType<DateTime>(
converter.ConvertToComTimestamp(CreateTimestampValue(ParseUtc("2026-11-01T05:30:00"))));
DateTime standard = Assert.IsType<DateTime>(
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)));
}
/// <summary>Verifies the default converter uses the worker box's own zone.</summary>
[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<DateTime>(result));
}
/// <summary>
/// Verifies the conversion is limited to the time argument: a timestamp
/// written as an attribute value is unchanged, because whether a
/// <c>Time</c>-typed value write follows the same local-time rule is unproven.
/// </summary>
[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<DateTime>(result));
}
/// <summary>Verifies a non-timestamp time argument carries no zone and passes through unchanged.</summary>
[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<string>(result));
}
/// <summary>Verifies an MXAccess-null time argument stays a CLR null.</summary>
[Fact]
public void ConvertToComTimestamp_WithNull_ReturnsNull()
{
VariantConverter converter = new(TestTimeZones.FixedUtcMinus5);
Assert.Null(converter.ConvertToComTimestamp(new MxValue { IsNull = true }));
}
/// <summary>Verifies an unspecified-kind input is treated as UTC, the rule the proto timestamp follows.</summary>
[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);
}
@@ -554,6 +554,9 @@ public sealed class MxAccessCommandExecutorTests
FakeMxAccessComObjectFactory factory = new(fakeComObject); FakeMxAccessComObjectFactory factory = new(fakeComObject);
using StaRuntime runtime = CreateRuntime(); using StaRuntime runtime = CreateRuntime();
using MxAccessStaSession session = new(runtime, factory, new NoopEventSink()); 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); await session.StartAsync(workerProcessId: 1234);
DateTime timestamp = new(2026, 5, 19, 12, 0, 0, DateTimeKind.Utc); DateTime timestamp = new(2026, 5, 19, 12, 0, 0, DateTimeKind.Utc);
@@ -567,7 +570,7 @@ public sealed class MxAccessCommandExecutorTests
Assert.True(result.WasSuccessful); Assert.True(result.WasSuccessful);
Assert.Equal(811, result.ItemHandle); Assert.Equal(811, result.ItemHandle);
Assert.Equal(100, fakeComObject.WriteValue); Assert.Equal(100, fakeComObject.WriteValue);
Assert.Equal(timestamp, fakeComObject.WriteTimestamp); Assert.Equal(timestamp.AddHours(-5).Ticks, Assert.IsType<DateTime>(fakeComObject.WriteTimestamp).Ticks);
Assert.Equal(7, fakeComObject.WriteUserId); Assert.Equal(7, fakeComObject.WriteUserId);
Assert.Contains("Write2:81:811", fakeComObject.OperationNames); Assert.Contains("Write2:81:811", fakeComObject.OperationNames);
} }
@@ -606,6 +609,9 @@ public sealed class MxAccessCommandExecutorTests
FakeMxAccessComObjectFactory factory = new(fakeComObject); FakeMxAccessComObjectFactory factory = new(fakeComObject);
using StaRuntime runtime = CreateRuntime(); using StaRuntime runtime = CreateRuntime();
using MxAccessStaSession session = new(runtime, factory, new NoopEventSink()); 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); await session.StartAsync(workerProcessId: 1234);
DateTime timestamp = new(2026, 5, 19, 13, 30, 0, DateTimeKind.Utc); 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(33, fakeComObject.WriteCurrentUserId);
Assert.Equal(44, fakeComObject.WriteVerifierUserId); Assert.Equal(44, fakeComObject.WriteVerifierUserId);
Assert.Equal(999, fakeComObject.WriteValue); Assert.Equal(999, fakeComObject.WriteValue);
Assert.Equal(timestamp, fakeComObject.WriteTimestamp); Assert.Equal(timestamp.AddHours(-5).Ticks, Assert.IsType<DateTime>(fakeComObject.WriteTimestamp).Ticks);
Assert.Contains("WriteSecured2:83:831", fakeComObject.OperationNames); Assert.Contains("WriteSecured2:83:831", fakeComObject.OperationNames);
} }
@@ -1027,6 +1033,9 @@ public sealed class MxAccessCommandExecutorTests
using MxAccessStaSession session = new(runtime, factory, new NoopEventSink()); using MxAccessStaSession session = new(runtime, factory, new NoopEventSink());
// Same rationale as the Write forwarding test above. // Same rationale as the Write forwarding test above.
session.WriteCompletionTimeout = TimeSpan.Zero; 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); await session.StartAsync(workerProcessId: 1234);
DateTime timestamp = new(2026, 5, 19, 12, 0, 0, DateTimeKind.Utc); 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(MxCommandKind.Write2, reply.Kind);
Assert.Equal(710, fakeComObject.WriteItemHandle); Assert.Equal(710, fakeComObject.WriteItemHandle);
Assert.Equal(456, fakeComObject.WriteValue); Assert.Equal(456, fakeComObject.WriteValue);
Assert.Equal(timestamp, fakeComObject.WriteTimestamp); Assert.Equal(timestamp.AddHours(-5).Ticks, Assert.IsType<DateTime>(fakeComObject.WriteTimestamp).Ticks);
Assert.Equal(6, fakeComObject.WriteUserId); Assert.Equal(6, fakeComObject.WriteUserId);
} }
@@ -1077,6 +1086,9 @@ public sealed class MxAccessCommandExecutorTests
using MxAccessStaSession session = new(runtime, factory, new NoopEventSink()); using MxAccessStaSession session = new(runtime, factory, new NoopEventSink());
// Same rationale as the WriteSecured forwarding test above. // Same rationale as the WriteSecured forwarding test above.
session.WriteCompletionTimeout = TimeSpan.Zero; 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); await session.StartAsync(workerProcessId: 1234);
DateTime timestamp = new(2026, 5, 19, 13, 30, 0, DateTimeKind.Utc); 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(ProtocolStatusCode.Ok, reply.ProtocolStatus.Code);
Assert.Equal(MxCommandKind.WriteSecured2, reply.Kind); Assert.Equal(MxCommandKind.WriteSecured2, reply.Kind);
Assert.Equal(1011, fakeComObject.WriteValue); Assert.Equal(1011, fakeComObject.WriteValue);
Assert.Equal(timestamp, fakeComObject.WriteTimestamp); Assert.Equal(timestamp.AddHours(-5).Ticks, Assert.IsType<DateTime>(fakeComObject.WriteTimestamp).Ticks);
Assert.Equal(33, fakeComObject.WriteCurrentUserId); Assert.Equal(33, fakeComObject.WriteCurrentUserId);
Assert.Equal(44, fakeComObject.WriteVerifierUserId); Assert.Equal(44, fakeComObject.WriteVerifierUserId);
} }
@@ -0,0 +1,44 @@
using System;
namespace ZB.MOM.WW.MxGateway.Worker.Tests.TestSupport;
/// <summary>
/// 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.
/// </summary>
internal static class TestTimeZones
{
/// <summary>
/// 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.
/// </summary>
public static TimeZoneInfo Eastern { get; } = CreateEastern();
/// <summary>Gets a fixed UTC-5 zone with no DST.</summary>
public static TimeZoneInfo FixedUtcMinus5 { get; } = TimeZoneInfo.CreateCustomTimeZone(
"Test UTC-5", TimeSpan.FromHours(-5), "Test UTC-5", "Test UTC-5");
/// <summary>Gets a fixed UTC+05:30 zone with no DST (a positive, non-whole-hour offset).</summary>
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 });
}
}
@@ -9,6 +9,31 @@ namespace ZB.MOM.WW.MxGateway.Worker.Conversion;
public sealed class VariantConverter public sealed class VariantConverter
{ {
private readonly TimeZoneInfo? mxAccessLocalTimeZone;
/// <summary>
/// Initializes a converter that renders timestamped-write time arguments in
/// the worker box's local zone (<see cref="TimeZoneInfo.Local"/>).
/// </summary>
public VariantConverter()
: this(mxAccessLocalTimeZone: null)
{
}
/// <summary>
/// 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.
/// </summary>
/// <param name="mxAccessLocalTimeZone">
/// Zone MXAccess reads the <c>Write2</c>/<c>WriteSecured2</c> time argument in,
/// or <see langword="null"/> for <see cref="TimeZoneInfo.Local"/> resolved per call.
/// </param>
public VariantConverter(TimeZoneInfo? mxAccessLocalTimeZone)
{
this.mxAccessLocalTimeZone = mxAccessLocalTimeZone;
}
/// <summary> /// <summary>
/// Converts an object value to an MxValue without a specified data type. /// Converts an object value to an MxValue without a specified data type.
/// </summary> /// </summary>
@@ -157,6 +182,69 @@ public sealed class VariantConverter
}; };
} }
/// <summary>
/// Converts the time argument of a timestamped write (<c>Write2</c>,
/// <c>WriteSecured2</c> and their bulk forms) into the CLR object MXAccess
/// expects. Unlike <see cref="ConvertToComValue(MxValue)"/>, a
/// <c>timestamp_value</c> instant is rendered as box-local wall-clock time.
/// </summary>
/// <remarks>
/// <para>
/// MXAccess reads the <c>VT_DATE</c> time argument as local time on the worker
/// box and converts it to UTC itself, while a <c>VT_DATE</c> carries no
/// offset and the COM marshaler ignores <see cref="DateTime.Kind"/>. 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 <c>ToTimestamp</c> treats them as UTC.
/// </para>
/// <para>
/// The UTC-to-local step uses <see cref="TimeZoneInfo.ConvertTimeFromUtc(DateTime, TimeZoneInfo)"/>
/// 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 <c>VT_DATE</c> 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.
/// </para>
/// <para>
/// Only the <c>timestamp_value</c> 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.
/// </para>
/// </remarks>
/// <param name="timestamp">Protobuf time argument of a timestamped write.</param>
/// <returns>A COM-marshalable value for the MXAccess time argument.</returns>
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);
}
/// <summary>
/// Converts a UTC instant to the wall-clock time MXAccess expects for a
/// timestamped-write time argument. See <see cref="ConvertToComTimestamp(MxValue)"/>.
/// </summary>
/// <param name="utcDateTime">UTC instant (<see cref="DateTimeKind.Utc"/> or unspecified).</param>
/// <returns>The same instant as wall-clock time in the MXAccess zone.</returns>
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) private static Array ConvertToComArray(MxArray array)
{ {
return array.ValuesCase switch return array.ValuesCase switch
@@ -497,7 +497,7 @@ public sealed class MxAccessCommandExecutor : IStaCommandExecutor
write2Command.ServerHandle, write2Command.ServerHandle,
write2Command.ItemHandle, write2Command.ItemHandle,
variantConverter.ConvertToComValue(write2Command.Value), variantConverter.ConvertToComValue(write2Command.Value),
variantConverter.ConvertToComValue(write2Command.TimestampValue), variantConverter.ConvertToComTimestamp(write2Command.TimestampValue),
write2Command.UserId); write2Command.UserId);
MxCommandReply reply = CreateOkReply(command); MxCommandReply reply = CreateOkReply(command);
@@ -580,7 +580,7 @@ public sealed class MxAccessCommandExecutor : IStaCommandExecutor
writeSecured2Command.CurrentUserId, writeSecured2Command.CurrentUserId,
writeSecured2Command.VerifierUserId, writeSecured2Command.VerifierUserId,
variantConverter.ConvertToComValue(writeSecured2Command.Value), variantConverter.ConvertToComValue(writeSecured2Command.Value),
variantConverter.ConvertToComValue(writeSecured2Command.TimestampValue)); variantConverter.ConvertToComTimestamp(writeSecured2Command.TimestampValue));
MxCommandReply reply = CreateOkReply(command); MxCommandReply reply = CreateOkReply(command);
AwaitWriteCompletion( AwaitWriteCompletion(
@@ -726,7 +726,8 @@ public sealed class MxAccessCommandExecutor : IStaCommandExecutor
session.Write2Bulk( session.Write2Bulk(
write2BulkCommand.ServerHandle, write2BulkCommand.ServerHandle,
write2BulkCommand.Entries, write2BulkCommand.Entries,
value => variantConverter.ConvertToComValue(value))); value => variantConverter.ConvertToComValue(value),
timestamp => variantConverter.ConvertToComTimestamp(timestamp)));
} }
private MxCommandReply ExecuteWriteSecuredBulk(StaCommand command) private MxCommandReply ExecuteWriteSecuredBulk(StaCommand command)
@@ -785,7 +786,8 @@ public sealed class MxAccessCommandExecutor : IStaCommandExecutor
session.WriteSecured2Bulk( session.WriteSecured2Bulk(
writeSecured2BulkCommand.ServerHandle, writeSecured2BulkCommand.ServerHandle,
writeSecured2BulkCommand.Entries, writeSecured2BulkCommand.Entries,
value => variantConverter.ConvertToComValue(value))); value => variantConverter.ConvertToComValue(value),
timestamp => variantConverter.ConvertToComTimestamp(timestamp)));
} }
private MxCommandReply ExecuteReadBulk(StaCommand command) private MxCommandReply ExecuteReadBulk(StaCommand command)
@@ -793,11 +793,16 @@ public sealed class MxAccessSession : IDisposable
/// <param name="serverHandle">The MXAccess server handle.</param> /// <param name="serverHandle">The MXAccess server handle.</param>
/// <param name="entries">The write2 entries to process.</param> /// <param name="entries">The write2 entries to process.</param>
/// <param name="convertValue">Converts protobuf MxValue to COM-compatible variant.</param> /// <param name="convertValue">Converts protobuf MxValue to COM-compatible variant.</param>
/// <param name="convertTimestamp">
/// Converts the per-entry time argument; it differs from
/// <paramref name="convertValue"/> because MXAccess reads the time argument as box-local time (#228).
/// </param>
/// <returns>The per-entry write results, in the order the entries were provided.</returns> /// <returns>The per-entry write results, in the order the entries were provided.</returns>
public IReadOnlyList<BulkWriteResult> Write2Bulk( public IReadOnlyList<BulkWriteResult> Write2Bulk(
int serverHandle, int serverHandle,
IReadOnlyList<Write2BulkEntry> entries, IReadOnlyList<Write2BulkEntry> entries,
Func<MxValue, object?> convertValue) Func<MxValue, object?> convertValue,
Func<MxValue, object?> convertTimestamp)
{ {
ThrowIfDisposed(); ThrowIfDisposed();
if (entries is null) if (entries is null)
@@ -810,6 +815,11 @@ public sealed class MxAccessSession : IDisposable
throw new ArgumentNullException(nameof(convertValue)); throw new ArgumentNullException(nameof(convertValue));
} }
if (convertTimestamp is null)
{
throw new ArgumentNullException(nameof(convertTimestamp));
}
List<BulkWriteResult> results = new(entries.Count); List<BulkWriteResult> results = new(entries.Count);
foreach (Write2BulkEntry entry in entries) foreach (Write2BulkEntry entry in entries)
{ {
@@ -820,7 +830,7 @@ public sealed class MxAccessSession : IDisposable
serverHandle, serverHandle,
entry.ItemHandle, entry.ItemHandle,
convertValue(entry.Value), convertValue(entry.Value),
convertValue(entry.TimestampValue), convertTimestamp(entry.TimestampValue),
entry.UserId))); entry.UserId)));
} }
@@ -869,11 +879,16 @@ public sealed class MxAccessSession : IDisposable
/// <param name="serverHandle">The MXAccess server handle.</param> /// <param name="serverHandle">The MXAccess server handle.</param>
/// <param name="entries">The WriteSecured2 entries to process.</param> /// <param name="entries">The WriteSecured2 entries to process.</param>
/// <param name="convertValue">Converts protobuf MxValue to COM-compatible variant.</param> /// <param name="convertValue">Converts protobuf MxValue to COM-compatible variant.</param>
/// <param name="convertTimestamp">
/// Converts the per-entry time argument; it differs from
/// <paramref name="convertValue"/> because MXAccess reads the time argument as box-local time (#228).
/// </param>
/// <returns>The per-entry write results, in the order the entries were provided.</returns> /// <returns>The per-entry write results, in the order the entries were provided.</returns>
public IReadOnlyList<BulkWriteResult> WriteSecured2Bulk( public IReadOnlyList<BulkWriteResult> WriteSecured2Bulk(
int serverHandle, int serverHandle,
IReadOnlyList<WriteSecured2BulkEntry> entries, IReadOnlyList<WriteSecured2BulkEntry> entries,
Func<MxValue, object?> convertValue) Func<MxValue, object?> convertValue,
Func<MxValue, object?> convertTimestamp)
{ {
ThrowIfDisposed(); ThrowIfDisposed();
if (entries is null) if (entries is null)
@@ -886,6 +901,11 @@ public sealed class MxAccessSession : IDisposable
throw new ArgumentNullException(nameof(convertValue)); throw new ArgumentNullException(nameof(convertValue));
} }
if (convertTimestamp is null)
{
throw new ArgumentNullException(nameof(convertTimestamp));
}
List<BulkWriteResult> results = new(entries.Count); List<BulkWriteResult> results = new(entries.Count);
foreach (WriteSecured2BulkEntry entry in entries) foreach (WriteSecured2BulkEntry entry in entries)
{ {
@@ -898,7 +918,7 @@ public sealed class MxAccessSession : IDisposable
entry.CurrentUserId, entry.CurrentUserId,
entry.VerifierUserId, entry.VerifierUserId,
convertValue(entry.Value), convertValue(entry.Value),
convertValue(entry.TimestampValue)))); convertTimestamp(entry.TimestampValue))));
} }
return results; return results;
@@ -229,6 +229,16 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
/// </summary> /// </summary>
internal TimeSpan WriteCompletionTimeout { get; set; } = ResolveWriteCompletionTimeout(); internal TimeSpan WriteCompletionTimeout { get; set; } = ResolveWriteCompletionTimeout();
/// <summary>
/// Zone the command executor renders the Write2/WriteSecured2 time
/// argument in, handed over at <see cref="StartAsync(string, int, CancellationToken)"/>.
/// <see langword="null"/> (the production value) means
/// <see cref="TimeZoneInfo.Local"/>. Internal-settable as a test seam so
/// Worker.Tests assert the #228 conversion independently of the zone of
/// the machine that runs them.
/// </summary>
internal TimeZoneInfo? MxAccessLocalTimeZone { get; set; }
/// <summary> /// <summary>
/// Cadence the alarm poll loop waits between polls. Resolved from the /// Cadence the alarm poll loop waits between polls. Resolved from the
/// launcher environment; internal-settable as a test seam (set before /// launcher environment; internal-settable as a test seam (set before
@@ -362,7 +372,7 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
staRuntime, staRuntime,
new MxAccessCommandExecutor( new MxAccessCommandExecutor(
session, session,
new VariantConverter(), new VariantConverter(MxAccessLocalTimeZone),
alarmCommandHandler, alarmCommandHandler,
// ReadBulk and the write-completion wait need to pump // ReadBulk and the write-completion wait need to pump
// Windows messages while they wait for the inbound COM // Windows messages while they wait for the inbound COM