async-matrix 2.1.0-arm-linux → 3.0.0-arm-linux

data/lib/async/matrix/content.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+module Async
+  module Matrix
+    # Wraps the content object of a Matrix event, providing typed access to
+    # schema-defined properties via method_missing.
+    #
+    # Common fields like `msgtype`, `body`, and `membership` have dedicated
+    # accessors for convenience. Any other field defined in the event's schema
+    # (or present in the raw hash) is accessible as a method call:
+    #
+    #   content.msgtype      # => "m.text"
+    #   content.body         # => "hello"
+    #   content.membership   # => "join"
+    #   content.avatar_url   # => "mxc://example.org/abc"
+    #   content["custom"]    # => direct hash access for non-standard fields
+    #
+    class Content
+      attr_reader :msgtype, :body, :membership
+
+      def initialize(data)
+        @data       = data
+        @msgtype    = data["msgtype"]
+        @body       = data["body"]
+        @membership = data["membership"]
+      end
+
+      def to_h = @data
+      def to_s = @body.to_s
+      def to_str = to_s
+
+      # Direct hash access for any content field.
+      def [](key) = @data[key.to_s]
+
+      # Dynamic access to any content field present in the raw data.
+      def method_missing(name, *args)
+        key = name.to_s
+
+        if @data.key?(key)
+          @data[key]
+        else
+          nil
+        end
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @data.key?(name.to_s) || super
+      end
+    end
+  end
+end
+
+__END__
+  describe "Async::Matrix::Content" do
+    it "parses msgtype, body, and membership" do
+      content = Async::Matrix::Content.new({
+        "msgtype" => "m.text",
+        "body" => "hello",
+        "membership" => "join"
+      })
+      content.msgtype.should == "m.text"
+      content.body.should == "hello"
+      content.membership.should == "join"
+    end
+
+    it "handles missing fields gracefully" do
+      content = Async::Matrix::Content.new({})
+      content.msgtype.should.be.nil
+      content.body.should.be.nil
+      content.membership.should.be.nil
+    end
+
+    it "provides hash access via []" do
+      content = Async::Matrix::Content.new({"custom_field" => "value"})
+      content["custom_field"].should == "value"
+    end
+
+    it "provides dynamic access via method_missing" do
+      content = Async::Matrix::Content.new({
+        "avatar_url" => "mxc://example.org/abc",
+        "displayname" => "Alice"
+      })
+      content.avatar_url.should == "mxc://example.org/abc"
+      content.displayname.should == "Alice"
+    end
+
+    it "returns nil for unknown fields via method_missing" do
+      content = Async::Matrix::Content.new({})
+      content.nonexistent.should.be.nil
+    end
+
+    it "returns the raw hash via to_h" do
+      data = {"msgtype" => "m.text", "body" => "hi"}
+      content = Async::Matrix::Content.new(data)
+      content.to_h.should == data
+    end
+
+    it "responds to keys present in the data" do
+      content = Async::Matrix::Content.new({"avatar_url" => "mxc://x/y"})
+      content.respond_to?(:avatar_url).should == true
+      content.respond_to?(:nonexistent).should == false
+    end
+  end

data/lib/async/matrix/double_puppet_client.rb

@@ -29,7 +29,7 @@ end
 __END__
   describe "Async::Matrix::DoublePuppetClient" do
     def make_config
-      Async::Matrix::ApplicationService::Config.new({
+      Async::Matrix::Config.new({
         "homeserver" => { "address" => "http://localhost:8008", "domain" => "localhost" },
         "appservice" => { "as_token" => "as_token_value", "hs_token" => "hs_secret", "bot" => { "username" => "bot" } }
       })

data/lib/async/matrix/error.rb

@@ -14,13 +14,6 @@ module Async
         super(message)
       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
 
@@ -45,23 +38,3 @@ __END__
       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 "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 "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

data/lib/async/matrix/{application_service/error_response.rb → error_response.rb}

@@ -5,23 +5,23 @@
 
 module Async
   module Matrix
-    module ApplicationService
-      class ErrorResponse
-        attr_reader :errcode, :error
+    # 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
+      def initialize(data)
+        @errcode = data["errcode"]
+        @error   = data["error"]
       end
     end
   end
 end
 
 __END__
-  describe "Async::Matrix::ApplicationService::ErrorResponse" do
+  describe "Async::Matrix::ErrorResponse" do
     it "parses errcode and error" do
-      resp = Async::Matrix::ApplicationService::ErrorResponse.new({
+      resp = Async::Matrix::ErrorResponse.new({
         "errcode" => "M_FORBIDDEN",
         "error" => "Access denied"
       })
@@ -30,7 +30,7 @@ __END__
     end
 
     it "handles missing fields" do
-      resp = Async::Matrix::ApplicationService::ErrorResponse.new({})
+      resp = Async::Matrix::ErrorResponse.new({})
       resp.errcode.should.be.nil
       resp.error.should.be.nil
     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

@@ -49,19 +49,24 @@ module Async
 
         Console.debug(self) { "UPLOAD #{method} #{path} (#{content_type}, #{body.bytesize} bytes)" }
 
-        response = internet.call(method, url, headers, body)
+        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
+          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
+            status: status,
           )
         end
 
@@ -87,19 +92,24 @@ module Async
 
         Console.debug(self) { "DOWNLOAD #{path}" }
 
-        response = internet.call("GET", url, @auth_headers, nil)
+        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
+          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
+            status: status,
           )
         end
 
@@ -113,37 +123,38 @@ module Async
 
       private
 
-      def internet
-        @internet ||= Async::HTTP::Internet.new
-      end
+        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"
-            )
+        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
     end
   end
 end
@@ -151,7 +162,7 @@ end
 __END__
   describe "Async::Matrix::MediaClient" 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/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

@@ -37,17 +37,21 @@ module Async
 
         loop do
           result = yield
-          return result if result
+          if result
+            break result
+          end
 
           remaining = deadline - Time.now
-          return result if remaining <= 0
+          if remaining <= 0
+            break result
+          end
 
           begin
             Async::Task.current.with_timeout(remaining) do
               @condition.wait
             end
           rescue Async::TimeoutError
-            return yield
+            break yield
           end
         end
       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