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>
/// 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.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[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_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
+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`.
### 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.
+7
View File
@@ -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
@@ -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),
},
},
},
@@ -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);
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<DateTime>(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<DateTime>(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<DateTime>(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<DateTime>(fakeComObject.WriteTimestamp).Ticks);
Assert.Equal(33, fakeComObject.WriteCurrentUserId);
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
{
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>
/// Converts an object value to an MxValue without a specified data type.
/// </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)
{
return array.ValuesCase switch
@@ -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)
@@ -793,11 +793,16 @@ public sealed class MxAccessSession : IDisposable
/// <param name="serverHandle">The MXAccess server handle.</param>
/// <param name="entries">The write2 entries to process.</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>
public IReadOnlyList<BulkWriteResult> Write2Bulk(
int serverHandle,
IReadOnlyList<Write2BulkEntry> entries,
Func<MxValue, object?> convertValue)
Func<MxValue, object?> convertValue,
Func<MxValue, object?> 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<BulkWriteResult> 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
/// <param name="serverHandle">The MXAccess server handle.</param>
/// <param name="entries">The WriteSecured2 entries to process.</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>
public IReadOnlyList<BulkWriteResult> WriteSecured2Bulk(
int serverHandle,
IReadOnlyList<WriteSecured2BulkEntry> entries,
Func<MxValue, object?> convertValue)
Func<MxValue, object?> convertValue,
Func<MxValue, object?> 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<BulkWriteResult> 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;
@@ -229,6 +229,16 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
/// </summary>
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>
/// 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