async-matrix 3.0.0-arm-linux-musl

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+module Async
+  module Matrix
+    module Api
+      # StringBuilder concat handler that renders a method chain into URL path segments.
+      #
+      # Convention:
+      #   - Bare methods become path segments:       .account.whoami -> ["account", "whoami"]
+      #   - Methods with args inject the arg as a path segment after the method name:
+      #       .rooms("!abc:ex.com") -> ["rooms", "!abc:ex.com"]
+      #   - .call("literal") injects a raw path segment:
+      #       .("m.room.message") -> ["m.room.message"]
+      #
+      # The handler returns an array of raw (unencoded) segments.
+      # URL-encoding is applied later when constructing the final URL.
+      #
+      class Concat
+        def self.call(buffer)
+          new(buffer).segments
+        end
+
+        def initialize(buffer)
+          if buffer.respond_to?(:to_a)
+            @buffer = buffer.to_a
+          else
+            @buffer = buffer
+          end
+        end
+
+        def segments
+          [].tap do |result|
+            @buffer.each do |entry|
+              case entry
+              when Symbol
+                # :slash, :dash -- ignore in URL context
+                next
+              when Array
+                name, args = entry
+                unless name.is_a?(String)
+                  next
+                end
+
+                if args.nil? || args.empty?
+                  # Bare method -> path segment
+                  result << name
+                else
+                  # Method with args -> method name as segment, then each arg as segment
+                  result << name
+                  args.each do |arg|
+                    if arg.is_a?(Hash)
+                      next
+                    end # kwargs are not path segments
+                    result << arg.to_s
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+__END__
+  require "string_builder"
+
+  describe "Async::Matrix::Api::Concat" do
+    it "converts bare methods to path segments" do
+      sb = StringBuilder.new
+      sb.account.whoami
+      segments = Async::Matrix::Api::Concat.call(sb)
+      segments.should == %w[account whoami]
+    end
+
+    it "converts methods with args to segment + arg" do
+      sb = StringBuilder.new
+      sb.rooms("!abc:ex.com").ban
+      segments = Async::Matrix::Api::Concat.call(sb)
+      segments.should == %w[rooms !abc:ex.com ban]
+    end
+
+    it "handles methods with multiple args" do
+      sb = StringBuilder.new
+      sb.rooms("!abc:ex.com").state("m.room.name", "some_key")
+      segments = Async::Matrix::Api::Concat.call(sb)
+      segments.should == %w[rooms !abc:ex.com state m.room.name some_key]
+    end
+
+    it "handles deep paths" do
+      sb = StringBuilder.new
+      sb.rooms("!abc:ex.com").state("m.room.name", "")
+      segments = Async::Matrix::Api::Concat.call(sb)
+      segments.should == ["rooms", "!abc:ex.com", "state", "m.room.name", ""]
+    end
+
+    it "ignores kwargs in segments" do
+      sb = StringBuilder.new
+      sb.account.whoami
+      segments = Async::Matrix::Api::Concat.call(sb)
+      segments.should == %w[account whoami]
+    end
+  end

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

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+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)
+          new.tap do |tree|
+            Pathname.glob(schema_dir / "*.yaml").each do |path|
+              tree.load_schema(path)
+            end
+          end
+        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)
+          if doc.is_a?(Hash)
+            base_path = extract_base_path(doc)
+            paths = doc["paths"]
+            if paths.is_a?(Hash)
+              paths.each do |path_template, methods_hash|
+                unless methods_hash.is_a?(Hash)
+                  next
+                end
+
+                # 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|
+                  unless %w[get post put delete patch head].include?(method)
+                    next
+                  end
+                  if operation.is_a?(Hash)
+                    operation_id = operation["operationId"]
+                  else
+                    operation_id = nil
+                  end
+                  insert(segments, method, operation_id)
+                end
+              end
+            else
+              nil
+            end
+          else
+            nil
+          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
+          unless node.methods.include?(method.downcase)
+            node.methods << method.downcase
+          end
+          if operation_id
+            node.operation_ids[method.downcase] = operation_id
+          end
+        end
+
+        # Match a concrete path (array of segments) against the trie.
+        # Returns a result hash.
+        def match(segments, method = nil)
+          node = segments.inject(@root) do |current, segment|
+            if current.nil?
+              nil
+            elsif current.children.key?(segment)
+              current.children[segment]
+            elsif current.wildcard
+              current.wildcard
+            end
+          end
+
+          if node.nil?
+            {valid: false, methods: [], operation_id: nil}
+          elsif 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"]
+            if servers.is_a?(Array) && servers.first.is_a?(Hash)
+              server = servers.first
+              variables = server["variables"] || {}
+              base_path_var = variables["basePath"]
+              if base_path_var.is_a?(Hash)
+                base_path_var["default"] || ""
+              else
+                ""
+              end
+            else
+              ""
+            end
+          end
+      end
+    end
+  end
+end
+
+__END__
+  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

data/lib/async/matrix/api.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+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
+
+__END__
+  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

data/lib/async/matrix/auth_error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+# Async::Matrix::Error is this class's superclass, so it has to exist before
+# this file finishes loading — the glob in async/matrix.rb sorts
+# alphabetically and would otherwise get here first.
+require_relative "error"
+
+module Async
+  module Matrix
+    class AuthError < Error; end
+  end
+end
+
+__END__
+  it "AuthError inherits from Error" do
+    Async::Matrix::AuthError.new("M_FORBIDDEN", "denied").should.be.kind_of Async::Matrix::Error
+  end

data/lib/async/matrix/bad_json_error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+# Async::Matrix::Error is this class's superclass, so it has to exist before
+# this file finishes loading — the glob in async/matrix.rb sorts
+# alphabetically and would otherwise get here first.
+require_relative "error"
+
+module Async
+  module Matrix
+    class BadJsonError < Error; end
+  end
+end
+
+__END__
+  it "BadJsonError inherits from Error" do
+    Async::Matrix::BadJsonError.new("M_BAD_JSON", "invalid").should.be.kind_of Async::Matrix::Error
+  end