proto/gateway.proto in zeebe-client-0.2.0 vs proto/gateway.proto in zeebe-client-0.3.0

@@ -3,223 +3,468 @@
 
 option java_multiple_files = false;
 option java_package = "io.zeebe.gateway.protocol";
 option go_package = "pb";
 
-message TopologyRequest {
-}
+// For a more complete documentation, refer to Zeebe documentation at:
+// https://docs.zeebe.io/grpc/reference.html
 
-message Partition {
-  int32 partitionId = 1;
-  enum PartitionBrokerRole {
-    LEADER = 0;
-    FOLLOWER = 1;
-  }
-  PartitionBrokerRole role = 3;
+message ActivateJobsRequest {
+  // the job type, as defined in the BPMN process (e.g. <zeebe:taskDefinition
+  // type="payment-service" />)
+  string type = 1;
+  // the name of the worker activating the jobs, mostly used for logging purposes
+  string worker = 2;
+  // a job returned after this call will not be activated by another call until the
+  // timeout has been reached
+  int64 timeout = 3;
+  // the maximum number of jobs to fetch in a single call
+  int32 amount = 4;
+  // a list of variables to fetch as the job payload; if empty, all visible variables at
+  // the time of activation for the scope of the job will be returned as the job payload
+  repeated string fetchVariable = 5;
 }
 
-message BrokerInfo {
-  int32 nodeId = 1;
-  string host = 2;
-  int32 port = 3;
-  repeated Partition partitions = 4;
+message ActivateJobsResponse {
+  // list of activated jobs
+  repeated ActivatedJob jobs = 1;
 }
 
-message TopologyResponse {
-  repeated BrokerInfo brokers = 1;
-  int32 clusterSize = 2;
-  int32 partitionsCount = 3;
-  int32 replicationFactor = 4;
-}
-
-message WorkflowRequestObject {
-  string name = 1;
-  enum ResourceType {
-    // FILE type means the gateway will try to detect the resource type using the file extension of the name
-    FILE = 0;
-    BPMN = 1;
-    YAML = 2;
-  }
-  ResourceType type = 2;
-  bytes definition = 3;
-}
-
-message DeployWorkflowRequest {
-  repeated WorkflowRequestObject workflows = 1;
-}
-
-message WorkflowMetadata {
-  string bpmnProcessId = 1;
-  int32 version = 2;
-  int64 workflowKey = 3;
-  string resourceName = 4;
-}
-
-message DeployWorkflowResponse {
+message ActivatedJob {
+  // the key, a unique identifier for the job
   int64 key = 1;
-  repeated WorkflowMetadata workflows = 2;
+  // the type of the job (should match what was requested)
+  string type = 2;
+  // a set of headers tying the job to a workflow instance/task instance
+  JobHeaders jobHeaders = 3;
+  // a set of custom headers defined during modelling; returned as a serialized
+  // JSON document
+  string customHeaders = 4;
+  // the name of the worker which activated this job
+  string worker = 5;
+  // the amount of retries left to this job (should always be positive)
+  int32 retries = 6;
+  // when the job can be activated again, sent as a UNIX epoch timestamp
+  int64 deadline = 7;
+  // JSON document, computed at activation time, consisting of all visible variables to
+  // the task scope
+  string payload = 8;
 }
 
-message PublishMessageRequest {
-  string name = 1;
-  string correlationKey = 2;
-  int64 timeToLive = 3;
-  string messageId = 4;
-  /* payload has to be a valid json object as string */
-  string payload = 5;
+message JobHeaders {
+  // the job's workflow instance key
+  int64 workflowInstanceKey = 1;
+  // the bpmn process ID of the job workflow definition
+  string bpmnProcessId = 2;
+  // the version of the job workflow definition
+  int32 workflowDefinitionVersion = 3;
+  // the key of the job workflow definition
+  int64 workflowKey = 4;
+  // the associated task element ID
+  string elementId = 5;
+  // the unique key identifying the associated task, unique within the scope of the
+  // workflow instance
+  int64 elementInstanceKey = 6;
 }
 
-message PublishMessageResponse {
+message CancelWorkflowInstanceRequest {
+  // the workflow instance key (as, for example, obtained from
+  // CreateWorkflowInstanceResponse)
+  int64 workflowInstanceKey = 1;
 }
 
-message UpdateJobRetriesRequest {
-  int64 jobKey = 1;
-  int32 retries = 2;
+message CancelWorkflowInstanceResponse {
 }
 
-message UpdateJobRetriesResponse {
-}
-
-message FailJobRequest {
-  int64 jobKey = 1;
-  int32 retries = 2;
-  string errorMessage = 3;
-}
-
-message FailJobResponse {
-}
-
 message CompleteJobRequest {
+  // the unique job identifier, as obtained from ActivateJobsResponse
   int64 jobKey = 1;
-  /* payload has to be a valid json object as string */
+  // a JSON document representing the variables in the current task scope
   string payload = 2;
 }
 
 message CompleteJobResponse {
 }
 
 message CreateWorkflowInstanceRequest {
+  // the unique key identifying the workflow definition (e.g. returned from a workflow
+  // in the DeployWorkflowResponse message)
   int64 workflowKey = 1;
+  // the BPMN process ID of the workflow definition
   string bpmnProcessId = 2;
-  /* if bpmnProcessId is set version = -1 indicates to use the latest version */
+  // the version of the process; set to -1 to use the latest version
   int32 version = 3;
-  /* payload has to be a valid json object as string */
+  // JSON document that will instantiate the variables for the root variable scope of the
+  // workflow instance; it must be a JSON object, as variables will be mapped in a
+  // key-value fashion. e.g. { "a": 1, "b": 2 } will create two variables, named "a" and
+  // "b" respectively, with their associated values. [{ "a": 1, "b": 2 }] would not be a
+  // valid payload, as the root of the JSON document is an array and not an object.
   string payload = 4;
 }
 
 message CreateWorkflowInstanceResponse {
+  // the key of the workflow definition which was used to create the workflow instance
   int64 workflowKey = 1;
+  // the BPMN process ID of the workflow definition which was used to create the workflow
+  // instance
   string bpmnProcessId = 2;
+  // the version of the workflow definition which was used to create the workflow instance
   int32 version = 3;
+  // the unique identifier of the created workflow instance; to be used wherever a request
+  // needs a workflow instance key (e.g. CancelWorkflowInstanceRequest)
   int64 workflowInstanceKey = 5;
 }
 
-message CancelWorkflowInstanceRequest {
-  int64 workflowInstanceKey = 1;
+message DeployWorkflowRequest {
+  // List of workflow resources to deploy
+  repeated WorkflowRequestObject workflows = 1;
 }
 
-message CancelWorkflowInstanceResponse {
-}
+message WorkflowRequestObject {
+  enum ResourceType {
+    // FILE type means the gateway will try to detect the resource type
+    // using the file extension of the name field
+    FILE = 0;
+    BPMN = 1; // extension 'bpmn'
+    YAML = 2; // extension 'yaml'
+  }
 
-message UpdateWorkflowInstancePayloadRequest {
-  int64 elementInstanceKey = 1;
-  /* payload has to be a valid json object as string */
-  string payload = 2;
+  // the resource basename, e.g. myProcess.bpmn
+  string name = 1;
+  // the resource type; if set to BPMN or YAML then the file extension
+  // is ignored
+  ResourceType type = 2;
+  // the process definition as a UTF8-encoded string
+  bytes definition = 3;
 }
 
-message UpdateWorkflowInstancePayloadResponse {
+message DeployWorkflowResponse {
+  // the unique key identifying the deployment
+  int64 key = 1;
+  // a list of deployed workflows
+  repeated WorkflowMetadata workflows = 2;
 }
 
-message ListWorkflowsRequest {
-  /* optional filter by BPMN process id, if empty all workflows are returned */
+message WorkflowMetadata {
+  // the bpmn process ID, as parsed during deployment; together with the version forms a
+  // unique identifier for a specific workflow definition
   string bpmnProcessId = 1;
+  // the assigned process version
+  int32 version = 2;
+  // the assigned key, which acts as a unique identifier for this workflow
+  int64 workflowKey = 3;
+  // the resource name (see: WorkflowRequestObject.name) from which this workflow was
+  // parsed
+  string resourceName = 4;
 }
 
-message ListWorkflowsResponse {
-  repeated WorkflowMetadata workflows = 1;
+message FailJobRequest {
+  // the unique job identifier, as obtained when activating the job
+  int64 jobKey = 1;
+  // the amount of retries the job should have left
+  int32 retries = 2;
+  // an optional message describing why the job failed
+  // this is particularly useful if a job runs out of retries and an incident is raised,
+  // as it this message can help explain why an incident was raised
+  string errorMessage = 3;
 }
 
-/* either workflow key or bpmn process id and version has to be specified*/
+message FailJobResponse {
+}
+
 message GetWorkflowRequest {
+  // the unique key identifying the workflow definition (e.g. returned from a workflow in
+  // the DeployWorkflowResponse message)
   int64 workflowKey = 1;
-  /* if bpmnProcessId is set version = -1 indicates to use the latest version */
+  // the version of the process; set to -1 to use the latest version
   int32 version = 2;
+  // the BPMN process ID of the workflow definition
   string bpmnProcessId = 3;
 }
 
 message GetWorkflowResponse {
+  // the unique key identifying the workflow definition (e.g. returned from a workflow in
+  // the DeployWorkflowResponse message)
   int64 workflowKey = 1;
+  // the version of the process
   int32 version = 2;
+  // the BPMN process ID of the workflow definition
   string bpmnProcessId = 3;
+  // the name of the resource used to deployed the workflow
   string resourceName = 4;
+  // a BPMN XML representation of the workflow
   string bpmnXml = 5;
 }
 
-message ActivateJobsRequest {
-  string type = 1;
-  string worker = 2;
-  int64 timeout = 3;
-  int32 amount = 4;
+message ListWorkflowsRequest {
+  // optional filter: if specified, only the workflows with this given process ID will be
+  // returned
+  string bpmnProcessId = 1;
 }
 
-message JobHeaders {
-  int64 workflowInstanceKey = 1;
-  string bpmnProcessId = 2;
-  int32 workflowDefinitionVersion = 3;
-  int64 workflowKey = 4;
-  string elementId = 5;
-  int64 elementInstanceKey = 6;
+message ListWorkflowsResponse {
+  // a list of deployed workflows matching the request criteria (if any)
+  repeated WorkflowMetadata workflows = 1;
 }
 
-message ActivatedJob {
-  int64 key = 1;
-  string type = 2;
-  JobHeaders jobHeaders = 3;
-  // json object as string
-  string customHeaders = 4;
-  string worker = 5;
-  int32 retries = 6;
-  // epoch milliseconds
-  int64 deadline = 7;
-  /* json object as string */
-  string payload = 8;
+message PublishMessageRequest {
+  // the name of the message
+  string name = 1;
+  // the correlation key of the message
+  string correlationKey = 2;
+  // how long the message should be buffered on the broker, in milliseconds
+  int64 timeToLive = 3;
+  // the unique ID of the message; can be omitted. only useful to ensure only one message
+  // with the given ID will ever be published (during its lifetime)
+  string messageId = 4;
+  // the message payload as a JSON document; see CreateWorkflowInstanceRequest for the
+  // rules about payloads
+  string payload = 5;
 }
 
-message ActivateJobsResponse {
-  repeated ActivatedJob jobs = 1;
+message PublishMessageResponse {
 }
 
 message ResolveIncidentRequest {
+  // the unique ID of the incident to resolve
   int64 incidentKey = 1;
 }
 
 message ResolveIncidentResponse {
 }
 
+message TopologyRequest {
+}
+message TopologyResponse {
+  // list of brokers part of this cluster
+  repeated BrokerInfo brokers = 1;
+  // how many nodes are in the cluster
+  int32 clusterSize = 2;
+  // how many partitions are spread across the cluster
+  int32 partitionsCount = 3;
+  // configured replication factor for this cluster
+  int32 replicationFactor = 4;
+}
+
+message BrokerInfo {
+  // unique (within a cluster) node ID for the broker
+  int32 nodeId = 1;
+  // hostname of the broker
+  string host = 2;
+  // port for the broker
+  int32 port = 3;
+  // list of partitions managed or replicated on this broker
+  repeated Partition partitions = 4;
+}
+
+message Partition {
+  // Describes the Raft role of the broker for a given partition
+  enum PartitionBrokerRole {
+    LEADER = 0;
+    FOLLOWER = 1;
+  }
+
+  // the unique ID of this partition
+  int32 partitionId = 1;
+  // the role of the broker for this partition
+  PartitionBrokerRole role = 3;
+}
+
+message UpdateJobRetriesRequest {
+  // the unique job identifier, as obtained through ActivateJobs
+  int64 jobKey = 1;
+  // the new amount of retries for the job; must be positive
+  int32 retries = 2;
+}
+
+message UpdateJobRetriesResponse {
+}
+
+message UpdateWorkflowInstancePayloadRequest {
+  // the unique identifier of a particular element; can be the workflow instance key (as
+  // obtained during instance creation), or a given element, such as a service task (see
+  // elementInstanceKey on the JobHeaders message)
+  int64 elementInstanceKey = 1;
+  // the new payload as a JSON document; see CreateWorkflowInstanceRequest for the rules
+  // about payloads
+  string payload = 2;
+}
+
+message UpdateWorkflowInstancePayloadResponse {
+}
+
 service Gateway {
-  rpc Topology (TopologyRequest) returns (TopologyResponse) {
+  /*
+    Iterates through all known partitions in a round-robin and activates up to the requested amount
+    of jobs and streams them back to the client as they are activated.
+
+    Errors:
+     INVALID_ARGUMENT:
+      - type is blank (empty string, null)
+      - worker is blank (empty string, null)
+      - timeout less than 1
+      - amount is less than 1
+   */
+  rpc ActivateJobs (ActivateJobsRequest) returns (stream ActivateJobsResponse) {
   }
-  rpc DeployWorkflow (DeployWorkflowRequest) returns (DeployWorkflowResponse) {
+
+  /*
+    Cancels a running workflow instance
+
+    Errors:
+      NOT_FOUND:
+        - no workflow instance exists with the given key
+   */
+  rpc CancelWorkflowInstance (CancelWorkflowInstanceRequest) returns (CancelWorkflowInstanceResponse) {
   }
-  rpc PublishMessage (PublishMessageRequest) returns (PublishMessageResponse) {
-  }
-  rpc UpdateJobRetries (UpdateJobRetriesRequest) returns (UpdateJobRetriesResponse) {
-  }
-  rpc FailJob (FailJobRequest) returns (FailJobResponse) {
-  }
+
+  /*
+    Completes a job with the given payload, which allows completing the associated service task.
+
+    Errors:
+      NOT_FOUND:
+        - no job exists with the given job key. Note that since jobs are removed once completed,
+          it could be that this job did exist at some point.
+
+      FAILED_PRECONDITION:
+        - the job was marked as failed. In that case, the related incident must be resolved before
+          the job can be activated again and completed.
+   */
   rpc CompleteJob (CompleteJobRequest) returns (CompleteJobResponse) {
   }
+
+  /*
+    Creates and starts an instance of the specified workflow. The workflow definition to use to
+    create the instance can be specified either using its unique key (as returned by
+    DeployWorkflow), or using the BPMN process ID and a version. Pass -1 as the version to use the
+    latest deployed version. Note that only workflows with none start events can be started through
+    this command.
+
+    Errors:
+      NOT_FOUND:
+        - no workflow with the given key exists (if workflowKey was given)
+        - no workflow with the given process ID exists (if bpmnProcessId was given but version was -1)
+        - no workflow with the given process ID and version exists (if both bpmnProcessId and version were given)
+
+      FAILED_PRECONDITION:
+        - the workflow definition does not contain a none start event; only workflows with none
+          start event can be started manually.
+
+      INVALID_ARGUMENT:
+        - the given payload is not a valid JSON document; all payloads are expected to be
+          valid JSON documents where the root node is an object.
+   */
   rpc CreateWorkflowInstance (CreateWorkflowInstanceRequest) returns (CreateWorkflowInstanceResponse) {
   }
-  rpc CancelWorkflowInstance (CancelWorkflowInstanceRequest) returns (CancelWorkflowInstanceResponse) {
+
+  /*
+    Deploys one or more workflows to Zeebe. Note that this is an atomic call,
+    i.e. either all workflows are deployed, or none of them are.
+
+    Errors:
+      INVALID_ARGUMENT:
+        - no resources given.
+        - if at least one resource is invalid. A resource is considered invalid if:
+          - it is not a BPMN or YAML file (currently detected through the file extension)
+          - the resource data is not deserializable (e.g. detected as BPMN, but it's broken XML)
+          - the workflow is invalid (e.g. an event-based gateway has an outgoing sequence flow to a task)
+   */
+  rpc DeployWorkflow (DeployWorkflowRequest) returns (DeployWorkflowResponse) {
   }
-  rpc UpdateWorkflowInstancePayload (UpdateWorkflowInstancePayloadRequest) returns (UpdateWorkflowInstancePayloadResponse) {
+
+  /*
+    Marks the job as failed; if the retries argument is positive, then the job will be immediately
+    activatable again, and a worker could try again to process it. If it is zero or negative however,
+    an incident will be raised, tagged with the given errorMessage, and the job will not be
+    activatable until the incident is resolved.
+
+    Errors:
+      NOT_FOUND:
+        - no job was found with the given key
+
+      FAILED_PRECONDITION:
+        - the job was not activated
+        - the job is already in a failed state, i.e. ran out of retries
+   */
+  rpc FailJob (FailJobRequest) returns (FailJobResponse) {
   }
-  rpc ActivateJobs (ActivateJobsRequest) returns (stream ActivateJobsResponse) {
+
+  /*
+    Fetches the workflow definition either by workflow key, or BPMN process ID and version.
+    At least one of workflowKey or bpmnProcessId must be specified.
+
+    Errors:
+      NOT_FOUND:
+        - no workflow with the given key exists (if workflowKey was given)
+        - no workflow with the given process ID exists (if bpmnProcessId was given but version was -1)
+        - no workflow with the given process ID and version exists (if both bpmnProcessId and version were given)
+   */
+  rpc GetWorkflow (GetWorkflowRequest) returns (GetWorkflowResponse) {
   }
+
+  /*
+    Lists all workflows matching the request criteria currently deployed in the cluster.
+
+    Errors:
+      NOT_FOUND:
+        - no workflows have been deployed yet (if no bpmnProcessId was given)
+        - no workflow with the given process ID exists (if bpmnProcessId was given)
+   */
   rpc ListWorkflows (ListWorkflowsRequest) returns (ListWorkflowsResponse) {
   }
-  rpc GetWorkflow (GetWorkflowRequest) returns (GetWorkflowResponse) {
+
+  /*
+    Publishes a single message. Messages are published to specific partitions computed from their
+    correlation keys.
+
+    Errors:
+      ALREADY_EXISTS:
+        - a message with the same ID was previously published (and is still alive)
+   */
+  rpc PublishMessage (PublishMessageRequest) returns (PublishMessageResponse) {
   }
+
+  /*
+    Resolves a given incident. This simply marks the incident as resolved; most likely a call to
+    UpdateJobRetries or UpdateWorkflowInstancePayload will be necessary to actually resolve the
+    problem, following by this call.
+
+    Errors:
+      NOT_FOUND:
+        - no incident with the given key exists
+   */
   rpc ResolveIncident (ResolveIncidentRequest) returns (ResolveIncidentResponse) {
+  }
+
+  /*
+    Obtains the current topology of the cluster the gateway is part of.
+   */
+  rpc Topology (TopologyRequest) returns (TopologyResponse) {
+  }
+
+  /*
+    Updates the number of retries a job has left. This is mostly useful for jobs that have run out of
+    retries, should the underlying problem be solved.
+
+    Errors:
+      NOT_FOUND:
+        - no job exists with the given key
+
+      INVALID_ARGUMENT:
+        - retries is not greater than 0
+   */
+  rpc UpdateJobRetries (UpdateJobRetriesRequest) returns (UpdateJobRetriesResponse) {
+  }
+
+  /*
+    Updates all the variables in the workflow instance scope from the given JSON document.
+
+    Errors:
+      NOT_FOUND:
+        - no element with the given elementInstanceKey exists
+      INVALID_ARGUMENT:
+        - the given payload is not a valid JSON document; all payloads are expected to be
+          valid JSON documents where the root node is an object.
+   */
+  rpc UpdateWorkflowInstancePayload (UpdateWorkflowInstancePayloadRequest) returns (UpdateWorkflowInstancePayloadResponse) {
   }
 }