zizq 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 (38) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +82 -11
  3. data/lib/active_job/queue_adapters/zizq_adapter.rb +4 -23
  4. data/lib/zizq/bulk_enqueue.rb +61 -14
  5. data/lib/zizq/client.rb +580 -77
  6. data/lib/zizq/crontab.rb +36 -3
  7. data/lib/zizq/crontab_builder.rb +10 -1
  8. data/lib/zizq/crontab_entry_builder.rb +66 -14
  9. data/lib/zizq/enqueue_request.rb +22 -21
  10. data/lib/zizq/enqueue_with.rb +65 -8
  11. data/lib/zizq/error.rb +10 -0
  12. data/lib/zizq/job_config.rb +95 -12
  13. data/lib/zizq/query.rb +111 -39
  14. data/lib/zizq/resources/budget.rb +109 -0
  15. data/lib/zizq/resources/cron_group.rb +4 -0
  16. data/lib/zizq/resources/job.rb +108 -2
  17. data/lib/zizq/resources/job_template.rb +15 -0
  18. data/lib/zizq/resources.rb +1 -0
  19. data/lib/zizq/test/client.rb +6 -3
  20. data/lib/zizq/version.rb +1 -1
  21. data/lib/zizq.rb +191 -14
  22. data/sig/generated/zizq/bulk_enqueue.rbs +4 -16
  23. data/sig/generated/zizq/client.rbs +377 -8
  24. data/sig/generated/zizq/crontab.rbs +17 -1
  25. data/sig/generated/zizq/crontab_builder.rbs +9 -0
  26. data/sig/generated/zizq/crontab_entry_builder.rbs +4 -17
  27. data/sig/generated/zizq/enqueue_request.rbs +11 -4
  28. data/sig/generated/zizq/enqueue_with.rbs +4 -9
  29. data/sig/generated/zizq/error.rbs +10 -0
  30. data/sig/generated/zizq/job_config.rbs +65 -0
  31. data/sig/generated/zizq/query.rbs +79 -2
  32. data/sig/generated/zizq/resources/budget.rbs +97 -0
  33. data/sig/generated/zizq/resources/cron_group.rbs +3 -0
  34. data/sig/generated/zizq/resources/job.rbs +94 -0
  35. data/sig/generated/zizq/resources/job_template.rbs +11 -0
  36. data/sig/generated/zizq.rbs +111 -33
  37. data/sig/zizq.rbs +100 -7
  38. metadata +4 -2
data/lib/zizq/query.rb CHANGED
@@ -71,6 +71,7 @@ module Zizq
71
71
  priority: nil,
72
72
  ready_at: nil,
73
73
  attempts: nil,
74
+ budgets_key: nil,
74
75
  order: nil,
75
76
  limit: nil,
76
77
  page_size: nil
@@ -83,6 +84,7 @@ module Zizq
83
84
  @priority = priority
84
85
  @ready_at = ready_at
85
86
  @attempts = attempts
87
+ @budgets_key = budgets_key
86
88
  @order = order
87
89
  @limit = limit
88
90
  @page_size = page_size
@@ -164,6 +166,24 @@ module Zizq
164
166
  rebuild(status: Array(@status) + Array(status))
165
167
  end
166
168
 
169
+ # Filter by budget (replaces any existing budget filter).
170
+ #
171
+ # Matches a job bound to any of the specified budgets.
172
+ #
173
+ # @rbs budgets_key: (String | Array[String])
174
+ # @rbs return: Query
175
+ def by_budgets_key(budgets_key)
176
+ rebuild(budgets_key:)
177
+ end
178
+
179
+ # Add a budget to the existing budget filter.
180
+ #
181
+ # @rbs budgets_key: String | Array[String]
182
+ # @rbs return: Query
183
+ def add_budgets_key(budgets_key)
184
+ rebuild(budgets_key: Array(@budgets_key) + Array(budgets_key))
185
+ end
186
+
167
187
  # Filter by priority range (replaces any existing priority filter).
168
188
  #
169
189
  # Accepts an Integer (exact match) or an inclusive Range. Lower numbers
@@ -371,17 +391,7 @@ module Zizq
371
391
  def count(*args, &block)
372
392
  return super if block || !args.empty?
373
393
 
374
- total =
375
- Zizq.client.count_jobs(
376
- id: @id,
377
- queue: @queue,
378
- type: @type,
379
- status: @status,
380
- filter: @jq_filter,
381
- priority: @priority,
382
- ready_at: @ready_at,
383
- attempts: @attempts
384
- )
394
+ total = Zizq.client.count_jobs(**filters)
385
395
 
386
396
  @limit ? [total, @limit].min : total
387
397
  end
@@ -450,6 +460,70 @@ module Zizq
450
460
  limit(1).delete_all
451
461
  end
452
462
 
463
+ # Bind every matching job to a budget, skipping over the ones already
464
+ # bound to it.
465
+ #
466
+ # Only queued (`scheduled`, `ready`) jobs can be rebound, so the result
467
+ # provides any that were in flight and were blocked — see the
468
+ # `Zizq::bulk_budget_change` type.
469
+ #
470
+ # @rbs key: String
471
+ # @rbs cost: Integer?
472
+ # @rbs create_with: Zizq::budget_policy?
473
+ # @rbs return: Zizq::bulk_budget_change
474
+ def bind_budget(key, cost: nil, create_with: nil)
475
+ Zizq.client.add_all_jobs_budget(key, where: filters, cost:, create_with:)
476
+ end
477
+
478
+ # Bind every matching job to a budget, replacing any existing
479
+ # binding to it.
480
+ #
481
+ # The binding is replaced whole, so a `cost` left unset returns to
482
+ # the default of 1 rather than keeping what was there.
483
+ #
484
+ # @rbs key: String
485
+ # @rbs cost: Integer?
486
+ # @rbs create_with: Zizq::budget_policy?
487
+ # @rbs return: Zizq::bulk_budget_change
488
+ def rebind_budget(key, cost: nil, create_with: nil)
489
+ Zizq.client.put_all_jobs_budget(key, where: filters, cost:, create_with:)
490
+ end
491
+
492
+ # Change what an existing binding costs, leaving the binding itself
493
+ # alone. Matching jobs not bound to this budget are skipped.
494
+ #
495
+ # @rbs key: String
496
+ # @rbs cost: Integer
497
+ # @rbs return: Zizq::bulk_budget_change
498
+ def set_budget_cost(key, cost)
499
+ Zizq.client.update_all_jobs_budget(key, cost:, where: filters)
500
+ end
501
+
502
+ # Unbind one budget from every matching job, leaving their other
503
+ # budgets alone.
504
+ #
505
+ # Paired with `by_budgets_key` this can be used to remove a budget
506
+ # binding from existing jobs before deleting the budget itself:
507
+ #
508
+ # Zizq.query.by_budgets_key("emails").unbind_budget("emails")
509
+ # Zizq.delete_budget("emails")
510
+ #
511
+ # @rbs key: String
512
+ # @rbs return: Zizq::bulk_budget_change
513
+ def unbind_budget(key)
514
+ Zizq.client.delete_all_jobs_budget(key, where: filters)
515
+ end
516
+
517
+ # Unbind *every* budget from every matching job.
518
+ #
519
+ # Beware: on an unfiltered query this unbinds every budget from
520
+ # every job on the server, reverting all jobs back to regular jobs.
521
+ #
522
+ # @rbs return: Zizq::bulk_budget_change
523
+ def unbind_all_budgets
524
+ Zizq.client.clear_all_jobs_budgets(where: filters)
525
+ end
526
+
453
527
  # Iterate over matching jobs, lazily paginating through results.
454
528
  #
455
529
  # Respects `limit` if set. Without a block, returns an `Enumerator`.
@@ -494,14 +568,7 @@ module Zizq
494
568
  if block_given?
495
569
  page =
496
570
  Zizq.client.list_jobs(
497
- id: @id,
498
- queue: @queue,
499
- type: @type,
500
- status: @status,
501
- filter: @jq_filter,
502
- priority: @priority,
503
- ready_at: @ready_at,
504
- attempts: @attempts,
571
+ **filters,
505
572
  limit: [
506
573
  @page_size,
507
574
  @limit,
@@ -551,16 +618,7 @@ module Zizq
551
618
  backoff: Zizq::UNCHANGED,
552
619
  retention: Zizq::UNCHANGED
553
620
  )
554
- where = {
555
- id: @id,
556
- queue: @queue,
557
- type: @type,
558
- status: @status,
559
- filter: @jq_filter,
560
- priority: @priority,
561
- ready_at: @ready_at,
562
- attempts: @attempts
563
- }
621
+ where = filters
564
622
 
565
623
  apply = {
566
624
  queue:,
@@ -612,16 +670,7 @@ module Zizq
612
670
  #
613
671
  # @rbs return: Integer
614
672
  def delete_all
615
- where = {
616
- id: @id,
617
- queue: @queue,
618
- type: @type,
619
- status: @status,
620
- filter: @jq_filter,
621
- priority: @priority,
622
- ready_at: @ready_at,
623
- attempts: @attempts
624
- }
673
+ where = filters
625
674
 
626
675
  if @limit || @page_size
627
676
  remaining = @limit
@@ -649,6 +698,27 @@ module Zizq
649
698
 
650
699
  private
651
700
 
701
+ # The filter arguments this query represents, as `Client` takes them.
702
+ #
703
+ # One definition rather than four: `count`, `each_page`,
704
+ # `update_all` and `delete_all` all send the same filter, and one
705
+ # added to only some of them silently widens the rest.
706
+ #
707
+ # @rbs return: Zizq::where_params
708
+ def filters
709
+ {
710
+ id: @id,
711
+ queue: @queue,
712
+ type: @type,
713
+ status: @status,
714
+ filter: @jq_filter,
715
+ priority: @priority,
716
+ ready_at: @ready_at,
717
+ attempts: @attempts,
718
+ budgets_key: @budgets_key
719
+ }
720
+ end
721
+
652
722
  # Build a new Query with the given overrides, preserving all other fields.
653
723
  #
654
724
  # @rbs return: Query
@@ -661,6 +731,7 @@ module Zizq
661
731
  priority: @priority,
662
732
  ready_at: @ready_at,
663
733
  attempts: @attempts,
734
+ budgets_key: @budgets_key,
664
735
  order: @order,
665
736
  limit: @limit,
666
737
  page_size: @page_size
@@ -674,6 +745,7 @@ module Zizq
674
745
  priority:,
675
746
  ready_at:,
676
747
  attempts:,
748
+ budgets_key:,
677
749
  limit:,
678
750
  order:,
679
751
  page_size:
@@ -0,0 +1,109 @@
1
+ # Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
2
+ # Licensed under the MIT License. See LICENSE file for details.
3
+
4
+ # rbs_inline: enabled
5
+ # frozen_string_literal: true
6
+
7
+ module Zizq
8
+ module Resources
9
+ # Typed wrapper around a budget response hash.
10
+ #
11
+ # A budget is a named token bucket that jobs draw from. Its strategy
12
+ # decides how tokens are managed: on a clock (`time_based`, a rate
13
+ # limit) or when a job stops running (`while_in_flight`, a
14
+ # concurrency limit, of which a mutex is the allocation = 1 case).
15
+ class Budget < Resource
16
+ # The budget's key, unique across the server.
17
+ def key = @data["key"] #: () -> String
18
+
19
+ # Tokens the budget makes available.
20
+ #
21
+ # For a `time_based` budget, how many tokens can be spent over its
22
+ # `duration`. For a `while_in_flight` budgets how many jobs may run
23
+ # at once.
24
+ def allocation = @data["allocation"] #: () -> Integer
25
+
26
+ def created_at = ms_to_seconds(@data["created_at"]) #: () -> Float?
27
+ def updated_at = ms_to_seconds(@data["updated_at"]) #: () -> Float?
28
+
29
+ # `:time_based` or `:while_in_flight`.
30
+ def strategy_type = strategy[:type] #: () -> Zizq::budget_strategy_type
31
+
32
+ def time_based? = strategy_type == :time_based #: () -> bool
33
+ def while_in_flight? = strategy_type == :while_in_flight #: () -> bool
34
+
35
+ # Period over which the whole allocation replenishes, in seconds.
36
+ #
37
+ # Tokens accrue using a continuous drip (leaky bucket) such that an
38
+ # empty bucket is full after this duration has elapsed, and is half
39
+ # full after half of the duration has elapsed, etc.
40
+ #
41
+ # `nil` for a `while_in_flight` budget.
42
+ def duration = strategy[:duration] #: () -> Float?
43
+
44
+ # Max tokens the bucket may hold at once, or `nil` when it holds
45
+ # a whole allocation.
46
+ #
47
+ # A newly created bucket starts full, so a budget with no burst set
48
+ # hands out an entire allocation the moment work arrives and only
49
+ # then settles to its continuous drip rate — `10` per minute really
50
+ # does permit twenty in the first minute. Setting a burst caps that
51
+ # spike without changing the long-run rate; a burst of `1` paces
52
+ # dispatches evenly at all times. The burst rule also applies to
53
+ # budgets that have not been consumed for an entire duration's worth
54
+ # of time.
55
+ #
56
+ # It is valid for `burst` to be set higher than the `allocation`. In
57
+ # this case the meaning is to continue filling the bucket after the
58
+ # duration has elapsed, so a `burst` of 200 on a 100 token allocation
59
+ # would continue accruing across two consecutive periods, but no more
60
+ # than that.
61
+ #
62
+ # This is designed to allow applications to absorb short-lived
63
+ # spikes.
64
+ #
65
+ # `nil` for a `while_in_flight` budget.
66
+ def burst = strategy[:burst] #: () -> Integer?
67
+
68
+ # Most tokens the bucket can hold, which is what a job's cost has
69
+ # to fit inside.
70
+ #
71
+ # The burst where one is set, and the allocation otherwise. Worth
72
+ # distinguishing from `allocation`: with a burst set it is the
73
+ # *smaller* number that decides whether a job can ever be
74
+ # afforded, so a cost well within the allocation may still be
75
+ # refused.
76
+ def capacity #: () -> Integer
77
+ burst || allocation
78
+ end
79
+
80
+ # The whole strategy, in the form `create_budget` and `put_budget`
81
+ # take it.
82
+ #
83
+ # budget = client.get_budget("emails")
84
+ # client.put_budget(
85
+ # "emails",
86
+ # allocation: budget.allocation * 2,
87
+ # strategy: budget.strategy
88
+ # )
89
+ #
90
+ # When absent, `burst` is omitted rather than sent as `nil`, since
91
+ # an absent burst and one explicitly cleared mean the same thing.
92
+ def strategy #: () -> Zizq::budget_strategy
93
+ @strategy ||= {
94
+ type: raw_strategy["type"]&.to_sym,
95
+ duration: ms_to_seconds(raw_strategy["duration_ms"]),
96
+ burst: raw_strategy["burst"]
97
+ }.compact #: Zizq::budget_strategy
98
+ end
99
+
100
+ private
101
+
102
+ # The strategy exactly as the server sent it — string keys, and
103
+ # the period in milliseconds under `duration_ms`.
104
+ def raw_strategy #: () -> Hash[String, untyped]
105
+ @data["strategy"] || {}
106
+ end
107
+ end
108
+ end
109
+ end
@@ -11,6 +11,10 @@ module Zizq
11
11
  def name = @data["name"] #: () -> String
12
12
  def paused = @data["paused"] #: () -> bool
13
13
  def paused? = paused #: () -> bool
14
+
15
+ # IANA timezone applied to entries that do not specify their own.
16
+ def timezone = @data["timezone"] #: () -> String?
17
+
14
18
  def paused_at = ms_to_seconds(@data["paused_at"]) #: () -> Float?
15
19
  def resumed_at = ms_to_seconds(@data["resumed_at"]) #: () -> Float?
16
20
 
@@ -99,9 +99,115 @@ module Zizq
99
99
  retention:
100
100
  )
101
101
 
102
- # Make sure this job's fields are updated.
103
- @data.merge!(job.to_h)
102
+ refresh_from(job)
103
+ end
104
+
105
+ # Bind this job to a budget it is not already bound to.
106
+ #
107
+ # Requires a Pro license on the server, else raise `Zizq::ClientError`
108
+ # for the server's 403 response.
109
+ #
110
+ # Raises a `Zizq::ConflictError` (409) if it is already bound to this
111
+ # budget, leaving the existing binding untouched — use
112
+ # `rebind_budget` to replace it, or `set_budget_cost` to change
113
+ # only what it costs.
114
+ #
115
+ # `create_with` declares the budget's policy should it not exist
116
+ # yet, binding and creating in one atomic call. It is ignored when
117
+ # the budget already exists.
118
+ #
119
+ # Only queued (`scheduled`, `ready`) jobs may be rebound. Anything
120
+ # else raises `Zizq::ClientError` (422).
121
+ #
122
+ # Returns the updated job, and refreshes this one.
123
+ #
124
+ # @rbs key: String
125
+ # @rbs cost: Integer?
126
+ # @rbs create_with: Zizq::budget_policy?
127
+ # @rbs return: Job
128
+ def bind_budget(key, cost: nil, create_with: nil)
129
+ refresh_from(@client.add_job_budget(id, key, cost:, create_with:))
130
+ end
131
+
132
+ # Bind this job to a budget, replacing any existing binding to it.
133
+ #
134
+ # Requires a Pro license on the server, else raise `Zizq::ClientError`
135
+ # for the server's 403 response.
136
+ #
137
+ # Unlike `bind_budget` this never conflicts. The binding is
138
+ # replaced whole, so a `cost` left unset returns to the default of
139
+ # 1 rather than keeping what was there.
140
+ #
141
+ # @rbs key: String
142
+ # @rbs cost: Integer?
143
+ # @rbs create_with: Zizq::budget_policy?
144
+ # @rbs return: Job
145
+ def rebind_budget(key, cost: nil, create_with: nil)
146
+ refresh_from(@client.put_job_budget(id, key, cost:, create_with:))
147
+ end
148
+
149
+ # Change what an existing binding costs, leaving the binding
150
+ # itself alone.
151
+ #
152
+ # Raises `Zizq::NotFoundError` if this job is not bound to the
153
+ # budget. Raises a `Zizq::ClientError` (422) if the new cost exceeds
154
+ # the budget's capacity.
155
+ #
156
+ # @rbs key: String
157
+ # @rbs cost: Integer
158
+ # @rbs return: Job
159
+ def set_budget_cost(key, cost)
160
+ refresh_from(@client.update_job_budget(id, key, cost:))
161
+ end
162
+
163
+ # Unbind one budget, leaving this job's other budgets alone.
164
+ #
165
+ # Raises `Zizq::NotFoundError` if it is not bound to it.
166
+ #
167
+ # @rbs key: String
168
+ # @rbs return: Job
169
+ def unbind_budget(key)
170
+ refresh_from(@client.delete_job_budget(id, key))
171
+ end
172
+
173
+ # Unbind every budget.
174
+ #
175
+ # The job will be dispatched the moment it reaches the front of
176
+ # the queue.
177
+ #
178
+ # @rbs return: Job
179
+ def unbind_all_budgets
180
+ refresh_from(@client.clear_job_budgets(id))
181
+ end
182
+
183
+ # Replace the whole set of budgets this job is bound to.
184
+ #
185
+ # Budgets omitted from `budgets` are unbound, so this describes the
186
+ # job's throttling outright rather than amending it. Passing `[]`
187
+ # is the same as `unbind_all_budgets`.
188
+ #
189
+ # @rbs budgets: Array[Zizq::budget_binding_params]
190
+ # @rbs return: Job
191
+ def replace_budgets(budgets)
192
+ refresh_from(@client.replace_job_budgets(id, budgets:))
193
+ end
194
+
195
+ private
104
196
 
197
+ # Refresh this job from a response carrying the whole job, and
198
+ # hand that response back.
199
+ #
200
+ # Replaces rather than merges. Every one of these endpoints
201
+ # responds with the complete job, and the fields that can be
202
+ # cleared are omitted from it rather than sent as null — `budgets`
203
+ # for an unthrottled job, `backoff` and `retention` once reset. A
204
+ # merge leaves exactly those behind, so the receiver would go on
205
+ # reporting what was just removed.
206
+ #
207
+ # @rbs job: Job
208
+ # @rbs return: Job
209
+ def refresh_from(job)
210
+ @data.replace(job.to_h)
105
211
  job
106
212
  end
107
213
  end
@@ -38,6 +38,21 @@ module Zizq
38
38
  }
39
39
  end
40
40
 
41
+ # Budgets this job must satisfy on when it dispatches, each with the cost
42
+ # it consumes.
43
+ #
44
+ # Not present for a normal job that dispatches as soon as it reaches the
45
+ # front of the queue.
46
+ #
47
+ # `cost` is the number of tokens the job takes from the budget. Any
48
+ # `create_with` the enqueue specified is not stored on the job and is
49
+ # only used during the enqueue operation.
50
+ def budgets #: () -> Array[Zizq::budget_binding]
51
+ (@data["budgets"] || []).map do |b|
52
+ { key: b["key"], cost: b["cost"] } #: Zizq::budget_binding
53
+ end
54
+ end
55
+
41
56
  # Retention configuration converted from the API format (ms) to the
42
57
  # Ruby-idiomatic format (seconds), matching the Zizq::retention type.
43
58
  def retention #: () -> Zizq::retention?
@@ -13,6 +13,7 @@ module Zizq
13
13
  autoload :JobPage, "zizq/resources/job_page"
14
14
  autoload :ErrorPage, "zizq/resources/error_page"
15
15
  autoload :ErrorEnumerator, "zizq/resources/error_enumerator"
16
+ autoload :Budget, "zizq/resources/budget"
16
17
  autoload :CronGroup, "zizq/resources/cron_group"
17
18
  autoload :CronEntry, "zizq/resources/cron_entry"
18
19
  end
@@ -144,7 +144,8 @@ module Zizq
144
144
  retention: nil,
145
145
  unique_key: nil,
146
146
  unique_while: nil,
147
- batch: nil
147
+ batch: nil,
148
+ budgets: nil
148
149
  )
149
150
  req =
150
151
  EnqueueRequest.new(
@@ -158,7 +159,8 @@ module Zizq
158
159
  retention:,
159
160
  unique_key:,
160
161
  unique_while:,
161
- batch:
162
+ batch:,
163
+ budgets:
162
164
  )
163
165
  @mutex.synchronize { record_unsynchronized(req) }.job
164
166
  end
@@ -179,7 +181,8 @@ module Zizq
179
181
  retention: params[:retention],
180
182
  unique_key: params[:unique_key],
181
183
  unique_while: params[:unique_while],
182
- batch: params[:batch]
184
+ batch: params[:batch],
185
+ budgets: params[:budgets]
183
186
  )
184
187
  record_unsynchronized(req).job
185
188
  end
data/lib/zizq/version.rb CHANGED
@@ -5,5 +5,5 @@
5
5
  # frozen_string_literal: true
6
6
 
7
7
  module Zizq
8
- VERSION = "0.6.0" #: String
8
+ VERSION = "0.8.0" #: String
9
9
  end