zeridion-flare 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4ac177cb1ba3e09ec4d70f0d88e50027da6e1b8dd4e0547a13dbbd3020d56889
+  data.tar.gz: 7763c74ddba147b9fb9d03d48b94aba0d201476d487d83b943262bfda877aa0e
+SHA512:
+  metadata.gz: fc72570ecde04bc6f2d2715c0e277cde593d1177362383911233185da59549ad01eeee660ad487e7bff5f41999a19c7bbfb57dd0ad602a7f4ce98c0737fa50a2
+  data.tar.gz: 576a86cba0236c0536c20a653056fcb4b5e27e9c2c13216a4be1f7b471b7b640ed56d7527783213803bc17481877a5f3a2cffa8ce23846ab43ed4253d23b98dc

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zeridion
+
+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,175 @@
+# zeridion-flare (Ruby)
+
+Ruby SDK for the [Zeridion Flare](https://docs.zeridion.com/flare) managed background-jobs API.
+
+[![Gem Version](https://badge.fury.io/rb/zeridion-flare.svg)](https://rubygems.org/gems/zeridion-flare)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**[Full documentation at docs.zeridion.com/flare](https://docs.zeridion.com/flare)**
+
+## Installation
+
+```bash
+gem install zeridion-flare
+```
+
+Or add to your `Gemfile`:
+
+```ruby
+gem "zeridion-flare", "~> 0.2"
+```
+
+Requires Ruby 3.2+. **Zero** runtime dependencies — uses stdlib `Net::HTTP`, `OpenSSL`, and `JSON` only. The opt-in worker runtime (`require "zeridion_flare/worker"`) ships in the same gem and adds no dependencies.
+
+## Quick start
+
+```ruby
+require "zeridion_flare"
+
+client = Zeridion::Flare::Client.new(api_key: "zf_live_sk_...")
+# Or, with FLARE_API_KEY set in the environment:
+#   client = Zeridion::Flare::Client.new
+
+job = client.create_job(
+  "job_type" => "SendWelcomeEmail",
+  "payload"  => { "email" => "alice@example.com" },
+  "queue"    => "default",
+)
+
+puts job["id"], job["state"]  # "job_abc123", "pending"
+```
+
+## `Client.new(...)`
+
+| Keyword                | Default                      | Notes                                                  |
+|------------------------|------------------------------|--------------------------------------------------------|
+| `api_key:`             | `ENV["FLARE_API_KEY"]`       | Required — pass directly or via env var                |
+| `base_url:`            | `https://api.zeridion.com`   | Override for dev / staging environments                |
+| `max_retries:`         | `3`                          | Set `0` to disable retries                             |
+| `retry_base_delay_ms:` | `500`                        | Base for exponential schedule                          |
+| `retry_max_delay_ms:`  | `30_000`                     | Cap on a single backoff wait (and on `Retry-After`)    |
+| `timeout_seconds:`     | `30`                         | Per-request read timeout                               |
+| `transport:`           | `NetHttpTransport.new`       | Swap for tests or to plug in a logging proxy           |
+
+Every public method accepts optional `idempotency_key:` and `request_id:` keyword arguments, sent as the `Idempotency-Key` and `X-Request-Id` headers.
+
+```ruby
+client.create_job(body, idempotency_key: "optional", request_id: "optional")
+client.get_job(id)                                # nil if 404
+client.list_jobs(state: "failed", limit: 25)
+client.cancel_job(id)                             # nil if 409
+client.retry_job(id)                              # nil if 409
+client.register_worker(body)                      # raises on non-2xx
+client.poll_workers(body)
+client.heartbeat(body)                            # {"status" => "ok" | "cancel"}
+client.ack_worker(body)
+```
+
+## Automatic retries
+
+The SDK auto-retries HTTP `429` / `502` / `503` / `504` responses and transient network errors with full-jitter exponential backoff capped at `retry_max_delay_ms`. The `Retry-After` header is honored when present.
+
+See the [stable error-code registry](https://docs.zeridion.com/flare/api/errors) for every `error.code` string the API can return.
+
+## Error handling
+
+All API errors inherit from `Zeridion::Flare::FlareError`:
+
+```ruby
+begin
+  client.create_job("job_type" => "MyJob")
+rescue Zeridion::Flare::RateLimitError => e
+  sleep(e.retry_after.to_i)        # honor X-RateLimit-Reset
+rescue Zeridion::Flare::AuthError
+  # 401 — invalid API key
+rescue Zeridion::Flare::ConflictError => e
+  case e.code
+  when "idempotency_key_reuse"
+    # Same Idempotency-Key reused with a different body
+  end
+rescue Zeridion::Flare::FlareError => e
+  warn "Error #{e.status_code}: #{e.code} — #{e.message} (req #{e.request_id})"
+end
+```
+
+Each error exposes `#status_code`, `#code`, `#request_id`, and `#message`. `RateLimitError` additionally exposes `#limit`, `#remaining`, `#retry_after`.
+
+## Verifying webhook signatures
+
+If you've configured outbound webhooks via the `/flare/v1/webhooks` API, verify the `X-Zeridion-Signature` header on each incoming delivery:
+
+```ruby
+require "zeridion_flare"
+
+post "/hooks/zeridion" do
+  payload = request.body.read
+  header  = request.env["HTTP_X_ZERIDION_SIGNATURE"].to_s
+
+  unless Zeridion::Flare::Webhook.verify(payload, header, ENV["ZERIDION_WEBHOOK_SECRET"], tolerance_seconds: 300)
+    halt 400, "invalid signature"
+  end
+  # ... process the event ...
+  200
+end
+```
+
+`Webhook.verify` is HMAC-SHA256 over `<unix_timestamp>.<raw_body>`, constant-time-compared (via `OpenSSL.secure_compare`) against every `v1=` value in the header (supports secret rotation). The optional `tolerance_seconds:` parameter rejects replays older than that many seconds.
+
+## Worker runtime
+
+Beyond the thin client, the gem ships an opt-in **background-worker runtime**.
+Define job classes and let it register, long-poll, dispatch, heartbeat with
+progress, honor server cancellation, and drain gracefully on shutdown — instead
+of hand-writing the poll/ack loop.
+
+```ruby
+require "zeridion_flare/worker"
+
+class SendWelcomeEmail
+  include Zeridion::Flare::Job
+  flare_options queue: "email", max_attempts: 5, timeout: 120
+
+  def perform(payload, ctx)
+    return if ctx.cancelled?
+    return if AlreadySent.exists?(ctx.job_id)   # at-least-once → idempotent
+    Mailer.welcome(payload["email"]).deliver_now
+    ctx.report_progress(1.0)
+  end
+end
+
+# Recurring (cron) jobs are payloadless and run on a schedule:
+class NightlyCleanup
+  include Zeridion::Flare::RecurringJob
+  flare_options cron: "0 3 * * *", queue: "maintenance", timezone: "UTC"
+
+  def perform(ctx)
+    PurgeExpired.run
+  end
+end
+
+worker = Zeridion::Flare::Worker::Worker.new(concurrency: 5)
+worker.run   # blocks; SIGTERM/SIGINT → graceful drain
+```
+
+Including the `Job` / `RecurringJob` mixin registers the class automatically.
+The worker reads the same `FLARE_API_KEY` fallback and base-URL default as the
+thin client. Handlers run **at least once** — dedupe on `ctx.job_id` to stay
+idempotent.
+
+Full reference: [docs.zeridion.com/flare/sdks/ruby/worker](https://docs.zeridion.com/flare/sdks/ruby/worker).
+
+## Sample app
+
+A runnable worker starter (one payload job + one recurring job + graceful drain,
+plus an `enqueue.rb` feeder) lives at
+[`samples/ruby-starter/`](../../samples/ruby-starter/).
+
+## Links
+
+- Documentation: https://docs.zeridion.com/flare
+- Dashboard: https://dashboard.zeridion.com/
+- .NET SDK: ../csharp/README.md
+- TypeScript SDK: ../typescript/README.md
+- Python SDK: ../python/README.md
+- Go SDK: ../go/README.md
+- PHP SDK: ../php/README.md

data/lib/zeridion_flare/client.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "securerandom"
+require "uri"
+
+require_relative "errors"
+require_relative "version"
+
+module Zeridion
+  module Flare
+    # Default HTTP transport backed by Ruby's stdlib Net::HTTP. Tests can swap
+    # in a custom object that responds to #send_request with the same
+    # signature to capture requests / queue responses without touching the
+    # network.
+    class NetHttpTransport
+      # @return [Hash{Symbol=>Object}] { status:, headers:, body: }
+      def send_request(method:, url:, headers:, body:, timeout:)
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = 10
+        http.read_timeout = timeout
+
+        req = build_request(method, uri, headers, body)
+        resp = http.request(req)
+
+        parsed_headers = {}
+        resp.each_header { |k, v| parsed_headers[k.downcase] = v }
+        { status: resp.code.to_i, headers: parsed_headers, body: resp.body.to_s }
+      end
+
+      private
+
+      def build_request(method, uri, headers, body)
+        path = uri.request_uri
+        req_class = {
+          "GET" => Net::HTTP::Get,
+          "POST" => Net::HTTP::Post,
+          "PUT" => Net::HTTP::Put,
+          "PATCH" => Net::HTTP::Patch,
+          "DELETE" => Net::HTTP::Delete,
+        }.fetch(method.upcase) do
+          raise ArgumentError, "unsupported HTTP method: #{method}"
+        end
+        req = req_class.new(path)
+        headers.each { |k, v| req[k] = v }
+        req.body = body if body
+        req
+      end
+    end
+
+    # Synchronous Flare API client.
+    class Client
+      DEFAULT_BASE_URL = "https://api.zeridion.com"
+      API_PREFIX = "/flare/v1"
+      RETRYABLE_STATUSES = [429, 502, 503, 504].freeze
+
+      attr_reader :api_key, :base_url
+
+      # @param api_key [String, nil] API key. Falls back to FLARE_API_KEY env var.
+      # @param base_url [String] Base URL — default https://api.zeridion.com
+      # @param max_retries [Integer] Set 0 to disable retries.
+      # @param retry_base_delay_ms [Integer] Base for exponential schedule.
+      # @param retry_max_delay_ms [Integer] Cap on a single backoff wait.
+      # @param timeout_seconds [Numeric] Per-request read timeout.
+      # @param transport [Object] Object responding to #send_request; default NetHttpTransport.
+      # @param max_response_bytes [Integer] Hard cap on response body bytes
+      #   the client will read. Protects against a misbehaving or malicious
+      #   server sending an unbounded body that would otherwise blow Ruby
+      #   memory. Defaults to 10 MiB; set 0 to disable.
+      def initialize(
+        api_key: nil,
+        base_url: DEFAULT_BASE_URL,
+        max_retries: 3,
+        retry_base_delay_ms: 500,
+        retry_max_delay_ms: 30_000,
+        timeout_seconds: 30,
+        max_response_bytes: 10 * 1024 * 1024,
+        transport: nil
+      )
+        api_key ||= ENV["FLARE_API_KEY"]
+        if api_key.nil? || api_key.to_s.empty?
+          raise ArgumentError,
+                "Client: api_key is required (pass directly or set the FLARE_API_KEY environment variable)"
+        end
+        @api_key = api_key
+        @base_url = base_url.chomp("/")
+        @max_retries = max_retries
+        @retry_base_delay_ms = retry_base_delay_ms
+        @retry_max_delay_ms = retry_max_delay_ms
+        @timeout_seconds = timeout_seconds
+        @max_response_bytes = max_response_bytes
+        @transport = transport || NetHttpTransport.new
+      end
+
+      # ── Jobs ────────────────────────────────────────────────────────────
+
+      def create_job(body, idempotency_key: nil, request_id: nil)
+        resp = request("POST", "/jobs", body: body, idempotency_key: idempotency_key, request_id: request_id)
+        decode(maybe_raise(resp))
+      end
+
+      def get_job(job_id, idempotency_key: nil, request_id: nil)
+        resp = request("GET", "/jobs/#{escape_path(job_id)}", idempotency_key: idempotency_key, request_id: request_id)
+        return nil if resp[:status] == 404
+
+        decode(maybe_raise(resp))
+      end
+
+      def list_jobs(
+        state: nil, queue: nil, job_type: nil, created_after: nil,
+        created_before: nil, limit: nil, cursor: nil,
+        idempotency_key: nil, request_id: nil
+      )
+        params = {
+          "state" => state, "queue" => queue, "job_type" => job_type,
+          "created_after" => created_after, "created_before" => created_before,
+          "limit" => limit, "cursor" => cursor,
+        }.reject { |_, v| v.nil? }
+        path = "/jobs"
+        path += "?#{URI.encode_www_form(params)}" unless params.empty?
+        resp = request("GET", path, idempotency_key: idempotency_key, request_id: request_id)
+        decode(maybe_raise(resp))
+      end
+
+      def cancel_job(job_id, idempotency_key: nil, request_id: nil)
+        resp = request("POST", "/jobs/#{escape_path(job_id)}/cancel",
+                       idempotency_key: idempotency_key, request_id: request_id)
+        return nil if resp[:status] == 409
+
+        decode(maybe_raise(resp))
+      end
+
+      def retry_job(job_id, idempotency_key: nil, request_id: nil)
+        resp = request("POST", "/jobs/#{escape_path(job_id)}/retry",
+                       idempotency_key: idempotency_key, request_id: request_id)
+        return nil if resp[:status] == 409
+
+        decode(maybe_raise(resp))
+      end
+
+      # ── Workers ─────────────────────────────────────────────────────────
+
+      # Announce this worker's identity, served queues + job types, and any
+      # recurring schedules. Best-effort on the server; STRICT here (raises on
+      # non-2xx) — the worker runtime is responsible for swallowing failures.
+      def register_worker(body, idempotency_key: nil, request_id: nil)
+        resp = request("POST", "/workers/register", body: body, idempotency_key: idempotency_key,
+                                                     request_id: request_id)
+        decode(maybe_raise(resp))
+      end
+
+      def poll_workers(body, idempotency_key: nil, request_id: nil)
+        resp = request("POST", "/workers/poll", body: body, idempotency_key: idempotency_key, request_id: request_id)
+        decode(maybe_raise(resp))
+      end
+
+      # Send a single liveness/progress beat for one in-flight job. STRICT here
+      # (raises on non-2xx); the worker runtime swallows. Returns the decoded
+      # response Hash, e.g. {"status" => "ok"} or {"status" => "cancel"}.
+      def heartbeat(body, idempotency_key: nil, request_id: nil)
+        resp = request("POST", "/workers/heartbeat", body: body, idempotency_key: idempotency_key,
+                                                      request_id: request_id)
+        decode(maybe_raise(resp))
+      end
+
+      def ack_worker(body, idempotency_key: nil, request_id: nil)
+        resp = request("POST", "/workers/ack", body: body, idempotency_key: idempotency_key, request_id: request_id)
+        decode(maybe_raise(resp))
+      end
+
+      # ── Internal ────────────────────────────────────────────────────────
+
+      private
+
+      def escape_path(segment)
+        URI.encode_www_form_component(segment)
+      end
+
+      def request(method, path, body: nil, idempotency_key: nil, request_id: nil)
+        url = "#{@base_url}#{API_PREFIX}#{path}"
+        headers = {
+          "Authorization" => "Bearer #{@api_key}",
+          "Accept" => "application/json",
+          "User-Agent" => "zeridion-flare-ruby/#{Zeridion::Flare::VERSION}",
+        }
+        body_str = nil
+        if body
+          body_str = JSON.generate(body)
+          headers["Content-Type"] = "application/json"
+        end
+        headers["Idempotency-Key"] = idempotency_key if idempotency_key
+        headers["X-Request-Id"] = request_id if request_id
+
+        last_exception = nil
+        attempt = 0
+        loop do
+          begin
+            resp = @transport.send_request(method: method, url: url, headers: headers, body: body_str,
+                                           timeout: @timeout_seconds)
+          rescue StandardError => e
+            raise e if attempt == @max_retries
+
+            last_exception = e
+            sleep(compute_backoff_seconds(attempt, nil))
+            attempt += 1
+            next
+          end
+
+          return resp unless RETRYABLE_STATUSES.include?(resp[:status]) && attempt < @max_retries
+
+          sleep(compute_backoff_seconds(attempt, resp[:headers]["retry-after"]))
+          attempt += 1
+        end
+      rescue StandardError
+        raise last_exception if last_exception
+
+        raise
+      end
+
+      def compute_backoff_seconds(attempt, retry_after_raw)
+        if retry_after_raw&.match?(/\A\d+\z/)
+          seconds = retry_after_raw.to_i
+          return [seconds, @retry_max_delay_ms / 1000.0].min if seconds >= 0
+        end
+        ceiling_ms = [@retry_base_delay_ms * (2**attempt), @retry_max_delay_ms].min
+        rand(0..ceiling_ms) / 1000.0
+      end
+
+      def maybe_raise(resp)
+        status = resp[:status]
+        return resp if status >= 200 && status < 300
+
+        code = "unknown"
+        message = "HTTP #{status}"
+        request_id = ""
+        if !resp[:body].empty?
+          begin
+            envelope = JSON.parse(resp[:body])
+            err = envelope.is_a?(Hash) ? envelope["error"] : nil
+            if err.is_a?(Hash)
+              code = err["code"] || code
+              message = err["message"] || message
+              request_id = err["request_id"] || request_id
+            end
+          rescue JSON::ParserError
+            # Non-JSON error body (e.g. plain-text 502 from a reverse proxy)
+          end
+        end
+
+        case status
+        when 401
+          raise AuthError.new(message, status_code: status, code: code, request_id: request_id)
+        when 402
+          raise QuotaError.new(message, status_code: status, code: code, request_id: request_id)
+        when 404
+          raise NotFoundError.new(message, status_code: status, code: code, request_id: request_id)
+        when 409
+          raise ConflictError.new(message, status_code: status, code: code, request_id: request_id)
+        when 429
+          limit = (resp[:headers]["x-ratelimit-limit"] || "0").to_i
+          remaining = (resp[:headers]["x-ratelimit-remaining"] || "0").to_i
+          reset_raw = resp[:headers]["x-ratelimit-reset"]
+          retry_after = reset_raw&.match?(/\A\d+\z/) ? reset_raw.to_i : nil
+          raise RateLimitError.new(message, status_code: status, code: code, request_id: request_id,
+                                            limit: limit, remaining: remaining, retry_after: retry_after)
+        else
+          raise FlareError.new(message, status_code: status, code: code, request_id: request_id)
+        end
+      end
+
+      def decode(resp)
+        return {} if resp[:body].empty?
+
+        # Cap the response body the parser sees so a misbehaving or malicious
+        # server can't blow Ruby memory with a multi-GiB payload. When
+        # @max_response_bytes is 0 the cap is disabled.
+        if @max_response_bytes.positive? && resp[:body].bytesize > @max_response_bytes
+          # FlareError#initialize requires status_code:/code:/request_id: keywords,
+          # so the bare `raise FlareError, msg` form would actually raise
+          # ArgumentError: missing keywords. Construct it explicitly with
+          # placeholders — the body-cap path has no upstream API call to
+          # attribute, so status_code is 0 and request_id is nil.
+          raise FlareError.new(
+            "flare: response body #{resp[:body].bytesize} bytes " \
+            "exceeds max_response_bytes=#{@max_response_bytes}",
+            status_code: 0,
+            code: "body_too_large",
+            request_id: nil,
+          )
+        end
+        JSON.parse(resp[:body])
+      end
+    end
+  end
+end

data/lib/zeridion_flare/errors.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Zeridion
+  module Flare
+    # Base exception for all Flare API errors. Every other exception in this
+    # SDK inherits from FlareError, so a single `rescue FlareError` covers them.
+    class FlareError < StandardError
+      attr_reader :status_code, :code, :request_id
+
+      def initialize(message, status_code:, code:, request_id:)
+        super(message)
+        @status_code = status_code
+        @code = code
+        @request_id = request_id
+      end
+    end
+
+    class AuthError < FlareError; end
+    class QuotaError < FlareError; end
+    class NotFoundError < FlareError; end
+    class ConflictError < FlareError; end
+
+    class RateLimitError < FlareError
+      attr_reader :limit, :remaining, :retry_after
+
+      def initialize(message, status_code:, code:, request_id:, limit:, remaining:, retry_after:)
+        super(message, status_code: status_code, code: code, request_id: request_id)
+        @limit = limit
+        @remaining = remaining
+        @retry_after = retry_after
+      end
+    end
+  end
+end

data/lib/zeridion_flare/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Zeridion
+  module Flare
+    VERSION = "0.2.0"
+  end
+end

data/lib/zeridion_flare/webhook.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Zeridion
+  module Flare
+    # Verify outbound webhook signatures from Zeridion Flare.
+    #
+    # Each delivery is signed with HMAC-SHA256 over `<unix_timestamp>.<raw_body>`
+    # using the subscription secret. The signature is sent in the
+    # X-Zeridion-Signature header in the form `t=<unix_timestamp>,v1=<hex>`.
+    module Webhook
+      # @param payload [String]          Raw request body. MUST be the exact bytes the
+      #                                  server signed — do not re-encode parsed JSON.
+      # @param signature_header [String] Full value of the X-Zeridion-Signature header.
+      # @param secret [String]           The subscription secret returned at creation.
+      # @param tolerance_seconds [Integer, nil] If set, reject signatures whose timestamp
+      #                                          differs from the current time by more
+      #                                          than this many seconds (replay protection;
+      #                                          recommended: 300).
+      # @return [Boolean] true iff the signature is valid (and within tolerance, if set).
+      def self.verify(payload, signature_header, secret, tolerance_seconds: nil)
+        return false if signature_header.nil? || signature_header.empty?
+        return false if secret.nil? || secret.empty?
+
+        timestamp = nil
+        signatures = []
+        signature_header.split(",").each do |part|
+          trimmed = part.strip
+          eq = trimmed.index("=")
+          next if eq.nil? || eq.zero?
+
+          key = trimmed[0, eq]
+          value = trimmed[(eq + 1)..]
+          case key
+          when "t"
+            timestamp = Integer(value, 10) if value.match?(/\A\d+\z/)
+          when "v1"
+            signatures << value.downcase
+          end
+        end
+
+        return false if timestamp.nil? || signatures.empty?
+
+        if tolerance_seconds
+          now = Time.now.to_i
+          return false if (now - timestamp).abs > tolerance_seconds
+        end
+
+        signing_input = "#{timestamp}.#{payload}"
+        expected = OpenSSL::HMAC.hexdigest("SHA256", secret, signing_input)
+
+        signatures.any? { |provided| secure_compare(expected, provided) }
+      end
+
+      # Constant-time string comparison (defends against timing-attack
+      # signature-guessing). OpenSSL.secure_compare is available in Ruby 3.0+;
+      # we fall back to a hand-rolled loop for older runtimes if it's missing.
+      def self.secure_compare(a, b)
+        return false if a.bytesize != b.bytesize
+
+        if OpenSSL.respond_to?(:secure_compare)
+          OpenSSL.secure_compare(a, b)
+        else
+          l = a.unpack("C*")
+          r = 0
+          i = -1
+          b.each_byte { |v| r |= v ^ l[i += 1] }
+          r.zero?
+        end
+      end
+    end
+  end
+end