basecamp-sdk 0.17.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6831e79b8c78f4ba54ee64287457227c5553fbd2837e71b09d022601084ac2af
-  data.tar.gz: 3dd5ac9aefd6f03e78fa9fa4c9833ac98d217a09a05ea129b8b2b6f3d7049939
+  metadata.gz: c53198686c7bf2b7f9fc25f60c14dec77dada2f3bbf7b6070f9a3e0639f7b529
+  data.tar.gz: f25233709c5a99476ed38728cf9ed005eb55e39457cc6dd4ea3250ac72583e60
 SHA512:
-  metadata.gz: 007f77e92a111a5687b26740caedc75e71e640ddfc10a32057b39b1627ab7cedd2412faebc75647b26402551e7f235b4bf77743236e8ab9da5fc26e8b8286c0b
-  data.tar.gz: dff2430d3c5225c2ad563c0848d61d09a1da0620c58d93438947318f567b2f551548b5a899dfbadb55d14f84b495efb8982f786515c8fd934a885757b5f9db5e
+  metadata.gz: 3d17039b8cddadbbc8ee270f46f0f3e4665651091c0cd0371728693398002dfdc9def64bc081316c496ca477e43a1e2b4e55b65bc53a2d47124694989d5a0437
+  data.tar.gz: 9bf77edeae08a13c60d1f25f3e9d16ad9d39298dffa7cc430fa319aee4ecfa208d62c1c3ccec629473058ac9b48569faea8190b4373313923caa48556a1ab83a

data/README.md

@@ -448,7 +448,7 @@ Only plain GET requests retry — automatically, with exponential backoff. Mutat
 - **Which errors**: A GET issued through a generated service carries its operation ID and is **governed** — status retries are gated on the statuses that operation declares, which is `[429, 503]` for every operation in the current metadata. A governed GET does **not** retry 500. Only the handful of GETs that carry no operation ID (`get_absolute`, OAuth discovery) fall back to the error taxonomy, where 429, 500, 502, 503, 504, and any other 5xx all retry. `NetworkError` (connection failures, including DNS and connect-phase timeouts) retries on both paths, since it has no status to gate on. Read timeouts are the exception: Faraday surfaces them as a status-less `ApiError` with `retryable? == false`, so a GET that times out mid-response fails on the first attempt. 400, 401, 403, 404, and 422 never retry.
 - **`max_retries`**: Total request attempts for GET requests, including the initial request — the default `3` means one initial attempt plus two retries. `max_retries: 0` is floored to a single attempt rather than sending zero requests.
 - **Backoff**: Exponential with jitter — `base_delay * 2^(attempt - 1) + rand * max_jitter` — uncapped, bounded in practice by the attempt budget.
-- **Rate limits**: A 429's `Retry-After` header overrides the calculated backoff. Only 429 carries it: 5xx and network errors always use the exponential backoff.
+- **`Retry-After`**: A `Retry-After` header overrides the calculated backoff at every status the loop is already retrying — a 429, or a retryable 5xx — and `retry_after` is carried on the error at every status, not only 429. Network errors have no header and always use the exponential backoff.
 - **401 responses**: With a refresh-capable token provider, the SDK refreshes the token and replays the request **once** — for all methods, including mutations — outside the `max_retries` budget. A second 401 is surfaced. The raw upload path has no 401 replay.
 - **Per-operation metadata**: Every GET a generated service issues passes its canonical operation ID, so essentially all SDK reads are **governed**: attempts are bounded by `min(config.max_retries, operation max)` and status retries are gated on the operation's declared `retry_on`. The GETs that carry no operation ID — `get_absolute` and the Launchpad authorization fetch it backs — are **ungoverned** and ride the classification-based loop bounded by `config.max_retries` alone. The declared `base_delay_ms` and `backoff` are inert in Ruby either way: the backoff is always the client's. (OAuth discovery uses its own single-attempt transport.)
 - **`retryable?`**: Unlike SDKs where the error classification is only a hint for your own code, in Ruby an error's `retryable?` (and `retry_after`) is exactly what the transport acts on for GET requests.

data/lib/basecamp/api_error.rb

@@ -3,13 +3,14 @@
 module Basecamp
   # Raised for generic API errors.
   class ApiError < Error
-    def initialize(message, http_status: nil, hint: nil, retryable: false, cause: nil)
+    def initialize(message, http_status: nil, hint: nil, retryable: false, retry_after: nil, cause: nil)
       super(
         code: ErrorCode::API,
         message: message,
         hint: hint,
         http_status: http_status,
         retryable: retryable,
+        retry_after: retry_after,
         cause: cause
       )
     end
@@ -18,11 +19,12 @@ module Basecamp
     # @param status [Integer] HTTP status code
     # @param message [String, nil] optional error message
     # @param hint [String, nil] optional hint (SPEC section 6 step 3)
+    # @param retry_after [Integer, nil] seconds from a parsed Retry-After header
     # @return [ApiError]
-    def self.from_status(status, message = nil, hint: nil)
+    def self.from_status(status, message = nil, hint: nil, retry_after: nil)
       message ||= "Request failed (HTTP #{status})"
       retryable = status >= 500 && status < 600
-      new(message, http_status: status, hint: hint, retryable: retryable)
+      new(message, http_status: status, hint: hint, retryable: retryable, retry_after: retry_after)
     end
   end
 end

data/lib/basecamp/bucket_mismatch_error.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Raised when the recording a typed read returned lives in a different bucket
+  # from the one the pointer named, so a pointer from one project can never
+  # resolve to a recording in another.
+  #
+  # +code+ is +usage+ with +retryable+ false, settled across every port on
+  # card 41[https://app.basecamp.com/2914079/buckets/48699913/card_tables/cards/10308966794] after
+  # Rust shipped +not_found+ where this port and three others shipped +usage+.
+  # The read succeeded and the API answered honestly — it FOUND the recording,
+  # in another bucket, and returned it, so nothing is absent and +not_found+
+  # would be a false claim. It is the caller's pointer that disagreed with it.
+  class BucketMismatchError < RecordingSummaryError
+    KIND = "bucket_mismatch"
+
+    # @return [Integer] the bucket the pointer named
+    attr_reader :bucket_id
+
+    # @return [Integer] the bucket the read returned
+    attr_reader :actual_bucket_id
+
+    # @return [Integer] the recording's id
+    attr_reader :recording_id
+
+    # @param bucket_id [Integer] the bucket the pointer named
+    # @param actual_bucket_id [Integer] the bucket the read returned
+    # @param recording_id [Integer]
+    def initialize(bucket_id:, actual_bucket_id:, recording_id:)
+      super(
+        kind: KIND,
+        code: ErrorCode::USAGE,
+        message: "recording is not in the requested bucket: recording #{recording_id} is in bucket " \
+                 "#{actual_bucket_id}, not #{bucket_id}"
+      )
+      @bucket_id = bucket_id
+      @actual_bucket_id = actual_bucket_id
+      @recording_id = recording_id
+    end
+  end
+end

data/lib/basecamp/campfire_discovery_incomplete_error.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Raised when a chat line's Campfire discovery could not be carried to a
+  # conclusion — the account-wide Campfire listing overflowed
+  # +CampfireIndex::MAX_LISTING+, or the bucket has more visible Campfires than
+  # +RecordingsExtensions::MAX_CAMPFIRE_CANDIDATES+.
+  #
+  # Deliberately distinct from {UnresolvedRecordingError}: candidates were left
+  # unsearched, so nothing can be reported absent. Nothing left unsearched is
+  # ever called missing.
+  #
+  # +code+ is +usage+ with +retryable+ false, settled across every port on
+  # card 40[https://app.basecamp.com/2914079/buckets/48699913/card_tables/cards/10308122086]
+  # after the merged ports shipped two different answers.
+  #
+  # +usage+ is one of only three coarse codes no HTTP response can produce —
+  # the status mapping yields +auth_required+, +forbidden+, +not_found+,
+  # +rate_limit+, +validation+, +limit_exceeded+ and +api_error+, and +network+
+  # and +ambiguous+ are equally unreachable from a status. +usage+ is the one of
+  # those three that also describes a call the SDK declined to complete, which
+  # is why it and not the other two. A verdict the composite reached on its own
+  # therefore can never be read back as a constituent read's own answer. This
+  # port previously said +api_error+, which a caller could not tell from a 500
+  # one of those reads returned.
+  #
+  # Retryability is a separate field and is unchanged: false, because the call
+  # reached no verdict and no argument the caller can change would produce one
+  # — the bounds are the SDK's, both reasons are deterministic for the same
+  # account state, and a retry loop would re-run the identical search forever.
+  class CampfireDiscoveryIncompleteError < RecordingSummaryError
+    KIND = "campfire_discovery_incomplete"
+
+    # @return [Integer] the bucket the pointer named
+    attr_reader :bucket_id
+
+    # @return [Integer] the chat line's id
+    attr_reader :recording_id
+
+    # @return [String] why discovery stopped short
+    attr_reader :reason
+
+    # @param bucket_id [Integer]
+    # @param recording_id [Integer]
+    # @param reason [String]
+    def initialize(bucket_id:, recording_id:, reason:)
+      super(
+        kind: KIND,
+        code: ErrorCode::USAGE,
+        message: "campfire discovery incomplete: line #{recording_id} in bucket #{bucket_id}: #{reason}"
+      )
+      @bucket_id = bucket_id
+      @recording_id = recording_id
+      @reason = reason
+    end
+  end
+end

data/lib/basecamp/campfire_index.rb

@@ -0,0 +1,398 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # The two Campfire discovery sources a chat line's read needs, each cached.
+  #
+  # A +chat.line.created+ row carries the line's id and bucket, not its
+  # Campfire, and the line read is +/chats/{campfireId}/lines/{lineId}+.
+  # Candidates come from two sources, tried in order and each cached {TTL}
+  # seconds:
+  #
+  # 1. The bucket's project dock, whose "chat" tool is the project's Campfire:
+  #    one project read per bucket, and the answer for every line posted in a
+  #    project. Cached per bucket.
+  # 2. The account-wide Campfire listing (BC3 has no per-bucket one), filtered
+  #    to the bucket, for buckets that are not projects or whose dock did not
+  #    hold the line. Cached per account, so a burst of lines costs one listing.
+  #
+  # This class holds the caching only; the reads themselves are passed in as
+  # blocks by +RecordingsExtensions+, so every request still goes through a
+  # generated service method (SPEC section 18 rule 1) and this file touches no
+  # wire.
+  #
+  # It lives on {Client}, shared by every {AccountClient} that client hands out.
+  # A Client is bound to one credential, so entries are never shared across
+  # authorization contexts, and every key carries the account id anyway. Expired
+  # snapshots are swept at each publication and each cache is bounded
+  # ({MAX_ITEMS}, oldest fetched out first), so the index holds at most the
+  # buckets and accounts consulted within the last TTL, and never more than the
+  # bound, whatever the Client has seen.
+  class CampfireIndex
+    # How long a cached discovery source — a bucket's project dock, the
+    # account's Campfire listing — is reused before it is read again.
+    TTL = 600.0
+
+    # Bounds the refresh-on-miss: a line found under no candidate re-reads the
+    # cached sources, but not more often than this per source, so a run of
+    # unresolvable lines cannot turn into a listing per line.
+    # +UnresolvedRecordingError#refreshed?+ says whether the floor applied.
+    MIN_REFRESH = 30.0
+
+    # Caps the account-wide Campfire listing the fallback source reads. A
+    # listing that overflows it is not cached and the call reports
+    # {CampfireDiscoveryIncompleteError}: the dock covers every project, so the
+    # listing only ever serves the leftover, and an account with more Campfires
+    # than this should not pay a full walk per TTL for it.
+    MAX_LISTING = 1000
+
+    # Bounds each cache's entry count. The dock cache holds one snapshot per
+    # bucket consulted within the TTL: a connector listening across every
+    # project an agent can see touches hundreds of buckets, not thousands, and a
+    # snapshot is a handful of ids, so this is generous headroom at a few
+    # hundred KB. The bound exists so that a process alive for weeks can never
+    # grow past it whatever it sees. When the bound is reached the
+    # oldest-fetched entries go first, deterministically.
+    MAX_ITEMS = 1024
+
+    # Raised by the listing loader when the account-wide listing overflows
+    # {MAX_LISTING}. +RecordingsExtensions+ turns it into the typed
+    # {CampfireDiscoveryIncompleteError}; it is never cached, so the next call
+    # re-reads rather than remembering a verdict it never reached.
+    class ListingOverflow < StandardError; end
+
+    # One consultation of a discovery source: the candidate ids it holds for the
+    # bucket, when that snapshot was fetched, and whether it predated the call.
+    SourceRead = Struct.new(:ids, :fetched, :cached, keyword_init: true) do
+      # @return [Boolean] whether the snapshot predated this call
+      def cached?
+        cached
+      end
+    end
+
+    # @param clock [#call, nil] monotonic seconds, injectable for tests
+    def initialize(clock: nil)
+      @docks = TTLCache.new(ttl: TTL, floor: MIN_REFRESH, max_items: MAX_ITEMS, clock: clock)
+      @listings = TTLCache.new(ttl: TTL, floor: MIN_REFRESH, max_items: MAX_ITEMS, clock: clock)
+    end
+
+    # The Campfire ids a bucket's project dock names.
+    #
+    # @param account_id [String]
+    # @param bucket_id [Integer]
+    # @param refresh [Boolean] re-read a cached snapshot older than {MIN_REFRESH}
+    # @yieldreturn [Array<Integer>] the dock's Campfire ids
+    # @return [SourceRead]
+    def dock_campfires(account_id:, bucket_id:, refresh: false, &load)
+      hit = @docks.get([ account_id, bucket_id ], refresh: refresh, &load)
+      SourceRead.new(ids: Array(hit.value), fetched: hit.fetched, cached: hit.cached)
+    end
+
+    # The Campfire ids the CACHED account-wide listing shows in a bucket,
+    # without fetching. nil when the listing is not cached or has expired.
+    #
+    # It exists so a caller can consult what the source already holds before
+    # deciding whether to pay for the listing fetch — the expensive, slow
+    # request, which the dock (including its refresh) should get to pre-empt.
+    #
+    # @param account_id [String]
+    # @param bucket_id [Integer]
+    # @return [SourceRead, nil]
+    def cached_listed_campfires(account_id:, bucket_id:)
+      hit = @listings.peek(account_id)
+      return nil if hit.nil?
+
+      SourceRead.new(ids: Array(hit.value[bucket_id]).dup, fetched: hit.fetched, cached: true)
+    end
+
+    # The Campfire ids the account-wide listing shows in a bucket.
+    #
+    # @param account_id [String]
+    # @param bucket_id [Integer]
+    # @param refresh [Boolean] re-read a cached snapshot older than {MIN_REFRESH}
+    # @yieldreturn [Hash{Integer => Array<Integer>}] campfire ids by bucket id
+    # @return [SourceRead]
+    # @raise [ListingOverflow] when the loader reports the listing was truncated
+    def listed_campfires(account_id:, bucket_id:, refresh: false, &load)
+      hit = @listings.get(account_id, refresh: refresh, &load)
+      SourceRead.new(ids: Array(hit.value[bucket_id]).dup, fetched: hit.fetched, cached: hit.cached)
+    end
+
+    # A per-key cache with single-flight loading: concurrent callers for one key
+    # wait on the one load in progress rather than loading again, and a refresh
+    # is honoured only once the value is older than a floor.
+    #
+    # A load that FAILS leaves the previous value in place and its error is
+    # shared with the waiters, so N callers never re-run one failed load N
+    # times. A load that was ABANDONED — the loading thread killed, or unwound
+    # by something that is not a StandardError — is the one exception: a waiter
+    # goes round once and loads for itself, because that outcome says nothing
+    # about whether the waiter's own call can succeed. See {LoaderAbandoned},
+    # which explains why the two can be told apart here.
+    class TTLCache
+      # Raised when a load left without publishing an outcome of its own — the
+      # loading thread was killed, or unwound by something that is not a
+      # StandardError, +Timeout.timeout+ included (it raises
+      # +Timeout::ExitException+ INSIDE the block and only becomes a
+      # +Timeout::Error+ at its own frame, so no rescue here ever sees it).
+      #
+      # It is a {Basecamp::Error} so that +rescue Basecamp::Error+ around a
+      # composite catches it like everything else, with +api_error+ and
+      # +retryable+ — the load reached no verdict and the key is free, so the
+      # next call loads for itself.
+      #
+      # A waiter does not normally re-run another caller's failed load, but this
+      # one it does, once: the classification is unambiguous here in a way Go's
+      # two-part +callerDone+ had to work for. A transport failure is a
+      # StandardError and is shared as the load's own; only a genuinely
+      # non-local unwind of the LOADING thread reaches this, and that says
+      # nothing about whether the waiter's own call can succeed. Without the
+      # re-run, one caller's +Timeout.timeout+ fails every concurrent waiter on
+      # a key the whole account shares.
+      class LoaderAbandoned < Error
+        def initialize(message = "cache loader did not complete")
+          super(code: ErrorCode::API, message: message, retryable: true)
+        end
+      end
+
+      # What a cache read hands back: the value, when it was fetched, and
+      # whether it predated the call (as opposed to being loaded during it, by
+      # this caller or by one it waited on). The fetch time is what lets a
+      # caller tell a snapshot it already consulted from a newer one, whoever
+      # loaded it.
+      Hit = Struct.new(:value, :fetched, :cached, keyword_init: true)
+
+      Entry = Struct.new(:value, :fetched, :seq, keyword_init: true)
+
+      # How many times one {#get} may try. Two: the call itself, plus the single
+      # re-run a waiter is allowed when the load it woke on was abandoned.
+      MAX_ATTEMPTS = 2
+
+      # The clock is MONOTONIC, never wall time. A backwards step in wall time —
+      # an NTP correction, a VM resume — would make an entry outlive its TTL,
+      # decline a refresh that is genuinely due, and take the `refreshed` and
+      # stale-candidate signals down with it, none of which surfaces as an
+      # error. The injected clock in tests is monotonic in the same sense: it
+      # only ever moves forward.
+      #
+      # @param ttl [Float] seconds a value is reused for
+      # @param floor [Float] seconds a refresh must wait before it is honoured
+      # @param max_items [Integer] entry bound; 0 or less disables eviction
+      # @param clock [#call, nil] monotonic seconds, injectable for tests
+      # @param on_wait [#call, nil] a test seam, called while the cache's lock
+      #   is held and immediately before a waiter releases it to wait. It is how
+      #   a test knows a waiter has REACHED the wait rather than guessing from
+      #   Thread#status, which reports a thread merely blocked on the lock as
+      #   sleeping too. The reference implementation carries a seam for the same
+      #   reason, though it calls its own after releasing the lock, which leaves
+      #   the waiter able to be descheduled before it waits; under the lock is
+      #   the stronger barrier and the reason this one is placed there. It also
+      #   means a seam that BLOCKS would wedge the cache — never set in
+      #   production, and never anything but a signal in a test.
+      def initialize(ttl:, floor:, max_items:, clock: nil, on_wait: nil)
+        @ttl = ttl
+        @floor = floor
+        @max_items = max_items
+        @on_wait = on_wait
+        @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @entries = {}
+        @inflight = {}
+        @seq = 0
+      end
+
+      # Returns the value for key, loading it when absent or older than the TTL
+      # — or, with +refresh+ set, older than the floor.
+      #
+      # @param key [Object]
+      # @param refresh [Boolean]
+      # @yieldreturn [Object] the loaded value
+      # @return [Hit]
+      def get(key, refresh: false)
+        # Two attempts, not a loop with a counter, and deliberately not
+        # Kernel#loop. The bound IS the retry rule — a waiter may load for
+        # itself once when the load it woke on was abandoned — so spelling it as
+        # the iteration count leaves nothing to drift. Kernel#loop would also
+        # rescue StopIteration out of the caller's loader and return its result
+        # in place of a Hit, turning a raise into a silently wrong answer.
+        MAX_ATTEMPTS.times do |attempt|
+          owner = false
+          pending = nil
+          published = false
+
+          # The ensure encloses the REGISTRATION, not just the loader. A loader
+          # that leaves by anything the rescue below does not catch — Interrupt,
+          # a signal, NoMemoryError, a Thread#kill that raises nothing at all —
+          # would otherwise leave the key in flight forever, and since {#await}
+          # waits with no timeout, every later caller for that key would park on
+          # it permanently rather than erroring. The listing's key is the bare
+          # account id, so that is one killed thread wedging chat-line discovery
+          # for a whole account for the life of the process. Go publishes from a
+          # deferred recover for exactly this reason — and an ensure that began
+          # after the key was registered would leave the same hole a few
+          # instructions wide.
+          begin
+            @mutex.synchronize do
+              entry = @entries[key]
+              if entry
+                age = @clock.call - entry.fetched
+                if age < @ttl && (!refresh || age < @floor)
+                  return Hit.new(value: entry.value, fetched: entry.fetched, cached: true)
+                end
+              end
+
+              pending = @inflight[key]
+              if pending.nil?
+                pending = { done: false, error: nil, value: nil, fetched: nil }
+                # Ownership is claimed BEFORE the key is registered, so an
+                # interrupt between the two leaves the ensure publishing a
+                # record that was never registered — which {#publish} ignores,
+                # because it only ever evicts its own.
+                owner = true
+                @inflight[key] = pending
+              end
+            end
+
+            unless owner
+              begin
+                return await(pending)
+              rescue LoaderAbandoned
+                # DELIBERATE, and the one place a waiter does not simply take
+                # the outcome it woke on. The load did not fail, it was
+                # abandoned — see {LoaderAbandoned} for why Ruby can tell those
+                # apart where Go needed a two-part test — so this caller goes
+                # round and loads for itself. On the last attempt it is raised
+                # rather than chased, so a run of abandoned owners cannot become
+                # a queue of sequential loads behind one waiter.
+                raise if attempt == MAX_ATTEMPTS - 1
+              end
+              next
+            end
+
+            value = yield
+            publish(key, pending, value, nil)
+            published = true
+            return Hit.new(value: value, fetched: pending[:fetched], cached: false)
+          rescue StandardError => e
+            publish(key, pending, nil, e) if owner
+            published = true
+            raise
+          ensure
+            publish(key, pending, nil, LoaderAbandoned.new) if owner && !published
+          end
+        end
+
+        # Unreachable: the last attempt either returns or raises. Stated so a
+        # future edit that breaks that cannot fall out of here with a value
+        # nobody meant.
+        raise LoaderAbandoned.new("cache load did not settle in #{MAX_ATTEMPTS} attempts")
+      end
+
+      # Returns the cached value for key when one is within the TTL, without
+      # loading.
+      #
+      # @param key [Object]
+      # @return [Hit, nil]
+      def peek(key)
+        @mutex.synchronize do
+          entry = @entries[key]
+          return nil if entry.nil? || (@clock.call - entry.fetched) >= @ttl
+
+          Hit.new(value: entry.value, fetched: entry.fetched, cached: true)
+        end
+      end
+
+      private
+
+      # Waits on another caller's load and hands its outcome over.
+      #
+      # The value is read off the load record, not out of the cache, so a sweep
+      # or the entry bound evicting the entry in the meantime cannot take it
+      # from this waiter. It is reported as loaded during this call rather than
+      # as something that predated it, because it was.
+      def await(pending)
+        @mutex.synchronize do
+          until pending[:done]
+            # Signalled under the lock, so a test that has seen it knows this
+            # thread reaches the wait before any other thread can take the lock
+            # and publish.
+            @on_wait&.call
+            @condition.wait(@mutex)
+          end
+        end
+        raise pending[:error] if pending[:error]
+
+        Hit.new(value: pending[:value], fetched: pending[:fetched], cached: false)
+      end
+
+      # Releases the key and wakes the waiters. A failed load publishes no entry,
+      # so the previous value — if any — stays in place and keeps serving until
+      # its own TTL runs out.
+      def publish(key, pending, value, error)
+        @mutex.synchronize do
+          # Idempotent, so publication survives being interrupted. An async
+          # exception landing between the load returning and this call
+          # completing would otherwise let {#get}'s ensure publish a second time
+          # and overwrite a good value with an abandonment error. Whichever
+          # publication lands first is the outcome; the rest only wake the
+          # waiters again.
+          #
+          # The repeat still broadcasts, and that is the point of doing it here
+          # rather than returning bare: an interrupt landing between the flag
+          # below and its broadcast would otherwise leave a record marked done
+          # with everybody still parked on it.
+          if pending[:done]
+            @condition.broadcast
+            return
+          end
+
+          # Only this call's own registration. An abandonment publish for a
+          # record that never made it into the map — the interrupt window the
+          # ensure covers — would otherwise delete whatever ANOTHER thread has
+          # since registered under the key, dropping its single-flight guarantee
+          # while it is still loading. The listing's key is the bare account id,
+          # so that is process-wide.
+          @inflight.delete(key) if @inflight[key].equal?(pending)
+          pending[:error] = error
+          if error.nil?
+            pending[:value] = value
+            pending[:fetched] = @clock.call
+            sweep_locked
+            make_room_locked(key)
+            @seq += 1
+            @entries[key] = Entry.new(value: value, fetched: pending[:fetched], seq: @seq)
+          end
+          pending[:done] = true
+          @condition.broadcast
+        end
+      end
+
+      # Drops every entry past its TTL. Runs at each publication — the one
+      # moment the cache does work proportional to a miss anyway — so a
+      # long-lived Client that has seen many buckets keeps a snapshot for at most
+      # a TTL past its last use plus the interval to the next load on any key,
+      # rather than for its lifetime.
+      def sweep_locked
+        now = @clock.call
+        @entries.delete_if { |_key, entry| (now - entry.fetched) >= @ttl }
+      end
+
+      # Evicts the oldest-fetched entries until the one about to be stored for
+      # +key+ fits under the bound — oldest by fetch time, and by publication
+      # order among equals, so the choice is total rather than whatever hash
+      # order happens to come first. Oldest-first is also the right order: the
+      # entry nearest its TTL is the one least worth keeping.
+      def make_room_locked(key)
+        return if @max_items <= 0
+        return if @entries.key?(key) # an overwrite takes no new room
+
+        while @entries.size >= @max_items
+          oldest = @entries.min_by { |_k, entry| [ entry.fetched, entry.seq ] }
+          break if oldest.nil?
+
+          @entries.delete(oldest.first)
+        end
+      end
+    end
+  end
+end

data/lib/basecamp/client.rb

@@ -96,6 +96,23 @@ module Basecamp
     def account_id
       nil
     end
+
+    # @api private
+    # The Campfire discovery caches used by +recordings.summarize+ when it
+    # resolves a chat line.
+    #
+    # It lives here rather than on {AccountClient} so a burst of lines costs one
+    # project read per bucket and one account-wide listing, however many
+    # AccountClients this Client has handed out. A Client is bound to one
+    # credential, so entries are never shared across authorization contexts, and
+    # every key carries the account id anyway.
+    #
+    # @return [CampfireIndex]
+    def campfire_index
+      @mutex.synchronize do
+        @campfire_index ||= CampfireIndex.new
+      end
+    end
   end
 
   # HTTP client bound to a specific Basecamp account.
@@ -142,6 +159,14 @@ module Basecamp
       @parent.http
     end
 
+    # @api private
+    # The parent Client's Campfire discovery caches, shared by every
+    # AccountClient it handed out. See {Client#campfire_index}.
+    # @return [CampfireIndex]
+    def campfire_index
+      @parent.campfire_index
+    end
+
     # @api private
     # @return [Hooks] the observability hooks
     def hooks
@@ -311,8 +336,12 @@ module Basecamp
 
         else
           # This shouldn't happen because Faraday's raise_error middleware
-          # handles 4xx/5xx, but handle it defensively
-          raise Basecamp.error_from_response(response.status, response.body)
+          # handles 4xx/5xx, but handle it defensively — carrying the parsed
+          # Retry-After as every other mapping does (SPEC §6).
+          raise Basecamp.error_from_response(
+            response.status, response.body,
+            retry_after: http.parse_retry_after_header(response.headers["Retry-After"] || response.headers["retry-after"])
+          )
         end
       rescue => e
         duration = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
@@ -507,6 +536,12 @@ module Basecamp
       service(:bookmarks) { Services::BookmarksService.new(self) }
     end
 
+    # The account event feed, the agent inbox, and stream tickets (SPEC §23 wire layer).
+    # @return [Services::EventFeedService]
+    def event_feed
+      service(:event_feed) { Services::EventFeedService.new(self) }
+    end
+
     # @return [Services::BubbleUpsService]
     def bubble_ups
       service(:bubble_ups) { Services::BubbleUpsService.new(self) }
@@ -674,14 +709,22 @@ module Basecamp
         raise NetworkError.new("Download failed"), cause: nil
       end
 
+      # Hop 2 is never retried, but its error still carries the parsed
+      # Retry-After like every other mapped status (SPEC §6): a caller
+      # rescheduling the download themselves reads it off whatever came back.
+      retry_after = http.parse_retry_after_header(response["Retry-After"])
+
       # The exact set hop 1 dispatches on, not Net::HTTPRedirection — that
       # class also covers 304, which is a cache answer, not a redirect.
       if [ 301, 302, 303, 307, 308 ].include?(response.code.to_i)
-        raise ApiError.new("redirect #{response.code} on the signed download hop is not followed", http_status: response.code.to_i)
+        raise ApiError.new(
+          "redirect #{response.code} on the signed download hop is not followed",
+          http_status: response.code.to_i, retry_after: retry_after
+        )
       end
 
       unless response.is_a?(Net::HTTPSuccess)
-        raise ApiError.new("download failed with status #{response.code}", http_status: response.code.to_i)
+        raise ApiError.new("download failed with status #{response.code}", http_status: response.code.to_i, retry_after: retry_after)
       end
 
       response