mxaccessgw/src/MxGateway.Contracts/Protos/mxaccess_gateway.proto

syntax = "proto3";

package mxaccess_gateway.v1;

option csharp_namespace = "MxGateway.Contracts.Proto";

import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

// Public client API for MXAccess sessions hosted by the gateway.
service MxAccessGateway {
  rpc OpenSession(OpenSessionRequest) returns (OpenSessionReply);
  rpc CloseSession(CloseSessionRequest) returns (CloseSessionReply);
  rpc Invoke(MxCommandRequest) returns (MxCommandReply);
  rpc StreamEvents(StreamEventsRequest) returns (stream MxEvent);
}

message OpenSessionRequest {
  string requested_backend = 1;
  string client_session_name = 2;
  string client_correlation_id = 3;
  google.protobuf.Duration command_timeout = 4;
}

message OpenSessionReply {
  string session_id = 1;
  string backend_name = 2;
  int32 worker_process_id = 3;
  uint32 worker_protocol_version = 4;
  repeated string capabilities = 5;
  google.protobuf.Duration default_command_timeout = 6;
  ProtocolStatus protocol_status = 7;
}

message CloseSessionRequest {
  string session_id = 1;
  string client_correlation_id = 2;
}

message CloseSessionReply {
  string session_id = 1;
  SessionState final_state = 2;
  ProtocolStatus protocol_status = 3;
}

message StreamEventsRequest {
  string session_id = 1;
  uint64 after_worker_sequence = 2;
}

message MxCommandRequest {
  string session_id = 1;
  string client_correlation_id = 2;
  MxCommand command = 3;
}

message MxCommand {
  MxCommandKind kind = 1;

  oneof payload {
    RegisterCommand register = 10;
    UnregisterCommand unregister = 11;
    AddItemCommand add_item = 12;
    AddItem2Command add_item2 = 13;
    RemoveItemCommand remove_item = 14;
    AdviseCommand advise = 15;
    UnAdviseCommand un_advise = 16;
    AdviseSupervisoryCommand advise_supervisory = 17;
    AddBufferedItemCommand add_buffered_item = 18;
    SetBufferedUpdateIntervalCommand set_buffered_update_interval = 19;
    SuspendCommand suspend = 20;
    ActivateCommand activate = 21;
    WriteCommand write = 22;
    Write2Command write2 = 23;
    WriteSecuredCommand write_secured = 24;
    WriteSecured2Command write_secured2 = 25;
    AuthenticateUserCommand authenticate_user = 26;
    ArchestrAUserToIdCommand archestra_user_to_id = 27;
    PingCommand ping = 100;
    GetSessionStateCommand get_session_state = 101;
    GetWorkerInfoCommand get_worker_info = 102;
    DrainEventsCommand drain_events = 103;
    ShutdownWorkerCommand shutdown_worker = 104;
  }
}

enum MxCommandKind {
  MX_COMMAND_KIND_UNSPECIFIED = 0;
  MX_COMMAND_KIND_REGISTER = 1;
  MX_COMMAND_KIND_UNREGISTER = 2;
  MX_COMMAND_KIND_ADD_ITEM = 3;
  MX_COMMAND_KIND_ADD_ITEM2 = 4;
  MX_COMMAND_KIND_REMOVE_ITEM = 5;
  MX_COMMAND_KIND_ADVISE = 6;
  MX_COMMAND_KIND_UN_ADVISE = 7;
  MX_COMMAND_KIND_ADVISE_SUPERVISORY = 8;
  MX_COMMAND_KIND_ADD_BUFFERED_ITEM = 9;
  MX_COMMAND_KIND_SET_BUFFERED_UPDATE_INTERVAL = 10;
  MX_COMMAND_KIND_SUSPEND = 11;
  MX_COMMAND_KIND_ACTIVATE = 12;
  MX_COMMAND_KIND_WRITE = 13;
  MX_COMMAND_KIND_WRITE2 = 14;
  MX_COMMAND_KIND_WRITE_SECURED = 15;
  MX_COMMAND_KIND_WRITE_SECURED2 = 16;
  MX_COMMAND_KIND_AUTHENTICATE_USER = 17;
  MX_COMMAND_KIND_ARCHESTRA_USER_TO_ID = 18;
  MX_COMMAND_KIND_PING = 100;
  MX_COMMAND_KIND_GET_SESSION_STATE = 101;
  MX_COMMAND_KIND_GET_WORKER_INFO = 102;
  MX_COMMAND_KIND_DRAIN_EVENTS = 103;
  MX_COMMAND_KIND_SHUTDOWN_WORKER = 104;
}

message RegisterCommand {
  string client_name = 1;
}

message UnregisterCommand {
  int32 server_handle = 1;
}

message AddItemCommand {
  int32 server_handle = 1;
  string item_definition = 2;
}

message AddItem2Command {
  int32 server_handle = 1;
  string item_definition = 2;
  string item_context = 3;
}

message RemoveItemCommand {
  int32 server_handle = 1;
  int32 item_handle = 2;
}

message AdviseCommand {
  int32 server_handle = 1;
  int32 item_handle = 2;
}

message UnAdviseCommand {
  int32 server_handle = 1;
  int32 item_handle = 2;
}

message AdviseSupervisoryCommand {
  int32 server_handle = 1;
  int32 item_handle = 2;
}

message AddBufferedItemCommand {
  int32 server_handle = 1;
  string item_definition = 2;
  string item_context = 3;
}

message SetBufferedUpdateIntervalCommand {
  int32 server_handle = 1;
  int32 update_interval_milliseconds = 2;
}

message SuspendCommand {
  int32 server_handle = 1;
  int32 item_handle = 2;
}

message ActivateCommand {
  int32 server_handle = 1;
  int32 item_handle = 2;
}

message WriteCommand {
  int32 server_handle = 1;
  int32 item_handle = 2;
  MxValue value = 3;
  int32 user_id = 4;
}

message Write2Command {
  int32 server_handle = 1;
  int32 item_handle = 2;
  MxValue value = 3;
  MxValue timestamp_value = 4;
  int32 user_id = 5;
}

message WriteSecuredCommand {
  int32 server_handle = 1;
  int32 item_handle = 2;
  int32 current_user_id = 3;
  int32 verifier_user_id = 4;
  // Credential-sensitive write value. Implementations must not log this field
  // unless an explicit redacted value-logging path is enabled.
  MxValue value = 5;
}

message WriteSecured2Command {
  int32 server_handle = 1;
  int32 item_handle = 2;
  int32 current_user_id = 3;
  int32 verifier_user_id = 4;
  // Credential-sensitive write value. Implementations must not log this field
  // unless an explicit redacted value-logging path is enabled.
  MxValue value = 5;
  MxValue timestamp_value = 6;
}

message AuthenticateUserCommand {
  int32 server_handle = 1;
  string verify_user = 2;
  // Raw MXAccess credential. Implementations must keep this field out of logs,
  // metrics labels, command lines, and diagnostics.
  string verify_user_password = 3;
}

message ArchestrAUserToIdCommand {
  int32 server_handle = 1;
  string user_id_guid = 2;
}

message PingCommand {
  string message = 1;
}

message GetSessionStateCommand {
}

message GetWorkerInfoCommand {
}

message DrainEventsCommand {
  uint32 max_events = 1;
}

message ShutdownWorkerCommand {
  google.protobuf.Duration grace_period = 1;
}

message MxCommandReply {
  string session_id = 1;
  string correlation_id = 2;
  MxCommandKind kind = 3;
  ProtocolStatus protocol_status = 4;
  // HRESULT captured from MXAccess or a COM exception. This remains separate
  // from gateway protocol status so MXAccess parity details are not hidden by
  // transport failures.
  optional int32 hresult = 5;
  MxValue return_value = 6;
  repeated MxStatusProxy statuses = 7;
  string diagnostic_message = 8;

  oneof payload {
    RegisterReply register = 20;
    AddItemReply add_item = 21;
    AddItem2Reply add_item2 = 22;
    AddBufferedItemReply add_buffered_item = 23;
    SuspendReply suspend = 24;
    ActivateReply activate = 25;
    AuthenticateUserReply authenticate_user = 26;
    ArchestrAUserToIdReply archestra_user_to_id = 27;
    SessionStateReply session_state = 100;
    WorkerInfoReply worker_info = 101;
    DrainEventsReply drain_events = 102;
  }
}

message RegisterReply {
  int32 server_handle = 1;
}

message AddItemReply {
  int32 item_handle = 1;
}

message AddItem2Reply {
  int32 item_handle = 1;
}

message AddBufferedItemReply {
  int32 item_handle = 1;
}

message SuspendReply {
  MxStatusProxy status = 1;
}

message ActivateReply {
  MxStatusProxy status = 1;
}

message AuthenticateUserReply {
  int32 user_id = 1;
}

message ArchestrAUserToIdReply {
  int32 user_id = 1;
}

message SessionStateReply {
  SessionState state = 1;
}

message WorkerInfoReply {
  int32 worker_process_id = 1;
  string worker_version = 2;
  string mxaccess_progid = 3;
  string mxaccess_clsid = 4;
}

message DrainEventsReply {
  repeated MxEvent events = 1;
}

message MxEvent {
  MxEventFamily family = 1;
  string session_id = 2;
  int32 server_handle = 3;
  int32 item_handle = 4;
  MxValue value = 5;
  int32 quality = 6;
  google.protobuf.Timestamp source_timestamp = 7;
  repeated MxStatusProxy statuses = 8;
  uint64 worker_sequence = 9;
  google.protobuf.Timestamp worker_timestamp = 10;
  google.protobuf.Timestamp gateway_receive_timestamp = 11;
  optional int32 hresult = 12;
  string raw_status = 13;

  oneof body {
    OnDataChangeEvent on_data_change = 20;
    OnWriteCompleteEvent on_write_complete = 21;
    OperationCompleteEvent operation_complete = 22;
    OnBufferedDataChangeEvent on_buffered_data_change = 23;
  }
}

enum MxEventFamily {
  MX_EVENT_FAMILY_UNSPECIFIED = 0;
  MX_EVENT_FAMILY_ON_DATA_CHANGE = 1;
  MX_EVENT_FAMILY_ON_WRITE_COMPLETE = 2;
  MX_EVENT_FAMILY_OPERATION_COMPLETE = 3;
  MX_EVENT_FAMILY_ON_BUFFERED_DATA_CHANGE = 4;
}

message OnDataChangeEvent {
}

message OnWriteCompleteEvent {
}

message OperationCompleteEvent {
}

message OnBufferedDataChangeEvent {
  MxDataType data_type = 1;
  MxArray quality_values = 2;
  MxArray timestamp_values = 3;
  int32 raw_data_type = 4;
}

message MxStatusProxy {
  int32 success = 1;
  MxStatusCategory category = 2;
  MxStatusSource detected_by = 3;
  int32 detail = 4;
  int32 raw_category = 5;
  int32 raw_detected_by = 6;
  string diagnostic_text = 7;
}

enum MxStatusCategory {
  MX_STATUS_CATEGORY_UNSPECIFIED = 0;
  MX_STATUS_CATEGORY_UNKNOWN = 1;
  MX_STATUS_CATEGORY_OK = 2;
  MX_STATUS_CATEGORY_PENDING = 3;
  MX_STATUS_CATEGORY_WARNING = 4;
  MX_STATUS_CATEGORY_COMMUNICATION_ERROR = 5;
  MX_STATUS_CATEGORY_CONFIGURATION_ERROR = 6;
  MX_STATUS_CATEGORY_OPERATIONAL_ERROR = 7;
  MX_STATUS_CATEGORY_SECURITY_ERROR = 8;
  MX_STATUS_CATEGORY_SOFTWARE_ERROR = 9;
  MX_STATUS_CATEGORY_OTHER_ERROR = 10;
}

enum MxStatusSource {
  MX_STATUS_SOURCE_UNSPECIFIED = 0;
  MX_STATUS_SOURCE_UNKNOWN = 1;
  MX_STATUS_SOURCE_REQUESTING_LMX = 2;
  MX_STATUS_SOURCE_RESPONDING_LMX = 3;
  MX_STATUS_SOURCE_REQUESTING_NMX = 4;
  MX_STATUS_SOURCE_RESPONDING_NMX = 5;
  MX_STATUS_SOURCE_REQUESTING_AUTOMATION_OBJECT = 6;
  MX_STATUS_SOURCE_RESPONDING_AUTOMATION_OBJECT = 7;
}

message MxValue {
  MxDataType data_type = 1;
  string variant_type = 2;
  bool is_null = 3;
  string raw_diagnostic = 4;
  int32 raw_data_type = 5;

  oneof kind {
    bool bool_value = 10;
    int32 int32_value = 11;
    int64 int64_value = 12;
    float float_value = 13;
    double double_value = 14;
    string string_value = 15;
    google.protobuf.Timestamp timestamp_value = 16;
    MxArray array_value = 17;
    bytes raw_value = 18;
  }
}

message MxArray {
  MxDataType element_data_type = 1;
  string variant_type = 2;
  repeated uint32 dimensions = 3;
  string raw_diagnostic = 4;
  int32 raw_element_data_type = 5;

  oneof values {
    BoolArray bool_values = 10;
    Int32Array int32_values = 11;
    Int64Array int64_values = 12;
    FloatArray float_values = 13;
    DoubleArray double_values = 14;
    StringArray string_values = 15;
    TimestampArray timestamp_values = 16;
    RawArray raw_values = 17;
  }
}

message BoolArray {
  repeated bool values = 1;
}

message Int32Array {
  repeated int32 values = 1;
}

message Int64Array {
  repeated int64 values = 1;
}

message FloatArray {
  repeated float values = 1;
}

message DoubleArray {
  repeated double values = 1;
}

message StringArray {
  repeated string values = 1;
}

message TimestampArray {
  repeated google.protobuf.Timestamp values = 1;
}

message RawArray {
  repeated bytes values = 1;
}

enum MxDataType {
  MX_DATA_TYPE_UNSPECIFIED = 0;
  MX_DATA_TYPE_UNKNOWN = 1;
  MX_DATA_TYPE_NO_DATA = 2;
  MX_DATA_TYPE_BOOLEAN = 3;
  MX_DATA_TYPE_INTEGER = 4;
  MX_DATA_TYPE_FLOAT = 5;
  MX_DATA_TYPE_DOUBLE = 6;
  MX_DATA_TYPE_STRING = 7;
  MX_DATA_TYPE_TIME = 8;
  MX_DATA_TYPE_ELAPSED_TIME = 9;
  MX_DATA_TYPE_REFERENCE_TYPE = 10;
  MX_DATA_TYPE_STATUS_TYPE = 11;
  MX_DATA_TYPE_ENUM = 12;
  MX_DATA_TYPE_SECURITY_CLASSIFICATION_ENUM = 13;
  MX_DATA_TYPE_DATA_QUALITY_TYPE = 14;
  MX_DATA_TYPE_QUALIFIED_ENUM = 15;
  MX_DATA_TYPE_QUALIFIED_STRUCT = 16;
  MX_DATA_TYPE_INTERNATIONALIZED_STRING = 17;
  MX_DATA_TYPE_BIG_STRING = 18;
  MX_DATA_TYPE_END = 19;
}

message ProtocolStatus {
  ProtocolStatusCode code = 1;
  string message = 2;
}

enum ProtocolStatusCode {
  PROTOCOL_STATUS_CODE_UNSPECIFIED = 0;
  PROTOCOL_STATUS_CODE_OK = 1;
  PROTOCOL_STATUS_CODE_INVALID_REQUEST = 2;
  PROTOCOL_STATUS_CODE_SESSION_NOT_FOUND = 3;
  PROTOCOL_STATUS_CODE_SESSION_NOT_READY = 4;
  PROTOCOL_STATUS_CODE_WORKER_UNAVAILABLE = 5;
  PROTOCOL_STATUS_CODE_TIMEOUT = 6;
  PROTOCOL_STATUS_CODE_CANCELED = 7;
  PROTOCOL_STATUS_CODE_PROTOCOL_VIOLATION = 8;
  PROTOCOL_STATUS_CODE_MXACCESS_FAILURE = 9;
}

enum SessionState {
  SESSION_STATE_UNSPECIFIED = 0;
  SESSION_STATE_CREATING = 1;
  SESSION_STATE_STARTING_WORKER = 2;
  SESSION_STATE_WAITING_FOR_PIPE = 3;
  SESSION_STATE_HANDSHAKING = 4;
  SESSION_STATE_INITIALIZING_WORKER = 5;
  SESSION_STATE_READY = 6;
  SESSION_STATE_CLOSING = 7;
  SESSION_STATE_CLOSED = 8;
  SESSION_STATE_FAULTED = 9;
}