async-matrix 3.0.0-arm-linux-musl

data/lib/async/matrix/config/vivify.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+module Async
+  module Matrix
+    class Config
+      # Mixin that gives a Hash dot-notation accessors with autovivification.
+      #
+      # Not applied globally — only extended onto the validated config hash
+      # and its nested children so the rest of the world is unaffected.
+      #
+      #   h = {}.extend(Vivify)
+      #   h.foo.bar.baz = 42
+      #   h  # => { foo: { bar: { baz: 42 } } }
+      #
+      module Vivify
+        def method_missing(name, *args)
+          key = name.to_s
+
+          if key.end_with?("=")
+            self[key.chomp("=").to_sym] = args.first
+          elsif key?(name.to_sym)
+            self[name.to_sym]
+          elsif key.start_with?("to_")
+            super
+          else
+            self[name.to_sym] = {}.extend(Vivify)
+          end
+        end
+
+        def respond_to_missing?(name, _priv = false)
+          name.to_s.end_with?("=") || key?(name.to_sym) || super
+        end
+
+        # Recursively symbolize keys and extend every nested Hash with Vivify.
+        #
+        # Call this on the raw (string-keyed) hash that comes out of
+        # YAML.safe_load before wrapping it in Config.
+        def self.deep_vivify(obj)
+          case obj
+          when Hash
+            result = {}
+            obj.each { |k, v| result[k.to_s.to_sym] = deep_vivify(v) }
+            result.extend(Vivify)
+          when Array
+            obj.map { |v| deep_vivify(v) }
+          else
+            obj
+          end
+        end
+      end
+    end
+  end
+end
+
+__END__
+  V = Async::Matrix::Config::Vivify
+
+  describe "Vivify" do
+    it "provides dot-notation read access to symbol keys" do
+      h = { foo: "bar" }.extend(V)
+      h.foo.should == "bar"
+    end
+
+    it "provides dot-notation write access" do
+      h = {}.extend(V)
+      h.foo = 42
+      h[:foo].should == 42
+    end
+
+    it "autovivifies missing keys as vivified hashes" do
+      h = {}.extend(V)
+      h.a.b.c = "deep"
+      h[:a][:b][:c].should == "deep"
+    end
+
+    it "delegates to_* methods to super (no autovivify)" do
+      h = { x: 1 }.extend(V)
+      h.to_a.should == [[:x, 1]]
+    end
+  end
+
+  describe "Vivify.deep_vivify" do
+    it "symbolizes string keys" do
+      result = V.deep_vivify({"a" => 1})
+      result[:a].should == 1
+    end
+
+    it "recursively vivifies nested hashes" do
+      result = V.deep_vivify({"outer" => {"inner" => "val"}})
+      result.outer.inner.should == "val"
+    end
+
+    it "vivifies hashes inside arrays" do
+      result = V.deep_vivify({"list" => [{"name" => "x"}]})
+      result.list.first.name.should == "x"
+    end
+
+    it "passes scalars through unchanged" do
+      result = V.deep_vivify({"n" => 42, "s" => "hi", "b" => true})
+      result.n.should == 42
+      result.s.should == "hi"
+      result.b.should == true
+    end
+  end

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/connection.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "async/http"
+
+module Async
+  module Matrix
+    module Connection
+      include Async::HTTP::Protocol::HTTP2::Connection
+    end
+  end
+end
+
+__END__
+  it "includes Async::HTTP::Protocol::HTTP2::Connection" do
+    Async::Matrix::Connection.ancestors.should.include Async::HTTP::Protocol::HTTP2::Connection
+  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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require_relative "client"
+
+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
+
+__END__
+  describe "Async::Matrix::DoublePuppetClient" do
+    def make_config
+      Async::Matrix::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

data/lib/async/matrix/e2ee.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+# Loads the native vodozemac binding (ext/async_matrix_e2ee) and namespaces the
+# Olm/Megolm primitives under Async::Matrix::E2EE.
+#
+# The native classes (Account, Session, GroupSession, InboundGroupSession) and
+# the module function verify_signature are defined by the Rust #[magnus::init].
+# This file only locates and requires the compiled object.
+#
+#   account = Async::Matrix::E2EE::Account.new
+#   account.curve25519_key            # => base64 string
+#   group = Async::Matrix::E2EE::GroupSession.new
+#   msg   = group.encrypt("hello")    # => base64 megolm message
+#   inbound = Async::Matrix::E2EE::InboundGroupSession.new(group.session_key)
+#   inbound.decrypt(msg)              # => ["hello", 0]
+
+module Async
+  module Matrix
+    module E2EE
+    end
+  end
+end
+
+# Precompiled ("fat") gems ship one .so per Ruby minor version under a versioned
+# subdir (lib/async/matrix/3.3/async_matrix_e2ee.so). A locally source-compiled
+# build lands flat, alongside this file. Try the versioned path first, then fall
+# back to the flat one.
+begin
+  RUBY_VERSION =~ /(\d+\.\d+)/
+  require_relative "#{Regexp.last_match(1)}/async_matrix_e2ee"
+rescue LoadError
+  require_relative "async_matrix_e2ee"
+end
+
+__END__
+  describe "Async::Matrix::E2EE" do
+    it "exposes account identity keys as base64" do
+      account = Async::Matrix::E2EE::Account.new
+      account.curve25519_key.should.be.kind_of String
+      account.ed25519_key.should.be.kind_of String
+      account.curve25519_key.length.should.be > 0
+    end
+
+    it "round-trips a megolm group message" do
+      group   = Async::Matrix::E2EE::GroupSession.new
+      inbound = Async::Matrix::E2EE::InboundGroupSession.new(group.session_key)
+
+      message = group.encrypt("hello world")
+      plaintext, index = inbound.decrypt(message)
+
+      plaintext.should == "hello world"
+      index.should == 0
+      inbound.session_id.should == group.session_id
+    end
+
+    it "imports an exported session key" do
+      # The path room keys take out of server-side key backup and out of
+      # m.forwarded_room_key. Without .import these are unusable, and a client
+      # can never read history it did not get a live m.room_key for.
+      group   = Async::Matrix::E2EE::GroupSession.new
+      inbound = Async::Matrix::E2EE::InboundGroupSession.new(group.session_key)
+      message = group.encrypt("restored from backup")
+
+      exported = inbound.export_at_first_known_index
+      restored = Async::Matrix::E2EE::InboundGroupSession.import(exported)
+
+      restored.session_id.should == group.session_id
+      restored.decrypt(message).first.should == "restored from backup"
+    end
+
+    it "rejects an exported key passed to .new, which requires a signature" do
+      # .new takes a version-2 SessionKey and verifies its signature; an exported
+      # key is version 1 and unsigned, so it must go through .import instead.
+      group    = Async::Matrix::E2EE::GroupSession.new
+      inbound  = Async::Matrix::E2EE::InboundGroupSession.new(group.session_key)
+      exported = inbound.export_at_first_known_index
+
+      lambda {
+        Async::Matrix::E2EE::InboundGroupSession.new(exported)
+      }.should.raise(RuntimeError)
+    end
+
+    it "exports at a given message index" do
+      group   = Async::Matrix::E2EE::GroupSession.new
+      inbound = Async::Matrix::E2EE::InboundGroupSession.new(group.session_key)
+      3.times { |i| group.encrypt("msg #{i}") }
+
+      Async::Matrix::E2EE::InboundGroupSession
+        .import(inbound.export_at(0))
+        .first_known_index.should == 0
+    end
+
+    it "round-trips an olm 1:1 message" do
+      alice = Async::Matrix::E2EE::Account.new
+      bob   = Async::Matrix::E2EE::Account.new
+      bob.generate_one_time_keys(1)
+      bob_otk = bob.one_time_keys.values.first
+
+      outbound = alice.create_outbound_session(bob.curve25519_key, bob_otk)
+      type, body = outbound.encrypt("yo g")
+      type.should == 0 # pre-key message
+
+      session, plaintext = bob.create_inbound_session(alice.curve25519_key, body)
+      plaintext.should == "yo g"
+
+      reply_type, reply_body = session.encrypt("hello back")
+      outbound.decrypt(reply_type, reply_body).should == "hello back"
+    end
+
+    it "verifies a valid ed25519 signature and rejects a bad one" do
+      account   = Async::Matrix::E2EE::Account.new
+      signature = account.sign("payload")
+
+      Async::Matrix::E2EE.verify_signature(account.ed25519_key, "payload", signature).should == true
+      Async::Matrix::E2EE.verify_signature(account.ed25519_key, "tampered", signature).should == false
+    end
+
+    it "survives a pickle round-trip" do
+      key   = "0" * 32
+      group = Async::Matrix::E2EE::GroupSession.new
+      pickled = group.pickle(key)
+
+      restored = Async::Matrix::E2EE::GroupSession.from_pickle(pickled, key)
+      restored.session_id.should == group.session_id
+    end
+  end

data/lib/async/matrix/endpoint.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "json"
+require "async/http"
+
+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
+end
+
+__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