async-matrix 1.0.0 → 1.1.1

data/lib/async/discord/gateway.rb

@@ -0,0 +1,362 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+require "async"
+require "async/http/endpoint"
+require "async/websocket/client"
+require "json"
+require "console"
+require "async/discord"
+
+module Async
+  module Discord
+    # WebSocket client for the Discord Gateway (v10).
+    #
+    # Connects to Discord's WebSocket gateway, authenticates with a bot token,
+    # manages heartbeating, and dispatches incoming events to registered handlers.
+    #
+    # Supports session resumption on reconnect.
+    #
+    #   gateway = Async::Discord::Gateway.new(token: "MTk...", intents: 0x30001)
+    #   gateway.on("MESSAGE_CREATE") { |data| puts data["content"] }
+    #   gateway.on("READY") { |data| puts "Connected as #{data["user"]["username"]}" }
+    #   gateway.run  # blocks, runs inside Async reactor
+    #
+    class Gateway
+      GATEWAY_URL = "wss://gateway.discord.gg/?v=10&encoding=json"
+
+      # Discord Gateway opcodes
+      DISPATCH           = 0
+      HEARTBEAT          = 1
+      IDENTIFY           = 2
+      PRESENCE_UPDATE    = 3
+      VOICE_STATE_UPDATE = 4
+      RESUME             = 6
+      RECONNECT          = 7
+      REQUEST_GUILD_MEMBERS = 8
+      INVALID_SESSION    = 9
+      HELLO              = 10
+      HEARTBEAT_ACK      = 11
+
+      attr_reader :session_id, :seq
+
+      def initialize(token:, intents:, gateway_url: GATEWAY_URL)
+        @token       = token
+        @intents     = intents
+        @gateway_url = gateway_url
+        @handlers    = Hash.new { |h, k| h[k] = [] }
+        @seq         = nil
+        @session_id  = nil
+        @resume_url  = nil
+        @heartbeat_interval = nil
+        @heartbeat_acked    = true
+        @connection  = nil
+        @running     = false
+      end
+
+      # Register a handler for a Discord event type.
+      #
+      #   gateway.on("MESSAGE_CREATE") { |data| ... }
+      #   gateway.on("READY") { |data| ... }
+      #
+      def on(event_type, &block)
+        @handlers[event_type] << block
+      end
+
+      # Connect to the gateway and run the event loop.
+      # Blocks until the connection is closed or an unrecoverable error occurs.
+      # Must be called inside an Async reactor.
+      def run
+        @running = true
+
+        while @running
+          begin
+            connect_and_run
+          rescue => e
+            Console.error(self) { "Gateway error: #{e.class}: #{e.message}" }
+            break unless @running
+            sleep(5)
+          end
+        end
+      end
+
+      # Gracefully stop the gateway.
+      def stop
+        @running = false
+        @connection&.close
+      end
+
+      # Send a raw payload to the gateway.
+      def send_payload(op:, d: nil)
+        return unless @connection
+
+        payload = {op: op, d: d}
+        @connection.write(payload.to_json)
+        @connection.flush
+      end
+
+      private
+
+        def connect_and_run
+          url = @resume_url || @gateway_url
+          endpoint = Async::HTTP::Endpoint.parse(url)
+
+          Console.info(self) { "Connecting to #{url}" }
+
+          Async::WebSocket::Client.connect(endpoint) do |connection|
+            @connection = connection
+
+            # First message should be HELLO
+            hello = read_message
+            unless hello && hello["op"] == HELLO
+              raise GatewayError.new("GATEWAY", "Expected HELLO, got: #{hello&.dig("op")}")
+            end
+
+            @heartbeat_interval = hello["d"]["heartbeat_interval"] / 1000.0
+            Console.info(self) { "Heartbeat interval: #{@heartbeat_interval}s" }
+
+            # Start heartbeat fiber
+            heartbeat_task = Async do
+              heartbeat_loop
+            end
+
+            # Identify or resume
+            if @session_id && @seq
+              send_resume
+            else
+              send_identify
+            end
+
+            # Read events until disconnected
+            read_loop
+
+          ensure
+            heartbeat_task&.stop
+            @connection = nil
+          end
+        end
+
+        def read_message
+          message = @connection.read
+          return nil unless message
+
+          JSON.parse(message.to_str)
+        rescue => e
+          Console.error(self) { "Failed to read/parse gateway message: #{e.message}" }
+          nil
+        end
+
+        def read_loop
+          loop do
+            payload = read_message
+            break unless payload
+
+            handle_payload(payload)
+          end
+        end
+
+        def handle_payload(payload)
+          op   = payload["op"]
+          data = payload["d"]
+          seq  = payload["s"]
+          type = payload["t"]
+
+          @seq = seq if seq
+
+          case op
+          when DISPATCH
+            Console.debug(self) { "DISPATCH: #{type}" }
+            dispatch(type, data)
+
+          when HEARTBEAT
+            # Server is asking us to heartbeat immediately
+            send_heartbeat
+
+          when RECONNECT
+            Console.info(self) { "Server requested reconnect" }
+            @connection&.close
+
+          when INVALID_SESSION
+            resumable = data == true
+            Console.warn(self) { "Invalid session (resumable=#{resumable})" }
+            unless resumable
+              @session_id = nil
+              @seq = nil
+            end
+            sleep(rand(1.0..5.0))
+            @connection&.close
+
+          when HEARTBEAT_ACK
+            @heartbeat_acked = true
+
+          else
+            Console.debug(self) { "Unknown opcode: #{op}" }
+          end
+        end
+
+        def dispatch(event_type, data)
+          case event_type
+          when "READY"
+            @session_id = data["session_id"]
+            @resume_url = data["resume_gateway_url"]
+            Console.info(self) { "Ready: session=#{@session_id}" }
+          when "RESUMED"
+            Console.info(self) { "Resumed successfully" }
+          end
+
+          @handlers[event_type].each do |handler|
+            begin
+              handler.call(data)
+            rescue => e
+              Console.error(self) { "Handler for #{event_type} raised: #{e.class}: #{e.message}" }
+            end
+          end
+        end
+
+        def send_identify
+          send_payload(
+            op: IDENTIFY,
+            d: {
+              token: @token,
+              intents: @intents,
+              properties: {
+                os: RUBY_PLATFORM,
+                browser: "async-discord",
+                device: "async-discord"
+              }
+            }
+          )
+        end
+
+        def send_resume
+          Console.info(self) { "Resuming session #{@session_id} at seq #{@seq}" }
+          send_payload(
+            op: RESUME,
+            d: {
+              token: @token,
+              session_id: @session_id,
+              seq: @seq
+            }
+          )
+        end
+
+        def send_heartbeat
+          send_payload(op: HEARTBEAT, d: @seq)
+          @heartbeat_acked = false
+        end
+
+        def heartbeat_loop
+          # Jitter the first heartbeat as per Discord docs
+          sleep(@heartbeat_interval * rand)
+          send_heartbeat
+
+          loop do
+            sleep(@heartbeat_interval)
+
+            unless @heartbeat_acked
+              Console.warn(self) { "Heartbeat not ACKed, reconnecting" }
+              @connection&.close
+              break
+            end
+
+            send_heartbeat
+          end
+        end
+    end
+  end
+end
+
+test do
+  describe "Async::Discord::Gateway" do
+    it "initializes with token and intents" do
+      gw = Async::Discord::Gateway.new(token: "test_token", intents: 0x30001)
+      gw.session_id.should.be.nil
+      gw.seq.should.be.nil
+    end
+
+    it "registers event handlers" do
+      gw = Async::Discord::Gateway.new(token: "test_token", intents: 0)
+      received = []
+      gw.on("MESSAGE_CREATE") { |data| received << data }
+      gw.on("MESSAGE_CREATE") { |data| received << :second }
+
+      # Dispatch manually via send to test handler registration
+      gw.send(:dispatch, "MESSAGE_CREATE", {"content" => "hello"})
+      received.length.should == 2
+      received[0]["content"].should == "hello"
+      received[1].should == :second
+    end
+
+    it "handles READY event and stores session_id" do
+      gw = Async::Discord::Gateway.new(token: "test_token", intents: 0)
+      ready_data = {
+        "session_id" => "abc123",
+        "resume_gateway_url" => "wss://resume.discord.gg",
+        "user" => {"username" => "testbot"}
+      }
+
+      gw.send(:dispatch, "READY", ready_data)
+      gw.session_id.should == "abc123"
+    end
+
+    it "updates seq from dispatch payloads" do
+      gw = Async::Discord::Gateway.new(token: "test_token", intents: 0)
+      gw.send(:handle_payload, {
+        "op" => 0,
+        "d" => {"content" => "hi"},
+        "s" => 42,
+        "t" => "MESSAGE_CREATE"
+      })
+      gw.seq.should == 42
+    end
+
+    it "clears session on non-resumable INVALID_SESSION" do
+      gw = Async::Discord::Gateway.new(token: "test_token", intents: 0)
+      # Set a session first
+      gw.send(:dispatch, "READY", {
+        "session_id" => "sess123",
+        "resume_gateway_url" => "wss://resume.discord.gg"
+      })
+      gw.session_id.should == "sess123"
+
+      # Simulate non-resumable invalid session (stub connection close)
+      gw.instance_variable_set(:@connection, nil)
+      gw.send(:handle_payload, {
+        "op" => Async::Discord::Gateway::INVALID_SESSION,
+        "d" => false,
+        "s" => nil,
+        "t" => nil
+      })
+      gw.session_id.should.be.nil
+      gw.seq.should.be.nil
+    end
+
+    it "continues dispatching when a handler raises" do
+      gw = Async::Discord::Gateway.new(token: "test_token", intents: 0)
+      results = []
+      gw.on("TEST") { |_| raise "boom" }
+      gw.on("TEST") { |data| results << data }
+
+      gw.send(:dispatch, "TEST", {"value" => 1})
+      results.length.should == 1
+      results.first["value"].should == 1
+    end
+
+    it "responds to stop" do
+      gw = Async::Discord::Gateway.new(token: "test_token", intents: 0)
+      gw.should.respond_to :stop
+    end
+
+    it "accepts custom gateway URL" do
+      gw = Async::Discord::Gateway.new(
+        token: "tok",
+        intents: 0,
+        gateway_url: "wss://custom.gateway.example.com"
+      )
+      gw.instance_variable_get(:@gateway_url).should == "wss://custom.gateway.example.com"
+    end
+  end
+end

data/lib/async/discord.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "async/http"
+require "scampi"
+
+module Async
+  module Discord
+  end
+end
+
+Dir.glob("#{__dir__}/discord/**/*.rb").sort.each do |path|
+  require path
+end

data/lib/async/matrix/api/chain.rb

@@ -75,6 +75,13 @@ module Async
           execute("DELETE", query: kwargs, max_retries: max_retries)
         end
 
+        def patch(body = nil, **kwargs)
+          content_type = kwargs.delete(:content_type)
+          max_retries  = kwargs.delete(:max_retries)
+          query        = _extract_query_params(kwargs)
+          execute("PATCH", body: body || kwargs, content_type: content_type, max_retries: max_retries, query: query)
+        end
+
         # ── Chain inspection ───────────────────────────────────────
 
         def to_s
@@ -125,11 +132,12 @@ module Async
 
           path = "/" + segments.map { |s| _encode(s) }.join("/")
 
+          if query && !query.empty?
+            qs = query.map { |k, v| "#{_encode(k.to_s)}=#{_encode(v.to_s)}" }.join("&")
+            path = "#{path}?#{qs}"
+          end
+
           if _binary_route?(segments)
-            if query && !query.empty?
-              qs = query.map { |k, v| "#{_encode(k.to_s)}=#{_encode(v.to_s)}" }.join("&")
-              path = "#{path}?#{qs}"
-            end
             case method
             when "GET"
               @client.media_client.download(path)
@@ -142,10 +150,6 @@ module Async
             retry_opts = max_retries ? {max_retries: max_retries} : {}
             case method
             when "GET"
-              if query && !query.empty?
-                qs = query.map { |k, v| "#{_encode(k.to_s)}=#{_encode(v.to_s)}" }.join("&")
-                path = "#{path}?#{qs}"
-              end
               @client.get(path, **retry_opts)
             when "POST"
               @client.post(path, body || {}, **retry_opts)
@@ -153,6 +157,8 @@ module Async
               @client.put(path, body || {}, **retry_opts)
             when "DELETE"
               @client.request("DELETE", path, nil, **retry_opts)
+            when "PATCH"
+              @client.request("PATCH", path, body || {}, **retry_opts)
             end
           end
         end

data/lib/async/matrix/application_service/config/vivify.rb

@@ -3,6 +3,9 @@
 # Released under the Apache License, Version 2.0.
 # Copyright, 2026, by General Intelligence Systems.
 
+require "bundler/setup"
+require "async/matrix"
+
 module Async
   module Matrix
     module ApplicationService

data/lib/async/matrix/application_service/event.rb

@@ -32,15 +32,12 @@ module Async
 					@membership = data["membership"]
 				end
 
-				# Direct hash access for any content field.
-				def [](key)
-					@data[key.to_s]
-				end
+				def to_h = @data
+        def to_s = @body.to_s
+        def to_str = to_s
 
-				# Returns the raw content hash.
-				def to_h
-					@data
-				end
+				# Direct hash access for any content field.
+				def [](key) = @data[key.to_s]
 
 				# Dynamic access to any content field present in the raw data.
 				def method_missing(name, *args)
@@ -86,15 +83,11 @@ module Async
 				end
 
 				# The JSONSchemer::Schema for this event's type, or nil if unknown.
-				def schema
-					Schema[@type]
-				end
+				def schema = Schema[@type]
 
 				# Validate this event against its schema.
 				# Returns true if valid or if no schema exists (lenient).
-				def valid?
-					Schema.valid?(@raw)
-				end
+				def valid? = Schema.valid?(@raw)
 
 				# Validate this event against its schema.
 				# Raises Schema::ValidationError with detailed errors on failure.
@@ -113,14 +106,10 @@ module Async
 
 				# Content property names defined by the schema for this event type.
 				# @return [Array<String>]
-				def content_properties
-					Schema.content_properties(@type)
-				end
+				def content_properties = Schema.content_properties(@type)
 
 				# Is this a state event? (has a state_key)
-				def state_event?
-					!@state_key.nil?
-				end
+				def state_event? = !@state_key.nil?
 			end
 		end
 	end

data/lib/async/matrix/application_service/server.rb

@@ -119,8 +119,8 @@ module Async
               parse_json(request).then do |body|
                 if body
                   Console.info(self) {
-                    event_count = (body["events"] || []).size
-                    "Transaction #{txn_id}: #{event_count} event(s)"
+                    events = body["events"] || []
+                    "Transaction #{txn_id}: #{events.size} event(s) — #{JSON.generate(events)}"
                   }
 
                   @dispatcher.dispatch_transaction(body)

data/lib/async/matrix/bridge/discord/db/connection.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+require "sequel"
+
+module Async
+  module Matrix
+    module Bridge
+      module Discord
+        module DB
+          # Establishes a Sequel database connection from the bridge config's
+          # database section.
+          #
+          # Supports both SQLite (with foreign keys and WAL mode) and PostgreSQL,
+          # matching the mautrix bridgev2 database config schema.
+          #
+          #   db = Connection.establish(config.database)
+          #   db[:users].all  # => [...]
+          #
+          module Connection
+            SQLITE_TYPE  = "sqlite3-fk-wal"
+            POSTGRES_TYPE = "postgres"
+
+            # Establish a database connection from a config.database section.
+            #
+            # @param database_config [Hash, Vivify] config.database with :type, :uri, :max_open_conns
+            # @return [Sequel::Database]
+            def self.establish(database_config)
+              type = database_config.type || SQLITE_TYPE
+              uri  = database_config.uri  || "sqlite://bridge.db"
+
+              db = case type
+                   when SQLITE_TYPE
+                     connect_sqlite(uri, database_config)
+                   when POSTGRES_TYPE
+                     connect_postgres(uri, database_config)
+                   else
+                     raise ArgumentError, "Unknown database type: #{type.inspect}. Expected #{SQLITE_TYPE.inspect} or #{POSTGRES_TYPE.inspect}."
+                   end
+
+              db
+            end
+
+            class << self
+              private
+
+                def connect_sqlite(uri, config)
+                  # Normalize mautrix-style URIs: "file:bridge.db?..." -> "sqlite://bridge.db"
+                  sequel_uri = if uri.start_with?("file:")
+                                 path = uri.sub(%r{\Afile:}, "").split("?").first
+                                 "sqlite://#{path}"
+                               elsif uri.start_with?("sqlite://")
+                                 uri
+                               else
+                                 "sqlite://#{uri}"
+                               end
+
+                  db = Sequel.connect(sequel_uri, max_connections: max_conns(config))
+                  db.run("PRAGMA foreign_keys = ON")
+                  db.run("PRAGMA journal_mode = WAL")
+                  db
+                end
+
+                def connect_postgres(uri, config)
+                  Sequel.connect(uri, max_connections: max_conns(config))
+                end
+
+                def max_conns(config)
+                  val = config.respond_to?(:max_open_conns) ? config.max_open_conns : nil
+                  val && val > 0 ? val : 5
+                end
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+test do
+  describe "Async::Matrix::Bridge::Discord::DB::Connection" do
+    it "connects to an in-memory SQLite database" do
+      config = Object.new
+      config.define_singleton_method(:type) { "sqlite3-fk-wal" }
+      config.define_singleton_method(:uri)  { "sqlite:/" }
+      config.define_singleton_method(:max_open_conns) { 1 }
+
+      db = Async::Matrix::Bridge::Discord::DB::Connection.establish(config)
+      db.should.be.kind_of Sequel::Database
+      db.database_type.should == :sqlite
+      db.disconnect
+    end
+
+    it "enables foreign keys and WAL on SQLite" do
+      config = Object.new
+      config.define_singleton_method(:type) { "sqlite3-fk-wal" }
+      config.define_singleton_method(:uri)  { "sqlite:/" }
+      config.define_singleton_method(:max_open_conns) { 1 }
+
+      db = Async::Matrix::Bridge::Discord::DB::Connection.establish(config)
+      fk = db["PRAGMA foreign_keys"].first
+      fk[:foreign_keys].should == 1
+      db.disconnect
+    end
+
+    it "normalizes mautrix file: URIs to sequel sqlite:// URIs" do
+      config = Object.new
+      config.define_singleton_method(:type) { "sqlite3-fk-wal" }
+      config.define_singleton_method(:uri)  { "file:test.db?_txlock=immediate" }
+      config.define_singleton_method(:max_open_conns) { 1 }
+
+      # Should not raise — the URI is normalized
+      db = Async::Matrix::Bridge::Discord::DB::Connection.establish(config)
+      db.should.be.kind_of Sequel::Database
+      db.disconnect
+    end
+
+    it "defaults to sqlite with 5 connections when config is empty" do
+      config = Object.new
+      config.define_singleton_method(:type) { nil }
+      config.define_singleton_method(:uri)  { nil }
+      config.define_singleton_method(:max_open_conns) { nil }
+
+      db = Async::Matrix::Bridge::Discord::DB::Connection.establish(config)
+      db.should.be.kind_of Sequel::Database
+      db.disconnect
+    end
+
+    it "raises on unknown database type" do
+      config = Object.new
+      config.define_singleton_method(:type) { "mysql" }
+      config.define_singleton_method(:uri)  { "mysql://localhost/db" }
+      config.define_singleton_method(:max_open_conns) { 1 }
+
+      lambda {
+        Async::Matrix::Bridge::Discord::DB::Connection.establish(config)
+      }.should.raise(ArgumentError)
+    end
+  end
+end