hatchet

package
v0.73.18 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 23, 2025 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Define workflows that can declare tasks and be run, scheduled, and so on. Transform functions into Hatchet tasks using a clean, reflection-based API.

Basic Usage 

client, err := hatchet.NewClient()
if err != nil {
	log.Fatal(err)
}

workflow := client.NewWorkflow("my-workflow",
	hatchet.WithWorkflowConcurrency(types.Concurrency{
		Expression: "input.userId",
		MaxRuns:    5,
	}))
fmt.Printf("Workflow name: %s\n", workflow.Name()) // Includes namespace if set

task1 := workflow.NewTask("task-1", MyTaskFunction)
task2 := workflow.NewTask("task-2", MyOtherTaskFunction,
	hatchet.WithParents(task1))

worker, err := client.NewWorker("worker-name", hatchet.WithWorkflows(workflow))
if err != nil {
	log.Fatal(err)
}

err = worker.StartBlocking(ctx)

Examples

For comprehensive examples demonstrating various Hatchet features, see:

View all examples: https://github.com/hatchet-dev/hatchet/tree/main/sdks/go/examples

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AndCondition 

func AndCondition(conditions ...condition.Condition) condition.Condition

AndCondition creates a condition that is satisfied when all of the provided conditions are met.

func OrCondition 

func OrCondition(conditions ...condition.Condition) condition.Condition

OrCondition creates a condition that is satisfied when any of the provided conditions are met.

func ParentCondition 

func ParentCondition(task *Task, expression string) condition.Condition

ParentCondition creates a condition based on a parent task's output.

func SleepCondition 

func SleepCondition(duration time.Duration) condition.Condition

SleepCondition creates a condition that waits for a specified duration.

func UserEventCondition 

func UserEventCondition(eventKey, expression string) condition.Condition

UserEventCondition creates a condition that waits for a user event.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client provides the main interface for interacting with Hatchet.

func NewClient 

func NewClient(opts ...v0Client.ClientOpt) (*Client, error)

NewClient creates a new Hatchet client. Configuration options can be provided to customize the client behavior.

func (*Client) CEL 

func (c *Client) CEL() *features.CELClient

CEL returns a client for working with CEL expressions.

func (*Client) Crons 

func (c *Client) Crons() *features.CronsClient

Crons returns a client for managing cron triggers.

func (*Client) Events 

func (c *Client) Events() v0Client.EventClient

Events returns a client for sending and managing events.

func (*Client) Filters 

func (c *Client) Filters() *features.FiltersClient

Filters returns a client for managing event filters.

func (*Client) Metrics 

func (c *Client) Metrics() *features.MetricsClient

Metrics returns a feature client for interacting with workflow and task metrics.

func (*Client) NewStandaloneDurableTask added in v0.71.11 

func (c *Client) NewStandaloneDurableTask(name string, fn any, options ...StandaloneTaskOption) *StandaloneTask

NewStandaloneDurableTask creates a standalone durable task that can be triggered independently. This is a specialized workflow containing only one durable task, making it easier to create simple single-task workflows with durable functionality.

The function parameter must have the signature: 

func(ctx hatchet.DurableContext, input any) (any, error)

Function signatures are validated at runtime using reflection.

Options can be any combination of WorkflowOption and TaskOption.

func (*Client) NewStandaloneTask added in v0.71.11 

func (c *Client) NewStandaloneTask(name string, fn any, options ...StandaloneTaskOption) *StandaloneTask

NewStandaloneTask creates a standalone task that can be triggered independently. This is a specialized workflow containing only one task, making it easier to create simple single-task workflows without the workflow boilerplate.

The function parameter must have the signature: 

func(ctx hatchet.Context, input any) (any, error)

Function signatures are validated at runtime using reflection.

Options can be any combination of WorkflowOption and TaskOption.

func (*Client) NewWorker 

func (c *Client) NewWorker(name string, options ...WorkerOption) (*Worker, error)

NewWorker creates a worker that can execute workflows.

func (*Client) NewWorkflow 

func (c *Client) NewWorkflow(name string, options ...WorkflowOption) *Workflow

NewWorkflow creates a new workflow definition. Workflows can be configured with triggers, events, and other options.

func (*Client) RateLimits 

func (c *Client) RateLimits() *features.RateLimitsClient

RateLimits returns a client for managing rate limits.

func (*Client) Run 

func (c *Client) Run(ctx context.Context, workflowName string, input any, opts ...RunOptFunc) (*WorkflowResult, error)

Run executes a workflow with the provided input and waits for completion.

func (*Client) RunMany 

func (c *Client) RunMany(ctx context.Context, workflowName string, inputs []RunManyOpt) ([]WorkflowRunRef, error)

RunMany executes multiple workflow instances with different inputs. Returns workflow run IDs that can be used to track the run statuses.

func (*Client) RunNoWait 

func (c *Client) RunNoWait(ctx context.Context, workflowName string, input any, opts ...RunOptFunc) (*WorkflowRunRef, error)

RunNoWait executes a workflow with the provided input without waiting for completion. Returns a workflow run reference that can be used to track the run status.

func (*Client) Runs 

func (c *Client) Runs() *features.RunsClient

Runs returns a client for managing workflow runs.

func (*Client) Schedules 

func (c *Client) Schedules() *features.SchedulesClient

Schedules returns a client for managing scheduled workflow runs.

func (*Client) Workers 

func (c *Client) Workers() *features.WorkersClient

Workers returns a client for managing workers.

func (*Client) Workflows 

func (c *Client) Workflows() *features.WorkflowsClient

Workflows returns a client for managing workflow definitions.

type Context 

type Context = pkgWorker.HatchetContext

Context represents the execution context passed to task functions. It provides access to workflow metadata, retry information, and other execution details.

type DurableContext 

type DurableContext = pkgWorker.DurableHatchetContext

DurableContext represents the execution context for durable tasks. It extends Context with additional methods for durable operations like SleepFor.

type RunManyOpt 

type RunManyOpt struct {
	Input any
	Opts  []RunOptFunc
}

RunManyOpt is a type that represents the options for running multiple instances of a workflow with different inputs and options.

type RunOptFunc 

type RunOptFunc func(*runOpts)

func WithRunKey added in v0.73.15 

func WithRunKey(key string) RunOptFunc

WithRunKey sets the key for the child workflow run.

func WithRunMetadata 

func WithRunMetadata(metadata map[string]interface{}) RunOptFunc

WithRunMetadata sets the additional metadata for the workflow run.

func WithRunPriority added in v0.72.2 

func WithRunPriority(priority RunPriority) RunOptFunc

WithRunPriority sets the priority for the workflow run.

func WithRunSticky added in v0.73.15 

func WithRunSticky(sticky bool) RunOptFunc

WithRunSticky enables stickiness for the child workflow run.

type RunPriority added in v0.71.2 

type RunPriority = features.RunPriority

type StandaloneTask added in v0.71.11 

type StandaloneTask struct {
	// contains filtered or unexported fields
}

StandaloneTask represents a single task that runs independently without a workflow wrapper. It's essentially a specialized workflow containing only one task.

func (*StandaloneTask) Dump added in v0.71.11 

func (st *StandaloneTask) Dump() (*contracts.CreateWorkflowVersionRequest, []internal.NamedFunction, []internal.NamedFunction, internal.WrappedTaskFn)

Dump implements the WorkflowBase interface for internal use, delegating to the underlying workflow.

func (*StandaloneTask) GetName added in v0.71.11 

func (st *StandaloneTask) GetName() string

GetName returns the name of the standalone task.

func (*StandaloneTask) Run added in v0.71.11 

func (st *StandaloneTask) Run(ctx context.Context, input any, opts ...RunOptFunc) (*TaskResult, error)

Run executes the standalone task with the provided input and waits for completion.

func (*StandaloneTask) RunMany added in v0.73.15 

func (st *StandaloneTask) RunMany(ctx context.Context, inputs []RunManyOpt) ([]WorkflowRunRef, error)

RunMany executes multiple standalone task instances with different inputs. Returns workflow run IDs that can be used to track the run statuses.

func (*StandaloneTask) RunNoWait added in v0.71.11 

func (st *StandaloneTask) RunNoWait(ctx context.Context, input any, opts ...RunOptFunc) (*WorkflowRunRef, error)

RunNoWait executes the standalone task with the provided input without waiting for completion. Returns a workflow run reference that can be used to track the run status.

type StandaloneTaskOption added in v0.71.11 

type StandaloneTaskOption any

StandaloneTaskOption represents options that can be applied to standalone tasks. This interface allows both WorkflowOption and TaskOption to be used interchangeably.

type Task 

type Task struct {
	// contains filtered or unexported fields
}

Task represents a task reference for building DAGs and conditions.

func (*Task) GetName 

func (t *Task) GetName() string

Name returns the name of the task.

type TaskOption 

type TaskOption func(*taskConfig)

TaskOption configures a task instance.

func WithConcurrency 

func WithConcurrency(concurrency ...*types.Concurrency) TaskOption

WithConcurrency sets concurrency limits for task execution.

func WithCron 

func WithCron(cronExpressions ...string) TaskOption

WithCron configures standalone tasks to run on a cron schedule. Only applicable to standalone tasks, not workflow tasks.

func WithDescription added in v0.71.11 

func WithDescription(description string) TaskOption

WithDescription sets a human-readable description for the task.

func WithEvents 

func WithEvents(events ...string) TaskOption

WithEvents configures standalone tasks to trigger on specific events. Only applicable to standalone tasks, not workflow tasks.

func WithExecutionTimeout added in v0.71.5 

func WithExecutionTimeout(timeout time.Duration) TaskOption

WithExecutionTimeout sets the maximum execution duration for a task.

func WithFilters 

func WithFilters(filters ...types.DefaultFilter) TaskOption

WithFilters sets default filters for event-triggered tasks.

func WithParents 

func WithParents(parents ...*Task) TaskOption

WithParents sets parent task dependencies.

func WithRateLimits 

func WithRateLimits(rateLimits ...*types.RateLimit) TaskOption

WithRateLimits sets rate limiting for task execution.

func WithRetries 

func WithRetries(retries int) TaskOption

WithRetries sets the number of retry attempts for failed tasks.

func WithRetryBackoff 

func WithRetryBackoff(factor float32, maxBackoffSeconds int) TaskOption

WithRetryBackoff configures exponential backoff for task retries.

func WithScheduleTimeout added in v0.71.5 

func WithScheduleTimeout(timeout time.Duration) TaskOption

WithScheduleTimeout sets the maximum time a task can wait to be scheduled.

func WithSkipIf 

func WithSkipIf(condition condition.Condition) TaskOption

WithSkipIf sets a condition that will skip the task if met.

func WithWaitFor 

func WithWaitFor(condition condition.Condition) TaskOption

WithWaitFor sets a condition that must be met before the task executes.

type TaskResult added in v0.71.11 

type TaskResult struct {
	// contains filtered or unexported fields
}

TaskResult wraps a single task's output and provides type-safe conversion methods.

func (*TaskResult) Into added in v0.71.11 

func (tr *TaskResult) Into(dest any) error

Into converts the task result into the provided destination using JSON marshal/unmarshal. The destination should be a pointer to the desired type.

Example usage: 

var output MyOutputType
err := taskResult.Into(&output)

type Worker 

type Worker struct {
	// contains filtered or unexported fields
}

Worker represents a worker that can execute workflows.

func (*Worker) Start 

func (w *Worker) Start() (func() error, error)

Starts the worker instance and returns a cleanup function.

func (*Worker) StartBlocking 

func (w *Worker) StartBlocking(ctx context.Context) error

StartBlocking starts the worker and blocks until it completes. This is a convenience method for common usage patterns.

type WorkerOption 

type WorkerOption func(*workerConfig)

WorkerOption configures a worker instance.

func WithDurableSlots 

func WithDurableSlots(durableSlots int) WorkerOption

WithDurableSlots sets the maximum number of concurrent durable task runs.

func WithLabels 

func WithLabels(labels map[string]any) WorkerOption

WithLabels assigns labels to the worker for task routing.

func WithLogger 

func WithLogger(logger *zerolog.Logger) WorkerOption

WithLogger sets a custom logger for the worker.

func WithPanicHandler added in v0.73.2 

func WithPanicHandler(panicHandler func(ctx Context, recovered any)) WorkerOption

WithPanicHandler sets a custom panic handler for the worker.

recovered is the non-nil value that was obtained after calling recover()

func WithSlots 

func WithSlots(slots int) WorkerOption

WithSlots sets the maximum number of concurrent workflow runs.

func WithWorkflows 

func WithWorkflows(workflows ...internal.WorkflowBase) WorkerOption

WithWorkflows registers workflows and standalone tasks with the worker. Both workflows and standalone tasks implement the WorkflowBase interface.

type Workflow 

type Workflow struct {
	// contains filtered or unexported fields
}

Workflow defines a Hatchet workflow, which can then declare tasks and be run, scheduled, and so on.

func (*Workflow) Dump 

func (w *Workflow) Dump() (*contracts.CreateWorkflowVersionRequest, []internal.NamedFunction, []internal.NamedFunction, internal.WrappedTaskFn)

Dump implements the WorkflowBase interface for internal use.

func (*Workflow) GetName 

func (w *Workflow) GetName() string

GetName returns the resolved workflow name (including namespace if applicable).

func (*Workflow) NewDurableTask 

func (w *Workflow) NewDurableTask(name string, fn any, options ...TaskOption) *Task

NewDurableTask transforms a function into a durable Hatchet task that runs as part of a workflow.

The function parameter must have the signature: 

func(ctx hatchet.DurableContext, input any) (any, error)

Function signatures are validated at runtime using reflection.

func (*Workflow) NewTask 

func (w *Workflow) NewTask(name string, fn any, options ...TaskOption) *Task

NewTask transforms a function into a Hatchet task that runs as part of a workflow.

The function parameter must have the signature: 

func(ctx hatchet.Context, input any) (any, error)

Function signatures are validated at runtime using reflection.

func (*Workflow) OnFailure 

func (w *Workflow) OnFailure(fn any) *Workflow

OnFailure sets a failure handler for the workflow. The handler will be called when any task in the workflow fails.

func (*Workflow) Run 

func (w *Workflow) Run(ctx context.Context, input any, opts ...RunOptFunc) (*WorkflowResult, error)

Run executes the workflow with the provided input and waits for completion.

func (*Workflow) RunMany added in v0.73.15 

func (w *Workflow) RunMany(ctx context.Context, inputs []RunManyOpt) ([]WorkflowRunRef, error)

RunMany executes multiple workflow instances with different inputs.

func (*Workflow) RunNoWait 

func (w *Workflow) RunNoWait(ctx context.Context, input any, opts ...RunOptFunc) (*WorkflowRunRef, error)

RunNoWait executes the workflow with the provided input without waiting for completion. Returns a workflow run reference that can be used to track the run status.

type WorkflowOption 

type WorkflowOption func(*workflowConfig)

WorkflowOption configures a workflow instance.

func WithWorkflowConcurrency 

func WithWorkflowConcurrency(concurrency ...types.Concurrency) WorkflowOption

WithWorkflowConcurrency sets concurrency controls for the workflow.

func WithWorkflowCron 

func WithWorkflowCron(cronExpressions ...string) WorkflowOption

WithWorkflowCron configures the workflow to run on a cron schedule. Multiple cron expressions can be provided.

func WithWorkflowDefaultPriority added in v0.73.15 

func WithWorkflowDefaultPriority(priority RunPriority) WorkflowOption

WithWorkflowDefaultPriority sets the default priority for the workflow.

func WithWorkflowDescription 

func WithWorkflowDescription(description string) WorkflowOption

WithWorkflowDescription sets a human-readable description for the workflow.

func WithWorkflowEvents 

func WithWorkflowEvents(events ...string) WorkflowOption

WithWorkflowEvents configures the workflow to trigger on specific events.

func WithWorkflowStickyStrategy added in v0.73.15 

func WithWorkflowStickyStrategy(stickyStrategy types.StickyStrategy) WorkflowOption

WithWorkflowStickyStrategy sets the sticky strategy for the workflow.

func WithWorkflowTaskDefaults added in v0.71.5 

func WithWorkflowTaskDefaults(defaults *create.TaskDefaults) WorkflowOption

WithWorkflowTaskDefaults sets the default configuration for all tasks in the workflow.

func WithWorkflowVersion 

func WithWorkflowVersion(version string) WorkflowOption

WithWorkflowVersion sets the version identifier for the workflow.

type WorkflowResult added in v0.71.11 

type WorkflowResult struct {
	// contains filtered or unexported fields
}

WorkflowResult wraps workflow execution results and provides type-safe conversion methods.

func (*WorkflowResult) Raw added in v0.71.11 

func (wr *WorkflowResult) Raw() any

Raw returns the raw workflow result as interface{}.

func (*WorkflowResult) TaskOutput added in v0.71.11 

func (wr *WorkflowResult) TaskOutput(taskName string) *TaskResult

TaskOutput extracts the output of a specific task from the workflow result. Returns a TaskResult that can be used to convert the task output into the desired type.

Example usage: 

taskResult := workflowResult.TaskOutput("myTask")
var output MyOutputType
err := taskResult.Into(&output)

type WorkflowRunRef added in v0.73.15 

type WorkflowRunRef struct {
	RunId string
	// contains filtered or unexported fields
}

WorkflowRunRef is a type that represents a reference to a workflow run.

func (*WorkflowRunRef) Result added in v0.73.15 

func (wr *WorkflowRunRef) Result() (*WorkflowResult, error)

V0Workflow returns the underlying v0Client.Workflow.

Source Files

View all Source files

Directories

Path Synopsis
examples
bulk-operations command
cancellations command
child-workflows command
concurrency command
conditions command
cron command
dag command
durable/event command
durable/sleep command
events command
migration-guides
on-event command
on-failure command
panic-handler command
priority command
rate-limiting command
retries command
retries-concurrency command
scheduled
sdk-migration command
setup command
simple command
sticky-workers
streaming/consumer command
streaming/server command
streaming/shared
streaming/worker command
stubs command
timeouts command
package features provides functionality for interacting with hatchet features.
 package features provides functionality for interacting with hatchet features.
Package internal provides internal functionality for the Hatchet Go SDK
 Package internal provides internal functionality for the Hatchet Go SDK
task

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.