lex-microsoft_teams 0.6.51 → 0.6.52

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76994e2ead987d49e26c776ff30d9e6a2b78789a12654d38e80e36e81814d703
-  data.tar.gz: ebf842a7daf81e017078e894d111d38f9474ecc1b3ced0f4105cea29dfb1b7fb
+  metadata.gz: ac161b519f294da86eb8956d3aab55f11f4cd87d7fe710c43c033640b630efe5
+  data.tar.gz: bf64b0446e44cd89f9f9cc8be018a2629f0d375ccbfea4848e4668a16ad04598
 SHA512:
-  metadata.gz: ac9c034b99ef410ab0c1727f83409cd8d8d063b20082ace208be85e0a1bbd4c8314b983caf4c2a80af82d9ca6245e3616d67dae3f60cdff4a204bea087b2d777
-  data.tar.gz: 1b13b4c36751a4dd02888c3867acafd0594d6a1a83e00668481a07533997de3bfce5abd68b66fc56adbb5bce6006601d1994daa16ebdb3738bd9309f0ff244a1
+  metadata.gz: 926fd8d8f6aa8bbe022fbb17491b959faea7580dd28dee76c48199392fb3d50bd917934ed4025f4a65f20f7353412abbc6788de4634ebeb00d3bf07497e53e28
+  data.tar.gz: 26ee2c81c7e0330b575b2aedb8f2284d86c4d40a5b42d089b8edce9a6cd33b06699cf2bac2e7671ff62eff830940ed179b27db1cbcdf2e171d856916a24a296f

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.6.52] - 2026-05-29
+### Fixed
+- **Actors now defer their next scheduled run on a Graph throttle** instead of re-firing on their fixed timer interval — resolves the 0.6.51 "Known follow-up". New `Helpers::ThrottleAware` mixin records a "suppress until" instant of `now + retry_after` when a Graph call raises `Errors::Throttled`; subsequent ticks short-circuit until that window elapses. Wired into `PresencePoller`, `MeetingIngest`, and `ApiIngest`. Falls back to a bounded 60s deferral when the server gave no usable `Retry-After`, and clamps any single deferral to 600s. Previously a poller on a 30–300s interval would walk straight back into the still-open shared circuit every interval, emitting a `[throttle_circuit] hard circuit` ERROR (and a duplicate `Errors::Throttled` WARN/ERROR) each tick while ingesting nothing.
+- **`ProfileIngest#full_ingest` and `ApiIngest#ingest_api` now propagate `Errors::Throttled`** rather than folding it into a per-stage error hash. `full_ingest` catches it once and aborts the remaining fan-out stages — once the shared circuit is open every later stage would only raise `Throttled(attempts: 0)` instantly, so continuing produced a burst of identical errors. The actor that drives `ingest_api` uses the propagated throttle to open its deferral window. Non-throttle errors keep their existing error-result behavior.
+
 ## [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.
@@ -18,7 +23,7 @@
 - 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.
+- 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. *(Resolved in [Unreleased] — see `Helpers::ThrottleAware`.)*
 
 ## [0.6.50] - 2026-05-27
 ### Added

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

@@ -5,6 +5,8 @@ module Legion
     module MicrosoftTeams
       module Actor
         class ApiIngest < Legion::Extensions::Actors::Every
+          include Legion::Extensions::MicrosoftTeams::Helpers::ThrottleAware
+
           def runner_class = Legion::Extensions::MicrosoftTeams::Runners::ApiIngest
 
           def runner_function = 'ingest_api'
@@ -40,6 +42,18 @@ module Legion
 
           def manual
             log.debug('ApiIngest#manual starting')
+            # The runner re-raises Errors::Throttled (rather than folding it
+            # into an error result) precisely so this actor can defer its
+            # next run by the advertised retry_after instead of charging the
+            # shared Graph circuit again on the next interval.
+            with_throttle_deferral { run_ingest }
+          rescue StandardError => e
+            handle_exception(e, level: :error, operation: 'ApiIngest#manual')
+          end
+
+          private
+
+          def run_ingest
             token = resolve_token
             unless token
               log.warn('ApiIngest: no delegated token, skipping')
@@ -57,12 +71,8 @@ module Legion
             )
             log.info("ApiIngest: #{result.inspect[0, 200]}")
             result
-          rescue StandardError => e
-            handle_exception(e, level: :error, operation: 'ApiIngest#manual')
           end
 
-          private
-
           def token_available?
             resolve_token != nil
           end

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

@@ -6,6 +6,7 @@ module Legion
       module Actor
         class MeetingIngest < Legion::Extensions::Actors::Every
           include Legion::Extensions::MicrosoftTeams::Helpers::Client
+          include Legion::Extensions::MicrosoftTeams::Helpers::ThrottleAware
 
           def runner_class    = self.class
           def runner_function = 'manual'
@@ -41,6 +42,17 @@ module Legion
 
           def manual
             log.info('MeetingIngest polling for meetings')
+            # Defer the next run when Graph throttles the meetings listing
+            # (the first, fixed call every tick makes); per-meeting throttles
+            # are handled by the inner rescue below and don't change cadence.
+            with_throttle_deferral { ingest_meetings }
+          rescue StandardError => e
+            handle_exception(e, level: :error, operation: 'MeetingIngest#manual')
+          end
+
+          private
+
+          def ingest_meetings
             token = Legion::Extensions::Identity::Entra::Helpers::TokenManager.load_token(:delegated)
             return if token.nil?
 
@@ -57,16 +69,12 @@ module Legion
                 process_meeting(meeting_id: meeting_id, subject: meeting['subject'], token: token)
                 @processed_meetings.add(meeting_id)
               rescue StandardError => e
-                handle_exception(e, level: :error, operation: 'MeetingIngest#manual',
+                handle_exception(e, level: :error, operation: 'MeetingIngest#ingest_meetings',
                                  meeting_id: meeting_id)
               end
             end
-          rescue StandardError => e
-            handle_exception(e, level: :error, operation: 'MeetingIngest#manual')
           end
 
-          private
-
           def process_meeting(meeting_id:, subject:, token:)
             log.debug("MeetingIngest#process_meeting meeting_id=#{meeting_id} subject=#{subject}")
             conn = graph_connection(token: token)

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

@@ -6,6 +6,7 @@ module Legion
       module Actor
         class PresencePoller < Legion::Extensions::Actors::Every
           include Legion::Extensions::MicrosoftTeams::Helpers::Client
+          include Legion::Extensions::MicrosoftTeams::Helpers::ThrottleAware
 
           def runner_class    = self.class
           def runner_function = 'manual'
@@ -28,6 +29,18 @@ module Legion
 
           def manual
             log.debug('PresencePoller#manual starting')
+            # Honour a recent Graph throttle by deferring this run; on a
+            # 429 the block raises Errors::Throttled, which the mixin
+            # converts into a deferral window so the next tick stands down
+            # for retry_after seconds instead of re-firing on the interval.
+            with_throttle_deferral { poll_presence }
+          rescue StandardError => e
+            handle_exception(e, level: :error, operation: 'PresencePoller#manual')
+          end
+
+          private
+
+          def poll_presence
             token = delegated_token
             unless token
               log.debug('No token available, skipping presence poll')
@@ -49,12 +62,8 @@ module Legion
               log.info("Presence changed: availability=#{availability}, activity=#{activity}")
               @last_presence = current
             end
-          rescue StandardError => e
-            handle_exception(e, level: :error, operation: 'PresencePoller#manual')
           end
 
-          private
-
           def delegated_token
             Legion::Extensions::Identity::Entra::Helpers::TokenManager.load_token(:delegated)
           rescue StandardError => e

data/lib/legion/extensions/microsoft_teams/helpers/throttle_aware.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'monitor'
+require 'legion/extensions/microsoft_teams/errors'
+
+module Legion
+  module Extensions
+    module MicrosoftTeams
+      module Helpers
+        # Mixin that lets an `Actors::Every`-style poller honour a Graph
+        # throttle by *deferring its own next run* instead of re-firing on
+        # its fixed timer interval.
+        #
+        # Background: `Faraday::RetryAfter` raises `Errors::Throttled`
+        # centrally when it exhausts retries (or when the advertised wait
+        # alone exceeds the retry budget), and `Faraday::ThrottleCircuit`
+        # opens a shared circuit so the whole fleet stops hammering a quota
+        # that Graph has already flagged. But the actors that *drive* those
+        # calls schedule themselves with a `Concurrent::TimerTask` whose
+        # `execution_interval` is fixed at boot. Catching `Throttled` in a
+        # `rescue` block stops the current tick, but the next tick still
+        # fires on the original cadence — so a poller on a 30–300s interval
+        # keeps walking straight back into an open circuit, emitting an
+        # ERROR every interval and contributing nothing but log noise (and,
+        # via the shared circuit, refreshing the block for cheaper callers).
+        #
+        # This mixin closes that gap. An actor wraps its Graph work in
+        # {#with_throttle_deferral}. On `Errors::Throttled` it records a
+        # "suppress until" instant of `now + retry_after` (falling back to a
+        # bounded default when the server gave no usable `Retry-After`).
+        # Subsequent ticks short-circuit via {#throttle_suppressed?} until
+        # that instant passes, so the actor effectively reschedules itself
+        # at `now + retry_after` rather than `now + interval` — exactly the
+        # behaviour the throttle integration spec and the 0.6.51 CHANGELOG
+        # flagged as the outstanding follow-up.
+        #
+        # State is per-actor-instance and guarded by a monitor because an
+        # actor's `manual` runs on a `Concurrent` thread-pool worker. The
+        # mixin reads the carried `retry_after` only when
+        # `retry_after_known?` is true; otherwise it applies
+        # {DEFAULT_DEFERRAL} so a throttle with a missing/garbage header
+        # still backs the poller off rather than letting it spin.
+        module ThrottleAware
+          # Fallback deferral (seconds) used when a `Throttled` carries no
+          # usable `retry_after` (header absent or unparseable). One minute
+          # matches Microsoft Graph's documented typical Retry-After and the
+          # circuit middleware's `DEFAULT_FALLBACK_TTL`.
+          DEFAULT_DEFERRAL = 60.0
+
+          # Hard ceiling (seconds) on a single deferral so a pathological
+          # advertised `Retry-After` can't park a poller for an unbounded
+          # time. Mirrors the circuit middleware's 600s cap in
+          # `ThrottleCircuit#set_hard_circuit`.
+          MAX_DEFERRAL = 600.0
+
+          # Run `block` unless the actor is currently deferring after a
+          # recent throttle. If a `Throttled` escapes the block, record the
+          # deferral window and swallow it (the throttle has already been
+          # logged at the middleware/circuit layer; re-raising would just
+          # trip the actor's generic `rescue StandardError` and double-log).
+          #
+          # @param now [Time] injectable clock for deterministic tests
+          # @return [Object, nil] the block's value, or nil when suppressed
+          #   or when a throttle was caught
+          def with_throttle_deferral(now: Time.now)
+            if throttle_suppressed?(now: now)
+              log_throttle_skip(now: now)
+              return nil
+            end
+
+            yield
+          rescue Legion::Extensions::MicrosoftTeams::Errors::Throttled => e
+            defer_after_throttle(e, now: now)
+            nil
+          end
+
+          # @return [Boolean] true while the actor is inside a deferral
+          #   window opened by a previous throttle.
+          def throttle_suppressed?(now: Time.now)
+            until_at = throttled_until
+            !until_at.nil? && now < until_at
+          end
+
+          # The instant before which the actor should not poll again, or nil
+          # if no deferral is active. Thread-safe read.
+          def throttled_until
+            throttle_monitor.synchronize { @throttled_until }
+          end
+
+          # Seconds remaining in the current deferral window (0.0 if none /
+          # elapsed). Useful for logging and for tests.
+          def throttle_remaining(now: Time.now)
+            until_at = throttled_until
+            return 0.0 if until_at.nil?
+
+            remaining = until_at - now
+            remaining.positive? ? remaining : 0.0
+          end
+
+          # Open (or extend) a deferral window of `seconds` from `now`. A
+          # later throttle never *shortens* an existing window — we keep the
+          # furthest-out instant so overlapping throttles compose safely.
+          def defer_for(seconds, now: Time.now)
+            window = clamp_deferral(seconds)
+            target = now + window
+            throttle_monitor.synchronize do
+              @throttled_until = if @throttled_until.nil? || target > @throttled_until
+                                   target
+                                 else
+                                   @throttled_until
+                                 end
+            end
+            window
+          end
+
+          # Clear any active deferral. Called implicitly is unnecessary —
+          # {#throttle_suppressed?} expires on its own once the clock passes
+          # `throttled_until` — but exposed for tests and explicit resets.
+          def reset_throttle_deferral
+            throttle_monitor.synchronize { @throttled_until = nil }
+          end
+
+          private
+
+          def defer_after_throttle(error, now: Time.now)
+            seconds = deferral_seconds_for(error)
+            window  = defer_for(seconds, now: now)
+            log.warn(
+              "[microsoft_teams][throttle_defer] #{actor_label}: " \
+              "deferring next run #{format('%.1f', window)}s " \
+              "(retry_after=#{error.retry_after_known? ? format('%.1f', error.retry_after) : 'unknown'} " \
+              "path=#{error.request})"
+            )
+          end
+
+          # Short, log-friendly name for the including actor. Falls back to
+          # the full class string for anonymous classes (whose `name` is
+          # nil), so the log line never raises on `name.split`.
+          def actor_label
+            (self.class.name || self.class.to_s).split('::').last
+          end
+
+          # Prefer the server-advised wait; fall back to {DEFAULT_DEFERRAL}
+          # only when the header was absent or unparseable.
+          def deferral_seconds_for(error)
+            if error.respond_to?(:retry_after_known?) && error.retry_after_known?
+              error.retry_after
+            else
+              DEFAULT_DEFERRAL
+            end
+          end
+
+          def clamp_deferral(seconds)
+            value = begin
+              Float(seconds)
+              # rubocop:disable Legion/RescueLogging/NoCapture
+              # Pure coercion fallback for a non-numeric deferral; the value
+              # is bounded immediately below, so a bad input degrades to the
+              # default rather than warranting its own log line.
+            rescue ArgumentError, TypeError
+              DEFAULT_DEFERRAL
+              # rubocop:enable Legion/RescueLogging/NoCapture
+            end
+            value = DEFAULT_DEFERRAL if value <= 0
+            [value, MAX_DEFERRAL].min
+          end
+
+          def log_throttle_skip(now: Time.now)
+            log.debug(
+              "[microsoft_teams][throttle_defer] #{actor_label}: " \
+              "skipping run, #{format('%.1f', throttle_remaining(now: now))}s deferral remaining"
+            )
+          end
+
+          def throttle_monitor
+            # `||=` is safe here: the first tick of an actor runs before any
+            # concurrent re-entry (the `Every` base guards re-entry with its
+            # own AtomicBoolean), so the monitor is initialised single-threaded.
+            @throttle_monitor ||= Monitor.new
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'digest'
+require 'legion/extensions/microsoft_teams/errors'
 require 'legion/extensions/microsoft_teams/helpers/client'
 require 'legion/extensions/microsoft_teams/helpers/graph_cache'
 require 'legion/extensions/microsoft_teams/helpers/permission_guard'
@@ -104,6 +105,16 @@ module Legion
             { result: { stored: stored, skipped: skipped, people_ingested: people_ingested,
                         people_found: people.length, chats_found: chats.length,
                         apollo: apollo_results } }
+          # rubocop:disable Legion/RescueLogging/NoCapture
+          # Re-raise unlogged: surface the typed throttle to the caller (the
+          # ApiIngest actor) so it can defer its next scheduled run by the
+          # advertised retry_after. The throttle is already logged at the
+          # middleware/circuit layer; folding it into an error result here
+          # would hide the one signal the actor needs to stop re-charging
+          # the shared Graph circuit on its fixed interval.
+          rescue Errors::Throttled
+            raise
+            # rubocop:enable Legion/RescueLogging/NoCapture
           rescue StandardError => e
             handle_exception(e, level: :error, operation: 'ApiIngest#ingest_api')
             { result: { stored: stored || 0, skipped: skipped || 0, error: e.message } }

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'legion/extensions/microsoft_teams/errors'
 require 'legion/extensions/microsoft_teams/helpers/client'
 require 'legion/extensions/microsoft_teams/helpers/graph_cache'
 require 'legion/extensions/microsoft_teams/helpers/permission_guard'
@@ -36,6 +37,15 @@ module Legion
             teams_result = ingest_teams_and_meetings(token: token)
 
             { self: self_result, people: people_result, conversations: conv_result, teams: teams_result }
+          rescue Errors::Throttled => e
+            # Once Graph throttles us, the shared circuit is open and every
+            # remaining stage would just raise Throttled(attempts: 0)
+            # instantly — a burst of identical errors that ingests nothing.
+            # Stop the fan-out at the first throttled stage and report it.
+            log.warn('[microsoft_teams][profile_ingest] throttled mid-ingest; ' \
+                     'aborting remaining stages (retry_after=' \
+                     "#{e.retry_after_known? ? format('%.1f', e.retry_after) : 'unknown'} path=#{e.request})")
+            { throttled: true, retry_after: e.retry_after, request: e.request }
           end
 
           def ingest_self(token:, **)
@@ -67,6 +77,13 @@ module Legion
             end
 
             { profile: profile, presence: presence }
+          # rubocop:disable Legion/RescueLogging/NoCapture
+          # Re-raise unlogged: full_ingest logs the throttle once and aborts
+          # the fan-out. A throttle is a fleet signal, not a per-stage error;
+          # logging it here too would just duplicate the line per stage.
+          rescue Errors::Throttled
+            raise
+            # rubocop:enable Legion/RescueLogging/NoCapture
           rescue StandardError => e
             handle_exception(e, level: :error, operation: 'ProfileIngest#ingest_self')
             { error: e.message }
@@ -99,6 +116,13 @@ module Legion
             end
 
             { people: people, count: people.length }
+          # rubocop:disable Legion/RescueLogging/NoCapture
+          # Re-raise unlogged: full_ingest logs the throttle once and aborts
+          # the fan-out. A throttle is a fleet signal, not a per-stage error;
+          # logging it here too would just duplicate the line per stage.
+          rescue Errors::Throttled
+            raise
+            # rubocop:enable Legion/RescueLogging/NoCapture
           rescue StandardError => e
             handle_exception(e, level: :error, operation: 'ProfileIngest#ingest_people')
             { error: e.message, skipped: false }
@@ -148,6 +172,13 @@ module Legion
             end
 
             { ingested: ingested }
+          # rubocop:disable Legion/RescueLogging/NoCapture
+          # Re-raise unlogged: full_ingest logs the throttle once and aborts
+          # the fan-out. A throttle is a fleet signal, not a per-stage error;
+          # logging it here too would just duplicate the line per stage.
+          rescue Errors::Throttled
+            raise
+            # rubocop:enable Legion/RescueLogging/NoCapture
           rescue StandardError => e
             handle_exception(e, level: :error, operation: 'ProfileIngest#ingest_conversations')
             { error: e.message, ingested: ingested || 0 }
@@ -194,6 +225,13 @@ module Legion
             end
 
             { teams: teams_count, meetings: meetings_count }
+          # rubocop:disable Legion/RescueLogging/NoCapture
+          # Re-raise unlogged: full_ingest logs the throttle once and aborts
+          # the fan-out. A throttle is a fleet signal, not a per-stage error;
+          # logging it here too would just duplicate the line per stage.
+          rescue Errors::Throttled
+            raise
+            # rubocop:enable Legion/RescueLogging/NoCapture
           rescue StandardError => e
             handle_exception(e, level: :error, operation: 'ProfileIngest#ingest_teams_and_meetings')
             { error: e.message }
@@ -224,6 +262,12 @@ module Legion
               end
             end
             index
+          # rubocop:disable Legion/RescueLogging/NoCapture
+          # Re-raise unlogged: propagate to full_ingest so the per-chat
+          # fan-out stops on the first throttle; full_ingest logs it once.
+          rescue Errors::Throttled
+            raise
+            # rubocop:enable Legion/RescueLogging/NoCapture
           rescue StandardError => e
             handle_exception(e, level: :warn, operation: 'ProfileIngest#build_chat_member_index')
             {}
@@ -236,6 +280,12 @@ module Legion
 
             resp = conn.get("chats/#{chat_id}/messages", params)
             (resp.body || {}).fetch('value', [])
+          # rubocop:disable Legion/RescueLogging/NoCapture
+          # Re-raise unlogged: propagate to full_ingest so the per-chat
+          # fan-out stops on the first throttle; full_ingest logs it once.
+          rescue Errors::Throttled
+            raise
+            # rubocop:enable Legion/RescueLogging/NoCapture
           rescue StandardError => e
             handle_exception(e, level: :warn, operation: 'ProfileIngest#fetch_new_messages',
                              chat_id: chat_id)

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module MicrosoftTeams
-      VERSION = '0.6.51'
+      VERSION = '0.6.52'
     end
   end
 end

data/lib/legion/extensions/microsoft_teams.rb

@@ -4,6 +4,7 @@ require 'legion/extensions/identity/entra/helpers/token_manager'
 require 'legion/extensions/microsoft_teams/version'
 require 'legion/extensions/microsoft_teams/errors'
 require 'legion/extensions/microsoft_teams/faraday/retry_after'
+require 'legion/extensions/microsoft_teams/helpers/throttle_aware'
 require 'legion/extensions/microsoft_teams/helpers/client'
 require 'legion/extensions/microsoft_teams/runners/auth'
 require 'legion/extensions/microsoft_teams/runners/teams'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-microsoft_teams
 version: !ruby/object:Gem::Version
-  version: 0.6.51
+  version: 0.6.52
 platform: ruby
 authors:
 - Esity
@@ -218,6 +218,7 @@ files:
 - lib/legion/extensions/microsoft_teams/helpers/prompt_resolver.rb
 - lib/legion/extensions/microsoft_teams/helpers/session_manager.rb
 - lib/legion/extensions/microsoft_teams/helpers/subscription_registry.rb
+- lib/legion/extensions/microsoft_teams/helpers/throttle_aware.rb
 - lib/legion/extensions/microsoft_teams/helpers/trace_retriever.rb
 - lib/legion/extensions/microsoft_teams/helpers/transform_definitions.rb
 - lib/legion/extensions/microsoft_teams/local_cache/extractor.rb