command_tower 0.18.0 → 0.19.0

data/app/services/command_tower/messaging/execution/expo_receipt_collection.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      # Collects Expo receipts that were still pending when a push attempt finished.
+      # Called at the end of the recovery sweep. It only reads receipts and records them in the
+      # attempt's provider_metadata; it never sends, enqueues, or changes delivery or attempt status.
+      #
+      # Poll window: attempts that finished within RECEIPT_WINDOW. A bounded, best-effort cleanup
+      # read just behind the window marks entries that are still pending as unchecked (no HTTP).
+      class ExpoReceiptCollection
+        RECEIPT_WINDOW = 15.minutes
+        BATCH_SIZE = 100
+        RECEIPT_ID_CHUNK_SIZE = 1000
+        DEVICE_INVALID_ERRORS = %w[DeviceNotRegistered].freeze
+        COUNT_KEYS = %i[
+          attempt_count
+          receipt_ok_count
+          receipt_error_count
+          receipt_unchecked_count
+          invalidated_count
+          poll_failure_count
+          update_failure_count
+        ].freeze
+
+        def self.call(configuration: nil, http_client: nil, now: Time.current)
+          new(configuration:, http_client:, now:).call
+        end
+
+        def initialize(configuration: nil, http_client: nil, now: Time.current)
+          @configuration = configuration || Adapters::Expo::Configuration.new
+          @http_client = http_client
+          @now = now
+          @counts = COUNT_KEYS.index_with { 0 }
+        end
+
+        def call
+          return @counts unless http_adapter?
+
+          cleanup_pass
+          poll_pass
+          @counts
+        rescue StandardError
+          @counts[:update_failure_count] += 1
+          @counts
+        ensure
+          OperationLogger.receipts_collected(@counts) if http_adapter?
+        end
+
+        private
+
+        def http_adapter?
+          @configuration.expo_configured? && @configuration.adapter_name == "http"
+        end
+
+        def http_client
+          @http_client ||= Adapters::Expo::HttpClient.new(configuration: @configuration)
+        end
+
+        def window_start
+          @now - RECEIPT_WINDOW
+        end
+
+        def poll_scope
+          attempts_scope.where(finished_at: window_start..)
+        end
+
+        def cleanup_scope
+          attempts_scope.where(finished_at: (@now - (2 * RECEIPT_WINDOW))...window_start)
+        end
+
+        def attempts_scope
+          Messaging::DeliveryAttempt.where.not(provider_metadata: nil)
+        end
+
+        # Keyset batches ordered by (finished_at, id) so the finished_at index serves the range.
+        def each_batch(scope)
+          table = Messaging::DeliveryAttempt.arel_table
+          cursor = nil
+
+          loop do
+            batch_scope = scope.order(:finished_at, :id).limit(BATCH_SIZE)
+            if cursor
+              batch_scope = batch_scope.where(
+                table[:finished_at].gt(cursor[:finished_at]).or(
+                  table[:finished_at].eq(cursor[:finished_at]).and(table[:id].gt(cursor[:id])),
+                ),
+              )
+            end
+
+            rows = batch_scope.preload(channel_delivery: :communication).to_a
+            break if rows.empty?
+
+            yield rows
+            break if rows.size < BATCH_SIZE
+
+            cursor = { finished_at: rows.last.finished_at, id: rows.last.id }
+          end
+        end
+
+        def cleanup_pass
+          each_batch(cleanup_scope) do |rows|
+            rows.each do |attempt|
+              next if pending_entries(attempt.provider_metadata).empty?
+
+              update_attempt(attempt, receipts: {}, expire: true)
+            end
+          end
+        end
+
+        def poll_pass
+          each_batch(poll_scope) do |rows|
+            pending = rows.select { |attempt| pending_entries(attempt.provider_metadata).any? }
+            next if pending.empty?
+
+            requested_ids = pending.flat_map { |attempt| pending_entries(attempt.provider_metadata).pluck("ticket_id") }
+            receipts = fetch_receipts(requested_ids.uniq)
+            next if receipts.empty?
+
+            pending.each do |attempt|
+              ticket_ids = pending_entries(attempt.provider_metadata).pluck("ticket_id")
+              next unless ticket_ids.any? { |ticket_id| receipts.key?(ticket_id) }
+
+              update_attempt(attempt, receipts:, expire: false)
+            end
+          end
+        end
+
+        def fetch_receipts(ticket_ids)
+          receipts = {}
+          ticket_ids.each_slice(RECEIPT_ID_CHUNK_SIZE) do |slice|
+            result = http_client.get_receipts(slice)
+            if result.is_a?(Hash) && result[:ok] && result[:receipts].is_a?(Hash)
+              receipts.merge!(result[:receipts])
+            else
+              @counts[:poll_failure_count] += 1
+            end
+          rescue StandardError
+            @counts[:poll_failure_count] += 1
+          end
+          receipts
+        end
+
+        def pending_entries(metadata)
+          endpoints = metadata.is_a?(Hash) ? metadata.dig("expo", "endpoints") : nil
+          return [] unless endpoints.is_a?(Array)
+
+          endpoints.select do |entry|
+            entry.is_a?(Hash) &&
+              entry["ticket_status"] == "ok" &&
+              entry["receipt_status"] == "pending" &&
+              entry["ticket_id"].present?
+          end
+        end
+
+        # One short transaction per attempt. A failure rolls back only this attempt and the pass
+        # continues with the next one; its entries stay pending for a later sweep.
+        def update_attempt(attempt, receipts:, expire:)
+          deltas = Hash.new(0)
+
+          ActiveRecord::Base.transaction do
+            attempt.lock!
+            metadata = attempt.provider_metadata.deep_dup
+            changed = false
+
+            pending_entries(metadata).each do |entry|
+              outcome = apply_outcome!(attempt:, entry:, receipt: receipts[entry["ticket_id"]], expire:, deltas:)
+              changed = true if outcome
+            end
+
+            attempt.update!(provider_metadata: metadata) if changed
+            deltas[:attempt_count] += 1 if changed
+          end
+
+          deltas.each { |key, value| @counts[key] += value }
+        rescue StandardError
+          @counts[:update_failure_count] += 1
+        end
+
+        # Returns :unchecked, :ok, or :error when the entry changed, nil when it stays pending.
+        def apply_outcome!(attempt:, entry:, receipt:, expire:, deltas:)
+          if expire
+            entry["receipt_status"] = "unchecked"
+            deltas[:receipt_unchecked_count] += 1
+            return :unchecked
+          end
+
+          case receipt&.dig(:status)
+          when "ok"
+            entry["receipt_status"] = "ok"
+            deltas[:receipt_ok_count] += 1
+            :ok
+          when "error"
+            record_receipt_error!(attempt:, entry:, receipt:, deltas:)
+            :error
+          end
+        end
+
+        def record_receipt_error!(attempt:, entry:, receipt:, deltas:)
+          entry["receipt_status"] = "error"
+          if DEVICE_INVALID_ERRORS.include?(receipt[:error].to_s)
+            entry["error_code"] = "expo_device_invalid"
+            invalidate_endpoint!(attempt:, endpoint_id: entry["endpoint_id"], deltas:)
+          else
+            entry["error_code"] = "expo_rejected"
+          end
+          deltas[:receipt_error_count] += 1
+        end
+
+        def invalidate_endpoint!(attempt:, endpoint_id:, deltas:)
+          owner_user_id = attempt.channel_delivery&.communication&.user_id
+          return if owner_user_id.nil? || endpoint_id.nil?
+
+          Endpoints.mark_invalid(owner_user_id:, endpoint_id:)
+          deltas[:invalidated_count] += 1
+        rescue Endpoints::NotFoundError, Endpoints::ValidationError
+          # The device endpoint is already gone; the receipt error is still recorded.
+          nil
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/execution/operation_logger.rb

@@ -45,6 +45,15 @@ module CommandTower
             info("messaging.execution.recovered", channel_delivery:)
           end
 
+          # One aggregate event per recovery sweep. Counts only; nothing when nothing happened.
+          def receipts_collected(counts)
+            counts = counts.to_h.slice(*ExpoReceiptCollection::COUNT_KEYS)
+            return if counts.values.sum.zero?
+
+            failed = counts[:poll_failure_count].to_i.positive? || counts[:update_failure_count].to_i.positive?
+            emit(failed ? :error : :info, "messaging.execution.receipts.collected", **counts)
+          end
+
           def attempt_started(channel_delivery:, delivery_attempt:)
             emit_attempt("messaging.execution.attempt.started", channel_delivery:, delivery_attempt:)
           end
@@ -62,6 +71,28 @@ module CommandTower
             )
           end
 
+          def push_destination_fallback(communication:, reason_code:, level:, channel_delivery: nil)
+            emit(
+              level,
+              "messaging.execution.push_destination.fallback",
+              channel_delivery:,
+              communication_id: communication.id,
+              notification_type_key: communication.notification_type_key.to_s,
+              reason_code:,
+            )
+          end
+
+          def push_presentation_fallback(communication:, reason_code:, channel_delivery: nil)
+            emit(
+              :warn,
+              "messaging.execution.push_presentation.fallback",
+              channel_delivery:,
+              communication_id: communication.id,
+              notification_type_key: communication.notification_type_key.to_s,
+              reason_code:,
+            )
+          end
+
           def attempt_create_failed(channel_delivery:, error:)
             emit(
               :error,
@@ -110,32 +141,35 @@ module CommandTower
             )
           end
 
-          def adapter_accepted(channel_delivery:, delivery_attempt:)
+          def adapter_accepted(channel_delivery:, delivery_attempt:, provider_metadata: nil)
             emit_adapter(
               :info,
               "messaging.execution.adapter.accepted",
               channel_delivery:,
               delivery_attempt:,
+              **provider_metadata_counts(provider_metadata),
             )
           end
 
-          def adapter_retryable(channel_delivery:, delivery_attempt:, error_code:)
+          def adapter_retryable(channel_delivery:, delivery_attempt:, error_code:, provider_metadata: nil)
             emit_adapter(
               :error,
               "messaging.execution.adapter.retryable",
               channel_delivery:,
               delivery_attempt:,
               error_code:,
+              **provider_metadata_counts(provider_metadata),
             )
           end
 
-          def adapter_terminal(channel_delivery:, delivery_attempt:, error_code:)
+          def adapter_terminal(channel_delivery:, delivery_attempt:, error_code:, provider_metadata: nil)
             emit_adapter(
               :error,
               "messaging.execution.adapter.terminal",
               channel_delivery:,
               delivery_attempt:,
               error_code:,
+              **provider_metadata_counts(provider_metadata),
             )
           end
 
@@ -178,16 +212,32 @@ module CommandTower
             )
           end
 
-          def emit_adapter(level, event, channel_delivery:, delivery_attempt:, error_code: nil)
+          # extra: optional error_code and provider_metadata counts.
+          def emit_adapter(level, event, channel_delivery:, delivery_attempt:, **extra)
             emit(
               level,
               event,
               channel_delivery:,
               delivery_attempt_id: delivery_attempt.id,
-              error_code:,
+              error_code: nil,
+              **extra,
             )
           end
 
+          # Counts only; the per-device record stays on the attempt row.
+          def provider_metadata_counts(provider_metadata)
+            endpoints = provider_metadata.is_a?(Hash) ? provider_metadata.dig("expo", "endpoints") : nil
+            return {} unless endpoints.is_a?(Array)
+
+            ticket_statuses = endpoints.pluck("ticket_status")
+            {
+              endpoint_count: endpoints.size,
+              ticket_ok_count: ticket_statuses.count("ok"),
+              ticket_error_count: ticket_statuses.count { |status| %w[error missing].include?(status) },
+              receipt_pending_count: endpoints.count { |endpoint| endpoint["receipt_status"] == "pending" },
+            }
+          end
+
           def info(event, channel_delivery:)
             emit(:info, event, channel_delivery:)
           end

data/app/services/command_tower/messaging/execution/recovery.rb

@@ -23,10 +23,18 @@ module CommandTower
           recover_queued!
           recover_failed!
           recover_stale_executing!
+          collect_expo_receipts!
         end
 
         private
 
+        # Runs last so it can never block a redrive. It only reads receipts and updates metadata.
+        def collect_expo_receipts!
+          ExpoReceiptCollection.call
+        rescue StandardError
+          OperationLogger.receipts_collected(update_failure_count: 1)
+        end
+
         def grace_before
           @grace_window.ago
         end

data/app/services/command_tower/messaging/inbox/reader.rb

@@ -65,13 +65,26 @@ module CommandTower
 
           def unread_count(recipient_id:)
             recipient_id = require_recipient_id!(recipient_id)
+            unread = Scope.for_recipient(recipient_id).merge(Messaging::InboxItem.unread)
 
-            count = Scope.for_recipient(recipient_id).merge(Messaging::InboxItem.unread).count
-            UnreadCountResult.build(recipient_id:, count:)
+            UnreadCountResult.build(
+              recipient_id:,
+              count: unread.count,
+              badge_count: badge_eligible_count(unread),
+            )
           end
 
           private
 
+          # Unread rows whose declaration is badge_eligible. Unregistered keys are absent
+          # from that set. Channel preferences are not consulted.
+          def badge_eligible_count(unread)
+            keys = CommandTower::Messaging::NotificationTypes.enumerate.select(&:badge_eligible).map(&:key)
+            return 0 if keys.empty?
+
+            unread.where(messaging_communications: { notification_type_key: keys }).count
+          end
+
           def require_recipient_id!(recipient_id)
             raise ValidationError, "recipient_id is required" if blank?(recipient_id)
 

data/app/services/command_tower/messaging/inbox/unread_count_result.rb

@@ -3,11 +3,12 @@
 module CommandTower
   module Messaging
     module Inbox
-      UnreadCountResult = Data.define(:recipient_id, :count) do
-        def self.build(recipient_id:, count:)
+      UnreadCountResult = Data.define(:recipient_id, :count, :badge_count) do
+        def self.build(recipient_id:, count:, badge_count:)
           new(
             recipient_id:,
             count: Integer(count),
+            badge_count: Integer(badge_count),
           ).freeze
         end
       end

data/app/services/command_tower/messaging/notification_types/declaration.rb

@@ -23,6 +23,10 @@ module CommandTower
         :delivery_status_visible,
         :host_ownership,
         :inbox_document_composer,
+        :badge_eligible,
+        :urgency,
+        :sound,
+        :deep_link_required,
       ) do
         def self.build(
           key:,
@@ -43,7 +47,11 @@ module CommandTower
           retention: nil,
           delivery_status_visible: nil,
           host_ownership: nil,
-          inbox_document_composer: nil
+          inbox_document_composer: nil,
+          badge_eligible: false,
+          urgency: nil,
+          sound: nil,
+          deep_link_required: false
         )
           new(
             key: key.nil? ? nil : key.to_s,
@@ -75,6 +83,16 @@ module CommandTower
             # renders via `InboxDocumentRenderer#build_generic`. See
             # artifacts/visual-improvements/rich-messaging/authority/RICH_MESSAGING_RUBY_INBOX_DEFINITION_DISCOVERY.md.
             inbox_document_composer: inbox_document_composer.nil? ? nil : inbox_document_composer.to_s,
+            # Notification Product Behavior (NPB-1). All default to today's behavior.
+            # `badge_eligible`: unread inbox items of this type count toward the app-icon badge.
+            # `urgency` / `sound`: `{ default:, allowed: [ids] | "all" }`; nil is fixed
+            # "normal" / "default". Invalid input is kept so DeclarationValidator reports it.
+            badge_eligible: !!badge_eligible,
+            urgency: PermittedChoice.from(urgency, fallback_default: "normal"),
+            sound: PermittedChoice.from(sound, fallback_default: "default"),
+            # NPB-5. Push-capable types that are not inbox-backed must set this
+            # so Produce can reject a missing metadata deep_link.
+            deep_link_required: !!deep_link_required,
           ).freeze
         end
 

data/app/services/command_tower/messaging/notification_types/declaration_validator.rb

@@ -72,9 +72,36 @@ module CommandTower
             errors << "settings_visible must be a boolean"
           end
 
+          validate_permitted_choice(
+            errors, declaration.urgency, field: "urgency",
+            valid_value: ->(value) { URGENCY_LEVELS.include?(value) },
+            invalid_message: "unknown urgency level"
+          )
+          validate_permitted_choice(
+            errors, declaration.sound, field: "sound",
+            valid_value: ->(value) { SoundCatalog::ID_FORMAT.match?(value) },
+            invalid_message: "malformed sound id"
+          )
+
+          if push_capable?(declaration) && !declaration.inbox_available && !declaration.deep_link_required
+            errors << "push-capable types must be inbox-backed or declare deep_link_required"
+          end
+
           errors
         end
 
+        # Seal-time check: every sound a declaration names is registered in the catalog.
+        def self.sound_reference_errors(declaration, catalog_ids:)
+          choice = declaration&.sound
+          return [] unless choice.is_a?(PermittedChoice)
+
+          named = ([choice.default] + (choice.allowed.is_a?(Array) ? choice.allowed : [])).compact.uniq
+          missing = named - catalog_ids
+          return [] if missing.empty?
+
+          ["sound references unregistered sound ids: #{missing.join(', ')}"]
+        end
+
         def self.validate_category_consistency!(declaration, peers:)
           errors = category_consistency_errors(declaration, peers:)
           return if errors.empty?
@@ -131,6 +158,41 @@ module CommandTower
         end
         private_class_method :validate_non_negative_integer
 
+        def self.validate_permitted_choice(errors, choice, field:, valid_value:, invalid_message:)
+          unless choice.is_a?(PermittedChoice)
+            errors << "#{field} must be a hash with default and allowed"
+            return
+          end
+
+          default = choice.default
+          allowed = choice.allowed
+          values = []
+
+          if default.is_a?(String) && !default.strip.empty?
+            values << default
+          else
+            errors << "#{field} default must be present"
+          end
+
+          # "all" permits every value in the universe, so only the default is checked.
+          if allowed.is_a?(Array) && allowed.any?
+            values.concat(allowed)
+            errors << "#{field} allowed contains duplicates" if allowed.uniq.size != allowed.size
+            errors << "#{field} default must be one of allowed" if default && allowed.exclude?(default)
+          elsif allowed != "all"
+            errors << "#{field} allowed must be \"all\" or a non-empty array"
+          end
+
+          bad = values.uniq.reject { |value| value.is_a?(String) && valid_value.call(value) }
+          errors << "#{field} has #{invalid_message}: #{bad.map(&:inspect).join(', ')}" if bad.any?
+        end
+        private_class_method :validate_permitted_choice
+
+        def self.push_capable?(declaration)
+          declaration.allowed_channels.is_a?(Array) && declaration.allowed_channels.include?("push")
+        end
+        private_class_method :push_capable?
+
         def self.validate_channel_list(errors, channels, field:)
           channels.each do |channel|
             key = channel.to_s

data/app/services/command_tower/messaging/notification_types/permitted_choice.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module NotificationTypes
+      # A declared default plus the values a member may choose from. Used by the
+      # `urgency` and `sound` declaration fields. `allowed` is either an Array of ids or
+      # the String "all" (every value in the universe). The mode is derived from
+      # `allowed`, never stored:
+      #
+      #   fixed       one permitted value
+      #   restricted  an explicit list of more than one
+      #   full        "all"
+      PermittedChoice = Data.define(:default, :allowed) do
+        # Normalizes a declaration input. `nil` becomes a choice fixed on `fallback_default`.
+        # A Hash is coerced. Any other value is returned unchanged so the validator can
+        # report it (mirrors how `default_preference_state` is handled).
+        def self.from(raw, fallback_default:)
+          return new(default: fallback_default, allowed: [fallback_default].freeze) if raw.nil?
+          return raw unless raw.is_a?(Hash)
+
+          hash = raw.transform_keys(&:to_sym)
+          default = hash[:default]&.to_s
+          allowed = hash[:allowed]
+          allowed =
+            if allowed.nil?
+              default.nil? ? nil : [default].freeze
+            elsif allowed.is_a?(Array)
+              allowed.map(&:to_s).freeze
+            elsif allowed.to_s == "all"
+              "all"
+            else
+              allowed
+            end
+
+          new(default:, allowed:)
+        end
+
+        def mode
+          return :full if allowed == "all"
+
+          allowed.size > 1 ? :restricted : :fixed
+        end
+
+        def permitted(universe)
+          allowed == "all" ? universe.to_a : allowed
+        end
+
+        def selectable?(universe)
+          permitted(universe).size > 1
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/notification_types/registry.rb

@@ -88,10 +88,35 @@ module CommandTower
             DeclarationValidator.validate!(declaration)
           end
 
+          validate_sound_references!
+
           @declarations.each_value do |declaration|
             peers = @declarations.values.reject { |peer| peer.equal?(declaration) || peer.key == declaration.key }
             DeclarationValidator.validate_category_consistency!(declaration, peers:)
           end
+
+          validate_home_deep_link_configuration!
+        end
+
+        # Sound ids are checked at seal, not register, so host initializer order cannot matter.
+        def validate_sound_references!
+          catalog_errors = SoundCatalog.validation_errors
+          raise InvalidDeclarationError, "invalid sound catalog: #{catalog_errors.join('; ')}" if catalog_errors.any?
+
+          @declarations.each_value do |declaration|
+            errors = DeclarationValidator.sound_reference_errors(declaration, catalog_ids: SoundCatalog.ids)
+            raise InvalidDeclarationError, "#{declaration.key}: #{errors.join('; ')}" if errors.any?
+          end
+        end
+
+        # Presence only. A Proc is configured and is not called here.
+        def validate_home_deep_link_configuration!
+          return if CommandTower.config.messaging.expo.adapter.to_s == "disabled"
+          return unless @declarations.values.any? { |declaration| declaration.allowed_channels.include?("push") }
+          return if CommandTower.config.messaging.expo.home_deep_link_configured?
+
+          raise InvalidDeclarationError,
+            "home_deep_link must be configured when a push-capable type is registered and the Expo adapter is enabled"
         end
 
         def type_sort_key(declaration)

data/app/services/command_tower/messaging/notification_types.rb

@@ -3,6 +3,9 @@
 module CommandTower
   module Messaging
     module NotificationTypes
+      # Push urgency levels a declaration may permit (D-8). IOS maps them to the OS.
+      URGENCY_LEVELS = %w[normal time_sensitive critical].freeze
+
       module_function
 
       def register(declaration)

data/app/services/command_tower/messaging/preferences/catalog.rb

@@ -75,6 +75,11 @@ module CommandTower
           available =
             declaration.allowed_channels & @platform_enabled_channels & recipient_ready_keys
 
+          blocks = EffectiveChoice.call(
+            declaration:,
+            stored: Store.find(recipient_id: @recipient_id, notification_type_key: declaration.key),
+          )
+
           ::CommandTower::Messaging::Preferences::CatalogNotificationResult.build(
             key: declaration.key,
             label: declaration.label,
@@ -88,6 +93,8 @@ module CommandTower
             inbox_enabled:,
             channels:,
             stored_override_present: evaluation.stored_override_present,
+            urgency: blocks[:urgency],
+            sound: blocks[:sound],
           )
         end
       end