Workflows

Workflows are a sequence of steps that gets executed durably. A workflow can be seen as a special type of Virtual Object with the following characteristics:

Each workflow definition has a Run handler that implements the workflow logic.
- The Run handler executes exactly one time for each workflow instance (object / key).
- The Run handler executes a set of durable steps/activities. These can either be:
  - Inline activities: for example a run block or sleep
  - Calls to other handlers implementing the activities
You can submit a workflow in the same way as any handler invocation (via SDK clients or Restate services, over HTTP or Kafka).
A workflow definition can implement other handlers that can be called multiple times, and can interact with the workflow:
- Query the workflow (get information out of it) by getting K/V state or awaiting promises that are resolved by the workflow.
- Signal the workflow (send information to it) by resolving promises that the workflow waits on.
Workflows have access to the WorkflowContext and WorkflowSharedContext, giving them some extra functionality, for example Durable Promises to signal workflows.
The K/V state of the workflow is isolated to the workflow execution, and can only be mutated by the Run handler.

Workflow retention time

The retention time of a workflow execution is 24 hours after the finishing of the Run handler. After this timeout any K/V state is cleared, the workflow's shared handlers cannot be called anymore, and the Durable Promises are discarded. The retention time can be configured via the Admin API per Workflow definition by setting workflow_completion_retention.

Implementing workflows

Have a look at the code example to get a better understanding of how workflows are implemented:

The run handler

Every workflow needs a Run handler. This handler has access to the same SDK features as Service and Virtual Object handlers. For example, use restate.Run to log intermediate results in Restate and avoid re-execution on replay. Or call other handlers to execute activities.

The run handler

Querying workflows

Similar to Virtual Objects, you can retrieve the K/V state of workflows via the other handlers defined in the workflow definition, For example, here we expose the status of the workflow to external clients. Every workflow execution can be seen as a new object, so the state is isolated to a single workflow execution. The state can only be mutated by the Run handler of the workflow. The other handlers can only read the state.

Querying workflows

Signaling workflows

You can use Durable Promises to interact with your running workflows: to let the workflow block until an event occurs, or to send a signal / information into or out of a running workflow. These promises are durable and distributed, meaning they survive crashes and can be resolved or rejected by any handler in the workflow.

Do the following:

Create a promise that is durable and distributed in the Run handler.
Resolve or reject the promise in another handler in the workflow. This can be done at most one time.

You can also use this pattern in reverse and let the Run handler resolve promises that other handlers are waiting on. For example, the Run handler could resolve a promise when it finishes a step of the workflow, so that other handlers can request whether this step has been completed.

Signaling workflows

Do the following:

Create a promise that is durable and distributed in the Run handler.
Resolve or reject the promise in another handler in the workflow. This can be done at most one time.

Serving and registering workflows

You serve workflows in the same way as Services and Virtual Objects: by binding them to an HTTP endpoint or AWS Lambda handler. Make sure you register the endpoint or Lambda handler in Restate before invoking it.

Serving and registering workflows

type SignupWorkflow struct{}

func (SignupWorkflow) Run(ctx restate.WorkflowContext, user User) (bool, error) {
	// workflow ID = user ID; workflow runs once per user
	userId := restate.Key(ctx)

	// Durably executed action; write to other system
	if _, err := restate.Run(ctx, func(ctx restate.RunContext) (restate.Void, error) {
		return restate.Void{}, CreateUserEntry(user)
	}); err != nil {
		return false, err
	}

	restate.Set(ctx, "status", "Created user")

	// Send the email with the verification link
	secret := restate.Rand(ctx).UUID().String()
	if _, err := restate.Run(ctx, func(ctx restate.RunContext) (restate.Void, error) {
		return restate.Void{}, SendEmailWithLink(userId, user, secret)
	}); err != nil {
		return false, err
	}

	restate.Set(ctx, "status", "Sent email")

	// Wait until user clicked email verification link
	// Promise gets resolved or rejected by the other handlers
	clickSecret, err := restate.Promise[string](ctx, "email-link").Result()
	if err != nil {
		return false, err
	}

	return clickSecret == secret, nil
}


func (SignupWorkflow) Click(ctx restate.WorkflowSharedContext, secret string) error {
	// Send data to the workflow via a durable promise
	return restate.Promise[string](ctx, "email-link").Resolve(secret)
}

func (SignupWorkflow) GetStatus(ctx restate.WorkflowSharedContext) (string, error) {
	return restate.Get[string](ctx, "status")
}


func main() {
	server := server.NewRestate().
		Bind(restate.Reflect(SignupWorkflow{}))

	if err := server.Start(context.Background(), ":9080"); err != nil {
		slog.Error("application exited unexpectedly", "err", err.Error())
		os.Exit(1)
	}
}

Workflows-as-code with Restate

Check out some examples of workflows-as-code with Restate on the use case page.

Submitting workflows programmatically over HTTP

Submit: This returns once the workflow has been registered in Restate. You can only submit once per workflow ID (here "someone"). The response tells whether Restate has accepted the workflow for execution or whether it was a duplicate submission.

const RESTATE_URL = "http://localhost:8080"
payload, err := json.Marshal(User{
	Name:  "John Doe",
	Email: "[email protected]",
})
if err != nil {
	return err
}

url := fmt.Sprintf("%s/SignupWorkflow/someone/Run/send", RESTATE_URL)
resp, err := http.Post(url, "application/json", bytes.NewBuffer(payload))
if err != nil {
	return err
}
defer resp.Body.Close()

Query/signal: Call the other handlers of the workflow in the same way as for Virtual Object handlers.

const RESTATE_URL = "http://localhost:8080"
url := fmt.Sprintf("%s/SignupWorkflow/someone/GetStatus", RESTATE_URL)
resp, err := http.Get(url)
if err != nil {
	return err
}
defer resp.Body.Close()

body, err := io.ReadAll(resp.Body)
if err != nil {
	return err
}
slog.Info("Response: " + string(body))

Attach: This lets you retrieve the result of a workflow or check if it's finished.

const RESTATE_URL = "http://localhost:8080"
attachUrl := fmt.Sprintf("%s/restate/workflow/SignupWorkflow/someone/attach", RESTATE_URL)
result, err := http.Get(attachUrl)
if err != nil {
	return err
}
defer result.Body.Close()

Submitting workflows from a Restate service

Submit/query/signal: Call the workflow handlers in the same way as for Services and Virtual Objects. This returns the result of the workflow/handler once it has finished. Use the WorkflowSend to call the handler without waiting for the result. You can only call the Run handler (submit) once per workflow ID (here "someone").

resp, err := restate.Workflow[bool](ctx, "SignupWorkflow", "someone", "Run").
	Request(User{Name: "John Doe", Email: "[email protected]"})
if err != nil {
	return err
}

workflowStatus, err := restate.Workflow[string](ctx, "SignupWorkflow", "someone", "GetStatus").
	Request(nil)
if err != nil {
	return err
}

Submitting workflows over HTTP

Submit/query/signal: Call any handler of the workflow in the same way as for Services and Virtual Objects. This returns the result of the handler once it has finished. Add /send to the path for one-way calls. You can only call the Run handler once per workflow ID (here "someone").

curl localhost:8080/SignupWorkflow/someone/Run \
    -H 'content-type: application/json' \
    -d '{"email": "[email protected]"}'

Attach/peek: This lets you retrieve the result of a workflow or check if it's finished.

curl localhost:8080/restate/workflow/SignupWorkflow/someone/attach
curl localhost:8080/restate/workflow/SignupWorkflow/someone/output

Inspecting workflows

Have a look at the introspection docs on how to inspect workflows. You can use this to for example:

Workflows

Implementing workflows​

Submitting workflows programmatically over HTTP​

Submitting workflows from a Restate service​

Submitting workflows over HTTP​

Inspecting workflows​

Implementing workflows

Submitting workflows programmatically over HTTP

Submitting workflows from a Restate service

Submitting workflows over HTTP

Inspecting workflows