Class: ThreeScale::Interface

Inherits:
Object
  • Object
show all
Defined in:
lib/3scale/interface.rb

Overview

This class provides interface to 3scale monitoring system.

Objects of this class are stateless and can be shared through multiple transactions and by multiple clients.

Constant Summary collapse

KEY_PREFIX =

:nodoc:

'3scale-'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(host = nil, provider_authentication_key = nil) ⇒ Interface

Create a 3scale interface object.

Arguments

host

Hostname of 3scale backend server.

provider_authentication_key

Unique key that identifies this provider.



70
71
72
73
 
# File 'lib/3scale/interface.rb', line 70

def initialize(host = nil, provider_authentication_key = nil)
  @host = host
  @provider_authentication_key = provider_authentication_key
end

Instance Attribute Details

#host ⇒ Object

Hostname of 3scale server.



59
60
61
 
# File 'lib/3scale/interface.rb', line 59

def host
  @host
end

#provider_authentication_key ⇒ Object

Key that uniquely identifies the provider. This key is known only to the provider and to 3scale.



63
64
65
 
# File 'lib/3scale/interface.rb', line 63

def provider_authentication_key
  @provider_authentication_key
end

Instance Method Details

#cancel(transaction_id) ⇒ Object

Cancels a transaction.

Use this if request processing failed. Any estimated resource usage reported by preceding call to start will be deleted. You don’t have to call this if call to start itself failed.

Arguments

transaction_id

A transaction id obtained from previous call to start.

Return values

If there were no exceptions raised, returns true.

Exceptions

ThreeScale::TransactionNotFound

transactions does not exits

ThreeScale::ProviderKeyInvalid

provider_authentication_key is not valid

ThreeScale::UnknownError

some other unexpected error



187
188
189
190
191
192
193
194
195
196
 
# File 'lib/3scale/interface.rb', line 187

def cancel(transaction_id)
  uri = URI.parse("#{host}/transactions/#{CGI.escape(transaction_id.to_s)}.xml" +
      "?provider_key=#{CGI.escape(provider_authentication_key)}")

  response = Net::HTTP.start(uri.host, uri.port) do |http|
    http.delete("#{uri.path}?#{uri.query}")
  end

  response.is_a?(Net::HTTPSuccess) ? true : handle_error(response.body)
end

#confirm(transaction_id, usage = {}) ⇒ Object

Confirms a transaction.

Arguments

transaction_id

A transaction id obtained from previous call to start.

usage

A hash of metric names/values pairs containing actual resource usage of this request. This parameter is required only if no usage information was passed to method start for this transaction, or if it was only approximate.

Return values

If there were no exceptions raised, returns true.

Exceptions

ThreeScale::TransactionNotFound

transactions does not exits

ThreeScale::ProviderKeyInvalid

provider_authentication_key is not valid

ThreeScale::MetricInvalid

usage contains invalid metrics

ThreeScale::UnknownError

some other unexpected error



155
156
157
158
159
160
161
162
163
164
 
# File 'lib/3scale/interface.rb', line 155

def confirm(transaction_id, usage = {})
  uri = URI.parse("#{host}/transactions/#{CGI.escape(transaction_id.to_s)}/confirm.xml")
  params = {
    'provider_key' => provider_authentication_key
  }
  params.merge!(encode_params(usage, 'usage'))

  response = Net::HTTP.post_form(uri, params)
  response.is_a?(Net::HTTPSuccess) ? true : handle_error(response.body)
end

#start(user_key, usage = {}) ⇒ Object

Starts a transaction. This can be used also to report estimated resource usage of the request.

Arguments

user_key

Key that uniquely identifies an user of the service.

usage

A hash of metric names/values pairs that contains predicted resource usage of this request.

For example, if this request is going to take 10MB of storage space, then this parameter could contain => 10. The values may be only approximate or they can be missing altogether. In these cases, the real values must be reported using method confirm.

Return values

A hash containing there keys:

:id

Transaction id. This is required for confirmation/cancellation of the transaction later.

:provider_verification_key

This key should be sent back to the user so he/she can use it to verify the authenticity of the provider.

:contract_name

This is name of the contract the user is singed for. This information can be used to serve different responses according to contract types, if that is desirable.

Exceptions

ThreeScale::UserKeyInvalid

user_key is not valid

ThreeScale::ProviderKeyInvalid

provider_authentication_key is not valid

ThreeScale::MetricInvalid

usage contains invalid metrics

ThreeScale::ContractNotActive

contract is not active

ThreeScale::LimitsExceeded

usage limits are exceeded

ThreeScale::UnknownError

some other unexpected error



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/3scale/interface.rb', line 112

def start(user_key, usage = {})
  uri = URI.parse("#{host}/transactions.xml")
  params = {
    'user_key' => prepare_key(user_key),
    'provider_key' => provider_authentication_key
  }
  params.merge!(encode_params(usage, 'usage'))
  response = Net::HTTP.post_form(uri, params)

  if response.is_a?(Net::HTTPSuccess)
    element = Hpricot::XML(response.body).at('transaction')
    [:id, :provider_verification_key, :contract_name].inject({}) do |memo, key|
      memo[key] = element.at(key).inner_text if element.at(key)
      memo
    end
  else
    handle_error(response.body)
  end
end

#system_key?(key) ⇒ Boolean

This can be used to quickly distinguish between keys used with 3scale system and any other keys the provider might use. Returns true if the key is for 3scale system.

Returns:

  • (Boolean) 


203
204
205
206
 
# File 'lib/3scale/interface.rb', line 203

def system_key?(key)
  # Key should start with prefix
  key.index(KEY_PREFIX) == 0
end