mixin_bot 2.6.0 → 3.0.2

data/lib/mixin_bot/blaze/reactor.rb

@@ -0,0 +1,249 @@
+# 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 = 300
+      # A connection must live at least this long to count as "stable" and
+      # reset the reconnect backoff. The bar sits well above any single
+      # backoff step so a session that a gateway throttles at a fixed short
+      # lifetime (e.g. closed ~30s after every handshake) never reads as
+      # stable — otherwise the loop pins itself at the fastest retry rate
+      # and hammers the endpoint indefinitely.
+      STABLE_PERIOD = 120
+
+      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/blaze/router.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module MixinBot
+  module Blaze
+    # Routes decoded Blaze envelopes to handler classes — the dispatch layer
+    # above {MixinBot::Blaze::Reactor}'s raw `blaze_handler` lambda contract.
+    #
+    # A router IS a handler: it answers #call with the decoded envelope Hash,
+    # so it plugs straight into the configured Blaze handler:
+    #
+    #   router = MixinBot::Blaze::Router.new do
+    #     on 'text', EchoHandler
+    #     on 'transfer', DepositHandler
+    #     on category: 'APP_CARD', handler: AppCardHandler
+    #     on action: 'CREATE_MESSAGE', handler: ->(message) { ... }
+    #   end
+    #
+    #   MixinBot.configure do
+    #     self.blaze_handler = router
+    #   end
+    #
+    # or per bot: MixinBot::Blaze::Router.new(api: MixinBot.bot(:shop)) { ... }
+    #
+    # Matching is first-registered-wins on the message category (aliases like
+    # 'text' normalize to PLAIN_TEXT; raw categories pass through verbatim) or
+    # on a Hash of conditions ({action:, category:}) that must all hold.
+    # Unmatched envelopes are logged and ignored.
+    #
+    # Handler exceptions are logged (:handler_error) and re-raised: the
+    # reactor owns containment (it logs and keeps the loop alive) and, under
+    # `ack_policy: :after_handler`, withholds the acknowledgement so a failed
+    # message is redelivered on reconnect. Swallowing here would turn that
+    # policy into at-most-once.
+    #
+    # Handlers are one of:
+    # - a Class with #initialize(message) + #call (see {Router::Base});
+    #   instantiated per message, so handlers stay stateless;
+    # - any object responding to #call(message) (proc, method, instance).
+    #
+    class Router
+      ##
+      # Decoded view of a Blaze envelope. Wraps the raw envelope Hash and the
+      # bot API client that dispatched it, exposing decoded message data and
+      # a reply helper over the HTTP message API (no WebSocket access).
+      #
+      class Message
+        # Categories whose data_base64 payload is JSON (everything but
+        # PLAIN_TEXT/PLAIN_POST, whose payloads are plain strings).
+        JSON_CATEGORIES = %w[
+          PLAIN_CONTACT
+          PLAIN_STICKER
+          PLAIN_LIVE
+          PLAIN_LOCATION
+          PLAIN_IMAGE
+          PLAIN_DATA
+          PLAIN_AUDIO
+          PLAIN_VIDEO
+          APP_CARD
+          APP_BUTTON_GROUP
+          SYSTEM_ACCOUNT_SNAPSHOT
+          MESSAGE_RECALL
+        ].freeze
+
+        attr_reader :raw
+
+        def initialize(raw, api:)
+          @raw = raw.is_a?(Hash) ? raw : {}
+          @api = api
+        end
+
+        def action
+          @raw['action']
+        end
+
+        # The envelope's message params Hash (empty when absent).
+        def params
+          data = @raw['data']
+          data.is_a?(Hash) ? data : {}
+        end
+
+        def category
+          params['category']
+        end
+
+        def conversation_id
+          params['conversation_id']
+        end
+
+        def recipient_id
+          params['recipient_id']
+        end
+
+        def representative_id
+          params['representative_id']
+        end
+
+        def message_id
+          params['message_id']
+        end
+
+        # The message's sender (inbound messages carry the sender in user_id).
+        def user_id
+          params['user_id']
+        end
+
+        def quote_message_id
+          params['quote_message_id']
+        end
+
+        ##
+        # The decoded message payload: the base64-decoded string for text-like
+        # categories, parsed JSON for structured ones. Decoded lazily, once.
+        #
+        def data
+          return @data if defined?(@data)
+
+          decoded = Base64.decode64(params['data_base64'].to_s)
+          @data = JSON_CATEGORIES.include?(category) ? parse_json(decoded) : decoded
+        end
+
+        ##
+        # Sends content back to the message's sender in its conversation over
+        # the HTTP message API. Supports PLAIN_TEXT (default) and PLAIN_POST;
+        # for anything richer, build params via the bound API (exposed by
+        # {Blaze::API helpers} on the api client) and send directly.
+        #
+        # @param content [String] text or post content
+        # @param category [String] 'PLAIN_TEXT' or 'PLAIN_POST'
+        #
+        def reply(content, category: 'PLAIN_TEXT')
+          options = { conversation_id:, recipient_id: user_id, data: content }
+          payload =
+            case category
+            when 'PLAIN_TEXT' then @api.plain_text(options)
+            when 'PLAIN_POST' then @api.plain_post(options)
+            else raise MixinBot::ArgumentError, "unsupported reply category #{category.inspect}"
+            end
+
+          @api.send_message(payload)
+        end
+
+        private
+
+        def parse_json(str)
+          JSON.parse(str)
+        rescue JSON::ParserError, EncodingError
+          str
+        end
+      end
+
+      ##
+      # Base class for message handlers: subclass, implement #handle, use
+      # #reply / #message. Instantiated per message by the router.
+      #
+      class Base
+        attr_reader :message
+
+        def initialize(message)
+          @message = message
+        end
+
+        def call
+          handle
+        end
+
+        def handle
+          raise NotImplementedError, "#{self.class} must implement #handle"
+        end
+
+        def reply(content, category: 'PLAIN_TEXT')
+          message.reply(content, category:)
+        end
+      end
+
+      # A compiled matcher paired with its handler.
+      Route = Struct.new(:matcher, :handler) do
+        def matches?(message)
+          matcher.call(message)
+        end
+      end
+
+      # Short aliases accepted by #on (in addition to raw categories, which
+      # pass through verbatim when they start with PLAIN_/SYSTEM_/APP_/
+      # MESSAGE_).
+      CATEGORY_ALIASES = {
+        'text' => 'PLAIN_TEXT',
+        'post' => 'PLAIN_POST',
+        'image' => 'PLAIN_IMAGE',
+        'data' => 'PLAIN_DATA',
+        'file' => 'PLAIN_DATA',
+        'sticker' => 'PLAIN_STICKER',
+        'contact' => 'PLAIN_CONTACT',
+        'audio' => 'PLAIN_AUDIO',
+        'video' => 'PLAIN_VIDEO',
+        'live' => 'PLAIN_LIVE',
+        'location' => 'PLAIN_LOCATION',
+        'transfer' => 'SYSTEM_ACCOUNT_SNAPSHOT',
+        'snapshot' => 'SYSTEM_ACCOUNT_SNAPSHOT',
+        'app_card' => 'APP_CARD',
+        'app_button_group' => 'APP_BUTTON_GROUP',
+        'buttons' => 'APP_BUTTON_GROUP',
+        'recall' => 'MESSAGE_RECALL'
+      }.freeze
+
+      attr_reader :api, :routes
+
+      ##
+      # @param api [MixinBot::API] bot client bound to this router; replies and
+      #   handler-side API calls use its credentials
+      # @param logger [#call, nil] called with (level, detail); defaults to
+      #   $stderr (same shape as MixinBot::Blaze::Reactor's logger)
+      # @yield the routing DSL (see #on)
+      #
+      def initialize(api: MixinBot.api, logger: nil, &)
+        @api = api
+        @routes = []
+        @logger = logger || ->(level, detail) { warn "[mixin_blaze] #{level}: #{detail}" }
+        instance_exec(&) if block_given?
+      end
+
+      ##
+      # Registers a route. Matchers:
+      # - a category alias or raw category string/symbol ('text', 'app_card',
+      #   'PLAIN_TEXT', ...);
+      # - a Hash of conditions, e.g. {action: 'CREATE_MESSAGE'} or
+      #   {category: 'text'} — all conditions must hold.
+      #
+      # The handler is a Class (instantiated per message) or anything
+      # responding to #call(message). Routes match in registration order;
+      # the first match wins.
+      #
+      # @return [self] (chainable)
+      #
+      def on(matcher, handler = nil, &block)
+        if matcher.is_a?(Hash) && matcher.key?(:handler)
+          raise MixinBot::ArgumentError, 'handler given twice (positional and :handler key)' if handler || block
+
+          handler = matcher[:handler]
+          matcher = matcher.except(:handler)
+        end
+        handler ||= block
+        raise MixinBot::ArgumentError, 'a handler class or callable is required' unless handler
+        unless handler.is_a?(Class) || handler.respond_to?(:call)
+          raise MixinBot::ArgumentError, "handler #{handler.inspect} must be a class or respond to #call"
+        end
+
+        @routes << Route.new(compile_matcher(matcher), handler)
+        self
+      end
+
+      ##
+      # Dispatches one decoded envelope Hash (the reactor's handler contract).
+      # Unmatched envelopes are logged and ignored; handler exceptions are
+      # logged and re-raised so the reactor's ack policy and containment
+      # govern retry/redelivery.
+      #
+      # @param raw [Hash] decoded envelope with 'action' and 'data' keys
+      # @raise [StandardError] when the matched handler raises
+      #
+      def call(raw)
+        message = Message.new(raw, api: @api)
+        route = @routes.find { |candidate| candidate.matches?(message) }
+
+        if route.nil?
+          @logger.call(:unmatched, "action=#{message.action.inspect} category=#{message.category.inspect}")
+          return
+        end
+
+        dispatch(route.handler, message)
+      end
+
+      # Normalizes a category alias or raw category to its canonical form.
+      #
+      # @return [String]
+      # @raise [MixinBot::ArgumentError] for unknown categories
+      #
+      def self.normalize_category(value)
+        key = value.to_s.downcase
+        return CATEGORY_ALIASES[key] if CATEGORY_ALIASES.key?(key)
+
+        upcased = value.to_s.upcase
+        return upcased if upcased.start_with?('PLAIN_', 'SYSTEM_', 'APP_', 'MESSAGE_')
+
+        raise MixinBot::ArgumentError, "unknown message category #{value.inspect}"
+      end
+
+      private
+
+      def dispatch(handler, message)
+        if handler.is_a?(Class)
+          handler.new(message).call
+        elsif handler.respond_to?(:call)
+          handler.call(message)
+        else
+          raise MixinBot::ArgumentError, "handler #{handler.inspect} must be a class or respond to #call"
+        end
+      rescue StandardError => e
+        @logger.call(:handler_error, e)
+        raise
+      end
+
+      def compile_matcher(matcher)
+        case matcher
+        when Hash
+          conditions = matcher.map { |key, value| compile_condition(key, value) }
+          ->(message) { conditions.all? { |condition| condition.call(message) } }
+        when String, Symbol
+          category = self.class.normalize_category(matcher)
+          ->(message) { message.category == category }
+        else
+          raise MixinBot::ArgumentError,
+                "matcher must be a category alias or a conditions Hash, got #{matcher.inspect}"
+        end
+      end
+
+      def compile_condition(key, value)
+        case key.to_sym
+        when :category
+          category = self.class.normalize_category(value)
+          ->(message) { message.category == category }
+        when :action
+          action = value.to_s
+          ->(message) { message.action == action }
+        else
+          raise MixinBot::ArgumentError,
+                "unknown route condition #{key.inspect} (supported: :category, :action)"
+        end
+      end
+    end
+  end
+end

data/lib/mixin_bot/cache_store_adapter.rb

@@ -20,7 +20,9 @@ module MixinBot
     KEY_PREFIX = 'mixin_bot/sessions'
 
     def initialize(cache = nil, expires_in: nil)
-      cache ||= Rails.cache if defined?(Rails)
+      # ::Rails (not bare Rails): lexical lookup under module MixinBot must
+      # never resolve to a MixinBot-namespaced constant.
+      cache ||= ::Rails.cache if defined?(::Rails)
       raise ArgumentError, 'a cache store is required' if cache.nil?
 
       @cache = cache

data/lib/mixin_bot/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'client/error_mapper'
+require_relative 'json_decoder'
 
 module MixinBot
   ##
@@ -24,7 +25,7 @@ module MixinBot
         f.request :retry, max: 2, interval: 0.5, interval_randomness: 0.5, backoff_factor: 2,
                           exceptions: [Faraday::ConnectionFailed, Faraday::TimeoutError]
         f.options.timeout = @config.http_timeout if @config.http_timeout
-        f.response :json
+        f.response :json, parser_options: { decoder: [JSONDecoder, :parse] }
         f.response :logger if @config.debug
       end
     end

data/lib/mixin_bot/computer.rb

@@ -2,6 +2,8 @@
 
 require 'faraday'
 
+require_relative 'json_decoder'
+
 module MixinBot
   # Mixin Computer API client (https://computer.mixin.one).
   class Computer
@@ -15,7 +17,7 @@ module MixinBot
       def connection
         @connection ||= Faraday.new(url: BASE_URI) do |f|
           f.request :json
-          f.response :json
+          f.response :json, parser_options: { decoder: [MixinBot::JSONDecoder, :parse] }
           f.adapter Faraday.default_adapter
         end
       end

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)