async-matrix 0.1.2 → 1.0.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/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

data/lib/async/matrix/notifier.rb

@@ -9,99 +9,99 @@ require "async/condition"
 require "async/matrix"
 
 module Async
-	module Matrix
-		# Waitable event bus. Signal it when events arrive;
-		# /sync handlers wait on it with a timeout.
-		#
-		#   notifier = Async::Matrix::Notifier.new
-		#
-		#   # In a /sync handler fiber (blocks until signalled or timeout):
-		#   notifier.wait(timeout: 30) { check_for_events() }
-		#
-		#   # After persisting an event (wakes all waiting fibers):
-		#   notifier.signal
-		#
-		class Notifier
-			def initialize
-				@condition = Async::Condition.new
-			end
-
-			# Wake all waiting fibers.
-			def signal
-				@condition.signal
-			end
-
-			# Block up to +timeout+ seconds. Yields to check for data after
-			# each wake-up; returns the block's value as soon as it is truthy.
-			# Returns the block's value (possibly nil/false) when time runs out.
-			def wait(timeout: 30, &block)
-				deadline = Time.now + timeout
-
-				loop do
-					result = yield
-					return result if result
-
-					remaining = deadline - Time.now
-					return result if remaining <= 0
-
-					begin
-						Async::Task.current.with_timeout(remaining) do
-							@condition.wait
-						end
-					rescue Async::TimeoutError
-						return yield
-					end
-				end
-			end
-		end
-	end
+  module Matrix
+    # Waitable event bus. Signal it when events arrive;
+    # /sync handlers wait on it with a timeout.
+    #
+    #   notifier = Async::Matrix::Notifier.new
+    #
+    #   # In a /sync handler fiber (blocks until signalled or timeout):
+    #   notifier.wait(timeout: 30) { check_for_events() }
+    #
+    #   # After persisting an event (wakes all waiting fibers):
+    #   notifier.signal
+    #
+    class Notifier
+      def initialize
+        @condition = Async::Condition.new
+      end
+
+      # Wake all waiting fibers.
+      def signal
+        @condition.signal
+      end
+
+      # Block up to +timeout+ seconds. Yields to check for data after
+      # each wake-up; returns the block's value as soon as it is truthy.
+      # Returns the block's value (possibly nil/false) when time runs out.
+      def wait(timeout: 30, &block)
+        deadline = Time.now + timeout
+
+        loop do
+          result = yield
+          return result if result
+
+          remaining = deadline - Time.now
+          return result if remaining <= 0
+
+          begin
+            Async::Task.current.with_timeout(remaining) do
+              @condition.wait
+            end
+          rescue Async::TimeoutError
+            return yield
+          end
+        end
+      end
+    end
+  end
 end
 
 test do
-	it "can be instantiated" do
-		notifier = Async::Matrix::Notifier.new
-		notifier.should.be.kind_of Async::Matrix::Notifier
-	end
-
-	it "responds to #signal" do
-		Async::Matrix::Notifier.new.should.respond_to :signal
-	end
-
-	it "responds to #wait" do
-		Async::Matrix::Notifier.new.should.respond_to :wait
-	end
-
-	it "returns truthy block value immediately without waiting" do
-		Async do
-			notifier = Async::Matrix::Notifier.new
-			result = notifier.wait(timeout: 1) { :data }
-			result.should == :data
-		end.wait
-	end
-
-	it "returns falsy block value on timeout" do
-		Async do
-			notifier = Async::Matrix::Notifier.new
-			result = notifier.wait(timeout: 0.05) { nil }
-			result.should.be.nil
-		end.wait
-	end
-
-	it "wakes waiting fibers on signal" do
-		result = nil
-		Async do |task|
-			notifier = Async::Matrix::Notifier.new
-			signalled = false
-
-			task.async do
-				result = notifier.wait(timeout: 5) { signalled }
-			end
-
-			task.async do
-				signalled = true
-				notifier.signal
-			end
-		end.wait
-		result.should == true
-	end
+  it "can be instantiated" do
+    notifier = Async::Matrix::Notifier.new
+    notifier.should.be.kind_of Async::Matrix::Notifier
+  end
+
+  it "responds to #signal" do
+    Async::Matrix::Notifier.new.should.respond_to :signal
+  end
+
+  it "responds to #wait" do
+    Async::Matrix::Notifier.new.should.respond_to :wait
+  end
+
+  it "returns truthy block value immediately without waiting" do
+    Async do
+      notifier = Async::Matrix::Notifier.new
+      result = notifier.wait(timeout: 1) { :data }
+      result.should == :data
+    end.wait
+  end
+
+  it "returns falsy block value on timeout" do
+    Async do
+      notifier = Async::Matrix::Notifier.new
+      result = notifier.wait(timeout: 0.05) { nil }
+      result.should.be.nil
+    end.wait
+  end
+
+  it "wakes waiting fibers on signal" do
+    result = nil
+    Async do |task|
+      notifier = Async::Matrix::Notifier.new
+      signalled = false
+
+      task.async do
+        result = notifier.wait(timeout: 5) { signalled }
+      end
+
+      task.async do
+        signalled = true
+        notifier.signal
+      end
+    end.wait
+    result.should == true
+  end
 end