activematrix 0.0.7 → 0.0.8

data/lib/active_matrix/bot/builtin_commands.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module ActiveMatrix
+  module Bot
+    # Built-in commands that can be included in bot classes
+    #
+    # @example Include in a bot
+    #   class MyBot < ActiveMatrix::Bot::Base
+    #     include ActiveMatrix::Bot::BuiltinCommands
+    #   end
+    #
+    module BuiltinCommands
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.register_builtin_commands
+      end
+
+      module ClassMethods
+        def register_builtin_commands
+          # Ping command - connectivity test
+          command(
+            :ping,
+            desc: 'Test bot connectivity and response time'
+          ) do
+            start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+            response_parts = [
+              '**Pong!**',
+              '',
+              'Bot is online and responding',
+              "Server time: #{Time.current.strftime('%Y-%m-%d %H:%M:%S %Z')}"
+            ]
+
+            end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            response_time_ms = ((end_time - start_time) * 1000).round(2)
+            response_parts.insert(2, "Response time: #{response_time_ms}ms")
+
+            room.send_notice(response_parts.join("\n"))
+          end
+
+          # Version command - show bot version
+          command(
+            :version,
+            desc: 'Show bot version information'
+          ) do
+            response_parts = [
+              '**Version Information**',
+              '',
+              "ActiveMatrix: #{ActiveMatrix::VERSION}",
+              "Ruby: #{RUBY_VERSION}",
+              "Platform: #{RUBY_PLATFORM}"
+            ]
+
+            # Add application version if available
+            response_parts << "Application: #{Rails.application.version}" if defined?(Rails) && Rails.application.respond_to?(:version)
+
+            room.send_notice(response_parts.join("\n"))
+          end
+
+          # Status command - show bot status
+          command(
+            :status,
+            desc: 'Show bot status and health information'
+          ) do
+            response_parts = [
+              '**Bot Status**',
+              '',
+              'State: Online',
+              "Uptime: #{format_uptime}",
+              "User ID: #{client.mxid}",
+              "Homeserver: #{client.api.homeserver}"
+            ]
+
+            # Add room count if available
+            if client.respond_to?(:rooms)
+              room_count = client.rooms.size
+              response_parts << "Joined rooms: #{room_count}"
+            end
+
+            # Add metrics if available
+            if defined?(ActiveMatrix::Metrics)
+              metrics = ActiveMatrix::Metrics.instance.get_health_summary
+              if metrics[:total_operations].positive?
+                response_parts += [
+                  '',
+                  '**Metrics**',
+                  "Total operations: #{metrics[:total_operations]}",
+                  "Success rate: #{metrics[:overall_success_rate]}%"
+                ]
+              end
+            end
+
+            room.send_notice(response_parts.join("\n"))
+          end
+
+          # Time command - show current time
+          command(
+            :time,
+            desc: 'Show current time in specified timezone',
+            notes: 'Usage: !time [TIMEZONE]. Examples: !time UTC, !time America/New_York'
+          ) do |timezone = nil|
+            time = if timezone && defined?(ActiveSupport::TimeZone)
+                     tz = ActiveSupport::TimeZone[timezone]
+                     if tz
+                       tz.now
+                     else
+                       room.send_notice("Unknown timezone: #{timezone}. Using server time.")
+                       Time.current
+                     end
+                   else
+                     Time.current
+                   end
+
+            formatted = time.strftime('%Y-%m-%d %H:%M:%S %Z')
+            unix_timestamp = time.to_i
+
+            response_parts = [
+              '**Current Time**',
+              '',
+              formatted,
+              "Unix timestamp: #{unix_timestamp}"
+            ]
+
+            room.send_notice(response_parts.join("\n"))
+          end
+
+          # Echo command - echo back message
+          command(
+            :echo,
+            desc: 'Echo back the provided message'
+          ) do |message = nil|
+            if message.nil? || message.strip.empty?
+              room.send_notice('Nothing to echo. Usage: !echo <message>')
+            else
+              room.send_text(message)
+            end
+          end
+
+          # Rooms command - list joined rooms (admin only)
+          command(
+            :rooms,
+            desc: 'List joined rooms',
+            only: :admin
+          ) do
+            rooms_list = client.rooms.map do |r|
+              name = r.display_name || r.id
+              "- #{name}"
+            end
+
+            if rooms_list.empty?
+              room.send_notice('Not joined to any rooms.')
+            else
+              response = [
+                "**Joined Rooms** (#{rooms_list.size})",
+                '',
+                *rooms_list.first(20)
+              ]
+
+              response << "... and #{rooms_list.size - 20} more" if rooms_list.size > 20
+
+              room.send_notice(response.join("\n"))
+            end
+          end
+        end
+      end
+
+      private
+
+      def format_uptime
+        return 'Unknown' unless defined?(@start_time)
+
+        seconds = (Time.current - @start_time).to_i
+        days = seconds / 86_400
+        hours = (seconds % 86_400) / 3600
+        minutes = (seconds % 3600) / 60
+        secs = seconds % 60
+
+        parts = []
+        parts << "#{days}d" if days.positive?
+        parts << "#{hours}h" if hours.positive?
+        parts << "#{minutes}m" if minutes.positive?
+        parts << "#{secs}s" if secs.positive? || parts.empty?
+
+        parts.join(' ')
+      end
+    end
+  end
+end

data/lib/active_matrix/bot/command_parser.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module ActiveMatrix
+  module Bot
+    # Parses command arguments with support for flags and quoted strings
+    #
+    # @example Basic parsing
+    #   parser = CommandParser.new('search "hello world" --verbose')
+    #   parser.args        # => ["search", "hello world"]
+    #   parser.flags       # => { "verbose" => true }
+    #
+    # @example With key-value flags
+    #   parser = CommandParser.new('greet --name=Alice --formal')
+    #   parser.positional_args  # => []
+    #   parser.flags            # => { "name" => "Alice", "formal" => true }
+    #
+    class CommandParser
+      attr_reader :raw_input, :command_name, :args, :raw_args
+
+      # Command prefixes recognized by the parser
+      COMMAND_PREFIXES = ['/', '!'].freeze
+
+      # @param input [String] Raw command input
+      # @param prefixes [Array<String>] Command prefixes to recognize
+      def initialize(input, prefixes: COMMAND_PREFIXES)
+        @raw_input = input.to_s.strip
+        @prefixes = prefixes
+        @command_name = nil
+        @args = []
+        @raw_args = ''
+        @parsed_flags = nil
+        parse!
+      end
+
+      # Check if input is a valid command (has prefix and command name)
+      #
+      # @return [Boolean]
+      def command?
+        !@command_name.nil? && @prefixes.any? { |prefix| @raw_input.start_with?(prefix) }
+      end
+
+      # Get the prefix used in the command
+      #
+      # @return [String, nil]
+      def prefix
+        @prefixes.find { |p| @raw_input.start_with?(p) }
+      end
+
+      # Parse flags and positional arguments
+      #
+      # @return [Hash] Hash with :flags and :args keys
+      def parse_flags
+        @parse_flags ||= begin
+          flags = {}
+          positional = []
+
+          @args.each do |arg|
+            case arg
+            when /\A--([^=]+)=(.+)\z/
+              # --key=value format
+              flags[Regexp.last_match(1)] = Regexp.last_match(2)
+            when /\A--(.+)\z/
+              # --flag format (boolean)
+              flags[Regexp.last_match(1)] = true
+            when /\A-([a-zA-Z]+)\z/
+              # Short flags like -v, -abc (multiple)
+              Regexp.last_match(1).chars.each { |c| flags[c] = true }
+            else
+              positional << arg
+            end
+          end
+
+          { flags: flags, args: positional }
+        end
+      end
+
+      # Get only positional arguments (no flags)
+      #
+      # @return [Array<String>]
+      def positional_args
+        parse_flags[:args]
+      end
+
+      # Get only flag arguments
+      #
+      # @return [Hash<String, Object>]
+      def flags
+        parse_flags[:flags]
+      end
+
+      # Check if a specific flag is set
+      #
+      # @param name [String] Flag name (without dashes)
+      # @return [Boolean]
+      def flag?(name)
+        flags.key?(name.to_s)
+      end
+
+      # Get a flag value
+      #
+      # @param name [String] Flag name
+      # @param default [Object] Default value if flag not set
+      # @return [Object]
+      def flag(name, default = nil)
+        flags.fetch(name.to_s, default)
+      end
+
+      # Formatted command string
+      #
+      # @return [String]
+      def formatted_command
+        return '' unless command?
+
+        [@command_name, *@args].join(' ')
+      end
+
+      private
+
+      def parse!
+        # Check if input starts with a valid prefix
+        found_prefix = @prefixes.find { |p| @raw_input.start_with?(p) }
+        return unless found_prefix
+
+        # Remove prefix
+        content = @raw_input[found_prefix.length..].strip
+        return if content.empty?
+
+        # Parse respecting quoted strings
+        parts = parse_with_quotes(content)
+        return if parts.empty?
+
+        @command_name = parts.first.downcase
+        @args = parts[1..] || []
+        @raw_args = @args.join(' ')
+      end
+
+      def parse_with_quotes(input)
+        parts = []
+        current = +''
+        in_quotes = false
+        quote_char = nil
+
+        input.each_char do |char|
+          case char
+          when '"', "'"
+            if in_quotes && char == quote_char
+              # End of quoted section
+              in_quotes = false
+              quote_char = nil
+            elsif !in_quotes
+              # Start of quoted section
+              in_quotes = true
+              quote_char = char
+            else
+              # Different quote inside quotes, treat as literal
+              current << char
+            end
+          when ' ', "\t"
+            if in_quotes
+              current << char
+            elsif current.length.positive?
+              parts << current
+              current = +''
+            end
+          else
+            current << char
+          end
+        end
+
+        parts << current if current.length.positive?
+        parts
+      end
+    end
+  end
+end

data/lib/active_matrix/cli.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+# rubocop:disable Rails/Exit
+require 'thor'
+require 'active_matrix'
+require 'active_matrix/daemon'
+
+module ActiveMatrix
+  # Command-line interface for ActiveMatrix daemon
+  #
+  # @example Start the daemon
+  #   bundle exec activematrix start
+  #
+  # @example Start with options
+  #   bundle exec activematrix start --workers 3 --probe-port 3042
+  #
+  class CLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'start', 'Start the ActiveMatrix daemon'
+    option :workers, type: :numeric, default: 1, desc: 'Number of worker processes'
+    option :probe_port, type: :numeric, default: 3042, desc: 'Health check probe port'
+    option :probe_host, type: :string, default: '127.0.0.1', desc: 'Health check bind address'
+    option :agents, type: :string, desc: 'Comma-separated list of agent names to start'
+    option :daemon, type: :boolean, default: false, desc: 'Run as background daemon'
+    option :pidfile, type: :string, desc: 'PID file path (implies --daemon)'
+    option :logfile, type: :string, desc: 'Log file path'
+    option :require, type: :string, aliases: '-r', desc: 'File to require before starting'
+    option :environment, type: :string, aliases: '-e', desc: 'Rails environment'
+    option :otel, type: :boolean, default: false, desc: 'Enable OpenTelemetry tracing'
+    option :otel_exporter, type: :string, default: 'otlp', desc: 'OTel exporter (otlp, console)'
+    def start
+      boot_rails
+      configure_from_options
+
+      daemonize if options[:daemon] || options[:pidfile]
+
+      run_daemon
+    end
+
+    desc 'stop', 'Stop the ActiveMatrix daemon'
+    option :pidfile, type: :string, default: 'tmp/pids/activematrix.pid', desc: 'PID file path'
+    option :timeout, type: :numeric, default: 30, desc: 'Shutdown timeout in seconds'
+    def stop
+      pidfile = options[:pidfile]
+
+      unless File.exist?(pidfile)
+        say "PID file not found: #{pidfile}", :red
+        exit 1
+      end
+
+      pid = File.read(pidfile).to_i
+      say "Stopping ActiveMatrix daemon (PID: #{pid})..."
+
+      begin
+        Process.kill('TERM', pid)
+        wait_for_shutdown(pid, options[:timeout])
+        say 'Daemon stopped successfully', :green
+      rescue Errno::ESRCH
+        say 'Process not running, cleaning up PID file', :yellow
+        File.delete(pidfile)
+      rescue Errno::EPERM
+        say "Permission denied to stop process #{pid}", :red
+        exit 1
+      end
+    end
+
+    desc 'status', 'Show daemon status'
+    option :pidfile, type: :string, default: 'tmp/pids/activematrix.pid', desc: 'PID file path'
+    option :probe_port, type: :numeric, default: 3042, desc: 'Health check probe port'
+    option :probe_host, type: :string, default: '127.0.0.1', desc: 'Health check host'
+    def status
+      # Try HTTP probe first
+      if (probe_status = fetch_probe_status)
+        display_status(probe_status)
+      elsif (pid = read_pid)
+        say "Daemon running (PID: #{pid}), but health probe not responding", :yellow
+      else
+        say 'Daemon not running', :red
+        exit 1
+      end
+    end
+
+    desc 'reload', 'Reload agent configuration'
+    option :pidfile, type: :string, default: 'tmp/pids/activematrix.pid', desc: 'PID file path'
+    def reload
+      pid = read_pid
+      unless pid
+        say 'Daemon not running', :red
+        exit 1
+      end
+
+      begin
+        Process.kill('HUP', pid)
+        say 'Reload signal sent', :green
+      rescue Errno::ESRCH
+        say 'Process not running', :red
+        exit 1
+      rescue Errno::EPERM
+        say 'Permission denied', :red
+        exit 1
+      end
+    end
+
+    desc 'version', 'Show ActiveMatrix version'
+    def version
+      say "ActiveMatrix #{ActiveMatrix::VERSION}"
+    end
+
+    map %w[-v --version] => :version
+
+    private
+
+    def boot_rails
+      ENV['RAILS_ENV'] ||= options[:environment] || 'development'
+
+      if options[:require]
+        require File.expand_path(options[:require])
+      elsif File.exist?('config/environment.rb')
+        require File.expand_path('config/environment.rb')
+      else
+        say 'No Rails application found. Use --require to specify a file.', :red
+        exit 1
+      end
+    end
+
+    def configure_from_options
+      ActiveMatrix.configure do |config|
+        config.daemon_workers = options[:workers] if options[:workers]
+        config.probe_port = options[:probe_port] if options[:probe_port]
+        config.probe_host = options[:probe_host] if options[:probe_host]
+      end
+
+      configure_telemetry if options[:otel]
+    end
+
+    def configure_telemetry
+      require 'active_matrix/telemetry'
+
+      exporter = options[:otel_exporter]&.to_sym
+      ActiveMatrix::Telemetry.configure!(exporter: exporter)
+    rescue LoadError => e
+      say "OpenTelemetry not available: #{e.message}", :yellow
+      say 'Install opentelemetry-sdk and opentelemetry-exporter-otlp gems', :yellow
+    end
+
+    def daemonize
+      pidfile = options[:pidfile] || 'tmp/pids/activematrix.pid'
+      logfile = options[:logfile] || 'log/activematrix.log'
+
+      # Ensure directories exist
+      FileUtils.mkdir_p(File.dirname(pidfile))
+      FileUtils.mkdir_p(File.dirname(logfile))
+
+      # Check if already running
+      if File.exist?(pidfile)
+        pid = File.read(pidfile).to_i
+        begin
+          Process.kill(0, pid)
+          say "Daemon already running (PID: #{pid})", :red
+          exit 1
+        rescue Errno::ESRCH
+          File.delete(pidfile)
+        end
+      end
+
+      Process.daemon(true, true)
+
+      # Redirect output
+      $stdout.reopen(logfile, 'a')
+      $stderr.reopen($stdout)
+      $stdout.sync = true
+
+      # Write PID file
+      File.write(pidfile, Process.pid.to_s)
+
+      at_exit { FileUtils.rm_f(pidfile) }
+    end
+
+    def run_daemon
+      daemon = ActiveMatrix::Daemon.new(
+        workers: options[:workers],
+        probe_port: options[:probe_port],
+        probe_host: options[:probe_host],
+        agent_names: parse_agent_names
+      )
+
+      daemon.run
+    end
+
+    def parse_agent_names
+      return nil unless options[:agents]
+
+      options[:agents].split(',').map(&:strip)
+    end
+
+    def read_pid
+      pidfile = options[:pidfile]
+      return nil unless File.exist?(pidfile)
+
+      pid = File.read(pidfile).to_i
+      begin
+        Process.kill(0, pid)
+        pid
+      rescue Errno::ESRCH
+        nil
+      end
+    end
+
+    def wait_for_shutdown(pid, timeout)
+      deadline = Time.zone.now + timeout
+
+      while Time.zone.now < deadline
+        begin
+          Process.kill(0, pid)
+          sleep 0.5
+        rescue Errno::ESRCH
+          return true
+        end
+      end
+
+      say 'Timeout waiting for graceful shutdown, sending SIGKILL', :yellow
+      Process.kill('KILL', pid)
+    end
+
+    def fetch_probe_status
+      require 'net/http'
+      require 'json'
+
+      uri = URI("http://#{options[:probe_host]}:#{options[:probe_port]}/status")
+      response = Net::HTTP.get_response(uri)
+
+      return nil unless response.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(response.body, symbolize_names: true)
+    rescue StandardError
+      nil
+    end
+
+    def display_status(status)
+      say 'ActiveMatrix Daemon Status', :green
+      say '=' * 40
+      say "Status: #{status[:status]}"
+      say "Uptime: #{format_duration(status[:uptime])}"
+      say "Workers: #{status[:workers]}"
+      say ''
+      say 'Agents:'
+      say "  Total:      #{status.dig(:agents, :total) || 0}"
+      say "  Online:     #{status.dig(:agents, :online) || 0}"
+      say "  Connecting: #{status.dig(:agents, :connecting) || 0}"
+      say "  Error:      #{status.dig(:agents, :error) || 0}"
+    end
+
+    def format_duration(seconds)
+      return 'N/A' unless seconds
+
+      hours = seconds / 3600
+      minutes = (seconds % 3600) / 60
+      secs = seconds % 60
+
+      if hours.positive?
+        "#{hours}h #{minutes}m #{secs}s"
+      elsif minutes.positive?
+        "#{minutes}m #{secs}s"
+      else
+        "#{secs}s"
+      end
+    end
+  end
+end
+# rubocop:enable Rails/Exit

data/lib/active_matrix/client.rb

@@ -18,7 +18,7 @@ module ActiveMatrix
     # @!attribute sync_filter [rw] The global sync filter
     #   @return [Hash,String] A filter definition, either as defined by the
     #           Matrix spec, or as an identifier returned by a filter creation request
-    attr_reader :api
+    attr_reader :api, :sync_thread
     attr_accessor :cache, :sync_filter, :next_batch
 
     events :error, :event, :account_data, :presence_event, :invite_event, :leave_event, :ephemeral_event, :state_event
@@ -499,11 +499,7 @@ module ActiveMatrix
     def stop_listener_thread
       return unless @sync_thread
 
-      if @should_listen.is_a? Hash
-        @should_listen[:run] = false
-      else
-        @should_listen = false
-      end
+      stop_listener
 
       if @sync_thread.alive?
         ret = @sync_thread.join(0.1)
@@ -512,11 +508,30 @@ module ActiveMatrix
       @sync_thread = nil
     end
 
+    # Signal the listener to stop (works for both thread and async modes)
+    def stop_listener
+      if @should_listen.is_a? Hash
+        @should_listen[:run] = false
+      else
+        @should_listen = false
+      end
+    end
+
+    # Start listening without spawning a thread (for use with async)
+    def start_listener
+      @should_listen = true
+    end
+
     # Check if there's a thread listening for events
     def listening?
       @sync_thread&.alive? == true
     end
 
+    # Check if listening is enabled (may or may not have active thread)
+    def listening_enabled?
+      @should_listen == true
+    end
+
     # Run a message sync round, triggering events as necessary
     #
     # @param skip_store_batch [Boolean] Should this sync skip storing the returned next_batch token,