async-matrix 2.0.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9cde8ca8632d237c371ec9a8a4ee8a422414b7e69222ca263ba505107d1dd234
-  data.tar.gz: 24583da0bbd5f8552990e5e1ce21d1b89dbdc41f7024da7d0377e5393665ce4e
+  metadata.gz: 65f191895135eb9d4f0580991c9beca1a319ed524c12b29d4f52c2cbff4aebc9
+  data.tar.gz: d3331bde0b5cea1d2e69081ab72747e72903f4c6977c9fb331e990ff0e1c31f4
 SHA512:
-  metadata.gz: f2d44ac4cbd06266e2988bb99af9de6051a0504e448ec8c730fc8978d5e91e023eae0f2dc01b7c45100344285b2e591237ffa349f72e8466dc634552947e7e74
-  data.tar.gz: aaaf8397d618585875a7447c7b46ca8e1d4802cda7dbbf98d6a3b66e9e3decda4a29d6f61ae9a04acaa12abaebb888d18137bc2efed91ec628b5eedd9a4332ca
+  metadata.gz: deffa5fa0c1bb2cbdf0ca642400bfa67c0b4bdc2839472a3923f3fc1aacccc060159b0b5d8646ffb8d544b577020a1035c07956fb884132ad2293ff78e27a3f1
+  data.tar.gz: 35de48c7bf9adb335031dbf8c9036947bea84f57cf8c0c3a4b22551b3be682c1df584eb9cc883c09c1ec109fd25772d96ad6d978c96385e7e87149301b032ff4

data/Cargo.lock

@@ -423,9 +423,9 @@ dependencies = [
 
 [[package]]
 name = "magnus"
-version = "0.8.2"
+version = "0.9.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3b36a5b126bbe97eb0d02d07acfeb327036c6319fd816139a49824a83b7f9012"
+checksum = "b9068710e00d21be762edca59b9c4c8946dbdb29820d4f76ad559afea07982c9"
 dependencies = [
  "magnus-macros",
  "rb-sys",
@@ -435,9 +435,9 @@ dependencies = [
 
 [[package]]
 name = "magnus-macros"
-version = "0.8.0"
+version = "0.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "47607461fd8e1513cb4f2076c197d8092d921a1ea75bd08af97398f593751892"
+checksum = "9dafde2eeb66f090e0f326112323eb8324b12cb32b5d1210e541d3df6b0ce77e"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -606,18 +606,18 @@ dependencies = [
 
 [[package]]
 name = "rb-sys"
-version = "0.9.128"
+version = "0.9.130"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "45ca28513560e56cfb79a62b1fce363c73af170a182024ce880c77ee9429920a"
+checksum = "02faf625bb10ba893e3ae620f19c9fb1b5f8fcae0fe4eb86bb3f2230fad75edb"
 dependencies = [
  "rb-sys-build",
 ]
 
 [[package]]
 name = "rb-sys-build"
-version = "0.9.128"
+version = "0.9.130"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ce04b2c55eff3a21aaa623fcc655d94373238e72cac6b3e1a3641ff31649f99a"
+checksum = "05be6f9c86fe5482808162826f6c047d093b3670582296c770de1d94f8066694"
 dependencies = [
  "bindgen",
  "lazy_static",

data/README.md

@@ -5,7 +5,9 @@
 [![License](https://img.shields.io/github/license/general-intelligence-systems/async-matrix)](https://github.com/general-intelligence-systems/async-matrix/blob/main/LICENSE)
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.3-red)](https://www.ruby-lang.org)
 
-Async-native [Matrix](https://matrix.org) Application Service SDK for Ruby. Built on the [Socketry](https://github.com/socketry) ecosystem (`async`, `async-http`, Falcon). No threads, no callbacks -- just fibers.
+Async-native [Matrix](https://matrix.org) protocol primitives for Ruby. Built on the [Socketry](https://github.com/socketry) ecosystem (`async`, `async-http`, Falcon). No threads, no callbacks -- just fibers.
+
+This gem is the protocol layer: a Client-Server API client, schema-validated events, media, and end-to-end encryption. The *server* side of a bridge or bot -- receiving transactions from a homeserver and dispatching events to handlers -- is [async-matrix-bridge](https://github.com/general-intelligence-systems/async-matrix-bridge), which builds on this gem.
 
 ## Usage
 
@@ -20,60 +22,17 @@ gem "async-matrix"
 ## Quick Start
 
 ```ruby
-# config.ru
 require "async/matrix"
 
-config = Async::Matrix::ApplicationService::Config.load("config/appservice.yml")
+config = Async::Matrix::Config.load("config/appservice.yml")
 client = Async::Matrix::Client.new(config)
 
-bot = Async::Matrix::ApplicationService::Bot.new(client) do
-  on "m.room.member" do |event|
-    join_room(event.room_id) if event.content.membership == "invite"
-  end
-
-  on "m.room.message", msgtype: "m.text", not_from: :self do |event|
-    send_notice event.room_id, "Echo: #{event.content.body}"
-  end
-end
-
-app = Async::Matrix::ApplicationService::Server.new(
-  hs_token: config.appservice.hs_token,
-  client:   client
-) do
-  dispatch bot
+Async do
+  client.join_room("!room:example.org")
+  client.send_notice("!room:example.org", "Hello from a fiber")
 end
-
-run app
-```
-
-```bash
-falcon serve --bind http://0.0.0.0:9292
 ```
 
-A complete working example with Docker Compose and Synapse lives in [`examples/echo_bot/`](https://github.com/general-intelligence-systems/async-matrix/tree/main/examples/echo_bot).
-
-## Handlers
-
-Any object that responds to `#event_types` and `#call(event)` is a handler. Use this when you need more control than the Bot DSL provides.
-
-```ruby
-class Echo
-  def initialize(client) = @client = client
-
-  def event_types = ["m.room.message"]
-
-  def call(event)
-    return unless event.content&.msgtype == "m.text"
-    return unless event.sender != @client.config.bot_mxid
-    @client.send_notice(event.room_id, "Echo: #{event.content.body}")
-  end
-end
-
-app.dispatch(Echo.new(client))
-```
-
-Dispatch is fault-tolerant -- one handler raising won't take down the rest.
-
 ## Client
 
 ```ruby
@@ -93,40 +52,56 @@ client.api.createRoom.post(name: "Pub")
 client.api.rooms("!room:ex.com").messages.get(dir: "b", limit: 10)
 ```
 
-All methods are fiber-safe with automatic connection pooling.
+Binary routes (upload, download, thumbnail) are detected and dispatched to a dedicated `MediaClient`, so raw bytes never pass through JSON encoding.
+
+All methods are fiber-safe with automatic connection pooling. The client retries 502/503/504 with exponential backoff and full jitter, honours `Retry-After` on 429, and caps response bodies while streaming them.
+
+## Events
+
+```ruby
+event = Async::Matrix::Schema.parse(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
+```
+
+Events validate against the official Matrix event JSON schemas, bundled into the gem.
 
 ## Configuration
 
-Create `config/appservice.yml` for your bot:
+`Async::Matrix::Config` loads a YAML file (or a plain hash) and exposes it through dot notation. `Client` reads `homeserver.address` and `appservice.as_token`; it ignores the rest.
 
 ```yaml
+# config/appservice.yml
 homeserver:
   address: "http://synapse:8008"
   domain: "localhost"
 
 appservice:
   as_token: "your-appservice-token"
-  hs_token: "your-homeserver-token"
   bot:
     username: "bot"
 ```
 
-You'll also need a [`registration.yml`](https://spec.matrix.org/latest/application-service-api/#registration) registered with your homeserver. See the [echo bot example](https://github.com/general-intelligence-systems/async-matrix/tree/main/examples/echo_bot) for a working template.
-
-Override the config path at runtime:
-
-```bash
-APPSERVICE_CONFIG=/etc/bot/appservice.yml falcon serve
+```ruby
+config = Async::Matrix::Config.load("config/appservice.yml")
+config.homeserver.address   # => "http://synapse:8008"
+config.bot_mxid             # => "@bot:localhost"
 ```
 
+It validates nothing by default. A subclass adds validation by overriding `.validate!` -- which is how async-matrix-bridge layers a mautrix bridgev2 JSON Schema suite on top without reimplementing the loading.
+
 ## Built With
 
 - [async](https://github.com/socketry/async) -- fiber-based concurrency framework
 - [async-http](https://github.com/socketry/async-http) -- HTTP client/server with connection pooling
-- [falcon](https://github.com/socketry/falcon) -- async Rack-compatible web server
 - [json_schemer](https://github.com/davishmcclurg/json_schemer) -- JSON Schema validation
 - [scampi](https://github.com/general-intelligence-systems/scampi) -- inline co-located test framework
 - [string_builder](https://github.com/general-intelligence-systems/string_builder) -- method-chain string builder
+- [vodozemac](https://github.com/matrix-org/vodozemac) -- Olm/Megolm, via a native Rust binding
 
 ## License
 

data/ext/async_matrix_e2ee/Cargo.toml

@@ -11,7 +11,13 @@ crate-type = ["cdylib"]
 [dependencies]
 # magnus 0.8 is required for Ruby 4.0 C-API compatibility (0.7 fails to compile
 # against Ruby 4.0: rb_fiber_raise pointer mutability + RTypedData.typed_flag).
-magnus = "0.8"
+#
+# 0.9 is required to cross-compile for arm-linux-musl. On 32-bit musl, bindgen
+# renders timespec's padding around tv_nsec as bitfield members, so magnus 0.8's
+# `From<Timespec> for timespec` struct literal fails with E0063 (missing fields
+# `_bitfield_1`, `_bitfield_align_1`). 0.9 builds the struct with mem::zeroed
+# and assigns the two fields instead.
+magnus = "0.9"
 
 # vodozemac 0.10.0 (2026-04-13), default features (libolm-compat).
 #

data/ext/async_matrix_e2ee/src/lib.rs

@@ -20,8 +20,9 @@ use vodozemac::olm::{
     SessionConfig as OlmSessionConfig, SessionPickle,
 };
 use vodozemac::megolm::{
-    GroupSession as MegolmGroupSession, GroupSessionPickle, InboundGroupSession as MegolmInbound,
-    InboundGroupSessionPickle, MegolmMessage, SessionConfig as MegolmSessionConfig, SessionKey,
+    ExportedSessionKey, GroupSession as MegolmGroupSession, GroupSessionPickle,
+    InboundGroupSession as MegolmInbound, InboundGroupSessionPickle, MegolmMessage,
+    SessionConfig as MegolmSessionConfig, SessionKey,
 };
 
 // --- helpers ---------------------------------------------------------------
@@ -236,6 +237,27 @@ impl InboundGroupSession {
         ))))
     }
 
+    /// Build from a base64 **exported** session key.
+    ///
+    /// This is the format room keys travel in outside of `m.room_key`: server-side
+    /// key backup (`m.megolm_backup.v1.curve25519-aes-sha2`) and
+    /// `m.forwarded_room_key` both carry an `ExportedSessionKey`, which is
+    /// version 1 and carries no signature — so `new` (which requires a signed
+    /// version 2 `SessionKey`) cannot accept them. Without this, a client can
+    /// never read history it did not receive a live `m.room_key` for.
+    ///
+    /// The resulting session is NOT signature-verified, because an exported key
+    /// has no signature to verify. That is inherent to the format: the sender
+    /// identity of such a session is only as trustworthy as whoever handed it
+    /// over, which is why the spec treats backup-restored keys as unverified.
+    fn import(exported_key: String) -> Result<Self, Error> {
+        let key = ExportedSessionKey::from_base64(&exported_key).map_err(rt_err)?;
+        Ok(InboundGroupSession(RefCell::new(MegolmInbound::import(
+            &key,
+            MegolmSessionConfig::version_1(),
+        ))))
+    }
+
     fn session_id(&self) -> String {
         self.0.borrow().session_id()
     }
@@ -244,6 +266,19 @@ impl InboundGroupSession {
         self.0.borrow().first_known_index()
     }
 
+    /// Export this session at `index`, base64, for uploading to key backup or
+    /// forwarding to another device. Returns nil when the ratchet has already
+    /// moved past `index` and can no longer produce a key for it — megolm
+    /// ratchets forward only, so an earlier index is unrecoverable by design.
+    fn export_at(&self, index: u32) -> Option<String> {
+        self.0.borrow_mut().export_at(index).map(|key| key.to_base64())
+    }
+
+    /// Export at the earliest index this session can still reach.
+    fn export_at_first_known_index(&self) -> String {
+        self.0.borrow().export_at_first_known_index().to_base64()
+    }
+
     /// Decrypts a base64 megolm message; returns `[plaintext, message_index]`.
     fn decrypt(&self, message: String) -> Result<(String, u32), Error> {
         let msg = MegolmMessage::from_base64(&message).map_err(rt_err)?;
@@ -316,11 +351,17 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
 
     let inbound = namespace.define_class("InboundGroupSession", ruby.class_object())?;
     inbound.define_singleton_method("new", function!(InboundGroupSession::new, 1))?;
+    inbound.define_singleton_method("import", function!(InboundGroupSession::import, 1))?;
     inbound.define_singleton_method("from_pickle", function!(InboundGroupSession::from_pickle, 2))?;
     inbound.define_method("session_id", method!(InboundGroupSession::session_id, 0))?;
     inbound.define_method("first_known_index", method!(InboundGroupSession::first_known_index, 0))?;
     inbound.define_method("decrypt", method!(InboundGroupSession::decrypt, 1))?;
     inbound.define_method("pickle", method!(InboundGroupSession::pickle, 1))?;
+    inbound.define_method("export_at", method!(InboundGroupSession::export_at, 1))?;
+    inbound.define_method(
+        "export_at_first_known_index",
+        method!(InboundGroupSession::export_at_first_known_index, 0),
+    )?;
 
     namespace.define_module_function("verify_signature", function!(verify_signature, 3))?;
 

data/lib/async/matrix/api/chain.rb

@@ -108,122 +108,148 @@ module Async
 
         private
 
-        def execute(method, body: nil, query: nil, content_type: nil, max_retries: nil)
-          segments = _rewrite_version(_build_full_segments)
-          result = @path_tree.match(segments, method)
-
-          if !result[:valid]
-            path = "/" + segments.join("/")
-            available = result[:methods]
-            if available.empty?
-              ::Kernel.raise ::Async::Matrix::InvalidEndpointError.new(
-                "INVALID_ENDPOINT",
-                "No Matrix API endpoint matches: #{method} #{path}"
-              )
-            else
-              ::Kernel.raise ::Async::Matrix::InvalidEndpointError.new(
-                "METHOD_NOT_ALLOWED",
-                "#{method} not allowed for #{path}. Valid methods: #{available.map(&:upcase).join(", ")}"
-              )
+          def execute(method, body: nil, query: nil, content_type: nil, max_retries: nil)
+            segments = _rewrite_version(_build_full_segments)
+            result = @path_tree.match(segments, method)
+
+            if !result[:valid]
+              path = "/" + segments.join("/")
+              available = result[:methods]
+              if available.empty?
+                ::Kernel.raise ::Async::Matrix::InvalidEndpointError.new(
+                  "INVALID_ENDPOINT",
+                  "No Matrix API endpoint matches: #{method} #{path}",
+                )
+              else
+                ::Kernel.raise ::Async::Matrix::InvalidEndpointError.new(
+                  "METHOD_NOT_ALLOWED",
+                  "#{method} not allowed for #{path}. Valid methods: #{available.map(&:upcase).join(", ")}",
+                )
+              end
             end
-          end
 
-          path = "/" + segments.map { |s| _encode(s) }.join("/")
+            path = "/" + segments.map { |s| _encode(s) }.join("/")
 
-          if query && !query.empty?
-            qs = query.map { |k, v| "#{_encode(k.to_s)}=#{_encode(v.to_s)}" }.join("&")
-            path = "#{path}?#{qs}"
-          end
+            if query && !query.empty?
+              qs = query.map { |k, v| "#{_encode(k.to_s)}=#{_encode(v.to_s)}" }.join("&")
+              path = "#{path}?#{qs}"
+            end
 
-          if _binary_route?(segments)
-            case method
-            when "GET"
-              @client.media_client.download(path)
-            when "POST"
-              @client.media_client.upload("POST", path, body, content_type || "application/octet-stream")
-            when "PUT"
-              @client.media_client.upload("PUT", path, body, content_type || "application/octet-stream")
+            if _binary_route?(segments)
+              case method
+              when "GET"
+                @client.media_client.download(path)
+              when "POST"
+                @client.media_client.upload(
+                  "POST",
+                  path,
+                  body,
+                  content_type || "application/octet-stream",
+                )
+              when "PUT"
+                @client.media_client.upload(
+                  "PUT",
+                  path,
+                  body,
+                  content_type || "application/octet-stream",
+                )
+              end
+            else
+              if max_retries
+                retry_opts = {max_retries: max_retries}
+            else
+              retry_opts = {}
             end
-          else
-            retry_opts = max_retries ? {max_retries: max_retries} : {}
-            case method
-            when "GET"
-              @client.get(path, **retry_opts)
-            when "POST"
-              @client.post(path, body || {}, **retry_opts)
-            when "PUT"
-              @client.put(path, body || {}, **retry_opts)
-            when "DELETE"
-              @client.request("DELETE", path, nil, **retry_opts)
-            when "PATCH"
-              @client.request("PATCH", path, body || {}, **retry_opts)
+              case method
+              when "GET"
+                @client.get(path, **retry_opts)
+              when "POST"
+                @client.post(path, body || {}, **retry_opts)
+              when "PUT"
+                @client.put(path, body || {}, **retry_opts)
+              when "DELETE"
+                @client.request(
+                  "DELETE",
+                  path,
+                  nil,
+**retry_opts,
+                )
+              when "PATCH"
+                @client.request(
+                  "PATCH",
+                  path,
+                  body || {},
+**retry_opts,
+                )
+              end
             end
           end
-        end
 
         # Rewrites version segments for endpoints that only exist at
         # a different version than the gateway prefix provides.
         #   _matrix/media/v3/create        → _matrix/media/v1/create
         #   _matrix/client/v3/media/...    → _matrix/client/v1/media/...
-        def _rewrite_version(segments)
-          # POST /_matrix/media/v1/create (only exists at v1)
-          if segments.length == 4 &&
-             segments[0] == "_matrix" && segments[1] == "media" &&
-             segments[2] == "v3" && segments[3] == "create"
-            segments = segments.dup
-            segments[2] = "v1"
-            return segments
-          end
-
-          # Authenticated media endpoints live at /_matrix/client/v1/media/...
-          if segments.length >= 5 &&
-             segments[0] == "_matrix" && segments[1] == "client" &&
-             segments[2] == "v3" && segments[3] == "media"
-            segments = segments.dup
-            segments[2] = "v1"
-            return segments
+          def _rewrite_version(segments)
+            # POST /_matrix/media/v1/create (only exists at v1)
+            media_create = segments.length == 4 &&
+                           segments[0] == "_matrix" && segments[1] == "media" &&
+                           segments[2] == "v3" && segments[3] == "create"
+
+            # Authenticated media endpoints live at /_matrix/client/v1/media/...
+            client_media = segments.length >= 5 &&
+                           segments[0] == "_matrix" && segments[1] == "client" &&
+                           segments[2] == "v3" && segments[3] == "media"
+
+            if media_create || client_media
+              segments.dup.tap { |rewritten| rewritten[2] = "v1" }
+            else
+              segments
+            end
           end
 
-          segments
-        end
-
-        def _binary_route?(segments)
-          BINARY_ROUTES.any? do |pattern|
-            parts = pattern.split("/")
-            next false unless parts.length == segments.length + 1 # leading slash adds empty element
-            parts.shift # remove empty string from leading /
-            parts.length == segments.length &&
-              parts.zip(segments).all? { |pat, seg| pat == "*" || pat == seg }
+          def _binary_route?(segments)
+            BINARY_ROUTES.any? do |pattern|
+              parts = pattern.split("/")
+              unless parts.length == segments.length + 1
+                next false
+              end # leading slash adds empty element
+              parts.shift # remove empty string from leading /
+              parts.length == segments.length &&
+                parts.zip(segments).all? { |pat, seg| pat == "*" || pat == seg }
+            end
           end
-        end
 
-        def _extract_query_params(kwargs)
-          query = {}
-          kwargs.each_key do |k|
-            key_s = k.to_s
-            if key_s.start_with?("?")
-              query[key_s[1..]] = kwargs.delete(k)
+          def _extract_query_params(kwargs)
+            query = {}
+            kwargs.each_key do |k|
+              key_s = k.to_s
+              if key_s.start_with?("?")
+                query[key_s[1..]] = kwargs.delete(k)
+              end
             end
+            query.empty? ? nil : query
           end
-          query.empty? ? nil : query
-        end
 
-        def _build_full_segments
-          chain_segments = []
-          @buffer.each do |name, args|
-            chain_segments << name
-            next if args.nil? || args.empty?
-            args.each do |arg|
-              next if arg.is_a?(::Hash)
-              chain_segments << arg.to_s
+          def _build_full_segments
+            chain_segments = []
+            @buffer.each do |name, args|
+              chain_segments << name
+              if args.nil? || args.empty?
+                next
+              end
+              args.each do |arg|
+                if arg.is_a?(::Hash)
+                  next
+                end
+                chain_segments << arg.to_s
+              end
             end
+            @prefix + chain_segments
           end
-          @prefix + chain_segments
-        end
 
-        def _encode(value)
-          ::ERB::Util.url_encode(value.to_s)
-        end
+          def _encode(value)
+            ::ERB::Util.url_encode(value.to_s)
+          end
       end
     end
   end

data/lib/async/matrix/api/concat.rb

@@ -24,36 +24,42 @@ module Async
         end
 
         def initialize(buffer)
-          @buffer = buffer.respond_to?(:to_a) ? buffer.to_a : buffer
+          if buffer.respond_to?(:to_a)
+            @buffer = buffer.to_a
+          else
+            @buffer = buffer
+          end
         end
 
         def segments
-          result = []
-
-          @buffer.each do |entry|
-            case entry
-            when Symbol
-              # :slash, :dash -- ignore in URL context
-              next
-            when Array
-              name, args = entry
-              next unless name.is_a?(String)
+          [].tap do |result|
+            @buffer.each do |entry|
+              case entry
+              when Symbol
+                # :slash, :dash -- ignore in URL context
+                next
+              when Array
+                name, args = entry
+                unless name.is_a?(String)
+                  next
+                end
 
-              if args.nil? || args.empty?
-                # Bare method -> path segment
-                result << name
-              else
-                # Method with args -> method name as segment, then each arg as segment
-                result << name
-                args.each do |arg|
-                  next if arg.is_a?(Hash) # kwargs are not path segments
-                  result << arg.to_s
+                if args.nil? || args.empty?
+                  # Bare method -> path segment
+                  result << name
+                else
+                  # Method with args -> method name as segment, then each arg as segment
+                  result << name
+                  args.each do |arg|
+                    if arg.is_a?(Hash)
+                      next
+                    end # kwargs are not path segments
+                    result << arg.to_s
+                  end
                 end
               end
             end
           end
-
-          result
         end
       end
     end