strongmind-platform-sdk 3.33.5 → 3.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe3ec6a94953018e636a9fc5bab7a7f66791db9d15aeed14035c1a444980f9a6
-  data.tar.gz: 678c3fc1a62d418838ab25d1fd8bafeea342a58a986bcd1a1ec3e5d6d087e6dc
+  metadata.gz: '04844dcb9535437ef995d84bb438f6c214c2ae46b9e05a68f1f51309adba6f86'
+  data.tar.gz: 8584e6f47bd375199e84d136564933d5fb8d94ee178ff9ef95825a52564e590d
 SHA512:
-  metadata.gz: 83d9ffbf4ee13769ae6ffb5d1346e8a37cbd6d1cfc511be1ef0d87a63863191bccc12b9a51cfdce4a4732ec70e9c35580018677e15aca638d3e9629cfc89cb37
-  data.tar.gz: 67bb2e2e837402cb15fdedab566a343111f17204795eafc1e149fa19976d53f277ab924f0d247877c76570996e18db6f125e444df27f162b05928342ce537570
+  metadata.gz: 728ad0c1173e142855ada5487833ae8896bb4dd02e383dcdc62e06098dd68109f663a10d9c598c86890958fe5833717565c9d8289f0aeeb69745df525a26d364
+  data.tar.gz: d8f8c3f2a78151161ef58f08971525b6ce6643df1d9984e1ca3784738e167dda798c25877e7290a29c5859010665660b9019335e7e2b723f2e54c0f530d0c96e

data/CHANGELOG.md

@@ -1,8 +1,17 @@
 ## [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 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 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.

data/lib/platform_sdk/canvas_api/client.rb

@@ -12,6 +12,14 @@ 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
@@ -41,8 +49,9 @@ module PlatformSdk
       #
       # `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.
+      # `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
@@ -79,7 +88,7 @@ module PlatformSdk
         if success?(response.status)
           paginated_items headers: response.headers, initial_response: response.body
         else
-          raise "Error getting course modules: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error getting course modules")
         end
       end
 
@@ -89,7 +98,7 @@ module PlatformSdk
         if success?(response.status)
           paginated_items headers: response.headers, initial_response: response.body
         else
-          raise "Error getting course modules: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error getting course modules")
         end
       end
 
@@ -102,7 +111,7 @@ module PlatformSdk
         if success?(response.status)
           paginated_items headers: response.headers, initial_response: response.body
         else
-          raise "Error getting module items: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error getting module items")
         end
       end
 
@@ -117,7 +126,7 @@ module PlatformSdk
         if success?(response.status)
           paginated_items headers: response.headers, initial_response: response.body
         else
-          raise "Error getting module items: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error getting module items")
         end
       end
 
@@ -131,7 +140,7 @@ module PlatformSdk
           assignments = paginated_items headers: response.headers, initial_response: response.body
           assignments.select { |item| item[:type] == 'Assignment' }
         else
-          raise "Error getting assignments: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error getting assignments")
         end
       end
 
@@ -143,7 +152,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          raise "Error getting quiz submissions#{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error getting assignment")
         end
       end
 
@@ -156,7 +165,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          raise "Error getting module item: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error getting module item")
         end
       end
 
@@ -166,7 +175,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          raise "Error getting module item: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error getting module item")
         end
       end
 
@@ -176,7 +185,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          raise "Error getting module item: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error getting module item")
         end
       end
 
@@ -188,7 +197,22 @@ module PlatformSdk
         if success?(response.status)
           paginated_items headers: response.headers, initial_response: response.body
         else
-          raise "Error getting submissions: #{error_messages_from(response.body)}"
+          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
 
@@ -206,7 +230,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          raise "Error update submissions to excused: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error update submissions to excused")
         end
       end
 
@@ -227,7 +251,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          raise "Error update submissions to excused: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error update submissions to excused")
         end
       end
 
@@ -240,7 +264,7 @@ module PlatformSdk
         if success?(response.status)
           paginated_items headers: response.headers, initial_response: response.body
         else
-          raise "Error getting course students: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error getting course students")
         end
       end
 
@@ -253,7 +277,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          raise "Error getting test students: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error getting test students")
         end
       end
 
@@ -265,7 +289,7 @@ module PlatformSdk
         if success?(response.status)
           paginated_items headers: response.headers, initial_response: response.body
         else
-          raise "Error getting course users: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error getting course users")
         end
       end
 
@@ -278,7 +302,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          raise "Error getting quiz: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error getting quiz")
         end
       end
 
@@ -293,7 +317,7 @@ module PlatformSdk
         if success?(response.status)
           paginated_items headers: response.headers, initial_response: response.body
         else
-          raise "Error getting quiz submissions#{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error getting quiz submissions")
         end
       end
 
@@ -373,7 +397,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          raise "Error posting a reply: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error posting a reply")
         end
       end
 
@@ -386,7 +410,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          raise CanvasClientError, "Error re-locking module: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error re-locking module")
         end
       end
 
@@ -404,7 +428,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          raise "Error updating module prerequisite: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error updating module prerequisite")
         end
       end
 
@@ -419,7 +443,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          raise "Error updating refreshing module prerequisite: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error updating refreshing module prerequisite")
         end
       end
 
@@ -438,7 +462,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          raise "Error creating module: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error creating module")
         end
       end
 
@@ -461,7 +485,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          raise "Error updating module: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error updating module")
         end
       end
 
@@ -484,7 +508,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          raise "Error creating module item: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error creating module item")
         end
       end
 
@@ -501,7 +525,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          raise "Error publishing module item: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error publishing module item")
         end
       end
 
@@ -514,7 +538,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          raise "Error destroying module item: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error destroying module item")
         end
       end
 
@@ -527,7 +551,7 @@ module PlatformSdk
         if success?(response.status)
           MultiJson.load response.body, symbolize_keys: true
         else
-          raise "Error retrieving discussion topic: #{error_messages_from(response.body)}"
+          handle_response_errors(response, "Error retrieving discussion topic")
         end
       end
 
@@ -572,10 +596,14 @@ module PlatformSdk
       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`.
+      # 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]
@@ -584,9 +612,18 @@ module PlatformSdk
         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}"
+        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
@@ -622,24 +659,145 @@ module PlatformSdk
       # 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 error_messages_from(body)
+        return EMPTY_BODY if body.to_s.strip.empty?
+
         result = MultiJson.load(body, symbolize_keys: true)
-        (result[:errors] || []).map { |error| "#{error[:message]} " }.join
+        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
-        body.to_s
+        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
+      end
+
+      # 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
+
+        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.
+      # 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.url.path}, retrying in #{will_retry_in.round(2)}s")
+                  "#{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]
@@ -659,6 +817,11 @@ module PlatformSdk
       # 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?
@@ -671,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 = 5
+  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.5
+  version: 3.34.0
 platform: ruby
 authors:
 - Platform Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-11 00:00:00.000000000 Z
+date: 2026-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64