async-matrix 0.1.2 → 1.0.0

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

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+require "async/matrix"
+require "yaml"
+require "pathname"
+
+module Async
+  module Matrix
+    module Api
+      # A trie of valid Matrix API paths, built from OpenAPI 3.1.0 YAML schemas.
+      #
+      # Each leaf node stores the set of HTTP methods valid at that path.
+      # Template segments like {roomId} become wildcard nodes that match any value.
+      #
+      # Example:
+      #   tree = PathTree.load
+      #   tree.match(["_matrix", "client", "v3", "rooms", "!abc:ex.com", "ban"], "POST")
+      #   # => { valid: true, operation_id: "ban", methods: ["post"] }
+      #
+      class PathTree
+        SCHEMA_DIR = Pathname.new(File.expand_path("../../../../data/matrix-spec/api/client-server", __dir__))
+
+        Node = Struct.new(:children, :wildcard, :methods, :operation_ids, keyword_init: true) do
+          def initialize(**)
+            super
+            self.children ||= {}
+            self.methods ||= []
+            self.operation_ids ||= {}
+          end
+        end
+
+        attr_reader :root
+
+        def initialize
+          @root = Node.new
+        end
+
+        # Load all OpenAPI schemas from data/ and build the tree.
+        def self.load(schema_dir: SCHEMA_DIR)
+          tree = new
+          Pathname.glob(schema_dir / "*.yaml").each do |path|
+            tree.load_schema(path)
+          end
+          tree
+        end
+
+        # Parse a single OpenAPI YAML file and insert its paths into the tree.
+        def load_schema(path)
+          doc = YAML.safe_load(File.read(path), permitted_classes: [Symbol], aliases: true)
+          return unless doc.is_a?(Hash)
+
+          base_path = extract_base_path(doc)
+          paths = doc["paths"]
+          return unless paths.is_a?(Hash)
+
+          paths.each do |path_template, methods_hash|
+            next unless methods_hash.is_a?(Hash)
+
+            # Build full path: basePath + path_template
+            full_path = "#{base_path}#{path_template.strip}"
+            segments = full_path.split("/").reject(&:empty?)
+
+            methods_hash.each do |method, operation|
+              next unless %w[get post put delete patch head].include?(method)
+              operation_id = operation.is_a?(Hash) ? operation["operationId"] : nil
+              insert(segments, method, operation_id)
+            end
+          end
+        end
+
+        # Insert a path (as array of segments) with an HTTP method into the trie.
+        def insert(segments, method, operation_id = nil)
+          node = @root
+          segments.each do |segment|
+            if segment.start_with?("{") && segment.end_with?("}")
+              # Wildcard segment — matches any value
+              node.wildcard ||= Node.new
+              node = node.wildcard
+            else
+              node.children[segment] ||= Node.new
+              node = node.children[segment]
+            end
+          end
+          node.methods << method.downcase unless node.methods.include?(method.downcase)
+          node.operation_ids[method.downcase] = operation_id if operation_id
+        end
+
+        # Match a concrete path (array of segments) against the trie.
+        # Returns a result hash.
+        def match(segments, method = nil)
+          node = @root
+          segments.each do |segment|
+            if node.children.key?(segment)
+              node = node.children[segment]
+            elsif node.wildcard
+              node = node.wildcard
+            else
+              return {valid: false, methods: [], operation_id: nil}
+            end
+          end
+
+          if method
+            method_down = method.downcase
+            valid = node.methods.include?(method_down)
+            {valid: valid, methods: node.methods, operation_id: node.operation_ids[method_down]}
+          else
+            {valid: node.methods.any?, methods: node.methods, operation_id: nil}
+          end
+        end
+
+        private
+
+        def extract_base_path(doc)
+          servers = doc["servers"]
+          return "" unless servers.is_a?(Array) && servers.first.is_a?(Hash)
+
+          server = servers.first
+          variables = server["variables"] || {}
+          base_path_var = variables["basePath"]
+          return "" unless base_path_var.is_a?(Hash)
+
+          base_path_var["default"] || ""
+        end
+      end
+    end
+  end
+end
+
+test do
+  describe "Async::Matrix::Api::PathTree" do
+    def make_tree
+      tree = Async::Matrix::Api::PathTree.new
+      # Simulate a few endpoints manually
+      tree.insert(%w[_matrix client v3 account whoami], "get", "getAccountWhoami")
+      tree.insert(%w[_matrix client v3 createRoom], "post", "createRoom")
+      tree.insert(%w[_matrix client v3 rooms {roomId} ban], "post", "ban")
+      tree.insert(%w[_matrix client v3 rooms {roomId} unban], "post", "unban")
+      tree.insert(%w[_matrix client v3 rooms {roomId} state {eventType} {stateKey}], "get", "getRoomStateWithKey")
+      tree.insert(%w[_matrix client v3 rooms {roomId} state {eventType} {stateKey}], "put", "setRoomStateWithKey")
+      tree.insert(%w[_matrix client v3 rooms {roomId} messages], "get", "getRoomMessages")
+      tree.insert(%w[_matrix client v3 profile {userId} displayname], "get", "getDisplayName")
+      tree.insert(%w[_matrix client v3 profile {userId} displayname], "put", "setDisplayName")
+      tree
+    end
+
+    it "matches a simple path" do
+      tree = make_tree
+      result = tree.match(%w[_matrix client v3 account whoami], "GET")
+      result[:valid].should == true
+      result[:operation_id].should == "getAccountWhoami"
+    end
+
+    it "rejects unknown paths" do
+      tree = make_tree
+      result = tree.match(%w[_matrix client v3 account foobar], "GET")
+      result[:valid].should == false
+    end
+
+    it "matches wildcard segments" do
+      tree = make_tree
+      result = tree.match(%w[_matrix client v3 rooms !abc:ex.com ban], "POST")
+      result[:valid].should == true
+      result[:operation_id].should == "ban"
+    end
+
+    it "matches deep wildcard paths" do
+      tree = make_tree
+      result = tree.match(%w[_matrix client v3 rooms !abc:ex.com state m.room.name some_key], "GET")
+      result[:valid].should == true
+      result[:operation_id].should == "getRoomStateWithKey"
+    end
+
+    it "rejects wrong HTTP method" do
+      tree = make_tree
+      result = tree.match(%w[_matrix client v3 account whoami], "POST")
+      result[:valid].should == false
+    end
+
+    it "reports available methods" do
+      tree = make_tree
+      result = tree.match(%w[_matrix client v3 profile @user:ex.com displayname])
+      result[:valid].should == true
+      result[:methods].should.include "get"
+      result[:methods].should.include "put"
+    end
+
+    it "loads from real schema files" do
+      skip "schemas not present" unless Async::Matrix::Api::PathTree::SCHEMA_DIR.exist?
+      tree = Async::Matrix::Api::PathTree.load
+      # createRoom should exist
+      result = tree.match(%w[_matrix client v3 createRoom], "POST")
+      result[:valid].should == true
+      # rooms/{id}/ban should exist
+      result = tree.match(%w[_matrix client v3 rooms !test:ex.com ban], "POST")
+      result[:valid].should == true
+      # sync should exist
+      result = tree.match(%w[_matrix client v3 sync], "GET")
+      result[:valid].should == true
+      # nonsense should not
+      result = tree.match(%w[_matrix client v3 totallyFake], "GET")
+      result[:valid].should == false
+    end
+  end
+end

data/lib/async/matrix/api.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+require "async/matrix"
+
+module Async
+  module Matrix
+    # Runtime-generated Matrix Client-Server API built from official OpenAPI schemas.
+    #
+    # Loads the OpenAPI 3.1.0 YAML files from data/matrix-spec/api/client-server/
+    # at require-time and builds a PathTree trie of all valid endpoints. API calls
+    # are constructed via StringBuilder method chains, validated against the tree,
+    # and terminated by .get(), .post(), .put(), or .delete().
+    #
+    # Usage:
+    #   # Via Client:
+    #   client.api.account.whoami.get
+    #   client.api.createRoom.post(name: "Pub", preset: "public_chat")
+    #   client.api.rooms("!room:ex.com").ban.post(user_id: "@bad:ex.com")
+    #   client.api.rooms("!room:ex.com").messages.get(dir: "b", limit: 10)
+    #
+    #   # Standalone (for inspection):
+    #   gateway = Async::Matrix::Api::Gateway.new(client)
+    #   chain = gateway.chain
+    #   chain.rooms("!room:ex.com").state("m.room.name", "").get
+    #
+    module Api
+      # The shared PathTree instance, loaded once from the bundled schemas.
+      def self.path_tree
+        @path_tree ||= PathTree.load
+      end
+
+      # Reset the cached path tree (useful for testing or reloading schemas).
+      def self.reset!
+        @path_tree = nil
+      end
+
+      # Gateway produces Chain instances bound to a specific Client.
+      # Each call to a method on the Gateway starts a new chain.
+      class Gateway
+        def initialize(client, prefix: %w[_matrix client v3])
+          @client  = client
+          @prefix  = prefix
+        end
+
+        # Start a fresh chain. Every method call on the gateway creates
+        # a new chain so chains are never reused.
+        def chain
+          Chain.new(client: @client, path_tree: Api.path_tree, prefix: @prefix)
+        end
+
+        # Forward all unknown methods to a fresh chain, starting the path.
+        def method_missing(name, *args, **kwargs, &block)
+          if name.start_with?("to_")
+            super
+          else
+            chain.__send__(name, *args, **kwargs, &block)
+          end
+        end
+
+        def respond_to_missing?(name, include_private = false)
+          !name.start_with?("to_") || super
+        end
+
+        def inspect
+          "#<#{self.class} prefix=/#{@prefix.join("/")}>"
+        end
+      end
+    end
+
+  end
+end
+
+test do
+  describe "Async::Matrix::Api::Gateway" do
+    # Stub client that records calls instead of making HTTP requests.
+    StubClient = Struct.new(:calls) do
+      def initialize
+        super([])
+      end
+
+      def get(path, max_retries: nil)
+        calls << [:get, path, {max_retries: max_retries}]
+        {"stub" => true}
+      end
+
+      def post(path, body = {}, max_retries: nil)
+        calls << [:post, path, body, {max_retries: max_retries}]
+        {"stub" => true}
+      end
+
+      def put(path, body = {}, max_retries: nil)
+        calls << [:put, path, body, {max_retries: max_retries}]
+        {"stub" => true}
+      end
+
+      def request(method, path, body = nil, max_retries: nil)
+        calls << [method.downcase.to_sym, path, body, {max_retries: max_retries}]
+        {"stub" => true}
+      end
+    end
+
+    def make_gateway
+      client = StubClient.new
+      # Build a small tree manually for deterministic tests
+      tree = Async::Matrix::Api::PathTree.new
+      tree.insert(%w[_matrix client v3 account whoami], "get")
+      tree.insert(%w[_matrix client v3 createRoom], "post")
+      tree.insert(%w[_matrix client v3 rooms {roomId} ban], "post")
+      tree.insert(%w[_matrix client v3 rooms {roomId} messages], "get")
+      tree.insert(%w[_matrix client v3 rooms {roomId} send {eventType} {txnId}], "put")
+      tree.insert(%w[_matrix client v3 profile {userId} displayname], "put")
+      tree.insert(%w[_matrix client v3 join {roomIdOrAlias}], "post")
+      tree.insert(%w[_matrix client v3 rooms {roomId} leave], "post")
+
+      # Inject our test tree
+      Async::Matrix::Api.instance_variable_set(:@path_tree, tree)
+
+      gateway = Async::Matrix::Api::Gateway.new(client)
+      [gateway, client]
+    end
+
+    it "GET /account/whoami" do
+      gw, client = make_gateway
+      gw.account.whoami.get
+      client.calls.last[0].should == :get
+      client.calls.last[1].should == "/_matrix/client/v3/account/whoami"
+    end
+
+    it "POST /createRoom with body" do
+      gw, client = make_gateway
+      gw.createRoom.post(name: "Pub", preset: "public_chat")
+      client.calls.last[0].should == :post
+      client.calls.last[1].should == "/_matrix/client/v3/createRoom"
+      client.calls.last[2].should == {name: "Pub", preset: "public_chat"}
+    end
+
+    it "POST /rooms/{roomId}/ban with body" do
+      gw, client = make_gateway
+      gw.rooms("!abc:ex.com").ban.post(user_id: "@bad:ex.com", reason: "spam")
+      client.calls.last[0].should == :post
+      client.calls.last[1].should == "/_matrix/client/v3/rooms/%21abc%3Aex.com/ban"
+      client.calls.last[2].should == {user_id: "@bad:ex.com", reason: "spam"}
+    end
+
+    it "GET /rooms/{roomId}/messages with query params" do
+      gw, client = make_gateway
+      gw.rooms("!abc:ex.com").messages.get(dir: "b", limit: 10)
+      call = client.calls.last
+      call[0].should == :get
+      call[1].should.include "/_matrix/client/v3/rooms/%21abc%3Aex.com/messages?"
+      call[1].should.include "dir=b"
+      call[1].should.include "limit=10"
+    end
+
+    it "PUT /rooms/{roomId}/send/{eventType}/{txnId}" do
+      gw, client = make_gateway
+      gw.rooms("!abc:ex.com").send("m.room.message", "txn-1").put(msgtype: "m.text", body: "hi")
+      call = client.calls.last
+      call[0].should == :put
+      call[1].should == "/_matrix/client/v3/rooms/%21abc%3Aex.com/send/m.room.message/txn-1"
+      call[2].should == {msgtype: "m.text", body: "hi"}
+    end
+
+    it "PUT /profile/{userId}/displayname" do
+      gw, client = make_gateway
+      gw.profile("@user:ex.com").displayname.put(displayname: "Bob")
+      call = client.calls.last
+      call[0].should == :put
+      call[1].should == "/_matrix/client/v3/profile/%40user%3Aex.com/displayname"
+      call[2].should == {displayname: "Bob"}
+    end
+
+    it "POST /join/{roomIdOrAlias}" do
+      gw, client = make_gateway
+      gw.join("!abc:ex.com").post
+      call = client.calls.last
+      call[0].should == :post
+      call[1].should == "/_matrix/client/v3/join/%21abc%3Aex.com"
+    end
+
+    it "raises InvalidEndpointError for unknown path" do
+      gw, _ = make_gateway
+      lambda { gw.totally.bogus.endpoint.get }.should.raise Async::Matrix::InvalidEndpointError
+    end
+
+    it "raises InvalidEndpointError for wrong method" do
+      gw, _ = make_gateway
+      lambda { gw.account.whoami.post }.should.raise Async::Matrix::InvalidEndpointError
+    end
+
+    it "each gateway method call starts a fresh chain" do
+      gw, client = make_gateway
+      gw.account.whoami.get
+      gw.createRoom.post(name: "test")
+      client.calls.length.should == 2
+      client.calls[0][1].should == "/_matrix/client/v3/account/whoami"
+      client.calls[1][1].should == "/_matrix/client/v3/createRoom"
+    end
+  end
+end

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

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+require "console"
+require "async/matrix"
+
+module Async
+  module Matrix
+    module ApplicationService
+      # DSL wrapper that pairs a Client with event handlers.
+      #
+      # A Bot produces handler objects that conform to the Dispatcher's
+      # duck-type contract (#event_types, #call). Register a bot on a
+      # Server (or Dispatcher) the same way you would register a plain handler.
+      #
+      #   bot = Bot.new(client) do
+      #     on "m.room.member" do |event|
+      #       join_room(event.room_id) if event.content.membership == "invite"
+      #     end
+      #
+      #     on "m.room.message", msgtype: "m.text", not_from: :self do |event|
+      #       send_notice event.room_id, "Echo: #{event.content.body}"
+      #     end
+      #   end
+      #
+      #   server.register(bot)
+      #
+      class Bot
+        attr_reader :client, :handlers
+
+        def initialize(client, &block)
+          @client   = client
+          @handlers = []
+
+          instance_eval(&block) if block
+        end
+
+        # Register a handler block for one or more event types.
+        #
+        # Filters (all optional):
+        #   msgtype:  — only dispatch when content.msgtype matches (e.g. "m.text")
+        #   not_from: — :self skips events sent by this bot's own MXID
+        #
+        def on(*event_types, msgtype: nil, not_from: nil, &block)
+          raise ArgumentError, "on requires at least one event type" if event_types.empty?
+          raise ArgumentError, "on requires a block" unless block
+
+          handler = Handler.new(
+            bot:         self,
+            event_types: event_types.flatten,
+            msgtype:     msgtype,
+            not_from:    not_from,
+            block:       block
+          )
+
+          @handlers << handler
+          handler
+        end
+
+        # Internal handler object produced by the #on DSL method.
+        # Conforms to the Dispatcher duck-type: #event_types, #call.
+        class Handler
+          attr_reader :event_types
+
+          def initialize(bot:, event_types:, msgtype:, not_from:, block:)
+            @bot         = bot
+            @event_types = event_types
+            @msgtype     = msgtype
+            @not_from    = not_from
+            @block       = block
+          end
+
+          def call(event)
+            return if @msgtype  && event.content&.msgtype != @msgtype
+            return if @not_from == :self && event.sender == @bot.client.config.bot_mxid
+
+            # Execute the block in a context that has helper methods
+            Context.new(@bot.client).execute(event, &@block)
+          end
+        end
+
+        # Execution context for handler blocks.
+        # Provides helper methods so blocks can call send_notice, join_room, etc.
+        # directly without holding a reference to the client.
+        class Context
+          def initialize(client)
+            @client = client
+          end
+
+          def execute(event, &block)
+            @event = event
+            instance_exec(event, &block)
+          end
+
+          def send_text(room_id, text)
+            @client.send_text(room_id, text)
+          end
+
+          def send_html(room_id, html, plaintext = nil)
+            @client.send_html(room_id, html, plaintext)
+          end
+
+          def send_notice(room_id, text)
+            @client.send_notice(room_id, text)
+          end
+
+          def join_room(room_id)
+            @client.join_room(room_id)
+          end
+
+          def leave_room(room_id)
+            @client.leave_room(room_id)
+          end
+
+          def set_display_name(name, user_id = nil)
+            @client.set_display_name(name, user_id)
+          end
+
+          def client
+            @client
+          end
+        end
+      end
+    end
+  end
+end
+
+test do
+  describe "Async::Matrix::ApplicationService::Bot" do
+    def make_config
+      Async::Matrix::ApplicationService::Config.new({
+        "homeserver" => { "address" => "http://localhost:8008", "domain" => "localhost" },
+        "appservice" => { "as_token" => "token_secret", "hs_token" => "hs_secret", "bot" => { "username" => "bot" } }
+      })
+    end
+
+    def make_event(type:, sender: "@user:localhost", msgtype: nil, body: nil, membership: nil, state_key: nil)
+      data = {"type" => type, "sender" => sender, "room_id" => "!room:localhost"}
+      content = {}
+      content["msgtype"]    = msgtype    if msgtype
+      content["body"]       = body       if body
+      content["membership"] = membership if membership
+      data["state_key"] = state_key if state_key
+      data["content"] = content
+      Async::Matrix::ApplicationService::Event.new(data)
+    end
+
+    it "registers handlers via the on DSL" do
+      config = make_config
+      client = Async::Matrix::Client.new(config)
+
+      bot = Async::Matrix::ApplicationService::Bot.new(client) do
+        on "m.room.message" do |event|
+          # no-op
+        end
+      end
+
+      bot.handlers.length.should == 1
+      bot.handlers.first.event_types.should == ["m.room.message"]
+    end
+
+    it "registers multiple event types on a single handler" do
+      config = make_config
+      client = Async::Matrix::Client.new(config)
+
+      bot = Async::Matrix::ApplicationService::Bot.new(client) do
+        on "m.room.message", "m.room.member" do |event|
+          # no-op
+        end
+      end
+
+      bot.handlers.first.event_types.should == ["m.room.message", "m.room.member"]
+    end
+
+    it "filters by msgtype" do
+      config = make_config
+      client = Async::Matrix::Client.new(config)
+      received = []
+
+      bot = Async::Matrix::ApplicationService::Bot.new(client) do
+        on "m.room.message", msgtype: "m.text" do |event|
+          received << event.content.body
+        end
+      end
+
+      handler = bot.handlers.first
+      handler.call(make_event(type: "m.room.message", msgtype: "m.text", body: "hello"))
+      handler.call(make_event(type: "m.room.message", msgtype: "m.notice", body: "ignored"))
+
+      received.should == ["hello"]
+    end
+
+    it "filters out self with not_from: :self" do
+      config = make_config
+      client = Async::Matrix::Client.new(config)
+      received = []
+
+      bot = Async::Matrix::ApplicationService::Bot.new(client) do
+        on "m.room.message", not_from: :self do |event|
+          received << event.content.body
+        end
+      end
+
+      handler = bot.handlers.first
+      handler.call(make_event(type: "m.room.message", sender: "@user:localhost", msgtype: "m.text", body: "yes"))
+      handler.call(make_event(type: "m.room.message", sender: "@bot:localhost", msgtype: "m.text", body: "no"))
+
+      received.should == ["yes"]
+    end
+
+    it "raises if on is called without event types" do
+      config = make_config
+      client = Async::Matrix::Client.new(config)
+
+      lambda {
+        Async::Matrix::ApplicationService::Bot.new(client) do
+          on do |event|; end
+        end
+      }.should.raise(ArgumentError)
+    end
+
+    it "raises if on is called without a block" do
+      config = make_config
+      client = Async::Matrix::Client.new(config)
+
+      lambda {
+        bot = Async::Matrix::ApplicationService::Bot.new(client)
+        bot.on "m.room.message"
+      }.should.raise(ArgumentError)
+    end
+  end
+end

data/lib/async/matrix/application_service/config/schema/analytics.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "analytics.json",
+  "description": "Analytics/telemetry settings. Maps to mautrix bridgev2/bridgeconfig.AnalyticsConfig.",
+  "type": "object",
+  "properties": {
+    "token": {
+      "type": "string",
+      "description": "Analytics token for the telemetry backend."
+    },
+    "url": {
+      "type": "string",
+      "description": "URL of the analytics/telemetry endpoint."
+    },
+    "user_id": {
+      "type": "string",
+      "description": "User ID to associate with analytics events."
+    }
+  },
+  "additionalProperties": false
+}