vault-usage-client 0.0.1

data/.gitignore

@@ -0,0 +1,5 @@
+.bundle
+doc
+test/.test.profile*
+vendor
+.yardoc

data/.yardopts

@@ -0,0 +1 @@
+-m markdown

data/Gemfile

@@ -0,0 +1,12 @@
+source :rubygems
+
+gemspec
+
+group :development do
+  gem 'rake'
+end
+
+group :test do
+  gem 'rr'
+  gem 'vault-test-tools', '~> 0.2.2', :git => 'https://github.com/heroku/vault-test-tools.git'
+end

data/Gemfile.lock

@@ -0,0 +1,58 @@
+GIT
+  remote: https://github.com/heroku/vault-test-tools.git
+  revision: 5eabd67610f279b81cadb803cee8ef704093a05d
+  specs:
+    vault-test-tools (0.2.2)
+      minitest
+      nokogiri
+      rack-perftools_profiler
+      rack-test
+      rdoc
+      redcarpet
+      turn
+      yard
+
+PATH
+  remote: .
+  specs:
+    vault-usage-client (0.0.1)
+      colorize
+      excon
+      yajl-ruby
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    ansi (1.4.3)
+    colorize (0.5.8)
+    excon (0.16.10)
+    json (1.7.6)
+    minitest (4.6.0)
+    nokogiri (1.5.6)
+    open4 (1.3.0)
+    perftools.rb (2.0.0)
+    rack (1.5.2)
+    rack-perftools_profiler (0.6.0)
+      open4 (~> 1.0)
+      perftools.rb (~> 2.0.0)
+      rack (~> 1.0)
+    rack-test (0.6.2)
+      rack (>= 1.0)
+    rake (10.0.3)
+    rdoc (3.12.1)
+      json (~> 1.4)
+    redcarpet (2.2.2)
+    rr (1.0.4)
+    turn (0.9.6)
+      ansi
+    yajl-ruby (1.1.0)
+    yard (0.8.4.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake
+  rr
+  vault-test-tools (~> 0.2.2)!
+  vault-usage-client!

data/README.md

@@ -0,0 +1,165 @@
+# Vault::Usage::Client
+
+Client provides a Ruby API for interacting with the `Vault::Usage`
+HTTP API.
+
+## Setting up a development environment
+
+Install dependencies and run the test suite:
+
+    bundle install --binstubs vendor/bin
+    rbenv rehash
+    rake
+
+Run tests:
+
+    rake test
+
+See tasks:
+
+    rake -T
+
+Generate API documentation:
+
+    rake yard
+
+## Using the client from the command-line
+
+The `bin/vault-usage` command-line tool can be used to quickly see
+usage data for a particular user:
+
+```bash
+export VAULT_USAGE_URL=https://username:secret@vault-usage.herokuapp.com
+bin/vault-usage user123@heroku.com 2013-01-01 2013-02-01
+```
+
+## Using the client in Ruby
+
+The `Vault::Usage` API may only be accessed with valid credentials.
+You must supply these when you create a new client:
+
+```ruby
+require 'vault-usage-client'
+
+client = Vault::Usage::Client::Client.new(
+  'https://username:secret@vault-usage.herokuapp.com')
+```
+
+### Usage events
+
+Usage events represent usage of a product, for a period of time, by an
+app or user.
+
+#### Opening a usage event
+
+Each usage event must have a unique UUID provided by the service
+reporting it and the start time must be in UTC:
+
+```ruby
+event_id = SecureRandom.uuid
+product_name = 'platform:dyno:logical'
+consumer_hid = 'app1234@heroku.com'
+start_time = Time.now.getutc
+client.open_usage_event(event_id, product_name, consumer_hid, start_time)
+```
+
+Arbitrary data related to the usage event can optionally be provided
+by way of a detail object:
+
+```ruby
+event_id = SecureRandom.uuid
+product_name = 'platform:dyno:logical'
+consumer_hid = 'app1234@heroku.com'
+start_time = Time.now.getutc
+detail = {type: 'web',
+          description: 'bundle exec bin/web',
+          kernel: 'us-east-1-a'}
+client.open_usage_event(event_id, product_name, consumer_hid, start_time,
+                        detail)
+```
+
+Keys in the detail object must be of type `Symbol` and values may only
+be of type `String`, `Fixnum`, `Bignum`, `Float`, `TrueClass`,
+`FalseClass` or `NilClass`.  In other words, it's not possible to use
+nested structures in the detail object.
+
+#### Closing a usage event
+
+Closing a usage event works the same way as opening one:
+
+```ruby
+event_id = SecureRandom.uuid
+product_name = 'platform:dyno:logical'
+consumer_hid = 'app1234@heroku.com'
+stop_time = Time.now.getutc
+client.close_event(event_id, product_name, consumer_hid, stop_time)
+```
+
+#### Retrieving usage information
+
+Usage information for a particular user can be retrieved by the
+client.  The start and stop time must both be specified in UTC:
+
+```ruby
+user_hid = 'user1234@heroku.com'
+start_time = Time.utc(2013, 1)
+stop_time = Time.utc(2013, 2)
+events = client.usage_for_user(user_hid, start_time, stop_time)
+```
+
+The `events` result is an `Array` of objects matching this format:
+
+```ruby
+[{id: '<event-uuid>',
+  product: '<name>',
+  consumer: '<consumer-hid>',
+  start_time: <Time>,
+  stop_time: <Time>,
+  detail: {<key1>: <value1>,
+           <key2>: <value2>,
+           ...}},
+  ...]}
+```
+
+In some cases it can be useful to exclude event data for certain
+products:
+
+```ruby
+user_hid = 'user1234@heroku.com'
+start_time = Time.utc(2013, 1)
+stop_time = Time.utc(2013, 2)
+events = client.usage_for_user(user_hid, start_time, stop_time,
+                               ['platform:dyno:physical'])
+```
+
+You can pass one or more product names to exclude.
+
+### App ownership events
+
+App ownership events represent ownership of an app, for a period of
+time, by a user.
+
+#### Opening an app ownership event
+
+Each app ownership event must have a unique UUID provided by the
+service reporting it and the start time must be in UTC:
+
+```ruby
+event_id = SecureRandom.uuid
+user_hid = 'user1234@heroku.com'
+app_hid = 'app1234@heroku.com'
+start_time = Time.now.getutc
+client.open_app_ownership_event(event_id, user_hid, app_hid, start_time)
+```
+
+#### Closing an app ownership event
+
+Closing an app ownership event works the same way as opening one:
+
+```ruby
+event_id = SecureRandom.uuid
+user_hid = 'user1234@heroku.com'
+app_hid = 'app1234@heroku.com'
+stop_time = Time.now.getutc
+client.close_app_ownership_event(event_id, user_hid, app_hid, stop_time)
+```

data/Rakefile

@@ -0,0 +1,11 @@
+require 'bundler/gem_tasks'
+require 'yard'
+
+desc "Test the things"
+require 'vault-test-tools/rake_task'
+
+desc "Doc the things"
+YARD::Rake::YardocTask.new
+
+desc "Run the test suite"
+task :default => [:test]

data/bin/vault-usage

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+
+lib = File.expand_path('../../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'vault-usage-client'
+require 'colorize'
+
+user_hid = ARGV[0]
+start_time = Time.utc(*ARGV[1].split('-'))
+stop_time  = Time.utc(*ARGV[2].split('-'))
+
+client = Vault::Usage::Client.new
+
+all_events = client.usage_for_user(user_hid, start_time, stop_time, ['platform:dyno:physical'])[:events]
+
+all_events.group_by { |e| e[:consumer] }.each do |consumer, app_events|
+  puts "=== #{consumer} ===".blue
+
+  app_events.group_by { |e| e[:product] }.each do |product, product_events|
+
+    puts " #{product}"
+    product_events.
+      map { |event| OpenStruct.new(event) }.
+      sort_by(&:start_time).
+      each do |e|
+        puts "    #{e.id}".light_green
+        puts "    #{e.start_time} -> #{e.stop_time}: #{e.detail}".green
+        if e.start_time > e.stop_time
+          puts "    ERROR: start_time is after stop_time".red
+        end
+        puts
+    end
+
+  end
+  puts
+end

data/lib/vault-usage-client/client.rb

@@ -0,0 +1,205 @@
+module Vault::Usage
+  # Client for the `Vault::Usage` HTTP API.
+  class Client
+    attr_reader :url
+
+    # Raised if a non-UTC time is used with the client.
+    class InvalidTimeError < Exception
+    end
+
+    # Instantiate a client.
+    #
+    # @param url [String] The URL to connect to.  Include the username and
+    #   password to use when connecting.
+    def initialize(url = nil)
+      @url = url || ENV['VAULT_USAGE_URL']
+    end
+
+    # Report that usage of a product, by a user or app, started at a
+    # particular time.
+    #
+    # @param event_id [String] A UUID that uniquely identifies the usage
+    #   event.
+    # @param product_name [String] The name of the product that was used, such
+    #   as `platform:dyno:logical` or `addon:memcache:100mb`.
+    # @param consumer_hid [String] The Heroku ID, such as `app1234@heroku.com`
+    #   or `user1234@heroku.com`, that represents the user or app that used
+    #   the specified product.
+    # @param start_time [Time] The beginning of the usage period, always in
+    #   UTC.
+    # @param detail [Hash] 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`.
+    # @raise [InvalidTimeError] Raised if a non-UTC start time is provided.
+    # @raise [Excon::Errors::HTTPStatusError] Raised if the server returns an
+    #   unsuccessful HTTP status code.
+    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 = JSON.generate(detail)
+      end
+      connection = Excon.new(@url)
+      connection.put(path: path, headers: headers, body: body,
+                     expects: [201])
+    end
+
+    # Report that usage of a product, by a user or app, stopped at a
+    # particular time.
+    #
+    # @param event_id [String] A UUID that uniquely identifies the usage
+    #   event.
+    # @param product_name [String] The name of the product that was used, such
+    #   as `platform:dyno:logical` or `addon:memcache:100mb`.
+    # @param consumer_hid [String] The Heroku ID, such as `app1234@heroku.com`
+    #   or `user1234@heroku.com`, that represents the user or app that used
+    #   the specified product.
+    # @param stop_time [Time] The end of the usage period, always in UTC.
+    # @raise [InvalidTimeError] Raised if a non-UTC stop time is provided.
+    # @raise [Excon::Errors::HTTPStatusError] Raised if the server returns an
+    #   unsuccessful HTTP status code.
+    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
+
+    # Get the usage events for the apps owned by the specified user during the
+    # specified period.
+    #
+    # @param user_hid [String] The user HID, such as `user1234@heroku.com`, to
+    #   fetch usage data for.
+    # @param start_time [Time] The beginning of the usage period, always in
+    #   UTC, within which events must overlap to be included in usage data.
+    # @param stop_time [Time] The end of the usage period, always in UTC,
+    #   within which events must overlap to be included in usage data.
+    # @param exclude [Array] Optionally, a list of product names, such as
+    #   `['platform:dyno:physical', 'addon:memcache:100mb']`, to be excluded
+    #   from usage data.
+    # @raise [InvalidTimeError] Raised if a non-UTC start or stop time is
+    #   provided.
+    # @raise [Excon::Errors::HTTPStatusError] Raised if the server returns an
+    #   unsuccessful HTTP status code.
+    # @return [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>,
+    #                ...}},
+    #       ...]}
+    #   ```
+    def usage_for_user(user_hid, start_time, stop_time, exclude=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)}"
+      unless exclude.nil? || exclude.empty?
+        query = {exclude: exclude.join(',')}
+      end
+      connection = Excon.new(@url)
+      response = connection.get(path: path, expects: [200], query: query)
+      events = JSON.parse(response.body, {symbolize_keys: true})
+      events.each do |event|
+        event.each do |key, value|
+          event[key] = parse_date(value) if date?(value)
+        end
+      end
+    end
+
+    # Report that ownership of an app by a user started at a particular time.
+    #
+    # @param event_id [String] A UUID that uniquely identifies the ownership
+    #   event.
+    # @param user_hid [String] The user HID, such as `user1234@heroku.com`,
+    #   that owns the specified app.
+    # @param app_hid [String] The app HID, such as `app1234@heroku.com`, that
+    #   is being transferred to the specified user.
+    # @param start_time [Time] The beginning of the ownership period, always
+    #   in UTC.
+    # @raise [InvalidTimeError] Raised if a non-UTC start time is provided.
+    # @raise [Excon::Errors::HTTPStatusError] Raised if the server returns an
+    #   unsuccessful HTTP status code.
+    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
+
+    # Report that ownership of an app by a user stopped at a particular time.
+    #
+    # @param event_id [String] A UUID that uniquely identifies the ownership
+    #   event.
+    # @param user_hid [String] The user HID, such as `user1234@heroku.com`,
+    #   that owned the specified app.
+    # @param app_hid [String] The app HID, such as `app1234@heroku.com`, that
+    #   is being transferred away from the specified user.
+    # @param stop_time [Time] The end of the ownership period, always in UTC.
+    # @raise [InvalidTimeError] Raised if a non-UTC stop time is provided.
+    # @raise [Excon::Errors::HTTPStatusError] Raised if the server returns an
+    #   unsuccessful HTTP status code.
+    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
+
+    private
+
+    # Convert a time to an ISO 8601 combined data and time format.
+    #
+    # @param time [Time] The time to convert to ISO 8601 format.
+    # @return [String] An ISO 8601 date in `YYYY-MM-DDTHH:MM:SSZ` format.
+    def iso_format(time)
+      time.strftime('%Y-%m-%dT%H:%M:%SZ')
+    end
+
+    # Determine if the value is an ISO 8601 date in `YYYY-MM-DDTHH:MM:SSZ`
+    # format.
+    #
+    # @param value [String] The value to check for date-ness.
+    # @return [TrueClass,FalseClass] True if the value resembles a date,
+    #   otherwise false.
+    def date?(value)
+      value =~ /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z/
+    end
+
+    # Parse an ISO 8601 date in `YYYY-MM-DDTHH:MM:SSZ` format into a Time
+    # instance.
+    #
+    # @param value [String] The value to parse.
+    # @raise [ArgumentError] Raised if the value doesn't represent a valid
+    #   date.
+    # @return [Time] The Time instance created from the date string in UTC.
+    def parse_date(value)
+      DateTime.parse(value).to_time.getutc
+    end
+  end
+end

data/lib/vault-usage-client/version.rb

@@ -0,0 +1,8 @@
+module Vault
+  module Usage
+    class Client
+      # The `Vault::Usage::Client` gem version.
+      VERSION = '0.0.1'
+    end
+  end
+end

data/lib/vault-usage-client.rb

@@ -0,0 +1,16 @@
+require 'bundler'
+Bundler.require :default, ENV['RACK_ENV'].to_sym
+
+require 'excon'
+require 'yajl/json_gem'
+
+module Vault
+  module Usage
+    # Client provides a Ruby API to access the Vault::Usage HTTP API.
+    class Client
+    end
+  end
+end
+
+require 'vault-usage-client/client'
+require 'vault-usage-client/version'

data/test/client_test.rb

@@ -0,0 +1,338 @@
+require 'helper'
+
+class ClientTest < Vault::TestCase
+  include Vault::Test::EnvironmentHelpers
+
+  def setup
+    super
+    Excon.stubs.clear
+    Excon.defaults[:mock] = true
+    @client = Vault::Usage::Client.new(
+      'https://username:secret@vault-usage.herokuapp.com')
+    @event_id = 'd8bb95d1-6279-4488-961d-133514b772fa'
+    @product_name = 'platform:dyno:logical'
+    @app_hid = 'app123@heroku.com'
+    @user_hid = 'user456@heroku.com'
+    @start_time = Time.utc(2013, 1)
+    @stop_time = Time.utc(2013, 2)
+  end
+
+  def teardown
+    # FIXME This is a bit ugly, but Excon doesn't provide a builtin way to
+    # ensure that a request was invoked, so we have to do it ourselves.
+    # Without this, and the Excon.stubs.pop calls in the tests below, tests
+    # will pass if request logic is completely removed from application
+    # code. -jkakar
+    assert(Excon.stubs.empty?, 'Expected HTTP requests were not made.')
+    super
+  end
+
+  # Convert a time to an ISO 8601 combined data and time format.
+  def iso_format(time)
+    time.strftime('%Y-%m-%dT%H:%M:%SZ')
+  end
+
+  # Client.new looks for VAULT_USAGE_URL if none is passed in to the constructor
+  def test_uses_env_for_url_if_not_given
+    url = 'http://foo:bar@example.com'
+    set_env 'VAULT_USAGE_URL', url
+    @client = Vault::Usage::Client.new
+    assert_equal(url, @client.url)
+  end
+
+  # Client.open_usage_event makes a PUT request to the Vault::Usage HTTP API,
+  # passing the supplied credentials using HTTP basic auth, to report that
+  # usage of a product began at a particular time.
+  def test_open_usage_event
+    Excon.stub(method: :put) do |request|
+      assert_equal('Basic dXNlcm5hbWU6c2VjcmV0',
+                   request[:headers]['Authorization'])
+      assert_equal('vault-usage.herokuapp.com:443', request[:host_port])
+      assert_equal("/products/#{@product_name}/usage/#{@app_hid}" +
+                   "/events/#{@event_id}/open/#{iso_format(@start_time)}",
+                   request[:path])
+      Excon.stubs.pop
+      {status: 201}
+    end
+    @client.open_usage_event(@event_id, @product_name, @app_hid, @start_time)
+  end
+
+  # Client.open_usage_event optionally accepts a detail hash which is sent as
+  # a JSON payload in the request body when provided.
+  def test_open_usage_event_with_detail
+    detail = {type: 'web',
+              description: 'bundle exec bin/web',
+              kernel: 'us-east-1-a'}
+    Excon.stub(method: :put) do |request|
+      assert_equal('application/json', request[:headers]['Content-Type'])
+      assert_equal(detail, JSON.parse(request[:body], {symbolize_keys: true}))
+      Excon.stubs.pop
+      {status: 201}
+    end
+    @client.open_usage_event(@event_id, @product_name, @app_hid, @start_time,
+                             detail)
+  end
+
+  # Client.open_usage_event raises an InvalidTimeError if the start time is
+  # not in UTC.
+  def test_open_usage_event_with_non_utc_start_time
+    start_time = Time.new(2013, 1, 12, 15, 25, 0, '+09:00')
+    error = assert_raises Vault::Usage::Client::InvalidTimeError do
+      @client.open_usage_event(@event_id, @product_name, @app_hid, start_time)
+    end
+    assert_equal('Start time must be in UTC.', error.message)
+  end
+
+  # Client.open_usage_event raises the appropriate
+  # Excon::Errors::HTTPStatusError if an unsuccessful HTTP status code is
+  # returned by the server.
+  def test_open_usage_event_with_unsuccessful_response
+    Excon.stub(method: :put) do |request|
+      Excon.stubs.pop
+      {status: 400, body: 'Bad inputs provided.'}
+    end
+    assert_raises Excon::Errors::BadRequest do
+      @client.open_usage_event(@event_id, @product_name, @app_hid, @start_time)
+    end
+  end
+
+  # Client.close_usage_event makes a PUT request to the Vault::Usage HTTP
+  # API, passing the supplied credentials using HTTP basic auth, to report
+  # that usage of a product ended at a particular time.
+  def test_close_usage_event
+    Excon.stub(method: :put) do |request|
+      assert_equal('Basic dXNlcm5hbWU6c2VjcmV0',
+                   request[:headers]['Authorization'])
+      assert_equal('vault-usage.herokuapp.com:443', request[:host_port])
+      assert_equal("/products/#{@product_name}/usage/#{@app_hid}" +
+                   "/events/#{@event_id}/close/#{iso_format(@stop_time)}",
+                   request[:path])
+      Excon.stubs.pop
+      {status: 201}
+    end
+    @client.close_usage_event(@event_id, @product_name, @app_hid, @stop_time)
+  end
+
+  # Client.close_usage_event raises an InvalidTimeError if the stop time is
+  # not in UTC.
+  def test_close_usage_event_with_non_utc_stop_time
+    stop_time = Time.new(2013, 1, 12, 15, 25, 0, '+09:00')
+    error = assert_raises Vault::Usage::Client::InvalidTimeError do
+      @client.close_usage_event(@event_id, @product_name, @app_hid, stop_time)
+    end
+    assert_equal('Stop time must be in UTC.', error.message)
+  end
+
+  # Client.close_usage_event raises the appropriate
+  # Excon::Errors::HTTPStatusError if an unsuccessful HTTP status code is
+  # returned by the server.
+  def test_close_usage_event_with_unsuccessful_response
+    Excon.stub(method: :put) do |request|
+      Excon.stubs.pop
+      {status: 400, body: 'Bad inputs provided.'}
+    end
+    assert_raises Excon::Errors::BadRequest do
+      @client.close_usage_event(@event_id, @product_name, @app_hid, @stop_time)
+    end
+  end
+
+  # Client.usage_for_user makes a GET request to the Vault::Usage HTTP API,
+  # passing the supplied credentials using HTTP basic auth, to retrieve the
+  # usage events for a particular user that occurred during the specified
+  # period of time.
+  def test_usage_for_user
+    Excon.stub(method: :get) do |request|
+      assert_equal('Basic dXNlcm5hbWU6c2VjcmV0',
+                   request[:headers]['Authorization'])
+      assert_equal('vault-usage.herokuapp.com:443', request[:host_port])
+      assert_equal("/users/#{@user_hid}/usage/#{iso_format(@start_time)}/" +
+                   "#{iso_format(@stop_time)}",
+                   request[:path])
+      Excon.stubs.pop
+      {status: 200, body: JSON.generate([])}
+    end
+    assert_equal([], @client.usage_for_user(@user_hid, @start_time,
+                                            @stop_time))
+  end
+
+  # Client.usage_for_user optionally accepts a list of products to exclude.
+  # They're passed to the server using query string arguments.
+  def test_usage_for_user_with_exclude
+    Excon.stub(method: :get) do |request|
+      assert_equal({exclude: 'platform:dyno:physical'}, request[:query])
+      Excon.stubs.pop
+      {status: 200, body: JSON.generate([])}
+    end
+    assert_equal([], @client.usage_for_user(@user_hid, @start_time, @stop_time,
+                                            ['platform:dyno:physical']))
+  end
+
+  # Client.usage_for_user comma-separates product names, when many are
+  # provided in the exclusion list, and passes them to the server using a
+  # single query argument.
+  def test_usage_for_user_with_many_excludes
+    Excon.stub(method: :get) do |request|
+      assert_equal({exclude: 'platform:dyno:physical,addons:memcache:100mb'},
+                   request[:query])
+      Excon.stubs.pop
+      {status: 200, body: JSON.generate([])}
+    end
+    assert_equal([], @client.usage_for_user(@user_hid, @start_time, @stop_time,
+                                            ['platform:dyno:physical',
+                                             'addons:memcache:100mb']))
+  end
+
+  # Client.usage_for_user with an empty product exclusion list is the same as
+  # not passing one at all.
+  def test_usage_for_user_with_empty_exclude
+    Excon.stub(method: :get) do |request|
+      assert_equal(nil, request[:query])
+      Excon.stubs.pop
+      {status: 200, body: JSON.generate([])}
+    end
+    assert_equal([], @client.usage_for_user(@user_hid, @start_time, @stop_time,
+                                            []))
+  end
+
+  # Client.usage_for_user converts event start and stop times to Time
+  # instances.
+  def test_usage_for_user_converts_times
+    Excon.stub(method: :get) do |request|
+      Excon.stubs.pop
+      events = [{id: @event_id,
+                 product: @product_name,
+                 consumer: @app_hid,
+                 start_time: iso_format(@start_time),
+                 stop_time: iso_format(@stop_time),
+                 detail: {}}]
+      {status: 200, body: JSON.generate(events)}
+    end
+    assert_equal([{id: @event_id,
+                   product: @product_name,
+                   consumer: @app_hid,
+                   start_time: @start_time,
+                   stop_time: @stop_time,
+                   detail: {}}],
+                 @client.usage_for_user(@user_hid, @start_time, @stop_time))
+  end
+
+  # Client.usage_for_user raises an InvalidTimeError if the start time is not
+  # in UTC.
+  def test_usage_for_user_with_non_utc_start_time
+    start_time = Time.new(2013, 1, 12, 15, 25, 0, '+09:00')
+    error = assert_raises Vault::Usage::Client::InvalidTimeError do
+      @client.usage_for_user(@user_hid, start_time, @stop_time)
+    end
+    assert_equal('Start time must be in UTC.', error.message)
+  end
+
+  # Client.usage_for_user raises an InvalidTimeError if the stop time is not
+  # in UTC.
+  def test_usage_for_user_with_non_utc_stop_time
+    stop_time = Time.new(2013, 1, 12, 15, 25, 0, '+09:00')
+    error = assert_raises Vault::Usage::Client::InvalidTimeError do
+      @client.usage_for_user(@user_hid, @start_time, stop_time)
+    end
+    assert_equal('Stop time must be in UTC.', error.message)
+  end
+
+  # Client.usage_for_user raises the appropriate Excon::Errors::HTTPStatusError
+  # if an unsuccessful HTTP status code is returned by the server.
+  def test_usage_for_user_with_unsuccessful_response
+    Excon.stub(method: :get) do |request|
+      Excon.stubs.pop
+      {status: 400, body: 'Bad inputs provided.'}
+    end
+    assert_raises Excon::Errors::BadRequest do
+      @client.usage_for_user(@user_hid, @start_time, @stop_time)
+    end
+  end
+
+  # Client.open_app_ownership_event makes a PUT request to the Vault::Usage
+  # HTTP API, passing the supplied credentials using HTTP basic auth, to
+  # report that ownership of an app, by a particular user, began at a
+  # particular time.
+  def test_open_app_ownership_event
+    Excon.stub(method: :put) do |request|
+      assert_equal('Basic dXNlcm5hbWU6c2VjcmV0',
+                   request[:headers]['Authorization'])
+      assert_equal('vault-usage.herokuapp.com:443', request[:host_port])
+      assert_equal("/users/#{@user_hid}/apps/#{@app_hid}/open/#{@event_id}" +
+                   "/#{iso_format(@start_time)}",
+                   request[:path])
+      Excon.stubs.pop
+      {status: 201}
+    end
+    @client.open_app_ownership_event(@event_id, @user_hid, @app_hid,
+                                     @start_time)
+  end
+
+  # Client.open_app_ownership_event raises an InvalidTimeError if the start
+  # time is not in UTC.
+  def test_open_app_ownership_event_with_non_utc_start_time
+    start_time = Time.new(2013, 1, 12, 15, 25, 0, '+09:00')
+    error = assert_raises Vault::Usage::Client::InvalidTimeError do
+      @client.open_app_ownership_event(@event_id, @user_hid, @app_hid,
+                                       start_time)
+    end
+    assert_equal('Start time must be in UTC.', error.message)
+  end
+
+  # Client.open_app_ownership_event raises the appropriate
+  # Excon::Errors::HTTPStatusError if an unsuccessful HTTP status code is
+  # returned by the server.
+  def test_open_app_ownership_event_with_unsuccessful_response
+    Excon.stub(method: :put) do |request|
+      Excon.stubs.pop
+      {status: 400, body: 'Bad inputs provided.'}
+    end
+    assert_raises Excon::Errors::BadRequest do
+      @client.open_app_ownership_event(@event_id, @user_hid, @app_hid,
+                                       @start_time)
+    end
+  end
+
+  # Client.close_app_ownership_event makes a PUT request to the Vault::Usage
+  # HTTP API, passing the supplied credentials using HTTP basic auth, to
+  # report that ownership of an app, by a particular user, began at a
+  # particular time.
+  def test_close_app_ownership_event
+    Excon.stub(method: :put) do |request|
+      assert_equal('Basic dXNlcm5hbWU6c2VjcmV0',
+                   request[:headers]['Authorization'])
+      assert_equal('vault-usage.herokuapp.com:443', request[:host_port])
+      assert_equal("/users/#{@user_hid}/apps/#{@app_hid}/close/#{@event_id}" +
+                   "/#{iso_format(@stop_time)}",
+                   request[:path])
+      Excon.stubs.pop
+      {status: 201}
+    end
+    @client.close_app_ownership_event(@event_id, @user_hid, @app_hid,
+                                      @stop_time)
+  end
+
+  # Client.close_app_ownership_event raises an InvalidTimeError if the stop
+  # time is not in UTC.
+  def test_close_app_ownership_event_with_non_utc_stop_time
+    stop_time = Time.new(2013, 1, 12, 15, 25, 0, '+09:00')
+    error = assert_raises Vault::Usage::Client::InvalidTimeError do
+      @client.close_app_ownership_event(@event_id, @user_hid, @app_hid,
+                                        stop_time)
+    end
+    assert_equal('Stop time must be in UTC.', error.message)
+  end
+
+  # Client.close_app_ownership_event raises the appropriate
+  # Excon::Errors::HTTPStatusError if an unsuccessful HTTP status code is
+  # returned by the server.
+  def test_close_app_ownership_event_with_unsuccessful_response
+    Excon.stub(method: :put) do |request|
+      Excon.stubs.pop
+      {status: 400, body: 'Bad inputs provided.'}
+    end
+    assert_raises Excon::Errors::BadRequest do
+      @client.close_app_ownership_event(@event_id, @user_hid, @app_hid,
+                                        @stop_time)
+    end
+  end
+end

data/test/helper.rb

@@ -0,0 +1,4 @@
+ENV['RACK_ENV'] = 'test'
+
+require 'vault-usage-client'
+require 'vault-test-tools'

data/test/version_test.rb

@@ -0,0 +1,9 @@
+require 'helper'
+
+class VersionTest < Vault::TestCase
+  # Vault::Usage::Client::VERSION is a string matching the `major.minor.patch`
+  # format.
+  def test_version
+    assert_match(/\d+\.\d+\.\d+/, Vault::Usage::Client::VERSION)
+  end
+end

data/vault-usage-client.gemspec

@@ -0,0 +1,21 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'vault-usage-client/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "vault-usage-client"
+  gem.version       = Vault::Usage::Client::VERSION
+  gem.authors       = ["Chris Continanza", "Jamu Kakar"]
+  gem.email         = ["csquared@heroku.com", "jkakar@heroku.com"]
+  gem.description   = "Client for Vault::Usage"
+  gem.summary       = "A simple wrapper around the Vault::Usage HTTP API"
+  gem.homepage      = "https://github.com/heroku/vault-usage-client"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.test_files    = gem.files.grep('^(test|spec|features)/')
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency 'excon'
+  gem.add_dependency 'yajl-ruby'
+  gem.add_dependency 'colorize'
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: vault-usage-client
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Chris Continanza
+- Jamu Kakar
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: excon
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yajl-ruby
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: colorize
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Client for Vault::Usage
+email:
+- csquared@heroku.com
+- jkakar@heroku.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .yardopts
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- bin/vault-usage
+- lib/vault-usage-client.rb
+- lib/vault-usage-client/client.rb
+- lib/vault-usage-client/version.rb
+- test/client_test.rb
+- test/helper.rb
+- test/version_test.rb
+- vault-usage-client.gemspec
+homepage: https://github.com/heroku/vault-usage-client
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 3440025206376780543
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 3440025206376780543
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: A simple wrapper around the Vault::Usage HTTP API
+test_files: []
+has_rdoc: