Class: Ably::Rest::Client
- Inherits:
-
Object
- Object
- Ably::Rest::Client
- Extended by:
- Forwardable
- Includes:
- Modules::Conversions, Modules::HttpHelpers
- Defined in:
- lib/ably/rest/client.rb
Overview
Client for the Ably REST API
Constant Summary collapse
- DOMAIN =
Default Ably domain for REST
'rest.ably.io'
- HTTP_DEFAULTS =
Configuration for HTTP timeouts and HTTP request reattempts to fallback hosts
{ open_timeout: 4, request_timeout: 10, max_retry_duration: 15, max_retry_count: 3 }.freeze
Instance Attribute Summary collapse
-
#add_request_ids ⇒ Boolean
readonly
Whethere the Client has to add a random identifier to the path of a request.
-
#auth ⇒ Ably::Auth
readonly
Auth authentication object configured for this connection.
-
#auth_options ⇒ Hash
readonly
Auth options configured for this client.
-
#channels ⇒ Aby::Rest::Channels
readonly
The collection of Channels that have been created.
-
#client_id ⇒ String
readonly
A client ID, used for identifying this client for presence purposes.
-
#custom_host ⇒ String, Nil
readonly
The custom host that is being used if it was provided with the option
:rest_host
when the Client was created. -
#custom_port ⇒ Integer, Nil
readonly
The custom port for non-TLS requests if it was provided with the option
:port
when the Client was created. -
#custom_tls_port ⇒ Integer, Nil
readonly
The custom TLS port for TLS requests if it was provided with the option
:tls_port
when the Client was created. -
#encoders ⇒ Array<Ably::Models::MessageEncoder::Base>
readonly
private
The registered encoders that are used to encode and decode message payloads.
-
#endpoint ⇒ URI::Generic
readonly
Default Ably REST endpoint used for all requests.
-
#environment ⇒ String
readonly
Custom environment to use such as ‘sandbox’ when testing the client library against an alternate Ably environment.
-
#fallback_hosts ⇒ Object
readonly
The list of fallback hosts to be used by this client if empty or nil then fallback host functionality is disabled.
-
#http_defaults ⇒ Hash
readonly
The immutable configured HTTP defaults for this client.
-
#log_level ⇒ Logger::Severity
readonly
Log level configured for this Client.
-
#logger ⇒ Logger
readonly
The Logger for this client.
-
#mime_type ⇒ String
readonly
Mime type used for HTTP requests.
-
#options ⇒ Hash
readonly
private
The additional options passed to this Client’s #initialize method not available as attributes of this class.
-
#protocol ⇒ Symbol
readonly
The protocol configured for this client, either binary ‘:msgpack` or text based `:json`.
-
#protocol_binary? ⇒ Boolean
readonly
True of the transport #protocol communicates with Ably with a binary protocol.
-
#use_tls? ⇒ Boolean
readonly
True if client is configured to use TLS for all Ably communication.
Instance Method Summary collapse
-
#auth_request_timeout ⇒ Object
private
Allowable duration for an external auth request For REST client this defaults to request_timeout For Realtime clients this defaults to realtime_request_timeout.
-
#channel(name, channel_options = {}) ⇒ Ably::Rest::Channel
Return a REST Channel for the given name.
-
#connection(options = {}) ⇒ Faraday::Connection
private
Connection used to make HTTP requests.
-
#fallback_connection ⇒ Faraday::Connection
private
Fallback connection used to make HTTP requests.
-
#get(path, params = {}, options = {}) ⇒ Faraday::Response
private
Perform an HTTP GET request to the API using configured authentication.
-
#initialize(options) ⇒ Ably::Rest::Client
constructor
Creates a Rest Client and configures the Auth object for the connection.
-
#lib_version_id ⇒ Object
private
Library Ably version user agent.
-
#post(path, params, options = {}) ⇒ Faraday::Response
private
Perform an HTTP POST request to the API using configured authentication.
-
#register_encoder(encoder, options = {}) ⇒ void
private
Register a message encoder and decoder that implements Ably::Models::MessageEncoders::Base interface.
-
#request(method, path, params = {}, body = nil, headers = {}, options = {}) ⇒ Ably::Models::HttpPaginatedResponse<>
Perform an HTTP request to the Ably API This is a convenience for customers who wish to use bleeding edge REST API functionality that is either not documented or is not included in the API for our client libraries.
-
#stats(options = {}) ⇒ Ably::Models::PaginatedResult<Ably::Models::Stats>
Retrieve the Stats for the application.
-
#time ⇒ Time
Retrieve the Ably service time.
Constructor Details
#initialize(options) ⇒ Ably::Rest::Client
Creates a Rest Client and configures the Auth object for the connection.
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 |
# File 'lib/ably/rest/client.rb', line 131 def initialize() raise ArgumentError, 'Options Hash is expected' if .nil? = .clone if .kind_of?(String) = if .match(Auth::API_KEY_REGEX) { key: } else { token: } end end @realtime_client = .delete(:realtime_client) @tls = .delete(:tls) == false ? false : true @environment = .delete(:environment) # nil is production @environment = nil if [:production, 'production'].include?(@environment) @protocol = .delete(:protocol) || :msgpack @debug_http = .delete(:debug_http) @log_level = .delete(:log_level) || ::Logger::WARN @custom_logger = .delete(:logger) @custom_host = .delete(:rest_host) @custom_port = .delete(:port) @custom_tls_port = .delete(:tls_port) @add_request_ids = .delete(:add_request_ids) if [:fallback_hosts_use_default] && [:fallback_jhosts] raise ArgumentError, "fallback_hosts_use_default cannot be set to trye when fallback_jhosts is also provided" end @fallback_hosts = case when .delete(:fallback_hosts_use_default) Ably::FALLBACK_HOSTS when = .delete(:fallback_hosts) when environment || custom_host || [:realtime_host] || custom_port || custom_tls_port [] else Ably::FALLBACK_HOSTS end @http_defaults = HTTP_DEFAULTS.dup .each do |key, val| if http_key = key[/^http_(.+)/, 1] @http_defaults[http_key.to_sym] = val if val && @http_defaults.has_key?(http_key.to_sym) end end @http_defaults.freeze if @log_level == :none @custom_logger = Ably::Models::NilLogger.new else @log_level = ::Logger.const_get(log_level.to_s.upcase) if log_level.kind_of?(Symbol) || log_level.kind_of?(String) end .delete(:use_binary_protocol).tap do |use_binary_protocol| if use_binary_protocol == true @protocol = :msgpack elsif use_binary_protocol == false @protocol = :json end end raise ArgumentError, 'Protocol is invalid. Must be either :msgpack or :json' unless [:msgpack, :json].include?(@protocol) token_params = .delete(:default_token_params) || {} @options = @auth = Auth.new(self, token_params, ) @channels = Ably::Rest::Channels.new(self) @encoders = [] .freeze initialize_default_encoders end |
Instance Attribute Details
#add_request_ids ⇒ Boolean (readonly)
Whethere the Ably::Rest::Client has to add a random identifier to the path of a request
88 89 90 |
# File 'lib/ably/rest/client.rb', line 88 def add_request_ids @add_request_ids end |
#auth ⇒ Ably::Auth (readonly)
Auth authentication object configured for this connection
45 46 47 |
# File 'lib/ably/rest/client.rb', line 45 def auth @auth end |
#auth_options ⇒ Hash (readonly)
Returns Auth options configured for this client.
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 |
# File 'lib/ably/rest/client.rb', line 17 class Client include Ably::Modules::Conversions include Ably::Modules::HttpHelpers extend Forwardable # Default Ably domain for REST DOMAIN = 'rest.ably.io' # Configuration for HTTP timeouts and HTTP request reattempts to fallback hosts HTTP_DEFAULTS = { open_timeout: 4, request_timeout: 10, max_retry_duration: 15, max_retry_count: 3 }.freeze def_delegators :auth, :client_id, :auth_options # Custom environment to use such as 'sandbox' when testing the client library against an alternate Ably environment # @return [String] attr_reader :environment # The protocol configured for this client, either binary `:msgpack` or text based `:json` # @return [Symbol] attr_reader :protocol # {Ably::Auth} authentication object configured for this connection # @return [Ably::Auth] attr_reader :auth # The collection of {Ably::Rest::Channel}s that have been created # @return [Aby::Rest::Channels] attr_reader :channels # Log level configured for this {Client} # @return [Logger::Severity] attr_reader :log_level # The custom host that is being used if it was provided with the option +:rest_host+ when the {Client} was created # @return [String,Nil] attr_reader :custom_host # The custom port for non-TLS requests if it was provided with the option +:port+ when the {Client} was created # @return [Integer,Nil] attr_reader :custom_port # The custom TLS port for TLS requests if it was provided with the option +:tls_port+ when the {Client} was created # @return [Integer,Nil] attr_reader :custom_tls_port # The immutable configured HTTP defaults for this client. # See {#initialize} for the configurable HTTP defaults prefixed with +http_+ # @return [Hash] attr_reader :http_defaults # The registered encoders that are used to encode and decode message payloads # @return [Array<Ably::Models::MessageEncoder::Base>] # @api private attr_reader :encoders # The additional options passed to this Client's #initialize method not available as attributes of this class # @return [Hash] # @api private attr_reader :options # The list of fallback hosts to be used by this client # if empty or nil then fallback host functionality is disabled attr_reader :fallback_hosts # Whethere the {Client} has to add a random identifier to the path of a request # @return [Boolean] attr_reader :add_request_ids # Creates a {Ably::Rest::Client Rest Client} and configures the {Ably::Auth} object for the connection. # # @param [Hash,String] options an options Hash used to configure the client and the authentication, or String with an API key or Token ID # @option options [Boolean] :tls (true) When false, TLS is disabled. Please note Basic Auth is disallowed without TLS as secrets cannot be transmitted over unsecured connections. # @option options [String] :key API key comprising the key name and key secret in a single string # @option options [String] :token Token string or {Models::TokenDetails} used to authenticate requests # @option options [String] :token_details {Models::TokenDetails} used to authenticate requests # @option options [Boolean] :use_token_auth Will force Basic Auth if set to false, and Token auth if set to true # @option options [String] :environment Specify 'sandbox' when testing the client library against an alternate Ably environment # @option options [Symbol] :protocol (:msgpack) Protocol used to communicate with Ably, :json and :msgpack currently supported # @option options [Boolean] :use_binary_protocol (true) When true will use the MessagePack binary protocol, when false it will use JSON encoding. This option will overide :protocol option # @option options [Logger::Severity,Symbol] :log_level (Logger::WARN) Log level for the standard Logger that outputs to STDOUT. Can be set to :fatal (Logger::FATAL), :error (Logger::ERROR), :warn (Logger::WARN), :info (Logger::INFO), :debug (Logger::DEBUG) or :none # @option options [Logger] :logger A custom logger can be used however it must adhere to the Ruby Logger interface, see http://www.ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html # @option options [String] :client_id client ID identifying this connection to other clients # @option options [String] :auth_url a URL to be used to GET or POST a set of token request params, to obtain a signed token request # @option options [Hash] :auth_headers a set of application-specific headers to be added to any request made to the +auth_url+ # @option options [Hash] :auth_params a set of application-specific query params to be added to any request made to the +auth_url+ # @option options [Symbol] :auth_method (:get) HTTP method to use with +auth_url+, must be either +:get+ or +:post+ # @option options [Proc] :auth_callback when provided, the Proc will be called with the token params hash as the first argument, whenever a new token is required. # The Proc should return a token string, {Ably::Models::TokenDetails} or JSON equivalent, {Ably::Models::TokenRequest} or JSON equivalent # @option options [Boolean] :query_time when true will query the {https://www.ably.io Ably} system for the current time instead of using the local time # @option options [Hash] :default_token_params convenience to pass in +token_params+ that will be used as a default for all token requests. See {Auth#create_token_request} # # @option options [Integer] :http_open_timeout (4 seconds) timeout in seconds for opening an HTTP connection for all HTTP requests # @option options [Integer] :http_request_timeout (10 seconds) timeout in seconds for any single complete HTTP request and response # @option options [Integer] :http_max_retry_count (3) maximum number of fallback host retries for HTTP requests that fail due to network issues or server problems # @option options [Integer] :http_max_retry_duration (15 seconds) maximum elapsed time in which fallback host retries for HTTP requests will be attempted i.e. if the first default host attempt takes 5s, and then the subsequent fallback retry attempt takes 7s, no further fallback host attempts will be made as the total elapsed time of 12s exceeds the default 10s limit # # @option options [Boolean] :fallback_hosts_use_default (false) When true, forces the user of fallback hosts even if a non-default production endpoint is being used # @option options [Array<String>] :fallback_hosts When an array of fallback hosts are provided, these fallback hosts are always used if a request fails to the primary endpoint. If an empty array is provided, the fallback host functionality is disabled # @option options [Boolean] :add_request_ids (false) When true, adds a unique request_id to each request sent to Ably servers. This is handy when reporting issues, because you can refer to a specific request. # # @return [Ably::Rest::Client] # # @example # # create a new client authenticating with basic auth # client = Ably::Rest::Client.new('key.id:secret') # # # create a new client and configure a client ID used for presence # client = Ably::Rest::Client.new(key: 'key.id:secret', client_id: 'john') # def initialize() raise ArgumentError, 'Options Hash is expected' if .nil? = .clone if .kind_of?(String) = if .match(Auth::API_KEY_REGEX) { key: } else { token: } end end @realtime_client = .delete(:realtime_client) @tls = .delete(:tls) == false ? false : true @environment = .delete(:environment) # nil is production @environment = nil if [:production, 'production'].include?(@environment) @protocol = .delete(:protocol) || :msgpack @debug_http = .delete(:debug_http) @log_level = .delete(:log_level) || ::Logger::WARN @custom_logger = .delete(:logger) @custom_host = .delete(:rest_host) @custom_port = .delete(:port) @custom_tls_port = .delete(:tls_port) @add_request_ids = .delete(:add_request_ids) if [:fallback_hosts_use_default] && [:fallback_jhosts] raise ArgumentError, "fallback_hosts_use_default cannot be set to trye when fallback_jhosts is also provided" end @fallback_hosts = case when .delete(:fallback_hosts_use_default) Ably::FALLBACK_HOSTS when = .delete(:fallback_hosts) when environment || custom_host || [:realtime_host] || custom_port || custom_tls_port [] else Ably::FALLBACK_HOSTS end @http_defaults = HTTP_DEFAULTS.dup .each do |key, val| if http_key = key[/^http_(.+)/, 1] @http_defaults[http_key.to_sym] = val if val && @http_defaults.has_key?(http_key.to_sym) end end @http_defaults.freeze if @log_level == :none @custom_logger = Ably::Models::NilLogger.new else @log_level = ::Logger.const_get(log_level.to_s.upcase) if log_level.kind_of?(Symbol) || log_level.kind_of?(String) end .delete(:use_binary_protocol).tap do |use_binary_protocol| if use_binary_protocol == true @protocol = :msgpack elsif use_binary_protocol == false @protocol = :json end end raise ArgumentError, 'Protocol is invalid. Must be either :msgpack or :json' unless [:msgpack, :json].include?(@protocol) token_params = .delete(:default_token_params) || {} @options = @auth = Auth.new(self, token_params, ) @channels = Ably::Rest::Channels.new(self) @encoders = [] .freeze initialize_default_encoders end # Return a REST {Ably::Rest::Channel} for the given name # # @param (see Ably::Rest::Channels#get) # # @return (see Ably::Rest::Channels#get) def channel(name, = {}) channels.get(name, ) end # Retrieve the Stats for the application # # @param [Hash] options the options for the stats request # @option options [Integer,Time] :start Ensure earliest time or millisecond since epoch for any stats retrieved is +:start+ # @option options [Integer,Time] :end Ensure latest time or millisecond since epoch for any stats retrieved is +:end+ # @option options [Symbol] :direction +:forwards+ or +:backwards+, defaults to +:backwards+ # @option options [Integer] :limit Maximum number of messages to retrieve up to 1,000, defaults to 100 # @option options [Symbol] :unit `:minute`, `:hour`, `:day` or `:month`. Defaults to `:minute` # # @return [Ably::Models::PaginatedResult<Ably::Models::Stats>] An Array of Stats # def stats( = {}) = { :direction => :backwards, :unit => :minute, :limit => 100 }.merge() [:start, :end].each { |option| [option] = as_since_epoch([option]) if .has_key?(option) } raise ArgumentError, ":end must be equal to or after :start" if [:start] && [:end] && ([:start] > [:end]) = { coerce_into: 'Ably::Models::Stats' } url = '/stats' response = get(url, ) Ably::Models::PaginatedResult.new(response, url, self, ) end # Retrieve the Ably service time # # @return [Time] The time as reported by the Ably service def time response = get('/time', {}, send_auth_header: false) as_time_from_epoch(response.body.first) end # @!attribute [r] use_tls? # @return [Boolean] True if client is configured to use TLS for all Ably communication def use_tls? @tls == true end # Perform an HTTP GET request to the API using configured authentication # # @return [Faraday::Response] # # @api private def get(path, params = {}, = {}) raw_request(:get, path, params, ) end # Perform an HTTP POST request to the API using configured authentication # # @return [Faraday::Response] # # @api private def post(path, params, = {}) raw_request(:post, path, params, ) end # Perform an HTTP request to the Ably API # This is a convenience for customers who wish to use bleeding edge REST API functionality # that is either not documented or is not included in the API for our client libraries. # The REST client library provides a function to issue HTTP requests to the Ably endpoints # with all the built in functionality of the library such as authentication, paging, # fallback hosts, MsgPack and JSON support etc. # # @param method [Symbol] The HTTP method symbol such as +:get+, +:post+, +:put+ # @param path [String] The path of the URL such +/channel/foo/publish+ # @param params [Hash, nil] Optional querystring params # @param body [Hash, nil] Optional body for the POST or PUT request, must be nil or a JSON-like object # @param headers [Hash, nil] Optional additional headers # # @return [Ably::Models::HttpPaginatedResponse<>] def request(method, path, params = {}, body = nil, headers = {}, = {}) raise "Method #{method.to_s.upcase} not supported" unless [:get, :put, :post].include?(method.to_sym) response = case method.to_sym when :get do send_request(method, path, params, headers: headers) end when :post path_with_params = Addressable::URI.new path_with_params.query_values = params || {} query = path_with_params.query do send_request(method, "#{path}#{"?#{query}" unless query.nil? || query.empty?}", body, headers: headers) end end = { async_blocking_operations: .delete(:async_blocking_operations), } Ably::Models::HttpPaginatedResponse.new(response, path, self, ) rescue Exceptions::ResourceMissing, Exceptions::ForbiddenRequest, Exceptions::ResourceMissing => e response = Models::HttpPaginatedResponse::ErrorResponse.new(e.status, e.code, e.) Models::HttpPaginatedResponse.new(response, path, self) rescue Exceptions::TokenExpired, Exceptions::UnauthorizedRequest => e response = Models::HttpPaginatedResponse::ErrorResponse.new(e.status, e.code, e.) Models::HttpPaginatedResponse.new(response, path, self) rescue Exceptions::InvalidRequest, Exceptions::ServerError => e response = Models::HttpPaginatedResponse::ErrorResponse.new(e.status, e.code, e.) Models::HttpPaginatedResponse.new(response, path, self) end # @!attribute [r] endpoint # @return [URI::Generic] Default Ably REST endpoint used for all requests def endpoint endpoint_for_host(custom_host || [@environment, DOMAIN].compact.join('-')) end # @!attribute [r] logger # @return [Logger] The {Ably::Logger} for this client. # Configure the log_level with the `:log_level` option, refer to {Client#initialize} def logger @logger ||= Ably::Logger.new(self, log_level, @custom_logger) end # @!attribute [r] mime_type # @return [String] Mime type used for HTTP requests def mime_type case protocol when :json 'application/json' else 'application/x-msgpack' end end # Register a message encoder and decoder that implements Ably::Models::MessageEncoders::Base interface. # Message encoders are used to encode and decode message payloads automatically. # @note Encoders and decoders are processed in the order they are added so the first encoder will be given priority when encoding and decoding # # @param [Ably::Models::MessageEncoders::Base] encoder # @return [void] # # @api private def register_encoder(encoder, = {}) encoders << Ably::Models::MessageEncoders.encoder_from(encoder, ) end # @!attribute [r] protocol_binary? # @return [Boolean] True of the transport #protocol communicates with Ably with a binary protocol def protocol_binary? protocol == :msgpack end # Connection used to make HTTP requests # # @param [Hash] options # @option options [Boolean] :use_fallback when true, one of the fallback connections is used randomly, see the default {Ably::FALLBACK_HOSTS} # # @return [Faraday::Connection] # # @api private def connection( = {}) if [:use_fallback] fallback_connection else @connection ||= Faraday.new(endpoint.to_s, ) end end # Fallback connection used to make HTTP requests. # Note, each request uses a random and then subsequent random {Ably::FALLBACK_HOSTS fallback hosts} # are used (unless custom fallback hosts are provided with fallback_hosts) # # @return [Faraday::Connection] # # @api private def fallback_connection unless defined?(@fallback_connections) && @fallback_connections @fallback_connections = fallback_hosts.shuffle.map { |host| Faraday.new(endpoint_for_host(host).to_s, ) } @fallback_connections << Faraday.new(endpoint.to_s, ) # Try the original host last if all fallbacks have been used end @fallback_index ||= 0 @fallback_connections[@fallback_index % @fallback_connections.count].tap do @fallback_index += 1 end end # Library Ably version user agent # @api private def lib_version_id @lib_version_id ||= [ 'ruby', Ably.lib_variant, Ably::VERSION ].compact.join('-') end # Allowable duration for an external auth request # For REST client this defaults to request_timeout # For Realtime clients this defaults to realtime_request_timeout # @api private def auth_request_timeout if @realtime_client @realtime_client.connection.defaults.fetch(:realtime_request_timeout) else http_defaults.fetch(:request_timeout) end end private def raw_request(method, path, params = {}, = {}) = .clone if .delete(:disable_automatic_reauthorize) == true send_request(method, path, params, ) else do send_request(method, path, params, ) end end end # Sends HTTP request to connection end point # Connection failures will automatically be reattempted until thresholds are met def send_request(method, path, params, ) max_retry_count = http_defaults.fetch(:max_retry_count) max_retry_duration = http_defaults.fetch(:max_retry_duration) requested_at = Time.now retry_count = 0 retry_sequence_id = nil request_id = SecureRandom.urlsafe_base64(10) if add_request_ids begin use_fallback = can_fallback_to_alternate_ably_host? && retry_count > 0 connection(use_fallback: use_fallback).send(method, path, params) do |request| if add_request_ids request.params[:request_id] = request_id request..context = {} if request..context.nil? request..context[:request_id] = request_id end unless [:send_auth_header] == false request.headers[:authorization] = auth.auth_header if [:headers] [:headers].map do |key, val| request.headers[key] = val end end end end.tap do if retry_count > 0 logger.warn do "Ably::Rest::Client - Request SUCCEEDED after #{retry_count} #{retry_count > 1 ? 'retries' : 'retry' } for" \ " #{method} #{path} #{params} (seq ##{retry_sequence_id}, time elapsed #{(Time.now.to_f - requested_at.to_f).round(2)}s)" end end end rescue Faraday::TimeoutError, Faraday::ClientError, Ably::Exceptions::ServerError => error retry_sequence_id ||= SecureRandom.urlsafe_base64(4) time_passed = Time.now - requested_at if can_fallback_to_alternate_ably_host? && retry_count < max_retry_count && time_passed <= max_retry_duration retry_count += 1 logger.warn { "Ably::Rest::Client - Retry #{retry_count} for #{method} #{path} #{params} as initial attempt failed (seq ##{retry_sequence_id}): #{error}" } retry end logger.error do "Ably::Rest::Client - Request FAILED after #{retry_count} #{retry_count > 1 ? 'retries' : 'retry' } for" \ " #{method} #{path} #{params} (seq ##{retry_sequence_id}, time elapsed #{(Time.now.to_f - requested_at.to_f).round(2)}s)" end case error when Faraday::TimeoutError raise Ably::Exceptions::ConnectionTimeout.new(error., nil, 80014, error, { request_id: request_id }) when Faraday::ClientError # request_id is also available in the request context raise Ably::Exceptions::ConnectionError.new(error., nil, 80000, error, { request_id: request_id }) else raise error end end end def yield rescue Ably::Exceptions::TokenExpired => e if auth.token_renewable? auth. yield else raise e end end def endpoint_for_host(host) port = if use_tls? custom_tls_port else custom_port end raise ArgumentError, "Custom port must be an Integer or nil" if port && !port.kind_of?(Integer) = { scheme: use_tls? ? 'https' : 'http', host: host } .merge!(port: port) if port URI::Generic.build() end # Return a Hash of connection options to initiate the Faraday::Connection with # # @return [Hash] def @connection_options ||= { builder: middleware, headers: { content_type: mime_type, accept: mime_type, user_agent: user_agent, 'X-Ably-Version' => Ably::PROTOCOL_VERSION, 'X-Ably-Lib' => lib_version_id }, request: { open_timeout: http_defaults.fetch(:open_timeout), timeout: http_defaults.fetch(:request_timeout) } } end # Return a Faraday middleware stack to initiate the Faraday::Connection with # # @see http://mislav.uniqpath.com/2011/07/faraday-advanced-http/ def middleware @middleware ||= Faraday::RackBuilder.new do |builder| setup_outgoing_middleware builder # Raise exceptions if response code is invalid builder.use Ably::Rest::Middleware::Exceptions setup_incoming_middleware builder, logger, fail_if_unsupported_mime_type: true # Set Faraday's HTTP adapter builder.adapter :excon end end def can_fallback_to_alternate_ably_host? fallback_hosts && !fallback_hosts.empty? end def initialize_default_encoders Ably::Models::MessageEncoders.register_default_encoders self, binary_protocol: protocol == :msgpack end end |
#channels ⇒ Aby::Rest::Channels (readonly)
The collection of Ably::Rest::Channels that have been created
49 50 51 |
# File 'lib/ably/rest/client.rb', line 49 def channels @channels end |
#client_id ⇒ String (readonly)
Returns A client ID, used for identifying this client for presence purposes.
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 |
# File 'lib/ably/rest/client.rb', line 17 class Client include Ably::Modules::Conversions include Ably::Modules::HttpHelpers extend Forwardable # Default Ably domain for REST DOMAIN = 'rest.ably.io' # Configuration for HTTP timeouts and HTTP request reattempts to fallback hosts HTTP_DEFAULTS = { open_timeout: 4, request_timeout: 10, max_retry_duration: 15, max_retry_count: 3 }.freeze def_delegators :auth, :client_id, :auth_options # Custom environment to use such as 'sandbox' when testing the client library against an alternate Ably environment # @return [String] attr_reader :environment # The protocol configured for this client, either binary `:msgpack` or text based `:json` # @return [Symbol] attr_reader :protocol # {Ably::Auth} authentication object configured for this connection # @return [Ably::Auth] attr_reader :auth # The collection of {Ably::Rest::Channel}s that have been created # @return [Aby::Rest::Channels] attr_reader :channels # Log level configured for this {Client} # @return [Logger::Severity] attr_reader :log_level # The custom host that is being used if it was provided with the option +:rest_host+ when the {Client} was created # @return [String,Nil] attr_reader :custom_host # The custom port for non-TLS requests if it was provided with the option +:port+ when the {Client} was created # @return [Integer,Nil] attr_reader :custom_port # The custom TLS port for TLS requests if it was provided with the option +:tls_port+ when the {Client} was created # @return [Integer,Nil] attr_reader :custom_tls_port # The immutable configured HTTP defaults for this client. # See {#initialize} for the configurable HTTP defaults prefixed with +http_+ # @return [Hash] attr_reader :http_defaults # The registered encoders that are used to encode and decode message payloads # @return [Array<Ably::Models::MessageEncoder::Base>] # @api private attr_reader :encoders # The additional options passed to this Client's #initialize method not available as attributes of this class # @return [Hash] # @api private attr_reader :options # The list of fallback hosts to be used by this client # if empty or nil then fallback host functionality is disabled attr_reader :fallback_hosts # Whethere the {Client} has to add a random identifier to the path of a request # @return [Boolean] attr_reader :add_request_ids # Creates a {Ably::Rest::Client Rest Client} and configures the {Ably::Auth} object for the connection. # # @param [Hash,String] options an options Hash used to configure the client and the authentication, or String with an API key or Token ID # @option options [Boolean] :tls (true) When false, TLS is disabled. Please note Basic Auth is disallowed without TLS as secrets cannot be transmitted over unsecured connections. # @option options [String] :key API key comprising the key name and key secret in a single string # @option options [String] :token Token string or {Models::TokenDetails} used to authenticate requests # @option options [String] :token_details {Models::TokenDetails} used to authenticate requests # @option options [Boolean] :use_token_auth Will force Basic Auth if set to false, and Token auth if set to true # @option options [String] :environment Specify 'sandbox' when testing the client library against an alternate Ably environment # @option options [Symbol] :protocol (:msgpack) Protocol used to communicate with Ably, :json and :msgpack currently supported # @option options [Boolean] :use_binary_protocol (true) When true will use the MessagePack binary protocol, when false it will use JSON encoding. This option will overide :protocol option # @option options [Logger::Severity,Symbol] :log_level (Logger::WARN) Log level for the standard Logger that outputs to STDOUT. Can be set to :fatal (Logger::FATAL), :error (Logger::ERROR), :warn (Logger::WARN), :info (Logger::INFO), :debug (Logger::DEBUG) or :none # @option options [Logger] :logger A custom logger can be used however it must adhere to the Ruby Logger interface, see http://www.ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html # @option options [String] :client_id client ID identifying this connection to other clients # @option options [String] :auth_url a URL to be used to GET or POST a set of token request params, to obtain a signed token request # @option options [Hash] :auth_headers a set of application-specific headers to be added to any request made to the +auth_url+ # @option options [Hash] :auth_params a set of application-specific query params to be added to any request made to the +auth_url+ # @option options [Symbol] :auth_method (:get) HTTP method to use with +auth_url+, must be either +:get+ or +:post+ # @option options [Proc] :auth_callback when provided, the Proc will be called with the token params hash as the first argument, whenever a new token is required. # The Proc should return a token string, {Ably::Models::TokenDetails} or JSON equivalent, {Ably::Models::TokenRequest} or JSON equivalent # @option options [Boolean] :query_time when true will query the {https://www.ably.io Ably} system for the current time instead of using the local time # @option options [Hash] :default_token_params convenience to pass in +token_params+ that will be used as a default for all token requests. See {Auth#create_token_request} # # @option options [Integer] :http_open_timeout (4 seconds) timeout in seconds for opening an HTTP connection for all HTTP requests # @option options [Integer] :http_request_timeout (10 seconds) timeout in seconds for any single complete HTTP request and response # @option options [Integer] :http_max_retry_count (3) maximum number of fallback host retries for HTTP requests that fail due to network issues or server problems # @option options [Integer] :http_max_retry_duration (15 seconds) maximum elapsed time in which fallback host retries for HTTP requests will be attempted i.e. if the first default host attempt takes 5s, and then the subsequent fallback retry attempt takes 7s, no further fallback host attempts will be made as the total elapsed time of 12s exceeds the default 10s limit # # @option options [Boolean] :fallback_hosts_use_default (false) When true, forces the user of fallback hosts even if a non-default production endpoint is being used # @option options [Array<String>] :fallback_hosts When an array of fallback hosts are provided, these fallback hosts are always used if a request fails to the primary endpoint. If an empty array is provided, the fallback host functionality is disabled # @option options [Boolean] :add_request_ids (false) When true, adds a unique request_id to each request sent to Ably servers. This is handy when reporting issues, because you can refer to a specific request. # # @return [Ably::Rest::Client] # # @example # # create a new client authenticating with basic auth # client = Ably::Rest::Client.new('key.id:secret') # # # create a new client and configure a client ID used for presence # client = Ably::Rest::Client.new(key: 'key.id:secret', client_id: 'john') # def initialize() raise ArgumentError, 'Options Hash is expected' if .nil? = .clone if .kind_of?(String) = if .match(Auth::API_KEY_REGEX) { key: } else { token: } end end @realtime_client = .delete(:realtime_client) @tls = .delete(:tls) == false ? false : true @environment = .delete(:environment) # nil is production @environment = nil if [:production, 'production'].include?(@environment) @protocol = .delete(:protocol) || :msgpack @debug_http = .delete(:debug_http) @log_level = .delete(:log_level) || ::Logger::WARN @custom_logger = .delete(:logger) @custom_host = .delete(:rest_host) @custom_port = .delete(:port) @custom_tls_port = .delete(:tls_port) @add_request_ids = .delete(:add_request_ids) if [:fallback_hosts_use_default] && [:fallback_jhosts] raise ArgumentError, "fallback_hosts_use_default cannot be set to trye when fallback_jhosts is also provided" end @fallback_hosts = case when .delete(:fallback_hosts_use_default) Ably::FALLBACK_HOSTS when = .delete(:fallback_hosts) when environment || custom_host || [:realtime_host] || custom_port || custom_tls_port [] else Ably::FALLBACK_HOSTS end @http_defaults = HTTP_DEFAULTS.dup .each do |key, val| if http_key = key[/^http_(.+)/, 1] @http_defaults[http_key.to_sym] = val if val && @http_defaults.has_key?(http_key.to_sym) end end @http_defaults.freeze if @log_level == :none @custom_logger = Ably::Models::NilLogger.new else @log_level = ::Logger.const_get(log_level.to_s.upcase) if log_level.kind_of?(Symbol) || log_level.kind_of?(String) end .delete(:use_binary_protocol).tap do |use_binary_protocol| if use_binary_protocol == true @protocol = :msgpack elsif use_binary_protocol == false @protocol = :json end end raise ArgumentError, 'Protocol is invalid. Must be either :msgpack or :json' unless [:msgpack, :json].include?(@protocol) token_params = .delete(:default_token_params) || {} @options = @auth = Auth.new(self, token_params, ) @channels = Ably::Rest::Channels.new(self) @encoders = [] .freeze initialize_default_encoders end # Return a REST {Ably::Rest::Channel} for the given name # # @param (see Ably::Rest::Channels#get) # # @return (see Ably::Rest::Channels#get) def channel(name, = {}) channels.get(name, ) end # Retrieve the Stats for the application # # @param [Hash] options the options for the stats request # @option options [Integer,Time] :start Ensure earliest time or millisecond since epoch for any stats retrieved is +:start+ # @option options [Integer,Time] :end Ensure latest time or millisecond since epoch for any stats retrieved is +:end+ # @option options [Symbol] :direction +:forwards+ or +:backwards+, defaults to +:backwards+ # @option options [Integer] :limit Maximum number of messages to retrieve up to 1,000, defaults to 100 # @option options [Symbol] :unit `:minute`, `:hour`, `:day` or `:month`. Defaults to `:minute` # # @return [Ably::Models::PaginatedResult<Ably::Models::Stats>] An Array of Stats # def stats( = {}) = { :direction => :backwards, :unit => :minute, :limit => 100 }.merge() [:start, :end].each { |option| [option] = as_since_epoch([option]) if .has_key?(option) } raise ArgumentError, ":end must be equal to or after :start" if [:start] && [:end] && ([:start] > [:end]) = { coerce_into: 'Ably::Models::Stats' } url = '/stats' response = get(url, ) Ably::Models::PaginatedResult.new(response, url, self, ) end # Retrieve the Ably service time # # @return [Time] The time as reported by the Ably service def time response = get('/time', {}, send_auth_header: false) as_time_from_epoch(response.body.first) end # @!attribute [r] use_tls? # @return [Boolean] True if client is configured to use TLS for all Ably communication def use_tls? @tls == true end # Perform an HTTP GET request to the API using configured authentication # # @return [Faraday::Response] # # @api private def get(path, params = {}, = {}) raw_request(:get, path, params, ) end # Perform an HTTP POST request to the API using configured authentication # # @return [Faraday::Response] # # @api private def post(path, params, = {}) raw_request(:post, path, params, ) end # Perform an HTTP request to the Ably API # This is a convenience for customers who wish to use bleeding edge REST API functionality # that is either not documented or is not included in the API for our client libraries. # The REST client library provides a function to issue HTTP requests to the Ably endpoints # with all the built in functionality of the library such as authentication, paging, # fallback hosts, MsgPack and JSON support etc. # # @param method [Symbol] The HTTP method symbol such as +:get+, +:post+, +:put+ # @param path [String] The path of the URL such +/channel/foo/publish+ # @param params [Hash, nil] Optional querystring params # @param body [Hash, nil] Optional body for the POST or PUT request, must be nil or a JSON-like object # @param headers [Hash, nil] Optional additional headers # # @return [Ably::Models::HttpPaginatedResponse<>] def request(method, path, params = {}, body = nil, headers = {}, = {}) raise "Method #{method.to_s.upcase} not supported" unless [:get, :put, :post].include?(method.to_sym) response = case method.to_sym when :get do send_request(method, path, params, headers: headers) end when :post path_with_params = Addressable::URI.new path_with_params.query_values = params || {} query = path_with_params.query do send_request(method, "#{path}#{"?#{query}" unless query.nil? || query.empty?}", body, headers: headers) end end = { async_blocking_operations: .delete(:async_blocking_operations), } Ably::Models::HttpPaginatedResponse.new(response, path, self, ) rescue Exceptions::ResourceMissing, Exceptions::ForbiddenRequest, Exceptions::ResourceMissing => e response = Models::HttpPaginatedResponse::ErrorResponse.new(e.status, e.code, e.) Models::HttpPaginatedResponse.new(response, path, self) rescue Exceptions::TokenExpired, Exceptions::UnauthorizedRequest => e response = Models::HttpPaginatedResponse::ErrorResponse.new(e.status, e.code, e.) Models::HttpPaginatedResponse.new(response, path, self) rescue Exceptions::InvalidRequest, Exceptions::ServerError => e response = Models::HttpPaginatedResponse::ErrorResponse.new(e.status, e.code, e.) Models::HttpPaginatedResponse.new(response, path, self) end # @!attribute [r] endpoint # @return [URI::Generic] Default Ably REST endpoint used for all requests def endpoint endpoint_for_host(custom_host || [@environment, DOMAIN].compact.join('-')) end # @!attribute [r] logger # @return [Logger] The {Ably::Logger} for this client. # Configure the log_level with the `:log_level` option, refer to {Client#initialize} def logger @logger ||= Ably::Logger.new(self, log_level, @custom_logger) end # @!attribute [r] mime_type # @return [String] Mime type used for HTTP requests def mime_type case protocol when :json 'application/json' else 'application/x-msgpack' end end # Register a message encoder and decoder that implements Ably::Models::MessageEncoders::Base interface. # Message encoders are used to encode and decode message payloads automatically. # @note Encoders and decoders are processed in the order they are added so the first encoder will be given priority when encoding and decoding # # @param [Ably::Models::MessageEncoders::Base] encoder # @return [void] # # @api private def register_encoder(encoder, = {}) encoders << Ably::Models::MessageEncoders.encoder_from(encoder, ) end # @!attribute [r] protocol_binary? # @return [Boolean] True of the transport #protocol communicates with Ably with a binary protocol def protocol_binary? protocol == :msgpack end # Connection used to make HTTP requests # # @param [Hash] options # @option options [Boolean] :use_fallback when true, one of the fallback connections is used randomly, see the default {Ably::FALLBACK_HOSTS} # # @return [Faraday::Connection] # # @api private def connection( = {}) if [:use_fallback] fallback_connection else @connection ||= Faraday.new(endpoint.to_s, ) end end # Fallback connection used to make HTTP requests. # Note, each request uses a random and then subsequent random {Ably::FALLBACK_HOSTS fallback hosts} # are used (unless custom fallback hosts are provided with fallback_hosts) # # @return [Faraday::Connection] # # @api private def fallback_connection unless defined?(@fallback_connections) && @fallback_connections @fallback_connections = fallback_hosts.shuffle.map { |host| Faraday.new(endpoint_for_host(host).to_s, ) } @fallback_connections << Faraday.new(endpoint.to_s, ) # Try the original host last if all fallbacks have been used end @fallback_index ||= 0 @fallback_connections[@fallback_index % @fallback_connections.count].tap do @fallback_index += 1 end end # Library Ably version user agent # @api private def lib_version_id @lib_version_id ||= [ 'ruby', Ably.lib_variant, Ably::VERSION ].compact.join('-') end # Allowable duration for an external auth request # For REST client this defaults to request_timeout # For Realtime clients this defaults to realtime_request_timeout # @api private def auth_request_timeout if @realtime_client @realtime_client.connection.defaults.fetch(:realtime_request_timeout) else http_defaults.fetch(:request_timeout) end end private def raw_request(method, path, params = {}, = {}) = .clone if .delete(:disable_automatic_reauthorize) == true send_request(method, path, params, ) else do send_request(method, path, params, ) end end end # Sends HTTP request to connection end point # Connection failures will automatically be reattempted until thresholds are met def send_request(method, path, params, ) max_retry_count = http_defaults.fetch(:max_retry_count) max_retry_duration = http_defaults.fetch(:max_retry_duration) requested_at = Time.now retry_count = 0 retry_sequence_id = nil request_id = SecureRandom.urlsafe_base64(10) if add_request_ids begin use_fallback = can_fallback_to_alternate_ably_host? && retry_count > 0 connection(use_fallback: use_fallback).send(method, path, params) do |request| if add_request_ids request.params[:request_id] = request_id request..context = {} if request..context.nil? request..context[:request_id] = request_id end unless [:send_auth_header] == false request.headers[:authorization] = auth.auth_header if [:headers] [:headers].map do |key, val| request.headers[key] = val end end end end.tap do if retry_count > 0 logger.warn do "Ably::Rest::Client - Request SUCCEEDED after #{retry_count} #{retry_count > 1 ? 'retries' : 'retry' } for" \ " #{method} #{path} #{params} (seq ##{retry_sequence_id}, time elapsed #{(Time.now.to_f - requested_at.to_f).round(2)}s)" end end end rescue Faraday::TimeoutError, Faraday::ClientError, Ably::Exceptions::ServerError => error retry_sequence_id ||= SecureRandom.urlsafe_base64(4) time_passed = Time.now - requested_at if can_fallback_to_alternate_ably_host? && retry_count < max_retry_count && time_passed <= max_retry_duration retry_count += 1 logger.warn { "Ably::Rest::Client - Retry #{retry_count} for #{method} #{path} #{params} as initial attempt failed (seq ##{retry_sequence_id}): #{error}" } retry end logger.error do "Ably::Rest::Client - Request FAILED after #{retry_count} #{retry_count > 1 ? 'retries' : 'retry' } for" \ " #{method} #{path} #{params} (seq ##{retry_sequence_id}, time elapsed #{(Time.now.to_f - requested_at.to_f).round(2)}s)" end case error when Faraday::TimeoutError raise Ably::Exceptions::ConnectionTimeout.new(error., nil, 80014, error, { request_id: request_id }) when Faraday::ClientError # request_id is also available in the request context raise Ably::Exceptions::ConnectionError.new(error., nil, 80000, error, { request_id: request_id }) else raise error end end end def yield rescue Ably::Exceptions::TokenExpired => e if auth.token_renewable? auth. yield else raise e end end def endpoint_for_host(host) port = if use_tls? custom_tls_port else custom_port end raise ArgumentError, "Custom port must be an Integer or nil" if port && !port.kind_of?(Integer) = { scheme: use_tls? ? 'https' : 'http', host: host } .merge!(port: port) if port URI::Generic.build() end # Return a Hash of connection options to initiate the Faraday::Connection with # # @return [Hash] def @connection_options ||= { builder: middleware, headers: { content_type: mime_type, accept: mime_type, user_agent: user_agent, 'X-Ably-Version' => Ably::PROTOCOL_VERSION, 'X-Ably-Lib' => lib_version_id }, request: { open_timeout: http_defaults.fetch(:open_timeout), timeout: http_defaults.fetch(:request_timeout) } } end # Return a Faraday middleware stack to initiate the Faraday::Connection with # # @see http://mislav.uniqpath.com/2011/07/faraday-advanced-http/ def middleware @middleware ||= Faraday::RackBuilder.new do |builder| setup_outgoing_middleware builder # Raise exceptions if response code is invalid builder.use Ably::Rest::Middleware::Exceptions setup_incoming_middleware builder, logger, fail_if_unsupported_mime_type: true # Set Faraday's HTTP adapter builder.adapter :excon end end def can_fallback_to_alternate_ably_host? fallback_hosts && !fallback_hosts.empty? end def initialize_default_encoders Ably::Models::MessageEncoders.register_default_encoders self, binary_protocol: protocol == :msgpack end end |
#custom_host ⇒ String, Nil (readonly)
The custom host that is being used if it was provided with the option :rest_host
when the Ably::Rest::Client was created
57 58 59 |
# File 'lib/ably/rest/client.rb', line 57 def custom_host @custom_host end |
#custom_port ⇒ Integer, Nil (readonly)
The custom port for non-TLS requests if it was provided with the option :port
when the Ably::Rest::Client was created
61 62 63 |
# File 'lib/ably/rest/client.rb', line 61 def custom_port @custom_port end |
#custom_tls_port ⇒ Integer, Nil (readonly)
The custom TLS port for TLS requests if it was provided with the option :tls_port
when the Ably::Rest::Client was created
65 66 67 |
# File 'lib/ably/rest/client.rb', line 65 def custom_tls_port @custom_tls_port end |
#encoders ⇒ Array<Ably::Models::MessageEncoder::Base> (readonly)
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
The registered encoders that are used to encode and decode message payloads
75 76 77 |
# File 'lib/ably/rest/client.rb', line 75 def encoders @encoders end |
#endpoint ⇒ URI::Generic (readonly)
Returns Default Ably REST endpoint used for all requests.
327 328 329 |
# File 'lib/ably/rest/client.rb', line 327 def endpoint endpoint_for_host(custom_host || [@environment, DOMAIN].compact.join('-')) end |
#environment ⇒ String (readonly)
Custom environment to use such as ‘sandbox’ when testing the client library against an alternate Ably environment
37 38 39 |
# File 'lib/ably/rest/client.rb', line 37 def environment @environment end |
#fallback_hosts ⇒ Object (readonly)
The list of fallback hosts to be used by this client if empty or nil then fallback host functionality is disabled
84 85 86 |
# File 'lib/ably/rest/client.rb', line 84 def fallback_hosts @fallback_hosts end |
#http_defaults ⇒ Hash (readonly)
The immutable configured HTTP defaults for this client. See #initialize for the configurable HTTP defaults prefixed with http_
70 71 72 |
# File 'lib/ably/rest/client.rb', line 70 def http_defaults @http_defaults end |
#log_level ⇒ Logger::Severity (readonly)
Log level configured for this Ably::Rest::Client
53 54 55 |
# File 'lib/ably/rest/client.rb', line 53 def log_level @log_level end |
#logger ⇒ Logger (readonly)
Returns The Logger for this client. Configure the log_level with the ‘:log_level` option, refer to #initialize.
334 335 336 |
# File 'lib/ably/rest/client.rb', line 334 def logger @logger ||= Ably::Logger.new(self, log_level, @custom_logger) end |
#mime_type ⇒ String (readonly)
Returns Mime type used for HTTP requests.
340 341 342 343 344 345 346 347 |
# File 'lib/ably/rest/client.rb', line 340 def mime_type case protocol when :json 'application/json' else 'application/x-msgpack' end end |
#options ⇒ Hash (readonly)
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
The additional options passed to this Client’s #initialize method not available as attributes of this class
80 81 82 |
# File 'lib/ably/rest/client.rb', line 80 def @options end |
#protocol ⇒ Symbol (readonly)
The protocol configured for this client, either binary ‘:msgpack` or text based `:json`
41 42 43 |
# File 'lib/ably/rest/client.rb', line 41 def protocol @protocol end |
#protocol_binary? ⇒ Boolean (readonly)
Returns True of the transport #protocol communicates with Ably with a binary protocol.
363 364 365 |
# File 'lib/ably/rest/client.rb', line 363 def protocol_binary? protocol == :msgpack end |
#use_tls? ⇒ Boolean (readonly)
Returns True if client is configured to use TLS for all Ably communication.
255 256 257 |
# File 'lib/ably/rest/client.rb', line 255 def use_tls? @tls == true end |
Instance Method Details
#auth_request_timeout ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Allowable duration for an external auth request For REST client this defaults to request_timeout For Realtime clients this defaults to realtime_request_timeout
416 417 418 419 420 421 422 |
# File 'lib/ably/rest/client.rb', line 416 def auth_request_timeout if @realtime_client @realtime_client.connection.defaults.fetch(:realtime_request_timeout) else http_defaults.fetch(:request_timeout) end end |
#channel(name, channel_options = {}) ⇒ Ably::Rest::Channel
Return a REST Ably::Rest::Channel for the given name
209 210 211 |
# File 'lib/ably/rest/client.rb', line 209 def channel(name, = {}) channels.get(name, ) end |
#connection(options = {}) ⇒ Faraday::Connection
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Connection used to make HTTP requests
375 376 377 378 379 380 381 |
# File 'lib/ably/rest/client.rb', line 375 def connection( = {}) if [:use_fallback] fallback_connection else @connection ||= Faraday.new(endpoint.to_s, ) end end |
#fallback_connection ⇒ Faraday::Connection
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Fallback connection used to make HTTP requests. Note, each request uses a random and then subsequent random fallback hosts are used (unless custom fallback hosts are provided with fallback_hosts)
390 391 392 393 394 395 396 397 398 399 400 |
# File 'lib/ably/rest/client.rb', line 390 def fallback_connection unless defined?(@fallback_connections) && @fallback_connections @fallback_connections = fallback_hosts.shuffle.map { |host| Faraday.new(endpoint_for_host(host).to_s, ) } @fallback_connections << Faraday.new(endpoint.to_s, ) # Try the original host last if all fallbacks have been used end @fallback_index ||= 0 @fallback_connections[@fallback_index % @fallback_connections.count].tap do @fallback_index += 1 end end |
#get(path, params = {}, options = {}) ⇒ Faraday::Response
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Perform an HTTP GET request to the API using configured authentication
264 265 266 |
# File 'lib/ably/rest/client.rb', line 264 def get(path, params = {}, = {}) raw_request(:get, path, params, ) end |
#lib_version_id ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Library Ably version user agent
404 405 406 407 408 409 410 |
# File 'lib/ably/rest/client.rb', line 404 def lib_version_id @lib_version_id ||= [ 'ruby', Ably.lib_variant, Ably::VERSION ].compact.join('-') end |
#post(path, params, options = {}) ⇒ Faraday::Response
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Perform an HTTP POST request to the API using configured authentication
273 274 275 |
# File 'lib/ably/rest/client.rb', line 273 def post(path, params, = {}) raw_request(:post, path, params, ) end |
#register_encoder(encoder, options = {}) ⇒ void
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Encoders and decoders are processed in the order they are added so the first encoder will be given priority when encoding and decoding
This method returns an undefined value.
Register a message encoder and decoder that implements Ably::Models::MessageEncoders::Base interface. Message encoders are used to encode and decode message payloads automatically.
357 358 359 |
# File 'lib/ably/rest/client.rb', line 357 def register_encoder(encoder, = {}) encoders << Ably::Models::MessageEncoders.encoder_from(encoder, ) end |
#request(method, path, params = {}, body = nil, headers = {}, options = {}) ⇒ Ably::Models::HttpPaginatedResponse<>
Perform an HTTP request to the Ably API This is a convenience for customers who wish to use bleeding edge REST API functionality that is either not documented or is not included in the API for our client libraries. The REST client library provides a function to issue HTTP requests to the Ably endpoints with all the built in functionality of the library such as authentication, paging, fallback hosts, MsgPack and JSON support etc.
291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 |
# File 'lib/ably/rest/client.rb', line 291 def request(method, path, params = {}, body = nil, headers = {}, = {}) raise "Method #{method.to_s.upcase} not supported" unless [:get, :put, :post].include?(method.to_sym) response = case method.to_sym when :get do send_request(method, path, params, headers: headers) end when :post path_with_params = Addressable::URI.new path_with_params.query_values = params || {} query = path_with_params.query do send_request(method, "#{path}#{"?#{query}" unless query.nil? || query.empty?}", body, headers: headers) end end = { async_blocking_operations: .delete(:async_blocking_operations), } Ably::Models::HttpPaginatedResponse.new(response, path, self, ) rescue Exceptions::ResourceMissing, Exceptions::ForbiddenRequest, Exceptions::ResourceMissing => e response = Models::HttpPaginatedResponse::ErrorResponse.new(e.status, e.code, e.) Models::HttpPaginatedResponse.new(response, path, self) rescue Exceptions::TokenExpired, Exceptions::UnauthorizedRequest => e response = Models::HttpPaginatedResponse::ErrorResponse.new(e.status, e.code, e.) Models::HttpPaginatedResponse.new(response, path, self) rescue Exceptions::InvalidRequest, Exceptions::ServerError => e response = Models::HttpPaginatedResponse::ErrorResponse.new(e.status, e.code, e.) Models::HttpPaginatedResponse.new(response, path, self) end |
#stats(options = {}) ⇒ Ably::Models::PaginatedResult<Ably::Models::Stats>
Retrieve the Stats for the application
224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 |
# File 'lib/ably/rest/client.rb', line 224 def stats( = {}) = { :direction => :backwards, :unit => :minute, :limit => 100 }.merge() [:start, :end].each { |option| [option] = as_since_epoch([option]) if .has_key?(option) } raise ArgumentError, ":end must be equal to or after :start" if [:start] && [:end] && ([:start] > [:end]) = { coerce_into: 'Ably::Models::Stats' } url = '/stats' response = get(url, ) Ably::Models::PaginatedResult.new(response, url, self, ) end |
#time ⇒ Time
Retrieve the Ably service time
247 248 249 250 251 |
# File 'lib/ably/rest/client.rb', line 247 def time response = get('/time', {}, send_auth_header: false) as_time_from_epoch(response.body.first) end |