# Runnables Runnables in the Hatchet Go SDK are things that can be run, namely tasks and workflows. The two main types you'll encounter are: - `Workflow`, which lets you declare tasks with `NewTask` and call the run methods - `StandaloneTask`, which is a single task returned by `client.NewStandaloneTask` (or its durable/batch variants) and supports the same run methods Both implement the `WorkflowBase` interface and can be registered on a worker with `hatchet.WithWorkflows`. See the [Client page](/reference/go/client) for the constructors. ## Workflow Workflow defines a Hatchet workflow, which can then declare tasks and be run, scheduled, and so on. Methods: Name, Description `GetName`, GetName returns the resolved workflow name (including namespace if applicable). `NewBatchTask`, NewBatchTask transforms a function into a Hatchet batch task that runs as part of a workflow. `NewDurableTask`, NewDurableTask transforms a function into a durable Hatchet task that runs as part of a workflow. `NewTask`, NewTask transforms a function into a Hatchet task that runs as part of a workflow. `OnFailure`, OnFailure sets a failure handler for the workflow. `Run`, Run executes the workflow with the provided input and waits for completion. `RunMany`, RunMany executes multiple workflow instances with different inputs. `RunNoWait`, RunNoWait executes the workflow with the provided input without waiting for completion. ### Functions #### `GetName` GetName returns the resolved workflow name (including namespace if applicable). ```go func (w *Workflow) GetName() string ``` Returns: Type `string` #### `NewBatchTask` NewBatchTask transforms a function into a Hatchet batch task that runs as part of a workflow. Batch tasks buffer concurrent runs until Hatchet flushes the batch (size reached or flush interval), then invoke the handler once with all buffered inputs keyed by each run's external id (BatchMemberId). retries is always forced to 0 for batch tasks. The function parameter must have the signature: ```go func(ctx hatchet.Context, input map[string]T) (map[string]R, error) ``` or, when batch.BroadcastOutput is true (the same result is returned to every caller): ```go func(ctx hatchet.Context, input map[string]T) (R, error) ``` Function signatures are validated at runtime using reflection. Batch tasks cannot be durable. Preview: batch tasks are in beta and may change in future releases. ```go func (w *Workflow) NewBatchTask(name string, fn any, batch BatchConfig, options ...TaskOption) *Task ``` Parameters: Name, Type `name`, `string` `fn`, `any` `batch`, `BatchConfig` `options`, `...TaskOption` Returns: Type `*Task` #### `NewDurableTask` NewDurableTask transforms a function into a durable Hatchet task that runs as part of a workflow. The function parameter must have the signature: ```go func(ctx hatchet.DurableContext, input any) (any, error) ``` Function signatures are validated at runtime using reflection. ```go func (w *Workflow) NewDurableTask(name string, fn any, options ...TaskOption) *Task ``` Parameters: Name, Type `name`, `string` `fn`, `any` `options`, `...TaskOption` Returns: Type `*Task` #### `NewTask` NewTask transforms a function into a Hatchet task that runs as part of a workflow. The function parameter must have the signature: ```go func(ctx hatchet.Context, input any) (any, error) ``` Function signatures are validated at runtime using reflection. ```go func (w *Workflow) NewTask(name string, fn any, options ...TaskOption) *Task ``` Parameters: Name, Type `name`, `string` `fn`, `any` `options`, `...TaskOption` Returns: Type `*Task` #### `OnFailure` OnFailure sets a failure handler for the workflow. The handler will be called when any task in the workflow fails. ```go func (w *Workflow) OnFailure(fn any) ``` Parameters: Name, Type `fn`, `any` #### `Run` Run executes the workflow with the provided input and waits for completion. ```go func (w *Workflow) Run(ctx context.Context, input any, opts ...RunOptFunc) (*WorkflowResult, error) ``` Parameters: Name, Type `ctx`, `context.Context` `input`, `any` `opts`, `...RunOptFunc` Returns: Type `*WorkflowResult` `error` #### `RunMany` RunMany executes multiple workflow instances with different inputs. The returned results are in the same order as the inputs. ```go func (w *Workflow) RunMany(ctx context.Context, inputs []RunManyOpt) ([]WorkflowRunRef, error) ``` Parameters: Name, Type `ctx`, `context.Context` `inputs`, `[]RunManyOpt` Returns: Type `[]WorkflowRunRef` `error` #### `RunNoWait` 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. ```go func (w *Workflow) RunNoWait(ctx context.Context, input any, opts ...RunOptFunc) (*WorkflowRunRef, error) ``` Parameters: Name, Type `ctx`, `context.Context` `input`, `any` `opts`, `...RunOptFunc` Returns: Type `*WorkflowRunRef` `error` ## StandaloneTask StandaloneTask represents a single task that runs independently without a workflow wrapper. It's essentially a specialized workflow containing only one task. Methods: Name, Description `GetName`, GetName returns the name of the standalone task. `OnFailure`, OnFailure sets a failure handler for the standalone task. `Run`, Run executes the standalone task with the provided input and waits for completion. `RunMany`, RunMany executes multiple standalone task instances with different inputs. `RunNoWait`, RunNoWait executes the standalone task with the provided input without waiting for completion. ### Functions #### `GetName` GetName returns the name of the standalone task. ```go func (st *StandaloneTask) GetName() string ``` Returns: Type `string` #### `OnFailure` OnFailure sets a failure handler for the standalone task. The handler will be called when the standalone task fails. ```go func (st *StandaloneTask) OnFailure(fn any) ``` Parameters: Name, Type `fn`, `any` #### `Run` Run executes the standalone task with the provided input and waits for completion. ```go func (st *StandaloneTask) Run(ctx context.Context, input any, opts ...RunOptFunc) (*TaskResult, error) ``` Parameters: Name, Type `ctx`, `context.Context` `input`, `any` `opts`, `...RunOptFunc` Returns: Type `*TaskResult` `error` #### `RunMany` RunMany executes multiple standalone task instances with different inputs. The returned results are in the same order as the inputs. Returns workflow run IDs that can be used to track the run statuses. ```go func (st *StandaloneTask) RunMany(ctx context.Context, inputs []RunManyOpt) ([]WorkflowRunRef, error) ``` Parameters: Name, Type `ctx`, `context.Context` `inputs`, `[]RunManyOpt` Returns: Type `[]WorkflowRunRef` `error` #### `RunNoWait` 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. ```go func (st *StandaloneTask) RunNoWait(ctx context.Context, input any, opts ...RunOptFunc) (*WorkflowRunRef, error) ``` Parameters: Name, Type `ctx`, `context.Context` `input`, `any` `opts`, `...RunOptFunc` Returns: Type `*WorkflowRunRef` `error` ## Task Task represents a task reference for building DAGs and conditions. ### Functions #### `GetName` GetName returns the name of the task. ```go func (t *Task) GetName() string ``` Returns: Type `string` ## WorkflowRunRef WorkflowRunRef is a type that represents a reference to a workflow run. Fields: Name, Type, Description `RunId`, `string` ### Functions #### `Result` Result blocks until the workflow run completes and returns its result. ```go func (wr *WorkflowRunRef) Result() (*WorkflowResult, error) ``` Returns: Type `*WorkflowResult` `error` ## WorkflowResult WorkflowResult wraps workflow execution results and provides type-safe conversion methods. Fields: Name, Type, Description `RunId`, `string` Methods: Name, Description `Raw`, Raw returns the raw, undecoded workflow result. `TaskOutput`, TaskOutput extracts the output of a specific task from the workflow result. ### Functions #### `Raw` Raw returns the raw, undecoded workflow result. ```go func (wr *WorkflowResult) Raw() any ``` Returns: Type `any` #### `TaskOutput` 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: ```go taskResult := workflowResult.TaskOutput("myTask") var output MyOutputType err := taskResult.Into(&output) ``` ```go func (wr *WorkflowResult) TaskOutput(taskName string) *TaskResult ``` Parameters: Name, Type `taskName`, `string` Returns: Type `*TaskResult` ## TaskResult TaskResult wraps a single task's output and provides type-safe conversion methods. Fields: Name, Type, Description `RunId`, `string` ### Functions #### `Into` 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: ```go var output MyOutputType err := taskResult.Into(&output) ``` ```go func (tr *TaskResult) Into(dest any) error ``` Parameters: Name, Type `dest`, `any` Returns: Type `error` ## RunManyOpt RunManyOpt is a type that represents the options for running multiple instances of a workflow with different inputs and options. Fields: Name, Type, Description `Input`, `any` `Opts`, `[]RunOptFunc` ## Workflow options Options for `Client.NewWorkflow` (and standalone task constructors): Name, Signature, Description `WithDefaultFilters`, `WithDefaultFilters(filters ...DefaultFilter)`, WithDefaultFilters sets default filters for event-triggered workflows or standalone tasks. `WithWorkflowConcurrency`, `WithWorkflowConcurrency(concurrency ...Concurrency)`, WithWorkflowConcurrency sets concurrency controls for the workflow. `WithWorkflowCron`, `WithWorkflowCron(cronExpressions ...string)`, WithWorkflowCron configures the workflow to run on a cron schedule. `WithWorkflowCronInput`, `WithWorkflowCronInput(input any)`, WithWorkflowCronInput sets the input for cron workflows. `WithWorkflowDefaultPriority`, `WithWorkflowDefaultPriority(priority RunPriority)`, WithWorkflowDefaultPriority sets the default priority for the workflow. `WithWorkflowDescription`, `WithWorkflowDescription(description string)`, WithWorkflowDescription sets a human-readable description for the workflow. `WithWorkflowEvents`, `WithWorkflowEvents(events ...string)`, WithWorkflowEvents configures the workflow to trigger on specific events. `WithWorkflowIdempotency`, `WithWorkflowIdempotency(config IdempotencyConfig)`, WithWorkflowIdempotency configures idempotency for the workflow. `WithWorkflowStickyStrategy`, `WithWorkflowStickyStrategy(stickyStrategy StickyStrategy)`, WithWorkflowStickyStrategy sets the sticky strategy for the workflow. `WithWorkflowTaskDefaults`, `WithWorkflowTaskDefaults(defaults *TaskDefaults)`, WithWorkflowTaskDefaults sets the default configuration for all tasks in the workflow. `WithWorkflowVersion`, `WithWorkflowVersion(version string)`, WithWorkflowVersion sets the version identifier for the workflow. ## Task options Options for `Workflow.NewTask` and the other task constructors: Name, Signature, Description `WithConcurrency`, `WithConcurrency(concurrency ...*Concurrency)`, WithConcurrency sets concurrency limits for task execution. `WithCron`, `WithCron(cronExpressions ...string)`, WithCron configures standalone tasks to run on a cron schedule. `WithDescription`, `WithDescription(description string)`, WithDescription sets a human-readable description for the task. `WithEvents`, `WithEvents(events ...string)`, WithEvents configures standalone tasks to trigger on specific events. `WithEvictionPolicy`, `WithEvictionPolicy(policy *EvictionPolicy)`, WithEvictionPolicy sets the eviction policy for a durable task. `WithExecutionTimeout`, `WithExecutionTimeout(timeout time.Duration)`, WithExecutionTimeout sets the maximum execution duration for a task. `WithParents`, `WithParents(parents ...*Task)`, WithParents sets parent task dependencies. `WithRateLimits`, `WithRateLimits(rateLimits ...*RateLimit)`, WithRateLimits sets rate limiting for task execution. `WithRetries`, `WithRetries(retries int)`, WithRetries sets the number of retry attempts for failed tasks. `WithRetryBackoff`, `WithRetryBackoff(factor float32, maxBackoffSeconds int)`, WithRetryBackoff configures exponential backoff for task retries. `WithScheduleTimeout`, `WithScheduleTimeout(timeout time.Duration)`, WithScheduleTimeout sets the maximum time a task can wait to be scheduled. `WithSkipIf`, `WithSkipIf(condition Condition)`, WithSkipIf sets a condition that will skip the task if met. `WithSlotCost`, `WithSlotCost(cost int)`, WithSlotCost sets the number of default worker slots this task consumes. `WithWaitFor`, `WithWaitFor(condition Condition)`, WithWaitFor sets a condition that must be met before the task executes. ## Run options Options for the `Run`, `RunNoWait`, and `RunMany` methods: Name, Signature, Description `WithDesiredWorkerLabels`, `WithDesiredWorkerLabels(labels map[string]*DesiredWorkerLabel)`, WithDesiredWorkerLabels sets desired worker labels for routing the workflow run to specific workers. `WithRunKey`, `WithRunKey(key string)`, WithRunKey sets the key for the child workflow run. `WithRunMetadata`, `WithRunMetadata(metadata map[string]string)`, WithRunMetadata sets the additional metadata for the workflow run. `WithRunPriority`, `WithRunPriority(priority RunPriority)`, WithRunPriority sets the priority for the workflow run. `WithRunSticky`, `WithRunSticky(sticky bool)`, WithRunSticky enables stickiness for the child workflow run. ## Other types ### BatchConfig BatchConfig configures batching behavior for a batch task. See Workflow.NewBatchTask. ### BatchMemberId BatchMemberId identifies a single item within a batch task's input/output map. Its value is the external id of the buffered item's underlying task run. ### BulkPushOpFunc BulkPushOpFunc configures a bulk event push via EventClient.BulkPush. ### BulkTriggerIdempotencyCollisionError BulkTriggerIdempotencyCollisionError is returned when one or more runs in a bulk trigger collide on idempotency keys. It carries the IDs of successful runs alongside the individual collision errors. Fields: Name, Type, Description `SuccessfulRunExternalIds`, `[]string` `Collisions`, `[]*IdempotencyCollisionError` #### Functions ##### `IsBulkTriggerIdempotencyCollisionError` IsBulkTriggerIdempotencyCollisionError checks if the error is a BulkTriggerIdempotencyCollisionError. ```go func IsBulkTriggerIdempotencyCollisionError(err error) (*BulkTriggerIdempotencyCollisionError, bool) ``` Parameters: Name, Type `err`, `error` Returns: Type `*BulkTriggerIdempotencyCollisionError` `bool` ##### `Error` ```go func (e *BulkTriggerIdempotencyCollisionError) Error() string ``` Returns: Type `string` ### ClientOpt ClientOpt configures the client created by NewClient. #### Functions ##### `WithClientLogLevel` WithClientLogLevel sets the log level for the client's default logger. ```go func WithClientLogLevel(lvl string) ClientOpt ``` Parameters: Name, Type `lvl`, `string` Returns: Type `ClientOpt` ##### `WithClientLogger` WithClientLogger sets the logger used by the client and its workers. ```go func WithClientLogger(l *zerolog.Logger) ClientOpt ``` Parameters: Name, Type `l`, `*zerolog.Logger` Returns: Type `ClientOpt` ##### `WithGRPCHeaders` WithGRPCHeaders adds custom headers to every gRPC request made by the client. ```go func WithGRPCHeaders(headers map[string]string) ClientOpt ``` Parameters: Name, Type `headers`, `map[string]string` Returns: Type `ClientOpt` ##### `WithHostPort` WithHostPort sets the gRPC host and port to connect to, overriding the address embedded in the token or set via environment variables. ```go func WithHostPort(host string, port int) ClientOpt ``` Parameters: Name, Type `host`, `string` `port`, `int` Returns: Type `ClientOpt` ##### `WithNamespace` WithNamespace prefixes all workflow, event, and cron names with the given namespace. ```go func WithNamespace(namespace string) ClientOpt ``` Parameters: Name, Type `namespace`, `string` Returns: Type `ClientOpt` ##### `WithSharedMeta` WithSharedMeta sets metadata that is attached to every event pushed by the client. ```go func WithSharedMeta(meta map[string]string) ClientOpt ``` Parameters: Name, Type `meta`, `map[string]string` Returns: Type `ClientOpt` ##### `WithTLSConfig` WithTLSConfig sets the gRPC TLS config directly, overriding any config derived from environment variables. A nil config connects without TLS (insecure). ```go func WithTLSConfig(tlsConfig *tls.Config) ClientOpt ``` Parameters: Name, Type `tlsConfig`, `*tls.Config` Returns: Type `ClientOpt` ##### `WithTenantId` WithTenantId sets the tenant ID for the client, overriding the one embedded in the token. ```go func WithTenantId(tenantId string) ClientOpt ``` Parameters: Name, Type `tenantId`, `string` Returns: Type `ClientOpt` ##### `WithToken` WithToken sets the API token used to authenticate with Hatchet. Defaults to the HATCHET_CLIENT_TOKEN environment variable. ```go func WithToken(token string) ClientOpt ``` Parameters: Name, Type `token`, `string` Returns: Type `ClientOpt` ### Concurrency Concurrency controls how many runs of a workflow or task may execute at once for a given key expression, and what happens when the limit is exceeded. ### ConcurrencyLimitStrategy ConcurrencyLimitStrategy determines what happens to runs beyond a concurrency limit. ### Condition Condition is a condition used with WithWaitFor and WithSkipIf to gate task execution. Build conditions with SleepCondition, UserEventCondition, ParentCondition, OrCondition, and AndCondition. #### Functions ##### `AndCondition` AndCondition creates a condition that is satisfied when all of the provided conditions are met. ```go func AndCondition(conditions ...Condition) Condition ``` Parameters: Name, Type `conditions`, `...Condition` Returns: Type `Condition` ##### `OrCondition` OrCondition creates a condition that is satisfied when any of the provided conditions are met. ```go func OrCondition(conditions ...Condition) Condition ``` Parameters: Name, Type `conditions`, `...Condition` Returns: Type `Condition` ##### `ParentCondition` ParentCondition creates a condition based on a parent task's output. ```go func ParentCondition(task *Task, expression string) Condition ``` Parameters: Name, Type `task`, `*Task` `expression`, `string` Returns: Type `Condition` ##### `SleepCondition` SleepCondition creates a condition that waits for a specified duration. ```go func SleepCondition(duration time.Duration) Condition ``` Parameters: Name, Type `duration`, `time.Duration` Returns: Type `Condition` ##### `UserEventCondition` UserEventCondition creates a condition that waits for a user event. ```go func UserEventCondition(eventKey, expression string, opts ...UserEventConditionOpt) Condition ``` Parameters: Name, Type `eventKey`, `string` `expression`, `string` `opts`, `...UserEventConditionOpt` Returns: Type `Condition` ### DefaultFilter DefaultFilter declares a default event filter for a workflow or standalone task, used with WithDefaultFilters. ### DeprecationError DeprecationError is returned when a deprecation grace period has expired. Fields: Name, Type, Description `Feature`, `string` `Message`, `string` #### Functions ##### `Error` ```go func (e *DeprecationError) Error() string ``` Returns: Type `string` ### DeprecationOpts DeprecationOpts provides optional configuration for EmitDeprecationNotice. Fields: Name, Type, Description `WarnWindow`, `time.Duration`, WarnWindow is how long after start the notice is a warning. Defaults to 90 days if zero. `ErrorWindow`, `time.Duration`, ErrorWindow is how long after start the notice is an error log. After this window, calls have a 20% chance of returning an error. If zero (default), the error/raise phase is never reached and the notice stays at error-level logging indefinitely. ### DesiredWorkerLabel ### EventClient EventClient sends events to Hatchet, triggering any workflows subscribed to the event key. Obtain one from Client.Events(). Methods: Name, Description `Push`, Push sends a single event with the given key and JSON-serializable payload, triggering any workflows subscribed to the event key. `BulkPush`, BulkPush sends multiple events in a single request. `PutLog`, PutLog writes a log line to the given task run. `PutLogWithTimestamp`, PutLogWithTimestamp writes a log line to the given task run with an explicit timestamp. `PutStreamEvent`, PutStreamEvent publishes a chunk of streaming output for the given task run, delivered to subscribers of the run's stream. #### `Push` Push sends a single event with the given key and JSON-serializable payload, triggering any workflows subscribed to the event key. ```go func Push(ctx context.Context, eventKey string, payload interface{}, options ...PushOpFunc) error ``` Parameters: Name, Type `ctx`, `context.Context` `eventKey`, `string` `payload`, `interface{}` `options`, `...PushOpFunc` Returns: Type `error` #### `BulkPush` BulkPush sends multiple events in a single request. ```go func BulkPush(ctx context.Context, payloads []EventWithAdditionalMetadata, options ...BulkPushOpFunc) error ``` Parameters: Name, Type `ctx`, `context.Context` `payloads`, `[]EventWithAdditionalMetadata` `options`, `...BulkPushOpFunc` Returns: Type `error` #### `PutLog` PutLog writes a log line to the given task run. ```go func PutLog(ctx context.Context, taskRunId, msg string, level *string, taskRetryCount *int32) error ``` Parameters: Name, Type `ctx`, `context.Context` `taskRunId`, `string` `msg`, `string` `level`, `*string` `taskRetryCount`, `*int32` Returns: Type `error` #### `PutLogWithTimestamp` PutLogWithTimestamp writes a log line to the given task run with an explicit timestamp. ```go func PutLogWithTimestamp(ctx context.Context, taskRunId, msg string, level *string, taskRetryCount *int32, createdAt *timestamppb.Timestamp) error ``` Parameters: Name, Type `ctx`, `context.Context` `taskRunId`, `string` `msg`, `string` `level`, `*string` `taskRetryCount`, `*int32` `createdAt`, `*timestamppb.Timestamp` Returns: Type `error` #### `PutStreamEvent` PutStreamEvent publishes a chunk of streaming output for the given task run, delivered to subscribers of the run's stream. ```go func PutStreamEvent(ctx context.Context, stepRunId string, message []byte, options ...StreamEventOption) error ``` Parameters: Name, Type `ctx`, `context.Context` `stepRunId`, `string` `message`, `[]byte` `options`, `...StreamEventOption` Returns: Type `error` ### EventUnmarshaller EventUnmarshaller is implemented by the result of DurableContext.WaitForEvent. Use EventInto to extract the event payload. ### EventWithAdditionalMetadata EventWithAdditionalMetadata is a single event in an EventClient.BulkPush call. ### EvictionNotSupportedError EvictionNotSupportedError is returned when an eviction policy is configured against an engine version that does not support durable-task eviction. Fields: Name, Type, Description `EngineVersion`, `string` #### Functions ##### `IsEvictionNotSupportedError` IsEvictionNotSupportedError reports whether err is an EvictionNotSupportedError. ```go func IsEvictionNotSupportedError(err error) (*EvictionNotSupportedError, bool) ``` Parameters: Name, Type `err`, `error` Returns: Type `*EvictionNotSupportedError` `bool` ##### `Error` ```go func (e *EvictionNotSupportedError) Error() string ``` Returns: Type `string` ### EvictionPolicy EvictionPolicy configures how durable tasks are evicted from worker slots when they are in a waiting state (e.g. sleeping, waiting for events, waiting for children). Fields: Name, Type, Description `TTL`, `time.Duration`, TTL is the maximum continuous waiting duration before TTL-eligible eviction. A zero value means no TTL-based eviction. `AllowCapacityEviction`, `bool`, AllowCapacityEviction controls whether this task may be evicted under durable-slot pressure. `Priority`, `int`, Priority determines eviction order when multiple candidates exist. Lower values are evicted first. ### IdempotencyCollisionError IdempotencyCollisionError is returned when an idempotency key collision occurs. It contains the ID of the existing run that claimed the key. Fields: Name, Type, Description `ExistingRunExternalId`, `string` #### Functions ##### `IsIdempotencyCollisionError` IsIdempotencyCollisionError checks if the error is an IdempotencyCollisionError. ```go func IsIdempotencyCollisionError(err error) (*IdempotencyCollisionError, bool) ``` Parameters: Name, Type `err`, `error` Returns: Type `*IdempotencyCollisionError` `bool` ##### `Error` ```go func (e *IdempotencyCollisionError) Error() string ``` Returns: Type `string` ### IdempotencyConfig IdempotencyConfig configures idempotency behavior for a workflow or standalone task. When set, runs triggered with the same computed key return an IdempotencyCollisionError instead of creating a new run. The Method controls how long the key lives: TTL evicts after a fixed window, while STATUS keeps the key until the run reaches a terminal status (using TTL as a fallback cap). Fields: Name, Type, Description `Expression`, `string`, Expression is a CEL expression evaluated against the workflow input to produce an idempotency key. `TTL`, `time.Duration`, TTL is the duration during which duplicate runs with the same key are rejected. When Method is STATUS, this acts as a fallback: the longest the key can live before it's evicted. `Method`, `IdempotencyMethod`, Method determines how the idempotency key's lifetime is managed. Defaults to TTL. ### IdempotencyMethod IdempotencyMethod determines how the lifetime of an idempotency key is managed. ### MiddlewareFunc MiddlewareFunc is a middleware function invoked around each task run execution. It receives the task's Context and a next function that continues the chain. ### NonDeterminismError NonDeterminismError is returned when a durable task replay detects non-deterministic behavior. Fields: Name, Type, Description `TaskExternalID`, `string` `Message`, `string` `NodeID`, `int64` `InvocationCount`, `int32` #### Functions ##### `IsNonDeterminismError` IsNonDeterminismError checks if the error is a NonDeterminismError and returns it if so. ```go func IsNonDeterminismError(err error) (*NonDeterminismError, bool) ``` Parameters: Name, Type `err`, `error` Returns: Type `*NonDeterminismError` `bool` ##### `Error` ```go func (e *NonDeterminismError) Error() string ``` Returns: Type `string` ### NonRetryableError NonRetryableError marks a task failure as non-retryable: the task fails immediately without consuming any remaining retries. ### PushOpFunc PushOpFunc configures a single event pushed via EventClient.Push. #### Functions ##### `WithEventMetadata` WithEventMetadata attaches additional metadata to the pushed event. ```go func WithEventMetadata(metadata map[string]string) PushOpFunc ``` Parameters: Name, Type `metadata`, `map[string]string` Returns: Type `PushOpFunc` ##### `WithEventPriority` WithEventPriority sets the priority of the runs triggered by the pushed event. ```go func WithEventPriority(priority *int32) PushOpFunc ``` Parameters: Name, Type `priority`, `*int32` Returns: Type `PushOpFunc` ##### `WithFilterScope` WithFilterScope sets the filter scope for the pushed event, matching it against default filters declared with the same scope (see WithDefaultFilters). ```go func WithFilterScope(scope *string) PushOpFunc ``` Parameters: Name, Type `scope`, `*string` Returns: Type `PushOpFunc` ### RateLimit RateLimit declares a rate limit consumed by a task run, used with WithRateLimits. ### RateLimitDuration RateLimitDuration is the window over which a rate limit applies. ### RunPriority ### SingleWaitResult SingleWaitResult holds the result of a single-condition durable wait such as DurableContext.SleepFor or DurableContext.WaitForEvent. Methods: Name, Description `Unmarshal`, Unmarshal decodes the matched event or condition payload into in, which must be a pointer. #### `Unmarshal` Unmarshal decodes the matched event or condition payload into in, which must be a pointer. hatchet.EventInto is a convenience wrapper around it. ```go func (w *SingleWaitResult) Unmarshal(in interface{}) error ``` Parameters: Name, Type `in`, `interface{}` Returns: Type `error` ### StickyStrategy StickyStrategy determines how child workflow runs are routed back to the worker that ran the parent. ### TaskDefaults TaskDefaults sets default task configuration for all tasks in a workflow, used with WithWorkflowTaskDefaults. ### UserEventConditionOpt UserEventConditionOpt configures a UserEventCondition. #### Functions ##### `WithConsiderEventsSince` WithConsiderEventsSince makes a user event condition also match events pushed after the given time but before the wait was registered (event lookback). Requires WithEventScope to be set as well. ```go func WithConsiderEventsSince(since time.Time) UserEventConditionOpt ``` Parameters: Name, Type `since`, `time.Time` Returns: Type `UserEventConditionOpt` ##### `WithEventScope` WithEventScope restricts a user event condition to events pushed with a matching scope. ```go func WithEventScope(scope string) UserEventConditionOpt ``` Parameters: Name, Type `scope`, `string` Returns: Type `UserEventConditionOpt` ### WaitResult WaitResult holds the results of a DurableContext.WaitFor call, keyed by condition. Methods: Name, Description `Keys`, Keys returns the readable keys of the conditions that produced this result, such as user event keys and "sleep:\" entries. `Unmarshal`, Unmarshal decodes the payload matched for the given condition key into in, which must be a pointer. #### `Keys` Keys returns the readable keys of the conditions that produced this result, such as user event keys and "sleep:\" entries. ```go func (w *WaitResult) Keys() []string ``` Returns: Type `[]string` #### `Unmarshal` Unmarshal decodes the payload matched for the given condition key into in, which must be a pointer. ```go func (w *WaitResult) Unmarshal(key string, in interface{}) error ``` Parameters: Name, Type `key`, `string` `in`, `interface{}` Returns: Type `error` ### WorkerLabelComparator #### Functions ##### `ComparatorPtr` ComparatorPtr returns a pointer to the given comparator, for use in DesiredWorkerLabel. ```go func ComparatorPtr(v WorkerLabelComparator) *WorkerLabelComparator ``` Parameters: Name, Type `v`, `WorkerLabelComparator` Returns: Type `*WorkerLabelComparator` ## Other functions ### `EmitDeprecationNotice` EmitDeprecationNotice emits a time-aware deprecation notice. - feature: a short identifier for deduplication (each feature logs once). - message: the human-readable deprecation message. - start: the UTC time when the deprecation window began. - logger: the zerolog logger to write to. - opts: optional configuration; pass nil for defaults. Returns a non-nil \*DeprecationError only in phase 3 (~20% chance). ```go func EmitDeprecationNotice(feature, message string, start time.Time, logger *zerolog.Logger, opts *DeprecationOpts) error ``` Parameters: Name, Type `feature`, `string` `message`, `string` `start`, `time.Time` `logger`, `*zerolog.Logger` `opts`, `*DeprecationOpts` Returns: Type `error` ### `EventInto` EventInto extracts the event payload from a WaitForEvent result into dest. ```go event, err := ctx.WaitForEvent("approval:decision", "") if err != nil { return err } var data map[string]interface{} if err := hatchet.EventInto(event, &data); err != nil { return err } ``` ```go func EventInto(event EventUnmarshaller, dest any) error ``` Parameters: Name, Type `event`, `EventUnmarshaller` `dest`, `any` Returns: Type `error` ### `IsNonRetryableError` IsNonRetryableError reports whether err is (or wraps) a NonRetryableError. ```go func IsNonRetryableError(err error) bool ``` Parameters: Name, Type `err`, `error` Returns: Type `bool` ### `NewNonRetryableError` NewNonRetryableError wraps err so that the task run fails without being retried, regardless of the task's retry configuration. ```go func NewNonRetryableError(err error) error ``` Parameters: Name, Type `err`, `error` Returns: Type `error` ### `ParseSemver` ParseSemver extracts major, minor, patch from a version string like "v0.78.23". Returns (0,0,0) if parsing fails. ```go func ParseSemver(v string) (int, int, int) ``` Parameters: Name, Type `v`, `string` Returns: Type `int` `int` `int` ### `SemverLessThan` SemverLessThan returns true if version a is strictly less than version b. ```go func SemverLessThan(a, b string) bool ``` Parameters: Name, Type `a`, `string` `b`, `string` Returns: Type `bool` ### `SupportsDurableEviction` SupportsDurableEviction checks whether the engine version supports durable eviction. ```go func SupportsDurableEviction(engineVersion string) (bool, error) ``` Parameters: Name, Type `engineVersion`, `string` Returns: Type `bool` `error`