mixin_bot 2.6.0 → 3.0.2

data/lib/generators/mixin_bot/install/USAGE

@@ -0,0 +1,24 @@
+Description:
+    Sets up a Mixin Messenger/Network Rails application in one command:
+    "Sign in with Mixin" (OmniAuth), Blaze message routing with the Puma
+    plugin, the outputs poller with an example processor, the outbound
+    transfer ledger, and Noticed-driven Mixin notifications.
+
+    Skip any component:
+
+        rails generate mixin_bot:install --skip-notifications --skip-transfers
+        rails generate mixin_bot:install --skip notifications,transfers
+        rails generate mixin_bot:install --skip authentication
+
+Example:
+    rails generate mixin_bot:install
+
+    This will run, in order:
+        rails generate mixin_bot:authentication
+        rails generate mixin_bot:blaze
+        rails generate mixin_bot:outputs
+        rails generate mixin_bot:transfers
+        rails generate mixin_bot:notifications
+
+    Afterwards: set your bot credentials, run `rails db:migrate`, and start
+    the poller (`rails mixin_bot:poller`) and your job backend.

data/lib/generators/mixin_bot/install/install_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module MixinBot
+  module Generators
+    # `rails generate mixin_bot:install` — one-command setup: runs every
+    # component generator in dependency order. Skip any of them:
+    #
+    #   rails g mixin_bot:install --skip-notifications --skip-transfers
+    #   rails g mixin_bot:install --skip notifications transfers
+    #   rails g mixin_bot:install --skip=notifications,transfers
+    #
+    # Idempotent: each component generator (and this one) is safe to re-run.
+    class InstallGenerator < Rails::Generators::Base
+      COMPONENTS = %w[authentication blaze outputs transfers notifications].freeze
+
+      class_option :skip,
+                   type: :array, default: [],
+                   banner: 'component,component2',
+                   desc: "Skip components (comma-separated; any of: #{COMPONENTS.join(' ')})"
+
+      COMPONENTS.each do |component|
+        class_option :"skip_#{component}", type: :boolean, default: false,
+                                           desc: "Skip the #{component} component"
+
+        define_method(:"install_#{component}") do
+          invoke "mixin_bot:#{component}" unless skip?(component)
+        end
+      end
+
+      def show_plan
+        skipped = COMPONENTS.select { |component| skip?(component) }
+        say_status :install, if skipped.empty?
+                               'all components'
+                             else
+                               "all components except #{skipped.join(', ')}"
+                             end
+      end
+
+      private
+
+      def skip?(component)
+        return true if options[:"skip_#{component}"]
+
+        Array(options[:skip]).flat_map { |value| value.to_s.split(',') }.include?(component.to_s)
+      end
+    end
+  end
+end

data/lib/generators/mixin_bot/notifications/USAGE

@@ -0,0 +1,13 @@
+Description:
+    Adds Noticed-driven Mixin message notifications: ensures the `noticed`
+    gem is in the Gemfile and scaffolds one example notification delivered
+    through MixinBot's Mixin channel (`deliver_by :mixin`) over the HTTP
+    message API.
+
+Example:
+    rails generate mixin_bot:notifications
+
+    This will create:
+        app/notifications/payment_received_notification.rb
+
+    It will also ensure `noticed` is present in the Gemfile.

data/lib/generators/mixin_bot/notifications/notifications_generator.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module MixinBot
+  module Generators
+    # `rails generate mixin_bot:notifications` — adds the Noticed gem and
+    # scaffolds one example notification delivered as a Mixin message through
+    # the gem's MixinChannel (`deliver_by :mixin`).
+    class NotificationsGenerator < Rails::Generators::Base
+      # Rails 8.1 moved bundle_command out of Actions into BundleHelper.
+      unless method_defined?(:bundle_command) || private_method_defined?(:bundle_command)
+        begin
+          require 'rails/generators/bundle_helper'
+          include Rails::Generators::BundleHelper
+        rescue LoadError
+          # Older Rails ships bundle_command in Rails::Generators::Actions.
+        end
+      end
+
+      source_root File.expand_path('templates', __dir__)
+
+      NOTICED_GEM = 'noticed'
+
+      def add_noticed_gem
+        gemfile = File.read(gemfile_path)
+        pattern = /gem\s+["']#{NOTICED_GEM}["']/
+        return if gemfile.match?(/^\s*#{pattern}/)
+
+        if gemfile.match?(/^\s*#\s*#{pattern}/)
+          uncomment_lines 'Gemfile', pattern
+          bundle_command('install --quiet')
+        else
+          bundle_command("add #{NOTICED_GEM} --quiet")
+        end
+      end
+
+      def create_example_notification
+        template 'app/notifications/payment_received_notification.rb'
+      end
+
+      private
+
+      def gemfile_path
+        File.expand_path('Gemfile', destination_root)
+      end
+    end
+  end
+end

data/lib/generators/mixin_bot/notifications/templates/app/notifications/payment_received_notification.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Example notification delivered as a Mixin message through the mixin channel:
+#
+#   PaymentReceivedNotification.with(amount: '1.5').deliver(user)
+#
+# (`user` must answer #mixin_user_id — the mixin_bot:authentication
+# generator's users table has that column.)
+#
+# The recipient and message contract lives here; MixinBot's channel sends
+# over the HTTP message API with the configured bot's credentials.
+class PaymentReceivedNotification < Noticed::Notification
+  deliver_by :mixin
+
+  param :amount
+
+  def mixin_recipient
+    recipient.mixin_user_id
+  end
+
+  def mixin_message
+    { category: 'PLAIN_TEXT', content: "Payment received: #{params[:amount]}" }
+  end
+end

data/lib/generators/mixin_bot/outputs/USAGE

@@ -0,0 +1,29 @@
+Description:
+    Scaffolds the Mixin output-polling foundation: the receipt table and
+    model, and an example processor under app/mixin/processors. Receipts
+    deduplicate every observed output (inbound or outbound); the poller's
+    resume cursor is derived from the receipts themselves; processors are
+    selected by predicate and run in the job queue.
+
+    Start polling with the rake task (bots default to MixinBot's global
+    credentials; pass a registered bot name for multi-bot apps):
+
+        rails mixin_bot:poller            # default bot
+        rails mixin_bot:poller[shop]      # registered bot :shop
+
+    Optional filters via environment variables:
+
+        MIXIN_BOT_POLL_ASSET      restrict to one asset id
+        MIXIN_BOT_POLL_MEMBERS    comma-separated member user ids
+        MIXIN_BOT_POLL_THRESHOLD  members threshold
+
+Example:
+    rails generate mixin_bot:outputs
+
+    This will create:
+        db/migrate/xxx_create_mixin_outputs.rb
+        app/models/mixin_output.rb
+        app/mixin/processors/deposit_processor.rb
+
+    Run `rails db:migrate` afterwards, and make sure a job backend
+    (e.g. Solid Queue) is running for processor jobs.

data/lib/generators/mixin_bot/outputs/outputs_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module MixinBot
+  module Generators
+    # `rails generate mixin_bot:outputs` — scaffolds the output-polling
+    # foundation: the receipt table and model, and an example processor under
+    # app/mixin/processors. Pair with the `mixin_bot:poller` rake task and a
+    # job backend (e.g. Solid Queue). The poller's resume cursor is derived
+    # from the receipts themselves — there is no separate cursor table.
+    class OutputsGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      def self.next_migration_number(dirname)
+        current = current_migration_number(dirname)
+        return Time.now.utc.strftime('%Y%m%d%H%M%S%6N') if current.zero?
+
+        current.succ.to_s
+      end
+
+      def create_migrations
+        migration 'create_mixin_outputs'
+      end
+
+      def create_model
+        template 'app/models/mixin_output.rb'
+      end
+
+      def create_example_processor
+        template 'app/mixin/processors/deposit_processor.rb'
+      end
+
+      private
+
+      # Skips the migration when a same-named one already exists (re-run).
+      def migration(name)
+        return if self.class.migration_exists?('db/migrate', name)
+
+        migration_template "db/migrate/#{name}.rb.tt", "db/migrate/#{name}.rb"
+      end
+
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/mixin_bot/outputs/templates/app/mixin/processors/deposit_processor.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Mixin
+  module Processors
+    # Example processor: matches every inbound (unspent) output. Replace the
+    # predicate and body with real business rules — processors run in the job
+    # queue and enqueue is at-least-once, so key side effects on
+    # envelope.output_id to stay idempotent.
+    class DepositProcessor < MixinBot::Outputs::Processor
+      def self.matches?(envelope)
+        !envelope.spent?
+      end
+
+      def process
+        Rails.logger.info(
+          "received #{envelope.amount} of #{envelope.asset_id} (output #{envelope.output_id})"
+        )
+      end
+    end
+  end
+end

data/lib/generators/mixin_bot/outputs/templates/app/models/mixin_output.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Receipt row for every output the poller observes (inbound or outbound).
+# The (bot_app_id, output_id) unique index is the dedup gate; snapshot-derived
+# fields (memo, opponent_id, trace_id) are cached here by the envelope bridge.
+class MixinOutput < ApplicationRecord
+  include MixinBot::Outputs::ReceiptModel
+end

data/lib/generators/mixin_bot/outputs/templates/db/migrate/create_mixin_outputs.rb.tt

@@ -0,0 +1,26 @@
+class CreateMixinOutputs < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :mixin_outputs do |t|
+      t.string :bot_app_id, null: false
+      t.string :output_id, null: false
+      t.string :amount
+      t.string :asset_id
+      t.string :state
+      t.string :transaction_hash
+      t.integer :output_index
+      t.bigint :sequence
+      t.datetime :output_created_at
+      t.text :memo
+      t.string :opponent_id
+      t.string :trace_id
+      t.boolean :snapshot_bridged, null: false, default: false
+      t.datetime :enqueued_at
+      t.timestamps
+    end
+
+    add_index :mixin_outputs, %i[bot_app_id output_id], unique: true
+    add_index :mixin_outputs, :bot_app_id
+    # cursor lookups: MAX(sequence) per bot
+    add_index :mixin_outputs, %i[bot_app_id sequence]
+  end
+end

data/lib/generators/mixin_bot/transfers/USAGE

@@ -0,0 +1,37 @@
+Description:
+    Scaffolds the outbound transfer ledger: a migration and model for
+    MixinTransfer (with the runtime state machine), perform and reconcile
+    jobs under app/jobs/mixin_transfers, and a Solid Queue recurring
+    schedule for reconciliation.
+
+    Usage:
+
+        transfer = MixinTransfer.create!(
+          recipient_id: user_id,          # Mixin user id of the recipient
+          asset_id: ASSET_ID,
+          amount: '1.5',
+          memo: 'payout',
+          trace_id: SecureRandom.uuid     # idempotency: re-sends are deduped
+        )
+
+    The record is enqueued on create and ends `confirmed` (with its
+    transaction hash), `failed` (definitive rejection), or `reconciling`
+    (timeout — resolved by the recurring job).
+
+Example:
+    rails generate mixin_bot:transfers
+
+    This will create:
+        db/migrate/xxx_create_mixin_transfers.rb
+        app/models/mixin_transfer.rb
+        app/jobs/mixin_transfers/perform_job.rb
+        app/jobs/mixin_transfers/reconcile_job.rb
+        config/recurring.yml
+
+    Run `rails db:migrate` afterwards. If config/recurring.yml already
+    exists, add the reconcile entry manually:
+
+        production:
+          mixin_transfers_reconcile:
+            class: MixinTransfers.ReconcileJob
+            schedule: every 5 minutes

data/lib/generators/mixin_bot/transfers/templates/app/jobs/mixin_transfers/perform_job.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module MixinTransfers
+  # Executes the Safe pipeline for one MixinTransfer. Retries are safe: the
+  # transfer's trace id deduplicates network-side.
+  class PerformJob < ApplicationJob
+    queue_as :mixin_transfers
+
+    def perform(transfer_id)
+      MixinTransfer.find(transfer_id).perform!
+    end
+  end
+end

data/lib/generators/mixin_bot/transfers/templates/app/jobs/mixin_transfers/reconcile_job.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MixinTransfers
+  # Resolves transfers whose send attempt ended indeterminately (timeout
+  # after submission): confirms from the trace snapshot or re-sends with the
+  # same trace id. Wired by the recurring schedule in config/recurring.yml.
+  class ReconcileJob < ApplicationJob
+    queue_as :mixin_transfers
+
+    def perform
+      MixinTransfer.reconcile_pending!
+    end
+  end
+end

data/lib/generators/mixin_bot/transfers/templates/app/models/mixin_transfer.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Outbound transfer ledger. Creating a record enqueues the perform job; the
+# runtime concern (MixinBot::Transfers::Model) drives the Safe pipeline and
+# records the outcome in #state. bot_app_id selects a registered bot
+# (MixinBot.register_bot); nil uses the default bot.
+class MixinTransfer < ApplicationRecord
+  include MixinBot::Transfers::Model
+
+  after_create_commit -> { MixinTransfers::PerformJob.perform_later(id) }
+end

data/lib/generators/mixin_bot/transfers/templates/db/migrate/create_mixin_transfers.rb.tt

@@ -0,0 +1,23 @@
+class CreateMixinTransfers < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :mixin_transfers do |t|
+      t.string :recipient_id, null: false
+      t.string :asset_id, null: false
+      t.decimal :amount, precision: 32, scale: 18, null: false
+      t.text :memo
+      t.string :trace_id, null: false
+      t.string :state, null: false, default: 'pending'
+      t.string :previous_state
+      t.string :transaction_hash
+      t.text :error
+      t.datetime :transitioned_at
+      t.string :bot_app_id
+
+      t.timestamps
+    end
+
+    add_index :mixin_transfers, :trace_id, unique: true
+    add_index :mixin_transfers, :state
+    add_index :mixin_transfers, :bot_app_id
+  end
+end

data/lib/generators/mixin_bot/transfers/transfers_generator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module MixinBot
+  module Generators
+    # `rails generate mixin_bot:transfers` — scaffolds the outbound transfer
+    # ledger: migration + model (state machine concern), perform/reconcile
+    # jobs, and a Solid Queue recurring entry for reconciliation.
+    class TransfersGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      RECURRING_ENTRY = <<~YAML
+        production:
+          mixin_transfers_reconcile:
+            class: MixinTransfers::ReconcileJob
+            schedule: every 5 minutes
+      YAML
+
+      def self.next_migration_number(dirname)
+        current = current_migration_number(dirname)
+        return Time.now.utc.strftime('%Y%m%d%H%M%S%6N') if current.zero?
+
+        current.succ.to_s
+      end
+
+      def create_ledger_migration
+        migration 'create_mixin_transfers'
+      end
+
+      def create_model
+        template 'app/models/mixin_transfer.rb'
+      end
+
+      def create_jobs
+        template 'app/jobs/mixin_transfers/perform_job.rb'
+        template 'app/jobs/mixin_transfers/reconcile_job.rb'
+      end
+
+      def create_recurring_schedule
+        path = File.expand_path('config/recurring.yml', destination_root)
+        if File.exist?(path)
+          say_status :todo, <<~MSG.chomp
+            add the MixinTransfers reconcile entry to config/recurring.yml (see USAGE)
+          MSG
+        else
+          create_file 'config/recurring.yml', RECURRING_ENTRY
+        end
+      end
+
+      private
+
+      # Skips the migration when a same-named one already exists (re-run).
+      def migration(name)
+        return if self.class.migration_exists?('db/migrate', name)
+
+        migration_template "db/migrate/#{name}.rb.tt", "db/migrate/#{name}.rb"
+      end
+
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/mixin_bot.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module MixinBot
+  module Generators
+    # Generator namespace discovered by railties: every bundler-managed gem's
+    # `lib/generators` directory is on the generator load path, so apps can run
+    # `rails generate mixin_bot:<name>` without any configuration. Individual
+    # generators live in sibling directories (e.g. mixin_bot/authentication).
+  end
+end

data/lib/mixin_bot/api/app.rb

@@ -85,6 +85,26 @@ module MixinBot
         client.post path, **payload, access_token: kwargs[:access_token]
       end
 
+      ##
+      # Updates the app security profile — the allowed IP addresses and the
+      # resource URL patterns.
+      #
+      # +POST /apps/:id+ does not persist these two fields; the security
+      # endpoint is the only one that stores them. Both lists are submitted on
+      # every call, so fetch the live values first when only one list should
+      # change.
+      #
+      # @param allowed_ips [Array<String>] IPv4 / CIDR entries; +[]+ removes
+      #   the restriction
+      # @param resource_patterns [Array<String>] URL patterns; +[]+ removes the
+      #   restriction
+      # @return [MixinBot::Models::ApiEnvelope]
+      #
+      def update_app_security(app_id, allowed_ips: [], resource_patterns: [], access_token: nil)
+        path = format('/apps/%<id>s/security', id: app_id)
+        client.post path, allowed_ips:, resource_patterns:, access_token:
+      end
+
       def rotate_app_secret(app_id, access_token: nil)
         path = format('/apps/%<id>s/secret', id: app_id)
         client.post path, access_token:

data/lib/mixin_bot/api/blaze_async.rb

@@ -33,7 +33,11 @@ module MixinBot
       # +handler:+ is yield-through so the caller can supply an
       # +Async::WebSocket::Connection+ subclass (e.g. one that correlates
       # PONG frames). +endpoint_options:+ are forwarded to
-      # +Async::HTTP::Endpoint.parse+ (e.g. +timeout:+ for the connect phase).
+      # +Async::HTTP::Endpoint.parse+. Prefer not passing +timeout:+ there: it
+      # becomes the socket's per-read timeout, so a quiet-but-healthy
+      # connection dies when no frame arrives within that window. Bound the
+      # connect phase at the call site instead (see
+      # MixinBot::Blaze::Reactor#connect!).
       def blaze_async(handler: Async::WebSocket::Connection, endpoint_options: {})
         access_token = access_token('GET', '/', '')
         authorization = format('Bearer %<access_token>s', access_token:)

data/lib/mixin_bot/api/snapshot.rb

@@ -23,6 +23,11 @@ module MixinBot
       end
       alias safe_snapshot_by_id safe_snapshot
 
+      def safe_snapshot_by_trace(trace_id, access_token: nil)
+        path = format('/safe/snapshots/trace/%<trace_id>s', trace_id:)
+        client.get path, access_token:
+      end
+
       def create_safe_snapshot_notification(**kwargs)
         path = '/safe/snapshots/notifications'