matrix_sdk 1.5.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3aa6522f1b8b49ed1ea60dc27c67fefb9479b5aa27d87c4597edf97e76d4eb6
-  data.tar.gz: b2a6d3b5ff58c037092515ccf42e0a2683f1ef024a8b6731c824faade7649a0a
+  metadata.gz: 2e0e5819346e56fd4eac1564434e88399500adefe0def16bc706a25ec7a254b2
+  data.tar.gz: 2d74cd2d5203f5431396b03717c4302f9a0c7816c47eaa969e2395ab2eb46586
 SHA512:
-  metadata.gz: b55690dbf6fe96eeb24a6831d390e122962b1c68d5e0031deb32641eaeb7f38568d47ec728d0adbd4eb9aea5d1f2064ff926667588b9b77893314b999366245b
-  data.tar.gz: 73eb136cd9285ffc1415b79c25ac05807eb0b17f52865df329ebff1a83962a5005802a3f914b7ebfe8f6a2371097967955dcdcd6de01d4148c5fd9d3c96dafbd
+  metadata.gz: 7eb8ef8277b0bda1191915e5be4dcf93856cd876f611b77974b8dc88e5e230ba5c3300995157f9717a4b00d1a7cba7f7a618844cc436ad0b6a3ea5865367049d
+  data.tar.gz: bd888c36cf3a082360dbecc408c0a67e16ddb337a721105be7abf3a9662d81bfa564a1093a64d1f934d484af6a22a36e5b91bafde70f02a882e6d092e81d5459

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 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/api.rb

@@ -98,6 +98,7 @@ module MatrixSdk
       target_uri = nil
 
       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
@@ -110,6 +111,7 @@ module MatrixSdk
                      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")
                          JSON.parse(data)
@@ -153,6 +155,14 @@ module MatrixSdk
           ))
     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 +211,28 @@ 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
     def request(method, api, path, **options)
       url = homeserver.dup.tap do |u|
         u.path = api_to_path(api) + path
@@ -272,7 +304,8 @@ module MatrixSdk
       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
+      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
     rescue StandardError => e
       logger.warn "#{e.class} occured while printing request debug; #{e.message}\n#{e.backtrace.join "\n"}"
@@ -303,7 +336,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,6 +31,17 @@ 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'
@@ -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: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?
 
@@ -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,13 +416,19 @@ 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) }
       @sync_thread = thread
       thread.run
     end
 
+    # Stops the running background thread if one is active
     def stop_listener_thread
       return unless @sync_thread
 
@@ -258,10 +437,21 @@ module MatrixSdk
       @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,10 +473,27 @@ module MatrixSdk
       @next_batch = data[:next_batch] unless skip_store_batch
 
       handle_sync_response(data)
+      true
     end
 
     alias listen_for_events sync
 
+    # 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
+
     private
 
     def listen_forever(timeout: 30, bad_sync_timeout: 5, sync_interval: 30, **params)
@@ -320,15 +527,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
 
@@ -368,10 +566,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