lex-microsoft_teams 0.6.50 → 0.6.51

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35010357ecbf55560b6957ae2467c5975eec04056da102a34b1d4c870a0f1ce3
-  data.tar.gz: 38d375c241ba2691948bf6d80f275410f0a1003e0e7456852f3bc2ca1bf4acce
+  metadata.gz: 76994e2ead987d49e26c776ff30d9e6a2b78789a12654d38e80e36e81814d703
+  data.tar.gz: ebf842a7daf81e017078e894d111d38f9474ecc1b3ced0f4105cea29dfb1b7fb
 SHA512:
-  metadata.gz: ae71a656141975e85dc7b5e294e99d7d5a1f67a34e57feea943f177d4bf1c31224ef462adc5140163f6cb028ca1fede816fa713c25185522d8718fe01631a0af
-  data.tar.gz: b2e865c65531f7d464d7f058c2e8d965b1ca96643ca15bee7a6018c0dd260d7477771b0418404f9a6dd0ef8fc8dd983d8c68d0a06704fb2432af031d377150d6
+  metadata.gz: ac9c034b99ef410ab0c1727f83409cd8d8d063b20082ace208be85e0a1bbd4c8314b983caf4c2a80af82d9ca6245e3616d67dae3f60cdff4a204bea087b2d777
+  data.tar.gz: 1b13b4c36751a4dd02888c3867acafd0594d6a1a83e00668481a07533997de3bfce5abd68b66fc56adbb5bce6006601d1994daa16ebdb3738bd9309f0ff244a1

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.6.51] - 2026-05-27
+### Added
+- `Faraday::RetryAfter` middleware honoring `Retry-After` per RFC 9110 §10.2.3 (originally RFC 7231 §7.1.3) in both delta-seconds and HTTP-date forms. Retries HTTP 429 by default; 503/504 opt-in. Bounded by `max_retries` and cumulative `max_wait`; ±jitter on advertised wait to avoid thundering-herd. Configurable via `microsoft_teams.client.retry.{max_retries,max_wait,jitter,fallback_wait,retry_statuses}`; `fetch` semantics preserve explicit falsey values.
+- `Errors::Throttled` exception with `status`, `retry_after` (nullable; `nil` distinguishes "no server guidance" from "retry immediately"), `retry_after_known?` predicate, `request`, and `attempts`.
+- `Faraday::RetryAfter.parse_header` shared class method (single source of truth for Retry-After parsing).
+- `default_settings` for all actors with explicit `enabled`, `interval`, and tuning knobs. Actors no longer need nil guards — values are guaranteed by the extension settings merge on boot. Defaults: `api_ingest` 3600s, `incremental_sync` 900s, `presence_poller` disabled, `channel_poller` disabled, `direct_chat_poller` disabled, `observed_chat_poller` disabled, `meeting_ingest` 900s, `profile_ingest` enabled (once on boot).
+- `Helpers::GraphCache` module — `cached_graph_get` wraps Graph API calls with `Legion::Cache` TTL-based caching. Supports `shared: true` for resource-scoped endpoints (e.g., `/chats/{id}/members` — same data for all participants) vs user-scoped for `/me/*` endpoints. Cache keys incorporate the process identity UUID to prevent cross-user leakage.
+
+### Fixed
+- Stuck or chatty consumers no longer brown out other users on the same Entra app registration's Graph quota. The `RetryAfter` middleware now raises `Errors::Throttled` **centrally on exhaustion** — every consumer of `graph_connection` and `bot_connection` gets the typed event without per-callsite handling. Fixes #18.
+- `Helpers::GraphClient#handle_graph_response` retains a defensive 429/503/504 branch that raises `Errors::Throttled` for callers that build a Faraday connection without the middleware (custom tests, ad-hoc tooling).
+- Logger acquisition failures no longer silently drop retry telemetry — falls back to `Legion::Logging` unconditionally; loss of those signals was how the original outage went undiagnosed for days.
+- **O(N×M) member scan eliminated** — `ProfileIngest#find_chat_for_person` and `ApiIngest#match_chat_to_person` previously called `GET /chats/{id}/members` for every chat × every person (up to 500+ calls per tick). Replaced with `build_chat_member_index` that fetches members once per chat and builds an in-memory lookup hash. Reduces ~514 calls/tick to ~50 for `IncrementalSync`; ~7,500 calls/tick to ~65 for `ApiIngest`.
+- `IncrementalSync` interval raised from 120s to 900s (was the single largest source of sustained Graph pressure).
+- `ApiIngest` interval raised from 1800s to 3600s.
+- Actors that were accidentally re-enabled by `952607c` (rubocop removed `return false` guards) are now properly gated by `settings[:actor_name][:enabled]` — `presence_poller`, `channel_poller`, `direct_chat_poller`, and `observed_chat_poller` all default to `false`.
+
+### Known follow-up
+- Actors (`*_poller.rb`, `meeting_ingest`, `profile_ingest`) still catch `Errors::Throttled` via the generic `rescue StandardError` block but do not yet *defer their next scheduled run* using the carried `retry_after`. To be addressed in a follow-up issue.
+
 ## [0.6.50] - 2026-05-27
 ### Added
 - Full OData query parameter support across all Graph API runner methods per Microsoft Graph REST v1.0 docs

data/lib/legion/extensions/microsoft_teams/actors/api_ingest.rb

@@ -27,12 +27,12 @@ module Legion
           end
 
           def time
-            interval = teams_settings.dig(:ingest, :api_interval) || 1800
-            interval.to_i
+            teams_settings.dig(:api_ingest, :interval)
           end
 
           def enabled?
-            defined?(Legion::Extensions::Agentic::Memory::Trace::Runners::Traces)
+            teams_settings.dig(:api_ingest, :enabled) &&
+              defined?(Legion::Extensions::Agentic::Memory::Trace::Runners::Traces)
           rescue StandardError => e
             handle_exception(e, level: :warn, operation: 'ApiIngest#enabled?')
             false
@@ -46,13 +46,13 @@ module Legion
               return
             end
 
-            ingest = teams_settings[:ingest] || {}
+            ai_settings = teams_settings[:api_ingest]
             log.info('ApiIngest: starting Graph API ingest')
             result = runner_class.ingest_api(
               token:          token,
-              top_people:     ingest.fetch(:top_people, 15),
-              message_depth:  ingest.fetch(:message_depth, 50),
-              skip_bots:      ingest.fetch(:skip_bots, true),
+              top_people:     ai_settings[:top_people],
+              message_depth:  ai_settings[:message_depth],
+              skip_bots:      ai_settings[:skip_bots],
               imprint_active: imprint_active?
             )
             log.info("ApiIngest: #{result.inspect[0, 200]}")
@@ -75,12 +75,7 @@ module Legion
           end
 
           def teams_settings
-            return {} unless defined?(Legion::Settings)
-
-            Legion::Settings[:microsoft_teams] || {}
-          rescue StandardError => e
-            handle_exception(e, level: :warn, operation: 'ApiIngest#teams_settings')
-            {}
+            settings
           end
 
           def imprint_active?

data/lib/legion/extensions/microsoft_teams/actors/channel_poller.rb

@@ -7,10 +7,6 @@ module Legion
         class ChannelPoller < Legion::Extensions::Actors::Every
           include Legion::Extensions::MicrosoftTeams::Helpers::Client
 
-          DEFAULT_INTERVAL       = 60
-          DEFAULT_MAX_TEAMS      = 10
-          DEFAULT_MAX_CHANNELS   = 5
-
           def initialize(**opts)
             return unless enabled?
 
@@ -20,7 +16,7 @@ module Legion
 
           def runner_class    = self.class
           def runner_function = 'manual'
-          def time            = channel_setting(:poll_interval, DEFAULT_INTERVAL)
+          def time            = settings.dig(:channel_poller, :interval)
           def delay           = 300
           def run_now?        = false
           def use_runner?     = false
@@ -36,7 +32,7 @@ module Legion
           end
 
           def enabled?
-            # channel_setting(:enabled, false) == true
+            settings.dig(:channel_poller, :enabled)
           rescue StandardError => e
             handle_exception(e, level: :debug, operation: 'ChannelPoller#enabled?')
             false
@@ -148,11 +144,11 @@ module Legion
           end
 
           def max_teams
-            channel_setting(:max_teams, DEFAULT_MAX_TEAMS)
+            settings.dig(:channel_poller, :max_teams)
           end
 
           def max_channels_per_team
-            channel_setting(:max_channels_per_team, DEFAULT_MAX_CHANNELS)
+            settings.dig(:channel_poller, :max_channels_per_team)
           end
 
           def delegated_token
@@ -162,17 +158,8 @@ module Legion
             nil
           end
 
-          def channel_setting(key, default)
-            return default unless defined?(Legion::Settings)
-
-            Legion::Settings.dig(:microsoft_teams, :channels, key) || default
-          rescue StandardError => e
-            handle_exception(e, level: :debug, operation: "ChannelPoller#channel_setting(#{key})")
-            default
-          end
-
           def channel_traces_enabled?
-            channel_setting(:store_traces, false) == true
+            settings.dig(:channel_poller, :store_traces) == true
           end
 
           def store_channel_message_trace(team_name:, channel_name:, msg:)

data/lib/legion/extensions/microsoft_teams/actors/direct_chat_poller.rb

@@ -8,8 +8,6 @@ module Legion
           include Legion::Extensions::MicrosoftTeams::Helpers::Client
           include Legion::Extensions::MicrosoftTeams::Helpers::HighWaterMark
 
-          POLL_INTERVAL = 15
-
           def initialize(**opts)
             return unless enabled?
 
@@ -19,7 +17,7 @@ module Legion
 
           def runner_class    = Legion::Extensions::MicrosoftTeams::Runners::Bot
           def runner_function = 'handle_message'
-          def time            = settings_interval(:direct_poll_interval, POLL_INTERVAL)
+          def time            = settings.dig(:direct_chat_poller, :interval)
           def delay           = 60
           def run_now?        = false
           def use_runner?     = false
@@ -27,7 +25,8 @@ module Legion
           def generate_task?  = false
 
           def enabled?
-            defined?(Legion::Extensions::MicrosoftTeams::Runners::Bot) &&
+            settings.dig(:direct_chat_poller, :enabled) &&
+              defined?(Legion::Extensions::MicrosoftTeams::Runners::Bot) &&
               Legion.const_defined?(:Transport, false)
           rescue StandardError => e
             handle_exception(e, level: :debug, operation: 'DirectChatPoller#enabled?')
@@ -95,9 +94,7 @@ module Legion
           end
 
           def bot_id_from_settings
-            return nil unless defined?(Legion::Settings)
-
-            Legion::Settings.dig(:microsoft_teams, :bot, :bot_id)
+            settings.dig(:bot, :bot_id)
           end
 
           def delegated_token
@@ -106,12 +103,6 @@ module Legion
             handle_exception(e, level: :warn, operation: 'DirectChatPoller#delegated_token')
             nil
           end
-
-          def settings_interval(key, default)
-            return default unless defined?(Legion::Settings)
-
-            Legion::Settings.dig(:microsoft_teams, :bot, key) || default
-          end
         end
       end
     end

data/lib/legion/extensions/microsoft_teams/actors/incremental_sync.rb

@@ -14,17 +14,12 @@ module Legion
           def delay           = 60
 
           def time
-            settings = begin
-              Legion::Settings[:microsoft_teams] || {}
-            rescue StandardError => e
-              handle_exception(e, level: :debug, operation: 'IncrementalSync#time')
-              {}
-            end
-            settings.dig(:ingest, :incremental_interval) || 120
+            settings.dig(:incremental_sync, :interval)
           end
 
           def enabled?
-            defined?(Legion::Extensions::Agentic::Memory::Trace::Runners::Traces) &&
+            settings.dig(:incremental_sync, :enabled) &&
+              defined?(Legion::Extensions::Agentic::Memory::Trace::Runners::Traces) &&
               token_available?
           rescue StandardError => e
             handle_exception(e, level: :debug, operation: 'IncrementalSync#enabled?')
@@ -36,17 +31,11 @@ module Legion
             token = resolve_token
             return unless token
 
-            settings = begin
-              Legion::Settings[:microsoft_teams] || {}
-            rescue StandardError => e
-              handle_exception(e, level: :debug, operation: 'IncrementalSync#manual settings')
-              {}
-            end
-            ingest = settings[:ingest] || {}
+            is_settings = settings[:incremental_sync]
             runner_class.incremental_sync(
               token:         token,
-              top_people:    ingest.fetch(:top_people, 10),
-              message_depth: ingest.fetch(:message_depth, 50)
+              top_people:    is_settings[:top_people],
+              message_depth: is_settings[:message_depth]
             )
           rescue StandardError => e
             handle_exception(e, level: :error, operation: 'IncrementalSync#manual')

data/lib/legion/extensions/microsoft_teams/actors/meeting_ingest.rb

@@ -7,8 +7,6 @@ module Legion
         class MeetingIngest < Legion::Extensions::Actors::Every
           include Legion::Extensions::MicrosoftTeams::Helpers::Client
 
-          DEFAULT_INGEST_INTERVAL = 300
-
           def runner_class    = self.class
           def runner_function = 'manual'
           def run_now?        = false
@@ -22,17 +20,12 @@ module Legion
           end
 
           def time
-            settings = begin
-              Legion::Settings[:microsoft_teams] || {}
-            rescue StandardError => e
-              handle_exception(e, level: :debug, operation: 'MeetingIngest#time')
-              {}
-            end
-            settings.dig(:meetings, :ingest_interval) || DEFAULT_INGEST_INTERVAL
+            settings.dig(:meeting_ingest, :interval)
           end
 
           def enabled?
-            Legion::Extensions::Identity::Entra::Helpers::TokenManager.respond_to?(:load_token)
+            settings.dig(:meeting_ingest, :enabled) &&
+              Legion::Extensions::Identity::Entra::Helpers::TokenManager.respond_to?(:load_token)
           rescue StandardError => e
             handle_exception(e, level: :debug, operation: 'MeetingIngest#enabled?')
             false

data/lib/legion/extensions/microsoft_teams/actors/observed_chat_poller.rb

@@ -8,8 +8,6 @@ module Legion
           include Legion::Extensions::MicrosoftTeams::Helpers::Client
           include Legion::Extensions::MicrosoftTeams::Helpers::HighWaterMark
 
-          POLL_INTERVAL = 30
-
           def initialize(**opts)
             return unless enabled?
 
@@ -18,7 +16,7 @@ module Legion
 
           def runner_class    = Legion::Extensions::MicrosoftTeams::Runners::Bot
           def runner_function = 'observe_message'
-          def time            = settings_interval(:observe_poll_interval, POLL_INTERVAL)
+          def time            = settings.dig(:observed_chat_poller, :interval)
           def delay           = 180
           def run_now?        = false
           def use_runner?     = false
@@ -26,11 +24,9 @@ module Legion
           def generate_task?  = false
 
           def enabled?
-            return false unless defined?(Legion::Extensions::MicrosoftTeams::Runners::Bot)
-            return false unless Legion.const_defined?(:Transport, false)
-            return false unless defined?(Legion::Settings)
-
-            Legion::Settings.dig(:microsoft_teams, :bot, :observe, :enabled) == true
+            settings.dig(:observed_chat_poller, :enabled) &&
+              defined?(Legion::Extensions::MicrosoftTeams::Runners::Bot) &&
+              Legion.const_defined?(:Transport, false)
           rescue StandardError => e
             handle_exception(e, level: :debug, operation: 'ObservedChatPoller#enabled?')
             false
@@ -106,12 +102,6 @@ module Legion
             handle_exception(e, level: :warn, operation: 'ObservedChatPoller#delegated_token')
             nil
           end
-
-          def settings_interval(key, default)
-            return default unless defined?(Legion::Settings)
-
-            Legion::Settings.dig(:microsoft_teams, :bot, key) || default
-          end
         end
       end
     end

data/lib/legion/extensions/microsoft_teams/actors/presence_poller.rb

@@ -7,8 +7,6 @@ module Legion
         class PresencePoller < Legion::Extensions::Actors::Every
           include Legion::Extensions::MicrosoftTeams::Helpers::Client
 
-          DEFAULT_POLL_INTERVAL = 60
-
           def runner_class    = self.class
           def runner_function = 'manual'
           def run_now?        = false
@@ -17,13 +15,12 @@ module Legion
           def generate_task?  = false
 
           def time
-            return DEFAULT_POLL_INTERVAL unless defined?(Legion::Settings)
-
-            Legion::Settings.dig(:microsoft_teams, :presence, :poll_interval) || DEFAULT_POLL_INTERVAL
+            settings.dig(:presence_poller, :interval)
           end
 
           def enabled?
-            Legion::Extensions::Identity::Entra::Helpers::TokenManager.respond_to?(:load_token)
+            settings.dig(:presence_poller, :enabled) &&
+              Legion::Extensions::Identity::Entra::Helpers::TokenManager.respond_to?(:load_token)
           rescue StandardError => e
             handle_exception(e, level: :debug, operation: 'PresencePoller#enabled?')
             false

data/lib/legion/extensions/microsoft_teams/actors/profile_ingest.rb

@@ -21,7 +21,8 @@ module Legion
           end
 
           def enabled?
-            defined?(Legion::Extensions::Agentic::Memory::Trace::Runners::Traces) &&
+            settings.dig(:profile_ingest, :enabled) &&
+              defined?(Legion::Extensions::Agentic::Memory::Trace::Runners::Traces) &&
               token_available?
           rescue StandardError => e
             handle_exception(e, level: :debug, operation: 'ProfileIngest#enabled?')
@@ -37,17 +38,11 @@ module Legion
             end
             log.info('ProfileIngest: token acquired, starting ingest')
 
-            settings = begin
-              Legion::Settings[:microsoft_teams] || {}
-            rescue StandardError => e
-              handle_exception(e, level: :debug, operation: 'ProfileIngest#manual settings')
-              {}
-            end
-            ingest = settings[:ingest] || {}
+            pi_settings = settings[:profile_ingest]
             runner_class.full_ingest(
               token:         token,
-              top_people:    ingest.fetch(:top_people, 10),
-              message_depth: ingest.fetch(:message_depth, 50)
+              top_people:    pi_settings[:top_people],
+              message_depth: pi_settings[:message_depth]
             )
           rescue StandardError => e
             handle_exception(e, level: :error, operation: 'ProfileIngest#manual')

data/lib/legion/extensions/microsoft_teams/errors.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module MicrosoftTeams
+      module Errors
+        # Raised when Microsoft Graph (or the Bot Framework) throttles the
+        # caller and the retry policy has been exhausted, or when an actor
+        # wants to surface a throttle event without retrying further.
+        #
+        # `retry_after` carries the last advertised Retry-After interval
+        # (in seconds) as parsed from the upstream header. **It is nil when
+        # the server returned no Retry-After header or one we could not
+        # parse** — callers must check `retry_after_known?` before treating
+        # the value as a server directive. Conflating "header missing" with
+        # "retry immediately" was the bug the original fleet outage exposed.
+        class Throttled < StandardError
+          attr_reader :status, :retry_after, :request, :attempts
+
+          # @param status [Integer]      the upstream HTTP status (e.g. 429)
+          # @param retry_after [Float, Integer, nil] seconds the server
+          #   advised waiting, or nil if the header was absent/unparseable
+          # @param request [String, nil] the path or URL that was throttled
+          # @param attempts [Integer, nil] how many retries the middleware
+          #   tried before giving up; nil means "not tracked"
+          def initialize(status:, retry_after: nil, request: nil, attempts: nil)
+            @status      = coerce_status(status)
+            @retry_after = coerce_retry_after(retry_after)
+            @request     = request
+            @attempts    = attempts.nil? ? nil : Integer(attempts)
+            super(build_message)
+          end
+
+          # @return [Boolean] true when the upstream advised a specific wait
+          #   interval; false when the header was missing or unparseable. Use
+          #   this to decide whether to honor the wait verbatim or apply a
+          #   local policy default before re-scheduling.
+          def retry_after_known?
+            !@retry_after.nil?
+          end
+
+          private
+
+          def coerce_status(value)
+            Integer(value)
+            # rubocop:disable Legion/RescueLogging/NoCapture
+            # No logger available during exception construction; we re-raise
+            # with a clearer message instead.
+          rescue ArgumentError, TypeError
+            raise ArgumentError, "Throttled status must be an Integer, got #{value.inspect}"
+            # rubocop:enable Legion/RescueLogging/NoCapture
+          end
+
+          def coerce_retry_after(value)
+            return nil if value.nil?
+
+            seconds = Float(value)
+            seconds.negative? ? 0.0 : seconds
+            # rubocop:disable Legion/RescueLogging/NoCapture
+            # Unparseable retry_after intentionally collapses to nil so the
+            # public `retry_after_known?` predicate is the single source of
+            # truth for "did the server give us usable guidance." Logging
+            # belongs at the parse site (Faraday::RetryAfter), not here.
+          rescue ArgumentError, TypeError
+            nil
+            # rubocop:enable Legion/RescueLogging/NoCapture
+          end
+
+          def build_message
+            parts = ["Microsoft Graph throttled (HTTP #{@status})"]
+            parts << "after #{@attempts} attempt(s)" if @attempts
+            parts << if retry_after_known?
+                       "retry_after=#{format('%.2f', @retry_after)}s"
+                     else
+                       'retry_after=unknown'
+                     end
+            parts << "request=#{@request}" if @request
+            parts.join('; ')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/microsoft_teams/faraday/retry_after.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'time'
+require 'legion/extensions/microsoft_teams/errors'
+
+module Legion
+  module Extensions
+    module MicrosoftTeams
+      module Faraday
+        # Faraday middleware that retries throttled responses honoring the
+        # upstream Retry-After header per RFC 9110 §10.2.3 (originally
+        # specified in RFC 7231 §7.1.3). Retries HTTP 429 by default; 503
+        # and 504 are opt-in via `retry_statuses:`.
+        #
+        # Retry-After is parsed in two forms:
+        #
+        # * delta-seconds  (e.g. "120")               — used as-is
+        # * HTTP-date      (e.g. "Wed, 27 May 2026 12:00:00 GMT")
+        #                                              — converted to delta
+        #                                                from current UTC,
+        #                                                clamped to >= 0
+        #
+        # The advertised wait is jittered by ±(jitter * wait) to avoid
+        # thundering-herd behavior across instances sharing one Entra app
+        # registration's Graph quota.
+        #
+        # When `max_retries` is reached, or cumulative wait would exceed
+        # `max_wait`, the middleware raises `Errors::Throttled` carrying
+        # the last advertised Retry-After (nil if the header was missing or
+        # unparseable), the final HTTP status, attempt count, and request
+        # path. Raising centrally — rather than returning a raw 429 and
+        # trusting every caller to detect it — is the difference between
+        # one typed event the fleet can defer on, and 60+ runner callsites
+        # that silently treat throttle envelopes as data.
+        class RetryAfter < ::Faraday::Middleware
+          DEFAULT_MAX_RETRIES    = 3
+          DEFAULT_MAX_WAIT       = 60.0
+          DEFAULT_JITTER         = 0.2
+          DEFAULT_FALLBACK_WAIT  = 1.0
+          DEFAULT_RETRY_STATUSES = [429].freeze
+
+          # Parse an HTTP Retry-After header value.
+          #
+          # @param raw [String, nil] the raw header value
+          # @param clock [#call] a callable returning current UTC Time,
+          #   injectable for deterministic tests
+          # @return [Float, nil] seconds to wait, or nil if `raw` is absent,
+          #   empty, or neither a numeric delta nor a valid HTTP-date
+          def self.parse_header(raw, clock: -> { Time.now.utc })
+            return nil if raw.nil?
+
+            value = raw.to_s.strip
+            return nil if value.empty?
+            return value.to_f if value.match?(/\A\d+(\.\d+)?\z/)
+
+            begin
+              target = Time.httpdate(value).utc
+              [(target - clock.call), 0.0].max
+              # rubocop:disable Legion/RescueLogging/NoCapture
+              # Pure parser — no logger access. The instance method
+              # `parse_advertised` warns on the same condition with full
+              # context; logging twice would just be noise.
+            rescue ArgumentError
+              nil
+              # rubocop:enable Legion/RescueLogging/NoCapture
+            end
+          end
+
+          def initialize(app, # rubocop:disable Metrics/ParameterLists
+                         max_retries: DEFAULT_MAX_RETRIES,
+                         max_wait: DEFAULT_MAX_WAIT,
+                         jitter: DEFAULT_JITTER,
+                         fallback_wait: DEFAULT_FALLBACK_WAIT,
+                         retry_statuses: DEFAULT_RETRY_STATUSES,
+                         sleeper: ->(seconds) { sleep(seconds) },
+                         logger: nil,
+                         clock: -> { Time.now.utc })
+            super(app)
+            @max_retries    = Integer(max_retries)
+            @max_wait       = Float(max_wait)
+            @jitter         = Float(jitter)
+            @fallback_wait  = Float(fallback_wait)
+            @retry_statuses = Array(retry_statuses).map(&:to_i).freeze
+            @sleeper        = sleeper
+            @logger         = logger
+            @clock          = clock
+          end
+
+          def call(env)
+            attempts          = 0
+            total_wait        = 0.0
+            last_advertised   = nil
+
+            loop do
+              response = @app.call(env.dup)
+              return response unless retryable?(response.status)
+
+              last_advertised = parse_advertised(response)
+              wait            = compute_wait(last_advertised)
+
+              if attempts >= @max_retries || (total_wait + wait) > @max_wait
+                log_giveup(env, response, attempts, total_wait)
+                raise Errors::Throttled.new(
+                  status:      response.status,
+                  retry_after: last_advertised,
+                  request:     request_path(env),
+                  attempts:    attempts
+                )
+              end
+
+              attempts   += 1
+              total_wait += wait
+              log_retry(env, response, wait, attempts)
+              @sleeper.call(wait)
+            end
+          end
+
+          private
+
+          def retryable?(status)
+            @retry_statuses.include?(status.to_i)
+          end
+
+          # Parse the advertised Retry-After value from a response. Returns
+          # nil if the header is missing or unparseable — callers branch on
+          # nil to distinguish "no server guidance" from "retry now".
+          def parse_advertised(response)
+            raw = retry_after_header(response)
+            parsed = self.class.parse_header(raw, clock: @clock)
+            @logger&.warn("[microsoft_teams][retry_after] unparseable Retry-After=#{raw.inspect}") if raw && !raw.to_s.strip.empty? && parsed.nil?
+            parsed
+          end
+
+          # Computes the actual wait the middleware will sleep before the
+          # next attempt. Falls back to `@fallback_wait` only when the
+          # server gave no usable guidance; jitter is always applied so
+          # concurrent instances don't synchronize their retries.
+          def compute_wait(advertised)
+            seconds = advertised || @fallback_wait
+            apply_jitter(seconds)
+          end
+
+          def retry_after_header(response)
+            headers = response_headers(response)
+            return nil unless headers
+
+            headers['Retry-After'] ||
+              headers['retry-after'] ||
+              headers['RETRY-AFTER']
+          end
+
+          # Faraday's Response exposes headers via #headers; some test
+          # doubles may not, so look in both common places.
+          def response_headers(response)
+            if response.respond_to?(:headers) && response.headers
+              response.headers
+            elsif response.respond_to?(:response_headers)
+              response.response_headers
+            end
+          end
+
+          def apply_jitter(seconds)
+            return seconds if @jitter.zero?
+
+            spread = seconds * @jitter
+            offset = ((rand * 2.0) - 1.0) * spread
+            wait   = seconds + offset
+            wait.negative? ? 0.0 : wait
+          end
+
+          def request_path(env)
+            env.url.respond_to?(:path) ? env.url.path : env.url.to_s
+            # rubocop:disable Legion/RescueLogging/NoCapture
+            # Defensive fallback for malformed env.url; the path is only used
+            # for log lines and error messages, never for control flow.
+          rescue StandardError
+            nil
+            # rubocop:enable Legion/RescueLogging/NoCapture
+          end
+
+          def log_retry(env, response, wait, attempts)
+            return unless @logger
+
+            @logger.warn(
+              "[microsoft_teams][retry_after] status=#{response.status} " \
+              "method=#{env.method.to_s.upcase} path=#{request_path(env)} " \
+              "wait=#{format('%.2f', wait)}s attempt=#{attempts}"
+            )
+          rescue StandardError => e
+            warn("[microsoft_teams][retry_after] log_retry suppressed #{e.class}: #{e.message}")
+          end
+
+          def log_giveup(env, response, attempts, total_wait)
+            return unless @logger
+
+            @logger.error(
+              "[microsoft_teams][retry_after] giving up; status=#{response.status} " \
+              "method=#{env.method.to_s.upcase} path=#{request_path(env)} " \
+              "attempts=#{attempts} total_wait=#{format('%.2f', total_wait)}s"
+            )
+          rescue StandardError => e
+            warn("[microsoft_teams][retry_after] log_giveup suppressed #{e.class}: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end