From 78905adf7fb065e14ca67d4bae826c6cf638c965 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Fri, 2 Sep 2022 11:11:41 +0200 Subject: [PATCH 01/70] Add docs workflow to ably-ruby --- .github/workflows/docs.yml | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..160c30ca5 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,36 @@ +on: + pull_request: + push: + branches: + - main +jobs: + build: + runs-on: ubuntu-latest + permissions: + deployments: write + id-token: write + steps: + - uses: actions/checkout@v2 + + - uses: ruby/setup-ruby@v1 + with: + ruby-version: '2.7' + bundler-cache: true + + - name: Build Documentation + run: | + yard + ls -al doc/ + - name: Configure AWS Credentials + uses: aws-actions/configure-aws-credentials@v1 + with: + aws-region: eu-west-2 + role-to-assume: arn:aws:iam::${{ secrets.ABLY_AWS_ACCOUNT_ID_SDK }}:role/ably-sdk-builds-ably-ruby + role-session-name: "${{ github.run_id }}-${{ github.run_number }}" + + - name: Upload Documentation + uses: ably/sdk-upload-action@v1 + with: + sourcePath: doc/ + githubToken: ${{ secrets.GITHUB_TOKEN }} + artifactName: docs \ No newline at end of file From 3739fcd0078dc36868280d258a2a703d68d522c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Fri, 2 Sep 2022 11:27:35 +0200 Subject: [PATCH 02/70] Execute yard run command within bundle exec --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 160c30ca5..735569f20 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -19,7 +19,7 @@ jobs: - name: Build Documentation run: | - yard + bundle exec yard ls -al doc/ - name: Configure AWS Credentials uses: aws-actions/configure-aws-credentials@v1 From 4a0ed713c04b06d88168c999d3534563db02386a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:49:32 +0200 Subject: [PATCH 03/70] Fix lib/ably/util/crypto.rb descriptions --- lib/ably/util/crypto.rb | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/lib/ably/util/crypto.rb b/lib/ably/util/crypto.rb index d8202812a..3635b59a5 100644 --- a/lib/ably/util/crypto.rb +++ b/lib/ably/util/crypto.rb @@ -2,6 +2,8 @@ require 'openssl' module Ably::Util + # Contains the properties required to configure the encryption of {Ably::Models::Message} payloads. + # class Crypto DEFAULTS = { algorithm: 'aes', @@ -14,6 +16,7 @@ class Crypto # Configured {Ably::Models::CipherParams} for this Crypto object, see {#initialize} for a list of configureable options # # @return [Ably::Models::CipherParams] + # attr_reader :cipher_params # Creates a {Ably::Util::Crypto} object @@ -34,13 +37,12 @@ def initialize(params) @cipher_params = Ably::Models::CipherParams(params) end - # Obtain a default {Ably::Models::CipherParams}. This uses default algorithm, mode and - # padding and key length. An IV is generated using the default - # system SecureRandom; the key may be obtained from the returned {Ably::Models::CipherParams} - # for out-of-band distribution to other clients. - + # Returns a {Ably::Models::CipherParams} object, using the default values for any fields not supplied by the `Hash` object. + # + # @spec RSE1, RSE1b, RSE1b + # # @param [Hash] params a Hash used to configure the Crypto library's {Ably::Models::CipherParams} - # @option params (see Ably::Models::CipherParams#initialize) + # @option params (see {Ably::Models::CipherParams#initialize}) # # @return [Ably::Models::CipherParams] Configured cipher params with :key, :algorithm, :mode, :key_length attributes # @@ -48,11 +50,13 @@ def self.get_default_params(params = {}) Ably::Models::CipherParams(params) end - # Generate a random encryption key from the supplied keylength (or the - # default key_length of 256 if none supplied) + # Generates a random key to be used in the encryption of the channel. If the language cryptographic randomness + # primitives are blocking or async, a callback is used. The callback returns a generated binary key. + # + # @spec RSE2, RSE2a, RSE2b # - # @param [Integer] key_length Optional (default 256) key length for the generated random key. 128 and 256 bit key lengths are supported - # @return Binary String (byte array) with ASCII_8BIT encoding + # @param [Integer] key_length The length of the key, in bits, to be generated. If not specified, this is equal to the default keyLength of the default algorithm: for AES this is 256 bits. + # @return Binary The key as a binary, for example, a byte array. # def self.generate_random_key(key_length = DEFAULTS.fetch(:key_length)) params = DEFAULTS.merge(key_length: key_length) From 2a41786c35fbc31b29b762b373ea5113cfe83d6f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:49:51 +0200 Subject: [PATCH 04/70] Fix lib/ably/rest/push/device_registrations.rb descriptions --- lib/ably/rest/push/device_registrations.rb | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/lib/ably/rest/push/device_registrations.rb b/lib/ably/rest/push/device_registrations.rb index 868ab4dff..f5eb22874 100644 --- a/lib/ably/rest/push/device_registrations.rb +++ b/lib/ably/rest/push/device_registrations.rb @@ -17,6 +17,8 @@ def initialize(admin) # Get registered device by device ID # + # @spec RSH1b1 + # # @param [String, Ably::Models::DeviceDetails] device_id the device to retrieve # # @return [Ably::Models::DeviceDetails] Returns {Ably::Models::DeviceDetails} if a match is found else a {Ably::Exceptions::ResourceMissing} is raised @@ -30,6 +32,8 @@ def get(device_id) # List registered devices filtered by optional params # + # @spec RSH1b2 + # # @param [Hash] params the filter options for the list registered device request # @option params [String] :client_id filter by devices registered to a client identifier. Cannot be used with +device_id+ param # @option params [String] :device_id filter by unique device ID. Cannot be used with +client_id+ param @@ -54,7 +58,10 @@ def list(params = {}) Ably::Models::PaginatedResult.new(response, '', client, paginated_options) end - # Save and register device + # Registers or updates a {Ably::Models::DeviceDetails} object with Ably. + # Returns the new, or updated {Ably::Models::DeviceDetails} object. + # + # @spec RSH1b3 # # @param [Ably::Models::DeviceDetails, Hash] device the device details to save # @@ -69,6 +76,8 @@ def save(device) # Remove device # + # @spec RSH1b4 + # # @param [String, Ably::Models::DeviceDetails] device_id the device to remove # # @return [void] @@ -80,7 +89,9 @@ def remove(device_id) client.delete("/push/deviceRegistrations/#{device_id}", {}) end - # Remove device matching where params + # Removes all devices registered to receive push notifications from Ably matching the filter params provided. + # + # @spec RSH1b5 # # @param [Hash] params the filter params for the remove request # @option params [String] :client_id remove devices registered to a client identifier. Cannot be used with +device_id+ param From 085a197183e3f08e6fe857ac12e1c7877aeb3e2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:50:04 +0200 Subject: [PATCH 05/70] Fix lib/ably/rest/push/admin.rb descriptions --- lib/ably/rest/push/admin.rb | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/lib/ably/rest/push/admin.rb b/lib/ably/rest/push/admin.rb index 8155e8ecd..f6dc7cb6f 100644 --- a/lib/ably/rest/push/admin.rb +++ b/lib/ably/rest/push/admin.rb @@ -39,13 +39,17 @@ def publish(recipient, data) end # Manage device registrations + # # @return [Ably::Rest::Push::DeviceRegistrations] + # def device_registrations @device_registrations ||= DeviceRegistrations.new(self) end # Manage channel subscriptions for devices or clients + # # @return [Ably::Rest::Push::ChannelSubscriptions] + # def channel_subscriptions @channel_subscriptions ||= ChannelSubscriptions.new(self) end From b33fc8b8151027f440d465fdcc5e8454d7650e0b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:50:16 +0200 Subject: [PATCH 06/70] Fix lib/ably/rest/push.rb descriptions --- lib/ably/rest/push.rb | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lib/ably/rest/push.rb b/lib/ably/rest/push.rb index ee15527e6..a03d0400c 100644 --- a/lib/ably/rest/push.rb +++ b/lib/ably/rest/push.rb @@ -14,7 +14,9 @@ def initialize(client) end # Admin features for push notifications like managing devices and channel subscriptions + # # @return [Ably::Rest::Push::Admin] + # def admin @admin ||= Admin.new(self) end From 5167490606f8f904cb17fc4b5e85a0707d6080bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:50:29 +0200 Subject: [PATCH 07/70] Fix lib/ably/rest/presence.rb descriptions --- lib/ably/rest/presence.rb | 39 +++++++++++++++++++++++++++------------ 1 file changed, 27 insertions(+), 12 deletions(-) diff --git a/lib/ably/rest/presence.rb b/lib/ably/rest/presence.rb index a025f5a5b..3fa3159ca 100644 --- a/lib/ably/rest/presence.rb +++ b/lib/ably/rest/presence.rb @@ -1,34 +1,45 @@ module Ably module Rest + # Enables the retrieval of the current and historic presence set for a channel. + # class Presence include Ably::Modules::Conversions # {Ably::Rest::Client} for this Presence object + # # @return {Ably::Rest::Client} + # # @private attr_reader :client # {Ably::Rest::Channel} this Presence object is associated with - # @return {Ably::Rest::Channel} + # + # @return [Ably::Rest::Channel] + # attr_reader :channel # Initialize a new Presence object # # @param client [Ably::Rest::Client] # @param channel [Channel] The channel object + # def initialize(client, channel) @client = client @channel = channel end - # Obtain the set of members currently present for a channel + # Retrieves the current members present on the channel and the metadata for each member, such as their + # {Ably::Models::PresenceMessage::ACTION} and ID. Returns a {Ably::Models::PaginatedResult} object, + # containing an array of {Ably::Models::PresenceMessage} objects. + # + # @spec RSPa, RSP3a, RSP3a2, RSP3a3 # # @param [Hash] options the options for the set of members present - # @option options [Integer] :limit Maximum number of members to retrieve up to 1,000, defaults to 100 - # @option options [String] :client_id optional client_id filter for the member - # @option options [String] :connection_id optional connection_id filter for the member + # @option options [Integer] :limit An upper limit on the number of messages returned. The default is 100, and the maximum is 1000. (RSP3a) + # @option options [String] :client_id Filters the list of returned presence members by a specific client using its ID. (RSP3a2) + # @option options [String] :connection_id Filters the list of returned presence members by a specific connection using its ID. (RSP3a3) # - # @return [Ably::Models::PaginatedResult] First {Ably::Models::PaginatedResult page} of {Ably::Models::PresenceMessage} objects accessible with {Ably::Models::PaginatedResult#items #items}. + # @return [Ably::Models::PaginatedResult] A {Ably::Models::PaginatedResult} object containing an array of {Ably::Models::PresenceMessage} objects. # def get(options = {}) options = options = { @@ -49,15 +60,19 @@ def get(options = {}) end end - # Return the presence messages history for the channel + # Retrieves a {Ably::Models::PaginatedResult} object, containing an array of historical {Ably::Models::PresenceMessage} + # objects for the channel. If the channel is configured to persist messages, then presence messages can be retrieved + # from history for up to 72 hours in the past. If not, presence messages can only be retrieved from history for up to two minutes in the past. + # + # @spec RSP4a # # @param [Hash] options the options for the message history request - # @option options [Integer,Time] :start Ensure earliest time or millisecond since epoch for any presence messages retrieved is +:start+ - # @option options [Integer,Time] :end Ensure latest time or millisecond since epoch for any presence messages retrieved is +:end+ - # @option options [Symbol] :direction +:forwards+ or +:backwards+, defaults to +:backwards+ - # @option options [Integer] :limit Maximum number of messages to retrieve up to 1,000, defaults to 100 + # @option options [Integer,Time] :start The time from which messages are retrieved, specified as milliseconds since the Unix epoch. (RSP4b1) + # @option options [Integer,Time] :end The time until messages are retrieved, specified as milliseconds since the Unix epoch. (RSP4b1) + # @option options [Symbol] :direction The order for which messages are returned in. Valid values are backwards which orders messages from most recent to oldest, or forwards which orders messages from oldest to most recent. The default is backwards. (RSP4b2) + # @option options [Integer] :limit An upper limit on the number of messages returned. The default is 100, and the maximum is 1000. (RSP4b3) # - # @return [Ably::Models::PaginatedResult] First {Ably::Models::PaginatedResult page} of {Ably::Models::PresenceMessage} objects accessible with {Ably::Models::PaginatedResult#items #items}. + # @return [Ably::Models::PaginatedResult] A {Ably::Models::PaginatedResult} object containing an array of {Ably::Models::PresenceMessage} objects. # def history(options = {}) url = "#{base_path}/history" From fa9bdac1413f9abd1511269695e231bb4170760a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:50:41 +0200 Subject: [PATCH 08/70] Fix lib/ably/rest/client.rb descriptions --- lib/ably/rest/client.rb | 74 ++++++++++++++++++++++------------------- 1 file changed, 40 insertions(+), 34 deletions(-) diff --git a/lib/ably/rest/client.rb b/lib/ably/rest/client.rb index 0d9ab8758..be121a16d 100644 --- a/lib/ably/rest/client.rb +++ b/lib/ably/rest/client.rb @@ -10,12 +10,7 @@ module Ably module Rest - # Client for the Ably REST API - # - # @!attribute [r] client_id - # @return [String] A client ID, used for identifying this client for presence purposes - # @!attribute [r] auth_options - # @return [Hash] {Ably::Auth} options configured for this client + # A client that offers a simple stateless API to interact directly with Ably's REST API. # class Client include Ably::Modules::Conversions @@ -59,11 +54,13 @@ class Client # @return [String] attr_reader :agent - # {Ably::Auth} authentication object configured for this connection + # An {Ably::Auth} object. + # @spec RSC5 # @return [Ably::Auth] attr_reader :auth - # The collection of {Ably::Rest::Channel}s that have been created + # A {Ably::Rest::Channels} object. + # @spec RSN1 # @return [Aby::Rest::Channels] attr_reader :channels @@ -127,7 +124,9 @@ class Client # @return [Integer] attr_reader :max_frame_size - # Creates a {Ably::Rest::Client Rest Client} and configures the {Ably::Auth} object for the connection. + # Constructs a {Ably::Rest::Client} object using an Ably API key or token string. + # + # @spec RSC1 # # @param [Hash,String] options an options Hash used to configure the client and the authentication, or String with an API key or Token ID # @option options [Boolean] :tls (true) When false, TLS is disabled. Please note Basic Auth is disallowed without TLS as secrets cannot be transmitted over unsecured connections. @@ -167,10 +166,10 @@ class Client # @return [Ably::Rest::Client] # # @example - # # create a new client authenticating with basic auth + # # The Ably API key or token string used to validate the client. # client = Ably::Rest::Client.new('key.id:secret') # - # # create a new client and configure a client ID used for presence + # # Construct a RestClient object using an Ably [Hash]{@link Hash} object. # client = Ably::Rest::Client.new(key: 'key.id:secret', client_id: 'john') # def initialize(options) @@ -275,16 +274,18 @@ def channel(name, channel_options = {}) channels.get(name, channel_options) end - # Retrieve the Stats for the application + # Queries the REST /stats API and retrieves your application's usage statistics. Returns a {Ably::Models::PaginatedResult} object, containing an array of {Ably::Models::Stats} objects. See the Stats docs. + # + # @spec RSC6a, RSC6b1, RSC6b2, RSC6b3, RSC6b4 # # @param [Hash] options the options for the stats request - # @option options [Integer,Time] :start Ensure earliest time or millisecond since epoch for any stats retrieved is +:start+ - # @option options [Integer,Time] :end Ensure latest time or millisecond since epoch for any stats retrieved is +:end+ - # @option options [Symbol] :direction +:forwards+ or +:backwards+, defaults to +:backwards+ - # @option options [Integer] :limit Maximum number of messages to retrieve up to 1,000, defaults to 100 - # @option options [Symbol] :unit `:minute`, `:hour`, `:day` or `:month`. Defaults to `:minute` + # @option options [Integer,Time] :start The time from which stats are retrieved, specified as milliseconds since the Unix epoch. RSC6b1 + # @option options [Integer,Time] :end The time until stats are retrieved, specified as milliseconds since the Unix epoch. RSC6b1 + # @option options [Symbol] :direction The order for which stats are returned in. Valid values are backwards which orders stats from most recent to oldest, or forwards which orders stats from oldest to most recent. The default is backwards. RSC6b2 + # @option options [Integer] :limit An upper limit on the number of stats returned. The default is 100, and the maximum is 1000. RSC6b3 + # @option options [Symbol] :unit minute, hour, day or month. Based on the unit selected, the given start or end times are rounded down to the start of the relevant interval depending on the unit granularity of the query. RSC6b4 # - # @return [Ably::Models::PaginatedResult] An Array of Stats + # @return [Ably::Models::PaginatedResult] A {Ably::Models::PaginatedResult} object containing an array of {Ably::Models::Stats} objects. # def stats(options = {}) options = { @@ -306,9 +307,13 @@ def stats(options = {}) Ably::Models::PaginatedResult.new(response, url, self, paginated_options) end - # Retrieve the Ably service time + # Retrieves the time from the Ably service as milliseconds since the Unix epoch. Clients that do not have access + # to a sufficiently well maintained time source and wish to issue Ably {Ably::Models::TokenRequest} with + # a more accurate timestamp should use the {Ably::Rest::Client#queryTime} property instead of this method. # - # @return [Time] The time as reported by the Ably service + # @spec RSC16 + # + # @return [Time] The time as milliseconds since the Unix epoch. def time response = get('/time', {}, send_auth_header: false) @@ -357,20 +362,19 @@ def delete(path, params, options = {}) raw_request(:delete, path, params, options) end - # Perform an HTTP request to the Ably API - # This is a convenience for customers who wish to use bleeding edge REST API functionality - # that is either not documented or is not included in the API for our client libraries. - # The REST client library provides a function to issue HTTP requests to the Ably endpoints - # with all the built in functionality of the library such as authentication, paging, - # fallback hosts, MsgPack and JSON support etc. + # Makes a REST request to a provided path. This is provided as a convenience for developers who wish to use REST API + # functionality that is either not documented or is not yet included in the public API, without having to directly + # handle features such as authentication, paging, fallback hosts, MsgPack and JSON support. + # + # @spec RSC19 # - # @param method [Symbol] The HTTP method symbol such as +:get+, +:post+, +:put+ - # @param path [String] The path of the URL such +/channel/foo/publish+ - # @param params [Hash, nil] Optional querystring params - # @param body [Hash, nil] Optional body for the POST or PUT request, must be nil or a JSON-like object - # @param headers [Hash, nil] Optional additional headers + # @param method [Symbol] The request method to use, such as GET, POST. + # @param path [String] The request path. + # @param params [Hash, nil] The parameters to include in the URL query of the request. The parameters depend on the endpoint being queried. See the REST API reference for the available parameters of each endpoint. + # @param body [Hash, nil] The JSON body of the request. + # @param headers [Hash, nil] Additional HTTP headers to include in the request. # - # @return [Ably::Models::HttpPaginatedResponse<>] + # @return [Ably::Models::HttpPaginatedResponse<>] An {Ably::Models::HttpPaginatedResponse} object returned by the HTTP request, containing an empty or JSON-encodable object. def request(method, path, params = {}, body = nil, headers = {}, options = {}) raise "Method #{method.to_s.upcase} not supported" unless %i(get put patch post delete).include?(method.to_sym) @@ -408,7 +412,8 @@ def request(method, path, params = {}, body = nil, headers = {}, options = {}) Models::HttpPaginatedResponse.new(response, path, self) end - # The local device detilas + # Retrieves an object that represents the current state of the device as a target for push notifications. + # @spec RSH8 # @return [Ably::Models::LocalDevice] # # @note This is unsupported in the Ruby library @@ -416,7 +421,8 @@ def device raise Ably::Exceptions::PushNotificationsNotSupported, 'This device does not support receiving or subscribing to push notifications. The local device object is not unavailable' end - # Push notification object for publishing and managing push notifications + # A {Ably::Rest::Push} object. + # @spec RSH7 # @return [Ably::Rest::Push] def push @push ||= Push.new(self) From 7e5f648e965c20c89b6ea6c3a7dce37edcd10784 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:50:53 +0200 Subject: [PATCH 09/70] Fix lib/ably/rest/channels.rb descriptions --- lib/ably/rest/channels.rb | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/lib/ably/rest/channels.rb b/lib/ably/rest/channels.rb index 8fccaf8bf..6bfdbea10 100644 --- a/lib/ably/rest/channels.rb +++ b/lib/ably/rest/channels.rb @@ -8,24 +8,26 @@ def initialize(client) super client, Ably::Rest::Channel end - # @!method get(name, channel_options = {}) # Return a {Ably::Rest::Channel} for the given name # # @param name [String] The name of the channel # @param channel_options [Hash] Channel options, currently reserved for Encryption options - # @return [Ably::Rest::Channel} + # + # @return [Ably::Rest::Channel] + # def get(*args) super end - # @!method fetch(name, &missing_block) # Return a {Ably::Rest::Channel} for the given name if it exists, else the block will be called. # 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 # # @param name [String] The name of the channel # @yield [options] (optional) if a missing_block is passed to this method and no channel exists matching the name, this block is called # @yieldparam [String] name of the missing channel + # # @return [Ably::Rest::Channel] + # def fetch(*args) super end @@ -36,6 +38,7 @@ def fetch(*args) # {Ably::Rest::Channel} object. Explicitly release channels to free up resources if required # # @return [void] + # def release(*args) super end From 239716d4a7bbf96bc5f2ee015a9f0134ad8dd897 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:51:07 +0200 Subject: [PATCH 10/70] Fix lib/ably/rest/channel/push_channel.rb --- lib/ably/rest/channel/push_channel.rb | 3 --- 1 file changed, 3 deletions(-) diff --git a/lib/ably/rest/channel/push_channel.rb b/lib/ably/rest/channel/push_channel.rb index b2f1a2e98..0c3e3b5b8 100644 --- a/lib/ably/rest/channel/push_channel.rb +++ b/lib/ably/rest/channel/push_channel.rb @@ -3,9 +3,6 @@ class Channel # A push channel used for push notifications # Each PushChannel maps to exactly one Rest Channel # - # @!attribute [r] channel - # @return [Ably::Rest::Channel] Underlying channel object - # class PushChannel attr_reader :channel From 5d40aa8db19ebd5c3fa029ab2e47677464a26489 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:51:19 +0200 Subject: [PATCH 11/70] Fix lib/ably/rest/channel.rb descriptions --- lib/ably/rest/channel.rb | 50 +++++++++++++++++++++++----------------- 1 file changed, 29 insertions(+), 21 deletions(-) diff --git a/lib/ably/rest/channel.rb b/lib/ably/rest/channel.rb index ed61c8930..a8bcfb83a 100644 --- a/lib/ably/rest/channel.rb +++ b/lib/ably/rest/channel.rb @@ -1,12 +1,7 @@ module Ably module Rest - # The Ably Realtime service organises the traffic within any application into named channels. - # Channels are the "unit" of message distribution; clients attach to channels to subscribe to messages, and every message broadcast by the service is associated with a unique channel. + # Enables messages to be published and historic messages to be retrieved for a channel. # - # @!attribute [r] name - # @return {String} channel name - # @!attribute [r] options - # @return {Hash} channel options configured for this channel, see {#initialize} for channel_options class Channel include Ably::Modules::Conversions @@ -15,9 +10,14 @@ class Channel # @api private attr_reader :client - attr_reader :name, :options + # The channel name. + # @return [String] + attr_reader :name - # Push channel used for push notification (client-side) + attr_reader :options + + # A {Ably::Rest::Channel::PushChannel} object + # @spec RSH4 # @return [Ably::Rest::Channel::PushChannel] # @api private attr_reader :push @@ -39,7 +39,10 @@ def initialize(client, name, channel_options = {}) @push = PushChannel.new(self) end - # Publish one or more messages to the channel. Five overloaded forms + # Publishes a message to the channel. A callback may optionally be passed in to this call to be notified of success or failure of the operation. + # + # @spec RSL1 + # # @param name [String, Array, Ably::Models::Message, 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, or a single Ably::Model::Message object # @param data [String, Array, Hash, nil] The message payload unless an Array of [Ably::Model::Message] objects passed in the first argument, in which case an optional hash of query parameters # @param attributes [Hash, nil] Optional additional message attributes such as :extras, :id, :client_id or :connection_id, applied when name attribute is nil or a string (Deprecated, will be removed in 2.0 in favour of constructing a Message object) @@ -112,15 +115,19 @@ def publish(name, data = nil, attributes = {}) [201, 204].include?(response.status) end - # Return the message of the channel + # Retrieves a {Ably::Models::PaginatedResult} object, containing an array of historical {Ably::Models::Message} + # objects for the channel. If the channel is configured to persist messages, then messages can be retrieved from + # history for up to 72 hours in the past. If not, messages can only be retrieved from history for up to two minutes in the past. + # + # @spec RSL2a # # @param [Hash] options the options for the message history request - # @option options [Integer,Time] :start Ensure earliest time or millisecond since epoch for any messages retrieved is +:start+ - # @option options [Integer,Time] :end Ensure latest time or millisecond since epoch for any messages retrieved is +:end+ - # @option options [Symbol] :direction +:forwards+ or +:backwards+, defaults to +:backwards+ - # @option options [Integer] :limit Maximum number of messages to retrieve up to 1,000, defaults to 100 + # @option options [Integer,Time] :start The time from which messages are retrieved, specified as milliseconds since the Unix epoch. RSL2b1 + # @option options [Integer,Time] :end The time until messages are retrieved, specified as milliseconds since the Unix epoch. RSL2b1 + # @option options [Symbol] :direction The order for which messages are returned in. Valid values are backwards which orders messages from most recent to oldest, or forwards which orders messages from oldest to most recent. The default is backwards. RSL2b2 + # @option options [Integer] :limit An upper limit on the number of messages returned. The default is 100, and the maximum is 1000. RSL2b3 # - # @return [Ably::Models::PaginatedResult] First {Ably::Models::PaginatedResult page} of {Ably::Models::Message} objects accessible with {Ably::Models::PaginatedResult#items #items}. + # @return [Ably::Models::PaginatedResult] A {Ably::Models::PaginatedResult} object containing an array of {Ably::Models::Message} objects. # def history(options = {}) url = "#{base_path}/messages" @@ -146,14 +153,15 @@ def history(options = {}) end end - # Return the {Ably::Rest::Presence} object - # + # A {Ably::Rest::Presence} object. + # @spec RSL3 # @return [Ably::Rest::Presence] def presence @presence ||= Presence.new(client, self) end - # Sets or updates the stored channel options. (#RSL7) + # Sets the {Ably::Models::ChannelOptions} for the channel. + # @spec RSL7 # @param channel_options [Hash, Ably::Models::ChannelOptions] A hash of options or a {Ably::Models::ChannelOptions} # @return [Ably::Models::ChannelOptions] def set_options(channel_options) @@ -161,9 +169,9 @@ def set_options(channel_options) end alias options= set_options - # Makes GET request for channel details (#RSL8, #RSL8a) - # - # @return [Ably::Models::ChannelDetails] + # Retrieves a {Ably::Models::ChannelDetails} object for the channel, which includes status and occupancy metrics. + # @spec RSL8 + # @return [Ably::Models::ChannelDetails] A {Ably::Models::ChannelDetails} object. def status Ably::Models::ChannelDetails.new(client.get(base_path).body) end From a89e6a28ce0f24eef52ed2a3985c27a549ff31bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:51:32 +0200 Subject: [PATCH 12/70] Fix lib/ably/realtime/push/admin.rb descriptions --- lib/ably/realtime/push/admin.rb | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/lib/ably/realtime/push/admin.rb b/lib/ably/realtime/push/admin.rb index be7fc3c84..746b87af2 100644 --- a/lib/ably/realtime/push/admin.rb +++ b/lib/ably/realtime/push/admin.rb @@ -5,6 +5,7 @@ module Ably::Realtime class Push # Class providing push notification administrative functionality # for registering devices and attaching to channels etc. + # class Admin include Ably::Modules::AsyncWrapper include Ably::Modules::Conversions @@ -20,9 +21,14 @@ def initialize(push) @client = push.client end + # Sends a push notification directly to a device, or a group of devices sharing the same clientId. + # # (see Ably::Rest::Push#publish) # + # @spec RSH1a + # # @yield Block is invoked upon successful publish of the message + # # @return [Ably::Util::SafeDeferrable] # def publish(recipient, data, &callback) @@ -36,14 +42,22 @@ def publish(recipient, data, &callback) end end - # Manage device registrations + # A {Ably::Realtime::Push::DeviceRegistrations} object. + # + # @spec RSH1b + # # @return [Ably::Realtime::Push::DeviceRegistrations] + # def device_registrations @device_registrations ||= DeviceRegistrations.new(self) end - # Manage channel subscriptions for devices or clients + # A {Ably::Realtime::Push::ChannelSubscriptions} object. + # + # @spec RSH1c + # # @return [Ably::Realtime::Push::ChannelSubscriptions] + # def channel_subscriptions @channel_subscriptions ||= ChannelSubscriptions.new(self) end From 90af70df57f340767b1a826c54598b6c5e1bad82 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:51:44 +0200 Subject: [PATCH 13/70] Fix lib/ably/realtime/push.rb descriptions --- lib/ably/realtime/push.rb | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/lib/ably/realtime/push.rb b/lib/ably/realtime/push.rb index 4b0cb6f80..b3ac400a0 100644 --- a/lib/ably/realtime/push.rb +++ b/lib/ably/realtime/push.rb @@ -11,27 +11,39 @@ def initialize(client) @client = client end - # Admin features for push notifications like managing devices and channel subscriptions + # A {Ably::Realtime::Push::Admin} object. + # + # @spec RSH1 + # # @return [Ably::Realtime::Push::Admin] + # def admin @admin ||= Admin.new(self) end - # Activate this device for push notifications by registering with the push transport such as GCM/APNS + # Activates the device for push notifications with FCM or APNS, obtaining a unique identifier from them. + # Subsequently registers the device with Ably and stores the deviceIdentityToken in local storage. + # + # @spec RSH2a # # @note This is unsupported in the Ruby library + # def activate(*arg) raise_unsupported end - # Deactivate this device for push notifications by removing the registration with the push transport such as GCM/APNS + # Deactivates the device from receiving push notifications with Ably and FCM or APNS. + # + # @spec RSH2b # # @note This is unsupported in the Ruby library + # def deactivate(*arg) raise_unsupported end private + def raise_unsupported raise Ably::Exceptions::PushNotificationsNotSupported, 'This device does not support receiving or subscribing to push notifications. All PushChannel methods are unavailable' end From c838162c398dc61aea525110fc4d6ca3a399d968 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:51:59 +0200 Subject: [PATCH 14/70] Fix lib/ably/realtime/presence.rb descriptions --- lib/ably/realtime/presence.rb | 98 ++++++++++++++++++++++------------- 1 file changed, 61 insertions(+), 37 deletions(-) diff --git a/lib/ably/realtime/presence.rb b/lib/ably/realtime/presence.rb index 8c8a89fed..7421ea619 100644 --- a/lib/ably/realtime/presence.rb +++ b/lib/ably/realtime/presence.rb @@ -1,5 +1,6 @@ module Ably::Realtime - # Presence provides access to presence operations and state for the associated Channel + # Enables the presence set to be entered and subscribed to, and the historic presence set to be retrieved for a channel. + # class Presence include Ably::Modules::Conversions include Ably::Modules::EventEmitter @@ -90,15 +91,14 @@ def enter(data = nil, &success_block) end end - # Enter the specified client_id into this channel. The given client will be added to the - # presence set and presence subscribers will see a corresponding presence message. - # This method is provided to support connections (e.g. connections from application - # server instances) that act on behalf of multiple client_ids. In order to be able to - # enter the channel with this method, the client library must have been instanced - # either with a key, or with a token bound to the wildcard client_id + # Enters the presence set of the channel for a given clientId. Enables a single client to update presence on behalf + # of any number of clients using a single connection. The library must have been instantiated with an API key + # or a token bound to a wildcard clientId. An optional callback may be provided to notify of the success or failure of the operation. + # + # @spec RTP4, RTP14, RTP15 # # @param [String] client_id id of the client - # @param [String,Hash,nil] data optional data (eg a status message) for this member + # @param [String,Hash,nil] data The payload associated with the presence member. A JSON object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads. # # @yield [Ably::Realtime::Presence] On success, will call the block with this {Ably::Realtime::Presence} object # @return [Ably::Util::SafeDeferrable] Deferrable that supports both success (callback) and failure (errback) callbacks @@ -151,13 +151,16 @@ def leave(data = nil, &success_block) end end - # Leave a given client_id from this channel. This client will be removed from the - # presence set and presence subscribers will see a leave message for this client. + # Leaves the presence set of the channel for a given clientId. Enables a single client to update presence on behalf + # of any number of clients using a single connection. The library must have been instantiated with an API key + # or a token bound to a wildcard clientId. An optional callback may be provided to notify of the success or failure of the operation. # - # @param (see Presence#enter_client) + # @spec RTP15 # - # @yield (see Presence#enter_client) - # @return (see Presence#enter_client) + # @param (see {Ably::Realtime::Presence#enter_client}) + # + # @yield (see {Ably::Realtime::Presence#enter_client}) + # @return (see {Ably::Realtime::Presence#enter_client}) # def leave_client(client_id, data = nil, &success_block) ensure_supported_client_id client_id @@ -166,14 +169,15 @@ def leave_client(client_id, data = nil, &success_block) send_presence_action_for_client(Ably::Models::PresenceMessage::ACTION.Leave, client_id, data, &success_block) end - # Update the presence data for this client. If the client is not already a member of - # the presence set it will be added, and presence subscribers will see an enter or - # update message for this client. + # Updates the data payload for a presence member. If called before entering the presence set, this is treated as + # an {Ably::Realtime::Presence::STATE.Entered} event. An optional callback may be provided to notify of the success or failure of the operation. # - # @param (see Presence#enter) + # @spec RTP9 # - # @yield (see Presence#enter) - # @return (see Presence#enter) + # @param (see {Ably::Realtime::Presence#enter}) + # + # @yield (see {Ably::Realtime::Presence#enter}) + # @return (see {Ably::Realtime::Presence#enter}) # def update(data = nil, &success_block) deferrable = create_deferrable @@ -197,11 +201,12 @@ def update(data = nil, &success_block) end end - # Update the presence data for a specified client_id into this channel. - # If the client is not already a member of the presence set it will be added, and - # presence subscribers will see an enter or update message for this client. - # As with {#enter_client}, the connection must be authenticated in a way that - # enables it to represent an arbitrary clientId. + # Updates the data payload for a presence member using a given clientId. Enables a single client to update presence + # on behalf of any number of clients using a single connection. The library must have been instantiated with an API + # key or a token bound to a wildcard clientId. An optional callback may be provided to notify of the success + # or failure of the operation. + # + # @spec RTP15 # # @param (see Presence#enter_client) # @@ -215,12 +220,16 @@ def update_client(client_id, data = nil, &success_block) send_presence_action_for_client(Ably::Models::PresenceMessage::ACTION.Update, client_id, data, &success_block) end - # Get the presence members for this Channel. + # Retrieves the current members present on the channel and the metadata for each member, such as their + # {Ably::Models::ProtocolMessage::ACTION} and ID. Returns an array of {Ably::Models::PresenceMessage} objects. + # + # @spec RTP11, RTP11c1, RTP11c2, RTP11c3 + # + # @param (see {Ably::Realtime::Presence::MembersMap#get}) + # @option options (see {Ably::Realtime::Presence::MembersMap#get}) + # @yield (see {Ably::Realtime::Presence::MembersMap#get}) # - # @param (see Ably::Realtime::Presence::MembersMap#get) - # @option options (see Ably::Realtime::Presence::MembersMap#get) - # @yield (see Ably::Realtime::Presence::MembersMap#get) - # @return (see Ably::Realtime::Presence::MembersMap#get) + # @return (see {Ably::Realtime::Presence::MembersMap#get}) # def get(options = {}, &block) deferrable = create_deferrable @@ -252,8 +261,11 @@ def get(options = {}, &block) end end - # Subscribe to presence events on the associated Channel. - # This implicitly attaches the Channel if it is not already attached. + # Registers a listener that is called each time a {Ably::Models::PresenceMessage} is received on the channel, + # such as a new member entering the presence set. A callback may optionally be passed in to this call to be notified + # of success or failure of the channel {Ably::Realtime::Channel#attach} operation. + # + # @spec RTP6a, RTP6b # # @param actions [Ably::Models::PresenceMessage::ACTION] Optional, the state change action to subscribe to. Defaults to all presence actions # @yield [Ably::Models::PresenceMessage] For each presence state change event, the block is called @@ -265,8 +277,9 @@ def subscribe(*actions, &callback) super end - # Unsubscribe the matching block for presence events on the associated Channel. - # If a block is not provided, all subscriptions will be unsubscribed + # Deregisters all listeners currently receiving {Ably::Models::PresenceMessage} for the channel. + # + # @spec RTP7a, RTP7b, RTE5 # # @param actions [Ably::Models::PresenceMessage::ACTION] Optional, the state change action to subscribe to. Defaults to all presence actions # @@ -276,10 +289,15 @@ def unsubscribe(*actions, &callback) super end - # Return the presence messages history for the channel + # Retrieves a {Ably::Models::PaginatedResult} object, containing an array of historical + # {Ably::Models::PresenceMessage} objects for the channel. If the channel is configured to persist messages, + # then presence messages can be retrieved from history for up to 72 hours in the past. If not, presence messages + # can only be retrieved from history for up to two minutes in the past. # - # @param (see Ably::Rest::Presence#history) - # @option options (see Ably::Rest::Presence#history) + # @spec RTP12c, RTP12a + # + # @param (see {Ably::Rest::Presence#history}) + # @option options (see {Ably::Rest::Presence#history}) # # @yield [Ably::Models::PaginatedResult] First {Ably::Models::PaginatedResult page} of {Ably::Models::PresenceMessage} objects accessible with {Ably::Models::PaginatedResult#items #items}. # @@ -306,7 +324,13 @@ def logger client.logger end - # Returns true when the initial member SYNC following channel attach is completed + # Indicates whether the presence set synchronization between Ably and the clients on the channel has been completed. + # Set to true when the sync is complete. + # + # @spec RTP13 + # + # return [Boolean] + # def sync_complete? members.sync_complete? end From e750fe1aaf4e03017f96beec591ac9231fb9d2c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:52:11 +0200 Subject: [PATCH 15/70] Fix lib/ably/realtime/connection/websocket_transport.rb descriptions --- lib/ably/realtime/connection/websocket_transport.rb | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/lib/ably/realtime/connection/websocket_transport.rb b/lib/ably/realtime/connection/websocket_transport.rb index faff5688f..1d348c9e3 100644 --- a/lib/ably/realtime/connection/websocket_transport.rb +++ b/lib/ably/realtime/connection/websocket_transport.rb @@ -31,7 +31,9 @@ def initialize(connection, url) # Disconnect the socket transport connection and write all pending text. # If Disconnected state is not automatically emitted, it will be emitted automatically + # # @return [void] + # # @api public def disconnect close_connection_after_writing @@ -133,15 +135,15 @@ def ready_for_release? !connecting? && !connected? end - # @!attribute [r] __incoming_protocol_msgbus__ # @return [Ably::Util::PubSub] Websocket Transport internal incoming protocol message bus + # # @api private def __incoming_protocol_msgbus__ @__incoming_protocol_msgbus__ ||= create_pub_sub_message_bus end - # @!attribute [r] __outgoing_protocol_msgbus__ # @return [Ably::Util::PubSub] Websocket Transport internal outgoing protocol message bus + # # @api private def __outgoing_protocol_msgbus__ @__outgoing_protocol_msgbus__ ||= create_pub_sub_message_bus From 93193d70b14dba0be73bd383b5050facb9368195 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:52:24 +0200 Subject: [PATCH 16/70] Fix lib/ably/realtime/connection/connection_manager.rb descriptions --- lib/ably/realtime/connection/connection_manager.rb | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/lib/ably/realtime/connection/connection_manager.rb b/lib/ably/realtime/connection/connection_manager.rb index c7b40fd26..8d514b9f9 100644 --- a/lib/ably/realtime/connection/connection_manager.rb +++ b/lib/ably/realtime/connection/connection_manager.rb @@ -270,7 +270,9 @@ def error_received_from_server(error) end # Number of consecutive attempts for provided state + # # @return [Integer] + # # @api private def retry_count_for_state(state) retries_for_state(state, ignore_states: [:connecting]).count @@ -356,7 +358,9 @@ def connection end # Timers used to manage connection state, for internal use by the client library + # # @return [Hash] + # def timers @timers end From 9d7cd6482706b10d8547597c99f4d0f2468d4f04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:52:36 +0200 Subject: [PATCH 17/70] Fix lib/ably/realtime/connection.rb descriptions --- lib/ably/realtime/connection.rb | 149 ++++++++++++++++++++------------ 1 file changed, 94 insertions(+), 55 deletions(-) diff --git a/lib/ably/realtime/connection.rb b/lib/ably/realtime/connection.rb index 246c79f53..2eeacb12a 100644 --- a/lib/ably/realtime/connection.rb +++ b/lib/ably/realtime/connection.rb @@ -2,39 +2,7 @@ module Ably module Realtime - # The Connection class represents the connection associated with an Ably Realtime instance. - # The Connection object exposes the lifecycle and parameters of the realtime connection. - # - # Connections will always be in one of the following states: - # - # initialized: 0 - # connecting: 1 - # connected: 2 - # disconnected: 3 - # suspended: 4 - # closing: 5 - # closed: 6 - # failed: 7 - # - # Note that the states are available as Enum-like constants: - # - # Connection::STATE.Initialized - # Connection::STATE.Connecting - # Connection::STATE.Connected - # Connection::STATE.Disconnected - # Connection::STATE.Suspended - # Connection::STATE.Closing - # Connection::STATE.Closed - # Connection::STATE.Failed - # - # @example - # client = Ably::Realtime::Client.new('key.id:secret') - # client.connection.on(:connected) do - # puts "Connected with connection ID: #{client.connection.id}" - # end - # - # @!attribute [r] state - # @return [Ably::Realtime::Connection::STATE] connection state + # Enables the management of a connection to Ably. # class Connection include Ably::Modules::EventEmitter @@ -42,8 +10,50 @@ class Connection include Ably::Modules::SafeYield extend Ably::Modules::Enum - # ConnectionState - # The permited states for this connection + # The current {Ably::Realtime::Connection::STATE} of the connection. + # Describes the realtime [Connection]{@link Connection} object states. + # + # @spec RTN4d + # + # INITIALIZED A connection with this state has been initialized but no connection has yet been attempted. + # CONNECTING A connection attempt has been initiated. The connecting state is entered as soon as the library + # has completed initialization, and is reentered each time connection is re-attempted following disconnection. + # CONNECTED A connection exists and is active. + # DISCONNECTED A temporary failure condition. No current connection exists because there is no network connectivity + # or no host is available. The disconnected state is entered if an established connection is dropped, + # or if a connection attempt was unsuccessful. In the disconnected state the library will periodically + # attempt to open a new connection (approximately every 15 seconds), anticipating that the connection + # will be re-established soon and thus connection and channel continuity will be possible. + # In this state, developers can continue to publish messages as they are automatically placed + # in a local queue, to be sent as soon as a connection is reestablished. Messages published by + # other clients while this client is disconnected will be delivered to it upon reconnection, + # so long as the connection was resumed within 2 minutes. After 2 minutes have elapsed, recovery + # is no longer possible and the connection will move to the SUSPENDED state. + # SUSPENDED A long term failure condition. No current connection exists because there is no network connectivity + # or no host is available. The suspended state is entered after a failed connection attempt if + # there has then been no connection for a period of two minutes. In the suspended state, the library + # will periodically attempt to open a new connection every 30 seconds. Developers are unable to + # publish messages in this state. A new connection attempt can also be triggered by an explicit + # call to {Ably::Realtime::Connection#connect}. Once the connection has been re-established, + # channels will be automatically re-attached. The client has been disconnected for too long for them + # to resume from where they left off, so if it wants to catch up on messages published by other clients + # while it was disconnected, it needs to use the History API. + # CLOSING An explicit request by the developer to close the connection has been sent to the Ably service. + # If a reply is not received from Ably within a short period of time, the connection is forcibly + # terminated and the connection state becomes CLOSED. + # CLOSED The connection has been explicitly closed by the client. In the closed state, no reconnection attempts + # are made automatically by the library, and clients may not publish messages. No connection state is + # preserved by the service or by the library. A new connection attempt can be triggered by an explicit + # call to {Ably::Realtime::Connection#connect}, which results in a new connection. + # FAILED This state is entered if the client library encounters a failure condition that it cannot recover from. + # This may be a fatal connection error received from the Ably service, for example an attempt to connect + # with an incorrect API key, or a local terminal error, for example the token in use has expired + # and the library does not have any way to renew it. In the failed state, no reconnection attempts + # are made automatically by the library, and clients may not publish messages. A new connection attempt + # can be triggered by an explicit call to {Ably::Realtime::Connection#connect}. + # + # @return [Ably::Realtime::Connection::STATE] + # STATE = ruby_enum('STATE', :initialized, :connecting, @@ -55,8 +65,10 @@ class Connection :failed ) - # ConnectionEvent - # The permitted connection events that are emitted for this connection + # Describes the events emitted by a {Ably::Realtime::Connection} object. An event is either an UPDATE or a {Ably::Realtime::Connection::STATE}. + # + # UPDATE RTN4h An event for changes to connection conditions for which the {Ably::Realtime::Connection::STATE} does not change. + # EVENT = ruby_enum('EVENT', STATE.to_sym_arr + [:update] ) @@ -82,20 +94,41 @@ class Connection # Max number of messages to bundle in a single ProtocolMessage MAX_PROTOCOL_MESSAGE_BATCH_SIZE = 50 - # A unique public identifier for this connection, used to identify this member in presence events and messages + # A unique public identifier for this connection, used to identify this member. + # + # @spec RTN8 + # # @return [String] + # attr_reader :id - # A unique private connection key used to recover this connection, assigned by Ably + # A unique private connection key used to recover or resume a connection, assigned by Ably. + # When recovering a connection explicitly, the recoveryKey is used in the recover client options as it contains + # both the key and the last message serial. This private connection key can also be used by other REST clients + # to publish on behalf of this client. See the publishing over REST on behalf of a realtime client docs for more info. + # + # @spec RTN9 + # # @return [String] + # attr_reader :key - # The serial number of the last message to be received on this connection, used to recover or resume a connection + # The serial number of the last message to be received on this connection, used automatically by the library when + # recovering or resuming a connection. When recovering a connection explicitly, the recoveryKey is used in + # the recover client options as it contains both the key and the last message serial. + # + # @spec RTN10 + # # @return [Integer] + # attr_reader :serial - # When a connection failure occurs this attribute contains the Ably Exception + # An {Ably::Models::ErrorInfo} object describing the last error received if a connection failure occurs. + # + # @spec RTN14a + # # @return [Ably::Models::ErrorInfo,Ably::Exceptions::BaseAblyException] + # attr_reader :error_reason # Connection details of the currently established connection @@ -165,9 +198,11 @@ def initialize(client, options) @current_host = client.endpoint.host end - # Causes the connection to close, entering the closed state, from any state except - # the failed state. Once closed, the library will not attempt to re-establish the - # connection without a call to {Connection#connect}. + # Causes the connection to close, entering the {Ably::Realtime::Connection::STATE} CLOSING state. + # Once closed, the library does not attempt to re-establish the connection without an explicit call to + # {Ably::Realtime::Connection#connect}. + # + # @spec RTN12 # # @yield block is called as soon as this connection is in the Closed state # @@ -183,13 +218,11 @@ def close(&success_block) deferrable_for_state_change_to(STATE.Closed, &success_block) end - # Causes the library to attempt connection. If it was previously explicitly - # closed by the user, or was closed as a result of an unrecoverable error, a new connection will be opened. - # Succeeds when connection is established i.e. state is @Connected@ - # Fails when state becomes either @Closing@, @Closed@ or @Failed@ + # Explicitly calling connect() is unnecessary unless the autoConnect attribute of + # the ClientOptions object is false. Unless already connected or connecting, + # this method causes the connection to open, entering the {Ably::Realtime::Connection::STATE} CONNECTING state. # - # Note that if the connection remains in the disconnected ans suspended states indefinitely, - # the Deferrable or block provided may never be called + # @spec RTC1b, RTN3, RTN11 # # @yield block is called as soon as this connection is in the Connected state # @@ -223,9 +256,11 @@ def connect(&success_block) end end - # Sends a ping to Ably and yields the provided block when a heartbeat ping request is echoed from the server. - # This can be useful for measuring true roundtrip client to Ably server latency for a simple message, or checking that an underlying transport is responding currently. - # The elapsed time in seconds is passed as an argument to the block and represents the time taken to echo a ping heartbeat once the connection is in the `:connected` state. + # When connected, sends a heartbeat ping to the Ably server and executes the callback with any error + # and the response time in milliseconds when a heartbeat ping request is echoed from the server. + # This can be useful for measuring true round-trip latency to the connected Ably server. + # + # @spec RTN13 # # @yield [Integer] if a block is passed to this method, then this block will be called once the ping heartbeat is received with the time elapsed in seconds. # If the ping is not received within an acceptable timeframe, the block will be called with +nil+ as he first argument @@ -312,8 +347,12 @@ def internet_up? end end - # @!attribute [r] recovery_key - # @return [String] recovery key that can be used by another client to recover this connection with the :recover option + # The recovery key string can be used by another client to recover this connection's state in the recover client options property. See connection state recover options for more information. + # + # @spec RTN16b, RTN16c + # + # @return [String] + # def recovery_key "#{key}:#{serial}:#{client_msg_serial}" if connection_resumable? end From a25e6c5a54fd79a9764ebe91924929246dc703a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:52:49 +0200 Subject: [PATCH 18/70] Fix lib/ably/realtime/client.rb descriptions --- lib/ably/realtime/client.rb | 85 +++++++++++++++++++++++-------------- 1 file changed, 53 insertions(+), 32 deletions(-) diff --git a/lib/ably/realtime/client.rb b/lib/ably/realtime/client.rb index 45f8f2be3..bf04776c2 100644 --- a/lib/ably/realtime/client.rb +++ b/lib/ably/realtime/client.rb @@ -3,22 +3,7 @@ module Ably module Realtime - # Client for the Ably Realtime API - # - # @!attribute [r] client_id - # (see Ably::Rest::Client#client_id) - # @!attribute [r] auth_options - # (see Ably::Rest::Client#auth_options) - # @!attribute [r] environment - # (see Ably::Rest::Client#environment) - # @!attribute [r] channels - # @return [Aby::Realtime::Channels] The collection of {Ably::Realtime::Channel}s that have been created - # @!attribute [r] encoders - # (see Ably::Rest::Client#encoders) - # @!attribute [r] protocol - # (see Ably::Rest::Client#protocol) - # @!attribute [r] protocol_binary? - # (see Ably::Rest::Client#protocol_binary?) + # A client that extends the functionality of the {Ably::Realtime::Client} and provides additional realtime-specific features. # class Client include Ably::Modules::AsyncWrapper @@ -29,19 +14,33 @@ class Client DOMAIN = 'realtime.ably.io' - # The collection of {Ably::Realtime::Channel}s that have been created + # A {Aby::Realtime::Channels} object. + # + # @spec RTC3, RTS1 + # # @return [Aby::Realtime::Channels] + # attr_reader :channels - # (see Ably::Rest::Client#auth) + # An {Ably::Auth} object. + # + # @spec RTC4 + # + # @return [Ably::Auth] + # attr_reader :auth - # The underlying connection for this client + # A {Aby::Realtime::Connection} object. + # + # @spec RTC2 + # # @return [Aby::Realtime::Connection] + # attr_reader :connection # The {Ably::Rest::Client REST client} instantiated with the same credentials and configuration that is used for all REST operations such as authentication # @return [Ably::Rest::Client] + # @private attr_reader :rest_client @@ -78,8 +77,10 @@ class Client # Creates a {Ably::Realtime::Client Realtime Client} and configures the {Ably::Auth} object for the connection. # - # @param (see Ably::Rest::Client#initialize) - # @option options (see Ably::Rest::Client#initialize) + # @spec RSC1 + # + # @param (see {Ably::Rest::Client#initialize}) + # @option options (see Ably::Rest::Client#initialize) An options {Hash} object. # @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. # Whilst the proc is called synchronously, it does not block the EventMachine reactor as it is run in a separate thread. # The Proc should return a token string, {Ably::Models::TokenDetails} or JSON equivalent, {Ably::Models::TokenRequest} or JSON equivalent @@ -97,10 +98,10 @@ class Client # @return [Ably::Realtime::Client] # # @example - # # create a new client authenticating with basic auth + # # Constructs a {Ably::Realtime::Client} object using an Ably API key or token string. # client = Ably::Realtime::Client.new('key.id:secret') # - # # create a new client and configure a client ID used for presence + # # Constructs a {Ably::Realtime::Client} object using an Ably options object. # client = Ably::Realtime::Client.new(key: 'key.id:secret', client_id: 'john') # def initialize(options) @@ -141,9 +142,13 @@ def channel(name, channel_options = {}) channels.get(name, channel_options) end - # Retrieve the Ably service time + # Retrieves the time from the Ably service as milliseconds since the Unix epoch. Clients that do not have access + # to a sufficiently well maintained time source and wish to issue Ably {Ably::Models::TokenRequests} with + # a more accurate timestamp should use the queryTime property instead of this method. + # + # @spec RTC6a # - # @yield [Time] The time as reported by the Ably service + # @yield [Time] The time as milliseconds since the Unix epoch. # @return [Ably::Util::SafeDeferrable] # def time(&success_callback) @@ -152,12 +157,15 @@ def time(&success_callback) end end - # Retrieve the stats for the application + # Queries the REST /stats API and retrieves your application's usage statistics. + # Returns a {Ably::Util::SafeDeferrable} object, containing an array of {Ably::Models::Stats} objects. See the Stats docs. + # + # @spec RTC5 # # @param (see Ably::Rest::Client#stats) # @option options (see Ably::Rest::Client#stats) # - # @yield [Ably::Models::PaginatedResult] An Array of Stats + # @yield [Ably::Models::PaginatedResult] A {Ably::Util::SafeDeferrable} object containing an array of {Ably::Models::Stats} objects. # # @return [Ably::Util::SafeDeferrable] # @@ -167,26 +175,38 @@ def stats(options = {}, &success_callback) end end + # Calls {Connection#close} and causes the connection to close, entering the closing state. + # Once closed, the library will not attempt to re-establish the connection without an explicit call to {Connection#connect}. + # @spec RTN12 # (see Ably::Realtime::Connection#close) def close(&block) connection.close(&block) end + # Calls {Ably::Realtime::Connection#connect} and causes the connection to open, entering the connecting + # state. Explicitly calling connect() is unnecessary unless the autoConnect property is disabled. + # @spec RTN11 # (see Ably::Realtime::Connection#connect) def connect(&block) connection.connect(&block) end - # Push notification object for publishing and managing push notifications + # A {Ably::Realtime::Push} object. # @return [Ably::Realtime::Push] def push @push ||= Push.new(self) end - # (see Ably::Rest::Client#request) + # Makes a REST request to a provided path. This is provided as a convenience for developers who wish to use REST + # API functionality that is either not documented or is not yet included in the public API, without having to + # directly handle features such as authentication, paging, fallback hosts, MsgPack and JSON support. + # + # @spec RTC9 + # + # (see {Ably::Rest::Client#request}) # @yield [Ably::Models::HttpPaginatedResponse<>] An Array of Stats # - # @return [Ably::Util::SafeDeferrable] + # @return [Ably::Util::SafeDeferrable] An {Ably::Util::SafeDeferrable} response object returned by the HTTP request, containing an empty or JSON-encodable object. def request(method, path, params = {}, body = nil, headers = {}, &callback) async_wrap(callback) do rest_client.request(method, path, params, body, headers, async_blocking_operations: true) @@ -303,8 +323,9 @@ def fallback_endpoint @fallback_endpoints[fallback_endpoint_index % @fallback_endpoints.count] end - # The local device detilas - # @return [Ably::Models::LocalDevice] + # Retrieves a {Ably::Models::LocalDevice} object that represents the current state of the device as a target for push notifications. + # @spec RSH8 + # @return [Ably::Models::LocalDevice] A {Ably::Models::LocalDevice} object. # # @note This is unsupported in the Ruby library def device From 2914fb8005896e9b87cf7df882d9dc2324b52317 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:53:01 +0200 Subject: [PATCH 19/70] Fix lib/ably/realtime/channels.rb descriptions --- lib/ably/realtime/channels.rb | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/lib/ably/realtime/channels.rb b/lib/ably/realtime/channels.rb index ef52e8d3d..9b814db12 100644 --- a/lib/ably/realtime/channels.rb +++ b/lib/ably/realtime/channels.rb @@ -5,28 +5,29 @@ class Channels include Ably::Modules::ChannelsCollection # @return [Ably::Realtime::Channels] + # def initialize(client) super client, Ably::Realtime::Channel end - # @!method get(name, channel_options = {}) # Return a {Ably::Realtime::Channel} for the given name # # @param name [String] The name of the channel # @param channel_options [Hash, Ably::Models::ChannelOptions] A hash of options or a {Ably::Models::ChannelOptions} - # @return [Ably::Realtime::Channel} + # + # @return [Ably::Realtime::Channel] # def get(*args) super end - # @!method fetch(name, &missing_block) # Return a {Ably::Realtime::Channel} for the given name if it exists, else the block will be called. # 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 # # @param name [String] The name of the channel # @yield [options] (optional) if a missing_block is passed to this method and no channel exists matching the name, this block is called # @yieldparam [String] name of the missing channel + # # @return [Ably::Realtime::Channel] # def fetch(*args) From 27b6a65e1567a886a4d6eb6f756dd72e72e2af45 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:53:12 +0200 Subject: [PATCH 20/70] Fix lib/ably/realtime/channel/push_channel.rb descriptions --- lib/ably/realtime/channel/push_channel.rb | 27 ++++++++++++++--------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/lib/ably/realtime/channel/push_channel.rb b/lib/ably/realtime/channel/push_channel.rb index b88d947bc..eebbf1d71 100644 --- a/lib/ably/realtime/channel/push_channel.rb +++ b/lib/ably/realtime/channel/push_channel.rb @@ -1,10 +1,6 @@ module Ably::Realtime class Channel - # A push channel used for push notifications - # Each PushChannel maps to exactly one Realtime Channel - # - # @!attribute [r] channel - # @return [Ably::Realtime::Channel] Underlying channel object + # Enables devices to subscribe to push notifications for a channel. # class PushChannel attr_reader :channel @@ -18,35 +14,46 @@ def to_s "" end - # Subscribe local device for push notifications on this channel + # Subscribes the device to push notifications for the channel. + # + # @spec RSH7a # # @note This is unsupported in the Ruby library def subscribe_device(*args) raise_unsupported end - # Subscribe all devices registered to this client's authenticated client_id for push notifications on this channel + # Subscribes all devices associated with the current device's clientId to push notifications for the channel. + # + # @spec RSH7b # # @note This is unsupported in the Ruby library def subscribe_client_id(*args) raise_unsupported end - # Unsubscribe local device for push notifications on this channel + # Unsubscribes the device from receiving push notifications for the channel. + # + # @spec RSH7c # # @note This is unsupported in the Ruby library def unsubscribe_device(*args) raise_unsupported end - # Unsubscribe all devices registered to this client's authenticated client_id for push notifications on this channel + # Unsubscribes all devices associated with the current device's clientId from receiving push notifications for the channel. + # + # @spec RSH7d # # @note This is unsupported in the Ruby library def unsubscribe_client_id(*args) raise_unsupported end - # Get list of subscriptions on this channel for this device or authenticate client_id + # Retrieves all push subscriptions for the channel. Subscriptions can be filtered using a params object. + # Returns a {Ably::Models::PaginatedResult} object containing an array of {Ably::Models::PushChannelSubscription} objects. + # + # @spec RSH7e # # @note This is unsupported in the Ruby library def get_subscriptions(*args) From f550994b53282c6362fed8f6dc61c16e277fb623 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:53:24 +0200 Subject: [PATCH 21/70] Fix lib/ably/realtime/channel/publisher.rb descriptions --- lib/ably/realtime/channel/publisher.rb | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lib/ably/realtime/channel/publisher.rb b/lib/ably/realtime/channel/publisher.rb index d7da60479..83b3dd85e 100644 --- a/lib/ably/realtime/channel/publisher.rb +++ b/lib/ably/realtime/channel/publisher.rb @@ -5,7 +5,9 @@ module Publisher private # Prepare and queue messages on the connection queue immediately + # # @return [Ably::Util::SafeDeferrable] + # def enqueue_messages_on_connection(client, raw_messages, channel_name, channel_options = {}) messages = Array(raw_messages).map do |raw_msg| create_message(client, raw_msg, channel_options).tap do |message| From fe6941dc041077b9ba0d58a5a8dc8004d28e0db8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:53:39 +0200 Subject: [PATCH 22/70] Fix lib/ably/realtime/channel/channel_properties.rb descriptions --- lib/ably/realtime/channel/channel_properties.rb | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/lib/ably/realtime/channel/channel_properties.rb b/lib/ably/realtime/channel/channel_properties.rb index 0f15b1ba0..26ddf2622 100644 --- a/lib/ably/realtime/channel/channel_properties.rb +++ b/lib/ably/realtime/channel/channel_properties.rb @@ -1,14 +1,21 @@ module Ably::Realtime class Channel - # Represents properties of a channel and its state + # Describes the properties of the channel state. class ChannelProperties # {Ably::Realtime::Channel} this object associated with + # # @return [Ably::Realtime::Channel] + # attr_reader :channel - # Contains the last channelSerial received in an ATTACHED ProtocolMesage for the channel, see RTL15a + # Starts unset when a channel is instantiated, then updated with the channelSerial from each + # {Ably::Realtime::Channel::STATE.Attached} event that matches the channel. + # Used as the value for {Ably::Realtime::Channel#history}. + # + # @spec CP2a # # @return [String] + # attr_reader :attach_serial def initialize(channel) From 601d03be483820342949e7bb104cb6621f40c5d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:53:57 +0200 Subject: [PATCH 23/70] Fix lib/ably/realtime/channel.rb descriptions --- lib/ably/realtime/channel.rb | 121 +++++++++++++++++++++++------------ 1 file changed, 79 insertions(+), 42 deletions(-) diff --git a/lib/ably/realtime/channel.rb b/lib/ably/realtime/channel.rb index 33fa71bcd..7fc3ea464 100644 --- a/lib/ably/realtime/channel.rb +++ b/lib/ably/realtime/channel.rb @@ -2,10 +2,8 @@ module Ably module Realtime - # The Channel class represents a Channel belonging to this application. - # The Channel instance allows messages to be published and - # received, and controls the lifecycle of this instance's - # attachment to the channel. + # Enables messages to be published and subscribed to. Also enables historic messages to be retrieved and provides + # access to the {Ably::Realtime::Channel} object of a channel. # # Channels will always be in one of the following states: # @@ -18,15 +16,17 @@ module Realtime # # Note that the states are available as Enum-like constants: # - # Channel::STATE.Initialized - # Channel::STATE.Attaching - # Channel::STATE.Attached - # Channel::STATE.Detaching - # Channel::STATE.Detached - # Channel::STATE.Failed - # - # @!attribute [r] state - # @return {Ably::Realtime::Channel::STATE} channel state + # Channel::STATE.Initialized The channel has been initialized but no attach has yet been attempted. + # Channel::STATE.Attaching An attach has been initiated by sending a request to Ably. + # This is a transient state, followed either by a transition to ATTACHED, SUSPENDED, or FAILED. + # 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. + # Channel::STATE.Detaching A detach has been initiated on an ATTACHED channel by sending a request to Ably. + # This is a transient state, followed either by a transition to DETACHED or FAILED. + # Channel::STATE.Detached The channel, having previously been ATTACHED, has been detached by the user. + # Channel::STATE.Suspended The channel, having previously been ATTACHED, has lost continuity, usually due to + # the client being disconnected from Ably for longer than two minutes. It will automatically attempt to reattach as soon as connectivity is restored. + # Channel::STATE.Failed An indefinite failure condition. This state is entered if a channel error + # has been received from the Ably service, such as an attempt to attach without the necessary access rights. # class Channel include Ably::Modules::Conversions @@ -38,7 +38,10 @@ class Channel extend Ably::Modules::Enum extend Forwardable - # ChannelState + # The current {Abbly::Realtime::Channel::STATE} of the channel. + # + # @spec RTL2b + # # The permited states for this channel STATE = ruby_enum('STATE', :initialized, @@ -50,8 +53,13 @@ class Channel :failed ) - # ChannelEvent + # Describes the events emitted by a {Ably::Rest::Channel} or {Ably::Realtime::Channel} object. + # An event is either an UPDATE or a {Ably::Rest::Channel::STATE}. + # # The permitted channel events that are emitted for this channel + # + # @spec RTL2g + # EVENT = ruby_enum('EVENT', STATE.to_sym_arr + [:update] ) @@ -64,15 +72,18 @@ class Channel MAX_PROTOCOL_MESSAGE_BATCH_SIZE = 50 # {Ably::Realtime::Client} associated with this channel + # # @return [Ably::Realtime::Client] + # # @api private attr_reader :client - # Channel name + # The channel name. # @return [String] attr_reader :name - # Push channel used for push notification + # A {Ably::Realtime::Channel::PushChannel} object. + # # @return [Ably::Realtime::Channel::PushChannel] attr_reader :push @@ -80,11 +91,15 @@ class Channel # @return [Hash] attr_reader :options - # Properties of a channel and its state + # A {Ably::Realtime::Channel::ChannelProperties} object. + # + # @spec CP1, RTL15 + # # @return [{Ably::Realtime::Channel::ChannelProperties}] attr_reader :properties - # When a channel failure occurs this attribute contains the Ably Exception + # An {Ably::Models::ErrorInfo} object describing the last error which occurred on the channel, if any. + # @spec RTL4e # @return [Ably::Models::ErrorInfo,Ably::Exceptions::BaseAblyException] attr_reader :error_reason @@ -94,11 +109,12 @@ class Channel attr_reader :manager # Flag that specifies whether channel is resuming attachment(reattach) or is doing a 'clean attach' RTL4j1 - # @return [Bolean] + # @return [Boolean] # @api private attr_reader :attach_resume - # ChannelOptions params attrribute (#RTL4k) + # Optional channel parameters that configure the behavior of the channel. + # @spec RTL4k1 # return [Hash] def_delegators :options, :params @@ -127,9 +143,11 @@ def initialize(client, name, channel_options = {}) setup_presence end - # Publish one or more messages to the channel. + # Publish a message to the channel. A callback may optionally be passed in to this call to be notified of success + # or failure of the operation. When publish is called with this client library, it won't attempt to implicitly + # attach to the channel. # - # When publishing a message, if the channel is not attached, the channel is implicitly attached + # @spec RTL6i # # @param name [String, Array, 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 # @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 @@ def publish(name, data = nil, attributes = {}, &success_block) end end - # Subscribe to messages matching providing event name, or all messages if event name not provided. + # Registers a listener for messages on this channel. The caller supplies a listener function, which is called + # each time one or more messages arrives on the channel. A callback may optionally be passed in to this call + # to be notified of success or failure of the channel {Ably::Realtime::Channel#attach} operation. # - # When subscribing to messages, if the channel is not attached, the channel is implicitly attached + # @spec RTL7a # # @param names [String] The event name of the message to subscribe to if provided. Defaults to all events. # @yield [Ably::Models::Message] For each message received, the block is called @@ -209,8 +229,9 @@ def subscribe(*names, &callback) super end - # Unsubscribe the matching block for messages matching providing event name, or all messages if event name not provided. - # If a block is not provided, all subscriptions will be unsubscribed + # Deregisters the given listener for the specified event name(s). This removes an earlier event-specific subscription. + # + # @spec RTL8a # # @param names [String] The event name of the message to subscribe to if provided. Defaults to all events. # @@ -220,9 +241,15 @@ def unsubscribe(*names, &callback) super end - # Attach to this channel, and call the block if provided when attached. - # Attaching to a channel is implicit in when a message is published or #subscribe is called, so it is uncommon - # to need to call attach explicitly. + # Attach to this channel ensuring the channel is created in the Ably system and all messages published on + # the channel are received by any channel listeners registered using {Ably::Realtime::Channel#subscribe}. + # Any resulting channel state change will be emitted to any listeners registered using the {Ably::Modules::EventEmitter#on} + # or {Ably::Modules::EventEmitter#once} methods. A callback may optionally be passed in to this call to be notified + # of success or failure of the operation. As a convenience, attach() is called implicitly + # if {Ably::Realtime::Channel#subscribe} for the channel is called, or {Ably::Realtime::Presence#enter} + # or {Ably::Realtime::Presence#subscribe} are called on the {Ably::Realtime::Presence} object for this channel. + # + # @spec RTL4d # # @yield [Ably::Realtime::Channel] Block is called as soon as this channel is in the Attached state # @return [Ably::Util::SafeDeferrable] Deferrable that supports both success (callback) and failure (errback) callback @@ -245,7 +272,12 @@ def attach(&success_block) deferrable_for_state_change_to(STATE.Attached, &success_block) end - # Detach this channel, and call the block if provided when in a Detached or Failed state + # Detach from this channel. Any resulting channel state change is emitted to any listeners registered using + # the {Ably::Modules::EventEmitter#on} or {Ably::Modules::EventEmitter#once} methods. A callback may optionally + # be passed in to this call to be notified of success or failure of the operation. Once all clients globally + # have detached from the channel, the channel will be released in the Ably service within two minutes. + # + # @spec RTL5e # # @yield [Ably::Realtime::Channel] Block is called as soon as this channel is in the Detached or Failed state # @return [Ably::Util::SafeDeferrable] Deferrable that supports both success (callback) and failure (errback) callback @@ -274,9 +306,9 @@ def detach(&success_block) deferrable_for_state_change_to(STATE.Detached, &success_block) end - # Presence object for this Channel. This controls this client's - # presence on the channel and may also be used to obtain presence information - # and change events for other members of the channel. + # A {Ably::Realtime::Presence} object. + # + # @spec RTL9 # # @return {Ably::Realtime::Presence} # @@ -284,14 +316,15 @@ def presence @presence end - # Return the message history of the channel + # Retrieves a {Ably::Models::PaginatedResult} object, containing an array of historical + # {Ably::Models::Message} objects for the channel. If the channel is configured to persist messages, + # then messages can be retrieved from history for up to 72 hours in the past. If not, messages can only + # be retrieved from history for up to two minutes in the past. # - # If the channel is attached, you can retrieve messages published on the channel before the - # channel was attached with the option until_attach: true. This is useful when a developer - # wishes to display historical messages with the guarantee that no messages have been missed since attach. + # @spec RSL2a # - # @param (see Ably::Rest::Channel#history) - # @option options (see Ably::Rest::Channel#history) + # @param (see {Ably::Rest::Channel#history}) + # @option options (see {Ably::Rest::Channel#history}) # @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 # # @yield [Ably::Models::PaginatedResult] First {Ably::Models::PaginatedResult page} of {Ably::Models::Message} objects accessible with {Ably::Models::PaginatedResult#items #items}. @@ -312,8 +345,8 @@ def history(options = {}, &callback) end end - # @!attribute [r] __incoming_msgbus__ # @return [Ably::Util::PubSub] Client library internal channel incoming message bus + # # @api private def __incoming_msgbus__ @__incoming_msgbus__ ||= Ably::Util::PubSub.new( @@ -321,7 +354,11 @@ def __incoming_msgbus__ ) end - # Sets or updates the stored channel options. (#RTL16) + # Sets the {Ably::Models::ChannelOptions} for the channel. + # An optional callback may be provided to notify of the success or failure of the operation. + # + # @spec RTL16 + # # @param channel_options [Hash, Ably::Models::ChannelOptions] A hash of options or a {Ably::Models::ChannelOptions} # @return [Ably::Models::ChannelOptions] def set_options(channel_options) From 1f42cc098450edf1d662898f6cd63d6886b15230 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:54:06 +0200 Subject: [PATCH 24/70] Fix lib/ably/modules/state_machine.rb descriptions --- lib/ably/modules/state_machine.rb | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/lib/ably/modules/state_machine.rb b/lib/ably/modules/state_machine.rb index 38ad9c23e..87502a0ea 100644 --- a/lib/ably/modules/state_machine.rb +++ b/lib/ably/modules/state_machine.rb @@ -20,6 +20,7 @@ def self.included(klass) # * log state change failures to {Logger} # # @return [void] + # def transition_state(state, *args) unless result = transition_to(state.to_sym, *args) exception = exception_for_state_change_to(state) @@ -29,16 +30,19 @@ def transition_state(state, *args) end # @return [Statesman History Object] + # def previous_transition history[-2] end # @return [Symbol] + # def previous_state previous_transition.to_state if previous_transition end # @return [Ably::Exceptions::InvalidStateChange] + # def exception_for_state_change_to(state) error_message = "#{self.class}: Unable to transition from #{current_state} => #{state}" Ably::Exceptions::InvalidStateChange.new(error_message, nil, Ably::Exceptions::Codes::CHANNEL_OPERATION_FAILED_INVALID_CHANNEL_STATE) From 9cb72e839e076c3a507d9b01ed8e5473162b172a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:54:19 +0200 Subject: [PATCH 25/70] Fix lib/ably/modules/state_emitter.rb descriptions --- lib/ably/modules/state_emitter.rb | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lib/ably/modules/state_emitter.rb b/lib/ably/modules/state_emitter.rb index 075702611..c638cb9a4 100644 --- a/lib/ably/modules/state_emitter.rb +++ b/lib/ably/modules/state_emitter.rb @@ -35,6 +35,7 @@ module StateEmitter # Current state {Ably::Modules::Enum} # # @return [Symbol] state + # def state STATE(@state) end @@ -42,6 +43,7 @@ def state # Evaluates if check_state matches current state # # @return [Boolean] + # def state?(check_state) state == check_state end From 85c486bf83f2ff1708da72405a10e5ee7a1f4f0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:54:31 +0200 Subject: [PATCH 26/70] Fix lib/ably/modules/model_common.rb descriptions --- lib/ably/modules/model_common.rb | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/lib/ably/modules/model_common.rb b/lib/ably/modules/model_common.rb index 121ff7fd6..f07c6aa6d 100644 --- a/lib/ably/modules/model_common.rb +++ b/lib/ably/modules/model_common.rb @@ -15,6 +15,7 @@ def self.included(base) # Provide a normal Hash accessor to the underlying raw message object # # @return [Object] + # def [](key) attributes[key] end @@ -25,13 +26,17 @@ def ==(other) end # Return a JSON ready object from the underlying #attributes using Ably naming conventions for keys + # # @return [Hash] + # def as_json(*args) attributes.as_json.reject { |key, val| val.nil? } end # Stringify the JSON representation of this object from the underlying #attributes + # # @return [String] + # def to_json(*args) as_json.to_json(*args) end From 79d6c03fcc2372393c7cc084fb1352a7937b43c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:54:42 +0200 Subject: [PATCH 27/70] Fix lib/ably/modules/event_emitter.rb descriptions --- lib/ably/modules/event_emitter.rb | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/lib/ably/modules/event_emitter.rb b/lib/ably/modules/event_emitter.rb index 749c8ec07..b777b29ce 100644 --- a/lib/ably/modules/event_emitter.rb +++ b/lib/ably/modules/event_emitter.rb @@ -46,9 +46,12 @@ def inherited(subclass) # On receiving an event matching the event_name, call the provided block # + # @spec RTE4 + # # @param [Array] event_names event name # # @return [void] + # def on(*event_names, &block) add_callback event_names, proc_for_block(block) end @@ -62,9 +65,12 @@ def unsafe_on(*event_names, &block) # On receiving an event maching the event_name, call the provided block only once and remove the registered callback # + # @spec RTE4 + # # @param [Array] event_names event name # # @return [void] + # def once(*event_names, &block) add_callback event_names, proc_for_block(block, delete_once_run: true) end @@ -76,7 +82,11 @@ def unsafe_once(*event_names, &block) add_callback event_names, proc_for_block(block, delete_once_run: true, unsafe: true) end - # Emit an event with event_name that will in turn call all matching callbacks setup with `on` + # Emits an event, calling registered listeners with the given event name and any other given arguments. + # 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. + # + # @spec RTE6 + # def emit(event_name, *args) [callbacks_any, callbacks[callbacks_event_coerced(event_name)]].each do |callback_arr| callback_arr.clone. @@ -97,9 +107,12 @@ def emit(event_name, *args) # If a block is provided, only callbacks matching that block signature will be removed. # If block is not provided, all callbacks matching the event_name will be removed. # + # @spec RTE5 + # # @param [Array] event_names event name # # @return [void] + # def off(*event_names, &block) off_internal(false, *event_names, &block) end From ab324bc9c66027454167a15adae5bc03fb0aac80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:55:01 +0200 Subject: [PATCH 28/70] Fix lib/ably/modules/enum.rb descriptions --- lib/ably/modules/enum.rb | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lib/ably/modules/enum.rb b/lib/ably/modules/enum.rb index 14f6b1898..8e5735ce9 100644 --- a/lib/ably/modules/enum.rb +++ b/lib/ably/modules/enum.rb @@ -90,7 +90,9 @@ def name end # Array of Enum values as symbols + # # @return [Array] + # def to_sym_arr @by_symbol.keys end From 174a525fbb832a236725a5768910319360e44df7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:55:13 +0200 Subject: [PATCH 29/70] Fix lib/ably/modules/async_wrapper.rb descriptions --- lib/ably/modules/async_wrapper.rb | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/ably/modules/async_wrapper.rb b/lib/ably/modules/async_wrapper.rb index 069b68e84..8bb9d431f 100644 --- a/lib/ably/modules/async_wrapper.rb +++ b/lib/ably/modules/async_wrapper.rb @@ -36,6 +36,7 @@ module AsyncWrapper # Will yield the provided block in a new thread and return an {Ably::Util::SafeDeferrable} # # @yield [Object] operation block that is run in a thread + # # @return [Ably::Util::SafeDeferrable] # def async_wrap(success_callback = nil, custom_error_handling = nil) From b523cfc4a81a3f3a0304734108dd9ce26a3be421 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:55:24 +0200 Subject: [PATCH 30/70] Fix lib/ably/models/token_request.rb descriptions --- lib/ably/models/token_request.rb | 50 +++++++++++++++++++++++--------- 1 file changed, 37 insertions(+), 13 deletions(-) diff --git a/lib/ably/models/token_request.rb b/lib/ably/models/token_request.rb index d41a50559..7036dfef5 100644 --- a/lib/ably/models/token_request.rb +++ b/lib/ably/models/token_request.rb @@ -4,6 +4,7 @@ module Ably::Models # @param attributes (see #initialize) # # @return [TokenRequest] + # def self.TokenRequest(attributes) case attributes when TokenRequest @@ -14,10 +15,7 @@ def self.TokenRequest(attributes) end - # TokenRequest is a class that stores the attributes of a token request - # - # 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 - # it must always be expressed in milliseconds as the Ably API always uses milliseconds for time fields. + # Contains the properties of a request for a token to Ably. Tokens are generated using {Ably::Auth#requestToken}. # class TokenRequest include Ably::Modules::ModelCommon @@ -39,13 +37,17 @@ def initialize(attributes = {}) self.attributes.freeze end - # @!attribute [r] key_name + # The name of the key against which this request is made. The key name is public, whereas the key secret is private. + # @spec TE2 # @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 +:+ def key_name attributes.fetch(:key_name) { raise Ably::Exceptions::InvalidTokenRequest, 'Key name is missing' } end - # @!attribute [r] ttl + # Requested time to live for the Ably Token in milliseconds. If the Ably TokenRequest is successful, the TTL of the + # returned Ably Token is less than or equal to this value, depending on application settings and the attributes of + # the issuing key. The default is 60 minutes. + # @spec TE4 # @return [Integer] requested time to live for the token in seconds. If the token request is successful, # the TTL of the returned token will be less than or equal to this value depending on application # settings and the attributes of the issuing key. @@ -54,7 +56,11 @@ def ttl attributes.fetch(:ttl) / 1000 end - # @!attribute [r] capability + # Capability of the requested Ably Token. If the Ably TokenRequest is successful, the capability of the returned + # Ably Token will be the intersection of this capability with the capability of the issuing key. The capabilities + # value is a JSON-encoded representation of the resource paths and associated operations. Read more about + # capabilities in the capabilities docs. + # @spec TE3 # @return [Hash] capability of the token. If the token request is successful, # the capability of the returned token will be the intersection of # this capability with the capability of the issuing key. @@ -71,14 +77,17 @@ def capability end end - # @!attribute [r] client_id + # The client ID to associate with the requested Ably Token. When provided, the Ably Token may only be used to + # perform operations on behalf of that client ID. + # @spec TE2 # @return [String] the client ID to associate with this token. The generated token # may be used to authenticate as this clientId. def client_id attributes[:client_id] end - # @!attribute [r] timestamp + # The timestamp of this request as milliseconds since the Unix epoch. + # @spec TE5 # @return [Time] the timestamp of this request. # Timestamps, in conjunction with the nonce, are used to prevent # token requests from being replayed. @@ -88,7 +97,8 @@ def timestamp as_time_from_epoch(timestamp_val, granularity: :ms) end - # @!attribute [r] nonce + # A cryptographically secure random string of at least 16 characters, used to ensure the TokenRequest cannot be reused. + # @spec TE2 # @return [String] an opaque nonce string of at least 16 characters to ensure # uniqueness of this request. Any subsequent request using the # same nonce will be rejected. @@ -96,9 +106,9 @@ def nonce attributes.fetch(:nonce) { raise Ably::Exceptions::InvalidTokenRequest, 'Nonce is missing' } end - # @!attribute [r] mac + # The Message Authentication Code for this request. + # @spec TE2 # @return [String] the Message Authentication Code for this request. See the - # {https://www.ably.com/docs Ably Authentication documentation} for more details. def mac attributes.fetch(:mac) { raise Ably::Exceptions::InvalidTokenRequest, 'MAC is missing' } end @@ -110,10 +120,24 @@ def persisted attributes[:persisted] end - # @!attribute [r] attributes # @return [Hash] the token request Hash object ruby'fied to use symbolized keys + # def attributes @hash_object end + + # A static factory method to create a TokenRequest object from a deserialized TokenRequest-like object or a JSON + # stringified TokenRequest object. This method is provided to minimize bugs as a result of differing types by platform + # for fields such as timestamp or ttl. For example, in Ruby ttl in the TokenRequest object is exposed in seconds as + # that is idiomatic for the language, yet when serialized to JSON using to_json it is automatically converted to + # the Ably standard which is milliseconds. By using the fromJson() method when constructing a TokenRequest object, + # Ably ensures that all fields are consistently serialized and deserialized across platforms. + # + # @overload from_json(json_like_object) + # @spec TE6 + # @param json_like_object [Hash, String] A deserialized TokenRequest-like object or a JSON stringified TokenRequest object to create a TokenRequest. + # + # @return [Ably::Models::TokenRequest] An Ably token request object. + # end end From 3e0786354ba0c6056411fe1f679dcae2a231366e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:55:36 +0200 Subject: [PATCH 31/70] Fix lib/ably/models/token_details.rb descriptions --- lib/ably/models/token_details.rb | 46 +++++++++++++++++++++++--------- 1 file changed, 34 insertions(+), 12 deletions(-) diff --git a/lib/ably/models/token_details.rb b/lib/ably/models/token_details.rb index 7745b90e8..99510ab4d 100644 --- a/lib/ably/models/token_details.rb +++ b/lib/ably/models/token_details.rb @@ -4,6 +4,7 @@ module Ably::Models # @param attributes (see #initialize) # # @return [TokenDetails] + # def self.TokenDetails(attributes) case attributes when TokenDetails @@ -13,11 +14,7 @@ def self.TokenDetails(attributes) end end - # TokenDetails is a class providing details of the token string and the token's associated metadata, - # constructed from the response from Ably when request in a token via the REST API. - # - # 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 - # it must always be expressed in milliseconds as the Ably API always uses milliseconds for time fields. + # Contains an Ably Token and its associated metadata. # class TokenDetails include Ably::Modules::ModelCommon @@ -46,31 +43,39 @@ def initialize(attributes = {}) self.attributes.freeze end - # @!attribute [r] token + # The Ably Token itself. A typical Ably Token string appears with the form xVLyHw.A-pwh7wicf3afTfgiw4k2Ku33kcnSA7z6y8FjuYpe3QaNRTEo4. + # + # @spec TD2 + # # @return [String] Token used to authenticate requests + # def token attributes[:token] end - # @!attribute [r] key_name # @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 +:+ + # def key_name attributes[:key_name] end - # @!attribute [r] issued + # The timestamp at which this token was issued as milliseconds since the Unix epoch. + # @spec TD4 # @return [Time] Time the token was issued def issued as_time_from_epoch(attributes[:issued], granularity: :ms, allow_nil: :true) end - # @!attribute [r] expires + # The timestamp at which this token expires as milliseconds since the Unix epoch. + # @spec TD3 # @return [Time] Time the token expires def expires as_time_from_epoch(attributes[:expires], granularity: :ms, allow_nil: :true) end - # @!attribute [r] capability + # The capabilities associated with this Ably Token. The capabilities value is a JSON-encoded representation of the + # resource paths and associated operations. Read more about capabilities in the capabilities docs. + # @spec TD5 # @return [Hash] Capabilities assigned to this token def capability if attributes.has_key?(:capability) @@ -86,7 +91,10 @@ def capability end end - # @!attribute [r] client_id + # The client ID, if any, bound to this Ably Token. If a client ID is included, then the Ably Token authenticates its + # bearer as that client ID, and the Ably Token may only be used to perform operations on behalf of that client ID. + # The client is then considered to be an identified client. + # @spec TD6 # @return [String] Optional client ID assigned to this token def client_id attributes[:client_id] @@ -113,8 +121,8 @@ def from_token_string? attributes.keys == [:token] end - # @!attribute [r] attributes # @return [Hash] Access the token details Hash object ruby'fied to use symbolized keys + # def attributes @hash_object end @@ -122,5 +130,19 @@ def attributes def to_s "" end + + # A static factory method to create a {Ably::Models::TokenDetails} object from a deserialized {Ably::Models::TokenDetails}-like + # object or a JSON stringified TokenDetails object. This method is provided to minimize bugs as a result of differing + # types by platform for fields such as timestamp or ttl. For example, in Ruby ttl in the {Ably::Models::TokenDetails} + # object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using to_json it + # is automatically converted to the Ably standard which is milliseconds. By using the fromJson() method when constructing + # a {Ably::Models::TokenDetails} object, Ably ensures that all fields are consistently serialized and deserialized across platforms. + # + # @overload from_json(json_like_object) + # @spec TD7 + # @param json_like_object [Hash, String] A deserialized TokenDetails-like object or a JSON stringified TokenDetails object. + # + # @return [Ably::Models::TokenDetails] An Ably authentication token. + # end end From 016095d5cf8f2c48b2460076b14e878283b144e4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:55:48 +0200 Subject: [PATCH 32/70] Fix lib/ably/models/stats_types.rb descriptions --- lib/ably/models/stats_types.rb | 56 ++++++++++------------------------ 1 file changed, 16 insertions(+), 40 deletions(-) diff --git a/lib/ably/models/stats_types.rb b/lib/ably/models/stats_types.rb index 1f1c19441..54eaa8672 100644 --- a/lib/ably/models/stats_types.rb +++ b/lib/ably/models/stats_types.rb @@ -59,71 +59,47 @@ def self.new(value) end # MessageCount contains aggregate counts for messages and data transferred - # @!attribute [r] count - # @return [Integer] count of all messages - # @!attribute [r] data - # @return [Integer] total data transferred for all messages in bytes + # + # @spec TS5a, TS5b + # class MessageCount < StatsStruct coerce_attributes :count, :data, into: IntegerDefaultZero end # RequestCount contains aggregate counts for requests made - # @!attribute [r] succeeded - # @return [Integer] requests succeeded - # @!attribute [r] failed - # @return [Integer] requests failed - # @!attribute [r] refused - # @return [Integer] requests refused typically as a result of permissions or a limit being exceeded + # + # @spec TS8a, TS8b, TS8c + # class RequestCount < StatsStruct coerce_attributes :succeeded, :failed, :refused, into: IntegerDefaultZero end # ResourceCount contains aggregate data for usage of a resource in a specific scope - # @!attribute [r] opened - # @return [Integer] total resources of this type opened - # @!attribute [r] peak - # @return [Integer] peak resources of this type used for this period - # @!attribute [r] mean - # @return [Integer] average resources of this type used for this period - # @!attribute [r] min - # @return [Integer] minimum total resources of this type used for this period - # @!attribute [r] refused - # @return [Integer] resource requests refused within this period + # class ResourceCount < StatsStruct coerce_attributes :opened, :peak, :mean, :min, :refused, into: IntegerDefaultZero end # ConnectionTypes contains a breakdown of summary stats data for different (TLS vs non-TLS) connection types - # @!attribute [r] tls - # @return [ResourceCount] TLS connection count - # @!attribute [r] plain - # @return [ResourceCount] non-TLS connection count (unencrypted) - # @!attribute [r] all - # @return [ResourceCount] all connection count (includes both TLS & non-TLS connections) + # + # @spec TS4a, TS4b, TS4c + # class ConnectionTypes < StatsStruct coerce_attributes :tls, :plain, :all, into: ResourceCount end # MessageTypes contains a breakdown of summary stats data for different (message vs presence) message types - # @!attribute [r] messages - # @return [MessageCount] count of channel messages - # @!attribute [r] presence - # @return [MessageCount] count of presence messages - # @!attribute [r] all - # @return [MessageCount] all messages count (includes both presence & messages) + # + # @spec TS6a, TS6b, TS6c + # class MessageTypes < StatsStruct coerce_attributes :messages, :presence, :all, into: MessageCount end # MessageTraffic contains a breakdown of summary stats data for traffic over various transport types - # @!attribute [r] realtime - # @return [MessageTypes] count of messages transferred over a realtime transport such as WebSockets - # @!attribute [r] rest - # @return [MessageTypes] count of messages transferred using REST - # @!attribute [r] webhook - # @return [MessageTypes] count of messages delivered using WebHooks - # @!attribute [r] all - # @return [MessageTypes] all messages count (includes realtime, rest and webhook messages) + # + # @spec TS7a, TS7b, TS7c, TS7d + # class MessageTraffic < StatsStruct coerce_attributes :realtime, :rest, :webhook, :all, into: MessageTypes end From ef3ebb26cadca5e3a77df53938fe1d7bb0b2d241 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:55:59 +0200 Subject: [PATCH 33/70] Fix lib/ably/models/stats.rb descriptions --- lib/ably/models/stats.rb | 116 +++++++++++++++++++++++++-------------- 1 file changed, 76 insertions(+), 40 deletions(-) diff --git a/lib/ably/models/stats.rb b/lib/ably/models/stats.rb index be38a5ab2..f7d919998 100644 --- a/lib/ably/models/stats.rb +++ b/lib/ably/models/stats.rb @@ -17,27 +17,17 @@ def self.Stats(stat) # A class representing an individual statistic for a specified {#interval_id} # - # @!attribute [r] all - # @return [Stats::MessageTypes] Breakdown of summary stats for all message types - # @!attribute [r] inbound - # @return [Stats::MessageTraffic] Breakdown of summary stats for traffic over various transport types for all inbound messages - # @!attribute [r] outbound - # @return [Stats::MessageTraffic] Breakdown of summary stats for traffic over various transport types for all outbound messages - # @!attribute [r] persisted - # @return [Stats::MessageTypes] Breakdown of summary stats for all persisted messages - # @!attribute [r] connections - # @return [Stats::ConnectionTypes] A breakdown of summary stats data for different (TLS vs non-TLS) connection types. - # @!attribute [r] channels - # @return [Stats::ResourceCount] Aggregate data for usage of Channels - # @!attribute [r] api_requests - # @return [Stats::RequestCount] Aggregate data for numbers of API requests - # @!attribute [r] token_requests - # @return [Stats::RequestCount] Aggregate data for numbers of Token requests - # class Stats include Ably::Modules::ModelCommon extend Ably::Modules::Enum + # Describes the interval unit over which statistics are gathered. + # + # MINUTE Interval unit over which statistics are gathered as minutes. + # HOUR Interval unit over which statistics are gathered as hours. + # DAY Interval unit over which statistics are gathered as days. + # MONTH Interval unit over which statistics are gathered as months. + # GRANULARITY = ruby_enum('GRANULARITY', :minute, :hour, @@ -88,13 +78,13 @@ def from_interval_id(interval_id) Time.strptime("#{interval_id} +0000", "#{format} %z").utc end - # Returns the {GRANULARITY} determined from the interval_id + # Returns the {Symbol} determined from the interval_id # @example # Stats.granularity_from_interval_id('2015-01-01:10') # => :hour # # @param interval_id [String] # - # @return [GRANULARITY] Granularity Enum for the interval_id + # @return [Symbol] # def granularity_from_interval_id(interval_id) raise ArgumentError, 'Interval ID must be a string' unless interval_id.kind_of?(String) @@ -120,68 +110,114 @@ def initialize(hash_object) set_attributes_object hash_object end - # Aggregates inbound and outbound messages - # @return {Stats::MessageTypes} + # A {Ably::Models::Stats::MessageTypes} object containing the aggregate count of all message stats. + # + # @spec TS12e + # + # @return [Stats::MessageTypes] + # def all @all ||= Stats::MessageTypes.new(attributes[:all]) end - # All inbound messages i.e. received by Ably from clients - # @return {Stats::MessageTraffic} + # A {Ably::Models::Stats::MessageTraffic} object containing the aggregate count of inbound message stats. + # + # @spec TS12f + # + # @return [Ably::Models::Stats::MessageTraffic] + # def inbound @inbound ||= Stats::MessageTraffic.new(attributes[:inbound]) end - # All outbound messages i.e. sent from Ably to clients - # @return {Stats::MessageTraffic} + # A {Ably::Models::Stats::MessageTraffic} object containing the aggregate count of outbound message stats. + # + # @spec TS12g + # + # @return [Ably::Models::Stats::MessageTraffic] + # def outbound @outbound ||= Stats::MessageTraffic.new(attributes[:outbound]) end - # Messages persisted for later retrieval via the history API - # @return {Stats::MessageTypes} + # A {Ably::Models::Stats::MessageTraffic} object containing the aggregate count of persisted message stats. + # + # @spec TS12h + # + # @return [Ably::Models::Stats::MessageTraffic] + # def persisted @persisted ||= Stats::MessageTypes.new(attributes[:persisted]) end - # Breakdown of connection stats data for different (TLS vs non-TLS) connection types - # @return {Stats::ConnectionTypes} + # A {Ably::Models::Stats::ConnectionTypes} object containing a breakdown of connection related stats, such as min, mean and peak connections. + # + # @spec TS12i + # + # @return [Ably::Models::Stats::ConnectionTypes] + # def connections @connections ||= Stats::ConnectionTypes.new(attributes[:connections]) end - # Breakdown of channels stats - # @return {Stats::ResourceCount} + # A {Ably::Models::Stats::ResourceCount} object containing a breakdown of connection related stats, such as min, mean and peak connections. + # + # @spec TS12j + # + # @return [Ably::Models::Stats::ResourceCount] + # def channels @channels ||= Stats::ResourceCount.new(attributes[:channels]) end - # Breakdown of API requests received via the REST API - # @return {Stats::RequestCount} + # A {Ably::Models::Stats::RequestCount} object containing a breakdown of API Requests. + # + # @spec TS12k + # + # @return [Ably::Models::Stats::RequestCount] + # def api_requests @api_requests ||= Stats::RequestCount.new(attributes[:api_requests]) end - # Breakdown of Token requests received via the REST API - # @return {Stats::RequestCount} + # A {Ably::Models::Stats::RequestCount} object containing a breakdown of Ably Token requests. + # + # @spec TS12l + # + # @return [Ably::Models::Stats::RequestCount] + # def token_requests @token_requests ||= Stats::RequestCount.new(attributes[:token_requests]) end - # @!attribute [r] interval_id - # @return [String] The interval that this statistic applies to, see {GRANULARITY} and {INTERVAL_FORMAT_STRING} + # The UTC time at which the time period covered begins. If unit is set to minute this will be in + # 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 + # and if month it will be YYYY-mm-01:00. + # + # @spec TS12a + # + # @return [String] + # def interval_id attributes.fetch(:interval_id) end - # @!attribute [r] interval_time - # @return [Time] A Time object representing the start of the interval + # Represents the intervalId as a time object. + # + # @spec TS12b + # + # @return [Time] + # def interval_time self.class.from_interval_id(interval_id) end - # @!attribute [r] interval_granularity + # The length of the interval the stats span. Values will be a [StatsIntervalGranularity]{@link StatsIntervalGranularity}. + # + # @spec TS12c + # # @return [GRANULARITY] The granularity of the interval for the stat such as :day, :hour, :minute, see {GRANULARITY} + # def interval_granularity self.class.granularity_from_interval_id(interval_id) end From 89aed93bda9ce38f31e7e7923e2fedad6b81ff27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:56:09 +0200 Subject: [PATCH 34/70] Fix lib/ably/models/push_channel_subscription.rb descriptions --- lib/ably/models/push_channel_subscription.rb | 55 ++++++++++++++------ 1 file changed, 40 insertions(+), 15 deletions(-) diff --git a/lib/ably/models/push_channel_subscription.rb b/lib/ably/models/push_channel_subscription.rb index c628f2b84..ff2c0e58e 100644 --- a/lib/ably/models/push_channel_subscription.rb +++ b/lib/ably/models/push_channel_subscription.rb @@ -6,6 +6,7 @@ module Conversions # @param push_channel_subscription [Ably::Models::PushChannelSubscription,Hash,nil] A device details object # # @return [Ably::Models::PushChannelSubscription] + # def PushChannelSubscription(push_channel_subscription) case push_channel_subscription when Ably::Models::PushChannelSubscription @@ -18,20 +19,14 @@ def PushChannelSubscription(push_channel_subscription) end module Ably::Models - # An object representing a devices details, used currently for push notifications - # - # @!attribute [r] channel - # @return [String] The realtime pub/sub channel this subscription is registered to - # @!attribute [r] client_id - # @return [String] Client ID that is assigned to one or more registered push devices - # @!attribute [r] device_id - # @return [String] Unique device identifier assigned to the push device + # Contains the subscriptions of a device, or a group of devices sharing the same clientId, + # has to a channel in order to receive push notifications. # class PushChannelSubscription < Ably::Exceptions::BaseAblyException include Ably::Modules::ModelCommon # @param hash_object [Hash,nil] Device detail attributes - #a + # def initialize(hash_object = {}) @raw_hash_object = hash_object || {} @hash_object = IdiomaticRubyWrapper(hash_object) @@ -47,7 +42,9 @@ def initialize(hash_object = {}) end end - # Constructor for channel subscription by device ID + # A static factory method to create a PushChannelSubscription object for a channel and single device. + # + # @spec PSC5 # # @param channel [String] the realtime pub/sub channel this subscription is registered to # @param device_id [String] Unique device identifier assigned to the push device @@ -58,7 +55,9 @@ def self.for_device(channel, device_id) PushChannelSubscription.new(channel: channel, device_id: device_id) end - # Constructor for channel subscription by client ID + # A static factory method to create a PushChannelSubscription object for a channel and group of devices sharing the same clientId. + # + # @spec PSC5 # # @param channel [String] the realtime pub/sub channel this subscription is registered to # @param client_id [String] Client ID that is assigned to one or more registered push devices @@ -69,11 +68,37 @@ def self.for_client_id(channel, client_id) PushChannelSubscription.new(channel: channel, client_id: client_id) end - %w(channel client_id device_id).each do |attribute| - define_method attribute do - attributes[attribute.to_sym] - end + # The channel the push notification subscription is for. + # + # @spec PCS4 + # + # @return [String] + # + def channel + attributes[:channel] + end + # The ID of the client the device, or devices are associated to. + # + # @spec PCS3, PCS6 + # + # @return [String] + # + def client_id + attributes[:client_id] + end + + # The unique ID of the device. + # + # @spec PCS2, PCS5, PCS6 + # + # @return [String] + # + def device_id + attributes[:device_id] + end + + %w(channel client_id device_id).each do |attribute| define_method "#{attribute}=" do |val| unless val.nil? || val.kind_of?(String) raise ArgumentError, "#{attribute} must be nil or a string value" From bf3dc1f31d67a07188aa47c4ed17d3a3c2cbd188 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:56:26 +0200 Subject: [PATCH 35/70] Fix lib/ably/models/presence_message.rb descriptions --- lib/ably/models/presence_message.rb | 94 ++++++++++++++++++++++------- 1 file changed, 72 insertions(+), 22 deletions(-) diff --git a/lib/ably/models/presence_message.rb b/lib/ably/models/presence_message.rb index 8066bf692..5e9ecc5f8 100644 --- a/lib/ably/models/presence_message.rb +++ b/lib/ably/models/presence_message.rb @@ -5,6 +5,7 @@ module Ably::Models # @param [Hash] options (see PresenceMessage#initialize) # # @return [PresenceMessage] + # def self.PresenceMessage(presence_message, options = {}) case presence_message when PresenceMessage @@ -19,24 +20,6 @@ def self.PresenceMessage(presence_message, options = {}) # A class representing an individual presence message to be sent or received # via the Ably Realtime service. # - # @!attribute [r] action - # @return [ACTION] the state change event signified by a PresenceMessage - # @!attribute [r] client_id - # @return [String] The client_id associated with this presence state - # @!attribute [r] connection_id - # @return [String] A unique member identifier, disambiguating situations where a given client_id is present on multiple connections simultaneously - # @!attribute [r] member_key - # @return [String] A unique connection and client_id identifier ensuring multiple connected clients with the same client_id are unique - # @!attribute [r] data - # @return [Object] Optional client-defined status or other event payload associated with this state - # @!attribute [r] encoding - # @return [String] The encoding for the message data. Encoding and decoding of messages is handled automatically by the client library. - # Therefore, the `encoding` attribute should always be nil unless an Ably library decoding error has occurred. - # @!attribute [r] timestamp - # @return [Time] Timestamp when the message was received by the Ably the realtime service - # @!attribute [r] attributes - # @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys - # class PresenceMessage include Ably::Modules::Conversions include Ably::Modules::Encodeable @@ -44,6 +27,16 @@ class PresenceMessage include Ably::Modules::SafeDeferrable if defined?(Ably::Realtime) extend Ably::Modules::Enum + # Describes the possible actions members in the presence set can emit. + # + # ABSENT TP2 A member is not present in the channel. + # PRESENT TP2 When subscribing to presence events on a channel that already has members present, this event is emitted for every member already present on the channel before the subscribe listener was registered. + # ENTER TP2 A new member has entered the channel. + # LEAVE TP2 A member who was present has now left the channel. This may be a result of an explicit request to leave or implicitly when detaching from the channel. Alternatively, if a member's connection is abruptly disconnected and they do not resume their connection within a minute, Ably treats this as a leave event as the client is no longer present. + # UPDATE TP2 An already present member has updated their member data. Being notified of member data updates can be very useful, for example, it can be used to update the status of a user when they are typing a message. + # + # @spec TP2 + # ACTION = ruby_enum('ACTION', :absent, :present, @@ -76,24 +69,75 @@ def initialize(attributes, options = {}) self.attributes.freeze end - %w( client_id data encoding ).each do |attribute| - define_method attribute do - attributes[attribute.to_sym] - end + # The ID of the client that published the PresenceMessage. + # + # @spec TP3c + # + # @return [String] + # + def client_id + attributes[:client_id] + end + + # The payload of the {Ably::Models::PresenceMessage}. + # + # @spec TP3e + # + # @return [Hash, nil] + # + def data + attributes[:date] + end + + # This will typically be empty as all presence messages received from Ably are automatically decoded client-side + # using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining + # transformations not applied to the data payload. + # + # @spec TP3f + # + # @return [String] + # + def encoding + attributes[:encoding] end + # A unique ID assigned to each {Ably::Models::PresenceMessage} by Ably. + # + # @spec TP3a + # + # @return [String] + # def id attributes.fetch(:id) { "#{protocol_message.id!}:#{protocol_message_index}" } end + # The ID of the connection associated with the client that published the {Ably::Models::PresenceMessage}. + # + # @spec TP3d + # + # @return [String] + # def connection_id attributes.fetch(:connection_id) { protocol_message.connection_id if assigned_to_protocol_message? } end + # Combines clientId and connectionId to ensure that multiple connected clients with an identical clientId are uniquely + # identifiable. A string function that returns the combined clientId and connectionId. + # + # @spec TP3h + # + # @return [String] + # def member_key "#{connection_id}:#{client_id}" end + # The time the {Ably::Models::PresenceMessage} was received by Ably, as milliseconds since the Unix epoch. + # + # @spec TP3g + # + # @return [Integer] + # def timestamp if attributes[:timestamp] as_time_from_epoch(attributes[:timestamp]) @@ -102,6 +146,12 @@ def timestamp end end + # The type of {Ably::Models::PresenceMessage::ACTION} the PresenceMessage is for. + # + # @spec TP3b + # + # @return [Ably::Models::PresenceMessage::ACTION] + # def action ACTION(attributes[:action]) end From 04a92cc7bf507ebb019ceeb266bb45434c41aafa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:56:35 +0200 Subject: [PATCH 36/70] Fix lib/ably/models/paginated_result.rb descriptions --- lib/ably/models/paginated_result.rb | 44 ++++++++++++++++++----------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/lib/ably/models/paginated_result.rb b/lib/ably/models/paginated_result.rb index 8d543e1e7..bf8a36990 100644 --- a/lib/ably/models/paginated_result.rb +++ b/lib/ably/models/paginated_result.rb @@ -1,16 +1,18 @@ module Ably::Models - # Wraps any Ably HTTP response that supports paging and provides methods to iterate through - # the pages using {#first}, {#next}, {#has_next?} and {#last?} - # - # All items in the HTTP response are available in the Array returned from {#items} - # - # Paging information is provided by Ably in the LINK HTTP headers + # Contains a page of results for message or presence history, stats, or REST presence requests. + # A PaginatedResult response from a REST API paginated query is also accompanied by metadata + # that indicates the relative queries available to the PaginatedResult object. # class PaginatedResult include Ably::Modules::AsyncWrapper if defined?(Ably::Realtime) - # The items contained within this {PaginatedResult} + # Contains the current page of results; for example, an array of {Ably::Models::Message} or {Ably::Models::PresenceMessage} objects + # for a channel history request. + # + # @spec TG3 + # # @return [Array] + # attr_reader :items # @param [Faraday::Response] http_response Initial HTTP response from an Ably request to a paged resource @@ -22,6 +24,7 @@ class PaginatedResult # @yield [Object] block will be called for each resource object for the current page. This is a useful way to apply a transformation to any page resources after they are retrieved # # @return [PaginatedResult] + # def initialize(http_response, base_url, client, options = {}, &each_block) @http_response = http_response @client = client @@ -41,11 +44,12 @@ def initialize(http_response, base_url, client, options = {}, &each_block) @items = items.map { |item| yield item } if block_given? end - # Retrieve the first page of results. - # When used as part of the {Ably::Realtime} library, it will return a {Ably::Util::SafeDeferrable} object, - # and allows an optional success callback block to be provided. + # Returns a new PaginatedResult for the first page of results. + # + # @spec TG5 + # + # @return [PaginatedResult, Ably::Util::SafeDeferrable] # - # @return [PaginatedResult,Ably::Util::SafeDeferrable] def first(&success_callback) async_wrap_if_realtime(success_callback) do return nil unless supports_pagination? @@ -53,11 +57,12 @@ def first(&success_callback) end end - # Retrieve the next page of results. - # When used as part of the {Ably::Realtime} library, it will return a {Ably::Util::SafeDeferrable} object, - # and allows an optional success callback block to be provided. + # Returns a new PaginatedResult loaded with the next page of results. If there are no further pages, then null is returned. + # + # @spec TG4 # # @return [PaginatedResult,Ably::Util::SafeDeferrable] + # def next(&success_callback) async_wrap_if_realtime(success_callback) do return nil unless has_next? @@ -65,17 +70,23 @@ def next(&success_callback) end end - # True if this is the last page in the paged resource set + # Returns true if this page is the last page and returns false if there are more pages available by calling next available. + # + # @spec TG7 # # @return [Boolean] + # def last? !supports_pagination? || pagination_header('next').nil? end - # True if there is a subsequent page in this paginated set available with {#next} + # Returns true if there are more pages available by calling next and returns false if this page is the last page available. + # + # @spec TG6 # # @return [Boolean] + # def has_next? supports_pagination? && !last? end @@ -83,6 +94,7 @@ def has_next? # True if the HTTP response supports paging with the expected LINK HTTP headers # # @return [Boolean] + # def supports_pagination? !pagination_headers.empty? end From 76de89e19e7f5be61ae26d1767303a4398174240 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:56:44 +0200 Subject: [PATCH 37/70] Fix lib/ably/models/message_encoders/base.rb descriptions --- lib/ably/models/message_encoders/base.rb | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/lib/ably/models/message_encoders/base.rb b/lib/ably/models/message_encoders/base.rb index dd4421548..81b019b46 100644 --- a/lib/ably/models/message_encoders/base.rb +++ b/lib/ably/models/message_encoders/base.rb @@ -32,6 +32,7 @@ def initialize(client, options = {}) # @param [Hash] channel_options the options used to initialize the channel that this message was received on # # @return [void] + # def encode(message, channel_options) raise "Not yet implemented" end @@ -48,6 +49,7 @@ def encode(message, channel_options) # @param [Hash] channel_options the options used to initialize the channel that this message was received on # # @return [void] + # def decode(message, channel_options) raise "Not yet implemented" end @@ -59,6 +61,7 @@ def decode(message, channel_options) # @param [String] encoding encoding to add to the current encoding # # @return [void] + # def add_encoding_to_message(encoding, message) message[:encoding] = [message[:encoding], encoding].compact.join('/') end @@ -67,6 +70,7 @@ def add_encoding_to_message(encoding, message) # i.e. current_encoding_part('utf-8/cipher+aes-128-cbc/base64') => 'base64' # # @return [String,nil] + # def current_encoding_part(message) if message[:encoding] message[:encoding].split('/')[-1] @@ -81,6 +85,7 @@ def current_encoding_part(message) # @param [Hash] message the message as a Hash object received directly from Ably. # # @return [void] + # def strip_current_encoding_part(message) raise "Cannot strip encoding when there is no encoding for this message" unless message[:encoding] message[:encoding] = message[:encoding].split('/')[0...-1].join('/') @@ -92,6 +97,7 @@ def strip_current_encoding_part(message) # @param [Hash] message the message as a Hash object received directly from Ably. # # @return [Boolean] + # def is_empty?(message) message[:data].nil? || message[:data] == '' end From 936ba8a21ad75a52cde83fe2c1b11436b13c8c19 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:56:56 +0200 Subject: [PATCH 38/70] Fix lib/ably/models/message.rb descriptions --- lib/ably/models/message.rb | 88 +++++++++++++++++++++++++++----------- 1 file changed, 64 insertions(+), 24 deletions(-) diff --git a/lib/ably/models/message.rb b/lib/ably/models/message.rb index 5c67fb7af..5c5817b06 100644 --- a/lib/ably/models/message.rb +++ b/lib/ably/models/message.rb @@ -7,6 +7,7 @@ module Ably::Models # @param [Hash] options (see Message#initialize) # # @return [Message] + # def self.Message(message, options = {}) case message when Message @@ -18,26 +19,7 @@ def self.Message(message, options = {}) end end - # A class representing an individual message to be sent or received - # via the Ably Realtime service. - # - # @!attribute [r] name - # @return [String] The event name, if available - # @!attribute [r] client_id - # @return [String] The id of the publisher of this message - # @!attribute [r] data - # @return [Object] The message payload. See the documentation for supported datatypes. - # @!attribute [r] encoding - # @return [Object] The encoding for the message data. Encoding and decoding of messages is handled automatically by the client library. - # Therefore, the `encoding` attribute should always be nil unless an Ably library decoding error has occurred. - # @!attribute [r] timestamp - # @return [Time] Timestamp when the message was received by the Ably the realtime service - # @!attribute [r] id - # @return [String] A globally unique message ID - # @!attribute [r] connection_id - # @return [String] The connection_id of the publisher of the message - # @!attribute [r] attributes - # @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys + # Contains an individual message that is sent to, or received from, Ably. # class Message include Ably::Modules::Conversions @@ -50,6 +32,8 @@ class Message # {Message} initializer # + # @spec TM2, TM3 + # # @param attributes [Hash] object with the underlying message detail key value attributes # @param [Hash] options an options Hash for this initializer # @option options [ProtocolMessage] :protocol_message An optional protocol message to assocate the presence message with @@ -69,24 +53,74 @@ def initialize(attributes, options = {}) self.attributes.freeze end - %w( name client_id encoding ).each do |attribute| - define_method attribute do - attributes[attribute.to_sym] - end + # The client ID of the publisher of this message. + # + # @spec RSL1g1, TM2b + # + # @return [String] + # + def client_id + attributes[:client_id] + end + + # This is typically empty, as all messages received from Ably are automatically decoded client-side using this value. + # However, if the message encoding cannot be processed, this attribute contains the remaining transformations + # not applied to the data payload. + # + # @spec TM2e + # + # @return [String] + # + def encoding + attributes[:encoding] end + # The event name. + # + # @spec TM2g + # + # @return [String] + # + def name + attributes[:name] + end + + # The message payload, if provided. + # + # @spec TM2d + # + # @return [Hash, nil] + # def data @data ||= attributes[:data].freeze end + # A Unique ID assigned by Ably to this message. + # + # @spec TM2a + # + # @return [String] + # def id attributes.fetch(:id) { "#{protocol_message.id!}:#{protocol_message_index}" } end + # The connection ID of the publisher of this message. + # + # @spec TM2c + # + # @return [String] + # def connection_id attributes.fetch(:connection_id) { protocol_message.connection_id if assigned_to_protocol_message? } end + # Timestamp of when the message was received by Ably, as milliseconds since the Unix epoch. + # + # @spec TM2f + # + # @return [Integer] + # def timestamp if attributes[:timestamp] as_time_from_epoch(attributes[:timestamp]) @@ -126,14 +160,18 @@ def assign_to_protocol_message(protocol_message) end # True if this message is assigned to a ProtocolMessage for delivery to Ably, or received from Ably + # # @return [Boolean] + # # @api private def assigned_to_protocol_message? !!@protocol_message end # The optional ProtocolMessage this message is assigned to. If ProtocolMessage is nil, an error will be raised. + # # @return [Ably::Models::ProtocolMessage] + # # @api private def protocol_message raise RuntimeError, 'Message is not yet published with a ProtocolMessage. ProtocolMessage is nil' if @protocol_message.nil? @@ -155,7 +193,9 @@ def extras end # Delta extras extension (TM2i) + # # @return [DeltaExtras, nil] + # # @api private def delta_extras return nil if attributes[:extras][:delta].nil? From 3f0ec5f9db584aab922e6a7e3970d84529c13201 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:57:08 +0200 Subject: [PATCH 39/70] Fix lib/ably/models/idiomatic_ruby_wrapper.rb descriptions --- lib/ably/models/idiomatic_ruby_wrapper.rb | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/lib/ably/models/idiomatic_ruby_wrapper.rb b/lib/ably/models/idiomatic_ruby_wrapper.rb index a9e964a1e..bc903f568 100644 --- a/lib/ably/models/idiomatic_ruby_wrapper.rb +++ b/lib/ably/models/idiomatic_ruby_wrapper.rb @@ -5,7 +5,8 @@ module Conversions private # Creates or returns an {IdiomaticRubyWrapper} ensuring it never wraps itself # - # @return {IdiomaticRubyWrapper} + # @return [IdiomaticRubyWrapper] + # def IdiomaticRubyWrapper(object, options = {}) case object when Ably::Models::IdiomaticRubyWrapper @@ -35,9 +36,6 @@ module Ably::Models # ruby_hash[:none] # => nil # ruby_hash.none # => nil # - # @!attribute [r] stop_at - # @return [Array] array of keys that this wrapper should stop wrapping at to preserve the underlying Hash as is - # class IdiomaticRubyWrapper include Enumerable include Ably::Modules::Conversions @@ -142,8 +140,6 @@ def method_missing(method_sym, *arguments) end end - # @!attribute [r] Hash - # @return [Hash] Access to the raw Hash object provided to the constructer of this wrapper def attributes @attributes end @@ -198,8 +194,6 @@ def to_s attributes.to_s end - # @!attribute [r] hash - # @return [Integer] Compute a hash-code for this hash. Two hashes with the same content will have the same hash code def hash attributes.hash end From d90d5a2ed6f4daa5e91990940c49aca8ffd91d5f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:57:26 +0200 Subject: [PATCH 40/70] Fix lib/ably/models/http_paginated_response.rb descriptions --- lib/ably/models/http_paginated_response.rb | 32 ++++++++++++++++++---- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/lib/ably/models/http_paginated_response.rb b/lib/ably/models/http_paginated_response.rb index 28d9d6668..052867694 100644 --- a/lib/ably/models/http_paginated_response.rb +++ b/lib/ably/models/http_paginated_response.rb @@ -11,6 +11,7 @@ class HttpPaginatedResponse < PaginatedResult # and allows an optional success callback block to be provided. # # @return [HttpPaginatedResponse,Ably::Util::SafeDeferrable] + # def first(&success_callback) async_wrap_if_realtime(success_callback) do return nil unless supports_pagination? @@ -23,6 +24,7 @@ def first(&success_callback) # and allows an optional success callback block to be provided. # # @return [HttpPaginatedResponse,Ably::Util::SafeDeferrable] + # def next(&success_callback) async_wrap_if_realtime(success_callback) do return nil unless has_next? @@ -30,34 +32,54 @@ def next(&success_callback) end end - # HTTP status code for response + # The HTTP status code of the response. + # + # @spec HP4 + # # @return [Integer] + # def status_code http_response.status.to_i end - # True if the response is considered successful due to the HTTP status code + # Whether statusCode indicates success. This is equivalent to 200 <= statusCode < 300. + # + # @spec HP5 + # # @return [Boolean] + # def success? (200..299).include?(http_response.status.to_i) end - # Ably error code from +X-Ably-Errorcode+ header if available from response + # The error code if the X-Ably-Errorcode HTTP header is sent in the response. + # + # @spec HP6 + # # @return [Integer] + # def error_code if http_response.headers['X-Ably-Errorcode'] http_response.headers['X-Ably-Errorcode'].to_i end end - # Error message from +X-Ably-Errormessage+ header if available from response + # The error message if the X-Ably-Errormessage HTTP header is sent in the response. + # + # @spec HP7 + # # @return [String] + # def error_message http_response.headers['X-Ably-Errormessage'] end - # Headers for the HTTP response + # The headers of the response. + # + # @spec HP8 + # # @return [Hash] + # def headers http_response.headers || {} end From d15a7a8c128e67bafb5a524db683ae87a092f6a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:57:38 +0200 Subject: [PATCH 41/70] Fix lib/ably/models/error_info.rb descriptions --- lib/ably/models/error_info.rb | 76 +++++++++++++++++++++++++++-------- 1 file changed, 59 insertions(+), 17 deletions(-) diff --git a/lib/ably/models/error_info.rb b/lib/ably/models/error_info.rb index 4057b1bfe..1ff8d4b56 100644 --- a/lib/ably/models/error_info.rb +++ b/lib/ably/models/error_info.rb @@ -6,6 +6,7 @@ module Conversions # @param error_details [ErrorInfo,Hash] Error info attributes # # @return [ErrorInfo] + # def ErrorInfo(error_details) case error_details when Ably::Models::ErrorInfo @@ -21,19 +22,6 @@ module Ably::Models # An exception type encapsulating error information containing # an Ably-specific error code and generic status code. # - # @!attribute [r] message - # @return [String] Additional reason information, where available - # @!attribute [r] code - # @return [Integer] Ably error code (see ably-common/protocol/errors.json) - # @!attribute [r] status - # @return [Integer] HTTP Status Code corresponding to this error, where applicable - # @!attribute [r] request_id - # @return [Integer] HTTP RequestId corresponding to this error, where applicable (#RSC7c) - # @!attribute [r] cause - # @return [Integer] HTTP Status Code corresponding to this error, where applicable (#TI1) - # @!attribute [r] attributes - # @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys - # class ErrorInfo < Ably::Exceptions::BaseAblyException include Ably::Modules::ModelCommon @@ -42,10 +30,64 @@ def initialize(hash_object) @hash_object = IdiomaticRubyWrapper(hash_object.clone.freeze) end - %w(message code href status_code request_id cause).each do |attribute| - define_method attribute do - attributes[attribute.to_sym] - end + # Ably error code. + # + # @spec TI1 + # + # @return [Integer] + # + def code + attributes[:code] + end + + # This is included for REST responses to provide a URL for additional help on the error code. + # + # @spec TI4 + # + # @return [String] + # + def href + attributes[:href] + end + + # Additional message information, where available. + # + # @spec TI1 + # + # @return [String] + # + def message + attributes[:message] + end + + # Information pertaining to what caused the error where available. + # + # @spec TI1 + # + # @return [Ably::Models::ErrorInfo] + # + def cause + attributes[:cause] + end + + # HTTP Status Code corresponding to this error, where applicable. + # + # @spec TI1 + # + # @return [Integer] + # + def status_code + attributes[:status_code] + end + + # If a request fails, the request ID must be included in the ErrorInfo returned to the user. + # + # @spec RSC7c + # + # @return [String] + # + def request_id + attributes[:request_id] end alias_method :status, :status_code From 73e21528476d14333c5fa08b6d9e32abf028ef24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:57:51 +0200 Subject: [PATCH 42/70] Fix lib/ably/models/device_push_details.rb descriptions --- lib/ably/models/device_push_details.rb | 46 +++++++++++++++----------- 1 file changed, 27 insertions(+), 19 deletions(-) diff --git a/lib/ably/models/device_push_details.rb b/lib/ably/models/device_push_details.rb index 9130723fd..45e1b7cc4 100644 --- a/lib/ably/models/device_push_details.rb +++ b/lib/ably/models/device_push_details.rb @@ -6,6 +6,7 @@ module Conversions # @param device_push_details [Ably::Models::DevicePushDetails,Hash,nil] A device push notification details object # # @return [Ably::Models::DevicePushDetails] + # def DevicePushDetails(device_push_details) case device_push_details when Ably::Models::DevicePushDetails @@ -20,38 +21,39 @@ def DevicePushDetails(device_push_details) module Ably::Models # An object with the push notification details for {DeviceDetails} object # - # @!attribute [r] transport_type - # @return [String] Transport type for push notifications such as gcm, apns, web - # @!attribute [r] state - # @return [String] The current state of this push target such as Active, Failing or Failed - # @!attribute [r] error_reason - # @return [ErrorInfo] If the state is Failing of Failed, this field may optionally contain a reason - # @!attribute [r] metadata - # @return [Hash] Arbitrary metadata that can be associated with this object - # class DevicePushDetails < Ably::Exceptions::BaseAblyException include Ably::Modules::ModelCommon # @param hash_object [Hash,nil] Device push detail attributes - #a + # def initialize(hash_object = {}) @raw_hash_object = hash_object || {} @hash_object = IdiomaticRubyWrapper(@raw_hash_object) end - %w(state).each do |attribute| - define_method attribute do - attributes[attribute.to_sym] - end + # The current state of the push registration. + # + # @spec PCP4 + # + # @return [Symbol] + # + def state + attributes[:state] + end - define_method "#{attribute}=" do |val| - unless val.nil? || val.kind_of?(String) - raise ArgumentError, "#{attribute} must be nil or a string value" - end - attributes[attribute.to_sym] = val + def state=(val) + unless val.nil? || val.kind_of?(String) + raise ArgumentError, "#{attribute} must be nil or a string value" end + attributes[:state] = val end + # A JSON object of key-value pairs that contains of the push transport and address. + # + # @spec PCP3 + # + # @return [Hash, nil] + # def recipient attributes[:recipient] || {} end @@ -63,6 +65,12 @@ def recipient=(val) attributes[:recipient] = val end + # An {Ably::Models::ErrorInfo} object describing the most recent error when the state is Failing or Failed. + # + # @spec PCP2 + # + # @return [Ably::Models::ErrorInfo] + # def error_reason attributes[:error_reason] end From 9eacd6359f1792b9238f214bd5a78d5d6d8f778a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:58:02 +0200 Subject: [PATCH 43/70] Fix lib/ably/models/device_details.rb descriptions --- lib/ably/models/device_details.rb | 81 +++++++++++++++++++++++-------- 1 file changed, 60 insertions(+), 21 deletions(-) diff --git a/lib/ably/models/device_details.rb b/lib/ably/models/device_details.rb index 558578da5..394b6fd7f 100644 --- a/lib/ably/models/device_details.rb +++ b/lib/ably/models/device_details.rb @@ -6,6 +6,7 @@ module Conversions # @param device_details [Ably::Models::DeviceDetails,Hash,nil] A device details object # # @return [Ably::Models::DeviceDetails] + # def DeviceDetails(device_details) case device_details when Ably::Models::DeviceDetails @@ -18,38 +19,63 @@ def DeviceDetails(device_details) end module Ably::Models - # An object representing a devices details, used currently for push notifications - # - # @!attribute [r] id - # @return [String] Unique device identifier assigned randomly by the device - # @!attribute [r] platform - # @return [String] Device platform such as android, ios or browser - # @!attribute [r] form_factor - # @return [String] Device form factor such as phone, tablet, watch - # @!attribute [r] client_id - # @return [String] The authenticated client identifier for this device. See {https://www.ably.com/docs/general/authentication#identified-clients auth documentation}. - # @!attribute [r] metadata - # @return [Hash] Arbitrary metadata that can be associated with a device - # @!attribute [r] device_secret - # @return [String] This secret is used internally by Ably client libraries to authenticate with Ably when push registration updates are required such as when the GCM token expires and needs renewing - # @!attribute [r] push - # @return [DevicePushDetails] The push notification specific properties for this device allowing push notifications to be delivered to the device + # Contains the properties of a device registered for push notifications. # class DeviceDetails < Ably::Exceptions::BaseAblyException include Ably::Modules::ModelCommon # @param hash_object [Hash,nil] Device detail attributes - #a + # def initialize(hash_object = {}) @raw_hash_object = hash_object || {} @hash_object = IdiomaticRubyWrapper(hash_object) end - %w(id platform form_factor client_id device_secret).each do |attribute| - define_method attribute do - attributes[attribute.to_sym] - end + # A unique ID generated by the device. + # + # @spec PCD2 + # + def id + attributes[:id] + end + + # The DevicePlatform associated with the device. + # Describes the platform the device uses, such as android or ios. + # + # @spec PCD6 + # + # @return [String] + # + def platform + attributes[:platform] + end + + # The client ID the device is connected to Ably with. + # + # @spec PCD3 + # + # @return [String] + # + def client_id + attributes[:client_id] + end + + # The DeviceFormFactor object associated with the device. + # Describes the type of the device, such as phone or tablet. + # + # @spec PCD4 + # + # @return [String] + # + def form_factor + attributes[:form_factor] + end + + def device_secret + attributes[:device_secret] + end + %w(id platform form_factor client_id device_secret).each do |attribute| define_method "#{attribute}=" do |val| unless val.nil? || val.kind_of?(String) raise ArgumentError, "#{attribute} must be nil or a string value" @@ -58,6 +84,12 @@ def initialize(hash_object = {}) end end + # A JSON object of key-value pairs that contains metadata for the device. + # + # @spec PCD5 + # + # @return [Hash, nil] + # def metadata attributes[:metadata] || {} end @@ -69,6 +101,13 @@ def metadata=(val) attributes[:metadata] = val end + # The {Ably::Models::DevicePushDetails} object associated with the device. + # Describes the details of the push registration of the device. + # + # @spec PCD7 + # + # @return [Ably::Models::DevicePushDetails] + # def push DevicePushDetails(attributes[:push] || {}) end From 2bd00828d1fc1e73e1a4f87538062cf4257e7159 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:58:12 +0200 Subject: [PATCH 44/70] Fix lib/ably/models/delta_extras.rb descriptions --- lib/ably/models/delta_extras.rb | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/lib/ably/models/delta_extras.rb b/lib/ably/models/delta_extras.rb index 8a9c35538..28c37f327 100644 --- a/lib/ably/models/delta_extras.rb +++ b/lib/ably/models/delta_extras.rb @@ -1,19 +1,18 @@ module Ably::Models - # - # @!attribute [r] from - # @return [String] The id of the message the delta was generated from - # @!attribute [r] format - # @return [String] The delta format. Only vcdiff is supported as at API version 1.2 + # Contains any arbitrary key-value pairs, which may also contain other primitive JSON types, JSON-encodable objects, + # or JSON-encodable arrays from delta compression. # class DeltaExtras include Ably::Modules::ModelCommon - # The id of the message the delta was generated from. + # The ID of the message the delta was generated from. + # # @return [String, nil] # attr_reader :from - # The delta format. + # The delta compression format. Only vcdiff is supported. + # # @return [String, nil] # attr_reader :format From aeb5284477d141e1fde4443e04ddfeae79d8fad1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:58:26 +0200 Subject: [PATCH 45/70] Fix lib/ably/models/connection_state_change.rb descriptions --- lib/ably/models/connection_state_change.rb | 69 +++++++++++++++++----- 1 file changed, 54 insertions(+), 15 deletions(-) diff --git a/lib/ably/models/connection_state_change.rb b/lib/ably/models/connection_state_change.rb index 29810a88c..e7f609cc6 100644 --- a/lib/ably/models/connection_state_change.rb +++ b/lib/ably/models/connection_state_change.rb @@ -1,15 +1,5 @@ module Ably::Models - # ConnectionStateChange is a class that is emitted by the {Ably::Realtime::Connection} object - # when a state change occurs - # - # @!attribute [r] current - # @return [Connection::STATE] Current connection state - # @!attribute [r] previous - # @return [Connection::STATE] Previous connection state - # @!attribute [r] retry_in - # @return [Integer] Time in seconds until the connection will reattempt to connect when in the +:disconnected+ or +:suspended+ state - # @!attribute [r] reason - # @return [Ably::Models::ErrorInfo] Object describing the reason for a state change when not initiated by the consumer of the client library + # Contains {Ably::Models::ConnectionState} change information emitted by the {Ably::Realtime::Connection} object. # class ConnectionStateChange include Ably::Modules::ModelCommon @@ -31,10 +21,59 @@ def initialize(hash_object) raise ArgumentError, e end - %w(current previous event retry_in reason protocol_message).each do |attribute| - define_method attribute do - @hash_object[attribute.to_sym] - end + # The new {Ably::Realtime::Connection::STATE}. + # + # @spec TA2 + # + # @return [Ably::Realtime::Connection::STATE] + # + def current + @hash_object[:current] + end + + # The event that triggered this {Ably::Realtime::Connection::EVENT} change. + # + # @spec TA5 + # + # @return [Ably::Realtime::Connection::STATE] + # + def event + @hash_object[:event] + end + + # The previous {Ably::Models::Connection::STATE}. For the {Ably::Models::Connection::EVENT} UPDATE event, + # this is equal to the current {Ably::Models::Connection::STATE}. + # + # @spec TA2 + # + # @return [Ably::Realtime::Connection::STATE] + # + def previous + @hash_object[:previous] + end + + # An {Ably::Models::ErrorInfo} object containing any information relating to the transition. + # + # @spec RTN4f, TA3 + # + # @return [Ably::Models::ErrorInfo, nil] + # + def reason + @hash_object[:reason] + end + + # Duration in milliseconds, after which the client retries a connection where applicable. + # + # @spec RTN14d, TA2 + # + # @return [Integer] + # + def retry_in + @hash_object[:retry_in] + end + + def protocol_message + @hash_object[:protocol_message] end def to_s From f8c7b854021ae0c358e822a761b9b5b03444c496 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:58:36 +0200 Subject: [PATCH 46/70] Fix lib/ably/models/connection_details.rb descriptions --- lib/ably/models/connection_details.rb | 101 +++++++++++++++++++++++--- 1 file changed, 91 insertions(+), 10 deletions(-) diff --git a/lib/ably/models/connection_details.rb b/lib/ably/models/connection_details.rb index 58be50efc..06f87e94a 100644 --- a/lib/ably/models/connection_details.rb +++ b/lib/ably/models/connection_details.rb @@ -4,6 +4,7 @@ module Ably::Models # @param attributes (see #initialize) # # @return [ConnectionDetails] + # def self.ConnectionDetails(attributes) case attributes when ConnectionDetails @@ -13,10 +14,8 @@ def self.ConnectionDetails(attributes) end end - # ConnectionDetails are optionally passed to the client library in the +CONNECTED+ {Ably::Models::ProtocolMessage#connectionDetails} attribute - # to inform the client about any constraints it should adhere to and provide additional metadata about the connection. - # For example, if a request is made to publish a message that exceeds the +maxMessageSize+, the client library can reject - # the message immediately, without communicating with the Ably service + # Contains any constraints a client should adhere to and provides additional metadata about a {Ably::Realtime::Connection}, + # such as if a request to {Ably::Realtime::Client#publish} a message that exceeds the maximum message size should be rejected immediately without communicating with Ably. # class ConnectionDetails include Ably::Modules::ModelCommon @@ -28,7 +27,7 @@ class ConnectionDetails MAX_FRAME_SIZE = 524288 # See spec TO3l9 # @param attributes [Hash] - # @option attributes [String] :client_id contains the client ID assigned to the connection + # @option attributes [String] :client_id Contains the client ID assigned to the token. If clientId is null or omitted, then the client is prohibited from assuming a clientId in any operations, however if clientId is a wildcard string *, then the client is permitted to assume any clientId. Any other string value for clientId implies that the clientId is both enforced and assumed for all operations from this client. # @option attributes [String] :connection_key the connection secret key string that is used to resume a connection and its state # @option attributes [Integer] :max_message_size maximum individual message size in bytes # @option attributes [Integer] :max_frame_size maximum size for a single frame of data sent to Ably. This restriction applies to a {Ably::Models::ProtocolMessage} sent over a realtime connection, or the total body size for a REST request @@ -49,18 +48,100 @@ def initialize(attributes = {}) self.attributes.freeze end - %w(client_id connection_key max_message_size max_frame_size max_inbound_rate connection_state_ttl max_idle_interval server_id).each do |attribute| - define_method attribute do - attributes[attribute.to_sym] - end + # Contains the client ID assigned to the token. If clientId is null or omitted, then the client is prohibited from + # assuming a clientId in any operations, however if clientId is a wildcard string *, then the client is permitted + # to assume any clientId. Any other string value for clientId implies that the clientId is both enforced and assumed + # for all operations from this client. + # + # @spec RSA12a, CD2a + # + # @return [String] + # + def client_id + attributes[:client_id] + end + + # The connection secret key string that is used to resume a connection and its state. + # + # @spec RTN15e, CD2b + # + # @return [String] + # + def connection_key + attributes[:connection_key] + end + + # The duration that Ably will persist the connection state for when a Realtime client is abruptly disconnected. + # + # @spec CD2f, RTN14e, DF1a + # + # @return [Integer] + # + def connection_state_ttl + attributes[:connection_state_ttl] + end + + # Overrides the default maxFrameSize. + # + # @spec CD2d + # + # @return [Integer] + # + def max_frame_size + attributes[:max_frame_size] + end + + # The maximum allowable number of requests per second from a client or Ably. In the case of a realtime connection, + # this restriction applies to the number of messages sent, whereas in the case of REST, it is the total number of REST requests per second. + # + # @spec CD2e + # + # @return [Integer] + # + def max_inbound_rate + attributes[:max_inbound_rate] + end + + # The maximum message size is an attribute of an Ably account and enforced by Ably servers. + # maxMessageSize indicates the maximum message size allowed by the Ably account this connection is using. + # Overrides the default value of ClientOptions.maxMessageSize. + # + # @spec CD2c + # + # @return [Integer] + # + def max_message_size + attributes[:max_message_size] + end + + # A unique identifier for the front-end server that the client has connected to. This server ID is only used for the purposes of debugging. + # + # @spec CD2g + # + # @return [String] + # + def server_id + attributes[:server_id] + end + + # The maximum length of time in milliseconds that the server will allow no activity to occur in the server to client direction. + # After such a period of inactivity, the server will send a HEARTBEAT or transport-level ping to the client. + # If the value is 0, the server will allow arbitrarily-long levels of inactivity. + # + # @spec CD2h + # + # @return [Integer] + # + def max_idle_interval + attributes[:max_idle_interval] end def has_client_id? attributes.has_key?(:client_id) end - # @!attribute [r] attributes # @return [Hash] Access the token details Hash object ruby'fied to use symbolized keys + # def attributes @hash_object end From 373bab771a081709b33b4994f7e11bc6402b4377 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:58:47 +0200 Subject: [PATCH 47/70] Fix lib/ably/models/cipher_params.rb descriptions --- lib/ably/models/cipher_params.rb | 49 +++++++++++++++++++++++--------- 1 file changed, 36 insertions(+), 13 deletions(-) diff --git a/lib/ably/models/cipher_params.rb b/lib/ably/models/cipher_params.rb index f97f21f8c..d9ba6a8ee 100644 --- a/lib/ably/models/cipher_params.rb +++ b/lib/ably/models/cipher_params.rb @@ -7,6 +7,7 @@ module Ably::Models # @param attributes (see #initialize) # # @return [CipherParams] + # def self.CipherParams(attributes) case attributes when CipherParams @@ -16,7 +17,7 @@ def self.CipherParams(attributes) end end - # CipherParams is used to configure a channel for encryption + # Sets the properties to configure encryption for a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel} object. # class CipherParams include Ably::Modules::ModelCommon @@ -57,49 +58,71 @@ def initialize(params = {}) end # The Cipher algorithm string such as AES-128-CBC + # # @param [Hash] params Hash containing :algorithm, :key_length and :mode key values # # @return [String] + # def self.cipher_type(params) "#{params[:algorithm]}-#{params[:key_length]}-#{params[:mode]}".to_s.upcase end - # @!attribute [r] algorithm - # @return [String] The algorithm to use for encryption, currently only +AES+ is supported + # The algorithm to use for encryption. Only AES is supported and is the default value. + # + # @spec TZ2a + # + # @return [String] + # def algorithm attributes.fetch(:algorithm) do Ably::Util::Crypto::DEFAULTS.fetch(:algorithm) end.downcase end - # @!attribute [r] key - # @return [Binary] Private key used to encrypt and decrypt payloads + # The private key used to encrypt and decrypt payloads. + # + # @spec TZ2d + # + # @return [Binary] + # def key attributes[:key] end - # @!attribute [r] key_length - # @return [Integer] The length in bits of the +key+ + # The length of the key in bits; for example 128 or 256. + # + # @spec TZ2b + # + # @return [Integer] + # def key_length key.unpack('b*').first.length end - # @!attribute [r] mode - # @return [String] The cipher mode, currently only +CBC+ is supported + # The cipher mode. Only CBC is supported and is the default value. + # + # @spec TZ2c + # + # @return [String] + # def mode attributes.fetch(:mode) do Ably::Util::Crypto::DEFAULTS.fetch(:mode) end.downcase end - # @!attribute [r] cipher_type - # @return [String] The complete Cipher algorithm string such as AES-128-CBC + # The complete Cipher algorithm string such as AES-128-CBC + # + # @return [String] + # def cipher_type self.class.cipher_type(algorithm: algorithm, key_length: key_length, mode: mode) end - # @!attribute [r] attributes - # @return [Hash] Access the token details Hash object ruby'fied to use symbolized keys + # Access the token details Hash object ruby'fied to use symbolized keys + # + # @return [Hash] + # def attributes @attributes end From 1da0f229cd3d8eb3715bc502ef172ac7e84a0879 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:58:58 +0200 Subject: [PATCH 48/70] Fix lib/ably/models/channel_status.rb descriptions --- lib/ably/models/channel_status.rb | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/lib/ably/models/channel_status.rb b/lib/ably/models/channel_status.rb index 3355ce716..175d23371 100644 --- a/lib/ably/models/channel_status.rb +++ b/lib/ably/models/channel_status.rb @@ -4,6 +4,7 @@ module Ably::Models # @param attributes (see #initialize) # # @return [ChannelStatus] + # def self.ChannelStatus(attributes) case attributes when ChannelStatus @@ -13,14 +14,19 @@ def self.ChannelStatus(attributes) end end - # ChannelStatus is a type that contains status and occupancy for a channel (CHS1) + # Contains the status of a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel} object + # such as whether it is active and its {Ably::Models::ChannelOccupancy}. + # + # @spec CHS1 # class ChannelStatus extend Ably::Modules::Enum extend Forwardable include Ably::Modules::ModelCommon - # The attributes of ChannelStatus (CHS2) + # The attributes of ChannelStatus + # + # @spec CHS2 # attr_reader :attributes @@ -32,7 +38,9 @@ def initialize(attrs) @attributes = IdiomaticRubyWrapper(attrs.clone) end - # Represents if the channel is active (CHS2a) + # If true, the channel is active, otherwise false. + # + # @spec CHS2a # # @return [Boolean] # @@ -42,7 +50,9 @@ def is_active alias_method :active?, :is_active alias_method :is_active?, :is_active - # Occupancy ChannelOccupancy – occupancy is an object containing the metrics for the channel (CHS2b) + # A {Ably::Models::ChannelOccupancy} object. + # + # @spec CHS2b # # @return [Ably::Models::ChannelOccupancy, nil] # From 2099c954aba961de095e90b40c1e98cfa95ea34e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:59:08 +0200 Subject: [PATCH 49/70] Fix lib/ably/models/channel_state_change.rb descriptions --- lib/ably/models/channel_state_change.rb | 60 ++++++++++++++++++------- 1 file changed, 45 insertions(+), 15 deletions(-) diff --git a/lib/ably/models/channel_state_change.rb b/lib/ably/models/channel_state_change.rb index ca3cc427e..6c843939b 100644 --- a/lib/ably/models/channel_state_change.rb +++ b/lib/ably/models/channel_state_change.rb @@ -1,15 +1,5 @@ module Ably::Models - # ChannelStateChange is a class that is emitted by the {Ably::Realtime::Channel} object - # when a state change occurs - # - # @!attribute [r] current - # @return [Connection::STATE] Current channel state - # @!attribute [r] previous - # @return [Connection::STATE] Previous channel state - # @!attribute [r] reason - # @return [Ably::Models::ErrorInfo] Object describing the reason for a state change when not initiated by the consumer of the client library - # @!attribute [r] resumed - # @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 + # Contains state change information emitted by {Ably::Rest::Channel} and {Ably::Realtime::Channel} objects. # class ChannelStateChange include Ably::Modules::ModelCommon @@ -31,12 +21,52 @@ def initialize(hash_object) raise ArgumentError, e end - %w(current previous event reason).each do |attribute| - define_method attribute do - @hash_object[attribute.to_sym] - end + # The new current {Ably::Realtime::Channel::STATE}. + # + # @spec RTL2a, RTL2b + # + # @return [Ably::Realtime::Channel::STATE] + # + def current + @hash_object[:current] + end + + # The previous state. For the {Ably::Realtime::Channel::EVENT}(:update) event, this is equal to the current {Ably::Realtime::Channel::STATE}. + # + # @spec RTL2a, RTL2b + # + # @return [Ably::Realtime::Channel::EVENT] + # + def previous + @hash_object[:previous] + end + + # The event that triggered this {Ably::Realtime::Channel::STATE} change. + # + # @spec TH5 + # + # @return [Ably::Realtime::Channel::STATE] + # + def event + @hash_object[:event] + end + + # An {Ably::Models::ErrorInfo} object containing any information relating to the transition. + # + # @spec RTL2e, TH3 + # + # @return [Ably::Models::ErrorInfo, nil] + # + def reason + @hash_object[:reason] end + # Indicates whether message continuity on this channel is preserved, see Nonfatal channel errors for more info. + # + # @spec RTL2f, TH4 + # + # @return [Boolean] + # def resumed !!@hash_object[:resumed] end From e51e033d3c90aca2de8793346055eedef10e7672 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:59:19 +0200 Subject: [PATCH 50/70] Fix lib/ably/models/channel_options.rb descriptions --- lib/ably/models/channel_options.rb | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/lib/ably/models/channel_options.rb b/lib/ably/models/channel_options.rb index ec23f0be4..36fbc5a4c 100644 --- a/lib/ably/models/channel_options.rb +++ b/lib/ably/models/channel_options.rb @@ -4,6 +4,7 @@ module Ably::Models # @param attributes (see #initialize) # # @return [ChannelOptions] + # def self.ChannelOptions(attributes) case attributes when ChannelOptions @@ -19,6 +20,15 @@ class ChannelOptions extend Forwardable include Ably::Modules::ModelCommon + # Describes the possible flags used to configure client capabilities, using {Ably::Models::ChannelOptions::MODES}. + # + # PRESENCE The client can enter the presence set. + # PUBLISH The client can publish messages. + # SUBSCRIBE The client can subscribe to messages. + # PRESENCE_SUBSCRIBE The client can receive presence messages. + # + # @spec TB2d + # MODES = ruby_enum('MODES', presence: 0, publish: 1, @@ -33,6 +43,8 @@ class ChannelOptions def_delegators :attributes, :fetch, :size, :empty? # Initialize a new ChannelOptions # + # @spec TB3 + # # @option params [Hash] (TB2c) params (for realtime client libraries only) a of key/value pairs # @option modes [Hash] modes (for realtime client libraries only) an array of ChannelMode # @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 @@ def initialize(attrs) attributes.clone end - # @!attribute cipher + # Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, + # chaining mode, key length and key). See an example. + # + # @spec RSL5a, TB2b # # @return [CipherParams] + # def cipher attributes[:cipher] end - # @!attribute params + # Channel Parameters that configure the behavior of the channel. + # + # @spec TB2c # # @return [Hash] + # def params attributes[:params].to_h end - # @!attribute modes + # An array of {Ably:Models:ChannelOptions::MODES} objects. + # + # @spec TB2d # # @return [Array] + # def modes attributes[:modes] end @@ -69,6 +91,7 @@ def modes # Converts modes to a bitfield that coresponds to ProtocolMessage#flags # # @return [Integer] + # def modes_to_flags modes.map { |mode| Ably::Models::ProtocolMessage::ATTACH_FLAGS_MAPPING[mode.to_sym] }.reduce(:|) end From c8b8fe68f7991a7bc8b12131fe93af5596826eda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:59:30 +0200 Subject: [PATCH 51/70] Fix lib/ably/models/channel_occupancy.rb descriptions --- lib/ably/models/channel_occupancy.rb | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/lib/ably/models/channel_occupancy.rb b/lib/ably/models/channel_occupancy.rb index 2a02a6126..eef9e51aa 100644 --- a/lib/ably/models/channel_occupancy.rb +++ b/lib/ably/models/channel_occupancy.rb @@ -4,6 +4,7 @@ module Ably::Models # @param attributes (see #initialize) # # @return [ChannelOccupancy] + # def self.ChannelOccupancy(attributes) case attributes when ChannelOccupancy @@ -13,14 +14,18 @@ def self.ChannelOccupancy(attributes) end end - # Type that contain channel metrics (CHO1) + # Contains the metrics of a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel} object. + # + # @spec CHO1 # class ChannelOccupancy extend Ably::Modules::Enum extend Forwardable include Ably::Modules::ModelCommon - # The attributes of ChannelOccupancy (CH02) + # The attributes of ChannelOccupancy. + # + # @spec CH02 # attr_reader :attributes @@ -32,7 +37,9 @@ def initialize(attrs) @attributes = IdiomaticRubyWrapper(attrs.clone) end - # Metrics object (CHO2a) + # A {Ably::Models::ChannelMetrics} object. + # + # @spec CHO2a # # @return [Ably::Models::ChannelMetrics, nil] # From 3a73825d8fd9426af26ecf978519d19feb378da7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:59:40 +0200 Subject: [PATCH 52/70] Fix lib/ably/models/channel_metrics.rb descriptions --- lib/ably/models/channel_metrics.rb | 39 ++++++++++++++++++++++++------ 1 file changed, 31 insertions(+), 8 deletions(-) diff --git a/lib/ably/models/channel_metrics.rb b/lib/ably/models/channel_metrics.rb index e83c25df5..05f57ad83 100644 --- a/lib/ably/models/channel_metrics.rb +++ b/lib/ably/models/channel_metrics.rb @@ -4,6 +4,7 @@ module Ably::Models # @param attributes (see #initialize) # # @return [ChannelMetrics] + # def self.ChannelMetrics(attributes) case attributes when ChannelMetrics @@ -13,8 +14,10 @@ def self.ChannelMetrics(attributes) end end - # ChannelMetrics is a type that contains the count of publishers and subscribers, connections and presenceConnections, - # presenceMembers and presenceSubscribers (CHM1) + # Contains the metrics associated with a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel}, + # such as the number of publishers, subscribers and connections it has. + # + # @spec CHM1 # class ChannelMetrics extend Ably::Modules::Enum @@ -33,7 +36,9 @@ def initialize(attrs) @attributes = IdiomaticRubyWrapper(attrs.clone) end - # The total number of connections to the channel (CHM2a) + # The number of realtime connections attached to the channel. + # + # @spec CHM2a # # @return [Integer] # @@ -41,7 +46,11 @@ def connections attributes[:connections] end - # The total number of presence connections to the channel (CHM2b) + # The number of realtime connections attached to the channel with permission to enter the presence set, regardless + # of whether or not they have entered it. This requires the presence capability and for a client to not have specified + # a {Ably::Models::ChannelOptions::MODES} flag that excludes {Ably::Models::ChannelOptions::MODES}#PRESENCE. + # + # @spec CHM2b # # @return [Integer] # @@ -49,7 +58,9 @@ def presence_connections attributes[:presence_connections] end - # The total number of presence members for the channel (CHM2c) + # The number of members in the presence set of the channel. + # + # @spec CHM2c # # @return [Integer] # @@ -57,7 +68,11 @@ def presence_members attributes[:presence_members] end - # The total number of presence subscribers for the channel (CHM2d) + # The number of realtime attachments receiving presence messages on the channel. This requires the subscribe capability + # and for a client to not have specified a {Ably::Models::ChannelOptions::MODES} flag that excludes + # {Ably::Models::ChannelOptions::MODES}#PRESENCE_SUBSCRIBE. + # + # @spec CHM2d # # @return [Integer] # @@ -65,7 +80,11 @@ def presence_subscribers attributes[:presence_subscribers] end - # The total number of publishers to the channel (CHM2e) + # The number of realtime attachments permitted to publish messages to the channel. This requires the publish + # capability and for a client to not have specified a {Ably::Models::ChannelOptions::MODES} flag that excludes + # {Ably::Models::ChannelOptions::MODES}#PUBLISH. + # + # @spec CHM2e # # @return [Integer] # @@ -73,7 +92,11 @@ def publishers attributes[:publishers] end - # The total number of subscribers to the channel (CHM2f) + # The number of realtime attachments receiving messages on the channel. This requires the subscribe capability and + # for a client to not have specified a {Ably::Models::ChannelOptions::MODES} flag that excludes + # {Ably::Models::ChannelOptions::MODES}#SUBSCRIBE. + # + # @spec CHM2f # # @return [Integer] # From c49e0e78dd4b4e08f7ed13a88abcde0b43434511 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 16:59:53 +0200 Subject: [PATCH 53/70] Fix lib/ably/models/channel_details.rb descriptions --- lib/ably/models/channel_details.rb | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/lib/ably/models/channel_details.rb b/lib/ably/models/channel_details.rb index 09bf0d4b1..268bd5588 100644 --- a/lib/ably/models/channel_details.rb +++ b/lib/ably/models/channel_details.rb @@ -4,6 +4,7 @@ module Ably::Models # @param attributes (see #initialize) # # @return [ChannelDetails] + # def self.ChannelDetails(attributes) case attributes when ChannelDetails @@ -13,14 +14,17 @@ def self.ChannelDetails(attributes) end end - # ChannelDetails is a type that represents information for a channel including channelId, name, status and occupancy (CHD1) + # Contains the details of a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel} object + # such as its ID and {Ably::Models::ChannelStatus}. # class ChannelDetails extend Ably::Modules::Enum extend Forwardable include Ably::Modules::ModelCommon - # The attributes of ChannelDetails (CHD2) + # The attributes of ChannelDetails + # + # @spec CHD2 # attr_reader :attributes @@ -32,7 +36,9 @@ def initialize(attrs) @attributes = IdiomaticRubyWrapper(attrs.clone) end - # The identifier of the channel (CHD2a) + # The identifier of the channel + # + # @spec CHD2a # # @return [String] # @@ -40,7 +46,9 @@ def channel_id attributes[:channel_id] end - # The identifier of the channel (CHD2a) + # The identifier of the channel + # + # @spec CHD2a # # @return [String] # @@ -48,7 +56,9 @@ def name attributes[:name] end - # The status of the channel (CHD2b) + # A {Ably::Models::ChannelStatus} object. + # + # @spec CHD2b # # @return [Ably::Models::ChannelStatus, nil] # From af0489f32ac4eb8adbf4fa7162dbf90833926896 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 17:00:04 +0200 Subject: [PATCH 54/70] Fix lib/ably/models/auth_details.rb descriptions --- lib/ably/models/auth_details.rb | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/lib/ably/models/auth_details.rb b/lib/ably/models/auth_details.rb index 3439b1334..757392d15 100644 --- a/lib/ably/models/auth_details.rb +++ b/lib/ably/models/auth_details.rb @@ -4,6 +4,7 @@ module Ably::Models # @param attributes (see #initialize) # # @return [AuthDetails] + # def self.AuthDetails(attributes) case attributes when AuthDetails @@ -27,14 +28,16 @@ def initialize(attributes = {}) self.attributes.freeze end - %w(access_token).each do |attribute| - define_method attribute do - attributes[attribute.to_sym] - end + # The authentication token string. + # + # @spec AD2 + # + # @return [String] + # + def access_token + attributes[:access_token] end - # @!attribute [r] attributes - # @return [Hash] Access the token details Hash object ruby'fied to use symbolized keys def attributes @hash_object end From 887f442c16ba77c5de3989b83ddfc3b0e1fad171 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 17:00:14 +0200 Subject: [PATCH 55/70] Fix lib/ably/auth.rb descriptions --- lib/ably/auth.rb | 49 +++++++++++++++++++++++++----------------------- 1 file changed, 26 insertions(+), 23 deletions(-) diff --git a/lib/ably/auth.rb b/lib/ably/auth.rb index bb10af52f..1e6e03fa6 100644 --- a/lib/ably/auth.rb +++ b/lib/ably/auth.rb @@ -5,24 +5,7 @@ require 'ably/rest/middleware/external_exceptions' module Ably - # Auth is responsible for authentication with {https://www.ably.com Ably} using basic or token authentication - # - # Find out more about Ably authentication at: https://www.ably.com/docs/general/authentication/ - # - # @!attribute [r] client_id - # @return [String] The provided client ID, used for identifying this client for presence purposes - # @!attribute [r] current_token_details - # @return [Ably::Models::TokenDetails] Current {Ably::Models::TokenDetails} issued by this library or one of the provided callbacks used to authenticate requests - # @!attribute [r] key - # @return [String] Complete API key containing both the key name and key secret, if present - # @!attribute [r] key_name - # @return [String] Key name (public part of the API key), if present - # @!attribute [r] key_secret - # @return [String] Key secret (private secure part of the API key), if present - # @!attribute [r] options - # @return [Hash] Default {Ably::Auth} options configured for this client - # @!attribute [r] token_params - # @return [Hash] Default token params used for token requests, see {#request_token} + # Creates Ably {Ably::Models::TokenRequest} objects and obtains Ably Tokens from Ably to subsequently issue to less trusted clients. # class Auth include Ably::Modules::Conversions @@ -124,9 +107,13 @@ def initialize(client, token_params, auth_options) @token_params.freeze end - # 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. + # Instructs the library to get a new token immediately. When using the realtime client, it upgrades the current + # realtime connection to use the new token, or if not connected, initiates a connection to Ably, once the new token + # has been obtained. Also stores any `token_params` and `auth_options` passed + # in as the new defaults, to be used for all subsequent implicit or explicit token requests. Any `token_params` + # and `auth_options` objects passed in entirely replace, as opposed to being merged with, the current client library saved values. # - # In the event that a new token request is made, the provided options are used. + # @spec RSA10 # # @param [Hash, nil] token_params the token params used for future token requests. When nil, previously configured token params are used # @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 @@ def authorise(*args, &block) authorize(*args, &block) end - # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests + # Calls the requestToken REST API endpoint to obtain an Ably Token according to the specified `token_params` and `auth_options`. + # Both `token_params` and `auth_options` are optional. When omitted or null, the default token parameters and authentication + # options for the client library are used, as specified in the `client_options` when the client library was instantiated, + # or later updated with an explicit authorize request. Values passed in are used instead of, rather than being merged with, the default values. + # To understand why an Ably {Ably::Models::TokenRequest} may be issued to clients in favor of a token, see Token Authentication explained. + # + # @spec RSA8e # # @param [Hash] auth_options (see #create_token_request) # @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 @@ def authorise(*args, &block) # @param [Hash] token_params (see #create_token_request) # @option (see #create_token_request) # - # @return [Ably::Models::TokenDetails] + # @return [Ably::Models::TokenDetails] A {Ably::Models::TokenDetails} object. RSA16 # # @example # # simple token request using basic auth @@ -273,7 +266,17 @@ def request_token(token_params = {}, auth_options = {}) send_token_request(token_request) end - # Creates and signs a token request that can then subsequently be used by any client to request a token + # Creates and signs an {Ably::Models::TokenRequest} based on the specified (or if none specified, the client + # library stored) `token_params` and `auth_options`. Note this can only be used when the API key value is available + # locally. Otherwise, the {Ably::Models::TokenRequest} must be obtained from the key owner. Use this to generate + # an {Ably::Models::TokenRequest} in order to implement an Ably Token request callback for use by other clients. + # Both `token_params` and `auth_options` are optional. When omitted or null, the default token parameters + # and authentication options for the client library are used, as specified in the `client_options` when the client + # library was instantiated, or later updated with an explicit authorize request. Values passed in are used instead + # of, rather than being merged with, the default values. To understand why an {Ably::Models::TokenRequest} may be + # issued to clients in favor of a token, see Token Authentication explained. + # + # @spec RSA9 # # @param [Hash] token_params the token params used in the token request # @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+ From 0641332b03f28e7be8c268b8a2b0c1ec27d5efe4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 17:00:26 +0200 Subject: [PATCH 56/70] Fix README.md --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 1fbcf2052..8db35c683 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,15 @@ -# [Ably](https://ably.com) +# Ably `Ruby` Client Library SDK API Reference [![Gem Version](https://img.shields.io/gem/v/ably?style=flat)](https://img.shields.io/gem/v/ably?style=flat) [![Coverage Status](https://coveralls.io/repos/ably/ably-ruby/badge.svg)](https://coveralls.io/r/ably/ably-ruby) -_[Ably](https://ably.com) is the platform that powers synchronized digital experiences in realtime. Whether attending an event in a virtual venue, receiving realtime financial information, or monitoring live car performance data – consumers simply expect realtime digital experiences as standard. Ably provides a suite of APIs to build, extend, and deliver powerful digital experiences in realtime for more than 250 million devices across 80 countries each month. Organizations like Bloomberg, HubSpot, Verizon, and Hopin depend on Ably’s platform to offload the growing complexity of business-critical realtime data synchronization at global scale. For more information, see the [Ably documentation](https://ably.com/documentation)._ +The `Ruby` Client Library SDK supports a realtime and a REST interface. -This is a Ruby client library for Ably. The library currently targets the [Ably 1.2 client library specification](https://ably.com/documentation/client-lib-development-guide/features/). You can see the complete list of features this client library supports in [our client library SDKs feature support matrix](https://ably.com/download/sdk-feature-support-matrix). +The realtime interface enables a client to maintain a persistent connection to Ably and publish, subscribe and be present on channels. The REST interface is stateless and typically implemented server-side. It is used to make requests such as retrieving statistics, token authentication and publishing to a channel. + +**Note**: The `Ruby` Client Library SDK implements the realtime and REST interfaces as two separate libraries. + +The `Ruby` API references are generated from the [Ably `Ruby` Client Library SDK source code](https://github.com/ably/ably-ruby) using [`yard`](https://yardoc.org/). View the [Ably docs](http://ably.com/docs/) for conceptual information on using Ably and for client library API references split between the [realtime](http://ably.com/docs/api/realtime-sdk) and [REST](http://ably.com/docs/api/rest-sdk) interfaces. ## Supported platforms @@ -17,10 +21,6 @@ We regression-test the SDK against a selection of Ruby versions (which we update If you find any compatibility issues, please [do raise an issue](https://github.com/ably/ably-ruby/issues/new) in this repository or [contact Ably customer support](https://ably.com/support/) for advice. -## Documentation - -Visit https://ably.com/documentation for a complete API reference and code examples. - ## Installation The client library is available as a [gem from RubyGems.org](https://rubygems.org/gems/ably). From ad530ba3af943b3a0b8361a8d213d3affc330023 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 17:06:13 +0200 Subject: [PATCH 57/70] Fix lib/ably/models/device_push_details.rb --- lib/ably/models/device_push_details.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/ably/models/device_push_details.rb b/lib/ably/models/device_push_details.rb index 45e1b7cc4..00b9679fe 100644 --- a/lib/ably/models/device_push_details.rb +++ b/lib/ably/models/device_push_details.rb @@ -43,7 +43,7 @@ def state def state=(val) unless val.nil? || val.kind_of?(String) - raise ArgumentError, "#{attribute} must be nil or a string value" + raise ArgumentError, "state must be nil or a string value" end attributes[:state] = val end From add50411be4cf915b7b283611e4d6e864b1d71f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 12 Sep 2022 17:13:13 +0200 Subject: [PATCH 58/70] Fix lib/ably/models/presence_message.rb --- lib/ably/models/presence_message.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/ably/models/presence_message.rb b/lib/ably/models/presence_message.rb index 5e9ecc5f8..f30582f52 100644 --- a/lib/ably/models/presence_message.rb +++ b/lib/ably/models/presence_message.rb @@ -86,7 +86,7 @@ def client_id # @return [Hash, nil] # def data - attributes[:date] + attributes[:data] end # This will typically be empty as all presence messages received from Ably are automatically decoded client-side From 958cc0cc1254ec55134a794baf04744fe33a2292 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 19 Sep 2022 16:09:30 +0200 Subject: [PATCH 59/70] Revert "Fix README.md" This reverts commit 0641332b03f28e7be8c268b8a2b0c1ec27d5efe4. --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 8db35c683..1fbcf2052 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,11 @@ -# Ably `Ruby` Client Library SDK API Reference +# [Ably](https://ably.com) [![Gem Version](https://img.shields.io/gem/v/ably?style=flat)](https://img.shields.io/gem/v/ably?style=flat) [![Coverage Status](https://coveralls.io/repos/ably/ably-ruby/badge.svg)](https://coveralls.io/r/ably/ably-ruby) -The `Ruby` Client Library SDK supports a realtime and a REST interface. +_[Ably](https://ably.com) is the platform that powers synchronized digital experiences in realtime. Whether attending an event in a virtual venue, receiving realtime financial information, or monitoring live car performance data – consumers simply expect realtime digital experiences as standard. Ably provides a suite of APIs to build, extend, and deliver powerful digital experiences in realtime for more than 250 million devices across 80 countries each month. Organizations like Bloomberg, HubSpot, Verizon, and Hopin depend on Ably’s platform to offload the growing complexity of business-critical realtime data synchronization at global scale. For more information, see the [Ably documentation](https://ably.com/documentation)._ -The realtime interface enables a client to maintain a persistent connection to Ably and publish, subscribe and be present on channels. The REST interface is stateless and typically implemented server-side. It is used to make requests such as retrieving statistics, token authentication and publishing to a channel. - -**Note**: The `Ruby` Client Library SDK implements the realtime and REST interfaces as two separate libraries. - -The `Ruby` API references are generated from the [Ably `Ruby` Client Library SDK source code](https://github.com/ably/ably-ruby) using [`yard`](https://yardoc.org/). View the [Ably docs](http://ably.com/docs/) for conceptual information on using Ably and for client library API references split between the [realtime](http://ably.com/docs/api/realtime-sdk) and [REST](http://ably.com/docs/api/rest-sdk) interfaces. +This is a Ruby client library for Ably. The library currently targets the [Ably 1.2 client library specification](https://ably.com/documentation/client-lib-development-guide/features/). You can see the complete list of features this client library supports in [our client library SDKs feature support matrix](https://ably.com/download/sdk-feature-support-matrix). ## Supported platforms @@ -21,6 +17,10 @@ We regression-test the SDK against a selection of Ruby versions (which we update If you find any compatibility issues, please [do raise an issue](https://github.com/ably/ably-ruby/issues/new) in this repository or [contact Ably customer support](https://ably.com/support/) for advice. +## Documentation + +Visit https://ably.com/documentation for a complete API reference and code examples. + ## Installation The client library is available as a [gem from RubyGems.org](https://rubygems.org/gems/ably). From 9ef147855d3745943a73b4ec1b4505b946a3b4f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 19 Sep 2022 18:06:41 +0200 Subject: [PATCH 60/70] Add INTRO.md --- INTRO.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 INTRO.md diff --git a/INTRO.md b/INTRO.md new file mode 100644 index 000000000..595249ddc --- /dev/null +++ b/INTRO.md @@ -0,0 +1,14 @@ +# Ably `Ruby` Client Library SDK API Reference + +The `Ruby` Client Library SDK supports a realtime and a REST interface. + +The realtime interface enables a client to maintain a persistent connection to Ably and publish, subscribe and be present on channels. +The REST interface is stateless and typically implemented server-side. It is used to make requests such as retrieving statistics, +token authentication and publishing to a channel. + +**Note**: The `Ruby` Client Library SDK implements the realtime and REST interfaces as two separate libraries. + +The `Ruby` API references are generated from the [Ably `Ruby` Client Library SDK source code](https://github.com/ably/ably-ruby) +using [`yard`](https://yardoc.org/). View the [Ably docs](http://ably.com/docs/) for conceptual information on using Ably +and for client library API references split between the [realtime](http://ably.com/docs/api/realtime-sdk) +and [REST](http://ably.com/docs/api/rest-sdk) interfaces. From 929d776665135a3e578c74754a271cbd548465bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 19 Sep 2022 18:08:37 +0200 Subject: [PATCH 61/70] Set --readme option to yard --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 735569f20..f51773c86 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -19,7 +19,7 @@ jobs: - name: Build Documentation run: | - bundle exec yard + bundle exec yard --readme INTRO.md ls -al doc/ - name: Configure AWS Credentials uses: aws-actions/configure-aws-credentials@v1 From d240e61f5979e4dfe4552dd6c8fe265c45609069 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 19 Sep 2022 18:09:47 +0200 Subject: [PATCH 62/70] Add newline --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f51773c86..faa4a9a36 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -33,4 +33,4 @@ jobs: with: sourcePath: doc/ githubToken: ${{ secrets.GITHUB_TOKEN }} - artifactName: docs \ No newline at end of file + artifactName: docs From acd5b50ac1777f6fef21f24e0ca11c982785e085 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 19 Sep 2022 18:21:05 +0200 Subject: [PATCH 63/70] Fix lib/ably/models/idiomatic_ruby_wrapper.rb --- lib/ably/models/idiomatic_ruby_wrapper.rb | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/lib/ably/models/idiomatic_ruby_wrapper.rb b/lib/ably/models/idiomatic_ruby_wrapper.rb index bc903f568..d41cf1775 100644 --- a/lib/ably/models/idiomatic_ruby_wrapper.rb +++ b/lib/ably/models/idiomatic_ruby_wrapper.rb @@ -36,6 +36,9 @@ module Ably::Models # ruby_hash[:none] # => nil # ruby_hash.none # => nil # + # @!attribute [r] stop_at + # @return [Array] array of keys that this wrapper should stop wrapping at to preserve the underlying Hash as is + # class IdiomaticRubyWrapper include Enumerable include Ably::Modules::Conversions @@ -140,6 +143,8 @@ def method_missing(method_sym, *arguments) end end + # @!attribute [r] Hash + # @return [Hash] Access to the raw Hash object provided to the constructor of this wrapper def attributes @attributes end @@ -194,6 +199,8 @@ def to_s attributes.to_s end + # @!attribute [r] hash + # @return [Integer] Compute a hash-code for this hash. Two hashes with the same content will have the same hash code def hash attributes.hash end From bfb059a340d0b682cf6e8147cdf6406f095a7cb6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 19 Sep 2022 18:27:22 +0200 Subject: [PATCH 64/70] Fix lib/ably/models/paginated_result.rb --- lib/ably/models/paginated_result.rb | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/lib/ably/models/paginated_result.rb b/lib/ably/models/paginated_result.rb index bf8a36990..47b8c5d24 100644 --- a/lib/ably/models/paginated_result.rb +++ b/lib/ably/models/paginated_result.rb @@ -57,7 +57,10 @@ def first(&success_callback) end end - # Returns a new PaginatedResult loaded with the next page of results. If there are no further pages, then null is returned. + # Retrieve the next page of results. + # + # When used as part of the {Ably::Realtime} library, it will return a {Ably::Util::SafeDeferrable} object, + # and allows an optional success callback block to be provided. # # @spec TG4 # From 69175962ce81cc21a01ce7c81f1a722ea86a0e00 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 19 Sep 2022 18:37:00 +0200 Subject: [PATCH 65/70] Fix lib/ably/models/token_request.rb --- lib/ably/models/token_request.rb | 39 +++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/lib/ably/models/token_request.rb b/lib/ably/models/token_request.rb index 7036dfef5..a568f665b 100644 --- a/lib/ably/models/token_request.rb +++ b/lib/ably/models/token_request.rb @@ -15,7 +15,11 @@ def self.TokenRequest(attributes) end - # Contains the properties of a request for a token to Ably. Tokens are generated using {Ably::Auth#requestToken}. + # Contains the properties of a request for a token to Ably. + # Tokens are generated using {Ably::Auth#requestToken}. + # + # 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 + # it must always be expressed in milliseconds as the Ably API always uses milliseconds for time fields. # class TokenRequest include Ably::Modules::ModelCommon @@ -38,8 +42,13 @@ def initialize(attributes = {}) end # The name of the key against which this request is made. The key name is public, whereas the key secret is private. + # + # @!attribute [r] key_name + # # @spec TE2 + # # @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 +:+ + # def key_name attributes.fetch(:key_name) { raise Ably::Exceptions::InvalidTokenRequest, 'Key name is missing' } end @@ -47,7 +56,11 @@ def key_name # Requested time to live for the Ably Token in milliseconds. If the Ably TokenRequest is successful, the TTL of the # returned Ably Token is less than or equal to this value, depending on application settings and the attributes of # the issuing key. The default is 60 minutes. + # + # @!attribute [r] ttl + # # @spec TE4 + # # @return [Integer] requested time to live for the token in seconds. If the token request is successful, # the TTL of the returned token will be less than or equal to this value depending on application # settings and the attributes of the issuing key. @@ -60,7 +73,11 @@ def ttl # Ably Token will be the intersection of this capability with the capability of the issuing key. The capabilities # value is a JSON-encoded representation of the resource paths and associated operations. Read more about # capabilities in the capabilities docs. + # + # @!attribute [r] capability + # # @spec TE3 + # # @return [Hash] capability of the token. If the token request is successful, # the capability of the returned token will be the intersection of # this capability with the capability of the issuing key. @@ -79,7 +96,11 @@ def capability # The client ID to associate with the requested Ably Token. When provided, the Ably Token may only be used to # perform operations on behalf of that client ID. + # + # @!attribute [r] client_id + # # @spec TE2 + # # @return [String] the client ID to associate with this token. The generated token # may be used to authenticate as this clientId. def client_id @@ -87,7 +108,11 @@ def client_id end # The timestamp of this request as milliseconds since the Unix epoch. + # + # @!attribute [r] timestamp + # # @spec TE5 + # # @return [Time] the timestamp of this request. # Timestamps, in conjunction with the nonce, are used to prevent # token requests from being replayed. @@ -98,7 +123,11 @@ def timestamp end # A cryptographically secure random string of at least 16 characters, used to ensure the TokenRequest cannot be reused. + # + # @!attribute [r] nonce + # # @spec TE2 + # # @return [String] an opaque nonce string of at least 16 characters to ensure # uniqueness of this request. Any subsequent request using the # same nonce will be rejected. @@ -107,19 +136,27 @@ def nonce end # The Message Authentication Code for this request. + # + # @!attribute [r] mac + # # @spec TE2 + # # @return [String] the Message Authentication Code for this request. See the + # def mac attributes.fetch(:mac) { raise Ably::Exceptions::InvalidTokenRequest, 'MAC is missing' } end # Requests that the token is always persisted + # # @api private # def persisted attributes[:persisted] end + # @!attribute [r] attributes + # # @return [Hash] the token request Hash object ruby'fied to use symbolized keys # def attributes From af58660e3fcdbd26475d0f408a01af4740227f88 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 19 Sep 2022 19:13:15 +0200 Subject: [PATCH 66/70] Fix lib/ably/realtime/presence.rb --- lib/ably/realtime/presence.rb | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lib/ably/realtime/presence.rb b/lib/ably/realtime/presence.rb index 7421ea619..0c4fcd3cd 100644 --- a/lib/ably/realtime/presence.rb +++ b/lib/ably/realtime/presence.rb @@ -277,7 +277,8 @@ def subscribe(*actions, &callback) super end - # Deregisters all listeners currently receiving {Ably::Models::PresenceMessage} for the channel. + # Unsubscribe the matching block for presence events on the associated Channel. + # If a block is not provided, all subscriptions will be unsubscribed {Ably::Models::PresenceMessage} for the channel. # # @spec RTP7a, RTP7b, RTE5 # From e5bc1a362b03ed1eade3b7169826f8463b863019 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 19 Sep 2022 20:18:42 +0200 Subject: [PATCH 67/70] Fixe lib/ably/rest/client.rb --- lib/ably/rest/client.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/ably/rest/client.rb b/lib/ably/rest/client.rb index be121a16d..9ba006893 100644 --- a/lib/ably/rest/client.rb +++ b/lib/ably/rest/client.rb @@ -128,7 +128,7 @@ class Client # # @spec RSC1 # - # @param [Hash,String] options an options Hash used to configure the client and the authentication, or String with an API key or Token ID + # @param [Hash,String] options an options Hash or String used to configure the client and the authentication, or String with an API key or Token ID # @option options [Boolean] :tls (true) When false, TLS is disabled. Please note Basic Auth is disallowed without TLS as secrets cannot be transmitted over unsecured connections. # @option options [String] :key API key comprising the key name and key secret in a single string # @option options [String] :token Token string or {Models::TokenDetails} used to authenticate requests From 1157a2dcd57bda030d312909951ec6e90e67a2b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 19 Sep 2022 20:20:32 +0200 Subject: [PATCH 68/70] Fix lib/ably/rest/client.rb --- lib/ably/rest/client.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/ably/rest/client.rb b/lib/ably/rest/client.rb index 9ba006893..9c8e385a5 100644 --- a/lib/ably/rest/client.rb +++ b/lib/ably/rest/client.rb @@ -166,7 +166,7 @@ class Client # @return [Ably::Rest::Client] # # @example - # # The Ably API key or token string used to validate the client. + # # Create a new client authenticating with basic auth # client = Ably::Rest::Client.new('key.id:secret') # # # Construct a RestClient object using an Ably [Hash]{@link Hash} object. @@ -368,7 +368,7 @@ def delete(path, params, options = {}) # # @spec RSC19 # - # @param method [Symbol] The request method to use, such as GET, POST. + # @param method [Symbol] The request method to use, such as :get, :post. # @param path [String] The request path. # @param params [Hash, nil] The parameters to include in the URL query of the request. The parameters depend on the endpoint being queried. See the REST API reference for the available parameters of each endpoint. # @param body [Hash, nil] The JSON body of the request. From d09a686635918a8486fdcce381b51c2ac4aed121 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 19 Sep 2022 20:22:32 +0200 Subject: [PATCH 69/70] Fix lib/ably/rest/client.rb --- lib/ably/rest/client.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/ably/rest/client.rb b/lib/ably/rest/client.rb index 9c8e385a5..235bd81f0 100644 --- a/lib/ably/rest/client.rb +++ b/lib/ably/rest/client.rb @@ -166,10 +166,10 @@ class Client # @return [Ably::Rest::Client] # # @example - # # Create a new client authenticating with basic auth + # # Create a new client authenticating with basic auth using a String object # client = Ably::Rest::Client.new('key.id:secret') # - # # Construct a RestClient object using an Ably [Hash]{@link Hash} object. + # # Construct a RestClient object using a Hash object. # client = Ably::Rest::Client.new(key: 'key.id:secret', client_id: 'john') # def initialize(options) From fb25a5f380a1f332b23680daf4012a8fbaa389d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20=C5=9Aliwa?= Date: Mon, 19 Sep 2022 20:47:55 +0200 Subject: [PATCH 70/70] Add --tag "spec:Specification" to yard --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index faa4a9a36..890e0eab1 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -19,7 +19,7 @@ jobs: - name: Build Documentation run: | - bundle exec yard --readme INTRO.md + bundle exec yard --readme INTRO.md --tag "spec:Specification" ls -al doc/ - name: Configure AWS Credentials uses: aws-actions/configure-aws-credentials@v1