Class: Chatrix::Matrix
- Inherits:
-
Object
- Object
- Chatrix::Matrix
- Includes:
- HTTParty
- Defined in:
- lib/chatrix/matrix.rb
Overview
Any of the methods may raise the errors listed in #parse_response. Consider this when calling the methods.
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.
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 API page.
Constant Summary collapse
- METHODS =
Maps HTTP methods to their respective HTTParty method.
{ get: -> (path, , &block) { get path, , &block }, put: -> (path, , &block) { put path, , &block }, post: -> (path, , &block) { post path, , &block }, delete: -> (path, , &block) { delete path, , &block } }.freeze
- ERROR_HANDLERS =
Registered request error handlers.
{ 400 => [RequestError, 'Request failed'], 401 => [AuthenticationError, 'Server requests additional authentication'], 403 => [ForbiddenError, 'You do not have access to that resource'], 404 => [NotFoundError, 'The resource was not found'], 429 => [RateLimitError, 'The request was rate limited'] }.tap do |h| h.default = [ApiError, 'An unknown API error occurred.'] end.freeze
- DEFAULT_HOMESERVER =
Default homeserver used if none is specified.
'https://matrix.org'.freeze
- API_PATH =
API path used.
'/_matrix/client/r0'.freeze
Instance Attribute Summary collapse
-
#access_token ⇒ String
The access token used when performing requests to the homeserver.
-
#homeserver ⇒ String
readonly
The homeserver for this API object.
-
#media ⇒ Api::Media
readonly
The instance of Api::Media to perform media-related API calls with.
-
#push ⇒ Api::Push
readonly
The instance of Api::Push to perform push-related API calls with.
-
#rooms ⇒ Api::Rooms
readonly
The instance of Api::Rooms to perform room-related API calls with.
-
#session ⇒ Api::Session
readonly
The instance of Api::Session to perform session-related API calls with.
-
#users ⇒ Api::Users
readonly
The instance of Api::Users to perform user-related API calls with.
Instance Method Summary collapse
-
#create_filter(user, filter) ⇒ String
Uploads a filter to the server.
-
#get_filter(user, filter) ⇒ Hash
Gets the definition for a filter.
-
#initialize(token = nil, homeserver = DEFAULT_HOMESERVER) ⇒ Matrix
constructor
Initializes a new instance of Matrix.
-
#make_body(content) ⇒ Hash{Symbol => Object}
private
Create a hash with body content based on the type of
content
. -
#make_options(params, content, headers = {}) ⇒ Hash
private
Create an options Hash to pass to a server request.
-
#make_request(method, path, opts = {}) {|fragment| ... } ⇒ HTTParty::Response
Helper method for performing requests to the homeserver.
-
#parse_filter(filter) ⇒ String
private
Parses a filter object for use in a query string.
-
#parse_response(response) ⇒ HTTParty::Response
private
Parses a HTTParty Response object and returns it if it was successful.
-
#search(from: nil, options: {}) ⇒ Hash
Performs a full text search on the server.
-
#sync(filter: nil, since: nil, full_state: false, set_presence: true, timeout: 30_000) ⇒ Hash
Synchronize with the latest state on the server.
-
#turn_server ⇒ Hash
Gets information about the TURN server.
-
#versions ⇒ Array<String>
Gets supported API versions from the server.
-
#whois(user) ⇒ Hash
Performs a whois lookup on the specified user.
Constructor Details
#initialize(token = nil, homeserver = DEFAULT_HOMESERVER) ⇒ Matrix
Initializes a new instance of Matrix.
89 90 91 92 93 94 95 96 97 98 99 |
# 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 |
Instance Attribute Details
#access_token ⇒ String
Returns the access token used when performing requests to the homeserver.
60 61 62 |
# File 'lib/chatrix/matrix.rb', line 60 def access_token @access_token end |
#homeserver ⇒ String (readonly)
Returns the homeserver for this API object.
63 64 65 |
# File 'lib/chatrix/matrix.rb', line 63 def homeserver @homeserver end |
#media ⇒ Api::Media (readonly)
Returns the instance of Api::Media to perform media-related API calls with.
79 80 81 |
# File 'lib/chatrix/matrix.rb', line 79 def media @media end |
#push ⇒ Api::Push (readonly)
Returns the instance of Api::Push to perform push-related API calls with.
83 84 85 |
# File 'lib/chatrix/matrix.rb', line 83 def push @push end |
#rooms ⇒ Api::Rooms (readonly)
Returns the instance of Api::Rooms to perform room-related API calls with.
75 76 77 |
# File 'lib/chatrix/matrix.rb', line 75 def rooms @rooms end |
#session ⇒ Api::Session (readonly)
Returns the instance of Api::Session to perform session-related API calls with.
67 68 69 |
# File 'lib/chatrix/matrix.rb', line 67 def session @session end |
#users ⇒ Api::Users (readonly)
Returns the instance of Api::Users to perform user-related API calls with.
71 72 73 |
# File 'lib/chatrix/matrix.rb', line 71 def users @users end |
Instance Method Details
#create_filter(user, filter) ⇒ String
Uploads a filter to the server.
158 159 160 |
# 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) ⇒ Hash
Gets the definition for a filter.
150 151 152 |
# File 'lib/chatrix/matrix.rb', line 150 def get_filter(user, filter) make_request(:get, "/user/#{user}/filter/#{filter}").parsed_response end |
#make_body(content) ⇒ Hash{Symbol => Object} (private)
Create a hash with body content based on the type of content
.
234 235 236 237 238 |
# 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 = {}) ⇒ Hash (private)
Create an options Hash to pass to a server request.
This method embeds the access_token into the query parameters.
220 221 222 223 224 225 226 |
# File 'lib/chatrix/matrix.rb', line 220 def (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 |
#make_request(method, path, opts = {}) {|fragment| ... } ⇒ HTTParty::Response
Helper method for performing requests to the homeserver.
201 202 203 204 205 206 |
# File 'lib/chatrix/matrix.rb', line 201 def make_request(method, path, opts = {}, &block) path = (opts[:base] || @base_uri) + URI.encode(path) = opts[:params], opts[:content], opts[:headers] parse_response METHODS[method].call(path, , &block) end |
#parse_filter(filter) ⇒ String (private)
Parses a filter object for use in a query string.
272 273 274 |
# 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) ⇒ HTTParty::Response (private)
Parses a HTTParty Response object and returns it if it was successful.
258 259 260 261 262 263 264 265 266 |
# 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 |
#search(from: nil, options: {}) ⇒ Hash
Performs a full text search on the server.
168 169 170 171 172 |
# File 'lib/chatrix/matrix.rb', line 168 def search(from: nil, options: {}) make_request( :post, '/search', params: { next_batch: from }, content: ).parsed_response end |
#sync(filter: nil, since: nil, full_state: false, set_presence: true, timeout: 30_000) ⇒ Hash
Synchronize with the latest state on the server.
For initial sync, call this method with the since
parameter
set to nil
.
134 135 136 137 138 139 140 141 142 143 144 |
# File 'lib/chatrix/matrix.rb', line 134 def sync(filter: nil, since: nil, full_state: false, set_presence: true, timeout: 30_000) = { full_state: full_state } [:since] = since if since [:set_presence] = 'offline' unless set_presence [:timeout] = timeout if timeout [:filter] = parse_filter filter make_request(:get, '/sync', params: ).parsed_response end |
#turn_server ⇒ Hash
Gets information about the TURN server. Contains credentials and server URIs for connecting.
177 178 179 |
# File 'lib/chatrix/matrix.rb', line 177 def turn_server make_request(:get, '/voip/turnServer').parsed_response end |
#versions ⇒ Array<String>
Gets supported API versions from the server.
103 104 105 106 107 |
# File 'lib/chatrix/matrix.rb', line 103 def versions make_request( :get, '/versions', base: "#{@homeserver}/_matrix/client" )['versions'] end |
#whois(user) ⇒ Hash
Performs a whois lookup on the specified user.
112 113 114 |
# File 'lib/chatrix/matrix.rb', line 112 def whois(user) make_request(:get, "/admin/whois/#{user}").parsed_response end |