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.11'

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.



304
305
306
307
308
309
310
311
312
 
# File 'lib/vault-usage-client/client.rb', line 304

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.



282
283
284
285
286
287
288
289
290
 
# File 'lib/vault-usage-client/client.rb', line 282

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.



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

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_event(event_id) ⇒ Array

Request a single usage event.

Returns:

  • (Array) —

    A single usage event, matching the following format:

      {id: '<event-uuid>',
   product: '<name>',
   consumer: '<heroku-id>',
   start_time: '<YYYY-MM-DDTHH:MM:SSZ>',
   stop_time: '<YYYY-MM-DDTHH:MM:SSZ>',
   detail: {<key1>: <value1>,
            <key2>: <value2> }
  }

Raises:

  • (Excon::Errors::HTTPStatusError) —

    Raised if the server returns an unsuccessful HTTP status code.



133
134
135
136
137
138
139
140
141
 
# File 'lib/vault-usage-client/client.rb', line 133

def usage_for_event(event_id)
  path = "/usage_events/#{event_id}"
  connection = Excon.new(@url)
  response = connection.get(path: path, expects: [200])
  event = MultiJson.load(response.body, {symbolize_keys: true})
  event.each do |key, value|
    event[key] = parse_date(value) if date?(value)
  end
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.



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

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.



221
222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/vault-usage-client/client.rb', line 221

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