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
@@ -93,6 +93,51 @@ module Zizq
93
93
  # If not configured, the server's default is used.
94
94
  def zizq_retention: (?completed: untyped, ?dead: untyped) -> untyped
95
95
 
96
+ # Declare a budget this job is bound to.
97
+ #
98
+ # Budgets are used for concurrency control and rate limiting, and
99
+ # require a Pro license on the server.
100
+ #
101
+ # This method is additive, called once per budget:
102
+ #
103
+ # zizq_budget "emails", cost: 2
104
+ # zizq_budget "stripe"
105
+ #
106
+ # The `cost` is how many tokens one job of this class consumes when
107
+ # it dispatches, defaulting to 1. `create_with` declares the
108
+ # budget's policy should it not exist yet, so jobs can be enqueued
109
+ # without first creating the budget in a separate step:
110
+ #
111
+ # zizq_budget "emails",
112
+ # create_with: {
113
+ # allocation: 100,
114
+ # strategy: { type: :time_based, duration: 60 }
115
+ # }
116
+ #
117
+ # It is ignored when the budget already exists, so this cannot
118
+ # accidentally overwrite an already configured budget.
119
+ #
120
+ # Declaring the same key twice raises `ArgumentError' — the server
121
+ # would reject a duplicate key outright.
122
+ #
123
+ # A per-enqueue `budgets` replaces these rather than adding to
124
+ # them, the same way a block-assigned `queue` or `priority` does:
125
+ #
126
+ # Zizq.enqueue(SendEmailJob) { |req| req.budgets = [...] }
127
+ # Zizq.enqueue(SendEmailJob) { |req| req.budgets << {key: "x"} }
128
+ #
129
+ # @rbs key: String
130
+ # @rbs cost: Integer?
131
+ # @rbs create_with: Zizq::budget_policy?
132
+ # @rbs return: Zizq::budget_binding_params
133
+ def zizq_budget: (String key, ?cost: Integer?, ?create_with: Zizq::budget_policy?) -> Zizq::budget_binding_params
134
+
135
+ # Budgets declared on this class, in declaration order.
136
+ #
137
+ # A fresh array each call, so mutating it cannot corrupt the
138
+ # class-level declaration. The bindings themselves are frozen.
139
+ def zizq_budgets: () -> untyped
140
+
96
141
  # Declare uniqueness for this job class.
97
142
  #
98
143
  # Requires a pro license.
@@ -216,6 +261,26 @@ module Zizq
216
261
  # end
217
262
  def zizq_enqueue_request: (*untyped args, **untyped kwargs) -> untyped
218
263
 
264
+ # Apply this class's declared configuration to an enqueue request.
265
+ #
266
+ # Everything set here is a property of the class rather than of one
267
+ # enqueue, so it applies the same way however the request was built.
268
+ # `zizq_enqueue_request` builds one entirely from the class and
269
+ # calls this. The ActiveJob adapter cannot: `job_id`, a
270
+ # `set(queue:)` override and a `set(wait:)` delay exist only on the
271
+ # job *instance*, so it constructs those fields itself and then
272
+ # calls this for the rest.
273
+ #
274
+ # Adding a field to the DSL means adding it here, and both paths
275
+ # pick it up. Setting it in only one of them is how a declaration
276
+ # silently stops reaching the server for half the callers.
277
+ #
278
+ # @rbs req: EnqueueRequest
279
+ # @rbs *args: untyped
280
+ # @rbs **kwargs: untyped
281
+ # @rbs return: EnqueueRequest
282
+ def zizq_apply_class_config: (EnqueueRequest req, *untyped args, **untyped kwargs) -> EnqueueRequest
283
+
219
284
  private
220
285
 
221
286
  # Class-name-prefixed SHA256 of the normalized hashable payload.
@@ -53,7 +53,7 @@ module Zizq
53
53
  # @rbs limit: Integer?
54
54
  # @rbs page_size: Integer?
55
55
  # @rbs return: void
56
- def initialize: (?id: (String | Array[String])?, ?queue: (String | Array[String])?, ?type: (String | Array[String])?, ?status: (String | Array[String])?, ?jq_filter: String?, ?priority: (Integer | Range[Integer?])?, ?ready_at: (Zizq::to_f | Range[Zizq::to_f?])?, ?attempts: (Integer | Range[Integer?])?, ?order: Zizq::sort_direction?, ?limit: Integer?, ?page_size: Integer?) -> void
56
+ def initialize: (?id: (String | Array[String])?, ?queue: (String | Array[String])?, ?type: (String | Array[String])?, ?status: (String | Array[String])?, ?jq_filter: String?, ?priority: (Integer | Range[Integer?])?, ?ready_at: (Zizq::to_f | Range[Zizq::to_f?])?, ?attempts: (Integer | Range[Integer?])?, ?budgets_key: untyped, ?order: Zizq::sort_direction?, ?limit: Integer?, ?page_size: Integer?) -> void
57
57
 
58
58
  # Set the page size for paginated iteration.
59
59
  #
@@ -113,6 +113,20 @@ module Zizq
113
113
  # @rbs return: Query
114
114
  def add_status: (String | Array[String] status) -> Query
115
115
 
116
+ # Filter by budget (replaces any existing budget filter).
117
+ #
118
+ # Matches a job bound to any of the specified budgets.
119
+ #
120
+ # @rbs budgets_key: (String | Array[String])
121
+ # @rbs return: Query
122
+ def by_budgets_key: (String | Array[String] budgets_key) -> Query
123
+
124
+ # Add a budget to the existing budget filter.
125
+ #
126
+ # @rbs budgets_key: String | Array[String]
127
+ # @rbs return: Query
128
+ def add_budgets_key: (String | Array[String] budgets_key) -> Query
129
+
116
130
  # Filter by priority range (replaces any existing priority filter).
117
131
  #
118
132
  # Accepts an Integer (exact match) or an inclusive Range. Lower numbers
@@ -327,6 +341,60 @@ module Zizq
327
341
  # @rbs return: Integer
328
342
  def delete_one: () -> Integer
329
343
 
344
+ # Bind every matching job to a budget, skipping over the ones already
345
+ # bound to it.
346
+ #
347
+ # Only queued (`scheduled`, `ready`) jobs can be rebound, so the result
348
+ # provides any that were in flight and were blocked — see the
349
+ # `Zizq::bulk_budget_change` type.
350
+ #
351
+ # @rbs key: String
352
+ # @rbs cost: Integer?
353
+ # @rbs create_with: Zizq::budget_policy?
354
+ # @rbs return: Zizq::bulk_budget_change
355
+ def bind_budget: (String key, ?cost: Integer?, ?create_with: Zizq::budget_policy?) -> Zizq::bulk_budget_change
356
+
357
+ # Bind every matching job to a budget, replacing any existing
358
+ # binding to it.
359
+ #
360
+ # The binding is replaced whole, so a `cost` left unset returns to
361
+ # the default of 1 rather than keeping what was there.
362
+ #
363
+ # @rbs key: String
364
+ # @rbs cost: Integer?
365
+ # @rbs create_with: Zizq::budget_policy?
366
+ # @rbs return: Zizq::bulk_budget_change
367
+ def rebind_budget: (String key, ?cost: Integer?, ?create_with: Zizq::budget_policy?) -> Zizq::bulk_budget_change
368
+
369
+ # Change what an existing binding costs, leaving the binding itself
370
+ # alone. Matching jobs not bound to this budget are skipped.
371
+ #
372
+ # @rbs key: String
373
+ # @rbs cost: Integer
374
+ # @rbs return: Zizq::bulk_budget_change
375
+ def set_budget_cost: (String key, Integer cost) -> Zizq::bulk_budget_change
376
+
377
+ # Unbind one budget from every matching job, leaving their other
378
+ # budgets alone.
379
+ #
380
+ # Paired with `by_budgets_key` this can be used to remove a budget
381
+ # binding from existing jobs before deleting the budget itself:
382
+ #
383
+ # Zizq.query.by_budgets_key("emails").unbind_budget("emails")
384
+ # Zizq.delete_budget("emails")
385
+ #
386
+ # @rbs key: String
387
+ # @rbs return: Zizq::bulk_budget_change
388
+ def unbind_budget: (String key) -> Zizq::bulk_budget_change
389
+
390
+ # Unbind *every* budget from every matching job.
391
+ #
392
+ # Beware: on an unfiltered query this unbinds every budget from
393
+ # every job on the server, reverting all jobs back to regular jobs.
394
+ #
395
+ # @rbs return: Zizq::bulk_budget_change
396
+ def unbind_all_budgets: () -> Zizq::bulk_budget_change
397
+
330
398
  # Iterate over matching jobs, lazily paginating through results.
331
399
  #
332
400
  # Respects `limit` if set. Without a block, returns an `Enumerator`.
@@ -382,10 +450,19 @@ module Zizq
382
450
 
383
451
  private
384
452
 
453
+ # The filter arguments this query represents, as `Client` takes them.
454
+ #
455
+ # One definition rather than four: `count`, `each_page`,
456
+ # `update_all` and `delete_all` all send the same filter, and one
457
+ # added to only some of them silently widens the rest.
458
+ #
459
+ # @rbs return: Zizq::where_params
460
+ def filters: () -> Zizq::where_params
461
+
385
462
  # Build a new Query with the given overrides, preserving all other fields.
386
463
  #
387
464
  # @rbs return: Query
388
- def rebuild: (?id: untyped, ?queue: untyped, ?type: untyped, ?status: untyped, ?jq_filter: untyped, ?priority: untyped, ?ready_at: untyped, ?attempts: untyped, ?order: untyped, ?limit: untyped, ?page_size: untyped) -> Query
465
+ def rebuild: (?id: untyped, ?queue: untyped, ?type: untyped, ?status: untyped, ?jq_filter: untyped, ?priority: untyped, ?ready_at: untyped, ?attempts: untyped, ?budgets_key: untyped, ?order: untyped, ?limit: untyped, ?page_size: untyped) -> Query
389
466
 
390
467
  # @rbs job_class: untyped
391
468
  # @rbs return: void
@@ -0,0 +1,97 @@
1
+ # Generated from lib/zizq/resources/budget.rb with RBS::Inline
2
+
3
+ module Zizq
4
+ module Resources
5
+ # Typed wrapper around a budget response hash.
6
+ #
7
+ # A budget is a named token bucket that jobs draw from. Its strategy
8
+ # decides how tokens are managed: on a clock (`time_based`, a rate
9
+ # limit) or when a job stops running (`while_in_flight`, a
10
+ # concurrency limit, of which a mutex is the allocation = 1 case).
11
+ class Budget < Resource
12
+ # The budget's key, unique across the server.
13
+ def key: () -> untyped
14
+
15
+ # Tokens the budget makes available.
16
+ #
17
+ # For a `time_based` budget, how many tokens can be spent over its
18
+ # `duration`. For a `while_in_flight` budgets how many jobs may run
19
+ # at once.
20
+ def allocation: () -> untyped
21
+
22
+ def created_at: () -> untyped
23
+
24
+ def updated_at: () -> untyped
25
+
26
+ # `:time_based` or `:while_in_flight`.
27
+ def strategy_type: () -> untyped
28
+
29
+ def time_based?: () -> untyped
30
+
31
+ def while_in_flight?: () -> untyped
32
+
33
+ # Period over which the whole allocation replenishes, in seconds.
34
+ #
35
+ # Tokens accrue using a continuous drip (leaky bucket) such that an
36
+ # empty bucket is full after this duration has elapsed, and is half
37
+ # full after half of the duration has elapsed, etc.
38
+ #
39
+ # `nil` for a `while_in_flight` budget.
40
+ def duration: () -> untyped
41
+
42
+ # Max tokens the bucket may hold at once, or `nil` when it holds
43
+ # a whole allocation.
44
+ #
45
+ # A newly created bucket starts full, so a budget with no burst set
46
+ # hands out an entire allocation the moment work arrives and only
47
+ # then settles to its continuous drip rate — `10` per minute really
48
+ # does permit twenty in the first minute. Setting a burst caps that
49
+ # spike without changing the long-run rate; a burst of `1` paces
50
+ # dispatches evenly at all times. The burst rule also applies to
51
+ # budgets that have not been consumed for an entire duration's worth
52
+ # of time.
53
+ #
54
+ # It is valid for `burst` to be set higher than the `allocation`. In
55
+ # this case the meaning is to continue filling the bucket after the
56
+ # duration has elapsed, so a `burst` of 200 on a 100 token allocation
57
+ # would continue accruing across two consecutive periods, but no more
58
+ # than that.
59
+ #
60
+ # This is designed to allow applications to absorb short-lived
61
+ # spikes.
62
+ #
63
+ # `nil` for a `while_in_flight` budget.
64
+ def burst: () -> untyped
65
+
66
+ # Most tokens the bucket can hold, which is what a job's cost has
67
+ # to fit inside.
68
+ #
69
+ # The burst where one is set, and the allocation otherwise. Worth
70
+ # distinguishing from `allocation`: with a burst set it is the
71
+ # *smaller* number that decides whether a job can ever be
72
+ # afforded, so a cost well within the allocation may still be
73
+ # refused.
74
+ def capacity: () -> untyped
75
+
76
+ # The whole strategy, in the form `create_budget` and `put_budget`
77
+ # take it.
78
+ #
79
+ # budget = client.get_budget("emails")
80
+ # client.put_budget(
81
+ # "emails",
82
+ # allocation: budget.allocation * 2,
83
+ # strategy: budget.strategy
84
+ # )
85
+ #
86
+ # When absent, `burst` is omitted rather than sent as `nil`, since
87
+ # an absent burst and one explicitly cleared mean the same thing.
88
+ def strategy: () -> untyped
89
+
90
+ private
91
+
92
+ # The strategy exactly as the server sent it — string keys, and
93
+ # the period in milliseconds under `duration_ms`.
94
+ def raw_strategy: () -> untyped
95
+ end
96
+ end
97
+ end
@@ -10,6 +10,9 @@ module Zizq
10
10
 
11
11
  def paused?: () -> untyped
12
12
 
13
+ # IANA timezone applied to entries that do not specify their own.
14
+ def timezone: () -> untyped
15
+
13
16
  def paused_at: () -> untyped
14
17
 
15
18
  def resumed_at: () -> untyped
@@ -64,6 +64,100 @@ module Zizq
64
64
  # @rbs retention: (Zizq::retention | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
65
65
  # @rbs return: Job
66
66
  def update: (?queue: (String | singleton(Zizq::UNCHANGED))?, ?priority: (Integer | singleton(Zizq::UNCHANGED))?, ?ready_at: (Zizq::to_f | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?, ?retry_limit: (Integer | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?, ?backoff: (Zizq::backoff | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?, ?retention: (Zizq::retention | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?) -> Job
67
+
68
+ # Bind this job to a budget it is not already bound to.
69
+ #
70
+ # Requires a Pro license on the server, else raise `Zizq::ClientError`
71
+ # for the server's 403 response.
72
+ #
73
+ # Raises a `Zizq::ConflictError` (409) if it is already bound to this
74
+ # budget, leaving the existing binding untouched — use
75
+ # `rebind_budget` to replace it, or `set_budget_cost` to change
76
+ # only what it costs.
77
+ #
78
+ # `create_with` declares the budget's policy should it not exist
79
+ # yet, binding and creating in one atomic call. It is ignored when
80
+ # the budget already exists.
81
+ #
82
+ # Only queued (`scheduled`, `ready`) jobs may be rebound. Anything
83
+ # else raises `Zizq::ClientError` (422).
84
+ #
85
+ # Returns the updated job, and refreshes this one.
86
+ #
87
+ # @rbs key: String
88
+ # @rbs cost: Integer?
89
+ # @rbs create_with: Zizq::budget_policy?
90
+ # @rbs return: Job
91
+ def bind_budget: (String key, ?cost: Integer?, ?create_with: Zizq::budget_policy?) -> Job
92
+
93
+ # Bind this job to a budget, replacing any existing binding to it.
94
+ #
95
+ # Requires a Pro license on the server, else raise `Zizq::ClientError`
96
+ # for the server's 403 response.
97
+ #
98
+ # Unlike `bind_budget` this never conflicts. The binding is
99
+ # replaced whole, so a `cost` left unset returns to the default of
100
+ # 1 rather than keeping what was there.
101
+ #
102
+ # @rbs key: String
103
+ # @rbs cost: Integer?
104
+ # @rbs create_with: Zizq::budget_policy?
105
+ # @rbs return: Job
106
+ def rebind_budget: (String key, ?cost: Integer?, ?create_with: Zizq::budget_policy?) -> Job
107
+
108
+ # Change what an existing binding costs, leaving the binding
109
+ # itself alone.
110
+ #
111
+ # Raises `Zizq::NotFoundError` if this job is not bound to the
112
+ # budget. Raises a `Zizq::ClientError` (422) if the new cost exceeds
113
+ # the budget's capacity.
114
+ #
115
+ # @rbs key: String
116
+ # @rbs cost: Integer
117
+ # @rbs return: Job
118
+ def set_budget_cost: (String key, Integer cost) -> Job
119
+
120
+ # Unbind one budget, leaving this job's other budgets alone.
121
+ #
122
+ # Raises `Zizq::NotFoundError` if it is not bound to it.
123
+ #
124
+ # @rbs key: String
125
+ # @rbs return: Job
126
+ def unbind_budget: (String key) -> Job
127
+
128
+ # Unbind every budget.
129
+ #
130
+ # The job will be dispatched the moment it reaches the front of
131
+ # the queue.
132
+ #
133
+ # @rbs return: Job
134
+ def unbind_all_budgets: () -> Job
135
+
136
+ # Replace the whole set of budgets this job is bound to.
137
+ #
138
+ # Budgets omitted from `budgets` are unbound, so this describes the
139
+ # job's throttling outright rather than amending it. Passing `[]`
140
+ # is the same as `unbind_all_budgets`.
141
+ #
142
+ # @rbs budgets: Array[Zizq::budget_binding_params]
143
+ # @rbs return: Job
144
+ def replace_budgets: (Array[Zizq::budget_binding_params] budgets) -> Job
145
+
146
+ private
147
+
148
+ # Refresh this job from a response carrying the whole job, and
149
+ # hand that response back.
150
+ #
151
+ # Replaces rather than merges. Every one of these endpoints
152
+ # responds with the complete job, and the fields that can be
153
+ # cleared are omitted from it rather than sent as null — `budgets`
154
+ # for an unthrottled job, `backoff` and `retention` once reset. A
155
+ # merge leaves exactly those behind, so the receiver would go on
156
+ # reporting what was just removed.
157
+ #
158
+ # @rbs job: Job
159
+ # @rbs return: Job
160
+ def refresh_from: (Job job) -> Job
67
161
  end
68
162
  end
69
163
  end
@@ -26,6 +26,17 @@ module Zizq
26
26
  # Ruby-idiomatic format (seconds), matching the Zizq::backoff type.
27
27
  def backoff: () -> untyped
28
28
 
29
+ # Budgets this job must satisfy on when it dispatches, each with the cost
30
+ # it consumes.
31
+ #
32
+ # Not present for a normal job that dispatches as soon as it reaches the
33
+ # front of the queue.
34
+ #
35
+ # `cost` is the number of tokens the job takes from the budget. Any
36
+ # `create_with` the enqueue specified is not stored on the job and is
37
+ # only used during the enqueue operation.
38
+ def budgets: () -> untyped
39
+
29
40
  # Retention configuration converted from the API format (ms) to the
30
41
  # Ruby-idiomatic format (seconds), matching the Zizq::retention type.
31
42
  def retention: () -> untyped
@@ -49,6 +49,95 @@ module Zizq
49
49
  # List all distinct queue names on the server.
50
50
  def self.queues: () -> untyped
51
51
 
52
+ # List every defined budget, with its policy.
53
+ #
54
+ # Requires a Pro license on the server, else raise `Zizq::ClientError`
55
+ # for the server's 403 response.
56
+ #
57
+ # @rbs return: Array[Zizq::Resources::Budget]
58
+ def self.budgets: () -> Array[Zizq::Resources::Budget]
59
+
60
+ # Fetch one budget's policy.
61
+ #
62
+ # Requires a Pro license on the server, else raise `Zizq::ClientError`
63
+ # for the server's 403 response.
64
+ #
65
+ # Raises `Zizq::NotFoundError` if no budget exists under this key.
66
+ #
67
+ # @rbs key: String
68
+ # @rbs return: Zizq::Resources::Budget
69
+ def self.budget: (String key) -> Zizq::Resources::Budget
70
+
71
+ # Define a budget.
72
+ #
73
+ # Requires a Pro license on the server, else raise `Zizq::ClientError`
74
+ # for the server's 403 response.
75
+ #
76
+ # Zizq.define_budget(
77
+ # "emails",
78
+ # allocation: 100,
79
+ # strategy: { type: :time_based, duration: 60 }
80
+ # )
81
+ #
82
+ # Refuses by default when one already exists under this key,
83
+ # raising `Zizq::ConflictError` and leaving the stored policy
84
+ # untouched — so an application declaring its budgets on boot
85
+ # cannot clobber a change that was explicitly applied since the
86
+ # budget was first created. Horizontally scaled processes can all
87
+ # call this safely, rescuing the conflict as success:
88
+ #
89
+ # begin
90
+ # Zizq.define_budget("emails", allocation: 100, strategy: ...)
91
+ # rescue Zizq::ConflictError
92
+ # # already declared
93
+ # end
94
+ #
95
+ # Pass `replace: true` to overwrite instead, which never conflicts.
96
+ # A replace changes the policy, not the budget's identity, so its
97
+ # `created_at` survives. Refused with a `Zizq::ClientError` (422)
98
+ # if the new allocation is below a cost already required by a
99
+ # queued job or a cron entry.
100
+ #
101
+ # @rbs key: String
102
+ # @rbs allocation: Integer
103
+ # @rbs strategy: Zizq::budget_strategy
104
+ # @rbs replace: bool
105
+ # @rbs return: Zizq::Resources::Budget
106
+ def self.define_budget: (String key, allocation: Integer, strategy: Zizq::budget_strategy, ?replace: bool) -> Zizq::Resources::Budget
107
+
108
+ # Amend named fields of a budget's policy, leaving the rest alone.
109
+ #
110
+ # Requires a Pro license on the server, else raise `Zizq::ClientError`
111
+ # for the server's 403 response.
112
+ #
113
+ # Deep merge-patches, so `burst` can be changed without repeating
114
+ # the `type` and `duration`:
115
+ #
116
+ # Zizq.update_budget("emails", strategy: { burst: 5 })
117
+ #
118
+ # Raises `Zizq::NotFoundError` if no budget exists under this key.
119
+ #
120
+ # @rbs key: String
121
+ # @rbs allocation: Integer?
122
+ # @rbs strategy: Zizq::budget_strategy_patch?
123
+ # @rbs return: Zizq::Resources::Budget
124
+ def self.update_budget: (String key, ?allocation: Integer?, ?strategy: Zizq::budget_strategy_patch?) -> Zizq::Resources::Budget
125
+
126
+ # Delete a budget.
127
+ #
128
+ # Requires a Pro license on the server, else raise `Zizq::ClientError`
129
+ # for the server's 403 response.
130
+ #
131
+ # Raises `Zizq::NotFoundError` if it does not exist, and
132
+ # `Zizq::ConflictError` while anything is still bound to it. To clear
133
+ # those bindings first:
134
+ #
135
+ # Zizq.query.by_budgets_key("emails").unbind_budget("emails")
136
+ #
137
+ # @rbs key: String
138
+ # @rbs return: void
139
+ def self.delete_budget: (String key) -> void
140
+
52
141
  # Start a query to retrieve or modify job data.
53
142
  #
54
143
  # @rbs id: (String | Array[String])?
@@ -85,7 +174,24 @@ module Zizq
85
174
  #
86
175
  # By default schedules operate in the system time zone of the Zizq server
87
176
  # but an explicit IANA timezone name can be specified when defining the
88
- # Crontab.
177
+ # Crontab. It applies to every entry that does not specify one of its own,
178
+ # so a schedule that runs in one timezone says so once:
179
+ #
180
+ # Zizq.define_crontab("example", timezone: "Europe/Rome") do |cron|
181
+ # # ...
182
+ # end
183
+ #
184
+ # An individual entry can still override it:
185
+ #
186
+ # cron.define_entry(
187
+ # "melbourne_digest",
188
+ # "0 9 * * *",
189
+ # timezone: "Australia/Melbourne"
190
+ # ).enqueue(DigestJob)
191
+ #
192
+ # The schedule's timezone is stored on the Zizq server as the schedule's
193
+ # own, so `Zizq.crontab("example").timezone` still reports it later. This
194
+ # requires Zizq 0.7.0 or newer on the server.
89
195
  #
90
196
  # This method sends exactly *one* request to the Zizq server upon
91
197
  # completion of the block. Any existing entries are retained. Any new
@@ -176,40 +282,12 @@ module Zizq
176
282
  # @rbs kwargs: Hash[Symbol, untyped]
177
283
  # @rbs &block: ?(EnqueueRequest) -> void
178
284
  # @rbs return: Resources::Job
285
+ def self.enqueue_job_class: (Class & Zizq::JobConfig job_class, *untyped args, **untyped kwargs) ?{ (EnqueueRequest) -> void } -> Resources::Job
286
+
179
287
  def self.enqueue: (Class & Zizq::JobConfig job_class, *untyped args, **untyped kwargs) ?{ (EnqueueRequest) -> void } -> Resources::Job
288
+ | (queue: String, type: String, payload: untyped, ?priority: Integer?, ?delay: Zizq::to_f?, ?ready_at: Zizq::to_f?, ?retry_limit: Integer?, ?backoff: Zizq::backoff?, ?retention: Zizq::retention?, ?unique_key: String?, ?unique_while: Zizq::unique_scope?, ?batch: Zizq::batch?, ?budgets: Array[Zizq::budget_binding_params]?) ?{ (EnqueueRequest) -> void } -> Resources::Job
180
289
 
181
- # Enqueue a job by providing raw inputs to the Zizq server.
182
- #
183
- # This is for advanced use cases such as enqueueing jobs for consumption in
184
- # other programming languages.
185
- #
186
- # Zizq.enqueue_raw(
187
- # queue: "emails",
188
- # type: "send_email",
189
- # payload: {user_id: 42, template: "welcome"}
190
- # )
191
- #
192
- # If using this method to enqueue a job that is intended for consumption in
193
- # the Ruby client itself a custom dispatcher implementation is likely
194
- # required:
195
- #
196
- # Zizq.configure do |c|
197
- # c.dispatcher = MyDispatcher.new
198
- # end
199
- #
200
- # @rbs queue: String
201
- # @rbs type: String
202
- # @rbs payload: untyped
203
- # @rbs priority: Integer?
204
- # @rbs ready_at: Zizq::to_f?
205
- # @rbs retry_limit: Integer?
206
- # @rbs backoff: Zizq::backoff?
207
- # @rbs retention: Zizq::retention?
208
- # @rbs unique_key: String?
209
- # @rbs unique_while: Zizq::unique_scope?
210
- # @rbs batch: Zizq::batch?
211
- # @rbs return: Resources::Job
212
- def self.enqueue_raw: (queue: String, type: String, payload: untyped, **untyped opts) -> Resources::Job
290
+ def self.enqueue_raw: (queue: String, type: String, payload: untyped, ?priority: Integer?, ?delay: Zizq::to_f?, ?ready_at: Zizq::to_f?, ?retry_limit: Integer?, ?backoff: Zizq::backoff?, ?retention: Zizq::retention?, ?unique_key: String?, ?unique_while: Zizq::unique_scope?, ?batch: Zizq::batch?, ?budgets: Array[Zizq::budget_binding_params]?) ?{ (EnqueueRequest) -> void } -> Resources::Job
213
291
 
214
292
  # Enqueue multiple jobs atomically in a single bulk request.
215
293
  #