async-matrix 2.0.1 → 3.0.0

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/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

data/lib/async/matrix/client.rb

@@ -72,7 +72,7 @@ module Async
           msgtype:        "m.text",
           body:           plaintext || html.gsub(/<[^>]+>/, ""),
           format:         "org.matrix.custom.html",
-          formatted_body: html
+          formatted_body: html,
         }
         send_message_event(room_id, "m.room.message", content)
       end
@@ -98,7 +98,7 @@ module Async
         uid = user_id || @config.bot_mxid
         put(
           "#{CLIENT_PREFIX}/profile/#{encode(uid)}/displayname",
-          {displayname: name}
+          {displayname: name},
         )
       end
 
@@ -151,15 +151,30 @@ module Async
       end
 
       def get(path, max_retries: nil)
-        request("GET", path, nil, max_retries: max_retries)
+        request(
+          "GET",
+          path,
+          nil,
+          max_retries: max_retries,
+        )
       end
 
       def put(path, body = {}, max_retries: nil)
-        request("PUT", path, body, max_retries: max_retries)
+        request(
+          "PUT",
+          path,
+          body,
+          max_retries: max_retries,
+        )
       end
 
       def post(path, body = {}, max_retries: nil)
-        request("POST", path, body, max_retries: max_retries)
+        request(
+          "POST",
+          path,
+          body,
+          max_retries: max_retries,
+        )
       end
 
       def close
@@ -171,51 +186,67 @@ module Async
 
       private
 
-      def internet
-        @internet ||= Async::HTTP::Internet.new
-      end
-
-      def request(method, path, body = nil, max_retries: nil)
-        url = "#{@base}#{path}"
-        json_body = body ? JSON.generate(body) : nil
-        effective_max_retries = max_retries || @max_retries
-
-        Console.debug(self) { "#{method} #{path}" }
-
-        attempt = 0
-        loop do
-          response = internet.call(method, url, @headers, json_body)
-          status   = response.status
+        def internet
+          @internet ||= Async::HTTP::Internet.new
+        end
 
-          if (200..299).cover?(status)
-            payload = read_limited(response, @response_size_limit)
-            return payload && !payload.empty? ? JSON.parse(payload) : {}
+        def request(method, path, body = nil, max_retries: nil)
+          url = "#{@base}#{path}"
+          if body
+            json_body = JSON.generate(body)
+          else
+            json_body = nil
           end
+          effective_max_retries = max_retries || @max_retries
 
-          attempt += 1
+          Console.debug(self) { "#{method} #{path}" }
 
-          if attempt <= effective_max_retries && retryable_status?(status)
-            delay = compute_retry_delay(status, response, attempt)
-            Console.warn(self) {
-              "#{method} #{path} returned #{status}, retry #{attempt}/#{effective_max_retries} in #{delay.round(2)}s"
-            }
-            response.close if response.respond_to?(:close)
-            sleep(delay)
-            next
+          attempt = 0
+          loop do
+            response = internet.call(
+              method,
+              url,
+              @headers,
+              json_body,
+            )
+            status   = response.status
+
+            if (200..299).cover?(status)
+              payload = read_limited(response, @response_size_limit)
+
+              if payload && !payload.empty?
+                break JSON.parse(payload)
+              else
+                break {}
+              end
+            end
+
+            attempt += 1
+
+            if attempt <= effective_max_retries && retryable_status?(status)
+              delay = compute_retry_delay(status, response, attempt)
+              Console.warn(self) {
+                "#{method} #{path} returned #{status}, retry #{attempt}/#{effective_max_retries} in #{delay.round(2)}s"
+              }
+              if response.respond_to?(:close)
+                response.close
+              end
+              sleep(delay)
+              next
+            end
+
+            payload = read_limited(response, @error_response_size_limit)
+            parsed = ErrorResponse.new(
+              begin; JSON.parse(payload); rescue; {} end,
+            )
+            Console.error(self) { "Matrix API #{status}: #{parsed.errcode} — #{parsed.error}" }
+            raise HomeserverError.new(
+              parsed.errcode || "UNKNOWN",
+              parsed.error || payload.to_s[0..200],
+              status: status,
+            )
           end
-
-          payload = read_limited(response, @error_response_size_limit)
-          parsed = ApplicationService::ErrorResponse.new(
-            begin; JSON.parse(payload); rescue; {} end
-          )
-          Console.error(self) { "Matrix API #{status}: #{parsed.errcode} — #{parsed.error}" }
-          raise HomeserverError.new(
-            parsed.errcode || "UNKNOWN",
-            parsed.error || payload.to_s[0..200],
-            status: status
-          )
         end
-      end
 
       # ── Response size limiting ──────────────────────────────────
 
@@ -226,46 +257,45 @@ module Async
       # @param response [Protocol::HTTP::Response] the HTTP response
       # @param limit [Integer] maximum allowed body size in bytes
       # @return [String, nil] the response body, or nil if empty
-      def read_limited(response, limit)
-        body = response.body
-        return nil unless body
-
-        # Fast path: reject immediately if Content-Length exceeds limit
-        if body.respond_to?(:length) && body.length && body.length > limit
-          body.close
-          raise ResponseTooLargeError.new(
-            "M_TOO_LARGE",
-            "Response Content-Length #{body.length} bytes exceeds limit of #{limit} bytes"
-          )
-        end
-
-        # Streaming read with enforcement
-        buffer = String.new(encoding: Encoding::BINARY)
-        body.each do |chunk|
-          buffer << chunk
-          if buffer.bytesize > limit
-            body.close
-            raise ResponseTooLargeError.new(
-              "M_TOO_LARGE",
-              "Response body exceeds limit of #{limit} bytes"
-            )
+        def read_limited(response, limit)
+          body = response.body
+          if body
+            if body.respond_to?(:length) && body.length && body.length > limit
+              body.close
+              raise ResponseTooLargeError.new(
+                "M_TOO_LARGE",
+                "Response Content-Length #{body.length} bytes exceeds limit of #{limit} bytes",
+              )
+            end
+            buffer = String.new(encoding: Encoding::BINARY)
+            body.each do |chunk|
+              buffer << chunk
+              if buffer.bytesize > limit
+                body.close
+                raise ResponseTooLargeError.new(
+                  "M_TOO_LARGE",
+                  "Response body exceeds limit of #{limit} bytes",
+                )
+              end
+            end
+            buffer.empty? ? nil : buffer
+          else
+            nil
           end
         end
-        buffer.empty? ? nil : buffer
-      end
 
       # ── Retry logic ─────────────────────────────────────────────
 
       # Whether the given HTTP status code should trigger a retry.
       # 429 is only retried if @ignore_rate_limit is false.
       # 502/503/504 are always retried.
-      def retryable_status?(status)
-        if status == RATE_LIMIT_STATUS
-          !@ignore_rate_limit
-        else
-          GATEWAY_ERROR_STATUSES.include?(status)
+        def retryable_status?(status)
+          if status == RATE_LIMIT_STATUS
+            !@ignore_rate_limit
+          else
+            GATEWAY_ERROR_STATUSES.include?(status)
+          end
         end
-      end
 
       # Compute the delay before the next retry attempt.
       #
@@ -276,47 +306,49 @@ module Async
       # For 502/503/504 (gateway errors): exponential backoff with full jitter.
       # Full jitter means rand(0..calculated), which is the AWS-recommended
       # approach to avoid thundering herd on shared homeservers.
-      def compute_retry_delay(status, response, attempt)
-        if status == RATE_LIMIT_STATUS
-          server_delay = parse_retry_after(response)
-          delay = server_delay || exponential_delay(attempt)
-          [delay, @max_retry_delay].min
-        else
-          calculated = exponential_delay(attempt)
-          rand(0.0..[calculated, @max_retry_delay].min)
+        def compute_retry_delay(status, response, attempt)
+          if status == RATE_LIMIT_STATUS
+            server_delay = parse_retry_after(response)
+            delay = server_delay || exponential_delay(attempt)
+            [delay, @max_retry_delay].min
+          else
+            calculated = exponential_delay(attempt)
+            rand(0.0..[calculated, @max_retry_delay].min)
+          end
         end
-      end
 
       # Base * 2^(attempt-1): 0.5, 1.0, 2.0, 4.0, ...
-      def exponential_delay(attempt)
-        @retry_base_delay * (2 ** (attempt - 1))
-      end
+        def exponential_delay(attempt)
+          @retry_base_delay * (2 ** (attempt - 1))
+        end
 
       # Parse the Retry-After header. Supports both delta-seconds ("120")
       # and HTTP-date ("Fri, 31 Dec 2026 23:59:59 GMT") formats per RFC 9110.
       # Returns seconds to wait as a Float, or nil if absent/unparseable.
-      def parse_retry_after(response)
-        value = response.headers["retry-after"]
-        return nil unless value
-
-        value = value.strip
-        if value.match?(/\A\d+\z/)
-          value.to_f
-        else
-          # HTTP-date format
-          begin
-            target = Time.httpdate(value)
-            delay = target - Time.now
-            delay > 0 ? delay : 0.0
-          rescue ArgumentError
+        def parse_retry_after(response)
+          value = response.headers["retry-after"]
+          if value
+            value = value.strip
+            if value.match?(/\A\d+\z/)
+              value.to_f
+            else
+              # HTTP-date format
+              begin
+                target = Time.httpdate(value)
+                delay = target - Time.now
+                delay > 0 ? delay : 0.0
+              rescue ArgumentError
+                nil
+              end
+            end
+          else
             nil
           end
         end
-      end
 
-      def encode(value)
-        ERB::Util.url_encode(value)
-      end
+        def encode(value)
+          ERB::Util.url_encode(value)
+        end
     end
   end
 end
@@ -324,7 +356,7 @@ end
 __END__
   describe "Async::Matrix::Client" do
     def make_config
-      Async::Matrix::ApplicationService::Config.new({
+      Async::Matrix::Config.new({
         "homeserver" => { "address" => "http://localhost:8008", "domain" => "localhost" },
         "appservice" => { "as_token" => "test_token", "hs_token" => "hs_secret", "bot" => { "username" => "bot" } }
       })
@@ -465,7 +497,7 @@ __END__
 
   describe "Client retry logic" do
     def make_config
-      Async::Matrix::ApplicationService::Config.new({
+      Async::Matrix::Config.new({
         "homeserver" => { "address" => "http://localhost:8008", "domain" => "localhost" },
         "appservice" => { "as_token" => "test_token", "hs_token" => "hs_secret", "bot" => { "username" => "bot" } }
       })
@@ -689,7 +721,7 @@ __END__
 
   describe "Client ignore_rate_limit" do
     def make_config
-      Async::Matrix::ApplicationService::Config.new({
+      Async::Matrix::Config.new({
         "homeserver" => { "address" => "http://localhost:8008", "domain" => "localhost" },
         "appservice" => { "as_token" => "test_token", "hs_token" => "hs_secret", "bot" => { "username" => "bot" } }
       })
@@ -757,7 +789,7 @@ __END__
 
   describe "Client per-request max_retries" do
     def make_config
-      Async::Matrix::ApplicationService::Config.new({
+      Async::Matrix::Config.new({
         "homeserver" => { "address" => "http://localhost:8008", "domain" => "localhost" },
         "appservice" => { "as_token" => "test_token", "hs_token" => "hs_secret", "bot" => { "username" => "bot" } }
       })
@@ -848,7 +880,7 @@ __END__
 
   describe "Client response size limiting" do
     def make_config
-      Async::Matrix::ApplicationService::Config.new({
+      Async::Matrix::Config.new({
         "homeserver" => { "address" => "http://localhost:8008", "domain" => "localhost" },
         "appservice" => { "as_token" => "test_token", "hs_token" => "hs_secret", "bot" => { "username" => "bot" } }
       })

data/lib/async/matrix/config/vivify.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
+    class Config
+      # Mixin that gives a Hash dot-notation accessors with autovivification.
+      #
+      # Not applied globally — only extended onto the validated config hash
+      # and its nested children so the rest of the world is unaffected.
+      #
+      #   h = {}.extend(Vivify)
+      #   h.foo.bar.baz = 42
+      #   h  # => { foo: { bar: { baz: 42 } } }
+      #
+      module Vivify
+        def method_missing(name, *args)
+          key = name.to_s
+
+          if key.end_with?("=")
+            self[key.chomp("=").to_sym] = args.first
+          elsif key?(name.to_sym)
+            self[name.to_sym]
+          elsif key.start_with?("to_")
+            super
+          else
+            self[name.to_sym] = {}.extend(Vivify)
+          end
+        end
+
+        def respond_to_missing?(name, _priv = false)
+          name.to_s.end_with?("=") || key?(name.to_sym) || super
+        end
+
+        # Recursively symbolize keys and extend every nested Hash with Vivify.
+        #
+        # Call this on the raw (string-keyed) hash that comes out of
+        # YAML.safe_load before wrapping it in Config.
+        def self.deep_vivify(obj)
+          case obj
+          when Hash
+            result = {}
+            obj.each { |k, v| result[k.to_s.to_sym] = deep_vivify(v) }
+            result.extend(Vivify)
+          when Array
+            obj.map { |v| deep_vivify(v) }
+          else
+            obj
+          end
+        end
+      end
+    end
+  end
+end
+
+__END__
+  V = Async::Matrix::Config::Vivify
+
+  describe "Vivify" do
+    it "provides dot-notation read access to symbol keys" do
+      h = { foo: "bar" }.extend(V)
+      h.foo.should == "bar"
+    end
+
+    it "provides dot-notation write access" do
+      h = {}.extend(V)
+      h.foo = 42
+      h[:foo].should == 42
+    end
+
+    it "autovivifies missing keys as vivified hashes" do
+      h = {}.extend(V)
+      h.a.b.c = "deep"
+      h[:a][:b][:c].should == "deep"
+    end
+
+    it "delegates to_* methods to super (no autovivify)" do
+      h = { x: 1 }.extend(V)
+      h.to_a.should == [[:x, 1]]
+    end
+  end
+
+  describe "Vivify.deep_vivify" do
+    it "symbolizes string keys" do
+      result = V.deep_vivify({"a" => 1})
+      result[:a].should == 1
+    end
+
+    it "recursively vivifies nested hashes" do
+      result = V.deep_vivify({"outer" => {"inner" => "val"}})
+      result.outer.inner.should == "val"
+    end
+
+    it "vivifies hashes inside arrays" do
+      result = V.deep_vivify({"list" => [{"name" => "x"}]})
+      result.list.first.name.should == "x"
+    end
+
+    it "passes scalars through unchanged" do
+      result = V.deep_vivify({"n" => 42, "s" => "hi", "b" => true})
+      result.n.should == 42
+      result.s.should == "hi"
+      result.b.should == true
+    end
+  end