async-matrix 2.1.0 → 3.0.0

data/lib/async/matrix/config.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "forwardable"
+require "yaml"
+require "pathname"
+require_relative "config/vivify"
+
+module Async
+  module Matrix
+    # Dot-notation access to a Matrix service's YAML configuration.
+    #
+    # {Client} only reads two fields — `homeserver.address` and
+    # `appservice.as_token` — so this class validates nothing: it vivifies
+    # whatever hash (or YAML file) it is handed and exposes every nested field
+    # as a method call.
+    #
+    #   config = Config.load("config/appservice.yml")
+    #   config.homeserver.address      # => "http://synapse:8008"
+    #   config.appservice.as_token     # => "secret..."
+    #   config.appservice.bot.username # => "bot"
+    #   config.bot_mxid                # => "@bot:localhost"
+    #
+    # A subclass layers validation on by overriding {.validate!}; that is how
+    # async-matrix-bridge's Config applies the mautrix bridgev2 JSON Schema
+    # suite without reimplementing any of the loading below.
+    class Config
+      extend Forwardable
+
+      # Delegate every top-level config section to the vivified data hash. An
+      # explicit list, not a method_missing forward: a typo'd section should
+      # raise NoMethodError rather than autovivify into an empty hash.
+      def_delegators :@data,
+        :network,
+        :bridge,
+        :database,
+        :homeserver,
+        :appservice,
+        :matrix,
+        :analytics,
+        :provisioning,
+        :public_media,
+        :direct_media,
+        :backfill,
+        :double_puppet,
+        :encryption,
+        :logging,
+        :management_room_texts,
+        :env_config_prefix
+
+      def initialize(data)
+        self.class.validate!(data)
+        @data = Vivify.deep_vivify(data)
+      end
+
+      # Load a YAML config file from disk.
+      def self.load(path)
+        unless File.exist?(path)
+          raise Async::Matrix::NotFoundError.new(
+            "M_NOT_FOUND",
+            "Config not found: #{path}",
+          )
+        end
+
+        data = YAML.safe_load_file(path, permitted_classes: [Symbol])
+        new(data)
+      end
+
+      # Validation hook, called with the raw (string-keyed) hash before it is
+      # vivified. A no-op here; subclasses override it to raise on bad input,
+      # and may mutate `data` to insert defaults.
+      def self.validate!(data)
+        nil
+      end
+
+      # Convenience: derive the bot's full Matrix ID from
+      # appservice.bot.username + homeserver.domain.
+      def bot_mxid
+        "@#{appservice.bot.username}:#{homeserver.domain}"
+      end
+    end
+  end
+end
+
+__END__
+  require "tempfile"
+
+  describe "Async::Matrix::Config" do
+    def minimal_data
+      {
+        "homeserver" => {
+          "address" => "http://localhost:8008",
+          "domain"  => "localhost",
+        },
+        "appservice" => {
+          "as_token" => "as_secret_token_value",
+          "hs_token" => "hs_secret_token_value",
+          "bot"      => {"username" => "bot"},
+        },
+      }
+    end
+
+    it "exposes top-level sections" do
+      config = Async::Matrix::Config.new(minimal_data)
+      config.homeserver.address.should == "http://localhost:8008"
+      config.homeserver.domain.should == "localhost"
+      config.appservice.as_token.should == "as_secret_token_value"
+      config.appservice.hs_token.should == "hs_secret_token_value"
+      config.appservice.bot.username.should == "bot"
+    end
+
+    it "derives bot_mxid from appservice.bot.username and homeserver.domain" do
+      Async::Matrix::Config.new(minimal_data).bot_mxid.should == "@bot:localhost"
+    end
+
+    it "provides dot-notation access to deeply nested fields" do
+      data = minimal_data.merge(
+        "encryption" => {
+          "allow" => true,
+          "rotation" => {"messages" => 200},
+        },
+      )
+      config = Async::Matrix::Config.new(data)
+      config.encryption.allow.should == true
+      config.encryption.rotation.messages.should == 200
+    end
+
+    it "autovivifies missing optional sections as empty hashes" do
+      config = Async::Matrix::Config.new(minimal_data)
+      config.analytics.should.be.kind_of Hash
+      config.analytics.should.be.empty?
+    end
+
+    it "raises NoMethodError for sections it does not delegate" do
+      config = Async::Matrix::Config.new(minimal_data)
+      lambda { config.bogus }.should.raise(NoMethodError)
+    end
+
+    it "validates nothing by default" do
+      lambda { Async::Matrix::Config.new({}) }.should.not.raise
+    end
+
+    it "loads from a YAML file" do
+      file = Tempfile.new(["config", ".yml"])
+      file.write(<<~YAML)
+        homeserver:
+          address: "http://localhost:8008"
+          domain: "localhost"
+        appservice:
+          as_token: "as123_secret"
+          hs_token: "hs456_secret"
+          bot:
+            username: "testbot"
+      YAML
+      file.close
+
+      config = Async::Matrix::Config.load(file.path)
+      config.homeserver.address.should == "http://localhost:8008"
+      config.bot_mxid.should == "@testbot:localhost"
+    ensure
+      file.unlink
+    end
+
+    it "raises NotFoundError for a missing file" do
+      lambda {
+        Async::Matrix::Config.load("/nonexistent/path.yml")
+      }.should.raise(Async::Matrix::NotFoundError)
+    end
+
+    it "runs the validate! hook a subclass overrides" do
+      strict = Class.new(Async::Matrix::Config) do
+        def self.validate!(data)
+          unless data.key?("homeserver")
+            raise Async::Matrix::BadJsonError.new("M_BAD_JSON", "no homeserver")
+          end
+        end
+      end
+
+      lambda { strict.new({}) }.should.raise(Async::Matrix::BadJsonError)
+      strict.new(minimal_data).homeserver.domain.should == "localhost"
+    end
+  end

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