From aec95b78c96f9e6b59175a289d82ef2688e2c4dc Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Sun, 9 Aug 2026 12:20:36 -0400 Subject: [PATCH] docs(proto): document the correlated write-completion statuses contract --- .../Generated/MxaccessGateway.cs | 24 +++++++++++++++++++ .../Protos/mxaccess_gateway.proto | 18 ++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/src/ZB.MOM.WW.MxGateway.Contracts/Generated/MxaccessGateway.cs b/src/ZB.MOM.WW.MxGateway.Contracts/Generated/MxaccessGateway.cs index f78dc5b..400e221 100644 --- a/src/ZB.MOM.WW.MxGateway.Contracts/Generated/MxaccessGateway.cs +++ b/src/ZB.MOM.WW.MxGateway.Contracts/Generated/MxaccessGateway.cs @@ -8694,6 +8694,11 @@ namespace ZB.MOM.WW.MxGateway.Contracts.Proto { } + /// + /// The unary reply's statuses field carries the correlated OnWriteComplete + /// outcome when it arrives within the worker's bounded wait — see + /// MxCommandReply.statuses. + /// [global::System.Diagnostics.DebuggerDisplayAttribute("{ToString(),nq}")] public sealed partial class WriteSecuredCommand : pb::IMessage #if !GOOGLE_PROTOBUF_REFSTRUCT_COMPATIBILITY_MODE @@ -9053,6 +9058,11 @@ namespace ZB.MOM.WW.MxGateway.Contracts.Proto { } + /// + /// The unary reply's statuses field carries the correlated OnWriteComplete + /// outcome when it arrives within the worker's bounded wait — see + /// MxCommandReply.statuses. + /// [global::System.Diagnostics.DebuggerDisplayAttribute("{ToString(),nq}")] public sealed partial class WriteSecured2Command : pb::IMessage #if !GOOGLE_PROTOBUF_REFSTRUCT_COMPATIBILITY_MODE @@ -17204,6 +17214,20 @@ namespace ZB.MOM.WW.MxGateway.Contracts.Proto { private static readonly pb::FieldCodec _repeated_statuses_codec = pb::FieldCodec.ForMessage(58, global::ZB.MOM.WW.MxGateway.Contracts.Proto.MxStatusProxy.Parser); private readonly pbc::RepeatedField statuses_ = new pbc::RepeatedField(); + /// + /// Correlated per-item outcome rows. For WRITE_SECURED / WRITE_SECURED2 + /// replies the worker holds the reply for a bounded window (default 1.5 s, + /// MXGATEWAY_WORKER_WRITE_COMPLETION_WAIT_MS) waiting for the matching + /// MXAccess OnWriteComplete callback and copies its status rows here, so + /// statuses[0] carries the real MXAccess commit outcome (success OR failure) + /// while protocol_status/hresult still describe command acceptance only. + /// Empty statuses on a write reply means the completion did not arrive + /// within the window — the write is unconfirmed, not failed. Correlation is + /// best-effort per (server_handle, item_handle): MXAccess's callback carries + /// no transaction id, so concurrent writes to the same item within the + /// window can swap rows. The OnWriteComplete event still flows on the event + /// stream unchanged. Other command kinds leave this field as before. + /// [global::System.Diagnostics.DebuggerNonUserCodeAttribute] [global::System.CodeDom.Compiler.GeneratedCode("protoc", null)] public pbc::RepeatedField Statuses { diff --git a/src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto b/src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto index be96d5a..ee923b5 100644 --- a/src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto +++ b/src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto @@ -256,6 +256,9 @@ message Write2Command { int32 user_id = 5; } +// The unary reply's statuses field carries the correlated OnWriteComplete +// outcome when it arrives within the worker's bounded wait — see +// MxCommandReply.statuses. message WriteSecuredCommand { int32 server_handle = 1; int32 item_handle = 2; @@ -266,6 +269,9 @@ message WriteSecuredCommand { MxValue value = 5; } +// The unary reply's statuses field carries the correlated OnWriteComplete +// outcome when it arrives within the worker's bounded wait — see +// MxCommandReply.statuses. message WriteSecured2Command { int32 server_handle = 1; int32 item_handle = 2; @@ -525,6 +531,18 @@ message MxCommandReply { // transport failures. optional int32 hresult = 5; MxValue return_value = 6; + // Correlated per-item outcome rows. For WRITE_SECURED / WRITE_SECURED2 + // replies the worker holds the reply for a bounded window (default 1.5 s, + // MXGATEWAY_WORKER_WRITE_COMPLETION_WAIT_MS) waiting for the matching + // MXAccess OnWriteComplete callback and copies its status rows here, so + // statuses[0] carries the real MXAccess commit outcome (success OR failure) + // while protocol_status/hresult still describe command acceptance only. + // Empty statuses on a write reply means the completion did not arrive + // within the window — the write is unconfirmed, not failed. Correlation is + // best-effort per (server_handle, item_handle): MXAccess's callback carries + // no transaction id, so concurrent writes to the same item within the + // window can swap rows. The OnWriteComplete event still flows on the event + // stream unchanged. Other command kinds leave this field as before. repeated MxStatusProxy statuses = 7; string diagnostic_message = 8;