v3: Client can download droplets on the v3 API

- `GET /v3/droplets/:guid/download`
- The setup requires a valid `droplet_hash`, which is a SHA1. It's used
  to create the blobstore key.
- We use the world's smallest (29 bytes) .tgz file, and we take the SHA1
  from that.
- The temporary file must be created in `/tmp/`, otherwise the upload
  will fail.
- Download link is now in the droplet response

[finishes #169630882]

Co-authored-by: Weyman Fung <wfung@pivotal.io>
Co-authored-by: Brian Cunnie <bcunnie@pivotal.io>
Co-authored-by: Merric de Launey <mdelauney@pivotal.io>
Co-authored-by: Reid Mitchell <rmitchell@pivotal.io>
Co-authored-by: Sarah Weinstein <sweinstein@pivotal.io>

Author: 5 people

app/controllers/runtime/helpers/blob_dispatcher.rb

@@ -9,6 +9,7 @@ def send_or_redirect(guid:)
       raise CloudController::Errors::BlobNotFound unless guid
 
       blob = @blobstore.blob(guid)
+
       raise CloudController::Errors::BlobNotFound unless blob
 
       send_or_redirect_blob(blob)

app/controllers/v3/droplets_controller.rb

@@ -134,8 +134,32 @@ def upload
     render status: :accepted, json: Presenters::V3::DropletPresenter.new(droplet)
   end
 
+  def download
+    droplet = DropletModel.where(guid: hashed_params[:guid]).eager(:app, :space, space: :organization).first
+
+    droplet_not_found! unless droplet && permission_queryer.can_read_from_space?(droplet.space.guid, droplet.space.organization.guid)
+
+    unless droplet.state == DropletModel::STAGED_STATE
+      unprocessable!('Only staged droplets can be downloaded.')
+    end
+
+    VCAP::CloudController::Repositories::DropletEventRepository.record_download(
+      droplet,
+      user_audit_info,
+      droplet.app.name,
+      droplet.space.guid,
+      droplet.space.organization.guid,
+      )
+    send_droplet_blob(droplet)
+  end
+
   private
 
+  def send_droplet_blob(droplet)
+    droplet_blobstore = CloudController::DependencyLocator.instance.droplet_blobstore
+    BlobDispatcher.new(blobstore: droplet_blobstore, controller: self).send_or_redirect(guid: droplet.blobstore_key)
+  end
+
   def combine_messages(messages)
     unprocessable!("Uploaded droplet file is invalid: #{messages.join(', ')}")
   end

app/presenters/v3/droplet_presenter.rb

@@ -47,6 +47,7 @@ def build_links
           }.tap do |links|
             links[:package] = { href: url_builder.build_url(path: "/v3/packages/#{droplet.package_guid}") } if droplet.package_guid.present?
             links[:upload] = { href: url_builder.build_url(path: "/v3/droplets/#{droplet.guid}/upload"), method: 'POST' } if droplet.state == DropletModel::AWAITING_UPLOAD_STATE
+            links[:download] = { href: url_builder.build_url(path: "/v3/droplets/#{droplet.guid}/download"), experimental: true } if droplet.state == DropletModel::STAGED_STATE
           end
         end
 

config/routes.rb

@@ -103,6 +103,7 @@
   get '/packages/:package_guid/droplets', to: 'droplets#index'
   patch '/droplets/:guid', to: 'droplets#update'
   post '/droplets/:guid/upload', to: 'droplets#upload'
+  get '/droplets/:guid/download', to: 'droplets#download'
 
   # errors
   match '404', to: 'errors#not_found', via: :all

docs/v3/source/includes/api_resources/_droplets.erb

@@ -200,6 +200,10 @@
     "assign_current_droplet": {
       "href": "https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet",
       "method": "PATCH"
+      },
+    "download": {
+      "href": "https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download",
+      "experimental": true
     }
   },
   "metadata": {

docs/v3/source/includes/resources/droplets/_download_bits.md.erb

@@ -0,0 +1,36 @@
+### Download droplet bits
+
+```
+Example Request
+```
+
+```shell
+curl "https://api.example.org/v3/droplets/[guid]/download" \
+  -X GET \
+  -H "Authorization: bearer [token]" \
+```
+
+```
+Example Response
+```
+
+```http
+HTTP/1.1 302 FOUND
+Content-Type: application/json
+```
+
+Download a gzip compressed tarball file containing a Cloud Foundry compatible droplet. When using a remote blobstore, such as AWS, the response is a redirect to the actual location of the bits. If the client is automatically following redirects, then the OAuth token that was used to communicate with Cloud Controller will be relayed on the new redirect request. Some blobstores may reject the request in that case. Clients may need to follow the redirect without including the OAuth token.
+
+#### Definition
+`POST /v3/droplets/:guid/download`
+
+#### Permitted roles
+ |
+--- | ---
+Admin |
+Admin Read-Only |
+Global Auditor |
+Org Manager |
+Space Auditor |
+Space Developer |
+Space Manager |

docs/v3/source/index.md

@@ -123,6 +123,7 @@ includes:
   - resources/droplets/update
   - resources/droplets/delete
   - resources/droplets/copy
+  - resources/droplets/download_bits
   - resources/droplets/upload_bits
   - resources/environment_variable_groups/header
   - resources/environment_variable_groups/object

spec/request/apps_spec.rb

@@ -2223,6 +2223,7 @@
             'self' => { 'href' => "#{link_prefix}/v3/droplets/#{guid}" },
             'package' => { 'href' => "#{link_prefix}/v3/packages/#{package_model.guid}" },
             'app' => { 'href' => "#{link_prefix}/v3/apps/#{app_guid}" },
+            'download' => { 'href' => "#{link_prefix}/v3/droplets/#{guid}/download", 'experimental' => true },
             'assign_current_droplet' => { 'href' => "#{link_prefix}/v3/apps/#{app_guid}/relationships/current_droplet",
                                           'method' => 'PATCH' },
         },

spec/request/droplets_spec.rb

@@ -11,6 +11,10 @@
   let(:developer_headers) { headers_for(developer, user_name: user_name) }
   let(:user_name) { 'sundance kid' }
 
+  let(:guid) { droplet_model.guid }
+  let(:package_model) { VCAP::CloudController::PackageModel.make(app_guid: app_model.guid) }
+  let(:app_guid) { droplet_model.app_guid }
+
   let(:parsed_response) { MultiJson.load(last_response.body) }
 
   describe 'POST /v3/droplets' do
@@ -189,10 +193,6 @@
   end
 
   describe 'GET /v3/droplets/:guid' do
-    let(:guid) { droplet_model.guid }
-    let(:package_model) { VCAP::CloudController::PackageModel.make(app_guid: app_model.guid) }
-    let(:app_guid) { droplet_model.app_guid }
-
     context 'when the droplet has a buildpack lifecycle' do
       let!(:droplet_model) do
         VCAP::CloudController::DropletModel.make(
@@ -239,6 +239,7 @@
             'self' => { 'href' => "#{link_prefix}/v3/droplets/#{guid}" },
             'package' => { 'href' => "#{link_prefix}/v3/packages/#{package_model.guid}" },
             'app' => { 'href' => "#{link_prefix}/v3/apps/#{app_guid}" },
+            'download' => { 'href' => "#{link_prefix}/v3/droplets/#{guid}/download", 'experimental' => true },
             'assign_current_droplet' => { 'href' => "#{link_prefix}/v3/apps/#{app_guid}/relationships/current_droplet", 'method' => 'PATCH' },
           },
           'metadata' => {
@@ -304,6 +305,7 @@
             'self' => { 'href' => "#{link_prefix}/v3/droplets/#{guid}" },
             'package' => { 'href' => "#{link_prefix}/v3/packages/#{package_model.guid}" },
             'app' => { 'href' => "#{link_prefix}/v3/apps/#{app_guid}" },
+            'download' => { 'href' => "#{link_prefix}/v3/droplets/#{guid}/download", 'experimental' => true },
             'assign_current_droplet' => { 'href' => "#{link_prefix}/v3/apps/#{app_guid}/relationships/current_droplet", 'method' => 'PATCH' },
           },
           'metadata' => {
@@ -315,6 +317,98 @@
     end
   end
 
+  describe 'GET /v3/droplets/:guid/download' do
+    let(:worlds_smallest_tgz_file) { "\x1f\x8b\x08\x00\x5e\xc2\xc6\x5e\x00\x03\x63\x60\x18\x05\xa3\x60\x14\x8c\x54\x00\x00\x2e\xaf\xb5\xef\x00\x04\x00\x00" }
+    let!(:droplet_model) do
+      VCAP::CloudController::DropletModel.make(
+        state: VCAP::CloudController::DropletModel::AWAITING_UPLOAD_STATE,
+        app_guid: app_model.guid,
+        package_guid: package_model.guid,
+        buildpack_receipt_buildpack: 'http://buildpack.git.url.com',
+        error_description: 'example error',
+        execution_metadata: 'some-data',
+        droplet_hash: Digest::SHA1.hexdigest(worlds_smallest_tgz_file),
+        sha256_checksum: 'some-sha-256',
+        process_types: { 'web' => 'start-command' },
+      )
+    end
+
+    let(:droplet_file) do
+      File.join(Dir.mktmpdir(nil, '/tmp'), 'droplet.tgz')
+    end
+    let(:upload_body) do
+      {
+        bits_name: 'droplet.tgz',
+        bits_path: droplet_file,
+      }
+    end
+    let(:bits_download_url) { CloudController::DependencyLocator.instance.blobstore_url_generator.droplet_download_url(droplet_model) }
+
+    context 'when the droplet is uploaded' do
+      let(:api_call) { lambda { |user_headers| get "/v3/droplets/#{guid}/download", nil, user_headers } }
+      let(:expected_codes_and_responses) do
+        h = Hash.new(
+          code: 302
+        )
+        h['org_auditor'] = {
+          code: 404
+        }
+        h['org_billing_manager'] = {
+          code: 404
+        }
+        h['no_role'] = {
+          code: 404
+        }
+        h.freeze
+      end
+
+      before do
+        File.write(droplet_file, worlds_smallest_tgz_file)
+        post "/v3/droplets/#{guid}/upload", upload_body.to_json, developer_headers
+        expect(last_response).to have_status_code(202)
+        successes, failures = Delayed::Worker.new.work_off
+        expect(successes).to eq(1)
+        expect(failures).to eq(0)
+      end
+
+      it_behaves_like 'permissions for single object endpoint', ALL_PERMISSIONS
+
+      it 'downloads the bit(s) for a droplet' do
+        get "/v3/droplets/#{guid}/download", nil, developer_headers
+
+        expect(last_response.status).to eq(302)
+        expect(last_response.headers['Location']).to eq(bits_download_url)
+
+        expected_metadata = { droplet_guid: droplet_model.guid }.to_json
+
+        event = VCAP::CloudController::Event.last
+        expect(event.values).to include({
+          type: 'audit.app.droplet.download',
+          actor_username: user_name,
+          metadata: expected_metadata,
+          space_guid: space.guid,
+          organization_guid: space.organization.guid
+        })
+      end
+    end
+
+    context 'when the droplet cannot be found' do
+      it 'returns 404 for the droplet' do
+        get '/v3/droplets/some-bogus-guid/download', nil, developer_headers
+        expect(last_response.status).to eq(404)
+        expect(last_response.body).to include('Droplet not found')
+      end
+    end
+
+    context "when the droplet hasn't finished uploading/processing" do
+      it 'returns a 422 with a helpful error message' do
+        get "/v3/droplets/#{guid}/download", nil, developer_headers
+        expect(last_response.status).to eq(422)
+        expect(last_response.body).to include('Only staged droplets can be downloaded.')
+      end
+    end
+  end
+
   describe 'GET /v3/droplets' do
     let(:buildpack) { VCAP::CloudController::Buildpack.make }
     let(:package_model) do
@@ -449,6 +543,7 @@
               'self' => { 'href' => "#{link_prefix}/v3/droplets/#{droplet2.guid}" },
               'package' => { 'href' => "#{link_prefix}/v3/packages/#{package_model.guid}" },
               'app' => { 'href' => "#{link_prefix}/v3/apps/#{app_model.guid}" },
+              'download' => { 'href' => "#{link_prefix}/v3/droplets/#{droplet2.guid}/download", 'experimental' => true },
               'assign_current_droplet' => { 'href' => "#{link_prefix}/v3/apps/#{app_model.guid}/relationships/current_droplet", 'method' => 'PATCH' },
             },
             'metadata' => {
@@ -845,6 +940,7 @@
               'self' => { 'href' => "#{link_prefix}/v3/droplets/#{droplet2.guid}" },
               'package' => { 'href' => "#{link_prefix}/v3/packages/#{package_model.guid}" },
               'app' => { 'href' => "#{link_prefix}/v3/apps/#{app_model.guid}" },
+              'download' => { 'href' => "#{link_prefix}/v3/droplets/#{droplet2.guid}/download", 'experimental' => true },
               'assign_current_droplet' => { 'href' => "#{link_prefix}/v3/apps/#{app_model.guid}/relationships/current_droplet", 'method' => 'PATCH' },
             },
             'metadata' => {
@@ -1032,6 +1128,7 @@
               'self' => { 'href' => "#{link_prefix}/v3/droplets/#{droplet2.guid}" },
               'package' => { 'href' => "#{link_prefix}/v3/packages/#{package_model.guid}" },
               'app' => { 'href' => "#{link_prefix}/v3/apps/#{app_model.guid}" },
+              'download' => { 'href' => "#{link_prefix}/v3/droplets/#{droplet2.guid}/download", 'experimental' => true },
               'assign_current_droplet' => { 'href' => "#{link_prefix}/v3/apps/#{app_model.guid}/relationships/current_droplet", 'method' => 'PATCH' },
             },
             'metadata' => {

spec/unit/presenters/v3/droplet_presenter_spec.rb

@@ -37,6 +37,7 @@ module VCAP::CloudController::Presenters::V3
             self: { href: "#{link_prefix}/v3/droplets/#{droplet.guid}" },
             package: { href: "#{link_prefix}/v3/packages/#{droplet.package_guid}" },
             app: { href: "#{link_prefix}/v3/apps/#{droplet.app_guid}" },
+            download: { href: "#{link_prefix}/v3/droplets/#{droplet.guid}/download", experimental: true },
             assign_current_droplet: { href: "#{link_prefix}/v3/apps/#{droplet.app_guid}/relationships/current_droplet", method: 'PATCH' }
           }
 
@@ -169,6 +170,7 @@ module VCAP::CloudController::Presenters::V3
             self: { href: "#{link_prefix}/v3/droplets/#{droplet.guid}" },
             package: { href: "#{link_prefix}/v3/packages/#{droplet.package_guid}" },
             app: { href: "#{link_prefix}/v3/apps/#{droplet.app_guid}" },
+            download: { href: "#{link_prefix}/v3/droplets/#{droplet.guid}/download", experimental: true },
             assign_current_droplet: { href: "#{link_prefix}/v3/apps/#{droplet.app_guid}/relationships/current_droplet", method: 'PATCH' }
           }
 
@@ -282,6 +284,28 @@ module VCAP::CloudController::Presenters::V3
           expect(result[:links]).to eq(links)
         end
       end
+      context 'when the droplet is STAGED' do
+        before do
+          droplet.state = VCAP::CloudController::DropletModel::STAGED_STATE
+          droplet.save
+        end
+
+        it 'adds the upload link' do
+          links = {
+            self: { href: "#{link_prefix}/v3/droplets/#{droplet.guid}" },
+            package: { href: "#{link_prefix}/v3/packages/#{droplet.package_guid}" },
+            app: { href: "#{link_prefix}/v3/apps/#{droplet.app_guid}" },
+            assign_current_droplet: { href: "#{link_prefix}/v3/apps/#{droplet.app_guid}/relationships/current_droplet", method: 'PATCH' },
+            download: { href: "#{link_prefix}/v3/droplets/#{droplet.guid}/download", experimental: true }
+          }
+
+          expect(result[:guid]).to eq(droplet.guid)
+          expect(result[:state]).to eq('STAGED')
+          expect(result[:created_at]).to be_a(Time)
+          expect(result[:updated_at]).to be_a(Time)
+          expect(result[:links]).to eq(links)
+        end
+      end
     end
   end
 end