Skip to content

Commit 15e2f10

Browse files
ricardozaniniricardozanini
authored
Fix #222 - Basic raw implementation for DSL 1.0.0 (#224)
* Fix #222 - (WIP): Basic raw implementation for DSL 1.0.0 Signed-off-by: Ricardo Zanini <[email protected]> * Evaluate expressions, statusphase, schema validation, export, as, from Signed-off-by: Ricardo Zanini <[email protected]> * Add raise task Signed-off-by: Ricardo Zanini <[email protected]> * Task Do implementation and refactoring Signed-off-by: Ricardo Zanini <[email protected]> * Upgrade Upload Artifact Signed-off-by: Ricardo Zanini <[email protected]> * Add missing license headers Signed-off-by: Ricardo Zanini <[email protected]> * Fix lint Signed-off-by: Ricardo Zanini <[email protected]> * Add partial 'For' implementation Signed-off-by: Ricardo Zanini <[email protected]> * Add implementation docs Signed-off-by: Ricardo Zanini <[email protected]> * Solve lint issues Signed-off-by: Ricardo Zanini <[email protected]> * Readd releases table to README Signed-off-by: Ricardo Zanini <[email protected]> --------- Signed-off-by: Ricardo Zanini <[email protected]>
1 parent ff500a0 commit 15e2f10

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

62 files changed

+3448
-230
lines changed

‎.github/workflows/Go-SDK-PR-Check.yaml

+2-2
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ jobs:
9393
run: go test ./... -coverprofile=test_coverage.out -covermode=atomic
9494

9595
- name: Upload Coverage Report
96-
uses: actions/upload-artifact@v3
96+
uses: actions/upload-artifact@v4
9797
with:
9898
name: Test Coverage Report
9999
path: test_coverage.out
@@ -120,7 +120,7 @@ jobs:
120120

121121
- name: Upload JUnit Report
122122
if: always()
123-
uses: actions/upload-artifact@v3
123+
uses: actions/upload-artifact@v4
124124
with:
125125
name: Integration Test JUnit Report
126126
path: ./integration-test-junit.xml

‎README.md

+130-97
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Go SDK for Serverless Workflow
22

3-
The Go SDK for Serverless Workflow provides the [specification types](https://github.com/serverlessworkflow/specification/blob/v1.0.0-alpha5/schema/workflow.yaml) defined by the Serverless Workflow DSL in Go, making it easy to parse, validate, and interact with workflows.
3+
The Go SDK for Serverless Workflow provides strongly-typed structures for the [Serverless Workflow specification](https://github.com/serverlessworkflow/specification/blob/v1.0.0/schema/workflow.yaml). It simplifies parsing, validating, and interacting with workflows in Go. Starting from version `v3.1.0`, the SDK also includes a partial reference implementation, allowing users to execute workflows directly within their Go applications.
44

55
---
66

@@ -10,8 +10,11 @@ The Go SDK for Serverless Workflow provides the [specification types](https://gi
1010
- [Releases](#releases)
1111
- [Getting Started](#getting-started)
1212
- [Installation](#installation)
13+
- [Basic Usage](#basic-usage)
1314
- [Parsing Workflow Files](#parsing-workflow-files)
1415
- [Programmatic Workflow Creation](#programmatic-workflow-creation)
16+
- [Reference Implementation](#reference-implementation)
17+
- [Example: Running a Workflow](#example-running-a-workflow)
1518
- [Slack Community](#slack-community)
1619
- [Contributing](#contributing)
1720
- [Code Style](#code-style)
@@ -22,160 +25,190 @@ The Go SDK for Serverless Workflow provides the [specification types](https://gi
2225

2326
## Status
2427

25-
The current status of features implemented in the SDK is listed below:
28+
This table indicates the current state of implementation of various SDK features:
2629

27-
| Feature | Status |
28-
|-------------------------------------------- | ------------------ |
29-
| Parse workflow JSON and YAML definitions | :heavy_check_mark: |
30-
| Programmatically build workflow definitions | :heavy_check_mark: |
31-
| Validate workflow definitions (Schema) | :heavy_check_mark: |
32-
| Validate workflow definitions (Integrity) | :no_entry_sign: |
33-
| Generate workflow diagram (SVG) | :no_entry_sign: |
30+
| Feature | Status |
31+
|-------------------------------------------- |---------------------|
32+
| Parse workflow JSON and YAML definitions | :heavy_check_mark: |
33+
| Programmatically build workflow definitions | :heavy_check_mark: |
34+
| Validate workflow definitions (Schema) | :heavy_check_mark: |
35+
| Specification Implementation | :heavy_check_mark:* |
36+
| Validate workflow definitions (Integrity) | :no_entry_sign: |
37+
| Generate workflow diagram (SVG) | :no_entry_sign: |
38+
39+
> **Note**: *Implementation is partial; contributions are encouraged.
3440
3541
---
3642

3743
## Releases
3844

39-
| Latest Releases | Conformance to Spec Version |
40-
|:--------------------------------------------------------------------------:|:------------------------------------------------------------------------:|
41-
| [v1.0.0](https://github.com/serverlessworkflow/sdk-go/releases/tag/v1.0.0) | [v0.5](https://github.com/serverlessworkflow/specification/tree/0.5.x) |
42-
| [v2.0.1](https://github.com/serverlessworkflow/sdk-go/releases/tag/v2.0.1) | [v0.6](https://github.com/serverlessworkflow/specification/tree/0.6.x) |
43-
| [v2.1.2](https://github.com/serverlessworkflow/sdk-go/releases/tag/v2.1.2) | [v0.7](https://github.com/serverlessworkflow/specification/tree/0.7.x) |
44-
| [v2.4.3](https://github.com/serverlessworkflow/sdk-go/releases/tag/v2.4.1) | [v0.8](https://github.com/serverlessworkflow/specification/tree/0.8.x) |
45-
| [v3.0.0](https://github.com/serverlessworkflow/sdk-go/releases/tag/v3.0.0) | [v1.0.0](https://github.com/serverlessworkflow/specification/releases/tag/v1.0.0-alpha5) |
45+
| Latest Releases | Conformance to Spec Version |
46+
|:--------------------------------------------------------------------------:|:---------------------------------------------------------------------------------:|
47+
| [v1.0.0](https://github.com/serverlessworkflow/sdk-go/releases/tag/v1.0.0) | [v0.5](https://github.com/serverlessworkflow/specification/tree/0.5.x) |
48+
| [v2.0.1](https://github.com/serverlessworkflow/sdk-go/releases/tag/v2.0.1) | [v0.6](https://github.com/serverlessworkflow/specification/tree/0.6.x) |
49+
| [v2.1.2](https://github.com/serverlessworkflow/sdk-go/releases/tag/v2.1.2) | [v0.7](https://github.com/serverlessworkflow/specification/tree/0.7.x) |
50+
| [v2.4.3](https://github.com/serverlessworkflow/sdk-go/releases/tag/v2.4.1) | [v0.8](https://github.com/serverlessworkflow/specification/tree/0.8.x) |
51+
| [v3.0.0](https://github.com/serverlessworkflow/sdk-go/releases/tag/v3.0.0) | [v1.0.0](https://github.com/serverlessworkflow/specification/releases/tag/v1.0.0) |
4652

4753
---
4854

49-
## Getting Started
50-
51-
### Installation
52-
53-
To use the SDK in your Go project, run the following command:
54-
55-
```shell
56-
$ go get github.com/serverlessworkflow/sdk-go/v3
57-
```
58-
59-
This will update your `go.mod` file to include the Serverless Workflow SDK as a dependency.
60-
61-
Import the SDK in your Go file:
62-
63-
```go
64-
import "github.com/serverlessworkflow/sdk-go/v3/model"
65-
```
66-
67-
You can now use the SDK types and functions, for example:
55+
## Reference Implementation
6856

69-
```go
70-
package main
57+
The SDK provides a partial reference runner to execute your workflows:
7158

72-
import (
73-
"github.com/serverlessworkflow/sdk-go/v3/builder"
74-
"github.com/serverlessworkflow/sdk-go/v3/model"
75-
)
59+
### Example: Running a Workflow
7660

77-
func main() {
78-
workflowBuilder := New().
79-
SetDocument("1.0.0", "examples", "example-workflow", "1.0.0").
80-
AddTask("task1", &model.CallHTTP{
81-
TaskBase: model.TaskBase{
82-
If: &model.RuntimeExpression{Value: "${condition}"},
83-
},
84-
Call: "http",
85-
With: model.HTTPArguments{
86-
Method: "GET",
87-
Endpoint: model.NewEndpoint("http://example.com"),
88-
},
89-
})
90-
workflow, _ := builder.Object(workflowBuilder)
91-
// use your models
92-
}
61+
Below is a simple YAML workflow that sets a message and then prints it:
9362

63+
```yaml
64+
document:
65+
dsl: "1.0.0"
66+
namespace: "examples"
67+
name: "simple-workflow"
68+
version: "1.0.0"
69+
do:
70+
- set:
71+
message: "Hello from the Serverless Workflow SDK in Go!"
9472
```
9573
96-
### Parsing Workflow Files
74+
You can execute this workflow using the following Go program:
9775
98-
The Serverless Workflow Specification supports YAML and JSON files. Use the following example to parse a workflow file into a Go data structure:
76+
Example of executing a workflow defined in YAML:
9977
10078
```go
10179
package main
10280

10381
import (
104-
"github.com/serverlessworkflow/sdk-go/v3/model"
82+
"fmt"
83+
"os"
84+
"path/filepath"
85+
86+
"github.com/serverlessworkflow/sdk-go/v3/impl"
10587
"github.com/serverlessworkflow/sdk-go/v3/parser"
10688
)
10789

108-
func ParseWorkflow(filePath string) (*model.Workflow, error) {
109-
workflow, err := parser.FromFile(filePath)
90+
func RunWorkflow(workflowFilePath string, input map[string]interface{}) (interface{}, error) {
91+
data, err := os.ReadFile(filepath.Clean(workflowFilePath))
92+
if err != nil {
93+
return nil, err
94+
}
95+
workflow, err := parser.FromYAMLSource(data)
11096
if err != nil {
11197
return nil, err
11298
}
113-
return workflow, nil
114-
}
115-
```
11699

117-
This `Workflow` structure can then be used programmatically in your application.
100+
runner := impl.NewDefaultRunner(workflow)
101+
output, err := runner.Run(input)
102+
if err != nil {
103+
return nil, err
104+
}
105+
return output, nil
106+
}
118107

119-
### Programmatic Workflow Creation
108+
func main() {
109+
output, err := RunWorkflow("./myworkflow.yaml", map[string]interface{}{"shouldCall": true})
110+
if err != nil {
111+
panic(err)
112+
}
113+
fmt.Printf("Workflow completed with output: %v\n", output)
114+
}
115+
```
120116

121-
Support for building workflows programmatically is planned for future releases. Stay tuned for updates in upcoming versions.
117+
### Implementation Roadmap
118+
119+
The table below lists the current state of this implementation. This table is a roadmap for the project based on the [DSL Reference doc](https://github.com/serverlessworkflow/specification/blob/v1.0.0/dsl-reference.md).
120+
121+
| Feature | State |
122+
| ----------- | --------------- |
123+
| Workflow Document | ✅ |
124+
| Workflow Use | 🟡 |
125+
| Workflow Schedule | ❌ |
126+
| Task Call | ❌ |
127+
| Task Do | ✅ |
128+
| Task Emit | ❌ |
129+
| Task For | ❌ |
130+
| Task Fork | ❌ |
131+
| Task Listen | ❌ |
132+
| Task Raise | ✅ |
133+
| Task Run | ❌ |
134+
| Task Set | ✅ |
135+
| Task Switch | ❌ |
136+
| Task Try | ❌ |
137+
| Task Wait | ❌ |
138+
| Lifecycle Events | 🟡 |
139+
| External Resource | ❌ |
140+
| Authentication | ❌ |
141+
| Catalog | ❌ |
142+
| Extension | ❌ |
143+
| Error | ✅ |
144+
| Event Consumption Strategies | ❌ |
145+
| Retry | ❌ |
146+
| Input | ✅ |
147+
| Output | ✅ |
148+
| Export | ✅ |
149+
| Timeout | ❌ |
150+
| Duration | ❌ |
151+
| Endpoint | ✅ |
152+
| HTTP Response | ❌ |
153+
| HTTP Request | ❌ |
154+
| URI Template | ✅ |
155+
| Container Lifetime | ❌ |
156+
| Process Result | ❌ |
157+
| AsyncAPI Server | ❌ |
158+
| AsyncAPI Outbound Message | ❌ |
159+
| AsyncAPI Subscription | ❌ |
160+
| Workflow Definition Reference | ❌ |
161+
| Subscription Iterator | ❌ |
162+
163+
We love contributions! Our aim is to have a complete implementation to serve as a reference or to become a project on its own to favor the CNCF Ecosystem.
164+
165+
If you are willing to help, please [file a sub-task](https://github.com/serverlessworkflow/sdk-go/issues/221) in this EPIC describing what you are planning to work on first.
122166

123167
---
124168

125169
## Slack Community
126170

127-
Join the conversation and connect with other contributors on the [CNCF Slack](https://communityinviter.com/apps/cloud-native/cncf). Find us in the `#serverless-workflow-sdk` channel and say hello! 🙋
171+
Join our community on the CNCF Slack to collaborate, ask questions, and contribute:
172+
173+
[CNCF Slack Invite](https://communityinviter.com/apps/cloud-native/cncf)
174+
175+
Find us in the `#serverless-workflow-sdk` channel.
128176

129177
---
130178

131179
## Contributing
132180

133-
We welcome contributions to improve this SDK. Please refer to the sections below for guidance on maintaining project standards.
181+
Your contributions are very welcome!
134182

135183
### Code Style
136184

137-
- Use `goimports` for import organization.
138-
- Lint your code with:
185+
- Format imports with `goimports`.
186+
- Run static analysis using:
139187

140-
```bash
188+
```shell
141189
make lint
142190
```
143191

144-
To automatically fix lint issues, use:
192+
Automatically fix lint issues:
145193

146-
```bash
194+
```shell
147195
make lint params=--fix
148196
```
149197

150-
Example lint error:
151-
152-
```bash
153-
$ make lint
154-
make addheaders
155-
make fmt
156-
./hack/go-lint.sh
157-
util/floatstr/floatstr_test.go:19: File is not `goimports`-ed (goimports)
158-
"k8s.io/apimachinery/pkg/util/yaml"
159-
make: *** [lint] Error 1
160-
```
161-
162198
### EditorConfig
163199

164-
For IntelliJ users, an example `.editorconfig` file is available [here](contrib/intellij.editorconfig). See the [Jetbrains documentation](https://www.jetbrains.com/help/idea/editorconfig.html) for usage details.
200+
A sample `.editorconfig` for IntelliJ or GoLand users can be found [here](contrib/intellij.editorconfig).
165201

166202
### Known Issues
167203

168-
#### MacOS Issue:
169-
170-
On MacOS, you might encounter the following error:
204+
- **MacOS Issue**: If you encounter `goimports: can't extract issues from gofmt diff output`, resolve it with:
171205

172-
```
173-
goimports: can't extract issues from gofmt diff output
206+
```shell
207+
brew install diffutils
174208
```
175209

176-
To resolve this, install `diffutils`:
210+
---
177211

178-
```bash
179-
brew install diffutils
180-
```
212+
Contributions are greatly appreciated! Check [this EPIC](https://github.com/serverlessworkflow/sdk-go/issues/221) and contribute to completing more features.
181213

214+
Happy coding!

‎builder/builder_test.go

+3-3
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ import (
1818
"errors"
1919
"testing"
2020

21-
"github.com/go-playground/validator/v10"
21+
validator "github.com/go-playground/validator/v10"
2222
"github.com/serverlessworkflow/sdk-go/v3/model"
2323
"github.com/serverlessworkflow/sdk-go/v3/test"
2424

@@ -137,7 +137,7 @@ func TestBuilder_Validate(t *testing.T) {
137137
Version: "1.0.0",
138138
},
139139
Do: &model.TaskList{
140-
{
140+
&model.TaskItem{
141141
Key: "task1",
142142
Task: &model.CallHTTP{
143143
Call: "http",
@@ -155,7 +155,7 @@ func TestBuilder_Validate(t *testing.T) {
155155

156156
// Test validation failure
157157
workflow.Do = &model.TaskList{
158-
{
158+
&model.TaskItem{
159159
Key: "task2",
160160
Task: &model.CallHTTP{
161161
Call: "http",

0 commit comments

Comments
 (0)