Module: Ably::Realtime

Defined in:
lib/ably/realtime.rb,
lib/ably/realtime/auth.rb,
lib/ably/realtime/push.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/push/admin.rb,
lib/ably/realtime/channel/publisher.rb,
lib/ably/realtime/channel/push_channel.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/push/device_registrations.rb,
lib/ably/realtime/channel/channel_properties.rb,
lib/ably/realtime/push/channel_subscriptions.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, Push

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):

  • :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. Whilst the proc is called synchronously, it does not block the EventMachine reactor as it is run in a separate thread. The Proc should return a token string, Models::TokenDetails or JSON equivalent, Models::TokenRequest or JSON equivalent

  • :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.

  • :transport_params (Hash) —

    Additional parameters to be sent in the querystring when initiating a realtime connection. Keys are Strings, values are Stringifiable(a value must respond to #to_s)

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

    . When a channel becomes SUSPENDED, after this delay in seconds, the channel will automatically attempt to reattach if the connection is CONNECTED

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

    . When the connection enters the DISCONNECTED state, after this delay in seconds, 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 seconds, if the state is still SUSPENDED, the client library will attempt to reconnect automatically

  • :disable_websocket_heartbeats (Boolean) —

    WebSocket heartbeats are more efficient than protocol level heartbeats, however they can be disabled for development purposes

  • :tls (Boolean) — default: true —

    When false, 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

  • :default_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: 10 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: 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

  • :fallback_hosts_use_default (Boolean) — default: false —

    When true, forces the user of fallback hosts even if a non-default production endpoint is being used

  • :fallback_hosts (Array<String>) —

    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

  • :fallback_retry_timeout (Integer) — default: 600 seconds —

    amount of time in seconds a REST client will continue to use a working fallback host when the primary fallback host has previously failed

  • :add_request_ids (Boolean) — default: 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.

  • :idempotent_rest_publishing (Boolean) — default: false if ver < 1.2 —

    When true, idempotent publishing is enabled for all messages published via REST

  • :max_message_size (Integer) — default: 65536 bytes —

    Maximum size of all messages when publishing via REST publish()

  • :max_frame_size (Integer) — default: 524288 bytes —

    Maximum size of frame

Returns:



56
57
58
 
# File 'lib/ably/realtime.rb', line 56

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