activematrix 0.0.5 → 0.0.8

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,

data/lib/active_matrix/client_pool.rb

@@ -1,26 +1,36 @@
 # frozen_string_literal: true
 
 require 'singleton'
-require 'concurrent'
+require 'async'
+require 'async/semaphore'
+require 'async/condition'
 
 module ActiveMatrix
-  # Manages a pool of Matrix client connections for efficiency
+  # Manages Matrix client connections per homeserver with rate limiting.
+  #
+  # NOTE: Despite the name, this is not a traditional connection pool.
+  # Each agent gets a dedicated long-lived client. The "pool" provides:
+  # - Semaphore-based rate limiting on client creation per homeserver
+  # - Tracking of active clients for health monitoring
+  #
+  # Clients are NOT returned to the pool after use - they remain active
+  # for the agent's lifetime. The semaphore prevents too many agents
+  # from connecting to a single homeserver simultaneously.
+  #
   class ClientPool
     include Singleton
     include ActiveMatrix::Logging
 
     def initialize
-      @pools = Concurrent::Hash.new
+      @pools = {}
       @config = ActiveMatrix.config
       @mutex = Mutex.new
     end
 
     # Get or create a client for a homeserver
     def get_client(homeserver, **)
-      @mutex.synchronize do
-        pool = get_or_create_pool(homeserver)
-        pool.checkout(**)
-      end
+      pool = @mutex.synchronize { get_or_create_pool(homeserver) }
+      pool.checkout(**)
     end
 
     # Return a client to the pool
@@ -78,32 +88,37 @@ module ActiveMatrix
         @available = []
         @in_use = {}
         @mutex = Mutex.new
-        @condition = ConditionVariable.new
+        @semaphore = Async::Semaphore.new(max_size)
       end
 
       def checkout(**)
-        @mutex.synchronize do
-          # Try to find an available client
-          client = find_available_client
+        # Acquire semaphore temporarily to rate-limit client creation
+        @semaphore.acquire
 
-          # Create new client if needed and pool not full
-          client = create_client(**) if client.nil? && @in_use.size < @max_size
+        client = @mutex.synchronize do
+          # Try to find an available client
+          existing = find_available_client
 
-          # Wait for a client if pool is full
-          while client.nil?
-            @condition.wait(@mutex, 1)
-            client = find_available_client
+          if existing
+            @available.delete(existing)
+            existing
+          else
+            create_client(**)
           end
+        end
 
-          # Mark as in use
-          @available.delete(client)
+        # Track as in use
+        @mutex.synchronize do
           @in_use[client.object_id] = {
             client: client,
             checked_out_at: Time.current
           }
-
-          client
         end
+
+        client
+      ensure
+        # Release immediately - semaphore only rate-limits creation, not usage
+        @semaphore.release
       end
 
       def checkin(client)
@@ -115,12 +130,8 @@ module ActiveMatrix
           if client_valid?(client)
             @available << client
           else
-            # Client is no longer valid, don't return to pool
             logger.debug "Discarding invalid client for #{@homeserver}"
           end
-
-          # Signal waiting threads
-          @condition.signal
         end
       end
 
@@ -140,7 +151,7 @@ module ActiveMatrix
         @mutex.synchronize do
           # Stop all clients
           (@available + @in_use.values.map { |e| e[:client] }).each do |client|
-            client.stop_listener_thread if client.listening?
+            client.stop_listener if client.listening?
             client.logout if client.logged_in?
           rescue StandardError => e
             logger.error "Error cleaning up client: #{e.message}"
@@ -158,7 +169,7 @@ module ActiveMatrix
         @available.select! { |client| client_valid?(client) }
 
         # Return first available
-        @available.first
+        @available.shift
       end
 
       def create_client(**)

data/lib/active_matrix/daemon/probe_server.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'async'
+require 'async/http'
+require 'json'
+
+module ActiveMatrix
+  class Daemon
+    # Lightweight HTTP health probe server using Async::HTTP
+    #
+    # Endpoints:
+    # - GET /health - Returns 200 if healthy, 503 if shutting down
+    # - GET /status - Returns detailed JSON status
+    # - GET /metrics - Prometheus-compatible metrics
+    #
+    class ProbeServer
+      attr_reader :host, :port, :daemon
+
+      def initialize(host:, port:, daemon:)
+        @host = host
+        @port = port
+        @daemon = daemon
+        @thread = nil
+      end
+
+      def start
+        @thread = Thread.new do
+          Sync do
+            endpoint = Async::HTTP::Endpoint.parse("http://#{host}:#{port}")
+
+            @server = Async::HTTP::Server.for(endpoint) do |request|
+              handle_request(request)
+            end
+
+            logger.info "Probe server listening on #{host}:#{port}"
+            @server.run
+          end
+        rescue StandardError => e
+          logger.error "Probe server error: #{e.message}"
+        end
+      end
+
+      def stop
+        @thread&.kill
+        @thread&.join(1)
+      end
+
+      private
+
+      def handle_request(request)
+        path = request.path
+
+        case path
+        when '/health'
+          health_response
+        when '/status'
+          status_response
+        when '/metrics'
+          metrics_response
+        else
+          not_found_response
+        end
+      end
+
+      def health_response
+        status = daemon.status
+        code = status[:status] == 'ok' ? 200 : 503
+
+        ::Protocol::HTTP::Response[code, { 'content-type' => 'text/plain' }, [status[:status]]]
+      end
+
+      def status_response
+        body = JSON.pretty_generate(daemon.status)
+
+        ::Protocol::HTTP::Response[200, { 'content-type' => 'application/json' }, [body]]
+      end
+
+      def metrics_response
+        status = daemon.status
+
+        lines = [
+          '# HELP activematrix_up Is the daemon running',
+          '# TYPE activematrix_up gauge',
+          "activematrix_up #{status[:status] == 'ok' ? 1 : 0}",
+          '',
+          '# HELP activematrix_uptime_seconds Daemon uptime in seconds',
+          '# TYPE activematrix_uptime_seconds counter',
+          "activematrix_uptime_seconds #{status[:uptime]}",
+          '',
+          '# HELP activematrix_workers Number of worker processes',
+          '# TYPE activematrix_workers gauge',
+          "activematrix_workers #{status[:workers]}",
+          '',
+          '# HELP activematrix_agents_total Total number of agents',
+          '# TYPE activematrix_agents_total gauge',
+          "activematrix_agents_total #{status.dig(:agents, :total) || 0}",
+          '',
+          '# HELP activematrix_agents Agent count by state',
+          '# TYPE activematrix_agents gauge',
+          "activematrix_agents{state=\"online\"} #{status.dig(:agents, :online) || 0}",
+          "activematrix_agents{state=\"connecting\"} #{status.dig(:agents, :connecting) || 0}",
+          "activematrix_agents{state=\"error\"} #{status.dig(:agents, :error) || 0}",
+          "activematrix_agents{state=\"offline\"} #{status.dig(:agents, :offline) || 0}"
+        ]
+
+        ::Protocol::HTTP::Response[200, { 'content-type' => 'text/plain; version=0.0.4' }, [lines.join("\n")]]
+      end
+
+      def not_found_response
+        ::Protocol::HTTP::Response[404, { 'content-type' => 'text/plain' }, ['Not Found']]
+      end
+
+      def logger
+        ActiveMatrix.logger
+      end
+    end
+  end
+end