async-matrix 3.0.1 → 4.0.1

data/lib/async/matrix/identifier/user_id.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require_relative "generic"
+
+module Async
+  module Matrix
+    module Identifier
+      # A user, namespaced to the homeserver which allocated the account.
+      class UserID < Generic
+        SIGIL = "@"
+
+        # The localpart the current specification allows, which is a subset of what older ones did.
+        LOCALPART = /\A[a-z0-9.\-=_\/+]+\z/
+
+        # The range outside which a localpart is not to be shown to a client except within an event.
+        COMPLIANT = /\A[!-~]+\z/
+
+        # The characters a mapped localpart can carry unescaped, which is the grammar less the escapes.
+        MAPPED = /\A[a-z0-9.\-\/+]\z/
+
+        class << self
+          # A localpart made from a name a wider character set allows, by the algorithm the appendices suggest.
+          #
+          # @parameter string [String] the name to map.
+          # @parameter server_name [String | ServerName] the server to namespace it to.
+          # @parameter escape [Boolean] whether to keep case, by writing an upper case letter as `_` and the letter.
+          # @returns [UserID] the user ID it maps onto.
+          def mapped(string, server_name:, escape: false)
+            localpart = string.to_s.dup.force_encoding(::Encoding::BINARY).each_byte.map do |byte|
+              self.mapped_byte(byte, escape: escape)
+            end
+
+            self.new(localpart.join, server_name)
+          end
+
+          # @parameter byte [Integer] the byte to write.
+          # @parameter escape [Boolean] whether to keep case, by writing an upper case letter as `_` and the letter.
+          # @returns [String] what the byte is written as.
+          def mapped_byte(byte, escape: false)
+            character = byte.chr
+
+            case character
+            when "A".."Z"
+              escape ? "_#{character.downcase}" : character.downcase
+            when "_"
+              escape ? "__" : "_"
+            when MAPPED
+              character
+            else
+              format("=%02x", byte)
+            end
+          end
+        end
+
+        # @returns [Boolean] whether the localpart is one only an older specification allowed.
+        def historical?
+          !LOCALPART.match?(@localpart)
+        end
+
+        # Whether a server may name this user outside an event.
+        #
+        # @returns [Boolean] whether the localpart is compliant.
+        def compliant?
+          COMPLIANT.match?(@localpart)
+        end
+
+        def validate
+          super
+
+          self.require_server_name
+        end
+      end
+    end
+  end
+end

data/lib/async/matrix/identifier.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require_relative "error"
+
+module Async
+  module Matrix
+    # Raised when a string is not the identifier it was read as.
+    class InvalidIdentifierError < Error
+    end
+
+    # The identifiers the appendices give a grammar.
+    module Identifier
+    end
+  end
+end
+
+require_relative "identifier/event_id"
+require_relative "identifier/generic"
+require_relative "identifier/namespaced"
+require_relative "identifier/opaque"
+require_relative "identifier/room_alias"
+require_relative "identifier/room_id"
+require_relative "identifier/server_name"
+require_relative "identifier/user_id"

data/lib/async/matrix/key_representation.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require_relative "error"
+
+module Async
+  module Matrix
+    # The form a key takes when a person reads it.
+    module KeyRepresentation
+      # The two bytes which say that what follows is one of these.
+      HEADER = "\x8B\x01".b
+
+      # The alphabet bitcoin addresses use, which leaves out the characters which look alike.
+      ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+
+      # How many characters go between one space and the next.
+      GROUP = 4
+
+      # The bytes a representation carries besides the key itself.
+      OVERHEAD = HEADER.bytesize + 1
+
+      class << self
+        # @parameter bytes [String] the raw key.
+        # @returns [String] the key as a person reads it, in groups of four characters.
+        def encode(bytes)
+          body = HEADER + bytes.b
+
+          self.group(self.base58(body + self.parity(body).chr))
+        end
+
+        # @parameter string [String] the key as a person typed it, whose whitespace does not matter.
+        # @parameter length [Integer | nil] the bytes the key must be, where the caller knows.
+        # @returns [String] the raw key.
+        # @raises [InvalidKeyError] if the alphabet, the length, the header or the parity is wrong.
+        def decode(string, length: nil)
+          decoded = self.bytes(string.gsub(/\s+/, ""))
+
+          self.check_size(decoded, length)
+
+          key = decoded.byteslice(HEADER.bytesize, decoded.bytesize - OVERHEAD)
+
+          self.check(decoded.byteslice(0, HEADER.bytesize), key, decoded.getbyte(decoded.bytesize - 1))
+
+          key
+        end
+
+        # The length is checked first, so that a key of the wrong size says so rather than failing the parity.
+        #
+        # @parameter decoded [String] the bytes the representation held.
+        # @parameter length [Integer | nil] the bytes the key must be, where the caller knows.
+        # @raises [InvalidKeyError] if there is no room for a key, or it is not the length wanted.
+        def check_size(decoded, length)
+          unless decoded.bytesize > OVERHEAD
+            raise InvalidKeyError, "A key representation is a header, a key and a parity byte, which #{decoded.bytesize} bytes cannot be!"
+          end
+
+          unless length.nil? or decoded.bytesize == length + OVERHEAD
+            raise InvalidKeyError, "This key is #{decoded.bytesize - OVERHEAD} bytes, and #{length} was expected!"
+          end
+        end
+
+        # @parameter header [String] the bytes the representation began with.
+        # @parameter key [String] the key it carried.
+        # @parameter parity [Integer] the parity byte it ended with.
+        # @raises [InvalidKeyError] if the header or the parity is wrong.
+        def check(header, key, parity)
+          unless header == HEADER
+            raise InvalidKeyError, "A key representation begins with #{HEADER.unpack1("H*")}, not #{header.unpack1("H*")}!"
+          end
+
+          unless parity == self.parity(HEADER + key)
+            raise InvalidKeyError, "The parity byte of this key representation does not match the key!"
+          end
+        end
+
+        # Every byte of the array exclusive ored together, including the header.
+        #
+        # @parameter bytes [String] the bytes to fold.
+        # @returns [Integer] the parity byte.
+        def parity(bytes)
+          bytes.each_byte.reduce(0, :^)
+        end
+
+        # @parameter string [String] the characters to space out.
+        # @returns [String] them, in groups of four.
+        def group(string)
+          string.scan(/.{1,#{GROUP}}/).join(" ")
+        end
+
+        # @parameter bytes [String] the bytes to write.
+        # @returns [String] them, in base58.
+        def base58(bytes)
+          number = bytes.each_byte.reduce(0){|total, byte| (total << 8) | byte}
+          digits = []
+
+          while number > 0
+            number, remainder = number.divmod(ALPHABET.length)
+            digits.unshift(ALPHABET[remainder])
+          end
+
+          (ALPHABET[0] * self.leading(bytes.each_byte, 0)) + digits.join
+        end
+
+        # @parameter string [String] the base58 to read.
+        # @returns [String] the bytes it holds.
+        # @raises [InvalidKeyError] if it holds a character the alphabet does not.
+        def bytes(string)
+          number = string.each_char.reduce(0) do |total, character|
+            index = ALPHABET.index(character)
+
+            unless index
+              raise InvalidKeyError, "#{character.inspect} is not a base58 character!"
+            end
+
+            (total * ALPHABET.length) + index
+          end
+
+          ("\x00".b * self.leading(string.each_char, ALPHABET[0])) + self.octets(number)
+        end
+
+        # Zero is no bytes at all, because the leading zero bytes are counted on their own.
+        #
+        # @parameter number [Integer] the number to write.
+        # @returns [String] its bytes, most significant first.
+        def octets(number)
+          digits = number.to_s(16).delete_prefix("0")
+
+          [digits.length.even? ? digits : "0#{digits}"].pack("H*")
+        end
+
+        # @parameter values [Enumerator] the values to count through.
+        # @parameter zero [Object] the value which counts as nothing.
+        # @returns [Integer] how many of them begin the sequence.
+        def leading(values, zero)
+          values.take_while{|value| value == zero}.count
+        end
+      end
+    end
+  end
+end

data/lib/async/matrix/middleware/authenticated.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "protocol/http/middleware"
+
+require_relative "repeatable"
+require_relative "../credentials"
+require_relative "../failure"
+
+module Async
+  module Matrix
+    module Middleware
+      # Authenticates every request, and replaces a rejected access token.
+      #
+      # It sits below the resource, so a request can be sent again without its path and headers being applied twice.
+      class Authenticated < ::Protocol::HTTP::Middleware
+        include Repeatable
+
+        # The status a homeserver rejects an access token with.
+        UNAUTHORIZED = 401
+
+        # @parameter delegate [Protocol::HTTP::Middleware] what handles requests.
+        # @parameter credentials [Credentials] the access token to authenticate with.
+        def initialize(delegate, credentials)
+          super(delegate)
+
+          @credentials = credentials
+        end
+
+        # @attribute [Credentials] the access token every request is authenticated with.
+        attr :credentials
+
+        # Authenticate the request, and try again with a new access token if it was rejected.
+        #
+        # @parameter request [Protocol::HTTP::Request] the request to make.
+        # @returns [Protocol::HTTP::Response] the response.
+        def call(request)
+          generation = self.authorize(request)
+
+          response = super
+
+          if self.rejected?(response)
+            self.retried(request, response, generation)
+          else
+            response
+          end
+        end
+
+        # The credentials may hold a connection to an authorization server on another host.
+        #
+        # @returns [Nil] nothing.
+        def close
+          @credentials.close
+
+          super
+        end
+
+        def inspect
+          "\#<#{self.class} #{@credentials.inspect}>"
+        end
+
+        # Set the authorization header, replacing whatever the resource supplied.
+        #
+        # `Protocol::HTTP::Headers#[]=` replaces where `merge` adds, and a homeserver rejects a request carrying two authorization headers.
+        #
+        # @parameter request [Protocol::HTTP::Request] the request to authenticate.
+        # @returns [Integer] the generation of the token it now carries.
+        private def authorize(request)
+          authorization, generation = @credentials.authorization
+
+          request.headers["authorization"] = authorization
+
+          generation
+        end
+
+        # Whether the access token was rejected and there is something to replace it with.
+        #
+        # A 401 reporting anything else is the caller's business, not ours.
+        #
+        # @parameter response [Protocol::HTTP::Response] the response to examine.
+        # @returns [Boolean] whether to try again.
+        private def rejected?(response)
+          if response.status == UNAUTHORIZED and @credentials.renewable?
+            Failure.for(response)&.unknown_token? || false
+          else
+            false
+          end
+        end
+
+        # Replace the access token and make the request again.
+        #
+        # @parameter request [Protocol::HTTP::Request] the request to make again.
+        # @parameter response [Protocol::HTTP::Response] the rejected response.
+        # @parameter generation [Integer] the generation of the rejected token.
+        # @returns [Protocol::HTTP::Response] the second response, or the first if it cannot be repeated.
+        private def retried(request, response, generation)
+          if self.repeatable?(request)
+            # Release the connection before asking for it again:
+            response.close
+
+            @credentials.renew!(generation)
+
+            self.authorize(request)
+            self.rewind(request)
+
+            @delegate.call(request)
+          else
+            response
+          end
+        end
+      end
+    end
+  end
+end

data/lib/async/matrix/middleware/rate_limited.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "protocol/http/middleware"
+
+require_relative "repeatable"
+require_relative "../failure"
+
+module Async
+  module Matrix
+    module Middleware
+      # Waits out a rate limit and sends the request again.
+      #
+      # It sits below the resource, so a request can be sent again without its path and headers being applied twice.
+      class RateLimited < ::Protocol::HTTP::Middleware
+        include Repeatable
+
+        # The status a homeserver reports a rate limit with.
+        TOO_MANY_REQUESTS = 429
+
+        # The longest delay we will wait before sending the request again. A longer delay is reported to the caller, rather than silently blocking the task.
+        MAXIMUM_RETRY_DELAY = 30.0
+
+        # How many times a request is sent before the rate limit is reported to the caller.
+        #
+        # {MAXIMUM_RETRY_DELAY} bounds one wait, not the total: a homeserver which answers 429 with `retry-after: 1` forever would spin here without it.
+        MAXIMUM_ATTEMPTS = 3
+
+        # Make the request, waiting and sending it again while the homeserver reports a rate limit.
+        #
+        # @parameter request [Protocol::HTTP::Request] the request to make.
+        # @returns [Protocol::HTTP::Response] the response.
+        def call(request)
+          attempt = 1
+
+          while true
+            response = @delegate.call(request)
+
+            unless response.status == TOO_MANY_REQUESTS and self.repeatable?(request)
+              break response
+            end
+
+            delay = self.retry_delay(response)
+
+            # Reported to the caller rather than retried: the homeserver asked us to wait longer than we are willing to, or it has had every attempt it is going to get.
+            if delay.nil? or attempt >= MAXIMUM_ATTEMPTS
+              break response
+            end
+
+            response.close
+            attempt += 1
+
+            sleep(delay)
+
+            self.rewind(request)
+          end
+        end
+
+        # How long to wait before sending a rate limited request again.
+        #
+        # @parameter response [Protocol::HTTP::Response] the rate limited response.
+        # @returns [Numeric | nil] the delay in seconds, or nil if it should not be sent again.
+        private def retry_delay(response)
+          delay = nil
+
+          if retry_after = response.headers["retry-after"]
+            delay = self.retry_after_duration(retry_after)
+          elsif retry_after_ms = Failure.for(response)&.retry_after_ms
+            delay = retry_after_ms / 1000.0
+          end
+
+          # Nothing said how long to wait, or it asked for longer than we are willing to: the caller is told about the rate limit instead.
+          if delay and delay <= MAXIMUM_RETRY_DELAY
+            delay
+          end
+        end
+
+        # How long a `retry-after` header asks us to wait, which is either a date or a number of seconds.
+        #
+        # @parameter value [String] the header value.
+        # @returns [Numeric] the delay in seconds.
+        private def retry_after_duration(value)
+          [Time.httpdate(value) - Time.now, 0].max
+        rescue ArgumentError
+          value.to_f
+        end
+      end
+    end
+  end
+end

data/lib/async/matrix/middleware/repeatable.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+module Async
+  module Matrix
+    module Middleware
+      # Sends a request more than once.
+      module Repeatable
+        # Whether the request can be sent again, which a body it cannot replay prevents.
+        #
+        # @parameter request [Protocol::HTTP::Request] the request to examine.
+        # @returns [Boolean] whether it can be sent again.
+        private def repeatable?(request)
+          request.body.nil? or request.body.rewindable?
+        end
+
+        # Wind the body back, so that the request can be sent again.
+        #
+        # @parameter request [Protocol::HTTP::Request] the request to rewind.
+        # @returns [Nil] nothing.
+        private def rewind(request)
+          request.body&.rewind
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/async/matrix/middleware/signed.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "json"
+
+require "protocol/http/body/buffered"
+require "protocol/http/middleware"
+
+require_relative "../server_key"
+
+module Async
+  module Matrix
+    module Middleware
+      # Signs every request with the server's own key.
+      #
+      # A server proves who it is by signing the request rather than by carrying a token.
+      class Signed < ::Protocol::HTTP::Middleware
+        # The authorization scheme a signature is carried under.
+        SCHEME = "X-Matrix"
+
+        # @parameter delegate [Protocol::HTTP::Middleware] what handles requests.
+        # @parameter origin [String] the server name the requests are made by.
+        # @parameter key [ServerKey] the key the origin signs with.
+        # @parameter destination [String] the server name the requests are made to.
+        def initialize(delegate, origin, key, destination)
+          super(delegate)
+
+          @origin = origin
+          @key = key
+          @destination = destination
+        end
+
+        # @attribute [String] the server name the requests are made by.
+        attr :origin
+
+        # @attribute [ServerKey] the key the origin signs with.
+        attr :key
+
+        # @attribute [String] the server name the requests are made to.
+        attr :destination
+
+        # Sign the request, and make it.
+        #
+        # @parameter request [Protocol::HTTP::Request] the request to make.
+        # @returns [Protocol::HTTP::Response] the response.
+        def call(request)
+          # `Protocol::HTTP::Headers#[]=` replaces where `merge` adds, and a server rejects a request carrying two authorization headers:
+          request.headers["authorization"] = self.authorization(request)
+
+          super
+        end
+
+        def inspect
+          "\#<#{self.class} #{@origin} -> #{@destination} as #{@key.id}>"
+        end
+
+        # The header which carries the signature, and what it was made over.
+        #
+        # @parameter request [Protocol::HTTP::Request] the request to sign.
+        # @returns [String] the authorization header.
+        private def authorization(request)
+          signature = @key.sign(self.signable(request))
+
+          "#{SCHEME} origin=#{self.quoted(@origin)},destination=#{self.quoted(@destination)},key=#{self.quoted(@key.id)},sig=#{self.quoted(signature)}"
+        end
+
+        # The object a signature is made over.
+        #
+        # The URI is the path as it is sent, and the content is the body as a document.
+        #
+        # @parameter request [Protocol::HTTP::Request] the request to sign.
+        # @returns [Hash] the object to sign.
+        private def signable(request)
+          {
+            method: request.method,
+            uri: request.path,
+            origin: @origin,
+            destination: @destination,
+          }.tap do |object|
+            content = self.content(request)
+
+            unless content.nil?
+              object[:content] = content
+            end
+          end
+        end
+
+        # The body as a document, read back so that it can be signed and then sent.
+        #
+        # Reading consumes the body, so it is replaced with what was read.
+        #
+        # @parameter request [Protocol::HTTP::Request] the request whose body to read.
+        # @returns [Hash | nil] the document, or nil where the request carries no body.
+        private def content(request)
+          body = request.body
+
+          if body.nil?
+            nil
+          else
+            bytes = body.join
+
+            request.body = ::Protocol::HTTP::Body::Buffered.new([bytes])
+
+            self.document(bytes)
+          end
+        end
+
+        # @parameter bytes [String] the body which was read.
+        # @returns [Hash | nil] the document it holds, or nil where it holds none.
+        private def document(bytes)
+          if bytes.nil? or bytes.empty?
+            nil
+          else
+            ::JSON.parse(bytes)
+          end
+        end
+
+        # @parameter value [String] the value to quote.
+        # @returns [String] the value, as a quoted string.
+        private def quoted(value)
+          "\"#{value}\""
+        end
+      end
+    end
+  end
+end

data/lib/async/matrix/oauth/error.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require_relative "../error"
+
+module Async
+  module Matrix
+    module OAuth
+      # The error the authorization server reported.
+      #
+      # @parameter response [Protocol::HTTP::Response] the refusal.
+      # @returns [Tuple(String, String | nil)] the error code and its description.
+      def self.error_for(response)
+        payload = response.read
+
+        if payload.is_a?(Hash)
+          [payload[:error] || "invalid_request", payload[:error_description]]
+        else
+          ["invalid_request", payload&.to_s]
+        end
+      rescue => error
+        ["invalid_request", error.message]
+      end
+
+      # Raised when the authorization server refuses a request.
+      #
+      # A {RequestError}, so a caller which handles one refusal handles both.
+      class Error < Matrix::RequestError
+        # @returns [Boolean] whether the grant was rejected, so the caller must authorize again.
+        def invalid_grant?
+          self.errcode == "invalid_grant"
+        end
+      end
+    end
+  end
+end