basecamp-sdk 0.17.0 → 0.19.0

data/lib/basecamp/http.rb

@@ -12,26 +12,179 @@ module Basecamp
     # Default User-Agent header
     USER_AGENT = "basecamp-sdk-ruby/#{VERSION} (api:#{API_VERSION})".freeze
 
-    # Normalizes Person-shaped objects in parsed JSON.
-    # For objects with personable_type and a string id:
-    # - Numeric strings: coerced to Integer, no system_label
+    # Normalizes Person-shaped objects in parsed JSON, finding them the TWO ways
+    # the reference finds them (go/pkg/basecamp/normalize.go):
+    #
+    # 1. by TYPE TAG — any object carrying "personable_type" (+normalizePersonIds+,
+    #    normalize.go:16);
+    # 2. by STRUCTURAL POSITION — the "creator" object and each "participants"
+    #    element, at any depth, WHETHER OR NOT they carry "personable_type"
+    #    (+normalizeEmbeddedPersonIds+, normalize.go:83).
+    #
+    # The second one is not a refinement of the first, and this method had only
+    # the first. BC3's embedded creator and participants people frequently omit
+    # "personable_type" — the reference's own comment (normalize.go:78-82) says
+    # that is why the pass exists — so their string ids reached callers
+    # unconverted: 62 of the 74 measured rows of GoPersonIds::CORPUS differed
+    # from the reference for a bare {"creator":{"id":…}}, and the twelve that
+    # agreed did so only because "leave the string" is also what doing nothing
+    # looks like. The visible cost was on a WRITE: {Services::MergeSafe} then
+    # required an Integer id, so a merge-safe update of a schedule entry whose
+    # participants came back with string ids raised where the reference reads
+    # the number and proceeds. (It now reads a person id itself, through
+    # {Ids.person_from_wire}; this pass is still what the reference does here.)
+    #
+    # Whichever way a person is found, the id rule is the same one
+    # ({coerce_person_id}, the reference's shared coercePersonID):
+    # - Signed decimal strings: coerced to Integer, no system_label
     # - Non-numeric sentinels (e.g. "basecamp"): id becomes 0, system_label preserves original
-    def self.normalize_person_ids(obj)
+    # - Numeric overflow: left as the string, for the reader to refuse
+    #
+    # ONE WALK, where the reference makes two passes over the same tree. That is
+    # sound only because {coerce_person_id} is idempotent — it returns untouched
+    # unless the id is a String, and it leaves a String behind only in the
+    # overflow case, where a second visit reaches the same refusal — so an
+    # object both passes find is coerced once and re-visited to no effect, and
+    # the order the two rules fire in cannot matter. Verified differentially
+    # against a literal two-walk transcription of normalize.go over the corpus
+    # in nineteen document shapes; if that idempotence is ever weakened, split
+    # this back into two walks.
+    def self.normalize_person_ids(obj, embedded_people: false)
       case obj
       when Hash
-        if obj.key?("personable_type") && obj["id"].is_a?(String)
-          raw_id = obj["id"]
-          numeric = Integer(raw_id, exception: false)
-          if numeric
-            obj["id"] = numeric
-          else
-            obj["system_label"] = raw_id
-            obj["id"] = 0
-          end
-        end
-        obj.each_value { |v| normalize_person_ids(v) }
+        coerce_person_id(obj) if obj.key?("personable_type")
+        coerce_embedded_person_ids(obj) if embedded_people
+        obj.each_value { |v| normalize_person_ids(v, embedded_people: embedded_people) }
       when Array
-        obj.each { |item| normalize_person_ids(item) }
+        obj.each { |item| normalize_person_ids(item, embedded_people: embedded_people) }
+      end
+    end
+
+    # The endpoints the reference runs the POSITIONAL pass over, and only those.
+    #
+    # +normalizeEmbeddedPeopleJSON+ is a function in the reference, not a layer.
+    # It is called from +decodeGaugePayload+ (gauges.go:170, reached by every
+    # gauge and needle body) and from the three notification decoders
+    # (my_notifications.go:171, 281, 296). Nothing else in Go calls it, so
+    # nothing else here runs it.
+    #
+    # WHY THIS GATE EXISTS AT ALL, which is a correction. The pass used to run
+    # on every response body. Its two keys are the reference's two, but "creator"
+    # and "participants" are not unique to the wrapper types: on
+    # +UpcomingScheduleEntry+ they hold +UpcomingSchedulePerson+, whose +Id+ is a
+    # plain int64 in the reference (client.gen.go:4194-4198), so a string id
+    # there is a decode error in Go and became person 0 with a +system_label+
+    # here — the SYSTEM ACTOR, on the field that says who acted, for a body the
+    # reference refuses outright. +MyAssignment.assignees+ and
+    # +DisableOutOfOfficeOutput.person+ are the same shape of mistake.
+    #
+    # Matched on the request path rather than an operation name because Go's own
+    # boundary is the call site, and because +update_gauge_needle+ reaches
+    # +decodeGaugePayload+ in the reference while passing no operation id here.
+    #
+    # Each pattern is anchored to the END of the URL's path, and only the path
+    # is matched — never the host, never the query. An unanchored pattern over
+    # the whole URL would let a base URL whose own path happened to contain
+    # "/gauge_needles/" switch the pass on for every request.
+    EMBEDDED_PEOPLE_PATHS = [
+      %r{/my/readings\.json\z},                  # GetMyNotifications
+      %r{/my/readings/bubble_ups\.json\z},       # GetBubbleUps
+      %r{/gauge_needles/\d+\z},                   # GetGaugeNeedle, UpdateGaugeNeedle
+      %r{/projects/\d+/gauge/needles\.json\z},    # ListGaugeNeedles, CreateGaugeNeedle
+      %r{/reports/gauges\.json\z}                 # ListGauges
+    ].freeze
+
+    # Whether +url+ is one of the reference's two normalization surfaces.
+    def self.embedded_people_url?(url)
+      path = begin
+        URI.parse(url.to_s).path.to_s
+      rescue URI::InvalidURIError
+        return false
+      end
+      EMBEDDED_PEOPLE_PATHS.any? { |pattern| pattern.match?(path) }
+    end
+
+    # The people this object carries by POSITION rather than by type tag: its
+    # "creator", and each element of its "participants" (normalize.go:86-95,
+    # matched key for key).
+    #
+    # Only those two keys, and only their immediate shape — an object under
+    # "creator", the object elements under "participants" — because the
+    # reference names exactly these: they are the keys its wrapper types embed a
+    # *Person under (Notification, Gauge, GaugeNeedle).
+    #
+    # NOT because the reference leaves other person ids as strings. It does not.
+    # An earlier version of this comment said widening to "assignees" would
+    # "coerce ids the reference leaves alone", and that is false about the
+    # reference as a whole: Go spells the rule TWICE. This normalizer covers
+    # creator/participants for the wrapper types whose Person.ID is a plain
+    # int64, and Go's generated decoder covers every other person-valued field,
+    # because generated.Person.Id is a types.FlexibleInt64. So Go's OBSERVABLE
+    # answer at "assignees" is the number, reached by the other route.
+    #
+    # Ruby has no decoder on the generated path — +get+ returns a raw Hash — so
+    # that second route does not exist here, and an "assignees" id that arrives
+    # as a string stays one. That gap was measured on a write, and it is
+    # deliberately NOT closed by widening this list: the faithful site is the
+    # reader, field by field against the reference, because some person ids in
+    # the model really are plain int64 there (TemplateLibraryConfirmationPerson)
+    # and a blanket sweep would break them. It is closed at that reader:
+    # {Services::MergeSafe.writable_id_list} reads a string person id through
+    # {Ids.person_from_wire}.
+    def self.coerce_embedded_person_ids(obj)
+      creator = obj["creator"]
+      coerce_person_id(creator) if creator.is_a?(Hash)
+
+      participants = obj["participants"]
+      return unless participants.is_a?(Array)
+
+      participants.each { |person| coerce_person_id(person) if person.is_a?(Hash) }
+    end
+
+    # One Person-shaped object's string id, by the reference's grammar.
+    #
+    # SIGNED DECIMAL, not Ruby's Integer(). That method detects a base from the
+    # literal and tolerates surrounding space and underscores, so it read
+    # "0x10" as 16, "0b11" as 3, "1_2" as 12 and " 7" as 7 where the reference
+    # reads every one of them as a non-numeric sentinel and zeroes it. Worst of
+    # the set is "010": the reference parses base 10 and gets 10, Ruby detected
+    # octal and got 8 — not a refusal against an acceptance but two different
+    # PEOPLE, either of which a caller could then mention.
+    #
+    # This runs before either composite sees the value, so the strict decoding
+    # they do could never have seen the original: the normalizer had already
+    # replaced it. Measured against strconv.ParseInt(s, 10, 64) over the shapes
+    # above; the two agree everywhere else.
+    #
+    # Overflow is left as a String on purpose, which is what the reference does:
+    # the id is out of range for the field, so the reader refuses it rather than
+    # this silently substituting a sentinel. WHICH strings are overflows is
+    # decided by Go's scan order and not by their shape — "18446744073709551616x"
+    # is one and "18446744073709551615x" is a sentinel — so this reads them with
+    # {Basecamp::Ids.parse_int}, which is that scan, and shares it with
+    # {Basecamp::Ids.person_from_wire}: one rule, both person-id sites.
+    def self.coerce_person_id(obj)
+      raw = obj["id"]
+      # An id that is already a number, or absent, is left alone — the guard the
+      # reference keeps inside this function rather than at its callers
+      # (normalize.go:41-44). Here it is also what makes the single walk above
+      # safe: both of the reference's passes can reach the same object, and the
+      # second visit has to be a no-op.
+      return unless raw.is_a?(String)
+
+      # Bounded by construction: this runs over EVERY decoded response, and a
+      # body may be 50 MB, so a long digit run built an arbitrarily large
+      # Integer here before anything decided to discard it. The scan refuses
+      # past 64 bits within 20 digits and never converts the rest.
+      parsed = Ids.parse_int(raw)
+      case parsed
+      when :syntax
+        obj["system_label"] = raw
+        obj["id"] = 0
+      when :range
+        nil # left as the string, for the reader to refuse
+      else
+        obj["id"] = parsed
       end
     end
 
@@ -225,11 +378,26 @@ module Basecamp
       wrapper = nil
       events = paginated_enumerator(path, key: key, params: params, operation: operation, \
         max_items: max_items) do |first_data|
-        wrapper = first_data.reject { |k, _| k == key }
+        # The wrapper is the same body the page items came out of, so it takes
+        # the same rule: a null body is an empty wrapper, not a crash. This is
+        # the site the previous null sweep did not reach — `nil.reject` raised
+        # NoMethodError out of a public method where the reference reads a zero
+        # value and reports no events.
+        wrapper = first_data.is_a?(Hash) ? first_data.reject { |k, _| k == key } : {}
       end
       wrapper.merge(key => events)
     end
 
+    # The parsed Retry-After for a response some other path is mapping itself
+    # (the download hops in Client), so its error carries the same value the
+    # retry loop reads here — populated at every status (SPEC §6).
+    #
+    # @param value [String, nil] the raw Retry-After header value
+    # @return [Integer, nil] seconds, or nil when absent or malformed
+    def parse_retry_after_header(value)
+      parse_retry_after(value)
+    end
+
     private
 
     # Shared paginator core behind paginate/paginate_key/paginate_wrapped.
@@ -256,7 +424,7 @@ module Basecamp
 
       @hooks.on_paginate(base_url, 1)
       first_response = get(base_url, params: params, operation: operation)
-      first_data = parse_page(first_response, page: 1)
+      first_data = parse_page(first_response, page: 1, operation: operation)
       yield first_data if block_given?
       first_items = extract_page_items(first_data, key: key, page: 1)
 
@@ -271,7 +439,7 @@ module Basecamp
         else
           @hooks.on_paginate(base_url, 1)
           response = get(base_url, params: params, operation: operation)
-          items = extract_page_items(parse_page(response, page: 1), key: key, page: 1)
+          items = extract_page_items(parse_page(response, page: 1, operation: operation), key: key, page: 1)
           meta.restart!(total_count: parse_total_count(response.headers))
         end
 
@@ -290,6 +458,11 @@ module Basecamp
 
           capped = false
           items.each_with_index do |item, index|
+            # A followed bare-array page is decoded item by item as each is
+            # KEPT: the reference trims a followed page to the cap before it
+            # decodes anything (client.go:604-631), so an item past the cap is
+            # never decoded there. Page 1 was decoded whole in parse_page.
+            PersonIdSites.decode_item!(item, operation) if page > 1 && key.nil?
             yielded += 1
             capped = max_items && yielded >= max_items
             # Truncation is recorded before the capping yield: consumers like
@@ -318,7 +491,12 @@ module Basecamp
           page += 1
           @hooks.on_paginate(next_url, page)
           response = get(next_url, operation: operation)
-          items = extract_page_items(parse_page(response, page: page), key: key, page: page)
+          # No whole-page decode on a followed page (operation: nil): see
+          # PersonIdSites.decode_item!. A wrapped listing decodes every item
+          # under its key before the cap trims them, as timeline.go:444-465
+          # does; a bare array decodes each kept item in the yield loop above.
+          items = extract_page_items(parse_page(response, page: page, operation: nil), key: key, page: page)
+          items.each { |item| PersonIdSites.decode_item!(item, operation, key: key) } if key
           url = next_url
         end
       end
@@ -338,13 +516,16 @@ module Basecamp
       page.respond_to?(:to_i) && page.to_i.positive?
     end
 
-    # Parses a pagination page body: size check, JSON parse, and person-ID
-    # normalization, with page-numbered error context.
-    def parse_page(response, page:)
+    # Parses a pagination page body: size check, JSON parse, person-ID
+    # normalization, then the operation's typed person-id decode of the whole
+    # page, with page-numbered error context. The whole-page decode is for
+    # page 1, which the reference decodes through Parse<Op>Response; a followed
+    # page passes operation: nil and is decoded per item by the caller.
+    def parse_page(response, page:, operation:)
       Security.check_body_size!(response.body, Security::MAX_RESPONSE_BODY_BYTES)
       data = JSON.parse(response.body)
-      Http.normalize_person_ids(data)
-      data
+      Http.normalize_person_ids(data, embedded_people: response.embedded_people)
+      PersonIdSites.decode!(data, operation)
     rescue JSON::ParserError => e
       # +cause+ carries the parser's own error, not just its message (#750). The
       # message says what happened; the slot is what a caller can act on, and it
@@ -362,20 +543,90 @@ module Basecamp
     # bare-array pagination, or the named key's array otherwise.
     def extract_page_items(data, key:, page:)
       if key.nil?
+        # Bare-array pagination, so the body must BE the array. It was returned
+        # verbatim, and the caller's loop then did `items.each_with_index` on
+        # it: a scalar, a boolean or a null body raised NoMethodError out of a
+        # public list method, and an object returned its key/value pairs as
+        # though they were records. An empty object was the worst of the set,
+        # because it silently paginated to zero items — a composite that reads
+        # "no rows" as "nothing exists" then reports absent what it never
+        # managed to read.
+        # A null body is an EMPTY page, not a malformed one. The reference
+        # decodes JSON `null` into a slice as the nil slice with no error, so a
+        # listing that comes back null is "no rows" there. Rejecting it turned
+        # that into an ApiError and, for Campfire discovery, into a failed read
+        # where the contract has an empty one.
+        return [] if data.nil?
+
+        unless data.is_a?(Array)
+          raise Basecamp::ApiError.new(
+            # The CLASS only. MergeSafe.describe appends up to 500 bytes of the
+            # value, and here the value is a whole paginated page — customer
+            # data in an exception message, which travels into logs and bug
+            # reports. The shape is what a caller needs; the contents are not.
+            "Paginated response (page #{page}) is #{data.class}, not a list",
+            hint: "This operation paginates over a bare JSON array; a body of another shape cannot be read.",
+            retryable: false
+          )
+        end
+
         data
       else
+        # Same rule as the bare-array branch above: the reference decodes JSON
+        # `null` as the zero value, so a null body is an empty page rather than
+        # a malformed one — and anything that is not an object cannot be asked
+        # for a key at all. `data.key?` raised NoMethodError on nil and on a
+        # scalar, and TypeError on an array, straight out of a public method.
+        return [] if data.nil?
+
+        unless data.is_a?(Hash)
+          raise Basecamp::ApiError.new(
+            "Paginated response (page #{page}) is #{data.class}, not an object",
+            hint: "This operation paginates over the #{key.inspect} key of a JSON object; " \
+                  "a body of another shape cannot be read.",
+            retryable: false
+          )
+        end
+
         unless data.key?(key)
           warn "[Basecamp SDK] paginate: expected key '#{key}' not found in response (page #{page})"
         end
-        data[key] || []
+        items = data[key]
+        # The VALUE at the key takes the same rule as the envelope above, and
+        # the guard added with that one stopped a line short. A scalar or a
+        # boolean here reached the caller's `each_with_index` as a native
+        # exception out of a public method, and an OBJECT paginated over its
+        # key/value pairs as though they were records — which is the hazard this
+        # method's own comment writes down for the bare-array branch, live one
+        # `else` away from it.
+        return [] if items.nil?
+
+        unless items.is_a?(Array)
+          raise Basecamp::ApiError.new(
+            "Paginated response (page #{page}) has a #{items.class} at #{key.inspect}, not a list",
+            hint: "This operation paginates over the #{key.inspect} key of a JSON object; " \
+                  "a value of another shape cannot be read.",
+            retryable: false
+          )
+        end
+
+        items
       end
     end
 
     # Parses the X-Total-Count header, returning 0 when absent or malformed.
     def parse_total_count(headers)
-      Integer(headers["X-Total-Count"] || headers["x-total-count"], 10)
-    rescue ArgumentError, TypeError
-      0
+      raw = headers["X-Total-Count"] || headers["x-total-count"]
+      return 0 unless raw.is_a?(String)
+
+      # The reference reads this with Atoi, which takes a signed decimal and
+      # returns 0 on anything else — so a negative, an overflow or a padded
+      # value is 0 there and was the number itself here. And nothing caps a
+      # HEADER: the body has a 50 MB ceiling, so this was the LESS defended of
+      # the sites the person-id sweep hardened, reached on the first response of
+      # every paginated call.
+      count = Ids.bounded_decimal(raw)
+      count.is_a?(Integer) && count.positive? ? count : 0
     end
 
     def build_faraday_client
@@ -391,7 +642,9 @@ module Basecamp
     def request(method, path, params: {}, body: nil, allow_cross_origin: false, operation: nil)
       url = build_url(path, allow_cross_origin: allow_cross_origin)
 
-      # Mutations don't retry on 429/5xx to avoid duplicating data
+      # Mutations don't retry on 429/5xx to avoid duplicating data. A mutation
+      # declared naturally idempotent (CreateStreamTicket) should retry per its
+      # operation metadata instead; routing it here is tracked in #901.
       if method == :get
         request_with_retry(method, url, params: params, allow_cross_origin: allow_cross_origin, operation: operation)
       else
@@ -540,8 +793,13 @@ module Basecamp
         Response.new(
           body: response.body,
           status: response.status,
-          headers: response.headers
+          headers: response.headers,
+          embedded_people: Http.embedded_people_url?(url)
         )
+      rescue Faraday::TimeoutError => e
+        # Faraday::TimeoutError < Faraday::ServerError: named before the status
+        # clause, or a stalled read classifies as a status-less api_error.
+        severed = transport_failure(e, info: info, start_time: start_time, download: download)
       rescue Faraday::ServerError, Faraday::ClientError => e
         duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
         error = handle_error(e, refresh_on_401: refresh_replay)
@@ -571,21 +829,35 @@ module Basecamp
 
         severed = error
       rescue Faraday::Error => e
-        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-        # SPEC §9: on a download hop 1 the Faraday error can render the URL it
-        # failed on, so it is neither the cause nor the hint, and it is raised
-        # below — outside this rescue, with cause: nil — so MRI's implicit
-        # cause is severed too. Every other request keeps its diagnostic.
-        error = download ? Basecamp::NetworkError.new : Basecamp::NetworkError.new("Connection failed", cause: e)
-        @hooks.on_request_end(info, RequestResult.new(duration: duration, error: error))
-        raise error unless download
-
-        severed = error
+        severed = transport_failure(e, info: info, start_time: start_time, download: download)
       end
 
       severed ? raise(severed, cause: nil) : result
     end
 
+    # A transport failure — no HTTP response, so no status to map — as the
+    # network error the caller and on_request_end both see: a timeout by name,
+    # anything else as a connection failure, both retryable (SPEC §6).
+    # download: on hop 1 the Faraday error can render the URL it failed on, so
+    # it is neither the cause nor the hint (SPEC §9), and the error is returned
+    # for the caller to raise outside its rescue with cause: nil, so MRI's
+    # implicit cause is severed too. Every other request keeps its diagnostic
+    # and raises here.
+    def transport_failure(exception, info:, start_time:, download: false)
+      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+      error = if download
+        Basecamp::NetworkError.new
+      else
+        Basecamp::NetworkError.new(transport_failure_message(exception), cause: exception)
+      end
+      @hooks.on_request_end(info, RequestResult.new(duration: duration, error: error))
+      download ? error : raise(error)
+    end
+
+    def transport_failure_message(exception)
+      exception.is_a?(Faraday::TimeoutError) ? "Request timed out" : "Connection failed"
+    end
+
     # accept: nil is the binary-download carve-out (SPEC §14): hop 1 sends
     # Authorization and User-Agent only, because it is not a JSON API call.
     # Every other caller keeps the JSON Accept.
@@ -614,8 +886,11 @@ module Basecamp
         Response.new(
           body: response.body,
           status: response.status,
-          headers: response.headers
+          headers: response.headers,
+          embedded_people: Http.embedded_people_url?(url)
         )
+      rescue Faraday::TimeoutError => e
+        transport_failure(e, info: info, start_time: start_time)
       rescue Faraday::ServerError, Faraday::ClientError => e
         duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
         error = handle_error(e)
@@ -628,11 +903,7 @@ module Basecamp
         @hooks.on_request_end(info, result)
         raise error
       rescue Faraday::Error => e
-        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-        error = Basecamp::NetworkError.new("Connection failed", cause: e)
-        result = RequestResult.new(duration: duration, error: error)
-        @hooks.on_request_end(info, result)
-        raise error
+        transport_failure(e, info: info, start_time: start_time)
       end
     end
 
@@ -682,15 +953,24 @@ module Basecamp
         message = Security.truncate(Basecamp.parse_error_message(body) || "Account limit reached")
         Basecamp::LimitExceededError.new(message, hint: hint)
       when 500
-        Basecamp::ApiError.new("Server error (500)", http_status: 500, retryable: true, hint: hint)
+        Basecamp::ApiError.new("Server error (500)", http_status: 500, retryable: true, hint: hint, retry_after: retry_after)
       when 502, 503, 504
-        Basecamp::ApiError.new("Gateway error (#{status})", http_status: status, retryable: true, hint: hint)
+        # retry_after rides along here as it does on the 429 arm (SPEC §6
+        # "HTTP Status Mapping Algorithm"): request_with_retry reads the delay
+        # off the error, so this is also what makes a 503's Retry-After govern
+        # the sleep rather than the backoff curve.
+        Basecamp::ApiError.new(
+          "Gateway error (#{status})", http_status: status, retryable: true, hint: hint, retry_after: retry_after
+        )
       else
         message = Security.truncate(Basecamp.parse_error_message(body) || "Request failed (HTTP #{status})")
-        Basecamp::ApiError.from_status(status || 0, message, hint: hint)
+        Basecamp::ApiError.from_status(status || 0, message, hint: hint, retry_after: retry_after)
       end
 
       err.instance_variable_set(:@request_id, request_id) if request_id
+      # Every status carries a parsed Retry-After (SPEC §6), including the arms
+      # whose error classes take no such argument.
+      err.instance_variable_set(:@retry_after, retry_after) if retry_after && err.retry_after.nil?
       err
     end
 
@@ -741,18 +1021,43 @@ module Basecamp
       base + jitter
     end
 
-    def parse_retry_after(value)
+    # SPEC §6 MAX_RETRY_AFTER_SECONDS: the value a parsed Retry-After saturates
+    # at, in both wire forms. A representability bound pinned once for all six
+    # SDKs (the narrowest retry_after integer any of them ships, and the ceiling
+    # §16 already names), not a policy cap. Ruby's Integer is arbitrary-
+    # precision, so without it the failure was one layer down: sleep raised
+    # RangeError on the retry path.
+    MAX_RETRY_AFTER_SECONDS = 2_147_483_647
+
+    def parse_retry_after(value, now: Time.now)
       return nil if value.nil? || value.empty?
 
-      # Try parsing as seconds (integer)
-      seconds = Integer(value, exception: false)
-      return seconds if seconds&.positive?
+      # RFC 9110 spells delay-seconds as 1*DIGIT: no sign, which Integer()
+      # would accept. A value over the ceiling saturates whatever its width,
+      # since 1*DIGIT has no upper bound and no digit string is malformed for
+      # its length.
+      if value.match?(/\A\d+\z/)
+        # Bounded before conversion, which is what the reference does here too
+        # — its own comment says "the width test comes before ParseInt so no
+        # conversion can overflow". So this is a contract divergence rather
+        # than a hardening choice: the gate existed there and not here, and the
+        # comment above fixed the consequence (sleep raising on a bignum)
+        # rather than the conversion that produced it.
+        seconds = Ids.bounded_decimal(value, signed: false)
+        return MAX_RETRY_AFTER_SECONDS if seconds == :overflow
+        return nil unless seconds.is_a?(Integer) && seconds.positive?
+
+        return [ seconds, MAX_RETRY_AFTER_SECONDS ].min
+      end
 
-      # Try parsing as HTTP-date
+      # Try parsing as HTTP-date. Rounded UP (SPEC §6 step 2): truncating a
+      # sub-second remainder toward zero turned a date 400ms out into 0, which
+      # reads as "no usable value" and drops onto the backoff curve, and
+      # retried up to a second before the moment the server named.
       begin
         date = Time.httpdate(value)
-        diff = (date - Time.now).to_i
-        return diff if diff.positive?
+        diff = (date - now).ceil
+        return [ diff, MAX_RETRY_AFTER_SECONDS ].min if diff.positive?
       rescue ArgumentError
         # Not a valid HTTP-date
       end
@@ -890,21 +1195,39 @@ module Basecamp
     # @return [Hash] response headers
     attr_reader :headers
 
-    def initialize(body:, status:, headers:)
+    # Whether this response came from one of the reference's two positional
+    # normalization surfaces. See +Http::EMBEDDED_PEOPLE_PATHS+.
+    # @return [Boolean]
+    attr_reader :embedded_people
+
+    def initialize(body:, status:, headers:, embedded_people: false)
       @body = body
       @status = status
       @headers = headers
+      @embedded_people = embedded_people
     end
 
     # Parses the response body as JSON, normalizing Person-shaped objects.
+    #
+    # +operation+ is the channel the generated read path uses to name its
+    # operation for the typed person-id decode ({PersonIdSites}). It is kept
+    # apart from the +operation:+ a GET passes to {Http#get}, which selects the
+    # declared retry policy: a mutation passes none there on purpose, and must
+    # still have its response decoded.
+    #
+    # @param operation [String, nil] canonical operation id whose person-id
+    #   sites to decode; nil decodes none
     # @return [Hash, Array]
-    def json
+    # @raise [ApiError] when a person id at one of the operation's sites
+    #   cannot be decoded
+    def json(operation: nil)
       @json ||= begin
         Security.check_body_size!(@body, Security::MAX_RESPONSE_BODY_BYTES)
         result = JSON.parse(@body)
-        Http.normalize_person_ids(result)
+        Http.normalize_person_ids(result, embedded_people: @embedded_people)
         result
       end
+      PersonIdSites.decode!(@json, operation)
     end
 
     # Returns whether the response was successful (2xx).