V3: GET /v3/usage_events/:guid

reidmit · Brian Cunnie · Brian Cunnie · commit 1095365b6056 · 2020-05-28T12:37:42.000-07:00
Usage events are a synthesis of app usage events and service usage
events. We combine both `AppUsageEvent` and `ServiceUsageEvent` in a
model `UsageEvent` backed by a union of the two tables.

Usage Events and their models do **not** have an `updated_at` field, for
events are created but not updated; however, we present an `updated_at`
field to the user for completeness's sake. The `updated_at` is the same
as the `created_at` value.

[#172985853]

[finishes #169237831]

Co-authored-by: Reid Mitchell &lt;rmitchell@pivotal.io&gt;
Co-authored-by: Brian Cunnie &lt;bcunnie@pivotal.io&gt;
diff --git a/app/controllers/v3/usage_events_controller.rb b/app/controllers/v3/usage_events_controller.rb
@@ -0,0 +1,17 @@
+require 'presenters/v3/usage_event_presenter'
+
+class UsageEventsController < ApplicationController
+  def show
+    usage_event_not_found! unless permission_queryer.can_read_globally?
+    usage_event = UsageEvent.first(guid: hashed_params[:guid])
+    usage_event_not_found! unless usage_event
+
+    render status: :ok, json: Presenters::V3::UsageEventPresenter.new(usage_event)
+  end
+
+  private
+
+  def usage_event_not_found!
+    resource_not_found!(:usage_event)
+  end
+end
diff --git a/app/models.rb b/app/models.rb
@@ -141,3 +141,4 @@
 require 'models/runtime/organization_manager'
 require 'models/runtime/organization_billing_manager'
 require 'models/runtime/role'
+require 'models/runtime/usage_event'
diff --git a/app/models/runtime/usage_event.rb b/app/models/runtime/usage_event.rb
@@ -0,0 +1,19 @@
+module VCAP::CloudController
+  class UsageEvent < Sequel::Model(
+    AppUsageEvent.select(
+      Sequel.as('app', :type),
+      :guid,
+      :created_at,
+      Sequel.as(:created_at, :updated_at)
+    ).union(
+      ServiceUsageEvent.select(
+        Sequel.as('service', :type),
+        :guid,
+        :created_at,
+        Sequel.as(:created_at, :updated_at)),
+      all: true,
+      from_self: false
+    ).from_self
+  )
+  end
+end
diff --git a/app/presenters/v3/usage_event_presenter.rb b/app/presenters/v3/usage_event_presenter.rb
@@ -0,0 +1,20 @@
+require 'presenters/v3/base_presenter'
+
+module VCAP::CloudController::Presenters::V3
+  class UsageEventPresenter < BasePresenter
+    def to_hash
+      {
+        guid: usage_event.guid,
+        created_at: usage_event.created_at,
+        updated_at: usage_event.updated_at,
+        type: usage_event.type,
+      }
+    end
+
+    private
+
+    def usage_event
+      @resource
+    end
+  end
+end
diff --git a/config/routes.rb b/config/routes.rb
@@ -291,6 +291,9 @@
   get '/audit_events', to: 'events#index'
   get '/audit_events/:guid', to: 'events#show'
 
+  # usage events
+  get '/usage_events/:guid', to: 'usage_events#show'
+
   # environment variable groups
   get '/environment_variable_groups/:name', to: 'environment_variable_groups#show'
   patch '/environment_variable_groups/:name', to: 'environment_variable_groups#update'
diff --git a/docs/v3/source/includes/api_resources/_usage_events.erb b/docs/v3/source/includes/api_resources/_usage_events.erb
@@ -0,0 +1,8 @@
+<% content_for :single_usage_event do %>
+{
+  "guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
+  "created_at": "2020-05-28T16:41:23Z",
+  "updated_at": "2020-05-28T16:41:26Z",
+  "type": "app"
+}
+<% end %>
diff --git a/docs/v3/source/includes/experimental_resources/usage_events/_get.md b/docs/v3/source/includes/experimental_resources/usage_events/_get.md
@@ -0,0 +1,40 @@
+### Get a usage event
+
+```
+Example Request
+```
+
+```shell
+curl "https://api.example.org/v3/usage_events/[guid]" \
+  -X GET \
+  -H "Authorization: bearer [token]"
+```
+
+```
+Example Response
+```
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "guid": "a595fe2f-01ff-4965-a50c-290258ab8582",
+  "created_at": "2020-05-28T16:41:23Z",
+  "updated_at": "2020-05-28T16:41:26Z",
+  "type": "app"
+}
+```
+
+Retrieve a usage event.
+
+#### Definition
+
+`GET /v3/usage_events/:guid`
+
+#### Permitted Roles
+ |
+--- | ---
+Admin |
+Admin Read-Only |
+Global Auditor |
diff --git a/docs/v3/source/includes/experimental_resources/usage_events/_header.md b/docs/v3/source/includes/experimental_resources/usage_events/_header.md
@@ -0,0 +1,8 @@
+## Usage Events
+
+Usage events are a record of changes in the usage of apps, services, and tasks.
+Examples include starting an application, scaling an application (from, say, one
+to three instances), and stopping an application.
+
+Usage events are typically used by billing and chargeback applications.
+
diff --git a/docs/v3/source/includes/experimental_resources/usage_events/_object.md.erb b/docs/v3/source/includes/experimental_resources/usage_events/_object.md.erb
@@ -0,0 +1,15 @@
+### The usage event object
+
+```
+Example Usage Event object
+```
+```json
+<%= yield_content :single_usage_event %>
+```
+
+Name | Type | Description
+---- | ---- | -----------
+**guid** | _uuid_ | Unique identifier for the event.
+**type** | _string_ | The type of the event, either "app" (application event) or "service" (service event)
+**created_at** | _datetime_ | The time with zone when the event occurred
+**updated_at** | _datetime_ | Identical to `created_at` (events are created, never updated)
diff --git a/docs/v3/source/index.md b/docs/v3/source/index.md
@@ -37,6 +37,7 @@ includes:
   - api_resources/space_quotas
   - api_resources/stacks
   - api_resources/tasks
+  - api_resources/usage_events
   - api_resources/users
   - introduction/introduction
   - concepts/concepts
@@ -351,6 +352,9 @@ includes:
   - experimental_resources/sidecars/list_for_app
   - experimental_resources/sidecars/list_for_process
   - experimental_resources/sidecars/delete
+  - experimental_resources/usage_events/header
+  - experimental_resources/usage_events/object
+  - experimental_resources/usage_events/get
   - upgrade_guide/upgrade_guide
 
 ---
diff --git a/spec/request/usage_events_spec.rb b/spec/request/usage_events_spec.rb
@@ -0,0 +1,68 @@
+require 'spec_helper'
+require 'request_spec_shared_examples'
+
+RSpec.describe 'Events' do
+  describe 'GET /v3/usage_events/:guid' do
+    let(:user) { make_user }
+    let(:admin_header) { admin_headers_for(user) }
+    let(:space) { VCAP::CloudController::Space.make }
+    let(:org) { space.organization }
+    let(:api_call) { lambda { |user_headers| get "/v3/usage_events/#{usage_event.guid}", nil, user_headers } }
+
+    context 'when the audit_event exists' do
+      let(:usage_event) {
+        VCAP::CloudController::AppUsageEvent.make
+      }
+
+      let(:usage_event_json) do
+        {
+          'guid' => usage_event.guid,
+          'created_at' => iso8601,
+          'updated_at' => iso8601,
+          'type' => 'app',
+        }
+      end
+
+      let(:expected_codes_and_responses) do
+        h = Hash.new(
+          code: 404,
+          response_object: []
+        )
+        h['admin'] = {
+          code: 200,
+          response_object: usage_event_json
+        }
+        h['admin_read_only'] = {
+          code: 200,
+          response_object: usage_event_json
+        }
+        h['global_auditor'] = {
+          code: 200,
+          response_object: usage_event_json
+        }
+        h.freeze
+      end
+
+      it_behaves_like 'permissions for single object endpoint', ALL_PERMISSIONS
+    end
+
+    context 'when the audit_event does not exist' do
+      it 'returns a 404' do
+        get '/v3/usage_events/does-not-exist', nil, admin_header
+        expect(last_response.status).to eq 404
+        expect(last_response).to have_error_message('Usage event not found')
+      end
+    end
+
+    context 'when the user is not logged in' do
+      let(:usage_event) {
+        VCAP::CloudController::AppUsageEvent.make
+      }
+
+      it 'returns 401 for Unauthenticated requests' do
+        get "/v3/usage_events/#{usage_event.guid}", nil, base_json_headers
+        expect(last_response.status).to eq(401)
+      end
+    end
+  end
+end
diff --git a/spec/unit/models/runtime/usage_event_spec.rb b/spec/unit/models/runtime/usage_event_spec.rb
@@ -0,0 +1,21 @@
+require 'spec_helper'
+
+module VCAP::CloudController
+  RSpec.describe VCAP::CloudController::UsageEvent, type: :model do
+    it { is_expected.to have_timestamp_columns }
+
+    context 'when there are usage events' do
+      let!(:app_usage_event) { AppUsageEvent.make }
+      let!(:service_usage_event) { ServiceUsageEvent.make }
+
+      it 'contains all the usage events' do
+        usage_events = VCAP::CloudController::UsageEvent.all.each_with_object({}) do |role, obj|
+          obj[role.type] = role.guid
+        end
+
+        expect(usage_events['app']).to eq app_usage_event.guid
+        expect(usage_events['service']).to eq service_usage_event.guid
+      end
+    end
+  end
+end
diff --git a/spec/unit/presenters/v3/usage_event_presenter_spec.rb b/spec/unit/presenters/v3/usage_event_presenter_spec.rb
@@ -0,0 +1,32 @@
+require 'spec_helper'
+require 'presenters/v3/usage_event_presenter'
+
+RSpec.describe VCAP::CloudController::Presenters::V3::UsageEventPresenter do
+  let(:app_usage_event) { VCAP::CloudController::AppUsageEvent.make }
+  let(:service_usage_event) { VCAP::CloudController::ServiceUsageEvent.make }
+
+  describe '#to_hash' do
+    let(:result) { described_class.new(usage_event).to_hash }
+
+    context "when it's an app usage event" do
+      let(:usage_event) { VCAP::CloudController::UsageEvent.find(guid: app_usage_event.guid) }
+
+      it 'presents the usage event' do
+        expect(result[:guid]).to eq(usage_event.guid)
+        expect(result[:created_at]).to eq(usage_event.created_at)
+        expect(result[:updated_at]).to eq(usage_event.updated_at)
+        expect(result[:type]).to eq('app')
+      end
+    end
+    context "when it's a service usage event" do
+      let(:usage_event) { VCAP::CloudController::UsageEvent.find(guid: service_usage_event.guid) }
+
+      it 'presents the usage event' do
+        expect(result[:guid]).to eq(usage_event.guid)
+        expect(result[:created_at]).to eq(usage_event.created_at)
+        expect(result[:updated_at]).to eq(usage_event.updated_at)
+        expect(result[:type]).to eq('service')
+      end
+    end
+  end
+end
