ordainer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f012928c3aedf7e8eafb2b5f2fd6fcec671f467e4a44d6214bc55c3adf49ee1
+  data.tar.gz: b748a4a31fa42620dc1fa045182147001f526fa789571ec9a1f2c112be85d416
+SHA512:
+  metadata.gz: 7c4e07d10dfb6911bddc8cba631b5ec33cc52499a9dfd8e83dfd75ce5424870a04fa8f1b69c87e73f66a4a719f44e8e14eb0fe4ee7b2c29cebdbda029ef044b0
+  data.tar.gz: 5fd5691ec62d7f837706fc46c6e4024cad416fa647dbac76357d74200446c1c077a58af50489752f8b6d8a4ced135bef3f88254ee3803082d50ba7ee9bc2fdf3

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+- First version: Ordainer::Client#decide, Decision, typed errors, retries, fail_mode, optional Rails guard.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ordainer
+
+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,82 @@
+# ordainer (Ruby)
+
+Ask Ordainer before your tool runs: one `decide` call checks the caller's plan and counts the use.
+Ruby 3.0+, standard library only (net/http, json), no runtime dependencies. Mirrors the Node SDK
+(`packages/ordainer-node`, 1.2.2).
+
+> 0.1.0, not on RubyGems yet. Install from the repo (see the Ruby quickstart in the docs).
+
+```ruby
+require "ordainer"
+
+client = Ordainer::Client.new(api_key: ENV["ORDAINER_API_KEY"]) # ord_test_... or ord_live_...
+decision = client.decide(tool: "research.run")
+
+if decision.allowed?
+  run_research
+else
+  r = Ordainer.deny_response(decision) # { status:, headers:, body: { error: { code, message, ... } } }
+end
+```
+
+## Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `api_key:` | `ENV["ORDAINER_API_KEY"]`, then `ENV["ORDAINER_KEY"]` | Agent key. Override per call: `decide(tool:, api_key:)`. |
+| `base_url:` | `ENV["ORDAINER_BASE_URL"]` or `https://api.ordainer.dev` | |
+| `timeout:` | `0.3` | Seconds per attempt. |
+| `fail_mode:` | `:open` | `:open` lets the call run when Ordainer can't answer; `:closed` blocks it. |
+| `retries:` | `1` | Extra attempts (0 to 5) after a timeout, network error or 503, with jittered backoff, same idempotency key. |
+| `retry_budget:` | `0.65` | Seconds for all attempts of one `decide`. |
+| `mode:` | `nil` | `nil` follows the plan's mode in the console; `:enforce` or `:shadow`. |
+| `billing_lapse:` | `:open` | What to do on 403 `subscription_inactive`. |
+| `deny_status:` | `429` | Status for quota denies: 429 or 402. |
+| `sticky_deny:` | `60` | Seconds to keep denying would-be fail-opens for an (agent key, tool) after a quota deny. 0 = off. |
+| `logger:` | warn to `$stderr` | A `Logger`, or `false`. |
+| `on_decision:` | `nil` | Called with every `Decision`. |
+
+## Rules (same as the Node SDK)
+
+- `decide` never raises for an Ordainer answer or an outage. A deny is a normal result. Bad options raise
+  `Ordainer::ConfigurationError`. `decide!` raises `DeniedError`, `RejectedError`, `RateLimitedError` or
+  `UnavailableError` (all `Ordainer::BlockedError`, with `#status`, `#headers`, `#body`, `#decision`).
+- Only a deny from Ordainer blocks in enforce mode. Shadow never blocks (`would_deny?`).
+- `fail_mode` covers only "Ordainer couldn't answer": timeout, network error, 5xx, or a 200 that isn't a decision.
+- A 4xx (bad or missing key, 400, 409, 429 rate limit, ...) is Ordainer answering "no": blocked in any
+  `fail_mode` (`rejected?`). 403 `subscription_inactive` follows `billing_lapse` instead. 429
+  `safety_limit_reached` lets the call run (`safety_limited`).
+- Only timeouts, network errors and 503 are retried, never other 5xx or 4xx.
+
+## Decision
+
+`allowed?`, `denied?`, `decision` (`"allow"`/`"deny"`/`nil`), `reason`, `remaining`, `limit`, `resets_at`,
+`request_id`, `mode`, `would_deny?`, `fail_open?`, `fail_closed?`, `unavailable?`, `rejected?`, `rate_limited?`,
+`retry_after_sec`, `billing_inactive`, `test_limit_reached`, `safety_limited`, `sticky_deny`, `replayed?`,
+`attempts`, `latency_ms`, `error` (`code`, `message`, `status`, `limit_scope`, `request_id`), `to_h`.
+
+## Rails
+
+```ruby
+# config/initializers/ordainer.rb
+Ordainer.configure do |c|
+  c.api_key = ENV["ORDAINER_API_KEY"]
+end
+
+class ResearchController < ApplicationController
+  include Ordainer::Rails::Guard
+  ordainer_check tool: "research.run", customer: ->(c) { c.current_account.ordainer_key }, only: :create
+end
+```
+
+`customer:` returns the agent key for the customer making the request (one agent key is one customer); leave it out
+to use the configured key. On a blocked call the controller answers the JSON from `Ordainer.deny_response`
+(403, 429, 500 or 503). `ordainer_decision` holds the `Decision`. Rails replaces `X-Request-Id` with its own id, so the guard also sends Ordainer's as `X-Ordainer-Request-Id` (and `request_id` in the body).
+
+## Tests
+
+```sh
+cd packages/ordainer-ruby && bundle install && bundle exec rspec
+```
+
+Set `ORDAINER_LIVE_TEST_KEY` (a test key) to also run one live call against `ORDAINER_BASE_URL`.

data/lib/ordainer/client.rb

@@ -0,0 +1,349 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "securerandom"
+require "digest"
+require "logger"
+
+module Ordainer
+  DEFAULT_BASE_URL = "https://api.ordainer.dev"
+  DEFAULT_TIMEOUT = 0.3        # seconds per attempt (Node: 300 ms)
+  DEFAULT_RETRIES = 1          # Node: 1
+  MAX_RETRIES = 5
+  DEFAULT_RETRY_BUDGET = 0.65  # seconds for all attempts of one decide (Node: 650 ms)
+  RETRY_DELAY = 0.05           # first pause; doubles each retry, with +/-50% jitter
+  MIN_ATTEMPT = 0.05           # a retry with less time left than this isn't started
+  DEFAULT_STICKY_DENY = 60     # seconds (Node: 60 s; 0 = off, max 300)
+  MAX_STICKY_DENY = 300
+  MAX_STICKY_ENTRIES = 10_000
+  MAX_IDEMPOTENCY_LEN = 255
+  MODES = %i[enforce shadow].freeze
+  FAIL_MODES = %i[open closed].freeze
+  DENY_STATUSES = [429, 402].freeze
+  BILLING_CODES = %w[subscription_inactive subscription_required].freeze
+  CONCURRENCY_CODE = "concurrency_limited"
+  SAFETY_LIMIT_CODE = "safety_limit_reached"
+  LIMIT_SCOPES = %w[per_key per_address per_key_concurrency org_safety].freeze
+  BAD_KEY_TEXT = /[\u0000-\u001f\u007f]/
+
+  # The idempotency key actually sent for raw: the key itself, or "tool:" + sha256hex(raw) (or bare sha256hex) when it
+  # is over 255 characters or holds control characters the server refuses. Same rule as the Node SDK.
+  def self.idempotency_key_for(tool, raw, prefix_tool: false)
+    raw = raw.to_s
+    candidate = prefix_tool ? "#{tool}:#{raw}" : raw
+    return candidate if candidate.length <= MAX_IDEMPOTENCY_LEN && candidate !~ BAD_KEY_TEXT
+
+    digest = Digest::SHA256.hexdigest(raw.b)
+    with_tool = "#{tool}:#{digest}"
+    with_tool.length <= MAX_IDEMPOTENCY_LEN && with_tool !~ BAD_KEY_TEXT ? with_tool : digest
+  end
+
+  # Thread-safe; share one per process.
+  class Client
+    attr_reader :base_url, :timeout, :fail_mode, :retries, :retry_budget, :mode, :billing_lapse, :deny_status
+
+    # api_key:      agent key (ord_test_/ord_live_). Default ENV["ORDAINER_API_KEY"] or ENV["ORDAINER_KEY"].
+    # base_url:     default ENV["ORDAINER_BASE_URL"] or https://api.ordainer.dev
+    # timeout:      seconds per attempt, default 0.3
+    # fail_mode:    :open (default) or :closed. ONLY for timeouts, network errors, 5xx and malformed answers.
+    #               Any 4xx and a missing key always block (decision.rejected?), except 403 subscription_inactive,
+    #               which follows billing_lapse.
+    # retries:      extra attempts after a timeout, network error or 503 (default 1, max 5, 0 = off). Same
+    #               idempotency key, so a retry is replayed, never counted twice. 4xx and other 5xx never retry.
+    # retry_budget: seconds for all attempts of one decide (default 0.65).
+    # mode:         nil (follow the plan's mode in the console), :enforce or :shadow
+    # billing_lapse: :open (default) or :closed, for 403 subscription_inactive (Terms 10.3(b)).
+    # deny_status:  429 (default) or 402 for quota denies.
+    # sticky_deny:  seconds to keep denying would-be fail-opens for an (agent key, tool) after quota_exceeded.
+    # logger:       a Logger (default: warn to $stderr), or false for silent.
+    # on_decision:  callable, called with every Decision (its errors are swallowed).
+    def initialize(api_key: nil, base_url: nil, timeout: DEFAULT_TIMEOUT, fail_mode: :open, retries: DEFAULT_RETRIES,
+                   retry_budget: DEFAULT_RETRY_BUDGET, mode: nil, billing_lapse: :open, deny_status: 429,
+                   sticky_deny: DEFAULT_STICKY_DENY, logger: nil, on_decision: nil, sleeper: nil)
+      @api_key = api_key || ENV["ORDAINER_API_KEY"] || ENV["ORDAINER_KEY"]
+      @base_url = (base_url || ENV["ORDAINER_BASE_URL"] || DEFAULT_BASE_URL).to_s.sub(%r{/+\z}, "")
+      @timeout = Float(timeout)
+      raise ConfigurationError, "timeout must be > 0" unless @timeout.positive?
+      @fail_mode = check_choice(fail_mode, FAIL_MODES, "fail_mode")
+      @billing_lapse = check_choice(billing_lapse, FAIL_MODES, "billing_lapse")
+      @mode = mode.nil? ? nil : check_choice(mode, MODES, "mode")
+      @retries = check_retries(retries)
+      @retry_budget = Float(retry_budget)
+      raise ConfigurationError, "deny_status must be 429 or 402" unless DENY_STATUSES.include?(deny_status)
+      @deny_status = deny_status
+      unless sticky_deny.is_a?(Numeric) && sticky_deny >= 0 && sticky_deny <= MAX_STICKY_DENY
+        raise ConfigurationError, "sticky_deny must be 0 (off) to #{MAX_STICKY_DENY} seconds"
+      end
+      @sticky_deny = sticky_deny
+      @sticky = {}
+      @lock = Mutex.new
+      @warned = {}
+      @logger = logger == false ? nil : (logger || Logger.new($stderr, progname: "ordainer"))
+      @on_decision = on_decision
+      @sleeper = sleeper || ->(s) { sleep(s) }
+      @uri = URI.join("#{@base_url}/", "v1/decide")
+    rescue ArgumentError, TypeError => e
+      raise ConfigurationError, e.message
+    end
+
+    # Never raises for an Ordainer answer or outage: a deny is a normal Decision. Bad arguments raise
+    # ConfigurationError. api_key: overrides the client's key for this call (one agent key per customer).
+    def decide(tool:, api_key: nil, idempotency_key: nil, mode: nil, fail_mode: nil, billing_lapse: nil, retries: nil)
+      started = monotonic
+      eff_fail = fail_mode.nil? ? @fail_mode : check_choice(fail_mode, FAIL_MODES, "fail_mode")
+      eff_lapse = billing_lapse.nil? ? @billing_lapse : check_choice(billing_lapse, FAIL_MODES, "billing_lapse")
+      req_mode = mode.nil? ? @mode : check_choice(mode, MODES, "mode")
+      max_attempts = 1 + (retries.nil? ? @retries : check_retries(retries))
+      key = api_key || @api_key
+      raw = idempotency_key.is_a?(Numeric) ? idempotency_key.to_s : idempotency_key
+      idem = raw.is_a?(String) && !raw.empty? ? Ordainer.idempotency_key_for(tool.is_a?(String) ? tool : "", raw) : SecureRandom.uuid
+      base = { tool: tool, idempotency_key: idem, mode: req_mode&.to_s, deny_status: @deny_status, attempts: 0,
+               would_deny: false, fail_open: false, fail_closed: false, rejected: false, billing_inactive: false,
+               test_limit_reached: false, rate_limited: false, safety_limited: false, sticky_deny: false, replayed: false }
+
+      result =
+        if key.nil? || key.to_s.empty?
+          rejected(base, ErrorInfo.new(code: "missing_key", message: "No #{BRAND_NAME} agent key (api_key / ORDAINER_API_KEY)."))
+        elsif !tool.is_a?(String) || tool.empty?
+          rejected(base, ErrorInfo.new(code: "invalid_request", message: "tool is required."))
+        else
+          budget_end = started + @retry_budget
+          attempt_timeout = @timeout
+          attempt = 0
+          loop do
+            attempt += 1
+            r, retryable = call(base, key, tool, idem, req_mode, eff_fail, eff_lapse, attempt_timeout)
+            r.attempts = attempt
+            result = r
+            break if !retryable || attempt >= max_attempts
+
+            pause = RETRY_DELAY * (2**(attempt - 1)) * (0.5 + rand) # jittered backoff
+            left = budget_end - monotonic - pause
+            break if left < MIN_ATTEMPT # out of budget: fail_mode applies now
+
+            attempt_timeout = [@timeout, left].min
+            @sleeper.call(pause)
+          end
+          apply_sticky_deny(result, key, tool, req_mode)
+        end
+      result.latency_ms = ((monotonic - started) * 1000).round
+      report(result)
+      result
+    end
+
+    # Like decide, but raises a BlockedError subclass when the call must not run. Returns the Decision otherwise.
+    def decide!(**kwargs)
+      d = decide(**kwargs)
+      return d if d.allowed?
+      raise RateLimitedError, d if d.rate_limited
+      raise RejectedError, d if d.rejected
+      raise UnavailableError, d if d.fail_closed
+      raise DeniedError, d
+    end
+
+    # Run the block only if allowed: client.guard(tool: "x") { do_work }. Raises like decide!.
+    def guard(**kwargs)
+      decision = decide!(**kwargs)
+      yield decision
+    end
+
+    def inspect = "#<Ordainer::Client base_url=#{@base_url} fail_mode=#{@fail_mode}>" # never shows the key
+
+    private
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    def check_choice(value, allowed, name)
+      sym = value.respond_to?(:to_sym) ? value.to_sym : value
+      return sym if allowed.include?(sym)
+
+      raise ConfigurationError, "#{name} must be #{allowed.map(&:inspect).join(' or ')} (got #{value.inspect})"
+    end
+
+    def check_retries(r)
+      return r if r.is_a?(Integer) && r >= 0 && r <= MAX_RETRIES
+
+      raise ConfigurationError, "retries must be an integer from 0 to #{MAX_RETRIES}"
+    end
+
+    # Returns [Decision, retryable].
+    def call(base, key, tool, idem, req_mode, fail_mode, lapse, timeout)
+      body = { tool: tool, idempotency_key: idem }
+      body[:mode] = req_mode.to_s if req_mode
+      begin
+        res = post(key, JSON.generate(body), timeout)
+      rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, ::Timeout::Error
+        return [failure(base, fail_mode, ErrorInfo.new(code: "timeout", message: "#{BRAND_NAME} did not answer within #{(timeout * 1000).round}ms")), true]
+      rescue SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError, Net::HTTPBadResponse, EOFError => e
+        dns = e.is_a?(SocketError) && e.message =~ /getaddrinfo|name or service|not known|nodename/i
+        msg = dns ? "#{e.message} (host #{@uri.host} not found; check ORDAINER_BASE_URL)" : e.message
+        report_dns(fail_mode) if dns
+        return [failure(base, fail_mode, ErrorInfo.new(code: "network_error", message: msg)), true]
+      end
+
+      status = res.code.to_i
+      json = begin
+        JSON.parse(res.body.to_s)
+      rescue JSON::ParserError
+        nil
+      end
+      json = nil unless json.is_a?(Hash)
+
+      if status != 200 || json.nil? || !%w[allow deny].include?(json["decision"])
+        env = json && json["error"].is_a?(Hash) ? json["error"] : {}
+        code = env["code"]
+        err = ErrorInfo.new(code: code || (status >= 500 ? "server_error" : "bad_response"),
+                            message: env["message"] || "#{BRAND_NAME} answered HTTP #{status}",
+                            status: status, request_id: env["request_id"] || res["x-request-id"])
+        if status == 429
+          err.limit_scope = LIMIT_SCOPES.include?(env["limit_scope"]) ? env["limit_scope"] :
+            { "too_many_failed_auth" => "per_address", "rate_limited" => "per_key",
+              CONCURRENCY_CODE => "per_key_concurrency", SAFETY_LIMIT_CODE => "org_safety" }[code]
+        end
+        # 429 safety_limit_reached: a safety limit, not a deny. Runs in any fail_mode.
+        if status == 429 && code == SAFETY_LIMIT_CODE
+          secs = Integer(res["retry-after"], exception: false)
+          return [Decision.new(**base, allowed: true, safety_limited: true, reason: SAFETY_LIMIT_CODE,
+                               resets_at: env["resets_at"].is_a?(String) ? env["resets_at"] : nil,
+                               retry_after_sec: secs&.positive? ? secs : nil, request_id: err.request_id,
+                               error: err.tap { |x| x.limit_scope = "org_safety" }), false]
+        end
+        is4xx = status >= 400 && status < 500
+        d = if status == 403 && code == "subscription_inactive" then lapse_decision(base, lapse, err)
+            elsif is4xx then rejected(base, err)
+            else failure(base, fail_mode, err)
+            end
+        if status == 403 && BILLING_CODES.include?(code)
+          d.billing_inactive = true
+          d.reason = code
+        end
+        if status == 429 && [CONCURRENCY_CODE, "rate_limited"].include?(code)
+          secs = Integer(res["retry-after"], exception: false)
+          d.rate_limited = true
+          d.reason = code
+          d.retry_after_sec = secs&.positive? ? secs : 1
+        end
+        return [d, status == 503] # only a 503 is retried (Node SDK: decide_timeout, db_unavailable, outage)
+      end
+
+      test_limit = json["decision"] == "deny" && json["reason"] == TEST_LIMIT_REASON
+      eff_mode = if test_limit then json["mode"] == "shadow" ? "shadow" : "enforce"
+                 elsif %w[shadow enforce].include?(json["mode"]) then json["mode"]
+                 else (req_mode || :enforce).to_s
+                 end
+      denied = json["decision"] == "deny"
+      [Decision.new(**base, test_limit_reached: test_limit, allowed: !denied || eff_mode == "shadow",
+                    decision: json["decision"], reason: json["reason"], remaining: json["remaining"],
+                    limit: json["limit"], resets_at: json["resets_at"], request_id: json["request_id"],
+                    mode: eff_mode, would_deny: denied && eff_mode == "shadow",
+                    replayed: res["idempotent-replayed"] == "true"), false]
+    end
+
+    def post(key, payload, timeout)
+      http = Net::HTTP.new(@uri.host, @uri.port)
+      http.use_ssl = @uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout
+      http.ssl_timeout = timeout if http.use_ssl?
+      http.max_retries = 0 # retries are ours (same idempotency key, budgeted)
+      req = Net::HTTP::Post.new(@uri)
+      req["Authorization"] = "Bearer #{key}"
+      req["Content-Type"] = "application/json"
+      req["User-Agent"] = "ordainer-ruby/#{VERSION}"
+      req.body = payload
+      ::Timeout.timeout(timeout * 2) { http.request(req) } # hard cap on top of the socket timeouts
+    end
+
+    def rejected(base, err)
+      Decision.new(**base, allowed: false, rejected: true, request_id: err.request_id, error: err)
+    end
+
+    def failure(base, fail_mode, err)
+      Decision.new(**base, allowed: fail_mode == :open, fail_open: fail_mode == :open,
+                           fail_closed: fail_mode == :closed, request_id: err.request_id, error: err)
+    end
+
+    def lapse_decision(base, lapse, err)
+      d = lapse == :closed ? rejected(base, err) : Decision.new(**base, allowed: true, request_id: err.request_id, error: err)
+      d.billing_lapse = lapse.to_s
+      d
+    end
+
+    def sticky_id(key, tool) = "#{Digest::SHA256.hexdigest(key.to_s)[0, 32]}\0#{tool}"
+
+    def apply_sticky_deny(r, key, tool, req_mode)
+      return r if @sticky_deny.zero?
+
+      id = sticky_id(key, tool)
+      now = Time.now
+      @lock.synchronize do
+        if r.decision == "deny" && r.reason == "quota_exceeded"
+          resets = (Time.iso8601(r.resets_at.to_s) rescue nil)
+          until_t = [now + @sticky_deny, resets].compact.min
+          if until_t > now
+            @sticky.delete(id)
+            @sticky.shift if @sticky.size >= MAX_STICKY_ENTRIES
+            @sticky[id] = { until: until_t, mode: r.mode, limit: r.limit, resets_at: r.resets_at }
+          end
+          return r
+        end
+        if r.decision == "allow"
+          @sticky.delete(id)
+          return r
+        end
+        return r if !r.fail_open || r.billing_inactive
+
+        entry = @sticky[id]
+        return r unless entry
+        if entry[:until] <= now
+          @sticky.delete(id)
+          return r
+        end
+        shadow = req_mode == :shadow || (req_mode.nil? && entry[:mode] == "shadow")
+        return r.dup_with(sticky_deny: true, would_deny: true, mode: "shadow") if shadow
+
+        r.dup_with(allowed: false, fail_open: false, sticky_deny: true, would_deny: false, reason: "quota_exceeded",
+                   remaining: 0, limit: entry[:limit], resets_at: entry[:resets_at], mode: "enforce")
+      end
+    end
+
+    def report(d)
+      if @logger && d.error && (!d.allowed? || d.fail_open)
+        kind = "#{d.rejected ? 'rejected' : d.fail_open ? 'fail_open' : 'fail_closed'}:#{d.error&.code}"
+        what = d.rejected ? "rejected (call blocked in any fail_mode)" : d.fail_open ? "fail-open (call allowed)" : "blocked"
+        throttled_warn(kind) { "[ordainer] #{what}: #{d.error&.code}: #{d.error&.message} X-Request-Id=#{d.request_id || 'none'} tool=#{d.tool}" }
+      elsif @logger && d.would_deny && d.mode == "shadow"
+        cap = d.limit.nil? ? "no cap" : "#{d.remaining}/#{d.limit}"
+        @logger.warn("[ordainer] shadow: would deny tool=#{d.tool} reason=#{d.reason} remaining=#{cap} request_id=#{d.request_id} (call allowed)")
+      end
+      begin
+        @on_decision&.call(d)
+      rescue StandardError
+        nil # hooks never break the request
+      end
+    end
+
+    # One warning per kind per minute, so an outage doesn't log once per call.
+    def throttled_warn(kind)
+      now = monotonic
+      @lock.synchronize do
+        return if @warned[kind] && now - @warned[kind] < 60
+
+        @warned[kind] = now
+      end
+      @logger.warn(yield)
+    end
+
+    def report_dns(fail_mode)
+      return if @dns_reported || !@logger
+
+      @dns_reported = true
+      @logger.error("[ordainer] ERROR: cannot resolve the #{BRAND_NAME} API host \"#{@uri.host}\" from base_url #{@base_url}. " \
+                    "Set ORDAINER_BASE_URL (or base_url:) to your #{BRAND_NAME} API URL. Until then every plan check fails: calls are " \
+                    "#{fail_mode == :closed ? 'blocked (fail_mode :closed)' : 'let through unchecked (fail_mode :open)'}.")
+    end
+  end
+end

data/lib/ordainer/configuration.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Ordainer
+  # Global settings for Ordainer.client and the Rails guard:
+  #   Ordainer.configure { |c| c.api_key = ENV["ORDAINER_API_KEY"]; c.fail_mode = :open }
+  class Configuration
+    attr_accessor :api_key, :base_url, :timeout, :fail_mode, :retries, :retry_budget, :mode,
+                  :billing_lapse, :deny_status, :sticky_deny, :logger, :on_decision
+
+    def initialize
+      @api_key = ENV["ORDAINER_API_KEY"] || ENV["ORDAINER_KEY"]
+      @base_url = nil
+    end
+
+    def to_client_options
+      { api_key: api_key, base_url: base_url, timeout: timeout, fail_mode: fail_mode, retries: retries,
+        retry_budget: retry_budget, mode: mode, billing_lapse: billing_lapse, deny_status: deny_status,
+        sticky_deny: sticky_deny, logger: logger, on_decision: on_decision }.compact
+    end
+  end
+
+  class << self
+    def configuration = (@configuration ||= Configuration.new)
+
+    def configure
+      yield configuration
+      @client = nil
+      configuration
+    end
+
+    # A shared client built from the configuration (thread-safe to share; one per process is fine).
+    def client = (@client ||= Client.new(**configuration.to_client_options))
+
+    def reset!
+      @configuration = nil
+      @client = nil
+    end
+  end
+end

data/lib/ordainer/decision.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Ordainer
+  # What went wrong when there was no decision: code, message, HTTP status, limit scope, request id.
+  ErrorInfo = Struct.new(:code, :message, :status, :limit_scope, :request_id, keyword_init: true)
+
+  # The result of Client#decide. Field names follow the Node SDK's result (snake_case).
+  class Decision
+    FIELDS = %i[
+      tool idempotency_key decision reason remaining limit resets_at request_id mode
+      would_deny fail_open fail_closed rejected error deny_status billing_inactive billing_lapse
+      test_limit_reached rate_limited retry_after_sec safety_limited sticky_deny replayed attempts latency_ms
+    ].freeze
+    attr_accessor(*FIELDS)
+    attr_writer :allowed
+
+    def initialize(**fields)
+      @allowed = false
+      fields.each { |k, v| public_send("#{k}=", v) }
+    end
+
+    # true: run the call. Shadow denies, fail-open and billing_lapse :open are allowed.
+    def allowed? = @allowed == true
+    def denied? = !allowed?
+    def would_deny? = would_deny == true
+    def fail_open? = fail_open == true
+    def fail_closed? = fail_closed == true
+    def rejected? = rejected == true
+    def rate_limited? = rate_limited == true
+    def replayed? = replayed == true
+    # Ordainer couldn't answer (timeout, network error, 5xx, malformed answer).
+    def unavailable? = fail_open? || fail_closed?
+
+    def to_h
+      FIELDS.to_h { |f| [f, public_send(f)] }.merge(allowed: allowed?).tap { |h| h[:error] = error&.to_h }
+    end
+
+    def dup_with(**changes)
+      d = dup
+      changes.each { |k, v| d.public_send("#{k}=", v) }
+      d
+    end
+  end
+end

data/lib/ordainer/deny_response.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Ordainer
+  BRAND_NAME = "Ordainer"
+  UNAVAILABLE_CODE = "ordainer_unavailable"
+  REJECTED_CODE = "plan_check_rejected"
+  TEST_LIMIT_REASON = "test_limit_reached"
+  # Legal-approved (Oct 3; tech/billing-lapse-scope.md item 2), verbatim, same as the Node SDK.
+  BILLING_BLOCKED_MESSAGE = "This action isn't available right now. This is a setup issue on the service's side; retrying won't help."
+
+  module_function
+
+  # What a blocked call should answer: { status:, headers:, body: { error: { code, message, request_id, ... } } }.
+  # Same statuses, codes and headers as the Node SDK's denyResponse(). Safe to return verbatim to the agent.
+  # The message never starts with a raw code; the code is its own field.
+  def deny_response(d, now: Time.now)
+    rid = d.request_id ? { "X-Request-Id" => d.request_id } : {}
+    if !d.allowed? && d.rate_limited
+      retry_after = (d.retry_after_sec || 1).to_s
+      return resp(429, { "Retry-After" => retry_after }.merge(rid),
+                  code: "rate_limited",
+                  message: "Too many plan checks for this agent right now (#{BRAND_NAME}'s per-key rate limit). Retry after #{retry_after}s. This call was not run.",
+                  request_id: d.request_id, retry_after: retry_after.to_i)
+    end
+    if d.rejected || (d.fail_closed && d.billing_inactive)
+      billing = d.billing_inactive
+      return resp(billing ? 403 : 500, rid,
+                  code: REJECTED_CODE,
+                  message: billing ? BILLING_BLOCKED_MESSAGE : "The plan check refused this call because of a setup problem on the service's side, so it was not run. This is not an outage: retrying will not help until whoever runs the service fixes its setup.",
+                  request_id: d.request_id)
+    end
+    if d.fail_closed
+      return resp(503, { "Retry-After" => "5" }.merge(rid),
+                  code: UNAVAILABLE_CODE,
+                  message: "The plan check is unavailable, so this call was not run. Try again shortly.",
+                  request_id: d.request_id)
+    end
+    if d.reason == TEST_LIMIT_REASON
+      return resp(429, retry_after_header(d.resets_at, now).merge(rid),
+                  code: TEST_LIMIT_REASON,
+                  message: "This #{BRAND_NAME} sandbox account has used its free test-key decisions for this month." +
+                           (d.resets_at ? " They reset at #{d.resets_at}." : "") +
+                           " This is a sandbox limit on test keys, not a plan limit and not an outage. Live keys are not affected. This call was not run.",
+                  request_id: d.request_id, reason: d.reason, resets_at: d.resets_at)
+    end
+    if d.reason == "quota_exceeded"
+      return resp(d.deny_status || 429, retry_after_header(d.resets_at, now).merge(rid),
+                  code: "plan_limit_reached",
+                  message: "This agent's plan limit is reached (#{d.remaining || 0} of #{d.limit || "?"} left)." +
+                           (d.resets_at ? " It resets at #{d.resets_at}." : "") +
+                           " Retrying before then will not succeed. This call was not run.",
+                  request_id: d.request_id, reason: d.reason, remaining: d.remaining, limit: d.limit, resets_at: d.resets_at)
+    end
+    # Node says "(<reason>)" in the message; here the reason is only a field (no raw codes in the message).
+    resp(403, rid,
+         code: "plan_denied",
+         message: "This agent's plan does not allow this call, so it was not run.",
+         request_id: d.request_id, reason: d.reason)
+  end
+
+  def resp(status, headers, **error)
+    { status: status, headers: headers, body: { error: error } }
+  end
+
+  def retry_after_header(resets_at, now)
+    t = Time.iso8601(resets_at.to_s) rescue nil
+    t ? { "Retry-After" => [1, (t - now).ceil].max.to_s } : {}
+  end
+  private_class_method :resp, :retry_after_header
+end

data/lib/ordainer/errors.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Ordainer
+  # Base class for everything this gem raises.
+  class Error < StandardError; end
+
+  # A bad option (fail_mode, retries, mode, ...). Raised up front, never from a network call.
+  class ConfigurationError < Error; end
+
+  # Raised only by Client#decide! (decide never raises). Carries the Decision and the response a
+  # blocked call should answer (status, headers, body).
+  class BlockedError < Error
+    attr_reader :decision, :status, :headers, :body
+
+    def initialize(decision)
+      @decision = decision
+      response = Ordainer.deny_response(decision)
+      @status = response[:status]
+      @headers = response[:headers]
+      @body = response[:body]
+      super(@body[:error][:message])
+    end
+  end
+
+  # Ordainer answered deny (quota_exceeded, tool_not_in_plan, test_limit_reached, ...) in enforce mode.
+  class DeniedError < BlockedError; end
+  # Ordainer refused the request (any 4xx, missing key): blocked in any fail_mode.
+  class RejectedError < BlockedError; end
+  # 429 rate_limited / concurrency_limited: slow down.
+  class RateLimitedError < RejectedError; end
+  # Ordainer couldn't answer (timeout, network, 5xx, malformed) and fail_mode is :closed.
+  class UnavailableError < BlockedError; end
+
+  # Raised inside the transport; turned into a Decision, never seen by callers of decide.
+  class TimeoutError < Error; end
+  class NetworkError < Error; end
+end

data/lib/ordainer/rails.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# Optional Rails helper. Loaded by `require "ordainer"` only when Rails (or ActionController) is already defined,
+# or explicitly with `require "ordainer/rails"`.
+#
+#   # config/initializers/ordainer.rb
+#   Ordainer.configure do |c|
+#     c.api_key = ENV["ORDAINER_API_KEY"]
+#     c.fail_mode = :open
+#   end
+#
+#   class ResearchController < ApplicationController
+#     include Ordainer::Rails::Guard
+#     ordainer_check tool: "research.run", customer: ->(c) { c.current_account.ordainer_key }, only: :create
+#   end
+module Ordainer
+  module Rails
+    # Controller concern. Works with any controller that has before_action, render and request
+    # (ActionController::Base / ::API). No ActiveSupport needed.
+    module Guard
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # tool:     the tool name, or ->(controller) { ... }
+        # customer: ->(controller) { agent key for this customer } (one agent key is one customer). Default: the
+        #           configured api_key.
+        # idempotency_key: ->(controller) { your own trusted id } (never the incoming Idempotency-Key header).
+        # mode:, fail_mode:, billing_lapse:, retries:, client: per-route overrides.
+        # on_deny:  ->(controller, decision) { ... } to answer a blocked call yourself.
+        # Any other options (only:, except:, if:, unless:) go to before_action.
+        def ordainer_check(tool:, customer: nil, idempotency_key: nil, mode: nil, fail_mode: nil, billing_lapse: nil,
+                           retries: nil, client: nil, on_deny: nil, **filter_options)
+          raise Ordainer::ConfigurationError, "ordainer_check: tool is required" if tool.nil? || tool == ""
+
+          opts = { tool: tool, customer: customer, idempotency_key: idempotency_key, mode: mode, fail_mode: fail_mode,
+                   billing_lapse: billing_lapse, retries: retries, client: client, on_deny: on_deny }
+          before_action(**filter_options) { |controller| controller.send(:ordainer_guard!, opts) }
+        end
+      end
+
+      # The Decision for this request (nil before the check runs).
+      def ordainer_decision = @ordainer_decision
+
+      private
+
+      def ordainer_guard!(opts)
+        resolve = ->(v) { v.respond_to?(:call) ? v.call(self) : v }
+        client = opts[:client] || Ordainer.client
+        decision = client.decide(tool: resolve.(opts[:tool]), api_key: resolve.(opts[:customer]),
+                                 idempotency_key: resolve.(opts[:idempotency_key]),
+                                 **opts.slice(:mode, :fail_mode, :billing_lapse, :retries).compact)
+        @ordainer_decision = decision
+        request.env["ordainer.decision"] = decision if respond_to?(:request, true) && request
+        return if decision.allowed?
+        return opts[:on_deny].call(self, decision) if opts[:on_deny]
+
+        r = Ordainer.deny_response(decision)
+        r[:headers].each { |k, v| response.headers[k] = v }
+        # Rails' RequestId middleware overwrites X-Request-Id with its own id; the body's request_id is Ordainer's.
+        response.headers["X-Ordainer-Request-Id"] = decision.request_id if decision.request_id
+        # Every block is a 403/429/500/503 JSON body: { error: { code, message, request_id, ... } }.
+        render json: r[:body], status: r[:status]
+      end
+    end
+  end
+end

data/lib/ordainer/version.rb

@@ -0,0 +1,3 @@
+module Ordainer
+  VERSION = "0.1.0"
+end

data/lib/ordainer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# ordainer: call Ordainer's POST /v1/decide before your tool runs. Ruby >= 3.0, stdlib only.
+#
+#   client = Ordainer::Client.new(api_key: ENV["ORDAINER_API_KEY"])
+#   decision = client.decide(tool: "research.run")
+#   return render_blocked(decision) unless decision.allowed?
+#
+# Mirrors the Node SDK (packages/ordainer-node, 1.2.2). See README.md for the rules.
+require_relative "ordainer/version"
+require_relative "ordainer/errors"
+require_relative "ordainer/decision"
+require_relative "ordainer/deny_response"
+require_relative "ordainer/client"
+require_relative "ordainer/configuration"
+require_relative "ordainer/rails" if defined?(::Rails) || defined?(::ActionController)

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: ordainer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ordainer
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ordainer.rb
+- lib/ordainer/client.rb
+- lib/ordainer/configuration.rb
+- lib/ordainer/decision.rb
+- lib/ordainer/deny_response.rb
+- lib/ordainer/errors.rb
+- lib/ordainer/rails.rb
+- lib/ordainer/version.rb
+homepage: https://docs.ordainer.dev
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: 'Ask Ordainer before your tool runs: one decide() call checks the caller''s
+  plan and counts the use.'
+test_files: []