mixin_bot 2.5.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce614b6fab815a9d8dfb1e93914fdaf3ba6b7306b1f5d35ab594efcd0b46fe68
-  data.tar.gz: 70b09c5ba22efc597a43b560a4257e2984b059b8334eee6efa19498934e87407
+  metadata.gz: 42fc9aa30981430bf8a4b32ac343994fedb94f3a318d4c519404f788f66d8c68
+  data.tar.gz: df1037544f1eb11ec4cf196aacbd076db8a3aa6c2dc11ed1d138751cdb37e073
 SHA512:
-  metadata.gz: ab61a3850c702cb36a00794f5cfacb3aa63d18d6fca24104d9be336b97b04332430eb702bba50d6bbaa80f9ad94976fa5aaeefaae69f736bed88b21ffce7f849
-  data.tar.gz: c2a237075b8c9399ef4f90d933d1bac288de35aefa11ff6fa55d3dd4e19a337d0a10f78173a9eef77a16476a63e208fa22b0c3250758ad7c2324490411ffa4b7
+  metadata.gz: a12c51222b50582cd31b4e80d17f3f95c73627845ec3500701a02de21d68de887e85ccf599e505be8ec81ce6c903485ec193ae6ee3e865dce9e2bd2b984ef023
+  data.tar.gz: 1dbb16ececb43acf6febcc42467ffb631b064fcb508f235c4a6e19148c15c328935a9ec1a297bffa45baebd70fc0b7458bf98d374fc2f5c0930734345bf67d29

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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,7 +6,7 @@ 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: **2.6.0** (see [CHANGELOG.md](CHANGELOG.md) for breaking changes and deprecations).
 
 ## Requirements
 
@@ -257,6 +257,39 @@ 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
+```
+
 ## Deep links and bot auth
 
 ```ruby

data/examples/blaze_async.rb

@@ -0,0 +1,89 @@
+# 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 (a connect
+  # timeout here). handler: stays default; pass an Async::WebSocket::Connection
+  # subclass to hook the raw frame events (e.g. PONG correlation).
+  connection = API.blaze_async(endpoint_options: { timeout: 10 })
+  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,58 @@
+# 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+ (e.g. +timeout:+ for the connect phase).
+      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/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/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mixin_bot
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.6.0
 platform: ruby
 authors:
 - an-lee
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-02 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7'
+- !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 +285,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 +296,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