async-matrix 2.1.0-x86_64-linux → 3.0.1-x86_64-linux

data/lib/async/matrix/client.rb

@@ -10,6 +10,12 @@ require "console"
 require "securerandom"
 require "time"
 
+# The action surface, mixed in below. Required explicitly because the library's
+# loader globs this directory in sorted order, which reaches client.rb before
+# client/ -- so `include Encryption` would resolve against nothing.
+require_relative "client/encryption"
+require_relative "client/rooms"
+
 module Async
   module Matrix
     # Async HTTP client for the Matrix Client-Server API.
@@ -37,6 +43,9 @@ module Async
       DEFAULT_RESPONSE_SIZE_LIMIT       = 50 * 1024 * 1024  # 50 MiB for JSON API responses
       DEFAULT_ERROR_RESPONSE_SIZE_LIMIT = 512 * 1024         # 512 KiB for error bodies
 
+      include Encryption
+      include Rooms
+
       attr_reader :config
 
       def initialize(config, max_retries: DEFAULT_MAX_RETRIES,
@@ -72,7 +81,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
@@ -84,12 +93,18 @@ module Async
 
       # ── Room actions ───────────────────────────────────────────
 
-      def join_room(room_id)
-        post("#{CLIENT_PREFIX}/join/#{encode(room_id)}")
+      # Positional OR keyword: `join_room("!r:example.org")` is how this was
+      # always called, and `join_room(room_id: "!r:example.org")` is the form
+      # every other action here takes. Keeping both means the action surface is
+      # consistent without breaking callers written against 3.0.
+      def join_room(room_id = nil, **options)
+        target = room_id || options[:room_id]
+        post("#{CLIENT_PREFIX}/join/#{encode(target)}")
       end
 
-      def leave_room(room_id)
-        post("#{CLIENT_PREFIX}/rooms/#{encode(room_id)}/leave")
+      def leave_room(room_id = nil, **options)
+        target = room_id || options[:room_id]
+        post("#{CLIENT_PREFIX}/rooms/#{encode(target)}/leave")
       end
 
       # ── Profile ────────────────────────────────────────────────
@@ -98,7 +113,7 @@ module Async
         uid = user_id || @config.bot_mxid
         put(
           "#{CLIENT_PREFIX}/profile/#{encode(uid)}/displayname",
-          {displayname: name}
+          {displayname: name},
         )
       end
 
@@ -108,6 +123,21 @@ module Async
         get("#{CLIENT_PREFIX}/account/whoami")
       end
 
+      # ── Syncing ────────────────────────────────────────────────────────────
+
+      # A stream of messages from this account, decrypted by +store+.
+      #
+      #   client.sync(store: device_store).each do |message|
+      #     ...
+      #   end
+      #
+      # See Client::Sync: the stream yields room messages only, and to-device
+      # events are fed to the store on the way through, which is how room keys
+      # arrive.
+      def sync(store: nil, since: nil, timeout: Sync::DEFAULT_TIMEOUT, filter: nil)
+        Sync.new(self, store: store, since: since, timeout: timeout, filter: filter)
+      end
+
       # ── Full API (runtime-generated from OpenAPI schemas) ─────
 
       # Returns a Gateway that provides method-chained access to every
@@ -151,17 +181,42 @@ 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
 
+      # Query parameters added to EVERY request this client makes.
+      #
+      # EMPTY FOR AN ORDINARY CLIENT: a user's own access token already says who
+      # the request is for. AppServiceClient overrides it, because an as_token
+      # says only "an appservice" -- without `?user_id=` the homeserver assumes
+      # the registration's sender_localpart, and without `?device_id=` the
+      # request has no device at all, which fails precisely the calls encryption
+      # depends on.
+      def default_query = {}
+
       def close
         @internet&.close
         @internet = nil
@@ -171,51 +226,97 @@ 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}" }
+        def internet
+          @internet ||= Async::HTTP::Internet.new
+        end
 
-        attempt = 0
-        loop do
-          response = internet.call(method, url, @headers, json_body)
-          status   = response.status
+        # Merge #default_query into a path that may already carry a query --
+        # Api::Chain appends its own parameters before handing the path over, so
+        # this is the single place both routes pass through.
+        #
+        # A parameter the caller already set WINS. Overwriting it would mean a
+        # client silently acting as somebody other than the caller asked for,
+        # which is worse than the request failing.
+        def apply_default_query(path)
+          missing = default_query.reject { |key, _|
+            path.match?(/[?&]#{Regexp.escape(key.to_s)}=/)
+          }
+
+          if missing.empty?
+            path
+          else
+            if path.include?("?")
+              separator = "&"
+            else
+              separator = "?"
+            end
+
+            pairs = missing.map { |key, value| "#{encode(key.to_s)}=#{encode(value.to_s)}" }
+
+            "#{path}#{separator}#{pairs.join('&')}"
+          end
+        end
 
-          if (200..299).cover?(status)
-            payload = read_limited(response, @response_size_limit)
-            return payload && !payload.empty? ? JSON.parse(payload) : {}
+        # PUBLIC, declared below: Api::Chain#execute calls `@client.request` for
+        # DELETE, so leaving this private makes every DELETE through the chain
+        # raise NoMethodError.
+        def request(method, path, body = nil, max_retries: nil)
+          url = "#{@base}#{apply_default_query(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 +327,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 +376,51 @@ 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
+
+        public :request
     end
   end
 end
@@ -324,7 +428,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 +569,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 +793,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 +861,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 +952,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