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
@@ -17,27 +17,17 @@ module Ably::Models
17
17
 
18
18
  # A class representing an individual statistic for a specified {#interval_id}
19
19
  #
20
- # @!attribute [r] all
21
- # @return [Stats::MessageTypes] Breakdown of summary stats for all message types
22
- # @!attribute [r] inbound
23
- # @return [Stats::MessageTraffic] Breakdown of summary stats for traffic over various transport types for all inbound messages
24
- # @!attribute [r] outbound
25
- # @return [Stats::MessageTraffic] Breakdown of summary stats for traffic over various transport types for all outbound messages
26
- # @!attribute [r] persisted
27
- # @return [Stats::MessageTypes] Breakdown of summary stats for all persisted messages
28
- # @!attribute [r] connections
29
- # @return [Stats::ConnectionTypes] A breakdown of summary stats data for different (TLS vs non-TLS) connection types.
30
- # @!attribute [r] channels
31
- # @return [Stats::ResourceCount] Aggregate data for usage of Channels
32
- # @!attribute [r] api_requests
33
- # @return [Stats::RequestCount] Aggregate data for numbers of API requests
34
- # @!attribute [r] token_requests
35
- # @return [Stats::RequestCount] Aggregate data for numbers of Token requests
36
- #
37
20
  class Stats
38
21
  include Ably::Modules::ModelCommon
39
22
  extend Ably::Modules::Enum
40
23
 
24
+ # Describes the interval unit over which statistics are gathered.
25
+ #
26
+ # MINUTE Interval unit over which statistics are gathered as minutes.
27
+ # HOUR Interval unit over which statistics are gathered as hours.
28
+ # DAY Interval unit over which statistics are gathered as days.
29
+ # MONTH Interval unit over which statistics are gathered as months.
30
+ #
41
31
  GRANULARITY = ruby_enum('GRANULARITY',
42
32
  :minute,
43
33
  :hour,
@@ -88,13 +78,13 @@ module Ably::Models
88
78
  Time.strptime("#{interval_id} +0000", "#{format} %z").utc
89
79
  end
90
80
 
91
- # Returns the {GRANULARITY} determined from the interval_id
81
+ # Returns the {Symbol} determined from the interval_id
92
82
  # @example
93
83
  # Stats.granularity_from_interval_id('2015-01-01:10') # => :hour
94
84
  #
95
85
  # @param interval_id [String]
96
86
  #
97
- # @return [GRANULARITY] Granularity Enum for the interval_id
87
+ # @return [Symbol]
98
88
  #
99
89
  def granularity_from_interval_id(interval_id)
100
90
  raise ArgumentError, 'Interval ID must be a string' unless interval_id.kind_of?(String)
@@ -120,68 +110,114 @@ module Ably::Models
120
110
  set_attributes_object hash_object
121
111
  end
122
112
 
123
- # Aggregates inbound and outbound messages
124
- # @return {Stats::MessageTypes}
113
+ # A {Ably::Models::Stats::MessageTypes} object containing the aggregate count of all message stats.
114
+ #
115
+ # @spec TS12e
116
+ #
117
+ # @return [Stats::MessageTypes]
118
+ #
125
119
  def all
126
120
  @all ||= Stats::MessageTypes.new(attributes[:all])
127
121
  end
128
122
 
129
- # All inbound messages i.e. received by Ably from clients
130
- # @return {Stats::MessageTraffic}
123
+ # A {Ably::Models::Stats::MessageTraffic} object containing the aggregate count of inbound message stats.
124
+ #
125
+ # @spec TS12f
126
+ #
127
+ # @return [Ably::Models::Stats::MessageTraffic]
128
+ #
131
129
  def inbound
132
130
  @inbound ||= Stats::MessageTraffic.new(attributes[:inbound])
133
131
  end
134
132
 
135
- # All outbound messages i.e. sent from Ably to clients
136
- # @return {Stats::MessageTraffic}
133
+ # A {Ably::Models::Stats::MessageTraffic} object containing the aggregate count of outbound message stats.
134
+ #
135
+ # @spec TS12g
136
+ #
137
+ # @return [Ably::Models::Stats::MessageTraffic]
138
+ #
137
139
  def outbound
138
140
  @outbound ||= Stats::MessageTraffic.new(attributes[:outbound])
139
141
  end
140
142
 
141
- # Messages persisted for later retrieval via the history API
142
- # @return {Stats::MessageTypes}
143
+ # A {Ably::Models::Stats::MessageTraffic} object containing the aggregate count of persisted message stats.
144
+ #
145
+ # @spec TS12h
146
+ #
147
+ # @return [Ably::Models::Stats::MessageTraffic]
148
+ #
143
149
  def persisted
144
150
  @persisted ||= Stats::MessageTypes.new(attributes[:persisted])
145
151
  end
146
152
 
147
- # Breakdown of connection stats data for different (TLS vs non-TLS) connection types
148
- # @return {Stats::ConnectionTypes}
153
+ # A {Ably::Models::Stats::ConnectionTypes} object containing a breakdown of connection related stats, such as min, mean and peak connections.
154
+ #
155
+ # @spec TS12i
156
+ #
157
+ # @return [Ably::Models::Stats::ConnectionTypes]
158
+ #
149
159
  def connections
150
160
  @connections ||= Stats::ConnectionTypes.new(attributes[:connections])
151
161
  end
152
162
 
153
- # Breakdown of channels stats
154
- # @return {Stats::ResourceCount}
163
+ # A {Ably::Models::Stats::ResourceCount} object containing a breakdown of connection related stats, such as min, mean and peak connections.
164
+ #
165
+ # @spec TS12j
166
+ #
167
+ # @return [Ably::Models::Stats::ResourceCount]
168
+ #
155
169
  def channels
156
170
  @channels ||= Stats::ResourceCount.new(attributes[:channels])
157
171
  end
158
172
 
159
- # Breakdown of API requests received via the REST API
160
- # @return {Stats::RequestCount}
173
+ # A {Ably::Models::Stats::RequestCount} object containing a breakdown of API Requests.
174
+ #
175
+ # @spec TS12k
176
+ #
177
+ # @return [Ably::Models::Stats::RequestCount]
178
+ #
161
179
  def api_requests
162
180
  @api_requests ||= Stats::RequestCount.new(attributes[:api_requests])
163
181
  end
164
182
 
165
- # Breakdown of Token requests received via the REST API
166
- # @return {Stats::RequestCount}
183
+ # A {Ably::Models::Stats::RequestCount} object containing a breakdown of Ably Token requests.
184
+ #
185
+ # @spec TS12l
186
+ #
187
+ # @return [Ably::Models::Stats::RequestCount]
188
+ #
167
189
  def token_requests
168
190
  @token_requests ||= Stats::RequestCount.new(attributes[:token_requests])
169
191
  end
170
192
 
171
- # @!attribute [r] interval_id
172
- # @return [String] The interval that this statistic applies to, see {GRANULARITY} and {INTERVAL_FORMAT_STRING}
193
+ # The UTC time at which the time period covered begins. If unit is set to minute this will be in
194
+ # the format YYYY-mm-dd:HH:MM, if hour it will be YYYY-mm-dd:HH, if day it will be YYYY-mm-dd:00
195
+ # and if month it will be YYYY-mm-01:00.
196
+ #
197
+ # @spec TS12a
198
+ #
199
+ # @return [String]
200
+ #
173
201
  def interval_id
174
202
  attributes.fetch(:interval_id)
175
203
  end
176
204
 
177
- # @!attribute [r] interval_time
178
- # @return [Time] A Time object representing the start of the interval
205
+ # Represents the intervalId as a time object.
206
+ #
207
+ # @spec TS12b
208
+ #
209
+ # @return [Time]
210
+ #
179
211
  def interval_time
180
212
  self.class.from_interval_id(interval_id)
181
213
  end
182
214
 
183
- # @!attribute [r] interval_granularity
215
+ # The length of the interval the stats span. Values will be a [StatsIntervalGranularity]{@link StatsIntervalGranularity}.
216
+ #
217
+ # @spec TS12c
218
+ #
184
219
  # @return [GRANULARITY] The granularity of the interval for the stat such as :day, :hour, :minute, see {GRANULARITY}
220
+ #
185
221
  def interval_granularity
186
222
  self.class.granularity_from_interval_id(interval_id)
187
223
  end
@@ -59,71 +59,47 @@ module Ably::Models
59
59
  end
60
60
 
61
61
  # MessageCount contains aggregate counts for messages and data transferred
62
- # @!attribute [r] count
63
- # @return [Integer] count of all messages
64
- # @!attribute [r] data
65
- # @return [Integer] total data transferred for all messages in bytes
62
+ #
63
+ # @spec TS5a, TS5b
64
+ #
66
65
  class MessageCount < StatsStruct
67
66
  coerce_attributes :count, :data, into: IntegerDefaultZero
68
67
  end
69
68
 
70
69
  # RequestCount contains aggregate counts for requests made
71
- # @!attribute [r] succeeded
72
- # @return [Integer] requests succeeded
73
- # @!attribute [r] failed
74
- # @return [Integer] requests failed
75
- # @!attribute [r] refused
76
- # @return [Integer] requests refused typically as a result of permissions or a limit being exceeded
70
+ #
71
+ # @spec TS8a, TS8b, TS8c
72
+ #
77
73
  class RequestCount < StatsStruct
78
74
  coerce_attributes :succeeded, :failed, :refused, into: IntegerDefaultZero
79
75
  end
80
76
 
81
77
  # ResourceCount contains aggregate data for usage of a resource in a specific scope
82
- # @!attribute [r] opened
83
- # @return [Integer] total resources of this type opened
84
- # @!attribute [r] peak
85
- # @return [Integer] peak resources of this type used for this period
86
- # @!attribute [r] mean
87
- # @return [Integer] average resources of this type used for this period
88
- # @!attribute [r] min
89
- # @return [Integer] minimum total resources of this type used for this period
90
- # @!attribute [r] refused
91
- # @return [Integer] resource requests refused within this period
78
+ #
92
79
  class ResourceCount < StatsStruct
93
80
  coerce_attributes :opened, :peak, :mean, :min, :refused, into: IntegerDefaultZero
94
81
  end
95
82
 
96
83
  # ConnectionTypes contains a breakdown of summary stats data for different (TLS vs non-TLS) connection types
97
- # @!attribute [r] tls
98
- # @return [ResourceCount] TLS connection count
99
- # @!attribute [r] plain
100
- # @return [ResourceCount] non-TLS connection count (unencrypted)
101
- # @!attribute [r] all
102
- # @return [ResourceCount] all connection count (includes both TLS & non-TLS connections)
84
+ #
85
+ # @spec TS4a, TS4b, TS4c
86
+ #
103
87
  class ConnectionTypes < StatsStruct
104
88
  coerce_attributes :tls, :plain, :all, into: ResourceCount
105
89
  end
106
90
 
107
91
  # MessageTypes contains a breakdown of summary stats data for different (message vs presence) message types
108
- # @!attribute [r] messages
109
- # @return [MessageCount] count of channel messages
110
- # @!attribute [r] presence
111
- # @return [MessageCount] count of presence messages
112
- # @!attribute [r] all
113
- # @return [MessageCount] all messages count (includes both presence & messages)
92
+ #
93
+ # @spec TS6a, TS6b, TS6c
94
+ #
114
95
  class MessageTypes < StatsStruct
115
96
  coerce_attributes :messages, :presence, :all, into: MessageCount
116
97
  end
117
98
 
118
99
  # MessageTraffic contains a breakdown of summary stats data for traffic over various transport types
119
- # @!attribute [r] realtime
120
- # @return [MessageTypes] count of messages transferred over a realtime transport such as WebSockets
121
- # @!attribute [r] rest
122
- # @return [MessageTypes] count of messages transferred using REST
123
- # @!attribute [r] webhook
124
- # @return [MessageTypes] count of messages delivered using WebHooks
125
- # @!attribute [r] all
126
- # @return [MessageTypes] all messages count (includes realtime, rest and webhook messages)
100
+ #
101
+ # @spec TS7a, TS7b, TS7c, TS7d
102
+ #
127
103
  class MessageTraffic < StatsStruct
128
104
  coerce_attributes :realtime, :rest, :webhook, :all, into: MessageTypes
129
105
  end
@@ -4,6 +4,7 @@ module Ably::Models
4
4
  # @param attributes (see #initialize)
5
5
  #
6
6
  # @return [TokenDetails]
7
+ #
7
8
  def self.TokenDetails(attributes)
8
9
  case attributes
9
10
  when TokenDetails
@@ -13,11 +14,7 @@ module Ably::Models
13
14
  end
14
15
  end
15
16
 
16
- # TokenDetails is a class providing details of the token string and the token's associated metadata,
17
- # constructed from the response from Ably when request in a token via the REST API.
18
- #
19
- # Ruby {http://ruby-doc.org/core/Time.html Time} objects are supported in place of Ably ms since epoch time fields. However, if a numeric is provided
20
- # it must always be expressed in milliseconds as the Ably API always uses milliseconds for time fields.
17
+ # Contains an Ably Token and its associated metadata.
21
18
  #
22
19
  class TokenDetails
23
20
  include Ably::Modules::ModelCommon
@@ -46,31 +43,39 @@ module Ably::Models
46
43
  self.attributes.freeze
47
44
  end
48
45
 
49
- # @!attribute [r] token
46
+ # The Ably Token itself. A typical Ably Token string appears with the form xVLyHw.A-pwh7wicf3afTfgiw4k2Ku33kcnSA7z6y8FjuYpe3QaNRTEo4.
47
+ #
48
+ # @spec TD2
49
+ #
50
50
  # @return [String] Token used to authenticate requests
51
+ #
51
52
  def token
52
53
  attributes[:token]
53
54
  end
54
55
 
55
- # @!attribute [r] key_name
56
56
  # @return [String] API key name used to create this token. An API key is made up of an API key name and secret delimited by a +:+
57
+ #
57
58
  def key_name
58
59
  attributes[:key_name]
59
60
  end
60
61
 
61
- # @!attribute [r] issued
62
+ # The timestamp at which this token was issued as milliseconds since the Unix epoch.
63
+ # @spec TD4
62
64
  # @return [Time] Time the token was issued
63
65
  def issued
64
66
  as_time_from_epoch(attributes[:issued], granularity: :ms, allow_nil: :true)
65
67
  end
66
68
 
67
- # @!attribute [r] expires
69
+ # The timestamp at which this token expires as milliseconds since the Unix epoch.
70
+ # @spec TD3
68
71
  # @return [Time] Time the token expires
69
72
  def expires
70
73
  as_time_from_epoch(attributes[:expires], granularity: :ms, allow_nil: :true)
71
74
  end
72
75
 
73
- # @!attribute [r] capability
76
+ # The capabilities associated with this Ably Token. The capabilities value is a JSON-encoded representation of the
77
+ # resource paths and associated operations. Read more about capabilities in the capabilities docs.
78
+ # @spec TD5
74
79
  # @return [Hash] Capabilities assigned to this token
75
80
  def capability
76
81
  if attributes.has_key?(:capability)
@@ -86,7 +91,10 @@ module Ably::Models
86
91
  end
87
92
  end
88
93
 
89
- # @!attribute [r] client_id
94
+ # The client ID, if any, bound to this Ably Token. If a client ID is included, then the Ably Token authenticates its
95
+ # bearer as that client ID, and the Ably Token may only be used to perform operations on behalf of that client ID.
96
+ # The client is then considered to be an identified client.
97
+ # @spec TD6
90
98
  # @return [String] Optional client ID assigned to this token
91
99
  def client_id
92
100
  attributes[:client_id]
@@ -113,8 +121,8 @@ module Ably::Models
113
121
  attributes.keys == [:token]
114
122
  end
115
123
 
116
- # @!attribute [r] attributes
117
124
  # @return [Hash] Access the token details Hash object ruby'fied to use symbolized keys
125
+ #
118
126
  def attributes
119
127
  @hash_object
120
128
  end
@@ -122,5 +130,19 @@ module Ably::Models
122
130
  def to_s
123
131
  "<TokenDetails token=#{token} client_id=#{client_id} key_name=#{key_name} issued=#{issued} expires=#{expires} capability=#{capability} expired?=#{expired?}>"
124
132
  end
133
+
134
+ # A static factory method to create a {Ably::Models::TokenDetails} object from a deserialized {Ably::Models::TokenDetails}-like
135
+ # object or a JSON stringified TokenDetails object. This method is provided to minimize bugs as a result of differing
136
+ # types by platform for fields such as timestamp or ttl. For example, in Ruby ttl in the {Ably::Models::TokenDetails}
137
+ # object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using to_json it
138
+ # is automatically converted to the Ably standard which is milliseconds. By using the fromJson() method when constructing
139
+ # a {Ably::Models::TokenDetails} object, Ably ensures that all fields are consistently serialized and deserialized across platforms.
140
+ #
141
+ # @overload from_json(json_like_object)
142
+ # @spec TD7
143
+ # @param json_like_object [Hash, String] A deserialized TokenDetails-like object or a JSON stringified TokenDetails object.
144
+ #
145
+ # @return [Ably::Models::TokenDetails] An Ably authentication token.
146
+ #
125
147
  end
126
148
  end
@@ -4,6 +4,7 @@ module Ably::Models
4
4
  # @param attributes (see #initialize)
5
5
  #
6
6
  # @return [TokenRequest]
7
+ #
7
8
  def self.TokenRequest(attributes)
8
9
  case attributes
9
10
  when TokenRequest
@@ -14,7 +15,8 @@ module Ably::Models
14
15
  end
15
16
 
16
17
 
17
- # TokenRequest is a class that stores the attributes of a token request
18
+ # Contains the properties of a request for a token to Ably.
19
+ # Tokens are generated using {Ably::Auth#requestToken}.
18
20
  #
19
21
  # Ruby {http://ruby-doc.org/core/Time.html Time} objects are supported in place of Ably ms since epoch time fields. However, if a numeric is provided
20
22
  # it must always be expressed in milliseconds as the Ably API always uses milliseconds for time fields.
@@ -39,13 +41,26 @@ module Ably::Models
39
41
  self.attributes.freeze
40
42
  end
41
43
 
44
+ # The name of the key against which this request is made. The key name is public, whereas the key secret is private.
45
+ #
42
46
  # @!attribute [r] key_name
47
+ #
48
+ # @spec TE2
49
+ #
43
50
  # @return [String] API key name of the key against which this request is made. An API key is made up of an API key name and secret delimited by a +:+
51
+ #
44
52
  def key_name
45
53
  attributes.fetch(:key_name) { raise Ably::Exceptions::InvalidTokenRequest, 'Key name is missing' }
46
54
  end
47
55
 
56
+ # Requested time to live for the Ably Token in milliseconds. If the Ably TokenRequest is successful, the TTL of the
57
+ # returned Ably Token is less than or equal to this value, depending on application settings and the attributes of
58
+ # the issuing key. The default is 60 minutes.
59
+ #
48
60
  # @!attribute [r] ttl
61
+ #
62
+ # @spec TE4
63
+ #
49
64
  # @return [Integer] requested time to live for the token in seconds. If the token request is successful,
50
65
  # the TTL of the returned token will be less than or equal to this value depending on application
51
66
  # settings and the attributes of the issuing key.
@@ -54,7 +69,15 @@ module Ably::Models
54
69
  attributes.fetch(:ttl) / 1000
55
70
  end
56
71
 
72
+ # Capability of the requested Ably Token. If the Ably TokenRequest is successful, the capability of the returned
73
+ # Ably Token will be the intersection of this capability with the capability of the issuing key. The capabilities
74
+ # value is a JSON-encoded representation of the resource paths and associated operations. Read more about
75
+ # capabilities in the capabilities docs.
76
+ #
57
77
  # @!attribute [r] capability
78
+ #
79
+ # @spec TE3
80
+ #
58
81
  # @return [Hash] capability of the token. If the token request is successful,
59
82
  # the capability of the returned token will be the intersection of
60
83
  # this capability with the capability of the issuing key.
@@ -71,14 +94,25 @@ module Ably::Models
71
94
  end
72
95
  end
73
96
 
97
+ # The client ID to associate with the requested Ably Token. When provided, the Ably Token may only be used to
98
+ # perform operations on behalf of that client ID.
99
+ #
74
100
  # @!attribute [r] client_id
101
+ #
102
+ # @spec TE2
103
+ #
75
104
  # @return [String] the client ID to associate with this token. The generated token
76
105
  # may be used to authenticate as this clientId.
77
106
  def client_id
78
107
  attributes[:client_id]
79
108
  end
80
109
 
110
+ # The timestamp of this request as milliseconds since the Unix epoch.
111
+ #
81
112
  # @!attribute [r] timestamp
113
+ #
114
+ # @spec TE5
115
+ #
82
116
  # @return [Time] the timestamp of this request.
83
117
  # Timestamps, in conjunction with the nonce, are used to prevent
84
118
  # token requests from being replayed.
@@ -88,7 +122,12 @@ module Ably::Models
88
122
  as_time_from_epoch(timestamp_val, granularity: :ms)
89
123
  end
90
124
 
125
+ # A cryptographically secure random string of at least 16 characters, used to ensure the TokenRequest cannot be reused.
126
+ #
91
127
  # @!attribute [r] nonce
128
+ #
129
+ # @spec TE2
130
+ #
92
131
  # @return [String] an opaque nonce string of at least 16 characters to ensure
93
132
  # uniqueness of this request. Any subsequent request using the
94
133
  # same nonce will be rejected.
@@ -96,14 +135,20 @@ module Ably::Models
96
135
  attributes.fetch(:nonce) { raise Ably::Exceptions::InvalidTokenRequest, 'Nonce is missing' }
97
136
  end
98
137
 
138
+ # The Message Authentication Code for this request.
139
+ #
99
140
  # @!attribute [r] mac
141
+ #
142
+ # @spec TE2
143
+ #
100
144
  # @return [String] the Message Authentication Code for this request. See the
101
- # {https://www.ably.com/docs Ably Authentication documentation} for more details.
145
+ #
102
146
  def mac
103
147
  attributes.fetch(:mac) { raise Ably::Exceptions::InvalidTokenRequest, 'MAC is missing' }
104
148
  end
105
149
 
106
150
  # Requests that the token is always persisted
151
+ #
107
152
  # @api private
108
153
  #
109
154
  def persisted
@@ -111,9 +156,25 @@ module Ably::Models
111
156
  end
112
157
 
113
158
  # @!attribute [r] attributes
159
+ #
114
160
  # @return [Hash] the token request Hash object ruby'fied to use symbolized keys
161
+ #
115
162
  def attributes
116
163
  @hash_object
117
164
  end
165
+
166
+ # A static factory method to create a TokenRequest object from a deserialized TokenRequest-like object or a JSON
167
+ # stringified TokenRequest object. This method is provided to minimize bugs as a result of differing types by platform
168
+ # for fields such as timestamp or ttl. For example, in Ruby ttl in the TokenRequest object is exposed in seconds as
169
+ # that is idiomatic for the language, yet when serialized to JSON using to_json it is automatically converted to
170
+ # the Ably standard which is milliseconds. By using the fromJson() method when constructing a TokenRequest object,
171
+ # Ably ensures that all fields are consistently serialized and deserialized across platforms.
172
+ #
173
+ # @overload from_json(json_like_object)
174
+ # @spec TE6
175
+ # @param json_like_object [Hash, String] A deserialized TokenRequest-like object or a JSON stringified TokenRequest object to create a TokenRequest.
176
+ #
177
+ # @return [Ably::Models::TokenRequest] An Ably token request object.
178
+ #
118
179
  end
119
180
  end
@@ -36,6 +36,7 @@ module Ably::Modules
36
36
  # Will yield the provided block in a new thread and return an {Ably::Util::SafeDeferrable}
37
37
  #
38
38
  # @yield [Object] operation block that is run in a thread
39
+ #
39
40
  # @return [Ably::Util::SafeDeferrable]
40
41
  #
41
42
  def async_wrap(success_callback = nil, custom_error_handling = nil)
@@ -90,7 +90,9 @@ module Ably::Modules
90
90
  end
91
91
 
92
92
  # Array of Enum values as symbols
93
+ #
93
94
  # @return [Array<Symbol>]
95
+ #
94
96
  def to_sym_arr
95
97
  @by_symbol.keys
96
98
  end
@@ -46,9 +46,12 @@ module Ably
46
46
 
47
47
  # On receiving an event matching the event_name, call the provided block
48
48
  #
49
+ # @spec RTE4
50
+ #
49
51
  # @param [Array<String>] event_names event name
50
52
  #
51
53
  # @return [void]
54
+ #
52
55
  def on(*event_names, &block)
53
56
  add_callback event_names, proc_for_block(block)
54
57
  end
@@ -62,9 +65,12 @@ module Ably
62
65
 
63
66
  # On receiving an event maching the event_name, call the provided block only once and remove the registered callback
64
67
  #
68
+ # @spec RTE4
69
+ #
65
70
  # @param [Array<String>] event_names event name
66
71
  #
67
72
  # @return [void]
73
+ #
68
74
  def once(*event_names, &block)
69
75
  add_callback event_names, proc_for_block(block, delete_once_run: true)
70
76
  end
@@ -76,7 +82,11 @@ module Ably
76
82
  add_callback event_names, proc_for_block(block, delete_once_run: true, unsafe: true)
77
83
  end
78
84
 
79
- # Emit an event with event_name that will in turn call all matching callbacks setup with `on`
85
+ # Emits an event, calling registered listeners with the given event name and any other given arguments.
86
+ # If an exception is raised in any of the listeners, the exception is caught by the EventEmitter and the exception is logged to the Ably logger.
87
+ #
88
+ # @spec RTE6
89
+ #
80
90
  def emit(event_name, *args)
81
91
  [callbacks_any, callbacks[callbacks_event_coerced(event_name)]].each do |callback_arr|
82
92
  callback_arr.clone.
@@ -97,9 +107,12 @@ module Ably
97
107
  # If a block is provided, only callbacks matching that block signature will be removed.
98
108
  # If block is not provided, all callbacks matching the event_name will be removed.
99
109
  #
110
+ # @spec RTE5
111
+ #
100
112
  # @param [Array<String>] event_names event name
101
113
  #
102
114
  # @return [void]
115
+ #
103
116
  def off(*event_names, &block)
104
117
  off_internal(false, *event_names, &block)
105
118
  end
@@ -15,6 +15,7 @@ module Ably::Modules
15
15
  # Provide a normal Hash accessor to the underlying raw message object
16
16
  #
17
17
  # @return [Object]
18
+ #
18
19
  def [](key)
19
20
  attributes[key]
20
21
  end
@@ -25,13 +26,17 @@ module Ably::Modules
25
26
  end
26
27
 
27
28
  # Return a JSON ready object from the underlying #attributes using Ably naming conventions for keys
29
+ #
28
30
  # @return [Hash]
31
+ #
29
32
  def as_json(*args)
30
33
  attributes.as_json.reject { |key, val| val.nil? }
31
34
  end
32
35
 
33
36
  # Stringify the JSON representation of this object from the underlying #attributes
37
+ #
34
38
  # @return [String]
39
+ #
35
40
  def to_json(*args)
36
41
  as_json.to_json(*args)
37
42
  end
@@ -35,6 +35,7 @@ module Ably::Modules
35
35
  # Current state {Ably::Modules::Enum}
36
36
  #
37
37
  # @return [Symbol] state
38
+ #
38
39
  def state
39
40
  STATE(@state)
40
41
  end
@@ -42,6 +43,7 @@ module Ably::Modules
42
43
  # Evaluates if check_state matches current state
43
44
  #
44
45
  # @return [Boolean]
46
+ #
45
47
  def state?(check_state)
46
48
  state == check_state
47
49
  end
@@ -20,6 +20,7 @@ module Ably::Modules
20
20
  # * log state change failures to {Logger}
21
21
  #
22
22
  # @return [void]
23
+ #
23
24
  def transition_state(state, *args)
24
25
  unless result = transition_to(state.to_sym, *args)
25
26
  exception = exception_for_state_change_to(state)
@@ -29,16 +30,19 @@ module Ably::Modules
29
30
  end
30
31
 
31
32
  # @return [Statesman History Object]
33
+ #
32
34
  def previous_transition
33
35
  history[-2]
34
36
  end
35
37
 
36
38
  # @return [Symbol]
39
+ #
37
40
  def previous_state
38
41
  previous_transition.to_state if previous_transition
39
42
  end
40
43
 
41
44
  # @return [Ably::Exceptions::InvalidStateChange]
45
+ #
42
46
  def exception_for_state_change_to(state)
43
47
  error_message = "#{self.class}: Unable to transition from #{current_state} => #{state}"
44
48
  Ably::Exceptions::InvalidStateChange.new(error_message, nil, Ably::Exceptions::Codes::CHANNEL_OPERATION_FAILED_INVALID_CHANNEL_STATE)