toc_doc 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a839823e2a82c7dd112617d6b969f275d7d88826e58f53b9ec9a5265701f277e
-  data.tar.gz: 6a3c3d24b598f0d2f85b2c0bd5f8faad939eeba847578692b072f0070fb5d3bb
+  metadata.gz: 36c32de39cc1eed0396372360e37b86d7df01e342926c32ab03aa450db500ff9
+  data.tar.gz: 578e0b0c633708c5c8adc7f3e8b0212e563ca7eb07c9e7b73b52d72196b7f652
 SHA512:
-  metadata.gz: 2580cf022a39c4f8e8d73c3b795927bf249ed3d4c9e6b36d051d326680d071ec4569e6f8da07143270584c7f65519f9df9c9efe824c7b623959d7be73f10f27f
-  data.tar.gz: 19ab224e5729cb04789e7739d1c0a6d9de16b02b2e32d850c1bc6fe3024c58b2c01d4ac9c1b7ffbfed45fb2d7e3498c537d169f9c77733b54d01da009b692047
+  metadata.gz: b120c55bf6b52c77b78c609867385150647fb0163d32abd449da8a53a4851939f0053caa3983784b80826be6bf4a6097da7084b0580f1d30d63a6066c5c61c7e
+  data.tar.gz: b463ad3fbc58cbd14101e5d8c1bffa37bacfda4373fd7a5c821ae2666d9b0ce839506e5ca97a2926389398387e900e26aac5cc977e036162d55e497d46de27d1

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [1.8.0] - 2026-04-05
+
+### Added
+
+- **`TocDoc::RateLimiter::TokenBucket`** — new thread-safe token-bucket rate limiter using a monotonic clock; tokens are refilled at a fixed `rate` per `interval`; `#acquire` blocks until a token is available; rate values below 1 are clamped with a warning
+- **`TocDoc::Middleware::RateLimiter`** — new Faraday middleware that enforces client-side rate limiting via a `TokenBucket`; inserted between the retry and JSON middleware so each retry attempt is individually rate-limited; enabled via the new `rate_limit` config key (accepts a `Numeric` for requests-per-second, a `Hash` of `TokenBucket` kwargs, or `nil` to disable)
+- **`TocDoc::Cache::MemoryStore`** — new thread-safe, in-memory response cache with per-entry TTL; lazy expiration (eviction happens on `#read`, not via a background sweep); compatible with the `ActiveSupport::Cache::Store` interface (`read`, `write`, `delete`, `clear`)
+- **`TocDoc::Middleware::Cache`** — new Faraday middleware that caches successful GET responses; cache hits bypass all downstream middleware; cache key is built from the full URL with query parameters sorted for determinism; only GET 200 responses are cached; enabled via the new `cache` config key (`:memory` for a default `MemoryStore`, a `Hash` with `:store`/`:ttl` keys, any AS-compatible store object, or `nil` to disable)
+- **`pagination_depth` config key** — new module-level and per-client option controlling how many `next_slot` hops `Availability.where` follows automatically; defaults to `1`; configurable via the `TOCDOC_PAGINATION_DEPTH` environment variable; negative values are clamped to 0 with a warning; `Default::PAGINATION_DEPTH` constant added
+- **`TocDoc::Availability::Collection#more?`** — returns `true` when the API response indicates further pages exist (`next_slot` present)
+- **`TocDoc::Availability::Collection#fetch_next_page`** — fetches the next page of availabilities and merges it into the collection; raises `StopIteration` when `#more?` is false; raises `TocDoc::Error` when no client was provided at construction time
+
+### Changed
+
+- **`TocDoc::Default#build_middleware`** — now accepts `rate_limit:` and `cache:` keyword arguments and injects the corresponding middleware into the Faraday stack; stack order is now: `RaiseError > [Cache] > [Logging] > Retry > [RateLimiter] > JSON > Adapter`
+- **`TocDoc::Default#options`** — now includes `pagination_depth:`, `rate_limit: nil`, and `cache: nil` in the defaults hash
+- **`TocDoc::Availability.where`** — now respects `pagination_depth` by following up to that many `next_slot` hops before returning; the constructed `Collection` now carries the client instance to enable `#fetch_next_page`
+
 ## [1.7.0] - 2026-04-04
 
 ### Added

data/README.md

@@ -140,12 +140,15 @@ client.get('/availabilities.json', query: { visit_motive_ids: '123', agenda_ids:
 | Option | Default | Description |
 |---|---|---|
 | `api_endpoint` | `https://www.doctolib.fr` | Base URL. Change to `.de` / `.it` for other countries. |
-| `user_agent` | `TocDoc Ruby Gem 1.7.0` | `User-Agent` header sent with every request. |
+| `user_agent` | `TocDoc Ruby Gem 1.8.0` | `User-Agent` header sent with every request. |
 | `default_media_type` | `application/json` | `Accept` and `Content-Type` headers. |
 | `per_page` | `15` | Default number of availability dates per request (capped at `15`). Emits a warning if the value exceeds the cap. |
 | `connect_timeout` | `5` | TCP connect timeout in seconds, passed to Faraday as `open_timeout`. Override via `TOCDOC_CONNECT_TIMEOUT`. |
 | `read_timeout` | `10` | Response read timeout in seconds, passed to Faraday as `timeout`. Override via `TOCDOC_READ_TIMEOUT`. |
 | `logger` | `nil` | Logger-compatible object (e.g. `Logger.new($stdout)`). When set, `TocDoc::Middleware::Logging` logs each request URL and response status. `nil` disables logging. |
+| `pagination_depth` | `1` | Number of `next_slot` hops `Availability.where` follows automatically. `0` disables automatic pagination. Override via `TOCDOC_PAGINATION_DEPTH`. Negative values are clamped to `0` with a warning. |
+| `rate_limit` | `nil` | Client-side rate limit. Pass a `Numeric` for requests-per-second (e.g. `5`), a `Hash` of `TokenBucket` kwargs (e.g. `{ rate: 5, interval: 2.0 }`), or `nil` to disable. Values below `1` are clamped. |
+| `cache` | `nil` | Response cache for GET requests. `:memory` uses a built-in `MemoryStore` (TTL 300s); a `Hash` with `:store` and `:ttl` keys accepts any AS-compatible store; `nil` disables caching. |
 | `middleware` | Retry + RaiseError + JSON + adapter | Full Faraday middleware stack. Override to customise completely. |
 | `connection_options` | `{}` | Options passed directly to `Faraday.new`. |
 
@@ -162,6 +165,7 @@ All primary options can be set via environment variables before the gem is loade
 | `TOCDOC_CONNECT_TIMEOUT` | `connect_timeout` (default `5`) |
 | `TOCDOC_READ_TIMEOUT` | `read_timeout` (default `10`) |
 | `TOCDOC_RETRY_MAX` | Maximum Faraday retry attempts (default `3`) |
+| `TOCDOC_PAGINATION_DEPTH` | `pagination_depth` (default `1`) |
 
 ---
 
@@ -304,6 +308,8 @@ Implements `Enumerable`, yielding `TocDoc::Availability` instances that have at
 | `#next_slot` | `String \| nil` | ISO 8601 datetime of the nearest available slot. `nil` when none remain. |
 | `#each` | — | Yields each `TocDoc::Availability` that has at least one slot (excludes empty-slot dates). |
 | `#raw_availabilities` | `Array<TocDoc::Availability>` | All date entries, including those with no slots. |
+| `#more?` | `Boolean` | `true` when the API has indicated further pages exist (`next_slot` is present). |
+| `#fetch_next_page` | `self` | Fetches the next page and merges it into this collection. Raises `StopIteration` when `#more?` is `false`. Requires a client (i.e. built via `Availability.where`). |
 | `#to_h` | `Hash` | Plain-hash representation (only dates with slots in the `availabilities` key). |
 
 ### `TocDoc::Availability`
@@ -447,15 +453,40 @@ The Doctolib availability endpoint is window-based: each request returns up to
 
 ### Automatic next-slot resolution
 
-`TocDoc::Availability.where` automatically follows `next_slot` once: if the
-first API response contains a `next_slot` key (indicating no available slots in
-the requested window), a second request is issued transparently from that date
-before the collection is returned.
+`TocDoc::Availability.where` automatically follows `next_slot` up to
+`pagination_depth` times (default: `1`). Each hop issues a follow-up request
+from the `next_slot` date returned by the previous response, transparently
+merging the pages before returning the collection. Set `pagination_depth: 0` to
+disable automatic pagination entirely.
+
+```ruby
+TocDoc.configure { |c| c.pagination_depth = 3 }
+# → up to 3 next_slot hops per Availability.where call
+```
+
+### On-demand pagination with `#fetch_next_page`
+
+After the initial call, check `#more?` and call `#fetch_next_page` to load
+additional pages one at a time:
+
+```ruby
+collection = TocDoc::Availability.where(
+  visit_motive_ids: 7_767_829,
+  agenda_ids:       1_101_600,
+  start_date:       Date.today
+)
+
+while collection.more?
+  collection.fetch_next_page
+end
+
+collection.total  # slots across all fetched pages
+```
 
 ### Manual window advancement
 
-To fetch additional date windows, call `TocDoc::Availability.where` again with a
-later `start_date`:
+To fetch a completely independent next window, call `TocDoc::Availability.where`
+again with a later `start_date`:
 
 ```ruby
 first_page = TocDoc::Availability.where(

data/TODO.md

@@ -3,12 +3,6 @@
 [POTENTIAL_ENDPOINTS][POTENTIAL_ENDPOINTS.md]
 
 
-## 1.8 — HTTP Layer Robustness
-
-- [ ] Configurable availability pagination depth + `Collection#more?` / `#fetch_next_page`
-- [ ] Client-side rate limiter (token-bucket middleware)
-- [ ] Optional response caching (memory or ActiveSupport-compatible store)
-
 ## 1.9 — Service Layer rework
 
 - [ ] `TocDoc::Services::Availabilities` — extract from `Availability.where`
@@ -33,6 +27,12 @@
 
 # DONE & RELEASED
 
+## 1.8
+
+- [x] Configurable availability pagination depth + `Collection#more?` / `#fetch_next_page`
+- [x] Client-side rate limiter (token-bucket middleware)
+- [x] Optional response caching (memory or ActiveSupport-compatible store)
+
 ## 1.7
 
 - [x] Logging middleware (`:logger` config key)

data/lib/toc_doc/cache/memory_store.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'monitor'
+
+module TocDoc
+  module Cache
+    # A thread-safe, in-memory response cache with per-entry TTL.
+    #
+    # Uses lazy expiration: expired entries are evicted on +#read+, not via a
+    # background sweep.  The key space is bounded by the number of distinct API
+    # URLs, so the overhead is negligible for typical gem usage.
+    #
+    # Compatible with the ActiveSupport::Cache::Store interface for the methods
+    # it implements (+read+, +write+, +delete+, +clear+).
+    #
+    # @example
+    #   store = TocDoc::Cache::MemoryStore.new(default_ttl: 60)
+    #   store.write('key', 'value', expires_in: 30)
+    #   store.read('key')   #=> 'value'
+    class MemoryStore
+      # @param default_ttl [Numeric] default TTL in seconds (default: 300)
+      def initialize(default_ttl: 300)
+        @default_ttl = default_ttl
+        @store = {}
+        @monitor = Monitor.new
+      end
+
+      # Reads the value stored under +key+.
+      #
+      # Returns +nil+ when the key is absent or has expired (and evicts the
+      # entry in the latter case).
+      #
+      # @param key [String]
+      # @return [Object, nil]
+      def read(key)
+        @monitor.synchronize do
+          entry = @store[key]
+          return nil unless entry
+
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) > entry[:expires_at]
+            @store.delete(key)
+            return nil
+          end
+
+          entry[:value]
+        end
+      end
+
+      # Stores +value+ under +key+ with the given TTL.
+      #
+      # @param key [String]
+      # @param value [Object]
+      # @param expires_in [Numeric] TTL in seconds; falls back to +default_ttl+
+      # @return [Object] the stored value
+      def write(key, value, expires_in: @default_ttl)
+        @monitor.synchronize do
+          @store[key] = {
+            value: value,
+            expires_at: Process.clock_gettime(Process::CLOCK_MONOTONIC) + expires_in
+          }
+          value
+        end
+      end
+
+      # Deletes the entry for +key+.
+      #
+      # @param key [String]
+      # @return [void]
+      def delete(key)
+        @monitor.synchronize { @store.delete(key) }
+      end
+
+      # Removes all entries from the store.
+      #
+      # @return [void]
+      def clear
+        @monitor.synchronize { @store.clear }
+      end
+    end
+  end
+end

data/lib/toc_doc/core/configurable.rb

@@ -32,6 +32,9 @@ module TocDoc
       connect_timeout
       read_timeout
       logger
+      pagination_depth
+      rate_limit
+      cache
     ].freeze
 
     # @!attribute [rw] api_endpoint
@@ -50,6 +53,12 @@ module TocDoc
     #   @return [Integer] read (response) timeout in seconds
     # @!attribute [rw] logger
     #   @return [Logger, :stdout, nil] logger for HTTP request logging; +nil+ disables logging
+    # @!attribute [rw] pagination_depth
+    #   @return [Integer] number of +next_slot+ hops to follow automatically (0 disables)
+    # @!attribute [rw] rate_limit
+    #   @return [Numeric, Hash, nil] client-side rate limit config; +nil+ disables
+    # @!attribute [rw] cache
+    #   @return [Symbol, Hash, Object, nil] response cache config; +nil+ disables
     attr_accessor(*VALID_CONFIG_KEYS)
 
     # Set the number of results per page, clamped to
@@ -68,6 +77,23 @@ module TocDoc
       @per_page = [int, TocDoc::Default::MAX_PER_PAGE].min
     end
 
+    # Set the number of +next_slot+ hops to follow automatically, clamped to 0
+    # when a negative value is given.
+    #
+    # Emits a warning on +$stderr+ when +value+ is negative so callers are not
+    # silently surprised.
+    #
+    # @param value [Integer, #to_i] desired pagination depth
+    # @return [Integer] the effective depth after clamping
+    def pagination_depth=(value)
+      int = value.to_i
+      if int.negative?
+        warn "[TocDoc] pagination_depth #{int} is negative; clamped to 0."
+        int = 0
+      end
+      @pagination_depth = int
+    end
+
     # Returns the list of recognised configurable attribute names.
     #
     # @return [Array<Symbol>]

data/lib/toc_doc/core/connection.rb

@@ -99,15 +99,15 @@ module TocDoc
 
     # Returns the appropriate middleware stack for this client.
     #
-    # When a logger is configured, builds a fresh stack with the logger injected
-    # so that the shared memoized default stack is never mutated.
-    # Falls back to the memoized {TocDoc::Default.middleware} when no logger is
-    # set.
+    # When a logger, rate limiter, or cache is configured, builds a fresh stack
+    # with those features injected so the shared memoized default stack is never
+    # mutated.  Falls back to the memoized {TocDoc::Default.middleware} when
+    # none of those options are set.
     #
     # @return [Faraday::RackBuilder]
     def effective_middleware
-      if logger
-        TocDoc::Default.build_middleware(logger: logger)
+      if logger || rate_limit || cache
+        TocDoc::Default.build_middleware(logger: logger, rate_limit: rate_limit, cache: cache)
       else
         middleware
       end

data/lib/toc_doc/core/default.rb

@@ -5,6 +5,10 @@ require 'faraday/retry'
 
 require 'toc_doc/http/middleware/raise_error'
 require 'toc_doc/http/middleware/logging'
+require 'toc_doc/http/middleware/rate_limiter'
+require 'toc_doc/http/middleware/cache'
+require 'toc_doc/http/rate_limiter/token_bucket'
+require 'toc_doc/cache/memory_store'
 
 module TocDoc
   # Provides sensible default values for every configurable option.
@@ -26,6 +30,9 @@ module TocDoc
     # @return [Integer] the default number of results per page
     PER_PAGE       = 15
 
+    # @return [Integer] the default number of +next_slot+ hops to follow
+    PAGINATION_DEPTH = 1
+
     # @return [Integer] the hard upper limit for per_page
     MAX_PER_PAGE   = 15
 
@@ -46,7 +53,7 @@ module TocDoc
       def options
         { api_endpoint:, user_agent:, default_media_type:, per_page:,
           middleware:, connection_options:, connect_timeout:, read_timeout:,
-          logger: nil }
+          logger: nil, pagination_depth:, rate_limit: nil, cache: nil }
       end
 
       # The base API endpoint URL.
@@ -91,6 +98,19 @@ module TocDoc
         PER_PAGE
       end
 
+      # Number of +next_slot+ hops to follow automatically.
+      #
+      # Falls back to the `TOCDOC_PAGINATION_DEPTH` environment variable, then
+      # {PAGINATION_DEPTH}.  Negative ENV values are clamped to 0.
+      #
+      # @return [Integer]
+      def pagination_depth
+        depth = Integer(ENV.fetch('TOCDOC_PAGINATION_DEPTH', PAGINATION_DEPTH), 10)
+        [depth, 0].max
+      rescue ArgumentError
+        PAGINATION_DEPTH
+      end
+
       # The default (memoized) Faraday middleware stack, built without a logger.
       #
       # Stack order (outermost first): RaiseError, retry, JSON parsing, adapter.
@@ -102,27 +122,21 @@ module TocDoc
         @middleware ||= build_middleware
       end
 
-      # Builds a Faraday middleware stack, optionally injecting a logger.
-      #
-      # When +logger+ is non-nil, {TocDoc::Middleware::Logging} is inserted
-      # between {TocDoc::Middleware::RaiseError} and the retry middleware so
-      # each logical request is logged exactly once after all retries are
-      # exhausted.
+      # Builds a Faraday middleware stack, optionally injecting a logger,
+      # rate limiter, and response cache.
       #
-      # Accepts +:stdout+ as a shorthand that writes to +$stdout+.
+      # Stack order (outermost first):
+      #   RaiseError > [Cache] > [Logging] > Retry > [RateLimiter] > JSON > Adapter
       #
-      # @param logger [Logger, :stdout, nil] the logger to inject; +nil+ omits
-      #   the logging middleware entirely
+      # @param logger [Logger, :stdout, nil] the logger to inject; +nil+ omits logging
+      # @param rate_limit [Numeric, Hash, nil] rate-limit config (see {.resolve_rate_limit})
+      # @param cache [Symbol, Hash, Object, nil] cache config (see {.resolve_cache})
       # @return [Faraday::RackBuilder]
-      def build_middleware(logger: nil)
-        resolved = resolve_logger(logger)
-        Faraday::RackBuilder.new do |builder|
-          builder.use TocDoc::Middleware::RaiseError
-          builder.use TocDoc::Middleware::Logging, logger: resolved if resolved
-          builder.request :retry, retry_options
-          builder.response :json, content_type: /\bjson$/
-          builder.adapter Faraday.default_adapter
-        end
+      def build_middleware(logger: nil, rate_limit: nil, cache: nil)
+        logger_obj   = resolve_logger(logger)
+        bucket       = resolve_rate_limit(rate_limit)
+        cache_config = resolve_cache(cache)
+        Faraday::RackBuilder.new { |b| apply_middleware(b, logger_obj, bucket, cache_config) }
       end
 
       # Default Faraday connection options (empty by default).
@@ -170,6 +184,22 @@ module TocDoc
 
       private
 
+      def apply_middleware(builder, logger, bucket, cache_config)
+        builder.use TocDoc::Middleware::RaiseError
+        insert_cache(builder, cache_config)
+        builder.use TocDoc::Middleware::Logging, logger: logger if logger
+        builder.request :retry, retry_options
+        builder.use TocDoc::Middleware::RateLimiter, bucket: bucket if bucket
+        builder.response :json, content_type: /\bjson$/
+        builder.adapter Faraday.default_adapter
+      end
+
+      def insert_cache(builder, cache_config)
+        return unless cache_config
+
+        builder.use TocDoc::Middleware::Cache, store: cache_config[:store], ttl: cache_config[:ttl]
+      end
+
       def resolve_logger(logger)
         case logger
         when :stdout
@@ -182,6 +212,32 @@ module TocDoc
         end
       end
 
+      def resolve_rate_limit(config)
+        case config
+        when nil, false
+          nil
+        when Numeric
+          TocDoc::RateLimiter::TokenBucket.new(rate: config, interval: 1.0)
+        when Hash
+          TocDoc::RateLimiter::TokenBucket.new(**config)
+        end
+      end
+
+      def resolve_cache(config)
+        case config
+        when nil, false then nil
+        when :memory    then { store: TocDoc::Cache::MemoryStore.new, ttl: 300 }
+        when Hash       then resolve_cache_hash(config)
+        else            { store: config, ttl: 300 }
+        end
+      end
+
+      def resolve_cache_hash(config)
+        store = config[:store]
+        store = TocDoc::Cache::MemoryStore.new if store.nil? || store == :memory
+        { store: store, ttl: config.fetch(:ttl, 300) }
+      end
+
       def retry_options
         {
           max: retry_max,

data/lib/toc_doc/core/version.rb

@@ -4,5 +4,5 @@ module TocDoc
   # The current version of the TocDoc gem.
   #
   # @return [String]
-  VERSION = '1.7.0'
+  VERSION = '1.8.0'
 end

data/lib/toc_doc/http/middleware/cache.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'toc_doc/cache/memory_store'
+
+module TocDoc
+  module Middleware
+    # Faraday middleware that caches successful GET responses.
+    #
+    # Cache hits bypass all downstream middleware (retry, rate-limiting, JSON
+    # parsing, and the HTTP adapter).  The cached body is the already-parsed
+    # object returned by the JSON middleware on the original miss.
+    #
+    # Only GET requests with 200 responses are cached.  All other verbs and
+    # non-200 responses flow through normally.
+    #
+    # The cache key is built from the full URL with query parameters sorted for
+    # determinism.
+    #
+    # Stack position (outermost first): RaiseError > Cache > Logging > Retry >
+    # RateLimiter > JSON > Adapter
+    #
+    # @example
+    #   store = TocDoc::Cache::MemoryStore.new
+    #   builder.use TocDoc::Middleware::Cache, store: store, ttl: 300
+    class Cache < Faraday::Middleware
+      # @param app [#call] the next middleware in the stack
+      # @param store [#read, #write] a cache store (MemoryStore or AS-compatible)
+      # @param ttl [Numeric] TTL in seconds for cached responses (default: 300)
+      def initialize(app, store:, ttl: 300)
+        super(app)
+        @store = store
+        @ttl   = ttl
+      end
+
+      # Serves from cache on hit; fetches and caches on miss.
+      #
+      # @param env [Faraday::Env] the request environment
+      # @return [Faraday::Response]
+      def call(env)
+        return @app.call(env) unless env[:method] == :get
+
+        cache_key = build_key(env)
+        cached = @store.read(cache_key)
+        return cached_response(env, cached) if cached
+
+        @app.call(env).on_complete do |response_env|
+          next unless response_env.status == 200
+
+          @store.write(cache_key, response_env.body, expires_in: @ttl)
+        end
+      end
+
+      private
+
+      def build_key(env)
+        uri = env.url.dup
+        if uri.query
+          sorted_query = URI.decode_www_form(uri.query).sort.map { |k, v| "#{k}=#{v}" }.join('&')
+          uri.query = sorted_query
+        end
+        "tocdoc:get:#{uri}"
+      end
+
+      def cached_response(env, body)
+        env.status = 200
+        env.body   = body
+        Faraday::Response.new(env)
+      end
+    end
+  end
+end

data/lib/toc_doc/http/middleware/rate_limiter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'toc_doc/http/rate_limiter/token_bucket'
+
+module TocDoc
+  module Middleware
+    # Faraday middleware that enforces a client-side rate limit via a
+    # {TocDoc::RateLimiter::TokenBucket}.
+    #
+    # Placed between the retry middleware and the JSON middleware so each retry
+    # attempt is individually rate-limited.
+    #
+    # @example
+    #   bucket = TocDoc::RateLimiter::TokenBucket.new(rate: 5)
+    #   builder.use TocDoc::Middleware::RateLimiter, bucket: bucket
+    class RateLimiter < Faraday::Middleware
+      # @param app [#call] the next middleware in the stack
+      # @param bucket [TocDoc::RateLimiter::TokenBucket] the rate-limiting token bucket
+      def initialize(app, bucket:)
+        super(app)
+        @bucket = bucket
+      end
+
+      # Acquires a token before forwarding the request downstream.
+      #
+      # @param env [Faraday::Env] the request environment
+      # @return [Faraday::Response]
+      def call(env)
+        @bucket.acquire
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/toc_doc/http/rate_limiter/token_bucket.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module TocDoc
+  module RateLimiter
+    # A thread-safe token-bucket rate limiter using a monotonic clock.
+    #
+    # Tokens are refilled at a fixed rate; when the bucket is empty, {#acquire}
+    # sleeps until the next token is available.
+    #
+    # @example Allow 5 requests per second
+    #   bucket = TocDoc::RateLimiter::TokenBucket.new(rate: 5)
+    #   bucket.acquire  # returns immediately while tokens remain
+    #
+    # @example 2 requests per 2 seconds
+    #   bucket = TocDoc::RateLimiter::TokenBucket.new(rate: 2, interval: 2.0)
+    class TokenBucket
+      MIN_RATE = 1.0
+
+      # @param rate [Numeric] maximum burst capacity and refill amount per +interval+;
+      #   clamped to a minimum of +1+
+      # @param interval [Float] refill period in seconds (default: 1.0)
+      def initialize(rate:, interval: 1.0)
+        raw = rate.to_f
+        if raw < MIN_RATE
+          warn "[TocDoc] rate_limit #{raw} is below minimum; clamped to #{MIN_RATE}."
+          raw = MIN_RATE
+        end
+        @rate     = raw
+        @interval = interval.to_f
+        @tokens   = @rate
+        @last_refill = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @mutex = Mutex.new
+      end
+
+      # Blocks until a token is available, then consumes it.
+      #
+      # The mutex is released while sleeping so other threads can proceed
+      # concurrently.
+      #
+      # @return [void]
+      def acquire
+        @mutex.synchronize do
+          refill
+          while @tokens < 1
+            sleep_time = @interval / @rate
+            @mutex.sleep(sleep_time)
+            refill
+          end
+          @tokens -= 1
+        end
+      end
+
+      private
+
+      def refill
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        elapsed = now - @last_refill
+        @tokens = [@tokens + ((elapsed / @interval) * @rate), @rate].min
+        @last_refill = now
+      end
+    end
+  end
+end

data/lib/toc_doc/models/availability/collection.rb

@@ -23,10 +23,13 @@ module TocDoc
       # @param data [Hash] parsed first-page response body
       # @param query [Hash] original query params (used to build next-page requests)
       # @param path [String] API path for subsequent requests
-      def initialize(data, query: {}, path: '/availabilities.json')
+      # @param client [TocDoc::Client, nil] client used to fetch additional pages
+      #   via {#fetch_next_page}; +nil+ disables {#fetch_next_page}
+      def initialize(data, query: {}, path: '/availabilities.json', client: nil)
         @data = data.dup
         @query = query
         @path = path
+        @client = client
       end
 
       # Iterates over {TocDoc::Availability} instances that have at least one slot.
@@ -62,6 +65,36 @@ module TocDoc
         nil
       end
 
+      # Returns +true+ when the API has indicated that more results exist beyond
+      # the currently loaded pages.
+      #
+      # @return [Boolean]
+      def more?
+        !!@data['next_slot']
+      end
+
+      # Fetches the next page of availabilities and merges it into this collection.
+      #
+      # Uses the +next_slot+ date from the API response as the +start_date+ for
+      # the follow-up request.
+      #
+      # @raise [TocDoc::Error] if no client was provided at construction time
+      # @raise [StopIteration] if {#more?} is +false+
+      # @return [self]
+      #
+      # @example
+      #   collection.fetch_next_page if collection.more?
+      def fetch_next_page
+        raise TocDoc::Error, 'No client available for pagination' unless @client
+        raise StopIteration, 'No more pages available' unless more?
+
+        next_date = Date.parse(@data['next_slot']).to_s
+        next_page = @client.get(@path, query: @query.merge(start_date: next_date))
+        @data.delete('next_slot')
+        @data['next_slot'] = next_page['next_slot'] if next_page.key?('next_slot')
+        merge_page!(next_page)
+      end
+
       # All date entries — including those with no slots — as {TocDoc::Availability}
       # objects.
       #

data/lib/toc_doc/models/availability.rb

@@ -55,12 +55,17 @@ module TocDoc
       def where(visit_motive_ids:, agenda_ids:, start_date: Date.today,
                 limit: TocDoc.per_page, **options)
         client = TocDoc.client
+        depth  = TocDoc.pagination_depth
         query  = build_query(visit_motive_ids, agenda_ids, start_date, limit, options)
         data   = client.get(PATH, query: query)
 
-        merge_next_page(client, query, data) if data['next_slot']
+        depth.times do
+          break unless data['next_slot']
 
-        Collection.new(data, query: query, path: PATH)
+          merge_next_page(client, query, data)
+        end
+
+        Collection.new(data, query: query, path: PATH, client: client)
       end
 
       private

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: toc_doc
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.0
 platform: ruby
 authors:
 - 01max
@@ -62,6 +62,7 @@ files:
 - Rakefile
 - TODO.md
 - lib/toc_doc.rb
+- lib/toc_doc/cache/memory_store.rb
 - lib/toc_doc/client.rb
 - lib/toc_doc/core/authentication.rb
 - lib/toc_doc/core/configurable.rb
@@ -70,8 +71,11 @@ files:
 - lib/toc_doc/core/error.rb
 - lib/toc_doc/core/uri_utils.rb
 - lib/toc_doc/core/version.rb
+- lib/toc_doc/http/middleware/cache.rb
 - lib/toc_doc/http/middleware/logging.rb
 - lib/toc_doc/http/middleware/raise_error.rb
+- lib/toc_doc/http/middleware/rate_limiter.rb
+- lib/toc_doc/http/rate_limiter/token_bucket.rb
 - lib/toc_doc/middleware/.keep
 - lib/toc_doc/models.rb
 - lib/toc_doc/models/agenda.rb