spree_cm_commissioner 2.15.2 → 2.15.3

data/app/services/spree_cm_commissioner/integrations/book_me_bus_v1/sync_strategies/full_sync_strategy.rb

@@ -50,19 +50,25 @@ module SpreeCmCommissioner::Integrations::BookMeBusV1::SyncStrategies
 
     def call
       sync_locations!
-      sync_routes!
-      sync_all_trips!
+      # A 429 ends the run: every call after it would be refused too.
+      sync_routes! unless rate_limited?
+      sync_trips! unless rate_limited?
 
       @sync_result
     end
 
     private
 
+    def rate_limited?
+      @sync_result.rate_limited?
+    end
+
     def sync_locations!
-      SpreeCmCommissioner::Integrations::BookMeBusV1::Polling::SyncLocations.new(
+      @sync_locations = SpreeCmCommissioner::Integrations::BookMeBusV1::Polling::SyncLocations.new(
         integration: @integration,
         sync_result: @sync_result
-      ).call
+      )
+      @sync_locations.call
     rescue StandardError => e
       @sync_result.record_error(e)
     end
@@ -70,21 +76,36 @@ module SpreeCmCommissioner::Integrations::BookMeBusV1::SyncStrategies
     def sync_routes!
       SpreeCmCommissioner::Integrations::BookMeBusV1::Polling::SyncRoutes.new(
         integration: @integration,
-        sync_result: @sync_result
+        sync_result: @sync_result,
+        trip_locations: @sync_locations&.trip_locations
       ).call
     rescue StandardError => e
       @sync_result.record_error(e)
     end
 
-    # Sync trips for all routes
-    # Uses custom routes if provided, otherwise syncs all active routes
-    def sync_all_trips!
-      routes = @custom_routes.presence || find_all_routes
+    # Routes passed in (a manual run) are synced here. Otherwise one SyncRouteJob is queued per route, so this
+    # session only covers locations and routes.
+    def sync_trips!
+      @custom_routes.present? ? sync_custom_routes! : enqueue_route_jobs!
+    end
 
-      routes.each do |route|
+    # Skips routes already synced today, so a rerun after a failure carries on where it stopped.
+    def enqueue_route_jobs!
+      synced_today = SpreeCmCommissioner::IntegrationMapping.active_routes_of(@integration)
+                                                            .where("private_metadata ->> 'full_synced_on' = ?", Date.current.iso8601)
+                                                            .pluck(:internal_id).to_set
+
+      find_all_routes.reject { |route| synced_today.include?(route.id) }.each do |route|
+        SpreeCmCommissioner::Integrations::BookMeBusV1::SyncRouteJob.perform_later(integration_id: @integration.id, route_id: route.id)
+      end
+    end
+
+    def sync_custom_routes!
+      @custom_routes.each do |route|
         sync_trips_for_route!(route)
       rescue StandardError => e
         @sync_result.record_error(e)
+        break if rate_limited?
       end
     end
 
@@ -103,15 +124,11 @@ module SpreeCmCommissioner::Integrations::BookMeBusV1::SyncStrategies
     end
 
     def sync_trips_for_route!(route)
-      # Sync trips for the configured number of days (default: 7)
-      today = Date.current
-      on_dates = (0...@integration.sync_days).map { |days_ahead| (today + days_ahead).strftime('%Y-%m-%d') }
-
       SpreeCmCommissioner::Integrations::BookMeBusV1::Polling::SyncTrips.new(
         integration: @integration,
         sync_result: @sync_result,
         route: route
-      ).call(on_dates: on_dates)
+      ).call(on_dates: @integration.sync_dates)
     end
   end
 end

data/app/services/spree_cm_commissioner/integrations/book_me_bus_v1/sync_strategies/incremental_sync_strategy.rb

@@ -1,63 +1,66 @@
 module SpreeCmCommissioner::Integrations::BookMeBusV1::SyncStrategies
-  # Incremental sync strategy - syncs trip data for specific routes.
-  #
-  # Runs periodically to fetch updated trip information for active routes.
-  # This allows keeping trip availability fresh without re-syncing all locations.
-  #
-  # Flow:
-  #   1. Gets the next vendor_route needing sync (oldest last_synced_at)
-  #   2. Gets the route's direction mapping to find origin_id/destination_id
-  #   3. Calls search_trips API and syncs trip data
-  #   4. Updates route mapping's last_synced_at
-
+  # Keeps seats fresh between full syncs: asks BookMeBus only for the routes and dates that are due (see
+  # RouteFreshness), stalest first, at most ROUTES_PER_RUN routes per run.
   class IncrementalSyncStrategy
+    # The routes beyond this wait for the next run.
+    ROUTES_PER_RUN = 10
+
     def initialize(integration:)
       @integration = integration
       @sync_result = ::SpreeCmCommissioner::Integrations::Base::SyncResult.new
     end
 
-    def call
-      vendor_route = find_next_vendor_route_to_sync
-      return @sync_result unless vendor_route
+    # False when every route is fresh: the manager then skips the run (and its session row) altogether.
+    def work_due?
+      due_routes.any?
+    end
 
-      sync_trips_for_vendor_route!(vendor_route)
+    def call
+      due_routes.first(ROUTES_PER_RUN).each do |route, dates|
+        sync_trips_for_route!(route, dates)
+        # A 429 ends the run: every call after it would be refused too.
+        break if @sync_result.rate_limited?
+      end
 
-      @sync_result
-    rescue StandardError => e
-      @sync_result.record_error(e)
       @sync_result
     end
 
     private
 
-    def find_next_vendor_route_to_sync
-      # Get routes for this vendor, join with route mappings to find oldest synced
-      mapping_table = SpreeCmCommissioner::IntegrationMapping.table_name
-
-      SpreeCmCommissioner::Route
-        .joins(:integration_mappings)
-        .where(vendor: @integration.vendor)
-        .where(
-          mapping_table => {
-            integration_id: @integration.id,
-            internal_type: 'SpreeCmCommissioner::Route',
-            status: :active
-          }
-        )
-        .order("#{mapping_table}.last_synced_at ASC NULLS FIRST")
-        .first
+    # [route, due dates] for each route with something due, stalest first (never refreshed comes first).
+    def due_routes
+      @due_routes ||= find_due_routes
     end
 
-    def sync_trips_for_vendor_route!(vendor_route)
-      # Sync trips for today and tomorrow to keep availability fresh
-      today = Date.current
-      on_dates = [today, today + 1.day].map { |date| date.strftime('%Y-%m-%d') }
+    def find_due_routes
+      due = route_mappings.filter_map do |mapping|
+        freshness = SpreeCmCommissioner::Integrations::BookMeBusV1::RouteFreshness.new(mapping)
+        dates = freshness.due_dates(days: @integration.sync_days)
+        [mapping.internal, dates, freshness.oldest_stamp(dates)] if dates.any? && mapping.internal
+      end
+
+      due.sort_by(&:last).map { |route, dates, _| [route, dates] }
+    end
 
+    # Only routes a SyncRouteJob has finished once (`full_synced_on`): the full sync's own jobs are still fetching the
+    # others, and refreshing them here too would compete with those jobs for the call limit.
+    # Only the columns read here: the payload column is large and not needed.
+    def route_mappings
+      SpreeCmCommissioner::IntegrationMapping.active_routes_of(@integration)
+                                             .where("private_metadata ->> 'full_synced_on' IS NOT NULL")
+                                             .select(:id, :internal_type, :internal_id, :private_metadata)
+                                             .includes(:internal)
+    end
+
+    # One route failing does not stop the others.
+    def sync_trips_for_route!(route, dates)
       SpreeCmCommissioner::Integrations::BookMeBusV1::Polling::SyncTrips.new(
         integration: @integration,
         sync_result: @sync_result,
-        route: vendor_route
-      ).call(on_dates: on_dates, full_sync: false)
+        route: route
+      ).call(on_dates: dates, full_sync: false)
+    rescue StandardError => e
+      @sync_result.record_error(e)
     end
   end
 end

data/app/services/spree_cm_commissioner/integrations/call_limiter.rb

@@ -0,0 +1,89 @@
+module SpreeCmCommissioner
+  module Integrations
+    # Caps the calls BookMe+ sends to one partner host per minute, shared by every vendor, process and thread.
+    #
+    # - Checkout calls are never limited or counted.
+    # - A customer opening a trip (lane: :customer) is not counted either, so a busy sync cannot refuse it. It still
+    #   waits out a 429 pause.
+    # - Any other call is refused with RateLimitedError (the error a real 429 raises, so the sync stops the same
+    #   way) when the minute's limit is used up or the partner answered 429 and its Retry-After is still running.
+    # - Redis down: calls go through. An outage must not stop syncing or selling.
+    class CallLimiter
+      WINDOW = 60
+      DEFAULT_MAX_CALLS_PER_MINUTE = 60
+      MAX_PAUSE = RateLimitedError::MAX_RETRY_AFTER.to_i
+
+      # @param base_url [String] the partner's base URL; calls are counted per host
+      def initialize(base_url:)
+        @host = URI.parse(base_url.to_s).host.presence || base_url.to_s
+      end
+
+      # Counts one call, or raises RateLimitedError when it must not be sent.
+      def take!(lane: :background)
+        return if lane == :checkout
+
+        raise_if_paused!
+        return if lane == :customer
+
+        result = SpreeCmCommissioner::RateLimiter.call(key: calls_key, limit: max_calls_per_minute, window: WINDOW)
+        return unless result.exceeded?
+
+        raise_rate_limited("BookMe+ call limit reached (#{result.limit} calls a minute) for #{host}")
+      end
+
+      # True while the pause after a 429 is running (checkout ignores it).
+      def paused?
+        paused_for.positive?
+      end
+
+      # Seconds left of that pause, 0 if none.
+      def paused_for
+        SpreeCmCommissioner.redis_pool.with { |redis| redis.ttl(pause_key) }.to_i.clamp(0, MAX_PAUSE)
+      rescue Redis::BaseError, ConnectionPool::TimeoutError => e
+        log_redis_error(e)
+        0
+      end
+
+      # The partner answered 429: pause every non-checkout call for `seconds`.
+      def pause!(seconds)
+        SpreeCmCommissioner.redis_pool.with { |redis| redis.set(pause_key, '1', ex: seconds.to_i.clamp(1, MAX_PAUSE)) }
+      rescue Redis::BaseError, ConnectionPool::TimeoutError => e
+        log_redis_error(e)
+      end
+
+      private
+
+      attr_reader :host
+
+      def raise_if_paused!
+        seconds_left = paused_for
+        return unless seconds_left.positive?
+
+        raise_rate_limited("#{host} answered 429 recently, not calling it for #{seconds_left} more seconds", retry_after: seconds_left)
+      end
+
+      def raise_rate_limited(message, retry_after: nil)
+        raise RateLimitedError.new(message, retry_after: retry_after)
+      end
+
+      def max_calls_per_minute
+        ENV.fetch('BOOKMEBUS_MAX_CALLS_PER_MINUTE', DEFAULT_MAX_CALLS_PER_MINUTE).to_i
+      end
+
+      def calls_key
+        "integrations:call_limiter:#{host}:calls"
+      end
+
+      def pause_key
+        "integrations:call_limiter:#{host}:paused"
+      end
+
+      def log_redis_error(error)
+        CmAppLogger.error(
+          label: 'Integrations::CallLimiter Redis error - failing open',
+          data: { host: host, error_class: error.class.name, error_message: error.message }
+        )
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/integrations/polling_scheduler.rb

@@ -6,9 +6,9 @@ module SpreeCmCommissioner
       def call
         SpreeCmCommissioner::Integration.active.find_each(batch_size: BATCH_SIZE) do |integration|
           if should_run_full_sync?(integration)
-            schedule_full_sync(integration)
+            schedule_full_sync(integration) unless paused_by_partner?(integration)
           elsif should_run_incremental_sync?(integration)
-            schedule_incremental_sync(integration)
+            schedule_incremental_sync(integration) unless paused_by_partner?(integration)
           end
         end
       end
@@ -20,6 +20,8 @@ module SpreeCmCommissioner
       # 1. No full sync is running or pending (excluding sessions older than 1 hour)
       # 2. No previous full sync exists, OR
       # 3. Last full sync was more than the configured interval ago (eg. 24 hours ago)
+      # And the last full syncs are not failing, with their wait still running (SyncBackoff): only completed sessions
+      # count here, so a failed one would otherwise be queued again on the next 10 s tick.
       def should_run_full_sync?(integration)
         return false if integration.integration_sync_sessions
                                    .where(sync_type: %i[full], status: %i[in_progress pending])
@@ -30,10 +32,8 @@ module SpreeCmCommissioner
                                     .order(created_at: :desc)
                                     .first
 
-        return true if last_full_sync.blank?
-
-        full_sync_interval = integration.full_sync_interval_hours.hours
-        (Time.current - last_full_sync.created_at) > full_sync_interval
+        due = last_full_sync.blank? || (Time.current - last_full_sync.created_at) > integration.full_sync_interval_hours.hours
+        due && !SyncBackoff.new(integration).full_sync_waiting?
       end
 
       # Check if incremental sync should run
@@ -43,8 +43,9 @@ module SpreeCmCommissioner
                                    .where(sync_type: %i[full incremental], status: %i[in_progress pending])
                                    .exists?(['created_at > ?', 1.hour.ago])
 
+        # A failed run counts too, so it waits the interval instead of retrying on the next tick.
         last_incremental_sync = integration.integration_sync_sessions
-                                           .where(sync_type: :incremental, status: :completed)
+                                           .where(sync_type: :incremental, status: %i[completed failed])
                                            .order(created_at: :desc)
                                            .first
 
@@ -57,6 +58,11 @@ module SpreeCmCommissioner
         (Time.current - last_incremental_sync.created_at) > incremental_sync_interval
       end
 
+      # The partner answered 429 and its Retry-After is still running.
+      def paused_by_partner?(integration)
+        SyncBackoff.new(integration).rate_limited?
+      end
+
       def schedule_full_sync(integration)
         CmAppLogger.log(
           label: 'Integrations::PollingSchedulerJob#schedule_full_sync Enqueued full sync',

data/app/services/spree_cm_commissioner/integrations/sync_backoff.rb

@@ -0,0 +1,61 @@
+module SpreeCmCommissioner
+  module Integrations
+    # Tells PollingScheduler when to wait after failed syncs, so a failure is not queued again on the next tick.
+    #
+    # - Full sync: after failures in a row it waits 15, 30, 60, then at most 120 minutes since the failed run ended.
+    #   A success resets it.
+    # - A 429 pauses every sync of the integration for the Retry-After the partner sent.
+    class SyncBackoff
+      BASE_WAIT = 15.minutes
+      MAX_WAIT = 2.hours
+      MAX_STREAK = 5 # four failures reach MAX_WAIT, so older history changes nothing
+      FINISHED_STATUSES = %i[completed failed].freeze
+
+      def initialize(integration)
+        @integration = integration
+      end
+
+      def full_sync_waiting?
+        failures = recent_full_sync_failures
+        return false if failures.empty?
+
+        wait = [BASE_WAIT * (2**(failures.size - 1)), MAX_WAIT].min
+        finished_at(*failures.first) + wait > Time.current
+      end
+
+      def rate_limited?
+        ended_at, created_at, error = last_finished_session
+        return false unless error&.dig('code') == 'RateLimitedError'
+
+        retry_after = error['retry_after'] || RateLimitedError::DEFAULT_RETRY_AFTER
+        finished_at(ended_at, created_at) + retry_after.to_i.seconds > Time.current
+      end
+
+      private
+
+      # [ended_at, created_at] of each full sync that failed in a row, newest first.
+      def recent_full_sync_failures
+        @integration.integration_sync_sessions
+                    .where(sync_type: :full, status: FINISHED_STATUSES)
+                    .order(created_at: :desc)
+                    .limit(MAX_STREAK)
+                    .pluck(:status, :ended_at, :created_at)
+                    .take_while { |status, _, _| status == 'failed' }
+                    .map { |_, ended_at, created_at| [ended_at, created_at] }
+      end
+
+      # [ended_at, created_at, error] of the latest run. Only the error is read from the (larger) sync result.
+      def last_finished_session
+        @integration.integration_sync_sessions
+                    .where(status: FINISHED_STATUSES)
+                    .order(created_at: :desc)
+                    .pick(:ended_at, :created_at, Arel.sql("sync_result -> 'error'"))
+      end
+
+      # A run that died has no ended_at: use its start.
+      def finished_at(ended_at, created_at)
+        ended_at || created_at
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/seats/apply_locks.rb

@@ -87,19 +87,25 @@ module SpreeCmCommissioner
                                             .pluck(:id)
       end
 
-      # "512:2026-08-08" => [512, Date]. Owned here so the gem never reaches into a controller helper.
+      # "512:2026-08-08" => [512, Date]. "512:" (no date) => [512, nil] -- an Event session-variant, whose
+      # single InventoryItem has inventory_date: nil. Owned here so the gem never reaches into a
+      # controller helper.
       def parse_selections(keys)
         Array(keys).filter_map do |key|
           variant_id, date = key.to_s.split(':')
-          next if variant_id.blank? || date.blank?
+          next if variant_id.blank?
 
-          begin
-            [variant_id.to_i, Date.parse(date)]
-          rescue Date::Error
-            nil
-          end
+          [variant_id.to_i, parse_date(date)]
         end
       end
+
+      def parse_date(date)
+        return nil if date.blank?
+
+        Date.parse(date)
+      rescue Date::Error
+        nil
+      end
     end
   end
 end

data/app/services/spree_cm_commissioner/seats/block_history.rb

@@ -0,0 +1,168 @@
+module SpreeCmCommissioner
+  module Seats
+    # A seat's change history, newest first, read out of the PaperTrail versions of the
+    # ReservedBlock rows on that block.
+    #
+    # `versions` has no object_changes column, and a version's `object` is the row *before* that
+    # change -- so what a change wrote is the next version's `object`, or the live row for the newest
+    # one. Each entry is the diff between those two snapshots, limited to TRACKED attributes.
+    #
+    # The actor is the `updated_by_id` the change itself wrote, not `whodunnit`: every ReservedBlock
+    # writer stamps updated_by, including background jobs (ApplyLocks) where whodunnit is blank, and
+    # the expiry jobs deliberately write nil for "system". whodunnit is only a fallback.
+    #
+    # Only live rows are read: a destroyed row's versions are keyed by its old item_id alone and can't
+    # be found from the block. Seats::UnlockBlocks cancels rather than destroys for that reason, but
+    # locks released before it did are gone from a seat's history.
+    class BlockHistory
+      Entry = Struct.new(:version_id, :event, :created_at, :actor, :changes, keyword_init: true)
+      GuestRef = Struct.new(:id, :name, keyword_init: true)
+
+      TRACKED = %w[status guest_id lock_reason lock_note expired_at payment_locked_at].freeze
+
+      # Bounded because versions are never pruned and a seat's hold/expire churn during checkout can
+      # write dozens of versions per day -- the panel only needs the recent story.
+      LIMIT = 50
+
+      def initialize(block)
+        @block = block
+      end
+
+      def entries
+        drafts = versions.group_by(&:item_id).flat_map { |item_id, row_versions| drafts_for(rows[item_id], row_versions) }
+        drafts = drafts.sort_by { |draft| -draft[:version].id }
+        drafts.reject! { |draft| draft[:version].event == 'update' && draft[:changes].empty? }
+
+        guests = guests_by_id(drafts)
+        actors = actors_by_id(drafts)
+
+        drafts.map { |draft| build_entry(draft, guests, actors) }
+      end
+
+      private
+
+      attr_reader :block
+
+      def rows
+        @rows ||= SpreeCmCommissioner::ReservedBlock.where(block_id: block.id).index_by(&:id)
+      end
+
+      def versions
+        return [] if rows.empty?
+
+        PaperTrail::Version.where(item_type: SpreeCmCommissioner::ReservedBlock.name, item_id: rows.keys)
+                           .reorder(id: :desc)
+                           .limit(LIMIT)
+                           .to_a
+      end
+
+      # row_versions arrive newest first, so each version's "after" is the snapshot just processed.
+      def drafts_for(row, row_versions)
+        after = row ? normalize(row.attributes) : {}
+
+        row_versions.map do |version|
+          before = state_in(version)
+          written = version.event == 'destroy' ? {} : after
+          after = before
+
+          { version: version, before: before, after: written, changes: diff(before, written) }
+        end
+      end
+
+      def diff(before, after)
+        TRACKED.each_with_object({}) do |attribute, changes|
+          from = before[attribute]
+          to = after[attribute]
+          changes[attribute] = [from, to] unless from == to
+        end
+      end
+
+      def state_in(version)
+        return {} if version.object.blank?
+
+        normalize(YAML.unsafe_load(version.object.to_s) || {})
+      rescue Psych::Exception, ArgumentError
+        {}
+      end
+
+      # Versions and the live row disagree on representation (enum integer vs name, jsonb as a JSON
+      # string vs a Hash, Time vs String), so both are reduced to the same plain shape before diffing.
+      def normalize(attributes)
+        metadata = metadata_in(attributes['private_metadata'])
+
+        {
+          'status' => status_name(attributes['status']),
+          'guest_id' => attributes['guest_id'],
+          'lock_reason' => metadata['lock_reason'].presence,
+          'lock_note' => metadata['lock_note'].presence,
+          'expired_at' => to_time(attributes['expired_at']),
+          'payment_locked_at' => to_time(attributes['payment_locked_at']),
+          'updated_by_id' => attributes['updated_by_id']
+        }
+      end
+
+      # PaperTrail serialises jsonb through the column type, which lands in `object` as a JSON string
+      # of a JSON string -- hence decoding until it stops being one, not just once.
+      def metadata_in(value)
+        2.times { value = JSON.parse(value) if value.is_a?(String) }
+        value.is_a?(Hash) ? value.stringify_keys : {}
+      rescue JSON::ParserError
+        {}
+      end
+
+      def status_name(value)
+        return value.to_s if value.is_a?(String) || value.is_a?(Symbol)
+        return nil if value.nil?
+
+        SpreeCmCommissioner::ReservedBlock.statuses.key(value)
+      end
+
+      # Second precision: a YAML snapshot and the live column can differ in sub-second digits for
+      # the same write, which would otherwise show up as a phantom change.
+      def to_time(value)
+        time = value.is_a?(String) ? Time.zone.parse(value) : value&.in_time_zone
+        time&.change(usec: 0)
+      rescue ArgumentError
+        nil
+      end
+
+      # A destroy has no "after" -- the row's own final snapshot (UnlockBlocks stamps updated_by on it
+      # just before destroying) is what names the actor.
+      def actor_id(draft)
+        source = draft[:version].event == 'destroy' ? draft[:before] : draft[:after]
+        source['updated_by_id'].presence || draft[:version].whodunnit.presence
+      end
+
+      def actors_by_id(drafts)
+        ids = drafts.filter_map { |draft| actor_id(draft) }.map(&:to_i).uniq
+        Spree.user_class.where(id: ids).index_by(&:id)
+      end
+
+      def guests_by_id(drafts)
+        ids = drafts.flat_map { |draft| draft[:changes].fetch('guest_id', []) }.compact.uniq
+        SpreeCmCommissioner::Guest.where(id: ids).index_by(&:id)
+      end
+
+      def build_entry(draft, guests, actors)
+        version = draft[:version]
+        changes = draft[:changes].dup
+        guest_ids = changes.delete('guest_id')
+        changes['guest'] = guest_ids.map { |id| guest_ref(id, guests) } if guest_ids
+
+        Entry.new(
+          version_id: version.id,
+          event: version.event,
+          created_at: version.created_at,
+          actor: actors[actor_id(draft).to_i],
+          changes: changes
+        )
+      end
+
+      def guest_ref(id, guests)
+        return nil if id.nil?
+
+        GuestRef.new(id: id, name: guests[id]&.full_name.presence)
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/seats/lock_state.rb

@@ -11,6 +11,8 @@ module SpreeCmCommissioner
     # those two disagreed the operator saw one thing and the server did another.
     class LockState
       # selections: array of [variant_id, Date] pairs, parsed from the calendar's "variant_id:date" keys.
+      # A pair may carry a nil date instead -- an Event session-variant, whose single InventoryItem row
+      # has inventory_date: nil (there is no date to choose, unlike Transit's permanent-stock variants).
       def initialize(selections:)
         @selections = Array(selections)
       end
@@ -71,7 +73,7 @@ module SpreeCmCommissioner
       # per variant.
       def dates_by_variant
         @dates_by_variant ||= selections.each_with_object({}) do |(variant_id, date), acc|
-          (acc[variant_id] ||= []) << date.to_date
+          (acc[variant_id] ||= []) << date&.to_date
         end
       end