Skip to content

Commit a36aa94

Browse files
tsurdilotsurdilo
authored
Adding rate limiting extension (#442)
* Adding rate limiting extension Signed-off-by: Tihomir Surdilovic <[email protected]> * update readme Signed-off-by: Tihomir Surdilovic <[email protected]>
1 parent 20e8fe9 commit a36aa94

File tree

7 files changed

+202
-2
lines changed

7 files changed

+202
-2
lines changed

‎extensions/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,5 @@ Click on the `Extension Id` link to see detailed explanation of the extension.
1313
| Extension Id | Description | Json Schema |
1414
| --- | --- | --- |
1515
| [kpi](kpi.md) | Define workflow key performance indicators (KPIs) | [kpi.json](../schema/extensions/kpi.json) |
16+
| [ratelimiting](ratelimiting.md) | Define numerous rate limiting options for a workflow per single or all instances | [ratelimiting.json](../schema/extensions/ratelimiting.json) |
1617

‎extensions/kpi.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ KPIs can be added for the model:
3434
| --- | --- | --- | --- |
3535
| extensionid | Unique extension Id (default is 'workflow-kpi-extension') | string | yes |
3636
| workflowid | Workflow definition unique identifier (workflow id property) | string | yes |
37+
| workflowVersions | Workflow versions. If not defined, applies to all workflow instances (regardless of their associated workflow version) | array | no |
3738
| [workflow](#Workflow-KPIs-Definition) | Workflow definition KPIs | object | no |
3839
| [events](#Event-KPIs-Definition) | Workflow event definitions KPIs | array | no |
3940
| [functions](#Function-KPIs-Definition) | Workflow function definitions KPIs | array | no |

‎extensions/ratelimiting.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Extensions - Rate Limiting
2+
3+
## Table of Contents
4+
5+
- [Introduction](#Introduction)
6+
- [Extension Definition](#Extension-Definition)
7+
- [Workflow KPIs Definition](#Workflow-KPIs-Definition)
8+
- [Example](#Example)
9+
10+
## Introduction
11+
12+
Out workflows can execute numerous downstream services. Rate limiting can be used to protect these
13+
downstream services from flooding. In addition, rate limiting can help us keep our cost
14+
at a desired rate in cases where downstream service invocations have an associated cost factor.
15+
16+
## Extension Definition
17+
18+
| Parameter | Description | Type | Required |
19+
| --- | --- | --- | --- |
20+
| extensionid | Unique extension Id (default is 'workflow-kpi-extension') | string | yes |
21+
| workflowid | Workflow definition unique identifier (workflow id property) | string | yes |
22+
| workflowVersions | Workflow versions. If not defined, applies to all workflow instances (regardless of their associated workflow version) | array | no |
23+
| [singleInstance](#Single-Instance-Definition) | Rate limits per single workflow instance | object | no |
24+
| [allInstances](#All-Instances-Definition) | Rate limits per all workflow instances | object | no |
25+
26+
### Single Instance Definition
27+
28+
| Parameter | Description | Type | Required |
29+
| --- | --- | --- | --- |
30+
| maxActionsPerSecond | Sets the rate limiting on number of actions that can be executed per second. Notice that the number is represented as number type, so that you can set it to less than 1 if needed. For example, set the number to 0.1 means you want workflow actions should be executed once every 10 seconds. Default zero value means 'unlimited'| number | no |
31+
| maxConcurrentActions | Maximum number of actions that can be executed in parallel | string | no |
32+
| maxProducedEventsPerSecond |Sets the rate limiting on number of events that can be produced per second. Notice that the number is represented as number type, so that you can set it to less than 1 if needed. For example, set the number to 0.1 means workflow can produce events once every 10 seconds. Default zero value means 'unlimited' | string | no |
33+
| maxStates | Maximum number of workflow states that should be executed. Default is zero, meaning unlimited. | string | no |
34+
| maxTransitions | Maximum number of workflow transitions that should be executed. Default is zero, meaning unlimited. | string | no |
35+
36+
### All Instances Definition
37+
38+
| Parameter | Description | Type | Required |
39+
| --- | --- | --- | --- |
40+
| maxActionsPerSecond | Sets the rate limiting on number of actions that can be executed per second. Notice that the number is represented as number type, so that you can set it to less than 1 if needed. For example, set the number to 0.1 means you want workflow actions should be executed once every 10 seconds. Default zero value means 'unlimited'| number | no |
41+
| maxConcurrentActions | Maximum number of actions that can be executed in parallel | string | no |
42+
| maxProducedEventsPerSecond |Sets the rate limiting on number of events that can be produced per second. Notice that the number is represented as number type, so that you can set it to less than 1 if needed. For example, set the number to 0.1 means workflow can produce events once every 10 seconds. Default zero value means 'unlimited' | string | no |
43+
| maxStates | Maximum number of workflow states that should be executed. Default is zero, meaning unlimited. | string | no |
44+
| maxTransitions | Maximum number of workflow transitions that should be executed. Default is zero, meaning unlimited. | string | no |
45+
46+
## Example
47+
48+
The following example shows a workflow definition on the left and
49+
an associated sample Rate Limiting extension definition on the right.
50+
51+
<table>
52+
<tr>
53+
<th>Workflow</th>
54+
<th>Rate Limiting Extension</th>
55+
</tr>
56+
<tr>
57+
<td valign="top">
58+
59+
```yaml
60+
id: processapplication
61+
name: Process Application
62+
version: '1.0'
63+
specVersion: '0.7'
64+
start: ProcessNewApplication
65+
states:
66+
- name: ProcessNewApplication
67+
type: event
68+
onEvents:
69+
- eventRefs:
70+
- ApplicationReceivedEvent
71+
actions:
72+
- functionRef: processApplicationFunction
73+
- functionRef: acceptApplicantFunction
74+
- functionRef: depositFeesFunction
75+
end:
76+
produceEvents:
77+
- eventRef: NotifyApplicantEvent
78+
functions:
79+
- name: processApplicationFunction
80+
operation: file://myservice.json#process
81+
- name: acceptApplicantFunction
82+
operation: file://myservice.json#accept
83+
- name: depositFeesFunction
84+
operation: file://myservice.json#deposit
85+
events:
86+
- name: ApplicationReceivedEvent
87+
type: application
88+
source: "/applications/new"
89+
- name: NotifyApplicantEvent
90+
type: notifications
91+
source: "/applicants/notify"
92+
```
93+
94+
</td>
95+
<td valign="top">
96+
97+
```yaml
98+
extensionid: workflow-ratelimiting-extension
99+
workflowid: processapplication
100+
singleInstance:
101+
maxActionsPerSecond: 0.1
102+
maxConcurrentActions: 200
103+
maxProducedEventsPerSecond: 2
104+
maxStates: '1000'
105+
maxTransitions: '1000'
106+
allInstances:
107+
maxActionsPerSecond: 1
108+
maxConcurrentActions: 500
109+
maxProducedEventsPerSecond: 20
110+
maxStates: '10000'
111+
maxTransitions: '10000'
112+
113+
```
114+
115+
</td>
116+
</tr>
117+
</table>

‎roadmap/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ _Status description:_
4242
| ✔️| Added function definition support for AsyncAPI | [spec doc](../specification.md) |
4343
| ✔️| Rename Delay state to Sleep state | [spec doc](../specification.md) |
4444
| ✔️| Added 'sleep' property to action definition | [spec doc](../specification.md) |
45+
| ✔️| Added Rate Limiting extension | [spec doc](../specification.md) |
4546
| ✏️ | AsyncAPI operation support | |
4647
| ✏️ | OData function definition support | |
4748
| ✏️ | Update to retries - state specific rather than error specific | |

‎schema/extensions/kpi.json

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,13 @@
1818
"minLength": 1,
1919
"description": "Workflow definition unique identifier (workflow id property)"
2020
},
21+
"workflowVersions": {
22+
"type": "array",
23+
"description": "Workflow versions. If not defined, applies to all workflow instances (regardless of their associated workflow version)",
24+
"items": {
25+
"type": "string"
26+
}
27+
},
2128
"currency": {
2229
"type": "string",
2330
"default": "USD",

‎schema/extensions/ratelimiting.json

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
{
2+
"$id": "https://serverlessworkflow.io/schemas/0.7/extensions/ratelimiting.json",
3+
"$schema": "http://json-schema.org/draft-07/schema#",
4+
"description": "Serverless Workflow specification - Various workflow rate limiting settings",
5+
"type": "object",
6+
"definitions": {
7+
"ratelimiting": {
8+
"type": "object",
9+
"description": "Serverless Workflow Rate Limiting Extension",
10+
"properties": {
11+
"extensionid": {
12+
"type": "string",
13+
"default": "workflow-ratelimiting-extension",
14+
"description": "Extension unique identifier"
15+
},
16+
"workflowid": {
17+
"type": "string",
18+
"minLength": 1,
19+
"description": "Workflow definition unique identifier (workflow id property)"
20+
},
21+
"workflowVersions": {
22+
"type": "array",
23+
"description": "Workflow versions. If not defined, applies to all workflow instances (regardless of their associated workflow version)",
24+
"items": {
25+
"type": "string"
26+
}
27+
},
28+
"singleInstance": {
29+
"description": "Rate Limit settings per single instance of a workflow with provided workflowid",
30+
"$ref": "#/definitions/ratelimits"
31+
},
32+
"allInstances": {
33+
"description": "Rate Limit settings across all instance of a workflow with provided workflowid",
34+
"$ref": "#/definitions/ratelimits"
35+
}
36+
},
37+
"required": [
38+
"extensionid",
39+
"workflowid"
40+
]
41+
},
42+
"ratelimits": {
43+
"type": "object",
44+
"properties": {
45+
"maxActionsPerSecond": {
46+
"type": "number",
47+
"default": 0,
48+
"description": "Sets the rate limiting on number of actions that can be executed per second. Notice that the number is represented as number type, so that you can set it to less than 1 if needed. For example, set the number to 0.1 means workflow actions can be executed once every 10 seconds. Default zero value means 'unlimited'"
49+
},
50+
"maxConcurrentActions": {
51+
"type": "number",
52+
"default": 100,
53+
"description": "Maximum number of actions that can be executed in parallel"
54+
},
55+
"maxProducedEventsPerSecond": {
56+
"type": "number",
57+
"default": 0,
58+
"description": "Sets the rate limiting on number of events that can be produced per second. Notice that the number is represented as number type, so that you can set it to less than 1 if needed. For example, set the number to 0.1 means workflow can produce events once every 10 seconds. Default zero value means 'unlimited'"
59+
},
60+
"maxStates": {
61+
"type": "integer",
62+
"default": 0,
63+
"description": "Maximum number of workflow states that should be executed. Default is zero, meaning unlimited."
64+
},
65+
"maxTransitions": {
66+
"type": "integer",
67+
"default": 0,
68+
"description": "Maximum number of workflow transitions that should be executed. Default is zero, meaning unlimited."
69+
}
70+
}
71+
}
72+
}
73+
}

‎specification.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -165,7 +165,7 @@ The specification has multiple components:
165165
* Set of [Workflow Extensions](extensions/README.md) which
166166
allow users to define additional, non-execution-related workflow information. This information can be used to improve
167167
workflow performance.
168-
Some example workflow extensions include Key Performance Indicators (KPIs), Simulation, Tracing, etc.
168+
Some example workflow extensions include Key Performance Indicators (KPIs), Rate Limiting, Simulation, Tracing, etc.
169169
* Technology Compatibility Kit (TCK) to be used as a specification conformance tool for runtime implementations.
170170

171171
## Specification Details
@@ -5743,7 +5743,7 @@ Some other examples of information that could be recorded in metadata are:
57435743
## Extensions
57445744

57455745
The workflow extension mechanism allows you to enhance your model definitions with additional information useful for
5746-
things like analytics, logging, simulation, debugging, tracing, etc.
5746+
things like analytics, rate limiting, logging, simulation, debugging, tracing, etc.
57475747

57485748
Model extensions do no influence control flow logic (workflow execution semantics).
57495749
They enhance it with extra information that can be consumed by runtime systems or tooling and

0 commit comments

Comments
 (0)