class Chatrix::Matrix

Provides an interface to the Matrix API on a homeserver.

Detailed information about the data structures is not included here and can be found on the {matrix.org/docs/api/client-server Matrix API page}.

@note Any of the methods may raise the errors listed in {#parse_response}.

Consider this when calling the methods.

@note Endpoints that require a room ID in the official API can be passed

a room alias in this implementation, the room ID will be automatically
looked up from the homeserver.

Constants

API_PATH

API path used.

DEFAULT_HOMESERVER

Default homeserver used if none is specified.

ERROR_HANDLERS

Registered request error handlers.

METHODS

Maps HTTP methods to their respective HTTParty method.

Attributes

access_token[RW]

@return [String] the access token used when performing requests

to the homeserver.
homeserver[R]

@return [String] the homeserver for this API object.

media[R]

@return [Api::Media] the instance of Api::Media to perform media-related

API calls with.
push[R]

@return [Api::Push] the instance of Api::Push to perform push-related

API calls with.
rooms[R]

@return [Api::Rooms] the instance of Api::Rooms to perform room-related

API calls with.
session[R]

@return [Api::Session] the instance of Api::Session to perform

session-related API calls with.
users[R]

@return [Api::Users] the instance of Api::Users to perform user-related

API calls with.

Public Class Methods

new(token = nil, homeserver = DEFAULT_HOMESERVER) click to toggle source

Initializes a new instance of Matrix.

@param token [String] The access token to use. @param homeserver [String] The homeserver to make requests to.

# File lib/chatrix/matrix.rb, line 89
def initialize(token = nil, homeserver = DEFAULT_HOMESERVER)
  @homeserver = homeserver
  @base_uri = @homeserver + API_PATH
  @access_token = token

  @session = Api::Session.new self
  @users = Api::Users.new self
  @rooms = Api::Rooms.new self
  @media = Api::Media.new self
  @push = Api::Push.new self
end

Public Instance Methods

create_filter(user, filter) click to toggle source

Uploads a filter to the server. @param user [String] The user to upload the filter as. @param filter [Hash] The filter definition. @return [String] The ID of the created filter.

# File lib/chatrix/matrix.rb, line 158
def create_filter(user, filter)
  make_request(:post, "/user/#{user}/filter", content: filter)['filter_id']
end
get_filter(user, filter) click to toggle source

Gets the definition for a filter. @param user [String] The user that has the filter. @param filter [String] The ID of the filter to get. @return [Hash] The filter definition.

# File lib/chatrix/matrix.rb, line 150
def get_filter(user, filter)
  make_request(:get, "/user/#{user}/filter/#{filter}").parsed_response
end
make_request(method, path, opts = {}, &block) click to toggle source

Helper method for performing requests to the homeserver.

@param method [Symbol] HTTP request method to use. Use only symbols

available as keys in {METHODS}.

@param path [String] The API path to query, relative to the base

API path, eg. `/login`.

@param opts [Hash] Additional request options.

@option opts [Hash] :params Additional parameters to include in the

query string (part of the URL, not put in the request body).

@option opts [Hash,#read] :content Content to put in the request body.

If set, must be a Hash or a stream object.

@option opts [Hash{String => String}] :headers Additional headers to

include in the request.

@option opts [String,nil] :base If this is set, it will be used as the

base URI for the request instead of the default (`@base_uri`).

@yield [fragment] HTTParty will call the block during the request.

@return [HTTParty::Response] The HTTParty response object.

# File lib/chatrix/matrix.rb, line 201
def make_request(method, path, opts = {}, &block)
  path = (opts[:base] || @base_uri) + URI.encode(path)
  options = make_options opts[:params], opts[:content], opts[:headers]

  parse_response METHODS[method].call(path, options, &block)
end
sync(filter: nil, since: nil, full_state: false, set_presence: true, timeout: 30_000) click to toggle source

Synchronize with the latest state on the server.

For initial sync, call this method with the `since` parameter set to `nil`.

@param filter [String,Hash] The ID of a filter to use, or provided

directly as a hash.

@param since [String,nil] A point in time to continue sync from.

Will retrieve a snapshot of the state if not set, which will also
provide a `next_batch` value to use for `since` in the next call.

@param full_state [Boolean] If `true`, all state events will be returned

for all rooms the user is a member of.

@param set_presence [Boolean] If `true`, the user performing this request

will have their presence updated to show them as being online.

@param timeout [Fixnum] Maximum time (in milliseconds) to wait before

the request is aborted.

@return [Hash] The initial snapshot of the state (if no `since` value

was provided), or a delta to use for updating state.
# File lib/chatrix/matrix.rb, line 134
def sync(filter: nil, since: nil, full_state: false,
         set_presence: true, timeout: 30_000)
  options = { full_state: full_state }

  options[:since] = since if since
  options[:set_presence] = 'offline' unless set_presence
  options[:timeout] = timeout if timeout
  options[:filter] = parse_filter filter

  make_request(:get, '/sync', params: options).parsed_response
end
turn_server() click to toggle source

Gets information about the TURN server. Contains credentials and server URIs for connecting. @return [Hash] TURN server details.

# File lib/chatrix/matrix.rb, line 177
def turn_server
  make_request(:get, '/voip/turnServer').parsed_response
end
versions() click to toggle source

Gets supported API versions from the server. @return [Array<String>] an array with the supported versions.

# File lib/chatrix/matrix.rb, line 103
def versions
  make_request(
    :get, '/versions', base: "#{@homeserver}/_matrix/client"
  )['versions']
end
whois(user) click to toggle source

Performs a whois lookup on the specified user. @param user [String] The user to look up. @return [Hash] Information about the user.

# File lib/chatrix/matrix.rb, line 112
def whois(user)
  make_request(:get, "/admin/whois/#{user}").parsed_response
end

Private Instance Methods

make_body(content) click to toggle source

Create a hash with body content based on the type of `content`. @param content [Hash,#read,Object] Some kind of content to put into

the request body. Can be a Hash, stream object, or other kind of
object.

@return [Hash{Symbol => Object}] A hash with the relevant body key

and value.
# File lib/chatrix/matrix.rb, line 234
def make_body(content)
  key = content.respond_to?(:read) ? :body_stream : :body
  value = content.is_a?(Hash) ? content.to_json : content
  { key => value }
end
make_options(params, content, headers = {}) click to toggle source

Create an options Hash to pass to a server request.

This method embeds the {#access_token access_token} into the query parameters.

@param params [Hash{String=>String},nil] Query parameters to add to

the options hash.

@param content [Hash,#read,nil] Request content. Can be a hash,

stream, or `nil`.

@return [Hash] Options hash ready to be passed into a server request.

# File lib/chatrix/matrix.rb, line 220
def make_options(params, content, headers = {})
  { headers: headers }.tap do |o|
    o[:query] = @access_token ? { access_token: @access_token } : {}
    o[:query].merge!(params) if params.is_a? Hash
    o.merge! make_body content
  end
end
parse_filter(filter) click to toggle source

Parses a filter object for use in a query string. @param filter [String,Hash] The filter object to parse. @return [String] Query-friendly filter object. Or the `filter`

parameter as-is if it failed to parse.
# File lib/chatrix/matrix.rb, line 272
def parse_filter(filter)
  filter.is_a?(Hash) ? URI.encode(filter.to_json) : filter
end
parse_response(response) click to toggle source

Parses a HTTParty Response object and returns it if it was successful.

@param response [HTTParty::Response] The response object to parse. @return [HTTParty::Response] The same response object that was passed

in, if the request was successful.

@raise [RequestError] If a `400` response code was returned from the

request.

@raise [AuthenticationError] If a `401` response code was returned

from the request.

@raise [ForbiddenError] If a `403` response code was returned from the

request.

@raise [NotFoundError] If a `404` response code was returned from the

request.

@raise [RateLimitError] If a `429` response code was returned from the

request.

@raise [ApiError] If an unknown response code was returned from the

request.
# File lib/chatrix/matrix.rb, line 258
def parse_response(response)
  case response.code
  when 200 # OK
    response
  else
    handler = ERROR_HANDLERS[response.code]
    raise handler.first.new(response.parsed_response), handler.last
  end
end