gateway_services_pb.rb in zeebe-client-0.3.0

- old
+ new
@@ -12,22 +12,145 @@
 
       self.marshal_class_method = :encode
       self.unmarshal_class_method = :decode
       self.service_name = 'gateway_protocol.Gateway'
 
-      rpc :Topology, TopologyRequest, TopologyResponse
-      rpc :DeployWorkflow, DeployWorkflowRequest, DeployWorkflowResponse
-      rpc :PublishMessage, PublishMessageRequest, PublishMessageResponse
-      rpc :UpdateJobRetries, UpdateJobRetriesRequest, UpdateJobRetriesResponse
-      rpc :FailJob, FailJobRequest, FailJobResponse
+      #
+      # 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, stream(ActivateJobsResponse)
+      #
+      # Cancels a running workflow instance
+      #
+      # Errors:
+      # NOT_FOUND:
+      # - no workflow instance exists with the given key
+      rpc :CancelWorkflowInstance, CancelWorkflowInstanceRequest, CancelWorkflowInstanceResponse
+      #
+      # 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, 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, CreateWorkflowInstanceResponse
-      rpc :CancelWorkflowInstance, CancelWorkflowInstanceRequest, CancelWorkflowInstanceResponse
-      rpc :UpdateWorkflowInstancePayload, UpdateWorkflowInstancePayloadRequest, UpdateWorkflowInstancePayloadResponse
-      rpc :ActivateJobs, ActivateJobsRequest, stream(ActivateJobsResponse)
-      rpc :ListWorkflows, ListWorkflowsRequest, ListWorkflowsResponse
+      #
+      # 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, DeployWorkflowResponse
+      #
+      # 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, FailJobResponse
+      #
+      # 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, 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, ListWorkflowsResponse
+      #
+      # 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, 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, ResolveIncidentResponse
+      #
+      # Obtains the current topology of the cluster the gateway is part of.
+      rpc :Topology, TopologyRequest, 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, 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, UpdateWorkflowInstancePayloadResponse
     end
 
     Stub = Service.rpc_stub_class
   end
 end