ably 1.2.2 → 1.2.3

Sign up to get free protection for your applications and to get access to all the features.
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
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 254c6088b3e3ef0d8cd6d2837b4efc73c2c7c04d8b7d4c61d416f023a8933603
4
- data.tar.gz: 91d7b17e533b41ede327696aff66dd97ea35d6f7cf2a9fee9fd467fa42e9041e
3
+ metadata.gz: 8c2ec62cdc84e7558147bdab0c6bf2cbb933d75b1298aafbdd78848c6ebf62b1
4
+ data.tar.gz: b7edf7e0643e1ff2ead0ec4af3aee1caf0863dab40d6b9e247dd0e1bcd56b0e6
5
5
  SHA512:
6
- metadata.gz: 8d51a067f02691481cf9489f82334f9200ef9ae00d71c2639c26a8d0b8fa62fbd76921fafb114699d4bf0d8e0f0e46f865bb07411a4dc4d6197a7ffeb9ebd6be
7
- data.tar.gz: a392f7f5ec08ab445aaad519e45dc841090950402516ef2bafe3863817af77536b85549701acfc52e4a171544b79a190b499b3f8d32552a9a08973bf60831c3d
6
+ metadata.gz: 77f961eaa1ecab40502a2b8a3ce193ab9448e5c3df675ee7212369a94252b314af55b54200f016317d48727d6df7a6526551a7e1090f8dfd4c56e6bc9e32a00a
7
+ data.tar.gz: 50df5abcdd20c6afc63c5ac71043fad7a07547c16c752356011cb0b0713666d429e79474190c346dfadb9d89afd4f774d8e9d899dc7bcf0e7a363dcf40af3a1b
@@ -0,0 +1,3 @@
1
+ --format documentation
2
+ --format RspecJunitFormatter
3
+ --out junit/<%= ENV['TEST_ENV_NUMBER'] %>_<%= ENV['TEST_TYPE'] %>_<%= ENV['PROTOCOL'] %>_ruby-<%= ENV['RUBY_VERSION'] %>.junit
@@ -26,14 +26,25 @@ jobs:
26
26
  PARALLEL_TEST_PROCESSORS: 2
27
27
  RSPEC_RETRY: true
28
28
  PROTOCOL: ${{ matrix.protocol }}
29
- run: bundle exec parallel_rspec --prefix-output-with-test-env-number -- --format documentation --format RspecJunitFormatter --out ${{ matrix.protocol }}-${{ matrix.type }}-ruby-${{ matrix.ruby }}.junit -- spec/${{ matrix.type }}
29
+ TEST_TYPE: ${{ matrix.type }}
30
+ RUBY_VERSION: ${{ matrix.ruby }}
31
+ run: |
32
+ cp .github/workflows/.rspec_parallel .rspec_parallel
33
+ mkdir junit
34
+ bundle exec parallel_rspec --prefix-output-with-test-env-number --first-is-1 -- spec/${{ matrix.type }}
35
+ - uses: actions/upload-artifact@v3
36
+ with:
37
+ path: |
38
+ junit/
39
+ coverage/
40
+ retention-days: 7
30
41
  - name: Upload test results
31
42
  if: always()
32
43
  uses: ably-labs/test-observability-action@main
33
44
  with:
34
45
  server-url: 'https://test-observability.herokuapp.com'
35
46
  server-auth: ${{ secrets.TEST_OBSERVABILITY_SERVER_AUTH_KEY }}
36
- path: '.'
47
+ path: 'junit/'
37
48
  - uses: coverallsapp/github-action@1.1.3
38
49
  with:
39
50
  github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -0,0 +1,36 @@
1
+ on:
2
+ pull_request:
3
+ push:
4
+ branches:
5
+ - main
6
+ jobs:
7
+ build:
8
+ runs-on: ubuntu-latest
9
+ permissions:
10
+ deployments: write
11
+ id-token: write
12
+ steps:
13
+ - uses: actions/checkout@v2
14
+
15
+ - uses: ruby/setup-ruby@v1
16
+ with:
17
+ ruby-version: '2.7'
18
+ bundler-cache: true
19
+
20
+ - name: Build Documentation
21
+ run: |
22
+ bundle exec yard --readme INTRO.md --tag "spec:Specification"
23
+ ls -al doc/
24
+ - name: Configure AWS Credentials
25
+ uses: aws-actions/configure-aws-credentials@v1
26
+ with:
27
+ aws-region: eu-west-2
28
+ role-to-assume: arn:aws:iam::${{ secrets.ABLY_AWS_ACCOUNT_ID_SDK }}:role/ably-sdk-builds-ably-ruby
29
+ role-session-name: "${{ github.run_id }}-${{ github.run_number }}"
30
+
31
+ - name: Upload Documentation
32
+ uses: ably/sdk-upload-action@v1
33
+ with:
34
+ sourcePath: doc/
35
+ githubToken: ${{ secrets.GITHUB_TOKEN }}
36
+ artifactName: docs
data/CHANGELOG.md CHANGED
@@ -1,5 +1,23 @@
1
1
  # Change Log
2
2
 
3
+ ## [v1.2.3](https://github.com/ably/ably-ruby/tree/v1.2.3)
4
+
5
+ [Full Changelog](https://github.com/ably/ably-ruby/compare/v1.2.2...v1.2.3)
6
+
7
+ **Implemented enhancements:**
8
+
9
+ - Add full docstring coverage to public API [\#376](https://github.com/ably/ably-ruby/pull/376) ([lukaszsliwa](https://github.com/lukaszsliwa))
10
+
11
+ **Fixed bugs:**
12
+
13
+ - Incorrect ProtocolMessage\#connection\_details object \(overwrites original connection\_details send on CONNECTED state\) [\#377](https://github.com/ably/ably-ruby/issues/377)
14
+
15
+ **Merged pull requests:**
16
+
17
+ - fix: remove inbound message size validation [\#382](https://github.com/ably/ably-ruby/pull/382) ([owenpearson](https://github.com/owenpearson))
18
+ - Changes related to docstring, generate docs and CI workflow [\#376](https://github.com/ably/ably-ruby/pull/376) ([lukaszsliwa](https://github.com/lukaszsliwa))
19
+ - Fix doc comment: incorrect channel.state type [\#375](https://github.com/ably/ably-ruby/pull/375) ([lukaszsliwa](https://github.com/lukaszsliwa))
20
+
3
21
  ## [v1.2.2](https://github.com/ably/ably-ruby/tree/v1.2.2)
4
22
 
5
23
  [Full Changelog](https://github.com/ably/ably-ruby/compare/v1.2.1...v1.2.2)
data/INTRO.md ADDED
@@ -0,0 +1,14 @@
1
+ # Ably `Ruby` Client Library SDK API Reference
2
+
3
+ The `Ruby` Client Library SDK supports a realtime and a REST interface.
4
+
5
+ The realtime interface enables a client to maintain a persistent connection to Ably and publish, subscribe and be present on channels.
6
+ The REST interface is stateless and typically implemented server-side. It is used to make requests such as retrieving statistics,
7
+ token authentication and publishing to a channel.
8
+
9
+ **Note**: The `Ruby` Client Library SDK implements the realtime and REST interfaces as two separate libraries.
10
+
11
+ The `Ruby` API references are generated from the [Ably `Ruby` Client Library SDK source code](https://github.com/ably/ably-ruby)
12
+ using [`yard`](https://yardoc.org/). View the [Ably docs](http://ably.com/docs/) for conceptual information on using Ably
13
+ and for client library API references split between the [realtime](http://ably.com/docs/api/realtime-sdk)
14
+ and [REST](http://ably.com/docs/api/rest-sdk) interfaces.
data/lib/ably/auth.rb CHANGED
@@ -5,24 +5,7 @@ require 'securerandom'
5
5
  require 'ably/rest/middleware/external_exceptions'
6
6
 
7
7
  module Ably
8
- # Auth is responsible for authentication with {https://www.ably.com Ably} using basic or token authentication
9
- #
10
- # Find out more about Ably authentication at: https://www.ably.com/docs/general/authentication/
11
- #
12
- # @!attribute [r] client_id
13
- # @return [String] The provided client ID, used for identifying this client for presence purposes
14
- # @!attribute [r] current_token_details
15
- # @return [Ably::Models::TokenDetails] Current {Ably::Models::TokenDetails} issued by this library or one of the provided callbacks used to authenticate requests
16
- # @!attribute [r] key
17
- # @return [String] Complete API key containing both the key name and key secret, if present
18
- # @!attribute [r] key_name
19
- # @return [String] Key name (public part of the API key), if present
20
- # @!attribute [r] key_secret
21
- # @return [String] Key secret (private secure part of the API key), if present
22
- # @!attribute [r] options
23
- # @return [Hash] Default {Ably::Auth} options configured for this client
24
- # @!attribute [r] token_params
25
- # @return [Hash] Default token params used for token requests, see {#request_token}
8
+ # Creates Ably {Ably::Models::TokenRequest} objects and obtains Ably Tokens from Ably to subsequently issue to less trusted clients.
26
9
  #
27
10
  class Auth
28
11
  include Ably::Modules::Conversions
@@ -124,9 +107,13 @@ module Ably
124
107
  @token_params.freeze
125
108
  end
126
109
 
127
- # Ensures valid auth credentials are present for the library instance. This may rely on an already-known and valid token, and will obtain a new token if necessary.
110
+ # Instructs the library to get a new token immediately. When using the realtime client, it upgrades the current
111
+ # realtime connection to use the new token, or if not connected, initiates a connection to Ably, once the new token
112
+ # has been obtained. Also stores any `token_params` and `auth_options` passed
113
+ # in as the new defaults, to be used for all subsequent implicit or explicit token requests. Any `token_params`
114
+ # and `auth_options` objects passed in entirely replace, as opposed to being merged with, the current client library saved values.
128
115
  #
129
- # In the event that a new token request is made, the provided options are used.
116
+ # @spec RSA10
130
117
  #
131
118
  # @param [Hash, nil] token_params the token params used for future token requests. When nil, previously configured token params are used
132
119
  # @param [Hash, nil] auth_options the authentication options used for future token requests. When nil, previously configure authentication options are used
@@ -205,7 +192,13 @@ module Ably
205
192
  authorize(*args, &block)
206
193
  end
207
194
 
208
- # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
195
+ # Calls the requestToken REST API endpoint to obtain an Ably Token according to the specified `token_params` and `auth_options`.
196
+ # Both `token_params` and `auth_options` are optional. When omitted or null, the default token parameters and authentication
197
+ # options for the client library are used, as specified in the `client_options` when the client library was instantiated,
198
+ # or later updated with an explicit authorize request. Values passed in are used instead of, rather than being merged with, the default values.
199
+ # To understand why an Ably {Ably::Models::TokenRequest} may be issued to clients in favor of a token, see Token Authentication explained.
200
+ #
201
+ # @spec RSA8e
209
202
  #
210
203
  # @param [Hash] auth_options (see #create_token_request)
211
204
  # @option auth_options [String] :auth_url a URL to be used to GET or POST a set of token request params, to obtain a signed token request
@@ -217,7 +210,7 @@ module Ably
217
210
  # @param [Hash] token_params (see #create_token_request)
218
211
  # @option (see #create_token_request)
219
212
  #
220
- # @return [Ably::Models::TokenDetails]
213
+ # @return [Ably::Models::TokenDetails] A {Ably::Models::TokenDetails} object. RSA16
221
214
  #
222
215
  # @example
223
216
  # # simple token request using basic auth
@@ -273,7 +266,17 @@ module Ably
273
266
  send_token_request(token_request)
274
267
  end
275
268
 
276
- # Creates and signs a token request that can then subsequently be used by any client to request a token
269
+ # Creates and signs an {Ably::Models::TokenRequest} based on the specified (or if none specified, the client
270
+ # library stored) `token_params` and `auth_options`. Note this can only be used when the API key value is available
271
+ # locally. Otherwise, the {Ably::Models::TokenRequest} must be obtained from the key owner. Use this to generate
272
+ # an {Ably::Models::TokenRequest} in order to implement an Ably Token request callback for use by other clients.
273
+ # Both `token_params` and `auth_options` are optional. When omitted or null, the default token parameters
274
+ # and authentication options for the client library are used, as specified in the `client_options` when the client
275
+ # library was instantiated, or later updated with an explicit authorize request. Values passed in are used instead
276
+ # of, rather than being merged with, the default values. To understand why an {Ably::Models::TokenRequest} may be
277
+ # issued to clients in favor of a token, see Token Authentication explained.
278
+ #
279
+ # @spec RSA9
277
280
  #
278
281
  # @param [Hash] token_params the token params used in the token request
279
282
  # @option token_params [String] :client_id A client ID to associate with this token. The generated token may be used to authenticate as this +client_id+
@@ -4,6 +4,7 @@ module Ably::Models
4
4
  # @param attributes (see #initialize)
5
5
  #
6
6
  # @return [AuthDetails]
7
+ #
7
8
  def self.AuthDetails(attributes)
8
9
  case attributes
9
10
  when AuthDetails
@@ -27,14 +28,16 @@ module Ably::Models
27
28
  self.attributes.freeze
28
29
  end
29
30
 
30
- %w(access_token).each do |attribute|
31
- define_method attribute do
32
- attributes[attribute.to_sym]
33
- end
31
+ # The authentication token string.
32
+ #
33
+ # @spec AD2
34
+ #
35
+ # @return [String]
36
+ #
37
+ def access_token
38
+ attributes[:access_token]
34
39
  end
35
40
 
36
- # @!attribute [r] attributes
37
- # @return [Hash] Access the token details Hash object ruby'fied to use symbolized keys
38
41
  def attributes
39
42
  @hash_object
40
43
  end
@@ -4,6 +4,7 @@ module Ably::Models
4
4
  # @param attributes (see #initialize)
5
5
  #
6
6
  # @return [ChannelDetails]
7
+ #
7
8
  def self.ChannelDetails(attributes)
8
9
  case attributes
9
10
  when ChannelDetails
@@ -13,14 +14,17 @@ module Ably::Models
13
14
  end
14
15
  end
15
16
 
16
- # ChannelDetails is a type that represents information for a channel including channelId, name, status and occupancy (CHD1)
17
+ # Contains the details of a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel} object
18
+ # such as its ID and {Ably::Models::ChannelStatus}.
17
19
  #
18
20
  class ChannelDetails
19
21
  extend Ably::Modules::Enum
20
22
  extend Forwardable
21
23
  include Ably::Modules::ModelCommon
22
24
 
23
- # The attributes of ChannelDetails (CHD2)
25
+ # The attributes of ChannelDetails
26
+ #
27
+ # @spec CHD2
24
28
  #
25
29
  attr_reader :attributes
26
30
 
@@ -32,7 +36,9 @@ module Ably::Models
32
36
  @attributes = IdiomaticRubyWrapper(attrs.clone)
33
37
  end
34
38
 
35
- # The identifier of the channel (CHD2a)
39
+ # The identifier of the channel
40
+ #
41
+ # @spec CHD2a
36
42
  #
37
43
  # @return [String]
38
44
  #
@@ -40,7 +46,9 @@ module Ably::Models
40
46
  attributes[:channel_id]
41
47
  end
42
48
 
43
- # The identifier of the channel (CHD2a)
49
+ # The identifier of the channel
50
+ #
51
+ # @spec CHD2a
44
52
  #
45
53
  # @return [String]
46
54
  #
@@ -48,7 +56,9 @@ module Ably::Models
48
56
  attributes[:name]
49
57
  end
50
58
 
51
- # The status of the channel (CHD2b)
59
+ # A {Ably::Models::ChannelStatus} object.
60
+ #
61
+ # @spec CHD2b
52
62
  #
53
63
  # @return [Ably::Models::ChannelStatus, nil]
54
64
  #
@@ -4,6 +4,7 @@ module Ably::Models
4
4
  # @param attributes (see #initialize)
5
5
  #
6
6
  # @return [ChannelMetrics]
7
+ #
7
8
  def self.ChannelMetrics(attributes)
8
9
  case attributes
9
10
  when ChannelMetrics
@@ -13,8 +14,10 @@ module Ably::Models
13
14
  end
14
15
  end
15
16
 
16
- # ChannelMetrics is a type that contains the count of publishers and subscribers, connections and presenceConnections,
17
- # presenceMembers and presenceSubscribers (CHM1)
17
+ # Contains the metrics associated with a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel},
18
+ # such as the number of publishers, subscribers and connections it has.
19
+ #
20
+ # @spec CHM1
18
21
  #
19
22
  class ChannelMetrics
20
23
  extend Ably::Modules::Enum
@@ -33,7 +36,9 @@ module Ably::Models
33
36
  @attributes = IdiomaticRubyWrapper(attrs.clone)
34
37
  end
35
38
 
36
- # The total number of connections to the channel (CHM2a)
39
+ # The number of realtime connections attached to the channel.
40
+ #
41
+ # @spec CHM2a
37
42
  #
38
43
  # @return [Integer]
39
44
  #
@@ -41,7 +46,11 @@ module Ably::Models
41
46
  attributes[:connections]
42
47
  end
43
48
 
44
- # The total number of presence connections to the channel (CHM2b)
49
+ # The number of realtime connections attached to the channel with permission to enter the presence set, regardless
50
+ # of whether or not they have entered it. This requires the presence capability and for a client to not have specified
51
+ # a {Ably::Models::ChannelOptions::MODES} flag that excludes {Ably::Models::ChannelOptions::MODES}#PRESENCE.
52
+ #
53
+ # @spec CHM2b
45
54
  #
46
55
  # @return [Integer]
47
56
  #
@@ -49,7 +58,9 @@ module Ably::Models
49
58
  attributes[:presence_connections]
50
59
  end
51
60
 
52
- # The total number of presence members for the channel (CHM2c)
61
+ # The number of members in the presence set of the channel.
62
+ #
63
+ # @spec CHM2c
53
64
  #
54
65
  # @return [Integer]
55
66
  #
@@ -57,7 +68,11 @@ module Ably::Models
57
68
  attributes[:presence_members]
58
69
  end
59
70
 
60
- # The total number of presence subscribers for the channel (CHM2d)
71
+ # The number of realtime attachments receiving presence messages on the channel. This requires the subscribe capability
72
+ # and for a client to not have specified a {Ably::Models::ChannelOptions::MODES} flag that excludes
73
+ # {Ably::Models::ChannelOptions::MODES}#PRESENCE_SUBSCRIBE.
74
+ #
75
+ # @spec CHM2d
61
76
  #
62
77
  # @return [Integer]
63
78
  #
@@ -65,7 +80,11 @@ module Ably::Models
65
80
  attributes[:presence_subscribers]
66
81
  end
67
82
 
68
- # The total number of publishers to the channel (CHM2e)
83
+ # The number of realtime attachments permitted to publish messages to the channel. This requires the publish
84
+ # capability and for a client to not have specified a {Ably::Models::ChannelOptions::MODES} flag that excludes
85
+ # {Ably::Models::ChannelOptions::MODES}#PUBLISH.
86
+ #
87
+ # @spec CHM2e
69
88
  #
70
89
  # @return [Integer]
71
90
  #
@@ -73,7 +92,11 @@ module Ably::Models
73
92
  attributes[:publishers]
74
93
  end
75
94
 
76
- # The total number of subscribers to the channel (CHM2f)
95
+ # The number of realtime attachments receiving messages on the channel. This requires the subscribe capability and
96
+ # for a client to not have specified a {Ably::Models::ChannelOptions::MODES} flag that excludes
97
+ # {Ably::Models::ChannelOptions::MODES}#SUBSCRIBE.
98
+ #
99
+ # @spec CHM2f
77
100
  #
78
101
  # @return [Integer]
79
102
  #
@@ -4,6 +4,7 @@ module Ably::Models
4
4
  # @param attributes (see #initialize)
5
5
  #
6
6
  # @return [ChannelOccupancy]
7
+ #
7
8
  def self.ChannelOccupancy(attributes)
8
9
  case attributes
9
10
  when ChannelOccupancy
@@ -13,14 +14,18 @@ module Ably::Models
13
14
  end
14
15
  end
15
16
 
16
- # Type that contain channel metrics (CHO1)
17
+ # Contains the metrics of a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel} object.
18
+ #
19
+ # @spec CHO1
17
20
  #
18
21
  class ChannelOccupancy
19
22
  extend Ably::Modules::Enum
20
23
  extend Forwardable
21
24
  include Ably::Modules::ModelCommon
22
25
 
23
- # The attributes of ChannelOccupancy (CH02)
26
+ # The attributes of ChannelOccupancy.
27
+ #
28
+ # @spec CH02
24
29
  #
25
30
  attr_reader :attributes
26
31
 
@@ -32,7 +37,9 @@ module Ably::Models
32
37
  @attributes = IdiomaticRubyWrapper(attrs.clone)
33
38
  end
34
39
 
35
- # Metrics object (CHO2a)
40
+ # A {Ably::Models::ChannelMetrics} object.
41
+ #
42
+ # @spec CHO2a
36
43
  #
37
44
  # @return [Ably::Models::ChannelMetrics, nil]
38
45
  #
@@ -4,6 +4,7 @@ module Ably::Models
4
4
  # @param attributes (see #initialize)
5
5
  #
6
6
  # @return [ChannelOptions]
7
+ #
7
8
  def self.ChannelOptions(attributes)
8
9
  case attributes
9
10
  when ChannelOptions
@@ -19,6 +20,15 @@ module Ably::Models
19
20
  extend Forwardable
20
21
  include Ably::Modules::ModelCommon
21
22
 
23
+ # Describes the possible flags used to configure client capabilities, using {Ably::Models::ChannelOptions::MODES}.
24
+ #
25
+ # PRESENCE The client can enter the presence set.
26
+ # PUBLISH The client can publish messages.
27
+ # SUBSCRIBE The client can subscribe to messages.
28
+ # PRESENCE_SUBSCRIBE The client can receive presence messages.
29
+ #
30
+ # @spec TB2d
31
+ #
22
32
  MODES = ruby_enum('MODES',
23
33
  presence: 0,
24
34
  publish: 1,
@@ -33,6 +43,8 @@ module Ably::Models
33
43
  def_delegators :attributes, :fetch, :size, :empty?
34
44
  # Initialize a new ChannelOptions
35
45
  #
46
+ # @spec TB3
47
+ #
36
48
  # @option params [Hash] (TB2c) params (for realtime client libraries only) a of key/value pairs
37
49
  # @option modes [Hash] modes (for realtime client libraries only) an array of ChannelMode
38
50
  # @option cipher [Hash,Ably::Models::CipherParams] :cipher A hash of options or a {Ably::Models::CipherParams} to configure the encryption. *:key* is required, all other options are optional.
@@ -45,23 +57,33 @@ module Ably::Models
45
57
  attributes.clone
46
58
  end
47
59
 
48
- # @!attribute cipher
60
+ # Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm,
61
+ # chaining mode, key length and key). See an example.
62
+ #
63
+ # @spec RSL5a, TB2b
49
64
  #
50
65
  # @return [CipherParams]
66
+ #
51
67
  def cipher
52
68
  attributes[:cipher]
53
69
  end
54
70
 
55
- # @!attribute params
71
+ # Channel Parameters that configure the behavior of the channel.
72
+ #
73
+ # @spec TB2c
56
74
  #
57
75
  # @return [Hash]
76
+ #
58
77
  def params
59
78
  attributes[:params].to_h
60
79
  end
61
80
 
62
- # @!attribute modes
81
+ # An array of {Ably:Models:ChannelOptions::MODES} objects.
82
+ #
83
+ # @spec TB2d
63
84
  #
64
85
  # @return [Array<ChannelOptions::MODES>]
86
+ #
65
87
  def modes
66
88
  attributes[:modes]
67
89
  end
@@ -69,6 +91,7 @@ module Ably::Models
69
91
  # Converts modes to a bitfield that coresponds to ProtocolMessage#flags
70
92
  #
71
93
  # @return [Integer]
94
+ #
72
95
  def modes_to_flags
73
96
  modes.map { |mode| Ably::Models::ProtocolMessage::ATTACH_FLAGS_MAPPING[mode.to_sym] }.reduce(:|)
74
97
  end
@@ -1,15 +1,5 @@
1
1
  module Ably::Models
2
- # ChannelStateChange is a class that is emitted by the {Ably::Realtime::Channel} object
3
- # when a state change occurs
4
- #
5
- # @!attribute [r] current
6
- # @return [Connection::STATE] Current channel state
7
- # @!attribute [r] previous
8
- # @return [Connection::STATE] Previous channel state
9
- # @!attribute [r] reason
10
- # @return [Ably::Models::ErrorInfo] Object describing the reason for a state change when not initiated by the consumer of the client library
11
- # @!attribute [r] resumed
12
- # @return [Boolean] True when a channel is resumed, false when continuity on the channel is no longer provided indicating that the developer is now responsible for recovering lost messages on this channel through other means, such as using the hisory API
2
+ # Contains state change information emitted by {Ably::Rest::Channel} and {Ably::Realtime::Channel} objects.
13
3
  #
14
4
  class ChannelStateChange
15
5
  include Ably::Modules::ModelCommon
@@ -31,12 +21,52 @@ module Ably::Models
31
21
  raise ArgumentError, e
32
22
  end
33
23
 
34
- %w(current previous event reason).each do |attribute|
35
- define_method attribute do
36
- @hash_object[attribute.to_sym]
37
- end
24
+ # The new current {Ably::Realtime::Channel::STATE}.
25
+ #
26
+ # @spec RTL2a, RTL2b
27
+ #
28
+ # @return [Ably::Realtime::Channel::STATE]
29
+ #
30
+ def current
31
+ @hash_object[:current]
32
+ end
33
+
34
+ # The previous state. For the {Ably::Realtime::Channel::EVENT}(:update) event, this is equal to the current {Ably::Realtime::Channel::STATE}.
35
+ #
36
+ # @spec RTL2a, RTL2b
37
+ #
38
+ # @return [Ably::Realtime::Channel::EVENT]
39
+ #
40
+ def previous
41
+ @hash_object[:previous]
42
+ end
43
+
44
+ # The event that triggered this {Ably::Realtime::Channel::STATE} change.
45
+ #
46
+ # @spec TH5
47
+ #
48
+ # @return [Ably::Realtime::Channel::STATE]
49
+ #
50
+ def event
51
+ @hash_object[:event]
52
+ end
53
+
54
+ # An {Ably::Models::ErrorInfo} object containing any information relating to the transition.
55
+ #
56
+ # @spec RTL2e, TH3
57
+ #
58
+ # @return [Ably::Models::ErrorInfo, nil]
59
+ #
60
+ def reason
61
+ @hash_object[:reason]
38
62
  end
39
63
 
64
+ # Indicates whether message continuity on this channel is preserved, see Nonfatal channel errors for more info.
65
+ #
66
+ # @spec RTL2f, TH4
67
+ #
68
+ # @return [Boolean]
69
+ #
40
70
  def resumed
41
71
  !!@hash_object[:resumed]
42
72
  end
@@ -4,6 +4,7 @@ module Ably::Models
4
4
  # @param attributes (see #initialize)
5
5
  #
6
6
  # @return [ChannelStatus]
7
+ #
7
8
  def self.ChannelStatus(attributes)
8
9
  case attributes
9
10
  when ChannelStatus
@@ -13,14 +14,19 @@ module Ably::Models
13
14
  end
14
15
  end
15
16
 
16
- # ChannelStatus is a type that contains status and occupancy for a channel (CHS1)
17
+ # Contains the status of a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel} object
18
+ # such as whether it is active and its {Ably::Models::ChannelOccupancy}.
19
+ #
20
+ # @spec CHS1
17
21
  #
18
22
  class ChannelStatus
19
23
  extend Ably::Modules::Enum
20
24
  extend Forwardable
21
25
  include Ably::Modules::ModelCommon
22
26
 
23
- # The attributes of ChannelStatus (CHS2)
27
+ # The attributes of ChannelStatus
28
+ #
29
+ # @spec CHS2
24
30
  #
25
31
  attr_reader :attributes
26
32
 
@@ -32,7 +38,9 @@ module Ably::Models
32
38
  @attributes = IdiomaticRubyWrapper(attrs.clone)
33
39
  end
34
40
 
35
- # Represents if the channel is active (CHS2a)
41
+ # If true, the channel is active, otherwise false.
42
+ #
43
+ # @spec CHS2a
36
44
  #
37
45
  # @return [Boolean]
38
46
  #
@@ -42,7 +50,9 @@ module Ably::Models
42
50
  alias_method :active?, :is_active
43
51
  alias_method :is_active?, :is_active
44
52
 
45
- # Occupancy ChannelOccupancy – occupancy is an object containing the metrics for the channel (CHS2b)
53
+ # A {Ably::Models::ChannelOccupancy} object.
54
+ #
55
+ # @spec CHS2b
46
56
  #
47
57
  # @return [Ably::Models::ChannelOccupancy, nil]
48
58
  #