async-matrix 0.1.3 → 1.1.0

data/lib/async/matrix/connection.rb

@@ -8,15 +8,15 @@ require "async/http"
 require "async/matrix"
 
 module Async
-	module Matrix
-		module Connection
-			include Async::HTTP::Protocol::HTTP2::Connection
-		end
-	end
+  module Matrix
+    module Connection
+      include Async::HTTP::Protocol::HTTP2::Connection
+    end
+  end
 end
 
 test do
-	it "includes Async::HTTP::Protocol::HTTP2::Connection" do
-		Async::Matrix::Connection.ancestors.should.include Async::HTTP::Protocol::HTTP2::Connection
-	end
+  it "includes Async::HTTP::Protocol::HTTP2::Connection" do
+    Async::Matrix::Connection.ancestors.should.include Async::HTTP::Protocol::HTTP2::Connection
+  end
 end

data/lib/async/matrix/double_puppet_client.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+require "async/matrix"
+
+module Async
+  module Matrix
+    # A Client subclass that authenticates with a user's double puppet token
+    # instead of the appservice's as_token.
+    #
+    # This allows the bridge to send events as the real Matrix user rather
+    # than as the appservice bot or a ghost user.
+    #
+    #   puppet = DoublePuppetClient.new(config, double_puppet_token: "syt_...")
+    #   puppet.send_text("!room:example.com", "sent as the real user")
+    #   puppet.whoami  # => {"user_id" => "@alice:example.com"}
+    #
+    class DoublePuppetClient < Client
+      def initialize(config, double_puppet_token:, **kwargs)
+        super(config, **kwargs)
+        @headers[0] = ["authorization", "Bearer #{double_puppet_token}"]
+      end
+    end
+  end
+end
+
+test do
+  describe "Async::Matrix::DoublePuppetClient" do
+    def make_config
+      Async::Matrix::ApplicationService::Config.new({
+        "homeserver" => { "address" => "http://localhost:8008", "domain" => "localhost" },
+        "appservice" => { "as_token" => "as_token_value", "hs_token" => "hs_secret", "bot" => { "username" => "bot" } }
+      })
+    end
+
+    it "uses the double_puppet_token for authorization" do
+      puppet = Async::Matrix::DoublePuppetClient.new(make_config, double_puppet_token: "syt_puppet_token")
+      auth_header = puppet.instance_variable_get(:@headers).find { |k, _| k == "authorization" }
+      auth_header[1].should == "Bearer syt_puppet_token"
+    end
+
+    it "does not use the as_token from config" do
+      puppet = Async::Matrix::DoublePuppetClient.new(make_config, double_puppet_token: "syt_puppet_token")
+      auth_header = puppet.instance_variable_get(:@headers).find { |k, _| k == "authorization" }
+      auth_header[1].should.not.include "as_token_value"
+    end
+
+    it "inherits retry defaults from Client" do
+      puppet = Async::Matrix::DoublePuppetClient.new(make_config, double_puppet_token: "syt_puppet_token")
+      puppet.config.appservice.as_token.should == "as_token_value"
+    end
+
+    it "accepts custom retry configuration" do
+      puppet = Async::Matrix::DoublePuppetClient.new(
+        make_config,
+        double_puppet_token: "syt_puppet_token",
+        max_retries: 5,
+        retry_base_delay: 1.0,
+        max_retry_delay: 60
+      )
+      auth_header = puppet.instance_variable_get(:@headers).find { |k, _| k == "authorization" }
+      auth_header[1].should == "Bearer syt_puppet_token"
+    end
+
+    it "responds to all Client methods" do
+      puppet = Async::Matrix::DoublePuppetClient.new(make_config, double_puppet_token: "syt_puppet_token")
+      puppet.should.respond_to :send_text
+      puppet.should.respond_to :send_html
+      puppet.should.respond_to :send_notice
+      puppet.should.respond_to :join_room
+      puppet.should.respond_to :leave_room
+      puppet.should.respond_to :whoami
+      puppet.should.respond_to :api
+    end
+
+    it "is a subclass of Client" do
+      puppet = Async::Matrix::DoublePuppetClient.new(make_config, double_puppet_token: "syt_puppet_token")
+      puppet.should.be.kind_of Async::Matrix::Client
+    end
+  end
+end

data/lib/async/matrix/endpoint.rb

@@ -9,52 +9,52 @@ require "async/http"
 require "async/matrix"
 
 module Async
-	module Matrix
-		# Extends Async::HTTP::Endpoint with Matrix well-known discovery.
-		# spec.matrix.org/v1.9/client-server-api/#well-known-uri
-		#
-		# A server at example.com may serve clients from a completely
-		# different origin — e.g. https://matrix.example.com:8448.
-		# #discover resolves that indirection as a proper async I/O
-		# operation before constructing the Endpoint, so every downstream
-		# caller gets a correctly-pointed connection pool for free.
-		class Endpoint < Async::HTTP::Endpoint
-			WELL_KNOWN = "/.well-known/matrix/client"
-
-			# Resolves homeserver base URL, falls back to https://domain.
-			# Must be called inside an Async block — uses the running scheduler.
-			def self.discover(domain, **options)
-				internet = Async::HTTP::Internet.new
-				data     = JSON.parse(internet.get("https://#{domain}#{WELL_KNOWN}").read)
-				base_url = data.dig("m.homeserver", "base_url") || "https://#{domain}"
-				parse(base_url, **options)
-			rescue StandardError
-				# Well-known is optional per spec — fall back gracefully
-				parse("https://#{domain}", **options)
-			ensure
-				internet&.close
-			end
-		end
-	end
+  module Matrix
+    # Extends Async::HTTP::Endpoint with Matrix well-known discovery.
+    # spec.matrix.org/v1.9/client-server-api/#well-known-uri
+    #
+    # A server at example.com may serve clients from a completely
+    # different origin — e.g. https://matrix.example.com:8448.
+    # #discover resolves that indirection as a proper async I/O
+    # operation before constructing the Endpoint, so every downstream
+    # caller gets a correctly-pointed connection pool for free.
+    class Endpoint < Async::HTTP::Endpoint
+      WELL_KNOWN = "/.well-known/matrix/client"
+
+      # Resolves homeserver base URL, falls back to https://domain.
+      # Must be called inside an Async block — uses the running scheduler.
+      def self.discover(domain, **options)
+        internet = Async::HTTP::Internet.new
+        data     = JSON.parse(internet.get("https://#{domain}#{WELL_KNOWN}").read)
+        base_url = data.dig("m.homeserver", "base_url") || "https://#{domain}"
+        parse(base_url, **options)
+      rescue StandardError
+        # Well-known is optional per spec — fall back gracefully
+        parse("https://#{domain}", **options)
+      ensure
+        internet&.close
+      end
+    end
+  end
 end
 
 test do
-	it "defines the WELL_KNOWN constant" do
-		Async::Matrix::Endpoint::WELL_KNOWN.should == "/.well-known/matrix/client"
-	end
-
-	it "responds to .discover" do
-		Async::Matrix::Endpoint.should.respond_to :discover
-	end
-
-	it "inherits from Async::HTTP::Endpoint" do
-		Async::Matrix::Endpoint.ancestors.should.include Async::HTTP::Endpoint
-	end
-
-	it "falls back to https://domain when well-known fails" do
-		Async do
-			endpoint = Async::Matrix::Endpoint.discover("nonexistent.invalid")
-			endpoint.to_s.should =~ /nonexistent\.invalid/
-		end.wait
-	end
+  it "defines the WELL_KNOWN constant" do
+    Async::Matrix::Endpoint::WELL_KNOWN.should == "/.well-known/matrix/client"
+  end
+
+  it "responds to .discover" do
+    Async::Matrix::Endpoint.should.respond_to :discover
+  end
+
+  it "inherits from Async::HTTP::Endpoint" do
+    Async::Matrix::Endpoint.ancestors.should.include Async::HTTP::Endpoint
+  end
+
+  it "falls back to https://domain when well-known fails" do
+    Async do
+      endpoint = Async::Matrix::Endpoint.discover("nonexistent.invalid")
+      endpoint.to_s.should =~ /nonexistent\.invalid/
+    end.wait
+  end
 end

data/lib/async/matrix/error.rb

@@ -6,59 +6,65 @@
 require "bundler/setup"
 
 module Async
-	module Matrix
-		class Error < StandardError
-			attr_reader :errcode, :status
+  module Matrix
+    class Error < StandardError
+      attr_reader :errcode, :status
 
-			def initialize(errcode, message, status: nil)
-				@errcode = errcode
-				@status = status
-				super(message)
-			end
-		end
+      def initialize(errcode, message, status: nil)
+        @errcode = errcode
+        @status = status
+        super(message)
+      end
+    end
 
-		class NotFoundError < Error; end
-		class BadJsonError < Error; end
-		class AuthError < Error; end
-		class HomeserverError < Error; end
-	end
+    class NotFoundError < Error; end
+    class BadJsonError < Error; end
+    class AuthError < Error; end
+    class HomeserverError < Error; end
+    class InvalidEndpointError < Error; end
+    class ResponseTooLargeError < Error; end
+  end
 end
 
 test do
-	describe "Async::Matrix::Error" do
-		it "stores errcode and message" do
-			err = Async::Matrix::Error.new("M_UNKNOWN", "something broke")
-			err.errcode.should == "M_UNKNOWN"
-			err.message.should == "something broke"
-		end
+  describe "Async::Matrix::Error" do
+    it "stores errcode and message" do
+      err = Async::Matrix::Error.new("M_UNKNOWN", "something broke")
+      err.errcode.should == "M_UNKNOWN"
+      err.message.should == "something broke"
+    end
 
-		it "stores optional status" do
-			err = Async::Matrix::Error.new("M_UNKNOWN", "bad", status: 400)
-			err.status.should == 400
-		end
+    it "stores optional status" do
+      err = Async::Matrix::Error.new("M_UNKNOWN", "bad", status: 400)
+      err.status.should == 400
+    end
 
-		it "defaults status to nil" do
-			Async::Matrix::Error.new("M_UNKNOWN", "bad").status.should.be.nil
-		end
+    it "defaults status to nil" do
+      Async::Matrix::Error.new("M_UNKNOWN", "bad").status.should.be.nil
+    end
 
-		it "is a StandardError" do
-			Async::Matrix::Error.new("M_UNKNOWN", "bad").should.be.kind_of StandardError
-		end
-	end
+    it "is a StandardError" do
+      Async::Matrix::Error.new("M_UNKNOWN", "bad").should.be.kind_of StandardError
+    end
+  end
 
-	it "NotFoundError inherits from Error" do
-		Async::Matrix::NotFoundError.new("M_NOT_FOUND", "gone").should.be.kind_of Async::Matrix::Error
-	end
+  it "NotFoundError inherits from Error" do
+    Async::Matrix::NotFoundError.new("M_NOT_FOUND", "gone").should.be.kind_of Async::Matrix::Error
+  end
 
-	it "BadJsonError inherits from Error" do
-		Async::Matrix::BadJsonError.new("M_BAD_JSON", "invalid").should.be.kind_of Async::Matrix::Error
-	end
+  it "BadJsonError inherits from Error" do
+    Async::Matrix::BadJsonError.new("M_BAD_JSON", "invalid").should.be.kind_of Async::Matrix::Error
+  end
 
-	it "AuthError inherits from Error" do
-		Async::Matrix::AuthError.new("M_FORBIDDEN", "denied").should.be.kind_of Async::Matrix::Error
-	end
+  it "AuthError inherits from Error" do
+    Async::Matrix::AuthError.new("M_FORBIDDEN", "denied").should.be.kind_of Async::Matrix::Error
+  end
 
-	it "HomeserverError inherits from Error" do
-		Async::Matrix::HomeserverError.new("M_UNKNOWN", "upstream").should.be.kind_of Async::Matrix::Error
-	end
+  it "HomeserverError inherits from Error" do
+    Async::Matrix::HomeserverError.new("M_UNKNOWN", "upstream").should.be.kind_of Async::Matrix::Error
+  end
+
+  it "ResponseTooLargeError inherits from Error" do
+    Async::Matrix::ResponseTooLargeError.new("M_TOO_LARGE", "too big").should.be.kind_of Async::Matrix::Error
+  end
 end

data/lib/async/matrix/media_client.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+require "async/http/internet"
+require "async/matrix"
+require "json"
+require "console"
+
+module Async
+  module Matrix
+    # Async HTTP client for binary Matrix media operations.
+    #
+    # Handles raw byte uploads and downloads against the Matrix content
+    # repository. Unlike the JSON-only Client, this never wraps request
+    # bodies in JSON.generate and can return raw binary response bodies.
+    #
+    # Not intended to be used directly — the Chain dispatches here
+    # automatically when the request path matches a BINARY_ROUTES entry.
+    #
+    #   media_client = Async::Matrix::MediaClient.new(config)
+    #   media_client.upload("POST", path, bytes, "image/png")
+    #   bytes = media_client.download(path)
+    #
+    class MediaClient
+      # Upload JSON responses are small; error bodies are even smaller.
+      UPLOAD_RESPONSE_SIZE_LIMIT = 1 * 1024 * 1024   # 1 MiB
+      ERROR_RESPONSE_SIZE_LIMIT  = 512 * 1024          # 512 KiB
+
+      def initialize(config)
+        @config = config
+        @base   = config.homeserver.address
+        @auth_headers = [
+          ["authorization", "Bearer #{config.appservice.as_token}"],
+          ["user-agent",    "AsyncMatrix/#{Async::Matrix::VERSION}"]
+        ]
+      end
+
+      # Upload raw bytes to the content repository.
+      #
+      # @param method [String] HTTP method ("POST" or "PUT")
+      # @param path [String] URL path (already URL-encoded)
+      # @param body [String] raw bytes to upload
+      # @param content_type [String] MIME type of the body
+      # @return [Hash] parsed JSON response (e.g. {"content_uri" => "mxc://..."})
+      def upload(method, path, body, content_type = "application/octet-stream")
+        url = "#{@base}#{path}"
+        headers = @auth_headers + [["content-type", content_type]]
+
+        Console.debug(self) { "UPLOAD #{method} #{path} (#{content_type}, #{body.bytesize} bytes)" }
+
+        response = internet.call(method, url, headers, body)
+        status   = response.status
+
+        unless (200..299).cover?(status)
+          payload = read_limited(response, ERROR_RESPONSE_SIZE_LIMIT)
+          parsed = ApplicationService::ErrorResponse.new(
+            begin; JSON.parse(payload); rescue; {} end
+          )
+          Console.error(self) { "Matrix media upload #{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, UPLOAD_RESPONSE_SIZE_LIMIT)
+        payload && !payload.empty? ? JSON.parse(payload) : {}
+      end
+
+      # Download from the content repository.
+      #
+      # Returns the raw HTTP response object so the caller has access to
+      # both the body and response metadata:
+      #
+      #   response = media_client.download(path)
+      #   response.read                          # raw bytes (String, Encoding::BINARY)
+      #   response.headers["content-type"]       # "image/png"
+      #   response.headers["content-disposition"] # "inline; filename=\"photo.jpg\""
+      #   response.body.each { |chunk| ... }     # streaming
+      #
+      # @param path [String] URL path (already URL-encoded, may include query string)
+      # @return [Protocol::HTTP::Response] the HTTP response
+      def download(path)
+        url = "#{@base}#{path}"
+
+        Console.debug(self) { "DOWNLOAD #{path}" }
+
+        response = internet.call("GET", url, @auth_headers, nil)
+        status   = response.status
+
+        unless (200..299).cover?(status)
+          payload = response.read
+          parsed = ApplicationService::ErrorResponse.new(
+            begin; JSON.parse(payload); rescue; {} end
+          )
+          Console.error(self) { "Matrix media download #{status}: #{parsed.errcode} — #{parsed.error}" }
+          raise HomeserverError.new(
+            parsed.errcode || "UNKNOWN",
+            parsed.error || payload.to_s[0..200],
+            status: status
+          )
+        end
+
+        response
+      end
+
+      def close
+        @internet&.close
+        @internet = nil
+      end
+
+      private
+
+      def internet
+        @internet ||= Async::HTTP::Internet.new
+      end
+
+      # Read response body with a size limit. Raises ResponseTooLargeError
+      # if the body exceeds the limit.
+      def read_limited(response, limit)
+        body = response.body
+        return nil unless 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
+      end
+    end
+  end
+end
+
+test do
+  describe "Async::Matrix::MediaClient" do
+    def make_config
+      Async::Matrix::ApplicationService::Config.new({
+        "homeserver" => { "address" => "http://localhost:8008", "domain" => "localhost" },
+        "appservice" => { "as_token" => "test_token", "hs_token" => "hs_secret", "bot" => { "username" => "bot" } }
+      })
+    end
+
+    it "responds to upload and download" do
+      client = Async::Matrix::MediaClient.new(make_config)
+      client.should.respond_to :upload
+      client.should.respond_to :download
+    end
+
+    it "can be closed without error" do
+      client = Async::Matrix::MediaClient.new(make_config)
+      lambda { client.close }.should.not.raise
+    end
+  end
+end