flexiq 2.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9e98266383975c9d410b23e1691b7494c4f1a25c91288d5aabf0a51969da59ed
+  data.tar.gz: e95eba4c46c659286fb6aa58f3a4524004e5c2d995db6b1b168ff74195bbcea8
+SHA512:
+  metadata.gz: 388d485f608c7bf541bb4463f5568f5be19fa70dfafbe173206c11d00cad1199e8a4ff51b1f4d45ea7a9706517aa8e2d2baa75e9b7e00a4db59cbd5a74a63a86
+  data.tar.gz: 0d26e5abe9642fb86c45a525695ae4bd17dd0d291f0fa8c757c27797144bacbdd429fab627297bf2641e59598cbb1b3c8a178bdb4a4468a0991d4eafaa088da8

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pratyush Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,302 @@
+# FlexiQ Ruby client
+
+A Ruby client for the **producer door** of a running
+[`flexiq-server`](../../crates/flexiq-server): submit work, read it back, wait for it, cancel it,
+count it, and submit static workflows.
+No database credential, no native extension, no gRPC toolchain — it speaks the server's JSON
+facade with the Ruby standard library alone.
+
+It is a producer client, not an SDK: it **cannot execute tasks**. It submits work that
+somebody else's workers drain. To run tasks in Ruby, use the companion
+[`flexiq-executor`](../ruby-executor) gem, which attaches to the executor door over gRPC.
+
+## Install
+
+Ruby 3.3 or newer. The gem is not on RubyGems yet; take it from this repository with Bundler:
+
+```ruby
+# Gemfile
+gem "flexiq", git: "https://github.com/ByteVeda/flexiq", glob: "sdks/ruby/*.gemspec"
+```
+
+## Quickstart
+
+```ruby
+require "flexiq"
+
+client = FlexiQ::Client.new("https://flexiq.internal:50051", token: ENV.fetch("FLEXIQ_TOKEN"))
+
+result = client.enqueue("orders.send_receipt",
+                        args: [{ "order_id" => "ord-0001" }],
+                        queue: "emails",
+                        unique_key: "receipt-ord-0001")
+job = client.get_job(result.job.id, include_result: true)
+job.status       # => :pending, :running, :complete, :failed, :dead or :cancelled
+job.terminal?    # => false until it finishes for good
+
+client.cancel_job(job.id)
+client.queue_stats("emails").pending
+```
+
+The URL is the address the server's `FLEXIQ_GRPC_LISTEN` binds (these examples use port `50051`);
+the JSON facade shares that listener.
+
+## Surface
+
+| Method | Route | Notes |
+|---|---|---|
+| `enqueue(task, args:, kwargs:, **options)` | `POST /v1/jobs` | Options are `FlexiQ::EnqueueOptions` fields. |
+| `enqueue_batch(requests)` | `POST /v1/jobs:batchEnqueue` | One `BatchItemResult` per item. Not atomic. |
+| `get_job(id, include_payload:, include_result:)` | `GET /v1/jobs/{id}` | Payload and result only on request. |
+| `list_jobs(status:, queue:, task_name:, page_size:, page_token:)` | `GET /v1/jobs` | One `JobPage`, newest first. See [Listing](#listing). |
+| `each_job(status:, queue:, task_name:, page_size:)` | `GET /v1/jobs` | An `Enumerator` over every page. |
+| `watch_jobs(ids)` | `GET /v1/jobs:watch` (SSE) | Yields each job's transitions until all are finished. See [Waiting](#waiting). |
+| `watch_queue(queue = nil, resume_cursor:)` | `GET /v1/jobs:watch` (SSE) | Yields a queue's live transitions until you break. |
+| `wait(id, timeout:)` | `GET /v1/jobs:watch`, then `GET /v1/jobs/{id}` | The finished `Job`, with its result. |
+| `cancel_job(id)` | `POST /v1/jobs/{id}:cancel` | Idempotent. |
+| `queue_stats(queue = nil)` | `GET /v1/queues/{queue}/stats`, `GET /v1/stats` | `nil` counts the whole namespace. |
+| `submit_workflow(name, graph, params_json:)` | `POST /v1/workflows` | The run id. Static graphs only; not idempotent. See [Workflows](#workflows). |
+| `get_workflow_run(run_id)` | `GET /v1/workflows/{run_id}` | A `WorkflowRunView`: the run and every node. |
+
+Enqueue options: `queue`, `priority`, `max_retries`, `scheduled_at` (`Time`), `timeout`
+(seconds), `unique_key`, `metadata`, `notes`, `depends_on`, `expires_at` (`Time`),
+`result_ttl` (seconds), `debounce` (`FlexiQ::Debounce` or a Hash of its fields).
+
+The namespace is the token's, fixed when an operator minted it. No call can name another, and a
+job in another namespace reads as `JOB_NOT_FOUND`. If enqueues succeed and nothing ever runs
+them, check the namespace first.
+
+## Listing
+
+`list_jobs` reads one page, newest first. Every filter is optional, and `status:` takes the
+`FlexiQ::JobStatus` symbols (`:pending`, `:failed`, …). Rows never carry payload or result; read
+one job with `get_job` for those.
+
+```ruby
+page = client.list_jobs(queue: "emails", status: :failed, page_size: 100)
+page.jobs            # => [FlexiQ::Job, ...]
+page.next_page_token # => pass back as page_token: for the next page; nil on the last
+
+client.each_job(queue: "emails", status: :failed).first(500) # follows the cursor for you
+```
+
+`next_page_token` is opaque. Pass it back unchanged and read nothing out of it; a page token the
+server did not issue is refused with `RPCError` reason `INVALID_REQUEST`. `page_size` defaults to
+the server's choice (50) and is capped (500), so trust `last_page?`, not the row count.
+
+A credential whose `produce` or `read` grant is narrowed must name what the grant narrows: a
+`queue:` it reaches for a queue-narrowed grant, a `task_name:` it reaches for a task-narrowed one,
+and both when the grant narrows both. Otherwise `list_jobs` is refused with `SCOPE_DENIED`. A
+listing is never filtered down to the rows the credential can see.
+
+## Waiting
+
+Watch a job instead of polling `get_job`. `wait` blocks until the job is finished and reads it
+back with its result:
+
+```ruby
+job = client.wait(job_id, timeout: 60) # raises FlexiQ::WaitTimeoutError after 60 s; nil = no limit
+job.status        # => :complete, :dead or :cancelled
+job.decode_result
+```
+
+`watch_jobs` yields every step on the way. Each id opens with a `:snapshot` of its current
+state (or a `FlexiQ::JobNotFound`), then live transitions follow, and the call returns once
+every job is finished:
+
+```ruby
+client.watch_jobs([a, b]) do |item|
+  case item
+  in FlexiQ::JobTransition => t then puts "#{t.job_id} #{t.kind} -> #{t.status}"
+  in FlexiQ::JobNotFound => n then puts "#{n.job_id} not visible to this token"
+  end
+end
+```
+
+Decide that a job is finished by `JobTransition#terminal?`, never by its status: `:failed` is
+not final while a retry or a dead-letter is still to come.
+
+`watch_queue` follows every job in a queue until you `break`. It has no snapshot. It opens with a
+`FlexiQ::WatchCheckpoint`, and then yields one `JobTransition` per live change. Every item
+carries a `cursor`; keep the last one, checkpoints included, and pass it back as
+`resume_cursor:` to replay what you missed:
+
+```ruby
+client.watch_queue("emails", resume_cursor: saved) do |item|
+  case item
+  in FlexiQ::WatchGap then reconcile_with(client.list_jobs(queue: "emails"))
+  in FlexiQ::JobTransition => t then handle(t)
+  else nil
+  end
+  saved = item.cursor if item.respond_to?(:cursor)
+end
+```
+
+Watches keep themselves alive:
+
+- **Dropped connection, `WATCH_OVERFLOW` or `SHUTTING_DOWN`:** the watch reopens after a
+  backoff. An id watch reopens on the jobs that are not finished yet, each with a fresh
+  snapshot. A queue watch resumes from its last cursor.
+- **Expired cursor** (`WATCH_CURSOR_EXPIRED`): the server keeps a bounded window, per process.
+  The queue watch yields a `FlexiQ::WatchGap` and starts again from now. The transitions in the
+  gap are gone; `list_jobs` reads current state, not history.
+- **Failure before the first item:** it raises. This covers a wrong URL, a missing `read`
+  scope, and a token already at its cap of concurrent watches (`WATCH_LIMIT`;
+  `RPCError#watch_limit` is the cap).
+
+A queue watch only sees transitions that the server process it reached handles itself. Each
+watch holds a connection of its own, so other calls on the same client are never blocked.
+`watch_read_timeout:` (default 60 s) is how long a watch may stay silent before it counts as
+dropped. The server sends a keepalive every 15 s.
+
+## Workflows
+
+A workflow is a graph of steps. Submitting one enqueues a job per node, chained by the edges, and
+any worker with workflow tracking enabled advances the run, not only whoever submitted it.
+
+```ruby
+graph = FlexiQ::WorkflowGraph.new(
+  nodes: [
+    FlexiQ::WorkflowNode.new(name: "charge", task_name: "orders.charge", args: [order], queue: "payments"),
+    FlexiQ::WorkflowNode.new(name: "ship", task_name: "orders.ship", args: [order],
+                             condition: :on_success, timeout: 30, compensate: "orders.unship")
+  ],
+  edges: [%w[charge ship]] # or FlexiQ::WorkflowEdge.new(from: "charge", to: "ship")
+)
+run_id = client.submit_workflow("checkout", graph, params_json: '{"order":"ord-0001"}')
+
+view = client.get_workflow_run(run_id)
+view.run.state            # => :pending, :running, :completed, :failed, … (FlexiQ::WorkflowState)
+view.run.terminal?
+view.node("ship").status  # => :pending, :running, :completed, … (FlexiQ::WorkflowNodeStatus)
+view.node("ship").job_id  # read it with get_job
+```
+
+A node takes the arguments `enqueue` does and sends the same `raw` bytes, plus `queue`,
+`max_retries`, `timeout` (seconds), `priority`, `condition` (`:on_success`, `:on_failure`,
+`:always`) and `compensate`. A Hash of a node's fields works wherever a node does. The graph is
+checked before the call: at least one node, unique names, and no edge to an undeclared node.
+
+**This door advances static graphs only.** A node setting `gate`, `cache`, `fan_out`, `fan_in`
+or `sub_workflow` is refused before anything is written; only a live SDK process can drive those.
+The refusal names one node, so a graph with several clears them one call at a time:
+
+```ruby
+begin
+  client.submit_workflow("review", graph)
+rescue FlexiQ::RPCError => e
+  raise unless e.reason == FlexiQ::Reason::WORKFLOW_CONSTRUCT_UNSUPPORTED
+
+  e.workflow_construct # => { node: "review", field: "gate" }
+end
+```
+
+Every submission is version 1 of `name`. Resubmitting a name with a different graph is refused
+with `INVALID_ARGUMENT`; submit a changed graph under a new name.
+
+**`submit_workflow` is not idempotent**, and a workflow has no `unique_key`. A run cannot be found
+by name, so a call that raised `TransportError` or an ambiguous `RPCError` (`UNAVAILABLE`,
+`DEADLINE_EXCEEDED`, `CANCELLED`) may have submitted a run whose id is lost. A retry submits a
+second run. Never retry it blind.
+
+A narrowed `produce` grant is checked on every node, as `enqueue` would check it, with an empty
+queue counted as `default`. The first node outside the grant refuses the whole graph:
+`SCOPE_DENIED`, with `RPCError#node` naming that node. A node's `compensate` task must be reached
+on every queue. `get_workflow_run` answers `NOT_FOUND` unless the grant reaches every node's job.
+
+## Credentials and TLS
+
+Every call sends `Authorization: Bearer <token>`. The token is opaque; the client never parses it.
+
+`https://` is the default and verifies the server's certificate. Point at a private CA, or
+present a client certificate for mTLS, with `tls:`:
+
+```ruby
+FlexiQ::Client.new(url, token: token, tls: {
+  ca_file: "/etc/flexiq/ca.pem",
+  cert: OpenSSL::X509::Certificate.new(File.read("client.pem")),
+  key: OpenSSL::PKey.read(File.read("client.key"))
+})
+```
+
+`http://` is refused unless you pass `insecure: true`, which is for a loopback listener you
+trust. A bearer token on a plaintext network hop can be replayed by anything that sees it.
+
+Other keywords: `open_timeout`, `read_timeout`, `write_timeout`, `watch_read_timeout` (seconds)
+and `user_agent`.
+
+## Errors
+
+Every error is a `FlexiQ::Error`:
+
+| Class | Means |
+|---|---|
+| `FlexiQ::RPCError` | The server refused. Branch on `#reason` (`FlexiQ::Reason::QUEUE_FULL`, …), never on the message. |
+| `FlexiQ::TransportError` | No answer arrived: connect, TLS, timeout, or a body that was not FlexiQ's. |
+| `FlexiQ::ConfigurationError` | The client was built with settings it will not honour. |
+| `FlexiQ::CodecError` | A value could not be encoded into, or decoded from, a payload. |
+| `FlexiQ::WaitTimeoutError` | `wait` ran out of time. The job is untouched. |
+
+```ruby
+begin
+  client.enqueue("orders.charge", args: [order], queue: "payments", unique_key: order["id"])
+rescue FlexiQ::RPCError => e
+  case e.reason
+  when FlexiQ::Reason::QUEUE_FULL then sleep(e.retry_after || 1) # e.queue_full => {queue:, pending:, cap:}
+  when FlexiQ::Reason::SCOPE_DENIED then raise "token lacks #{e.scope}"
+  else raise
+  end
+end
+```
+
+`RPCError#retryable?` says whether the condition clears on its own. It never says a write is
+safe to resend.
+
+## Retries
+
+The client never retries a call; only watches reopen themselves, since a watch writes nothing.
+A write that raised `TransportError`, or `RPCError` with code
+`UNAVAILABLE`, `DEADLINE_EXCEEDED` or `CANCELLED`, may have landed before the connection dropped,
+and nothing on the wire says which. Resend a write only with `unique_key` set, reusing the same
+value. `unique_key` dedupes against the *active* job only — once that job finishes the key is
+free — so keep the total retry window shorter than the job's own life.
+
+## Payloads
+
+Arguments travel as the `raw` CBOR envelope this gem writes itself — tag byte `0x02`, then
+`[args, kwargs]` — held to the contract's three rules: definite-length containers,
+shortest-form integers and 64-bit floats. The bytes are therefore the same ones any other FlexiQ
+runtime writes for the same call, which is what keeps cross-runtime `auto:` idempotency keys
+equal. Hash keys keep their insertion order.
+
+| Ruby | CBOR |
+|---|---|
+| `nil`, `true`, `false` | simple values |
+| `Integer` (64-bit range) | integer |
+| `Float` | 64-bit float |
+| `String` | text — or a byte string when its encoding is `Encoding::BINARY` |
+| `Symbol` | text |
+| `Array`, `Hash` | array, map |
+
+Prefer one Hash argument (`args: [{...}]`): it binds cleanly in every runtime's handlers.
+
+Reading back: `job.decode_payload` returns `[args, kwargs]`, `job.decode_result` the task's
+return value, and `job.task_error` a `FlexiQ::TaskError` — structured when the failure carried the
+canonical JSON, otherwise the raw text verbatim.
+
+## Development
+
+```bash
+bin/setup            # bundle install
+bundle exec rake     # rubocop + unit suite (includes the wire-vector conformance test)
+bundle exec rake e2e # against a real server; build one first:
+                     #   cargo build -p flexiq-server --features grpc
+```
+
+The e2e suite runs `FLEXIQ_SERVER_BIN`, or else `target/{debug,release}/flexiq-server`.
+
+## Contract
+
+[`contracts/REMOTE_SDK_CONTRACT.md`](../../contracts/REMOTE_SDK_CONTRACT.md) is the rule this
+client implements, and [`contracts/wire-vectors.json`](../../contracts/wire-vectors.json) is the
+conformance bar its suite asserts.

data/lib/flexiq/backoff.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  # Retry delay: 0.25 s doubling to 5 s; `reset` after a success.
+  class Backoff
+    START = 0.25
+    CAP = 5.0
+
+    def initialize = reset
+
+    def reset
+      @delay = START
+    end
+
+    # Sleeps the current delay, cut short by `deadline` (Deadline) when given.
+    def pause(deadline = nil)
+      sleep(deadline ? deadline.cap(@delay) : @delay)
+      @delay = [@delay * 2, CAP].min
+    end
+  end
+end

data/lib/flexiq/batch_item_result.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  # One item of an EnqueueBatch: either `enqueued` (an EnqueueResult, durable) or `error`
+  # (an unraised RPCError — that item alone did not land). A batch is never atomic.
+  #
+  # Both nil means a newer server answered with an outcome this build does not know.
+  BatchItemResult = Data.define(:index, :enqueued, :error) do
+    def self.from_json(json, index)
+      new(
+        index: index,
+        enqueued: json["enqueued"] && EnqueueResult.from_json(json["enqueued"]),
+        error: json["error"] && RPCError.from_status(json["error"])
+      )
+    end
+
+    def enqueued? = !enqueued.nil?
+
+    def failed? = !error.nil?
+  end
+end

data/lib/flexiq/cbor/decoder.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  module CBOR
+    # A CBOR tag this client has no meaning for, kept so the value is not lost.
+    Tagged = Data.define(:tag, :value)
+
+    # RFC 8949 reader. Accepts every form the encoder is forbidden to write —
+    # indefinite lengths, non-shortest integers, half and single floats — because a
+    # payload written before those rules, or by another writer, still has to run.
+    class Decoder
+      # Nesting cap, so hostile input cannot exhaust the stack.
+      MAX_DEPTH = 512
+      BREAK = Object.new.freeze
+      private_constant :BREAK
+
+      # Decodes exactly one CBOR item; trailing bytes are an error.
+      def self.decode(bytes)
+        decoder = new(bytes)
+        value = decoder.read_value(0)
+        decoder.finish
+        value
+      end
+
+      def initialize(bytes)
+        @bytes = bytes.b
+        @pos = 0
+      end
+
+      def finish
+        return if @pos == @bytes.bytesize
+
+        raise CodecError, "#{@bytes.bytesize - @pos} trailing byte(s) after the CBOR item"
+      end
+
+      # One complete item; a break code is only legal where an indefinite container reads it.
+      def read_value(depth)
+        value = read_item(depth)
+        raise CodecError, "unexpected CBOR break code" if value.equal?(BREAK)
+
+        value
+      end
+
+      private
+
+      def read_item(depth)
+        raise CodecError, "CBOR nesting deeper than #{MAX_DEPTH}" if depth > MAX_DEPTH
+
+        initial = take_byte
+        major = initial >> 5
+        info = initial & 0x1F
+        case major
+        when 0 then read_argument(info)
+        when 1 then -1 - read_argument(info)
+        when 2 then read_string(info, Encoding::BINARY, depth)
+        when 3 then read_string(info, Encoding::UTF_8, depth)
+        when 4 then read_array(info, depth)
+        when 5 then read_map(info, depth)
+        when 6 then Tagged.new(tag: read_argument(info), value: read_value(depth + 1))
+        else read_simple(info)
+        end
+      end
+
+      def take_byte
+        raise CodecError, "CBOR input ended early" if @pos >= @bytes.bytesize
+
+        byte = @bytes.getbyte(@pos)
+        @pos += 1
+        byte
+      end
+
+      def take(count)
+        raise CodecError, "CBOR input ended early" if @pos + count > @bytes.bytesize
+
+        slice = @bytes.byteslice(@pos, count)
+        @pos += count
+        slice
+      end
+
+      def read_argument(info)
+        case info
+        when 0..23 then info
+        when 24 then take(1).unpack1("C")
+        when 25 then take(2).unpack1("n")
+        when 26 then take(4).unpack1("N")
+        when 27 then take(8).unpack1("Q>")
+        else raise CodecError, "invalid CBOR argument encoding #{info}"
+        end
+      end
+
+      def indefinite?(info) = info == 31
+
+      def read_string(info, encoding, depth)
+        raw = indefinite?(info) ? read_chunks(encoding, depth) : take(read_argument(info))
+        text = raw.dup.force_encoding(encoding)
+        raise CodecError, "CBOR text string is not valid UTF-8" unless text.valid_encoding?
+
+        text
+      end
+
+      # An indefinite string is a run of definite chunks of the same major type.
+      def read_chunks(encoding, depth)
+        out = +"".b
+        loop do
+          chunk = read_item(depth + 1)
+          break if chunk.equal?(BREAK)
+          raise CodecError, "indefinite CBOR string holds a chunk of another type" unless chunk.is_a?(String)
+          raise CodecError, "indefinite CBOR string mixes text and bytes" unless chunk.encoding == encoding
+
+          out << chunk.b
+        end
+        out
+      end
+
+      def read_array(info, depth)
+        return Array.new(read_argument(info)) { read_value(depth + 1) } unless indefinite?(info)
+
+        items = []
+        loop do
+          item = read_item(depth + 1)
+          break if item.equal?(BREAK)
+
+          items << item
+        end
+        items
+      end
+
+      def read_map(info, depth)
+        map = {}
+        if indefinite?(info)
+          loop do
+            key = read_item(depth + 1)
+            break if key.equal?(BREAK)
+
+            map[key] = read_value(depth + 1)
+          end
+        else
+          read_argument(info).times { map[read_value(depth + 1)] = read_value(depth + 1) }
+        end
+        map
+      end
+
+      def read_simple(info)
+        case info
+        when 20 then false
+        when 21 then true
+        when 22, 23 then nil
+        when 25 then half_float(take(2).unpack1("n"))
+        when 26 then take(4).unpack1("g")
+        when 27 then take(8).unpack1("G")
+        when 31 then BREAK
+        else raise CodecError, "unsupported CBOR simple value #{info}"
+        end
+      end
+
+      # IEEE 754 binary16 has no pack directive; RFC 8949 appendix D spells the decode.
+      def half_float(bits)
+        exponent = (bits >> 10) & 0x1F
+        mantissa = bits & 0x3FF
+        magnitude =
+          if exponent.zero? then Math.ldexp(mantissa, -24)
+          elsif exponent == 31 then mantissa.zero? ? Float::INFINITY : Float::NAN
+          else Math.ldexp(mantissa + 1024, exponent - 25)
+          end
+        bits.anybits?(0x8000) ? -magnitude : magnitude
+      end
+    end
+  end
+end

data/lib/flexiq/cbor/encoder.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module FlexiQ
+  module CBOR
+    # RFC 8949 writer held to the three rules the wire contract pins:
+    # definite-length containers, shortest-form integers, 64-bit finite floats.
+    #
+    # Each rule moves bytes without moving meaning, and the `auto:` idempotency key
+    # hashes those bytes — so a drift here silently stops cross-runtime dedupe.
+    module Encoder
+      UINT64_MAX = (2**64) - 1
+      NEGATIVE_MIN = -(2**64)
+
+      # Preferred serialization for the non-finite floats; the contract leaves their width free.
+      POSITIVE_INFINITY = "\xF9\x7C\x00".b.freeze
+      NEGATIVE_INFINITY = "\xF9\xFC\x00".b.freeze
+      NAN = "\xF9\x7E\x00".b.freeze
+
+      module_function
+
+      # Encodes one Ruby value into a binary String.
+      #
+      # A String tagged `Encoding::BINARY` is a CBOR byte string; any other String is text.
+      # Symbols are text. Hash keys keep insertion order: the vectors pin unsorted keys.
+      def encode(value)
+        write(+"".b, value)
+      end
+
+      def write(out, value)
+        case value
+        when nil then out << "\xF6".b
+        when true then out << "\xF5".b
+        when false then out << "\xF4".b
+        when Integer then write_integer(out, value)
+        when Float then write_float(out, value)
+        when Symbol then write_text(out, value.name)
+        when String then write_string(out, value)
+        when Array then write_array(out, value)
+        when Hash then write_map(out, value)
+        else raise CodecError, "cannot encode #{value.class} as CBOR"
+        end
+      end
+
+      def write_integer(out, value)
+        unless value.between?(NEGATIVE_MIN, UINT64_MAX)
+          raise CodecError, "integer #{value} is outside CBOR's 64-bit range"
+        end
+
+        value.negative? ? write_head(out, 1, -1 - value) : write_head(out, 0, value)
+      end
+
+      def write_float(out, value)
+        return out << NAN if value.nan?
+        return out << (value.positive? ? POSITIVE_INFINITY : NEGATIVE_INFINITY) if value.infinite?
+
+        out << "\xFB".b << [value].pack("G")
+      end
+
+      def write_string(out, value)
+        return write_bytes(out, value) if value.encoding == Encoding::BINARY
+
+        write_text(out, value)
+      end
+
+      def write_bytes(out, value)
+        write_head(out, 2, value.bytesize)
+        out << value
+      end
+
+      def write_text(out, value)
+        text = value.encoding == Encoding::UTF_8 ? value : value.encode(Encoding::UTF_8)
+        raise CodecError, "text is not valid UTF-8: #{text.inspect}" unless text.valid_encoding?
+
+        write_head(out, 3, text.bytesize)
+        out << text.b
+      rescue EncodingError => e
+        raise CodecError, "text cannot be converted to UTF-8: #{e.message}"
+      end
+
+      def write_array(out, value)
+        write_head(out, 4, value.length)
+        value.each { |item| write(out, item) }
+        out
+      end
+
+      def write_map(out, value)
+        write_head(out, 5, value.length)
+        value.each do |key, item|
+          write(out, key)
+          write(out, item)
+        end
+        out
+      end
+
+      # Major type in the top three bits, then the argument in its shortest form.
+      def write_head(out, major, argument)
+        prefix = major << 5
+        if argument < 24
+          out << (prefix | argument).chr
+        elsif argument <= 0xFF
+          out << (prefix | 24).chr << [argument].pack("C")
+        elsif argument <= 0xFFFF
+          out << (prefix | 25).chr << [argument].pack("n")
+        elsif argument <= 0xFFFF_FFFF
+          out << (prefix | 26).chr << [argument].pack("N")
+        else
+          out << (prefix | 27).chr << [argument].pack("Q>")
+        end
+      end
+    end
+  end
+end