async-matrix 2.1.0-x86_64-linux → 3.0.0-x86_64-linux

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

data/lib/async/matrix/config.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "forwardable"
+require "yaml"
+require "pathname"
+require_relative "config/vivify"
+
+module Async
+  module Matrix
+    # Dot-notation access to a Matrix service's YAML configuration.
+    #
+    # {Client} only reads two fields — `homeserver.address` and
+    # `appservice.as_token` — so this class validates nothing: it vivifies
+    # whatever hash (or YAML file) it is handed and exposes every nested field
+    # as a method call.
+    #
+    #   config = Config.load("config/appservice.yml")
+    #   config.homeserver.address      # => "http://synapse:8008"
+    #   config.appservice.as_token     # => "secret..."
+    #   config.appservice.bot.username # => "bot"
+    #   config.bot_mxid                # => "@bot:localhost"
+    #
+    # A subclass layers validation on by overriding {.validate!}; that is how
+    # async-matrix-bridge's Config applies the mautrix bridgev2 JSON Schema
+    # suite without reimplementing any of the loading below.
+    class Config
+      extend Forwardable
+
+      # Delegate every top-level config section to the vivified data hash. An
+      # explicit list, not a method_missing forward: a typo'd section should
+      # raise NoMethodError rather than autovivify into an empty hash.
+      def_delegators :@data,
+        :network,
+        :bridge,
+        :database,
+        :homeserver,
+        :appservice,
+        :matrix,
+        :analytics,
+        :provisioning,
+        :public_media,
+        :direct_media,
+        :backfill,
+        :double_puppet,
+        :encryption,
+        :logging,
+        :management_room_texts,
+        :env_config_prefix
+
+      def initialize(data)
+        self.class.validate!(data)
+        @data = Vivify.deep_vivify(data)
+      end
+
+      # Load a YAML config file from disk.
+      def self.load(path)
+        unless File.exist?(path)
+          raise Async::Matrix::NotFoundError.new(
+            "M_NOT_FOUND",
+            "Config not found: #{path}",
+          )
+        end
+
+        data = YAML.safe_load_file(path, permitted_classes: [Symbol])
+        new(data)
+      end
+
+      # Validation hook, called with the raw (string-keyed) hash before it is
+      # vivified. A no-op here; subclasses override it to raise on bad input,
+      # and may mutate `data` to insert defaults.
+      def self.validate!(data)
+        nil
+      end
+
+      # Convenience: derive the bot's full Matrix ID from
+      # appservice.bot.username + homeserver.domain.
+      def bot_mxid
+        "@#{appservice.bot.username}:#{homeserver.domain}"
+      end
+    end
+  end
+end
+
+__END__
+  require "tempfile"
+
+  describe "Async::Matrix::Config" do
+    def minimal_data
+      {
+        "homeserver" => {
+          "address" => "http://localhost:8008",
+          "domain"  => "localhost",
+        },
+        "appservice" => {
+          "as_token" => "as_secret_token_value",
+          "hs_token" => "hs_secret_token_value",
+          "bot"      => {"username" => "bot"},
+        },
+      }
+    end
+
+    it "exposes top-level sections" do
+      config = Async::Matrix::Config.new(minimal_data)
+      config.homeserver.address.should == "http://localhost:8008"
+      config.homeserver.domain.should == "localhost"
+      config.appservice.as_token.should == "as_secret_token_value"
+      config.appservice.hs_token.should == "hs_secret_token_value"
+      config.appservice.bot.username.should == "bot"
+    end
+
+    it "derives bot_mxid from appservice.bot.username and homeserver.domain" do
+      Async::Matrix::Config.new(minimal_data).bot_mxid.should == "@bot:localhost"
+    end
+
+    it "provides dot-notation access to deeply nested fields" do
+      data = minimal_data.merge(
+        "encryption" => {
+          "allow" => true,
+          "rotation" => {"messages" => 200},
+        },
+      )
+      config = Async::Matrix::Config.new(data)
+      config.encryption.allow.should == true
+      config.encryption.rotation.messages.should == 200
+    end
+
+    it "autovivifies missing optional sections as empty hashes" do
+      config = Async::Matrix::Config.new(minimal_data)
+      config.analytics.should.be.kind_of Hash
+      config.analytics.should.be.empty?
+    end
+
+    it "raises NoMethodError for sections it does not delegate" do
+      config = Async::Matrix::Config.new(minimal_data)
+      lambda { config.bogus }.should.raise(NoMethodError)
+    end
+
+    it "validates nothing by default" do
+      lambda { Async::Matrix::Config.new({}) }.should.not.raise
+    end
+
+    it "loads from a YAML file" do
+      file = Tempfile.new(["config", ".yml"])
+      file.write(<<~YAML)
+        homeserver:
+          address: "http://localhost:8008"
+          domain: "localhost"
+        appservice:
+          as_token: "as123_secret"
+          hs_token: "hs456_secret"
+          bot:
+            username: "testbot"
+      YAML
+      file.close
+
+      config = Async::Matrix::Config.load(file.path)
+      config.homeserver.address.should == "http://localhost:8008"
+      config.bot_mxid.should == "@testbot:localhost"
+    ensure
+      file.unlink
+    end
+
+    it "raises NotFoundError for a missing file" do
+      lambda {
+        Async::Matrix::Config.load("/nonexistent/path.yml")
+      }.should.raise(Async::Matrix::NotFoundError)
+    end
+
+    it "runs the validate! hook a subclass overrides" do
+      strict = Class.new(Async::Matrix::Config) do
+        def self.validate!(data)
+          unless data.key?("homeserver")
+            raise Async::Matrix::BadJsonError.new("M_BAD_JSON", "no homeserver")
+          end
+        end
+      end
+
+      lambda { strict.new({}) }.should.raise(Async::Matrix::BadJsonError)
+      strict.new(minimal_data).homeserver.domain.should == "localhost"
+    end
+  end