Module: Ably::Realtime

Defined in:
lib/ably/realtime.rb,
lib/ably/realtime/auth.rb,
lib/ably/realtime/client.rb,
lib/ably/realtime/channel.rb,
lib/ably/realtime/channels.rb,
lib/ably/realtime/presence.rb,
lib/ably/realtime/connection.rb,
lib/ably/realtime/presence/members_map.rb,
lib/ably/realtime/channel/channel_manager.rb,
lib/ably/realtime/presence/presence_manager.rb,
lib/ably/realtime/channel/channel_state_machine.rb,
lib/ably/realtime/connection/connection_manager.rb,
lib/ably/realtime/connection/websocket_transport.rb,
lib/ably/realtime/presence/presence_state_machine.rb,
lib/ably/realtime/client/incoming_message_dispatcher.rb,
lib/ably/realtime/client/outgoing_message_dispatcher.rb,
lib/ably/realtime/connection/connection_state_machine.rb

Overview

Realtime provides the top-level class to be instanced for the Ably Realtime library

Examples:

client = Ably::Realtime.new("xxxxx")
channel = client.channel("test")
channel.subscribe do |message|
  message[:name] #=> "greeting"
end
channel.publish "greeting", "data"

Defined Under Namespace

Modules: Models Classes: Auth, Channel, Channels, Client, Connection, Presence

Class Method Summary collapse

Class Method Details

.new(options) ⇒ Ably::Realtime::Client

Convenience method providing an alias to Client constructor.

Examples:

# create a new client authenticating with basic auth
client = Ably::Realtime.new('key.id:secret')

# create a new client authenticating with basic auth and a client_id
client = Ably::Realtime.new(key: 'key.id:secret', client_id: 'john')

Parameters:

  • options (Hash, String) —

    an options Hash used to configure the client and the authentication, or String with an API key or Token ID

Options Hash (options):

  • :queue_messages (Boolean) —

    If false, this disables the default behaviour whereby the library queues messages on a connection in the disconnected or connecting states

  • :echo_messages (Boolean) —

    If false, prevents messages originating from this connection being echoed back on the same connection

  • :recover (String) —

    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

  • :auto_connect (Boolean) —

    By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect.

  • :disconnected_retry_timeout (Integer) — default: 15 seconds —

    . When the connection enters the DISCONNECTED state, after this delay in milliseconds, if the state is still DISCONNECTED, the client library will attempt to reconnect automatically

  • :suspended_retry_timeout (Integer) — default: 30 seconds —

    . When the connection enters the SUSPENDED state, after this delay in milliseconds, if the state is still SUSPENDED, the client library will attempt to reconnect automatically

  • :tls (Boolean) — default: true —

    When fales, TLS is disabled. Please note Basic Auth is disallowed without TLS as secrets cannot be transmitted over unsecured connections.

  • :key (String) —

    API key comprising the key name and key secret in a single string

  • :token (String) —

    Token string or Models::TokenDetails used to authenticate requests

  • :token_details (String) —

    Models::TokenDetails used to authenticate requests

  • :use_token_auth (Boolean) —

    Will force Basic Auth if set to false, and Token auth if set to true

  • :environment (String) —

    Specify ‘sandbox’ when testing the client library against an alternate Ably environment

  • :protocol (Symbol) — default: :msgpack —

    Protocol used to communicate with Ably, :json and :msgpack currently supported

  • :use_binary_protocol (Boolean) — default: true —

    When true will use the MessagePack binary protocol, when false it will use JSON encoding. This option will overide :protocol option

  • :log_level (Logger::Severity, Symbol) — default: 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

  • :logger (Logger) —

    A custom logger can be used however it must adhere to the Ruby Logger interface, see www.ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html

  • :client_id (String) —

    client ID identifying this connection to other clients

  • :auth_url (String) —

    a URL to be used to GET or POST a set of token request params, to obtain a signed token request

  • :auth_headers (Hash) —

    a set of application-specific headers to be added to any request made to the auth_url

  • :auth_params (Hash) —

    a set of application-specific query params to be added to any request made to the auth_url

  • :auth_method (Symbol) — default: :get —

    HTTP method to use with auth_url, must be either :get or :post

  • :auth_callback (Proc) —

    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, Models::TokenDetails or JSON equivalent, Models::TokenRequest or JSON equivalent

  • :query_time (Boolean) —

    when true will query the Ably system for the current time instead of using the local time

  • :token_params (Hash) —

    convenience to pass in token_params that will be used as a default for all token requests. See Ably::Realtime::Auth#create_token_request

  • :http_open_timeout (Integer) — default: 4 seconds —

    timeout in seconds for opening an HTTP connection for all HTTP requests

  • :http_request_timeout (Integer) — default: 15 seconds —

    timeout in seconds for any single complete HTTP request and response

  • :http_max_retry_count (Integer) — default: 3 —

    maximum number of fallback host retries for HTTP requests that fail due to network issues or server problems

  • :http_max_retry_duration (Integer) — default: 10 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

Returns:



53
54
55
 
# File 'lib/ably/realtime.rb', line 53

def self.new(options)
  Ably::Realtime::Client.new(options)
end