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.
- checksums.yaml +4 -4
- data/README.md +82 -11
- data/lib/active_job/queue_adapters/zizq_adapter.rb +4 -23
- data/lib/zizq/bulk_enqueue.rb +61 -14
- data/lib/zizq/client.rb +580 -77
- data/lib/zizq/crontab.rb +36 -3
- data/lib/zizq/crontab_builder.rb +10 -1
- data/lib/zizq/crontab_entry_builder.rb +66 -14
- data/lib/zizq/enqueue_request.rb +22 -21
- data/lib/zizq/enqueue_with.rb +65 -8
- data/lib/zizq/error.rb +10 -0
- data/lib/zizq/job_config.rb +95 -12
- data/lib/zizq/query.rb +111 -39
- data/lib/zizq/resources/budget.rb +109 -0
- data/lib/zizq/resources/cron_group.rb +4 -0
- data/lib/zizq/resources/job.rb +108 -2
- data/lib/zizq/resources/job_template.rb +15 -0
- data/lib/zizq/resources.rb +1 -0
- data/lib/zizq/test/client.rb +6 -3
- data/lib/zizq/version.rb +1 -1
- data/lib/zizq.rb +191 -14
- data/sig/generated/zizq/bulk_enqueue.rbs +4 -16
- data/sig/generated/zizq/client.rbs +377 -8
- data/sig/generated/zizq/crontab.rbs +17 -1
- data/sig/generated/zizq/crontab_builder.rbs +9 -0
- data/sig/generated/zizq/crontab_entry_builder.rbs +4 -17
- data/sig/generated/zizq/enqueue_request.rbs +11 -4
- data/sig/generated/zizq/enqueue_with.rbs +4 -9
- data/sig/generated/zizq/error.rbs +10 -0
- data/sig/generated/zizq/job_config.rbs +65 -0
- data/sig/generated/zizq/query.rbs +79 -2
- data/sig/generated/zizq/resources/budget.rbs +97 -0
- data/sig/generated/zizq/resources/cron_group.rbs +3 -0
- data/sig/generated/zizq/resources/job.rbs +94 -0
- data/sig/generated/zizq/resources/job_template.rbs +11 -0
- data/sig/generated/zizq.rbs +111 -33
- data/sig/zizq.rbs +100 -7
- 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
|
|
@@ -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
|
data/sig/generated/zizq.rbs
CHANGED
|
@@ -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
|
-
|
|
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
|
#
|