Class: Hatchet::Client

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

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



114
115
116
117
 
# File 'lib/hatchet-sdk.rb', line 114

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



99
100
101
 
# File 'lib/hatchet-sdk.rb', line 99

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:



310
311
312
 
# File 'lib/hatchet-sdk.rb', line 310

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:



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

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:



155
156
157
 
# File 'lib/hatchet-sdk.rb', line 155

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) 


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

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

#cron ⇒ Hatchet::Features::Cron

Feature Client for managing cron workflows

Returns:



185
186
187
 
# File 'lib/hatchet-sdk.rb', line 185

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

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

gRPC Dispatcher client (lazy-initialized).

Returns:



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

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

Yields:

  • (input, ctx) —

    The task execution block

Returns:



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

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:



292
293
294
 
# File 'lib/hatchet-sdk.rb', line 292

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:



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

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

#filters ⇒ Hatchet::Features::Filters

Feature Client for managing filters

Returns:



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

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

#logger ⇒ Logger

Convenience accessor for the logger

Returns:

  • (Logger) 


257
258
259
 
# File 'lib/hatchet-sdk.rb', line 257

def logger
  @config.logger
end

#logs ⇒ Hatchet::Features::Logs

Feature Client for interacting with Hatchet logs

Returns:



143
144
145
 
# File 'lib/hatchet-sdk.rb', line 143

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

#metrics ⇒ Hatchet::Features::Metrics

Feature Client for reading metrics

Returns:



173
174
175
 
# File 'lib/hatchet-sdk.rb', line 173

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

#rate_limits ⇒ Hatchet::Features::RateLimits

Feature Client for managing rate limits

Returns:



179
180
181
 
# File 'lib/hatchet-sdk.rb', line 179

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

#rest_client ⇒ Object 



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

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

#runs ⇒ Hatchet::Features::Runs

Feature Client for interacting with Hatchet workflow runs

Returns:



131
132
133
 
# File 'lib/hatchet-sdk.rb', line 131

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

#scheduled ⇒ Hatchet::Features::Scheduled

Feature Client for managing scheduled workflows

Returns:



191
192
193
 
# File 'lib/hatchet-sdk.rb', line 191

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

Yields:

  • (input, ctx) —

    The task execution block

Returns:



217
218
219
220
221
222
223
 
# File 'lib/hatchet-sdk.rb', line 217

def task(name:, **opts, &block)
  # Create a workflow wrapper for standalone tasks
  wf = Workflow.new(name: name, client: self,
                    on_events: opts.delete(:on_events) || [],
                    default_filters: opts.delete(:default_filters) || [],)
  wf.task(name, **opts, &block)
end

#tenant ⇒ Hatchet::Features::Tenant

Feature Client for interacting with the current tenant

Returns:



137
138
139
 
# File 'lib/hatchet-sdk.rb', line 137

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

#tenant_id ⇒ String

Returns The tenant ID.

Returns:

  • (String) —

    The tenant ID



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

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:



251
252
253
 
# File 'lib/hatchet-sdk.rb', line 251

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

#workers ⇒ Hatchet::Features::Workers

Feature Client for managing workers

Returns:



149
150
151
 
# File 'lib/hatchet-sdk.rb', line 149

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

Returns:



204
205
206
 
# File 'lib/hatchet-sdk.rb', line 204

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:



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

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:



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

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