matrix_sdk 1.5.0 → 2.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3aa6522f1b8b49ed1ea60dc27c67fefb9479b5aa27d87c4597edf97e76d4eb6
-  data.tar.gz: b2a6d3b5ff58c037092515ccf42e0a2683f1ef024a8b6731c824faade7649a0a
+  metadata.gz: 5af1e7af0f473a5c44df1ede83655cdbdb120e215e42f125b6af576740b88aa6
+  data.tar.gz: cca80fe97ca22f0ddb0c5a2b39b24b70345baa25fb20bea305fa019f46ca7d3a
 SHA512:
-  metadata.gz: b55690dbf6fe96eeb24a6831d390e122962b1c68d5e0031deb32641eaeb7f38568d47ec728d0adbd4eb9aea5d1f2064ff926667588b9b77893314b999366245b
-  data.tar.gz: 73eb136cd9285ffc1415b79c25ac05807eb0b17f52865df329ebff1a83962a5005802a3f914b7ebfe8f6a2371097967955dcdcd6de01d4148c5fd9d3c96dafbd
+  metadata.gz: 0e4c694d8489dae1b2602d01f4aab08b20119c6697e83b41a2a463adb7ebcaf7b1afd439db04a6e54a0979c5a93be865c8afa3d2d03b4ca34b98f82afae87a5f
+  data.tar.gz: 8f52c12d1eb8af55ac5bc011852c9d5f648e9de1cc3241ea1ed76530036b02cff373cb69b8a4c721956add3df1359377d79b2fa2562e8dab8efe5ce877596e2d

data/CHANGELOG.md

@@ -1,3 +1,47 @@
+## 2.1.2 - 2020-09-10
+
+- Adds method for reading complete member lists for rooms, improves the CS spec adherence
+- Adds test for state events
+- Fixes state event handler for rooms not actually passing events
+- Fixes Api#new_for_domain using a faulty URI in certain cases
+
+## 2.1.1 - 2020-08-21
+
+- Fixes crash if state event content is null (#11)
+- Fixes an uninitialized URI constant exception when requiring only the main library file
+- Fixes the Api#get_pushrules method missing an ending slash in the request URI
+- Fixes discovery code for client/server connections based on domain
+
+## 2.1.0 - 2020-05-22
+
+- Adds unique query IDs as well as duration in API debug output, to make it easier to track long requests
+- Finishes up MSC support, get sync over SSE working flawlessly
+- Exposes the #listen_forever method in the client abstraction
+- Fixes room access methods
+
+## 2.0.1 - 2020-03-13
+
+- Adds code for handling non-final MSC's in protocols
+  - Currently implementing clients parts of MSC2018 for Sync over Server Sent Events
+
+## 2.0.0 - 2020-02-14
+
+**NB**, this release includes backwards-incompatible changes;  
+- Changes room state lookup to separate specific state lookups from full state retrieval.
+  This will require changes in client code where `#get_room_state` is called to retrieve
+  all state, as it now requires a state key. For retrieving full room state,
+  `#get_room_state_all` is now the method to use.
+- Changes some advanced parameters to named parameters, ensure your code is updated if it makes use of them
+- Fixes SSL verification to actually verify certs (#9)
+
+- Adds multiple CS API endpoints
+- Adds `:room_id` key to all room events
+- Adds `:self` as a valid option to the client abstraction's `#get_user` method
+- Separates homeserver part stringification for MXIDs
+- Exposes some previously private client abstraction methods (`#ensure_room`, `#next_batch`) for easier bot usage
+- Changes room abstraction member lookups to use `#get_room_joined_members`, reducing transferred data amounts
+- Fixes debug print of methods that return arrays (e.g. CS `/room/{id}/state`)
+
 ## 1.5.0 - 2019-10-25
 
 - Adds error event to the client abstraction, for handling errors in the background listener

data/lib/matrix_sdk.rb

@@ -27,6 +27,9 @@ module MatrixSdk
     autoload :CS, 'matrix_sdk/protocols/cs'
     autoload :IS, 'matrix_sdk/protocols/is'
     autoload :SS, 'matrix_sdk/protocols/ss'
+
+    # Non-final protocol extensions
+    autoload :MSC, 'matrix_sdk/protocols/msc'
   end
 
   def self.debug!

data/lib/matrix_sdk/api.rb

@@ -11,10 +11,6 @@ module MatrixSdk
   class Api
     extend MatrixSdk::Extensions
     include MatrixSdk::Logging
-    include MatrixSdk::Protocols::AS
-    include MatrixSdk::Protocols::CS
-    include MatrixSdk::Protocols::IS
-    include MatrixSdk::Protocols::SS
 
     USER_AGENT = "Ruby Matrix SDK v#{MatrixSdk::VERSION}"
     DEFAULT_HEADERS = {
@@ -23,7 +19,7 @@ module MatrixSdk
     }.freeze
 
     attr_accessor :access_token, :connection_address, :connection_port, :device_id, :autoretry, :global_headers
-    attr_reader :homeserver, :validate_certificate, :open_timeout, :read_timeout, :protocols, :well_known, :proxy_uri
+    attr_reader :homeserver, :validate_certificate, :open_timeout, :read_timeout, :well_known, :proxy_uri
 
     ignore_inspect :access_token, :logger
 
@@ -51,10 +47,6 @@ module MatrixSdk
       @homeserver.path.gsub!(/\/?_matrix\/?/, '') if @homeserver.path =~ /_matrix\/?$/
       raise ArgumentError, 'Please use the base URL for your HS (without /_matrix/)' if @homeserver.path.include? '/_matrix/'
 
-      @protocols = params.fetch(:protocols, %i[CS])
-      @protocols = [@protocols] unless @protocols.is_a? Array
-      @protocols << :CS if @protocols.include?(:AS) && !@protocols.include?(:CS)
-
       @proxy_uri = params.fetch(:proxy_uri, nil)
       @connection_address = params.fetch(:address, nil)
       @connection_port = params.fetch(:port, nil)
@@ -71,6 +63,10 @@ module MatrixSdk
       @global_headers.merge!(params.fetch(:global_headers)) if params.key? :global_headers
       @http = nil
 
+      ([params.fetch(:protocols, [:CS])].flatten - protocols).each do |proto|
+        self.class.include MatrixSdk::Protocols.const_get(proto)
+      end
+
       login(user: @homeserver.user, password: @homeserver.password) if @homeserver.user && @homeserver.password && !@access_token && !params[:skip_login] && protocol?(:CS)
       @homeserver.userinfo = '' unless params[:skip_login]
     end
@@ -96,24 +92,37 @@ module MatrixSdk
       uri = URI("http#{ssl ? 's' : ''}://#{domain}")
       well_known = nil
       target_uri = nil
+      logger = ::Logging.logger[self]
+      logger.debug "Resolving #{domain}"
 
       if !port.nil? && !port.empty?
+        # If the domain is fully qualified according to Matrix (FQDN and port) then skip discovery
         target_uri = URI("https://#{domain}:#{port}")
       elsif target == :server
         # Attempt SRV record discovery
         target_uri = begin
                        require 'resolv'
                        resolver = Resolv::DNS.new
-                       resolver.getresource("_matrix._tcp.#{domain}")
-                     rescue StandardError
+                       srv = "_matrix._tcp.#{domain}"
+                       logger.debug "Trying DNS #{srv}..."
+                       d = resolver.getresource(srv, Resolv::DNS::Resource::IN::SRV)
+                       d
+                     rescue StandardError => e
+                       logger.debug "DNS lookup failed with #{e.class}: #{e.message}"
                        nil
                      end
 
         if target_uri.nil?
+          # Attempt .well-known discovery for server-to-server
           well_known = begin
-                         data = Net::HTTP.get("https://#{domain}/.well-known/matrix/server")
+                         wk_uri = URI("https://#{domain}/.well-known/matrix/server")
+                         logger.debug "Trying #{wk_uri}..."
+                         data = Net::HTTP.start(wk_uri.host, wk_uri.port, use_ssl: true, open_timeout: 5, read_timeout: 5, write_timeout: 5) do |http|
+                           http.get(wk_uri.path).body
+                         end
                          JSON.parse(data)
-                       rescue StandardError
+                       rescue StandardError => e
+                         logger.debug "Well-known failed with #{e.class}: #{e.message}"
                          nil
                        end
 
@@ -124,9 +133,14 @@ module MatrixSdk
       elsif %i[client identity].include? target
         # Attempt .well-known discovery
         well_known = begin
-                       data = Net::HTTP.get("https://#{domain}/.well-known/matrix/client")
-                       JSON.parse(data)
-                     rescue StandardError
+                       wk_uri = URI("https://#{domain}/.well-known/matrix/client")
+                       logger.debug "Trying #{wk_uri}..."
+                       data = Net::HTTP.start(wk_uri.host, wk_uri.port, use_ssl: true, open_timeout: 5, read_timeout: 5, write_timeout: 5) do |http|
+                         http.get(wk_uri.path).body
+                       end
+                       data = JSON.parse(data)
+                     rescue StandardError => e
+                       logger.debug "Well-known failed with #{e.class}: #{e.message}"
                        nil
                      end
 
@@ -140,6 +154,7 @@ module MatrixSdk
           end
         end
       end
+      logger.debug "Using #{target_uri.inspect}"
 
       # Fall back to direct domain connection
       target_uri ||= URI("https://#{domain}:8448")
@@ -153,6 +168,29 @@ module MatrixSdk
           ))
     end
 
+    # Get a list of enabled protocols on the API client
+    #
+    # @example
+    #   MatrixSdk::Api.new_for_domain('matrix.org').protocols
+    #   # => [:IS, :CS]
+    #
+    # @return [Symbol[]] An array of enabled APIs
+    def protocols
+      self
+        .class.included_modules
+        .reject { |m| m&.name.nil? }
+        .select { |m| m.name.start_with? 'MatrixSdk::Protocols::' }
+        .map { |m| m.name.split('::').last.to_sym }
+    end
+
+    # Check if a protocol is enabled on the API connection
+    #
+    # @example Checking for identity server API support
+    #   api.protocol? :IS
+    #   # => false
+    #
+    # @param protocol [Symbol] The protocol to check
+    # @return [Boolean] Is the protocol enabled
     def protocol?(protocol)
       protocols.include? protocol
     end
@@ -201,6 +239,29 @@ module MatrixSdk
       @proxy_uri = proxy_uri
     end
 
+    # Perform a raw Matrix API request
+    #
+    # @example Simple API query
+    #   api.request(:get, :client_r0, '/account/whoami')
+    #   # => { :user_id => "@alice:matrix.org" }
+    #
+    # @example Advanced API request
+    #   api.request(:post,
+    #               :media_r0,
+    #               '/upload',
+    #               body_stream: open('./file'),
+    #               headers: { 'content-type' => 'image/png' })
+    #   # => { :content_uri => "mxc://example.com/AQwafuaFswefuhsfAFAgsw" }
+    #
+    # @param method [Symbol] The method to use, can be any of the ones under Net::HTTP
+    # @param api [Symbol] The API symbol to use, :client_r0 is the current CS one
+    # @param path [String] The API path to call, this is the part that comes after the API definition in the spec
+    # @param options [Hash] Additional options to pass along to the request
+    # @option options [Hash] :query Query parameters to set on the URL
+    # @option options [Hash,String] :body The body to attach to the request, will be JSON-encoded if sent as a hash
+    # @option options [IO] :body_stream A body stream to attach to the request
+    # @option options [Hash] :headers Additional headers to set on the request
+    # @option options [Boolean] :skip_auth (false) Skip authentication
     def request(method, api, path, **options)
       url = homeserver.dup.tap do |u|
         u.path = api_to_path(api) + path
@@ -218,7 +279,7 @@ module MatrixSdk
         request.content_length = (request.body || request.body_stream).size
       end
 
-      request['authorization'] = "Bearer #{access_token}" if access_token
+      request['authorization'] = "Bearer #{access_token}" if access_token && !options.fetch(:skip_auth, false)
       if options.key? :headers
         options[:headers].each do |h, v|
           request[h.to_s.downcase] = v
@@ -229,14 +290,20 @@ module MatrixSdk
       loop do
         raise MatrixConnectionError, "Server still too busy to handle request after #{failures} attempts, try again later" if failures >= 10
 
-        print_http(request)
+        req_id = ('A'..'Z').to_a.sample(4).join
+
+        print_http(request, id: req_id)
         begin
+          dur_start = Time.now
           response = http.request request
-        rescue EOFError => e
+          dur_end = Time.now
+          duration = dur_end - dur_start
+        rescue EOFError
           logger.error 'Socket closed unexpectedly'
-          raise e
+          raise
         end
-        print_http(response)
+        print_http(response, duration: duration, id: req_id)
+
         data = JSON.parse(response.body, symbolize_names: true) rescue nil
 
         if response.is_a? Net::HTTPTooManyRequests
@@ -255,35 +322,41 @@ module MatrixSdk
       end
     end
 
+    # Generate a transaction ID
+    #
+    # @return [String] An arbitrary transaction ID
+    def transaction_id
+      ret = @transaction_id ||= 0
+      @transaction_id = @transaction_id.succ
+      ret
+    end
+
     private
 
-    def print_http(http)
+    def print_http(http, body: true, duration: nil, id: nil)
       return unless logger.debug?
 
       if http.is_a? Net::HTTPRequest
-        dir = '>'
+        dir = "#{id ? id + ' : ' : nil}>"
         logger.debug "#{dir} Sending a #{http.method} request to `#{http.path}`:"
       else
-        dir = '<'
-        logger.debug "#{dir} Received a #{http.code} #{http.message} response:"
+        dir = "#{id ? id + ' : ' : nil}<"
+        logger.debug "#{dir} Received a #{http.code} #{http.message} response:#{duration ? " [#{(duration * 1000).to_i}ms]" : nil}"
       end
       http.to_hash.map { |k, v| "#{k}: #{k == 'authorization' ? '[ REDACTED ]' : v.join(', ')}" }.each do |h|
         logger.debug "#{dir} #{h}"
       end
       logger.debug dir
-      clean_body = JSON.parse(http.body) rescue nil if http.body
-      clean_body.keys.each { |k| clean_body[k] = '[ REDACTED ]' if %w[password access_token].include?(k) }.to_json if clean_body
-      logger.debug "#{dir} #{clean_body.length < 200 ? clean_body : clean_body.slice(0..200) + "... [truncated, #{clean_body.length} Bytes]"}" if clean_body
+      if body
+        clean_body = JSON.parse(http.body) rescue nil if http.body
+        clean_body.keys.each { |k| clean_body[k] = '[ REDACTED ]' if %w[password access_token].include?(k) }.to_json if clean_body.is_a? Hash
+        clean_body = clean_body.to_s if clean_body
+        logger.debug "#{dir} #{clean_body.length < 200 ? clean_body : clean_body.slice(0..200) + "... [truncated, #{clean_body.length} Bytes]"}" if clean_body
+      end
     rescue StandardError => e
       logger.warn "#{e.class} occured while printing request debug; #{e.message}\n#{e.backtrace.join "\n"}"
     end
 
-    def transaction_id
-      ret = @transaction_id ||= 0
-      @transaction_id = @transaction_id.succ
-      ret
-    end
-
     def api_to_path(api)
       # TODO: <api>_current / <api>_latest
       "/_matrix/#{api.to_s.split('_').join('/')}"
@@ -303,7 +376,7 @@ module MatrixSdk
       @http.open_timeout = open_timeout
       @http.read_timeout = read_timeout
       @http.use_ssl = homeserver.scheme == 'https'
-      @http.verify_mode = validate_certificate ? ::OpenSSL::SSL::VERIFY_NONE : nil
+      @http.verify_mode = validate_certificate ? ::OpenSSL::SSL::VERIFY_PEER : ::OpenSSL::SSL::VERIFY_NONE
       @http.start
       @http
     end

data/lib/matrix_sdk/client.rb

@@ -11,7 +11,16 @@ module MatrixSdk
     include MatrixSdk::Logging
     extend Forwardable
 
-    attr_reader :api
+    # @!attribute api [r] The underlying API connection
+    #   @return [Api] The underlying API connection
+    # @!attribute next_batch [r] The batch token for a running sync
+    #   @return [String] The opaque batch token
+    # @!attribute cache [rw] The cache level
+    #   @return [:all,:some,:none] The level of caching to do
+    # @!attribute sync_filter [rw] The global sync filter
+    #   @return [Hash,String] A filter definition, either as defined by the
+    #           Matrix spec, or as an identifier returned by a filter creation request
+    attr_reader :api, :next_batch
     attr_accessor :cache, :sync_filter
 
     events :error, :event, :presence_event, :invite_event, :leave_event, :ephemeral_event
@@ -22,9 +31,20 @@ module MatrixSdk
                    :access_token, :access_token=, :device_id, :device_id=, :homeserver, :homeserver=,
                    :validate_certificate, :validate_certificate=
 
+    # Create a new client instance from only a Matrix HS domain
+    #
+    # This will use the well-known delegation lookup to find the correct client URL
+    #
+    # @note This method will not verify that the created client has a valid connection,
+    #       it will only perform the necessary lookups to build a connection URL.
+    # @return [Client] The new client instance
+    # @param domain [String] The domain name to look up
+    # @param params [Hash] Additional parameters to pass along to {Api.new_for_domain} as well as {initialize}
+    # @see Api.new_for_domain
+    # @see #initialize
     def self.new_for_domain(domain, **params)
       api = MatrixSdk::Api.new_for_domain(domain, keep_wellknown: true)
-      return new(api, params) unless api.well_known.key? 'm.identity_server'
+      return new(api, params) unless api.well_known&.key?('m.identity_server')
 
       identity_server = MatrixSdk::Api.new(api.well_known['m.identity_server']['base_url'], protocols: %i[IS])
       new(api, params.merge(identity_server: identity_server))
@@ -53,7 +73,7 @@ module MatrixSdk
       @rooms = {}
       @users = {}
       @cache = client_cache
-      @identity_server = params.fetch(:identity_server, nil)
+      @identity_server = nil
 
       @sync_token = nil
       @sync_thread = nil
@@ -75,22 +95,42 @@ module MatrixSdk
       @mxid = params[:user_id]
     end
 
+    # Gets the currently logged in user's MXID
+    #
+    # @return [MXID] The MXID of the current user
     def mxid
       @mxid ||= begin
-        api.whoami?[:user_id] if api&.access_token
+        MXID.new api.whoami?[:user_id] if api&.access_token
       end
     end
 
-    def mxid=(id)
-      id = MXID.new id.to_s unless id.is_a? MXID
-      raise ArgumentError, 'Must be a User ID' unless id.user?
+    alias user_id mxid
 
-      @mxid = id
+    # Gets the current user presence status object
+    #
+    # @return [Response] The user presence
+    # @see User#presence
+    # @see Protocols::CS#get_presence_status
+    def presence
+      api.get_presence_status(mxid).tap { |h| h.delete :user_id }
     end
 
-    alias user_id mxid
-    alias user_id= mxid=
+    # Sets the current user's presence status
+    #
+    # @param status [:online,:offline,:unavailable] The new status to use
+    # @param message [String] A custom status message to set
+    # @see User#presence=
+    # @see Protocols::CS#set_presence_status
+    def set_presence(status, message: nil)
+      raise ArgumentError, 'Presence must be one of :online, :offline, :unavailable' unless %i[online offline unavailable].include?(status)
+
+      api.set_presence_status(mxid, status, message: message)
+    end
 
+    # Gets a list of all the public rooms on the connected HS
+    #
+    # @note This will try to list all public rooms on the HS, and may take a while on larger instances
+    # @return [Array[Room]] The public rooms
     def public_rooms
       rooms = []
       since = nil
@@ -114,6 +154,12 @@ module MatrixSdk
       rooms
     end
 
+    # Gets a list of all relevant rooms, either the ones currently handled by
+    # the client, or the list of currently joined ones if no rooms are handled
+    #
+    # @return [Array[Room]] All the currently handled rooms
+    # @note This will always return the empty array if the cache level is set
+    #       to :none
     def rooms
       if @rooms.empty? && cache != :none
         api.get_joined_rooms.joined_rooms.each do |id|
@@ -124,6 +170,11 @@ module MatrixSdk
       @rooms.values
     end
 
+    # Refresh the list of currently handled rooms, replacing it with the user's
+    # currently joined rooms.
+    #
+    # @note This will be a no-op if the cache level is set to :none
+    # @return [Boolean] If the refresh succeeds
     def reload_rooms!
       return true if cache == :none
 
@@ -137,12 +188,25 @@ module MatrixSdk
     end
     alias refresh_rooms! reload_rooms!
 
+    # Register - and log in - on the connected HS as a guest
+    #
+    # @note This feature is not commonly supported by many HSes
     def register_as_guest
       data = api.register(kind: :guest)
       post_authentication(data)
     end
 
-    def register_with_password(username, password, full_state: true, **params)
+    # Register a new user account on the connected HS
+    #
+    # This will also trigger an initial sync unless no_sync is set
+    #
+    # @note This method will currently always use auth type 'm.login.dummy'
+    # @param username [String] The new user's name
+    # @param password [String] The new user's password
+    # @param params [Hash] Additional options
+    # @option params [Boolean] :no_sync Skip the initial sync on registering
+    # @option params [Boolean] :allow_sync_retry Allow sync to retry on failure
+    def register_with_password(username, password, **params)
       username = username.to_s unless username.is_a?(String)
       password = password.to_s unless password.is_a?(String)
 
@@ -154,10 +218,21 @@ module MatrixSdk
 
       return if params[:no_sync]
 
-      sync full_state: full_state,
+      sync full_state: true,
            allow_sync_retry: params.fetch(:allow_sync_retry, nil)
     end
 
+    # Logs in as a user on the connected HS
+    #
+    # This will also trigger an initial sync unless no_sync is set
+    #
+    # @param username [String] The username of the user
+    # @param password [String] The password of the user
+    # @param sync_timeout [Numeric] The timeout of the initial sync on login
+    # @param full_state [Boolean] Should the initial sync retrieve full state
+    # @param params [Hash] Additional options
+    # @option params [Boolean] :no_sync Skip the initial sync on registering
+    # @option params [Boolean] :allow_sync_retry Allow sync to retry on failure
     def login(username, password, sync_timeout: 15, full_state: false, **params)
       username = username.to_s unless username.is_a?(String)
       password = password.to_s unless password.is_a?(String)
@@ -175,6 +250,17 @@ module MatrixSdk
            allow_sync_retry: params.fetch(:allow_sync_retry, nil)
     end
 
+    # Logs in as a user on the connected HS
+    #
+    # This will also trigger an initial sync unless no_sync is set
+    #
+    # @param username [String] The username of the user
+    # @param token [String] The token to log in with
+    # @param sync_timeout [Numeric] The timeout of the initial sync on login
+    # @param full_state [Boolean] Should the initial sync retrieve full state
+    # @param params [Hash] Additional options
+    # @option params [Boolean] :no_sync Skip the initial sync on registering
+    # @option params [Boolean] :allow_sync_retry Allow sync to retry on failure
     def login_with_token(username, token, sync_timeout: 15, full_state: false, **params)
       username = username.to_s unless username.is_a?(String)
       token = token.to_s unless token.is_a?(String)
@@ -192,30 +278,90 @@ module MatrixSdk
            allow_sync_retry: params.fetch(:allow_sync_retry, nil)
     end
 
+    # Logs out of the current session
     def logout
       api.logout
       @api.access_token = nil
       @mxid = nil
     end
 
+    # Check if there's a currently logged in session
+    #
+    # @note This will not check if the session is valid, only if it exists
+    # @return [Boolean] If there's a current session
     def logged_in?
-      !(mxid.nil? || @api.access_token.nil?)
+      !@api.access_token.nil?
+    end
+
+    # Retrieve a list of all registered third-party IDs for the current user
+    #
+    # @return [Response] A response hash containing the key :threepids
+    # @see Protocols::CS#get_3pids
+    def registered_3pids
+      data = api.get_3pids
+      data.threepids.each do |obj|
+        obj.instance_eval do
+          def added_at
+            Time.at(self[:added_at] / 1000)
+          end
+
+          def validated_at
+            return unless validated?
+
+            Time.at(self[:validated_at] / 1000)
+          end
+
+          def validated?
+            key? :validated_at
+          end
+
+          def to_s
+            "#{self[:medium]}:#{self[:address]}"
+          end
+
+          def inspect
+            "#<MatrixSdk::Response 3pid=#{to_s.inspect} added_at=\"#{added_at}\"#{validated? ? " validated_at=\"#{validated_at}\"" : ''}>"
+          end
+        end
+      end
+      data
     end
 
+    # Creates a new room
+    #
+    # @example Creating a room with an alias
+    #   client.create_room('myroom')
+    #   #<MatrixSdk::Room ... >
+    #
+    # @param room_alias [String] A default alias to set on the room, should only be the localpart
+    # @return [Room] The resulting room
+    # @see Protocols::CS#create_room
     def create_room(room_alias = nil, **params)
       data = api.create_room(params.merge(room_alias: room_alias))
       ensure_room(data.room_id)
     end
 
+    # Joins an already created room
+    #
+    # @param room_id_or_alias [String,MXID] A room alias (#room:example.com) or a room ID (!id:example.com)
+    # @param server_name [Array[String]] A list of servers to attempt the join through, required for IDs
+    # @return [Room] The resulting room
+    # @see Protocols::CS#join_room
     def join_room(room_id_or_alias, server_name: [])
       server_name = [server_name] unless server_name.is_a? Array
       data = api.join_room(room_id_or_alias, server_name: server_name)
       ensure_room(data.fetch(:room_id, room_id_or_alias))
     end
 
+    # Find a room in the locally cached list of rooms that the current user is part of
+    #
+    # @param room_id_or_alias [String,MXID] A room ID or alias
+    # @param only_canonical [Boolean] Only match alias against the canonical alias
+    # @return [Room] The found room
+    # @return [nil] If no room was found
     def find_room(room_id_or_alias, only_canonical: false)
       room_id_or_alias = MXID.new(room_id_or_alias.to_s) unless room_id_or_alias.is_a? MXID
-      raise ArgumentError, 'Must be a room id or alias' unless %i[room_id room_alias].include? room_id_or_alias.type
+      raise ArgumentError, 'Must be a room id or alias' unless room_id_or_alias.room?
 
       return @rooms.fetch(room_id_or_alias.to_s, nil) if room_id_or_alias.room_id?
 
@@ -224,7 +370,21 @@ module MatrixSdk
       @rooms.values.find { |r| r.aliases.include? room_id_or_alias.to_s }
     end
 
+    # Get a User instance from a MXID
+    #
+    # @param user_id [String,MXID,:self] The MXID to look up, will also accept :self in order to get the currently logged-in user
+    # @return [User] The User instance for the specified user
+    # @raise [ArgumentError] If the input isn't a valid user ID
+    # @note The method doesn't perform any existence checking, so the returned User object may point to a non-existent user
     def get_user(user_id)
+      user_id = mxid if user_id == :self
+
+      user_id = MXID.new user_id.to_s unless user_id.is_a? MXID
+      raise ArgumentError, 'Must be a User ID' unless user_id.user?
+
+      # To still use regular string storage in the hash itself
+      user_id = user_id.to_s
+
       if cache == :all
         @users[user_id] ||= User.new(self, user_id)
       else
@@ -232,10 +392,23 @@ module MatrixSdk
       end
     end
 
+    # Remove a room alias
+    #
+    # @param room_alias [String,MXID] The room alias to remove
+    # @see Protocols::CS#remove_room_alias
     def remove_room_alias(room_alias)
+      room_alias = MXID.new room_alias.to_s unless room_alias.is_a? MXID
+      raise ArgumentError, 'Must be a room alias' unless room_alias.room_alias?
+
       api.remove_room_alias(room_alias)
     end
 
+    # Upload a piece of data to the media repo
+    #
+    # @return [URI::MATRIX] A Matrix content (mxc://) URL pointing to the uploaded data
+    # @param content [String] The data to upload
+    # @param content_type [String] The MIME type of the data
+    # @see Protocols::CS#media_upload
     def upload(content, content_type)
       data = api.media_upload(content, content_type)
       return data[:content_uri] if data.key? :content_uri
@@ -243,25 +416,72 @@ module MatrixSdk
       raise MatrixUnexpectedResponseError, 'Upload succeeded, but no media URI returned'
     end
 
+    # Starts a background thread that will listen to new events
+    #
+    # @see sync For What parameters are accepted
     def start_listener_thread(**params)
+      return if listening?
+
       @should_listen = true
-      thread = Thread.new { listen_forever(params) }
+      if api.protocol?(:MSC) && api.msc2108?
+        params[:filter] = sync_filter unless params.key? :filter
+        params[:filter] = params[:filter].to_json unless params[:filter].nil? || params[:filter].is_a?(String)
+        params[:since] = @next_batch if @next_batch
+
+        errors = 0
+        thread, cancel_token = api.msc2108_sync_sse(params) do |data, event:, id:|
+          @next_batch = id if id
+          if event.to_sym == :sync
+            handle_sync_response(data)
+            errors = 0
+          elsif event.to_sym == :sync_error
+            logger.error "SSE Sync error received; #{data.type}: #{data.message}"
+            errors += 1
+
+            # TODO: Allow configuring
+            raise 'Aborting due to excessive errors' if errors >= 5
+          end
+        end
+
+        @should_listen = cancel_token
+      else
+        thread = Thread.new { listen_forever(params) }
+      end
       @sync_thread = thread
       thread.run
     end
 
+    # Stops the running background thread if one is active
     def stop_listener_thread
       return unless @sync_thread
 
-      @should_listen = false
-      @sync_thread.join if @sync_thread.alive?
+      if @should_listen.is_a? Hash
+        @should_listen[:run] = false
+      else
+        @should_listen = false
+      end
+      if @sync_thread.alive?
+        ret = @sync_thread.join(2)
+        @sync_thread.kill unless ret
+      end
       @sync_thread = nil
     end
 
+    # Check if there's a thread listening for events
     def listening?
       @sync_thread&.alive? == true
     end
 
+    # Run a message sync round, triggering events as necessary
+    #
+    # @param skip_store_batch [Boolean] Should this sync skip storing the returned next_batch token,
+    #        doing this would mean the next sync re-runs from the same point. Useful with use of filters.
+    # @param params [Hash] Additional options
+    # @option params [String,Hash] :filter (#sync_filter) A filter to use for this sync
+    # @option params [Numeric] :timeout (30) A timeout value in seconds for the sync request
+    # @option params [Numeric] :allow_sync_retry (0) The number of retries allowed for this sync request
+    # @option params [String] :since An override of the "since" token to provide to the sync request
+    # @see Protocols::CS#sync
     def sync(skip_store_batch: false, **params)
       extra_params = {
         filter: sync_filter,
@@ -283,11 +503,26 @@ module MatrixSdk
       @next_batch = data[:next_batch] unless skip_store_batch
 
       handle_sync_response(data)
+      true
     end
 
     alias listen_for_events sync
 
-    private
+    # Ensures that a room exists in the cache
+    #
+    # @param room_id [String,MXID] The room ID to ensure
+    # @return [Room] The room object for the requested room
+    def ensure_room(room_id)
+      room_id = MXID.new room_id.to_s unless room_id.is_a? MXID
+      raise ArgumentError, 'Must be a room ID' unless room_id.room_id?
+
+      room_id = room_id.to_s
+      @rooms.fetch(room_id) do
+        room = Room.new(self, room_id)
+        @rooms[room_id] = room unless cache == :none
+        room
+      end
+    end
 
     def listen_forever(timeout: 30, bad_sync_timeout: 5, sync_interval: 30, **params)
       orig_bad_sync_timeout = bad_sync_timeout + 0
@@ -312,6 +547,8 @@ module MatrixSdk
       fire_error(ErrorEvent.new(e, :listener_thread))
     end
 
+    private
+
     def post_authentication(data)
       @mxid = data[:user_id]
       @api.access_token = data[:access_token]
@@ -320,19 +557,11 @@ module MatrixSdk
       access_token
     end
 
-    def ensure_room(room_id)
-      room_id = room_id.to_s unless room_id.is_a? String
-      @rooms.fetch(room_id) do
-        room = Room.new(self, room_id)
-        @rooms[room_id] = room unless cache == :none
-        room
-      end
-    end
-
     def handle_state(room_id, state_event)
       return unless state_event.key? :type
 
       room = ensure_room(room_id)
+      room.send :put_state_event, state_event
       content = state_event[:content]
       case state_event[:type]
       when 'm.room.name'
@@ -346,9 +575,9 @@ module MatrixSdk
       when 'm.room.aliases'
         room.instance_variable_get('@aliases').concat content[:aliases]
       when 'm.room.join_rules'
-        room.instance_variable_set '@join_rule', content[:join_rule].to_sym
+        room.instance_variable_set '@join_rule', content[:join_rule].nil? ? nil : content[:join_rule].to_sym
       when 'm.room.guest_access'
-        room.instance_variable_set '@guest_access', content[:guest_access].to_sym
+        room.instance_variable_set '@guest_access', content[:guest_access].nil? ? nil : content[:guest_access].to_sym
       when 'm.room.member'
         return unless cache == :all
 
@@ -368,10 +597,12 @@ module MatrixSdk
       end
 
       data[:rooms][:invite].each do |room_id, invite|
+        invite[:room_id] = room_id.to_s
         fire_invite_event(MatrixEvent.new(self, invite), room_id.to_s)
       end
 
       data[:rooms][:leave].each do |room_id, left|
+        left[:room_id] = room_id.to_s
         fire_leave_event(MatrixEvent.new(self, left), room_id.to_s)
       end
 
@@ -387,7 +618,7 @@ module MatrixSdk
 
         join[:timeline][:events].each do |event|
           event[:room_id] = room_id.to_s
-          handle_state(room_id, event) unless event[:type] == 'm.room.message'
+          handle_state(room_id, event) if event.key? :state_key
           room.send :put_event, event
 
           fire_event(MatrixEvent.new(self, event), event[:type])