Class: Ably::Realtime::Auth

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Modules::AsyncWrapper
Defined in:
lib/ably/realtime/auth.rb

Overview

Auth is responsible for authentication with Ably using basic or token authentication This Realtime::Auth class wraps the Synchronous Ably::Auth class in an EventMachine friendly way using Deferrables for all IO. See Ably::Auth for more information

Find out more about Ably authentication at: www.ably.io/documentation/general/authentication/

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client) ⇒ Auth

Returns a new instance of Auth.



48
49
50
51
 
# File 'lib/ably/realtime/auth.rb', line 48

def initialize(client)
  @client = client
  @auth_sync = client.rest_client.auth
end

Instance Attribute Details

#authentication_security_requirements_met? ⇒ Boolean (readonly)

Returns false when attempting to send an API Key over a non-secure connection Token auth must be used for non-secure connections

Returns:

  • (Boolean) 


35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/ably/realtime/auth.rb', line 35

class Auth
  extend Forwardable
  include Ably::Modules::AsyncWrapper

  def_delegators :auth_sync, :client_id
  def_delegators :auth_sync, :token_client_id_allowed?, :configure_client_id, :client_id_validated?
  def_delegators :auth_sync, :can_assume_client_id?, :has_client_id?
  def_delegators :auth_sync, :current_token_details, :token
  def_delegators :auth_sync, :key, :key_name, :key_secret, :options, :auth_options, :token_params
  def_delegators :auth_sync, :using_basic_auth?, :using_token_auth?
  def_delegators :auth_sync, :token_renewable?, :authentication_security_requirements_met?
  def_delegators :client, :logger

  def initialize(client)
    @client = client
    @auth_sync = client.rest_client.auth
  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.
  #
  # In the event that a new token request is made, the provided options are used
  #
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # will issue a simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.authorise do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def authorise(token_params = nil, auth_options = nil, &success_callback)
    async_wrap(success_callback) do
      auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
    end.tap do |deferrable|
      deferrable.errback do |error|
        client.connection.transition_state_machine :failed, reason: error if error.kind_of?(Ably::Exceptions::IncompatibleClientId)
      end
    end
  end

  # Synchronous version of {#authorise}. See {Ably::Auth#authorise} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def authorise_sync(token_params = nil, auth_options = nil)
    auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
  end

  # def_delegator :auth_sync, :request_token, :request_token_sync
  # def_delegator :auth_sync, :create_token_request, :create_token_request_sync
  # def_delegator :auth_sync, :auth_header, :auth_header_sync
  # def_delegator :auth_sync, :auth_params, :auth_params_sync

  # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
  #
  # @param (see Ably::Auth#request_token)
  # @option (see Ably::Auth#request_token)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.request_token do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def request_token(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      request_token_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#request_token}. See {Ably::Auth#request_token} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def request_token_sync(token_params = {}, auth_options = {})
    auth_sync.request_token(token_params, auth_options)
  end

  # Creates and signs a token request that can then subsequently be used by any client to request a token
  #
  # @param (see Ably::Auth#create_token_request)
  # @option (see Ably::Auth#create_token_request)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Models::TokenRequest]
  #
  # @example
  #   client.auth.create_token_request({ ttl: 3600 }, id: 'asd.asd') do |token_request|
  #     token_request #=> Ably::Models::TokenRequest
  #   end
  def create_token_request(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      create_token_request_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#create_token_request}. See {Ably::Auth#create_token_request} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenRequest]
  #
  def create_token_request_sync(token_params = {}, auth_options = {})
    auth_sync.create_token_request(token_params, auth_options)
  end

  # Auth header string used in HTTP requests to Ably
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header(&success_callback)
    async_wrap(success_callback) do
      auth_header_sync
    end
  end

  # Synchronous version of {#auth_header}. See {Ably::Auth#auth_header} for method definition
  # @return [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header_sync
    auth_sync.auth_header
  end

  # Auth params used in URI endpoint for Realtime connections
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Hash] Auth params for a new Realtime connection
  #
  def auth_params(&success_callback)
    async_wrap(success_callback) do
      auth_params_sync
    end
  end

  # Synchronous version of {#auth_params}. See {Ably::Auth#auth_params} for method definition
  # @return [Hash] Auth params for a new Realtime connection
  #
  def auth_params_sync
    auth_sync.auth_params
  end

  private
  # The synchronous Auth class instanced by the Rest client
  # @return [Ably::Auth]
  def auth_sync
    @auth_sync
  end

  def client
    @client
  end

  # If authorise is called with true, this block is executed so that it
  # can perform the authentication upgrade
  def upgrade_authentication_block(new_token)
    # This block is called if the authorisation was forced
    if client.connection.connected? || client.connection.connecting?
      logger.debug "Realtime::Auth - authorise called with { force: true } so forcibly disconnecting transport to initiate auth upgrade"
      block = Proc.new do
        if client.connection.transport
          logger.debug "Realtime::Auth - current transport disconnected"
          client.connection.transport.disconnect
        else
          EventMachine.add_timer(0.1, &block)
        end
      end
      block.call
    end
  end
end

#client_id ⇒ String (readonly)

Returns The provided client ID, used for identifying this client for presence purposes.

Returns:

  • (String) —

    The provided client ID, used for identifying this client for presence purposes



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/ably/realtime/auth.rb', line 35

class Auth
  extend Forwardable
  include Ably::Modules::AsyncWrapper

  def_delegators :auth_sync, :client_id
  def_delegators :auth_sync, :token_client_id_allowed?, :configure_client_id, :client_id_validated?
  def_delegators :auth_sync, :can_assume_client_id?, :has_client_id?
  def_delegators :auth_sync, :current_token_details, :token
  def_delegators :auth_sync, :key, :key_name, :key_secret, :options, :auth_options, :token_params
  def_delegators :auth_sync, :using_basic_auth?, :using_token_auth?
  def_delegators :auth_sync, :token_renewable?, :authentication_security_requirements_met?
  def_delegators :client, :logger

  def initialize(client)
    @client = client
    @auth_sync = client.rest_client.auth
  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.
  #
  # In the event that a new token request is made, the provided options are used
  #
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # will issue a simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.authorise do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def authorise(token_params = nil, auth_options = nil, &success_callback)
    async_wrap(success_callback) do
      auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
    end.tap do |deferrable|
      deferrable.errback do |error|
        client.connection.transition_state_machine :failed, reason: error if error.kind_of?(Ably::Exceptions::IncompatibleClientId)
      end
    end
  end

  # Synchronous version of {#authorise}. See {Ably::Auth#authorise} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def authorise_sync(token_params = nil, auth_options = nil)
    auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
  end

  # def_delegator :auth_sync, :request_token, :request_token_sync
  # def_delegator :auth_sync, :create_token_request, :create_token_request_sync
  # def_delegator :auth_sync, :auth_header, :auth_header_sync
  # def_delegator :auth_sync, :auth_params, :auth_params_sync

  # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
  #
  # @param (see Ably::Auth#request_token)
  # @option (see Ably::Auth#request_token)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.request_token do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def request_token(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      request_token_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#request_token}. See {Ably::Auth#request_token} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def request_token_sync(token_params = {}, auth_options = {})
    auth_sync.request_token(token_params, auth_options)
  end

  # Creates and signs a token request that can then subsequently be used by any client to request a token
  #
  # @param (see Ably::Auth#create_token_request)
  # @option (see Ably::Auth#create_token_request)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Models::TokenRequest]
  #
  # @example
  #   client.auth.create_token_request({ ttl: 3600 }, id: 'asd.asd') do |token_request|
  #     token_request #=> Ably::Models::TokenRequest
  #   end
  def create_token_request(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      create_token_request_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#create_token_request}. See {Ably::Auth#create_token_request} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenRequest]
  #
  def create_token_request_sync(token_params = {}, auth_options = {})
    auth_sync.create_token_request(token_params, auth_options)
  end

  # Auth header string used in HTTP requests to Ably
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header(&success_callback)
    async_wrap(success_callback) do
      auth_header_sync
    end
  end

  # Synchronous version of {#auth_header}. See {Ably::Auth#auth_header} for method definition
  # @return [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header_sync
    auth_sync.auth_header
  end

  # Auth params used in URI endpoint for Realtime connections
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Hash] Auth params for a new Realtime connection
  #
  def auth_params(&success_callback)
    async_wrap(success_callback) do
      auth_params_sync
    end
  end

  # Synchronous version of {#auth_params}. See {Ably::Auth#auth_params} for method definition
  # @return [Hash] Auth params for a new Realtime connection
  #
  def auth_params_sync
    auth_sync.auth_params
  end

  private
  # The synchronous Auth class instanced by the Rest client
  # @return [Ably::Auth]
  def auth_sync
    @auth_sync
  end

  def client
    @client
  end

  # If authorise is called with true, this block is executed so that it
  # can perform the authentication upgrade
  def upgrade_authentication_block(new_token)
    # This block is called if the authorisation was forced
    if client.connection.connected? || client.connection.connecting?
      logger.debug "Realtime::Auth - authorise called with { force: true } so forcibly disconnecting transport to initiate auth upgrade"
      block = Proc.new do
        if client.connection.transport
          logger.debug "Realtime::Auth - current transport disconnected"
          client.connection.transport.disconnect
        else
          EventMachine.add_timer(0.1, &block)
        end
      end
      block.call
    end
  end
end

#current_token_details ⇒ Ably::Models::TokenDetails (readonly)

Returns Current Models::TokenDetails issued by this library or one of the provided callbacks used to authenticate requests.

Returns:



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/ably/realtime/auth.rb', line 35

class Auth
  extend Forwardable
  include Ably::Modules::AsyncWrapper

  def_delegators :auth_sync, :client_id
  def_delegators :auth_sync, :token_client_id_allowed?, :configure_client_id, :client_id_validated?
  def_delegators :auth_sync, :can_assume_client_id?, :has_client_id?
  def_delegators :auth_sync, :current_token_details, :token
  def_delegators :auth_sync, :key, :key_name, :key_secret, :options, :auth_options, :token_params
  def_delegators :auth_sync, :using_basic_auth?, :using_token_auth?
  def_delegators :auth_sync, :token_renewable?, :authentication_security_requirements_met?
  def_delegators :client, :logger

  def initialize(client)
    @client = client
    @auth_sync = client.rest_client.auth
  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.
  #
  # In the event that a new token request is made, the provided options are used
  #
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # will issue a simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.authorise do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def authorise(token_params = nil, auth_options = nil, &success_callback)
    async_wrap(success_callback) do
      auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
    end.tap do |deferrable|
      deferrable.errback do |error|
        client.connection.transition_state_machine :failed, reason: error if error.kind_of?(Ably::Exceptions::IncompatibleClientId)
      end
    end
  end

  # Synchronous version of {#authorise}. See {Ably::Auth#authorise} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def authorise_sync(token_params = nil, auth_options = nil)
    auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
  end

  # def_delegator :auth_sync, :request_token, :request_token_sync
  # def_delegator :auth_sync, :create_token_request, :create_token_request_sync
  # def_delegator :auth_sync, :auth_header, :auth_header_sync
  # def_delegator :auth_sync, :auth_params, :auth_params_sync

  # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
  #
  # @param (see Ably::Auth#request_token)
  # @option (see Ably::Auth#request_token)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.request_token do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def request_token(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      request_token_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#request_token}. See {Ably::Auth#request_token} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def request_token_sync(token_params = {}, auth_options = {})
    auth_sync.request_token(token_params, auth_options)
  end

  # Creates and signs a token request that can then subsequently be used by any client to request a token
  #
  # @param (see Ably::Auth#create_token_request)
  # @option (see Ably::Auth#create_token_request)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Models::TokenRequest]
  #
  # @example
  #   client.auth.create_token_request({ ttl: 3600 }, id: 'asd.asd') do |token_request|
  #     token_request #=> Ably::Models::TokenRequest
  #   end
  def create_token_request(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      create_token_request_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#create_token_request}. See {Ably::Auth#create_token_request} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenRequest]
  #
  def create_token_request_sync(token_params = {}, auth_options = {})
    auth_sync.create_token_request(token_params, auth_options)
  end

  # Auth header string used in HTTP requests to Ably
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header(&success_callback)
    async_wrap(success_callback) do
      auth_header_sync
    end
  end

  # Synchronous version of {#auth_header}. See {Ably::Auth#auth_header} for method definition
  # @return [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header_sync
    auth_sync.auth_header
  end

  # Auth params used in URI endpoint for Realtime connections
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Hash] Auth params for a new Realtime connection
  #
  def auth_params(&success_callback)
    async_wrap(success_callback) do
      auth_params_sync
    end
  end

  # Synchronous version of {#auth_params}. See {Ably::Auth#auth_params} for method definition
  # @return [Hash] Auth params for a new Realtime connection
  #
  def auth_params_sync
    auth_sync.auth_params
  end

  private
  # The synchronous Auth class instanced by the Rest client
  # @return [Ably::Auth]
  def auth_sync
    @auth_sync
  end

  def client
    @client
  end

  # If authorise is called with true, this block is executed so that it
  # can perform the authentication upgrade
  def upgrade_authentication_block(new_token)
    # This block is called if the authorisation was forced
    if client.connection.connected? || client.connection.connecting?
      logger.debug "Realtime::Auth - authorise called with { force: true } so forcibly disconnecting transport to initiate auth upgrade"
      block = Proc.new do
        if client.connection.transport
          logger.debug "Realtime::Auth - current transport disconnected"
          client.connection.transport.disconnect
        else
          EventMachine.add_timer(0.1, &block)
        end
      end
      block.call
    end
  end
end

#key ⇒ String (readonly)

Returns Complete API key containing both the key name and key secret, if present.

Returns:

  • (String) —

    Complete API key containing both the key name and key secret, if present



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/ably/realtime/auth.rb', line 35

class Auth
  extend Forwardable
  include Ably::Modules::AsyncWrapper

  def_delegators :auth_sync, :client_id
  def_delegators :auth_sync, :token_client_id_allowed?, :configure_client_id, :client_id_validated?
  def_delegators :auth_sync, :can_assume_client_id?, :has_client_id?
  def_delegators :auth_sync, :current_token_details, :token
  def_delegators :auth_sync, :key, :key_name, :key_secret, :options, :auth_options, :token_params
  def_delegators :auth_sync, :using_basic_auth?, :using_token_auth?
  def_delegators :auth_sync, :token_renewable?, :authentication_security_requirements_met?
  def_delegators :client, :logger

  def initialize(client)
    @client = client
    @auth_sync = client.rest_client.auth
  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.
  #
  # In the event that a new token request is made, the provided options are used
  #
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # will issue a simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.authorise do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def authorise(token_params = nil, auth_options = nil, &success_callback)
    async_wrap(success_callback) do
      auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
    end.tap do |deferrable|
      deferrable.errback do |error|
        client.connection.transition_state_machine :failed, reason: error if error.kind_of?(Ably::Exceptions::IncompatibleClientId)
      end
    end
  end

  # Synchronous version of {#authorise}. See {Ably::Auth#authorise} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def authorise_sync(token_params = nil, auth_options = nil)
    auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
  end

  # def_delegator :auth_sync, :request_token, :request_token_sync
  # def_delegator :auth_sync, :create_token_request, :create_token_request_sync
  # def_delegator :auth_sync, :auth_header, :auth_header_sync
  # def_delegator :auth_sync, :auth_params, :auth_params_sync

  # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
  #
  # @param (see Ably::Auth#request_token)
  # @option (see Ably::Auth#request_token)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.request_token do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def request_token(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      request_token_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#request_token}. See {Ably::Auth#request_token} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def request_token_sync(token_params = {}, auth_options = {})
    auth_sync.request_token(token_params, auth_options)
  end

  # Creates and signs a token request that can then subsequently be used by any client to request a token
  #
  # @param (see Ably::Auth#create_token_request)
  # @option (see Ably::Auth#create_token_request)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Models::TokenRequest]
  #
  # @example
  #   client.auth.create_token_request({ ttl: 3600 }, id: 'asd.asd') do |token_request|
  #     token_request #=> Ably::Models::TokenRequest
  #   end
  def create_token_request(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      create_token_request_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#create_token_request}. See {Ably::Auth#create_token_request} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenRequest]
  #
  def create_token_request_sync(token_params = {}, auth_options = {})
    auth_sync.create_token_request(token_params, auth_options)
  end

  # Auth header string used in HTTP requests to Ably
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header(&success_callback)
    async_wrap(success_callback) do
      auth_header_sync
    end
  end

  # Synchronous version of {#auth_header}. See {Ably::Auth#auth_header} for method definition
  # @return [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header_sync
    auth_sync.auth_header
  end

  # Auth params used in URI endpoint for Realtime connections
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Hash] Auth params for a new Realtime connection
  #
  def auth_params(&success_callback)
    async_wrap(success_callback) do
      auth_params_sync
    end
  end

  # Synchronous version of {#auth_params}. See {Ably::Auth#auth_params} for method definition
  # @return [Hash] Auth params for a new Realtime connection
  #
  def auth_params_sync
    auth_sync.auth_params
  end

  private
  # The synchronous Auth class instanced by the Rest client
  # @return [Ably::Auth]
  def auth_sync
    @auth_sync
  end

  def client
    @client
  end

  # If authorise is called with true, this block is executed so that it
  # can perform the authentication upgrade
  def upgrade_authentication_block(new_token)
    # This block is called if the authorisation was forced
    if client.connection.connected? || client.connection.connecting?
      logger.debug "Realtime::Auth - authorise called with { force: true } so forcibly disconnecting transport to initiate auth upgrade"
      block = Proc.new do
        if client.connection.transport
          logger.debug "Realtime::Auth - current transport disconnected"
          client.connection.transport.disconnect
        else
          EventMachine.add_timer(0.1, &block)
        end
      end
      block.call
    end
  end
end

#key_name ⇒ String (readonly)

Returns Key name (public part of the API key), if present.

Returns:

  • (String) —

    Key name (public part of the API key), if present



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/ably/realtime/auth.rb', line 35

class Auth
  extend Forwardable
  include Ably::Modules::AsyncWrapper

  def_delegators :auth_sync, :client_id
  def_delegators :auth_sync, :token_client_id_allowed?, :configure_client_id, :client_id_validated?
  def_delegators :auth_sync, :can_assume_client_id?, :has_client_id?
  def_delegators :auth_sync, :current_token_details, :token
  def_delegators :auth_sync, :key, :key_name, :key_secret, :options, :auth_options, :token_params
  def_delegators :auth_sync, :using_basic_auth?, :using_token_auth?
  def_delegators :auth_sync, :token_renewable?, :authentication_security_requirements_met?
  def_delegators :client, :logger

  def initialize(client)
    @client = client
    @auth_sync = client.rest_client.auth
  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.
  #
  # In the event that a new token request is made, the provided options are used
  #
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # will issue a simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.authorise do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def authorise(token_params = nil, auth_options = nil, &success_callback)
    async_wrap(success_callback) do
      auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
    end.tap do |deferrable|
      deferrable.errback do |error|
        client.connection.transition_state_machine :failed, reason: error if error.kind_of?(Ably::Exceptions::IncompatibleClientId)
      end
    end
  end

  # Synchronous version of {#authorise}. See {Ably::Auth#authorise} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def authorise_sync(token_params = nil, auth_options = nil)
    auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
  end

  # def_delegator :auth_sync, :request_token, :request_token_sync
  # def_delegator :auth_sync, :create_token_request, :create_token_request_sync
  # def_delegator :auth_sync, :auth_header, :auth_header_sync
  # def_delegator :auth_sync, :auth_params, :auth_params_sync

  # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
  #
  # @param (see Ably::Auth#request_token)
  # @option (see Ably::Auth#request_token)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.request_token do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def request_token(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      request_token_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#request_token}. See {Ably::Auth#request_token} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def request_token_sync(token_params = {}, auth_options = {})
    auth_sync.request_token(token_params, auth_options)
  end

  # Creates and signs a token request that can then subsequently be used by any client to request a token
  #
  # @param (see Ably::Auth#create_token_request)
  # @option (see Ably::Auth#create_token_request)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Models::TokenRequest]
  #
  # @example
  #   client.auth.create_token_request({ ttl: 3600 }, id: 'asd.asd') do |token_request|
  #     token_request #=> Ably::Models::TokenRequest
  #   end
  def create_token_request(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      create_token_request_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#create_token_request}. See {Ably::Auth#create_token_request} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenRequest]
  #
  def create_token_request_sync(token_params = {}, auth_options = {})
    auth_sync.create_token_request(token_params, auth_options)
  end

  # Auth header string used in HTTP requests to Ably
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header(&success_callback)
    async_wrap(success_callback) do
      auth_header_sync
    end
  end

  # Synchronous version of {#auth_header}. See {Ably::Auth#auth_header} for method definition
  # @return [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header_sync
    auth_sync.auth_header
  end

  # Auth params used in URI endpoint for Realtime connections
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Hash] Auth params for a new Realtime connection
  #
  def auth_params(&success_callback)
    async_wrap(success_callback) do
      auth_params_sync
    end
  end

  # Synchronous version of {#auth_params}. See {Ably::Auth#auth_params} for method definition
  # @return [Hash] Auth params for a new Realtime connection
  #
  def auth_params_sync
    auth_sync.auth_params
  end

  private
  # The synchronous Auth class instanced by the Rest client
  # @return [Ably::Auth]
  def auth_sync
    @auth_sync
  end

  def client
    @client
  end

  # If authorise is called with true, this block is executed so that it
  # can perform the authentication upgrade
  def upgrade_authentication_block(new_token)
    # This block is called if the authorisation was forced
    if client.connection.connected? || client.connection.connecting?
      logger.debug "Realtime::Auth - authorise called with { force: true } so forcibly disconnecting transport to initiate auth upgrade"
      block = Proc.new do
        if client.connection.transport
          logger.debug "Realtime::Auth - current transport disconnected"
          client.connection.transport.disconnect
        else
          EventMachine.add_timer(0.1, &block)
        end
      end
      block.call
    end
  end
end

#key_secret ⇒ String (readonly)

Returns Key secret (private secure part of the API key), if present.

Returns:

  • (String) —

    Key secret (private secure part of the API key), if present



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/ably/realtime/auth.rb', line 35

class Auth
  extend Forwardable
  include Ably::Modules::AsyncWrapper

  def_delegators :auth_sync, :client_id
  def_delegators :auth_sync, :token_client_id_allowed?, :configure_client_id, :client_id_validated?
  def_delegators :auth_sync, :can_assume_client_id?, :has_client_id?
  def_delegators :auth_sync, :current_token_details, :token
  def_delegators :auth_sync, :key, :key_name, :key_secret, :options, :auth_options, :token_params
  def_delegators :auth_sync, :using_basic_auth?, :using_token_auth?
  def_delegators :auth_sync, :token_renewable?, :authentication_security_requirements_met?
  def_delegators :client, :logger

  def initialize(client)
    @client = client
    @auth_sync = client.rest_client.auth
  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.
  #
  # In the event that a new token request is made, the provided options are used
  #
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # will issue a simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.authorise do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def authorise(token_params = nil, auth_options = nil, &success_callback)
    async_wrap(success_callback) do
      auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
    end.tap do |deferrable|
      deferrable.errback do |error|
        client.connection.transition_state_machine :failed, reason: error if error.kind_of?(Ably::Exceptions::IncompatibleClientId)
      end
    end
  end

  # Synchronous version of {#authorise}. See {Ably::Auth#authorise} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def authorise_sync(token_params = nil, auth_options = nil)
    auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
  end

  # def_delegator :auth_sync, :request_token, :request_token_sync
  # def_delegator :auth_sync, :create_token_request, :create_token_request_sync
  # def_delegator :auth_sync, :auth_header, :auth_header_sync
  # def_delegator :auth_sync, :auth_params, :auth_params_sync

  # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
  #
  # @param (see Ably::Auth#request_token)
  # @option (see Ably::Auth#request_token)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.request_token do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def request_token(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      request_token_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#request_token}. See {Ably::Auth#request_token} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def request_token_sync(token_params = {}, auth_options = {})
    auth_sync.request_token(token_params, auth_options)
  end

  # Creates and signs a token request that can then subsequently be used by any client to request a token
  #
  # @param (see Ably::Auth#create_token_request)
  # @option (see Ably::Auth#create_token_request)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Models::TokenRequest]
  #
  # @example
  #   client.auth.create_token_request({ ttl: 3600 }, id: 'asd.asd') do |token_request|
  #     token_request #=> Ably::Models::TokenRequest
  #   end
  def create_token_request(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      create_token_request_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#create_token_request}. See {Ably::Auth#create_token_request} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenRequest]
  #
  def create_token_request_sync(token_params = {}, auth_options = {})
    auth_sync.create_token_request(token_params, auth_options)
  end

  # Auth header string used in HTTP requests to Ably
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header(&success_callback)
    async_wrap(success_callback) do
      auth_header_sync
    end
  end

  # Synchronous version of {#auth_header}. See {Ably::Auth#auth_header} for method definition
  # @return [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header_sync
    auth_sync.auth_header
  end

  # Auth params used in URI endpoint for Realtime connections
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Hash] Auth params for a new Realtime connection
  #
  def auth_params(&success_callback)
    async_wrap(success_callback) do
      auth_params_sync
    end
  end

  # Synchronous version of {#auth_params}. See {Ably::Auth#auth_params} for method definition
  # @return [Hash] Auth params for a new Realtime connection
  #
  def auth_params_sync
    auth_sync.auth_params
  end

  private
  # The synchronous Auth class instanced by the Rest client
  # @return [Ably::Auth]
  def auth_sync
    @auth_sync
  end

  def client
    @client
  end

  # If authorise is called with true, this block is executed so that it
  # can perform the authentication upgrade
  def upgrade_authentication_block(new_token)
    # This block is called if the authorisation was forced
    if client.connection.connected? || client.connection.connecting?
      logger.debug "Realtime::Auth - authorise called with { force: true } so forcibly disconnecting transport to initiate auth upgrade"
      block = Proc.new do
        if client.connection.transport
          logger.debug "Realtime::Auth - current transport disconnected"
          client.connection.transport.disconnect
        else
          EventMachine.add_timer(0.1, &block)
        end
      end
      block.call
    end
  end
end

#options ⇒ Hash (readonly)

Returns Default Auth options configured for this client.

Returns:

  • (Hash) —

    Default Auth options configured for this client



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/ably/realtime/auth.rb', line 35

class Auth
  extend Forwardable
  include Ably::Modules::AsyncWrapper

  def_delegators :auth_sync, :client_id
  def_delegators :auth_sync, :token_client_id_allowed?, :configure_client_id, :client_id_validated?
  def_delegators :auth_sync, :can_assume_client_id?, :has_client_id?
  def_delegators :auth_sync, :current_token_details, :token
  def_delegators :auth_sync, :key, :key_name, :key_secret, :options, :auth_options, :token_params
  def_delegators :auth_sync, :using_basic_auth?, :using_token_auth?
  def_delegators :auth_sync, :token_renewable?, :authentication_security_requirements_met?
  def_delegators :client, :logger

  def initialize(client)
    @client = client
    @auth_sync = client.rest_client.auth
  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.
  #
  # In the event that a new token request is made, the provided options are used
  #
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # will issue a simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.authorise do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def authorise(token_params = nil, auth_options = nil, &success_callback)
    async_wrap(success_callback) do
      auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
    end.tap do |deferrable|
      deferrable.errback do |error|
        client.connection.transition_state_machine :failed, reason: error if error.kind_of?(Ably::Exceptions::IncompatibleClientId)
      end
    end
  end

  # Synchronous version of {#authorise}. See {Ably::Auth#authorise} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def authorise_sync(token_params = nil, auth_options = nil)
    auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
  end

  # def_delegator :auth_sync, :request_token, :request_token_sync
  # def_delegator :auth_sync, :create_token_request, :create_token_request_sync
  # def_delegator :auth_sync, :auth_header, :auth_header_sync
  # def_delegator :auth_sync, :auth_params, :auth_params_sync

  # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
  #
  # @param (see Ably::Auth#request_token)
  # @option (see Ably::Auth#request_token)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.request_token do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def request_token(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      request_token_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#request_token}. See {Ably::Auth#request_token} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def request_token_sync(token_params = {}, auth_options = {})
    auth_sync.request_token(token_params, auth_options)
  end

  # Creates and signs a token request that can then subsequently be used by any client to request a token
  #
  # @param (see Ably::Auth#create_token_request)
  # @option (see Ably::Auth#create_token_request)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Models::TokenRequest]
  #
  # @example
  #   client.auth.create_token_request({ ttl: 3600 }, id: 'asd.asd') do |token_request|
  #     token_request #=> Ably::Models::TokenRequest
  #   end
  def create_token_request(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      create_token_request_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#create_token_request}. See {Ably::Auth#create_token_request} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenRequest]
  #
  def create_token_request_sync(token_params = {}, auth_options = {})
    auth_sync.create_token_request(token_params, auth_options)
  end

  # Auth header string used in HTTP requests to Ably
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header(&success_callback)
    async_wrap(success_callback) do
      auth_header_sync
    end
  end

  # Synchronous version of {#auth_header}. See {Ably::Auth#auth_header} for method definition
  # @return [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header_sync
    auth_sync.auth_header
  end

  # Auth params used in URI endpoint for Realtime connections
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Hash] Auth params for a new Realtime connection
  #
  def auth_params(&success_callback)
    async_wrap(success_callback) do
      auth_params_sync
    end
  end

  # Synchronous version of {#auth_params}. See {Ably::Auth#auth_params} for method definition
  # @return [Hash] Auth params for a new Realtime connection
  #
  def auth_params_sync
    auth_sync.auth_params
  end

  private
  # The synchronous Auth class instanced by the Rest client
  # @return [Ably::Auth]
  def auth_sync
    @auth_sync
  end

  def client
    @client
  end

  # If authorise is called with true, this block is executed so that it
  # can perform the authentication upgrade
  def upgrade_authentication_block(new_token)
    # This block is called if the authorisation was forced
    if client.connection.connected? || client.connection.connecting?
      logger.debug "Realtime::Auth - authorise called with { force: true } so forcibly disconnecting transport to initiate auth upgrade"
      block = Proc.new do
        if client.connection.transport
          logger.debug "Realtime::Auth - current transport disconnected"
          client.connection.transport.disconnect
        else
          EventMachine.add_timer(0.1, &block)
        end
      end
      block.call
    end
  end
end

#token ⇒ Object (readonly) 



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/ably/realtime/auth.rb', line 35

class Auth
  extend Forwardable
  include Ably::Modules::AsyncWrapper

  def_delegators :auth_sync, :client_id
  def_delegators :auth_sync, :token_client_id_allowed?, :configure_client_id, :client_id_validated?
  def_delegators :auth_sync, :can_assume_client_id?, :has_client_id?
  def_delegators :auth_sync, :current_token_details, :token
  def_delegators :auth_sync, :key, :key_name, :key_secret, :options, :auth_options, :token_params
  def_delegators :auth_sync, :using_basic_auth?, :using_token_auth?
  def_delegators :auth_sync, :token_renewable?, :authentication_security_requirements_met?
  def_delegators :client, :logger

  def initialize(client)
    @client = client
    @auth_sync = client.rest_client.auth
  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.
  #
  # In the event that a new token request is made, the provided options are used
  #
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # will issue a simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.authorise do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def authorise(token_params = nil, auth_options = nil, &success_callback)
    async_wrap(success_callback) do
      auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
    end.tap do |deferrable|
      deferrable.errback do |error|
        client.connection.transition_state_machine :failed, reason: error if error.kind_of?(Ably::Exceptions::IncompatibleClientId)
      end
    end
  end

  # Synchronous version of {#authorise}. See {Ably::Auth#authorise} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def authorise_sync(token_params = nil, auth_options = nil)
    auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
  end

  # def_delegator :auth_sync, :request_token, :request_token_sync
  # def_delegator :auth_sync, :create_token_request, :create_token_request_sync
  # def_delegator :auth_sync, :auth_header, :auth_header_sync
  # def_delegator :auth_sync, :auth_params, :auth_params_sync

  # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
  #
  # @param (see Ably::Auth#request_token)
  # @option (see Ably::Auth#request_token)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.request_token do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def request_token(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      request_token_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#request_token}. See {Ably::Auth#request_token} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def request_token_sync(token_params = {}, auth_options = {})
    auth_sync.request_token(token_params, auth_options)
  end

  # Creates and signs a token request that can then subsequently be used by any client to request a token
  #
  # @param (see Ably::Auth#create_token_request)
  # @option (see Ably::Auth#create_token_request)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Models::TokenRequest]
  #
  # @example
  #   client.auth.create_token_request({ ttl: 3600 }, id: 'asd.asd') do |token_request|
  #     token_request #=> Ably::Models::TokenRequest
  #   end
  def create_token_request(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      create_token_request_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#create_token_request}. See {Ably::Auth#create_token_request} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenRequest]
  #
  def create_token_request_sync(token_params = {}, auth_options = {})
    auth_sync.create_token_request(token_params, auth_options)
  end

  # Auth header string used in HTTP requests to Ably
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header(&success_callback)
    async_wrap(success_callback) do
      auth_header_sync
    end
  end

  # Synchronous version of {#auth_header}. See {Ably::Auth#auth_header} for method definition
  # @return [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header_sync
    auth_sync.auth_header
  end

  # Auth params used in URI endpoint for Realtime connections
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Hash] Auth params for a new Realtime connection
  #
  def auth_params(&success_callback)
    async_wrap(success_callback) do
      auth_params_sync
    end
  end

  # Synchronous version of {#auth_params}. See {Ably::Auth#auth_params} for method definition
  # @return [Hash] Auth params for a new Realtime connection
  #
  def auth_params_sync
    auth_sync.auth_params
  end

  private
  # The synchronous Auth class instanced by the Rest client
  # @return [Ably::Auth]
  def auth_sync
    @auth_sync
  end

  def client
    @client
  end

  # If authorise is called with true, this block is executed so that it
  # can perform the authentication upgrade
  def upgrade_authentication_block(new_token)
    # This block is called if the authorisation was forced
    if client.connection.connected? || client.connection.connecting?
      logger.debug "Realtime::Auth - authorise called with { force: true } so forcibly disconnecting transport to initiate auth upgrade"
      block = Proc.new do
        if client.connection.transport
          logger.debug "Realtime::Auth - current transport disconnected"
          client.connection.transport.disconnect
        else
          EventMachine.add_timer(0.1, &block)
        end
      end
      block.call
    end
  end
end

#token_params ⇒ Hash (readonly)

Returns Default Auth options configured for this client.

Returns:

  • (Hash) —

    Default Auth options configured for this client



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/ably/realtime/auth.rb', line 35

class Auth
  extend Forwardable
  include Ably::Modules::AsyncWrapper

  def_delegators :auth_sync, :client_id
  def_delegators :auth_sync, :token_client_id_allowed?, :configure_client_id, :client_id_validated?
  def_delegators :auth_sync, :can_assume_client_id?, :has_client_id?
  def_delegators :auth_sync, :current_token_details, :token
  def_delegators :auth_sync, :key, :key_name, :key_secret, :options, :auth_options, :token_params
  def_delegators :auth_sync, :using_basic_auth?, :using_token_auth?
  def_delegators :auth_sync, :token_renewable?, :authentication_security_requirements_met?
  def_delegators :client, :logger

  def initialize(client)
    @client = client
    @auth_sync = client.rest_client.auth
  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.
  #
  # In the event that a new token request is made, the provided options are used
  #
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # will issue a simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.authorise do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def authorise(token_params = nil, auth_options = nil, &success_callback)
    async_wrap(success_callback) do
      auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
    end.tap do |deferrable|
      deferrable.errback do |error|
        client.connection.transition_state_machine :failed, reason: error if error.kind_of?(Ably::Exceptions::IncompatibleClientId)
      end
    end
  end

  # Synchronous version of {#authorise}. See {Ably::Auth#authorise} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def authorise_sync(token_params = nil, auth_options = nil)
    auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
  end

  # def_delegator :auth_sync, :request_token, :request_token_sync
  # def_delegator :auth_sync, :create_token_request, :create_token_request_sync
  # def_delegator :auth_sync, :auth_header, :auth_header_sync
  # def_delegator :auth_sync, :auth_params, :auth_params_sync

  # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
  #
  # @param (see Ably::Auth#request_token)
  # @option (see Ably::Auth#request_token)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.request_token do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def request_token(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      request_token_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#request_token}. See {Ably::Auth#request_token} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def request_token_sync(token_params = {}, auth_options = {})
    auth_sync.request_token(token_params, auth_options)
  end

  # Creates and signs a token request that can then subsequently be used by any client to request a token
  #
  # @param (see Ably::Auth#create_token_request)
  # @option (see Ably::Auth#create_token_request)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Models::TokenRequest]
  #
  # @example
  #   client.auth.create_token_request({ ttl: 3600 }, id: 'asd.asd') do |token_request|
  #     token_request #=> Ably::Models::TokenRequest
  #   end
  def create_token_request(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      create_token_request_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#create_token_request}. See {Ably::Auth#create_token_request} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenRequest]
  #
  def create_token_request_sync(token_params = {}, auth_options = {})
    auth_sync.create_token_request(token_params, auth_options)
  end

  # Auth header string used in HTTP requests to Ably
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header(&success_callback)
    async_wrap(success_callback) do
      auth_header_sync
    end
  end

  # Synchronous version of {#auth_header}. See {Ably::Auth#auth_header} for method definition
  # @return [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header_sync
    auth_sync.auth_header
  end

  # Auth params used in URI endpoint for Realtime connections
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Hash] Auth params for a new Realtime connection
  #
  def auth_params(&success_callback)
    async_wrap(success_callback) do
      auth_params_sync
    end
  end

  # Synchronous version of {#auth_params}. See {Ably::Auth#auth_params} for method definition
  # @return [Hash] Auth params for a new Realtime connection
  #
  def auth_params_sync
    auth_sync.auth_params
  end

  private
  # The synchronous Auth class instanced by the Rest client
  # @return [Ably::Auth]
  def auth_sync
    @auth_sync
  end

  def client
    @client
  end

  # If authorise is called with true, this block is executed so that it
  # can perform the authentication upgrade
  def upgrade_authentication_block(new_token)
    # This block is called if the authorisation was forced
    if client.connection.connected? || client.connection.connecting?
      logger.debug "Realtime::Auth - authorise called with { force: true } so forcibly disconnecting transport to initiate auth upgrade"
      block = Proc.new do
        if client.connection.transport
          logger.debug "Realtime::Auth - current transport disconnected"
          client.connection.transport.disconnect
        else
          EventMachine.add_timer(0.1, &block)
        end
      end
      block.call
    end
  end
end

#token_renewable? ⇒ Boolean (readonly)

True if prerequisites for creating a new token request are present

One of the following criterion must be met:

  • Valid API key and token option not provided as token options cannot be determined

  • Authentication callback for new token requests

  • Authentication URL for new token requests

Returns:

  • (Boolean) 


35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/ably/realtime/auth.rb', line 35

class Auth
  extend Forwardable
  include Ably::Modules::AsyncWrapper

  def_delegators :auth_sync, :client_id
  def_delegators :auth_sync, :token_client_id_allowed?, :configure_client_id, :client_id_validated?
  def_delegators :auth_sync, :can_assume_client_id?, :has_client_id?
  def_delegators :auth_sync, :current_token_details, :token
  def_delegators :auth_sync, :key, :key_name, :key_secret, :options, :auth_options, :token_params
  def_delegators :auth_sync, :using_basic_auth?, :using_token_auth?
  def_delegators :auth_sync, :token_renewable?, :authentication_security_requirements_met?
  def_delegators :client, :logger

  def initialize(client)
    @client = client
    @auth_sync = client.rest_client.auth
  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.
  #
  # In the event that a new token request is made, the provided options are used
  #
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # will issue a simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.authorise do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def authorise(token_params = nil, auth_options = nil, &success_callback)
    async_wrap(success_callback) do
      auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
    end.tap do |deferrable|
      deferrable.errback do |error|
        client.connection.transition_state_machine :failed, reason: error if error.kind_of?(Ably::Exceptions::IncompatibleClientId)
      end
    end
  end

  # Synchronous version of {#authorise}. See {Ably::Auth#authorise} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def authorise_sync(token_params = nil, auth_options = nil)
    auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
  end

  # def_delegator :auth_sync, :request_token, :request_token_sync
  # def_delegator :auth_sync, :create_token_request, :create_token_request_sync
  # def_delegator :auth_sync, :auth_header, :auth_header_sync
  # def_delegator :auth_sync, :auth_params, :auth_params_sync

  # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
  #
  # @param (see Ably::Auth#request_token)
  # @option (see Ably::Auth#request_token)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.request_token do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def request_token(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      request_token_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#request_token}. See {Ably::Auth#request_token} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def request_token_sync(token_params = {}, auth_options = {})
    auth_sync.request_token(token_params, auth_options)
  end

  # Creates and signs a token request that can then subsequently be used by any client to request a token
  #
  # @param (see Ably::Auth#create_token_request)
  # @option (see Ably::Auth#create_token_request)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Models::TokenRequest]
  #
  # @example
  #   client.auth.create_token_request({ ttl: 3600 }, id: 'asd.asd') do |token_request|
  #     token_request #=> Ably::Models::TokenRequest
  #   end
  def create_token_request(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      create_token_request_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#create_token_request}. See {Ably::Auth#create_token_request} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenRequest]
  #
  def create_token_request_sync(token_params = {}, auth_options = {})
    auth_sync.create_token_request(token_params, auth_options)
  end

  # Auth header string used in HTTP requests to Ably
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header(&success_callback)
    async_wrap(success_callback) do
      auth_header_sync
    end
  end

  # Synchronous version of {#auth_header}. See {Ably::Auth#auth_header} for method definition
  # @return [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header_sync
    auth_sync.auth_header
  end

  # Auth params used in URI endpoint for Realtime connections
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Hash] Auth params for a new Realtime connection
  #
  def auth_params(&success_callback)
    async_wrap(success_callback) do
      auth_params_sync
    end
  end

  # Synchronous version of {#auth_params}. See {Ably::Auth#auth_params} for method definition
  # @return [Hash] Auth params for a new Realtime connection
  #
  def auth_params_sync
    auth_sync.auth_params
  end

  private
  # The synchronous Auth class instanced by the Rest client
  # @return [Ably::Auth]
  def auth_sync
    @auth_sync
  end

  def client
    @client
  end

  # If authorise is called with true, this block is executed so that it
  # can perform the authentication upgrade
  def upgrade_authentication_block(new_token)
    # This block is called if the authorisation was forced
    if client.connection.connected? || client.connection.connecting?
      logger.debug "Realtime::Auth - authorise called with { force: true } so forcibly disconnecting transport to initiate auth upgrade"
      block = Proc.new do
        if client.connection.transport
          logger.debug "Realtime::Auth - current transport disconnected"
          client.connection.transport.disconnect
        else
          EventMachine.add_timer(0.1, &block)
        end
      end
      block.call
    end
  end
end

#using_basic_auth? ⇒ Object (readonly)

True when Basic Auth is being used to authenticate with Ably



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/ably/realtime/auth.rb', line 35

class Auth
  extend Forwardable
  include Ably::Modules::AsyncWrapper

  def_delegators :auth_sync, :client_id
  def_delegators :auth_sync, :token_client_id_allowed?, :configure_client_id, :client_id_validated?
  def_delegators :auth_sync, :can_assume_client_id?, :has_client_id?
  def_delegators :auth_sync, :current_token_details, :token
  def_delegators :auth_sync, :key, :key_name, :key_secret, :options, :auth_options, :token_params
  def_delegators :auth_sync, :using_basic_auth?, :using_token_auth?
  def_delegators :auth_sync, :token_renewable?, :authentication_security_requirements_met?
  def_delegators :client, :logger

  def initialize(client)
    @client = client
    @auth_sync = client.rest_client.auth
  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.
  #
  # In the event that a new token request is made, the provided options are used
  #
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # will issue a simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.authorise do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def authorise(token_params = nil, auth_options = nil, &success_callback)
    async_wrap(success_callback) do
      auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
    end.tap do |deferrable|
      deferrable.errback do |error|
        client.connection.transition_state_machine :failed, reason: error if error.kind_of?(Ably::Exceptions::IncompatibleClientId)
      end
    end
  end

  # Synchronous version of {#authorise}. See {Ably::Auth#authorise} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def authorise_sync(token_params = nil, auth_options = nil)
    auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
  end

  # def_delegator :auth_sync, :request_token, :request_token_sync
  # def_delegator :auth_sync, :create_token_request, :create_token_request_sync
  # def_delegator :auth_sync, :auth_header, :auth_header_sync
  # def_delegator :auth_sync, :auth_params, :auth_params_sync

  # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
  #
  # @param (see Ably::Auth#request_token)
  # @option (see Ably::Auth#request_token)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.request_token do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def request_token(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      request_token_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#request_token}. See {Ably::Auth#request_token} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def request_token_sync(token_params = {}, auth_options = {})
    auth_sync.request_token(token_params, auth_options)
  end

  # Creates and signs a token request that can then subsequently be used by any client to request a token
  #
  # @param (see Ably::Auth#create_token_request)
  # @option (see Ably::Auth#create_token_request)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Models::TokenRequest]
  #
  # @example
  #   client.auth.create_token_request({ ttl: 3600 }, id: 'asd.asd') do |token_request|
  #     token_request #=> Ably::Models::TokenRequest
  #   end
  def create_token_request(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      create_token_request_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#create_token_request}. See {Ably::Auth#create_token_request} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenRequest]
  #
  def create_token_request_sync(token_params = {}, auth_options = {})
    auth_sync.create_token_request(token_params, auth_options)
  end

  # Auth header string used in HTTP requests to Ably
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header(&success_callback)
    async_wrap(success_callback) do
      auth_header_sync
    end
  end

  # Synchronous version of {#auth_header}. See {Ably::Auth#auth_header} for method definition
  # @return [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header_sync
    auth_sync.auth_header
  end

  # Auth params used in URI endpoint for Realtime connections
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Hash] Auth params for a new Realtime connection
  #
  def auth_params(&success_callback)
    async_wrap(success_callback) do
      auth_params_sync
    end
  end

  # Synchronous version of {#auth_params}. See {Ably::Auth#auth_params} for method definition
  # @return [Hash] Auth params for a new Realtime connection
  #
  def auth_params_sync
    auth_sync.auth_params
  end

  private
  # The synchronous Auth class instanced by the Rest client
  # @return [Ably::Auth]
  def auth_sync
    @auth_sync
  end

  def client
    @client
  end

  # If authorise is called with true, this block is executed so that it
  # can perform the authentication upgrade
  def upgrade_authentication_block(new_token)
    # This block is called if the authorisation was forced
    if client.connection.connected? || client.connection.connecting?
      logger.debug "Realtime::Auth - authorise called with { force: true } so forcibly disconnecting transport to initiate auth upgrade"
      block = Proc.new do
        if client.connection.transport
          logger.debug "Realtime::Auth - current transport disconnected"
          client.connection.transport.disconnect
        else
          EventMachine.add_timer(0.1, &block)
        end
      end
      block.call
    end
  end
end

#using_token_auth? ⇒ Object (readonly)

True when Token Auth is being used to authenticate with Ably



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/ably/realtime/auth.rb', line 35

class Auth
  extend Forwardable
  include Ably::Modules::AsyncWrapper

  def_delegators :auth_sync, :client_id
  def_delegators :auth_sync, :token_client_id_allowed?, :configure_client_id, :client_id_validated?
  def_delegators :auth_sync, :can_assume_client_id?, :has_client_id?
  def_delegators :auth_sync, :current_token_details, :token
  def_delegators :auth_sync, :key, :key_name, :key_secret, :options, :auth_options, :token_params
  def_delegators :auth_sync, :using_basic_auth?, :using_token_auth?
  def_delegators :auth_sync, :token_renewable?, :authentication_security_requirements_met?
  def_delegators :client, :logger

  def initialize(client)
    @client = client
    @auth_sync = client.rest_client.auth
  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.
  #
  # In the event that a new token request is made, the provided options are used
  #
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # will issue a simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.authorise do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def authorise(token_params = nil, auth_options = nil, &success_callback)
    async_wrap(success_callback) do
      auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
    end.tap do |deferrable|
      deferrable.errback do |error|
        client.connection.transition_state_machine :failed, reason: error if error.kind_of?(Ably::Exceptions::IncompatibleClientId)
      end
    end
  end

  # Synchronous version of {#authorise}. See {Ably::Auth#authorise} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def authorise_sync(token_params = nil, auth_options = nil)
    auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
  end

  # def_delegator :auth_sync, :request_token, :request_token_sync
  # def_delegator :auth_sync, :create_token_request, :create_token_request_sync
  # def_delegator :auth_sync, :auth_header, :auth_header_sync
  # def_delegator :auth_sync, :auth_params, :auth_params_sync

  # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
  #
  # @param (see Ably::Auth#request_token)
  # @option (see Ably::Auth#request_token)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Ably::Models::TokenDetails]
  #
  # @example
  #    # simple token request using basic auth
  #    client = Ably::Rest::Client.new(key: 'key.id:secret')
  #    client.auth.request_token do |token_details|
  #      token_details #=> Ably::Models::TokenDetails
  #    end
  #
  def request_token(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      request_token_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#request_token}. See {Ably::Auth#request_token} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenDetails]
  #
  def request_token_sync(token_params = {}, auth_options = {})
    auth_sync.request_token(token_params, auth_options)
  end

  # Creates and signs a token request that can then subsequently be used by any client to request a token
  #
  # @param (see Ably::Auth#create_token_request)
  # @option (see Ably::Auth#create_token_request)
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Models::TokenRequest]
  #
  # @example
  #   client.auth.create_token_request({ ttl: 3600 }, id: 'asd.asd') do |token_request|
  #     token_request #=> Ably::Models::TokenRequest
  #   end
  def create_token_request(token_params = {}, auth_options = {}, &success_callback)
    async_wrap(success_callback) do
      create_token_request_sync(token_params, auth_options)
    end
  end

  # Synchronous version of {#create_token_request}. See {Ably::Auth#create_token_request} for method definition
  # @param (see Ably::Auth#authorise)
  # @option (see Ably::Auth#authorise)
  # @return [Ably::Models::TokenRequest]
  #
  def create_token_request_sync(token_params = {}, auth_options = {})
    auth_sync.create_token_request(token_params, auth_options)
  end

  # Auth header string used in HTTP requests to Ably
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header(&success_callback)
    async_wrap(success_callback) do
      auth_header_sync
    end
  end

  # Synchronous version of {#auth_header}. See {Ably::Auth#auth_header} for method definition
  # @return [String] HTTP authentication value used in HTTP_AUTHORIZATION header
  #
  def auth_header_sync
    auth_sync.auth_header
  end

  # Auth params used in URI endpoint for Realtime connections
  # Will reauthorise implicitly if required and capable
  #
  # @return [Ably::Util::SafeDeferrable]
  # @yield [Hash] Auth params for a new Realtime connection
  #
  def auth_params(&success_callback)
    async_wrap(success_callback) do
      auth_params_sync
    end
  end

  # Synchronous version of {#auth_params}. See {Ably::Auth#auth_params} for method definition
  # @return [Hash] Auth params for a new Realtime connection
  #
  def auth_params_sync
    auth_sync.auth_params
  end

  private
  # The synchronous Auth class instanced by the Rest client
  # @return [Ably::Auth]
  def auth_sync
    @auth_sync
  end

  def client
    @client
  end

  # If authorise is called with true, this block is executed so that it
  # can perform the authentication upgrade
  def upgrade_authentication_block(new_token)
    # This block is called if the authorisation was forced
    if client.connection.connected? || client.connection.connecting?
      logger.debug "Realtime::Auth - authorise called with { force: true } so forcibly disconnecting transport to initiate auth upgrade"
      block = Proc.new do
        if client.connection.transport
          logger.debug "Realtime::Auth - current transport disconnected"
          client.connection.transport.disconnect
        else
          EventMachine.add_timer(0.1, &block)
        end
      end
      block.call
    end
  end
end

Instance Method Details

#auth_header {|String| ... } ⇒ Ably::Util::SafeDeferrable

Auth header string used in HTTP requests to Ably Will reauthorise implicitly if required and capable

Yields:

  • (String) —

    HTTP authentication value used in HTTP_AUTHORIZATION header

Returns:



157
158
159
160
161
 
# File 'lib/ably/realtime/auth.rb', line 157

def auth_header(&success_callback)
  async_wrap(success_callback) do
    auth_header_sync
  end
end

#auth_header_sync ⇒ String

Synchronous version of #auth_header. See Auth#auth_header for method definition

Returns:

  • (String) —

    HTTP authentication value used in HTTP_AUTHORIZATION header



166
167
168
 
# File 'lib/ably/realtime/auth.rb', line 166

def auth_header_sync
  auth_sync.auth_header
end

#auth_params {|Hash| ... } ⇒ Ably::Util::SafeDeferrable

Auth params used in URI endpoint for Realtime connections Will reauthorise implicitly if required and capable

Yields:

  • (Hash) —

    Auth params for a new Realtime connection

Returns:



176
177
178
179
180
 
# File 'lib/ably/realtime/auth.rb', line 176

def auth_params(&success_callback)
  async_wrap(success_callback) do
    auth_params_sync
  end
end

#auth_params_sync ⇒ Hash

Synchronous version of #auth_params. See Auth#auth_params for method definition

Returns:

  • (Hash) —

    Auth params for a new Realtime connection



185
186
187
 
# File 'lib/ably/realtime/auth.rb', line 185

def auth_params_sync
  auth_sync.auth_params
end

#authorise(token_params = nil, auth_options = nil) {|Ably::Models::TokenDetails| ... } ⇒ Ably::Util::SafeDeferrable

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.

In the event that a new token request is made, the provided options are used

Examples:

# will issue a simple token request using basic auth
client = Ably::Rest::Client.new(key: 'key.id:secret')
client.auth.authorise do |token_details|
  token_details #=> Ably::Models::TokenDetails
end

Parameters:

  • token_params (Hash, nil) (defaults to: nil) —

    the token params used for future token requests. When nil, previously configured token params are used

  • auth_options (Hash, nil) (defaults to: nil) —

    the authentication options used for future token requests. When nil, previously configure authentication options are used

Options Hash (token_params):

  • :client_id (String) —

    A client ID to associate with this token. The generated token may be used to authenticate as this client_id

  • :ttl (Integer) —

    validity time in seconds for the requested Models::TokenDetails. Limits may apply, see https://www.ably.io/documentation/other/authentication

  • :capability (Hash) —

    canonicalised representation of the resource paths and associated operations

  • :timestamp (Time) —

    the time of the request

  • :nonce (String) —

    an unquoted, unescaped random string of at least 16 characters

Options Hash (auth_options):

  • :force (Boolean) —

    obtains a new token even if the current token is valid. If the provided auth_options Hash contains only this :force attribute, the existing configured authentication options are not overwriten

  • :auth_url (String) —

    a URL to be used to GET or POST a set of token request params, to obtain a signed token request

  • :auth_headers (Hash) —

    a set of application-specific headers to be added to any request made to the auth_url

  • :auth_params (Hash) —

    a set of application-specific query params to be added to any request made to the auth_url

  • :auth_method (Symbol) — default: :get —

    HTTP method to use with auth_url, must be either :get or :post

  • :auth_callback (Proc) —

    when provided, the Proc will be called with the token params hash as the first argument, whenever a new token is required. The Proc should return a token string, Models::TokenDetails or JSON equivalent, Models::TokenRequest or JSON equivalent

  • :key (String) —

    API key comprising the key name and key secret in a single string

  • :client_id (String) —

    client ID identifying this connection to other clients (will use client_id specified when library was instanced if provided)

  • :query_time (Boolean) —

    when true will query the Ably system for the current time instead of using the local time

  • :token_params (Hash) —

    convenience to pass in token_params within the auth_options argument, especially useful when setting default token_params in the client constructor

Yields:

Returns:



70
71
72
73
74
75
76
77
78
 
# File 'lib/ably/realtime/auth.rb', line 70

def authorise(token_params = nil, auth_options = nil, &success_callback)
  async_wrap(success_callback) do
    auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
  end.tap do |deferrable|
    deferrable.errback do |error|
      client.connection.transition_state_machine :failed, reason: error if error.kind_of?(Ably::Exceptions::IncompatibleClientId)
    end
  end
end

#authorise_sync(token_params = nil, auth_options = nil) ⇒ Ably::Models::TokenDetails

Synchronous version of #authorise. See Auth#authorise for method definition

Parameters:

  • token_params (Hash, nil) (defaults to: nil) —

    the token params used for future token requests. When nil, previously configured token params are used

  • auth_options (Hash, nil) (defaults to: nil) —

    the authentication options used for future token requests. When nil, previously configure authentication options are used

Options Hash (token_params):

  • :client_id (String) —

    A client ID to associate with this token. The generated token may be used to authenticate as this client_id

  • :ttl (Integer) —

    validity time in seconds for the requested Models::TokenDetails. Limits may apply, see https://www.ably.io/documentation/other/authentication

  • :capability (Hash) —

    canonicalised representation of the resource paths and associated operations

  • :timestamp (Time) —

    the time of the request

  • :nonce (String) —

    an unquoted, unescaped random string of at least 16 characters

Options Hash (auth_options):

  • :force (Boolean) —

    obtains a new token even if the current token is valid. If the provided auth_options Hash contains only this :force attribute, the existing configured authentication options are not overwriten

  • :auth_url (String) —

    a URL to be used to GET or POST a set of token request params, to obtain a signed token request

  • :auth_headers (Hash) —

    a set of application-specific headers to be added to any request made to the auth_url

  • :auth_params (Hash) —

    a set of application-specific query params to be added to any request made to the auth_url

  • :auth_method (Symbol) — default: :get —

    HTTP method to use with auth_url, must be either :get or :post

  • :auth_callback (Proc) —

    when provided, the Proc will be called with the token params hash as the first argument, whenever a new token is required. The Proc should return a token string, Models::TokenDetails or JSON equivalent, Models::TokenRequest or JSON equivalent

  • :key (String) —

    API key comprising the key name and key secret in a single string

  • :client_id (String) —

    client ID identifying this connection to other clients (will use client_id specified when library was instanced if provided)

  • :query_time (Boolean) —

    when true will query the Ably system for the current time instead of using the local time

  • :token_params (Hash) —

    convenience to pass in token_params within the auth_options argument, especially useful when setting default token_params in the client constructor

Returns:



85
86
87
 
# File 'lib/ably/realtime/auth.rb', line 85

def authorise_sync(token_params = nil, auth_options = nil)
  auth_sync.authorise(token_params, auth_options, &method(:upgrade_authentication_block).to_proc)
end

#create_token_request(token_params = {}, auth_options = {}) {|Models::TokenRequest| ... } ⇒ Ably::Util::SafeDeferrable

Creates and signs a token request that can then subsequently be used by any client to request a token

Examples:

client.auth.create_token_request({ ttl: 3600 }, id: 'asd.asd') do |token_request|
  token_request #=> Ably::Models::TokenRequest
end

Parameters:

  • token_params (Hash) (defaults to: {}) —

    the token params used in the token request

  • auth_options (Hash) (defaults to: {}) —

    the authentication options for the token request

Options Hash (token_params):

  • :client_id (String) —

    A client ID to associate with this token. The generated token may be used to authenticate as this client_id

  • :ttl (Integer) —

    validity time in seconds for the requested Models::TokenDetails. Limits may apply, see https://www.ably.io/documentation/other/authentication

  • :capability (Hash) —

    canonicalised representation of the resource paths and associated operations

  • :timestamp (Time) —

    the time of the request

  • :nonce (String) —

    an unquoted, unescaped random string of at least 16 characters

Options Hash (auth_options):

  • :key (String) —

    API key comprising the key name and key secret in a single string

  • :client_id (String) —

    client ID identifying this connection to other clients (will use client_id specified when library was instanced if provided)

  • :query_time (Boolean) —

    when true will query the Ably system for the current time instead of using the local time

  • :token_params (Hash) —

    convenience to pass in token_params within the auth_options argument, especially useful when setting default token_params in the client constructor

Yields:

Returns:



136
137
138
139
140
 
# File 'lib/ably/realtime/auth.rb', line 136

def create_token_request(token_params = {}, auth_options = {}, &success_callback)
  async_wrap(success_callback) do
    create_token_request_sync(token_params, auth_options)
  end
end

#create_token_request_sync(token_params = {}, auth_options = {}) ⇒ Ably::Models::TokenRequest

Synchronous version of #create_token_request. See Auth#create_token_request for method definition

Parameters:

  • token_params (Hash, nil) (defaults to: {}) —

    the token params used for future token requests. When nil, previously configured token params are used

  • auth_options (Hash, nil) (defaults to: {}) —

    the authentication options used for future token requests. When nil, previously configure authentication options are used

Options Hash (token_params):

  • :client_id (String) —

    A client ID to associate with this token. The generated token may be used to authenticate as this client_id

  • :ttl (Integer) —

    validity time in seconds for the requested Models::TokenDetails. Limits may apply, see https://www.ably.io/documentation/other/authentication

  • :capability (Hash) —

    canonicalised representation of the resource paths and associated operations

  • :timestamp (Time) —

    the time of the request

  • :nonce (String) —

    an unquoted, unescaped random string of at least 16 characters

Options Hash (auth_options):

  • :force (Boolean) —

    obtains a new token even if the current token is valid. If the provided auth_options Hash contains only this :force attribute, the existing configured authentication options are not overwriten

  • :auth_url (String) —

    a URL to be used to GET or POST a set of token request params, to obtain a signed token request

  • :auth_headers (Hash) —

    a set of application-specific headers to be added to any request made to the auth_url

  • :auth_params (Hash) —

    a set of application-specific query params to be added to any request made to the auth_url

  • :auth_method (Symbol) — default: :get —

    HTTP method to use with auth_url, must be either :get or :post

  • :auth_callback (Proc) —

    when provided, the Proc will be called with the token params hash as the first argument, whenever a new token is required. The Proc should return a token string, Models::TokenDetails or JSON equivalent, Models::TokenRequest or JSON equivalent

  • :key (String) —

    API key comprising the key name and key secret in a single string

  • :client_id (String) —

    client ID identifying this connection to other clients (will use client_id specified when library was instanced if provided)

  • :query_time (Boolean) —

    when true will query the Ably system for the current time instead of using the local time

  • :token_params (Hash) —

    convenience to pass in token_params within the auth_options argument, especially useful when setting default token_params in the client constructor

Returns:



147
148
149
 
# File 'lib/ably/realtime/auth.rb', line 147

def create_token_request_sync(token_params = {}, auth_options = {})
  auth_sync.create_token_request(token_params, auth_options)
end

#request_token(token_params = {}, auth_options = {}) {|Ably::Models::TokenDetails| ... } ⇒ Ably::Util::SafeDeferrable

Request a Models::TokenDetails which can be used to make authenticated token based requests

Examples:

# simple token request using basic auth
client = Ably::Rest::Client.new(key: 'key.id:secret')
client.auth.request_token do |token_details|
  token_details #=> Ably::Models::TokenDetails
end

Parameters:

  • auth_options (Hash) (defaults to: {}) —

    (see #create_token_request)

  • token_params (Hash) (defaults to: {}) —

    (see #create_token_request)

Options Hash (token_params):

  • :client_id (String) —

    A client ID to associate with this token. The generated token may be used to authenticate as this client_id

  • :ttl (Integer) —

    validity time in seconds for the requested Models::TokenDetails. Limits may apply, see https://www.ably.io/documentation/other/authentication

  • :capability (Hash) —

    canonicalised representation of the resource paths and associated operations

  • :timestamp (Time) —

    the time of the request

  • :nonce (String) —

    an unquoted, unescaped random string of at least 16 characters

Options Hash (auth_options):

  • :auth_url (String) —

    a URL to be used to GET or POST a set of token request params, to obtain a signed token request

  • :auth_headers (Hash) —

    a set of application-specific headers to be added to any request made to the auth_url

  • :auth_params (Hash) —

    a set of application-specific query params to be added to any request made to the auth_url

  • :auth_method (Symbol) — default: :get —

    HTTP method to use with auth_url, must be either :get or :post

  • :auth_callback (Proc) —

    when provided, the Proc will be called with the token params hash as the first argument, whenever a new token is required. The Proc should return a token string, Models::TokenDetails or JSON equivalent, Models::TokenRequest or JSON equivalent

  • :key (String) —

    API key comprising the key name and key secret in a single string

  • :client_id (String) —

    client ID identifying this connection to other clients (will use client_id specified when library was instanced if provided)

  • :query_time (Boolean) —

    when true will query the Ably system for the current time instead of using the local time

  • :token_params (Hash) —

    convenience to pass in token_params within the auth_options argument, especially useful when setting default token_params in the client constructor

Yields:

Returns:



109
110
111
112
113
 
# File 'lib/ably/realtime/auth.rb', line 109

def request_token(token_params = {}, auth_options = {}, &success_callback)
  async_wrap(success_callback) do
    request_token_sync(token_params, auth_options)
  end
end

#request_token_sync(token_params = {}, auth_options = {}) ⇒ Ably::Models::TokenDetails

Synchronous version of #request_token. See Auth#request_token for method definition

Parameters:

  • token_params (Hash, nil) (defaults to: {}) —

    the token params used for future token requests. When nil, previously configured token params are used

  • auth_options (Hash, nil) (defaults to: {}) —

    the authentication options used for future token requests. When nil, previously configure authentication options are used

Options Hash (token_params):

  • :client_id (String) —

    A client ID to associate with this token. The generated token may be used to authenticate as this client_id

  • :ttl (Integer) —

    validity time in seconds for the requested Models::TokenDetails. Limits may apply, see https://www.ably.io/documentation/other/authentication

  • :capability (Hash) —

    canonicalised representation of the resource paths and associated operations

  • :timestamp (Time) —

    the time of the request

  • :nonce (String) —

    an unquoted, unescaped random string of at least 16 characters

Options Hash (auth_options):

  • :force (Boolean) —

    obtains a new token even if the current token is valid. If the provided auth_options Hash contains only this :force attribute, the existing configured authentication options are not overwriten

  • :auth_url (String) —

    a URL to be used to GET or POST a set of token request params, to obtain a signed token request

  • :auth_headers (Hash) —

    a set of application-specific headers to be added to any request made to the auth_url

  • :auth_params (Hash) —

    a set of application-specific query params to be added to any request made to the auth_url

  • :auth_method (Symbol) — default: :get —

    HTTP method to use with auth_url, must be either :get or :post

  • :auth_callback (Proc) —

    when provided, the Proc will be called with the token params hash as the first argument, whenever a new token is required. The Proc should return a token string, Models::TokenDetails or JSON equivalent, Models::TokenRequest or JSON equivalent

  • :key (String) —

    API key comprising the key name and key secret in a single string

  • :client_id (String) —

    client ID identifying this connection to other clients (will use client_id specified when library was instanced if provided)

  • :query_time (Boolean) —

    when true will query the Ably system for the current time instead of using the local time

  • :token_params (Hash) —

    convenience to pass in token_params within the auth_options argument, especially useful when setting default token_params in the client constructor

Returns:



120
121
122
 
# File 'lib/ably/realtime/auth.rb', line 120

def request_token_sync(token_params = {}, auth_options = {})
  auth_sync.request_token(token_params, auth_options)
end