Files
mxaccessgw/clients/rust/protos/mxaccess_worker.proto
T
Joseph Doherty 30ac3f3225 feat(worker,gateway): report record-info pin outcome in WorkerReady; drain-thread completion tests
The worker logged its MXSTATUS_PROXY record-info pin outcome only to its own
stderr, which the gateway's launcher does not capture, so operators never saw
whether the pin took.

- Contract (additive, internal IPC): WorkerReady.record_info_pin_status = 5.
  No protocol version bump; an older peer ignores it or sends it empty.
  Regenerated Contracts/Generated, the client protoset, the Rust vendored
  proto, and the Go/Python/Java worker bindings (real delta only).
- Worker: the handshake copies MxStatusProxyRecordInfoPin.Status into
  WorkerReady unless the runtime already set it.
- Gateway: WorkerClient records it (IWorkerClient.RecordInfoPinStatus, default
  null) and logs it at Information when pinned, Warning otherwise; empty is
  not logged. Shown as "Record-info pin" in the dashboard session details
  Worker table via DashboardSessionSummary.WorkerRecordInfoPinStatus.
- Tests: drain-thread cancellation (task ends Canceled; RunAsync cancels,
  runtime disposed, thread exits, no EventDrain stop-failure log) and fault
  (exception on the thread faults RunAsync with the same instance) paths;
  WorkerReady carries the pin status; gateway logging/recording and the
  dashboard projection.
- Docs: gateway.md STA thread model (drain thread, pin step in COM lifetime),
  MxAccessWorkerInstanceDesign, GatewayProcessDesign, GatewayDashboardDesign,
  WorkerFrameProtocol.
2026-11-21 08:13:27 -05:00

153 lines
5.2 KiB
Protocol Buffer

syntax = "proto3";
package mxaccess_worker.v1;
option csharp_namespace = "ZB.MOM.WW.MxGateway.Contracts.Proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";
import "mxaccess_gateway.proto";
// Wire-compatibility policy (ProtobufStyleGuide): this contract evolves
// additively only. Never renumber or repurpose an existing field number or
// enum value. When a field or enum value is removed, add a `reserved` range
// (and `reserved` name) covering it in the same change so a future editor
// cannot accidentally reuse the retired tag. There are no `reserved`
// declarations today because no field or enum value has ever been removed.
// Gateway-to-worker IPC envelope. Named-pipe framing prepends a little-endian
// uint32 payload length to this protobuf payload.
message WorkerEnvelope {
uint32 protocol_version = 1;
string session_id = 2;
uint64 sequence = 3;
string correlation_id = 4;
oneof body {
GatewayHello gateway_hello = 10;
WorkerHello worker_hello = 11;
WorkerReady worker_ready = 12;
WorkerCommand worker_command = 13;
WorkerCommandReply worker_command_reply = 14;
WorkerCancel worker_cancel = 15;
WorkerShutdown worker_shutdown = 16;
WorkerShutdownAck worker_shutdown_ack = 17;
WorkerEvent worker_event = 18;
WorkerHeartbeat worker_heartbeat = 19;
WorkerFault worker_fault = 20;
}
}
message GatewayHello {
uint32 supported_protocol_version = 1;
string nonce = 2;
string gateway_version = 3;
// Maximum worker-frame payload size, in bytes, negotiated by the gateway from its
// configured pipe limit. The worker adopts this as its frame-protocol MaxMessageBytes
// instead of a hard-coded default; 0 (an older gateway that never set the field) means
// "use the worker's built-in default". Sits above the public gRPC cap by an
// envelope-overhead margin so an accepted gRPC payload always fits one worker frame.
// Every worker->gateway frame — events, heartbeats, faults, and control replies
// including DrainEvents — must serialize within this limit; reply builders truncate
// to fit rather than emit an oversized frame.
uint32 max_frame_bytes = 4;
}
message WorkerHello {
uint32 protocol_version = 1;
string nonce = 2;
int32 worker_process_id = 3;
string worker_version = 4;
}
message WorkerReady {
int32 worker_process_id = 1;
string mxaccess_progid = 2;
string mxaccess_clsid = 3;
google.protobuf.Timestamp ready_timestamp = 4;
// Outcome of the worker's process-wide MXSTATUS_PROXY record-info pin
// (MxStatusProxyRecordInfoPin): "pinned {library-guid} vM.m record {record-guid}" on
// success, or the failing call and HRESULT / exception type otherwise. Empty when the
// worker made no attempt (an older worker, or a runtime that never created the
// MXAccess COM object). Diagnostic only: the gateway logs it and shows it on the
// dashboard, and never gates readiness on it, because the pin is a cache warm-up.
string record_info_pin_status = 5;
}
message WorkerCommand {
mxaccess_gateway.v1.MxCommand command = 1;
google.protobuf.Timestamp enqueue_timestamp = 2;
}
message WorkerCommandReply {
mxaccess_gateway.v1.MxCommandReply reply = 1;
google.protobuf.Timestamp completed_timestamp = 2;
}
message WorkerCancel {
string reason = 1;
}
message WorkerShutdown {
google.protobuf.Duration grace_period = 1;
string reason = 2;
}
message WorkerShutdownAck {
mxaccess_gateway.v1.ProtocolStatus status = 1;
}
message WorkerEvent {
mxaccess_gateway.v1.MxEvent event = 1;
}
message WorkerHeartbeat {
int32 worker_process_id = 1;
WorkerState state = 2;
google.protobuf.Timestamp last_sta_activity_timestamp = 3;
uint32 pending_command_count = 4;
uint32 outbound_event_queue_depth = 5;
uint64 last_event_sequence = 6;
string current_command_correlation_id = 7;
}
message WorkerFault {
WorkerFaultCategory category = 1;
string command_method = 2;
optional int32 hresult = 3;
string exception_type = 4;
string diagnostic_message = 5;
mxaccess_gateway.v1.ProtocolStatus protocol_status = 6;
}
enum WorkerState {
WORKER_STATE_UNSPECIFIED = 0;
WORKER_STATE_STARTING = 1;
WORKER_STATE_HANDSHAKING = 2;
WORKER_STATE_INITIALIZING_STA = 3;
WORKER_STATE_READY = 4;
WORKER_STATE_EXECUTING_COMMAND = 5;
WORKER_STATE_SHUTTING_DOWN = 6;
WORKER_STATE_STOPPED = 7;
WORKER_STATE_FAULTED = 8;
}
enum WorkerFaultCategory {
WORKER_FAULT_CATEGORY_UNSPECIFIED = 0;
// Values 1 and 2 are reserved: never emitted. Bootstrap failures (bad
// arguments, gateway authentication) exit via WorkerExitCode before the pipe
// exists, so there is no channel to carry a fault. Names kept so the numbers
// are not reused.
WORKER_FAULT_CATEGORY_INVALID_ARGUMENTS = 1;
WORKER_FAULT_CATEGORY_GATEWAY_AUTHENTICATION_FAILED = 2;
WORKER_FAULT_CATEGORY_PROTOCOL_MISMATCH = 3;
WORKER_FAULT_CATEGORY_PROTOCOL_VIOLATION = 4;
WORKER_FAULT_CATEGORY_PIPE_DISCONNECTED = 5;
WORKER_FAULT_CATEGORY_MXACCESS_CREATION_FAILED = 6;
WORKER_FAULT_CATEGORY_MXACCESS_COMMAND_FAILED = 7;
WORKER_FAULT_CATEGORY_MXACCESS_EVENT_CONVERSION_FAILED = 8;
WORKER_FAULT_CATEGORY_STA_HUNG = 9;
WORKER_FAULT_CATEGORY_QUEUE_OVERFLOW = 10;
WORKER_FAULT_CATEGORY_SHUTDOWN_TIMEOUT = 11;
}