matrix_sdk 1.4.0 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44e3f36b32757df6369cafc95f4b6d9b42cff5a8b5152373519556a227aa6be4
-  data.tar.gz: dfdb434855b6ceea028a2f374f239aeec92504f36d52e8400d500193d0642d80
+  metadata.gz: 487904c24bd70f3d0412ba040f84687d6ef7a6bfe570d259f6d5d73fe7194128
+  data.tar.gz: 7d6f53ba5ec1e1426c5bd274e0809f0edcb67a8e8a355b1dd6d409ac57ee3e0f
 SHA512:
-  metadata.gz: c5a57bafba59ce9616041f64172c4e5c117f7a46455612c8ae8c74693c691037e25dc5037be90c3d18600a3b30cdc2827761bfdcd9baea7ef5e5f6e7cbccc4cc
-  data.tar.gz: 99792cb46ab43e6e9d0757c5f2c171da05233d5b8d697ef1ad9d60eb2e2bdb707dca57e35b157687b6ea77ecfb955c579f72289d684699077af1f29de4ce0e54
+  metadata.gz: cfbaff099abec9777a5593fa1646ff5e4285fc246894f850b000834185d352f024e8bc9340c17554da6e73c056db9f327bd98f27c259d123ceadf78977203ed0
+  data.tar.gz: f53ec1ca41f8884a8916609f364db9fd849b8957629c1f46cfaa440910030035d6f4c92de464aaabd3dc3d207ccf47e9bedccce30980ab213a625d5bb4e13473

data/CHANGELOG.md

@@ -1,3 +1,46 @@
+## 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
+- Adds an `open_timeout` setter to the API
+- Fixes an overly aggressive filter for event handlers
+
 ## 1.4.0 - 2019-09-30
 
 - Adds the option to change the logger globally or per-object.

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!
@@ -42,10 +45,10 @@ module MatrixSdk
 
   def self.logger=(global_logger)
     @logger = global_logger
-    @use_global_logger = !global_logger.nil?
+    @global_logger = !global_logger.nil?
   end
 
   def self.global_logger?
-    @use_global_logger || false
+    @global_logger ||= false
   end
 end

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, :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
 
@@ -38,6 +34,7 @@ module MatrixSdk
     # @option params [Boolean] :validate_certificate (false) Should the connection require valid SSL certificates
     # @option params [Integer] :transaction_id (0) The starting ID for transactions
     # @option params [Numeric] :backoff_time (5000) The request backoff time in milliseconds
+    # @option params [Numeric] :open_timeout (60) The timeout in seconds to wait for a TCP session to open
     # @option params [Numeric] :read_timeout (240) The timeout in seconds for reading responses
     # @option params [Hash] :global_headers Additional headers to set for all requests
     # @option params [Boolean] :skip_login Should the API skip logging in if the HS URL contains user information
@@ -50,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)
@@ -63,12 +56,17 @@ module MatrixSdk
       @validate_certificate = params.fetch(:validate_certificate, false)
       @transaction_id = params.fetch(:transaction_id, 0)
       @backoff_time = params.fetch(:backoff_time, 5000)
+      @open_timeout = params.fetch(:open_timeout, 60)
       @read_timeout = params.fetch(:read_timeout, 240)
       @well_known = params.fetch(:well_known, {})
       @global_headers = DEFAULT_HEADERS.dup
       @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
@@ -94,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")
+                         uri = URI("https://#{domain}/.well-known/matrix/server")
+                         logger.debug "Trying #{uri}..."
+                         data = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 5, read_timeout: 5, write_timeout: 5) do |http|
+                           http.get(uri.path).body
+                         end
                          JSON.parse(data)
-                       rescue StandardError
+                       rescue StandardError => e
+                         logger.debug "Well-known failed with #{e.class}: #{e.message}"
                          nil
                        end
 
@@ -122,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
+                       uri = URI("https://#{domain}/.well-known/matrix/client")
+                       logger.debug "Trying #{uri}..."
+                       data = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 5, read_timeout: 5, write_timeout: 5) do |http|
+                         http.get(uri.path).body
+                       end
+                       data = JSON.parse(data)
+                     rescue StandardError => e
+                       logger.debug "Well-known failed with #{e.class}: #{e.message}"
                        nil
                      end
 
@@ -138,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")
@@ -151,10 +168,40 @@ 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
 
+    # @param seconds [Numeric]
+    # @return [Numeric]
+    def open_timeout=(seconds)
+      @http.finish if @http && @open_timeout != seconds
+      @open_timeout = seconds
+    end
+
     # @param seconds [Numeric]
     # @return [Numeric]
     def read_timeout=(seconds)
@@ -192,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
@@ -209,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
@@ -220,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
@@ -246,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('/')}"
@@ -291,9 +373,10 @@ module MatrixSdk
                   Net::HTTP.new(host, port)
                 end
 
+      @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

@@ -2,6 +2,7 @@
 
 require 'matrix_sdk'
 
+require 'English'
 require 'forwardable'
 
 module MatrixSdk
@@ -10,10 +11,19 @@ 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 :event, :presence_event, :invite_event, :leave_event, :ephemeral_event
+    events :error, :event, :presence_event, :invite_event, :leave_event, :ephemeral_event
     ignore_inspect :api,
                    :on_event, :on_presence_event, :on_invite_event, :on_leave_event, :on_ephemeral_event
 
@@ -21,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))
@@ -52,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
@@ -74,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
@@ -113,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|
@@ -123,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
 
@@ -136,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)
 
@@ -153,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)
@@ -174,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)
@@ -191,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:exmaple.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?
 
@@ -223,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
@@ -231,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
@@ -242,21 +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,
@@ -278,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
@@ -301,8 +541,14 @@ module MatrixSdk
           end
         end
       end
+    rescue StandardError => e
+      logger.error "Unhandled #{e.class} raised in background listener"
+      logger.error [e.message, *e.backtrace].join($RS)
+      fire_error(ErrorEvent.new(e, :listener_thread))
     end
 
+    private
+
     def post_authentication(data)
       @mxid = data[:user_id]
       @api.access_token = data[:access_token]
@@ -311,15 +557,6 @@ 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
 
@@ -337,9 +574,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
 
@@ -359,10 +596,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