Skip to content

Commit 865464e

Browse files
authored
Merge branch 'main' into feat-lifecycle-cloud-events
2 parents bd6e4ed + be474b2 commit 865464e

File tree

6 files changed

+222
-14
lines changed

6 files changed

+222
-14
lines changed

README.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,10 +73,12 @@ These SDKs empower developers to seamlessly integrate serverless workflows into
7373

7474
Explore our SDKs for different programming languages:
7575

76+
- [.NET](https://github.com/serverlessworkflow/sdk-net)
7677
- [Go](https://github.com/serverlessworkflow/sdk-go)
7778
- [Java](https://github.com/serverlessworkflow/sdk-java)
78-
- [.NET](https://github.com/serverlessworkflow/sdk-net)
79+
- [PHP](https://github.com/serverlessworkflow/sdk-php)
7980
- [Python](https://github.com/serverlessworkflow/sdk-python)
81+
- [Rust](https://github.com/serverlessworkflow/sdk-rust)
8082
- [TypeScript](https://github.com/serverlessworkflow/sdk-typescript)
8183

8284
Don't see your favorite implementation on the list? Shout out to the community about it or, even better, contribute to the ecosystem with a new SDK!

dsl-reference.md

Lines changed: 104 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -79,9 +79,10 @@
7979
+ [Container Lifetime](#container-lifetime)
8080
+ [Process Result](#process-result)
8181
+ [AsyncAPI Server](#asyncapi-server)
82-
+ [AsyncAPI Message](#asyncapi-message)
82+
+ [AsyncAPI Outbound Message](#asyncapi-outbound-message)
8383
+ [AsyncAPI Subscription](#asyncapi-subscription)
8484
+ [Workflow Definition Reference](#workflow-definition-reference)
85+
+ [Subscription Iterator](#subscription-iterator)
8586

8687
## Abstract
8788

@@ -333,7 +334,7 @@ The [AsyncAPI Call](#asyncapi-call) enables workflows to interact with external
333334
| 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`.* |
334335
| 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. |
335336
| 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`* |
336-
| 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.* |
337+
| message | [`asyncApiMessage`](#asyncapi-outbound-message) | `no` | An object used to configure the message to publish using the target operation.<br>*Required if `subscription` has not been set.* |
337338
| 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.* |
338339
| authentication | `string`<br>[`authentication`](#authentication) | `no` | The authentication policy, or the name of the authentication policy, to use when calling the AsyncAPI operation. |
339340

@@ -672,7 +673,19 @@ Provides a mechanism for workflows to await and react to external events, enabli
672673

673674
| Name | Type | Required | Description|
674675
|:--|:---:|:---:|:---|
675-
| listen.to | [`eventConsumptionStrategy`](#event-consumption-strategy) | `yes` | Configures the event(s) the workflow must listen to. |
676+
| listen.to | [`eventConsumptionStrategy`](#event-consumption-strategy) | `yes` | Configures the [event(s)](https://cloudevents.io/) the workflow must listen to. |
677+
| listen.read | `string` | `no` | Specifies how [events](https://cloudevents.io/) are read during the listen operation.<br>*Supported values are:*<br>*- `data`: Reads the [event's](https://cloudevents.io/) data.*<br>*- `envelope`: Reads the [event's](https://cloudevents.io/) envelope, including its [context attributes](https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#context-attributes).*<br>*- `raw`: Reads the [event's](https://cloudevents.io/) raw data.*<br>*Defaults to `data`.*|
678+
| foreach | [`subscriptionIterator`](#subscription-iterator) | `no` | Configures the iterator, if any, for processing each consumed [event](https://cloudevents.io/). |
679+
680+
> [!NOTE]
681+
> A `listen` task produces a sequentially ordered array of all the [events](https://cloudevents.io/) it has consumed, and potentially transformed using `foreach.output.as`.
682+
683+
> [!NOTE]
684+
> When `foreach` is set, the configured operations for a [events](https://cloudevents.io/) must complete before moving on to the next one. As a result, consumed [events](https://cloudevents.io/) should be stored in a First-In-First-Out (FIFO) queue while awaiting iteration.
685+
686+
> [!WARNING]
687+
> [Events](https://cloudevents.io/) consumed by an `until` clause should not be included in the task's output. These [events](https://cloudevents.io/) are used solely to determine when the until condition has been met, and they do not contribute to the result or data produced by the task itself
688+
676689

677690
##### Examples
678691

@@ -689,12 +702,10 @@ do:
689702
any:
690703
- with:
691704
type: com.fake-hospital.vitals.measurements.temperature
692-
data:
693-
temperature: ${ .temperature > 38 }
705+
data: ${ .temperature > 38 }
694706
- with:
695707
type: com.fake-hospital.vitals.measurements.bpm
696-
data:
697-
temperature: ${ .bpm < 60 or .bpm > 100 }
708+
data: ${ .bpm < 60 or .bpm > 100 }
698709
```
699710

700711
#### Raise
@@ -2004,7 +2015,7 @@ An event object typically includes details such as the event type, source, times
20042015
| subject | `string` | `no` | Describes the subject of the event in the context of the event producer. |
20052016
| datacontenttype | `string` | `no` | Content type of `data` value. If omitted, it implies the `data` is a JSON value conforming to the "application/json" media type. |
20062017
| dataschema | `string` | `no` | An URI formatted string, or [runtime expression](dsl.md#runtime-expressions), that identifies the schema that `data` adheres to. |
2007-
| data | `object` | `no` | The event payload. |
2018+
| data | `any` | `no` | The event payload. |
20082019

20092020
*Additional properties can be supplied, see the Cloud Events specification [documentation](https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#extension-context-attributes) for more info.*
20102021

@@ -2445,7 +2456,7 @@ do:
24452456
bar: baz
24462457
```
24472458

2448-
### AsyncAPI Message
2459+
### AsyncAPI Outbound Message
24492460

24502461
Configures an AsyncAPI message to publish.
24512462

@@ -2480,16 +2491,46 @@ do:
24802491
bar: baz
24812492
```
24822493

2494+
### AsyncAPI Inbound Message
2495+
2496+
Configures an AsyncAPI message consumed by a subscription.
2497+
2498+
#### Properties
2499+
2500+
| Name | Type | Required | Description |
2501+
|:-------|:------:|:----------:|:--------------|
2502+
| payload | `object` | `no` | The message's payload, if any. |
2503+
| headers | `object` | `no` | The message's headers, if any. |
2504+
| correlationId | `string` | `no` | The message's correlation id, if any. |
2505+
2506+
#### Examples
2507+
2508+
```yaml
2509+
payload:
2510+
greetings: Hello, World!
2511+
headers:
2512+
foo: bar
2513+
bar: baz
2514+
correlationid: '123456'
2515+
```
2516+
24832517
### AsyncAPI Subscription
24842518

24852519
Configures a subscription to an AsyncAPI operation.
24862520

24872521
#### Properties
24882522

24892523
| Name | Type | Required | Description |
2490-
|:-----|:----:|:--------:|:------------|
2491-
| filter | `string` | `no` | A [runtime expression](dsl.md#runtime-expressions), if any, used to filter consumed messages. |
2524+
|:-------|:------:|:----------:|:--------------|
2525+
| filter | `string` | `no` | A [runtime expression](dsl.md#runtime-expressions), if any, used to filter consumed [messages](#asyncapi-inbound-message). |
24922526
| consume | [`subscriptionLifetime`](#asyncapi-subscription-lifetime) | `yes` | An object used to configure the subscription's lifetime. |
2527+
| foreach | [`subscriptionIterator`](#subscription-iterator) | `no` | Configures the iterator, if any, for processing each consumed [message](#asyncapi-inbound-message). |
2528+
2529+
> [!NOTE]
2530+
> An AsyncAPI subscribe operation call produces a sequentially ordered array of all the [messages](#asyncapi-inbound-message) it has consumed, and potentially transformed using `foreach.output.as`.
2531+
2532+
> [!NOTE]
2533+
> When `foreach` is set, the configured operations for a [message](#asyncapi-inbound-message) must complete before moving on to the next one. As a result, consumed [messages](#asyncapi-inbound-message) should be stored in a First-In-First-Out (FIFO) queue while awaiting iteration.
24932534

24942535
#### Examples
24952536

@@ -2552,18 +2593,68 @@ do:
25522593
seconds: 10
25532594
```
25542595

2596+
### Subscription Iterator
2597+
2598+
Configures the iteration over each item (event or message) consumed by a subscription. It encapsulates configuration for processing tasks, output formatting, and export behavior for every item encountered.
2599+
2600+
#### Properties
2601+
2602+
| Name | Type | Required | Description |
2603+
|:-----|:----:|:--------:|:------------|
2604+
| item | `string` | `no` | The name of the variable used to store the current item being enumerated.<br>*Defaults to `item`.* |
2605+
| at | `string` | `no` | The name of the variable used to store the index of the current item being enumerated.<br>*Defaults to `index`.* |
2606+
| do | [`map[string, task][]`](#task) | `no` | The tasks to perform for each consumed item. |
2607+
| output | [`output`](#output) | `no` | An object, if any, used to customize the item's output and to document its schema. |
2608+
| export | [`export`](#export) | `no` | An object, if any, used to customize the content of the workflow context. |
2609+
2610+
#### Examples
2611+
2612+
```yaml
2613+
document:
2614+
dsl: '1.0.0-alpha5'
2615+
namespace: test
2616+
name: asyncapi-example
2617+
version: '0.1.0'
2618+
do:
2619+
- subscribeToChatInboxUntil:
2620+
call: asyncapi
2621+
with:
2622+
document:
2623+
endpoint: https://fake.com/docs/asyncapi.json
2624+
operation: chat-inbox
2625+
protocol: http
2626+
subscription:
2627+
filter: ${ . == $workflow.input.chat.roomId }
2628+
consume:
2629+
until: '${ ($context.messages | length) == 5 }'
2630+
for:
2631+
seconds: 10
2632+
foreach:
2633+
item: message
2634+
at: index
2635+
do:
2636+
- emitEvent:
2637+
emit:
2638+
event:
2639+
with:
2640+
source: https://serverlessworkflow.io/samples
2641+
type: io.serverlessworkflow.samples.asyncapi.message.consumed.v1
2642+
data:
2643+
message: '${ $message }'
2644+
```
2645+
25552646
### Workflow Definition Reference
25562647

25572648
References a workflow definition.
2558-
2649+
25592650
#### Properties
25602651

25612652
| Name | Type | Required | Description |
25622653
|:-----|:----:|:--------:|:------------|
25632654
| name | `string` | `yes` | The name of the referenced workflow definition. |
25642655
| namespace | `string` | `yes` | The namespace of the referenced workflow definition. |
25652656
| version | `string` | `yes` | The semantic version of the referenced workflow definition. |
2566-
2657+
25672658
#### Examples
25682659

25692660
```yaml
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
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+
subscription:
14+
filter: '${ .correlationId == $context.userId and .payload.from.firstName == $context.contact.firstName and .payload.from.lastName == $context.contact.lastName }'
15+
consume:
16+
while: '${ true }'
17+
foreach:
18+
item: message
19+
do:
20+
- publishCloudEvent:
21+
emit:
22+
event:
23+
with:
24+
source: https://serverlessworkflow.io/samples
25+
type: io.serverlessworkflow.samples.asyncapi.message.consumed.v1
26+
data:
27+
message: '${ $message }'
28+
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: test
4+
name: listen-to-all-read-envelope
5+
version: '0.1.0'
6+
do:
7+
- callDoctor:
8+
listen:
9+
to:
10+
all:
11+
- with:
12+
type: com.fake-hospital.vitals.measurements.temperature
13+
data: ${ .temperature > 38 }
14+
- with:
15+
type: com.fake-hospital.vitals.measurements.bpm
16+
data: ${ .bpm < 60 or .bpm > 100 }
17+
read: envelope
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
document:
2+
dsl: '1.0.0-alpha1'
3+
namespace: test
4+
name: listen-to-any-while-foreach
5+
version: '0.1.0'
6+
do:
7+
- listenToGossips:
8+
listen:
9+
to:
10+
any: []
11+
until: '${ false }'
12+
foreach:
13+
item: event
14+
at: i
15+
do:
16+
- postToChatApi:
17+
call: http
18+
with:
19+
method: post
20+
endpoint: https://fake-chat-api.com/room/{roomId}
21+
body:
22+
event: ${ $event }

schema/workflow.yaml

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -558,7 +558,17 @@ $defs:
558558
$ref: '#/$defs/eventConsumptionStrategy'
559559
title: ListenTo
560560
description: Defines the event(s) to listen to.
561+
read:
562+
type: string
563+
enum: [ data, envelope, raw ]
564+
default: data
565+
title: ListenAndReadAs
566+
description: Specifies how events are read during the listen operation.
561567
required: [ to ]
568+
foreach:
569+
$ref: '#/$defs/subscriptionIterator'
570+
title: ListenIterator
571+
description: Configures the iterator, if any, for processing consumed event(s).
562572
raiseTask:
563573
type: object
564574
$ref: '#/$defs/taskBase'
@@ -1292,6 +1302,12 @@ $defs:
12921302
- title: ExpressionDataSchema
12931303
$ref: '#/$defs/runtimeExpression'
12941304
description: An expression based event data schema.
1305+
data:
1306+
title: EventData
1307+
description: The event's payload data
1308+
anyOf:
1309+
- $ref: '#/$defs/runtimeExpression'
1310+
- {}
12951311
additionalProperties: true
12961312
eventConsumptionStrategy:
12971313
type: object
@@ -1704,6 +1720,10 @@ $defs:
17041720
$ref: '#/$defs/asyncApiMessageConsumptionPolicy'
17051721
title: AsyncApiMessageConsumptionPolicy
17061722
description: An object used to configure the subscription's message consumption policy.
1723+
foreach:
1724+
$ref: '#/$defs/subscriptionIterator'
1725+
title: AsyncApiSubscriptionIterator
1726+
description: Configures the iterator, if any, for processing consumed messages(s).
17071727
required: [ consume ]
17081728
asyncApiMessageConsumptionPolicy:
17091729
type: object
@@ -1734,3 +1754,31 @@ $defs:
17341754
title: AsyncApiMessageConsumptionPolicyUntil
17351755
description: A runtime expression evaluated before each consumed (filtered) message to decide if message consumption should continue.
17361756
required: [ until ]
1757+
subscriptionIterator:
1758+
type: object
1759+
title: SubscriptionIterator
1760+
description: Configures the iteration over each item (event or message) consumed by a subscription.
1761+
unevaluatedProperties: false
1762+
properties:
1763+
item:
1764+
type: string
1765+
title: SubscriptionIteratorItem
1766+
description: The name of the variable used to store the current item being enumerated.
1767+
default: item
1768+
at:
1769+
type: string
1770+
title: SubscriptionIteratorIndex
1771+
description: The name of the variable used to store the index of the current item being enumerated.
1772+
default: index
1773+
do:
1774+
$ref: '#/$defs/taskList'
1775+
title: SubscriptionIteratorTasks
1776+
description: The tasks to perform for each consumed item.
1777+
output:
1778+
$ref: '#/$defs/output'
1779+
title: SubscriptionIteratorOutput
1780+
description: An object, if any, used to customize the item's output and to document its schema.
1781+
export:
1782+
$ref: '#/$defs/export'
1783+
title: SubscriptionIteratorExport
1784+
description: An object, if any, used to customize the content of the workflow context.

0 commit comments

Comments
 (0)