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.

'1.0.0'.freeze

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.



309
310
311
312
313
314
315
316
317
 
# File 'lib/vault-usage-client/client.rb', line 309

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.



287
288
289
290
291
292
293
294
295
 
# File 'lib/vault-usage-client/client.rb', line 287

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.



260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/vault-usage-client/client.rb', line 260

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, snapshot = false) ⇒ Array

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

usage events JSON at the start_time

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.

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

    The URL vault-usage will callback after generating

  • snapshot (Boolean) (defaults to: false) —

    Whether or not to return only events that were open

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.



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

def usage_for_user(user_hid, start_time, stop_time, exclude=nil, callback_url=nil, snapshot=false)
  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 = {}
  query[:snapshot] = true if snapshot
  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.



226
227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/vault-usage-client/client.rb', line 226

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