async-matrix 2.1.0 → 3.0.1

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

@@ -22,7 +22,13 @@ module Async
       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
+        Node = Struct.new(
+          :children,
+          :wildcard,
+          :methods,
+          :operation_ids,
+          keyword_init: true,
+        ) do
           def initialize(**)
             super
             self.children ||= {}
@@ -39,34 +45,46 @@ module Async
 
         # 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)
+          new.tap do |tree|
+            Pathname.glob(schema_dir / "*.yaml").each do |path|
+              tree.load_schema(path)
+            end
           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)
+          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
 
@@ -83,25 +101,30 @@ module Async
               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
+          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 = @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}
+          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 method
+          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]}
@@ -112,17 +135,21 @@ module Async
 
         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
+          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

data/lib/async/matrix/api.rb

@@ -54,7 +54,12 @@ module Async
           if name.start_with?("to_")
             super
           else
-            chain.__send__(name, *args, **kwargs, &block)
+            chain.__send__(
+              name,
+              *args,
+              **kwargs,
+              &block
+            )
           end
         end
 

data/lib/async/matrix/app_service_client.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require_relative "client"
+
+module Async
+  module Matrix
+    # A Client that acts AS one of the appservice's users, on one of that user's
+    # devices.
+    #
+    #   client = AppServiceClient.new(config, user_id: "@ada:example.org", device_id: "ABCDEFGHIJ")
+    #   client.upload_keys(device_keys: ...)   # uploaded for Ada's device, not the bot's
+    #
+    # This is double puppeting, and it is the officially intended mechanism
+    # rather than a trick. Identity assertion -- `?user_id=` -- has been in the
+    # application service spec for years; [MSC4326] added `?device_id=` beside
+    # it and is MERGED, so the plain parameter names below are stable spec, not
+    # the unstable `org.matrix.msc3202.device_id` an older implementation would
+    # have sent.
+    #
+    # WHY NOT A TOKEN. Bridges used to get a per-user access token by calling
+    # /login with `m.login.application_service` ([MSC2778]), and that route is
+    # gone on a homeserver fronted by OAuth2 -- it answers
+    # M_APPSERVICE_LOGIN_UNSUPPORTED. [MSC4190], which is also merged, replaced
+    # it: an appservice creates devices directly (`PUT /devices/{deviceId}`) and
+    # then acts as them with these two parameters. No token is ever issued, so
+    # none can expire or need refreshing.
+    #
+    # IT STILL WORKS BEHIND MAS. Synapse checks an as_token against its own
+    # appservice registry before it introspects anything at the authentication
+    # service, so masquerading is unaffected by next-generation auth.
+    #
+    # THE USER MUST BE IN THE REGISTRATION'S NAMESPACE. The homeserver refuses
+    # otherwise -- which is why a double-puppet registration claims a wide user
+    # namespace non-exclusively rather than naming individuals.
+    #
+    # [MSC4326]: https://github.com/matrix-org/matrix-spec-proposals/pull/4326
+    # [MSC4190]: https://github.com/matrix-org/matrix-spec-proposals/pull/4190
+    # [MSC2778]: https://github.com/matrix-org/matrix-spec-proposals/pull/2778
+    class AppServiceClient < Client
+      # @parameter user_id [String] the user to act as. Must match the
+      #   registration's user namespace.
+      # @parameter device_id [String] the device to act as.
+      #
+      #   WITHOUT IT THE REQUEST HAS NO DEVICE, and an appservice request with
+      #   no device cannot upload one-time keys, claim keys or send to-device
+      #   messages -- every call encryption is made of. It is optional only
+      #   because the device has to be CREATED before it can be acted as, and
+      #   that one call is made without it.
+      def initialize(config, user_id:, device_id: nil, **options)
+        super(config, **options)
+
+        @user_id = user_id
+        @device_id = device_id
+      end
+
+      attr_reader :user_id, :device_id
+
+      # NAMED ON EVERY REQUEST, not only the ones that obviously need it. An
+      # appservice request that omits them is not an error: it silently acts as
+      # the registration's sender_localpart, with no device, which is far worse
+      # than a failure because it succeeds.
+      def default_query
+        {user_id: @user_id}.tap do |query|
+          if @device_id
+            query[:device_id] = @device_id
+          end
+        end
+      end
+
+      # A sibling client for another user or device, sharing this one's config
+      # and retry policy.
+      #
+      # One appservice commonly acts for many users, and the alternative --
+      # mutating user_id on a single client -- races itself the moment two
+      # fibers use it, which is exactly what an async bridge does.
+      def as(user_id:, device_id: nil)
+        self.class.new(@config, user_id: user_id, device_id: device_id)
+      end
+
+      # The same user, now on a device: what you call once the device exists.
+      def with_device(device_id)
+        as(user_id: @user_id, device_id: device_id)
+      end
+    end
+  end
+end
+
+__END__
+  describe "Async::Matrix::AppServiceClient" do
+    def config
+      Async::Matrix::Config.new({
+        "homeserver" => {"address" => "http://synapse:8008", "domain" => "example.org"},
+        "appservice" => {"as_token" => "as", "hs_token" => "hs", "bot" => {"username" => "bot"}},
+      })
+    end
+
+    def recording_client(user_id: "@ada:example.org", device_id: "ABCDEFGHIJ")
+      Async::Matrix::Api.reset!
+
+      client = Async::Matrix::AppServiceClient.new(config, user_id: user_id, device_id: device_id)
+      calls = []
+      client.define_singleton_method(:calls) { calls }
+      client.define_singleton_method(:internet) do
+        internet = Object.new
+        internet.define_singleton_method(:call) do |method, url, _headers, _body|
+          calls << [method, url]
+
+          # Shaped like what Client#read_limited consumes: a body that yields
+          # chunks and reports its own length.
+          body = Object.new
+          body.define_singleton_method(:length) { 2 }
+          body.define_singleton_method(:each) { |&block| block.call("{}") }
+          body.define_singleton_method(:close) { nil }
+
+          response = Object.new
+          response.define_singleton_method(:status) { 200 }
+          response.define_singleton_method(:body) { body }
+          response.define_singleton_method(:close) { nil }
+          response
+        end
+        internet
+      end
+      client
+    end
+
+    def last_url(client) = client.calls.last[1]
+
+    it "asserts the user and device on every request" do
+      client = recording_client
+      client.whoami
+
+      last_url(client).should ==
+        "http://synapse:8008/_matrix/client/v3/account/whoami" \
+        "?user_id=%40ada%3Aexample.org&device_id=ABCDEFGHIJ"
+    end
+
+    # Not only on the calls that obviously need it: an appservice request that
+    # omits them silently acts as the sender_localpart, with no device.
+    it "asserts them through the api chain too" do
+      client = recording_client
+      client.joined_members(room_id: "!ops:example.org")
+
+      last_url(client).should.be.include? "user_id=%40ada%3Aexample.org"
+      last_url(client).should.be.include? "device_id=ABCDEFGHIJ"
+    end
+
+    # The chain appends its own query first, so this is the case that catches a
+    # naive "?" concatenation.
+    it "appends to a path that already carries a query" do
+      client = recording_client
+      client.messages(room_id: "!ops:example.org", limit: 10)
+
+      last_url(client).should.be.include? "?dir=b&limit=10&"
+      last_url(client).should.be.include? "user_id=%40ada%3Aexample.org"
+      last_url(client).count("?").should == 1
+    end
+
+    # The device has to be created before it can be acted as, and that one call
+    # is made without a device.
+    it "omits the device when it has none" do
+      client = recording_client(device_id: nil)
+      client.whoami
+
+      last_url(client).should.be.include? "user_id=%40ada%3Aexample.org"
+      last_url(client).should.not.be.include? "device_id"
+    end
+
+    # Overwriting it would mean acting as somebody other than the caller asked
+    # for, which is worse than a failure.
+    it "lets a caller's own parameter win" do
+      client = recording_client
+      client.get("/_matrix/client/v3/account/whoami?user_id=%40bob%3Aexample.org")
+
+      last_url(client).should.be.include? "user_id=%40bob%3Aexample.org"
+      last_url(client).scan("user_id=").length.should == 1
+    end
+
+    it "encodes the punctuation in a user id" do
+      client = recording_client(user_id: "@ada:example.org")
+      client.whoami
+
+      last_url(client).should.be.include? "%40ada%3Aexample.org"
+    end
+
+    # One appservice acts for many users; mutating a shared client would race
+    # itself the moment two fibers used it.
+    it "makes a sibling client for another user" do
+      client = recording_client
+      other = client.as(user_id: "@bob:example.org", device_id: "OTHERDEV")
+
+      other.user_id.should == "@bob:example.org"
+      other.device_id.should == "OTHERDEV"
+      client.user_id.should == "@ada:example.org"
+      other.config.should.be == client.config
+    end
+
+    it "makes a client for the same user on a device" do
+      client = recording_client(device_id: nil)
+      with_device = client.with_device("NEWDEVICE")
+
+      with_device.user_id.should == "@ada:example.org"
+      with_device.device_id.should == "NEWDEVICE"
+    end
+
+    # An ordinary client asserts nothing: a user's own token already says who
+    # the request is for.
+    it "is the only client that asserts anything" do
+      Async::Matrix::Client.new(config).default_query.should == {}
+    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