hatchet-sdk 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +15 -0
  3. data/README.md +45 -0
  4. data/lib/hatchet/clients/rest/.openapi-generator/FILES +9 -0
  5. data/lib/hatchet/clients/rest/README.md +16 -3
  6. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/api/filter_api.rb +4 -0
  7. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/api/operator_api.rb +405 -0
  8. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/api/webhook_api.rb +2 -0
  9. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/api/worker_api.rb +3 -0
  10. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/api/workflow_runs_api.rb +3 -0
  11. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/api_meta.rb +14 -4
  12. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/create_tenant_invite_request.rb +14 -4
  13. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/feature_flag_id.rb +2 -1
  14. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/pause_workflow_request.rb +105 -0
  15. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/pause_workflow_request_pause.rb +343 -0
  16. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/pause_workflow_request_unpause.rb +262 -0
  17. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/tenant_invite.rb +11 -1
  18. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/tenant_member.rb +11 -1
  19. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/tenant_member_role.rb +2 -1
  20. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/update_tenant_invite_request.rb +14 -4
  21. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/update_tenant_member_request.rb +14 -4
  22. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_create_http_operator_request.rb +346 -0
  23. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_event.rb +14 -4
  24. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_http_operator.rb +372 -0
  25. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_http_operator_list.rb +231 -0
  26. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_task_summary.rb +14 -4
  27. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_update_http_operator_request.rb +252 -0
  28. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_workflow_run.rb +14 -4
  29. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/worker.rb +24 -4
  30. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/workflow.rb +43 -1
  31. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/workflow_pause_scheduled_cron_run_queue_behavior.rb +40 -0
  32. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/workflow_update_request.rb +7 -8
  33. data/lib/hatchet/clients/rest/lib/hatchet-sdk-rest.rb +9 -0
  34. data/lib/hatchet/concurrency.rb +85 -18
  35. data/lib/hatchet/context.rb +5 -2
  36. data/lib/hatchet/contracts/v1/workflows_pb.rb +1 -1
  37. data/lib/hatchet/durable_context.rb +5 -12
  38. data/lib/hatchet/features/cel.rb +2 -2
  39. data/lib/hatchet/features/cron.rb +5 -5
  40. data/lib/hatchet/features/events.rb +7 -7
  41. data/lib/hatchet/features/filters.rb +7 -7
  42. data/lib/hatchet/features/logs.rb +2 -2
  43. data/lib/hatchet/features/metrics.rb +6 -6
  44. data/lib/hatchet/features/rate_limits.rb +2 -2
  45. data/lib/hatchet/features/runs.rb +4 -5
  46. data/lib/hatchet/features/scheduled.rb +7 -7
  47. data/lib/hatchet/features/tenant.rb +2 -2
  48. data/lib/hatchet/features/workers.rb +5 -5
  49. data/lib/hatchet/features/workflows.rb +6 -6
  50. data/lib/hatchet/version.rb +1 -1
  51. data/lib/hatchet/workflow.rb +58 -33
  52. data/lib/hatchet-sdk.rb +65 -32
  53. data/sig/hatchet/concurrency.rbs +12 -2
  54. metadata +11 -2
@@ -8,10 +8,10 @@ module Hatchet
8
8
  # updating workers in the Hatchet system.
9
9
  #
10
10
  # @example Getting a worker
11
- # worker = workers_client.get("worker-id")
11
+ # worker = hatchet.workers.get("worker-id")
12
12
  #
13
13
  # @example Listing all workers
14
- # workers = workers_client.list
14
+ # workers = hatchet.workers.list
15
15
  #
16
16
  # @since 0.1.0
17
17
  class Workers
@@ -33,7 +33,7 @@ module Hatchet
33
33
  # @return [Object] The worker details
34
34
  # @raise [HatchetSdkRest::ApiError] If the API request fails
35
35
  # @example
36
- # worker = workers_client.get("worker-123")
36
+ # worker = hatchet.workers.get("worker-123")
37
37
  def get(worker_id)
38
38
  @worker_api.worker_get(worker_id)
39
39
  end
@@ -43,7 +43,7 @@ module Hatchet
43
43
  # @return [Object] A list of workers
44
44
  # @raise [HatchetSdkRest::ApiError] If the API request fails
45
45
  # @example
46
- # workers = workers_client.list
46
+ # workers = hatchet.workers.list
47
47
  def list
48
48
  @worker_api.worker_list(@config.tenant_id)
49
49
  end
@@ -55,7 +55,7 @@ module Hatchet
55
55
  # @return [Object] The updated worker
56
56
  # @raise [HatchetSdkRest::ApiError] If the API request fails
57
57
  # @example
58
- # updated = workers_client.update("worker-123", { is_paused: true })
58
+ # updated = hatchet.workers.update("worker-123", { is_paused: true })
59
59
  def update(worker_id, opts)
60
60
  update_request = HatchetSdkRest::UpdateWorkerRequest.new(opts)
61
61
  @worker_api.worker_update(worker_id, update_request)
@@ -8,10 +8,10 @@ module Hatchet
8
8
  # If you're looking for runs, use the Runs client instead.
9
9
  #
10
10
  # @example Getting a workflow
11
- # workflow = workflows_client.get("workflow-id")
11
+ # workflow = hatchet.workflows.get("workflow-id")
12
12
  #
13
13
  # @example Listing workflows
14
- # workflows = workflows_client.list(workflow_name: "my-workflow", limit: 10)
14
+ # workflows = hatchet.workflows.list(workflow_name: "my-workflow", limit: 10)
15
15
  #
16
16
  # @since 0.1.0
17
17
  class Workflows
@@ -33,7 +33,7 @@ module Hatchet
33
33
  # @return [Object] The workflow details
34
34
  # @raise [HatchetSdkRest::ApiError] If the API request fails
35
35
  # @example
36
- # workflow = workflows_client.get("workflow-123")
36
+ # workflow = hatchet.workflows.get("workflow-123")
37
37
  def get(workflow_id)
38
38
  @workflow_api.workflow_get(workflow_id)
39
39
  end
@@ -46,7 +46,7 @@ module Hatchet
46
46
  # @return [Object] A list of workflows
47
47
  # @raise [HatchetSdkRest::ApiError] If the API request fails
48
48
  # @example
49
- # workflows = workflows_client.list(workflow_name: "my-workflow", limit: 10, offset: 0)
49
+ # workflows = hatchet.workflows.list(workflow_name: "my-workflow", limit: 10, offset: 0)
50
50
  def list(workflow_name: nil, limit: nil, offset: nil)
51
51
  @workflow_api.workflow_list(
52
52
  @config.tenant_id,
@@ -65,7 +65,7 @@ module Hatchet
65
65
  # @return [Object] The workflow version
66
66
  # @raise [HatchetSdkRest::ApiError] If the API request fails
67
67
  # @example
68
- # version = workflows_client.get_version("workflow-123", version: "v2")
68
+ # version = hatchet.workflows.get_version("workflow-123", version: "v2")
69
69
  def get_version(workflow_id, version: nil)
70
70
  @workflow_api.workflow_version_get(workflow_id, { version: version })
71
71
  end
@@ -78,7 +78,7 @@ module Hatchet
78
78
  # @return [void]
79
79
  # @raise [HatchetSdkRest::ApiError] If the API request fails
80
80
  # @example
81
- # workflows_client.delete("workflow-123")
81
+ # hatchet.workflows.delete("workflow-123")
82
82
  def delete(workflow_id)
83
83
  @workflow_api.workflow_delete(workflow_id)
84
84
  end
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Hatchet
4
- VERSION = "0.6.0"
4
+ VERSION = "0.8.0"
5
5
  end
@@ -98,10 +98,23 @@ module Hatchet
98
98
  @id ||= resolve_workflow_id
99
99
  end
100
100
 
101
- # Define a task within this workflow
101
+ # Define a task within this workflow. The block receives the workflow input
102
+ # and a {Context} object, and its return value (a Hash) becomes the task
103
+ # output.
102
104
  #
103
- # @param name [Symbol, String] Task name
104
- # @param opts [Hash] Task options (parents:, execution_timeout:, retries:, etc.)
105
+ # @param name [Symbol, String] The name of the task
106
+ # @option opts [Array<Task, Symbol>] :parents ([]) A list of tasks that are parents of the task. Note: parents must be defined before their children
107
+ # @option opts [Integer, String, nil] :execution_timeout (nil) The maximum time to wait for the task to complete, in seconds or as a duration string (e.g. "60s")
108
+ # @option opts [Integer, String, nil] :schedule_timeout (nil) The maximum time to wait for the task to be scheduled
109
+ # @option opts [Integer, nil] :retries (nil) The number of times to retry the task before failing
110
+ # @option opts [Float, nil] :backoff_factor (nil) The backoff factor for controlling exponential backoff in retries
111
+ # @option opts [Integer, nil] :backoff_max_seconds (nil) The maximum number of seconds to allow retries with exponential backoff to continue
112
+ # @option opts [Array<RateLimit>] :rate_limits ([]) A list of rate limit configurations for the task
113
+ # @option opts [ConcurrencyExpression, Array<ConcurrencyExpression>, nil] :concurrency (nil) A concurrency expression (or list of them) controlling the concurrency settings for this task
114
+ # @option opts [Hash, nil] :desired_worker_labels (nil) A hash of desired worker labels that determine to which worker the task should be assigned
115
+ # @option opts [Array] :wait_for ([]) A list of conditions that must be met before the task can run
116
+ # @option opts [Array] :skip_if ([]) A list of conditions that, if met, will cause the task to be skipped
117
+ # @option opts [Hash, nil] :deps (nil) Dependency providers to inject into the task's context
105
118
  # @yield [input, ctx] The task execution block
106
119
  # @return [Task] The created task
107
120
  def task(name, **opts, &)
@@ -238,55 +251,65 @@ module Hatchet
238
251
  ::V1::CreateWorkflowVersionRequest.new(**args)
239
252
  end
240
253
 
241
- # Run this workflow synchronously
254
+ # Run this workflow synchronously and wait for it to complete.
242
255
  #
243
- # @param input [Hash] Workflow input
244
- # @param options [TriggerWorkflowOptions, nil] Trigger options
245
- # @return [Hash] The workflow run output
256
+ # @param input [Hash] The input data for the workflow
257
+ # @param options [TriggerWorkflowOptions, nil] Additional options for workflow execution, such as +additional_metadata:+ and +priority:+
258
+ # @return [Hash] The workflow run output, keyed by task name (e.g. `{"step1" => {...}, "step2" => {...}}`)
259
+ # @raise [Hatchet::Error] If no client is associated with the workflow
260
+ # @raise [Hatchet::FailedRunError] If the workflow run failed
246
261
  def run(input = {}, options: nil)
247
262
  raise Error, "No client associated with workflow #{@name}" unless @client
248
263
 
249
264
  @client.admin.trigger_workflow(self, input, options: options)
250
265
  end
251
266
 
252
- # Run this workflow without waiting for the result
267
+ # Trigger a workflow run without waiting for it to complete. Useful for
268
+ # starting a run and immediately returning a reference to it without
269
+ # blocking while the workflow runs.
253
270
  #
254
- # @param input [Hash] Workflow input
255
- # @param options [TriggerWorkflowOptions, nil] Trigger options
256
- # @return [WorkflowRunRef]
271
+ # @param input [Hash] The input data for the workflow
272
+ # @param options [TriggerWorkflowOptions, nil] Additional options for workflow execution
273
+ # @return [WorkflowRunRef] A reference to the workflow run, whose +result+ method blocks until the run completes
274
+ # @raise [Hatchet::Error] If no client is associated with the workflow
257
275
  def run_no_wait(input = {}, options: nil)
258
276
  raise Error, "No client associated with workflow #{@name}" unless @client
259
277
 
260
278
  @client.admin.trigger_workflow_no_wait(self, input, options: options)
261
279
  end
262
280
 
263
- # Run many instances of this workflow in bulk
281
+ # Run this workflow in bulk and wait for all runs to complete. Runs are
282
+ # triggered via bulk gRPC triggering (batched by 1000) and results are
283
+ # collected concurrently.
264
284
  #
265
- # @param items [Array<Hash>] Bulk run items
266
- # @param return_exceptions [Boolean] Return exceptions instead of raising
267
- # @return [Array] Results
285
+ # @param items [Array<Hash>] A list of bulk run items, as created by {#create_bulk_run_item}
286
+ # @param return_exceptions [Boolean] If +true+, exceptions are returned as part of the results instead of being raised
287
+ # @return [Array] A list of results for each workflow run
288
+ # @raise [Hatchet::Error] If no client is associated with the workflow
268
289
  def run_many(items, return_exceptions: false)
269
290
  raise Error, "No client associated with workflow #{@name}" unless @client
270
291
 
271
292
  @client.admin.trigger_workflow_many(self, items, return_exceptions: return_exceptions)
272
293
  end
273
294
 
274
- # Run many instances without waiting for results
295
+ # Run this workflow in bulk without waiting for the runs to complete.
275
296
  #
276
- # @param items [Array<Hash>] Bulk run items
277
- # @return [Array<WorkflowRunRef>]
297
+ # @param items [Array<Hash>] A list of bulk run items, as created by {#create_bulk_run_item}
298
+ # @return [Array<WorkflowRunRef>] A list of references to the triggered workflow runs
299
+ # @raise [Hatchet::Error] If no client is associated with the workflow
278
300
  def run_many_no_wait(items)
279
301
  raise Error, "No client associated with workflow #{@name}" unless @client
280
302
 
281
303
  @client.admin.trigger_workflow_many_no_wait(self, items)
282
304
  end
283
305
 
284
- # Create a bulk run item for use with run_many
306
+ # Create a bulk run item for this workflow, intended to be used with the
307
+ # {#run_many} methods.
285
308
  #
286
- # @param input [Hash] Input data
287
- # @param key [String, nil] Deduplication key
288
- # @param options [TriggerWorkflowOptions, nil] Trigger options
289
- # @return [Hash] Bulk run item
309
+ # @param input [Hash] The input data for the workflow
310
+ # @param key [String, nil] The key for the workflow run, used for identification and deduplication
311
+ # @param options [TriggerWorkflowOptions, nil] Additional options for the workflow run
312
+ # @return [Hash] A bulk run item that can be passed to the +run_many+ methods
290
313
  def create_bulk_run_item(input: {}, key: nil, options: nil)
291
314
  item = { input: input }
292
315
  item[:key] = key if key
@@ -294,24 +317,26 @@ module Hatchet
294
317
  item
295
318
  end
296
319
 
297
- # Schedule this workflow for future execution
320
+ # Schedule this workflow to run at a specific time.
298
321
  #
299
- # @param time [Time] When to execute
300
- # @param input [Hash] Workflow input
301
- # @param options [ScheduleTriggerWorkflowOptions, nil] Schedule options
302
- # @return [Object] Schedule result
322
+ # @param time [Time] When to execute the workflow
323
+ # @param input [Hash] The input data for the workflow
324
+ # @param options [ScheduleTriggerWorkflowOptions, nil] Additional schedule options
325
+ # @return [Object] The schedule response from the Hatchet engine
326
+ # @raise [Hatchet::Error] If no client is associated with the workflow
303
327
  def schedule(time, input: {}, options: nil)
304
328
  raise Error, "No client associated with workflow #{@name}" unless @client
305
329
 
306
330
  @client.admin.schedule_workflow(self, time, input: input, options: options)
307
331
  end
308
332
 
309
- # Create a cron trigger for this workflow
333
+ # Create a cron trigger for this workflow.
310
334
  #
311
- # @param cron_name [String] Name for the cron
312
- # @param expression [String] Cron expression
313
- # @param input [Hash] Workflow input
314
- # @return [Object] Cron result
335
+ # @param cron_name [String] The name of the cron job
336
+ # @param expression [String] The cron expression that defines the schedule
337
+ # @param input [Hash] The input data for the workflow
338
+ # @return [Object] The created cron workflow trigger
339
+ # @raise [Hatchet::Error] If no client is associated with the workflow
315
340
  def create_cron(cron_name, expression, input: {})
316
341
  raise Error, "No client associated with workflow #{@name}" unless @client
317
342
 
data/lib/hatchet-sdk.rb CHANGED
@@ -113,83 +113,103 @@ module Hatchet
113
113
  @rest_client ||= Hatchet::Clients.rest_client(@config)
114
114
  end
115
115
 
116
- # Feature Client for interacting with Hatchet events
116
+ # The events client, which you can use to push events to Hatchet to trigger
117
+ # event-driven workflows.
117
118
  # @return [Hatchet::Features::Events]
118
119
  def events
119
120
  @events ||= Hatchet::Features::Events.new(rest_client, event_grpc, @config)
120
121
  end
121
122
 
122
- # Feature Client for interacting with Hatchet workflow runs
123
+ # The runs client is a client for interacting with task and workflow runs
124
+ # within Hatchet.
123
125
  # @return [Hatchet::Features::Runs]
124
126
  def runs
125
127
  @runs ||= Hatchet::Features::Runs.new(rest_client, @config, client: self)
126
128
  end
127
129
 
128
- # Feature Client for interacting with the current tenant
130
+ # The tenant client is a client for reading information about the tenant
131
+ # you're operating in.
129
132
  # @return [Hatchet::Features::Tenant]
130
133
  def tenant
131
134
  @tenant ||= Hatchet::Features::Tenant.new(rest_client, @config)
132
135
  end
133
136
 
134
- # Feature Client for interacting with Hatchet logs
137
+ # The logs client is a client for interacting with Hatchet's logs API.
135
138
  # @return [Hatchet::Features::Logs]
136
139
  def logs
137
140
  @logs ||= Hatchet::Features::Logs.new(rest_client, @config)
138
141
  end
139
142
 
140
- # Feature Client for managing workers
143
+ # The workers client is a client for managing workers programmatically
144
+ # within Hatchet.
141
145
  # @return [Hatchet::Features::Workers]
142
146
  def workers
143
147
  @workers ||= Hatchet::Features::Workers.new(rest_client, @config)
144
148
  end
145
149
 
146
- # Feature Client for debugging CEL expressions
150
+ # The CEL client is a client for debugging CEL expressions within Hatchet.
147
151
  # @return [Hatchet::Features::CEL]
148
152
  def cel
149
153
  @cel ||= Hatchet::Features::CEL.new(rest_client, @config)
150
154
  end
151
155
 
152
- # Feature Client for managing workflow definitions
156
+ # The workflows client is a client for managing workflow declarations
157
+ # programmatically within Hatchet. Note that workflows are the declaration,
158
+ # _not_ the individual runs; if you're looking for runs, use the runs
159
+ # client instead.
153
160
  # @return [Hatchet::Features::Workflows]
154
161
  def workflows
155
162
  @workflows ||= Hatchet::Features::Workflows.new(rest_client, @config)
156
163
  end
157
164
 
158
- # Feature Client for managing filters
165
+ # The filters client is a client for managing filters within Hatchet, which
166
+ # scope event triggers to workflows using CEL expressions.
159
167
  # @return [Hatchet::Features::Filters]
160
168
  def filters
161
169
  @filters ||= Hatchet::Features::Filters.new(rest_client, @config)
162
170
  end
163
171
 
164
- # Feature Client for reading metrics
172
+ # The metrics client is a client for reading metrics out of Hatchet's
173
+ # metrics API.
165
174
  # @return [Hatchet::Features::Metrics]
166
175
  def metrics
167
176
  @metrics ||= Hatchet::Features::Metrics.new(rest_client, @config)
168
177
  end
169
178
 
170
- # Feature Client for managing rate limits
179
+ # The rate limits client is a wrapper for Hatchet's gRPC API that makes it
180
+ # easier to work with rate limits in Hatchet.
171
181
  # @return [Hatchet::Features::RateLimits]
172
182
  def rate_limits
173
183
  @rate_limits ||= Hatchet::Features::RateLimits.new(admin_grpc, @config)
174
184
  end
175
185
 
176
- # Feature Client for managing cron workflows
186
+ # The cron client is a client for managing cron workflow triggers within
187
+ # Hatchet.
177
188
  # @return [Hatchet::Features::Cron]
178
189
  def cron
179
190
  @cron ||= Hatchet::Features::Cron.new(rest_client, @config)
180
191
  end
181
192
 
182
- # Feature Client for managing scheduled workflows
193
+ # The scheduled client is a client for managing scheduled workflow runs
194
+ # within Hatchet.
183
195
  # @return [Hatchet::Features::Scheduled]
184
196
  def scheduled
185
197
  @scheduled ||= Hatchet::Features::Scheduled.new(rest_client, @config)
186
198
  end
187
199
 
188
- # Create a new workflow definition
200
+ # Define a Hatchet workflow, which can then declare tasks and be run,
201
+ # scheduled, and so on.
189
202
  #
190
- # @param name [String] Workflow name
191
- # @param opts [Hash] Workflow options (on_events:, concurrency:, idempotency:, etc.)
192
- # @return [Hatchet::Workflow]
203
+ # @param name [String] The name of the workflow
204
+ # @option opts [Array<String>] :on_events ([]) A list of event triggers for the workflow - events which cause the workflow to be run
205
+ # @option opts [Array<String>] :on_crons ([]) A list of cron triggers for the workflow
206
+ # @option opts [ConcurrencyExpression, Array<ConcurrencyExpression>, nil] :concurrency (nil) A concurrency object (or list of them) controlling the concurrency settings for this workflow
207
+ # @option opts [Integer, nil] :default_priority (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
208
+ # @option opts [Hash, nil] :task_defaults (nil) Default task settings for this workflow
209
+ # @option opts [Array<DefaultFilter>] :default_filters ([]) A list of filters to create when the workflow is created
210
+ # @option opts [Symbol, nil] :sticky (nil) A sticky strategy for the workflow, either +:soft+ or +:hard+
211
+ # @option opts [TTLBasedIdempotencyConfig, StatusBasedIdempotencyConfig, nil] :idempotency (nil) An idempotency configuration for the workflow
212
+ # @return [Hatchet::Workflow] The created workflow object, which can be used to declare tasks, run the workflow, and so on
193
213
  #
194
214
  # @example
195
215
  # wf = hatchet.workflow(name: "MyWorkflow")
@@ -198,12 +218,18 @@ module Hatchet
198
218
  Workflow.new(name: name, client: self, **opts)
199
219
  end
200
220
 
201
- # Create a standalone task (auto-wraps in a single-task workflow)
221
+ # Create a standalone Hatchet task. The task is automatically wrapped in a
222
+ # single-task workflow, so it can be run, scheduled, and registered on a
223
+ # worker just like a workflow. The block receives the run's input and a
224
+ # {Context} object.
202
225
  #
203
- # @param name [String] Task name
204
- # @param opts [Hash] Task options (on_events:, idempotency:, retries:, etc.)
226
+ # @param name [String] The name of the task
227
+ # @option opts [Array<String>] :on_events ([]) A list of event triggers for the task - events which cause the task to be run
228
+ # @option opts [Array<DefaultFilter>] :default_filters ([]) A list of filters to create when the task is created
229
+ # @option opts [TTLBasedIdempotencyConfig, StatusBasedIdempotencyConfig, nil] :idempotency (nil) An idempotency configuration for the task
230
+ # @param 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
205
231
  # @yield [input, ctx] The task execution block
206
- # @return [Hatchet::Task]
232
+ # @return [Hatchet::Task] The created task object, which can be run, scheduled, and registered on a worker
207
233
  #
208
234
  # @example
209
235
  # my_task = hatchet.task(name: "my_task") { |input, ctx| { "result" => "done" } }
@@ -225,11 +251,11 @@ module Hatchet
225
251
  #
226
252
  # Preview: batch tasks are in beta and may change in future releases.
227
253
  #
228
- # @param name [String] Task name
229
- # @param batch [Hatchet::BatchTaskConfig] Batch configuration
230
- # @param opts [Hash] Task options (on_events:, idempotency:, etc.)
254
+ # @param name [String] The name of the task
255
+ # @param batch [Hatchet::BatchTaskConfig] The batch configuration (+max_size+, flush interval, +broadcast_output+)
256
+ # @param opts [Hash] Any other keyword arguments (+on_events:+, +idempotency:+, and so on) are forwarded to {#task}
231
257
  # @yield [inputs, ctx] The batch execution block, receiving a Hash of task-run external id => input
232
- # @return [Hatchet::Task]
258
+ # @return [Hatchet::Task] The created batch task object
233
259
  #
234
260
  # @example
235
261
  # batch = hatchet.batch_task(name: "my_batch", batch: Hatchet::BatchTaskConfig.new(max_size: 3)) do |inputs, ctx|
@@ -239,16 +265,18 @@ module Hatchet
239
265
  task(name: name, batch: batch, **opts, &block)
240
266
  end
241
267
 
242
- # Create a standalone durable task.
268
+ # Create a standalone _durable_ Hatchet task, which works using Hatchet's
269
+ # durable execution capabilities. Durable tasks receive a {DurableContext}
270
+ # with additional methods like +sleep_for+ and +wait_for+.
243
271
  #
244
- # @param name [String] Task name
272
+ # @param name [String] The name of the task
245
273
  # @param eviction_policy [Hatchet::EvictionPolicy, nil] Eviction policy for this
246
274
  # durable task. Defaults to {Hatchet::DEFAULT_DURABLE_TASK_EVICTION_POLICY}
247
275
  # (15-minute TTL, capacity-eviction enabled). Pass ``nil`` to disable
248
276
  # eviction entirely for this task.
249
- # @param opts [Hash] Task options
277
+ # @param 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
250
278
  # @yield [input, ctx] The task execution block
251
- # @return [Hatchet::Task]
279
+ # @return [Hatchet::Task] The created durable task object
252
280
  def durable_task(name:, eviction_policy: Hatchet::DEFAULT_DURABLE_TASK_EVICTION_POLICY, **opts, &block)
253
281
  wf = Workflow.new(name: name, client: self,
254
282
  on_events: opts.delete(:on_events) || [],
@@ -256,11 +284,16 @@ module Hatchet
256
284
  wf.durable_task(name, eviction_policy: eviction_policy, **opts, &block)
257
285
  end
258
286
 
259
- # Create a new worker
287
+ # Create a Hatchet worker on which to run workflows.
260
288
  #
261
- # @param name [String] Worker name
262
- # @param opts [Hash] Worker options (workflows:, slots:, labels:)
263
- # @return [Hatchet::Worker]
289
+ # @param name [String] The name of the worker
290
+ # @option opts [Array<Workflow, Task>] :workflows ([]) A list of workflows (or standalone tasks) to register on the worker
291
+ # @option opts [Integer] :slots (10) Slot count for standard tasks, i.e. the number of tasks the worker can run concurrently
292
+ # @option opts [Integer, nil] :durable_slots (nil) Slot count for durable tasks; defaults to +slots+ if not provided
293
+ # @option opts [Hash] :labels ({}) A hash of labels to assign to the worker, for use with worker affinity; merged with the client's +worker_preset_labels+
294
+ # @return [Hatchet::Worker] The created worker object, which exposes an instance
295
+ # method +start+ which can be called to start the worker (blocking until
296
+ # shutdown), and +stop+ to request a graceful shutdown
264
297
  #
265
298
  # @example
266
299
  # worker = hatchet.worker("my-worker", workflows: [wf], slots: 10)
@@ -4,16 +4,26 @@ module Hatchet
4
4
  CANCEL_NEWEST: Symbol
5
5
  GROUP_ROUND_ROBIN: Symbol
6
6
  QUEUE: Symbol
7
+ CANCEL_QUEUED_EXCEPT_NEWEST: Symbol
8
+ CANCEL_QUEUED_EXCEPT_OLDEST: Symbol
9
+ end
10
+
11
+ module ConcurrencyProto
12
+ LIMIT_STRATEGY_MAP: Hash[Symbol, Symbol]
13
+
14
+ def self.split_max_runs: (Integer | String max_runs) -> [Integer, String?]
7
15
  end
8
16
 
9
17
  class ConcurrencyExpression
10
18
  LIMIT_STRATEGY_MAP: Hash[Symbol, Symbol]
11
19
 
12
20
  attr_reader expression: String
13
- attr_reader max_runs: Integer
21
+ attr_reader max_runs: Integer | String
14
22
  attr_reader limit_strategy: Symbol
23
+ attr_reader name: String?
24
+ attr_reader is_tenant_scoped: bool
15
25
 
16
- def initialize: (expression: String, ?max_runs: Integer, ?limit_strategy: Symbol) -> void
26
+ def initialize: (expression: String, ?max_runs: Integer | String, ?limit_strategy: Symbol, ?name: String?, ?is_tenant_scoped: bool) -> void
17
27
  def to_h: () -> Hash[Symbol, untyped]
18
28
  def to_proto: () -> untyped
19
29
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: hatchet-sdk
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.6.0
4
+ version: 0.8.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - gabriel ruttner
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2026-07-23 00:00:00.000000000 Z
11
+ date: 2026-09-07 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: faraday
@@ -217,6 +217,7 @@ files:
217
217
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/api/log_api.rb
218
218
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/api/metadata_api.rb
219
219
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/api/observability_api.rb
220
+ - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/api/operator_api.rb
220
221
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/api/rate_limits_api.rb
221
222
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/api/slack_api.rb
222
223
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/api/sns_api.rb
@@ -291,6 +292,9 @@ files:
291
292
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/otel_span_list.rb
292
293
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/otel_status_code.rb
293
294
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/pagination_response.rb
295
+ - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/pause_workflow_request.rb
296
+ - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/pause_workflow_request_pause.rb
297
+ - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/pause_workflow_request_unpause.rb
294
298
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/pull_request.rb
295
299
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/pull_request_state.rb
296
300
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/queue_metrics.rb
@@ -374,6 +378,7 @@ files:
374
378
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_cel_debug_response.rb
375
379
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_cel_debug_response_status.rb
376
380
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_create_filter_request.rb
381
+ - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_create_http_operator_request.rb
377
382
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_create_webhook_request.rb
378
383
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_create_webhook_request_api_key.rb
379
384
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_create_webhook_request_base.rb
@@ -390,6 +395,8 @@ files:
390
395
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_event_workflow_run_summary.rb
391
396
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_filter.rb
392
397
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_filter_list.rb
398
+ - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_http_operator.rb
399
+ - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_http_operator_list.rb
393
400
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_log_line.rb
394
401
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_log_line_level.rb
395
402
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_log_line_list.rb
@@ -416,6 +423,7 @@ files:
416
423
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_task_timing_list.rb
417
424
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_trigger_workflow_run_request.rb
418
425
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_update_filter_request.rb
426
+ - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_update_http_operator_request.rb
419
427
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_update_webhook_request.rb
420
428
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_wait_item.rb
421
429
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/v1_webhook.rb
@@ -454,6 +462,7 @@ files:
454
462
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/workflow_kind.rb
455
463
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/workflow_list.rb
456
464
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/workflow_metrics.rb
465
+ - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/workflow_pause_scheduled_cron_run_queue_behavior.rb
457
466
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/workflow_run.rb
458
467
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/workflow_run_list.rb
459
468
  - lib/hatchet/clients/rest/lib/hatchet-sdk-rest/models/workflow_run_order_by_direction.rb