strongmind-platform-sdk 3.33.4 → 3.33.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80e27a2c045cd72bc8633ded3fc6505f5c2a029158bb67b120ed6b39b31c3438
-  data.tar.gz: 9941c3cde4236922d326beb90cfef6847568fb1b996eb55bc999f86217672385
+  metadata.gz: fe3ec6a94953018e636a9fc5bab7a7f66791db9d15aeed14035c1a444980f9a6
+  data.tar.gz: 678c3fc1a62d418838ab25d1fd8bafeea342a58a986bcd1a1ec3e5d6d087e6dc
 SHA512:
-  metadata.gz: d991813ce02b2207fc72c523930d4dbe827d05e644be07d6868caa562be89936ec71a305bf275c1c378571005775cbcf584784bb2fbc57a806ccc236e438caac
-  data.tar.gz: c29637d88a1e720243e39a556195e89836c1346d1fc2a0e0de2d5c88a0d286c1a5bdc8096fea2be727dd2b0777f4e4fb6d32c37a3130c8ccf3b0063fbaef5588
+  metadata.gz: 83d9ffbf4ee13769ae6ffb5d1346e8a37cbd6d1cfc511be1ef0d87a63863191bccc12b9a51cfdce4a4732ec70e9c35580018677e15aca638d3e9629cfc89cb37
+  data.tar.gz: 67bb2e2e837402cb15fdedab566a343111f17204795eafc1e149fa19976d53f277ab924f0d247877c76570996e18db6f125e444df27f162b05928342ce537570

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+- Bound `Client::DEFAULT_RETRY_OPTIONS` with `max_interval: 10`. faraday-retry defaults `max_interval` to `Float::MAX`, so a `Retry-After` header (Canvas doesn't send one today, but could) would otherwise block a single request for as long as that header said. Retries also now log a warning before each sleep via a default `retry_block`, so a sustained throttle shows up in logs rather than only as request latency; callers passing their own `retry_options: { retry_block: ... }` still override it.
+- Fix `Client#page_links` returning `{}` -- read as "no more pages" -- when the `Link` header is present but fails to parse, which silently truncated a listing to its first page instead of raising. Only a genuinely absent header is now treated as unpaginated; a present-but-malformed header raises `CanvasClientError`.
+- Fix the page-1 error branch of every listing/read/write method assuming a non-2xx Canvas response is JSON. Canvas's own throttle (`RequestThrottle`, Rack middleware ahead of the Rails app) returns a plain-text `429` body, which raised `MultiJson::ParseError` once retries were exhausted instead of the descriptive error each method is meant to raise. Extracted into `error_messages_from`, which falls back to the raw body when it isn't JSON, collapsing 27 duplicated copies of the same parsing block in the process. Nine of those methods (`put_relock_module`, `put_module_prerequesites`, `put_recompute_module_prerequisites`, `create_module`, `update_module`, `post_module_item`, `put_publish_module_item`, `delete_module_item`, `retrieve_discussion_topic`) additionally parsed the body *before* checking `success?`, so the `ParseError` fired ahead of the error branch entirely; they now parse only on success. The now-unused `parse_response_errors` helper is removed.
+- Fix `client.rb` raising `NameError: uninitialized constant Faraday::RetriableResponse` when required directly (e.g. `require "platform_sdk/canvas_api/client"`) rather than through `canvas_api.rb`. `faraday/retry`, which defines the constant `DEFAULT_RETRY_OPTIONS` references at load time, is now required alongside `faraday` in the file that uses it.
+- Fix `handle_rate_limiting` treating Canvas's `X-Rate-Limit-Remaining` as an integer via `to_i` truncation -- a fractional value like `"0.75"` (quota still available) was read as `0` and slept a second anyway. The header is now parsed as a float, so only a value at or below zero throttles.
+- Add the pre-emptive `handle_rate_limiting` check to `update_submission_excused_with_comment`, the one write endpoint that had been skipping it.
+- Add wire-level specs asserting `post_module_item` sends exactly one request under a `429` (POST is excluded from retry), that a form-encoded PUT body lands the way Canvas expects, and that a rate-limited later page actually retries (rather than merely raising) before giving up.
+- Fix `CanvasApiWrapper::Client` still raising `NoMethodError: undefined method 'split' for nil:NilClass` from `page_links` when Canvas throttles a page *after* the first. The `success?` fix above guards only the initial response of each request; `paginated_items` handed every subsequent page straight to `page_links`, which needs the `Link` header a `429` does not carry. Pages are now fetched through `fetch_page`, which status-checks each one and raises `CanvasClientError` with the response body instead.
+- Retry throttled Canvas requests instead of only failing more legibly. The connection installs `faraday-retry` with `retry_statuses: [429]`, 3 attempts and exponential backoff (1s, 2s, 4s, jittered), so a rate-limited call now recovers on its own rather than surfacing to the caller. Retries are scoped to Faraday's idempotent methods — POST is excluded, so a throttled `post_module_item` can never be replayed into a duplicate item. Defaults live in `Client::DEFAULT_RETRY_OPTIONS` and can be overridden per client with `Client.new(domain:, token:, retry_options: {...})`.
+- Fix `handle_rate_limiting` sleeping a second on every response that carries no `X-Rate-Limit-Remaining` header. `nil.to_i` is `0`, which the "bucket is spent" check could not tell apart from a genuinely exhausted quota, so the client throttled itself against responses Canvas had said nothing about. An absent header is now distinguished from a zero quota. (This was not merely theoretical: the Canvas client's own spec file spent 39s of its 40s runtime asleep, and now runs in 0.25s.)
+- The Canvas connection now declares `url_encoded` explicitly. Faraday installs it by default *only* when no block is given, and adding the retry middleware requires a block — several endpoints here assign a Hash to `req.body` for form-encoded Canvas APIs and depend on that middleware to serialize it.
+
 - Fix `CanvasApiWrapper::Client#success?` treating some non-2xx responses as successful. The check used an unanchored `/2[0-9]/` match, so `429` matched on its `"29"` substring and a rate-limited response took the success branch, then raised `NoMethodError: undefined method 'split' for nil:NilClass` in `page_links` — `429` responses carry no `Link` header. Now anchored to `(200..299)`, so these fall through to the error branch and raise a descriptive message. Also corrects `422` and the other `3xx`/`4xx`/`5xx` codes matching the same pattern.
 
 ## [3.33.0] - 2026-07-28

data/lib/platform_sdk/canvas_api/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "faraday"
+require "faraday/retry"
 require "platform_sdk/version"
 
 module PlatformSdk
@@ -11,18 +12,63 @@ module PlatformSdk
 
       PAGE_SIZE = 10
 
+      # Retries are scoped to Canvas's 429 throttle and nothing else.
+      #
+      # `retry_statuses` is implemented by raising the synthetic
+      # `Faraday::RetriableResponse`, so that class has to stay in
+      # `exceptions` for a 429 to be retried at all -- an empty list would
+      # let it escape to the caller instead. Naming it as the only entry is
+      # what drops faraday-retry's default `Errno::ETIMEDOUT`,
+      # `Timeout::Error` and `Faraday::TimeoutError`: a timed-out request may
+      # already have been applied by Canvas, and replaying it is not safe for
+      # every endpoint here. `update_submission_excused_with_comment` PUTs a
+      # `submission_comments` entry, which Canvas appends rather than
+      # replaces, so a replayed timeout would leave the student duplicate
+      # comments.
+      #
+      # `methods` restates faraday-retry's own IDEMPOTENT_METHODS so the
+      # exclusion is visible at the call site: POST is left out because a
+      # retry could re-create a module item. PUT is safe on the remaining 429
+      # path because Canvas rejects a throttled request before applying it,
+      # so the replay is the first time the write lands.
+      #
+      # The backoff is deliberately short: Canvas refills the rate-limit
+      # bucket continuously, so max: 3 with interval: 1 and
+      # backoff_factor: 2 spends about 1.0-1.5s, 2.0-2.5s and 4.0-4.5s (the
+      # randomness is additive, not a +/- percentage of the interval) before
+      # giving up -- that's 3 retries, 4 attempts total. Callers that need a
+      # different budget pass `retry_options:` to the constructor.
+      #
+      # `retry_statuses: [429]` assumes the hosted Canvas instance has
+      # `request_throttle.send_429_response` enabled; without it Canvas's
+      # `RequestThrottle` returns 403 instead, which won't retry and surfaces
+      # as `LockedModuleItemError` on the write endpoints below.
+      #
+      # `max_interval` bounds both the exponential backoff and a `Retry-After`
+      # header Canvas might one day send -- without it, a single throttled
+      # request could block for as long as that header says (faraday-retry
+      # defaults `max_interval` to `Float::MAX`).
+      DEFAULT_RETRY_OPTIONS = {
+        max: 3,
+        interval: 1,
+        interval_randomness: 0.5,
+        backoff_factor: 2,
+        max_interval: 10,
+        retry_statuses: [429],
+        exceptions: [Faraday::RetriableResponse],
+        methods: %i[delete get head options put]
+      }.freeze
+
       # @param domain [String]
       # @param token [String]
-      def initialize(domain:, token:)
+      # @param retry_options [Hash] overrides merged onto DEFAULT_RETRY_OPTIONS
+      def initialize(domain:, token:, retry_options: {})
         @host = "https://#{domain}"
         @token = token
-        @connection = Faraday.new(
-          url: host,
-          headers: {
-            'Authorization' => "Bearer #{token}",
-            'User-Agent' => "StrongMind-PlatformSDK/#{PlatformSdk::VERSION}"
-          }
-        )
+        @retry_options = DEFAULT_RETRY_OPTIONS
+                          .merge(retry_block: method(:log_rate_limit_retry))
+                          .merge(retry_options)
+        @connection = build_connection
       end
 
       # @param course_id [Integer]
@@ -33,12 +79,7 @@ module PlatformSdk
         if success?(response.status)
           paginated_items headers: response.headers, initial_response: response.body
         else
-          result = MultiJson.load response.body, symbolize_keys: true
-          error_messages = String.new
-          result[:errors].each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error getting course modules: #{error_messages}"
+          raise "Error getting course modules: #{error_messages_from(response.body)}"
         end
       end
 
@@ -48,12 +89,7 @@ module PlatformSdk
         if success?(response.status)
           paginated_items headers: response.headers, initial_response: response.body
         else
-          result = MultiJson.load response.body, symbolize_keys: true
-          error_messages = String.new
-          result[:errors].each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error getting course modules: #{error_messages}"
+          raise "Error getting course modules: #{error_messages_from(response.body)}"
         end
       end
 
@@ -66,12 +102,7 @@ module PlatformSdk
         if success?(response.status)
           paginated_items headers: response.headers, initial_response: response.body
         else
-          result = MultiJson.load response.body, symbolize_keys: true
-          error_messages = String.new
-          result[:errors].each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error getting module items: #{error_messages}"
+          raise "Error getting module items: #{error_messages_from(response.body)}"
         end
       end
 
@@ -86,12 +117,7 @@ module PlatformSdk
         if success?(response.status)
           paginated_items headers: response.headers, initial_response: response.body
         else
-          result = MultiJson.load response.body, symbolize_keys: true
-          error_messages = String.new
-          result[:errors].each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error getting module items: #{error_messages}"
+          raise "Error getting module items: #{error_messages_from(response.body)}"
         end
       end
 
@@ -105,12 +131,7 @@ module PlatformSdk
           assignments = paginated_items headers: response.headers, initial_response: response.body
           assignments.select { |item| item[:type] == 'Assignment' }
         else
-          result = MultiJson.load response.body, symbolize_keys: true
-          error_messages = String.new
-          result[:errors].each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error getting assignments: #{error_messages}"
+          raise "Error getting assignments: #{error_messages_from(response.body)}"
         end
       end
 
@@ -122,12 +143,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          result = MultiJson.load response.body, symbolize_keys: true
-          error_messages = String.new
-          result[:errors].each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error getting quiz submissions#{error_messages}"
+          raise "Error getting quiz submissions#{error_messages_from(response.body)}"
         end
       end
 
@@ -140,12 +156,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          result = MultiJson.load response.body, symbolize_keys: true
-          error_messages = String.new
-          result[:errors].each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error getting module item: #{error_messages}"
+          raise "Error getting module item: #{error_messages_from(response.body)}"
         end
       end
 
@@ -155,12 +166,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          result = MultiJson.load response.body, symbolize_keys: true
-          error_messages = String.new
-          result[:errors].each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error getting module item: #{error_messages}"
+          raise "Error getting module item: #{error_messages_from(response.body)}"
         end
       end
 
@@ -170,12 +176,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          result = MultiJson.load response.body, symbolize_keys: true
-          error_messages = String.new
-          result[:errors].each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error getting module item: #{error_messages}"
+          raise "Error getting module item: #{error_messages_from(response.body)}"
         end
       end
 
@@ -187,12 +188,7 @@ module PlatformSdk
         if success?(response.status)
           paginated_items headers: response.headers, initial_response: response.body
         else
-          result = MultiJson.load response.body, symbolize_keys: true
-          error_messages = String.new
-          result[:errors].each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error getting submissions: #{error_messages}"
+          raise "Error getting submissions: #{error_messages_from(response.body)}"
         end
       end
 
@@ -210,12 +206,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          result = MultiJson.load response.body, symbolize_keys: true
-          error_messages = String.new
-          result[:errors].each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error update submissions to excused: #{error_messages}"
+          raise "Error update submissions to excused: #{error_messages_from(response.body)}"
         end
       end
 
@@ -232,15 +223,11 @@ module PlatformSdk
             }
           }.to_json
         end
+        handle_rate_limiting response
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          result = MultiJson.load response.body, symbolize_keys: true
-          error_messages = String.new
-          result[:errors].each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error update submissions to excused: #{error_messages}"
+          raise "Error update submissions to excused: #{error_messages_from(response.body)}"
         end
       end
 
@@ -253,12 +240,7 @@ module PlatformSdk
         if success?(response.status)
           paginated_items headers: response.headers, initial_response: response.body
         else
-          result = MultiJson.load response.body, symbolize_keys: true
-          error_messages = String.new
-          result[:errors].each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error getting course students: #{error_messages}"
+          raise "Error getting course students: #{error_messages_from(response.body)}"
         end
       end
 
@@ -271,12 +253,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          result = MultiJson.load response.body, symbolize_keys: true
-          error_messages = String.new
-          result[:errors].each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error getting test students: #{error_messages}"
+          raise "Error getting test students: #{error_messages_from(response.body)}"
         end
       end
 
@@ -288,12 +265,7 @@ module PlatformSdk
         if success?(response.status)
           paginated_items headers: response.headers, initial_response: response.body
         else
-          result = MultiJson.load response.body, symbolize_keys: true
-          error_messages = String.new
-          result[:errors].each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error getting course users: #{error_messages}"
+          raise "Error getting course users: #{error_messages_from(response.body)}"
         end
       end
 
@@ -306,12 +278,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          result = MultiJson.load response.body, symbolize_keys: true
-          error_messages = String.new
-          result[:errors].each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error getting quiz: #{error_messages}"
+          raise "Error getting quiz: #{error_messages_from(response.body)}"
         end
       end
 
@@ -326,12 +293,7 @@ module PlatformSdk
         if success?(response.status)
           paginated_items headers: response.headers, initial_response: response.body
         else
-          result = MultiJson.load response.body, symbolize_keys: true
-          error_messages = String.new
-          result[:errors].each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error getting quiz submissions#{error_messages}"
+          raise "Error getting quiz submissions#{error_messages_from(response.body)}"
         end
       end
 
@@ -411,12 +373,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          result = MultiJson.load response.body, symbolize_keys: true
-          error_messages = String.new
-          result[:errors]&.each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error posting a reply: #{error_messages}"
+          raise "Error posting a reply: #{error_messages_from(response.body)}"
         end
       end
 
@@ -425,13 +382,11 @@ module PlatformSdk
       def put_relock_module(course_id:, module_id:)
         uri = "api/v1/courses/#{course_id}/modules/#{module_id}/relock"
         response = @connection.put(uri)
-        result = MultiJson.load response.body, symbolize_keys: true
         handle_rate_limiting response
         if success?(response.status)
-          result
+          MultiJson.load response.body, symbolize_keys: true
         else
-          error_message = parse_response_errors(result:, message: 'Error re-locking module')
-          raise CanvasClientError, error_message
+          raise CanvasClientError, "Error re-locking module: #{error_messages_from(response.body)}"
         end
       end
 
@@ -446,15 +401,10 @@ module PlatformSdk
           req.body = { 'module[prerequisite_module_ids]' => prerequisite_ids }
         end
         handle_rate_limiting response
-        result = MultiJson.load response.body, symbolize_keys: true
         if success?(response.status)
-          result
+          MultiJson.load response.body, symbolize_keys: true
         else
-          error_messages = String.new
-          result[:errors]&.each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error updating module prerequisite: #{error_messages}"
+          raise "Error updating module prerequisite: #{error_messages_from(response.body)}"
         end
       end
 
@@ -466,15 +416,10 @@ module PlatformSdk
           req.body = { 'module[name]' => original_name }
         end
         handle_rate_limiting response
-        result = MultiJson.load response.body, symbolize_keys: true
         if success?(response.status)
-          result
+          MultiJson.load response.body, symbolize_keys: true
         else
-          error_messages = String.new
-          result[:errors]&.each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error updating refreshing module prerequisite: #{error_messages}"
+          raise "Error updating refreshing module prerequisite: #{error_messages_from(response.body)}"
         end
       end
 
@@ -490,15 +435,10 @@ module PlatformSdk
           req.body = body
         end
         handle_rate_limiting response
-        result = MultiJson.load response.body, symbolize_keys: true
         if success?(response.status)
-          result
+          MultiJson.load response.body, symbolize_keys: true
         else
-          error_messages = String.new
-          result[:errors]&.each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error creating module: #{error_messages}"
+          raise "Error creating module: #{error_messages_from(response.body)}"
         end
       end
 
@@ -518,15 +458,10 @@ module PlatformSdk
           req.body = body
         end
         handle_rate_limiting response
-        result = MultiJson.load response.body, symbolize_keys: true
         if success?(response.status)
-          result
+          MultiJson.load response.body, symbolize_keys: true
         else
-          error_messages = String.new
-          result[:errors]&.each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error updating module: #{error_messages}"
+          raise "Error updating module: #{error_messages_from(response.body)}"
         end
       end
 
@@ -546,15 +481,10 @@ module PlatformSdk
           req.body = body
         end
         handle_rate_limiting response
-        result = MultiJson.load response.body, symbolize_keys: true
         if success?(response.status)
-          result
+          MultiJson.load response.body, symbolize_keys: true
         else
-          error_messages = String.new
-          result[:errors]&.each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error creating module item: #{error_messages}"
+          raise "Error creating module item: #{error_messages_from(response.body)}"
         end
       end
 
@@ -568,15 +498,10 @@ module PlatformSdk
           req.body = { 'module_item[published]' => true }
         end
         handle_rate_limiting response
-        result = MultiJson.load response.body, symbolize_keys: true
         if success?(response.status)
-          result
+          MultiJson.load response.body, symbolize_keys: true
         else
-          error_messages = String.new
-          result[:errors]&.each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error publishing module item: #{error_messages}"
+          raise "Error publishing module item: #{error_messages_from(response.body)}"
         end
       end
 
@@ -586,15 +511,10 @@ module PlatformSdk
           req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
         end
         handle_rate_limiting response
-        result = MultiJson.load response.body, symbolize_keys: true
         if success?(response.status)
-          result
+          MultiJson.load response.body, symbolize_keys: true
         else
-          error_messages = String.new
-          result[:errors]&.each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error destroying module item: #{error_messages}"
+          raise "Error destroying module item: #{error_messages_from(response.body)}"
         end
       end
 
@@ -604,44 +524,90 @@ module PlatformSdk
           req.headers['Content-Type'] = 'application/json'
         end
         handle_rate_limiting response
-        result = MultiJson.load response.body, symbolize_keys: true
         if success?(response.status)
-          result
+          MultiJson.load response.body, symbolize_keys: true
         else
-          error_messages = String.new
-          result[:errors]&.each do |error|
-            error_messages << "#{error[:message]} "
-          end
-          raise "Error retrieving discussion topic: #{error_messages}"
+          raise "Error retrieving discussion topic: #{error_messages_from(response.body)}"
         end
       end
 
       private
 
+      def default_headers
+        {
+          'Authorization' => "Bearer #{token}",
+          'User-Agent' => "StrongMind-PlatformSDK/#{PlatformSdk::VERSION}"
+        }
+      end
+
+      def build_connection
+        Faraday.new(url: host, headers: default_headers) do |f|
+          # Faraday installs UrlEncoded by default, but only when no block is
+          # given -- several endpoints here post a Hash body as form data and
+          # depend on it, so it has to be re-declared alongside the retry.
+          f.request :url_encoded
+          f.request :retry, @retry_options
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      # Walks `rel="next"` rather than comparing `rel="current"` to
+      # `rel="last"`. Canvas omits `last` when the total count is too
+      # expensive to compute, which left the old condition permanently true
+      # and crashed on the final page, where there is no `next` to follow.
+      # https://canvas.instructure.com/doc/api/file.pagination.html
+      #
       # @param headers [Faraday::Utils::Headers]
       # @return [Array]
       def paginated_items(headers:, initial_response:)
         pages = page_links(headers:)
         items = []
         items.append MultiJson.load(initial_response, symbolize_keys: true)
-        while pages[:current] != pages[:last]
-          response = @connection.get(pages[:next][:url])
-          handle_rate_limiting response
+        while pages[:next]
+          response = fetch_page(pages[:next][:url])
           pages = page_links(headers: response.headers)
           items.append MultiJson.load(response.body, symbolize_keys: true)
         end
         items.flatten
       end
 
+      # A failed page carries no `Link` header for `page_links` to read, so
+      # this has to raise rather than return. It raises `CanvasClientError`
+      # directly instead of going through `handle_post_response_errors`,
+      # whose status mapping is specific to module-item writes -- a 403 on
+      # page 2 of a listing is not a `LockedModuleItemError`.
+      #
+      # @param url [String]
+      # @return [Faraday::Response]
+      def fetch_page(url)
+        response = @connection.get(url)
+        handle_rate_limiting response
+        return response if success?(response.status)
+
+        raise CanvasClientError,
+              "Error paginating Canvas results,\nhost: #{host},\nurl: #{url},\n" \
+              "status: #{response.status},\nresponse: #{response.body}"
+      end
+
+      # Tolerates only a missing `Link` header -- an unpaginated 2xx has none
+      # at all, and `{}` reads as "no next page" to `paginated_items`. A
+      # header that is present but does not parse raises instead of also
+      # returning `{}`, which would read as a complete listing when records
+      # are actually missing. Canvas quotes `rel` per RFC 8288, so a present
+      # header that fails this parse is not a shape production sends.
+      #
       # @param headers [Faraday::Utils::Headers]
       # @return [Hash]
       def page_links(headers:)
-        parts = headers[:link].split(',')
-        parts.map do |part, _|
-          section = part.split(';')
-          name = section[1][/rel="(.*)"/, 1].to_sym
-          url = section[0][/<(.*)>/, 1]
-          [name, { url: }]
+        raw = headers[:link]
+        return {} if raw.nil?
+
+        raw.split(',').map do |part|
+          name = part[/rel="(.*?)"/, 1]
+          url = part[/<(.*?)>/, 1]
+          raise CanvasClientError, "Malformed Canvas Link header: #{raw}" if name.nil? || url.nil?
+
+          [name.to_sym, { url: }]
         end.to_h
       end
 
@@ -651,25 +617,53 @@ module PlatformSdk
         (200..299).cover?(response_code.to_i)
       end
 
-      # @param message [String]
-      # @param result [Hash]
+      # Canvas's own 429 body (raised by `RequestThrottle`, not the Rails app)
+      # is plain text, not the JSON error shape every other failure returns.
+      # Without this, an exhausted retry surfaced as `MultiJson::ParseError`
+      # instead of the descriptive error each caller raises.
+      #
+      # @param body [String]
       # @return [String]
-      def parse_response_errors(message:, result:)
-        error_messages = String.new
-        unless result[:errors].nil?
-          result[:errors].each do |error|
-            error_messages << "#{error[:message]} "
-          end
+      def error_messages_from(body)
+        result = MultiJson.load(body, symbolize_keys: true)
+        (result[:errors] || []).map { |error| "#{error[:message]} " }.join
+      rescue MultiJson::ParseError
+        body.to_s
+      end
+
+      # Called by faraday-retry before each retry sleep so a sustained
+      # throttle shows up in logs instead of only as request latency.
+      #
+      # @param env [Faraday::Env]
+      # @param retry_count [Integer] retries already attempted, starts at 0
+      # @param will_retry_in [Float] seconds until the retry fires
+      def log_rate_limit_retry(env:, retry_count:, will_retry_in:, **)
+        log_warn("Canvas rate limited (attempt #{retry_count + 1}): " \
+                  "#{env.url.path}, retrying in #{will_retry_in.round(2)}s")
+      end
+
+      # @param message [String]
+      def log_warn(message)
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger.warn(message)
+        else
+          warn(message)
         end
-        "#{message}: #{error_messages}"
       end
 
+      # Pre-emptive throttle: when Canvas reports the bucket is spent, wait for
+      # it to refill rather than spending the next call on a 429. An absent
+      # header is not a quota of zero.
+      #
+      # Canvas reports the remaining quota as a float that goes negative once
+      # a client is over the high-water mark, e.g. "0.75" or "-2.0" -- `to_i`
+      # truncation read "0.75" as spent and slept unnecessarily. Parsed as a
+      # float instead, so only a value at or below zero throttles.
       def handle_rate_limiting(response)
-        remaining_requests = response.headers["X-Rate-Limit-Remaining"].to_i
-        reset_time = response.headers["X-Rate-Limit-Reset"].to_i
-
-        return unless remaining_requests.zero?
+        remaining_requests = Float(response.headers['X-Rate-Limit-Remaining'], exception: false)
+        return if remaining_requests.nil? || remaining_requests.positive?
 
+        reset_time = response.headers['X-Rate-Limit-Reset'].to_i
         sleep_time = [reset_time - Time.now.to_i, 0].max + 1
         sleep(sleep_time)
       end

data/lib/platform_sdk/version.rb

@@ -3,7 +3,7 @@
 module PlatformSdk
   MAJOR = 3
   MINOR = 33
-  PATCH = 4
+  PATCH = 5
 
   VERSION = "#{PlatformSdk::MAJOR}.#{PlatformSdk::MINOR}.#{PlatformSdk::PATCH}".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: strongmind-platform-sdk
 version: !ruby/object:Gem::Version
-  version: 3.33.4
+  version: 3.33.5
 platform: ruby
 authors:
 - Platform Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-18 00:00:00.000000000 Z
+date: 2026-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64