zizq 0.6.0 → 0.7.0

data/lib/zizq/client.rb

@@ -30,10 +30,35 @@ module Zizq
     # the async reactor that produced it.
     RawResponse = Data.define(:status, :body, :content_type)
 
-    CONTENT_TYPES = { #: Hash[Zizq::format, String]
+    CONTENT_TYPES = {
       msgpack: "application/msgpack",
       json: "application/json"
-    }.freeze
+    }.freeze #: Hash[Zizq::format, String]
+
+    # Filter keys the server accepts as comma-delimited lists, matching
+    # any of the named values. An empty value matches nothing, which every
+    # filtered call short-circuits on rather than sending a request that
+    # would have matched everything. Callers should omit the key entirely
+    # if what they really mean is "match everything".
+    #
+    # These are the Ruby keyword argument names; see `API_FILTER_NAMES` for
+    # alternative names used in the API.
+    MULTI_FILTER_KEYS = %i[id status queue type budgets_key].freeze #: Array[Symbol]
+
+    # Filter arguments whose query parameter is spelled differently in
+    # the API.
+    #
+    # `budgets.key` is dotted in the API to mirror the path into the
+    # `budgets` array on a job, which is not a valid Ruby keyword, so
+    # `validate_where` takes it as `budgets_key:`.
+    #
+    # The rename happens here, in value position, rather than as a key
+    # in `validate_where`'s hash: syntax_tree rewrites a quoted symbol
+    # *key* into a string key when the same hash uses Ruby 3.1 omitted
+    # values, and a string key silently stops matching
+    # `MULTI_FILTER_KEYS` — so an empty filter would be sent as no
+    # filter, matching everything.
+    API_FILTER_NAMES = { budgets_key: :"budgets.key" }.freeze #: Hash[Symbol, Symbol]
 
     STREAM_ACCEPT = { #: Hash[Zizq::format, String]
       msgpack: "application/vnd.zizq.msgpack-stream",
@@ -152,6 +177,9 @@ module Zizq
     # using the Zizq API's expected inputs. Callers should generally use
     # [`Zizq::enqueue`] instead.
     #
+    # Durations and timestamps are fractional seconds throughout to align with
+    # Ruby, as opposed to the server's integer milliseconds representation.
+    #
     # Returns a resource instance of the new job wrapping the API response.
     #
     # @rbs queue: String
@@ -165,6 +193,7 @@ module Zizq
     # @rbs unique_key: String?
     # @rbs unique_while: Zizq::unique_scope?
     # @rbs batch: Zizq::batch?
+    # @rbs budgets: Array[Zizq::budget_binding_params]?
     # @rbs return: Resources::Job
     def enqueue(
       queue:,
@@ -177,18 +206,20 @@ module Zizq
       retention: nil,
       unique_key: nil,
       unique_while: nil,
-      batch: nil
+      batch: nil,
+      budgets: nil
     )
       body = { queue:, type:, payload: } #: Hash[Symbol, untyped]
       body[:priority] = priority if priority
       # ready_at is fractional seconds in Ruby; the server expects ms.
       body[:ready_at] = (ready_at.to_f * 1000).to_i if ready_at
       body[:retry_limit] = retry_limit if retry_limit
-      body[:backoff] = backoff if backoff
-      body[:retention] = retention if retention
+      body[:backoff] = wire_backoff(backoff) if backoff
+      body[:retention] = wire_retention(retention) if retention
       body[:unique_key] = unique_key if unique_key
       body[:unique_while] = unique_while.to_s if unique_while
       body[:batch] = batch if batch
+      body[:budgets] = budgets.map { |b| wire_binding(b) } if budgets&.any?
 
       response = post("/jobs", body)
       data = handle_response!(response, expected: [200, 201])
@@ -220,11 +251,16 @@ module Zizq
               :ready_at
             ]
             wire[:retry_limit] = job[:retry_limit] if job[:retry_limit]
-            wire[:backoff] = job[:backoff] if job[:backoff]
-            wire[:retention] = job[:retention] if job[:retention]
+            wire[:backoff] = wire_backoff(job[:backoff]) if job[:backoff]
+            wire[:retention] = wire_retention(job[:retention]) if job[
+              :retention
+            ]
             wire[:unique_key] = job[:unique_key] if job[:unique_key]
             wire[:unique_while] = job[:unique_while].to_s if job[:unique_while]
             wire[:batch] = job[:batch] if job[:batch]
+            if (budgets = job[:budgets])&.any?
+              wire[:budgets] = budgets.map { |b| wire_binding(b) }
+            end
             wire
           end
       }
@@ -273,34 +309,30 @@ module Zizq
       priority: nil,
       ready_at: nil,
       attempts: nil,
+      budgets_key: nil,
       from: nil,
       order: nil,
       limit: nil
     )
-      options = {
+      where = {
         id:,
         status:,
         queue:,
         type:,
         filter:,
-        priority: encode_range(priority),
-        ready_at: encode_range(ready_at) { |v| (v.to_f * 1000).to_i },
-        attempts: encode_range(attempts),
-        from:,
-        order:,
-        limit:
-      }.compact #: Hash[Symbol, untyped]
-
-      multi_keys = %i[id status queue type]
-      params = build_where_params(options, multi_keys:)
-
-      # An empty filter ([] or "") matches nothing — short-circuit.
-      multi_keys.each do |key|
-        if params[key] == ""
-          return Resources::JobPage.new(self, { "jobs" => [], "pages" => {} })
-        end
+        priority:,
+        ready_at:,
+        attempts:,
+        budgets_key:
+      }.compact #: Zizq::where_params
+      params = filter_params(where)
+
+      if params.nil?
+        return Resources::JobPage.new(self, { "jobs" => [], "pages" => {} })
       end
 
+      params = params.merge({ from:, order:, limit: }.compact)
+
       response = get("/jobs", params:)
       data = handle_response!(response, expected: 200)
       Resources::JobPage.new(self, data)
@@ -328,24 +360,22 @@ module Zizq
       filter: nil,
       priority: nil,
       ready_at: nil,
-      attempts: nil
+      attempts: nil,
+      budgets_key: nil
     )
-      options = {
+      where = {
         id:,
         status:,
         queue:,
         type:,
         filter:,
-        priority: encode_range(priority),
-        ready_at: encode_range(ready_at) { |v| (v.to_f * 1000).to_i },
-        attempts: encode_range(attempts)
-      }.compact #: Hash[Symbol, untyped]
-
-      multi_keys = %i[id status queue type]
-      params = build_where_params(options, multi_keys:)
-
-      # An empty filter ([] or "") matches nothing — short-circuit.
-      multi_keys.each { |key| return 0 if params[key] == "" }
+        priority:,
+        ready_at:,
+        attempts:,
+        budgets_key:
+      }.compact #: Zizq::where_params
+      params = filter_params(where)
+      return 0 if params.nil?
 
       response = get("/jobs/count", params:)
       data = handle_response!(response, expected: 200)
@@ -372,13 +402,8 @@ module Zizq
     # @rbs where: Zizq::where_params
     # @rbs return: Integer
     def delete_all_jobs(where: {})
-      filter_params = validate_where(**where)
-
-      multi_keys = %i[id status queue type]
-      params = build_where_params(filter_params, multi_keys:)
-
-      # An empty multi-value filter matches nothing — short-circuit.
-      multi_keys.each { |key| return 0 if params[key] == "" }
+      params = filter_params(where)
+      return 0 if params.nil?
 
       response = delete("/jobs", params:)
       data = handle_response!(response, expected: 200)
@@ -458,13 +483,8 @@ module Zizq
     # @rbs apply: Zizq::apply_params
     # @rbs return: Integer
     def update_all_jobs(where: {}, apply: {})
-      filter_params = validate_where(**where)
-
-      multi_keys = %i[id status queue type]
-      params = build_where_params(filter_params, multi_keys:)
-
-      # An empty multi-value filter matches nothing — short-circuit.
-      multi_keys.each { |key| return 0 if params[key] == "" }
+      params = filter_params(where)
+      return 0 if params.nil?
 
       body = validate_and_build_set(**apply)
       response = patch("/jobs", body, params:)
@@ -517,6 +537,336 @@ module Zizq
       data["queues"]
     end
 
+    # List every defined budget, with its policy.
+    #
+    # Requires a Pro license on the server, else a `Zizq::ClientError`
+    # is raised.
+    #
+    # @rbs return: Array[Zizq::Resources::Budget]
+    def list_budgets
+      response = get("/budgets")
+      data = handle_response!(response, expected: 200)
+      (data["budgets"] || []).map { |b| Resources::Budget.new(self, b) }
+    end
+
+    # Fetch one budget's policy.
+    #
+    # Raises `Zizq::NotFoundError` if no budget exists under this key.
+    #
+    # @rbs key: String
+    # @rbs return: Zizq::Resources::Budget
+    def get_budget(key)
+      response = get("/budgets/#{enc(key)}")
+      data = handle_response!(response, expected: 200)
+      Resources::Budget.new(self, data)
+    end
+
+    # Create a budget, raising if the key would be overwritten.
+    #
+    # Raises a `Zizq::ConflictError` (409) if a budget already
+    # exists under this key, leaving the stored policy untouched.
+    #
+    # See `#put_budget` for the version that would overwrite the existing
+    # key.
+    #
+    # `strategy` is one of:
+    #
+    #     { type: :time_based, duration: 60 }
+    #     { type: :time_based, duration: 60, burst: 5 }
+    #     { type: :while_in_flight }
+    #
+    # `duration` is fractional seconds and is also read back as fractional
+    # seconds.
+    #
+    # A newly created bucket starts full, so a budget with no burst set
+    # hands out an entire allocation the moment work arrives and only
+    # then settles to its continuous drip rate — `10` per minute really
+    # does permit twenty in the first minute. Setting a burst caps that
+    # spike without changing the long-run rate; a burst of `1` paces
+    # dispatches evenly at all times. The burst rule also applies to
+    # budgets that have not been consumed for an entire duration's worth
+    # of time.
+    #
+    # It is valid for `burst` to be set higher than the `allocation`. In
+    # this case the meaning is to continue filling the bucket after the
+    # duration has elapsed, so a `burst` of 200 on a 100 token allocation
+    # would continue accruing across two consecutive periods, but no more
+    # than that.
+    #
+    # This is designed to allow applications to absorb short-lived
+    # spikes.
+    #
+    # @rbs key: String
+    # @rbs allocation: Integer
+    # @rbs strategy: Zizq::budget_strategy
+    # @rbs return: Zizq::Resources::Budget
+    def create_budget(key, allocation:, strategy:)
+      body = { allocation:, strategy: wire_strategy(strategy) }
+      response = post("/budgets/#{enc(key)}", body)
+      data = handle_response!(response, expected: 201)
+      Resources::Budget.new(self, data)
+    end
+
+    # Create a budget, or replace an existing budgets policy outright.
+    #
+    # Unlike `create_budget` this never conflicts. `created_at` is
+    # preserved when the budget already exists — a replace changes the
+    # policy, not the budget's identity.
+    #
+    # Raises a `Zizq::ClientError` (422) if the new allocation is below
+    # a cost already committed to the budget by a queued job or a cron
+    # entry, since those could then never be afforded.
+    #
+    # `strategy` takes the same shape as `create_budget`.
+    #
+    # @rbs key: String
+    # @rbs allocation: Integer
+    # @rbs strategy: Zizq::budget_strategy
+    # @rbs return: Zizq::Resources::Budget
+    def put_budget(key, allocation:, strategy:)
+      body = { allocation:, strategy: wire_strategy(strategy) }
+      response = put("/budgets/#{enc(key)}", body)
+      data = handle_response!(response, expected: 200)
+      Resources::Budget.new(self, data)
+    end
+
+    # Update specified fields of a budget's policy, leaving the rest
+    # unchanged.
+    #
+    # Follows JSON merge patch semantics, and recurses into `strategy`, so
+    # e.g. the burst can be changed without restating the type and period:
+    #
+    #     update_budget("emails", strategy: {burst: 5})
+    #
+    # Within `strategy`, an absent field is left alone and `burst: nil`
+    # clears it back to the default value of the allocation. `burst` is
+    # the only field with a meaningful "unset": a strategy with no type, or
+    # a `time_based` strategy with no period, is not a valid strategy.
+    #
+    # Raises `Zizq::NotFoundError` if no budget exists under this key.
+    #
+    # @rbs key: String
+    # @rbs allocation: Integer?
+    # @rbs strategy: Zizq::budget_strategy_patch?
+    # @rbs return: Zizq::Resources::Budget
+    def update_budget(key, allocation: nil, strategy: nil)
+      body = {
+        allocation:,
+        strategy: strategy && wire_strategy(strategy)
+      }.compact
+      response = patch("/budgets/#{enc(key)}", body)
+      data = handle_response!(response, expected: 200)
+      Resources::Budget.new(self, data)
+    end
+
+    # Delete a budget.
+    #
+    # Raises `Zizq::NotFoundError` if no budget exists under this key.
+    #
+    # Raises a `Zizq::ConflictError` (409) while anything still
+    # references it.
+    #
+    # @rbs key: String
+    # @rbs return: void
+    def delete_budget(key)
+      response = delete("/budgets/#{enc(key)}")
+      handle_response!(response, expected: 204)
+      nil
+    end
+
+    # Replace the whole set of budgets a job is bound to.
+    #
+    # Budgets omitted from `budgets` will be unbound. Passing `[]` is
+    # the same as `clear_job_budgets`.
+    #
+    # Only queued (scheduled, ready) jobs may have their budgets changed —
+    # an in-flight job already debited tokens against its budgets, and
+    # jobs in a terminal state are immutable to all further changes.
+    # Either raises a `Zizq::ClientError` (422).
+    #
+    # Requires a Pro license on the server, else a `Zizq::ClientError`
+    # (403) is raised.
+    #
+    # @rbs id: String
+    # @rbs budgets: Array[Zizq::budget_binding_params]
+    # @rbs return: Resources::Job
+    def replace_job_budgets(id, budgets:)
+      body = { budgets: budgets.map { |b| wire_binding(b) } }
+      response = put("/jobs/#{enc(id)}/budgets", body)
+      data = handle_response!(response, expected: 200)
+      Resources::Job.new(self, data)
+    end
+
+    # Unbind every budget from a job, leaving it unthrottled.
+    #
+    # @rbs id: String
+    # @rbs return: Resources::Job
+    def clear_job_budgets(id)
+      response = delete("/jobs/#{enc(id)}/budgets")
+      data = handle_response!(response, expected: 200)
+      Resources::Job.new(self, data)
+    end
+
+    # Bind a job to a budget it is not already bound to.
+    #
+    # Raises a `Zizq::ConflictError` (409) if the job is already bound
+    # to this budget, leaving the existing binding untouched — use
+    # `put_job_budget` to replace it, or `update_job_budget` to change
+    # only its cost.
+    #
+    # `create_with` declares the budget's policy should it not exist
+    # yet, binding and creating in one atomic call. It is ignored when
+    # the budget already exists.
+    #
+    # @rbs id: String
+    # @rbs key: String
+    # @rbs cost: Integer?
+    # @rbs create_with: Zizq::budget_policy?
+    # @rbs return: Resources::Job
+    def add_job_budget(id, key, cost: nil, create_with: nil)
+      body = binding_body(cost:, create_with:)
+      response = post("/jobs/#{enc(id)}/budgets/#{enc(key)}", body)
+      data = handle_response!(response, expected: 200)
+      Resources::Job.new(self, data)
+    end
+
+    # Bind a job to a budget, replacing any existing binding to it.
+    #
+    # Unlike `add_job_budget` this never conflicts. The binding is
+    # replaced whole, so a `cost` left unset returns to the default of 1
+    # rather than keeping what was there.
+    #
+    # @rbs id: String
+    # @rbs key: String
+    # @rbs cost: Integer?
+    # @rbs create_with: Zizq::budget_policy?
+    # @rbs return: Resources::Job
+    def put_job_budget(id, key, cost: nil, create_with: nil)
+      body = binding_body(cost:, create_with:)
+      response = put("/jobs/#{enc(id)}/budgets/#{enc(key)}", body)
+      data = handle_response!(response, expected: 200)
+      Resources::Job.new(self, data)
+    end
+
+    # Change what an existing binding costs, leaving the rest alone.
+    #
+    # Raises `Zizq::NotFoundError` if the job is not bound to this
+    # budget. Unlike `put_job_budget`, a change of cost has nothing to
+    # apply to and does not create the binding if missing.
+    #
+    # Raises a `Zizq::ClientError` (422) if the new cost exceeds the
+    # budget's capacity.
+    #
+    # @rbs id: String
+    # @rbs key: String
+    # @rbs cost: Integer
+    # @rbs return: Resources::Job
+    def update_job_budget(id, key, cost:)
+      response = patch("/jobs/#{enc(id)}/budgets/#{enc(key)}", { cost: })
+      data = handle_response!(response, expected: 200)
+      Resources::Job.new(self, data)
+    end
+
+    # Unbind one budget from a job, leaving its other budgets alone.
+    #
+    # Raises `Zizq::NotFoundError` if the job is not bound to it.
+    #
+    # @rbs id: String
+    # @rbs key: String
+    # @rbs return: Resources::Job
+    def delete_job_budget(id, key)
+      response = delete("/jobs/#{enc(id)}/budgets/#{enc(key)}")
+      data = handle_response!(response, expected: 200)
+      Resources::Job.new(self, data)
+    end
+
+    # Bind every job matching the filter to a budget, skipping over the
+    # ones that are already bound to it.
+    #
+    # The bulk form of `add_job_budget`; each of these takes the same
+    # name with `job` widened to `all_jobs`.
+    #
+    # Filters in the `where:` argument use the same keys as `list_jobs`.
+    # An unfiltered call binds every queued job on the server.
+    #
+    # Unlike the single-job form this does not conflict but simply
+    # skips.
+    #
+    # @rbs key: String
+    # @rbs where: Zizq::where_params
+    # @rbs cost: Integer?
+    # @rbs create_with: Zizq::budget_policy?
+    # @rbs return: Zizq::bulk_budget_change
+    def add_all_jobs_budget(key, where: {}, cost: nil, create_with: nil)
+      bulk_budget_request(
+        :post,
+        "/jobs/budgets/#{enc(key)}",
+        where,
+        binding_body(cost:, create_with:)
+      )
+    end
+
+    # Bind every job matching the filter to a budget, replacing any
+    # existing binding to it.
+    #
+    # See `add_all_jobs_budget` for the filter semantics, and
+    # `put_job_budget` for how a binding is replaced.
+    #
+    # @rbs key: String
+    # @rbs where: Zizq::where_params
+    # @rbs cost: Integer?
+    # @rbs create_with: Zizq::budget_policy?
+    # @rbs return: Zizq::bulk_budget_change
+    def put_all_jobs_budget(key, where: {}, cost: nil, create_with: nil)
+      bulk_budget_request(
+        :put,
+        "/jobs/budgets/#{enc(key)}",
+        where,
+        binding_body(cost:, create_with:)
+      )
+    end
+
+    # Change what an existing binding costs, across every job matching
+    # the filter. Jobs not bound to this budget are skipped.
+    #
+    # The bulk form of `update_job_budget`.
+    #
+    # Raises a `Zizq::ClientError` (422) if the new cost exceeds the
+    # budget's capacity.
+    #
+    # @rbs key: String
+    # @rbs cost: Integer
+    # @rbs where: Zizq::where_params
+    # @rbs return: Zizq::bulk_budget_change
+    def update_all_jobs_budget(key, cost:, where: {})
+      bulk_budget_request(:patch, "/jobs/budgets/#{enc(key)}", where, { cost: })
+    end
+
+    # Unbind one budget from every job matching the filter, leaving
+    # their other budgets alone. The bulk form of `delete_job_budget`.
+    #
+    # This is the way to drain a budget before deleting it, since
+    # `delete_budget` refuses while anything is still bound to it.
+    #
+    # @rbs key: String
+    # @rbs where: Zizq::where_params
+    # @rbs return: Zizq::bulk_budget_change
+    def delete_all_jobs_budget(key, where: {})
+      bulk_budget_request(:delete, "/jobs/budgets/#{enc(key)}", where, nil)
+    end
+
+    # Unbind *every* budget from every job matching the filter. The
+    # bulk form of `clear_job_budgets`.
+    #
+    # Beware: An unfiltered call leaves every queued job on the server
+    # unthrottled — include a filter unless that is the intent.
+    #
+    # @rbs where: Zizq::where_params
+    # @rbs return: Zizq::bulk_budget_change
+    def clear_all_jobs_budgets(where: {})
+      bulk_budget_request(:delete, "/jobs/budgets", where, nil)
+    end
+
     # List all cron group names.
     #
     # @rbs return: Array[String]
@@ -541,13 +891,19 @@ module Zizq
     # Entries not present in the request are removed. Entries with unchanged
     # expressions preserve their scheduling state.
     #
+    # The timezone applies to every entry that does not specify one of its
+    # own. Since this replaces the group in full, omitting it clears whatever
+    # the group had.
+    #
     # @rbs name: String
     # @rbs paused: bool?
+    # @rbs timezone: String?
     # @rbs entries: Array[Zizq::cron_entry_params]
     # @rbs return: Resources::CronGroup
-    def replace_cron_group(name, paused: nil, entries: [])
+    def replace_cron_group(name, paused: nil, timezone: nil, entries: [])
       body = {
         paused:,
+        timezone:,
         entries: entries.map { |entry| build_cron_entry(**entry) }
       }.compact
       response = put("/crons/#{enc(name)}", body)
@@ -606,7 +962,7 @@ module Zizq
 
     # Add a single entry to a cron group (creates the group if needed).
     #
-    # Raises a ClientError (409 Conflict) if an entry with the same name
+    # Raises a `Zizq::ConflictError` (409) if an entry with the same name
     # already exists.
     #
     # @rbs group: String
@@ -997,6 +1353,8 @@ module Zizq
     # @rbs retention: Zizq::retention?
     # @rbs unique_key: String?
     # @rbs unique_while: Zizq::unique_scope?
+    # @rbs batch: Zizq::batch?
+    # @rbs budgets: Array[Zizq::budget_binding_params]?
     # @rbs return: Hash[Symbol, untyped]
     def build_cron_job(
       type: nil,
@@ -1007,15 +1365,19 @@ module Zizq
       backoff: nil,
       retention: nil,
       unique_key: nil,
-      unique_while: nil
+      unique_while: nil,
+      batch: nil,
+      budgets: nil
     )
       job = { type:, queue:, payload: } #: Hash[Symbol, untyped]
       job[:priority] = priority if priority
       job[:retry_limit] = retry_limit if retry_limit
-      job[:backoff] = backoff if backoff
-      job[:retention] = retention if retention
+      job[:backoff] = wire_backoff(backoff) if backoff
+      job[:retention] = wire_retention(retention) if retention
       job[:unique_key] = unique_key if unique_key
       job[:unique_while] = unique_while.to_s if unique_while
+      job[:batch] = batch if batch
+      job[:budgets] = budgets.map { |b| wire_binding(b) } if budgets&.any?
       job
     end
 
@@ -1031,6 +1393,7 @@ module Zizq
     # @rbs priority: (Integer | Range[Integer?])?
     # @rbs ready_at: (Zizq::to_f | Range[Zizq::to_f?])?
     # @rbs attempts: (Integer | Range[Integer?])?
+    # @rbs budgets_key: (String | Array[String])?
     # @rbs return: Hash[Symbol, untyped]
     def validate_where(
       id: nil,
@@ -1040,7 +1403,8 @@ module Zizq
       filter: nil,
       priority: nil,
       ready_at: nil,
-      attempts: nil
+      attempts: nil,
+      budgets_key: nil
     )
       {
         id:,
@@ -1050,7 +1414,8 @@ module Zizq
         filter:,
         priority: encode_range(priority),
         ready_at: encode_range(ready_at) { |v| (v.to_f * 1000).to_i },
-        attempts: encode_range(attempts)
+        attempts: encode_range(attempts),
+        budgets_key:
       }.compact
     end
 
@@ -1165,43 +1530,179 @@ module Zizq
       end
 
       unless backoff.equal?(UNCHANGED)
-        body[:backoff] = if backoff.equal?(RESET)
-          nil
-        else
-          {
-            exponent: backoff[:exponent].to_f,
-            base_ms: (backoff[:base].to_f * 1000).to_i,
-            jitter_ms: (backoff[:jitter].to_f * 1000).to_i
-          }
-        end
+        body[:backoff] = backoff.equal?(RESET) ? nil : wire_backoff(backoff)
       end
 
       unless retention.equal?(UNCHANGED)
         body[:retention] = if retention.equal?(RESET)
           nil
         else
-          ret = {} #: Hash[Symbol, Integer]
-          ret[:completed_ms] = (
-            retention[:completed].to_f * 1000
-          ).to_i if retention[:completed]
-          ret[:dead_ms] = (retention[:dead].to_f * 1000).to_i if retention[
-            :dead
-          ]
-          ret
+          wire_retention(retention)
         end
       end
 
       body
     end
 
+    # Convert a `Zizq::backoff` (fractional seconds) into the server's form
+    # (integer milliseconds under keys suffixed `_ms`).
+    #
+    # @rbs backoff: Zizq::backoff
+    # @rbs return: Hash[Symbol, untyped]
+    def wire_backoff(backoff)
+      {
+        exponent: backoff[:exponent].to_f,
+        base_ms: (backoff[:base].to_f * 1000).to_i,
+        jitter_ms: (backoff[:jitter].to_f * 1000).to_i
+      }
+    end
+
+    # Convert a `Zizq::retention` (fractional seconds) into the server's form
+    # (integer milliseconds under keys suffixed `_ms`). Both fields are
+    # optional.
+    #
+    # @rbs retention: Zizq::retention
+    # @rbs return: Hash[Symbol, Integer]
+    def wire_retention(retention)
+      wire = {} #: Hash[Symbol, Integer]
+      wire[:completed_ms] = (
+        retention[:completed].to_f * 1000
+      ).to_i if retention[:completed]
+      wire[:dead_ms] = (retention[:dead].to_f * 1000).to_i if retention[:dead]
+      wire
+    end
+
+    # Build the body for a single binding, where the budget key travels
+    # in the path rather than the body.
+    #
+    # @rbs cost: Integer?
+    # @rbs create_with: Zizq::budget_policy?
+    # @rbs return: Hash[Symbol, untyped]
+    def binding_body(cost:, create_with:)
+      body = {} #: Hash[Symbol, untyped]
+      body[:cost] = cost if cost
+      body[:create_with] = wire_policy(create_with) if create_with
+      body
+    end
+
+    # Convert a `Zizq::budget_binding_params` into the wire form, key included.
+    #
+    # @rbs binding: Zizq::budget_binding_params
+    # @rbs return: Hash[Symbol, untyped]
+    def wire_binding(binding)
+      { key: binding[:key] }.merge(
+        binding_body(cost: binding[:cost], create_with: binding[:create_with])
+      )
+    end
+
+    # Convert a `Zizq::budget_policy` into the wire form.
+    #
+    # @rbs policy: Zizq::budget_policy
+    # @rbs return: Hash[Symbol, untyped]
+    def wire_policy(policy)
+      {
+        allocation: policy[:allocation],
+        strategy: wire_strategy(policy[:strategy])
+      }
+    end
+
+    # Send one of the bulk job-budget requests and read its result.
+    #
+    # `body` is `nil` for the two that carry none, which are sent as
+    # `DELETE` with the filter in the query string.
+    #
+    # @rbs method: Symbol
+    # @rbs path: String
+    # @rbs where: Zizq::where_params
+    # @rbs body: Hash[Symbol, untyped]?
+    # @rbs return: Zizq::bulk_budget_change
+    def bulk_budget_request(method, path, where, body)
+      params = filter_params(where)
+
+      # An empty multi-value filter matches nothing — short-circuit
+      # rather than send a request that would match everything.
+      return { changed: 0, blocked: [] } if params.nil?
+
+      response =
+        case method
+        when :post
+          post(build_path(path, params:), body || {})
+        when :put
+          put(build_path(path, params:), body || {})
+        when :patch
+          patch(path, body || {}, params:)
+        else
+          delete(path, params:)
+        end
+      data = handle_response!(response, expected: 200)
+      { changed: data.fetch("changed"), blocked: data.fetch("blocked") }
+    end
+
+    # Validate a `where:` filter and build its query params.
+    #
+    # Returns `nil` when a multi-value filter is present but empty,
+    # which matches nothing — callers short-circuit rather than send a
+    # request that would match everything instead.
+    #
+    # @rbs where: Zizq::where_params
+    # @rbs return: Hash[Symbol, untyped]?
+    def filter_params(where)
+      params =
+        build_where_params(
+          validate_where(**where),
+          multi_keys: MULTI_FILTER_KEYS
+        )
+
+      # Both `[]` and `""` mean "match nothing"; an empty array has
+      # already been joined into an empty string by this point.
+      if MULTI_FILTER_KEYS.any? { |key| params[wire_name(key)] == "" }
+        return nil
+      end
+
+      params
+    end
+
+    # Convert a budget strategy into the wire form — the period as
+    # integer milliseconds under `duration_ms`, and the kind as a
+    # string. A `while_in_flight` strategy carries neither field.
+    #
+    # Takes the merge-patch shape, which a whole `Zizq::budget_strategy`
+    # also satisfies, so `create_budget` and `update_budget` share this.
+    # Key presence is what the server reads either way: a field absent
+    # from a patch is absent from the body and left alone, while an
+    # explicit `burst: nil` is sent as JSON null and clears the burst.
+    # That is why `burst` is tested with `key?` rather than for truth.
+    #
+    # @rbs strategy: Zizq::budget_strategy_patch
+    # @rbs return: Hash[Symbol, untyped]
+    def wire_strategy(strategy)
+      wire = {} #: Hash[Symbol, untyped]
+      wire[:type] = strategy[:type].to_s if strategy[:type]
+      if (duration = strategy[:duration])
+        wire[:duration_ms] = (duration.to_f * 1000).to_i
+      end
+      wire[:burst] = strategy[:burst] if strategy.key?(:burst)
+      wire
+    end
+
     # Build query params for list endpoints, joining multi-value keys with ",".
+    # The query parameter name for a filter argument, which differs from
+    # the Ruby name only where `API_FILTER_NAMES` says so.
+    #
+    # @rbs key: Symbol
+    # @rbs return: Symbol
+    def wire_name(key)
+      API_FILTER_NAMES.fetch(key, key)
+    end
+
     def build_where_params(options, multi_keys: []) #: (Hash[Symbol, untyped], ?multi_keys: Array[Symbol]) -> Hash[Symbol, untyped]
       params = {} #: Hash[Symbol, untyped]
       options.each do |key, value|
-        if multi_keys.include?(key) && value.is_a?(Array)
-          params[key] = value.join(",")
+        params[wire_name(key)] = if multi_keys.include?(key) &&
+             value.is_a?(Array)
+          value.join(",")
         else
-          params[key] = value
+          value
         end
       end
       params
@@ -1438,6 +1939,8 @@ module Zizq
           case status
           when 404
             NotFoundError
+          when 409
+            ConflictError
           when 400..499
             ClientError
           when 500..599