google-cloud-storage 1.14.0 → 1.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9f89f223328cb434f1b1f27c38475d5608f83be9b7adb358aa65691d90933ea
-  data.tar.gz: be494fa2f05dd9c00e4d4b0059ca3d654019703f5fadc844b8d3e203163b1e82
+  metadata.gz: 349f612cd2d7620e74e3488ba4da57918288ca32328ed0e7be988c3848ec39ff
+  data.tar.gz: 14a9285c48557ca8f71909c63e049c9427581f1340cad9fc685b2ef473d84d13
 SHA512:
-  metadata.gz: d1d7fcfa4de5d70f6dcfd72067cda51a44bbdc74358f54e1a52658965b34b2a6ac15e32c2226fafdf72ccc7f447edecb395f45a50c00c154bb87413aacdbe5a7
-  data.tar.gz: 2d06a35d929cdf7b7909a2407a3cb7886a604e58c58461b427a92c703f1241848df9605810ba957358552ab9069c033d2b14b9b9de27aa4f2814868d5d44ba61
+  metadata.gz: 0a3de34c94ffdd04627638f46fb1f5076e128967982114fdd33b5232aa2375f53c4916b95df972a803af5c2d2ecdf235a4306a5c94398911e19fac6d56018936
+  data.tar.gz: 64c0cf9b35db7084e931fc4779bf7eec1fc159b77a7eee27b2f9d92e30c61c683def31766e419544de1c04512771b5a74da0f624951a0e96c17d726961285e82

data/AUTHENTICATION.md

@@ -0,0 +1,178 @@
+# Authentication
+
+In general, the google-cloud-storage library uses [Service
+Account](https://cloud.google.com/iam/docs/creating-managing-service-accounts)
+credentials to connect to Google Cloud services. When running on Compute Engine
+the credentials will be discovered automatically. When running on other
+environments, the Service Account credentials can be specified by providing the
+path to the [JSON
+keyfile](https://cloud.google.com/iam/docs/managing-service-account-keys) for
+the account (or the JSON itself) in environment variables. Additionally, Cloud
+SDK credentials can also be discovered automatically, but this is only
+recommended during development.
+
+## Project and Credential Lookup
+
+The google-cloud-storage library aims to make authentication as simple as
+possible, and provides several mechanisms to configure your system without
+providing **Project ID** and **Service Account Credentials** directly in code.
+
+**Project ID** is discovered in the following order:
+
+1. Specify project ID in method arguments
+2. Specify project ID in configuration
+3. Discover project ID in environment variables
+4. Discover GCE project ID
+
+**Credentials** are discovered in the following order:
+
+1. Specify credentials in method arguments
+2. Specify credentials in configuration
+3. Discover credentials path in environment variables
+4. Discover credentials JSON in environment variables
+5. Discover credentials file in the Cloud SDK's path
+6. Discover GCE credentials
+
+### Google Cloud Platform environments
+
+While running on Google Cloud Platform environments such as Google Compute
+Engine, Google App Engine and Google Kubernetes Engine, no extra work is needed.
+The **Project ID** and **Credentials** and are discovered automatically. Code
+should be written as if already authenticated. Just be sure when you [set up the
+GCE instance][gce-how-to], you add the correct scopes for the APIs you want to
+access. For example:
+
+  * **All APIs**
+    * `https://www.googleapis.com/auth/cloud-platform`
+    * `https://www.googleapis.com/auth/cloud-platform.read-only`
+  * **BigQuery**
+    * `https://www.googleapis.com/auth/bigquery`
+    * `https://www.googleapis.com/auth/bigquery.insertdata`
+  * **Compute Engine**
+    * `https://www.googleapis.com/auth/compute`
+  * **Datastore**
+    * `https://www.googleapis.com/auth/datastore`
+    * `https://www.googleapis.com/auth/userinfo.email`
+  * **DNS**
+    * `https://www.googleapis.com/auth/ndev.clouddns.readwrite`
+  * **Pub/Sub**
+    * `https://www.googleapis.com/auth/pubsub`
+  * **Storage**
+    * `https://www.googleapis.com/auth/devstorage.full_control`
+    * `https://www.googleapis.com/auth/devstorage.read_only`
+    * `https://www.googleapis.com/auth/devstorage.read_write`
+
+### Environment Variables
+
+The **Project ID** and **Credentials JSON** can be placed in environment
+variables instead of declaring them directly in code. Each service has its own
+environment variable, allowing for different service accounts to be used for
+different services. (See the READMEs for the individual service gems for
+details.) The path to the **Credentials JSON** file can be stored in the
+environment variable, or the **Credentials JSON** itself can be stored for
+environments such as Docker containers where writing files is difficult or not
+encouraged.
+
+The environment variables that Storage checks for project ID are:
+
+1. `STORAGE_PROJECT`
+2. `GOOGLE_CLOUD_PROJECT`
+
+The environment variables that Storage checks for credentials are configured on {Google::Cloud::Storage::Credentials}:
+
+1. `STORAGE_CREDENTIALS` - Path to JSON file, or JSON contents
+2. `STORAGE_KEYFILE` - Path to JSON file, or JSON contents
+3. `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents
+4. `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents
+5. `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file
+
+```ruby
+require "google/cloud/storage"
+
+ENV["STORAGE_PROJECT"]     = "my-project-id"
+ENV["STORAGE_CREDENTIALS"] = "path/to/keyfile.json"
+
+storage = Google::Cloud::Storage.new
+```
+
+### Configuration
+
+The **Project ID** and **Credentials JSON** can be configured instead of placing them in environment variables or providing them as arguments.
+
+```ruby
+require "google/cloud/storage"
+
+Google::Cloud::Storage.configure do |config|
+  config.project_id  = "my-project-id"
+  config.credentials = "path/to/keyfile.json"
+end
+
+storage = Google::Cloud::Storage.new
+```
+
+### Cloud SDK
+
+This option allows for an easy way to authenticate during development. If
+credentials are not provided in code or in environment variables, then Cloud SDK
+credentials are discovered.
+
+To configure your system for this, simply:
+
+1. [Download and install the Cloud SDK](https://cloud.google.com/sdk)
+2. Authenticate using OAuth 2.0 `$ gcloud auth login`
+3. Write code as if already authenticated.
+
+**NOTE:** This is _not_ recommended for running in production. The Cloud SDK
+*should* only be used during development.
+
+[gce-how-to]: https://cloud.google.com/compute/docs/authentication#using
+[dev-console]: https://console.cloud.google.com/project
+
+[enable-apis]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/enable-apis.png
+
+[create-new-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account.png
+[create-new-service-account-existing-keys]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account-existing-keys.png
+[reuse-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/reuse-service-account.png
+
+## Creating a Service Account
+
+Google Cloud requires a **Project ID** and **Service Account Credentials** to
+connect to the APIs. You will use the **Project ID** and **JSON key file** to
+connect to most services with google-cloud-storage.
+
+If you are not running this client on Google Compute Engine, you need a Google
+Developers service account.
+
+1. Visit the [Google Developers Console][dev-console].
+1. Create a new project or click on an existing project.
+1. Activate the slide-out navigation tray and select **API Manager**. From
+   here, you will enable the APIs that your application requires.
+
+   ![Enable the APIs that your application requires][enable-apis]
+
+   *Note: You may need to enable billing in order to use these services.*
+
+1. Select **Credentials** from the side navigation.
+
+   You should see a screen like one of the following.
+
+   ![Create a new service account][create-new-service-account]
+
+   ![Create a new service account With Existing Keys][create-new-service-account-existing-keys]
+
+   Find the "Add credentials" drop down and select "Service account" to be
+   guided through downloading a new JSON key file.
+
+   If you want to re-use an existing service account, you can easily generate a
+   new key file. Just select the account you wish to re-use, and click "Generate
+   new JSON key":
+
+   ![Re-use an existing service account][reuse-service-account]
+
+   The key file you download will be used by this library to authenticate API
+   requests and should be stored in a secure location.
+
+## Troubleshooting
+
+If you're having trouble authenticating you can ask for help by following the
+{file:TROUBLESHOOTING.md Troubleshooting Guide}.

data/CHANGELOG.md

@@ -0,0 +1,167 @@
+# Release History
+
+### 1.14.1 / 2018-09-12
+
+* Add missing documentation files to package.
+
+### 1.14.0 / 2018-09-10
+
+* Add Object Lifecycle Management:
+  * Add Bucket#lifecycle.
+  * Add Bucket::Lifecycle and Bucket::Lifecycle::Rule.
+* Update documentation.
+
+### 1.13.1 / 2018-08-21
+
+* Update documentation.
+
+### 1.13.0 / 2018-06-22
+
+* Update Policy, protect from role duplication.
+* Updated dependencies.
+
+### 1.12.0 / 2018-05-09
+
+* Support Cloud KMS keys / Customer-managed encryption keys (CMEK).
+
+### 1.11.0 / 2018-05-01
+
+* Support partial Storage::File downloads. (georgeclaghorn)
+* Add File#rewrite.
+  * Similar to File#copy, except for being able to specify both source and destination encryption keys.
+  * Refactor both File#copy and File#rotate to call File#rewrite.
+* Update documentation for File-like IO parameters. The underlying libraries call #size on the argument, which is not present on IO, but is present on File and StringIO.
+
+### 1.10.0 / 2018-02-27
+
+* Support Shared Configuration.
+* Fix verification for gzipped files.
+  * Add skip_decompress to File#download
+  * Update documentation and examples for gzip-encoded files.
+* Fix issue with IAM Policy not refreshing properly.
+* Update Google API Client dependency.
+* Update authentication documentation
+
+### 1.9.0 / 2017-11-20
+
+* Add `Google::Cloud::Storage.anonymous` to support public data access.
+
+### 1.8.0 / 2017-11-14
+
+* Add `Google::Cloud::Storage::Credentials` class.
+* Rename constructor arguments to `project_id` and `credentials`.
+  (The previous arguments `project` and `keyfile` are still supported.)
+* Document `Google::Auth::Credentials` as `credentials` value.
+* Updated `google-api-client`, `googleauth` dependencies.
+
+### 1.7.1 / 2017-10-24
+
+* Fix bug in Bucket#create_file, Bucket#compose, File#copy and File#rotate in
+  which user_project was not set on returned File object.
+* Fix bug in Bucket::Acl#add_reader and Bucket::Acl#add_owner in which
+  user_project was not passed in the API request.
+
+### 1.7.0 / 2017-10-18
+
+* Add `Bucket#compose`.
+* Update documentation.
+
+### 1.6.0 / 2017-09-28
+
+* Add `user_project` option to `Project#buckets` and `Project#create_bucket`.
+* Upgrade to Google API Client 0.14.2.
+* Update documentation.
+
+### 1.5.0 / 2017-09-26
+
+* Add Pub/Sub notification subscriptions.
+* Update `#signed_url` to support symbols (dimroc).
+
+### 1.4.0 / 2017-08-02
+
+* Add `skip_lookup` option for retrieving `Bucket` and `File` objects
+  without accessing the Storage API
+  * Add `Bucket#exists?` method
+  * Add `File#exists?` method
+* Add `File#generations` method
+  * Add `generation` argument to `File#delete`
+  * Add `generation` argument to `File#reload!`
+* Add `Bucket#storage_class=` method
+* Fix for when the `user_project` value set on a `Bucket` was not being
+  properly set on all `File` objects returned by `Bucket`.
+* Fix to use `user_project` value when reloading a `Bucket`.
+
+### 1.3.0 / 2017-07-11
+
+* Add `query` parameter to `#signed_url` methods (georgeclaghorn).
+
+### 1.2.0 / 2017-06-27
+
+* Add Requester Pays support.
+* Upgrade dependency on Google API Client.
+
+### 1.1.0 / 2017-06-01
+
+* Add Bucket#labels.
+* Update gem spec homepage links.
+* Remove memoization of Policy.
+* Deprecate force parameter in Bucket#policy. (Will be removed in a future version.)
+* Deprecate Policy#deep_dup. (Will be removed in a future version.)
+
+
+### 1.0.1 / 2017-04-10
+
+* Add Bucket IAM support
+
+### 1.0.0 / 2017-04-05
+
+* Release 1.0
+* Improvements to File copy for large files
+* Allow file attributes to be changed during copy
+* Upgrade dependency on Google API Client
+
+### 0.25.0 / 2017-03-31
+
+* Allow upload and download of in-memory IO objects
+* Added signed_url at top-level object, without creating a bucket or file object
+* Updated documentation
+
+### 0.24.0 / 2017-03-03
+
+* Dependency on Google API Client has been updated to 0.10.x.
+
+### 0.23.2 / 2017-02-21
+
+* Allow setting a File's storage_class on file creation
+* Allow updating an existing File's storage_class
+* Add File#rotate to rotate encryption keys
+* Add PostObject and Bucket#post_object for uploading via HTML forms
+
+### 0.23.1 / 2016-12-12
+
+* Support Google extension headers on signed URLs (calavera)
+
+### 0.23.0 / 2016-12-8
+
+* Remove `encryption_key_sha256` method parameter, hash will be calculated using `encryption_key`
+* Many documentation improvements
+
+### 0.21.0 / 2016-10-20
+
+* New service constructor Google::Cloud::Storage.new
+* Bucket#signed_url added to create URLs without a File object
+
+### 0.20.2 / 2016-09-30
+
+* Fix issue with signed_url and file names with spaces (gsbucks)
+
+### 0.20.1 / 2016-09-02
+
+* Fix for timeout on uploads.
+
+### 0.20.0 / 2016-08-26
+
+This gem contains the Google Cloud Storage service implementation for the `google-cloud` gem. The `google-cloud` gem replaces the old `gcloud` gem. Legacy code can continue to use the `gcloud` gem.
+
+* Namespace is now `Google::Cloud`
+* The `google-cloud` gem is now an umbrella package for individual gems

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,40 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct. By adopting this Code of Conduct, project
+maintainers commit themselves to fairly and consistently applying these
+principles to every aspect of managing this project. Project maintainers who do
+not follow or enforce the Code of Conduct may be permanently removed from the
+project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by opening an issue or contacting one or more of the project
+maintainers.
+
+This Code of Conduct is adapted from the [Contributor
+Covenant](http://contributor-covenant.org), version 1.2.0, available at
+[http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/)

data/CONTRIBUTING.md

@@ -0,0 +1,188 @@
+# Contributing to Google Cloud Storage
+
+1. **Sign one of the contributor license agreements below.**
+2. Fork the repo, develop and test your code changes.
+3. Send a pull request.
+
+## Contributor License Agreements
+
+Before we can accept your pull requests you'll need to sign a Contributor
+License Agreement (CLA):
+
+- **If you are an individual writing original source code** and **you own the
+  intellectual property**, then you'll need to sign an [individual
+  CLA](https://developers.google.com/open-source/cla/individual).
+- **If you work for a company that wants to allow you to contribute your work**,
+  then you'll need to sign a [corporate
+  CLA](https://developers.google.com/open-source/cla/corporate).
+
+You can sign these electronically (just scroll to the bottom). After that, we'll
+be able to accept your pull requests.
+
+## Setup
+
+In order to use the google-cloud-storage console and run the project's tests,
+there is a small amount of setup:
+
+1. Install Ruby. google-cloud-storage requires Ruby 2.3+. You may choose to
+   manage your Ruby and gem installations with [RVM](https://rvm.io/),
+   [rbenv](https://github.com/rbenv/rbenv), or
+   [chruby](https://github.com/postmodern/chruby).
+
+2. Install [Bundler](http://bundler.io/).
+
+   ```sh
+   $ gem install bundler
+   ```
+
+3. Install the top-level project dependencies.
+
+   ```sh
+   $ bundle install
+   ```
+
+4. Install the Storage dependencies.
+
+   ```sh
+   $ cd google-cloud-storage/
+   $ bundle exec rake bundleupdate
+   ```
+
+## Console
+
+In order to run code interactively, you can automatically load
+google-cloud-storage and its dependencies in IRB. This requires that your
+developer environment has already been configured by following the steps
+described in the {file:AUTHENTICATION.md Authentication Guide}. An IRB console
+can be created with:
+
+```sh
+$ cd google-cloud-storage/
+$ bundle exec rake console
+```
+
+## Storage Tests
+
+Tests are very important part of google-cloud-storage. All contributions
+should include tests that ensure the contributed code behaves as expected.
+
+To run the unit tests, documentation tests, and code style checks together for a
+package:
+
+``` sh
+$ cd google-cloud-storage/
+$ bundle exec rake ci
+```
+
+To run the command above, plus all acceptance tests, use `rake ci:acceptance` or
+its handy alias, `rake ci:a`.
+
+### Storage Unit Tests
+
+
+The project uses the [minitest](https://github.com/seattlerb/minitest) library,
+including [specs](https://github.com/seattlerb/minitest#specs),
+[mocks](https://github.com/seattlerb/minitest#mocks) and
+[minitest-autotest](https://github.com/seattlerb/minitest-autotest).
+
+To run the Storage unit tests:
+
+``` sh
+$ cd google-cloud-storage/
+$ bundle exec rake test
+```
+
+### Storage Documentation Tests
+
+The project tests the code examples in the gem's
+[YARD](https://github.com/lsegal/yard)-based documentation.
+
+The example testing functions in a way that is very similar to unit testing, and
+in fact the library providing it,
+[yard-doctest](https://github.com/p0deje/yard-doctest), is based on the
+project's unit test library, [minitest](https://github.com/seattlerb/minitest).
+
+To run the Storage documentation tests:
+
+``` sh
+$ cd google-cloud-storage/
+$ bundle exec rake doctest
+```
+
+If you add, remove or modify documentation examples when working on a pull
+request, you may need to update the setup for the tests. The stubs and mocks
+required to run the tests are located in `support/doctest_helper.rb`. Please
+note that much of the setup is matched by the title of the
+[`@example`](http://www.rubydoc.info/gems/yard/file/docs/Tags.md#example) tag.
+If you alter an example's title, you may encounter breaking tests.
+
+### Storage Acceptance Tests
+
+The Storage acceptance tests interact with the live service API. Follow the
+instructions in the {file:AUTHENTICATION.md Authentication guide} for enabling
+the Storage API. Occasionally, some API features may not yet be generally
+available, making it difficult for some contributors to successfully run the
+entire acceptance test suite. However, please ensure that you do successfully
+run acceptance tests for any code areas covered by your pull request.
+
+To run the acceptance tests, first create and configure a project in the Google
+Developers Console, as described in the {file:AUTHENTICATION.md Authentication
+guide}. Be sure to download the JSON KEY file. Make note of the PROJECT_ID and
+the KEYFILE location on your system.
+
+Before you can run the Storage acceptance tests, you must first create indexes
+used in the tests.
+
+#### Running the Storage acceptance tests
+
+To run the Storage acceptance tests:
+
+``` sh
+$ cd google-cloud-storage/
+$ bundle exec rake acceptance[\\{my-project-id},\\{/path/to/keyfile.json}]
+```
+
+Or, if you prefer you can store the values in the `GCLOUD_TEST_PROJECT` and
+`GCLOUD_TEST_KEYFILE` environment variables:
+
+``` sh
+$ cd google-cloud-storage/
+$ export GCLOUD_TEST_PROJECT=\\{my-project-id}
+$ export GCLOUD_TEST_KEYFILE=\\{/path/to/keyfile.json}
+$ bundle exec rake acceptance
+```
+
+If you want to use a different project and credentials for acceptance tests, you
+can use the more specific `STORAGE_TEST_PROJECT`  and `STORAGE_TEST_KEYFILE`
+environment variables:
+
+``` sh
+$ cd google-cloud-storage/
+$ export STORAGE_TEST_PROJECT=\\{my-project-id}
+$ export STORAGE_TEST_KEYFILE=\\{/path/to/keyfile.json}
+$ bundle exec rake acceptance
+```
+
+## Coding Style
+
+Please follow the established coding style in the library. The style is is
+largely based on [The Ruby Style
+Guide](https://github.com/bbatsov/ruby-style-guide) with a few exceptions based
+on seattle-style:
+
+* Avoid parenthesis when possible, including in method definitions.
+* Always use double quotes strings. ([Option
+  B](https://github.com/bbatsov/ruby-style-guide#strings))
+
+You can check your code against these rules by running Rubocop like so:
+
+```sh
+$ cd google-cloud-storage/
+$ bundle exec rake rubocop
+```
+
+## Code of Conduct
+
+Please note that this project is released with a Contributor Code of Conduct. By
+participating in this project you agree to abide by its terms. See
+{file:CODE_OF_CONDUCT.md Code of Conduct} for more information.