ably 1.2.1 → 1.2.3

Sign up to get free protection for your applications and to get access to all the features.
Files changed (73) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/.rspec_parallel +3 -0
  3. data/.github/workflows/check.yml +24 -4
  4. data/.github/workflows/docs.yml +36 -0
  5. data/CHANGELOG.md +26 -0
  6. data/INTRO.md +14 -0
  7. data/ably.gemspec +1 -0
  8. data/lib/ably/auth.rb +26 -23
  9. data/lib/ably/models/auth_details.rb +9 -6
  10. data/lib/ably/models/channel_details.rb +69 -0
  11. data/lib/ably/models/channel_metrics.rb +107 -0
  12. data/lib/ably/models/channel_occupancy.rb +50 -0
  13. data/lib/ably/models/channel_options.rb +26 -3
  14. data/lib/ably/models/channel_state_change.rb +45 -15
  15. data/lib/ably/models/channel_status.rb +63 -0
  16. data/lib/ably/models/cipher_params.rb +36 -13
  17. data/lib/ably/models/connection_details.rb +91 -10
  18. data/lib/ably/models/connection_state_change.rb +54 -15
  19. data/lib/ably/models/delta_extras.rb +6 -7
  20. data/lib/ably/models/device_details.rb +60 -21
  21. data/lib/ably/models/device_push_details.rb +27 -19
  22. data/lib/ably/models/error_info.rb +59 -17
  23. data/lib/ably/models/http_paginated_response.rb +27 -5
  24. data/lib/ably/models/idiomatic_ruby_wrapper.rb +3 -2
  25. data/lib/ably/models/message.rb +64 -24
  26. data/lib/ably/models/message_encoders/base.rb +6 -0
  27. data/lib/ably/models/paginated_result.rb +29 -14
  28. data/lib/ably/models/presence_message.rb +72 -22
  29. data/lib/ably/models/protocol_message.rb +0 -4
  30. data/lib/ably/models/push_channel_subscription.rb +40 -15
  31. data/lib/ably/models/stats.rb +76 -40
  32. data/lib/ably/models/stats_types.rb +16 -40
  33. data/lib/ably/models/token_details.rb +34 -12
  34. data/lib/ably/models/token_request.rb +63 -2
  35. data/lib/ably/modules/async_wrapper.rb +1 -0
  36. data/lib/ably/modules/enum.rb +2 -0
  37. data/lib/ably/modules/event_emitter.rb +14 -1
  38. data/lib/ably/modules/model_common.rb +5 -0
  39. data/lib/ably/modules/state_emitter.rb +2 -0
  40. data/lib/ably/modules/state_machine.rb +4 -0
  41. data/lib/ably/realtime/channel/channel_properties.rb +9 -2
  42. data/lib/ably/realtime/channel/publisher.rb +2 -0
  43. data/lib/ably/realtime/channel/push_channel.rb +17 -10
  44. data/lib/ably/realtime/channel.rb +79 -42
  45. data/lib/ably/realtime/channels.rb +4 -3
  46. data/lib/ably/realtime/client/incoming_message_dispatcher.rb +6 -14
  47. data/lib/ably/realtime/client.rb +53 -32
  48. data/lib/ably/realtime/connection/connection_manager.rb +4 -0
  49. data/lib/ably/realtime/connection/websocket_transport.rb +4 -2
  50. data/lib/ably/realtime/connection.rb +94 -55
  51. data/lib/ably/realtime/presence.rb +61 -36
  52. data/lib/ably/realtime/push/admin.rb +16 -2
  53. data/lib/ably/realtime/push.rb +15 -3
  54. data/lib/ably/rest/channel/push_channel.rb +0 -3
  55. data/lib/ably/rest/channel.rb +33 -18
  56. data/lib/ably/rest/channels.rb +6 -3
  57. data/lib/ably/rest/client.rb +41 -35
  58. data/lib/ably/rest/presence.rb +27 -12
  59. data/lib/ably/rest/push/admin.rb +4 -0
  60. data/lib/ably/rest/push/device_registrations.rb +13 -2
  61. data/lib/ably/rest/push.rb +2 -0
  62. data/lib/ably/util/crypto.rb +14 -10
  63. data/lib/ably/version.rb +1 -1
  64. data/spec/acceptance/realtime/connection_spec.rb +0 -15
  65. data/spec/acceptance/realtime/message_spec.rb +3 -3
  66. data/spec/acceptance/rest/channel_spec.rb +18 -0
  67. data/spec/unit/models/channel_details_spec.rb +30 -0
  68. data/spec/unit/models/channel_metrics_spec.rb +42 -0
  69. data/spec/unit/models/channel_occupancy_spec.rb +17 -0
  70. data/spec/unit/models/channel_status_spec.rb +36 -0
  71. data/spec/unit/models/protocol_message_spec.rb +0 -26
  72. data/spec/unit/realtime/incoming_message_dispatcher_spec.rb +0 -38
  73. metadata +32 -3
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 6d535fd596cbed132fc9c540fb46997c5fcaafeae4b4531ab6fbe02dba33178f
4
- data.tar.gz: 1792b4e4f47d7044d0a937d3b75f9e3b9d9f1d6a436a36bfde2f9e65ae3f2552
3
+ metadata.gz: 8c2ec62cdc84e7558147bdab0c6bf2cbb933d75b1298aafbdd78848c6ebf62b1
4
+ data.tar.gz: b7edf7e0643e1ff2ead0ec4af3aee1caf0863dab40d6b9e247dd0e1bcd56b0e6
5
5
  SHA512:
6
- metadata.gz: fad634a453ebbb3d1b05ad13fa7c3683e794635862267376920aa7d43e93afeab7c5ba06398609e048d7f421f8d10f80f9866828f07468e153be843f6b38a136
7
- data.tar.gz: 1d76ae8ffe50a043b82fbb553af787a2a49665909d802f6471644e9614d81677d04c38926cb34890a2daeef2d498cabe7c39817c40fbb8d1be88070d2d103669
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
@@ -12,6 +12,7 @@ jobs:
12
12
  matrix:
13
13
  ruby: [ '2.7', '3.0', '3.1' ]
14
14
  protocol: [ 'json', 'msgpack' ]
15
+ type: [ 'unit', 'acceptance' ]
15
16
  steps:
16
17
  - uses: actions/checkout@v2
17
18
  with:
@@ -20,15 +21,34 @@ jobs:
20
21
  with:
21
22
  ruby-version: ${{ matrix.ruby }}
22
23
  bundler-cache: true
23
- - env:
24
- RSPEC_RETRY: true
24
+ - name: 'Run ${{ matrix.type }} tests on ruby ${{ matrix.ruby }} (${{ matrix.protocol }} protocol)'
25
+ env:
25
26
  PARALLEL_TEST_PROCESSORS: 2
27
+ RSPEC_RETRY: true
26
28
  PROTOCOL: ${{ matrix.protocol }}
27
- run: ./spec/run_parallel_tests
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
41
+ - name: Upload test results
42
+ if: always()
43
+ uses: ably-labs/test-observability-action@main
44
+ with:
45
+ server-url: 'https://test-observability.herokuapp.com'
46
+ server-auth: ${{ secrets.TEST_OBSERVABILITY_SERVER_AUTH_KEY }}
47
+ path: 'junit/'
28
48
  - uses: coverallsapp/github-action@1.1.3
29
49
  with:
30
50
  github-token: ${{ secrets.GITHUB_TOKEN }}
31
- flag-name: run-ruby_${{ matrix.ruby }}-${{ matrix.protocol }}_protocol
51
+ flag-name: ruby-${{ matrix.ruby }}-${{ matrix.protocol }}-${{ matrix.type }}
32
52
  parallel: true
33
53
  finish:
34
54
  needs: check
@@ -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,31 @@
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
+
21
+ ## [v1.2.2](https://github.com/ably/ably-ruby/tree/v1.2.2)
22
+
23
+ [Full Changelog](https://github.com/ably/ably-ruby/compare/v1.2.1...v1.2.2)
24
+
25
+ **Implemented enhancements:**
26
+
27
+ - Add support to get channel lifecycle status [\#362](https://github.com/ably/ably-ruby/issues/362)
28
+
3
29
  ## [v1.2.1](https://github.com/ably/ably-ruby/tree/v1.2.1)
4
30
 
5
31
  [Full Changelog](https://github.com/ably/ably-ruby/compare/v1.2.0...v1.2.1)
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/ably.gemspec CHANGED
@@ -32,6 +32,7 @@ Gem::Specification.new do |spec|
32
32
  spec.add_development_dependency 'rake', '~> 13.0'
33
33
  spec.add_development_dependency 'redcarpet', '~> 3.3'
34
34
  spec.add_development_dependency 'rspec', '~> 3.11.0'
35
+ spec.add_development_dependency 'rspec_junit_formatter', '~> 0.5.1'
35
36
  spec.add_development_dependency 'rspec-retry', '~> 0.6'
36
37
  spec.add_development_dependency 'yard', '~> 0.9'
37
38
  spec.add_development_dependency 'rspec-instafail', '~> 1.0'
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
@@ -0,0 +1,69 @@
1
+ module Ably::Models
2
+ # Convert token details argument to a {ChannelDetails} object
3
+ #
4
+ # @param attributes (see #initialize)
5
+ #
6
+ # @return [ChannelDetails]
7
+ #
8
+ def self.ChannelDetails(attributes)
9
+ case attributes
10
+ when ChannelDetails
11
+ return attributes
12
+ else
13
+ ChannelDetails.new(attributes)
14
+ end
15
+ end
16
+
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}.
19
+ #
20
+ class ChannelDetails
21
+ extend Ably::Modules::Enum
22
+ extend Forwardable
23
+ include Ably::Modules::ModelCommon
24
+
25
+ # The attributes of ChannelDetails
26
+ #
27
+ # @spec CHD2
28
+ #
29
+ attr_reader :attributes
30
+
31
+ alias_method :to_h, :attributes
32
+
33
+ # Initialize a new ChannelDetails
34
+ #
35
+ def initialize(attrs)
36
+ @attributes = IdiomaticRubyWrapper(attrs.clone)
37
+ end
38
+
39
+ # The identifier of the channel
40
+ #
41
+ # @spec CHD2a
42
+ #
43
+ # @return [String]
44
+ #
45
+ def channel_id
46
+ attributes[:channel_id]
47
+ end
48
+
49
+ # The identifier of the channel
50
+ #
51
+ # @spec CHD2a
52
+ #
53
+ # @return [String]
54
+ #
55
+ def name
56
+ attributes[:name]
57
+ end
58
+
59
+ # A {Ably::Models::ChannelStatus} object.
60
+ #
61
+ # @spec CHD2b
62
+ #
63
+ # @return [Ably::Models::ChannelStatus, nil]
64
+ #
65
+ def status
66
+ Ably::Models::ChannelStatus(attributes[:status])
67
+ end
68
+ end
69
+ end
@@ -0,0 +1,107 @@
1
+ module Ably::Models
2
+ # Convert token details argument to a {ChannelMetrics} object
3
+ #
4
+ # @param attributes (see #initialize)
5
+ #
6
+ # @return [ChannelMetrics]
7
+ #
8
+ def self.ChannelMetrics(attributes)
9
+ case attributes
10
+ when ChannelMetrics
11
+ return attributes
12
+ else
13
+ ChannelMetrics.new(attributes)
14
+ end
15
+ end
16
+
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
21
+ #
22
+ class ChannelMetrics
23
+ extend Ably::Modules::Enum
24
+ extend Forwardable
25
+ include Ably::Modules::ModelCommon
26
+
27
+ # The attributes of ChannelMetrics (CHM2)
28
+ #
29
+ attr_reader :attributes
30
+
31
+ alias_method :to_h, :attributes
32
+
33
+ # Initialize a new ChannelMetrics
34
+ #
35
+ def initialize(attrs)
36
+ @attributes = IdiomaticRubyWrapper(attrs.clone)
37
+ end
38
+
39
+ # The number of realtime connections attached to the channel.
40
+ #
41
+ # @spec CHM2a
42
+ #
43
+ # @return [Integer]
44
+ #
45
+ def connections
46
+ attributes[:connections]
47
+ end
48
+
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
54
+ #
55
+ # @return [Integer]
56
+ #
57
+ def presence_connections
58
+ attributes[:presence_connections]
59
+ end
60
+
61
+ # The number of members in the presence set of the channel.
62
+ #
63
+ # @spec CHM2c
64
+ #
65
+ # @return [Integer]
66
+ #
67
+ def presence_members
68
+ attributes[:presence_members]
69
+ end
70
+
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
76
+ #
77
+ # @return [Integer]
78
+ #
79
+ def presence_subscribers
80
+ attributes[:presence_subscribers]
81
+ end
82
+
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
88
+ #
89
+ # @return [Integer]
90
+ #
91
+ def publishers
92
+ attributes[:publishers]
93
+ end
94
+
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
100
+ #
101
+ # @return [Integer]
102
+ #
103
+ def subscribers
104
+ attributes[:subscribers]
105
+ end
106
+ end
107
+ end
@@ -0,0 +1,50 @@
1
+ module Ably::Models
2
+ # Convert token details argument to a {ChannelOccupancy} object
3
+ #
4
+ # @param attributes (see #initialize)
5
+ #
6
+ # @return [ChannelOccupancy]
7
+ #
8
+ def self.ChannelOccupancy(attributes)
9
+ case attributes
10
+ when ChannelOccupancy
11
+ return attributes
12
+ else
13
+ ChannelOccupancy.new(attributes)
14
+ end
15
+ end
16
+
17
+ # Contains the metrics of a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel} object.
18
+ #
19
+ # @spec CHO1
20
+ #
21
+ class ChannelOccupancy
22
+ extend Ably::Modules::Enum
23
+ extend Forwardable
24
+ include Ably::Modules::ModelCommon
25
+
26
+ # The attributes of ChannelOccupancy.
27
+ #
28
+ # @spec CH02
29
+ #
30
+ attr_reader :attributes
31
+
32
+ alias_method :to_h, :attributes
33
+
34
+ # Initialize a new ChannelOccupancy
35
+ #
36
+ def initialize(attrs)
37
+ @attributes = IdiomaticRubyWrapper(attrs.clone)
38
+ end
39
+
40
+ # A {Ably::Models::ChannelMetrics} object.
41
+ #
42
+ # @spec CHO2a
43
+ #
44
+ # @return [Ably::Models::ChannelMetrics, nil]
45
+ #
46
+ def metrics
47
+ Ably::Models::ChannelMetrics(attributes[:metrics])
48
+ end
49
+ end
50
+ end
@@ -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