nb_api_client 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef855607df4fa9e26f513dd0ead54a8110b30baf30af94d21f10a8b11de06b45
-  data.tar.gz: 9ddcd3bc22a1b7947fc74e0d789a498a5b252b980e0cefb92cf916afcdedb8af
+  metadata.gz: 03ba7132dde127d46367c5a7e9731862657586a3a16da516a951a108ab1b89ed
+  data.tar.gz: 4d6e1c174a2ff5a1efe821ab92cbad01902271a18bfdc6c87724c83d1e79ef43
 SHA512:
-  metadata.gz: 027ae83f574dcfdccdfd1c0b138bc37f731ac24b5d7c0321874d7846115e99ff5d506ff896abb566770889024520a59825578b5933c5a6489994a5229f9f6735
-  data.tar.gz: afe137de2bc248504c9a83f6b4e84e266de8f077556db836f8a6c3601636aa2aed094a912994479ebcf08ada7e694165c107ed886559df6c0b7916b61653857a
+  metadata.gz: 03efb68afa45a268187f5d464d6f46f049c8c206400da5d9effcfb26ffaa3f901cae7e3ec40505f6a267b27ca3c3e332c110ce074006dd34ee87ec37ec541fb7
+  data.tar.gz: 928da3e0894dc85da016d3a35e1cc8c75614e5a863119a9aef40d6ca54d01c158f4b163aecf75942f93c4cb017baa506981c6db4996b2446a8c4b13eb620b430

data/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+## [0.3.0] - 2026-07-16
+
+- `NbApiClient::RateLimiter` now enforces an exact sliding window via a Redis
+  Lua script (ZADD/ZREMRANGEBYSCORE/ZCARD on a sorted set) when
+  `configuration.cache_store` is Redis-backed and its client supports Lua
+  scripts (true for `ActiveSupport::Cache::RedisCacheStore`, or a raw
+  Redis/`ConnectionPool` passed in directly as `cache_store`). This is
+  detected automatically at runtime — no configuration change is needed. Every
+  other `cache_store` still falls back to the bucketed sliding-window-counter
+  approximation introduced in 0.2.0. `redis` is added as a development-only
+  dependency, used solely by the gem's own integration test.
+
 ## [0.2.0] - 2026-07-16
 
 - **Breaking:** Removed the `redis` and `connection_pool` gem dependencies, along with

data/README.md

@@ -5,7 +5,7 @@ A rate-limited, token-refreshing HTTP client for the NationBuilder API, for use
 It provides two pieces:
 
 - `NbApiClient::Request` — makes a single authenticated API call, transparently retrying on rate limits and refreshing expired OAuth tokens.
-- `NbApiClient::RateLimiter` — a sliding-window rate limiter, backed by your configured `cache_store` (defaults to `Rails.cache`), shared across every process/thread in your fleet, so you don't blow through NationBuilder's server-side rate limit when running many workers. If no `cache_store` is configured, rate limiting is disabled entirely.
+- `NbApiClient::RateLimiter` — a sliding-window rate limiter, backed by your configured `cache_store` (defaults to `Rails.cache`), shared across every process/thread in your fleet, so you don't blow through NationBuilder's server-side rate limit when running many workers. If no `cache_store` is configured, rate limiting is disabled entirely. If `cache_store` is Redis-backed and its client supports Lua scripts, an exact sliding window is enforced atomically via a Lua script; otherwise a bucketed sliding-window-counter approximation is used, so any `ActiveSupport::Cache::Store` works.
 
 ## Installation
 
@@ -24,22 +24,22 @@ gem "nb_api_client", path: "gems/nb_api_client"
 ## Usage
 
 ```ruby
-NbApiClient::Request.call(nation, :get, "/api/v2/people/123")
-NbApiClient::Request.call(nation, :post, "/api/v2/people", {person: {email: "a@b.com"}})
+NbApiClient::Request.call(nation, :get, "/api/v2/signups/123")
+NbApiClient::Request.call(nation, :post, "/api/v2/signups", "data": {"type": "signups", "attributes": {{"email": "email@example.com"}}})
 ```
 
 ### The `nation` interface
 
 `nation` can be any object — it does not need to be an ActiveRecord model — that responds to:
 
-| Method | Returns |
-| --- | --- |
-| `slug` | A string uniquely identifying the account (used as a cache-key/log prefix). |
-| `active?` | Whether requests should be allowed (checked before every call, except `/oauth/token`). |
-| `url` | The base URL for the account, e.g. `"https://myorg.nationbuilder.com"`. |
-| `token` | The current OAuth access token, appended as a query param on every request. |
-| `refresh_oauth_token` | Refreshes the OAuth token in place; returns truthy on success, falsy on failure. |
-| `deauthorize` | Called after too many consecutive "unauthorized" responses (see `unauthorized_error_threshold` below). |
+| Method                | Returns                                                                                                |
+| --------------------- | ------------------------------------------------------------------------------------------------------ |
+| `slug`                | A string uniquely identifying the account (used as a cache-key/log prefix).                            |
+| `active?`             | Whether requests should be allowed (checked before every call, except `/oauth/token`).                 |
+| `url`                 | The base URL for the account, e.g. `"https://myorg.nationbuilder.com"`.                                |
+| `token`               | The current OAuth access token, appended as a query param on every request.                            |
+| `refresh_oauth_token` | Refreshes the OAuth token in place; returns truthy on success, falsy on failure.                       |
+| `deauthorize`         | Called after too many consecutive "unauthorized" responses (see `unauthorized_error_threshold` below). |
 
 ### Configuration
 
@@ -71,7 +71,11 @@ NbApiClient.configure do |config|
   config.short_circuit_in_test = true
 
   # Sliding-window rate limit enforced via `cache_store` across every process.
-  # Disabled entirely if `cache_store` is nil.
+  # Disabled entirely if `cache_store` is nil. If `cache_store` is Redis-backed
+  # (e.g. Rails.cache is an ActiveSupport::Cache::RedisCacheStore, or you set
+  # cache_store to a raw Redis/ConnectionPool) and its client supports Lua
+  # scripts, this is enforced as an exact sliding window via a Lua script
+  # instead of the bucketed approximation used for other cache stores.
   config.rate_limit = 200               # requests
   config.rate_limit_window_seconds = 10 # per this many seconds
   config.rate_limit_max_wait_seconds = 120
@@ -80,6 +84,22 @@ end
 
 All of the above have working defaults (matching NationBuilder's published limits with a safety margin), so a new app can start with zero configuration beyond `on_repeated_unauthorized`.
 
+### Responses
+
+On success, `NbApiClient::Request.call` returns the raw [`HTTParty::Response`](https://www.rubydoc.info/gems/httparty/HTTParty/Response) object from the underlying call — it is not parsed or unwrapped for you. Useful methods on it include:
+
+| Method                                                                                 | Returns                                                              |
+| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `parsed_response`                                                                        | The JSON body parsed into a `Hash`/`Array`.                          |
+| `code`                                                                                   | The HTTP status code, as an integer.                                 |
+| `headers`                                                                                | An [`HTTParty::Response::Headers`](https://www.rubydoc.info/gems/httparty/HTTParty/Response/Headers) (delegates to `Net::HTTPHeader`). |
+| `body`                                                                                   | The raw response body, as a string.                                  |
+| `success?`                                                                               | Whether the response was a 2xx.                                      |
+
+`HTTParty::Response` also delegates most `Hash`/`Array` methods (`[]`, `fetch`, `each`, …) straight to `parsed_response`, so e.g. `response["data"]` or `response.fetch("code", "")` works directly on the response without calling `parsed_response` first. See the [HTTParty README](https://github.com/jnunemaker/httparty#readme) for the full API.
+
+Under `Rails.env.test?` (with the default `short_circuit_in_test`, see below), `call` returns a plain `{}` instead of a real response.
+
 ### Error handling
 
 `NbApiClient::Request.call` raises:
@@ -99,6 +119,8 @@ bundle install
 bundle exec rake test
 ```
 
+The Lua-script integration test in `rate_limiter_test.rb` is skipped automatically if no Redis is reachable at `REDIS_URL` (defaults to `redis://localhost:6379/0`).
+
 ## Releasing a new version
 
 1. Bump `NbApiClient::VERSION` in `lib/nb_api_client/version.rb` and add an entry to `CHANGELOG.md`.

data/lib/nb_api_client/rate_limiter.rb

@@ -3,19 +3,55 @@
 module NbApiClient
   # A global (cross-process, cross-thread) distributed rate limiter backed by
   # configuration.cache_store (the same store used for unauthorized-response
-  # tracking; defaults to Rails.cache). Implements a "sliding window counter"
-  # algorithm: each window is divided into fixed buckets, and the previous
-  # bucket's count is weighted by how much of it still overlaps the sliding
-  # window. This approximates a true sliding window without requiring
-  # sorted-set support, so it works with any ActiveSupport::Cache::Store
-  # (memory, Redis, Memcached, ...). All callers share one window (configure
+  # tracking; defaults to Rails.cache). All callers share one window (configure
   # via NbApiClient.configure).
   #
+  # If cache_store is Redis-backed and its underlying client supports Lua
+  # scripts (i.e. responds to #eval — true for ActiveSupport::Cache::RedisCacheStore
+  # and for a bare Redis/ConnectionPool passed in directly), a true sliding
+  # window is enforced atomically via a Lua script (ZADD/ZREMRANGEBYSCORE/ZCARD
+  # on a sorted set).
+  #
+  # Otherwise, a "sliding window counter" algorithm is used instead: each window
+  # is divided into fixed buckets, and the previous bucket's count is weighted
+  # by how much of it still overlaps the sliding window. This approximates a
+  # true sliding window without requiring sorted-set support, so it works with
+  # any ActiveSupport::Cache::Store (memory, Memcached, ...).
+  #
   # If no cache_store is configured, rate limiting is disabled entirely (every
   # request is allowed through immediately).
   class RateLimiter
     class RateLimitExhausted < StandardError; end
 
+    # 1. Remove all entries older than (now - window) to slide the window
+    # 2. Count remaining entries in the set
+    # 3. If under the limit, add a new entry (scored by timestamp) and return the new count
+    # 4. If at/over the limit, return -1 (rejected)
+    #
+    # The sorted set key is given a TTL of 2*window as a safety net to avoid
+    # unbounded memory growth if traffic stops entirely.
+    ACQUIRE_SLOT_SCRIPT = <<~LUA
+      local key = KEYS[1]
+      local limit = tonumber(ARGV[1])
+      local window = tonumber(ARGV[2])
+      local now = tonumber(ARGV[3])
+      local member = ARGV[4]
+
+      -- Prune entries outside the sliding window
+      redis.call('ZREMRANGEBYSCORE', key, '-inf', now - window)
+
+      local count = redis.call('ZCARD', key)
+
+      if count < limit then
+        redis.call('ZADD', key, now, member)
+        -- Safety-net expiry so the key doesn't live forever if traffic stops
+        redis.call('EXPIRE', key, window * 2)
+        return count + 1
+      else
+        return -1
+      end
+    LUA
+
     # Blocks until a request slot is available, then yields to the caller.
     # Raises RateLimitExhausted if the wait exceeds configuration.rate_limit_max_wait_seconds.
     def self.with_limit(&block)
@@ -57,13 +93,29 @@ module NbApiClient
     private
 
     # Attempts to acquire a slot in the sliding window.
-    # Returns the new (weighted) count (positive) on success, or -1 if the window is full.
+    # Returns the new count (positive) on success, or -1 if the window is full.
     # Always succeeds (returns 1) if no cache_store is configured, i.e. rate limiting is disabled.
     def try_acquire_slot
       config = NbApiClient.configuration
       store = config.cache_store
       return 1 unless store
 
+      redis = redis_client(store)
+      redis ? try_acquire_slot_via_lua(redis, config) : try_acquire_slot_via_cache_store(store, config)
+    end
+
+    def try_acquire_slot_via_lua(redis, config)
+      now = Process.clock_gettime(Process::CLOCK_REALTIME)
+      member = "#{now}:#{SecureRandom.hex(4)}"
+      argv = [config.rate_limit.to_s, config.rate_limit_window_seconds.to_s, now.to_s, member]
+
+      run = ->(conn) { conn.eval(ACQUIRE_SLOT_SCRIPT, keys: [@key], argv: argv) }
+      redis.respond_to?(:with) ? redis.with(&run) : run.call(redis)
+    end
+
+    # Approximates a sliding window via fixed buckets, weighting the previous
+    # bucket's count by how much of it still overlaps the sliding window.
+    def try_acquire_slot_via_cache_store(store, config)
       window = config.rate_limit_window_seconds
       now = Process.clock_gettime(Process::CLOCK_REALTIME)
       current_bucket = (now / window).floor
@@ -85,5 +137,29 @@ module NbApiClient
         -1
       end
     end
+
+    # Returns the Redis client (or ConnectionPool of them) backing `store`, if
+    # it -- or a checked-out connection from it -- supports Lua scripts (#eval).
+    # Covers ActiveSupport::Cache::RedisCacheStore (whose #redis may itself be a
+    # bare client or a ConnectionPool) as well as a bare Redis/ConnectionPool
+    # object passed in directly as cache_store. Returns nil otherwise, so the
+    # caller falls back to the generic cache_store algorithm. Memoized per
+    # RateLimiter instance since cache_store doesn't change mid-request.
+    def redis_client(store)
+      return @redis_client if defined?(@redis_client)
+
+      @redis_client = begin
+        candidate = store.respond_to?(:redis) ? store.redis : store
+        if candidate.nil?
+          nil
+        elsif candidate.respond_to?(:with)
+          candidate.with { |conn| conn.respond_to?(:eval) } ? candidate : nil
+        elsif candidate.respond_to?(:eval)
+          candidate
+        end
+      rescue StandardError
+        nil
+      end
+    end
   end
 end

data/lib/nb_api_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NbApiClient
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nb_api_client
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Alex Flint
@@ -94,6 +94,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
 description: Wraps NationBuilder API requests with OAuth token refresh, deauthorization
   handling, and a cache-store-backed sliding-window rate limiter shared across processes.
 email: