mixin_bot 2.5.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce614b6fab815a9d8dfb1e93914fdaf3ba6b7306b1f5d35ab594efcd0b46fe68
-  data.tar.gz: 70b09c5ba22efc597a43b560a4257e2984b059b8334eee6efa19498934e87407
+  metadata.gz: 6c6e5421b12eabf2c32c0500c1b828228fd24a10855047f2f7f1bf605dc62ada
+  data.tar.gz: a18da86395abe9053e52d70965538359cbbada5bc13439196c73536382d05c87
 SHA512:
-  metadata.gz: ab61a3850c702cb36a00794f5cfacb3aa63d18d6fca24104d9be336b97b04332430eb702bba50d6bbaa80f9ad94976fa5aaeefaae69f736bed88b21ffce7f849
-  data.tar.gz: c2a237075b8c9399ef4f90d933d1bac288de35aefa11ff6fa55d3dd4e19a337d0a10f78173a9eef77a16476a63e208fa22b0c3250758ad7c2324490411ffa4b7
+  metadata.gz: 4a20f4ef42062cff12ff5ecb280f8d447528ee2f7882e0425783af545b57a3fe7faecf36ca7c70387e5c3dbeb08cdcea02729b919cddadb386fe76b5b6d45fa6
+  data.tar.gz: f9f88a933a44502b2709fd282c8170adf73653d46721c83044358b59434444b10efac60ef82b84cb470cffaf7d4694d7bbeb270dc851c54ba5a66e40ff285713

data/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — MixinBot
 
-Ruby gem (v2.3.0): Mixin Network REST SDK + `mixinbot` CLI. Parity targets: [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client), [bot-api-nodejs-client](https://github.com/MixinNetwork/bot-api-nodejs-client).
+Ruby gem (v3.0.0): Mixin Network REST SDK + `mixinbot` CLI. Parity targets: [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client), [bot-api-nodejs-client](https://github.com/MixinNetwork/bot-api-nodejs-client).
 
 ## Commands
 
@@ -34,13 +34,13 @@ docs/agent/             # LLM-oriented CLI and cookbook docs
 
 ## CI and release
 
-- **CI** (`.github/workflows/ci.yml`): `pull_request` and `push` to `main` — `rake test` on Ruby 3.2/3.3/4.0, `rake rubocop` (3.3), `rake mixin_bot:api_coverage`.
+- **CI** (`.github/workflows/ci.yml`): `pull_request` and `push` to `main` — `rake test` on Ruby 4.0, `rake rubocop` (4.0), `rake mixin_bot:api_coverage`.
 - **Release** (`.github/workflows/release.yml`): push tag `v*` (must match `MixinBot::VERSION`, e.g. tag `v2.1.0` for `VERSION = '2.1.0'`) → `rake build` → RubyGems via [trusted publishing](https://guides.rubygems.org/trusted-publishing/) (OIDC; workflow `release.yml`, no repo secret) → GitHub Release (notes from `CHANGELOG.md`, `.gem` attached).
 - **Dependabot** (`.github/dependabot.yml`): weekly Bundler and GitHub Actions updates; Dependabot PRs use the same CI workflow.
 
 ## Conventions
 
-- **Ruby** >= 3.2 (CI: 3.2, 3.3, 4.0)
+- **Ruby** >= 4.0 (CI: 4.0)
 - **HTTP responses**: `MixinBot::Models::ApiEnvelope` — use `res['data']` or delegated keys
 - **Safe transfers**: require `spend_key`; prefer `create_safe_transfer` / `create_transfer` (Safe pipeline)
 - **Legacy APIs**: `create_legacy_transfer`, `POST /transfers` — deprecated, warns once

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.0.0] - 2026-09-15
+
+### Added
+
+- **Puma plugin hosting the Blaze connection** (`plugin :mixin_blaze`) — Solid Queue-style in-process hosting, removing the standalone Blaze deployment artifact. Dual run modes via the `mixin_blaze_mode` Puma DSL option: `:fork` (default) forks a dedicated Blaze child on `on_booted` with a monitor thread that stops Puma if the child dies, terminated on `on_stopped`/`on_restart`; `:async` runs the reactor on a Puma background thread in-process. Handler resolution comes from `MixinBot` configuration (resolved lazily after app boot) with an explicit ack policy (on-receipt vs after-handler); Puma 6/7 lifecycle-event compatibility; cluster mode requires `preload_app!` and fails loudly without it. Puma remains a host-app concern — no new gem dependency.
+- **`MixinBot::Blaze::Reactor`** — reusable Blaze loop (connect, keepalive ping, read → handler → ack, reconnect with backoff) wrapping `API#blaze_async`; extracted from `examples/blaze_async.rb` so the plugin shell stays thin and the loop is unit-testable offline.
+
+### Changed
+
+- **Breaking**: Ruby >= 4.0 is now required — `required_ruby_version` bumped from `>= 3.2.0` to `>= 4.0.0`. The CI matrix, RuboCop target, and Release workflow all run Ruby 4.0; the dev-only `parallel` version pin (kept for the old Ruby 3.2 floor) was dropped.
+
+## [2.6.0] - 2026-09-07
+
+### Added
+
+- **`API#blaze_async`** — fiber-based sibling of `blaze`: returns a connected `async-websocket` client (same `wss://<blaze_host>/` URL, `Mixin-Blaze-1` subprotocol, Bearer JWT, User-Agent, and shared frame codec) for hosts driving Blaze outside EventMachine. `handler:` is yield-through for caller-supplied `Async::WebSocket::Connection` subclasses; `endpoint_options:` forwards to `Async::HTTP::Endpoint.parse`. Forces the HTTP/1 upgrade path via ALPN. Caller-side wire notes: send `write_ws_message` byte arrays as `BinaryMessage.new(ary.pack('C*'))`, feed `message.to_str` into `ws_message`, and own the keepalive ping (server pings are auto-replied).
+
 ## [2.5.0] - 2026-09-03
 
 ### Added

data/README.md

@@ -6,12 +6,12 @@ Ruby SDK and CLI for [Mixin Network](https://developers.mixin.one/docs): authent
 
 The gem aims for **parity with the official [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client)** Go SDK and **[bot-api-nodejs-client](https://github.com/MixinNetwork/bot-api-nodejs-client)** Node SDK. See [API_COVERAGE.md](API_COVERAGE.md) for the full mapping; run `rake mixin_bot:api_coverage` to confirm no gaps are marked missing.
 
-Current gem version: **2.3.0** (see [CHANGELOG.md](CHANGELOG.md) for breaking changes and deprecations).
+Current gem version: **3.0.0** (see [CHANGELOG.md](CHANGELOG.md) for breaking changes and deprecations).
 
 ## Requirements
 
-- **Ruby** ≥ 3.2 (CI runs 3.2, 3.3, and 4.0).
-- **Bundler** 2.5+ recommended, especially on Ruby 4.
+- **Ruby** ≥ 4.0 (CI runs 4.0).
+- **Bundler** 2.6+ recommended.
 - Optional: the **`mixin`** CLI in `PATH` if you use `MixinBot::API#encode_raw_transaction_native` / `#decode_raw_transaction_native` or the experimental `MixinBot::NodeCLI` helpers.
 
 ## Installation
@@ -257,6 +257,76 @@ end
 
 For outbound messages over an open socket, use `blaze_send_plain_text`, `blaze_send_contact`, `blaze_send_app_card`, and related helpers (parity with Go `BlazeClient`).
 
+### Without EventMachine: `blaze_async`
+
+`blaze_async` returns the connected `async-websocket` connection instead of a `Faye::WebSocket::Client` — same URL, `Mixin-Blaze-1` subprotocol, and frame codec; the caller drives the loop in an `Async` reactor. Wire notes: wrap `write_ws_message` byte arrays in `Protocol::WebSocket::BinaryMessage`, feed `message.to_str` into `ws_message`, and own the keepalive ping (see `examples/blaze_async.rb`).
+
+```ruby
+require 'async'
+require 'mixin_bot'
+
+Async do |task|
+  connection = MixinBot.api.blaze_async
+
+  task.async do # keepalive is the caller's job
+    loop do
+      sleep 30
+      connection.send_ping
+    end
+  end
+
+  connection.write Protocol::WebSocket::BinaryMessage.new(MixinBot.api.list_pending_message.pack('C*'))
+  while (message = connection.read)
+    raw = JSON.parse MixinBot.api.ws_message(message.to_str)
+    # data is a Hash for message envelopes, an Array in LIST_PENDING_MESSAGES replies
+    data = raw['data'].is_a?(Hash) ? raw['data'] : {}
+    next unless (message_id = data['message_id'])
+
+    bytes = MixinBot.api.acknowledge_message_receipt(message_id)
+    connection.write Protocol::WebSocket::BinaryMessage.new(bytes.pack('C*'))
+  end
+ensure
+  connection&.close
+end
+```
+
+### Running Blaze inside Puma (`plugin :mixin_blaze`)
+
+For Rails/Puma apps, the gem ships a Puma plugin (Solid Queue-style) that hosts the Blaze connection inside the web process tree — no standalone Blaze process to deploy or supervise:
+
+```ruby
+# config/puma.rb
+plugin :mixin_blaze
+mixin_blaze_mode :fork # default; see table below
+```
+
+```ruby
+# config/initializers/mixin_bot.rb
+MixinBot.configure do
+  # ... credentials ...
+  self.blaze_handler = ->(envelope) { MyBot.process! envelope }
+  self.blaze_ack_policy = :on_receipt # default; or :after_handler
+end
+```
+
+The handler receives each decoded message envelope (a Hash with `action` and `data` keys) and runs serially on the hosting thread — safe for ActiveRecord. Handlers run one message at a time; the keepalive ping runs separately.
+
+| Mode | Where the connection lives | Notes |
+|---|---|---|
+| `:fork` (default) | Dedicated child process forked from the Puma launcher | Crash-isolated; if the child dies, Puma is stopped so the process manager restarts the unit |
+| `:async` | Background thread inside the Puma process itself | In cluster mode that process is the master; no child process |
+
+Ack policy: `:on_receipt` acknowledges each message immediately (at-most-once dispatch — a handler crash loses that message); `:after_handler` acknowledges only after the handler completes without raising (at-least-once — handlers must be idempotent, since unacknowledged messages are redelivered on reconnect).
+
+Receipt confirmations (`ACKNOWLEDGE_MESSAGE_RECEIPT` frames the server pushes for your own outgoing/acknowledged messages) are consumed internally: the handler never sees them and they are never re-acknowledged.
+
+Operational notes:
+
+- **Remove any standalone Blaze process when enabling the plugin** — two connections double your handler invocations (or split deliveries).
+- **Cluster mode requires `preload_app!`** — plugins run in the launcher process, which holds no application code without preloading; the plugin reports an error and stays off otherwise.
+- **Phased restarts keep the old handler code** in the hosting process until a full restart; the same applies to Solid Queue's plugin.
+- Workers that need to *send* messages should use the REST API (`create_message` / `create_messages`), not the socket.
+
 ## Deep links and bot auth
 
 ```ruby
@@ -363,8 +433,8 @@ Examples under `examples/` expect `examples/config.yml` (copy from `examples/con
 
 GitHub Actions runs on every pull request and on pushes to `main`:
 
-- **Test** — Ruby 3.2, 3.3, and 4.0: `bundle exec rake test`
-- **RuboCop** — Ruby 3.3: `bundle exec rake rubocop`
+- **Test** — Ruby 4.0: `bundle exec rake test`
+- **RuboCop** — Ruby 4.0: `bundle exec rake rubocop`
 - **API coverage** — `bundle exec rake mixin_bot:api_coverage`
 
 ### Release

data/docs/agent/cookbook.md

@@ -130,6 +130,32 @@ end
 
 See [examples/blaze.rb](../../examples/blaze.rb).
 
+## Blaze inside Puma (`plugin :mixin_blaze`)
+
+For Rails/Puma apps the gem ships a Puma plugin (Solid Queue-style) that hosts the Blaze connection inside the web process tree — no standalone Blaze process. Requires a configured `blaze_handler`; without one the plugin logs an error and stays off.
+
+```ruby
+# config/puma.rb
+plugin :mixin_blaze
+mixin_blaze_mode :fork # default (:fork = supervised child process); :async = in-process thread
+
+# config/initializers/mixin_bot.rb
+MixinBot.configure do
+  # ... credentials ...
+  self.blaze_handler = ->(envelope) { MyBot.process! envelope } # required
+  self.blaze_ack_policy = :on_receipt # default; :after_handler = ack after handler success
+end
+```
+
+Behavior: reconnect with bounded backoff, keepalive pings, serial handler dispatch (ActiveRecord-safe), handler exceptions logged without ending delivery, graceful shutdown with Puma (child killed on stop; in `:fork` mode a dead child stops Puma so the unit restarts). `ACKNOWLEDGE_MESSAGE_RECEIPT` confirmations are consumed internally — the handler never sees them and they are never re-acknowledged.
+
+Operational notes:
+
+- **Remove any standalone Blaze process when enabling the plugin** — duplicate connections duplicate handler invocations.
+- **Puma cluster mode requires `preload_app!`** — plugins run in the launcher process; without preloading there is no app code to resolve the handler and the plugin reports an error.
+- **Phased restarts keep old handler code** in the hosting process until a full restart.
+- Workers that need to *send* messages use the REST API (`create_message`), not the socket.
+
 ## Discover API methods
 
 ```bash

data/examples/blaze_async.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Fiber-based Blaze client — the async-websocket sibling of examples/blaze.rb.
+#
+# Drives API#blaze_async without EventMachine: the gem returns the connected
+# connection and the caller runs the loop inside an Async reactor. The frame
+# codec (write_ws_message / ws_message / list_pending_message /
+# acknowledge_message_receipt) is shared with blaze verbatim; only the wire
+# differs:
+# - *Send*: write_ws_message returns an Array of byte integers (Faye framed
+#   that itself) — wrap it in a Protocol::WebSocket::BinaryMessage.
+# - *Read*: connection.read yields a Protocol::WebSocket::Message (or nil
+#   after a clean close) — feed message.to_str into ws_message.
+# - *Keepalive*: Faye's ping: 60 becomes the caller's job; server pings are
+#   auto-replied by the protocol layer.
+#
+# Run: ruby examples/blaze_async.rb
+
+require './lib/mixin_bot'
+require 'async'
+require 'base64'
+require 'json'
+require 'securerandom'
+require 'yaml'
+
+CONFIG = YAML.load_file("#{File.dirname __FILE__}/config.yml")
+MixinBot.configure do
+  self.app_id = CONFIG['app_id']
+  self.client_secret = CONFIG['client_secret']
+  self.session_id = CONFIG['session_id']
+  self.server_public_key = CONFIG['server_public_key']
+  self.session_private_key = CONFIG['session_private_key']
+end
+
+API = MixinBot.api
+
+# gzip+JSON bytes from write_ws_message -> one binary WebSocket frame
+def send_frame(connection, bytes)
+  connection.write Protocol::WebSocket::BinaryMessage.new(bytes.pack('C*'))
+end
+
+Async do |task|
+  # endpoint_options: is forwarded to Async::HTTP::Endpoint.parse. No
+  # timeout: here — it would become the socket's per-read timeout and kill
+  # quiet-but-healthy connections; liveness is the keepalive ping below.
+  # handler: stays default; pass an Async::WebSocket::Connection subclass to
+  # hook the raw frame events (e.g. PONG correlation).
+  connection = API.blaze_async
+  p [Time.now.to_s, :connected]
+
+  # liveness is the caller's policy: nothing on the wire goes stale quietly
+  keepalive = task.async do
+    loop do
+      sleep 30
+      connection.send_ping
+    end
+  rescue Protocol::WebSocket::ProtocolError, IOError # IOError covers EOFError
+    # connection is gone; the read loop below is already winding down
+  end
+
+  # sends nothing on open — mirror blaze and request pending messages first
+  send_frame connection, API.list_pending_message
+
+  # read returns nil after a clean close; an abrupt one raises EOFError
+  while (message = connection.read)
+    raw = JSON.parse API.ws_message(message.to_str)
+    p [Time.now.to_s, :on_message, raw&.[]('action')]
+
+    # data is a Hash for message envelopes, but an Array (the pending list)
+    # in the LIST_PENDING_MESSAGES reply
+    data = raw['data'].is_a?(Hash) ? raw['data'] : {}
+    send_frame connection, API.acknowledge_message_receipt(data['message_id']) if data['message_id']
+
+    # echo PLAIN_TEXT back to its sender over the same connection
+    next unless data['category'] == 'PLAIN_TEXT'
+
+    send_frame connection, API.write_ws_message(
+      params: {
+        conversation_id: data['conversation_id'],
+        recipient_id: data['user_id'],
+        message_id: SecureRandom.uuid,
+        category: 'PLAIN_TEXT',
+        data_base64: Base64.urlsafe_encode64("echo: #{Base64.urlsafe_decode64(data['data'])}", padding: false)
+      }
+    )
+  end
+  p [Time.now.to_s, :closed]
+ensure
+  keepalive&.stop
+  connection&.close
+end

data/lib/mixin_bot/api/blaze_async.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'async/http/endpoint'
+require 'async/http/protocol/http11'
+require 'async/websocket/client'
+
+module MixinBot
+  class API
+    # Fiber-based sibling of +Blaze#blaze+: returns a connected
+    # +Async::WebSocket+ client instead of a +Faye::WebSocket::Client+.
+    #
+    # Same endpoint, +Mixin-Blaze-1+ subprotocol, Bearer JWT, and User-Agent as
+    # +blaze+. The frame codec (+ws_message+, +write_ws_message+,
+    # +list_pending_message+, +acknowledge_message_receipt+) is
+    # transport-agnostic and shared verbatim.
+    #
+    # Wire differences the caller must handle:
+    # - *Send*: +write_ws_message+ returns an +Array+ of byte integers (the
+    #   Faye backend framed that automatically); here the caller wraps it:
+    #   +connection.write(Protocol::WebSocket::BinaryMessage.new(bytes.pack('C*')))+.
+    # - *Read*: +connection.read+ returns a +Protocol::WebSocket::Message+;
+    #   pass +message.to_str+ (the binary buffer) into +ws_message+.
+    # - *Keepalive*: Faye's +ping: 60+ becomes the caller's job (server pings
+    #   are still auto-replied by the protocol layer).
+    #
+    # Sends nothing on open — the caller sends +list_pending_message+ first,
+    # mirroring +blaze+. No per-IO read timeout by default: quiet-but-healthy
+    # connections are legitimate; liveness is the caller's policy.
+    module BlazeAsync
+      # Returns the block-less +Client.connect+ connection, preserving
+      # +blaze+'s "returns a client the caller drives" contract.
+      #
+      # +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+. 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:)
+
+        endpoint = Async::HTTP::Endpoint.parse(
+          format('wss://%<host>s/', host: config.blaze_host),
+          # Force the HTTP/1 upgrade path: avoids the RFC 8441 (h2 CONNECT)
+          # route, which not every gateway negotiates the same way.
+          alpn_protocols: Async::HTTP::Protocol::HTTP11.names,
+          **endpoint_options
+        )
+
+        Async::WebSocket::Client.connect(
+          endpoint,
+          protocols: ['Mixin-Blaze-1'],
+          headers: { 'Authorization' => authorization, 'User-Agent' => "mixin_bot/#{MixinBot::VERSION}" },
+          handler: handler
+        )
+      end
+    end
+  end
+end

data/lib/mixin_bot/api.rb

@@ -8,6 +8,7 @@ require_relative 'api/asset'
 require_relative 'api/attachment'
 require_relative 'api/auth'
 require_relative 'api/blaze'
+require_relative 'api/blaze_async'
 require_relative 'api/chain'
 require_relative 'api/code'
 require_relative 'api/circle'
@@ -338,6 +339,7 @@ module MixinBot
     include MixinBot::API::Attachment
     include MixinBot::API::Auth
     include MixinBot::API::Blaze
+    include MixinBot::API::BlazeAsync
     include MixinBot::API::Chain
     include MixinBot::API::Code
     include MixinBot::API::Circle

data/lib/mixin_bot/blaze/reactor.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require 'async'
+require 'json'
+require 'protocol/websocket'
+
+module MixinBot
+  module Blaze
+    # Fiber-based Blaze receive loop — the hosted sibling of
+    # examples/blaze_async.rb.
+    #
+    # Drives API#blaze_async inside its own Async reactor (created by #run,
+    # so it can be called from any plain thread — e.g. a Puma plugin's
+    # background thread or a forked child). The loop: connect, request
+    # pending messages, read frames serially, dispatch each decoded envelope
+    # to the configured handler, and acknowledge per the ack policy. Receipt
+    # confirmations (ACKNOWLEDGE_MESSAGE_RECEIPT frames) are consumed
+    # internally — never dispatched to the handler nor re-acknowledged.
+    # Dropped connections are re-established with bounded exponential backoff.
+    #
+    # Handlers run serially on the reactor thread — never in concurrent
+    # fibers — so handler code may use per-thread resources like ActiveRecord
+    # connections safely. Handler exceptions are logged and do not end
+    # message delivery.
+    #
+    #   Reactor.new(handler: ->(envelope) { ... }).run   # blocks forever
+    #
+    class Reactor
+      CONNECT_TIMEOUT = 10
+      KEEPALIVE_INTERVAL = 30
+      INITIAL_BACKOFF = 1
+      MAX_BACKOFF = 30
+      # a connection must live at least this long for the backoff to reset
+      STABLE_PERIOD = 30
+
+      attr_reader :handler, :ack_policy
+
+      ##
+      # @param api [MixinBot::API] API used for frame codecs and connecting
+      # @param handler [#call] invoked with each decoded message envelope
+      #   Hash (with +action+ and +data+ keys)
+      # @param ack_policy [Symbol] +:on_receipt+ (ack before the handler
+      #   runs) or +:after_handler+ (ack only after the handler succeeds;
+      #   failed messages are redelivered on reconnect)
+      # @param connection_factory [#call, nil] returns a connected
+      #   +Async::WebSocket+ connection; defaults to +api.blaze_async+
+      #   with a +connect_timeout+ connect phase
+      # @param keepalive_interval [Numeric] seconds between client pings
+      # @param connect_timeout [Numeric] seconds allowed for the connect phase
+      #   (DNS + TCP + TLS + WebSocket upgrade); established connections are
+      #   never timed out on read
+      # @param sleeper [#call, nil] backoff hook, called with seconds;
+      #   defaults to +Kernel#sleep+ (inject for tests)
+      # @param logger [#call, nil] called with +(level, exception_or_message)+;
+      #   defaults to +$stderr+
+      def initialize(handler:, api: MixinBot.api, ack_policy: MixinBot.config.blaze_ack_policy,
+                     connection_factory: nil, keepalive_interval: KEEPALIVE_INTERVAL,
+                     connect_timeout: CONNECT_TIMEOUT, sleeper: nil, logger: nil)
+        raise MixinBot::ArgumentError, 'handler must respond to #call' unless handler.respond_to?(:call)
+        unless %i[on_receipt after_handler].include?(ack_policy)
+          raise MixinBot::ArgumentError, "ack_policy must be :on_receipt or :after_handler, got #{ack_policy.inspect}"
+        end
+
+        @api = api
+        @handler = handler
+        @ack_policy = ack_policy
+        # No socket-level timeout: endpoint timeout: would apply to every read
+        # (a quiet-but-healthy connection would be killed), not just the
+        # connect phase. Liveness is the keepalive ping + the connect-phase
+        # timeout applied in #connect!.
+        @connection_factory = connection_factory || -> { api.blaze_async }
+        @keepalive_interval = keepalive_interval
+        @connect_timeout = connect_timeout
+        @sleeper = sleeper || ->(seconds) { sleep seconds }
+        @logger = logger || ->(level, detail) { warn "[mixin_blaze] #{level}: #{detail}" }
+        @guard = Mutex.new
+        @stopping = false
+        @connection = nil
+      end
+
+      ##
+      # Runs the connect/read/reconnect loop, blocking the calling thread
+      # until #stop. Yields control to the fiber scheduler while waiting.
+      #
+      # @return [void]
+      def run
+        Async do |task|
+          @task = task
+          backoff = INITIAL_BACKOFF
+
+          until stopped?
+            started_at = monotonic_time
+            begin
+              run_connection
+              backoff = INITIAL_BACKOFF if stable?(started_at)
+            rescue StandardError => e
+              log.call :error, e
+              backoff = INITIAL_BACKOFF if stable?(started_at)
+            end
+
+            break if stopped?
+
+            sleep_backoff backoff
+            backoff = [(backoff * 2), MAX_BACKOFF].min
+          end
+        end
+      end
+
+      ##
+      # Stops the loop and closes the current connection. Safe to call from
+      # any thread (including while #run blocks in another one) and safe to
+      # call more than once.
+      #
+      # @return [void]
+      def stop
+        @guard.synchronize do
+          @stopping = true
+          begin
+            @connection&.close
+          rescue StandardError
+            # already dead; the read loop will notice on its own
+          end
+        end
+      end
+
+      private
+
+      def stopped?
+        @guard.synchronize { @stopping }
+      end
+
+      # One connection lifetime: connect, keepalive, pending request, read
+      # loop. Returns on a clean close; raises on a broken one.
+      def run_connection
+        return unless connect!
+
+        log.call :connected, "pid=#{Process.pid}"
+
+        keepalive = start_keepalive
+        send_frame @api.list_pending_message
+
+        while (message = @connection.read)
+          dispatch message
+        end
+        log.call :closed, 'clean close'
+      ensure
+        keepalive&.stop
+        @connection&.close
+        @connection = nil
+      end
+
+      # Establishes the connection and registers it under the guard, so a
+      # concurrent #stop can always find and close it. The connect phase
+      # (DNS + TCP + TLS + WebSocket upgrade) is bounded by #connect_timeout —
+      # a hung connect becomes an error the run loop retries, never a
+      # permanently stuck loop. Returns nil when the reactor stopped
+      # mid-connect; the fresh connection is closed here.
+      def connect!
+        fresh = @task.with_timeout(@connect_timeout) { @connection_factory.call }
+
+        @guard.synchronize do
+          if @stopping
+            begin
+              fresh&.close
+            rescue StandardError
+              nil
+            end
+            return nil
+          end
+
+          @connection = fresh
+        end
+
+        fresh
+      end
+
+      def start_keepalive
+        Async do
+          loop do
+            sleep @keepalive_interval
+            @connection&.send_ping
+          end
+        rescue Protocol::WebSocket::ProtocolError, IOError
+          # the connection is gone; the read loop is already winding down
+        end
+      end
+
+      # Serial dispatch — handlers never run in concurrent fibers.
+      def dispatch(message)
+        raw = decode(message)
+        return if raw.nil?
+
+        # Receipt confirmations echo a message_id the client already knows and
+        # are never redelivered by LIST_PENDING_MESSAGES — they are not
+        # dispatchable events, and acknowledging one back would only
+        # round-trip a no-op frame. Skip them before the ack policy sees them.
+        return if raw['action'] == 'ACKNOWLEDGE_MESSAGE_RECEIPT'
+
+        data = raw['data'].is_a?(Hash) ? raw['data'] : {}
+        message_id = data['message_id']
+
+        send_frame @api.acknowledge_message_receipt(message_id) if @ack_policy == :on_receipt && message_id
+
+        handler_ok =
+          begin
+            handler.call raw
+            true
+          rescue StandardError => e
+            log.call :handler_error, e
+            false
+          end
+
+        send_frame @api.acknowledge_message_receipt(message_id) if @ack_policy == :after_handler && handler_ok && message_id
+      end
+
+      def decode(message)
+        JSON.parse @api.ws_message(message.to_str)
+      rescue Zlib::Error, JSON::ParserError => e
+        log.call :decode_error, e
+        nil
+      end
+
+      def send_frame(bytes)
+        @connection.write Protocol::WebSocket::BinaryMessage.new(bytes.pack('C*'))
+      end
+
+      def sleep_backoff(seconds)
+        @sleeper.call seconds
+      end
+
+      def stable?(started_at)
+        monotonic_time - started_at >= STABLE_PERIOD
+      end
+
+      def monotonic_time
+        Process.clock_gettime Process::CLOCK_MONOTONIC
+      end
+
+      def log
+        @logger
+      end
+    end
+  end
+end

data/lib/mixin_bot/cli/base.rb

@@ -28,6 +28,7 @@ module MixinBot
     INTERACTIVE_API_METHODS = %i[
       start_blaze_connect
       blaze
+      blaze_async
       upload_attachment
     ].freeze
 

data/lib/mixin_bot/configuration.rb

@@ -59,6 +59,17 @@ module MixinBot
     ].freeze
     attr_accessor(*CONFIGURABLE_ATTRS)
 
+    # Acknowledgement policies for the Blaze message loop:
+    # - +:on_receipt+ (default): ack immediately on receipt, before the handler
+    #   runs (at-most-once dispatch).
+    # - +:after_handler+: ack only after the handler completes without raising
+    #   (at-least-once dispatch; unacked messages are redelivered on reconnect).
+    BLAZE_ACK_POLICIES = %i[on_receipt after_handler].freeze
+
+    DEFAULT_BLAZE_ACK_POLICY = :on_receipt
+
+    attr_reader :blaze_handler, :blaze_ack_policy
+
     ##
     # Initializes a new Configuration instance.
     #
@@ -96,6 +107,10 @@ module MixinBot
 
       @debug = kwargs[:debug] || false
 
+      @blaze_ack_policy = DEFAULT_BLAZE_ACK_POLICY
+      self.blaze_handler = kwargs[:blaze_handler]
+      self.blaze_ack_policy = kwargs[:blaze_ack_policy]
+
       self.session_private_key = kwargs[:session_private_key] || kwargs[:private_key]
       self.server_public_key = kwargs[:server_public_key] || kwargs[:pin_token]
       self.spend_key = kwargs[:spend_key]
@@ -203,6 +218,43 @@ module MixinBot
         end
     end
 
+    ##
+    # Sets the callable invoked for each decoded Blaze message envelope.
+    #
+    # Used by MixinBot::Blaze::Reactor (and the +plugin :mixin_blaze+ Puma
+    # plugin) to dispatch messages. The callable receives the full decoded
+    # message envelope Hash (with +action+ and +data+ keys).
+    #
+    # @param callable [#call, nil] the message handler; must respond to #call
+    # @raise [ArgumentError] if a non-callable, non-nil value is given
+    #
+    def blaze_handler=(callable)
+      unless callable.nil? || callable.respond_to?(:call)
+        raise ArgumentError,
+              "blaze_handler must respond to #call, got #{callable.inspect}"
+      end
+
+      @blaze_handler = callable
+    end
+
+    ##
+    # Sets the Blaze acknowledgement policy.
+    #
+    # @param policy [Symbol] +:on_receipt+ (default) or +:after_handler+
+    # @raise [ArgumentError] for unknown policies
+    #
+    def blaze_ack_policy=(policy)
+      return if policy.nil?
+
+      policy = policy.to_sym
+      unless BLAZE_ACK_POLICIES.include?(policy)
+        raise ArgumentError,
+              "blaze_ack_policy must be one of #{BLAZE_ACK_POLICIES.join(', ')}, got #{policy.inspect}"
+      end
+
+      @blaze_ack_policy = policy
+    end
+
     private
 
     def decode_key(key)

data/lib/mixin_bot/version.rb

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

data/lib/mixin_bot.rb

@@ -26,6 +26,7 @@ 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'

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.0.
 
 Important notes:
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: mixin_bot
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 3.0.0
 platform: ruby
 authors:
 - an-lee
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-02 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -24,6 +23,34 @@ 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
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.30'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.30'
 - !ruby/object:Gem::Dependency
   name: awesome_print
   requirement: !ruby/object:Gem::Requirement
@@ -271,6 +298,7 @@ files:
 - docs/agent/cli.md
 - docs/agent/cookbook.md
 - examples/blaze.rb
+- examples/blaze_async.rb
 - examples/config.yml.example
 - lib/mixin_bot.rb
 - lib/mixin_bot/address.rb
@@ -281,6 +309,7 @@ files:
 - lib/mixin_bot/api/attachment.rb
 - lib/mixin_bot/api/auth.rb
 - lib/mixin_bot/api/blaze.rb
+- lib/mixin_bot/api/blaze_async.rb
 - lib/mixin_bot/api/chain.rb
 - lib/mixin_bot/api/circle.rb
 - lib/mixin_bot/api/code.rb
@@ -317,6 +346,7 @@ 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/bot_auth.rb
 - lib/mixin_bot/cache_store_adapter.rb
 - lib/mixin_bot/cli.rb
@@ -371,6 +401,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
@@ -378,7 +409,6 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -386,15 +416,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.16
 specification_version: 4
 summary: A Ruby SDK for Mixin Network
 test_files: []