mixin_bot 3.0.0 → 3.0.2

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

data/lib/mixin_bot/outputs/processors.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module MixinBot
+  module Outputs
+    ##
+    # Base class for output processors. Subclass, implement class-level
+    # {matches?} and instance-level {#process}:
+    #
+    #   module Mixin
+    #     module Processors
+    #       class OrderDeposit < MixinBot::Outputs::Processor
+    #         def self.matches?(envelope)
+    #           !envelope.spent? && envelope.memo.to_s.start_with?('ORDER-')
+    #         end
+    #
+    #         def process
+    #           Order.settle_by_deposit!(envelope)
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # Processors live in app/mixin/processors (Rails autoloads them as
+    # Mixin::Processors::*). Every processor whose predicate matches an output
+    # gets a job enqueued — matches are independent side effects, and an
+    # output matching no processor is recorded only.
+    #
+    # Enqueue is at-least-once: processors should tolerate rare duplicate
+    # runs and can use the envelope's output_id as a natural idempotency key.
+    #
+    class Processor
+      def initialize(envelope)
+        @envelope = envelope
+      end
+
+      def call
+        process
+      end
+
+      attr_reader :envelope
+
+      # Override with the processor's selection predicate.
+      def self.matches?(_envelope)
+        false
+      end
+
+      def process
+        raise NotImplementedError, "#{self.class} must implement #process"
+      end
+    end
+
+    ##
+    # Processor discovery and selection over the Mixin::Processors namespace.
+    #
+    module Processors
+      NAMESPACE_NAME = 'Mixin::Processors'
+
+      module_function
+
+      ##
+      # All processor classes currently defined under Mixin::Processors. Under
+      # Rails the namespace is eager-loaded first so the poller process sees
+      # every processor without referencing each one.
+      #
+      # @return [Array<Class>]
+      #
+      def discover
+        eager_load_namespace! if defined?(::Rails.application) && ::Rails.application.respond_to?(:autoloaders)
+
+        namespace = namespace_class
+        return [] if namespace.nil?
+
+        namespace.constants.filter_map do |const|
+          candidate = namespace.const_get(const)
+          candidate if candidate.is_a?(Class) && candidate < Processor
+        end
+      end
+
+      # Finds a processor by fully-qualified class name (the payload the
+      # poller's jobs carry).
+      #
+      # @param name [String]
+      # @return [Class]
+      # @raise [NameError] when no such processor is loaded
+      #
+      def resolve(name)
+        constant = Object.const_get(name)
+        raise NameError, "#{name} is not a MixinBot::Outputs::Processor" unless constant.is_a?(Class) && constant < Processor
+
+        constant
+      end
+
+      ##
+      # Processors whose predicate matches the envelope.
+      #
+      # @return [Array<Class>]
+      #
+      def for_envelope(envelope, processors:)
+        processors.select { |processor| processor.matches?(envelope) }
+      end
+
+      def namespace_class
+        Object.const_get(NAMESPACE_NAME)
+      rescue NameError
+        nil
+      end
+
+      def eager_load_namespace!
+        autoloader = ::Rails.autoloaders.main
+        namespace = namespace_class
+        return if namespace.nil?
+
+        if autoloader.respond_to?(:eager_load_namespace)
+          autoloader.eager_load_namespace(namespace)
+        else
+          ::Rails.application.eager_load!
+        end
+      rescue Zeitwerk::SetupRequired, StandardError
+        # Best effort: an eager-load problem must not stop polling.
+        nil
+      end
+    end
+  end
+end

data/lib/mixin_bot/outputs/receipt_model.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module MixinBot
+  module Outputs
+    ##
+    # ActiveRecord concern for the generated +MixinOutput+ receipt model
+    # (mixin_bot:outputs generator). Implements the receipt-store interface
+    # the poller consumes, on top of the table's unique
+    # +(bot_app_id, output_id)+ index:
+    #
+    #   class MixinOutput < ApplicationRecord
+    #     include MixinBot::Outputs::ReceiptModel
+    #   end
+    #
+    # Including the model also registers it as the integration's receipt
+    # store (the mixin_bot:poller rake task) and as the processing job's
+    # receipt loader. The poller's resume cursor is derived from the receipts
+    # themselves — the newest output sequence per bot — so there is no
+    # separate cursor table.
+    #
+    # Required columns (see the generated migration): bot_app_id, output_id,
+    # amount, asset_id, state, transaction_hash, output_index, sequence
+    # (the outputs API's pagination key — the poller's cursor), memo,
+    # opponent_id, trace_id, snapshot_bridged, enqueued_at, plus Rails
+    # timestamps (created_at backs the sweep query).
+    #
+    module ReceiptModel
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Records the output or reports it as already seen. Uniqueness is
+        # enforced by the (bot_app_id, output_id) index, so concurrent pollers
+        # race safely.
+        def record!(bot_app_id:, output:)
+          existing = find_by(bot_app_id:, output_id: output['output_id'])
+          return [existing, :duplicate] if existing
+
+          receipt = create!(
+            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'],
+            output_created_at: output['created_at']
+          )
+          [receipt, :created]
+        rescue ActiveRecord::RecordNotUnique
+          [find_by!(bot_app_id:, output_id: output['output_id']), :duplicate]
+        end
+
+        def mark_enqueued!(receipt)
+          receipt.update!(enqueued_at: Time.now)
+        end
+
+        # created_at is the Rails timestamp (when the receipt row was written),
+        # so the sweep's cutoff means "recorded before this moment".
+        def unenqueued(bot_app_id:, older_than:)
+          where(bot_app_id:, enqueued_at: nil).where(created_at: ...older_than)
+        end
+
+        # The poller's resume position: the newest output sequence recorded
+        # for this bot — unique and monotonic, and the key the outputs API
+        # paginates on (nil = fetch from the beginning). Derived from the
+        # receipts themselves — no separate cursor state.
+        def cursor_value(bot_app_id:)
+          where(bot_app_id:).maximum(:sequence)
+        end
+      end
+
+      # Caches the envelope's resolved snapshot data (one bridge attempt per
+      # output — including failures, which cache nils and the flag).
+      def cache_snapshot!(memo:, opponent_id:, trace_id:)
+        update!(memo:, opponent_id:, trace_id:, snapshot_bridged: true) unless frozen?
+      end
+
+      included do
+        MixinBot::Outputs.receipt_loader = method(:find)
+        MixinBot::Outputs.receipt_store = self
+      end
+    end
+  end
+end

data/lib/mixin_bot/outputs.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module MixinBot
+  ##
+  # Output (transfer) polling integration: delivers every output touching the
+  # bot's Safe UTXO set — inbound or outbound — to application processor
+  # classes exactly once, via a standalone polling process and the
+  # application's job queue.
+  #
+  #   poller = MixinBot::Outputs::Poller.new(api: MixinBot.bot(:shop))
+  #   poller.run   # blocks; see the mixin_bot:poller rake task
+  #
+  module Outputs
+    class << self
+      # Shared logger for the outputs integration; called with (level, detail),
+      # same shape as MixinBot::Blaze::Reactor's logger. Injectable per
+      # component; this default is the fallback.
+      attr_accessor :logger
+
+      # Called with a receipt id to reload the receipt record when a processing
+      # job runs — set by the generated receipt model (ActiveRecord host apps).
+      # Without a loader, processing jobs raise a clear error explaining how to
+      # wire one.
+      attr_accessor :receipt_loader
+
+      # The receipt store the poller process uses — set by the generated
+      # receipt model when it loads. The mixin_bot:poller rake task refuses to
+      # run without one (polling with an in-memory store would silently lose
+      # dedup across restarts).
+      attr_accessor :receipt_store
+    end
+
+    self.logger = ->(level, detail) { warn "[mixin_outputs] #{level}: #{detail}" }
+  end
+end
+
+require_relative 'outputs/envelope'
+require_relative 'outputs/memory_stores'
+require_relative 'outputs/processors'
+require_relative 'outputs/poller'
+require_relative 'outputs/processing_job'
+require_relative 'outputs/receipt_model'

data/lib/mixin_bot/rails/railtie.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module MixinBot
+  # Registers the Rails integration's rake tasks and application-code
+  # conventions. Lives at lib/mixin_bot/rails/railtie.rb (loaded by
+  # `require 'mixin_bot/rails'`), named +MixinBot::Railtie+ — deliberately not
+  # +MixinBot::Rails+, which would lexically shadow ::Rails for code written
+  # inside module MixinBot.
+  #
+  # Application conventions:
+  # - +app/mixin/handlers+ hosts Blaze message handler classes
+  #   (+Mixin::Handlers::*+) and +app/mixin/processors+ hosts output
+  #   processor classes (+Mixin::Processors::*+). Rails' default path
+  #   inference would make +app/mixin+ itself a Zeitwerk root (mapping files
+  #   to +Handlers::*+ / +Processors::*+, not +Mixin::Handlers::*+), so the
+  #   railtie excludes it from the defaults and re-registers it with the
+  #   +Mixin+ namespace explicitly. Eager loading is the poller process's
+  #   responsibility (it eager-loads before discovering processors),
+  #   mirroring how Solid Queue's supervisor boots.
+  #
+  # Generator discovery needs no registration either: railties scans loaded
+  # gems for +lib/generators+ automatically.
+  class Railtie < ::Rails::Railtie
+    railtie_name 'mixin_bot'
+
+    initializer 'mixin_bot.exclude_default_mixin_root', before: :set_autoload_paths do |app|
+      app.config.paths.add 'app/mixin', autoload: false, eager_load: false
+    end
+
+    initializer 'mixin_bot.push_mixin_root', after: :set_autoload_paths, before: :setup_main_autoloader do |app|
+      mixin_root = app.root.join('app/mixin')
+      next unless mixin_root.directory?
+
+      Object.const_set(:Mixin, Module.new) unless Object.const_defined?(:Mixin)
+      app.autoloaders.main.push_dir(mixin_root, namespace: Mixin)
+    end
+
+    rake_tasks do
+      load File.expand_path('tasks/poller.rake', __dir__)
+    end
+  end
+end

data/lib/mixin_bot/rails/tasks/poller.rake

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+namespace :mixin_bot do
+  desc 'Poll Mixin outputs for the default bot (or the given [bot_name]) and enqueue processor jobs'
+  task :poller, [:bot] => :environment do |_task, args|
+    # Processor classes live in app/mixin/processors; eager load so discovery
+    # sees them (the poller process never references them directly).
+    Rails.application.eager_load!
+
+    unless MixinBot::Outputs.receipt_store
+      raise MixinBot::ArgumentError,
+            'no receipt store configured: run `rails g mixin_bot:outputs` (or include ' \
+            'MixinBot::Outputs::ReceiptModel in your receipt model) so polling dedup ' \
+            'survives restarts'
+    end
+
+    api = args[:bot] ? MixinBot.bot(args[:bot]) : MixinBot.api
+    poller = MixinBot::Outputs::Poller.new(
+      api:,
+      receipts: MixinBot::Outputs.receipt_store,
+      interval: Integer(ENV.fetch('MIXIN_BOT_POLL_INTERVAL', 5)),
+      asset: ENV.fetch('MIXIN_BOT_POLL_ASSET', nil),
+      members: ENV['MIXIN_BOT_POLL_MEMBERS']&.split(','),
+      threshold: ENV['MIXIN_BOT_POLL_THRESHOLD']&.then { |t| Integer(t) }
+    )
+
+    %w[TERM INT].each { |signal| trap(signal) { poller.stop } }
+
+    MixinBot::Outputs.logger.call(:info, "poller started (pid=#{Process.pid})")
+    poller.run
+    MixinBot::Outputs.logger.call(:info, 'poller stopped')
+  end
+end