Class: Ably::Realtime::Client
- Inherits:
-
Object
- Object
- Ably::Realtime::Client
- Extended by:
- Forwardable
- Defined in:
- lib/ably/realtime/client.rb,
lib/ably/realtime/client/incoming_message_dispatcher.rb,
lib/ably/realtime/client/outgoing_message_dispatcher.rb
Overview
A client that extends the functionality of the Client and provides additional realtime-specific features.
Defined Under Namespace
Classes: IncomingMessageDispatcher, OutgoingMessageDispatcher
Constant Summary collapse
- DOMAIN =
'realtime.ably.io'
Instance Attribute Summary collapse
-
#auth ⇒ Ably::Auth
readonly
An Auth object.
-
#auto_connect ⇒ Boolean
readonly
When true, as soon as the client library is instantiated it will connect to Ably.
-
#channels ⇒ Aby::Realtime::Channels
readonly
A Aby::Realtime::Channels object.
-
#connection ⇒ Aby::Realtime::Connection
readonly
A Aby::Realtime::Connection object.
-
#custom_realtime_host ⇒ String, Nil
readonly
The custom realtime websocket host that is being used if it was provided with the option ‘:ws_host` when the Client was created.
-
#echo_messages ⇒ Boolean
readonly
When false the client suppresses messages originating from this connection being echoed back on the same connection.
-
#endpoint ⇒ URI::Generic
readonly
Default Ably Realtime endpoint used for all requests.
-
#fallback_endpoint ⇒ URI::Generic
readonly
private
Fallback endpoint used to connect to the realtime Ably service.
-
#queue_messages ⇒ Boolean
readonly
If false, this disables the default behaviour whereby the library queues messages on a connection in the disconnected or connecting states.
-
#recover ⇒ String, Nil
readonly
When a recover option is specified a connection inherits the state of a previous connection that may have existed under a different instance of the Realtime library, please refer to the API documentation for further information on connection state recovery.
- #rest_client ⇒ Object readonly
-
#transport_params ⇒ Hash
readonly
Additional parameters to be sent in the querystring when initiating a realtime connection.
Instance Method Summary collapse
-
#channel(name, channel_options = {}) ⇒ Ably::Realtime::Channel
Return a Realtime Channel for the given name.
-
#close(&block) ⇒ Object
Calls Ably::Realtime::Connection#close and causes the connection to close, entering the closing state.
-
#connect(&block) ⇒ Object
Calls Ably::Realtime::Connection#connect and causes the connection to open, entering the connecting state.
-
#device ⇒ Ably::Models::LocalDevice
Retrieves a Models::LocalDevice object that represents the current state of the device as a target for push notifications.
-
#disable_automatic_connection_recovery ⇒ void
private
Disable connection recovery, typically used after a connection has been recovered.
-
#fallback_hosts ⇒ Object
The list of fallback hosts to be used by this client if empty or nil then fallback host functionality is disabled.
-
#initialize(options) ⇒ Ably::Realtime::Client
constructor
Creates a Realtime Client and configures the Auth object for the connection.
-
#logger ⇒ Logger
The Logger for this client.
-
#publish(channel_name, name, data = nil, attributes = {}) {|Ably::Models::Message, Array<Ably::Models::Message>| ... } ⇒ Ably::Util::SafeDeferrable
Publish one or more messages to the specified channel.
-
#push ⇒ Ably::Realtime::Push
A Push object.
-
#register_encoder(encoder) ⇒ void
private
Register a message encoder and decoder that implements Ably::Models::MessageEncoders::Base interface.
-
#request(method, path, params = {}, body = nil, headers = {}) {|Ably::Models::HttpPaginatedResponse<>| ... } ⇒ Ably::Util::SafeDeferrable
Makes a REST request to a provided path.
-
#stats(options = {}) {|Ably::Models::PaginatedResult<Ably::Models::Stats>| ... } ⇒ Ably::Util::SafeDeferrable
Queries the REST /stats API and retrieves your application’s usage statistics.
-
#time {|Time| ... } ⇒ Ably::Util::SafeDeferrable
Retrieves the time from the Ably service as milliseconds since the Unix epoch.
Constructor Details
#initialize(options) ⇒ Ably::Realtime::Client
Creates a Realtime Client and configures the Auth object for the connection.
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 |
# File 'lib/ably/realtime/client.rb', line 107 def initialize() raise ArgumentError, 'Options Hash is expected' if .nil? = .clone if .kind_of?(String) = if .match(Ably::Auth::API_KEY_REGEX) { key: } else { token: } end end @transport_params = .delete(:transport_params).to_h.each_with_object({}) do |(key, value), acc| acc[key.to_s] = value.to_s end @rest_client = Ably::Rest::Client.new(.merge(realtime_client: self)) @echo_messages = rest_client..fetch(:echo_messages, true) == false ? false : true @queue_messages = rest_client..fetch(:queue_messages, true) == false ? false : true @custom_realtime_host = rest_client.[:realtime_host] || rest_client.[:ws_host] @auto_connect = rest_client..fetch(:auto_connect, true) == false ? false : true @recover = rest_client.[:recover] raise ArgumentError, "Recovery key '#{recover}' is invalid" if recover && !recover.match(Connection::RECOVER_REGEX) @auth = Ably::Realtime::Auth.new(self) @channels = Ably::Realtime::Channels.new(self) @connection = Ably::Realtime::Connection.new(self, ) end |
Instance Attribute Details
#auth ⇒ Ably::Auth (readonly)
An Auth object.
31 32 33 |
# File 'lib/ably/realtime/client.rb', line 31 def auth @auth end |
#auto_connect ⇒ Boolean (readonly)
When true, as soon as the client library is instantiated it will connect to Ably. If this attribute is false, a connection must be opened explicitly
61 62 63 |
# File 'lib/ably/realtime/client.rb', line 61 def auto_connect @auto_connect end |
#channels ⇒ Aby::Realtime::Channels (readonly)
A Aby::Realtime::Channels object.
23 24 25 |
# File 'lib/ably/realtime/client.rb', line 23 def channels @channels end |
#connection ⇒ Aby::Realtime::Connection (readonly)
A Aby::Realtime::Connection object.
39 40 41 |
# File 'lib/ably/realtime/client.rb', line 39 def connection @connection end |
#custom_realtime_host ⇒ String, Nil (readonly)
The custom realtime websocket host that is being used if it was provided with the option ‘:ws_host` when the Ably::Realtime::Client was created
57 58 59 |
# File 'lib/ably/realtime/client.rb', line 57 def custom_realtime_host @custom_realtime_host end |
#echo_messages ⇒ Boolean (readonly)
When false the client suppresses messages originating from this connection being echoed back on the same connection. Defaults to true
49 50 51 |
# File 'lib/ably/realtime/client.rb', line 49 def @echo_messages end |
#endpoint ⇒ URI::Generic (readonly)
Returns Default Ably Realtime endpoint used for all requests.
286 287 288 |
# File 'lib/ably/realtime/client.rb', line 286 def endpoint endpoint_for_host(custom_realtime_host || [environment, DOMAIN].compact.join('-')) end |
#fallback_endpoint ⇒ URI::Generic (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.
Returns Fallback endpoint used to connect to the realtime Ably service. Note, after each connection attempt, a new random fallback host or provided fallback hosts are used.
315 316 317 318 319 320 321 322 323 324 |
# File 'lib/ably/realtime/client.rb', line 315 def fallback_endpoint unless defined?(@fallback_endpoints) && @fallback_endpoints @fallback_endpoints = fallback_hosts.shuffle.map { |fallback_host| endpoint_for_host(fallback_host) } @fallback_endpoints << endpoint # Try the original host last if all fallbacks have been used end fallback_endpoint_index = connection.manager.retry_count_for_state(:disconnected) + connection.manager.retry_count_for_state(:suspended) - 1 @fallback_endpoints[fallback_endpoint_index % @fallback_endpoints.count] end |
#queue_messages ⇒ Boolean (readonly)
If false, this disables the default behaviour whereby the library queues messages on a connection in the disconnected or connecting states. Defaults to true
53 54 55 |
# File 'lib/ably/realtime/client.rb', line 53 def @queue_messages end |
#recover ⇒ String, Nil (readonly)
When a recover option is specified a connection inherits the state of a previous connection that may have existed under a different instance of the Realtime library, please refer to the API documentation for further information on connection state recovery
65 66 67 |
# File 'lib/ably/realtime/client.rb', line 65 def recover @recover end |
#rest_client ⇒ Object (readonly)
45 46 47 |
# File 'lib/ably/realtime/client.rb', line 45 def rest_client @rest_client end |
#transport_params ⇒ Hash (readonly)
Additional parameters to be sent in the querystring when initiating a realtime connection
69 70 71 |
# File 'lib/ably/realtime/client.rb', line 69 def transport_params @transport_params end |
Instance Method Details
#channel(name, channel_options = {}) ⇒ Ably::Realtime::Channel
Return a Realtime Channel for the given name
141 142 143 |
# File 'lib/ably/realtime/client.rb', line 141 def channel(name, = {}) channels.get(name, ) end |
#close(&block) ⇒ Object
Calls Ably::Realtime::Connection#close and causes the connection to close, entering the closing state. Once closed, the library will not attempt to re-establish the connection without an explicit call to Ably::Realtime::Connection#connect. (see Ably::Realtime::Connection#close)
182 183 184 |
# File 'lib/ably/realtime/client.rb', line 182 def close(&block) connection.close(&block) end |
#connect(&block) ⇒ Object
Calls Ably::Realtime::Connection#connect and causes the connection to open, entering the connecting state. Explicitly calling connect() is unnecessary unless the autoConnect property is disabled. (see Ably::Realtime::Connection#connect)
190 191 192 |
# File 'lib/ably/realtime/client.rb', line 190 def connect(&block) connection.connect(&block) end |
#device ⇒ Ably::Models::LocalDevice
This is unsupported in the Ruby library
Retrieves a Models::LocalDevice object that represents the current state of the device as a target for push notifications.
331 332 333 |
# File 'lib/ably/realtime/client.rb', line 331 def device raise Ably::Exceptions::PushNotificationsNotSupported, 'This device does not support receiving or subscribing to push notifications. The local device object is not unavailable' end |
#disable_automatic_connection_recovery ⇒ 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.
This method returns an undefined value.
Disable connection recovery, typically used after a connection has been recovered
308 309 310 |
# File 'lib/ably/realtime/client.rb', line 308 def disable_automatic_connection_recovery @recover = nil end |
#fallback_hosts ⇒ Object
The list of fallback hosts to be used by this client if empty or nil then fallback host functionality is disabled
296 297 298 |
# File 'lib/ably/realtime/client.rb', line 296 def fallback_hosts rest_client.fallback_hosts end |
#logger ⇒ Logger
Returns The Logger for this client. Configure the log_level with the ‘:log_level` option, refer to #initialize.
301 302 303 |
# File 'lib/ably/realtime/client.rb', line 301 def logger @logger ||= Ably::Logger.new(self, log_level, rest_client.logger.custom_logger) end |
#publish(channel_name, name, data = nil, attributes = {}) {|Ably::Models::Message, Array<Ably::Models::Message>| ... } ⇒ Ably::Util::SafeDeferrable
Publish one or more messages to the specified channel.
This method allows messages to be efficiently published to Ably without instancing a Ably::Realtime::Channel object. If you want to publish a high rate of messages to Ably without instancing channels or using the REST API, then this method is recommended. However, channel options such as encryption are not supported with this method. If you need to specify channel options we recommend you use the Ably::Realtime::Channel publish
method without attaching to each channel, unless you also want to subscribe to published messages on that channel.
Note: This feature is still in beta. As such, we cannot guarantee the API will not change in future.
260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 |
# File 'lib/ably/realtime/client.rb', line 260 def publish(channel_name, name, data = nil, attributes = {}, &success_block) if !connection. error = Ably::Exceptions::MessageQueueingDisabled.new("Message cannot be published. Client is not allowed to queue messages when connection is in state #{connection.state}") return Ably::Util::SafeDeferrable.new_and_fail_immediately(logger, error) end = if name.kind_of?(Enumerable) name else name = ensure_utf_8(:name, name, allow_nil: true) ensure_supported_payload data [{ name: name, data: data }.merge(attributes)] end if .length > Realtime::Connection::MAX_PROTOCOL_MESSAGE_BATCH_SIZE error = Ably::Exceptions::InvalidRequest.new("It is not possible to publish more than #{Realtime::Connection::MAX_PROTOCOL_MESSAGE_BATCH_SIZE} messages with a single publish request.") return Ably::Util::SafeDeferrable.new_and_fail_immediately(logger, error) end (self, , channel_name).tap do |deferrable| deferrable.callback(&success_block) if block_given? end end |
#push ⇒ Ably::Realtime::Push
A Push object.
196 197 198 |
# File 'lib/ably/realtime/client.rb', line 196 def push @push ||= Push.new(self) end |
#register_encoder(encoder) ⇒ 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.
291 292 293 |
# File 'lib/ably/realtime/client.rb', line 291 def register_encoder(encoder) rest_client.register_encoder encoder end |
#request(method, path, params = {}, body = nil, headers = {}) {|Ably::Models::HttpPaginatedResponse<>| ... } ⇒ Ably::Util::SafeDeferrable
Makes a REST request to a provided path. This is provided as a convenience for developers who wish to use REST API functionality that is either not documented or is not yet included in the public API, without having to directly handle features such as authentication, paging, fallback hosts, MsgPack and JSON support.
210 211 212 213 214 |
# File 'lib/ably/realtime/client.rb', line 210 def request(method, path, params = {}, body = nil, headers = {}, &callback) async_wrap(callback) do rest_client.request(method, path, params, body, headers, async_blocking_operations: true) end end |
#stats(options = {}) {|Ably::Models::PaginatedResult<Ably::Models::Stats>| ... } ⇒ Ably::Util::SafeDeferrable
Queries the REST /stats API and retrieves your application’s usage statistics. Returns a Util::SafeDeferrable object, containing an array of Models::Stats objects. See the Stats docs.
172 173 174 175 176 |
# File 'lib/ably/realtime/client.rb', line 172 def stats( = {}, &success_callback) async_wrap(success_callback) do rest_client.stats() end end |
#time {|Time| ... } ⇒ Ably::Util::SafeDeferrable
Retrieves the time from the Ably service as milliseconds since the Unix epoch. Clients that do not have access to a sufficiently well maintained time source and wish to issue Ably Models::TokenRequests with a more accurate timestamp should use the queryTime property instead of this method.
154 155 156 157 158 |
# File 'lib/ably/realtime/client.rb', line 154 def time(&success_callback) async_wrap(success_callback) do rest_client.time end end |