nb_api_client 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2082f32bdb205caf63485893abe3199b480329fde2079592e38ba4b53b37660d
-  data.tar.gz: 793459a2c5f1271be72812d91cbf8d251795c8dffa5d73edb4d0d68047ca62e8
+  metadata.gz: 03ba7132dde127d46367c5a7e9731862657586a3a16da516a951a108ab1b89ed
+  data.tar.gz: 4d6e1c174a2ff5a1efe821ab92cbad01902271a18bfdc6c87724c83d1e79ef43
 SHA512:
-  metadata.gz: efd0d26a0b2ac02fa0cd418b0ff27281fea5afa8122790d0ef36b83dc81216604d0395576b01207d4321de2cc39a446d03ee1b988ed1f5d18b85f79bbc5b26c2
-  data.tar.gz: d19ea9e67bb1689876e9d33d81c561ae452b59f41a5c736df151c4c7d90ef34a185a6b6c0602e1fcbfe496faf0fc90f15941fa99f4207c44112cf5c36c8cc3a8
+  metadata.gz: 03efb68afa45a268187f5d464d6f46f049c8c206400da5d9effcfb26ffaa3f901cae7e3ec40505f6a267b27ca3c3e332c110ce074006dd34ee87ec37ec541fb7
+  data.tar.gz: 928da3e0894dc85da016d3a35e1cc8c75614e5a863119a9aef40d6ca54d01c158f4b163aecf75942f93c4cb017baa506981c6db4996b2446a8c4b13eb620b430

data/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 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
+  `config.redis_url` and `config.rate_limit_pool_size`. `NbApiClient::RateLimiter` now
+  implements its sliding window (a bucketed sliding-window-counter algorithm) on top of
+  the existing `configuration.cache_store` (defaults to `Rails.cache`) instead of a
+  dedicated Redis connection pool and Lua script. Rate limiting is disabled entirely if
+  no `cache_store` is configured.
+
 ## [0.1.1] - 2026-07-16
 
 - Publish to rubygems.org instead of GitLab's RubyGems registry (which is

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 Redis-backed sliding-window rate limiter shared across every process/thread in your fleet, so you don't blow through NationBuilder's server-side rate limit when running many workers.
+- `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
 
@@ -57,8 +57,9 @@ NbApiClient.configure do |config|
   config.unauthorized_error_threshold = 25
   config.unauthorized_error_window = 5 * 60
 
-  # Cache store used to count those unauthorized responses. Defaults to
-  # Rails.cache; must respond to #increment(key, amount, options).
+  # Cache store used to count those unauthorized responses, and (below) to
+  # back the sliding-window rate limiter. Defaults to Rails.cache; must
+  # respond to #increment(key, amount, options), #decrement, and #read.
   config.cache_store = Rails.cache
 
   # Logger for rate-limit/retry warnings. Defaults to Rails.logger.
@@ -69,17 +70,36 @@ NbApiClient.configure do |config|
   # rather stub HTTP at a lower level (e.g. WebMock/VCR) in your test suite.
   config.short_circuit_in_test = true
 
-  # Sliding-window rate limit enforced via Redis across every process.
+  # Sliding-window rate limit enforced via `cache_store` across every process.
+  # 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
-  config.rate_limit_pool_size = 6        # Redis connection pool size
-  config.redis_url = ENV.fetch("REDIS_URL", "redis://localhost:6379/0")
 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,7 +119,7 @@ bundle install
 bundle exec rake test
 ```
 
-The two Lua-script integration tests in `rate_limiter_test.rb` are skipped automatically if no Redis is reachable at `REDIS_URL`.
+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
 

data/lib/nb_api_client/configuration.rb

@@ -31,14 +31,13 @@ module NbApiClient
     attr_accessor :max_token_retries
 
     # Sliding-window rate limit: at most `rate_limit` requests per `rate_limit_window_seconds`,
-    # enforced across all processes via Redis.
+    # enforced across all processes via `cache_store` (above). If `cache_store` is nil,
+    # rate limiting is disabled entirely.
     attr_accessor :rate_limit
     attr_accessor :rate_limit_window_seconds
     attr_accessor :rate_limit_max_wait_seconds
     attr_accessor :rate_limit_poll_interval
     attr_accessor :rate_limit_max_jitter
-    attr_accessor :rate_limit_pool_size
-    attr_accessor :redis_url
 
     def initialize
       @cache_store = (defined?(Rails) && Rails.respond_to?(:cache)) ? Rails.cache : nil
@@ -55,8 +54,6 @@ module NbApiClient
       @rate_limit_max_wait_seconds = ENV.fetch("API_RATE_MAX_WAIT_SECONDS", 120).to_i
       @rate_limit_poll_interval = 0.25
       @rate_limit_max_jitter = 0.25
-      @rate_limit_pool_size = ENV.fetch("RATE_LIMITER_POOL_SIZE", 6).to_i
-      @redis_url = ENV.fetch("REDIS_URL", "redis://localhost:6379/0")
     end
   end
 end

data/lib/nb_api_client/rate_limiter.rb

@@ -1,10 +1,25 @@
 # frozen_string_literal: true
 
 module NbApiClient
-  # A global (cross-process, cross-thread) distributed rate limiter backed by Redis.
-  # Implements a sliding-window algorithm in a Lua script (atomic ZADD/ZREMRANGEBYSCORE/ZCARD
-  # on a sorted set) to enforce "N requests per window" across every process sharing the
-  # same Redis. All callers share one window (configure via NbApiClient.configure).
+  # 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). 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
 
@@ -66,10 +81,12 @@ module NbApiClient
           waited += sleep_time
         end
       end
-    rescue ConnectionPool::TimeoutError, Redis::BaseError, RedisClient::Error => e
-      # Fail open: if Redis is unavailable, allow the request through.
+    rescue RateLimitExhausted
+      raise
+    rescue StandardError => e
+      # Fail open: if the cache store is unavailable, allow the request through.
       # NbApiClient::Request's 429 handling acts as a safety net.
-      config.logger&.warn("[NbApiClient::RateLimiter] Redis error, failing open: #{e.class} - #{e.message}")
+      config.logger&.warn("[NbApiClient::RateLimiter] cache store error, failing open: #{e.class} - #{e.message}")
       yield
     end
 
@@ -77,22 +94,72 @@ module NbApiClient
 
     # Attempts to acquire a slot in the sliding window.
     # 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
+      previous_bucket = current_bucket - 1
+      elapsed_in_current = now - (current_bucket * window)
+      previous_weight = [(window - elapsed_in_current) / window, 0.0].max
 
-      redis do |conn|
-        conn.eval(
-          ACQUIRE_SLOT_SCRIPT,
-          keys: [@key],
-          argv: [config.rate_limit.to_s, config.rate_limit_window_seconds.to_s, now.to_s, member]
-        )
+      # Safety-net expiry so bucket keys don't live forever if traffic stops.
+      current_count = store.increment("#{@key}:#{current_bucket}", 1, expires_in: window * 2)
+      previous_count = store.read("#{@key}:#{previous_bucket}") || 0
+
+      weighted_count = current_count + (previous_count * previous_weight)
+
+      if weighted_count <= config.rate_limit
+        weighted_count
+      else
+        # Undo the increment so this rejected attempt doesn't count against the window.
+        store.decrement("#{@key}:#{current_bucket}", 1)
+        -1
       end
     end
 
-    def redis(&block)
-      NbApiClient.connection_pool.with(&block)
+    # 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.1.0"
+  VERSION = "0.3.0"
 end

data/lib/nb_api_client.rb

@@ -10,8 +10,6 @@ require "active_support/core_ext/object/inclusion"
 require "httparty"
 require "addressable/uri"
 require "oauth2"
-require "redis"
-require "connection_pool"
 
 require_relative "nb_api_client/version"
 require_relative "nb_api_client/configuration"
@@ -28,14 +26,5 @@ module NbApiClient
     def configure
       yield(configuration)
     end
-
-    # Lazily built so it always reflects the redis_url/pool_size in effect the
-    # first time a request needs it (i.e. after any NbApiClient.configure block
-    # has run).
-    def connection_pool
-      @connection_pool ||= ConnectionPool.new(size: configuration.rate_limit_pool_size, timeout: 3) {
-        Redis.new(url: configuration.redis_url)
-      }
-    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nb_api_client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Alex Flint
@@ -67,63 +67,49 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.0'
 - !ruby/object:Gem::Dependency
-  name: redis
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '5.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '5.0'
-- !ruby/object:Gem::Dependency
-  name: connection_pool
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
-  type: :runtime
+        version: '13.0'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '5.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '5.0'
 - !ruby/object:Gem::Dependency
-  name: minitest
+  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 Redis-backed sliding-window rate limiter shared across processes.
+  handling, and a cache-store-backed sliding-window rate limiter shared across processes.
 email:
 executables: []
 extensions: []