mixin_bot 2.6.0 → 3.0.2

data/lib/mixin_bot/json_decoder.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MixinBot
+  # json 3.x made +JSON.parse+ keyword-only, while faraday's JSON middleware
+  # calls its decoder with positional options. Splatted keywords keep this
+  # compatible with both json 2.x and 3.x.
+  module JSONDecoder
+    module_function
+
+    def parse(body, options = {})
+      JSON.parse(body, **options)
+    end
+  end
+end

data/lib/mixin_bot/notifications/mixin_channel.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Loads only when the Noticed gem is already loaded (it is in every app that
+# declares `deliver_by :mixin`); requiring the integration layer without
+# Noticed neither raises nor loads this file's contents.
+return unless defined?(Noticed::Channel)
+
+module MixinBot
+  module Notifications
+    ##
+    # Noticed delivery channel that sends the notification as a Mixin message
+    # over the HTTP message API.
+    #
+    # Notification-class contract (all resolution lives in the notification,
+    # so the channel stays a thin adapter over Noticed's surface):
+    #
+    #   class PaymentReceivedNotification < Noticed::Notification
+    #     deliver_by :mixin                      # or: deliver_by :mixin, bot: :shop
+    #
+    #     def mixin_recipient                    # Mixin user id to deliver to
+    #       recipient.mixin_user_id
+    #     end
+    #
+    #     def mixin_message
+    #       { category: 'PLAIN_TEXT', content: "received #{params[:amount]}" }
+    #     end
+    #   end
+    #
+    # mixin_message supports {category: 'PLAIN_TEXT'|'PLAIN_POST', content:}
+    # and {category: 'APP_CARD', card: {title:, description:, action:, ...}}.
+    # When the notification class does not define #mixin_recipient, the
+    # channel falls back to the recipient record's #mixin_user_id.
+    #
+    # Delivery failures raise out of #deliver — Noticed captures them per
+    # delivery without aborting sibling channels.
+    #
+    class MixinChannel < ::Noticed::Channel
+      def deliver
+        api.send_message(payload)
+      end
+
+      private
+
+      def api
+        @api ||=
+          if params[:bot]
+            MixinBot.bot(params[:bot])
+          else
+            MixinBot.api
+          end
+      end
+
+      def payload
+        message = notification.try(:mixin_message) ||
+                  raise(MixinBot::ArgumentError,
+                        "#{notification.class} must define #mixin_message for the mixin channel")
+
+        options = { recipient_id: recipient_id, data: message[:content] }
+        case message[:category]
+        when 'PLAIN_POST' then api.plain_post(options)
+        when 'APP_CARD' then api.app_card(options.merge(data: message[:card]))
+        else api.plain_text(options)
+        end
+      end
+
+      def recipient_id
+        id =
+          if notification.respond_to?(:mixin_recipient)
+            notification.mixin_recipient
+          elsif recipient.respond_to?(:mixin_user_id)
+            recipient.mixin_user_id
+          end
+
+        raise MixinBot::ArgumentError, 'could not resolve a Mixin recipient id' if id.blank?
+
+        id
+      end
+    end
+  end
+end

data/lib/mixin_bot/outputs/cursor_model.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module MixinBot
+  module Outputs
+    ##
+    # ActiveRecord concern for the generated +MixinPollerCursor+ model
+    # (mixin_bot:outputs generator): one row per bot app id, remembering the
+    # last absorbed output position (the outputs API's own created_at value).
+    #
+    #   class MixinPollerCursor < ApplicationRecord
+    #     include MixinBot::Outputs::CursorModel
+    #   end
+    #
+    # Required columns: bot_app_id (unique), value.
+    #
+    module CursorModel
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def value(bot_app_id:)
+          find_by(bot_app_id:)&.value
+        end
+
+        def advance!(bot_app_id:, value:)
+          record = find_or_initialize_by(bot_app_id:)
+          record.update!(value:)
+        end
+      end
+    end
+  end
+end

data/lib/mixin_bot/outputs/envelope.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+
+module MixinBot
+  module Outputs
+    ##
+    # Application-facing view of one Mixin output (a transfer touching the
+    # bot's Safe UTXO set — inbound or outbound).
+    #
+    # The output stream itself carries amount/asset/state but no memo; the
+    # memo, counterparty, and trace id are bridged lazily — at most once per
+    # output — through the snapshot notification API
+    # (+create_safe_snapshot_notification+). A failed bridge logs a warning
+    # and yields nil fields; processing continues without them.
+    #
+    # Wraps a receipt record (the poller's dedup row): output fields are read
+    # from it and resolved snapshot data is cached back onto it. Receipt-like
+    # objects must expose:
+    #   output_id, amount (String), asset_id, state, transaction_hash,
+    #   output_index, memo, opponent_id, trace_id
+    #   snapshot_bridged?            # bridge already attempted (success or not)
+    #   cache_snapshot!(memo:, opponent_id:, trace_id:)  # write-back
+    #
+    #   envelope.amount        # => BigDecimal
+    #   envelope.memo          # => String or nil (bridged on first access)
+    #   envelope.spent?        # => true when the output is spent
+    #
+    class Envelope
+      attr_reader :receipt, :api
+
+      ##
+      # @param receipt [Object] receipt record backing this envelope
+      # @param api [MixinBot::API] bot client used for the snapshot bridge
+      #
+      def initialize(receipt, api:)
+        @receipt = receipt
+        @api = api
+      end
+
+      def output_id
+        receipt.output_id
+      end
+
+      # The output's amount as a BigDecimal.
+      def amount
+        BigDecimal(receipt.amount.to_s)
+      end
+
+      def asset_id
+        receipt.asset_id
+      end
+
+      def transaction_hash
+        receipt.transaction_hash
+      end
+
+      def output_index
+        receipt.output_index
+      end
+
+      # The output's kernel sequence — unique and monotonic; the key the
+      # outputs API paginates on and the value processors can key on for
+      # ordering.
+      def sequence
+        receipt.sequence
+      end
+
+      # True when the output is spent (outbound from the bot's perspective).
+      def spent?
+        receipt.state == 'spent'
+      end
+
+      def state
+        receipt.state
+      end
+
+      ##
+      # Snapshot-derived memo; nil when the bridge failed or the snapshot has
+      # no memo. Bridged at most once per output.
+      #
+      def memo
+        bridge_snapshot.memo
+      end
+
+      # Snapshot-derived counterparty user id; nil on bridge failure.
+      def opponent_id
+        bridge_snapshot.opponent_id
+      end
+
+      # Snapshot-derived trace id (the sender's idempotency trace); nil on
+      # bridge failure.
+      def trace_id
+        bridge_snapshot.trace_id
+      end
+
+      private
+
+      # Returns the memo/opponent/trace triple after a single bridge attempt.
+      # Receipts whose bridge already ran (success OR failure — the flag is
+      # written in both cases) short-circuit the API call, so each output is
+      # bridged at most once per receipt lifetime, not just per Envelope.
+      def bridge_snapshot
+        return @bridge_snapshot if defined?(@bridge_snapshot)
+
+        if receipt.respond_to?(:snapshot_bridged?) && receipt.snapshot_bridged?
+          return Snapshot.new(memo: receipt.memo, opponent_id: receipt.opponent_id,
+                              trace_id: receipt.trace_id, bridged: true)
+        end
+
+        fetch_snapshot
+      end
+
+      def fetch_snapshot
+        response = api.create_safe_snapshot_notification(
+          transaction_hash: receipt.transaction_hash,
+          output_index: receipt.output_index,
+          receiver_id: api.config.app_id
+        )
+
+        snapshot = response['data'].is_a?(Hash) ? response['data'] : {}
+
+        fields = Snapshot.new(
+          memo: snapshot['memo'],
+          opponent_id: snapshot['opponent_id'],
+          trace_id: snapshot['trace_id'],
+          bridged: true
+        )
+
+        if receipt.respond_to?(:cache_snapshot!)
+          receipt.cache_snapshot!(
+            memo: fields.memo,
+            opponent_id: fields.opponent_id,
+            trace_id: fields.trace_id
+          )
+        end
+
+        fields
+      rescue StandardError => e
+        MixinBot::Outputs.logger.call(:snapshot_bridge_error,
+                                      "#{e.class}: #{e.message} (output #{receipt.output_id})")
+        # Mark the attempt even on failure so later jobs don't re-POST.
+        receipt.cache_snapshot!(memo: nil, opponent_id: nil, trace_id: nil) if receipt.respond_to?(:cache_snapshot!)
+        Snapshot.new(memo: nil, opponent_id: nil, trace_id: nil, bridged: false)
+      end
+
+      # Immutable triple of bridged snapshot fields.
+      Snapshot = Struct.new(:memo, :opponent_id, :trace_id, keyword_init: true) do
+        def initialize(bridged:, memo: nil, opponent_id: nil, trace_id: nil)
+          super(memo:, opponent_id:, trace_id:)
+          @bridged = bridged
+        end
+
+        def bridged?
+          @bridged
+        end
+      end
+    end
+  end
+end

data/lib/mixin_bot/outputs/memory_stores.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module MixinBot
+  module Outputs
+    ##
+    # In-memory receipt store: the dedup gate + enqueue bookkeeping the poller
+    # needs, backed by nothing but a Hash. Used by the offline test suite and
+    # available for non-ActiveRecord hosts; Rails applications use the
+    # generated +MixinOutput+ model (see {ReceiptModel}), which implements the
+    # same interface:
+    #
+    #   record!(bot_app_id:, output:)        # => [receipt, :created] or
+    #                                        #    [existing, :duplicate]
+    #   mark_enqueued!(receipt)              # stamp the receipt as dispatched
+    #   unenqueued(bot_app_id:, older_than:) # records not yet dispatched
+    #   cursor_value(bot_app_id:)            # poller resume position
+    #
+    class MemoryReceiptStore
+      ##
+      # A receipt row: the poller's dedup + cache record for one output.
+      # Field names match the generated +mixin_outputs+ table columns.
+      #
+      Receipt = Struct.new(
+        :id, :bot_app_id, :output_id, :amount, :asset_id, :state,
+        :transaction_hash, :output_index, :sequence, :created_at,
+        :memo, :opponent_id, :trace_id, :snapshot_bridged,
+        :enqueued_at, :recorded_at,
+        keyword_init: true
+      ) do
+        def snapshot_bridged?
+          snapshot_bridged ? true : false
+        end
+
+        # Writes resolved snapshot data back onto the receipt (one-time cache)
+        # and marks the bridge as attempted — even when it failed with all-nil
+        # fields, so it is not retried per job.
+        def cache_snapshot!(memo:, opponent_id:, trace_id:)
+          self.memo = memo
+          self.opponent_id = opponent_id
+          self.trace_id = trace_id
+          self.snapshot_bridged = true
+        end
+      end
+
+      def initialize(clock: -> { Time.now })
+        @records = {}
+        @sequence = 0
+        @clock = clock
+      end
+
+      def record!(bot_app_id:, output:)
+        key = [bot_app_id, output['output_id']]
+        existing = @records[key]
+        return [existing, :duplicate] if existing
+
+        @sequence += 1
+        receipt = Receipt.new(
+          id: @sequence,
+          bot_app_id:,
+          output_id: output['output_id'],
+          amount: output['amount'],
+          asset_id: output['asset_id'],
+          state: output['state'],
+          transaction_hash: output['transaction_hash'],
+          output_index: output['output_index'],
+          sequence: output['sequence'],
+          created_at: output['created_at'],
+          recorded_at: @clock.call
+        )
+        @records[key] = receipt
+        [receipt, :created]
+      end
+
+      def mark_enqueued!(receipt)
+        receipt.enqueued_at = @clock.call
+      end
+
+      def unenqueued(bot_app_id:, older_than:)
+        @records.values.select do |receipt|
+          receipt.bot_app_id == bot_app_id &&
+            receipt.enqueued_at.nil? &&
+            receipt.recorded_at < older_than
+        end
+      end
+
+      # The poller's resume position: the newest output sequence this bot has
+      # recorded — unique and monotonic, and the key the outputs API paginates
+      # on (nil = fetch from the beginning).
+      def cursor_value(bot_app_id:)
+        @records.values
+                .select { |receipt| receipt.bot_app_id == bot_app_id }
+                .filter_map(&:sequence)
+                .max
+      end
+    end
+  end
+end

data/lib/mixin_bot/outputs/poller.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module MixinBot
+  module Outputs
+    ##
+    # The polling loop: fetches a page of the bot's outputs oldest-first,
+    # records unseen outputs in the receipt store (the dedup gate), enqueues
+    # every matching processor through the job queue, and advances its cursor
+    # only after the whole page is absorbed.
+    #
+    # The resume cursor is derived from the receipts themselves — the newest
+    # output sequence recorded for the bot (unique, monotonic, and the key
+    # the outputs API paginates on) — and kept in memory afterwards: receipts
+    # recorded past a mid-page failure cover the remainder (the API returns
+    # outputs strictly after the offset), so there is no gap and no separate
+    # cursor state.
+    #
+    # Each loop iteration first sweeps receipts that were recorded but never
+    # dispatched (a crash between the two steps), re-evaluating predicates and
+    # enqueueing late — making dispatch at-least-once.
+    #
+    # All collaborators are injectable for offline testing: sleeper, clock,
+    # receipt store, processor list, and the enqueue hook. {#run} blocks until
+    # {#stop}; signal wiring is the process's job (the mixin_bot:poller rake
+    # task).
+    #
+    #   poller = Poller.new(api: MixinBot.bot(:shop), interval: 5)
+    #   trap('TERM') { poller.stop }
+    #   poller.run
+    #
+    class Poller
+      DEFAULT_INTERVAL = 5
+      DEFAULT_PAGE_SIZE = 500
+
+      attr_reader :api, :receipts, :interval, :page_size
+
+      # rubocop:disable Metrics/ParameterLists
+      ##
+      # @param api [MixinBot::API] the bot whose outputs are polled
+      # @param receipts [#record!, #mark_enqueued!, #unenqueued, #cursor_value]
+      #   receipt store (default: the registered store from the generated
+      #   model, else in-memory; Rails hosts normally rely on the registration)
+      # @param processors [Array<Class>, nil] processor classes; nil discovers
+      #   them from the Mixin::Processors namespace on first use
+      # @param interval [Numeric] seconds between fetch cycles
+      # @param page_size [Integer] outputs fetched per cycle
+      # @param state [String] output state filter ('' = all states, covering
+      #   inbound unspent outputs and outbound spent ones)
+      # @param asset [String, nil] restrict polling to one asset id
+      # @param members [Array<String>, String, nil] restrict polling to these
+      #   member user ids (defaults to the bot itself at the API)
+      # @param threshold [Integer, nil] members threshold (defaults to the
+      #   members count at the API)
+      # @param enqueuer [#call, nil] called with (processor_class, receipt);
+      #   defaults to ProcessingJob.perform_later
+      # @param sleeper [#call, nil] called with seconds between cycles
+      # @param clock [#call, nil] returns current Time (sweep bookkeeping)
+      # @param logger [#call, nil] called with (level, detail)
+      #
+      def initialize(api: MixinBot.api, receipts: nil,
+                     processors: nil, interval: DEFAULT_INTERVAL, page_size: DEFAULT_PAGE_SIZE, state: '',
+                     asset: nil, members: nil, threshold: nil,
+                     enqueuer: nil, sleeper: nil, clock: nil, logger: nil)
+        @api = api
+        @bot_app_id = api.config.app_id
+        @receipts = receipts || Outputs.receipt_store || MemoryReceiptStore.new
+        @processors = processors
+        @interval = interval
+        @page_size = page_size
+        @state = state
+        @asset = asset
+        @members = Array(members) if members
+        @threshold = threshold
+        @enqueuer = enqueuer || ->(processor, receipt) { ProcessingJob.perform_later(receipt.id, processor.name) }
+        @sleeper = sleeper || ->(seconds) { sleep seconds }
+        @clock = clock || -> { Time.now }
+        @logger = logger || Outputs.logger
+        @stopping = false
+        @cursor_value = nil
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      ##
+      # Runs fetch cycles until {#stop} is called. One cycle = sweep stale
+      # receipts, fetch a page, absorb every output, advance the cursor.
+      # Cycle errors are logged and retried after the interval; the cursor
+      # only moves after a fully absorbed page.
+      #
+      # @return [void]
+      #
+      def run
+        until stopped?
+          begin
+            poll_once
+          rescue StandardError => e
+            @logger.call(:poll_error, e)
+          end
+
+          break if stopped?
+
+          @sleeper.call @interval
+        end
+      end
+
+      ##
+      # Requests termination; the in-flight cycle finishes first.
+      #
+      # Signal-safe: a plain flag (no Mutex — trap handlers cannot synchronize).
+      def stop
+        @stopping = true
+      end
+
+      def stopped?
+        @stopping
+      end
+
+      ##
+      # One fetch cycle. Exposed for tests and callers that drive the loop
+      # themselves.
+      #
+      # @return [Integer] number of outputs in the fetched page
+      #
+      def poll_once
+        sweep_undispatched
+
+        page = fetch_page
+        page.each { |output| absorb(output) }
+
+        @cursor_value = page.last['sequence'] if page.last
+        page.size
+      end
+
+      private
+
+      def sweep_undispatched
+        cutoff = @clock.call - @interval
+        @receipts.unenqueued(bot_app_id: @bot_app_id, older_than: cutoff).each do |receipt|
+          dispatch(Envelope.new(receipt, api: @api), receipt)
+        end
+      end
+
+      # Resume position: the newest recorded receipt for this bot, held in
+      # memory afterwards (advance = in-memory, no persistence needed).
+      def fetch_page
+        @cursor_value ||= @receipts.cursor_value(bot_app_id: @bot_app_id)
+
+        response = @api.safe_outputs(
+          state: @state, limit: @page_size, offset: @cursor_value.to_s, order: 'ASC',
+          asset: @asset, members: @members, threshold: @threshold
+        )
+        Array(response['data'])
+      end
+
+      def absorb(output)
+        receipt, status = @receipts.record!(bot_app_id: @bot_app_id, output:)
+        return if status == :duplicate
+
+        dispatch(Envelope.new(receipt, api: @api), receipt)
+      end
+
+      # Evaluates every processor against the envelope and enqueues the
+      # matches, then stamps the receipt as dispatched. An output matching no
+      # processor is stamped without work.
+      def dispatch(envelope, receipt)
+        processor_list(envelope).each { |processor| @enqueuer.call(processor, receipt) }
+        @receipts.mark_enqueued!(receipt)
+      rescue StandardError => e
+        # Leave the receipt undispatched so the next sweep retries the enqueue.
+        @logger.call(:dispatch_error, "#{e.class}: #{e.message} (output #{receipt.output_id})")
+      end
+
+      def processor_list(envelope)
+        @processors ||= Processors.discover
+        Processors.for_envelope(envelope, processors: @processors)
+      end
+    end
+  end
+end

data/lib/mixin_bot/outputs/processing_job.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+begin
+  require 'active_job/base'
+rescue LoadError
+  nil
+end
+
+module MixinBot
+  module Outputs
+    ##
+    # The poller's processing job — carries only (receipt id, processor class
+    # name) in its payload and rehydrates everything else at run time: the
+    # receipt from the application's receipt loader, the bot API client from
+    # the receipt's app id, and the envelope from the receipt.
+    #
+    # Defined only when ActiveJob is available (it is in every Rails stack
+    # that runs a job queue).
+    #
+    if defined?(ActiveJob::Base)
+      class ProcessingJob < ActiveJob::Base
+        queue_as :mixin_outputs
+
+        # @param receipt_id [Object] the receipt record's primary key
+        # @param processor_name [String] fully-qualified processor class name
+        def perform(receipt_id, processor_name)
+          loader = MixinBot::Outputs.receipt_loader
+          unless loader
+            raise ArgumentError,
+                  'no receipt loader configured: include MixinBot::Outputs::ReceiptModel ' \
+                  'in your receipt model (the mixin_bot:outputs generator does this)'
+          end
+
+          receipt = loader.call(receipt_id)
+          envelope = Envelope.new(receipt, api: api_for(receipt))
+          Processors.resolve(processor_name).new(envelope).call
+        end
+
+        private
+
+        # The receipt's own bot: nil bot_app_id = the default bot; an explicit
+        # app id that no longer resolves is a configuration error, never a
+        # reason to spend the default bot's credentials on it.
+        def api_for(receipt)
+          app_id = receipt.respond_to?(:bot_app_id) ? receipt.bot_app_id : nil
+          return MixinBot.api if app_id.blank?
+
+          MixinBot.bot_by_app_id(app_id) ||
+            raise(MixinBot::NotFoundError, "no bot registered for app_id #{app_id}")
+        end
+      end
+    end
+  end
+end