sdk-go

README

Go SDK for Serverless Workflow

The Go SDK for Serverless Workflow provides strongly-typed structures for the Serverless Workflow specification. 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.

---

Table of Contents

• Status
• Releases
• Getting Started
  • Installation
  • Basic Usage
  • Parsing Workflow Files
  • Programmatic Workflow Creation
• Reference Implementation
  • Example: Running a Workflow
• Slack Community
• Contributing
  • Code Style
  • EditorConfig
  • Known Issues

---

Status

This table indicates the current state of implementation of various SDK features:

Feature	Status
Parse workflow JSON and YAML definitions	✔
Programmatically build workflow definitions	✔
Validate workflow definitions (Schema)	✔
Specification Implementation	✔*
Validate workflow definitions (Integrity)	🚫
Generate workflow diagram (SVG)	🚫

Note: *Implementation is partial; contributions are encouraged.

---

Releases

Latest Releases	Conformance to Spec Version
v1.0.0	v0.5
v2.0.1	v0.6
v2.1.2	v0.7
v2.5.0	v0.8
v3.1.0	v1.0.0

---

Reference Implementation

The SDK provides a partial reference runner to execute your workflows:

Example: Running a Workflow

Below is a simple YAML workflow that sets a message and then prints it:

document:
  dsl: "1.0.0"
  namespace: "examples"
  name: "simple-workflow"
  version: "1.0.0"
do:
  - set:
      message: "Hello from the Serverless Workflow SDK in Go!"

You can execute this workflow using the following Go program:

Example of executing a workflow defined in YAML:

package main

import (
    "fmt"
    "os"
    "path/filepath"

    "github.com/serverlessworkflow/sdk-go/v3/impl"
    "github.com/serverlessworkflow/sdk-go/v3/parser"
)

func RunWorkflow(workflowFilePath string, input map[string]interface{}) (interface{}, error) {
    data, err := os.ReadFile(filepath.Clean(workflowFilePath))
    if err != nil {
        return nil, err
    }
    workflow, err := parser.FromYAMLSource(data)
    if err != nil {
        return nil, err
    }

    runner := impl.NewDefaultRunner(workflow)
    output, err := runner.Run(input)
    if err != nil {
        return nil, err
    }
    return output, nil
}

func main() {
    output, err := RunWorkflow("./myworkflow.yaml", map[string]interface{}{"shouldCall": true})
    if err != nil {
        panic(err)
    }
    fmt.Printf("Workflow completed with output: %v\n", output)
}

Implementation Roadmap

The table below lists the current state of this implementation. This table is a roadmap for the project based on the DSL Reference doc.

Feature	State
Workflow Document	✅
Workflow Use	🟡
Workflow Schedule	❌
Task Call	❌
Task Do	✅
Task Emit	❌
Task For	✅
Task Fork	✅
Task Listen	❌
Task Raise	✅
Task Run	❌
Task Set	✅
Task Switch	✅
Task Try	❌
Task Wait	❌
Lifecycle Events	🟡
External Resource	❌
Authentication	❌
Catalog	❌
Extension	❌
Error	✅
Event Consumption Strategies	❌
Retry	❌
Input	✅
Output	✅
Export	✅
Timeout	❌
Duration	❌
Endpoint	✅
HTTP Response	❌
HTTP Request	❌
URI Template	✅
Container Lifetime	❌
Process Result	❌
AsyncAPI Server	❌
AsyncAPI Outbound Message	❌
AsyncAPI Subscription	❌
Workflow Definition Reference	✅
Subscription Iterator	❌

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.

If you are willing to help, please file a sub-task in this EPIC describing what you are planning to work on first.

---

Slack Community

Join our community on the CNCF Slack to collaborate, ask questions, and contribute:

CNCF Slack Invite

Find us in the #serverless-workflow-sdk channel.

---

Contributing

Your contributions are very welcome!

Code Style

• Format imports with goimports.
• Run static analysis using:

make lint

Automatically fix lint issues:

make lint params=--fix

EditorConfig

A sample .editorconfig for IntelliJ or GoLand users can be found here.

Known Issues

• MacOS Issue: If you encounter goimports: can't extract issues from gofmt diff output, resolve it with:

brew install diffutils

---

Contributions are greatly appreciated! Check this EPIC and contribute to completing more features.

Happy coding!