gcloud 0.0.7 → 0.1.0

data/lib/gcloud/storage.rb

@@ -0,0 +1,78 @@
+# 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 "gcloud"
+require "gcloud/storage/project"
+
+##
+# Google Cloud Storage
+module Gcloud
+  ##
+  # Create a new Storage project.
+  #
+  #   storage = Gcloud.storage "my-todo-project",
+  #                            "/path/to/keyfile.json"
+  #   bucket = storage.find_bucket "my-bucket"
+  #   file = bucket.find_file "path/to/my-file.ext"
+  #
+  # @param project [String] the project identifier for the Storage
+  # account you are connecting to.
+  # @param keyfile [String] the path to the keyfile you downloaded from
+  # Google Cloud. The file must readable.
+  # @return [Gcloud::Storage::Project] storage project.
+  #
+  # See Gcloud::Storage::Project
+  def self.storage project = ENV["STORAGE_PROJECT"],
+                   keyfile = nil
+    if keyfile.nil?
+      credentials = Gcloud::Storage::Credentials.default
+    else
+      credentials = Gcloud::Storage::Credentials.new keyfile
+    end
+    Gcloud::Storage::Project.new project, credentials
+  end
+
+  ##
+  # Google Cloud Storage
+  #
+  #   storage = Gcloud.storage "my-todo-project",
+  #                            "/path/to/keyfile.json"
+  #   bucket = storage.find_bucket "my-bucket"
+  #   file = bucket.find_file "path/to/my-file.ext"
+  #
+  # See Gcloud::Storage::Project
+  module Storage
+    ##
+    # Retrieve resumable threshold.
+    # If uploads are larger in size than this value then
+    # resumable uploads are used.
+    #
+    # The default value is 5 MiB (5,000,000 bytes).
+    def self.resumable_threshold
+      @@resumable_threshold
+    end
+
+    ##
+    # Sets a new resumable threshold value.
+    def self.resumable_threshold= new_resumable_threshold
+      # rubocop:disable Style/ClassVars
+      # Disabled rubocop because this is the best option.
+      @@resumable_threshold = new_resumable_threshold.to_i
+      # rubocop:enable Style/ClassVars
+    end
+
+    # Set the default threshold to 5 MiB.
+    self.resumable_threshold = 5_000_000
+  end
+end

data/lib/gcloud/storage/bucket.rb

@@ -0,0 +1,254 @@
+# 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 "gcloud/storage/bucket/acl"
+require "gcloud/storage/bucket/list"
+require "gcloud/storage/file"
+
+module Gcloud
+  module Storage
+    ##
+    # Represents a Bucket. Belongs to a Project and has many Files.
+    class Bucket
+      ##
+      # The Connection object.
+      attr_accessor :connection #:nodoc:
+
+      ##
+      # The Google API Client object.
+      attr_accessor :gapi #:nodoc:
+
+      ##
+      # Create an empty Bucket object.
+      def initialize
+        @connection = nil
+        @gapi = {}
+      end
+
+      ##
+      # The kind of item this is.
+      # For buckets, this is always storage#bucket.
+      def kind
+        @gapi["kind"]
+      end
+
+      ##
+      # The ID of the bucket.
+      def id
+        @gapi["id"]
+      end
+
+      ##
+      # The name of the bucket.
+      def name
+        @gapi["name"]
+      end
+
+      ##
+      # The URI of this bucket.
+      def url
+        @gapi["selfLink"]
+      end
+
+      ##
+      # The location of the bucket.
+      # Object data for objects in the bucket resides in physical
+      # storage within this region. Defaults to US.
+      # See the developer's guide for the authoritative list.
+      #
+      # https://cloud.google.com/storage/docs/concepts-techniques
+      def location
+        @gapi["location"]
+      end
+
+      ##
+      # Creation time of the bucket.
+      def created_at
+        @gapi["timeCreated"]
+      end
+
+      ##
+      # Permenently deletes the bucket.
+      # The bucket must be empty.
+      #
+      #   bucket.delete
+      #
+      # The API call to delete the bucket may be retried under certain
+      # conditions. See Gcloud::Backoff to control this behavior, or
+      # specify the wanted behavior in the call:
+      #
+      #   bucket.delete retries: 5
+      def delete options = {}
+        ensure_connection!
+        resp = connection.delete_bucket name, options
+        if resp.success?
+          true
+        else
+          ApiError.from_response(resp)
+        end
+      end
+
+      ##
+      # Retrieves a list of files matching the criteria.
+      #
+      #   storage = Gcloud.storage
+      #   bucket = storage.find_bucket "my-bucket"
+      #   files = bucket.files
+      #   files.each do |file|
+      #     puts file.name
+      #   end
+      #
+      # See Gcloud::Storage::File
+      def files options = {}
+        ensure_connection!
+        resp = connection.list_files name, options
+        if resp.success?
+          File::List.from_resp resp, connection
+        else
+          fail ApiError.from_response(resp)
+        end
+      end
+
+      ##
+      # Retrieves a file matching the path.
+      #
+      #   storage = Gcloud.storage
+      #   bucket = storage.find_bucket "my-bucket"
+      #   file = bucket.find_file "path/to/my-file.ext"
+      #   puts file.name
+      #
+      # See Gcloud::Storage::File
+      def find_file path, options = {}
+        ensure_connection!
+        resp = connection.get_file name, path, options
+        if resp.success?
+          File.from_gapi resp.data, connection
+        else
+          fail ApiError.from_response(resp)
+        end
+      end
+
+      ##
+      # Create a new Gcloud::Storeage::File object by providing a
+      # File object to upload and the path to store it with.
+      #
+      #   storage = Gcloud.storage
+      #   bucket = storage.find_bucket "my-bucket"
+      #   bucket.create_file "path/to/local.file.ext"
+      #
+      # Additionally, a destination path can be specified.
+      #
+      #   storage = Gcloud.storage
+      #   bucket = storage.find_bucket "my-bucket"
+      #   bucket.create_file "path/to/local.file.ext",
+      #                      "destination/path/file.ext"
+      #
+      # A chunk_size value can be provided in the options to be used
+      # in resumable uploads. This value is the number of bytes per
+      # chunk and must be divisible by 256KB. If it is not divisible
+      # by 265KB then it will be lowered to the nearest acceptible
+      # value.
+      #
+      #   bucket.create_file "path/to/local.file.ext",
+      #                      "destination/path/file.ext",
+      #                      chunk_size: 1024*1024 # 1 MB chunk
+      #
+      # See Gcloud::Storage::File
+      def create_file file, path = nil, options = {}
+        ensure_connection!
+        # TODO: Raise if file doesn't exist
+        # ensure_file_exists!
+        fail unless ::File.file? file
+
+        options[:acl] = File::Acl.predefined_rule_for options[:acl]
+
+        if resumable_upload? file
+          upload_resumable file, path, options[:chunk_size], options
+        else
+          upload_multipart file, path, options
+        end
+      end
+
+      ##
+      # Access Control List
+      def acl
+        @acl ||= Bucket::Acl.new self
+      end
+
+      ##
+      # Default Access Control List
+      def default_acl
+        @default_acl ||= Bucket::DefaultAcl.new self
+      end
+
+      ##
+      # New Bucket from a Google API Client object.
+      def self.from_gapi gapi, conn #:nodoc:
+        new.tap do |f|
+          f.gapi = gapi
+          f.connection = conn
+        end
+      end
+
+      protected
+
+      ##
+      # Raise an error unless an active connection is available.
+      def ensure_connection!
+        fail "Must have active connection" unless connection
+      end
+
+      ##
+      # Determines if a resumable upload should be used.
+      def resumable_upload? file #:nodoc:
+        ::File.size?(file).to_i > Storage.resumable_threshold
+      end
+
+      def upload_multipart file, path, options = {}
+        resp = @connection.insert_file_multipart name, file, path, options
+
+        if resp.success?
+          File.from_gapi resp.data, connection
+        else
+          fail ApiError.from_response(resp)
+        end
+      end
+
+      def upload_resumable file, path, chunk_size, options = {}
+        chunk_size = verify_chunk_size! chunk_size
+
+        resp = @connection.insert_file_resumable name, file,
+                                                 path, chunk_size, options
+
+        if resp.success?
+          File.from_gapi resp.data, connection
+        else
+          fail ApiError.from_response(resp)
+        end
+      end
+
+      ##
+      # Determines if a chunk_size is valid.
+      def verify_chunk_size! chunk_size
+        chunk_size = chunk_size.to_i
+        chunk_mod = 256 * 1024 # 256KB
+        if (chunk_size.to_i % chunk_mod) != 0
+          chunk_size = (chunk_size / chunk_mod) * chunk_mod
+        end
+        return if chunk_size.zero?
+        chunk_size
+      end
+    end
+  end
+end

data/lib/gcloud/storage/bucket/acl.rb

@@ -0,0 +1,311 @@
+# Copyright 2015 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.
+
+module Gcloud
+  module Storage
+    class Bucket
+      ##
+      # Represents a Bucket's Access Control List.
+      class Acl
+        RULES = { "authenticatedRead" => "authenticatedRead",
+                  "auth" => "authenticatedRead",
+                  "auth_read" => "authenticatedRead",
+                  "authenticated" => "authenticatedRead",
+                  "authenticated_read" => "authenticatedRead",
+                  "private" => "private",
+                  "projectPrivate" => "projectPrivate",
+                  "proj_private" => "projectPrivate",
+                  "project_private" => "projectPrivate",
+                  "publicRead" => "publicRead",
+                  "public" => "publicRead",
+                  "public_read" => "publicRead",
+                  "publicReadWrite" => "publicReadWrite",
+                  "public_write" => "publicReadWrite" }
+
+        ##
+        # Initialized a new Acl object.
+        # Must provide a valid Bucket object.
+        def initialize bucket #:nodoc:
+          @bucket = bucket.name
+          @connection = bucket.connection
+          @owners  = nil
+          @writers = nil
+          @readers = nil
+        end
+
+        def refresh!
+          resp = @connection.list_bucket_acls @bucket
+          acls = resp.data["items"]
+          @owners  = entities_from_acls acls, "OWNER"
+          @writers = entities_from_acls acls, "WRITER"
+          @readers = entities_from_acls acls, "READER"
+        end
+
+        def owners
+          refresh! if @owners.nil?
+          @owners
+        end
+
+        def writers
+          refresh! if @writers.nil?
+          @writers
+        end
+
+        def readers
+          refresh! if @readers.nil?
+          @readers
+        end
+
+        def add_owner entity
+          resp = @connection.insert_bucket_acl @bucket, entity, "OWNER"
+          if resp.success?
+            entity = resp.data["entity"]
+            @owners.push entity unless @owners.nil?
+            return entity
+          end
+          nil
+        end
+
+        def add_writer entity
+          resp = @connection.insert_bucket_acl @bucket, entity, "WRITER"
+          if resp.success?
+            entity = resp.data["entity"]
+            @writers.push entity unless @writers.nil?
+            return entity
+          end
+          nil
+        end
+
+        def add_reader entity
+          resp = @connection.insert_bucket_acl @bucket, entity, "READER"
+          if resp.success?
+            entity = resp.data["entity"]
+            @readers.push entity unless @readers.nil?
+            return entity
+          end
+          nil
+        end
+
+        def delete entity
+          resp = @connection.delete_bucket_acl @bucket, entity
+          if resp.success?
+            @owners.delete entity  unless @owners.nil?
+            @writers.delete entity unless @writers.nil?
+            @readers.delete entity unless @readers.nil?
+            return true
+          end
+          false
+        end
+
+        def self.predefined_rule_for rule_name
+          RULES[rule_name.to_s]
+        end
+
+        # Predefined ACL helpers
+
+        def auth!
+          update_predefined_acl! "authenticatedRead"
+        end
+        alias_method :authenticatedRead!, :auth!
+        alias_method :auth_read!, :auth!
+        alias_method :authenticated!, :auth!
+        alias_method :authenticated_read!, :auth!
+
+        def private!
+          update_predefined_acl! "private"
+        end
+
+        def project_private!
+          update_predefined_acl! "projectPrivate"
+        end
+        alias_method :projectPrivate!, :project_private!
+
+        def public!
+          update_predefined_acl! "publicRead"
+        end
+        alias_method :publicRead!, :public!
+        alias_method :public_read!, :public!
+
+        def public_write!
+          update_predefined_acl! "publicReadWrite"
+        end
+        alias_method :publicReadWrite!, :public_write!
+
+        protected
+
+        def update_predefined_acl! acl_role
+          resp = @connection.patch_bucket @bucket,
+                                          acl: acl_role
+
+          resp.success?
+        end
+
+        def entities_from_acls acls, role
+          selected = acls.select { |acl| acl["role"] == role }
+          entities = selected.map { |acl| acl["entity"] }
+          entities
+        end
+      end
+
+      ##
+      # Represents a Bucket's Default Access Control List.
+      class DefaultAcl
+        RULES = { "authenticatedRead" => "authenticatedRead",
+                  "auth" => "authenticatedRead",
+                  "auth_read" => "authenticatedRead",
+                  "authenticated" => "authenticatedRead",
+                  "authenticated_read" => "authenticatedRead",
+                  "bucketOwnerFullControl" => "bucketOwnerFullControl",
+                  "owner_full" => "bucketOwnerFullControl",
+                  "bucketOwnerRead" => "bucketOwnerRead",
+                  "owner_read" => "bucketOwnerRead",
+                  "private" => "private",
+                  "projectPrivate" => "projectPrivate",
+                  "project_private" => "projectPrivate",
+                  "publicRead" => "publicRead",
+                  "public" => "publicRead",
+                  "public_read" => "publicRead" }
+
+        ##
+        # Initialized a new DefaultAcl object.
+        # Must provide a valid Bucket object.
+        def initialize bucket #:nodoc:
+          @bucket = bucket.name
+          @connection = bucket.connection
+          @owners  = nil
+          @writers = nil
+          @readers = nil
+        end
+
+        def refresh!
+          resp = @connection.list_default_acls @bucket
+          acls = resp.data["items"]
+          @owners  = entities_from_acls acls, "OWNER"
+          @writers = entities_from_acls acls, "WRITER"
+          @readers = entities_from_acls acls, "READER"
+        end
+
+        def owners
+          refresh! if @owners.nil?
+          @owners
+        end
+
+        def writers
+          refresh! if @writers.nil?
+          @writers
+        end
+
+        def readers
+          refresh! if @readers.nil?
+          @readers
+        end
+
+        def add_owner entity
+          resp = @connection.insert_default_acl @bucket, entity, "OWNER"
+          if resp.success?
+            entity = resp.data["entity"]
+            @owners.push entity unless @owners.nil?
+            return entity
+          end
+          nil
+        end
+
+        def add_writer entity
+          resp = @connection.insert_default_acl @bucket, entity, "WRITER"
+          if resp.success?
+            entity = resp.data["entity"]
+            @writers.push entity unless @writers.nil?
+            return entity
+          end
+          nil
+        end
+
+        def add_reader entity
+          resp = @connection.insert_default_acl @bucket, entity, "READER"
+          if resp.success?
+            entity = resp.data["entity"]
+            @readers.push entity unless @readers.nil?
+            return entity
+          end
+          nil
+        end
+
+        def delete entity
+          resp = @connection.delete_default_acl @bucket, entity
+          if resp.success?
+            @owners.delete entity  unless @owners.nil?
+            @writers.delete entity unless @writers.nil?
+            @readers.delete entity unless @readers.nil?
+            return true
+          end
+          false
+        end
+
+        def self.predefined_rule_for rule_name
+          RULES[rule_name.to_s]
+        end
+
+        # Predefined ACL helpers
+
+        def auth!
+          update_predefined_default_acl! "authenticatedRead"
+        end
+        alias_method :authenticatedRead!, :auth!
+        alias_method :auth_read!, :auth!
+        alias_method :authenticated!, :auth!
+        alias_method :authenticated_read!, :auth!
+
+        def owner_full!
+          update_predefined_default_acl! "bucketOwnerFullControl"
+        end
+        alias_method :bucketOwnerFullControl!, :owner_full!
+
+        def owner_read!
+          update_predefined_default_acl! "bucketOwnerRead"
+        end
+        alias_method :bucketOwnerRead!, :owner_read!
+
+        def private!
+          update_predefined_default_acl! "private"
+        end
+
+        def project_private!
+          update_predefined_default_acl! "projectPrivate"
+        end
+        alias_method :projectPrivate!, :project_private!
+
+        def public!
+          update_predefined_default_acl! "publicRead"
+        end
+        alias_method :publicRead!, :public!
+        alias_method :public_read!, :public!
+
+        protected
+
+        def update_predefined_default_acl! acl_role
+          resp = @connection.patch_bucket @bucket,
+                                          default_acl: acl_role
+
+          resp.success?
+        end
+
+        def entities_from_acls acls, role
+          selected = acls.select { |acl| acl["role"] == role }
+          entities = selected.map { |acl| acl["entity"] }
+          entities
+        end
+      end
+    end
+  end
+end