ably 1.2.2 → 1.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/.rspec_parallel +3 -0
  3. data/.github/workflows/check.yml +13 -2
  4. data/.github/workflows/docs.yml +36 -0
  5. data/CHANGELOG.md +18 -0
  6. data/INTRO.md +14 -0
  7. data/lib/ably/auth.rb +26 -23
  8. data/lib/ably/models/auth_details.rb +9 -6
  9. data/lib/ably/models/channel_details.rb +15 -5
  10. data/lib/ably/models/channel_metrics.rb +31 -8
  11. data/lib/ably/models/channel_occupancy.rb +10 -3
  12. data/lib/ably/models/channel_options.rb +26 -3
  13. data/lib/ably/models/channel_state_change.rb +45 -15
  14. data/lib/ably/models/channel_status.rb +14 -4
  15. data/lib/ably/models/cipher_params.rb +36 -13
  16. data/lib/ably/models/connection_details.rb +91 -10
  17. data/lib/ably/models/connection_state_change.rb +54 -15
  18. data/lib/ably/models/delta_extras.rb +6 -7
  19. data/lib/ably/models/device_details.rb +60 -21
  20. data/lib/ably/models/device_push_details.rb +27 -19
  21. data/lib/ably/models/error_info.rb +59 -17
  22. data/lib/ably/models/http_paginated_response.rb +27 -5
  23. data/lib/ably/models/idiomatic_ruby_wrapper.rb +3 -2
  24. data/lib/ably/models/message.rb +64 -24
  25. data/lib/ably/models/message_encoders/base.rb +6 -0
  26. data/lib/ably/models/paginated_result.rb +29 -14
  27. data/lib/ably/models/presence_message.rb +72 -22
  28. data/lib/ably/models/protocol_message.rb +0 -4
  29. data/lib/ably/models/push_channel_subscription.rb +40 -15
  30. data/lib/ably/models/stats.rb +76 -40
  31. data/lib/ably/models/stats_types.rb +16 -40
  32. data/lib/ably/models/token_details.rb +34 -12
  33. data/lib/ably/models/token_request.rb +63 -2
  34. data/lib/ably/modules/async_wrapper.rb +1 -0
  35. data/lib/ably/modules/enum.rb +2 -0
  36. data/lib/ably/modules/event_emitter.rb +14 -1
  37. data/lib/ably/modules/model_common.rb +5 -0
  38. data/lib/ably/modules/state_emitter.rb +2 -0
  39. data/lib/ably/modules/state_machine.rb +4 -0
  40. data/lib/ably/realtime/channel/channel_properties.rb +9 -2
  41. data/lib/ably/realtime/channel/publisher.rb +2 -0
  42. data/lib/ably/realtime/channel/push_channel.rb +17 -10
  43. data/lib/ably/realtime/channel.rb +79 -42
  44. data/lib/ably/realtime/channels.rb +4 -3
  45. data/lib/ably/realtime/client/incoming_message_dispatcher.rb +6 -14
  46. data/lib/ably/realtime/client.rb +53 -32
  47. data/lib/ably/realtime/connection/connection_manager.rb +4 -0
  48. data/lib/ably/realtime/connection/websocket_transport.rb +4 -2
  49. data/lib/ably/realtime/connection.rb +94 -55
  50. data/lib/ably/realtime/presence.rb +61 -36
  51. data/lib/ably/realtime/push/admin.rb +16 -2
  52. data/lib/ably/realtime/push.rb +15 -3
  53. data/lib/ably/rest/channel/push_channel.rb +0 -3
  54. data/lib/ably/rest/channel.rb +29 -21
  55. data/lib/ably/rest/channels.rb +6 -3
  56. data/lib/ably/rest/client.rb +41 -35
  57. data/lib/ably/rest/presence.rb +27 -12
  58. data/lib/ably/rest/push/admin.rb +4 -0
  59. data/lib/ably/rest/push/device_registrations.rb +13 -2
  60. data/lib/ably/rest/push.rb +2 -0
  61. data/lib/ably/util/crypto.rb +14 -10
  62. data/lib/ably/version.rb +1 -1
  63. data/spec/acceptance/realtime/connection_spec.rb +0 -15
  64. data/spec/acceptance/realtime/message_spec.rb +3 -3
  65. data/spec/unit/models/protocol_message_spec.rb +0 -26
  66. data/spec/unit/realtime/incoming_message_dispatcher_spec.rb +0 -38
  67. metadata +6 -3
@@ -1,14 +1,21 @@
1
1
  module Ably::Realtime
2
2
  class Channel
3
- # Represents properties of a channel and its state
3
+ # Describes the properties of the channel state.
4
4
  class ChannelProperties
5
5
  # {Ably::Realtime::Channel} this object associated with
6
+ #
6
7
  # @return [Ably::Realtime::Channel]
8
+ #
7
9
  attr_reader :channel
8
10
 
9
- # Contains the last channelSerial received in an ATTACHED ProtocolMesage for the channel, see RTL15a
11
+ # Starts unset when a channel is instantiated, then updated with the channelSerial from each
12
+ # {Ably::Realtime::Channel::STATE.Attached} event that matches the channel.
13
+ # Used as the value for {Ably::Realtime::Channel#history}.
14
+ #
15
+ # @spec CP2a
10
16
  #
11
17
  # @return [String]
18
+ #
12
19
  attr_reader :attach_serial
13
20
 
14
21
  def initialize(channel)
@@ -5,7 +5,9 @@ module Ably::Realtime
5
5
  private
6
6
 
7
7
  # Prepare and queue messages on the connection queue immediately
8
+ #
8
9
  # @return [Ably::Util::SafeDeferrable]
10
+ #
9
11
  def enqueue_messages_on_connection(client, raw_messages, channel_name, channel_options = {})
10
12
  messages = Array(raw_messages).map do |raw_msg|
11
13
  create_message(client, raw_msg, channel_options).tap do |message|
@@ -1,10 +1,6 @@
1
1
  module Ably::Realtime
2
2
  class Channel
3
- # A push channel used for push notifications
4
- # Each PushChannel maps to exactly one Realtime Channel
5
- #
6
- # @!attribute [r] channel
7
- # @return [Ably::Realtime::Channel] Underlying channel object
3
+ # Enables devices to subscribe to push notifications for a channel.
8
4
  #
9
5
  class PushChannel
10
6
  attr_reader :channel
@@ -18,35 +14,46 @@ module Ably::Realtime
18
14
  "<PushChannel: name=#{channel.name}>"
19
15
  end
20
16
 
21
- # Subscribe local device for push notifications on this channel
17
+ # Subscribes the device to push notifications for the channel.
18
+ #
19
+ # @spec RSH7a
22
20
  #
23
21
  # @note This is unsupported in the Ruby library
24
22
  def subscribe_device(*args)
25
23
  raise_unsupported
26
24
  end
27
25
 
28
- # Subscribe all devices registered to this client's authenticated client_id for push notifications on this channel
26
+ # Subscribes all devices associated with the current device's clientId to push notifications for the channel.
27
+ #
28
+ # @spec RSH7b
29
29
  #
30
30
  # @note This is unsupported in the Ruby library
31
31
  def subscribe_client_id(*args)
32
32
  raise_unsupported
33
33
  end
34
34
 
35
- # Unsubscribe local device for push notifications on this channel
35
+ # Unsubscribes the device from receiving push notifications for the channel.
36
+ #
37
+ # @spec RSH7c
36
38
  #
37
39
  # @note This is unsupported in the Ruby library
38
40
  def unsubscribe_device(*args)
39
41
  raise_unsupported
40
42
  end
41
43
 
42
- # Unsubscribe all devices registered to this client's authenticated client_id for push notifications on this channel
44
+ # Unsubscribes all devices associated with the current device's clientId from receiving push notifications for the channel.
45
+ #
46
+ # @spec RSH7d
43
47
  #
44
48
  # @note This is unsupported in the Ruby library
45
49
  def unsubscribe_client_id(*args)
46
50
  raise_unsupported
47
51
  end
48
52
 
49
- # Get list of subscriptions on this channel for this device or authenticate client_id
53
+ # Retrieves all push subscriptions for the channel. Subscriptions can be filtered using a params object.
54
+ # Returns a {Ably::Models::PaginatedResult} object containing an array of {Ably::Models::PushChannelSubscription} objects.
55
+ #
56
+ # @spec RSH7e
50
57
  #
51
58
  # @note This is unsupported in the Ruby library
52
59
  def get_subscriptions(*args)
@@ -2,10 +2,8 @@ require 'ably/realtime/channel/publisher'
2
2
 
3
3
  module Ably
4
4
  module Realtime
5
- # The Channel class represents a Channel belonging to this application.
6
- # The Channel instance allows messages to be published and
7
- # received, and controls the lifecycle of this instance's
8
- # attachment to the channel.
5
+ # Enables messages to be published and subscribed to. Also enables historic messages to be retrieved and provides
6
+ # access to the {Ably::Realtime::Channel} object of a channel.
9
7
  #
10
8
  # Channels will always be in one of the following states:
11
9
  #
@@ -18,15 +16,17 @@ module Ably
18
16
  #
19
17
  # Note that the states are available as Enum-like constants:
20
18
  #
21
- # Channel::STATE.Initialized
22
- # Channel::STATE.Attaching
23
- # Channel::STATE.Attached
24
- # Channel::STATE.Detaching
25
- # Channel::STATE.Detached
26
- # Channel::STATE.Failed
27
- #
28
- # @!attribute [r] state
29
- # @return {Ably::Realtime::Connection::STATE} channel state
19
+ # Channel::STATE.Initialized The channel has been initialized but no attach has yet been attempted.
20
+ # Channel::STATE.Attaching An attach has been initiated by sending a request to Ably.
21
+ # This is a transient state, followed either by a transition to ATTACHED, SUSPENDED, or FAILED.
22
+ # Channel::STATE.Attached The attach has succeeded. In the ATTACHED state a client may publish and subscribe to messages, or be present on the channel.
23
+ # Channel::STATE.Detaching A detach has been initiated on an ATTACHED channel by sending a request to Ably.
24
+ # This is a transient state, followed either by a transition to DETACHED or FAILED.
25
+ # Channel::STATE.Detached The channel, having previously been ATTACHED, has been detached by the user.
26
+ # Channel::STATE.Suspended The channel, having previously been ATTACHED, has lost continuity, usually due to
27
+ # the client being disconnected from Ably for longer than two minutes. It will automatically attempt to reattach as soon as connectivity is restored.
28
+ # Channel::STATE.Failed An indefinite failure condition. This state is entered if a channel error
29
+ # has been received from the Ably service, such as an attempt to attach without the necessary access rights.
30
30
  #
31
31
  class Channel
32
32
  include Ably::Modules::Conversions
@@ -38,7 +38,10 @@ module Ably
38
38
  extend Ably::Modules::Enum
39
39
  extend Forwardable
40
40
 
41
- # ChannelState
41
+ # The current {Abbly::Realtime::Channel::STATE} of the channel.
42
+ #
43
+ # @spec RTL2b
44
+ #
42
45
  # The permited states for this channel
43
46
  STATE = ruby_enum('STATE',
44
47
  :initialized,
@@ -50,8 +53,13 @@ module Ably
50
53
  :failed
51
54
  )
52
55
 
53
- # ChannelEvent
56
+ # Describes the events emitted by a {Ably::Rest::Channel} or {Ably::Realtime::Channel} object.
57
+ # An event is either an UPDATE or a {Ably::Rest::Channel::STATE}.
58
+ #
54
59
  # The permitted channel events that are emitted for this channel
60
+ #
61
+ # @spec RTL2g
62
+ #
55
63
  EVENT = ruby_enum('EVENT',
56
64
  STATE.to_sym_arr + [:update]
57
65
  )
@@ -64,15 +72,18 @@ module Ably
64
72
  MAX_PROTOCOL_MESSAGE_BATCH_SIZE = 50
65
73
 
66
74
  # {Ably::Realtime::Client} associated with this channel
75
+ #
67
76
  # @return [Ably::Realtime::Client]
77
+ #
68
78
  # @api private
69
79
  attr_reader :client
70
80
 
71
- # Channel name
81
+ # The channel name.
72
82
  # @return [String]
73
83
  attr_reader :name
74
84
 
75
- # Push channel used for push notification
85
+ # A {Ably::Realtime::Channel::PushChannel} object.
86
+ #
76
87
  # @return [Ably::Realtime::Channel::PushChannel]
77
88
  attr_reader :push
78
89
 
@@ -80,11 +91,15 @@ module Ably
80
91
  # @return [Hash]
81
92
  attr_reader :options
82
93
 
83
- # Properties of a channel and its state
94
+ # A {Ably::Realtime::Channel::ChannelProperties} object.
95
+ #
96
+ # @spec CP1, RTL15
97
+ #
84
98
  # @return [{Ably::Realtime::Channel::ChannelProperties}]
85
99
  attr_reader :properties
86
100
 
87
- # When a channel failure occurs this attribute contains the Ably Exception
101
+ # An {Ably::Models::ErrorInfo} object describing the last error which occurred on the channel, if any.
102
+ # @spec RTL4e
88
103
  # @return [Ably::Models::ErrorInfo,Ably::Exceptions::BaseAblyException]
89
104
  attr_reader :error_reason
90
105
 
@@ -94,11 +109,12 @@ module Ably
94
109
  attr_reader :manager
95
110
 
96
111
  # Flag that specifies whether channel is resuming attachment(reattach) or is doing a 'clean attach' RTL4j1
97
- # @return [Bolean]
112
+ # @return [Boolean]
98
113
  # @api private
99
114
  attr_reader :attach_resume
100
115
 
101
- # ChannelOptions params attrribute (#RTL4k)
116
+ # Optional channel parameters that configure the behavior of the channel.
117
+ # @spec RTL4k1
102
118
  # return [Hash]
103
119
  def_delegators :options, :params
104
120
 
@@ -127,9 +143,11 @@ module Ably
127
143
  setup_presence
128
144
  end
129
145
 
130
- # Publish one or more messages to the channel.
146
+ # Publish a message to the channel. A callback may optionally be passed in to this call to be notified of success
147
+ # or failure of the operation. When publish is called with this client library, it won't attempt to implicitly
148
+ # attach to the channel.
131
149
  #
132
- # When publishing a message, if the channel is not attached, the channel is implicitly attached
150
+ # @spec RTL6i
133
151
  #
134
152
  # @param name [String, Array<Ably::Models::Message|Hash>, nil] The event name of the message to publish, or an Array of [Ably::Model::Message] objects or [Hash] objects with +:name+ and +:data+ pairs
135
153
  # @param data [String, ByteArray, nil] The message payload unless an Array of [Ably::Model::Message] objects passed in the first argument
@@ -195,9 +213,11 @@ module Ably
195
213
  end
196
214
  end
197
215
 
198
- # Subscribe to messages matching providing event name, or all messages if event name not provided.
216
+ # Registers a listener for messages on this channel. The caller supplies a listener function, which is called
217
+ # each time one or more messages arrives on the channel. A callback may optionally be passed in to this call
218
+ # to be notified of success or failure of the channel {Ably::Realtime::Channel#attach} operation.
199
219
  #
200
- # When subscribing to messages, if the channel is not attached, the channel is implicitly attached
220
+ # @spec RTL7a
201
221
  #
202
222
  # @param names [String] The event name of the message to subscribe to if provided. Defaults to all events.
203
223
  # @yield [Ably::Models::Message] For each message received, the block is called
@@ -209,8 +229,9 @@ module Ably
209
229
  super
210
230
  end
211
231
 
212
- # Unsubscribe the matching block for messages matching providing event name, or all messages if event name not provided.
213
- # If a block is not provided, all subscriptions will be unsubscribed
232
+ # Deregisters the given listener for the specified event name(s). This removes an earlier event-specific subscription.
233
+ #
234
+ # @spec RTL8a
214
235
  #
215
236
  # @param names [String] The event name of the message to subscribe to if provided. Defaults to all events.
216
237
  #
@@ -220,9 +241,15 @@ module Ably
220
241
  super
221
242
  end
222
243
 
223
- # Attach to this channel, and call the block if provided when attached.
224
- # Attaching to a channel is implicit in when a message is published or #subscribe is called, so it is uncommon
225
- # to need to call attach explicitly.
244
+ # Attach to this channel ensuring the channel is created in the Ably system and all messages published on
245
+ # the channel are received by any channel listeners registered using {Ably::Realtime::Channel#subscribe}.
246
+ # Any resulting channel state change will be emitted to any listeners registered using the {Ably::Modules::EventEmitter#on}
247
+ # or {Ably::Modules::EventEmitter#once} methods. A callback may optionally be passed in to this call to be notified
248
+ # of success or failure of the operation. As a convenience, attach() is called implicitly
249
+ # if {Ably::Realtime::Channel#subscribe} for the channel is called, or {Ably::Realtime::Presence#enter}
250
+ # or {Ably::Realtime::Presence#subscribe} are called on the {Ably::Realtime::Presence} object for this channel.
251
+ #
252
+ # @spec RTL4d
226
253
  #
227
254
  # @yield [Ably::Realtime::Channel] Block is called as soon as this channel is in the Attached state
228
255
  # @return [Ably::Util::SafeDeferrable] Deferrable that supports both success (callback) and failure (errback) callback
@@ -245,7 +272,12 @@ module Ably
245
272
  deferrable_for_state_change_to(STATE.Attached, &success_block)
246
273
  end
247
274
 
248
- # Detach this channel, and call the block if provided when in a Detached or Failed state
275
+ # Detach from this channel. Any resulting channel state change is emitted to any listeners registered using
276
+ # the {Ably::Modules::EventEmitter#on} or {Ably::Modules::EventEmitter#once} methods. A callback may optionally
277
+ # be passed in to this call to be notified of success or failure of the operation. Once all clients globally
278
+ # have detached from the channel, the channel will be released in the Ably service within two minutes.
279
+ #
280
+ # @spec RTL5e
249
281
  #
250
282
  # @yield [Ably::Realtime::Channel] Block is called as soon as this channel is in the Detached or Failed state
251
283
  # @return [Ably::Util::SafeDeferrable] Deferrable that supports both success (callback) and failure (errback) callback
@@ -274,9 +306,9 @@ module Ably
274
306
  deferrable_for_state_change_to(STATE.Detached, &success_block)
275
307
  end
276
308
 
277
- # Presence object for this Channel. This controls this client's
278
- # presence on the channel and may also be used to obtain presence information
279
- # and change events for other members of the channel.
309
+ # A {Ably::Realtime::Presence} object.
310
+ #
311
+ # @spec RTL9
280
312
  #
281
313
  # @return {Ably::Realtime::Presence}
282
314
  #
@@ -284,14 +316,15 @@ module Ably
284
316
  @presence
285
317
  end
286
318
 
287
- # Return the message history of the channel
319
+ # Retrieves a {Ably::Models::PaginatedResult} object, containing an array of historical
320
+ # {Ably::Models::Message} objects for the channel. If the channel is configured to persist messages,
321
+ # then messages can be retrieved from history for up to 72 hours in the past. If not, messages can only
322
+ # be retrieved from history for up to two minutes in the past.
288
323
  #
289
- # If the channel is attached, you can retrieve messages published on the channel before the
290
- # channel was attached with the option <tt>until_attach: true</tt>. This is useful when a developer
291
- # wishes to display historical messages with the guarantee that no messages have been missed since attach.
324
+ # @spec RSL2a
292
325
  #
293
- # @param (see Ably::Rest::Channel#history)
294
- # @option options (see Ably::Rest::Channel#history)
326
+ # @param (see {Ably::Rest::Channel#history})
327
+ # @option options (see {Ably::Rest::Channel#history})
295
328
  # @option options [Boolean] :until_attach When true, the history request will be limited only to messages published before this channel was attached. Channel must be attached
296
329
  #
297
330
  # @yield [Ably::Models::PaginatedResult<Ably::Models::Message>] First {Ably::Models::PaginatedResult page} of {Ably::Models::Message} objects accessible with {Ably::Models::PaginatedResult#items #items}.
@@ -312,8 +345,8 @@ module Ably
312
345
  end
313
346
  end
314
347
 
315
- # @!attribute [r] __incoming_msgbus__
316
348
  # @return [Ably::Util::PubSub] Client library internal channel incoming message bus
349
+ #
317
350
  # @api private
318
351
  def __incoming_msgbus__
319
352
  @__incoming_msgbus__ ||= Ably::Util::PubSub.new(
@@ -321,7 +354,11 @@ module Ably
321
354
  )
322
355
  end
323
356
 
324
- # Sets or updates the stored channel options. (#RTL16)
357
+ # Sets the {Ably::Models::ChannelOptions} for the channel.
358
+ # An optional callback may be provided to notify of the success or failure of the operation.
359
+ #
360
+ # @spec RTL16
361
+ #
325
362
  # @param channel_options [Hash, Ably::Models::ChannelOptions] A hash of options or a {Ably::Models::ChannelOptions}
326
363
  # @return [Ably::Models::ChannelOptions]
327
364
  def set_options(channel_options)
@@ -5,28 +5,29 @@ module Ably
5
5
  include Ably::Modules::ChannelsCollection
6
6
 
7
7
  # @return [Ably::Realtime::Channels]
8
+ #
8
9
  def initialize(client)
9
10
  super client, Ably::Realtime::Channel
10
11
  end
11
12
 
12
- # @!method get(name, channel_options = {})
13
13
  # Return a {Ably::Realtime::Channel} for the given name
14
14
  #
15
15
  # @param name [String] The name of the channel
16
16
  # @param channel_options [Hash, Ably::Models::ChannelOptions] A hash of options or a {Ably::Models::ChannelOptions}
17
- # @return [Ably::Realtime::Channel}
17
+ #
18
+ # @return [Ably::Realtime::Channel]
18
19
  #
19
20
  def get(*args)
20
21
  super
21
22
  end
22
23
 
23
- # @!method fetch(name, &missing_block)
24
24
  # Return a {Ably::Realtime::Channel} for the given name if it exists, else the block will be called.
25
25
  # This method is intentionally similar to {http://ruby-doc.org/core-2.1.3/Hash.html#method-i-fetch Hash#fetch} providing a simple way to check if a channel exists or not without creating one
26
26
  #
27
27
  # @param name [String] The name of the channel
28
28
  # @yield [options] (optional) if a missing_block is passed to this method and no channel exists matching the name, this block is called
29
29
  # @yieldparam [String] name of the missing channel
30
+ #
30
31
  # @return [Ably::Realtime::Channel]
31
32
  #
32
33
  def fetch(*args)
@@ -121,23 +121,15 @@ module Ably::Realtime
121
121
  presence.manager.sync_process_messages protocol_message.channel_serial, protocol_message.presence
122
122
 
123
123
  when ACTION.Presence
124
- if protocol_message.has_correct_message_size?
125
- presence = get_channel(protocol_message.channel).presence
126
- protocol_message.presence.each do |presence_message|
127
- presence.__incoming_msgbus__.publish :presence, presence_message
128
- end
129
- else
130
- logger.fatal Ably::Exceptions::ProtocolError.new("Not published. Channel message limit exceeded #{protocol_message.message_size} bytes", 400, Ably::Exceptions::Codes::UNABLE_TO_RECOVER_CHANNEL_MESSAGE_LIMIT_EXCEEDED).message
124
+ presence = get_channel(protocol_message.channel).presence
125
+ protocol_message.presence.each do |presence_message|
126
+ presence.__incoming_msgbus__.publish :presence, presence_message
131
127
  end
132
128
 
133
129
  when ACTION.Message
134
- if protocol_message.has_correct_message_size?
135
- channel = get_channel(protocol_message.channel)
136
- protocol_message.messages.each do |message|
137
- channel.__incoming_msgbus__.publish :message, message
138
- end
139
- else
140
- logger.fatal Ably::Exceptions::ProtocolError.new("Not published. Channel message limit exceeded #{protocol_message.message_size} bytes", 400, Ably::Exceptions::Codes::UNABLE_TO_RECOVER_CHANNEL_MESSAGE_LIMIT_EXCEEDED).message
130
+ channel = get_channel(protocol_message.channel)
131
+ protocol_message.messages.each do |message|
132
+ channel.__incoming_msgbus__.publish :message, message
141
133
  end
142
134
 
143
135
  when ACTION.Auth
@@ -3,22 +3,7 @@ require 'ably/realtime/channel/publisher'
3
3
 
4
4
  module Ably
5
5
  module Realtime
6
- # Client for the Ably Realtime API
7
- #
8
- # @!attribute [r] client_id
9
- # (see Ably::Rest::Client#client_id)
10
- # @!attribute [r] auth_options
11
- # (see Ably::Rest::Client#auth_options)
12
- # @!attribute [r] environment
13
- # (see Ably::Rest::Client#environment)
14
- # @!attribute [r] channels
15
- # @return [Aby::Realtime::Channels] The collection of {Ably::Realtime::Channel}s that have been created
16
- # @!attribute [r] encoders
17
- # (see Ably::Rest::Client#encoders)
18
- # @!attribute [r] protocol
19
- # (see Ably::Rest::Client#protocol)
20
- # @!attribute [r] protocol_binary?
21
- # (see Ably::Rest::Client#protocol_binary?)
6
+ # A client that extends the functionality of the {Ably::Realtime::Client} and provides additional realtime-specific features.
22
7
  #
23
8
  class Client
24
9
  include Ably::Modules::AsyncWrapper
@@ -29,19 +14,33 @@ module Ably
29
14
 
30
15
  DOMAIN = 'realtime.ably.io'
31
16
 
32
- # The collection of {Ably::Realtime::Channel}s that have been created
17
+ # A {Aby::Realtime::Channels} object.
18
+ #
19
+ # @spec RTC3, RTS1
20
+ #
33
21
  # @return [Aby::Realtime::Channels]
22
+ #
34
23
  attr_reader :channels
35
24
 
36
- # (see Ably::Rest::Client#auth)
25
+ # An {Ably::Auth} object.
26
+ #
27
+ # @spec RTC4
28
+ #
29
+ # @return [Ably::Auth]
30
+ #
37
31
  attr_reader :auth
38
32
 
39
- # The underlying connection for this client
33
+ # A {Aby::Realtime::Connection} object.
34
+ #
35
+ # @spec RTC2
36
+ #
40
37
  # @return [Aby::Realtime::Connection]
38
+ #
41
39
  attr_reader :connection
42
40
 
43
41
  # The {Ably::Rest::Client REST client} instantiated with the same credentials and configuration that is used for all REST operations such as authentication
44
42
  # @return [Ably::Rest::Client]
43
+
45
44
  # @private
46
45
  attr_reader :rest_client
47
46
 
@@ -78,8 +77,10 @@ module Ably
78
77
 
79
78
  # Creates a {Ably::Realtime::Client Realtime Client} and configures the {Ably::Auth} object for the connection.
80
79
  #
81
- # @param (see Ably::Rest::Client#initialize)
82
- # @option options (see Ably::Rest::Client#initialize)
80
+ # @spec RSC1
81
+ #
82
+ # @param (see {Ably::Rest::Client#initialize})
83
+ # @option options (see Ably::Rest::Client#initialize) An options {Hash} object.
83
84
  # @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.
84
85
  # Whilst the proc is called synchronously, it does not block the EventMachine reactor as it is run in a separate thread.
85
86
  # The Proc should return a token string, {Ably::Models::TokenDetails} or JSON equivalent, {Ably::Models::TokenRequest} or JSON equivalent
@@ -97,10 +98,10 @@ module Ably
97
98
  # @return [Ably::Realtime::Client]
98
99
  #
99
100
  # @example
100
- # # create a new client authenticating with basic auth
101
+ # # Constructs a {Ably::Realtime::Client} object using an Ably API key or token string.
101
102
  # client = Ably::Realtime::Client.new('key.id:secret')
102
103
  #
103
- # # create a new client and configure a client ID used for presence
104
+ # # Constructs a {Ably::Realtime::Client} object using an Ably options object.
104
105
  # client = Ably::Realtime::Client.new(key: 'key.id:secret', client_id: 'john')
105
106
  #
106
107
  def initialize(options)
@@ -141,9 +142,13 @@ module Ably
141
142
  channels.get(name, channel_options)
142
143
  end
143
144
 
144
- # Retrieve the Ably service time
145
+ # Retrieves the time from the Ably service as milliseconds since the Unix epoch. Clients that do not have access
146
+ # to a sufficiently well maintained time source and wish to issue Ably {Ably::Models::TokenRequests} with
147
+ # a more accurate timestamp should use the queryTime property instead of this method.
148
+ #
149
+ # @spec RTC6a
145
150
  #
146
- # @yield [Time] The time as reported by the Ably service
151
+ # @yield [Time] The time as milliseconds since the Unix epoch.
147
152
  # @return [Ably::Util::SafeDeferrable]
148
153
  #
149
154
  def time(&success_callback)
@@ -152,12 +157,15 @@ module Ably
152
157
  end
153
158
  end
154
159
 
155
- # Retrieve the stats for the application
160
+ # Queries the REST /stats API and retrieves your application's usage statistics.
161
+ # Returns a {Ably::Util::SafeDeferrable} object, containing an array of {Ably::Models::Stats} objects. See the Stats docs.
162
+ #
163
+ # @spec RTC5
156
164
  #
157
165
  # @param (see Ably::Rest::Client#stats)
158
166
  # @option options (see Ably::Rest::Client#stats)
159
167
  #
160
- # @yield [Ably::Models::PaginatedResult<Ably::Models::Stats>] An Array of Stats
168
+ # @yield [Ably::Models::PaginatedResult<Ably::Models::Stats>] A {Ably::Util::SafeDeferrable} object containing an array of {Ably::Models::Stats} objects.
161
169
  #
162
170
  # @return [Ably::Util::SafeDeferrable]
163
171
  #
@@ -167,26 +175,38 @@ module Ably
167
175
  end
168
176
  end
169
177
 
178
+ # Calls {Connection#close} and causes the connection to close, entering the closing state.
179
+ # Once closed, the library will not attempt to re-establish the connection without an explicit call to {Connection#connect}.
180
+ # @spec RTN12
170
181
  # (see Ably::Realtime::Connection#close)
171
182
  def close(&block)
172
183
  connection.close(&block)
173
184
  end
174
185
 
186
+ # Calls {Ably::Realtime::Connection#connect} and causes the connection to open, entering the connecting
187
+ # state. Explicitly calling connect() is unnecessary unless the autoConnect property is disabled.
188
+ # @spec RTN11
175
189
  # (see Ably::Realtime::Connection#connect)
176
190
  def connect(&block)
177
191
  connection.connect(&block)
178
192
  end
179
193
 
180
- # Push notification object for publishing and managing push notifications
194
+ # A {Ably::Realtime::Push} object.
181
195
  # @return [Ably::Realtime::Push]
182
196
  def push
183
197
  @push ||= Push.new(self)
184
198
  end
185
199
 
186
- # (see Ably::Rest::Client#request)
200
+ # Makes a REST request to a provided path. This is provided as a convenience for developers who wish to use REST
201
+ # API functionality that is either not documented or is not yet included in the public API, without having to
202
+ # directly handle features such as authentication, paging, fallback hosts, MsgPack and JSON support.
203
+ #
204
+ # @spec RTC9
205
+ #
206
+ # (see {Ably::Rest::Client#request})
187
207
  # @yield [Ably::Models::HttpPaginatedResponse<>] An Array of Stats
188
208
  #
189
- # @return [Ably::Util::SafeDeferrable]
209
+ # @return [Ably::Util::SafeDeferrable] An {Ably::Util::SafeDeferrable} response object returned by the HTTP request, containing an empty or JSON-encodable object.
190
210
  def request(method, path, params = {}, body = nil, headers = {}, &callback)
191
211
  async_wrap(callback) do
192
212
  rest_client.request(method, path, params, body, headers, async_blocking_operations: true)
@@ -303,8 +323,9 @@ module Ably
303
323
  @fallback_endpoints[fallback_endpoint_index % @fallback_endpoints.count]
304
324
  end
305
325
 
306
- # The local device detilas
307
- # @return [Ably::Models::LocalDevice]
326
+ # Retrieves a {Ably::Models::LocalDevice} object that represents the current state of the device as a target for push notifications.
327
+ # @spec RSH8
328
+ # @return [Ably::Models::LocalDevice] A {Ably::Models::LocalDevice} object.
308
329
  #
309
330
  # @note This is unsupported in the Ruby library
310
331
  def device
@@ -270,7 +270,9 @@ module Ably::Realtime
270
270
  end
271
271
 
272
272
  # Number of consecutive attempts for provided state
273
+ #
273
274
  # @return [Integer]
275
+ #
274
276
  # @api private
275
277
  def retry_count_for_state(state)
276
278
  retries_for_state(state, ignore_states: [:connecting]).count
@@ -356,7 +358,9 @@ module Ably::Realtime
356
358
  end
357
359
 
358
360
  # Timers used to manage connection state, for internal use by the client library
361
+ #
359
362
  # @return [Hash]
363
+ #
360
364
  def timers
361
365
  @timers
362
366
  end
@@ -31,7 +31,9 @@ module Ably::Realtime
31
31
 
32
32
  # Disconnect the socket transport connection and write all pending text.
33
33
  # If Disconnected state is not automatically emitted, it will be emitted automatically
34
+ #
34
35
  # @return [void]
36
+ #
35
37
  # @api public
36
38
  def disconnect
37
39
  close_connection_after_writing
@@ -133,15 +135,15 @@ module Ably::Realtime
133
135
  !connecting? && !connected?
134
136
  end
135
137
 
136
- # @!attribute [r] __incoming_protocol_msgbus__
137
138
  # @return [Ably::Util::PubSub] Websocket Transport internal incoming protocol message bus
139
+ #
138
140
  # @api private
139
141
  def __incoming_protocol_msgbus__
140
142
  @__incoming_protocol_msgbus__ ||= create_pub_sub_message_bus
141
143
  end
142
144
 
143
- # @!attribute [r] __outgoing_protocol_msgbus__
144
145
  # @return [Ably::Util::PubSub] Websocket Transport internal outgoing protocol message bus
146
+ #
145
147
  # @api private
146
148
  def __outgoing_protocol_msgbus__
147
149
  @__outgoing_protocol_msgbus__ ||= create_pub_sub_message_bus