Class: Vault::Usage::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/vault-usage-client.rb,
lib/vault-usage-client/client.rb,
lib/vault-usage-client/version.rb

Overview

Client for the Vault::Usage HTTP API.

Defined Under Namespace

Classes: InvalidTimeError

Constant Summary collapse

VERSION =

The Vault::Usage::Client gem version.

'0.0.10'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(url = nil) ⇒ Client

Instantiate a client.

Parameters:

  • url (String) (defaults to: nil) —

    The URL to connect to. Include the username and password to use when connecting.



14
15
16
 
# File 'lib/vault-usage-client/client.rb', line 14

def initialize(url = nil)
  @url = url || ENV['VAULT_USAGE_URL']
end

Instance Attribute Details

#url ⇒ Object (readonly)

Returns the value of attribute url.



4
5
6
 
# File 'lib/vault-usage-client/client.rb', line 4

def url
  @url
end

Instance Method Details

#close_app_ownership_event(event_id, user_hid, app_hid, stop_time) ⇒ Object

Report that ownership of an app by a user stopped at a particular time.

Parameters:

  • event_id (String) —

    A UUID that uniquely identifies the ownership event.

  • user_hid (String) —

    The user HID, such as [email protected], that owned the specified app.

  • app_hid (String) —

    The app HID, such as [email protected], that is being transferred away from the specified user.

  • stop_time (Time) —

    The end of the ownership period, always in UTC.

Raises:

  • (InvalidTimeError) —

    Raised if a non-UTC stop time is provided.

  • (Excon::Errors::HTTPStatusError) —

    Raised if the server returns an unsuccessful HTTP status code.



278
279
280
281
282
283
284
285
286
 
# File 'lib/vault-usage-client/client.rb', line 278

def close_app_ownership_event(event_id, user_hid, app_hid, stop_time)
  unless stop_time.zone.eql?('UTC')
    raise InvalidTimeError.new('Stop time must be in UTC.')
  end
  path = "/users/#{user_hid}/apps/#{app_hid}/close/#{event_id}" +
         "/#{iso_format(stop_time)}"
  connection = Excon.new(@url)
  connection.put(path: path, expects: [201])
end

#close_usage_event(event_id, product_name, consumer_hid, stop_time) ⇒ Object

Report that usage of a product, by a user or app, stopped at a particular time.

Parameters:

  • event_id (String) —

    A UUID that uniquely identifies the usage event.

  • product_name (String) —

    The name of the product that was used, such as platform:dyno:logical or addon:memcache:100mb.

  • consumer_hid (String) —

    The Heroku ID, such as [email protected] or [email protected], that represents the user or app that used the specified product.

  • stop_time (Time) —

    The end of the usage period, always in UTC.

Raises:

  • (InvalidTimeError) —

    Raised if a non-UTC stop time is provided.

  • (Excon::Errors::HTTPStatusError) —

    Raised if the server returns an unsuccessful HTTP status code.



67
68
69
70
71
72
73
74
75
 
# File 'lib/vault-usage-client/client.rb', line 67

def close_usage_event(event_id, product_name, consumer_hid, stop_time)
  unless stop_time.zone.eql?('UTC')
    raise InvalidTimeError.new('Stop time must be in UTC.')
  end
  path = "/products/#{product_name}/usage/#{consumer_hid}" +
         "/events/#{event_id}/close/#{iso_format(stop_time)}"
  connection = Excon.new(@url)
  connection.put(path: path, expects: [201])
end

#open_app_ownership_event(event_id, user_hid, app_hid, start_time) ⇒ Object

Report that ownership of an app by a user started at a particular time.

Parameters:

  • event_id (String) —

    A UUID that uniquely identifies the ownership event.

  • user_hid (String) —

    The user HID, such as [email protected], that owns the specified app.

  • app_hid (String) —

    The app HID, such as [email protected], that is being transferred to the specified user.

  • start_time (Time) —

    The beginning of the ownership period, always in UTC.

Raises:

  • (InvalidTimeError) —

    Raised if a non-UTC start time is provided.

  • (Excon::Errors::HTTPStatusError) —

    Raised if the server returns an unsuccessful HTTP status code.



256
257
258
259
260
261
262
263
264
 
# File 'lib/vault-usage-client/client.rb', line 256

def open_app_ownership_event(event_id, user_hid, app_hid, start_time)
  unless start_time.zone.eql?('UTC')
    raise InvalidTimeError.new('Start time must be in UTC.')
  end
  path = "/users/#{user_hid}/apps/#{app_hid}/open/#{event_id}" +
         "/#{iso_format(start_time)}"
  connection = Excon.new(@url)
  connection.put(path: path, expects: [201])
end

#open_close_usage_event(event_id, product_name, consumer_hid, start_time, stop_time, detail = nil) ⇒ Object

Report that usage of a product, by a user or app, started at a particular time.

Parameters:

  • event_id (String) —

    A UUID that uniquely identifies the usage event.

  • product_name (String) —

    The name of the product that was used, such as platform:dyno:logical or addon:memcache:100mb.

  • consumer_hid (String) —

    The Heroku ID, such as [email protected] or [email protected], that represents the user or app that used the specified product.

  • start_time (Time) —

    The beginning of the usage period, always in UTC.

  • stop_time (Time) —

    The end of the usage period, always in UTC.

  • detail (Hash) (defaults to: nil) —

    Optionally, additional details to store with the event. Keys must be of type Symbol and values may only be of type String, Fixnum, Bignum, Float, TrueClass, FalseClass or NilClass.

Raises:

  • (InvalidTimeError) —

    Raised if a non-UTC start time is provided.

  • (Excon::Errors::HTTPStatusError) —

    Raised if the server returns an unsuccessful HTTP status code.



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/vault-usage-client/client.rb', line 97

def open_close_usage_event(event_id, product_name, consumer_hid,
                           start_time, stop_time, detail=nil)
  unless start_time.zone.eql?('UTC')
    raise InvalidTimeError.new('Start time must be in UTC.')
  end
  unless stop_time.zone.eql?('UTC')
    raise InvalidTimeError.new('Stop time must be in UTC.')
  end
  path = "/products/#{product_name}/usage/#{consumer_hid}" +
         "/events/#{event_id}/open/#{iso_format(start_time)}" +
         "/close/#{iso_format(stop_time)}"
  unless detail.nil?
    headers = {'Content-Type' => 'application/json'}
    body = MultiJson.dump(detail)
  end
  connection = Excon.new(@url)
  connection.put(path: path, headers: headers, body: body,
                 expects: [201])
end

#open_dynos_for_app(app_hid) ⇒ Array

Get the open dyno usage events for the specified app

Parameters:

  • app_hid (String) —

    The app HID, such as [email protected], to fetch open dyno usage data for.

Returns:

  • (Array) —

    A list of usage events for the specified app, matching the following format:

      [{id: '<event-uuid>',
    product: '<name>',
    consumer: '<heroku-id>',
    start_time: <Time>,
    stop_time: <Time>,
    detail: {<key1>: <value1>,
             <key2>: <value2>,
             ...}},
    ...]}

Raises:

  • (Excon::Errors::HTTPStatusError) —

    Raised if the server returns an unsuccessful HTTP status code.



229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/vault-usage-client/client.rb', line 229

def open_dynos_for_app(app_hid)
  path = "/apps/#{app_hid}/ps/open"
  query = {}
  connection = Excon.new(@url)
  response = connection.get(path: path, expects: [200], query: query)
  payload = MultiJson.load(response.body, {symbolize_keys: true})
  events = payload[:events]
  events.each do |event|
    event.each do |key, value|
      event[key] = parse_date(value) if date?(value)
    end
  end
end

#open_usage_event(event_id, product_name, consumer_hid, start_time, detail = nil) ⇒ Object

Report that usage of a product, by a user or app, started at a particular time.

Parameters:

  • event_id (String) —

    A UUID that uniquely identifies the usage event.

  • product_name (String) —

    The name of the product that was used, such as platform:dyno:logical or addon:memcache:100mb.

  • consumer_hid (String) —

    The Heroku ID, such as [email protected] or [email protected], that represents the user or app that used the specified product.

  • start_time (Time) —

    The beginning of the usage period, always in UTC.

  • detail (Hash) (defaults to: nil) —

    Optionally, additional details to store with the event. Keys must be of type Symbol and values may only be of type String, Fixnum, Bignum, Float, TrueClass, FalseClass or NilClass.

Raises:

  • (InvalidTimeError) —

    Raised if a non-UTC start time is provided.

  • (Excon::Errors::HTTPStatusError) —

    Raised if the server returns an unsuccessful HTTP status code.



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/vault-usage-client/client.rb', line 37

def open_usage_event(event_id, product_name, consumer_hid, start_time,
                     detail=nil)
  unless start_time.zone.eql?('UTC')
    raise InvalidTimeError.new('Start time must be in UTC.')
  end
  path = "/products/#{product_name}/usage/#{consumer_hid}" +
         "/events/#{event_id}/open/#{iso_format(start_time)}"
  unless detail.nil?
    headers = {'Content-Type' => 'application/json'}
    body = MultiJson.dump(detail)
  end
  connection = Excon.new(@url)
  connection.put(path: path, headers: headers, body: body,
                 expects: [201])
end

#usage_for_user(user_hid, start_time, stop_time, exclude = nil, callback_url = nil) ⇒ Array

Get the usage events for the apps owned by the specified user during the specified period.

Parameters:

  • user_hid (String) —

    The user HID, such as [email protected], to fetch usage data for.

  • start_time (Time) —

    The beginning of the usage period, always in UTC, within which events must overlap to be included in usage data.

  • stop_time (Time) —

    The end of the usage period, always in UTC, within which events must overlap to be included in usage data.

  • exclude (Array) (defaults to: nil) —

    Optionally, a list of product names, such as ['platform:dyno:physical', 'addon:memcache:100mb'], to be excluded from usage data.

Returns:

  • (Array) —

    A list of usage events for the specified user, matching the following format:

      [{id: '<event-uuid>',
    product: '<name>',
    consumer: '<heroku-id>',
    start_time: <Time>,
    stop_time: <Time>,
    detail: {<key1>: <value1>,
             <key2>: <value2>,
             ...}},
    ...]}

Raises:

  • (InvalidTimeError) —

    Raised if a non-UTC start or stop time is provided.

  • (Excon::Errors::HTTPStatusError) —

    Raised if the server returns an unsuccessful HTTP status code.



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
 
# File 'lib/vault-usage-client/client.rb', line 147

def usage_for_user(user_hid, start_time, stop_time, exclude=nil, callback_url = nil)
  unless start_time.zone.eql?('UTC')
    raise InvalidTimeError.new('Start time must be in UTC.')
  end
  unless stop_time.zone.eql?('UTC')
    raise InvalidTimeError.new('Stop time must be in UTC.')
  end
  path = "/users/#{user_hid}/usage/#{iso_format(start_time)}/" +
         "#{iso_format(stop_time)}"
  query = {}
  unless exclude.nil? || exclude.empty?
    query[:exclude] = exclude.join(',')
  end
  query[:callback_url] = callback_url if callback_url
  connection = Excon.new(@url)
  response = connection.get(path: path, expects: [200], query: query)
  payload = MultiJson.load(response.body, {symbolize_keys: true})
  return payload[:job_id] if payload[:job_id]
  events = payload[:events]
  events.each do |event|
    event.each do |key, value|
      event[key] = parse_date(value) if date?(value)
    end
  end
end

#usage_for_user_by_product(user_hid, product_name) ⇒ Array

Get the usage events for a product specific to a user.

Parameters:

  • user_hid (String) —

    The user HID, such as [email protected], to fetch usage data for.

  • product_name (String) —

    The product name such as account:credit:lumpsum, to fetch usage data for.

Returns:

  • (Array) —

    A list of usage events for the specified user, matching the following format:

      [{id: '<event-uuid>',
    product: '<name>',
    consumer: '<heroku-id>',
    start_time: <Time>,
    stop_time: <Time>,
    detail: {<key1>: <value1>,
             <key2>: <value2>,
             ...}},
    ...]}

Raises:

  • (Excon::Errors::HTTPStatusError) —

    Raised if the server returns an unsuccessful HTTP status code.



195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/vault-usage-client/client.rb', line 195

def usage_for_user_by_product(user_hid, product_name)
  path = "/users/#{user_hid}/usage/product/#{product_name}"
  connection = Excon.new(@url)
  response = connection.get(path: path, expects: [200])
  payload = MultiJson.load(response.body, {symbolize_keys: true})
  return payload[:job_id] if payload[:job_id]
  events = payload[:events]
  events.each do |event|
    event.each do |key, value|
      event[key] = parse_date(value) if date?(value)
    end
  end
end