strongmind-platform-sdk 3.33.4 → 3.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80e27a2c045cd72bc8633ded3fc6505f5c2a029158bb67b120ed6b39b31c3438
-  data.tar.gz: 9941c3cde4236922d326beb90cfef6847568fb1b996eb55bc999f86217672385
+  metadata.gz: '04844dcb9535437ef995d84bb438f6c214c2ae46b9e05a68f1f51309adba6f86'
+  data.tar.gz: 8584e6f47bd375199e84d136564933d5fb8d94ee178ff9ef95825a52564e590d
 SHA512:
-  metadata.gz: d991813ce02b2207fc72c523930d4dbe827d05e644be07d6868caa562be89936ec71a305bf275c1c378571005775cbcf584784bb2fbc57a806ccc236e438caac
-  data.tar.gz: c29637d88a1e720243e39a556195e89836c1346d1fc2a0e0de2d5c88a0d286c1a5bdc8096fea2be727dd2b0777f4e4fb6d32c37a3130c8ccf3b0063fbaef5588
+  metadata.gz: 728ad0c1173e142855ada5487833ae8896bb4dd02e383dcdc62e06098dd68109f663a10d9c598c86890958fe5833717565c9d8289f0aeeb69745df525a26d364
+  data.tar.gz: d8f8c3f2a78151161ef58f08971525b6ce6643df1d9984e1ca3784738e167dda798c25877e7290a29c5859010665660b9019335e7e2b723f2e54c0f530d0c96e

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Unreleased]
 
+- Raise typed errors from every Canvas error branch. The read/list/PUT-write methods raised bare `RuntimeError` strings, which consumers could not distinguish from a bug — Central's grade-passback retry wrapper, for example, only retries `CanvasClientError` and so treated every throttled read as fatal. All error branches now raise through one handler: 404 → `MissingModuleItemError`, 401 → `UnauthorizedError`, rate-limited → `RateLimitedError` (new), anything else → `CanvasClientError`. Every class subclasses `CanvasClientError` (itself a `StandardError`), so rescues written against the old classes keep working; only code matching on `RuntimeError` specifically (none known) would notice. Message text changed (see below); no known consumer parses it.
+- Stop echoing raw Canvas response bodies and page query strings into error messages. Consumers persist `error.message` (Central's `OutcomeLog.exception_message`) and forward it to Sentry, and a raw body from a submission, quiz or roster endpoint can carry student records (FERPA). Every error path now shares one message policy: `"<descriptor>: <Canvas's own error messages> (status: N, host: H)"`, with a fixed `unparseable Canvas error body` / `empty Canvas error body` / `Canvas rate limit exceeded` descriptor in place of any body that isn't a JSON error object. The write-path tail (`handle_post_response_errors`) previously appended the whole body and skipped the `error_messages_from` hardening; it now goes through the same builder. Pagination failures name the page path only, dropping the query that carries `as_user_id`/`student_id`. The raw body and status are still available as `CanvasClientError#response_body` and `#status` for a consumer that decides it is safe to inspect.
+- `error_messages_from` also reads a hash-shaped `errors` (field => messages, as Canvas validation errors return) and a top-level `message` key, instead of producing an inspect blob or nothing.
+- Anchor 403-throttle detection to the start of Canvas's plain-text `403 Forbidden (Rate Limit Exceeded)` body. The unanchored substring match would have turned a genuine JSON 403 that mentioned the phrase into a retryable `RateLimitedError`, the opposite of `LockedModuleItemError` on the write paths.
+- The retry warning logs the HTTP method and route shape with numeric path segments replaced by `:id`, so a Canvas user id in a submission path does not land in logs.
+- Add `CanvasApiWrapper::RateLimitedError`, raised for a 429 as well as the 403 + "Rate Limit Exceeded" body that hosted Canvas sends when `request_throttle.send_429_response` is disabled — the shape behind the QTY-19690 grade-loss incident, previously surfacing as `MultiJson::ParseError`/`RuntimeError`. Carries `retry_after` (seconds, `Float`) when Canvas sent a `Retry-After` header, nil otherwise; callers own the backoff policy. `handle_post_response_errors` checks it before the status mapping, so a throttled write no longer misreports as `LockedModuleItemError` (a gap the retry-options comment had documented).
+- Add `Client#submission(course_id:, assignment_id:, user_id:)` — reads a single user's assignment submission. Central previously issued this GET against the raw connection and parsed the body itself, recreating the untyped-error problem the client had just fixed.
+- Fix `error_messages_from` raising `NoMethodError` when the error JSON carries `errors` as a bare string (Sentry CENTRAL-7R5) or uses the singular `error` key — the formatter's own crash masked the real failure. Array-of-hashes, string, singular-key, non-hash and non-JSON bodies all format safely now.
+- Fix `Client#assignment` raising "Error getting quiz submissions" — a copy-paste from `quiz_submissions`; it now says "Error getting assignment".
+- 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 substitutes a fixed descriptor when the body 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,72 @@ module PlatformSdk
 
       PAGE_SIZE = 10
 
+      # The plain-text body Canvas's `RequestThrottle` sends with a 403 when
+      # `request_throttle.send_429_response` is disabled.
+      THROTTLED_403_BODY = "403 Forbidden (Rate Limit Exceeded)"
+      RATE_LIMITED_MESSAGE = "Canvas rate limit exceeded"
+      UNPARSEABLE_BODY = "unparseable Canvas error body"
+      EMPTY_BODY = "empty Canvas error body"
+      NO_ERROR_MESSAGE = "no error message in Canvas response"
+
+      # 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. That shape won't retry here;
+      # it is recognised by `rate_limited?` and raised as `RateLimitedError`
+      # on read and write paths alike, so callers can still back off.
+      #
+      # `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 +88,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}"
+          handle_response_errors(response, "Error getting course modules")
         end
       end
 
@@ -48,12 +98,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}"
+          handle_response_errors(response, "Error getting course modules")
         end
       end
 
@@ -66,12 +111,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}"
+          handle_response_errors(response, "Error getting module items")
         end
       end
 
@@ -86,12 +126,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}"
+          handle_response_errors(response, "Error getting module items")
         end
       end
 
@@ -105,12 +140,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}"
+          handle_response_errors(response, "Error getting assignments")
         end
       end
 
@@ -122,12 +152,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}"
+          handle_response_errors(response, "Error getting assignment")
         end
       end
 
@@ -140,12 +165,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}"
+          handle_response_errors(response, "Error getting module item")
         end
       end
 
@@ -155,12 +175,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}"
+          handle_response_errors(response, "Error getting module item")
         end
       end
 
@@ -170,12 +185,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}"
+          handle_response_errors(response, "Error getting module item")
         end
       end
 
@@ -187,12 +197,22 @@ 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}"
+          handle_response_errors(response, "Error getting submissions")
+        end
+      end
+
+      # @param course_id [Integer]
+      # @param assignment_id [Integer]
+      # @param user_id [Integer]
+      # @return [Hash]
+      def submission(course_id:, assignment_id:, user_id:)
+        uri = "/api/v1/courses/#{course_id}/assignments/#{assignment_id}/submissions/#{user_id}"
+        response = @connection.get(uri)
+        handle_rate_limiting response
+        if success?(response.status)
+          MultiJson.load response.body, symbolize_keys: true
+        else
+          handle_response_errors(response, "Error getting submission")
         end
       end
 
@@ -210,12 +230,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}"
+          handle_response_errors(response, "Error update submissions to excused")
         end
       end
 
@@ -232,15 +247,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}"
+          handle_response_errors(response, "Error update submissions to excused")
         end
       end
 
@@ -253,12 +264,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}"
+          handle_response_errors(response, "Error getting course students")
         end
       end
 
@@ -271,12 +277,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}"
+          handle_response_errors(response, "Error getting test students")
         end
       end
 
@@ -288,12 +289,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}"
+          handle_response_errors(response, "Error getting course users")
         end
       end
 
@@ -306,12 +302,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}"
+          handle_response_errors(response, "Error getting quiz")
         end
       end
 
@@ -326,12 +317,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}"
+          handle_response_errors(response, "Error getting quiz submissions")
         end
       end
 
@@ -411,12 +397,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}"
+          handle_response_errors(response, "Error posting a reply")
         end
       end
 
@@ -425,13 +406,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
+          handle_response_errors(response, "Error re-locking module")
         end
       end
 
@@ -446,15 +425,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}"
+          handle_response_errors(response, "Error updating module prerequisite")
         end
       end
 
@@ -466,15 +440,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}"
+          handle_response_errors(response, "Error updating refreshing module prerequisite")
         end
       end
 
@@ -490,15 +459,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}"
+          handle_response_errors(response, "Error creating module")
         end
       end
 
@@ -518,15 +482,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}"
+          handle_response_errors(response, "Error updating module")
         end
       end
 
@@ -546,15 +505,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}"
+          handle_response_errors(response, "Error creating module item")
         end
       end
 
@@ -568,15 +522,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}"
+          handle_response_errors(response, "Error publishing module item")
         end
       end
 
@@ -586,15 +535,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}"
+          handle_response_errors(response, "Error destroying module item")
         end
       end
 
@@ -604,44 +548,103 @@ 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}"
+          handle_response_errors(response, "Error retrieving discussion topic")
         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. Anything but a throttle raises
+      # plain `CanvasClientError` instead of going through the status
+      # mapping: a 403 on page 2 of a listing is not a
+      # `LockedModuleItemError`, and a 404 mid-listing is not a permanent
+      # absence of the resource the caller asked for.
+      #
+      # The message names only the page's path. The query string carries
+      # `as_user_id`/`student_id` and is left out along with the body.
+      #
+      # @param url [String]
+      # @return [Faraday::Response]
+      def fetch_page(url)
+        response = @connection.get(url)
+        handle_rate_limiting response
+        return response if success?(response.status)
+
+        message = error_message_for(response, "Error paginating Canvas results (#{path_of(url)})")
+        raise_rate_limited(response, message) if rate_limited?(response)
+
+        raise canvas_error(CanvasClientError, response, message)
+      end
+
+      # @param url [String]
+      # @return [String]
+      def path_of(url)
+        URI(url.to_s).path
+      rescue URI::InvalidURIError
+        "unparseable page url"
+      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 +654,179 @@ 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.
+      #
+      # Canvas is also not consistent about the JSON shape itself: `errors`
+      # is usually an array of `{message:}` hashes but is sometimes a bare
+      # string or a hash of field => messages, and some endpoints use a
+      # singular `error` or top-level `message` key. Formatting must never
+      # raise -- it would mask the failure it is describing.
+      #
+      # Only Canvas's own message strings reach the result. A body that is
+      # not a JSON object is replaced by a fixed descriptor rather than
+      # echoed: these messages are persisted and sent to error tracking by
+      # consumers, and a raw body from a student-data endpoint can carry
+      # student records. The raw body stays available on the raised error's
+      # `response_body` for a consumer that wants it.
+      #
+      # @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)
+        return EMPTY_BODY if body.to_s.strip.empty?
+
+        result = MultiJson.load(body, symbolize_keys: true)
+        return UNPARSEABLE_BODY unless result.is_a?(Hash)
+
+        messages = messages_in(result[:errors] || result[:error] || result[:message])
+        messages.empty? ? NO_ERROR_MESSAGE : messages.join(" ")
+      rescue MultiJson::ParseError
+        UNPARSEABLE_BODY
+      end
+
+      # @param value [Object] an `errors`/`error`/`message` value from Canvas
+      # @return [Array<String>]
+      def messages_in(value)
+        case value
+        when Array then value.flat_map { |item| messages_in(item) }
+        when Hash
+          value.key?(:message) ? messages_in(value[:message]) : value.values.flat_map { |item| messages_in(item) }
+        when nil then []
+        else [value.to_s]
         end
-        "#{message}: #{error_messages}"
       end
 
-      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
+      # The single message policy for every error path: the caller's
+      # descriptor, Canvas's own error messages, the status and the host.
+      #
+      # @param response [Faraday::Response]
+      # @param prefix [String]
+      # @return [String]
+      def error_message_for(response, prefix)
+        details = rate_limited?(response) ? RATE_LIMITED_MESSAGE : error_messages_from(response.body)
+        "#{prefix}: #{details} (status: #{response.status}, host: #{host})"
+      end
+
+      # @param response [Faraday::Response]
+      # @param message [String]
+      def handle_response_errors(response, message)
+        raise_typed_error(response, error_message_for(response, message))
+      end
+
+      # One owner of the status→error mapping for read and write paths
+      # alike; a taxonomy change is an edit here, not at each call site. 404
+      # maps to `MissingModuleItemError` for every endpoint -- the name is
+      # narrower than its use here, but it is the class consumers already
+      # treat as "the resource is gone, do not retry". `locked_on_403:` is
+      # the single divergence: module-item writes read a non-throttle 403
+      # as Canvas content state.
+      #
+      # @param response [Faraday::Response]
+      # @param message [String]
+      # @param locked_on_403 [Boolean]
+      def raise_typed_error(response, message, locked_on_403: false)
+        raise_rate_limited(response, message) if rate_limited?(response)
+
+        error_class = case response.status.to_i
+                      when 403 then locked_on_403 ? LockedModuleItemError : CanvasClientError
+                      when 404 then MissingModuleItemError
+                      when 401 then UnauthorizedError
+                      else CanvasClientError
+                      end
+        raise canvas_error(error_class, response, message)
+      end
+
+      # @param error_class [Class<CanvasClientError>]
+      # @param response [Faraday::Response]
+      # @param message [String]
+      # @return [CanvasClientError]
+      def canvas_error(error_class, response, message)
+        error_class.new(message, status: response.status.to_i, response_body: response.body)
+      end
+
+      # Canvas's `RequestThrottle` answers 429 when `send_429_response` is
+      # enabled and 403 with a plain-text "403 Forbidden (Rate Limit
+      # Exceeded)" body when it is not; both mean the same thing to a caller
+      # deciding whether to back off. The 403 match is anchored to the start
+      # of that body, so a genuine 403 whose JSON error happens to mention
+      # the phrase is not turned into a retryable throttle.
+      #
+      # @param response [Faraday::Response]
+      # @return [Boolean]
+      def rate_limited?(response)
+        status = response.status.to_i
+        return true if status == 429
 
-        return unless remaining_requests.zero?
+        status == 403 && response.body.to_s.start_with?(THROTTLED_403_BODY)
+      end
 
+      # @param response [Faraday::Response]
+      # @param message [String]
+      def raise_rate_limited(response, message)
+        raise RateLimitedError.new(message, retry_after: retry_after_from(response),
+                                            status: response.status.to_i, response_body: response.body)
+      end
+
+      # Seconds only: an RFC 9110 HTTP-date `Retry-After` is deliberately
+      # treated as absent -- Canvas sends neither form today, and a nil
+      # tells the caller to fall back to its own backoff.
+      #
+      # @param response [Faraday::Response]
+      # @return [Float, nil]
+      def retry_after_from(response)
+        Float(response.headers["Retry-After"], exception: false)
+      end
+
+      # Called by faraday-retry before each retry sleep so a sustained
+      # throttle shows up in logs instead of only as request latency. Numeric
+      # path segments are replaced with `:id`: submission endpoints carry the
+      # Canvas user id in the path, and the route shape is what an operator
+      # needs.
+      #
+      # @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.method.to_s.upcase} #{route_label(env.url.path)}, " \
+                  "retrying in #{will_retry_in.round(2)}s")
+      end
+
+      # @param path [String]
+      # @return [String]
+      def route_label(path)
+        path.to_s.gsub(%r{/\d+(?=/|\z)}, "/:id")
+      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
+      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.
+      #
+      # This also runs on a throttled response before `RateLimitedError` is
+      # raised, so a caller honouring `retry_after` may wait on top of this
+      # pause. That is deliberate: consumers without their own backoff still
+      # get the pause they always had.
+      def handle_rate_limiting(response)
+        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
@@ -677,25 +834,40 @@ module PlatformSdk
       # @param response [Faraday::Response]
       # @param message [String]
       def handle_post_response_errors(response, message)
-        message = "#{message},\n" + "host: #{host},\n" + "response: #{response.body}"
-        case response.status
-        when 403
-          raise LockedModuleItemError, message
-        when 404
-          raise MissingModuleItemError, message
-        when 401
-          raise UnauthorizedError, message
-        else
-          raise CanvasClientError, message
-        end
+        raise_typed_error(response, error_message_for(response, message), locked_on_403: true)
       end
     end
 
-    class CanvasClientError < StandardError; end
+    # `status` and `response_body` are set when the error came from a Canvas
+    # response. The message deliberately omits the raw body, which can carry
+    # student records; `response_body` keeps it for a consumer that decides
+    # it is safe to inspect. Do not forward it to logs or error tracking.
+    class CanvasClientError < StandardError
+      attr_reader :status, :response_body
+
+      def initialize(message = nil, status: nil, response_body: nil)
+        @status = status
+        @response_body = response_body
+        super(message)
+      end
+    end
 
     class LockedModuleItemError < CanvasClientError; end
 
     class MissingModuleItemError < CanvasClientError; end
     class UnauthorizedError < CanvasClientError; end
+
+    # Canvas throttled the request (429, or 403 with a rate-limit body).
+    # `retry_after` carries the `Retry-After` header in seconds when Canvas
+    # sent one, nil otherwise; callers own the backoff policy. The client
+    # may already have paused before raising (see `handle_rate_limiting`).
+    class RateLimitedError < CanvasClientError
+      attr_reader :retry_after
+
+      def initialize(message = nil, retry_after: nil, **response)
+        @retry_after = retry_after
+        super(message, **response)
+      end
+    end
   end
 end

data/lib/platform_sdk/version.rb

@@ -2,8 +2,8 @@
 
 module PlatformSdk
   MAJOR = 3
-  MINOR = 33
-  PATCH = 4
+  MINOR = 34
+  PATCH = 0
 
   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.34.0
 platform: ruby
 authors:
 - Platform Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-18 00:00:00.000000000 Z
+date: 2026-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64