mixin_bot 2.6.0 → 3.0.2

data/lib/mixin_bot/transfers.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module MixinBot
+  ##
+  # Outbound transfer pipeline: a persisted transfer record enqueues a job
+  # that executes the Safe transaction pipeline exactly once per trace id,
+  # records the outcome on the record's state, and reconciles unknown
+  # outcomes (timeout after submission) against the snapshot API before any
+  # retry — the network's trace deduplication makes retries safe.
+  #
+  module Transfers
+    class << self
+      # Shared logger for the transfers integration; called with (level, detail).
+      attr_accessor :logger
+    end
+
+    self.logger = ->(level, detail) { warn "[mixin_transfers] #{level}: #{detail}" }
+  end
+end
+
+require_relative 'transfers/model'
+require_relative 'transfers/performer'
+require_relative 'transfers/reconcile'

data/lib/mixin_bot/version.rb

@@ -11,5 +11,5 @@ module MixinBot
   #
   # @see https://semver.org/
   #
-  VERSION = '2.6.0'
+  VERSION = '3.0.2'
 end

data/lib/mixin_bot.rb

@@ -26,11 +26,13 @@ require_relative 'mixin_bot/models'
 require_relative 'mixin_bot/session_store'
 require_relative 'mixin_bot/cache_store_adapter'
 require_relative 'mixin_bot/api'
+require_relative 'mixin_bot/blaze/reactor'
 require_relative 'mixin_bot/bot_auth'
 require_relative 'mixin_bot/cli'
 require_relative 'mixin_bot/computer'
 require_relative 'mixin_bot/invoice'
 require_relative 'mixin_bot/monitor'
+require_relative 'mixin_bot/registry'
 require_relative 'mixin_bot/url_scheme'
 require_relative 'mixin_bot/utils'
 require_relative 'mixin_bot/nfo'
@@ -229,4 +231,6 @@ module MixinBot
       @deprecator ||= ActiveSupport::Deprecation.new('2.0', 'MixinBot')
     end
   end
+
+  extend Registry
 end

data/lib/puma/plugin/mixin_blaze.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+# Puma plugin hosting the Blaze connection inside the web process tree —
+# the Solid Queue plugin architecture:
+#
+#   # config/puma.rb
+#   plugin :mixin_blaze
+#   mixin_blaze_mode :fork   # default; :async hosts the loop in-process
+#
+#   # config/initializers/mixin_bot.rb
+#   MixinBot.configure do
+#     self.blaze_handler = ->(envelope) { MyBot.process! envelope }
+#   end
+#
+# Modes:
+# - *fork* (default): after boot a dedicated child process runs
+#   {MixinBot::Blaze::Reactor}; a background thread supervises it and stops
+#   Puma if the child dies (fail fast — silent non-reception is worse than a
+#   visible restart). The child stops with Puma and monitors the master.
+# - *async*: the reactor runs in a Puma background thread inside this very
+#   process. In cluster mode that process is the master.
+#
+# Requires `preload_app!` in cluster mode: plugins run in the launcher
+# process, and without preloading it holds no application code to resolve
+# the handler.
+require 'English'
+require 'mixin_bot'
+require 'puma/plugin'
+
+module Puma
+  class DSL
+    # Selects where the Blaze connection lives (see file comment).
+    #
+    # @param mode [Symbol] +:fork+ (default) or +:async+
+    def mixin_blaze_mode(mode = :fork)
+      @options[:mixin_blaze_mode] = mode.to_sym
+    end
+  end
+end
+
+Puma::Plugin.create do
+  def start(launcher)
+    @launcher = launcher
+    @log_writer = launcher.log_writer
+    @puma_pid = $PROCESS_ID
+    @mode = launcher.options[:mixin_blaze_mode] || :fork
+
+    unless %i[fork async].include?(@mode)
+      @log_writer.error "mixin_blaze: mixin_blaze_mode must be fork or async, got #{@mode.inspect}; plugin not started"
+      return
+    end
+
+    if launcher.options[:workers].to_i.positive? && !launcher.options[:preload_app]
+      @log_writer.error 'mixin_blaze: Puma cluster mode requires preload_app! (the launcher process hosts the Blaze handler); ' \
+                        'enable preload_app! or drop to single mode; plugin not started'
+      return
+    end
+
+    @mode == :async ? start_async_mode : start_fork_mode
+  end
+
+  private
+
+  def start_fork_mode
+    in_background { monitor_blaze_fork }
+
+    register_lifecycle(
+      booted: -> { fork_blaze },
+      stopped: -> { stop_blaze_fork },
+      restart: -> { stop_blaze_fork }
+    )
+  end
+
+  def start_async_mode
+    register_lifecycle(
+      booted: -> { start_blaze_async },
+      stopped: -> { stop_blaze_async },
+      restart: lambda {
+        stop_blaze_async
+        start_blaze_async
+      }
+    )
+  end
+
+  # Puma 7 renamed the lifecycle hooks; the old names remain as deprecated
+  # aliases (same branching as Solid Queue's plugin).
+  def register_lifecycle(booted:, stopped:, restart:)
+    if Gem::Version.new(Puma::Const::VERSION) < Gem::Version.new('7')
+      @launcher.events.on_booted { booted.call }
+      @launcher.events.on_stopped { stopped.call }
+      @launcher.events.on_restart { restart.call }
+    else
+      @launcher.events.after_booted { booted.call }
+      @launcher.events.after_stopped { stopped.call }
+      @launcher.events.before_restart { restart.call }
+    end
+  end
+
+  # ---- fork mode ----
+
+  def fork_blaze
+    reactor = build_reactor
+    return if reactor.nil?
+
+    @blaze_pid = fork do
+      @blaze_pid = nil
+      # the master's INT trap must not run here; raise Interrupt on the main
+      # thread instead, so the reactor unwinds and closes the connection
+      Signal.trap(:INT) { raise Interrupt }
+      Signal.trap(:TERM) { exit!(0) }
+      Thread.new { monitor_puma_master }
+
+      begin
+        reactor.run
+      ensure
+        # skip at-exit finalization, which can deadlock on inherited
+        # database handles (same rationale as Solid Queue's plugin)
+        exit!(0)
+      end
+    end
+
+    log "mixin_blaze: forked Blaze child (pid #{@blaze_pid})"
+  rescue NotImplementedError
+    @log_writer.error 'mixin_blaze: fork is unavailable on this platform; use mixin_blaze_mode :async'
+  end
+
+  def stop_blaze_fork
+    return unless @blaze_pid
+
+    @shutting_down = true
+
+    begin
+      Process.waitpid(@blaze_pid, Process::WNOHANG)
+    rescue Errno::ECHILD, Errno::ESRCH
+      # already gone; the reap loop below handles it
+    end
+    log 'mixin_blaze: stopping Blaze child...'
+    begin
+      Process.kill(:INT, @blaze_pid)
+    rescue Errno::ESRCH
+      @blaze_pid = nil
+      return
+    end
+
+    # bounded reap: never let a stuck child hold up Puma's shutdown
+    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 10.0
+    reaped = false
+    while Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+      begin
+        reaped = true if Process.waitpid(@blaze_pid, Process::WNOHANG)
+        break if reaped
+      rescue Errno::ECHILD, Errno::ESRCH
+        reaped = true
+        break
+      end
+      sleep 0.05
+    end
+
+    unless reaped
+      log "mixin_blaze: Blaze child #{@blaze_pid} did not stop within 10s; killing"
+      begin
+        Process.kill(:KILL, @blaze_pid)
+      rescue Errno::ESRCH
+        nil
+      end
+      begin
+        Process.waitpid(@blaze_pid) # KILL is fatal; reap the zombie
+      rescue Errno::ECHILD, Errno::ESRCH
+        nil
+      end
+    end
+    @blaze_pid = nil
+  rescue Errno::ECHILD, Errno::ESRCH
+    @blaze_pid = nil
+  end
+
+  def monitor_blaze_fork
+    loop do
+      if blaze_fork_dead?
+        log 'mixin_blaze: Blaze child has gone away, stopping Puma...'
+        stop_puma!
+        break
+      end
+      sleep 2
+    end
+  rescue StandardError => e
+    log "mixin_blaze: monitor thread ended (#{e.class}: #{e.message})"
+  end
+
+  def blaze_fork_dead?
+    return false if @shutting_down
+    return false unless @blaze_pid
+
+    Process.waitpid(@blaze_pid, Process::WNOHANG)
+    false
+  rescue Errno::ECHILD, Errno::ESRCH
+    true
+  end
+
+  def monitor_puma_master
+    loop do
+      if Process.ppid != @puma_pid
+        Process.kill(:INT, $PROCESS_ID)
+        break
+      end
+      sleep 2
+    end
+  end
+
+  # ---- async mode ----
+
+  def start_blaze_async
+    reactor = build_reactor
+    return if reactor.nil?
+
+    @reactor = reactor
+    @blaze_thread = Thread.new do
+      Thread.current.name = 'puma plugin mixin_blaze' if Thread.current.respond_to?(:name=)
+      reactor.run
+    end
+
+    log "mixin_blaze: Blaze reactor running in-process (pid #{Process.pid})"
+  end
+
+  def stop_blaze_async(join_limit: 1)
+    reactor = @reactor
+    thread = @blaze_thread
+    @reactor = nil
+    @blaze_thread = nil
+
+    return unless reactor
+
+    reactor.stop
+    thread&.join(join_limit)
+    log 'mixin_blaze: in-process Blaze reactor stopped'
+  end
+
+  # ---- shared ----
+
+  # Handler resolution happens at boot time (after the application has
+  # loaded — Puma starts plugin background work after load_and_bind).
+  def build_reactor
+    handler = MixinBot.config.blaze_handler
+    if handler.nil?
+      @log_writer.error 'mixin_blaze: no handler configured — set MixinBot.configure { self.blaze_handler = ->(envelope) { ... } }; ' \
+                        'plugin not started'
+      return nil
+    end
+
+    MixinBot::Blaze::Reactor.new(handler: handler, logger: ->(level, detail) { log("mixin_blaze #{level}: #{detail}") })
+  end
+
+  def stop_puma!
+    Process.kill(:INT, $PROCESS_ID)
+  end
+
+  def log(message)
+    @log_writer.log(message)
+  rescue Errno::EIO, Errno::EPIPE, Errno::EBADF
+    # the controlling terminal can disappear mid-shutdown; keep going
+    nil
+  end
+end

data/llms.txt

@@ -1,6 +1,6 @@
 # MixinBot
 
-> Ruby SDK and CLI for Mixin Network: Safe UTXO transfers, REST API, Blaze messaging, transaction crypto, optional MVM helpers. Ruby >= 3.2. Gem version 2.3.0.
+> Ruby SDK and CLI for Mixin Network: Safe UTXO transfers, REST API, Blaze messaging, transaction crypto, optional MVM helpers. Ruby >= 4.0. Gem version 3.0.2.
 
 Important notes:
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: mixin_bot
 version: !ruby/object:Gem::Version
-  version: 2.6.0
+  version: 3.0.2
 platform: ruby
 authors:
 - an-lee
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -24,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7'
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: async-websocket
   requirement: !ruby/object:Gem::Requirement
@@ -287,6 +300,36 @@ files:
 - examples/blaze.rb
 - examples/blaze_async.rb
 - examples/config.yml.example
+- lib/generators/mixin_bot.rb
+- lib/generators/mixin_bot/authentication/USAGE
+- lib/generators/mixin_bot/authentication/authentication_generator.rb
+- lib/generators/mixin_bot/authentication/templates/app/controllers/concerns/authentication.rb.tt
+- lib/generators/mixin_bot/authentication/templates/app/controllers/sessions_controller.rb.tt
+- lib/generators/mixin_bot/authentication/templates/app/models/current.rb.tt
+- lib/generators/mixin_bot/authentication/templates/app/models/session.rb.tt
+- lib/generators/mixin_bot/authentication/templates/app/models/user.rb.tt
+- lib/generators/mixin_bot/authentication/templates/app/views/sessions/new.html.erb.tt
+- lib/generators/mixin_bot/authentication/templates/config/initializers/omniauth.rb.tt
+- lib/generators/mixin_bot/blaze/USAGE
+- lib/generators/mixin_bot/blaze/blaze_generator.rb
+- lib/generators/mixin_bot/blaze/templates/app/mixin/handlers/text_handler.rb
+- lib/generators/mixin_bot/blaze/templates/config/initializers/mixin_bot_blaze.rb
+- lib/generators/mixin_bot/install/USAGE
+- lib/generators/mixin_bot/install/install_generator.rb
+- lib/generators/mixin_bot/notifications/USAGE
+- lib/generators/mixin_bot/notifications/notifications_generator.rb
+- lib/generators/mixin_bot/notifications/templates/app/notifications/payment_received_notification.rb
+- lib/generators/mixin_bot/outputs/USAGE
+- lib/generators/mixin_bot/outputs/outputs_generator.rb
+- lib/generators/mixin_bot/outputs/templates/app/mixin/processors/deposit_processor.rb
+- lib/generators/mixin_bot/outputs/templates/app/models/mixin_output.rb
+- lib/generators/mixin_bot/outputs/templates/db/migrate/create_mixin_outputs.rb.tt
+- lib/generators/mixin_bot/transfers/USAGE
+- lib/generators/mixin_bot/transfers/templates/app/jobs/mixin_transfers/perform_job.rb
+- lib/generators/mixin_bot/transfers/templates/app/jobs/mixin_transfers/reconcile_job.rb
+- lib/generators/mixin_bot/transfers/templates/app/models/mixin_transfer.rb
+- lib/generators/mixin_bot/transfers/templates/db/migrate/create_mixin_transfers.rb.tt
+- lib/generators/mixin_bot/transfers/transfers_generator.rb
 - lib/mixin_bot.rb
 - lib/mixin_bot/address.rb
 - lib/mixin_bot/api.rb
@@ -333,6 +376,8 @@ files:
 - lib/mixin_bot/api/turn.rb
 - lib/mixin_bot/api/user.rb
 - lib/mixin_bot/api/withdraw.rb
+- lib/mixin_bot/blaze/reactor.rb
+- lib/mixin_bot/blaze/router.rb
 - lib/mixin_bot/bot_auth.rb
 - lib/mixin_bot/cache_store_adapter.rb
 - lib/mixin_bot/cli.rb
@@ -351,6 +396,7 @@ files:
 - lib/mixin_bot/configuration.rb
 - lib/mixin_bot/errors.rb
 - lib/mixin_bot/invoice.rb
+- lib/mixin_bot/json_decoder.rb
 - lib/mixin_bot/models.rb
 - lib/mixin_bot/models/address.rb
 - lib/mixin_bot/models/api_envelope.rb
@@ -362,11 +408,28 @@ files:
 - lib/mixin_bot/models/user.rb
 - lib/mixin_bot/monitor.rb
 - lib/mixin_bot/nfo.rb
+- lib/mixin_bot/notifications/mixin_channel.rb
+- lib/mixin_bot/outputs.rb
+- lib/mixin_bot/outputs/cursor_model.rb
+- lib/mixin_bot/outputs/envelope.rb
+- lib/mixin_bot/outputs/memory_stores.rb
+- lib/mixin_bot/outputs/poller.rb
+- lib/mixin_bot/outputs/processing_job.rb
+- lib/mixin_bot/outputs/processors.rb
+- lib/mixin_bot/outputs/receipt_model.rb
+- lib/mixin_bot/rails.rb
+- lib/mixin_bot/rails/railtie.rb
+- lib/mixin_bot/rails/tasks/poller.rake
+- lib/mixin_bot/registry.rb
 - lib/mixin_bot/session_store.rb
 - lib/mixin_bot/transaction.rb
 - lib/mixin_bot/transaction/buffer.rb
 - lib/mixin_bot/transaction/decoder.rb
 - lib/mixin_bot/transaction/encoder.rb
+- lib/mixin_bot/transfers.rb
+- lib/mixin_bot/transfers/model.rb
+- lib/mixin_bot/transfers/performer.rb
+- lib/mixin_bot/transfers/reconcile.rb
 - lib/mixin_bot/url_scheme.rb
 - lib/mixin_bot/utils.rb
 - lib/mixin_bot/utils/address.rb
@@ -387,6 +450,7 @@ files:
 - lib/mvm/nft.rb
 - lib/mvm/registry.rb
 - lib/mvm/scan.rb
+- lib/puma/plugin/mixin_blaze.rb
 - lib/tasks/api_coverage.rake
 - llms.txt
 homepage: https://github.com/an-lee/mixin_bot
@@ -394,7 +458,6 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -402,15 +465,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 4.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.20
 specification_version: 4
 summary: A Ruby SDK for Mixin Network
 test_files: []