dinie-sdk-sandbox 1.1.0

data/lib/dinie/runtime/paginator.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Dinie
+  # `Page` — one page of a cursor-paginated list, and the auto-pagination engine over the pages
+  # that follow it (architecture §11, RB8). Ports `sdk-js` `src/runtime/paginator.ts` and mirrors
+  # the mechanics of OpenAI Ruby's `base_page.rb`. Part of the **public surface** (`Dinie::Page`).
+  #
+  # Dinie has exactly ONE cursor scheme (inherited contract): `starting_after` (the `id` of the
+  # last item of the previous page) + `has_more` (the ONLY end-of-list signal — never
+  # `data.length == limit`, since the server may return fewer items with `has_more: true`).
+  #
+  # A resource's `list*` does the first request **eagerly** and returns a `Page` carrying the
+  # first page's `data`, its `has_more`, and a `fetch_page` closure that knows how to fetch the
+  # next page (it maps a cursor to the `starting_after` query param and calls the transport).
+  # The `Page` owns *when* to call the closure and *what* cursor to pass; the resource owns *how*
+  # the closure reaches the network — so this class stays pure and is tested with an in-memory
+  # fake (no `HttpClient` coupling).
+  #
+  # ── Why NOT `include Enumerable` (RB8) ──
+  # `Enumerable` would graft on methods that materialize EVERY page eagerly (`to_a`, `count`,
+  # `sort`, `min`…). A paginator must stay lazy, so we deliberately define only `#each` (+ its
+  # `#auto_paging_each` alias) and `#each_page`; calling either without a block returns an
+  # `Enumerator`, which gives `.map` / `.first` / `.lazy` on demand without eager-loading.
+  #
+  # ── Iteration modes ──
+  #   * `#each` / `#auto_paging_each` — yield EVERY item of EVERY following page (auto-paginate).
+  #   * `#each_page` — yield page-by-page (manual control via `#next_page?` / `#next_page`).
+  #   * `#first(n)` — the first `n` items across pages, fetched lazily (stops as soon as it has `n`).
+  #
+  # @example auto-paginate every item
+  #   client.customers.list(limit: 50).each { |c| puts c.id }
+  # @example page-by-page
+  #   client.customers.list.each_page { |page| process(page.data) }
+  # @example just the first 10, lazily
+  #   top = client.customers.list.first(10)
+  #
+  # @note Items must respond to `#id` — the next page's `starting_after` cursor is the `id` of the
+  #   last item on the current page. Every list item in the frozen surface satisfies this.
+  class Page
+    # Items on this page — already deserialized into typed POROs by the resource's `fetch_page`.
+    # @return [Array<Object>]
+    attr_reader :data
+    # Whether the API reports more pages after this one — the ONLY end-of-list signal.
+    # @return [Boolean]
+    attr_reader :has_more
+
+    # Message raised by {#next_page} when there is no next page to fetch.
+    NO_NEXT_PAGE_MESSAGE = "No next page; guard with `#next_page?` (or check `#has_more`) first."
+
+    class << self
+      # Build the FIRST page by invoking `fetch_page` with no cursor (so the closure uses the
+      # caller's `starting_after`, if any). This is the entry point a resource's `list*` calls.
+      #
+      # @param fetch_page [#call] `->(cursor) { { data: [...], has_more: bool } }` — fetches the
+      #   page after `cursor` (`nil` ⇒ the first page) and returns the wire envelope
+      # @return [Dinie::Page]
+      def from_fetch(fetch_page)
+        build(fetch_page.call(nil), fetch_page)
+      end
+
+      # Wrap a fetched `{ data:, has_more: }` envelope (already item-deserialized) in a `Page`.
+      #
+      # @api private
+      # @param envelope [Hash] `{ data: Array, has_more: Boolean }`
+      # @param fetch_page [#call]
+      # @return [Dinie::Page]
+      def build(envelope, fetch_page)
+        new(data: envelope[:data] || [], has_more: envelope[:has_more] == true, fetch_page: fetch_page)
+      end
+
+      # The deterministic discriminator (architecture §7.5/§11): a list endpoint is paginated **iff**
+      # its envelope carries `has_more`. `/banks` lacks it, so the platform resource (story 010)
+      # returns a flat `Array<Bank>` instead of a `Page`. Exposed here so that rule has one home.
+      #
+      # @param envelope [Object] a parsed response body
+      # @return [Boolean] true when the body is a paginated list envelope
+      def paginated?(envelope)
+        envelope.is_a?(Hash) && envelope.key?(:has_more)
+      end
+    end
+
+    # @param data [Array<Object>] this page's items
+    # @param has_more [Boolean] whether more pages follow
+    # @param fetch_page [#call] `->(cursor) { envelope }` for the next page
+    def initialize(data:, has_more:, fetch_page:)
+      @data = data
+      @has_more = has_more
+      @fetch_page = fetch_page
+      freeze
+    end
+
+    # Whether a next page can be fetched. Driven by `has_more`; the `!data.empty?` guard is a safety
+    # net — an empty page has no last item (so no cursor), so we stop rather than loop forever on a
+    # malformed `{ data: [], has_more: true }`.
+    #
+    # @return [Boolean]
+    def next_page?
+      @has_more && !@data.empty?
+    end
+
+    # Fetch the next page. The cursor is the `id` of the LAST item on this page (mapped to
+    # `starting_after` by the closure). Guard with {#next_page?} before calling.
+    #
+    # @return [Dinie::Page]
+    # @raise [Dinie::Error] when there is no next page
+    def next_page
+      raise Dinie::Error, NO_NEXT_PAGE_MESSAGE unless next_page?
+
+      self.class.build(@fetch_page.call(@data.last.id), @fetch_page)
+    end
+
+    # Auto-paginate: yield every item of this page, then every item of each following page, until
+    # `has_more` is false. Without a block, returns an `Enumerator` (`.map` / `.first` / `.lazy`).
+    #
+    # @yieldparam item [Object]
+    # @return [self, Enumerator]
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      page = self
+      loop do
+        page.data.each(&block)
+        break unless page.next_page?
+
+        page = page.next_page
+      end
+      self
+    end
+    alias auto_paging_each each
+
+    # Yield page-by-page (manual control), following the cursor until `has_more` is false. Without
+    # a block, returns an `Enumerator` over the pages.
+    #
+    # @yieldparam page [Dinie::Page]
+    # @return [self, Enumerator]
+    def each_page
+      return enum_for(:each_page) unless block_given?
+
+      page = self
+      loop do
+        yield page
+        break unless page.next_page?
+
+        page = page.next_page
+      end
+      self
+    end
+
+    # The first `count` items across pages (or the very first item when `count` is omitted),
+    # fetched lazily — only as many pages as needed are requested.
+    #
+    # @param count [Integer, nil] how many items to take; omit for a single item
+    # @return [Object, Array<Object>]
+    def first(count = UNSPECIFIED)
+      return auto_paging_each.first if count.equal?(UNSPECIFIED)
+
+      auto_paging_each.first(count)
+    end
+
+    # Sentinel distinguishing `first` (one item) from `first(n)` (an array) — `nil`/`0` are valid `n`.
+    UNSPECIFIED = Object.new
+    private_constant :UNSPECIFIED
+  end
+end

data/lib/dinie/runtime/rate_limit.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Dinie
+  # The rate-limit snapshot read from the most recent response's `X-RateLimit-*` headers
+  # (architecture §10, RB6). Surfaced as `client.rate_limit`; `nil` until a response carries
+  # valid headers.
+  #
+  # `reset_at` is the SDK's **only** `Time` (RB6): every body timestamp stays an `Integer`
+  # epoch, but this value comes from a transport header (not the wire body), so it is
+  # normalized to a `Time` — mirroring the `Date` the TypeScript SDK exposes here.
+  #
+  # @example
+  #   rl = client.rate_limit
+  #   rl.remaining        # => 87
+  #   rl.reset_at         # => 2026-06-02 12:00:30 UTC
+  class RateLimit
+    # @return [Integer] ceiling for the current window (`X-RateLimit-Limit`)
+    attr_reader :limit
+    # @return [Integer] requests left in the current window (`X-RateLimit-Remaining`)
+    attr_reader :remaining
+    # @return [Time] when the window resets (`X-RateLimit-Reset`)
+    attr_reader :reset_at
+
+    # @param limit [Integer]
+    # @param remaining [Integer]
+    # @param reset_at [Time]
+    def initialize(limit:, remaining:, reset_at:)
+      @limit = limit
+      @remaining = remaining
+      @reset_at = reset_at
+      freeze
+    end
+
+    # @return [Hash{Symbol => Object}]
+    def to_h
+      { limit: limit, remaining: remaining, reset_at: reset_at }
+    end
+    alias to_hash to_h
+
+    # Enable pattern matching (`case rl; in { remaining: 0 }`).
+    #
+    # @param _keys [Array<Symbol>, nil]
+    # @return [Hash{Symbol => Object}]
+    def deconstruct_keys(_keys) = to_h
+
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(RateLimit) && other.to_h == to_h
+    end
+    alias eql? ==
+
+    # @return [Integer]
+    def hash
+      to_h.hash
+    end
+  end
+
+  module Internal
+    # Parses the three `X-RateLimit-*` headers off the latest response and holds the most
+    # recent {Dinie::RateLimit} snapshot for {HttpClient} (architecture §10). Mirrors
+    # `sdk-js` `rate-limit.ts` (`parseRateLimit` + `RateLimitTracker`).
+    #
+    # **All-or-nothing (decision):** {Dinie::RateLimit} has non-nullable fields, so {parse}
+    # returns the whole object or `nil` — never a partial. A missing/garbage header makes the
+    # parse `nil`, and {#update} then keeps the previous snapshot rather than clobbering a good
+    # value with a header-less response (such as the token call).
+    class RateLimitTracker
+      # Response header carrying the window ceiling.
+      LIMIT_HEADER = "x-ratelimit-limit"
+      # Response header carrying the requests remaining in the window.
+      REMAINING_HEADER = "x-ratelimit-remaining"
+      # Response header carrying the window reset time (epoch seconds or delta seconds).
+      RESET_HEADER = "x-ratelimit-reset"
+
+      # `X-RateLimit-Reset` values at or above this (seconds) are read as an absolute Unix
+      # epoch; anything below as a delta in seconds from now. `1e9` seconds is ~2001-09 — far
+      # above any plausible "seconds until reset" window yet below every real epoch.
+      EPOCH_THRESHOLD_SECONDS = 1_000_000_000
+
+      # @return [Dinie::RateLimit, nil] latest snapshot, or `nil` before any valid headers
+      def snapshot
+        @current
+      end
+
+      # Fold a response's headers into the snapshot. A header-less or garbage response leaves
+      # the previous snapshot untouched (does not reset it to `nil`).
+      #
+      # @param headers [#each] response headers (case-insensitive keys)
+      # @return [void]
+      def update(headers)
+        parsed = self.class.parse(headers)
+        @current = parsed unless parsed.nil?
+      end
+
+      # Parse the three `X-RateLimit-*` headers into a {Dinie::RateLimit}, or `nil` when any is
+      # absent or unparseable. Never raises.
+      #
+      # @param headers [#each] response headers
+      # @return [Dinie::RateLimit, nil]
+      def self.parse(headers)
+        limit = parse_count(header_value(headers, LIMIT_HEADER))
+        remaining = parse_count(header_value(headers, REMAINING_HEADER))
+        reset_at = parse_reset(header_value(headers, RESET_HEADER))
+        return nil if limit.nil? || remaining.nil? || reset_at.nil?
+
+        Dinie::RateLimit.new(limit: limit, remaining: remaining, reset_at: reset_at)
+      end
+
+      # @api private
+      # @return [Integer, nil]
+      def self.parse_count(raw)
+        return nil if raw.nil?
+
+        value = Integer(raw.to_s.strip, exception: false)
+        value && value >= 0 ? value : nil
+      end
+
+      # @api private
+      # @return [Time, nil]
+      def self.parse_reset(raw)
+        return nil if raw.nil?
+
+        seconds = Float(raw.to_s.strip, exception: false)
+        return nil if seconds.nil? || seconds.negative?
+
+        seconds >= EPOCH_THRESHOLD_SECONDS ? Time.at(seconds) : Time.now + seconds
+      end
+
+      # @api private
+      # Case-insensitive header lookup; first value of a repeated header.
+      # @return [String, nil]
+      def self.header_value(headers, name)
+        return nil unless headers.respond_to?(:each)
+
+        target = name.downcase
+        headers.each do |key, value|
+          next unless key.to_s.downcase == target
+
+          return value.is_a?(Array) ? value.first : value
+        end
+        nil
+      end
+
+      private_class_method :parse_count, :parse_reset, :header_value
+    end
+  end
+end

data/lib/dinie/runtime/request_options.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Dinie
+  module Internal
+    # Normalized per-call options, the trailing `request_options:` Hash every public method
+    # accepts (architecture §12, RB5). Validates types up front and freezes; the actual
+    # header merge against the client defaults (where a `nil` value removes a default) and
+    # the timeout/retry wiring happen in the transport (story 003).
+    #
+    # @example
+    #   Dinie::Internal::RequestOptions.coerce(timeout: 5, headers: { "x-trace" => "abc" })
+    class RequestOptions
+      # @return [Numeric, nil] per-call timeout, in seconds
+      attr_reader :timeout
+      # @return [String, nil] explicit idempotency key (overrides the auto-generated one)
+      attr_reader :idempotency_key
+      # @return [Hash{String => String, nil}, nil] per-call header overrides (a `nil` value removes a default)
+      attr_reader :headers
+      # @return [Integer, nil] per-call retry budget override
+      attr_reader :max_retries
+
+      # Coerce a value into a {RequestOptions}: pass an instance through, or build one from a
+      # Hash (string or symbol keys; `nil` → empty).
+      #
+      # @param value [RequestOptions, Hash, nil]
+      # @return [RequestOptions]
+      # @raise [ArgumentError] on an unknown key or an invalid value type
+      def self.coerce(value)
+        return value if value.is_a?(self)
+
+        new(**(value || {}).transform_keys(&:to_sym))
+      end
+
+      # @param timeout [Numeric, nil] seconds; must be a non-negative Numeric
+      # @param idempotency_key [String, nil]
+      # @param headers [Hash, nil] values must be String or nil
+      # @param max_retries [Integer, nil] must be a non-negative Integer
+      # @raise [ArgumentError] on an invalid value type
+      def initialize(timeout: nil, idempotency_key: nil, headers: nil, max_retries: nil)
+        @timeout = validate_timeout(timeout)
+        @idempotency_key = validate_string(idempotency_key, :idempotency_key)
+        @headers = validate_headers(headers)
+        @max_retries = validate_max_retries(max_retries)
+        freeze
+      end
+
+      # @return [Hash{Symbol => Object}] the normalized options
+      def to_h
+        { timeout: timeout, idempotency_key: idempotency_key, headers: headers, max_retries: max_retries }
+      end
+      alias to_hash to_h
+
+      # @param other [Object]
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(RequestOptions) && other.to_h == to_h
+      end
+      alias eql? ==
+
+      # @return [Integer]
+      def hash
+        to_h.hash
+      end
+
+      private
+
+      def validate_timeout(value)
+        return nil if value.nil?
+        unless value.is_a?(Numeric) && !value.negative?
+          raise ArgumentError,
+                "request_options[:timeout] must be a non-negative Numeric (seconds), got #{value.inspect}"
+        end
+
+        value
+      end
+
+      def validate_max_retries(value)
+        return nil if value.nil?
+        unless value.is_a?(Integer) && !value.negative?
+          raise ArgumentError, "request_options[:max_retries] must be a non-negative Integer, got #{value.inspect}"
+        end
+
+        value
+      end
+
+      def validate_string(value, key)
+        return nil if value.nil?
+        unless value.is_a?(String)
+          raise ArgumentError,
+                "request_options[:#{key}] must be a String, got #{value.inspect}"
+        end
+
+        value
+      end
+
+      def validate_headers(value)
+        return nil if value.nil?
+        raise ArgumentError, "request_options[:headers] must be a Hash, got #{value.inspect}" unless value.is_a?(Hash)
+
+        value.each_with_object({}) do |(key, header_value), acc|
+          unless header_value.nil? || header_value.is_a?(String)
+            raise ArgumentError,
+                  "request_options[:headers] values must be String or nil (nil removes a default), " \
+                  "got #{header_value.inspect} for #{key.inspect}"
+          end
+
+          acc[key.to_s] = header_value
+        end
+      end
+    end
+  end
+end

data/lib/dinie/runtime/retry.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "set"
+require "faraday"
+
+module Dinie
+  module Internal
+    # Retry policy — pure decision + delay functions (no I/O, no state). The retry loop itself
+    # — sleeping, attempt counting, the `X-Dinie-Retry-Count` header, the 401 one-shot re-auth
+    # — lives in {HttpClient} (architecture §10, RB15). Mirrors `sdk-js` `retry.ts` so the two
+    # SDKs share the exact same backoff/jitter/status-set behavior (the `comparison.md` axis).
+    #
+    # Runtime-internal: imported directly by {HttpClient}, not part of the public surface. The
+    # public `Retry-After` parser lives separately as {Dinie.parse_retry_after} (story 002).
+    module Retry
+      # HTTP status codes the SDK retries (V0.2 freeze decision; architecture §10).
+      #
+      # Exactly `{408, 429, 500, 502, 503, 504}`, plus timeouts/connection errors (handled by
+      # {retryable_network_error?}). `409` (Dinie semantic conflict) and `410` (gone) **never**
+      # retry; `401` is a one-shot re-auth handled in {HttpClient}, orthogonal to this set.
+      # `500` is safe to retry on a non-GET because the stable `X-Idempotency-Key` (minted once
+      # before the loop) guarantees a retry never creates a duplicate resource.
+      RETRYABLE_STATUS = Set[408, 429, 500, 502, 503, 504].freeze
+
+      # Initial backoff, in seconds (the `attempt = 0` base before jitter).
+      INITIAL_BACKOFF_SECONDS = 0.5
+      # Backoff ceiling, in seconds (reached at `attempt = 4`).
+      MAX_BACKOFF_SECONDS = 8
+      # Subtractive jitter fraction — the delay is reduced by up to this share.
+      JITTER_RATIO = 0.25
+
+      # Faraday transport errors (no HTTP response) worth retrying: a request timeout and a
+      # connection failure (DNS/refused/reset). Anything else propagates as a connection error.
+      RETRYABLE_NETWORK_ERRORS = [Faraday::TimeoutError, Faraday::ConnectionFailed].freeze
+
+      module_function
+
+      # True only for the retryable status set (`{408, 429, 500, 502, 503, 504}`).
+      #
+      # @param status [Integer]
+      # @return [Boolean]
+      def should_retry?(status)
+        RETRYABLE_STATUS.include?(status)
+      end
+
+      # Whether a thrown transport error (no HTTP response) is worth retrying: a timeout or a
+      # connection failure. Keys off the Faraday error class, never the message.
+      #
+      # @param error [Exception]
+      # @return [Boolean]
+      def retryable_network_error?(error)
+        RETRYABLE_NETWORK_ERRORS.any? { |klass| error.is_a?(klass) }
+      end
+
+      # Seconds to wait before the next attempt.
+      #
+      # A parseable `Retry-After` / `Retry-After-Ms` wins (already clamped to `[0, 60]` by
+      # {Dinie.parse_retry_after}). Otherwise: exponential backoff `min(0.5 · 2^attempt, 8) s`
+      # minus up to 25% subtractive jitter via `rand` (assert the band in specs, not the value).
+      #
+      # @param attempt [Integer] zero-based attempt index just completed
+      # @param retry_after [String, Array<String>, nil] the response `Retry-After` header
+      # @param retry_after_ms [String, Array<String>, nil] the response `Retry-After-Ms` header
+      # @return [Float] seconds to sleep
+      def retry_delay(attempt, retry_after: nil, retry_after_ms: nil)
+        from_header = Dinie.parse_retry_after(retry_after, retry_after_ms: retry_after_ms)
+        return from_header unless from_header.nil?
+
+        base = [INITIAL_BACKOFF_SECONDS * (2**attempt), MAX_BACKOFF_SECONDS].min
+        base * (1 - (JITTER_RATIO * rand))
+      end
+    end
+  end
+end