async-matrix 3.0.0-arm-linux-musl

data/lib/async/matrix/error.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+module Async
+  module Matrix
+    class Error < StandardError
+      attr_reader :errcode, :status
+
+      def initialize(errcode, message, status: nil)
+        @errcode = errcode
+        @status = status
+        super(message)
+      end
+    end
+  end
+end
+
+__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 "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

data/lib/async/matrix/error_response.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+module Async
+  module Matrix
+    # A Matrix standard error response body: `{"errcode": ..., "error": ...}`.
+    # Both {Client} and {MediaClient} parse failed responses into one of these.
+    class ErrorResponse
+      attr_reader :errcode, :error
+
+      def initialize(data)
+        @errcode = data["errcode"]
+        @error   = data["error"]
+      end
+    end
+  end
+end
+
+__END__
+  describe "Async::Matrix::ErrorResponse" do
+    it "parses errcode and error" do
+      resp = Async::Matrix::ErrorResponse.new({
+        "errcode" => "M_FORBIDDEN",
+        "error" => "Access denied"
+      })
+      resp.errcode.should == "M_FORBIDDEN"
+      resp.error.should == "Access denied"
+    end
+
+    it "handles missing fields" do
+      resp = Async::Matrix::ErrorResponse.new({})
+      resp.errcode.should.be.nil
+      resp.error.should.be.nil
+    end
+  end

data/lib/async/matrix/event.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+module Async
+  module Matrix
+    # Represents a Matrix event, however it arrived — a /sync response, an
+    # application service transaction, or a hash you built yourself.
+    #
+    # Provides typed accessors for all envelope fields plus schema-driven
+    # validation using the official Matrix spec YAML schemas.
+    #
+    #   event = Event.new(raw_hash)
+    #   event.type           # => "m.room.message"
+    #   event.sender         # => "@alice:example.org"
+    #   event.content.body   # => "hello"
+    #   event.valid?         # => true
+    #   event.valid!         # => true (or raises Schema::ValidationError)
+    #
+    class Event
+      attr_reader :type,
+        :sender,
+        :room_id,
+        :state_key,
+        :content,
+        :event_id,
+        :origin_server_ts,
+        :unsigned,
+        :raw
+
+      def initialize(data)
+        @raw       = data
+        @type      = data["type"]
+        @sender    = data["sender"]
+        @room_id   = data["room_id"]
+        @state_key = data["state_key"]
+        @event_id  = data["event_id"]
+        @origin_server_ts = data["origin_server_ts"]
+        @unsigned  = data["unsigned"]
+        @content   = Content.new(data["content"] || {})
+      end
+
+      # The JSONSchemer::Schema for this event's type, or nil if unknown.
+      def schema = Schema[@type]
+
+      # Validate this event against its schema.
+      # Returns true if valid or if no schema exists (lenient).
+      def valid? = Schema.valid?(@raw)
+
+      # Validate this event against its schema.
+      # Raises Schema::ValidationError with detailed errors on failure.
+      # Returns true if valid or if no schema exists.
+      def valid!
+        errors = Schema.validate(@raw)
+
+        unless errors.empty?
+          raise Schema::ValidationError.new(
+            errors,
+            event_type: @type,
+            event_id:   @event_id,
+          )
+        end
+
+        true
+      end
+
+      # Content property names defined by the schema for this event type.
+      # @return [Array<String>]
+      def content_properties = Schema.content_properties(@type)
+
+      # Is this a state event? (has a state_key)
+      def state_event? = !@state_key.nil?
+    end
+  end
+end
+
+__END__
+  describe "Async::Matrix::Event" do
+    it "parses all event fields" do
+      event = Async::Matrix::Event.new({
+        "type" => "m.room.message",
+        "sender" => "@alice:example.com",
+        "room_id" => "!abc:example.com",
+        "state_key" => "",
+        "event_id" => "$evt1",
+        "origin_server_ts" => 1234567890,
+        "unsigned" => {"age" => 1000},
+        "content" => {"msgtype" => "m.text", "body" => "hi"}
+      })
+      event.type.should == "m.room.message"
+      event.sender.should == "@alice:example.com"
+      event.room_id.should == "!abc:example.com"
+      event.state_key.should == ""
+      event.event_id.should == "$evt1"
+      event.origin_server_ts.should == 1234567890
+      event.unsigned.should == {"age" => 1000}
+      event.content.should.be.kind_of Async::Matrix::Content
+      event.content.body.should == "hi"
+    end
+
+    it "defaults content to empty Content when missing" do
+      event = Async::Matrix::Event.new({"type" => "m.room.message"})
+      event.content.should.be.kind_of Async::Matrix::Content
+      event.content.body.should.be.nil
+    end
+
+    it "exposes the raw hash" do
+      data = {"type" => "m.room.message", "content" => {"body" => "hi", "msgtype" => "m.text"}}
+      event = Async::Matrix::Event.new(data)
+      event.raw.should.equal data
+    end
+
+    it "detects state events" do
+      state = Async::Matrix::Event.new({"type" => "m.room.member", "state_key" => "@a:b"})
+      state.state_event?.should == true
+
+      msg = Async::Matrix::Event.new({"type" => "m.room.message"})
+      msg.state_event?.should == false
+    end
+
+    it "returns the schema for known event types" do
+      event = Async::Matrix::Event.new({"type" => "m.room.message", "content" => {}})
+      event.schema.should.not.be.nil
+      event.schema.should.be.kind_of JSONSchemer::Schema
+    end
+
+    it "returns nil schema for unknown event types" do
+      event = Async::Matrix::Event.new({"type" => "m.custom.event", "content" => {}})
+      event.schema.should.be.nil
+    end
+
+    it "validates a correct event" do
+      event = Async::Matrix::Event.new({
+        "type" => "m.room.message",
+        "content" => {"msgtype" => "m.text", "body" => "hello"},
+        "event_id" => "$abc123",
+        "sender" => "@alice:example.org",
+        "origin_server_ts" => 1234567890,
+        "room_id" => "!room:example.org"
+      })
+      event.valid?.should == true
+      event.valid!.should == true
+    end
+
+    it "rejects an invalid event" do
+      event = Async::Matrix::Event.new({
+        "type" => "m.room.message",
+        "content" => {"msgtype" => "m.text"},
+        "event_id" => "$abc123",
+        "sender" => "@alice:example.org",
+        "origin_server_ts" => 1234567890,
+        "room_id" => "!room:example.org"
+      })
+      event.valid?.should == false
+    end
+
+    it "raises ValidationError from valid!" do
+      event = Async::Matrix::Event.new({
+        "type" => "m.room.member",
+        "content" => {"membership" => "invalid_state"},
+        "state_key" => "@alice:example.org",
+        "event_id" => "$abc123",
+        "sender" => "@alice:example.org",
+        "origin_server_ts" => 1234567890,
+        "room_id" => "!room:example.org"
+      })
+      begin
+        event.valid!
+        raise "should have raised"
+      rescue Async::Matrix::Schema::ValidationError => e
+        e.message.should.include "m.room.member"
+        e.message.should.include "$abc123"
+        e.errors.should.not.be.empty
+      end
+    end
+
+    it "is lenient with unknown event types" do
+      event = Async::Matrix::Event.new({
+        "type" => "com.custom.event",
+        "content" => {"anything" => "goes"},
+        "event_id" => "$x",
+        "sender" => "@a:b"
+      })
+      event.valid?.should == true
+      event.valid!.should == true
+    end
+
+    it "returns content properties for known types" do
+      event = Async::Matrix::Event.new({
+        "type" => "m.room.member",
+        "content" => {"membership" => "join"}
+      })
+      props = event.content_properties
+      props.should.include "membership"
+    end
+  end

data/lib/async/matrix/homeserver_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 HomeserverError < Error; end
+  end
+end
+
+__END__
+  it "HomeserverError inherits from Error" do
+    Async::Matrix::HomeserverError.new("M_UNKNOWN", "upstream").should.be.kind_of Async::Matrix::Error
+  end

data/lib/async/matrix/invalid_endpoint_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 InvalidEndpointError < Error; end
+  end
+end
+
+__END__
+  it "InvalidEndpointError inherits from Error" do
+    Async::Matrix::InvalidEndpointError.new("M_UNRECOGNIZED", "no such route").should.be.kind_of Async::Matrix::Error
+  end

data/lib/async/matrix/media_client.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "async/http/internet"
+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 = 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 = 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
+          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
+    end
+  end
+end
+
+__END__
+  describe "Async::Matrix::MediaClient" do
+    def make_config
+      Async::Matrix::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

data/lib/async/matrix/not_found_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 NotFoundError < Error; end
+  end
+end
+
+__END__
+  it "NotFoundError inherits from Error" do
+    Async::Matrix::NotFoundError.new("M_NOT_FOUND", "gone").should.be.kind_of Async::Matrix::Error
+  end

data/lib/async/matrix/notifier.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "async"
+require "async/condition"
+
+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
+          if result
+            break result
+          end
+
+          remaining = deadline - Time.now
+          if remaining <= 0
+            break result
+          end
+
+          begin
+            Async::Task.current.with_timeout(remaining) do
+              @condition.wait
+            end
+          rescue Async::TimeoutError
+            break yield
+          end
+        end
+      end
+    end
+  end
+end
+
+__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

data/lib/async/matrix/response_too_large_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 ResponseTooLargeError < Error; end
+  end
+end
+
+__END__
+  it "ResponseTooLargeError inherits from Error" do
+    Async::Matrix::ResponseTooLargeError.new("M_TOO_LARGE", "too big").should.be.kind_of Async::Matrix::Error
+  end