async-matrix 3.0.0-arm-linux → 3.0.1-arm-linux

data/lib/async/matrix/client/sync.rb

@@ -0,0 +1,508 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "console"
+
+require_relative "../../../protocol/matrix/message_batch"
+
+module Async
+  module Matrix
+    class Client
+      # A stream of messages from the homeserver, decrypted on the way through.
+      #
+      #   stream = client.sync(store: device_store)
+      #
+      #   stream.each do |message|
+      #     message.decrypted?   # false means we hold no key for it YET
+      #     message.type         # the real type, once decrypted
+      #     message.content
+      #     checkpoint(stream.next_batch)
+      #   end
+      #
+      # WHAT A CONSUMER SEES IS MESSAGES. /sync also carries to-device events,
+      # device lists and key counts, and none of that is a message: to-device
+      # events are how room keys travel, so they are fed to the store and never
+      # yielded. A consumer that had to recognise and route them would be
+      # reimplementing this class.
+      #
+      # ORDER IS THE WHOLE TRICK, and MessageBatch provides it. A batch
+      # routinely carries both an `m.room_key` and the timeline event that key
+      # unlocks; because the batch yields to-device first and the store absorbs
+      # keys as it reads them, that event decrypts on its first pass instead of
+      # being stored as a placeholder and repaired later.
+      #
+      # THE STORE IS PASSED IN, holding this device's keys. It is what makes any
+      # room readable, and it is optional only in the sense that a consumer
+      # interested solely in unencrypted rooms can omit it and receive encrypted
+      # messages undecrypted.
+      #
+      # NOT RESILIENT, DELIBERATELY. A failed request raises. How to react to a
+      # homeserver that is down -- retry, back off, give up, alert -- is policy,
+      # and policy belongs to whatever is driving the loop rather than to the
+      # thing reading the protocol.
+      class Sync
+        # Synapse holds a /sync request open until something happens or this
+        # elapses, so it is a normal quiet-room duration rather than a failure
+        # timeout.
+        DEFAULT_TIMEOUT = 30_000
+
+        def initialize(client, store: nil, since: nil, timeout: DEFAULT_TIMEOUT, filter: nil)
+          @client = client
+          @store = store
+          @next_batch = since
+          @timeout = timeout
+          @filter = filter
+          @one_time_keys_count = {}
+        end
+
+        attr_reader :store, :timeout, :filter
+
+        # The cursor to resume from.
+        #
+        # COMMIT IT ONLY AFTER THE MESSAGES OF ITS BATCH ARE DURABLE. It advances
+        # when a batch is drained, so reading it inside the loop and storing it
+        # before handling the message is how a crash loses messages with nothing
+        # recording that it happened.
+        attr_reader :next_batch
+
+        # What the server last said it still holds of our one-time keys.
+        #
+        # Surfaced rather than acted on. Running low means topping up, which is
+        # an upload, and deciding when to upload is not this object's business --
+        # but a device whose keys run out silently stops being reachable, so the
+        # number has to be visible to someone.
+        attr_reader :one_time_keys_count
+
+        # One round trip. Returns the batch, undecrypted.
+        #
+        # An INITIAL sync -- no cursor -- asks for the full state of every room
+        # the account is in, which is as large as a response gets. A filter is
+        # the only thing that makes it smaller.
+        def poll
+          Protocol::Matrix::MessageBatch.from_sync(fetch)
+        end
+
+        # Read one batch, yielding each room message with whatever the store
+        # could decrypt.
+        #
+        # @returns [Integer] how many messages were yielded.
+        def read(&block)
+          batch = poll
+          yielded = 0
+
+          batch.each do |message, _section|
+            if batch.to_device?
+              handle_to_device(message)
+            else
+              yielded += 1
+              block.call(decrypt(message))
+            end
+          end
+
+          # AFTER the batch, never during: the cursor says "everything before
+          # this has been handed over", and advancing it mid-batch would promise
+          # that of messages still in it.
+          @next_batch = batch.next_batch
+          yielded
+        end
+
+        # Poll forever, yielding every message. Stops when +stop+ says so, which
+        # defaults to never -- a sync stream has no natural end.
+        def each(stop: -> { false }, &block)
+          unless block
+            raise ArgumentError, "Client::Sync#each requires a block; a sync stream is not enumerable"
+          end
+
+          until stop.call
+            read(&block)
+          end
+
+          self
+        end
+
+        private
+
+          def fetch
+            query = {timeout: @timeout}
+
+            if @next_batch
+              query[:since] = @next_batch
+            end
+
+            if @filter
+              query[:filter] = @filter
+            end
+
+            response = @client.api.sync.get(**query)
+            remember_key_counts(response)
+            response
+          end
+
+          def remember_key_counts(response)
+            counts = response["device_one_time_keys_count"]
+
+            if counts
+              @one_time_keys_count = counts
+            end
+          end
+
+          # To-device messages are plumbing: decrypting one is how a room key
+          # reaches the store, and the store absorbs it as it reads. Nothing is
+          # yielded.
+          #
+          # A FAILURE HERE MUST NOT REACH THE LOOP. Anyone sharing a room can
+          # send us a to-device message, so a malformed one that propagated
+          # would be a remote-controlled crash -- and the loss is recoverable
+          # anyway, because a sender who sees us unable to decrypt re-shares the
+          # key. Protocol errors are swallowed; anything else is a bug in us and
+          # still raises.
+          def handle_to_device(message)
+            if @store && message.encrypted?
+              @store.decrypt(message)
+            end
+          rescue Protocol::Matrix::Error => error
+            Console.warn(self, "Discarding undecryptable to-device message.", error: error)
+            nil
+          end
+
+          # An encrypted message with no key is returned AS IT IS, undecrypted.
+          # That is not a failure: it is the commonest state in an encrypted
+          # room, the key may still arrive, and a consumer that stores the row
+          # now can have it repaired in place later.
+          def decrypt(message)
+            if @store && message.encrypted?
+              @store.decrypt(message)
+            end
+
+            message
+          end
+      end
+    end
+  end
+end
+
+__END__
+  describe "Async::Matrix::Client::Sync" do
+    # A client faked at the api-chain level, so the specs exercise the real call
+    # path (client.api.sync.get) rather than a shortcut around it.
+    def fake_client(*responses)
+      queried = []
+      remaining = responses.dup
+      client = Object.new
+      client.define_singleton_method(:queried) { queried }
+      client.define_singleton_method(:api) do
+        chain = Object.new
+        chain.define_singleton_method(:sync) do
+          endpoint = Object.new
+          endpoint.define_singleton_method(:get) do |**query|
+            queried << query
+            remaining.shift || {"next_batch" => "empty"}
+          end
+          endpoint
+        end
+        chain
+      end
+      client
+    end
+
+    # A store that records what it was asked to read and "decrypts" whatever it
+    # has a key for.
+    def fake_store(readable: [])
+      store = Object.new
+      seen = []
+      # Captured as locals: inside define_singleton_method, self is the store,
+      # so the spec's own helpers are out of scope.
+      olm = olm_session_double
+      megolm = megolm_session_double
+
+      store.define_singleton_method(:seen) { seen }
+      store.define_singleton_method(:decrypt) do |message|
+        seen << message
+
+        if message.olm?
+          message.decrypt!(olm, identity_key: message.recipients.first)
+          message
+        elsif readable.include?(message.session_id)
+          message.decrypt!(megolm)
+          message
+        end
+      end
+      store
+    end
+
+    def megolm_session_double
+      session = Object.new
+      session.define_singleton_method(:decrypt) do |_ciphertext|
+        [JSON.generate({"type" => "m.room.message", "content" => {"body" => "plain"}}), 0]
+      end
+      session
+    end
+
+    # A real olm payload: the OlmPayload schema's required fields are what make
+    # the message attributable, and EncryptedMessage refuses one without them.
+    def olm_session_double(type: "m.room_key")
+      session = Object.new
+      session.define_singleton_method(:decrypt) do |_type, _body|
+        JSON.generate({
+          "type" => type,
+          "content" => {"algorithm" => "m.megolm.v1.aes-sha2"},
+          "sender" => "@bob:example.org",
+          "recipient" => "@us:example.org",
+          "recipient_keys" => {"ed25519" => "ours"},
+          "keys" => {"ed25519" => "theirs"},
+        })
+      end
+      session
+    end
+
+    def encrypted_timeline(session_id: "session1", event_id: "$enc")
+      {
+        "type" => "m.room.encrypted",
+        "event_id" => event_id,
+        "sender" => "@alice:example.org",
+        "content" => {
+          "algorithm" => "m.megolm.v1.aes-sha2",
+          "ciphertext" => "AwgAEnAC",
+          "session_id" => session_id,
+        },
+      }
+    end
+
+    def plaintext_timeline(event_id = "$msg")
+      {
+        "type" => "m.room.message",
+        "event_id" => event_id,
+        "sender" => "@alice:example.org",
+        "content" => {"msgtype" => "m.text", "body" => "hello"},
+      }
+    end
+
+    def to_device_event
+      {
+        "type" => "m.room.encrypted",
+        "sender" => "@bob:example.org",
+        "content" => {
+          "algorithm" => "m.olm.v1.curve25519-aes-sha2",
+          "sender_key" => "theircurve",
+          "ciphertext" => {"ourcurve" => {"type" => 0, "body" => "olmbody"}},
+        },
+      }
+    end
+
+    def response(events: [plaintext_timeline], to_device: [], next_batch: "s2", **extra)
+      {
+        "next_batch" => next_batch,
+        "to_device" => {"events" => to_device},
+        "rooms" => {"join" => {"!room:example.org" => {"timeline" => {"events" => events}}}},
+      }.merge(extra)
+    end
+
+    def sync_for(client, **options)
+      Async::Matrix::Client::Sync.new(client, **options)
+    end
+
+    # ── The request ───────────────────────────────────────────────────────────
+
+    it "polls with a timeout and no cursor on the first request" do
+      client = fake_client(response)
+      sync_for(client).read { |_message| nil }
+
+      client.queried.should == [{timeout: 30_000}]
+    end
+
+    it "sends the cursor it was given" do
+      client = fake_client(response)
+      sync_for(client, since: "s1").read { |_message| nil }
+
+      client.queried.should == [{timeout: 30_000, since: "s1"}]
+    end
+
+    it "sends a filter when it has one" do
+      client = fake_client(response)
+      sync_for(client, filter: "2", timeout: 100).read { |_message| nil }
+
+      client.queried.should == [{timeout: 100, filter: "2"}]
+    end
+
+    it "advances the cursor across polls" do
+      client = fake_client(response(next_batch: "s2"), response(next_batch: "s3"))
+      sync = sync_for(client)
+
+      sync.next_batch.should.be.nil
+      sync.read { |_message| nil }
+      sync.next_batch.should == "s2"
+      sync.read { |_message| nil }
+      sync.next_batch.should == "s3"
+      client.queried.last.should == {timeout: 30_000, since: "s2"}
+    end
+
+    # ── What is yielded ───────────────────────────────────────────────────────
+
+    it "yields room messages" do
+      sync = sync_for(fake_client(response(events: [plaintext_timeline("$a"), plaintext_timeline("$b")])))
+      seen = []
+      sync.read { |message| seen << message.event_id }
+
+      seen.should == ["$a", "$b"]
+    end
+
+    # To-device events are how room keys travel. They are not messages, and a
+    # consumer that had to recognise them would be reimplementing this class.
+    it "never yields a to-device message" do
+      sync = sync_for(
+        fake_client(response(to_device: [to_device_event], events: [plaintext_timeline])),
+        store: fake_store,
+      )
+      seen = []
+      sync.read { |message| seen << message }
+
+      seen.length.should == 1
+      seen.first.type.should == "m.room.message"
+    end
+
+    it "still feeds to-device messages to the store" do
+      store = fake_store
+      sync = sync_for(fake_client(response(to_device: [to_device_event], events: [])), store: store)
+      sync.read { |_message| nil }
+
+      store.seen.length.should == 1
+      store.seen.first.olm?.should == true
+    end
+
+    it "counts what it yielded" do
+      sync = sync_for(fake_client(response(events: [plaintext_timeline("$a"), plaintext_timeline("$b")])))
+
+      sync.read { |_message| nil }.should == 2
+    end
+
+    it "yields nothing for an empty batch" do
+      sync = sync_for(fake_client(response(events: [])))
+      seen = []
+
+      sync.read { |message| seen << message }.should == 0
+      seen.should == []
+    end
+
+    # ── Decryption ────────────────────────────────────────────────────────────
+
+    it "decrypts a room message with the store's keys" do
+      sync = sync_for(
+        fake_client(response(events: [encrypted_timeline(session_id: "known")])),
+        store: fake_store(readable: ["known"]),
+      )
+      seen = []
+      sync.read { |message| seen << message }
+
+      seen.first.decrypted?.should == true
+      seen.first.type.should == "m.room.message"
+      seen.first.content.should == {"body" => "plain"}
+    end
+
+    # NOT A FAILURE, and not a reason to drop the message: the key may still
+    # arrive, and a consumer that stored this row can have it repaired later.
+    it "yields an encrypted message it has no key for, undecrypted" do
+      sync = sync_for(
+        fake_client(response(events: [encrypted_timeline(session_id: "unknown")])),
+        store: fake_store(readable: []),
+      )
+      seen = []
+      sync.read { |message| seen << message }
+
+      seen.length.should == 1
+      seen.first.decrypted?.should == false
+      seen.first.encrypted?.should == true
+      seen.first.session_id.should == "unknown"
+    end
+
+    # A consumer interested only in unencrypted rooms needs no keys at all.
+    it "works with no store, leaving encrypted messages alone" do
+      sync = sync_for(fake_client(response(events: [encrypted_timeline, plaintext_timeline])))
+      seen = []
+      sync.read { |message| seen << message }
+
+      seen.length.should == 2
+      seen.first.decrypted?.should == false
+      seen.last.type.should == "m.room.message"
+    end
+
+    it "leaves a plaintext message untouched by the store" do
+      store = fake_store
+      sync = sync_for(fake_client(response(events: [plaintext_timeline])), store: store)
+      sync.read { |_message| nil }
+
+      store.seen.should == []
+    end
+
+    # Anyone sharing a room can send us one, so a malformed to-device message
+    # must not take the loop down with it.
+    it "discards an undecryptable to-device message and keeps going" do
+      exploding = Object.new
+      exploding.define_singleton_method(:decrypt) do |_message|
+        raise(Protocol::Matrix::EncryptedMessage::MalformedError, "nonsense")
+      end
+
+      sync = sync_for(
+        fake_client(response(to_device: [to_device_event], events: [plaintext_timeline])),
+        store: exploding,
+      )
+      seen = []
+
+      sync.read { |message| seen << message }.should == 1
+      seen.first.type.should == "m.room.message"
+    end
+
+    # ── Key counts ────────────────────────────────────────────────────────────
+
+    # A device whose one-time keys run out silently stops being reachable, so
+    # the number has to be visible to someone.
+    it "remembers what the server says it holds of our one-time keys" do
+      sync = sync_for(
+        fake_client(response("device_one_time_keys_count" => {"signed_curve25519" => 12})),
+      )
+
+      sync.one_time_keys_count.should == {}
+      sync.read { |_message| nil }
+      sync.one_time_keys_count.should == {"signed_curve25519" => 12}
+    end
+
+    it "keeps the last count when a response omits it" do
+      client = fake_client(
+        response("device_one_time_keys_count" => {"signed_curve25519" => 12}),
+        response,
+      )
+      sync = sync_for(client)
+      sync.read { |_message| nil }
+      sync.read { |_message| nil }
+
+      sync.one_time_keys_count.should == {"signed_curve25519" => 12}
+    end
+
+    # ── Looping ───────────────────────────────────────────────────────────────
+
+    it "polls until told to stop" do
+      client = fake_client(response(next_batch: "s2"), response(next_batch: "s3"))
+      polls = 0
+      sync = sync_for(client)
+
+      sync.each(stop: -> { polls >= 2 }) { |_message| polls += 1 }
+
+      polls.should == 2
+      client.queried.length.should == 2
+    end
+
+    it "requires a block, because a sync stream is not enumerable" do
+      lambda { sync_for(fake_client(response)).each }.should.raise(ArgumentError)
+    end
+
+    # ── The batch, unprocessed ────────────────────────────────────────────────
+
+    it "exposes the raw batch for a caller that wants to drive it itself" do
+      batch = sync_for(fake_client(response(to_device: [to_device_event]))).poll
+
+      batch.should.be.kind_of Protocol::Matrix::MessageBatch
+      batch.size.should == 2
+      batch.next_batch.should == "s2"
+    end
+  end

data/lib/async/matrix/client.rb

@@ -10,6 +10,12 @@ require "console"
 require "securerandom"
 require "time"
 
+# The action surface, mixed in below. Required explicitly because the library's
+# loader globs this directory in sorted order, which reaches client.rb before
+# client/ -- so `include Encryption` would resolve against nothing.
+require_relative "client/encryption"
+require_relative "client/rooms"
+
 module Async
   module Matrix
     # Async HTTP client for the Matrix Client-Server API.
@@ -37,6 +43,9 @@ module Async
       DEFAULT_RESPONSE_SIZE_LIMIT       = 50 * 1024 * 1024  # 50 MiB for JSON API responses
       DEFAULT_ERROR_RESPONSE_SIZE_LIMIT = 512 * 1024         # 512 KiB for error bodies
 
+      include Encryption
+      include Rooms
+
       attr_reader :config
 
       def initialize(config, max_retries: DEFAULT_MAX_RETRIES,
@@ -84,12 +93,18 @@ module Async
 
       # ── Room actions ───────────────────────────────────────────
 
-      def join_room(room_id)
-        post("#{CLIENT_PREFIX}/join/#{encode(room_id)}")
+      # Positional OR keyword: `join_room("!r:example.org")` is how this was
+      # always called, and `join_room(room_id: "!r:example.org")` is the form
+      # every other action here takes. Keeping both means the action surface is
+      # consistent without breaking callers written against 3.0.
+      def join_room(room_id = nil, **options)
+        target = room_id || options[:room_id]
+        post("#{CLIENT_PREFIX}/join/#{encode(target)}")
       end
 
-      def leave_room(room_id)
-        post("#{CLIENT_PREFIX}/rooms/#{encode(room_id)}/leave")
+      def leave_room(room_id = nil, **options)
+        target = room_id || options[:room_id]
+        post("#{CLIENT_PREFIX}/rooms/#{encode(target)}/leave")
       end
 
       # ── Profile ────────────────────────────────────────────────
@@ -108,6 +123,21 @@ module Async
         get("#{CLIENT_PREFIX}/account/whoami")
       end
 
+      # ── Syncing ────────────────────────────────────────────────────────────
+
+      # A stream of messages from this account, decrypted by +store+.
+      #
+      #   client.sync(store: device_store).each do |message|
+      #     ...
+      #   end
+      #
+      # See Client::Sync: the stream yields room messages only, and to-device
+      # events are fed to the store on the way through, which is how room keys
+      # arrive.
+      def sync(store: nil, since: nil, timeout: Sync::DEFAULT_TIMEOUT, filter: nil)
+        Sync.new(self, store: store, since: since, timeout: timeout, filter: filter)
+      end
+
       # ── Full API (runtime-generated from OpenAPI schemas) ─────
 
       # Returns a Gateway that provides method-chained access to every
@@ -177,6 +207,16 @@ module Async
         )
       end
 
+      # Query parameters added to EVERY request this client makes.
+      #
+      # EMPTY FOR AN ORDINARY CLIENT: a user's own access token already says who
+      # the request is for. AppServiceClient overrides it, because an as_token
+      # says only "an appservice" -- without `?user_id=` the homeserver assumes
+      # the registration's sender_localpart, and without `?device_id=` the
+      # request has no device at all, which fails precisely the calls encryption
+      # depends on.
+      def default_query = {}
+
       def close
         @internet&.close
         @internet = nil
@@ -190,8 +230,38 @@ module Async
           @internet ||= Async::HTTP::Internet.new
         end
 
+        # Merge #default_query into a path that may already carry a query --
+        # Api::Chain appends its own parameters before handing the path over, so
+        # this is the single place both routes pass through.
+        #
+        # A parameter the caller already set WINS. Overwriting it would mean a
+        # client silently acting as somebody other than the caller asked for,
+        # which is worse than the request failing.
+        def apply_default_query(path)
+          missing = default_query.reject { |key, _|
+            path.match?(/[?&]#{Regexp.escape(key.to_s)}=/)
+          }
+
+          if missing.empty?
+            path
+          else
+            if path.include?("?")
+              separator = "&"
+            else
+              separator = "?"
+            end
+
+            pairs = missing.map { |key, value| "#{encode(key.to_s)}=#{encode(value.to_s)}" }
+
+            "#{path}#{separator}#{pairs.join('&')}"
+          end
+        end
+
+        # PUBLIC, declared below: Api::Chain#execute calls `@client.request` for
+        # DELETE, so leaving this private makes every DELETE through the chain
+        # raise NoMethodError.
         def request(method, path, body = nil, max_retries: nil)
-          url = "#{@base}#{path}"
+          url = "#{@base}#{apply_default_query(path)}"
           if body
             json_body = JSON.generate(body)
           else
@@ -349,6 +419,8 @@ module Async
         def encode(value)
           ERB::Util.url_encode(value)
         end
+
+        public :request
     end
   end
 end