ordainer 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f012928c3aedf7e8eafb2b5f2fd6fcec671f467e4a44d6214bc55c3adf49ee1
-  data.tar.gz: b748a4a31fa42620dc1fa045182147001f526fa789571ec9a1f2c112be85d416
+  metadata.gz: 53bc08e22508421e545a73555380d25329bc5c7cffb96f6476b479a416eb7586
+  data.tar.gz: 90543ec827c7accd06f17893821df1051ccd8b2faa5f6d4bcbc1351158518fab
 SHA512:
-  metadata.gz: 7c4e07d10dfb6911bddc8cba631b5ec33cc52499a9dfd8e83dfd75ce5424870a04fa8f1b69c87e73f66a4a719f44e8e14eb0fe4ee7b2c29cebdbda029ef044b0
-  data.tar.gz: 5fd5691ec62d7f837706fc46c6e4024cad416fa647dbac76357d74200446c1c077a58af50489752f8b6d8a4ced135bef3f88254ee3803082d50ba7ee9bc2fdf3
+  metadata.gz: 76c013a98e2d18e2d4306c975660b95a06c4aa1484a99311a3fd2f0a5175dfd394cde60915da49222026174cd56609f7b055f058b37d25396e0cdc8680b8b46c
+  data.tar.gz: c4deb82535a6f9cb7134358e609a966cf17a76b00d85257bbcd52b5e5470d9ade3a7884d686561c63e3736446837a3a430927ad31a7d59ca016d3588688e26de

data/CHANGELOG.md

@@ -1,4 +1,40 @@
 # Changelog
 
-## 0.1.0 (unreleased)
+## 0.1.1 (2026-10-18)
+- Fixed (QA P95F-N4): `Ordainer.deny_response` no longer raises `FloatDomainError` when the server's `resets_at` parses but
+  gives a non-finite number of seconds (for example a fraction hundreds of digits long); there is no `Retry-After` header
+  then, as for an unknown reset time. Status, code and body are unchanged.
+- Changed (PM final wording, Oct 18; replaces the P95R-N3 text below): Error messages reworded; codes, statuses and fields unchanged. Match on error.code, not the message. Same bytes as the Node SDK. `503 ordainer_unavailable`: "This call wasn't run. The service couldn't finish a safety check it does before each call, so it stopped instead of going ahead without it. Nothing is wrong on your side. Please try again in a minute. (ordainer_unavailable)".
+  `429 test_limit_reached`: "This call wasn't run. This service's test calls for the month are used up. They reset on
+  November 1 (UTC). Nothing is wrong on your side, and trying again won't help until they reset. If you need it sooner, contact
+  the service's team. (test_limit_reached)". The reset day is `resets_at` in UTC as "<Month D>" (full English month, no
+  leading zero, no year; no locale APIs), and the sentence appears only when `resets_at` is a valid ISO-8601 date-time
+  String (`YYYY-MM-DDTHH:MM:SS`, optional fraction, `Z` or `±HH:MM`); nil, empty, numbers, garbage or trailing text leave
+  it out (closes P95R-N4 for this message; `plan_limit_reached` is unchanged). `403 plan_denied` with `tool_not_in_plan`:
+  "This call wasn't run because your plan doesn't include "<tool>". If you need it, ask whoever manages your plan.
+  (tool_not_in_plan)", where `<tool>` is the tool passed to `decide` / `decide!` / the Rails guard (no extra request),
+  quoted only when it matches `\A[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}\z` and has no `//` and no leading `scheme:` (`\A[A-Za-z][A-Za-z0-9+.-]*:`, so nothing URL-like is echoed), otherwise "this action" without quotes. Any other
+  plan deny: "This call wasn't run because it isn't allowed on your account right now. If you need it, contact the
+  service's team. (<reason>)", with the bracket only when the reason matches `\A[a-z][a-z_]{0,39}\z`. Status, `code`,
+  `reason`, `resets_at`, `request_id`, headers and whether the call runs are unchanged.
+- Changed (P95R-N3, Content & DevRel Addendum 3, same bytes as the Node SDK): three more caller messages drop our name
+  and our terms. `503 ordainer_unavailable`: "This call wasn't run. The service couldn't complete a check it needs before
+  running it, and it's set to stop rather than go ahead without one. Please try again in a moment. (ordainer_unavailable)".
+  `429 test_limit_reached`: "This call wasn't run. The service's test allowance for this month is used up. It resets at
+  {resets_at}. It isn't something you did, and retrying won't help until the allowance resets. (test_limit_reached)" (no
+  "It resets at" sentence when `resets_at` is nil or empty; an empty value used to render "They reset at ."). `403
+  plan_denied`: "This call wasn't run because this agent's plan doesn't allow it. ({reason})", with the bracketed reason
+  only when it matches `\A[a-z][a-z_]{0,39}\z` (the same check as the `plan_check_rejected` message); otherwise it ends at
+  "allow it.". Before, the Ruby 403 message never named the reason. Only `message` (and the raised errors' `message`)
+  changes: status, `code` (still `ordainer_unavailable`), `reason`, `resets_at`, `request_id`, headers and whether the call
+  runs are unchanged.
+- Changed (T18-P40, same strings as the Node SDK): the caller's `500 plan_check_rejected` message says what kind of setup
+  issue it is (a key isn't recognized, has been turned off, or is missing; anything else) and ends with the API's code for
+  the service's team. The `429 rate_limited` message no longer names us: "The service is getting too many requests on this
+  key right now, so this call was held back. Please wait a moment and try again. (rate_limited)". A `429 concurrency_limited`
+  now gets its own: "The service is handling too many calls on this key at once, so this call was held back. Please wait a moment and try again. (concurrency_limited)" (the `code` field stays `rate_limited`). Only `message` changes:
+  status, `code`, headers (`Retry-After`, `X-Request-Id`), `retry_after`, `rejected?` / `rate_limited?` and whether the call
+  runs are unchanged. The 403 billing message is unchanged.
+
+## 0.1.0 (2026-10-14)
 - First version: Ordainer::Client#decide, Decision, typed errors, retries, fail_mode, optional Rails guard.

data/README.md

@@ -4,7 +4,17 @@ Ask Ordainer before your tool runs: one `decide` call checks the caller's plan a
 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).
+Install from [RubyGems](https://rubygems.org/gems/ordainer):
+
+```sh
+gem install ordainer
+```
+
+or in your Gemfile:
+
+```ruby
+gem "ordainer", "~> 0.1"
+```
 
 ```ruby
 require "ordainer"
@@ -47,6 +57,26 @@ end
   `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.
+- What the caller reads (`Ordainer.deny_response`, same text as the Node SDK): a block a retry can't fix answers
+  `500 plan_check_rejected` with plain words for the cause and the API's code last, e.g. "This call wasn't run. This is a
+  setup issue on the service's side: one of its keys isn't recognized. It isn't something you did, and retrying won't help
+  until the service fixes the key. (For the service's team: unknown_key.)" A `429 rate_limited` answers "The service is
+  getting too many requests on this key right now, so this call was held back. Please wait a moment and try again.
+  (rate_limited)" with `Retry-After`; a `429 concurrency_limited` answers "The service is handling too many calls on this key at once, so this call was held back. Please wait a moment and try again. (concurrency_limited)" (the `code` field
+  stays `rate_limited`). Billing blocks (403) keep the Legal-approved text.
+- The same text as the Node SDK for the other blocks too (PM final wording, Oct 18). Error messages can be reworded;
+  codes, statuses and fields stay the same, so match on `code`, not the message. An outage under `fail_mode: :closed`
+  answers `503 ordainer_unavailable` with `Retry-After: 5`: "This call wasn't run. The service couldn't finish a safety check it does before each call, so it stopped instead of going ahead without it. Nothing is wrong on your side. Please try again in a minute. (ordainer_unavailable)".
+  A used-up test allowance answers `429 test_limit_reached`: "This call wasn't run. This service's test calls for the
+  month are used up. They reset on November 1 (UTC). Nothing is wrong on your side, and trying again won't help until
+  they reset. If you need it sooner, contact the service's team. (test_limit_reached)" (the day is `resets_at` in UTC as
+  "<Month D>"; no "They reset on" sentence unless `resets_at` is a valid ISO-8601 date-time). A `tool_not_in_plan` deny
+  answers `403 plan_denied`: "This call wasn't run because your plan doesn't include "research.run". If you need it, ask
+  whoever manages your plan. (tool_not_in_plan)", naming the tool you passed to `decide` (or the Rails guard) in quotes
+  only when it matches `\A[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}\z` and has no `//` and no leading `scheme:` (`\A[A-Za-z][A-Za-z0-9+.-]*:`, so nothing URL-like is echoed), otherwise "this action". Any other deny answers "This
+  call wasn't run because it isn't allowed on your account right now. If you need it, contact the service's team.
+  (reason)", with the reason in brackets only when it looks like an API code (lowercase letters and `_`, up to 40
+  characters); the reason is also its own `reason` field.
 
 ## Decision
 

data/lib/ordainer/deny_response.rb

@@ -9,6 +9,34 @@ module Ordainer
   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."
+  # Caller-facing text for a 429 rate_limited / concurrency_limited block, same as the Node SDK (Content & DevRel, Oct 18):
+  # no product name. Only the message differs; the code field stays rate_limited for both, and status, Retry-After and
+  # retry_after are unchanged.
+  RATE_LIMITED_MESSAGE = "The service is getting too many requests on this key right now, so this call was held back. Please wait a moment and try again. (rate_limited)"
+  CONCURRENCY_LIMITED_MESSAGE = "The service is handling too many calls on this key at once, so this call was held back. Please wait a moment and try again. (concurrency_limited)"
+  # T18-P40 (Content & DevRel final wording, Oct 18; same strings as the Node SDK's rejectedMessage()): the caller-facing
+  # sentence for a block a retry can't fix (500 plan_check_rejected). Plain words first, the API's own code last for the
+  # service's team; the code is echoed only if it looks like an API code (lowercase letters and _, <= 40 chars).
+  # too_many_failed_auth stays with "isn't recognized": the API's "couldn't check this key" variant has the same status,
+  # code, limit_scope and headers; only its English message differs.
+  KEY_NOT_RECOGNIZED_CODES = %w[unknown_key old_key_format too_many_failed_auth].freeze
+  REJECTED_TAIL = "It isn't something you did, and retrying won't help until the service"
+  # P95R-N3 (Content & DevRel, Oct 18, content/persona-2-2026-10-18/p40-sdk-key-messages.md Addendum 3; same bytes as
+  # the Node SDK): the 503 fail-closed outage, the 429 test allowance and the 403 plan deny. No product name and none of
+  # our terms. Only the message changes: status, code (ordainer_unavailable is kept), headers and fields are unchanged.
+  # Text replaced by the PM's final wording (Oct 18); codes and fields are as before.
+  UNAVAILABLE_MESSAGE = "This call wasn't run. The service couldn't finish a safety check it does before each call, so it stopped instead of going ahead without it. Nothing is wrong on your side. Please try again in a minute. (#{UNAVAILABLE_CODE})"
+  API_CODE_SHAPE = /\A[a-z][a-z_]{0,39}\z/
+  # PM final wording (Oct 18): tool_not_in_plan names the tool sent in decide(), in double quotes, only when it looks
+  # like a plain tool name; otherwise "this action". Same check and bytes as the Node SDK's TOOL_NAME_SHAPE.
+  TOOL_NAME_SHAPE = /\A[A-Za-z0-9][A-Za-z0-9_.:\/-]{0,63}\z/
+  # QA P95F-N3: nothing URL-like is echoed either: no "//" anywhere and no leading "scheme:" (RFC 3986 shape). Same as Node.
+  TOOL_SCHEME_PREFIX = /\A[A-Za-z][A-Za-z0-9+.-]*:/
+  # Addendum 3 amendment (Oct 18, CoS): the reset day as "<Month D>" in UTC (full English month, no leading zero, no
+  # year). Only for a String that is a valid ISO-8601 date-time (YYYY-MM-DDTHH:MM:SS, optional .fraction, then Z or
+  # +HH:MM/-HH:MM). Fixed month list and integer UTC math only (no Time.parse, no locale), same bytes as Node.
+  MONTHS = %w[January February March April May June July August September October November December].freeze
+  ISO_DATE_TIME = /\A(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?(?:Z|([+-])(\d{2}):(\d{2}))\z/
 
   module_function
 
@@ -21,28 +49,26 @@ module Ordainer
       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.",
+                  message: d.reason == "concurrency_limited" ? CONCURRENCY_LIMITED_MESSAGE : RATE_LIMITED_MESSAGE,
                   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.",
+                  message: billing ? BILLING_BLOCKED_MESSAGE : rejected_message(d.error&.code),
                   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.",
+                  message: UNAVAILABLE_MESSAGE,
                   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.",
+                  message: test_limit_message(d.resets_at),
                   request_id: d.request_id, reason: d.reason, resets_at: d.resets_at)
     end
     if d.reason == "quota_exceeded"
@@ -53,20 +79,103 @@ module Ordainer
                            " 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).
+    # Same as Node: the reason in brackets at the end, only when it looks like an API code.
     resp(403, rid,
          code: "plan_denied",
-         message: "This agent's plan does not allow this call, so it was not run.",
+         message: plan_denied_message(d.reason, d.tool),
          request_id: d.request_id, reason: d.reason)
   end
 
+  def rejected_message(code)
+    msg =
+      if code == "missing_key"
+        "This call wasn't run. This is a setup issue on the service's side: a key it needs is missing. #{REJECTED_TAIL} adds the key."
+      elsif code == "revoked_key"
+        "This call wasn't run. This is a setup issue on the service's side: one of its keys has been turned off. #{REJECTED_TAIL} switches to a new key."
+      elsif KEY_NOT_RECOGNIZED_CODES.include?(code)
+        "This call wasn't run. This is a setup issue on the service's side: one of its keys isn't recognized. #{REJECTED_TAIL} fixes the key."
+      else
+        "This call wasn't run because of a setup issue on the service's side. #{REJECTED_TAIL} fixes it."
+      end
+    code.is_a?(String) && code.match?(API_CODE_SHAPE) ? "#{msg} (For the service's team: #{code}.)" : msg
+  end
+
+  # Same rules as Node's resetDayUtc(): nil for anything that isn't a valid ISO-8601 date-time String.
+  def reset_day_utc(v)
+    return nil unless v.is_a?(String) && v.valid_encoding?
+
+    m = ISO_DATE_TIME.match(v)
+    return nil unless m
+
+    y, mo, d, h, mi, s = m.captures[0, 6].map(&:to_i)
+    leap = (y % 4).zero? && !(y % 100).zero? || (y % 400).zero?
+    dim = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
+    return nil if mo < 1 || mo > 12 || d < 1 || d > dim[mo - 1] || h > 23 || mi > 59 || s > 59
+
+    off = 0
+    if m[7]
+      oh = m[8].to_i
+      om = m[9].to_i
+      return nil if oh > 23 || om > 59
+
+      off = (m[7] == "-" ? -1 : 1) * (oh * 60 + om)
+    end
+    # Minutes from local midnight, shifted to UTC; at most one day either way.
+    mins = h * 60 + mi - off
+    uy, um, ud = y, mo, d
+    if mins.negative?
+      ud -= 1
+      if ud < 1
+        um -= 1
+        if um < 1
+          um = 12
+          uy -= 1
+        end
+        ud = dim[um - 1] # February only from March 1 (same year)
+      end
+    elsif mins >= 1440
+      ud += 1
+      if ud > dim[mo - 1]
+        ud = 1
+        um += 1
+        um = 1 if um > 12
+      end
+    end
+    "#{MONTHS[um - 1]} #{ud}"
+  end
+
+  def test_limit_message(resets_at)
+    day = reset_day_utc(resets_at)
+    "This call wasn't run. This service's test calls for the month are used up." +
+      (day ? " They reset on #{day} (UTC)." : "") +
+      " Nothing is wrong on your side, and trying again won't help until they reset. If you need it sooner, contact the service's team. (test_limit_reached)"
+  end
+
+  def showable_tool?(tool)
+    tool.is_a?(String) && tool.valid_encoding? && tool.match?(TOOL_NAME_SHAPE) && !tool.include?("//") &&
+      !tool.match?(TOOL_SCHEME_PREFIX)
+  end
+
+  def plan_denied_message(reason, tool = nil)
+    if reason == "tool_not_in_plan"
+      what = showable_tool?(tool) ? "\"#{tool}\"" : "this action"
+      return "This call wasn't run because your plan doesn't include #{what}. If you need it, ask whoever manages your plan. (tool_not_in_plan)"
+    end
+    msg = "This call wasn't run because it isn't allowed on your account right now. If you need it, contact the service's team."
+    reason.is_a?(String) && reason.valid_encoding? && reason.match?(API_CODE_SHAPE) ? "#{msg} (#{reason})" : msg
+  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 } : {}
+    return {} unless t
+
+    # QA P95F-N4: a huge fraction can make the difference NaN/Infinity; no header then, never a FloatDomainError.
+    secs = (t - now).to_f
+    secs.finite? ? { "Retry-After" => [1, secs.ceil].max.to_s } : {}
   end
   private_class_method :resp, :retry_after_header
 end

data/lib/ordainer/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ordainer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Ordainer
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies: []
 executables: []
 extensions: []