Class: Hatchet::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/hatchet-sdk.rb,
sig/hatchet-sdk.rbs

Overview

The main client for interacting with Hatchet services.

Examples:

Basic usage with API token

hatchet = Hatchet::Client.new()

With custom configuration

hatchet = Hatchet::Client.new(
  token: "your-jwt-token",
  namespace: "production"
)

Define a workflow

wf = hatchet.workflow(name: "MyWorkflow")
step1 = wf.task(:step1) { |input, ctx| { "result" => 42 } }

Define a standalone task

my_task = hatchet.task(name: "my_task") { |input, ctx| { "result" => "done" } }

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(**options) ⇒ Client

Initialize a new Hatchet client with the given configuration options.

Parameters:

  • options (Hash) —

    Configuration options for the client

Options Hash (**options):

  • :debug (Boolean) —

    Enable debug logging (default: false)

  • :token (String) —

    The JWT token for authentication (required)

  • :tenant_id (String) —

    Override tenant ID (extracted from JWT token 'sub' field if not provided)

  • :host_port (String) —

    gRPC server host and port (default: "localhost:7070")

  • :server_url (String) —

    Server URL for HTTP requests

  • :namespace (String) —

    Namespace prefix for resource names (default: "")

  • :logger (Logger) —

    Custom logger instance

  • :worker_preset_labels (Hash) —

    Default labels applied to all workers

Raises:

  • (Error) —

    if token or configuration is missing or invalid



107
108
109
110
 
# File 'lib/hatchet-sdk.rb', line 107

def initialize(**options)
  @debug = options.delete(:debug) || false
  @config = Config.new(**options)
end

Instance Attribute Details

#config ⇒ Config (readonly)

Returns The configuration object used by this client.

Returns:

  • (Config) —

    The configuration object used by this client



92
93
94
 
# File 'lib/hatchet-sdk.rb', line 92

def config
  @config
end

Instance Method Details

#admin ⇒ AdminClient

High-level admin client for workflow triggering. Delegates to the gRPC admin client with context variable propagation.

Returns:



360
361
362
 
# File 'lib/hatchet-sdk.rb', line 360

def admin
  @admin ||= AdminClient.new(client: self)
end

#admin_grpc ⇒ Hatchet::Clients::Grpc::Admin

gRPC Admin client (lazy-initialized). Uses both v0 WorkflowService and v1 AdminService stubs.

Returns:



335
336
337
 
# File 'lib/hatchet-sdk.rb', line 335

def admin_grpc
  @admin_grpc ||= Clients::Grpc::Admin.new(config: @config, channel: channel)
end

#batch_task(name:, batch:, **opts) {|inputs, ctx| ... } ⇒ Hatchet::Task

Create a standalone batch task (auto-wraps in a single-task workflow).

Batch tasks buffer concurrent runs until Hatchet flushes the batch (size reached or flush interval), then invoke the block once with all buffered inputs keyed by each run's task-run external id. The block must return a Hash mapping each id to its output, or use broadcast_output on the batch config to return the same result to all callers. retries is always forced to 0 for batch tasks.

Preview: batch tasks are in beta and may change in future releases.

Examples:

batch = hatchet.batch_task(name: "my_batch", batch: Hatchet::BatchTaskConfig.new(max_size: 3)) do |inputs, ctx|
  inputs.transform_values { |input| { "result" => input["message"].upcase } }
end

Parameters:

  • name (String) —

    The name of the task

  • batch (Hatchet::BatchTaskConfig) —

    The batch configuration (+max_size+, flush interval, broadcast_output)

  • opts (Hash) —

    Any other keyword arguments (+on_events:+, idempotency:, and so on) are forwarded to #task

Yields:

  • (inputs, ctx) —

    The batch execution block, receiving a Hash of task-run external id => input

Returns:



264
265
266
 
# File 'lib/hatchet-sdk.rb', line 264

def batch_task(name:, batch:, **opts, &block)
  task(name: name, batch: batch, **opts, &block)
end

#cel ⇒ Hatchet::Features::CEL

The CEL client is a client for debugging CEL expressions within Hatchet.

Returns:



152
153
154
 
# File 'lib/hatchet-sdk.rb', line 152

def cel
  @cel ||= Hatchet::Features::CEL.new(rest_client, @config)
end

#channel ⇒ GRPC::Core::Channel

Shared gRPC channel (lazy-initialized). A single channel is shared across all gRPC stubs for connection reuse.

Returns:

  • (GRPC::Core::Channel) 


320
321
322
 
# File 'lib/hatchet-sdk.rb', line 320

def channel
  @channel ||= Connection.new_channel(@config)
end

#cron ⇒ Hatchet::Features::Cron

The cron client is a client for managing cron workflow triggers within Hatchet.

Returns:



189
190
191
 
# File 'lib/hatchet-sdk.rb', line 189

def cron
  @cron ||= Hatchet::Features::Cron.new(rest_client, @config)
end

#dispatcher_grpc ⇒ Hatchet::Clients::Grpc::Dispatcher

gRPC Dispatcher client (lazy-initialized).

Returns:



327
328
329
 
# File 'lib/hatchet-sdk.rb', line 327

def dispatcher_grpc
  @dispatcher_grpc ||= Clients::Grpc::Dispatcher.new(config: @config, channel: channel)
end

#durable_task(name:, eviction_policy: Hatchet::DEFAULT_DURABLE_TASK_EVICTION_POLICY, **opts) {|input, ctx| ... } ⇒ Hatchet::Task

Create a standalone durable Hatchet task, which works using Hatchet's durable execution capabilities. Durable tasks receive a DurableContext with additional methods like sleep_for and wait_for.

Parameters:

  • name (String) —

    The name of the task

  • eviction_policy (Hatchet::EvictionPolicy, nil) (defaults to: Hatchet::DEFAULT_DURABLE_TASK_EVICTION_POLICY) —

    Eviction policy for this durable task. Defaults to DEFAULT_DURABLE_TASK_EVICTION_POLICY (15-minute TTL, capacity-eviction enabled). Pass nil to disable eviction entirely for this task.

  • opts (Hash) —

    Any other keyword arguments (+retries:+, execution_timeout:, and so on) are forwarded to the task declaration - see Workflow#task for the full list

  • name: (String)
  • eviction_policy: (EvictionPolicy, nil) (defaults to: Hatchet::DEFAULT_DURABLE_TASK_EVICTION_POLICY)

Yields:

  • (input, ctx) —

    The task execution block

Yield Parameters:

Yield Returns:

  • (Object)

Returns:



280
281
282
283
284
285
 
# File 'lib/hatchet-sdk.rb', line 280

def durable_task(name:, eviction_policy: Hatchet::DEFAULT_DURABLE_TASK_EVICTION_POLICY, **opts, &block)
  wf = Workflow.new(name: name, client: self,
                    on_events: opts.delete(:on_events) || [],
                    default_filters: opts.delete(:default_filters) || [],)
  wf.durable_task(name, eviction_policy: eviction_policy, **opts, &block)
end

#event_grpc ⇒ Hatchet::Clients::Grpc::EventClient

gRPC Event client (lazy-initialized).

Returns:



342
343
344
 
# File 'lib/hatchet-sdk.rb', line 342

def event_grpc
  @event_grpc ||= Clients::Grpc::EventClient.new(config: @config, channel: channel)
end

#events ⇒ Hatchet::Features::Events

The events client, which you can use to push events to Hatchet to trigger event-driven workflows.

Returns:



119
120
121
 
# File 'lib/hatchet-sdk.rb', line 119

def events
  @events ||= Hatchet::Features::Events.new(rest_client, event_grpc, @config)
end

#filters ⇒ Hatchet::Features::Filters

The filters client is a client for managing filters within Hatchet, which scope event triggers to workflows using CEL expressions.

Returns:



168
169
170
 
# File 'lib/hatchet-sdk.rb', line 168

def filters
  @filters ||= Hatchet::Features::Filters.new(rest_client, @config)
end

#logger ⇒ Logger

Convenience accessor for the logger

Returns:



307
308
309
 
# File 'lib/hatchet-sdk.rb', line 307

def logger
  @config.logger
end

#logs ⇒ Hatchet::Features::Logs

The logs client is a client for interacting with Hatchet's logs API.

Returns:



139
140
141
 
# File 'lib/hatchet-sdk.rb', line 139

def logs
  @logs ||= Hatchet::Features::Logs.new(rest_client, @config)
end

#metrics ⇒ Hatchet::Features::Metrics

The metrics client is a client for reading metrics out of Hatchet's metrics API.

Returns:



175
176
177
 
# File 'lib/hatchet-sdk.rb', line 175

def metrics
  @metrics ||= Hatchet::Features::Metrics.new(rest_client, @config)
end

#rate_limits ⇒ Hatchet::Features::RateLimits

The rate limits client is a wrapper for Hatchet's gRPC API that makes it easier to work with rate limits in Hatchet.

Returns:



182
183
184
 
# File 'lib/hatchet-sdk.rb', line 182

def rate_limits
  @rate_limits ||= Hatchet::Features::RateLimits.new(admin_grpc, @config)
end

#rest_client ⇒ Object

Returns:

  • (Object) 


112
113
114
 
# File 'lib/hatchet-sdk.rb', line 112

def rest_client
  @rest_client ||= Hatchet::Clients.rest_client(@config)
end

#runs ⇒ Hatchet::Features::Runs

The runs client is a client for interacting with task and workflow runs within Hatchet.

Returns:



126
127
128
 
# File 'lib/hatchet-sdk.rb', line 126

def runs
  @runs ||= Hatchet::Features::Runs.new(rest_client, @config, client: self)
end

#scheduled ⇒ Hatchet::Features::Scheduled

The scheduled client is a client for managing scheduled workflow runs within Hatchet.

Returns:



196
197
198
 
# File 'lib/hatchet-sdk.rb', line 196

def scheduled
  @scheduled ||= Hatchet::Features::Scheduled.new(rest_client, @config)
end

#task(name:, **opts) {|input, ctx| ... } ⇒ Hatchet::Task

Create a standalone Hatchet task. The task is automatically wrapped in a single-task workflow, so it can be run, scheduled, and registered on a worker just like a workflow. The block receives the run's input and a Hatchet::Context object.

Examples:

my_task = hatchet.task(name: "my_task") { |input, ctx| { "result" => "done" } }

Parameters:

  • name (String) —

    The name of the task

  • opts (Hash) —

    Any other keyword arguments (+retries:+, execution_timeout:, concurrency:, and so on) are forwarded to the task declaration - see Workflow#task for the full list

  • name: (String)

Options Hash (**opts):

  • :on_events (Array<String>) — default: [] —

    A list of event triggers for the task - events which cause the task to be run

  • :default_filters (Array<DefaultFilter>) — default: [] —

    A list of filters to create when the task is created

  • :idempotency (TTLBasedIdempotencyConfig, StatusBasedIdempotencyConfig, nil) — default: nil —

    An idempotency configuration for the task

Yields:

  • (input, ctx) —

    The task execution block

Yield Parameters:

  • arg0 (Hash[String, untyped])
  • arg1 (Context)

Yield Returns:

  • (Object)

Returns:

  • (Hatchet::Task) —

    The created task object, which can be run, scheduled, and registered on a worker



236
237
238
239
240
241
242
 
# File 'lib/hatchet-sdk.rb', line 236

def task(name:, **opts, &block)
  wf = Workflow.new(name: name, client: self,
                    on_events: opts.delete(:on_events) || [],
                    default_filters: opts.delete(:default_filters) || [],
                    idempotency: opts.delete(:idempotency),)
  wf.task(name, **opts, &block)
end

#tenant ⇒ Hatchet::Features::Tenant

The tenant client is a client for reading information about the tenant you're operating in.

Returns:



133
134
135
 
# File 'lib/hatchet-sdk.rb', line 133

def tenant
  @tenant ||= Hatchet::Features::Tenant.new(rest_client, @config)
end

#tenant_id ⇒ String

Returns The tenant ID.

Returns:

  • (String) —

    The tenant ID



312
313
314
 
# File 'lib/hatchet-sdk.rb', line 312

def tenant_id
  @config.tenant_id
end

#worker(name, **opts) ⇒ Hatchet::Worker

Create a Hatchet worker on which to run workflows.

Examples:

worker = hatchet.worker("my-worker", workflows: [wf], slots: 10)
worker.start

Parameters:

  • name (String) —

    The name of the worker

  • opts (Hash) —

    a customizable set of options

Options Hash (**opts):

  • :workflows (Array<Workflow, Task>) — default: [] —

    A list of workflows (or standalone tasks) to register on the worker

  • :slots (Integer) — default: 10 —

    Slot count for standard tasks, i.e. the number of tasks the worker can run concurrently

  • :durable_slots (Integer, nil) — default: nil —

    Slot count for durable tasks; defaults to slots if not provided

  • :labels (Hash) — default: {} —

    A hash of labels to assign to the worker, for use with worker affinity; merged with the client's worker_preset_labels

Returns:

  • (Hatchet::Worker) —

    The created worker object, which exposes an instance method start which can be called to start the worker (blocking until shutdown), and stop to request a graceful shutdown



301
302
303
 
# File 'lib/hatchet-sdk.rb', line 301

def worker(name, **opts)
  Worker.new(name: name, client: self, **opts)
end

#workers ⇒ Hatchet::Features::Workers

The workers client is a client for managing workers programmatically within Hatchet.

Returns:



146
147
148
 
# File 'lib/hatchet-sdk.rb', line 146

def workers
  @workers ||= Hatchet::Features::Workers.new(rest_client, @config)
end

#workflow(name:, **opts) ⇒ Hatchet::Workflow

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

Examples:

wf = hatchet.workflow(name: "MyWorkflow")
wf.task(:step1) { |input, ctx| { "value" => 42 } }

Parameters:

  • name (String) —

    The name of the workflow

  • opts (Hash) —

    a customizable set of options

  • name: (String)

Options Hash (**opts):

  • :on_events (Array<String>) — default: [] —

    A list of event triggers for the workflow - events which cause the workflow to be run

  • :on_crons (Array<String>) — default: [] —

    A list of cron triggers for the workflow

  • :concurrency (ConcurrencyExpression, Array<ConcurrencyExpression>, nil) — default: nil —

    A concurrency object (or list of them) controlling the concurrency settings for this workflow

  • :default_priority (Integer, nil) — default: nil —

    The default priority of the workflow. Higher values will cause runs of this workflow to have priority in scheduling over other, lower priority ones

  • :task_defaults (Hash, nil) — default: nil —

    Default task settings for this workflow

  • :default_filters (Array<DefaultFilter>) — default: [] —

    A list of filters to create when the workflow is created

  • :sticky (Symbol, nil) — default: nil —

    A sticky strategy for the workflow, either :soft or :hard

  • :idempotency (TTLBasedIdempotencyConfig, StatusBasedIdempotencyConfig, nil) — default: nil —

    An idempotency configuration for the workflow

Returns:

  • (Hatchet::Workflow) —

    The created workflow object, which can be used to declare tasks, run the workflow, and so on



217
218
219
 
# File 'lib/hatchet-sdk.rb', line 217

def workflow(name:, **opts)
  Workflow.new(name: name, client: self, **opts)
end

#workflow_run_listener ⇒ Hatchet::WorkflowRunListener

Pooled gRPC listener for workflow run completion events (lazy-initialized).

Maintains a single bidi stream to Dispatcher.SubscribeToWorkflowRuns shared by all callers of WorkflowRunRef#result.

Returns:



352
353
354
 
# File 'lib/hatchet-sdk.rb', line 352

def workflow_run_listener
  @workflow_run_listener ||= WorkflowRunListener.new(config: @config, channel: channel)
end

#workflows ⇒ Hatchet::Features::Workflows

The workflows client is a client for managing workflow declarations programmatically within Hatchet. Note that workflows are the declaration, not the individual runs; if you're looking for runs, use the runs client instead.

Returns:



161
162
163
 
# File 'lib/hatchet-sdk.rb', line 161

def workflows
  @workflows ||= Hatchet::Features::Workflows.new(rest_client, @config)
end