google-cloud-storage 0.20.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6a1c76520a0d11fc1c5c1eab6e2d1f1b4ff91722
+  data.tar.gz: 13c3e68262197af5291c8ad83176390781a4fcad
+SHA512:
+  metadata.gz: 3a72a3dc3325b969ecb69737731f794e5115a3691d3d2194858df9358a3384a5cb3f21e6cc54c0a67f14bd5004e05131acd1d636385df8a07543348bc93eb9d9
+  data.tar.gz: 24acdbc0c2ebf827a4f6a2a64457f1b45719d8222df10612054e0579b3fea5719f97a8ef845470e884dc9c334ec508b8f9c7d751147753da555304166b8d66a6

data/lib/google-cloud-storage.rb

@@ -0,0 +1,124 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# 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.
+
+##
+# This file is here to be autorequired by bundler, so that the .bigquery and
+# #bigquery methods can be available, but the library and all dependencies won't
+# be loaded until required and used.
+
+
+gem "google-cloud-core"
+require "google/cloud"
+
+module Google
+  module Cloud
+    ##
+    # Creates a new object for connecting to the Storage service.
+    # Each call creates a new connection.
+    #
+    # For more information on connecting to Google Cloud see the [Authentication
+    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    #
+    # @see https://cloud.google.com/storage/docs/authentication#oauth Storage
+    #   OAuth 2.0 Authentication
+    #
+    # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+    #   set of resources and operations that the connection can access. See
+    #   [Using OAuth 2.0 to Access Google
+    #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+    #
+    #   The default scope is:
+    #
+    #   * `https://www.googleapis.com/auth/devstorage.full_control`
+    # @param [Integer] retries Number of times to retry requests on server
+    #   error. The default value is `3`. Optional.
+    # @param [Integer] timeout Default timeout to use in requests. Optional.
+    #
+    # @return [Google::Cloud::Storage::Project]
+    #
+    # @example
+    #   require "google/cloud"
+    #
+    #   gcloud  = Google::Cloud.new
+    #   storage = gcloud.storage
+    #   bucket = storage.bucket "my-bucket"
+    #   file = bucket.file "path/to/my-file.ext"
+    #
+    # @example The default scope can be overridden with the `scope` option:
+    #   require "google/cloud"
+    #
+    #   gcloud  = Google::Cloud.new
+    #   readonly_scope = "https://www.googleapis.com/auth/devstorage.read_only"
+    #   readonly_storage = gcloud.storage scope: readonly_scope
+    #
+    def storage scope: nil, retries: nil, timeout: nil
+      Google::Cloud.storage @project, @keyfile, scope: scope,
+                                                retries: (retries || @retries),
+                                                timeout: (timeout || @timeout)
+    end
+
+    ##
+    # Creates a new object for connecting to the Storage service.
+    # Each call creates a new connection.
+    #
+    # For more information on connecting to Google Cloud see the [Authentication
+    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    #
+    # @param [String] project Project identifier for the Storage service you are
+    #   connecting to.
+    # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
+    #   file path the file must be readable.
+    # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+    #   set of resources and operations that the connection can access. See
+    #   [Using OAuth 2.0 to Access Google
+    #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+    #
+    #   The default scope is:
+    #
+    #   * `https://www.googleapis.com/auth/devstorage.full_control`
+    # @param [Integer] retries Number of times to retry requests on server
+    #   error. The default value is `3`. Optional.
+    # @param [Integer] timeout Default timeout to use in requests. Optional.
+    #
+    # @return [Google::Cloud::Storage::Project]
+    #
+    # @example
+    #   require "google/cloud/storage"
+    #
+    #   storage = Google::Cloud.storage "my-todo-project",
+    #                            "/path/to/keyfile.json"
+    #
+    #   bucket = storage.bucket "my-bucket"
+    #   file = bucket.file "path/to/my-file.ext"
+    #
+    def self.storage project = nil, keyfile = nil, scope: nil, retries: nil,
+                     timeout: nil
+      require "google/cloud/storage"
+      project ||= Google::Cloud::Storage::Project.default_project
+      project = project.to_s # Always cast to a string
+      fail ArgumentError, "project is missing" if project.empty?
+
+      if keyfile.nil?
+        credentials = Google::Cloud::Storage::Credentials.default scope: scope
+      else
+        credentials = Google::Cloud::Storage::Credentials.new(
+          keyfile, scope: scope)
+      end
+
+      Google::Cloud::Storage::Project.new(
+        Google::Cloud::Storage::Service.new(
+          project, credentials, retries: retries, timeout: timeout))
+    end
+  end
+end

data/lib/google/cloud/storage.rb

@@ -0,0 +1,412 @@
+# Copyright 2014 Google Inc. All rights reserved.
+#
+# 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 "google-cloud-storage"
+require "google/cloud/storage/project"
+
+module Google
+  module Cloud
+    ##
+    # # Google Cloud Storage
+    #
+    # Google Cloud Storage is an Internet service to store data in Google's
+    # cloud. It allows world-wide storage and retrieval of any amount of data
+    # and at any time, taking advantage of Google's own reliable and fast
+    # networking infrastructure to perform data operations in a cost effective
+    # manner.
+    #
+    # The goal of google-cloud is to provide a API that is comfortable to
+    # Rubyists. Authentication is handled by {Google::Cloud#storage}. You can
+    # provide the project and credential information to connect to the Storage
+    # service, or if you are running on Google Compute Engine this configuration
+    # is taken care of for you.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new "my-todo-project",
+    #                     "/path/to/keyfile.json"
+    # storage = gcloud.storage
+    #
+    # bucket = storage.bucket "my-bucket"
+    # file = bucket.file "path/to/my-file.ext"
+    # ```
+    #
+    # You can learn more about various options for connection on the
+    # [Authentication
+    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    #
+    # To learn more about Cloud Storage, read the
+    # [Google Cloud Storage Overview
+    # ](https://cloud.google.com/storage/docs/overview).
+    #
+    # ## Retrieving Buckets
+    #
+    # A Bucket is the container for your data. There is no limit on the number
+    # of buckets that you can create in a project. You can use buckets to
+    # organize and control access to your data. Each bucket has a unique name,
+    # which is how they are retrieved: (See
+    # {Google::Cloud::Storage::Project#bucket})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # bucket = storage.bucket "my-todo-app"
+    # ```
+    #
+    # You can also retrieve all buckets on a project: (See
+    # {Google::Cloud::Storage::Project#buckets})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # all_buckets = storage.buckets
+    # ```
+    #
+    # If you have a significant number of buckets, you may need to paginate
+    # through them: (See {Google::Cloud::Storage::Bucket::List#token})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # all_buckets = []
+    # tmp_buckets = storage.buckets
+    # while tmp_buckets.any? do
+    #   tmp_buckets.each do |bucket|
+    #     all_buckets << bucket
+    #   end
+    #   # break loop if no more buckets available
+    #   break if tmp_buckets.token.nil?
+    #   # get the next group of buckets
+    #   tmp_buckets = storage.buckets token: tmp_buckets.token
+    # end
+    # ```
+    #
+    # ## Creating a Bucket
+    #
+    # A unique name is all that is needed to create a new bucket: (See
+    # {Google::Cloud::Storage::Project#create_bucket})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # bucket = storage.create_bucket "my-todo-app-attachments"
+    # ```
+    #
+    # ## Retrieving Files
+    #
+    # A File is an individual pieces of data that you store in Google Cloud
+    # Storage. Files contain the data stored as well as metadata describing the
+    # data. Files belong to a bucket and cannot be shared among buckets. There
+    # is no limit on the number of objects that you can create in a bucket.
+    #
+    # Files are retrieved by their name, which is the path of the file in the
+    # bucket: (See {Google::Cloud::Storage::Bucket#file})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # bucket = storage.bucket "my-todo-app"
+    # file = bucket.file "avatars/heidi/400x400.png"
+    # ```
+    #
+    # You can also retrieve all files in a bucket: (See Bucket#files)
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # bucket = storage.bucket "my-todo-app"
+    # all_files = bucket.files
+    # ```
+    #
+    # Or you can retrieve all files in a specified path:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # bucket = storage.bucket "my-todo-app"
+    # avatar_files = bucket.files prefix: "avatars/"
+    # ```
+    #
+    # If you have a significant number of files, you may need to paginate
+    # through them: (See {Google::Cloud::Storage::File::List#token})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # bucket = storage.bucket "my-todo-app"
+    #
+    # all_files = []
+    # tmp_files = bucket.files
+    # while tmp_files.any? do
+    #   tmp_files.each do |file|
+    #     all_files << file
+    #   end
+    #   # break loop if no more files available
+    #   break if tmp_files.token.nil?
+    #   # get the next group of files
+    #   tmp_files = bucket.files token: tmp_files.token
+    # end
+    # ```
+    #
+    # ## Creating a File
+    #
+    # A new File can be uploaded by specifying the location of a file on the
+    # local file system, and the name/path that the file should be stored in the
+    # bucket. (See {Google::Cloud::Storage::Bucket#create_file})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # bucket = storage.bucket "my-todo-app"
+    # bucket.create_file "/var/todo-app/avatars/heidi/400x400.png",
+    #                    "avatars/heidi/400x400.png"
+    # ```
+    #
+    # ### Customer-supplied encryption keys
+    #
+    # By default, Google Cloud Storage manages server-side encryption keys on
+    # your behalf. However, a [customer-supplied encryption
+    # key](https://cloud.google.com/storage/docs/encryption#customer-supplied)
+    # can be provided with the `encryption_key` and `encryption_key_sha256`
+    # options. If given, the same key and SHA256 hash also must be provided to
+    # subsequently download or copy the file. If you use customer-supplied
+    # encryption keys, you must securely manage your keys and ensure that they
+    # are not lost. Also, please note that file metadata is not encrypted, with
+    # the exception of the CRC32C checksum and MD5 hash. The names of files and
+    # buckets are also not encrypted, and you can read or update the metadata of
+    # an encrypted file without providing the encryption key.
+    #
+    # ```ruby
+    # require "google/cloud"
+    # require "digest/sha2"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    # bucket = storage.bucket "my-todo-app"
+    #
+    # # Key generation shown for example purposes only. Write your own.
+    # cipher = OpenSSL::Cipher.new "aes-256-cfb"
+    # cipher.encrypt
+    # key = cipher.random_key
+    # key_hash = Digest::SHA256.digest key
+    #
+    # bucket.create_file "/var/todo-app/avatars/heidi/400x400.png",
+    #                    "avatars/heidi/400x400.png",
+    #                    encryption_key: key,
+    #                    encryption_key_sha256: key_hash
+    #
+    # # Store your key and hash securely for later use.
+    # file = bucket.file "avatars/heidi/400x400.png",
+    #                    encryption_key: key,
+    #                    encryption_key_sha256: key_hash
+    # ```
+    #
+    # ## Downloading a File
+    #
+    # Files can be downloaded to the local file system. (See
+    # {Google::Cloud::Storage::File#download})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # bucket = storage.bucket "my-todo-app"
+    # file = bucket.file "avatars/heidi/400x400.png"
+    # file.download "/var/todo-app/avatars/heidi/400x400.png"
+    # ```
+    #
+    # ## Using Signed URLs
+    #
+    # Access without authentication can be granted to a File for a specified
+    # period of time. This URL uses a cryptographic signature of your
+    # credentials to access the file. (See
+    # {Google::Cloud::Storage::File#signed_url})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # bucket = storage.bucket "my-todo-app"
+    # file = bucket.file "avatars/heidi/400x400.png"
+    # shared_url = file.signed_url method: "GET",
+    #                              expires: 300 # 5 minutes from now
+    # ```
+    #
+    # ## Controlling Access to a Bucket
+    #
+    # Access to a bucket is controlled with
+    # {Google::Cloud::Storage::Bucket#acl}. A bucket has owners, writers, and
+    # readers. Permissions can be granted to an individual user's email address,
+    # a group's email address, as well as many predefined lists. See the [Access
+    # Control guide](https://cloud.google.com/storage/docs/access-control) for
+    # more.
+    #
+    # Access to a bucket can be granted to a user by appending `"user-"` to the
+    # email address:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # bucket = storage.bucket "my-todo-app"
+    #
+    # email = "heidi@example.net"
+    # bucket.acl.add_reader "user-#{email}"
+    # ```
+    #
+    # Access to a bucket can be granted to a group by appending `"group-"` to
+    # the email address:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # bucket = storage.bucket "my-todo-app"
+    #
+    # email = "authors@example.net"
+    # bucket.acl.add_reader "group-#{email}"
+    # ```
+    #
+    # Access to a bucket can also be granted to a predefined list of
+    # permissions:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # bucket = storage.bucket "my-todo-app"
+    #
+    # bucket.acl.public!
+    # ```
+    #
+    # ## Controlling Access to a File
+    #
+    # Access to a file is controlled in two ways, either by the setting the
+    # default permissions to all files in a bucket with
+    # {Google::Cloud::Storage::Bucket#default_acl}, or by setting permissions to
+    # an individual file with {Google::Cloud::Storage::File#acl}.
+    #
+    # Access to a file can be granted to a user by appending `"user-"` to the
+    # email address:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # bucket = storage.bucket "my-todo-app"
+    # file = bucket.file "avatars/heidi/400x400.png"
+    #
+    # email = "heidi@example.net"
+    # file.acl.add_reader "user-#{email}"
+    # ```
+    #
+    # Access to a file can be granted to a group by appending `"group-"` to the
+    # email address:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # bucket = storage.bucket "my-todo-app"
+    # file = bucket.file "avatars/heidi/400x400.png"
+    #
+    # email = "authors@example.net"
+    # file.acl.add_reader "group-#{email}"
+    # ```
+    #
+    # Access to a file can also be granted to a predefined list of permissions:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # bucket = storage.bucket "my-todo-app"
+    # file = bucket.file "avatars/heidi/400x400.png"
+    #
+    # file.acl.public!
+    # ```
+    #
+    # ## Configuring retries and timeout
+    #
+    # You can configure how many times API requests may be automatically
+    # retried. When an API request fails, the response will be inspected to see
+    # if the request meets criteria indicating that it may succeed on retry,
+    # such as `500` and `503` status codes or a specific internal error code
+    # such as `rateLimitExceeded`. If it meets the criteria, the request will be
+    # retried after a delay. If another error occurs, the delay will be
+    # increased before a subsequent attempt, until the `retries` limit is
+    # reached.
+    #
+    # You can also set the request `timeout` value in seconds.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage retries: 10, timeout: 120
+    # ```
+    #
+    # See the [Storage status and error
+    # codes](https://cloud.google.com/storage/docs/json_api/v1/status-codes)
+    # for a list of error conditions.
+    #
+    module Storage
+    end
+  end
+end