async-matrix 2.0.1-x86_64-linux → 3.0.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bcb270a5870317bcf2f520822c51be7ec986895b42fe393399a060cc2973ed61
-  data.tar.gz: 89272c6298430e6e1652e22a0d9db6d932c19f6796522053209ea5d57220a811
+  metadata.gz: 4fe4d4e0b7fc49cc1bfbe641fed7a4ed1430555973a1db1c08a27bec5765d591
+  data.tar.gz: f9d721081238308c948a735039944f61fa0f4878f91efa848179ee7527307559
 SHA512:
-  metadata.gz: 6873d7693f6acda23bcae84eb23ece21e01e036e3250655373b3f2cd5c53874c3d1b0429789db311128194902fcb13b0f22591db275b3ddc2a9505c0ad6ddaa2
-  data.tar.gz: 425bfcef07fed7045781295134bb1606502bd76642037d6ac8f0a53546122aad3d859257964a979c08795d56afab99bea4d81ded8cfa9c528a053868d37e35ba
+  metadata.gz: 1a0b60b1edb4cc6be2e33ac158c727c26ffcfcc2d8083a1b6f96a355112d622c126f26206db064c9ae91ed2c925c65d6e1c518883362219476fd53ebff9e6854
+  data.tar.gz: 77dccb7126f368a5d5c0fe713180ad6d213ff5beb7542c26edf2c5ad8b8a993e60c5ff866e9f59b2a23da47937787a9bb26044c3cf2420d6024f2b04779e0e99

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/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

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

@@ -22,7 +22,13 @@ module Async
       class PathTree
         SCHEMA_DIR = Pathname.new(File.expand_path("../../../../data/matrix-spec/api/client-server", __dir__))
 
-        Node = Struct.new(:children, :wildcard, :methods, :operation_ids, keyword_init: true) do
+        Node = Struct.new(
+          :children,
+          :wildcard,
+          :methods,
+          :operation_ids,
+          keyword_init: true,
+        ) do
           def initialize(**)
             super
             self.children ||= {}
@@ -39,34 +45,46 @@ module Async
 
         # Load all OpenAPI schemas from data/ and build the tree.
         def self.load(schema_dir: SCHEMA_DIR)
-          tree = new
-          Pathname.glob(schema_dir / "*.yaml").each do |path|
-            tree.load_schema(path)
+          new.tap do |tree|
+            Pathname.glob(schema_dir / "*.yaml").each do |path|
+              tree.load_schema(path)
+            end
           end
-          tree
         end
 
         # Parse a single OpenAPI YAML file and insert its paths into the tree.
         def load_schema(path)
           doc = YAML.safe_load(File.read(path), permitted_classes: [Symbol], aliases: true)
-          return unless doc.is_a?(Hash)
-
-          base_path = extract_base_path(doc)
-          paths = doc["paths"]
-          return unless paths.is_a?(Hash)
-
-          paths.each do |path_template, methods_hash|
-            next unless methods_hash.is_a?(Hash)
-
-            # Build full path: basePath + path_template
-            full_path = "#{base_path}#{path_template.strip}"
-            segments = full_path.split("/").reject(&:empty?)
-
-            methods_hash.each do |method, operation|
-              next unless %w[get post put delete patch head].include?(method)
-              operation_id = operation.is_a?(Hash) ? operation["operationId"] : nil
-              insert(segments, method, operation_id)
+          if doc.is_a?(Hash)
+            base_path = extract_base_path(doc)
+            paths = doc["paths"]
+            if paths.is_a?(Hash)
+              paths.each do |path_template, methods_hash|
+                unless methods_hash.is_a?(Hash)
+                  next
+                end
+
+                # Build full path: basePath + path_template
+                full_path = "#{base_path}#{path_template.strip}"
+                segments = full_path.split("/").reject(&:empty?)
+
+                methods_hash.each do |method, operation|
+                  unless %w[get post put delete patch head].include?(method)
+                    next
+                  end
+                  if operation.is_a?(Hash)
+                    operation_id = operation["operationId"]
+                  else
+                    operation_id = nil
+                  end
+                  insert(segments, method, operation_id)
+                end
+              end
+            else
+              nil
             end
+          else
+            nil
           end
         end
 
@@ -83,25 +101,30 @@ module Async
               node = node.children[segment]
             end
           end
-          node.methods << method.downcase unless node.methods.include?(method.downcase)
-          node.operation_ids[method.downcase] = operation_id if operation_id
+          unless node.methods.include?(method.downcase)
+            node.methods << method.downcase
+          end
+          if operation_id
+            node.operation_ids[method.downcase] = operation_id
+          end
         end
 
         # Match a concrete path (array of segments) against the trie.
         # Returns a result hash.
         def match(segments, method = nil)
-          node = @root
-          segments.each do |segment|
-            if node.children.key?(segment)
-              node = node.children[segment]
-            elsif node.wildcard
-              node = node.wildcard
-            else
-              return {valid: false, methods: [], operation_id: nil}
+          node = segments.inject(@root) do |current, segment|
+            if current.nil?
+              nil
+            elsif current.children.key?(segment)
+              current.children[segment]
+            elsif current.wildcard
+              current.wildcard
             end
           end
 
-          if method
+          if node.nil?
+            {valid: false, methods: [], operation_id: nil}
+          elsif method
             method_down = method.downcase
             valid = node.methods.include?(method_down)
             {valid: valid, methods: node.methods, operation_id: node.operation_ids[method_down]}
@@ -112,17 +135,21 @@ module Async
 
         private
 
-        def extract_base_path(doc)
-          servers = doc["servers"]
-          return "" unless servers.is_a?(Array) && servers.first.is_a?(Hash)
-
-          server = servers.first
-          variables = server["variables"] || {}
-          base_path_var = variables["basePath"]
-          return "" unless base_path_var.is_a?(Hash)
-
-          base_path_var["default"] || ""
-        end
+          def extract_base_path(doc)
+            servers = doc["servers"]
+            if servers.is_a?(Array) && servers.first.is_a?(Hash)
+              server = servers.first
+              variables = server["variables"] || {}
+              base_path_var = variables["basePath"]
+              if base_path_var.is_a?(Hash)
+                base_path_var["default"] || ""
+              else
+                ""
+              end
+            else
+              ""
+            end
+          end
       end
     end
   end

data/lib/async/matrix/api.rb

@@ -54,7 +54,12 @@ module Async
           if name.start_with?("to_")
             super
           else
-            chain.__send__(name, *args, **kwargs, &block)
+            chain.__send__(
+              name,
+              *args,
+              **kwargs,
+              &block
+            )
           end
         end