-
Notifications
You must be signed in to change notification settings - Fork 6
/
gateway.proto
478 lines (420 loc) · 17.9 KB
/
gateway.proto
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
//Zeebe Community License v1.0
//
//This Zeebe Community License v1.0 ("this Agreement") sets forth the terms and
//conditions on which Camunda Services GmbH ("the Licensor") makes available this
//software ("the Software"). BY INSTALLING, DOWNLOADING, ACCESSING, USING OR
//DISTRIBUTING THE SOFTWARE YOU INDICATE YOUR ACCEPTANCE TO, AND ARE ENTERING
//INTO A CONTRACT WITH, THE LICENSOR ON THE TERMS SET OUT IN THIS AGREEMENT. IF
//YOU DO NOT AGREE TO THESE TERMS, YOU MUST NOT USE THE SOFTWARE. IF YOU ARE
//RECEIVING THE SOFTWARE ON BEHALF OF A LEGAL ENTITY, YOU REPRESENT AND WARRANT
//THAT YOU HAVE THE ACTUAL AUTHORITY TO AGREE TO THE TERMS AND CONDITIONS OF THIS
//AGREEMENT ON BEHALF OF SUCH ENTITY. "Licensee" means you, an individual, or the
//entity on whose behalf you are receiving the Software.
//
//Permission is hereby granted, free of charge, to the Licensee obtaining a copy
//of this Software and associated documentation files, to deal in the Software
//without restriction, including without limitation the rights to use, copy,
//modify, merge, publish, distribute, sublicense, and/or sell copies of the
//Software, and to permit persons to whom the Software is furnished to do so,
//subject in each case to the following conditions:
//
//Condition 1: If the Licensee distributes the Software or any derivative works
//of the Software, the Licensee must attach this Agreement.
//
//Condition 2: Without limiting other conditions in this Agreement, the grant of
//rights under this Agreement does not include the right to provide a Commercial
//Workflow Service.
//
//A "Commercial Workflow Service" is a service intended for or directed towards
//commercial advantage or monetary compensation for the provider of the service
//enabling third parties (other than the provider’s employees or Contractors) to
//deploy and execute Custom Workflows or to access the Software via its APIs.
//
//"Contractors" means third parties who are engaged to perform ICT development,
//maintenance, configuration, training, consulting or associated management
//services and are acting in that capacity.
//
//"Custom Workflows" means workflow descriptions contained in BPMN or similar
//configuration files, that specify the logic for executing programmatic
//services, such that third parties can define these programmatic services freely
//(as opposed to selecting them from a restricted set of pre-defined programmatic
//services made available by the provider of the Commercial Workflow Service).
//
//If the Licensee is in breach of the Conditions, this Agreement, including the
//rights granted under it, will automatically terminate with immediate effect.
//
//SUBJECT AS SET OUT BELOW, THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
//ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
//MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
//EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
//OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
//ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
//DEALINGS IN THE SOFTWARE.
//
//NOTHING IN THIS AGREEMENT EXCLUDES OR RESTRICTS A PARTY’S LIABILITY FOR (A)
//DEATH OR PERSONAL INJURY CAUSED BY THAT PARTY’S NEGLIGENCE, (B) FRAUD, OR (C)
//ANY OTHER LIABILITY TO THE EXTENT THAT IT CANNOT BE LAWFULLY EXCLUDED OR
//RESTRICTED.
syntax = 'proto3';
package gateway_protocol;
option java_multiple_files = false;
option java_package = "io.zeebe.gateway.protocol";
option go_package = "pb";
// For a more complete documentation, refer to Zeebe documentation at:
// https://docs.zeebe.io/grpc/reference.html
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 jobs to activate by this request
int32 maxJobsToActivate = 4;
// a list of variables to fetch as the job variables; if empty, all visible variables at
// the time of activation for the scope of the job will be returned
repeated string fetchVariable = 5;
// The request will be completed when at least one job is activated or after the requestTimeout.
// if the requestTimeout = 0, a default timeout is used.
// if the requestTimeout < 0, long polling is disabled and the request is completed immediately, even when no job is activated.
int64 requestTimeout = 6;
}
message ActivateJobsResponse {
// list of activated jobs
repeated ActivatedJob jobs = 1;
}
message ActivatedJob {
// the key, a unique identifier for the job
int64 key = 1;
// the type of the job (should match what was requested)
string type = 2;
// the job's workflow instance key
int64 workflowInstanceKey = 3;
// the bpmn process ID of the job workflow definition
string bpmnProcessId = 4;
// the version of the job workflow definition
int32 workflowDefinitionVersion = 5;
// the key of the job workflow definition
int64 workflowKey = 6;
// the associated task element ID
string elementId = 7;
// the unique key identifying the associated task, unique within the scope of the
// workflow instance
int64 elementInstanceKey = 8;
// a set of custom headers defined during modelling; returned as a serialized
// JSON document
string customHeaders = 9;
// the name of the worker which activated this job
string worker = 10;
// the amount of retries left to this job (should always be positive)
int32 retries = 11;
// when the job can be activated again, sent as a UNIX epoch timestamp
int64 deadline = 12;
// JSON document, computed at activation time, consisting of all visible variables to
// the task scope
string variables = 13;
}
message CancelWorkflowInstanceRequest {
// the workflow instance key (as, for example, obtained from
// CreateWorkflowInstanceResponse)
int64 workflowInstanceKey = 1;
}
message CancelWorkflowInstanceResponse {
}
message CompleteJobRequest {
// the unique job identifier, as obtained from ActivateJobsResponse
int64 jobKey = 1;
// a JSON document representing the variables in the current task scope
string variables = 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;
// the version of the process; set to -1 to use the latest version
int32 version = 3;
// 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 argument, as the root of the JSON document is an array and not an object.
string variables = 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 = 4;
}
message DeployWorkflowRequest {
// List of workflow resources to deploy
repeated WorkflowRequestObject workflows = 1;
}
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'
}
// 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 DeployWorkflowResponse {
// the unique key identifying the deployment
int64 key = 1;
// a list of deployed workflows
repeated WorkflowMetadata workflows = 2;
}
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 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;
}
message FailJobResponse {
}
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 variables as a JSON document; to be valid, the root of the document must be an
// object, e.g. { "a": "foo" }. [ "foo" ] would not be valid.
string variables = 5;
}
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 = 2;
}
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 SetVariablesRequest {
// 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 job message)
int64 elementInstanceKey = 1;
// a JSON serialized document describing variables as key value pairs; the root of the document
// must be an object
string variables = 2;
// if true, the variables will be merged strictly into the local scope (as indicated by
// elementInstanceKey); this means the variables is not propagated to upper scopes.
// for example, let's say we have two scopes, '1' and '2', with each having effective variables as:
// 1 => `{ "foo" : 2 }`, and 2 => `{ "bar" : 1 }`. if we send an update request with
// elementInstanceKey = 2, variables `{ "foo" : 5 }`, and local is true, then scope 1 will
// be unchanged, and scope 2 will now be `{ "bar" : 1, "foo" 5 }`. if local was false, however,
// then scope 1 would be `{ "foo": 5 }`, and scope 2 would be `{ "bar" : 1 }`.
bool local = 3;
}
message SetVariablesResponse {
}
service Gateway {
/*
Iterates through all known partitions round-robin and activates up to the requested
maximum 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
- maxJobsToActivate is less than 1
*/
rpc ActivateJobs (ActivateJobsRequest) returns (stream ActivateJobsResponse) {
}
/*
Cancels a running workflow instance
Errors:
NOT_FOUND:
- no workflow instance exists with the given key
*/
rpc CancelWorkflowInstance (CancelWorkflowInstanceRequest) returns (CancelWorkflowInstanceResponse) {
}
/*
Completes a job with the given variables, 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 variables argument is not a valid JSON document; it is expected to be a valid
JSON document where the root node is an object.
*/
rpc CreateWorkflowInstance (CreateWorkflowInstanceRequest) returns (CreateWorkflowInstanceResponse) {
}
/*
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) {
}
/*
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) {
}
/*
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 SetVariables 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) {
}
/*
Updates all the variables of a particular scope (e.g. workflow instance, flow element instance)
from the given JSON document.
Errors:
NOT_FOUND:
- no element with the given elementInstanceKey exists
INVALID_ARGUMENT:
- the given variables document is not a valid JSON document; valid documents are expected to
be JSON documents where the root node is an object.
*/
rpc SetVariables (SetVariablesRequest) returns (SetVariablesResponse) {
}
/*
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) {
}
}