add storage samples

google-cloud-storage/Rakefile

@@ -125,6 +125,40 @@ namespace :acceptance do
   end
 end
 
+task :samples do
+  Rake::Task["samples:latest"].invoke
+end
+
+namespace :samples do
+  task :latest do
+    if File.directory? "samples"
+      Dir.chdir "samples" do
+        Bundler.with_clean_env do
+          ENV["GOOGLE_CLOUD_SAMPLES_TEST"] = "not_master"
+          sh "bundle update"
+          sh "bundle exec rake test"
+        end
+      end
+    else
+      puts "The google-cloud-language gem has no samples to test."
+    end
+  end
+
+  task :master do
+    if File.directory? "samples"
+      Dir.chdir "samples" do
+        Bundler.with_clean_env do
+          ENV["GOOGLE_CLOUD_SAMPLES_TEST"] = "master"
+          sh "bundle update"
+          sh "bundle exec rake test"
+        end
+      end
+    else
+      puts "The google-cloud-language gem has no samples to test."
+    end
+  end
+end
+
 desc "Run yard-doctest example tests."
 task :doctest do
   sh "bundle exec yard config load_plugins true && bundle exec yard doctest"

google-cloud-storage/samples/Gemfile

@@ -0,0 +1,35 @@
+# Copyright 2020 Google, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# [START storage_dependencies]
+source "https://rubygems.org"
+
+# [END storage_dependencies]
+
+if ENV["GOOGLE_CLOUD_SAMPLES_TEST"] == "master"
+  gem "google-cloud-kms", group: :test, path: "../../google-cloud-kms"
+  gem "google-cloud-storage", path: "../../google-cloud-storage"
+else
+  # rubocop:disable Bundler/DuplicatedGem
+  gem "google-cloud-kms", group: :test
+  # [START storage_dependencies]
+  gem "google-cloud-storage"
+  # [END storage_dependencies]
+  # rubocop:enable Bundler/DuplicatedGem
+end
+
+group :test do
+  gem "minitest", "~> 5.13"
+  gem "rake"
+end

google-cloud-storage/samples/README.md

@@ -0,0 +1,149 @@
+<img src="https://avatars2.githubusercontent.com/u/2810941?v=3&s=96" alt="Google Cloud Platform logo" title="Google Cloud Platform" align="right" height="96" width="96"/>
+
+# Google Cloud Storage Ruby Samples
+
+[Cloud Storage][storage_docs] allows world-wide storage and retrieval of any
+amount of data at any time.
+
+[storage_docs]: https://cloud.google.com/storage/docs/
+
+## Run sample
+
+To run the sample, first install dependencies:
+
+    bundle install
+
+Run the sample:
+
+    bundle exec ruby buckets.rb
+    bundle exec ruby files.rb
+    bundle exec ruby acls.rb
+
+## Samples
+
+### Buckets
+
+**Usage:** `bundle exec ruby buckets.rb [command] [arguments]`
+
+```
+Usage: bundle exec ruby buckets.rb [command] [arguments]
+
+Commands:
+  list                                                                 List all buckets in the authenticated project
+  enable_requester_pays               <bucket>                            Enable requester pays for a bucket
+  disable_requester_pays              <bucket>                            Disable requester pays for a bucket
+  check_requester_pays                <bucket>                            Check status of requester pays for a bucket
+  enable_default_kms_key              <bucket> <kms_key>                  Enable default KMS encryption for bucket
+  create                              <bucket>                            Create a new bucket with default storage class and location
+  create                              <bucket> <location> <storage_class> Create a new bucket with specific storage class and location
+  list_bucket_labels                  <bucket>                            List bucket labels
+  add_bucket_label                    <bucket> <label_key> <label_value>  Add bucket label
+  delete_bucket_label                 <bucket> <label_key>                Delete bucket label
+  delete                              <bucket>                            Delete bucket with the provided name
+  set_retention_policy                <bucket> <retention_period>         Set a retention policy on bucket with a retention period determined in seconds
+  remove_retention_policy             <bucket>                            Remove a retention policy from a bucket if policy is not locked
+  lock_retention_policy               <bucket>                            Lock retention policy
+  get_retention_policy                <bucket>                            Get retention policy for a bucket
+  enable_default_event_based_hold     <bucket>                            Enable event-based hold for a bucket
+  disable_default_event_based_hold    <bucket>                            Disable event-based hold for a bucket
+  get_default_event_based_hold        <bucket>                            Get state of event-based hold for a bucket
+  enable_uniform_bucket_level_access  <bucket>                            Enable uniform bucket-level access for a bucket
+  disable_uniform_bucket_level_access <bucket>                            Disable uniform bucket-level access for a bucket
+  get_uniform_bucket_level_access     <bucket>                            Get uniform bucket-level access for a bucket
+
+Environment variables:
+  GOOGLE_CLOUD_PROJECT must be set to your Google Cloud project ID
+```
+
+### Files
+
+**Usage:** `bundle exec ruby files.rb [command] [arguments]`
+
+```
+Usage: bundle exec ruby files.rb [command] [arguments]
+
+Commands:
+  list                 <bucket>                                     List all files in the bucket
+  upload               <bucket> <file> <dest_path>                  Upload local file to a bucket
+  encrypted_upload     <bucket> <file> <dest_path> <encryption_key> Upload local file as an encrypted file to a bucket
+  kms_upload           <bucket> <file> <dest_path> <kms_key>        Upload local file and encrypt service side using a KMS key
+  download             <bucket> <file> <path>                       Download a file from a bucket
+  download_public_file <bucket> <file> <path>                       Download a publically accessible file from a bucket
+  encrypted_download <bucket> <file> <path> <encryption_key>        Download an encrypted file from a bucket
+  download_with_requester_pays <project> <bucket> <file> <path>     Download a file from a requester pays enabled bucket
+  rotate_encryption_key <bucket> <file> <base64_current_encryption_key> <base64_new_encryption_key> Update encryption key of an encrypted file.
+  generate_encryption_key                                           Generate a sample encryption key
+  delete       <bucket> <file>                                      Delete a file from a bucket
+  metadata     <bucket> <file>                                      Display metadata for a file in a bucket
+  make_public  <bucket> <file>                                      Make a file in a bucket public
+  rename       <bucket> <file> <new>                                Rename a file in a bucket
+  copy <srcBucket> <srcFile> <destBucket> <destFile>                Copy file to other bucket
+  generate_signed_url <bucket> <file>                               Generate a signed url for a file
+  set_event_based_hold     <bucket> <file>                          Set an event-based hold on a file
+  release_event_based_hold <bucket> <file>                          Relase an event-based hold on a file
+  set_temporary_hold       <bucket> <file>                          Set a temporary hold on a file
+  release_temporary_hold   <bucket> <file>                          Release a temporary hold on a file
+
+Environment variables:
+  GOOGLE_CLOUD_PROJECT must be set to your Google Cloud project ID
+```
+
+### Access Control List
+
+**Usage:** `bundle exec ruby acls.rb [command] [arguments]`
+
+```
+Usage: bundle exec ruby acls.rb [command] [arguments]
+
+Commands:
+  print_bucket_acl <bucket>                  Print bucket Access Control List
+  print_bucket_acl_for_user <bucket> <email> Print bucket ACL for an email
+  add_bucket_owner <bucket> <email>          Add a new OWNER to a bucket
+  remove_bucket_acl <bucket> <email>         Remove an entity from a bucket ACL
+  add_bucket_default_owner <bucket> <email>  Add a default OWNER for a bucket
+  remove_bucket_default_acl <bucket> <email> Remove an entity from default bucket ACL
+  print_file_acl <bucket> <file>             Print file ACL
+  print_file_acl_for_user <bucket> <file> <email> Print file ACL for an email
+  add_file_owner <bucket> <file> <email>          Add an OWNER to a file
+  remove_file_acl <bucket> <file> <email>         Remove an entity from a file ACL
+
+Environment variables:
+  GOOGLE_CLOUD_PROJECT must be set to your Google Cloud project ID
+```
+
+### Cloud Storage Bucket-level Identity & Access Management
+
+**Usage:** `bundle exec ruby iam.rb [command] [arguments]`
+
+```
+Usage: bundle exec ruby iam.rb [command] [arguments]
+
+Commands:
+  view_bucket_iam_members  <bucket>                                                                                View bucket-level IAM members
+  add_bucket_iam_member    <bucket> <iam_role> <iam_member>                                                        Add a bucket-level IAM member
+  add_bucket_conditional_iam_binding <bucket> <iam_role> <iam_member> <cond_title> <cond_description> <cond_expr>  Add a conditional bucket-level binding
+  remove_bucket_iam_member <bucket> <iam_role> <iam_member>                                                        Remove a bucket-level IAM member
+  remove_bucket_conditional_iam_binding <bucket> <iam_member> <cond_title> <cond_description> <cond_expr>          Remove a conditional bucket-level binding
+
+Environment variables:
+  GOOGLE_CLOUD_PROJECT must be set to your Google Cloud project ID
+```
+
+### Cloud Storage Service Account HMAC Key Management
+
+**Usage:** `bundle exec ruby hmac.rb [commmand] [arguments]`
+
+```
+Usage: bundle exec ruby hmac.rb [command] [arguments]
+
+Commands:
+  list_hmac_keys                               List all HMAC keys for a project
+  create_hmac_key     <serviceAccountEmail>    Create HMAC Key
+  get_hmac_key        <accessId>               Get HMAC Key metadata
+  activate_hmac_key   <accessId>               Activate an HMAC Key
+  deactivate_hmac_key <accessId>               Deactivate an HMAC Key
+  delete_hmac_key     <accessId>               Delete a deactivated HMAC key
+
+Environment variables:
+  GOOGLE_CLOUD_PROJECT must be set to your Google Cloud project ID
+```

google-cloud-storage/samples/Rakefile

@@ -0,0 +1,6 @@
+require "rake/testtask"
+
+Rake::TestTask.new "test" do |t|
+  t.test_files = FileList["**/*_test.rb"]
+  t.warning = false
+end

google-cloud-storage/samples/acceptance/acls_test.rb

@@ -0,0 +1,165 @@
+# Copyright 2020 Google, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative "helper"
+require_relative "../acls.rb"
+
+describe "ACL Snippets" do
+  parallelize_me!
+
+  let :bucket do
+    create_bucket_helper "ruby_storage_sample_#{SecureRandom.hex}"
+  end
+
+  let(:storage_client)   { Google::Cloud::Storage.new }
+  let(:local_file)       { File.expand_path "data/file.txt", __dir__ }
+  let(:email)            { "user-test@test.com" }
+  let(:remote_file_name) { "path/file_name.txt" }
+
+  after do
+    delete_bucket_helper bucket.name
+  end
+
+  describe "print_bucket_acl" do
+    it "prints a bucket's acl" do
+      bucket.acl.add_owner email
+
+      out, _err = capture_io do
+        print_bucket_acl bucket_name: bucket.name
+      end
+
+      assert_includes out, "ACL for #{bucket.name}:"
+      assert_includes out, "OWNER #{email}"
+    end
+  end
+
+  describe "print_bucket_acl_for_user" do
+    it "prints a bucket's acl for a user" do
+      bucket.acl.add_owner email
+
+      expected_output = <<~OUTPUT
+        Permissions for #{email}:
+        OWNER
+      OUTPUT
+
+      assert_output expected_output do
+        print_bucket_acl_for_user bucket_name: bucket.name,
+                                  email:       email
+      end
+    end
+  end
+
+  describe "add_bucket_owner" do
+    it "adds owner permissions to a user for a bucket" do
+      assert_output "Added OWNER permission for #{email} to #{bucket.name}\n" do
+        add_bucket_owner bucket_name: bucket.name,
+                         email:       email
+      end
+      assert_includes bucket.acl.owners, email
+    end
+  end
+
+  describe "remove_bucket_acl" do
+    it "removes a user from a bucket's acl" do
+      bucket.acl.add_owner email
+      assert_output "Removed ACL permissions for #{email} from #{bucket.name}\n" do
+        remove_bucket_acl bucket_name: bucket.name,
+                          email:       email
+      end
+      refute_includes bucket.acl.owners, email
+    end
+  end
+
+  describe "add_bucket_default_owner" do
+    it "adds a user as default owner for a bucket" do
+      assert_output "Added default OWNER permission for #{email} to #{bucket.name}\n" do
+        add_bucket_default_owner bucket_name: bucket.name,
+                                 email:       email
+      end
+      assert_includes bucket.default_acl.owners, email
+    end
+  end
+
+  describe "remove_bucket_default_acl" do
+    it "adds a user as default owner for a bucket" do
+      bucket.default_acl.add_owner email
+      assert_output "Removed default ACL permissions for #{email} from #{bucket.name}\n" do
+        remove_bucket_default_acl bucket_name: bucket.name,
+                                  email:       email
+      end
+      refute_includes bucket.default_acl.owners, email
+    end
+  end
+
+  describe "print_file_acl" do
+    it "prints the acl for a file in a bucket" do
+      bucket.create_file local_file, remote_file_name
+      owners  = bucket.file(remote_file_name).acl.owners
+      readers = bucket.file(remote_file_name).acl.readers
+
+      out, _err = capture_io do
+        print_file_acl bucket_name: bucket.name,
+                       file_name:   remote_file_name
+      end
+
+      assert owners.all? do |owner|
+        out.includes? "OWNER #{owner}"
+      end
+
+      assert readers.all? do |reader|
+        out.includes? "READER #{reader}"
+      end
+    end
+  end
+
+  describe "print_file_acl_for_user" do
+    it "prints the permissions of a given user for a file in a bucket" do
+      bucket.create_file local_file, remote_file_name
+      bucket.file(remote_file_name).acl.add_owner email
+
+      assert_output "Permissions for #{email}:\nOWNER\n" do
+        print_file_acl_for_user bucket_name: bucket.name,
+                                file_name:   remote_file_name,
+                                email:       email
+      end
+    end
+  end
+
+  describe "add_file_owner" do
+    it "adds a user as an owner of for a file in a bucket" do
+      bucket.create_file local_file, remote_file_name
+
+      assert_output "Added OWNER permission for #{email} to #{remote_file_name}\n" do
+        add_file_owner bucket_name: bucket.name,
+                       file_name:   remote_file_name,
+                       email:       email
+      end
+      assert_includes bucket.file(remote_file_name).acl.owners, email
+    end
+  end
+
+  describe "remove_file_acl" do
+    it "removes a user from the acl for file in a bucket" do
+      bucket.create_file local_file, remote_file_name
+      bucket.file(remote_file_name).acl.add_owner email
+
+      assert_output "Removed ACL permissions for #{email} from #{remote_file_name}\n" do
+        remove_file_acl bucket_name: bucket.name,
+                        file_name:   remote_file_name,
+                        email:       email
+      end
+      refute_includes bucket.file(remote_file_name).acl.owners, email
+    end
+  end
+end