Skip to content

Commit fd241d8

Browse files
cdavernascdavernas
authored
Merge branch 'main' into feat-container-lifetime
2 parents 3983190 + dab7039 commit fd241d8

11 files changed

+485
-57
lines changed

‎dsl-reference.md

Lines changed: 223 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,10 @@
5656
+ [HTTP Request](#http-request)
5757
+ [URI Template](#uri-template)
5858
+ [Container Lifetime](#container-lifetime)
59+
+ [Process Result](#process-result)
60+
+ [AsyncAPI Server](#asyncapi-server)
61+
+ [AsyncAPI Message](#asyncapi-message)
62+
+ [AsyncAPI Subscription](#asyncapi-subscription)
5963

6064
## Abstract
6165

@@ -300,15 +304,16 @@ The [AsyncAPI Call](#asyncapi-call) enables workflows to interact with external
300304

301305
###### Properties
302306

303-
| Name | Type | Required | Description|
304-
|:--|:---:|:---:|:---|
305-
| document | [`externalResource`](#external-resource) | `yes` | The AsyncAPI document that defines the operation to call. |
306-
| operationRef | `string` | `yes` | A reference to the AsyncAPI operation to call. |
307-
| server | `string` | `no` | A reference to the server to call the specified AsyncAPI operation on.<br>If not set, default to the first server matching the operation's channel. |
308-
| message | `string` | `no` | The name of the message to use. <br>If not set, defaults to the first message defined by the operation. |
309-
| binding | `string` | `no` | The name of the binding to use. <br>If not set, defaults to the first binding defined by the operation |
310-
| payload | `any` | `no` | The operation's payload, as defined by the configured message |
311-
| authentication | `string`<br>[`authentication`](#authentication) | `no` | The authentication policy, or the name of the authentication policy, to use when calling the AsyncAPI operation. |
307+
| Name | Type | Required | Description |
308+
|:-------|:------:|:----------:|:--------------|
309+
| document | [`externalResource`](#external-resource) | `yes` | The AsyncAPI document that defines the [operation](https://www.asyncapi.com/docs/reference/specification/v3.0.0#operationObject) to call. |
310+
| channel | `string` | `yes` | The name of the channel on which to perform the operation. The operation to perform is defined by declaring either `message`, in which case the [channel](https://v2.asyncapi.com/docs/reference/specification/v2.6.0#channelItemObject)'s `publish` operation will be executed, or `subscription`, in which case the [channel](https://v2.asyncapi.com/docs/reference/specification/v2.6.0#channelItemObject)'s `subscribe` operation will be executed.<br>*Used only in case the referenced document uses AsyncAPI `v2.6.0`.* |
311+
| operation | `string` | `yes` | A reference to the AsyncAPI [operation](https://www.asyncapi.com/docs/reference/specification/v3.0.0#operationObject) to call.<br>*Used only in case the referenced document uses AsyncAPI `v3.0.0`.* |
312+
| server | [`asyncApiServer`](#asyncapi-server) | `no` | An object used to configure to the [server](https://www.asyncapi.com/docs/reference/specification/v3.0.0#serverObject) to call the specified AsyncAPI [operation](https://www.asyncapi.com/docs/reference/specification/v3.0.0#operationObject) on.<br>If not set, default to the first [server](https://www.asyncapi.com/docs/reference/specification/v3.0.0#serverObject) matching the operation's channel. |
313+
| protocol | `string` | `no` | The [protocol](https://www.asyncapi.com/docs/reference/specification/v3.0.0#definitionsProtocol) to use to select the target [server](https://www.asyncapi.com/docs/reference/specification/v3.0.0#serverObject). <br>Ignored if `server` has been set.<br>*Supported values are: `amqp`, `amqp1`, `anypointmq`, `googlepubsub`, `http`, `ibmmq`, `jms`, `kafka`, `mercure`, `mqtt`, `mqtt5`, `nats`, `pulsar`, `redis`, `sns`, `solace`, `sqs`, `stomp` and `ws`* |
314+
| message | [`asyncApiMessage`](#asyncapi-message) | `no` | An object used to configure the message to publish using the target operation.<br>*Required if `subscription` has not been set.* |
315+
| subscription | [`asyncApiSubscription`](#asyncapi-subscription) | `no` | An object used to configure the subscription to messages consumed using the target operation.<br>*Required if `message` has not been set.* |
316+
| authentication | `string`<br>[`authentication`](#authentication) | `no` | The authentication policy, or the name of the authentication policy, to use when calling the AsyncAPI operation. |
312317

313318
###### Examples
314319

@@ -319,17 +324,35 @@ document:
319324
name: asyncapi-example
320325
version: '0.1.0'
321326
do:
322-
- findPet:
327+
- publishGreetings:
328+
call: asyncapi
329+
with:
330+
document:
331+
endpoint: https://fake.com/docs/asyncapi.json
332+
operation: greet
333+
server:
334+
name: greetingsServer
335+
variables:
336+
environment: dev
337+
message:
338+
payload:
339+
greetings: Hello, World!
340+
headers:
341+
foo: bar
342+
bar: baz
343+
- subscribeToChatInbox:
323344
call: asyncapi
324345
with:
325346
document:
326347
endpoint: https://fake.com/docs/asyncapi.json
327-
operationRef: findPetsByStatus
328-
server: staging
329-
message: getPetByStatusQuery
330-
binding: http
331-
payload:
332-
petId: ${ .pet.id }
348+
operation: chat-inbox
349+
protocol: http
350+
subscription:
351+
filter: ${ . == $workflow.input.chat.roomId }
352+
consume:
353+
amount: 5
354+
for:
355+
seconds: 10
333356
```
334357

335358
##### gRPC Call
@@ -412,7 +435,7 @@ The [OpenAPI Call](#openapi-call) enables workflows to interact with external se
412435
|:--|:---:|:---:|:---|
413436
| document | [`externalResource`](#external-resource) | `yes` | The OpenAPI document that defines the operation to call. |
414437
| operationId | `string` | `yes` | The id of the OpenAPI operation to call. |
415-
| arguments | `map` | `no` | A name/value mapping of the parameters, if any, of the OpenAPI operation to call. |
438+
| parameters | `map` | `no` | A name/value mapping of the parameters, if any, of the OpenAPI operation to call. |
416439
| authentication | [`authentication`](#authentication) | `no` | The authentication policy, or the name of the authentication policy, to use when calling the OpenAPI operation. |
417440
| output | `string` | `no` | The OpenAPI call's output format.<br>*Supported values are:*<br>*- `raw`, which output's the base-64 encoded [http response](#http-response) content, if any.*<br>*- `content`, which outputs the content of [http response](#http-response), possibly deserialized.*<br>*- `response`, which outputs the [http response](#http-response).*<br>*Defaults to `content`.* |
418441

@@ -717,13 +740,14 @@ Provides the capability to execute external [containers](#container-process), [s
717740

718741
##### Properties
719742

720-
| Name | Type | Required | Description|
743+
| Name | Type | Required | Description |
721744
|:--|:---:|:---:|:---|
722745
| run.container | [`container`](#container-process) | `no` | The definition of the container to run.<br>*Required if `script`, `shell` and `workflow` have not been set.* |
723746
| run.script | [`script`](#script-process) | `no` | The definition of the script to run.<br>*Required if `container`, `shell` and `workflow` have not been set.* |
724747
| run.shell | [`shell`](#shell-process) | `no` | The definition of the shell command to run.<br>*Required if `container`, `script` and `workflow` have not been set.* |
725748
| run.workflow | [`workflow`](#workflow-process) | `no` | The definition of the workflow to run.<br>*Required if `container`, `script` and `shell` have not been set.* |
726-
| await | `boolean` | `no` | Determines whether or not the process to run should be awaited for.<br>*Defaults to `true`.* |
749+
| await | `boolean` | `no` | Determines whether or not the process to run should be awaited for.<br>*When set to `false`, the task cannot wait for the process to complete and thus cannot output the process’s result. In this case, it should simply output its transformed input.*<br>*Defaults to `true`.* |
750+
| return | `string` | `no` | Configures the output of the process.<br>*Supported values are:*<br>*- `stdout`: Outputs the content of the process **STDOUT**.*<br>*- `stderr`: Outputs the content of the process **STDERR**.*<br>*- `code`: Outputs the process's **exit code**.*<br>*- `all`: Outputs the **exit code**, the **STDOUT** content and the **STDERR** content, wrapped into a new [processResult](#process-result) object.*<br>*- `none`: Does not output anything.*<br>*Defaults to `stdout`.* |
727751

728752
##### Examples
729753

@@ -1901,6 +1925,17 @@ Configures the lifetime of a container.
19011925
|----------|:----:|:--------:|-------------|
19021926
| cleanup | `string` | `yes` | The cleanup policy to use.<br>*Supported values are:<br>- `always`: the container is deleted immediately after execution.<br>-`never`: the runtime should never delete the container.<br>-`eventually`: the container is deleted after a configured amount of time after its execution.*<br>*Defaults to `never`.* |
19031927
| after | [`duration`](#duration) | `no` | The [`duration`](#duration), if any, after which to delete the container once executed.<br>*Required if `cleanup` has been set to `eventually`, otherwise ignored.* |
1928+
### Process Result
1929+
1930+
Describes the result of a process.
1931+
1932+
#### Properties
1933+
1934+
| Name | Type | Required | Description|
1935+
|:--|:---:|:---:|:---|
1936+
| code | `integer` | `yes` | The process's exit code. |
1937+
| stdout | `string` | `yes` | The process's **STDOUT** output. |
1938+
| stderr | `string` | `yes` | The process's **STDERR** output. |
19041939

19051940
#### Examples
19061941

@@ -1919,4 +1954,173 @@ do:
19191954
cleanup: eventually
19201955
after:
19211956
minutes: 30
1957+
return: stderr
1958+
1959+
- runScript:
1960+
run:
1961+
script:
1962+
language: js
1963+
code: >
1964+
Some cool multiline script
1965+
return: code
1966+
1967+
- runShell:
1968+
run:
1969+
shell:
1970+
command: 'echo "Hello, ${ .user.name }"'
1971+
return: all
1972+
1973+
- runWorkflow:
1974+
run:
1975+
workflow:
1976+
namespace: another-one
1977+
name: do-stuff
1978+
version: '0.1.0'
1979+
input: {}
1980+
return: none
1981+
```
1982+
1983+
### AsyncAPI Server
1984+
1985+
Configures the target server of an AsyncAPI operation.
1986+
1987+
#### Properties
1988+
1989+
| Name | Type | Required | Description |
1990+
|:-------|:------:|:----------:|:--------------|
1991+
| name | `string` | `yes` | The name of the [server](https://www.asyncapi.com/docs/reference/specification/v3.0.0#serverObject) to call the specified AsyncAPI operation on. |
1992+
| variables | `object` | `no` | The target [server's variables](https://www.asyncapi.com/docs/reference/specification/v3.0.0#serverVariableObject), if any. |
1993+
1994+
#### Examples
1995+
1996+
```yaml
1997+
document:
1998+
dsl: '1.0.0-alpha5'
1999+
namespace: test
2000+
name: asyncapi-example
2001+
version: '0.1.0'
2002+
do:
2003+
- publishGreetings:
2004+
call: asyncapi
2005+
with:
2006+
document:
2007+
endpoint: https://fake.com/docs/asyncapi.json
2008+
operation: greet
2009+
server:
2010+
name: greetingsServer
2011+
variables:
2012+
environment: dev
2013+
message:
2014+
payload:
2015+
greetings: Hello, World!
2016+
headers:
2017+
foo: bar
2018+
bar: baz
2019+
```
2020+
2021+
### AsyncAPI Message
2022+
2023+
Configures an AsyncAPI message to publish.
2024+
2025+
#### Properties
2026+
2027+
| Name | Type | Required | Description |
2028+
|:-------|:------:|:----------:|:--------------|
2029+
| payload | `object` | `no` | The message's payload, if any. |
2030+
| headers | `object` | `no` | The message's headers, if any. |
2031+
2032+
#### Examples
2033+
2034+
```yaml
2035+
document:
2036+
dsl: '1.0.0-alpha5'
2037+
namespace: test
2038+
name: asyncapi-example
2039+
version: '0.1.0'
2040+
do:
2041+
- publishGreetings:
2042+
call: asyncapi
2043+
with:
2044+
document:
2045+
endpoint: https://fake.com/docs/asyncapi.json
2046+
operation: greet
2047+
protocol: http
2048+
message:
2049+
payload:
2050+
greetings: Hello, World!
2051+
headers:
2052+
foo: bar
2053+
bar: baz
2054+
```
2055+
2056+
### AsyncAPI Subscription
2057+
2058+
Configures a subscription to an AsyncAPI operation.
2059+
2060+
#### Properties
2061+
2062+
| Name | Type | Required | Description |
2063+
|:-------|:------:|:----------:|:--------------|
2064+
| filter | `string` | `no` | A [runtime expression](dsl.md#runtime-expressions), if any, used to filter consumed messages. |
2065+
| consume | [`subscriptionLifetime`](#asyncapi-subscription-lifetime) | `yes` | An object used to configure the subscription's lifetime. |
2066+
2067+
#### Examples
2068+
2069+
```yaml
2070+
document:
2071+
dsl: '1.0.0-alpha5'
2072+
namespace: test
2073+
name: asyncapi-example
2074+
version: '0.1.0'
2075+
do:
2076+
- subscribeToChatInboxForAmount:
2077+
call: asyncapi
2078+
with:
2079+
document:
2080+
endpoint: https://fake.com/docs/asyncapi.json
2081+
operation: chat-inbox
2082+
protocol: http
2083+
subscription:
2084+
filter: ${ . == $workflow.input.chat.roomId }
2085+
consume:
2086+
amount: 5
2087+
for:
2088+
seconds: 10
2089+
```
2090+
2091+
### AsyncAPI Subscription Lifetime
2092+
2093+
Configures the lifetime of an AsyncAPI subscription
2094+
2095+
#### Properties
2096+
2097+
| Name | Type | Required | Description |
2098+
|:-------|:------:|:----------:|:--------------|
2099+
| amount | `integer` | `no` | The amount of messages to consume.<br>*Required if `while` and `until` have not been set.* |
2100+
| for | [`duration`](#duration) | `no` | The [`duration`](#duration) that defines for how long to consume messages. |
2101+
| while | `string` | `no` | A [runtime expression](dsl.md#runtime-expressions), if any, used to determine whether or not to keep consuming messages.<br>*Required if `amount` and `until` have not been set.* |
2102+
| until | `string` | `no` | A [runtime expression](dsl.md#runtime-expressions), if any, used to determine until when to consume messages.<br>*Required if `amount` and `while` have not been set.* |
2103+
2104+
#### Examples
2105+
2106+
```yaml
2107+
document:
2108+
dsl: '1.0.0-alpha5'
2109+
namespace: test
2110+
name: asyncapi-example
2111+
version: '0.1.0'
2112+
do:
2113+
- subscribeToChatInboxUntil:
2114+
call: asyncapi
2115+
with:
2116+
document:
2117+
endpoint: https://fake.com/docs/asyncapi.json
2118+
operation: chat-inbox
2119+
protocol: http
2120+
subscription:
2121+
filter: ${ . == $workflow.input.chat.roomId }
2122+
consume:
2123+
until: '${ ($context.messages | length) == 5 }'
2124+
for:
2125+
seconds: 10
19222126
```

‎dsl.md

Lines changed: 20 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -343,18 +343,20 @@ When the evaluation of an expression fails, runtimes **must** raise an error wit
343343
| input | `any` | The task's transformed input. |
344344
| output | `any` | The task's transformed output. |
345345
| secrets | `map` | A key/value map of the workflow secrets.<br>To avoid unintentional bleeding, secrets can only be used in the `input.from` runtime expression. |
346+
| authorization | [`authorizationDescriptor`](#authorization-descriptor) | Describes the resolved authorization, as defined by the task's authentication, if any. |
346347
| task | [`taskDescriptor`](#task-descriptor) | Describes the current task. |
347348
| workflow | [`workflowDescriptor`](#workflow-descriptor) | Describes the current workflow. |
348349
| runtime | [`runtimeDescriptor`](#runtime-descriptor) | Describes the runtime. |
349350

351+
350352
##### Runtime Descriptor
351353

352354
This argument contains information about the runtime executing the workflow.
353355

354356
| Name | Type | Description | Example |
355-
|:-----|:----:|:------------| ------- |
357+
|:-----|:----:|:------------|:--------|
356358
| name | `string` | A human friendly name for the runtime. | `Synapse`, `Sonata` |
357-
| version | `string` | The version of the runtime. This can be an arbitrary string | a incrementing positive integer (`362`), semantic version (`1.4.78`), commit hash (`04cd3be6da98fc35422c8caa821e0aa1ef6b2c02`) or container image label (`v0.7.43-alpine`) |
359+
| version | `string` | The version of the runtime. This can be an arbitrary string | An incrementing positive integer (`362`), semantic version (`1.4.78`), commit hash (`04cd3be6da98fc35422c8caa821e0aa1ef6b2c02`) or container image label (`v0.7.43-alpine`) |
358360
| metadata | `map` | An object/map of implementation specific key-value pairs. This can be chosen by runtime implementors and usage of this argument signals that a given workflow definition might not be runtime agnostic | A Software as a Service (SaaS) provider might choose to expose information about the tenant the workflow is executed for e.g. `{ "organization": { "id": "org-ff51cff2-fc83-4d70-9af1-8dacdbbce0be", "name": "example-corp" }, "featureFlags": ["fastZip", "arm64"] }`. |
359361

360362
##### Workflow Descriptor
@@ -377,6 +379,13 @@ This argument contains information about the runtime executing the workflow.
377379
| output | `any` | The task's *raw* output (i.e. *BEFORE* the `output.as` expression). | |
378380
| startedAt | [`dateTimeDescriptor`](#datetime-descriptor) | The start time of the task | |
379381

382+
##### Authorization Descriptor
383+
384+
| Name | Type | Description | Example |
385+
|:-------|:------:|:------------|:--------|
386+
| scheme | `string` | The resolved authorization scheme. | `Bearer` |
387+
| parameter | `string` | The resolved authorization parameter. | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJVadQssw5c` |
388+
380389
##### DateTime Descriptor
381390

382391
| Name | Type | Description | Example |
@@ -387,15 +396,15 @@ This argument contains information about the runtime executing the workflow.
387396

388397
The following table shows which arguments are available for each runtime expression:
389398

390-
| Runtime Expression | Evaluated on | Produces | `$context` | `$input` | `$output` | `$secrets` | `$task` | `$workflow` |
391-
|:-------------------|:---------:|:---------:|:---------:|:---------:|:-------:|:---------:|:-------:|:----------:|
392-
| Workflow `input.from` | Raw workflow input | Transformed workflow input | | | | ✔ | | ✔ |
393-
| Task `input.from` | Raw task input (i.e. transformed workflow input for the first task, transformed output from previous task otherwise) | Transformed task input | ✔ | | | ✔ | ✔ | ✔ |
394-
| Task `if` | Transformed task input | | ✔ | ✔ | | ✔ | ✔ | ✔ |
395-
| Task definition | Transformed task input | | ✔ | ✔ | | ✔ | ✔ | ✔ |
396-
| Task `output.as` | Raw task output | Transformed task output | ✔ | ✔ | | ✔ | ✔ | ✔ |
397-
| Task `export.as` | Transformed task output | `$context` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
398-
| Workflow `output.as` | Last task's transformed output | Transformed workflow output | ✔ | | | ✔ | | ✔ |
399+
| Runtime Expression | Evaluated on | Produces | `$context` | `$input` | `$output` | `$secrets` | `$task` | `$workflow` | `$runtime` | `$authorization` |
400+
|:-------------------|:---------:|:---------:|:---------:|:---------:|:-------:|:---------:|:-------:|:----------:|:----------:|:----------:|
401+
| Workflow `input.from` | Raw workflow input | Transformed workflow input | | | | ✔ | | ✔ | ✔ | |
402+
| Task `input.from` | Raw task input (i.e. transformed workflow input for the first task, transformed output from previous task otherwise) | Transformed task input | ✔ | | | ✔ | ✔ | ✔ | ✔ | |
403+
| Task `if` | Transformed task input | | ✔ | ✔ | | ✔ | ✔ | ✔ | ✔ | |
404+
| Task definition | Transformed task input | | ✔ | ✔ | | ✔ | ✔ | ✔ | ✔ | ✔ |
405+
| Task `output.as` | Raw task output | Transformed task output | ✔ | ✔ | | ✔ | ✔ | ✔ | ✔ | ✔ |
406+
| Task `export.as` | Transformed task output | `$context` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
407+
| Workflow `output.as` | Last task's transformed output | Transformed workflow output | ✔ | | | ✔ | | ✔ | ✔ | |
399408

400409
### Fault Tolerance
401410

‎examples/call-asyncapi.yaml renamed to ‎examples/call-asyncapi-publish.yaml

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,12 @@ do:
99
with:
1010
document:
1111
endpoint: https://fake.com/docs/asyncapi.json
12-
operationRef: findPetsByStatus
13-
server: staging
14-
message: getPetByStatusQuery
15-
binding: http
16-
payload:
17-
petId: ${ .pet.id }
12+
operation: findPetsByStatus
13+
server:
14+
name: staging
15+
message:
16+
payload:
17+
petId: ${ .pet.id }
1818
authentication:
1919
bearer:
2020
token: ${ .token }

‎examples/call-asyncapi-subscribe-consume-amount.yaml

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
document:
2+
dsl: '1.0.0-alpha5'
3+
namespace: examples
4+
name: bearer-auth
5+
version: '0.1.0'
6+
do:
7+
- getNotifications:
8+
call: asyncapi
9+
with:
10+
document:
11+
endpoint: https://fake.com/docs/asyncapi.json
12+
operation: getNotifications
13+
protocol: ws
14+
subscription:
15+
filter: '${ .correlationId == $context.userId and .payload.from.firstName == $context.contact.firstName and .payload.from.lastName == $context.contact.lastName }'
16+
consume:
17+
amount: 5

0 commit comments

Comments
 (0)