// NOTICE: SEMI makes no warranties or representations as to the suitability of
// the standards set forth herein for any particular application. The
// determination of the suitability of the standard is solely the responsibility
// of the user. Users are cautioned to refer to manufacturer's instructions,
// product labels, product data sheets, and other relevant literature,
// respecting any materials or equipment mentioned herein. These standards
// are subject to change without notice.
//
// By publication of this standard, Semiconductor Equipment and Materials
// International (SEMI) takes no position respecting the validity of any patent
// rights or copyrights asserted in connection with any items mentioned in this
// standard. Users of this standard are expressly advised that determination of
// any such patent rights or copyrights, and the risk of infringement of such
// rights are entirely their own responsibility.

// This proto file will define representations of objects in SEMI E132 in the Protocol Buffer 3 language

syntax = "proto3";

package semi;

// Import statements allow Protocol Buffer messages defined in this .proto file to use
// Protocol Buffer messages defined in other .proto files
// Import statements need to match the filenames of the corresponding .proto files to import for
// this .proto file to compile properly.
//
// This .proto file can import .proto files corresponding to newer revisions of SEMI Standards
// used by this SEMI Standard as long as they are compatible (e.g. the SEMI standard revision corresponding
// to the .proto file to import is the latest revision referenced by the SEMI standard corresponding to this
// .proto file.
// * This allows referenced SEMI Standards to be updated without having to constantly update the import statements
//   used by this .proto file.
// * For example, implementers can update the import statement referencing the .proto file corresponding to a newer
//   revision of SEMI E179.
// * If a specific revision of the referenced SEMI Standard is required, this .proto file will be explicitly updated to
//   import the corresponding .proto file of the referenced SEMI standard as part of updates to this .proto file.

import "semi_e179-1224.proto";

import "google/protobuf/descriptor.proto";

// ***************************************************************
// Version information
// ***************************************************************

// Protobuf3 doesn't support the concept of constants
// We want a way for the implementor to get the .proto file version
// if they want to log or check this information.
// We workaround the issue by exposing a file attribute with the version information
// Information corresponding to the associated SEMI Standard as a custom file option on the .proto file.
//
// Note - the proto_buf_file_version will uniquely identify the .proto file version.
// * For the .proto file associated with the official standard, the proto_buf_file_version will
//   be the SEMI Standard version (including the publication date in MMYY format)
//   For example,
//     proto_buf_file_version="E134.2-MMYY" will indicate this .proto file is for
//     an official SEMI Version (SEMI E134.2-MMYY)
// * If the .proto file is for an interim release (for example as part of a ballot),
//   suffix information along the lines of "-Ballot<nnnn>-<Date>" can be added.
//   For example,
//     proto_buf_file_version="E134.2-Ballot1234-20180522" will indicate this .proto file is an interim version for
//     SEMI E134.2-XXXX Ballot 1234 and was released on May 22, 2018
//
// Note - semi_standard_information Field is defined once in the SEMI E179 .proto file

option (semi_standard_information) =
{
  semi_standard : "SEMI E132.2",
  proto_buf_file_version : "SEMIE132-02-1224"
};

// ***************************************************************
// Enumerated Type Definitions
// ***************************************************************

// Best Practice is to specify Unknown element as index 0 for future proofing
// Enum elements need to be unique across the namespace, so make sure Unknown element name
// is meaningful to the enum.

// Defines notification message destinations
enum NotificationDestination
{
  NOTIFICATION_DESTINATION_UNSPECIFIED = 0;   // Value when unspecified enum value is received - per Protocol Buffers best practice
  CLIENT_ONLY = 1;                            // Only to the Client.
  CONSUMER_ONLY = 2;                          // Only to the Consumer.
  BOTH = 3;                                   // Both the Client and Consumer.
  NONE = 4;                                   // Equipment Server does not any send notification messages for this session.

  reserved 5 to 999;                          // Reserved for future use
}

// Defines operational message destinations
enum OperationalDestination
{
  OPERATIONAL_DESTINATION_UNSPECIFIED = 0;    // Value when unspecified enum value is received - per Protocol Buffers best practice
  CLIENT = 1;                                 // To the Client.
  CONSUMER = 2;                               // To the Consumer.
  NO_OPERATIONAL_DESTINATION = 3;             // Equipment Server does not any send operational messages for this session.
                                              // Maps to the SEMI E132 OperationalDestination.None value

  reserved 4 to 999;                          // Reserved for future use
}

// ***************************************************************
// Message Definitions
// ***************************************************************

// Specifies a network connection point
// This is different than a URL, which also includes the webservice information
message PortConfigurationType
{
  string target_address = 1;        // Target Address of the network connection point
  uint32 port_number = 2;           // Port to connect to
  bool use_secure_connection = 3;   // Indicates if this should be a secure connection
}

// The HTTP Endpoint can be either a URL, or a connection point
// For endpoints using gRPC/Protocol Buffers, ConnectionPort should be specified
// Url should be used with Freeze 2 interfaces (using HTTP1.1 with SOAP/XML)
message HttpEndPointType    
{
  oneof endpoint
  {
    string url = 1;         
    PortConfigurationType connection_port = 2;
  }
}

message ActiveSessionType   
{
  string session_id = 1;    
  string client_id = 2;     
  OperationalDestination operational_recipient = 3;

  oneof endpoint
  {
    HttpEndPointType session_end_point = 4;   
                                              
  }
}

message PrincipalType   
{
  string principal_id = 1;    

  bytes salt = 2;             
  bytes password_hash = 3;    
}

message RoleType    
{
  string role_id = 1;   

}

message RoleAssignmentType    
{
  PrincipalType principal = 1;    
  RoleType role = 2;              
}

message SubjectSelectorType   
{
  oneof acl_entry_type              
  {
    PrincipalType principal = 1;    // INTERNAL -<xsd:element name="Principal" type="PrincipalType" nillable="false"/>
    RoleType role = 2;              
  }

}

message PrivilegeAssignmentType   
{
  SubjectSelectorType subject = 1;    
  repeated string privileges = 2;     // Privilege is the PrivilegeId        
}

message ACLEntrySelectorType    
{
  oneof assignment
  {
    PrivilegeAssignmentType privilege_assignment = 1;   
    RoleAssignmentType role_assignment = 2;             
  }
}

message UnauthorizedOperationType   
{
  string description = 1;                     
  repeated string required_privileges = 2;    // RequiredPrivilege is the PrivilegeId  
}

message UnrecognizedPrivilegeType   
{
  string description = 1;                         
  repeated string unrecognized_privileges = 2;    // UnrecognizedPrivilege is the PrivilegeId     
}

// Get information about the Equipment Server
// This operation does not require SessionID metadata
message GetEquipmentInformationRequestType
{
  string equipment_id = 1;    // Identifies the Equipment Server
  string client_id = 2;       // Identifies the Client
}

message GetEquipmentInformationResponseType
{
  bytes salt = 1;               // Salt value to use with hashing functions
  bytes challenge_token = 2;    // Challenge token for EstablishSession authentication

  oneof error_information
  {
    ErrorType error = 3;        // Use this for regular errors that use ErrorType content
                                // for example Equipment Server not ready
  }
}

// Request changing ACL password
message ChangeACLPasswordRequestType
{
  string client_id = 1;           // Identifies the Client
  bytes salt = 2;                 // Salt value to use with hashing functions
  bytes acl_password_hash = 3;    // New hashed ACL password for the ACLEntry specified by the clientId parameter.  Value cannot be null.
}

message ChangeACLPasswordResponseType
{
  oneof error_information
  {
    ErrorType error = 1;          // Use this for regular errors that use ErrorType content
                                  // for example UnrecognizedSession
    UnauthorizedOperationType unauthorized_operation_error = 2;       
  }
}

// Check if the Equipment Server is alive
message IsEquipmentServerAliveRequestType
{
}

message IsEquipmentServerAliveResponseType
{
  string equipment_id = 1;    // Identifies the Equipment Server
  oneof error_information
  {
    ErrorType error = 2;      // Use this for regular errors that use ErrorType content
                              // for example UnrecognizedSession
  }
}

message EstablishSessionRequestType   
{
  string equipment_id = 1;                                // Identifies the Equipment
  string client_id = 2;                                   // Identifies the Client
  bytes challenge_password_hash = 3;                      // Hashed value used for authentication
  OperationalDestination operational_recipient = 4;       // Specifies who receives the operational messages for this session
  NotificationDestination notification_recipients = 5;    // Specifies who receives notification messages for this session

  oneof endpoint
  {
    HttpEndPointType http_end_point = 6;                  
                                                          
  }
}

message EstablishSessionResponseType    
{
  string session_id = 1;    // Generated SessionID   
  oneof error_information   
                            
  {
    ErrorType error = 2;    // Use this for regular errors that use ErrorType content
                            // for example MaxSessionLimitExceeded, SystemShuttingDown, InvalidEndpoint
                            // InvalidNotificationRecipients, SpecifiedACLAlreadyHasActiveSession
  }
}

// INTERNAL -

// INTERNAL -

// INTERNAL -

message CloseSessionRequestType     
{
  string session_id_to_close = 1;   // SessionId to close           
}

message CloseSessionResponseType    
{
  oneof error_information           
                                    
  {
    ErrorType error = 1;            // Use this for regular errors that use ErrorType content
                                    // for example UnrecognizedSession
    UnauthorizedOperationType unauthorized_operation_error = 2;       
  }
}

// Note - cannot change the endpoint to a null value.
// Note - If a session changes so there is no Consumer associated with the session anymore
// close the session. (Cannot change the endpoint to a null value).
message InitiateChangeSessionEndpointRequestType
{
  HttpEndPointType end_point = 1;   // New endpoint information     
}

message InitiateChangeSessionEndpointResponseType
{
  oneof error_information           
  {
    ErrorType error = 2;            // Use this for regular errors that use ErrorType content
                                    // for example InvalidEndpoint, UnrecognizedSession, SystemShuttingDown
    UnauthorizedOperationType unauthorized_operation_error = 3;
  }
}

message SessionClosedNotificationType 
{
  // Session that was closed
  string session_id_hash = 1;   // Since this message is part of the SEMI E132 SessionClient interface, ID values are hashed
                                // ID is SessionId
}

message AclPasswordChangedNotificationType
{
  // Session whose clientId's ACL password changed
  string session_id_hash = 1;   // Since this message is part of the SEMI E132 SessionClient interface, ID values are hashed
                                // ID is SessionId
}

// SessionPing can be sent by Equipment Server
// The message could be sent in a request stream or a response stream
// so the message name doesn't include Request or Response keyword to avoid confusion
// For example, the SessionPingQueryType message can be sent in a Request Stream

message SessionPingQueryType    
{
}

// SessionPing can be sent by Equipment Server
// The message could be sent in a request stream or a response stream
// so the message name doesn't include Request or Response keyword to avoid confusion
// The SessionID is sent as part of the gRPC metadata
// If the SessionID is unrecognized, the streaming gRPC method should fail

message SessionPingAnswerType   
{
  // If the Query was sent by the Equipment Server, this value will be the ClientId
  // The gRPC connection this message will be sent on is not secure, so the
  // ID should be hashed (and IdHash field should be populated)
  oneof reported_id
  {
    string id = 1;          // ID value in plain-text
                            
    string id_hash = 2;     // ID value hashed
  }

  oneof error_information   
                            
  {
    ErrorType error = 3;    // Use this for regular errors that use ErrorType content
                            // For example, NotReady
  }
}

message SessionEstablishedNotificationType
{
  bool from_frozen = 1;     // Indicates if the session was restored from FROZEN state
}

message SessionFrozenNotificationType   
{
}

// Notification that the request to change the session endpoint with an InitiateChangeSessionEndpoint() operation is complete.
message InitiateChangeSessionEndpointCompleteNotificationType
{
  HttpEndPointType new_end_point = 1;   // New endpoint where session data was requested to be sent to

  oneof error_information               // INTERNAL -Use same Error structure as other response messages
  {
    ErrorType error = 2;                // Use this for regular errors that use ErrorType content
                                        // for example Could not change the session endpoint
  }
}

message SessionEndpointChangedNotificationType
{
  HttpEndPointType new_end_point = 1;         // New endpoint where operational messages are being sent

  HttpEndPointType previous_end_point = 2;    // Previous endpoint where operational messages were sent
                                              
}

message DefinedPrivilegeType    
{
  string privilege_id = 1;      
  string description = 2;       
}

message GetDefinedPrivilegesRequestType   
{
}

message GetDefinedPrivilegesResponseType    
{
  repeated DefinedPrivilegeType privileges = 1;   

  oneof error_information                         
                                                  
  {
    ErrorType error = 2;                          // Use this for regular errors that use ErrorType content
                                                  // for example UnrecognizedSession
    UnauthorizedOperationType unauthorized_operation_error = 3;   
  }
}

message GetACLRequestType   
{
}

message GetACLResponseType    

{
  repeated ACLEntrySelectorType acl_entries = 1;    

  oneof error_information                           
                                                    
  {
    ErrorType error = 2;                            // Use this for regular errors that use ErrorType content
                                                    // for example UnrecognizedSession
    UnauthorizedOperationType unauthorized_operation_error = 3;   
  }
}

message AddACLEntryRequestType    
{
  ACLEntrySelectorType acl_entry = 1;   
}

message AddACLEntryResponseType   
{
  oneof error_information   
                            
   {
    ErrorType error = 2;    // Use this for regular errors that use ErrorType content
                            // for example DuplicateEntryFound, UnrecognizedRole, UnrecognizedSession
    UnauthorizedOperationType unauthorized_operation_error = 3;       
    UnrecognizedPrivilegeType unrecognized_privilege_error = 4;       
  }
}

message DeleteACLEntryRequestType   
{
  string subject_id = 1;    
}

message DeleteACLEntryResponseType    
{
  oneof error_information   
                            
  {
    ErrorType error = 2;    // Use this for regular errors that use ErrorType content
                            // for example EntryNotFound,UnrecognizedSession, DeletingRoleWithPrincipalsAssigned
    UnauthorizedOperationType unauthorized_operation_error = 3;   
  }
}

message GetActiveSessionsRequestType    
{
}

message GetActiveSessionsResponseType   
{
  repeated ActiveSessionType active_sessions = 1;   

  oneof error_information                           
                                                    
  {
    ErrorType error = 2;                            // Use this for regular errors that use ErrorType content
                                                    // for example UnrecognizedSession
    UnauthorizedOperationType unauthorized_operation_error = 3;   
  }
}

message SetMaxSessionsRequestType   
{
  uint32 max_sessions = 1;    
}

message SetMaxSessionsResponseType    
{
  uint32 session_count = 1;   

  oneof error_information     
                              
  {
    ErrorType error = 2;      // Use this for regular errors that use ErrorType content
                              // for example UnrecognizedSession
    UnauthorizedOperationType unauthorized_operation_error = 3;   
  }
}

message GetMaxSessionsRequestType   
{
}

message GetMaxSessionsResponseType    
{

  uint32 max_session = 1;     
                              
  uint32 session_count = 2;   

  oneof error_information     
                              
  {
    ErrorType error = 3;      // Use this for regular errors that use ErrorType content
                              // for example UnrecognizedSession
    UnauthorizedOperationType unauthorized_operation_error = 4;   
  }
}

message SetSessionPingSettingsRequestType
{
  uint32 ping_interval = 1;
  uint32 ping_response_timeout = 2;
  uint32 ping_maximum_failures = 3;
  uint32 ping_retry_interval = 4;
}

message SetSessionPingSettingsResponseType
{
  oneof error_information
  {
    ErrorType error = 2;    // Use this for regular errors that use ErrorType content
                            // for example SystemShuttingDown, InvalidNewSessionPingSettings
    UnauthorizedOperationType unauthorized_operation_error = 3;
  }
}

message GetSessionPingSettingsRequestType
{
}

message GetSessionPingSettingsResponseType
{
  uint32 ping_interval = 1;
  uint32 ping_response_timeout = 2;
  uint32 ping_maximum_failures = 3;
  uint32 ping_retry_interval = 4;

  oneof error_information
  {
    ErrorType error = 5;    // Use this for regular errors that use ErrorType content
                            // for example SystemShuttingDown
    UnauthorizedOperationType unauthorized_operation_error = 6;
  }
}

message GetNewSaltRequestType
{
}

message GetNewSaltResponseType
{
  bytes salt = 1;
  oneof error_information
  {
    ErrorType error = 2;    // Use this for regular errors that use ErrorType content
                            // for example SystemShuttingDown
    UnauthorizedOperationType unauthorized_operation_error = 3;
  }
}

// Container message for all the items that could be sent on the stream to the Equipment Server
// related to session usage
message SessionUsageStreamRequest
{
  oneof request
  {
    SessionPingAnswerType session_ping_answer_from_receiver = 1;    
  }
}

// Container message for all the items that could be sent on the stream from the Equipment Server
// related to session usage
// Note - Since this streaming method can be used by a Client, the SessionPing from the Equipment Server message is included.
message SessionUsageStreamResponse
{
  oneof result
  {
    // INTERNAL – Equipment Server does not respond to a SessionPing from the EDA Client, so no need for SessionPingResponse
    
    SessionEstablishedNotificationType session_established_notification = 1;
    SessionFrozenNotificationType session_frozen_notification = 2;    
    SessionClosedNotificationType session_closed_notification = 3;    
    SessionPingQueryType session_ping_query_to_receiver = 4;          
    InitiateChangeSessionEndpointCompleteNotificationType initiate_change_session_endpoint_complete_notification = 5;
    SessionEndpointChangedNotificationType session_endpoint_changed_notification = 6;
    AclPasswordChangedNotificationType acl_password_changed_notification = 7;
  }
}

// Container message for all the items that could be sent on the stream from the Equipment Server
// related to session information
// Note - this interface is for the Equipment Server to push information to the Consumer.
message ConsumerSessionUsageStreamRequest
{
  oneof request
  {
    SessionPingQueryType session_ping_query_to_receiver = 1;          
    SessionEstablishedNotificationType session_established_notification = 2;
    SessionFrozenNotificationType session_frozen_notification = 3;    
    SessionClosedNotificationType session_closed_notification = 4;    
    InitiateChangeSessionEndpointCompleteNotificationType initiate_change_session_endpoint_complete_notification = 5;
    SessionEndpointChangedNotificationType session_endpoint_changed_notification = 6;
    AclPasswordChangedNotificationType acl_password_changed_notification = 7;
  }
}

// Container message for all the items that could be sent on the stream to the Equipment Server
// related to session information
// Note - this interface is for the Equipment Server to receive information from the Consumer.
message ConsumerSessionUsageStreamResponse
{
  oneof result
  {
    SessionPingAnswerType session_ping_answer_from_receiver = 1;    
  }
}

message EquipmentInterfaceDescriptionType   
{
  string name = 1;                                
  string description = 2;                         
  repeated SessionGroupType session_groups = 3;   
}

message SessionGroupType    
{
  string name = 1;                                                
  string description = 2;                                         
  InterfaceDescriptionType session_manager = 3;                   
  InterfaceDescriptionType security_admin = 4;                    
  repeated InterfaceDescriptionType interface_descriptions = 5;   
}

message InterfaceDescriptionType  
{
  string name = 1;                
  string description = 2;         

  // Only one of URL or ConnectionPort can be specified, so the oneof structure will be used
  oneof endpoint
  {
    string url = 3;               
                                  
    PortConfigurationType connection_port = 4;
  }

  string standard = 5;            
  string standard_name = 6;       
  string standard_version = 7;    
}

// Since the GetInterface is available to everyone, SessionId information is not required as a parameter
message GetInterfacesRequestType    
{
}

// Since the GetInterface is available to everyone, SessionId information is not required as a parameter
message GetInterfacesResponseType   
{
  repeated EquipmentInterfaceDescriptionType equipment_interface_descriptions = 1;   
}

message ConfirmConnectionRequestType
{
}

message ConfirmConnectionResponseType
{
}

// ***************************************************************
// Service Definitions
// ***************************************************************

// This gRPC service looks after security administration functionality defined in SEMI E132.
service E132SecurityAdmin
{
  // *********************************************************************
  // Unary Request/Response methods to manage Security metadata
  // *********************************************************************

  rpc GetDefinedPrivileges (GetDefinedPrivilegesRequestType) returns (GetDefinedPrivilegesResponseType ) {}

  rpc GetACL (GetACLRequestType) returns (GetACLResponseType) {}

  rpc AddACLEntry (AddACLEntryRequestType) returns (AddACLEntryResponseType) {}

  rpc DeleteACLEntry (DeleteACLEntryRequestType) returns (DeleteACLEntryResponseType) {}

  rpc GetActiveSessions (GetActiveSessionsRequestType) returns (GetActiveSessionsResponseType) {}

  rpc SetMaxSessions (SetMaxSessionsRequestType) returns (SetMaxSessionsResponseType) {}

  rpc GetMaxSessions (GetMaxSessionsRequestType) returns (GetMaxSessionsResponseType) {}

  rpc SetSessionPingSettings  (SetSessionPingSettingsRequestType) returns (SetSessionPingSettingsResponseType) {}

  rpc GetSessionPingSettings  (GetSessionPingSettingsRequestType) returns (GetSessionPingSettingsResponseType) {}

  rpc GetNewSalt  (GetNewSaltRequestType) returns (GetNewSaltResponseType) {}

  // *********************************************************************
  // Streaming  methods
  // *********************************************************************
  // None

}

// This service looks after Session functionality defined in SEMI E132 that is done by a Client (management and receiving messages)
// It is in a separate service from the Security Administration functionality to support scenarios where implementations have
// this functionality separated.
service E132SessionManagement
{
  // *********************************************************************
  // Unary Request/Response methods to manage Sessions
  // *********************************************************************
  rpc GetEquipmentInformation (GetEquipmentInformationRequestType) returns (GetEquipmentInformationResponseType ) {}

  rpc ChangeACLPassword (ChangeACLPasswordRequestType) returns (ChangeACLPasswordResponseType ) {}

  rpc IsEquipmentServerAlive (IsEquipmentServerAliveRequestType) returns (IsEquipmentServerAliveResponseType ) {}

  rpc EstablishSession (EstablishSessionRequestType) returns (EstablishSessionResponseType ) {}

  rpc CloseSession (CloseSessionRequestType) returns (CloseSessionResponseType ) {}

  rpc InitiateChangeSessionEndpoint (InitiateChangeSessionEndpointRequestType) returns (InitiateChangeSessionEndpointResponseType) {}

  // *********************************************************************
  // Streaming  methods
  // *********************************************************************

  // Establish stream to and from the Server for messages related to session usage (notification, ping)
  rpc SessionUsageStream (stream SessionUsageStreamRequest) returns (stream SessionUsageStreamResponse) {}
}

// This service looks after Session Ping and notification functionality for the Consumer
// It is in a separate service because the Equipment Server opens the connection to the Consumer.
service E132SessionConsumer
{
  // *********************************************************************
  // Unary Request/Response methods
  // *********************************************************************

  // SEMI E132.2 specific method to confirm the connection to the implementing code is working.
  rpc ConfirmConnection (ConfirmConnectionRequestType) returns (ConfirmConnectionResponseType) {}

  // *********************************************************************
  // Streaming  methods
  // *********************************************************************

  // Establish stream to and from the Server for messages related to session usage (notification, ping)
  rpc ConsumerSessionUsageStream (stream ConsumerSessionUsageStreamRequest) returns (stream ConsumerSessionUsageStreamResponse) {}
}

// This service looks after Interface Discovery functionality defined by SEMI E132 to query the interfaces supported by the equipment.
service E132InterfaceDiscovery
{

  // *********************************************************************
  // Unary Request/Response methods to query interfaces
  // *********************************************************************

  rpc GetInterfaces (GetInterfacesRequestType) returns (GetInterfacesResponseType) {}

  // *********************************************************************
  // Streaming  methods
  // *********************************************************************
  // None
}