Upstash Workflow Go Client

Note

This project is in GA Stage.

The Upstash Professional Support fully covers this project. It receives regular updates, and bug fixes. The Upstash team is committed to maintaining and improving its functionality.

Upstash Workflow lets you write durable, reliable and performant serverless functions. Get delivery guarantees, automatic retries on failure, scheduling and more without managing any infrastructure.

This is the HTTP-based Go client for Upstash Workflow.

Note that this SDK only offers client-side workflow functions for managing workflows; it does not include server-side functionality for writing workflows in Golang.

Documentation

• Reference Documentation
• Quickstart
• API Reference

Installation

Use go get to install the Upstash Workflow package:

go get github.com/upstash/workflow-go

Import the Upstash Workflow package in your project:

import "github.com/upstash/workflow-go"

Usage

The QSTASH_TOKEN is required to initialize an Upstash Workflow client. Find your credentials in the console dashboard at Upstash Console.

import (
	"github.com/upstash/workflow-go"
)

func main() {
	client, err := workflow.NewClient("<QSTASH_TOKEN>")
}

Alternatively, you can set the following environment variables:

QSTASH_URL="<QSTASH_URL>"
QSTASH_TOKEN="<QSTASH_TOKEN>"

and then create the client by using:

import (
	"github.com/upstash/workflow-go"
)

func main() {
	client, err := workflow.NewClientWithEnv()
}

Using a custom HTTP client

By default, http.DefaultClient will be used for doing requests. It is possible to use a custom HTTP client by passing it in the options while constructing the client.

import (
	"net/http"

	"github.com/upstash/workflow-go"
)

func main() {
	client, err := workflow.NewClientWith(workflow.Options{
        Token:  "<QSTASH_TOKEN>",
        Client: &http.Client{},
    })
}

Trigger a workflow run

Start a new workflow run with provided options.

runID, err := client.Trigger(workflow.TriggerOptions{
    Url: "https://your-workflow-endpoint.com/api/process"
    Body: []byte("request payload"),
})
if err != nil {
    // handle err
}

Notify Events

Send a notify message to workflows waiting for a specific event.

messages, err := client.Notify("event-id", []byte("notify data"))
if err != nil {
    // handle err
}

Cancel Workflows

Cancel one or more ongoing workflow runs.

err := client.Cancel("workflow-run-id")
if err != nil {
    // handle err
}

canceled, err := client.CancelMany([]string{"run-a", "run-b", "run-c"})
if err != nil {
    // handle err
}

canceled, err = client.CancelAll()
if err != nil {
    // handle err
}

Fetch waiters

Get the list of workflows waiting on a specific event.

waiters, err := client.Waiters("my-event-id")
if err != nil {
    // handle err
}

Fetch Logs

Get the logs for workflow runs with filtering.

runs, cursor, err := client.Logs(workflow.LogsOptions{})
if err != nil {
    // handle err
}

runs, cursor, err = client.Logs(workflow.LogsOptions{
    Filter: workflow.LogFilter{
        RunId: "workflow-run-id",
    },
})
if err != nil {
	// handle err
}

runs, cursor, err = client.Logs(workflow.LogsOptions{
    Filter: workflow.LogFilter{
        State: "RUN_SUCCESS",
    },
})
if err != nil {
	// handle err
}