flexiq 2.1.0

data/lib/flexiq/client.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  # A producer client: submit work and workflows, read them back, list, cancel and count jobs.
+  #
+  #   client = FlexiQ::Client.new("https://flexiq.internal:50051", token: ENV.fetch("FLEXIQ_TOKEN"))
+  #   job = client.enqueue("send_receipt", args: [{ "order_id" => "o-1" }], queue: "emails").job
+  #   client.get_job(job.id).status # => :pending
+  #
+  # The namespace is the token's, fixed when it was minted; no call can name another.
+  # Methods raise RPCError when the server refuses and TransportError when no answer arrived.
+  # Thread-safe; calls on one client are serialised over one connection, and each watch holds a
+  # connection of its own.
+  class Client
+    # See Transport#initialize for the keyword options (TLS, timeouts, user agent).
+    def initialize(url, token:, transport: nil, **)
+      @transport = transport || Transport.new(url, token: token, **)
+    end
+
+    # Submits one job. Keywords other than `args:` / `kwargs:` are EnqueueOptions.
+    #
+    # Not idempotent. If this raises TransportError, or RPCError with code UNAVAILABLE,
+    # DEADLINE_EXCEEDED or CANCELLED, the job may exist; resend only with `unique_key` set.
+    def enqueue(task_name, args: [], kwargs: {}, **options)
+      request = EnqueueRequest.new(task_name: task_name, args: args, kwargs: kwargs, options: options)
+      EnqueueResult.from_json(@transport.post("/v1/jobs", request.to_wire))
+    end
+
+    # Submits several jobs in one call; returns one BatchItemResult per request, in order.
+    #
+    # Not atomic. An item's error is that item alone. When the whole call raises instead,
+    # nothing was enqueued and `RPCError#batch_index` names the item that failed.
+    def enqueue_batch(requests)
+      items = requests.map { |request| coerce_request(request).to_wire }
+      response = @transport.post("/v1/jobs:batchEnqueue", { "items" => items })
+      batch_results(response["results"], items.length)
+    end
+
+    # Reads one job. The payload and result are left out unless asked for: they are the largest
+    # things a job carries. A job in another namespace reads as JOB_NOT_FOUND.
+    def get_job(job_id, include_payload: false, include_result: false)
+      fetch_job(job_id, include_payload: include_payload, include_result: include_result)
+    end
+
+    # Reads one page of jobs, newest first. Every filter is optional; `status` is a
+    # FlexiQ::JobStatus symbol. A grant narrowed to queues needs a `queue:` it reaches, one
+    # narrowed to tasks a `task_name:`, or the call raises RPCError SCOPE_DENIED: a listing is
+    # refused, never filtered silently.
+    def list_jobs(status: nil, queue: nil, task_name: nil, page_size: nil, page_token: nil)
+      query = {
+        "status" => status.nil? ? nil : JobStatus.dump(status), "queue" => queue, "taskName" => task_name,
+        "pageSize" => page_size, "pageToken" => page_token
+      }
+      JobPage.from_json(@transport.get("/v1/jobs", query))
+    end
+
+    # Every job `list_jobs` reaches with these filters, one page at a time. Without a block,
+    # returns an Enumerator; a page is fetched only when iteration reaches it.
+    def each_job(status: nil, queue: nil, task_name: nil, page_size: nil, &block)
+      return enum_for(:each_job, status: status, queue: queue, task_name: task_name, page_size: page_size) unless block
+
+      filters = { status: status, queue: queue, task_name: task_name, page_size: page_size }
+
+      # Not `loop`: it would swallow a StopIteration the caller's block raised.
+      page = nil
+      until page&.last_page?
+        page = list_jobs(**filters, page_token: page&.next_page_token)
+        page.jobs.each(&block)
+      end
+    end
+
+    # Requests cancellation and returns the job as the call left it. Idempotent.
+    def cancel_job(job_id)
+      job_from(@transport.post("/v1/jobs/#{Wire::Path.segment(job_id)}:cancel"))
+    end
+
+    # Counts jobs by state in `queue`, or across the namespace when `queue` is nil.
+    def queue_stats(queue = nil)
+      path = queue.nil? ? "/v1/stats" : "/v1/queues/#{Wire::Path.segment(queue)}/stats"
+      QueueStats.from_json(@transport.get(path))
+    end
+
+    # Follows jobs by id until each is `terminal?`. Yields a `:snapshot` JobTransition (or
+    # JobNotFound) per id, then live transitions. At most 100 ids. Enumerator without a block.
+    #
+    # A dropped stream reopens on the unfinished ids only.
+    def watch_jobs(job_ids, &block)
+      return enum_for(:watch_jobs, job_ids) unless block
+
+      Watch::ByIds.new(@transport, job_ids).run(&block)
+      nil
+    end
+
+    # Follows `queue` (nil = "default") until the block breaks. Yields a WatchCheckpoint, then
+    # live JobTransitions; no snapshot. Pass the last `cursor` back as `resume_cursor:` to replay.
+    #
+    # A dropped stream resumes from its last cursor; an expired one yields a WatchGap.
+    # Sees only transitions the reached server process handles.
+    def watch_queue(queue = nil, resume_cursor: nil, &block)
+      return enum_for(:watch_queue, queue, resume_cursor: resume_cursor) unless block
+
+      Watch::ByQueue.new(@transport, queue, resume_cursor).run(&block)
+    end
+
+    # Blocks until the job is finished; returns it with its result. Watches, never polls.
+    # Raises WaitTimeoutError after `timeout` seconds (nil: no limit), RPCError JOB_NOT_FOUND
+    # for an id this token cannot see.
+    def wait(job_id, timeout:)
+      deadline = Deadline.within(timeout)
+      Watch::ByIds.new(@transport, [job_id], deadline: deadline).run { nil }
+      read_finished(job_id, deadline)
+    end
+
+    # Submits a static workflow graph (a FlexiQ::WorkflowGraph) and returns the new run's id.
+    # The server enqueues one job per node, chained by the edges; any worker with workflow
+    # tracking enabled advances the run. `params_json` is JSON text the run carries, never a call.
+    #
+    # Static graphs only: a node setting gate, cache, fan_out, fan_in or sub_workflow is refused
+    # with WORKFLOW_CONSTRUCT_UNSUPPORTED, naming one node (`RPCError#workflow_construct`).
+    # Every submission is version 1 of `name`; a different graph under a used name is refused.
+    #
+    # Not idempotent, and there is no `unique_key`: a run cannot be found by name, so a call that
+    # raised TransportError, or RPCError UNAVAILABLE / DEADLINE_EXCEEDED / CANCELLED, may have
+    # submitted a run whose id is lost. A retry submits a second run; never retry blind.
+    def submit_workflow(name, graph, params_json: nil)
+      raise ArgumentError, "a workflow name must be a non-empty String" unless name.is_a?(String) && !name.empty?
+      raise ArgumentError, "graph must be a FlexiQ::WorkflowGraph, got #{graph.class}" unless graph.is_a?(WorkflowGraph)
+      unless params_json.nil? || params_json.is_a?(String)
+        raise ArgumentError, "params_json must be JSON text (a String), got #{params_json.class}"
+      end
+
+      body = { "name" => name, "graph" => graph.validate!.to_wire, "paramsJson" => params_json }.compact
+      run_id = @transport.post("/v1/workflows", body)["runId"]
+      raise TransportError, "the server answered a submission without a run id" if run_id.to_s.empty?
+
+      run_id
+    end
+
+    # Reads a workflow run and every node it has, as a WorkflowRunView. A run in another
+    # namespace, or one whose jobs a narrowed grant does not all reach, reads as NOT_FOUND.
+    def get_workflow_run(run_id)
+      WorkflowRunView.from_json(@transport.get("/v1/workflows/#{Wire::Path.segment(run_id)}"))
+    end
+
+    # Closes the underlying connection; the next call reopens it.
+    def close = @transport.close
+
+    private
+
+    # The job is done, so only the read can fail; retry what clears, within the deadline.
+    # The deadline also caps this read, so a stalled answer cannot outlast `wait`'s timeout.
+    def read_finished(job_id, deadline)
+      backoff = Backoff.new
+      begin
+        fetch_job(job_id, include_result: true, deadline: deadline)
+      rescue TransportError, RPCError => e
+        raise if e.is_a?(RPCError) && !e.retryable?
+        raise WaitTimeoutError, "gave up after #{deadline.seconds}s reading job #{job_id}" if deadline&.expired?
+
+        backoff.pause(deadline)
+        retry
+      end
+    end
+
+    def fetch_job(job_id, include_payload: false, include_result: false, deadline: nil)
+      query = { "includePayload" => include_payload || nil, "includeResult" => include_result || nil }
+      job_from(@transport.get("/v1/jobs/#{Wire::Path.segment(job_id)}", query, deadline: deadline))
+    end
+
+    def coerce_request(request)
+      case request
+      when EnqueueRequest then request
+      when Hash then EnqueueRequest.new(**request)
+      else raise ArgumentError, "a batch item must be an EnqueueRequest or a Hash, got #{request.class}"
+      end
+    end
+
+    # A short or long answer cannot be paired with its requests; guessing would attribute an
+    # outcome to the wrong job, or report an item that never landed as handled.
+    def batch_results(results, expected)
+      unless results.is_a?(Array) && results.length == expected
+        got = results.is_a?(Array) ? results.length : "no"
+        raise TransportError, "the batch answered #{got} result(s) for #{expected} item(s)"
+      end
+
+      results.each_with_index.map { |result, index| BatchItemResult.from_json(result, index) }
+    end
+
+    def job_from(response)
+      json = response["job"]
+      raise TransportError, "the server answered without a job" unless json.is_a?(Hash)
+
+      Job.from_json(json)
+    end
+  end
+end

data/lib/flexiq/deadline.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  # A monotonic-clock deadline, immune to wall-clock steps.
+  Deadline = Data.define(:at, :seconds) do
+    # nil for nil (no limit).
+    def self.within(seconds)
+      return nil if seconds.nil?
+      raise ArgumentError, "a timeout must be a positive number of seconds, got #{seconds.inspect}" unless
+        seconds.is_a?(Numeric) && seconds.positive?
+
+      new(at: now + seconds, seconds: seconds)
+    end
+
+    def self.now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    def remaining = [at - self.class.now, 0].max
+
+    def expired? = remaining.zero?
+
+    # `limit`, capped at the time left.
+    def cap(limit) = [limit, remaining].min
+  end
+end

data/lib/flexiq/debounce.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  # Collapses a burst of enqueues sharing `key` into one job. Durations are seconds.
+  Debounce = Data.define(:key, :window, :max_wait, :replace_payload, :max_pending) do
+    def initialize(key:, window: nil, max_wait: nil, replace_payload: false, max_pending: nil)
+      super
+    end
+
+    def to_wire
+      {
+        "key" => key,
+        "window" => window && Wire::Duration.dump(window),
+        "maxWait" => max_wait && Wire::Duration.dump(max_wait),
+        "replacePayload" => replace_payload || nil,
+        "maxPending" => max_pending && Wire::Int64.dump(max_pending)
+      }.compact
+    end
+  end
+end

data/lib/flexiq/edge_condition.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  # `EdgeCondition` as symbols: how a node's inbound edges gate it on its predecessors' outcome.
+  # nil (unset) and `:always` both mean no filter.
+  module EdgeCondition
+    WIRE_NAME = {
+      on_success: "EDGE_CONDITION_ON_SUCCESS",
+      on_failure: "EDGE_CONDITION_ON_FAILURE",
+      always: "EDGE_CONDITION_ALWAYS"
+    }.freeze
+
+    module_function
+
+    # The wire name; nil stays nil so the field is omitted. A String passes as-is.
+    def dump(condition)
+      case condition
+      when nil, String then condition
+      when Symbol then WIRE_NAME.fetch(condition) { raise ArgumentError, "unknown edge condition #{condition.inspect}" }
+      else raise ArgumentError, "an edge condition must be a Symbol or a String, got #{condition.class}"
+      end
+    end
+  end
+end

data/lib/flexiq/enqueue_options.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  # Per-job settings for an enqueue. Every field is optional; an unset one takes the server's
+  # default. Times are `Time`, durations are seconds (Integer, Float or Rational).
+  #
+  # `unique_key` dedupes against the *active* job only — once it finishes the key is free again —
+  # so it is the value to reuse when resending a write whose outcome is unknown.
+  EnqueueOptions = Data.define(
+    :queue, :priority, :max_retries, :scheduled_at, :timeout, :unique_key, :metadata,
+    :notes, :depends_on, :expires_at, :result_ttl, :debounce
+  ) do
+    def initialize(queue: nil, priority: nil, max_retries: nil, scheduled_at: nil, timeout: nil,
+                   unique_key: nil, metadata: nil, notes: nil, depends_on: [], expires_at: nil,
+                   result_ttl: nil, debounce: nil)
+      debounce = Debounce.new(**debounce) if debounce.is_a?(Hash)
+      super
+    end
+
+    # The proto3 JSON `EnqueueOptions` object, unset fields omitted.
+    def to_wire
+      {
+        "queue" => queue,
+        "priority" => priority,
+        "maxRetries" => max_retries,
+        "scheduledAt" => scheduled_at && Wire::Timestamp.dump(scheduled_at),
+        "timeout" => timeout && Wire::Duration.dump(timeout),
+        "uniqueKey" => unique_key,
+        "metadata" => metadata,
+        "notes" => notes,
+        "dependsOn" => depends_on.empty? ? nil : depends_on.map(&:to_s),
+        "expiresAt" => expires_at && Wire::Timestamp.dump(expires_at),
+        "resultTtl" => result_ttl && Wire::Duration.dump(result_ttl),
+        "debounce" => debounce&.to_wire
+      }.compact
+    end
+  end
+end

data/lib/flexiq/enqueue_request.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  # One job to submit: a task name, its call arguments and its options.
+  #
+  # The arguments travel as the `raw` CBOR envelope, so the bytes — and any `auto:` key derived
+  # from them — match every other FlexiQ runtime's. Prefer one Hash argument (`args: [{...}]`);
+  # it maps onto every runtime's handler-binding model.
+  EnqueueRequest = Data.define(:task_name, :args, :kwargs, :options) do
+    def initialize(task_name:, args: [], kwargs: {}, options: EnqueueOptions.new)
+      raise ArgumentError, "task_name must be a non-empty String" unless task_name.is_a?(String) && !task_name.empty?
+
+      options = EnqueueOptions.new(**options) if options.is_a?(Hash)
+      super
+    end
+
+    # The proto3 JSON `EnqueueRequest` object.
+    def to_wire
+      wire = { "taskName" => task_name, "raw" => Wire::Bytes.dump(Payload.encode_call(args, kwargs)) }
+      opts = options.to_wire
+      wire["options"] = opts unless opts.empty?
+      wire
+    end
+  end
+end

data/lib/flexiq/enqueue_result.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  # What an accepted enqueue returned. `deduplicated` is true when a live job already held the
+  # `unique_key` and that job came back instead of a new one.
+  EnqueueResult = Data.define(:job, :deduplicated) do
+    def self.from_json(json)
+      new(job: json["job"] && Job.from_json(json["job"]), deduplicated: json["deduplicated"] == true)
+    end
+
+    alias_method :deduplicated?, :deduplicated
+  end
+end

data/lib/flexiq/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  # Root of every error this gem raises, so one `rescue FlexiQ::Error` covers them all.
+  class Error < StandardError; end
+
+  # The client was built with settings it cannot honour (no token, plaintext without opt-in, …).
+  class ConfigurationError < Error; end
+
+  # A value could not be written as, or read from, the CBOR payload envelope.
+  class CodecError < Error; end
+
+  # The request never produced a FlexiQ answer: DNS, connect, TLS, timeout, or a non-FlexiQ body.
+  #
+  # On a write this does not mean the write failed — the connection may have dropped after
+  # the server committed it. Retry a write only with `unique_key` set, reusing the same value.
+  class TransportError < Error; end
+
+  # Client#wait timed out before the job finished. The job itself is untouched.
+  class WaitTimeoutError < Error; end
+end

data/lib/flexiq/job.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  # One job as the server reports it.
+  #
+  # Timestamps are `Time` (UTC), durations are seconds as `Rational`, and `payload` / `result` are
+  # the raw envelope bytes — nil unless requested on `Client#get_job` and present. `status` is a
+  # Symbol from FlexiQ::JobStatus, or the raw wire value when this build does not know it.
+  Job = Data.define(
+    :id, :queue, :task_name, :status, :priority, :created_at, :scheduled_at,
+    :retry_count, :max_retries, :timeout, :cancel_requested, :has_deps, :namespace,
+    :started_at, :completed_at, :payload, :result, :error, :progress, :metadata, :notes,
+    :unique_key, :expires_at, :result_ttl, :debounce_key, :enqueued_by
+  ) do
+    # Builds a Job from its proto3 JSON object; unknown keys are ignored as "not this build".
+    def self.from_json(json)
+      new(
+        id: json["id"], queue: json["queue"], task_name: json["taskName"],
+        status: JobStatus.load(json["status"]), priority: json["priority"] || 0,
+        created_at: Wire::Timestamp.load(json["createdAt"]),
+        scheduled_at: Wire::Timestamp.load(json["scheduledAt"]),
+        retry_count: json["retryCount"] || 0, max_retries: json["maxRetries"] || 0,
+        timeout: Wire::Duration.load(json["timeout"]),
+        cancel_requested: json["cancelRequested"] == true, has_deps: json["hasDeps"] == true,
+        namespace: json["namespace"],
+        started_at: Wire::Timestamp.load(json["startedAt"]),
+        completed_at: Wire::Timestamp.load(json["completedAt"]),
+        payload: Wire::Bytes.load(json["payload"]), result: Wire::Bytes.load(json["result"]),
+        error: json["error"], progress: json["progress"], metadata: json["metadata"], notes: json["notes"],
+        unique_key: json["uniqueKey"], expires_at: Wire::Timestamp.load(json["expiresAt"]),
+        result_ttl: Wire::Duration.load(json["resultTtl"]), debounce_key: json["debounceKey"],
+        enqueued_by: json["enqueuedBy"]
+      )
+    end
+
+    # Finished for good. An unrecognised status is never terminal.
+    def terminal? = JobStatus.terminal?(status)
+
+    def known_status? = JobStatus.known?(status)
+
+    def cancel_requested? = cancel_requested
+
+    # `[args, kwargs]` from the payload. Requires `get_job(..., include_payload: true)`.
+    def decode_payload
+      raise CodecError, "job #{id} carries no payload; request it with include_payload: true" if payload.nil?
+
+      Payload.decode_call(payload)
+    end
+
+    # The value the task returned. Requires `get_job(..., include_result: true)`.
+    def decode_result
+      raise CodecError, "job #{id} carries no result; request it with include_result: true" if result.nil?
+
+      Payload.decode_result(result)
+    end
+
+    # The failure as a TaskError, or nil when the job has not failed.
+    def task_error = error && TaskError.parse(error)
+  end
+end

data/lib/flexiq/job_page.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  # One page of `Client#list_jobs`, newest first. Rows never carry payload or result.
+  #
+  # `next_page_token` is opaque: pass it back as `page_token:` and read nothing out of it.
+  # It is nil on the last page.
+  JobPage = Data.define(:jobs, :next_page_token) do
+    def self.from_json(json)
+      jobs = json.fetch("jobs", [])
+      raise TransportError, "the server answered a listing whose jobs are not a list" unless jobs.is_a?(Array)
+
+      token = json["nextPageToken"]
+      new(jobs: jobs.map { |job| Job.from_json(job) }, next_page_token: token.nil? || token.empty? ? nil : token)
+    end
+
+    def last_page? = next_page_token.nil?
+  end
+end

data/lib/flexiq/job_status.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  # `JobStatus` as Ruby symbols.
+  #
+  # A value this build does not recognise is kept as the server sent it (a String name, or an
+  # Integer) and is never terminal: a newer server may grow a state, and reading it as finished
+  # would have a poller stop watching a job that is still running.
+  module JobStatus
+    BY_WIRE_NAME = {
+      "JOB_STATUS_PENDING" => :pending,
+      "JOB_STATUS_RUNNING" => :running,
+      "JOB_STATUS_COMPLETE" => :complete,
+      "JOB_STATUS_FAILED" => :failed,
+      "JOB_STATUS_DEAD" => :dead,
+      "JOB_STATUS_CANCELLED" => :cancelled
+    }.freeze
+
+    KNOWN = BY_WIRE_NAME.values.freeze
+    TERMINAL = %i[complete dead cancelled].freeze
+    WIRE_NAME = BY_WIRE_NAME.invert.freeze
+
+    module_function
+
+    def load(value) = BY_WIRE_NAME.fetch(value, value)
+
+    # The wire name for a request filter. A String passes as-is, so a state this build does not
+    # know can still be named; an unknown Symbol is a typo and is refused before the call.
+    def dump(status)
+      case status
+      when String then status
+      when Symbol then WIRE_NAME.fetch(status) { raise ArgumentError, "unknown job status #{status.inspect}" }
+      else raise ArgumentError, "a job status must be a Symbol or a String, got #{status.class}"
+      end
+    end
+
+    def known?(status) = KNOWN.include?(status)
+
+    def terminal?(status) = TERMINAL.include?(status)
+  end
+end

data/lib/flexiq/job_transition.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  # A job's state, or a change to it. `kind`: TransitionKind; `status`: JobStatus; `attempt`:
+  # retry count. `cursor` is nil on an id watch.
+  JobTransition = Data.define(
+    :job_id, :queue, :task_name, :kind, :status, :attempt, :time, :terminal,
+    :error, :reason, :timed_out, :wake_at, :cursor
+  ) do
+    def self.from_json(json, cursor: nil)
+      new(
+        job_id: json["jobId"], queue: json["queue"], task_name: json["taskName"],
+        kind: TransitionKind.load(json["kind"]), status: JobStatus.load(json["status"]),
+        attempt: Wire::Int64.load(json["attempt"]) || 0, time: Wire::Timestamp.load(json["time"]),
+        terminal: json["terminal"] == true, error: json["error"], reason: json["reason"],
+        timed_out: json["timedOut"] == true, wake_at: Wire::Timestamp.load(json["wakeAt"]), cursor: cursor
+      )
+    end
+
+    # The job is finished. Use this, never `status`: `:failed` may still retry or dead-letter.
+    def terminal? = terminal
+
+    def timed_out? = timed_out
+  end
+end

data/lib/flexiq/payload.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  # The payload envelope: one codec tag byte, then that codec's body.
+  #
+  # A call body (`Job#payload`) is a two-element CBOR array `[args, kwargs]`.
+  # A result body (`Job#result`) is a bare CBOR value with no wrapper.
+  module Payload
+    NATIVE = 0x00
+    MSGPACK = 0x01
+    CBOR_TAG = 0x02
+
+    CODEC_NAMES = { NATIVE => "language-native", MSGPACK => "MessagePack" }.freeze
+    private_constant :CODEC_NAMES
+
+    module_function
+
+    # Encodes a call as `0x02 ++ CBOR([args, kwargs])`.
+    def encode_call(args = [], kwargs = {})
+      raise ArgumentError, "args must be an Array, got #{args.class}" unless args.is_a?(Array)
+      raise ArgumentError, "kwargs must be a Hash, got #{kwargs.class}" unless kwargs.is_a?(Hash)
+
+      CBOR_TAG.chr.b << CBOR::Encoder.encode([args, kwargs])
+    end
+
+    # Encodes a task's return value as `0x02 ++ CBOR(value)`, the form `decode_result` reads.
+    def encode_result(value) = CBOR_TAG.chr.b << CBOR::Encoder.encode(value)
+
+    # Decodes a call body into `[args, kwargs]`.
+    def decode_call(bytes)
+      body = decode(bytes)
+      unless body.is_a?(Array) && body.length == 2 && body[0].is_a?(Array) && body[1].is_a?(Hash)
+        raise CodecError, "a call body must be a two-element [args, kwargs] array"
+      end
+
+      body
+    end
+
+    # Decodes a result body into the value the task returned.
+    def decode_result(bytes) = decode(bytes)
+
+    # Strips the tag and decodes the CBOR body. Untagged payloads are never sniffed:
+    # a raw CBOR or MessagePack body can begin with any byte.
+    def decode(bytes)
+      raise CodecError, "an empty payload carries no codec tag" if bytes.nil? || bytes.empty?
+
+      tag = bytes.getbyte(0)
+      return CBOR::Decoder.decode(bytes.byteslice(1..)) if tag == CBOR_TAG
+
+      name = CODEC_NAMES.fetch(tag, "reserved")
+      raise CodecError, format("payload codec tag 0x%<tag>02x (%<name>s) is not readable by this client",
+                               tag: tag, name: name)
+    end
+  end
+end

data/lib/flexiq/queue_stats.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  # Job counts by state, for one queue or the whole namespace.
+  QueueStats = Data.define(:pending, :running, :completed, :failed, :dead, :cancelled) do
+    def self.from_json(json)
+      new(**members.to_h { |name| [name, Wire::Int64.load(json[name.to_s]) || 0] })
+    end
+
+    def total = to_h.values.sum
+  end
+end

data/lib/flexiq/reason.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  # The closed list of `google.rpc.ErrorInfo.reason` values. Branch on these, never on a
+  # message: messages are for humans and may be reworded in any release.
+  #
+  # A newer server may send a reason missing here; it arrives verbatim on `RPCError#reason`.
+  module Reason
+    UNAUTHENTICATED = "UNAUTHENTICATED"
+    SCOPE_DENIED = "SCOPE_DENIED"
+    INVALID_REQUEST = "INVALID_REQUEST"
+    MALFORMED_PAYLOAD = "MALFORMED_PAYLOAD"
+    NO_SUCH_METHOD = "NO_SUCH_METHOD"
+    JOB_NOT_FOUND = "JOB_NOT_FOUND"
+    DEAD_LETTER_NOT_FOUND = "DEAD_LETTER_NOT_FOUND"
+    PERIODIC_TASK_NOT_FOUND = "PERIODIC_TASK_NOT_FOUND"
+    WORKER_NOT_FOUND = "WORKER_NOT_FOUND"
+    TOKEN_NOT_FOUND = "TOKEN_NOT_FOUND"
+    DEPENDENCY_NOT_FOUND = "DEPENDENCY_NOT_FOUND"
+    QUEUE_FULL = "QUEUE_FULL"
+    RATE_LIMITED = "RATE_LIMITED"
+    TASK_NOT_REGISTERED = "TASK_NOT_REGISTERED"
+    WORKFLOW_CONSTRUCT_UNSUPPORTED = "WORKFLOW_CONSTRUCT_UNSUPPORTED"
+    CONTRACT_TOO_OLD = "CONTRACT_TOO_OLD"
+    JOB_TIMEOUT = "JOB_TIMEOUT"
+    CLAIM_LOST = "CLAIM_LOST"
+    JOB_CANCELLED = "JOB_CANCELLED"
+    STEP_DIVERGED = "STEP_DIVERGED"
+    STEP_LIMIT_EXCEEDED = "STEP_LIMIT_EXCEEDED"
+    STEP_REFUSED = "STEP_REFUSED"
+    LOCK_HELD = "LOCK_HELD"
+    SETTING_CONFLICT = "SETTING_CONFLICT"
+    WATCH_LIMIT = "WATCH_LIMIT"
+    WATCH_OVERFLOW = "WATCH_OVERFLOW"
+    WATCH_CURSOR_EXPIRED = "WATCH_CURSOR_EXPIRED"
+    SHUTTING_DOWN = "SHUTTING_DOWN"
+    STORAGE_UNAVAILABLE = "STORAGE_UNAVAILABLE"
+    STORAGE_CONSTRAINT = "STORAGE_CONSTRAINT"
+    SERVER_MISCONFIGURED = "SERVER_MISCONFIGURED"
+    INTERNAL = "INTERNAL"
+    UNKNOWN = "UNKNOWN"
+
+    # Conditions that clear on their own. Says nothing about whether a write is safe to resend.
+    TRANSIENT = [
+      QUEUE_FULL, RATE_LIMITED, STORAGE_UNAVAILABLE, LOCK_HELD,
+      SETTING_CONFLICT, WATCH_LIMIT, WATCH_OVERFLOW, SHUTTING_DOWN
+    ].freeze
+
+    # The domain every FlexiQ ErrorInfo carries; details from any other domain are ignored.
+    DOMAIN = "flexiq.byteveda.org"
+  end
+end