async-matrix 0.1.3 → 1.1.0

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

@@ -0,0 +1,584 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+require "async/matrix"
+require "string_builder"
+require "erb"
+
+module Async
+  module Matrix
+    module Api
+      # Wraps a StringBuilder to build Matrix API paths via method chaining,
+      # terminated by .get(), .post(), .put(), or .delete() which validate
+      # the path against the PathTree and fire the HTTP request.
+      #
+      # Inherits from BasicObject so that method names like `send`, `display`,
+      # `format`, `test`, etc. are not defined and fall through to
+      # method_missing, where they get recorded as URL path segments.
+      #
+      # Usage:
+      #   chain = Chain.new(client: client, path_tree: tree, prefix: %w[_matrix client v3])
+      #   chain.account.whoami.get
+      #   chain.rooms("!abc:ex.com").send("m.room.message", "txn1").put(body: "hi")
+      #   chain.rooms("!abc:ex.com").messages.get(dir: "b", limit: 10)
+      #
+      class Chain < ::BasicObject
+        # Paths that carry raw bytes instead of JSON. Matched by
+        # _binary_route? where * is a single-segment wildcard.
+        # The HTTP method determines the operation:
+        #   GET  → download (returns raw bytes)
+        #   POST/PUT → upload (sends raw bytes)
+        BINARY_ROUTES = [
+          "/_matrix/media/v3/upload",
+          "/_matrix/media/v3/upload/*/*",
+          "/_matrix/media/v3/download/*/*",
+          "/_matrix/media/v3/download/*/*/*",
+          "/_matrix/media/v3/thumbnail/*/*",
+          "/_matrix/client/v1/media/download/*/*",
+          "/_matrix/client/v1/media/download/*/*/*",
+          "/_matrix/client/v1/media/thumbnail/*/*",
+        ].freeze
+
+        def initialize(client:, path_tree:, prefix: nil)
+          @client    = client
+          @path_tree = path_tree
+          @prefix    = prefix || ["_matrix", "client", "v3"]
+          @buffer    = []
+        end
+
+        # ── Terminal HTTP methods ──────────────────────────────────
+
+        def get(**kwargs)
+          max_retries = kwargs.delete(:max_retries)
+          execute("GET", query: kwargs, max_retries: max_retries)
+        end
+
+        def post(body = nil, **kwargs)
+          content_type = kwargs.delete(:content_type)
+          max_retries  = kwargs.delete(:max_retries)
+          query        = _extract_query_params(kwargs)
+          execute("POST", body: body || kwargs, content_type: content_type, max_retries: max_retries, query: query)
+        end
+
+        def put(body = nil, **kwargs)
+          content_type = kwargs.delete(:content_type)
+          max_retries  = kwargs.delete(:max_retries)
+          query        = _extract_query_params(kwargs)
+          execute("PUT", body: body || kwargs, content_type: content_type, max_retries: max_retries, query: query)
+        end
+
+        def delete(**kwargs)
+          max_retries = kwargs.delete(:max_retries)
+          execute("DELETE", query: kwargs, max_retries: max_retries)
+        end
+
+        def patch(body = nil, **kwargs)
+          content_type = kwargs.delete(:content_type)
+          max_retries  = kwargs.delete(:max_retries)
+          query        = _extract_query_params(kwargs)
+          execute("PATCH", body: body || kwargs, content_type: content_type, max_retries: max_retries, query: query)
+        end
+
+        # ── Chain inspection ───────────────────────────────────────
+
+        def to_s
+          "/" + _build_full_segments.map { |s| _encode(s) }.join("/")
+        end
+
+        def inspect
+          segments = _build_full_segments
+          "#<Async::Matrix::Api::Chain path=/#{segments.join("/")}>"
+        end
+
+        def path_segments
+          _build_full_segments
+        end
+
+        # ── Everything else becomes a path segment ─────────────────
+
+        def method_missing(name, *args, **kwargs)
+          if kwargs.empty?
+            @buffer << [name.to_s, args]
+          else
+            @buffer << [name.to_s, [*args, kwargs]]
+          end
+          self
+        end
+
+        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(", ")}"
+              )
+            end
+          end
+
+          path = "/" + segments.map { |s| _encode(s) }.join("/")
+
+          if _binary_route?(segments)
+            if query && !query.empty?
+              qs = query.map { |k, v| "#{_encode(k.to_s)}=#{_encode(v.to_s)}" }.join("&")
+              path = "#{path}?#{qs}"
+            end
+            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
+            retry_opts = max_retries ? {max_retries: max_retries} : {}
+            case method
+            when "GET"
+              if query && !query.empty?
+                qs = query.map { |k, v| "#{_encode(k.to_s)}=#{_encode(v.to_s)}" }.join("&")
+                path = "#{path}?#{qs}"
+              end
+              @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
+
+        # 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
+          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 }
+          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)
+            end
+          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
+            end
+          end
+          @prefix + chain_segments
+        end
+
+        def _encode(value)
+          ::ERB::Util.url_encode(value.to_s)
+        end
+      end
+    end
+  end
+end
+
+test do
+  describe "Async::Matrix::Api::Chain" do
+    def make_tree
+      tree = Async::Matrix::Api::PathTree.new
+      tree.insert(%w[_matrix client v3 account whoami], "get", "getAccountWhoami")
+      tree.insert(%w[_matrix client v3 createRoom], "post", "createRoom")
+      tree.insert(%w[_matrix client v3 rooms {roomId} ban], "post", "ban")
+      tree.insert(%w[_matrix client v3 rooms {roomId} state {eventType} {stateKey}], "get")
+      tree.insert(%w[_matrix client v3 rooms {roomId} state {eventType} {stateKey}], "put")
+      tree.insert(%w[_matrix client v3 rooms {roomId} messages], "get", "getRoomMessages")
+      tree.insert(%w[_matrix client v3 rooms {roomId} send {eventType} {txnId}], "put")
+      tree.insert(%w[_matrix client v3 profile {userId} displayname], "put", "setDisplayName")
+      tree
+    end
+
+    it "builds correct path segments for simple chain" do
+      chain = Async::Matrix::Api::Chain.new(
+        client: nil, path_tree: make_tree
+      )
+      chain.account.whoami
+      chain.path_segments.should == %w[_matrix client v3 account whoami]
+    end
+
+    it "builds correct path segments with args" do
+      chain = Async::Matrix::Api::Chain.new(
+        client: nil, path_tree: make_tree
+      )
+      chain.rooms("!abc:ex.com").ban
+      chain.path_segments.should == %w[_matrix client v3 rooms !abc:ex.com ban]
+    end
+
+    it "builds correct to_s with URL encoding" do
+      chain = Async::Matrix::Api::Chain.new(
+        client: nil, path_tree: make_tree
+      )
+      chain.rooms("!abc:ex.com").ban
+      chain.to_s.should == "/_matrix/client/v3/rooms/%21abc%3Aex.com/ban"
+    end
+
+    it "builds path for /rooms/{roomId}/send/{eventType}/{txnId}" do
+      chain = Async::Matrix::Api::Chain.new(
+        client: nil, path_tree: make_tree
+      )
+      chain.rooms("!abc:ex.com").send("m.room.message", "txn-123")
+      chain.path_segments.should == %w[_matrix client v3 rooms !abc:ex.com send m.room.message txn-123]
+    end
+
+    it "raises InvalidEndpointError for unknown path" do
+      chain = Async::Matrix::Api::Chain.new(
+        client: nil, path_tree: make_tree
+      )
+      chain.account.foobar
+      lambda { chain.get }.should.raise Async::Matrix::InvalidEndpointError
+    end
+
+    it "raises InvalidEndpointError for wrong HTTP method" do
+      chain = Async::Matrix::Api::Chain.new(
+        client: nil, path_tree: make_tree
+      )
+      chain.account.whoami
+      lambda { chain.post }.should.raise Async::Matrix::InvalidEndpointError
+    end
+
+    # ── Binary route detection ───────────────────────────────
+
+    def make_media_tree
+      tree = Async::Matrix::Api::PathTree.new
+      tree.insert(%w[_matrix media v3 upload], "post", "uploadContent")
+      tree.insert(%w[_matrix media v3 upload {serverName} {mediaId}], "put", "uploadContentToMXC")
+      tree.insert(%w[_matrix media v3 download {serverName} {mediaId}], "get", "getContent")
+      tree.insert(%w[_matrix media v3 download {serverName} {mediaId} {fileName}], "get", "getContentOverrideName")
+      tree.insert(%w[_matrix media v3 thumbnail {serverName} {mediaId}], "get", "getContentThumbnail")
+      tree.insert(%w[_matrix client v1 media download {serverName} {mediaId}], "get", "getContentAuthed")
+      tree.insert(%w[_matrix client v1 media download {serverName} {mediaId} {fileName}], "get", "getContentOverrideNameAuthed")
+      tree.insert(%w[_matrix client v1 media thumbnail {serverName} {mediaId}], "get", "getContentThumbnailAuthed")
+      tree
+    end
+
+    # Stub response object for download tests.
+    StubResponse = Struct.new(:body_bytes, :headers, :status) do
+      def initialize(body_bytes = "\xFF\xD8\xFF".b)
+        super(body_bytes, {"content-type" => "image/jpeg"}, 200)
+      end
+
+      def read
+        body_bytes
+      end
+    end
+
+    # Stub client with a stub media_client for testing dispatch.
+    StubMediaClient = Struct.new(:calls) do
+      def initialize
+        super([])
+      end
+
+      def upload(method, path, body, content_type)
+        calls << [:upload, method, path, body, content_type]
+        {"content_uri" => "mxc://example.com/abc123"}
+      end
+
+      def download(path)
+        calls << [:download, path]
+        StubResponse.new
+      end
+    end
+
+    StubClientWithMedia = Struct.new(:calls, :media_client) do
+      def initialize
+        super([], StubMediaClient.new)
+      end
+
+      def get(path, max_retries: nil)
+        calls << [:get, path, {max_retries: max_retries}]
+        {"stub" => true}
+      end
+
+      def post(path, body = {}, max_retries: nil)
+        calls << [:post, path, body, {max_retries: max_retries}]
+        {"stub" => true}
+      end
+
+      def put(path, body = {}, max_retries: nil)
+        calls << [:put, path, body, {max_retries: max_retries}]
+        {"stub" => true}
+      end
+
+      def request(method, path, body = nil, max_retries: nil)
+        calls << [method.downcase.to_sym, path, body, {max_retries: max_retries}]
+        {"stub" => true}
+      end
+    end
+
+    it "detects upload route and dispatches to media_client" do
+      client = StubClientWithMedia.new
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: make_media_tree, prefix: %w[_matrix media v3]
+      )
+      chain.upload.post("image-bytes", content_type: "image/png")
+      client.media_client.calls.last[0].should == :upload
+      client.media_client.calls.last[1].should == "POST"
+      client.media_client.calls.last[3].should == "image-bytes"
+      client.media_client.calls.last[4].should == "image/png"
+      client.calls.should.be.empty
+    end
+
+    it "detects upload PUT route and dispatches to media_client" do
+      client = StubClientWithMedia.new
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: make_media_tree, prefix: %w[_matrix media v3]
+      )
+      chain.upload("example.com", "abc123").put("image-bytes", content_type: "image/jpeg")
+      client.media_client.calls.last[0].should == :upload
+      client.media_client.calls.last[1].should == "PUT"
+      client.media_client.calls.last[4].should == "image/jpeg"
+      client.calls.should.be.empty
+    end
+
+    it "detects download route and dispatches to media_client" do
+      client = StubClientWithMedia.new
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: make_media_tree, prefix: %w[_matrix media v3]
+      )
+      response = chain.download("example.com", "abc123").get
+      client.media_client.calls.last[0].should == :download
+      response.read.should == "\xFF\xD8\xFF".b
+      response.headers["content-type"].should == "image/jpeg"
+      client.calls.should.be.empty
+    end
+
+    it "detects download with filename route" do
+      client = StubClientWithMedia.new
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: make_media_tree, prefix: %w[_matrix media v3]
+      )
+      chain.download("example.com", "abc123", "photo.jpg").get
+      client.media_client.calls.last[0].should == :download
+    end
+
+    it "detects thumbnail route and passes query params" do
+      client = StubClientWithMedia.new
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: make_media_tree, prefix: %w[_matrix media v3]
+      )
+      chain.thumbnail("example.com", "abc123").get(width: 64, height: 64)
+      call = client.media_client.calls.last
+      call[0].should == :download
+      call[1].should.include "width=64"
+      call[1].should.include "height=64"
+    end
+
+    it "detects authed download route (client/v1 prefix)" do
+      client = StubClientWithMedia.new
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: make_media_tree, prefix: %w[_matrix client v1]
+      )
+      chain.media.download("example.com", "abc123").get
+      client.media_client.calls.last[0].should == :download
+    end
+
+    it "does NOT route non-binary paths to media_client" do
+      client = StubClientWithMedia.new
+      tree = make_tree
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: tree
+      )
+      chain.account.whoami.get
+      client.calls.last[0].should == :get
+      client.media_client.calls.should.be.empty
+    end
+
+    it "defaults content_type to application/octet-stream for uploads" do
+      client = StubClientWithMedia.new
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: make_media_tree, prefix: %w[_matrix media v3]
+      )
+      chain.upload.post("raw-bytes")
+      client.media_client.calls.last[4].should == "application/octet-stream"
+    end
+
+    # ── ?-prefixed query params on uploads ────────────────────
+
+    it "passes ?-prefixed kwargs as query params on upload POST" do
+      client = StubClientWithMedia.new
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: make_media_tree, prefix: %w[_matrix media v3]
+      )
+      chain.upload.post("image-bytes", content_type: "image/png", "?filename": "photo.png")
+      call = client.media_client.calls.last
+      call[0].should == :upload
+      call[2].should.include "filename=photo.png"
+      call[4].should == "image/png"
+    end
+
+    it "passes ?-prefixed kwargs as query params on upload PUT" do
+      client = StubClientWithMedia.new
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: make_media_tree, prefix: %w[_matrix media v3]
+      )
+      chain.upload("example.com", "abc123").put("bytes", content_type: "image/jpeg", "?filename": "pic.jpg")
+      call = client.media_client.calls.last
+      call[0].should == :upload
+      call[2].should.include "filename=pic.jpg"
+    end
+
+    # ── Version rewrites ──────────────────────────────────────
+
+    def make_full_media_tree
+      tree = make_media_tree
+      tree.insert(%w[_matrix media v1 create], "post", "createContent")
+      tree.insert(%w[_matrix media v3 config], "get", "getConfig")
+      tree.insert(%w[_matrix media v3 preview_url], "get", "getUrlPreview")
+      tree
+    end
+
+    it "rewrites media/v3/create to media/v1/create" do
+      client = StubClientWithMedia.new
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: make_full_media_tree, prefix: %w[_matrix media v3]
+      )
+      chain.create.post
+      call = client.calls.last
+      call[0].should == :post
+      call[1].should == "/_matrix/media/v1/create"
+    end
+
+    it "rewrites client/v3/media/download to client/v1/media/download" do
+      client = StubClientWithMedia.new
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: make_media_tree, prefix: %w[_matrix client v3]
+      )
+      chain.media.download("example.com", "abc123").get
+      call = client.media_client.calls.last
+      call[0].should == :download
+      call[1].should.include "/_matrix/client/v1/media/download/"
+    end
+
+    it "rewrites client/v3/media/thumbnail to client/v1/media/thumbnail" do
+      client = StubClientWithMedia.new
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: make_media_tree, prefix: %w[_matrix client v3]
+      )
+      chain.media.thumbnail("example.com", "abc123").get(width: 32, height: 32)
+      call = client.media_client.calls.last
+      call[0].should == :download
+      call[1].should.include "/_matrix/client/v1/media/thumbnail/"
+    end
+
+    it "does NOT rewrite non-media client/v3 paths" do
+      client = StubClientWithMedia.new
+      tree = make_tree
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: tree, prefix: %w[_matrix client v3]
+      )
+      chain.account.whoami.get
+      call = client.calls.last
+      call[1].should == "/_matrix/client/v3/account/whoami"
+    end
+
+    it "does NOT rewrite media/v3 paths that are not create" do
+      client = StubClientWithMedia.new
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: make_full_media_tree, prefix: %w[_matrix media v3]
+      )
+      chain.config.get
+      call = client.calls.last
+      call[0].should == :get
+      call[1].should == "/_matrix/media/v3/config"
+    end
+
+    # ── max_retries forwarding ─────────────────────────────────
+
+    it "forwards max_retries on get" do
+      client = StubClientWithMedia.new
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: make_tree
+      )
+      chain.account.whoami.get(max_retries: 0)
+      client.calls.last.last[:max_retries].should == 0
+    end
+
+    it "forwards max_retries on post" do
+      client = StubClientWithMedia.new
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: make_tree
+      )
+      chain.createRoom.post({name: "Test"}, max_retries: 1)
+      client.calls.last.last[:max_retries].should == 1
+    end
+
+    it "forwards max_retries on put" do
+      client = StubClientWithMedia.new
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: make_tree
+      )
+      chain.profile("@user:ex.com").displayname.put({displayname: "Bob"}, max_retries: 2)
+      client.calls.last.last[:max_retries].should == 2
+    end
+
+    it "forwards nil max_retries by default" do
+      client = StubClientWithMedia.new
+      chain = Async::Matrix::Api::Chain.new(
+        client: client, path_tree: make_tree
+      )
+      chain.account.whoami.get
+      client.calls.last.last[:max_retries].should.be.nil
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+require "async/matrix"
+
+module Async
+  module Matrix
+    module Api
+      # StringBuilder concat handler that renders a method chain into URL path segments.
+      #
+      # Convention:
+      #   - Bare methods become path segments:       .account.whoami -> ["account", "whoami"]
+      #   - Methods with args inject the arg as a path segment after the method name:
+      #       .rooms("!abc:ex.com") -> ["rooms", "!abc:ex.com"]
+      #   - .call("literal") injects a raw path segment:
+      #       .("m.room.message") -> ["m.room.message"]
+      #
+      # The handler returns an array of raw (unencoded) segments.
+      # URL-encoding is applied later when constructing the final URL.
+      #
+      class Concat
+        def self.call(buffer)
+          new(buffer).segments
+        end
+
+        def initialize(buffer)
+          @buffer = buffer.respond_to?(:to_a) ? buffer.to_a : buffer
+        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)
+
+              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
+                end
+              end
+            end
+          end
+
+          result
+        end
+      end
+    end
+  end
+end
+
+test do
+  require "string_builder"
+
+  describe "Async::Matrix::Api::Concat" do
+    it "converts bare methods to path segments" do
+      sb = StringBuilder.new
+      sb.account.whoami
+      segments = Async::Matrix::Api::Concat.call(sb)
+      segments.should == %w[account whoami]
+    end
+
+    it "converts methods with args to segment + arg" do
+      sb = StringBuilder.new
+      sb.rooms("!abc:ex.com").ban
+      segments = Async::Matrix::Api::Concat.call(sb)
+      segments.should == %w[rooms !abc:ex.com ban]
+    end
+
+    it "handles methods with multiple args" do
+      sb = StringBuilder.new
+      sb.rooms("!abc:ex.com").state("m.room.name", "some_key")
+      segments = Async::Matrix::Api::Concat.call(sb)
+      segments.should == %w[rooms !abc:ex.com state m.room.name some_key]
+    end
+
+    it "handles deep paths" do
+      sb = StringBuilder.new
+      sb.rooms("!abc:ex.com").state("m.room.name", "")
+      segments = Async::Matrix::Api::Concat.call(sb)
+      segments.should == ["rooms", "!abc:ex.com", "state", "m.room.name", ""]
+    end
+
+    it "ignores kwargs in segments" do
+      sb = StringBuilder.new
+      sb.account.whoami
+      segments = Async::Matrix::Api::Concat.call(sb)
+      segments.should == %w[account whoami]
+    end
+  end
+end