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



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

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



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

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:



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

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:



277
278
279
 
# File 'lib/hatchet-sdk.rb', line 277

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

#cel ⇒ Hatchet::Features::CEL

Feature Client for debugging CEL expressions

Returns:



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

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) 


262
263
264
 
# File 'lib/hatchet-sdk.rb', line 262

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

#cron ⇒ Hatchet::Features::Cron

Feature Client for managing cron workflows

Returns:



177
178
179
 
# File 'lib/hatchet-sdk.rb', line 177

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

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

gRPC Dispatcher client (lazy-initialized).

Returns:



269
270
271
 
# File 'lib/hatchet-sdk.rb', line 269

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 task.

Parameters:

  • name (String) —

    Task name

  • 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) —

    Task options

  • 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:



227
228
229
230
231
232
 
# File 'lib/hatchet-sdk.rb', line 227

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:



284
285
286
 
# File 'lib/hatchet-sdk.rb', line 284

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

#events ⇒ Hatchet::Features::Events

Feature Client for interacting with Hatchet events

Returns:



117
118
119
 
# File 'lib/hatchet-sdk.rb', line 117

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

#filters ⇒ Hatchet::Features::Filters

Feature Client for managing filters

Returns:



159
160
161
 
# File 'lib/hatchet-sdk.rb', line 159

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

#logger ⇒ Logger

Convenience accessor for the logger

Returns:



249
250
251
 
# File 'lib/hatchet-sdk.rb', line 249

def logger
  @config.logger
end

#logs ⇒ Hatchet::Features::Logs

Feature Client for interacting with Hatchet logs

Returns:



135
136
137
 
# File 'lib/hatchet-sdk.rb', line 135

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

#metrics ⇒ Hatchet::Features::Metrics

Feature Client for reading metrics

Returns:



165
166
167
 
# File 'lib/hatchet-sdk.rb', line 165

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

#rate_limits ⇒ Hatchet::Features::RateLimits

Feature Client for managing rate limits

Returns:



171
172
173
 
# File 'lib/hatchet-sdk.rb', line 171

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

#rest_client ⇒ Object

Returns:

  • (Object) 


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

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

#runs ⇒ Hatchet::Features::Runs

Feature Client for interacting with Hatchet workflow runs

Returns:



123
124
125
 
# File 'lib/hatchet-sdk.rb', line 123

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

#scheduled ⇒ Hatchet::Features::Scheduled

Feature Client for managing scheduled workflows

Returns:



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

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

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

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

Examples:

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

Parameters:

  • name (String) —

    Task name

  • opts (Hash) —

    Task options (on_events:, idempotency:, retries:, etc.)

  • name: (String)

Yields:

  • (input, ctx) —

    The task execution block

Yield Parameters:

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

Yield Returns:

  • (Object)

Returns:



209
210
211
212
213
214
215
 
# File 'lib/hatchet-sdk.rb', line 209

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

Feature Client for interacting with the current tenant

Returns:



129
130
131
 
# File 'lib/hatchet-sdk.rb', line 129

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

#tenant_id ⇒ String

Returns The tenant ID.

Returns:

  • (String) —

    The tenant ID



254
255
256
 
# File 'lib/hatchet-sdk.rb', line 254

def tenant_id
  @config.tenant_id
end

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

Create a new worker

Examples:

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

Parameters:

  • name (String) —

    Worker name

  • opts (Hash) —

    Worker options (workflows:, slots:, labels:)

Returns:



243
244
245
 
# File 'lib/hatchet-sdk.rb', line 243

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

#workers ⇒ Hatchet::Features::Workers

Feature Client for managing workers

Returns:



141
142
143
 
# File 'lib/hatchet-sdk.rb', line 141

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

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

Create a new workflow definition

Examples:

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

Parameters:

  • name (String) —

    Workflow name

  • opts (Hash) —

    Workflow options (on_events:, concurrency:, idempotency:, etc.)

  • name: (String)

Returns:



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

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:



294
295
296
 
# File 'lib/hatchet-sdk.rb', line 294

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

#workflows ⇒ Hatchet::Features::Workflows

Feature Client for managing workflow definitions

Returns:



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

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