Skip to content

Commit 86c62a9

Browse files
ricardozaniniricardozanini
committed
Add implementation docs
Signed-off-by: Ricardo Zanini <[email protected]>
1 parent e813705 commit 86c62a9

File tree

1 file changed

+122
-101
lines changed

1 file changed

+122
-101
lines changed

‎README.md

Lines changed: 122 additions & 101 deletions
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,178 @@ 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: |
3438

35-
---
36-
37-
## Releases
38-
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) |
39+
> **Note**: *Implementation is partial; contributions are encouraged.
4640
4741
---
4842

49-
## Getting Started
50-
51-
### Installation
43+
## Reference Implementation
5244

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-
```
45+
The SDK provides a partial reference runner to execute your workflows:
5846

59-
This will update your `go.mod` file to include the Serverless Workflow SDK as a dependency.
47+
### Example: Running a Workflow
6048

61-
Import the SDK in your Go file:
49+
Below is a simple YAML workflow that sets a message and then prints it:
6250

63-
```go
64-
import "github.com/serverlessworkflow/sdk-go/v3/model"
51+
```yaml
52+
document:
53+
dsl: "1.0.0"
54+
namespace: "examples"
55+
name: "simple-workflow"
56+
version: "1.0.0"
57+
do:
58+
- set:
59+
message: "Hello from the Serverless Workflow SDK in Go!"
6560
```
6661
67-
You can now use the SDK types and functions, for example:
68-
69-
```go
70-
package main
62+
You can execute this workflow using the following Go program:
7163
72-
import (
73-
"github.com/serverlessworkflow/sdk-go/v3/builder"
74-
"github.com/serverlessworkflow/sdk-go/v3/model"
75-
)
76-
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-
}
93-
94-
```
95-
96-
### Parsing Workflow Files
97-
98-
The Serverless Workflow Specification supports YAML and JSON files. Use the following example to parse a workflow file into a Go data structure:
64+
Example of executing a workflow defined in YAML:
9965
10066
```go
10167
package main
10268

10369
import (
104-
"github.com/serverlessworkflow/sdk-go/v3/model"
70+
"fmt"
71+
"os"
72+
"path/filepath"
73+
74+
"github.com/serverlessworkflow/sdk-go/v3/impl"
10575
"github.com/serverlessworkflow/sdk-go/v3/parser"
10676
)
10777

108-
func ParseWorkflow(filePath string) (*model.Workflow, error) {
109-
workflow, err := parser.FromFile(filePath)
78+
func RunWorkflow(workflowFilePath string, input map[string]interface{}) (interface{}, error) {
79+
data, err := os.ReadFile(filepath.Clean(workflowFilePath))
80+
if err != nil {
81+
return nil, err
82+
}
83+
workflow, err := parser.FromYAMLSource(data)
11084
if err != nil {
11185
return nil, err
11286
}
113-
return workflow, nil
114-
}
115-
```
11687

117-
This `Workflow` structure can then be used programmatically in your application.
88+
runner := impl.NewDefaultRunner(workflow)
89+
output, err := runner.Run(input)
90+
if err != nil {
91+
return nil, err
92+
}
93+
return output, nil
94+
}
11895

119-
### Programmatic Workflow Creation
96+
func main() {
97+
output, err := RunWorkflow("./myworkflow.yaml", map[string]interface{}{"shouldCall": true})
98+
if err != nil {
99+
panic(err)
100+
}
101+
fmt.Printf("Workflow completed with output: %v\n", output)
102+
}
103+
```
120104

121-
Support for building workflows programmatically is planned for future releases. Stay tuned for updates in upcoming versions.
105+
### Implementation Roadmap
106+
107+
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).
108+
109+
| Feature | State |
110+
| ----------- | --------------- |
111+
| Workflow Document | ✅ |
112+
| Workflow Use | 🟡 |
113+
| Workflow Schedule | ❌ |
114+
| Task Call | ❌ |
115+
| Task Do | ✅ |
116+
| Task Emit | ❌ |
117+
| Task For | ❌ |
118+
| Task Fork | ❌ |
119+
| Task Listen | ❌ |
120+
| Task Raise | ✅ |
121+
| Task Run | ❌ |
122+
| Task Set | ✅ |
123+
| Task Switch | ❌ |
124+
| Task Try | ❌ |
125+
| Task Wait | ❌ |
126+
| Lifecycle Events | 🟡 |
127+
| External Resource | ❌ |
128+
| Authentication | ❌ |
129+
| Catalog | ❌ |
130+
| Extension | ❌ |
131+
| Error | ✅ |
132+
| Event Consumption Strategies | ❌ |
133+
| Retry | ❌ |
134+
| Input | ✅ |
135+
| Output | ✅ |
136+
| Export | ✅ |
137+
| Timeout | ❌ |
138+
| Duration | ❌ |
139+
| Endpoint | ✅ |
140+
| HTTP Response | ❌ |
141+
| HTTP Request | ❌ |
142+
| URI Template | ✅ |
143+
| Container Lifetime | ❌ |
144+
| Process Result | ❌ |
145+
| AsyncAPI Server | ❌ |
146+
| AsyncAPI Outbound Message | ❌ |
147+
| AsyncAPI Subscription | ❌ |
148+
| Workflow Definition Reference | ❌ |
149+
| Subscription Iterator | ❌ |
150+
151+
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.
152+
153+
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.
122154

123155
---
124156

125157
## Slack Community
126158

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! 🙋
159+
Join our community on the CNCF Slack to collaborate, ask questions, and contribute:
160+
161+
[CNCF Slack Invite](https://communityinviter.com/apps/cloud-native/cncf)
162+
163+
Find us in the `#serverless-workflow-sdk` channel.
128164

129165
---
130166

131167
## Contributing
132168

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

135171
### Code Style
136172

137-
- Use `goimports` for import organization.
138-
- Lint your code with:
173+
- Format imports with `goimports`.
174+
- Run static analysis using:
139175

140-
```bash
176+
```shell
141177
make lint
142178
```
143179

144-
To automatically fix lint issues, use:
180+
Automatically fix lint issues:
145181

146-
```bash
182+
```shell
147183
make lint params=--fix
148184
```
149185

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-
162186
### EditorConfig
163187

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.
188+
A sample `.editorconfig` for IntelliJ or GoLand users can be found [here](contrib/intellij.editorconfig).
165189

166190
### Known Issues
167191

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

172-
```
173-
goimports: can't extract issues from gofmt diff output
194+
```shell
195+
brew install diffutils
174196
```
175197

176-
To resolve this, install `diffutils`:
198+
---
177199

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

202+
Happy coding!

0 commit comments

Comments
 (0)