google-cloud-storage 1.13.1 → 1.14.0

data/lib/google/cloud/storage/bucket.rb

@@ -16,10 +16,12 @@
 require "google/cloud/storage/bucket/acl"
 require "google/cloud/storage/bucket/list"
 require "google/cloud/storage/bucket/cors"
-require "google/cloud/storage/policy"
-require "google/cloud/storage/post_object"
+require "google/cloud/storage/bucket/lifecycle"
+require "google/cloud/storage/convert"
 require "google/cloud/storage/file"
 require "google/cloud/storage/notification"
+require "google/cloud/storage/policy"
+require "google/cloud/storage/post_object"
 require "pathname"
 
 module Google
@@ -39,6 +41,7 @@ module Google
       #   file = bucket.file "path/to/my-file.ext"
       #
       class Bucket
+        include Convert
         ##
         # @private The Service object.
         attr_accessor :service
@@ -188,6 +191,73 @@ module Google
           cors_builder.freeze # always return frozen objects
         end
 
+        ##
+        # Returns the current Object Lifecycle Management rules configuration
+        # for the bucket.
+        #
+        # This method also accepts a block for updating the bucket's Object
+        # Lifecycle Management rules. See {Bucket::Lifecycle} for details.
+        #
+        # @see https://cloud.google.com/storage/docs/lifecycle Object
+        #   Lifecycle Management
+        # @see https://cloud.google.com/storage/docs/managing-lifecycles
+        #   Managing Object Lifecycles
+        #
+        # @yield [lifecycle] a block for setting Object Lifecycle Management
+        #   rules
+        # @yieldparam [Bucket::Lifecycle] lifecycle the object accepting Object
+        #   Lifecycle Management rules
+        #
+        # @return [Bucket::Lifecycle] The frozen builder object.
+        #
+        # @example Retrieving a bucket's lifecycle management rules.
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.lifecycle.size #=> 2
+        #   rule = bucket.lifecycle.first
+        #   rule.action #=> "SetStorageClass"
+        #   rule.storage_class #=> "COLDLINE"
+        #   rule.age #=> 10
+        #   rule.matches_storage_class #=> ["MULTI_REGIONAL", "REGIONAL"]
+        #
+        # @example Updating the bucket's lifecycle management rules in a block.
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.update do |b|
+        #     b.lifecycle do |l|
+        #       # Remove the last rule from the array
+        #       l.pop
+        #       # Remove rules with the given condition
+        #       l.delete_if do |r|
+        #         r.matches_storage_class.include? "NEARLINE"
+        #       end
+        #       # Update rules
+        #       l.each do |r|
+        #         r.age = 90 if r.action == "Delete"
+        #       end
+        #       # Add a rule
+        #       l.add_set_storage_class_rule "COLDLINE", age: 10
+        #     end
+        #   end
+        #
+        def lifecycle
+          lifecycle_builder = Bucket::Lifecycle.from_gapi @gapi.lifecycle
+          if block_given?
+            yield lifecycle_builder
+            if lifecycle_builder.changed?
+              @gapi.lifecycle = lifecycle_builder.to_gapi
+              patch_gapi! :lifecycle
+            end
+          end
+          lifecycle_builder.freeze # always return frozen objects
+        end
+
         ##
         # The location of the bucket.
         # Object data for objects in the bucket resides in physical
@@ -522,6 +592,7 @@ module Google
           # Add check for mutable cors
           updater.check_for_changed_labels!
           updater.check_for_mutable_cors!
+          updater.check_for_mutable_lifecycle!
           patch_gapi! updater.updates unless updater.updates.empty?
         end
 
@@ -1519,14 +1590,14 @@ module Google
         #   require "google/cloud/storage"
         #
         #   pubsub = Google::Cloud::Pubsub.new
+        #   storage = Google::Cloud::Storage.new
+        #
         #   topic = pubsub.create_topic "my-topic"
         #   topic.policy do |p|
         #     p.add "roles/pubsub.publisher",
-        #           "serviceAccount:my-project" \
-        #           "@gs-project-accounts.iam.gserviceaccount.com"
+        #           "serviceAccount:#{storage.service_account_email}"
         #   end
         #
-        #   storage = Google::Cloud::Storage.new
         #   bucket = storage.bucket "my-bucket"
         #
         #   notification = bucket.create_notification topic.name
@@ -1639,18 +1710,6 @@ module Google
           raise ArgumentError, "cannot find file #{file}"
         end
 
-        def storage_class_for str
-          return nil if str.nil?
-          { "durable_reduced_availability" => "DURABLE_REDUCED_AVAILABILITY",
-            "dra" => "DURABLE_REDUCED_AVAILABILITY",
-            "durable" => "DURABLE_REDUCED_AVAILABILITY",
-            "nearline" => "NEARLINE",
-            "coldline" => "COLDLINE",
-            "multi_regional" => "MULTI_REGIONAL",
-            "regional" => "REGIONAL",
-            "standard" => "STANDARD" }[str.to_s.downcase] || str.to_s
-        end
-
         ##
         # Yielded to a block to accumulate changes for a patch request.
         class Updater < Bucket
@@ -1662,6 +1721,7 @@ module Google
             @gapi = gapi
             @labels = @gapi.labels.to_h.dup
             @cors_builder = nil
+            @lifecycle_builder = nil
           end
 
           ##
@@ -1708,6 +1768,22 @@ module Google
             patch_gapi! :cors_configurations
           end
 
+          def lifecycle
+            # Same as Bucket#lifecycle, but not frozen
+            @lifecycle_builder ||= Bucket::Lifecycle.from_gapi @gapi.lifecycle
+            yield @lifecycle_builder if block_given?
+            @lifecycle_builder
+          end
+
+          ##
+          # @private Make sure any lifecycle changes are saved
+          def check_for_mutable_lifecycle!
+            return if @lifecycle_builder.nil?
+            return unless @lifecycle_builder.changed?
+            @gapi.lifecycle = @lifecycle_builder.to_gapi
+            patch_gapi! :lifecycle
+          end
+
           protected
 
           ##

data/lib/google/cloud/storage/bucket/cors.rb

@@ -46,6 +46,19 @@ module Google
         #                max_age: 3600
         #   end
         #
+        # @example Retrieving the bucket's CORS rules.
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #   bucket.cors.size #=> 2
+        #   rule = bucket.cors.first
+        #   rule.origin #=> ["http://example.org"]
+        #   rule.methods #=> ["GET","POST","DELETE"]
+        #   rule.headers #=> ["X-My-Custom-Header"]
+        #   rule.max_age #=> 3600
+        #
         class Cors < DelegateClass(::Array)
           ##
           # @private Initialize a new CORS rules builder with existing CORS
@@ -118,9 +131,50 @@ module Google
             super
           end
 
+          ##
+          # # Bucket Cors Rule
+          #
+          # Represents a website CORS rule for a bucket. Accessed via
+          # {Bucket#cors}.
+          #
+          # @see https://cloud.google.com/storage/docs/cross-origin Cross-Origin
+          #   Resource Sharing (CORS)
+          #
+          # @attr [String] origin The [origin](http://tools.ietf.org/html/rfc6454)
+          #   or origins permitted for cross origin resource sharing with the
+          #   bucket. Note: "*" is permitted in the list of origins, and means
+          #   "any Origin".
+          # @attr [String] methods The list of HTTP methods permitted in cross
+          #   origin resource sharing with the bucket. (GET, OPTIONS, POST, etc)
+          #   Note: "*" is permitted in the list of methods, and means
+          #   "any method".
+          # @attr [String] headers The list of header field names to send in the
+          #   Access-Control-Allow-Headers header in the preflight response.
+          #   Indicates the custom request headers that may be used in the
+          #   actual request.
+          # @attr [String] max_age The value to send in the
+          #   Access-Control-Max-Age header in the preflight response. Indicates
+          #   how many seconds the results of a preflight request can be cached
+          #   in a preflight result cache. The default value is `1800` (30
+          #   minutes.)
+          #
+          # @example Retrieving the bucket's CORS rules.
+          #   require "google/cloud/storage"
+          #
+          #   storage = Google::Cloud::Storage.new
+          #
+          #   bucket = storage.bucket "my-bucket"
+          #   bucket.cors.size #=> 2
+          #   rule = bucket.cors.first
+          #   rule.origin #=> ["http://example.org"]
+          #   rule.methods #=> ["GET","POST","DELETE"]
+          #   rule.headers #=> ["X-My-Custom-Header"]
+          #   rule.max_age #=> 3600
+          #
           class Rule
             attr_accessor :origin, :methods, :headers, :max_age
 
+            # @private
             def initialize origin, methods, headers: nil, max_age: nil
               @origin = Array(origin)
               @methods = Array(methods)
@@ -128,6 +182,7 @@ module Google
               @max_age = (max_age || 1800)
             end
 
+            # @private
             def to_gapi
               Google::Apis::StorageV1::Bucket::CorsConfiguration.new(
                 origin: Array(origin).dup, http_method: Array(methods).dup,
@@ -135,12 +190,14 @@ module Google
               )
             end
 
+            # @private
             def self.from_gapi gapi
               new gapi.origin.dup, gapi.http_method.dup, \
                   headers: gapi.response_header.dup,
                   max_age: gapi.max_age_seconds
             end
 
+            # @private
             def freeze
               @origin.freeze
               @methods.freeze

data/lib/google/cloud/storage/bucket/lifecycle.rb

@@ -0,0 +1,355 @@
+# Copyright 2018 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
+#
+#     https://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 "delegate"
+require "google/cloud/storage/convert"
+
+module Google
+  module Cloud
+    module Storage
+      class Bucket
+        ##
+        # # Bucket Lifecycle
+        #
+        # A special-case Array for managing the Object Lifecycle Management
+        # rules for a bucket. Accessed via {Bucket#lifecycle}.
+        #
+        # @see https://cloud.google.com/storage/docs/lifecycle Object
+        #   Lifecycle Management
+        # @see https://cloud.google.com/storage/docs/managing-lifecycles
+        #   Managing Object Lifecycles
+        #
+        # @example Specifying the lifecycle management rules for a new bucket.
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.create_bucket "my-bucket" do |b|
+        #     b.lifecycle.add_set_storage_class_rule "COLDLINE", age: 10
+        #     b.lifecycle.add_delete_rule age: 30, is_live: false
+        #   end
+        #
+        # @example Retrieving a bucket's lifecycle management rules.
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.lifecycle.size #=> 2
+        #   rule = bucket.lifecycle.first
+        #   rule.action #=> "SetStorageClass"
+        #   rule.storage_class #=> "COLDLINE"
+        #   rule.age #=> 10
+        #   rule.matches_storage_class #=> ["MULTI_REGIONAL", "REGIONAL"]
+        #
+        # @example Updating the bucket's lifecycle management rules in a block.
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.lifecycle do |l|
+        #     # Remove the last rule from the array
+        #     l.pop
+        #     # Remove all rules with the given condition
+        #     l.delete_if do |r|
+        #       r.matches_storage_class.include? "NEARLINE"
+        #     end
+        #     l.add_set_storage_class_rule "COLDLINE", age: 10, is_live: true
+        #     l.add_delete_rule age: 30, is_live: false
+        #   end
+        #
+        class Lifecycle < DelegateClass(::Array)
+          include Convert
+          ##
+          # @private Initialize a new lifecycle rules builder with existing
+          # lifecycle rules, if any.
+          def initialize rules = []
+            super rules
+            @original = to_gapi.rule.map(&:to_json)
+          end
+
+          # @private
+          def changed?
+            @original != to_gapi.rule.map(&:to_json)
+          end
+
+          ##
+          # Adds a SetStorageClass lifecycle rule to the Object Lifecycle
+          # Management rules for a bucket.
+          #
+          # @see https://cloud.google.com/storage/docs/lifecycle Object
+          #   Lifecycle Management
+          # @see https://cloud.google.com/storage/docs/managing-lifecycles
+          #   Managing Object Lifecycles
+          #
+          # @param [String,Symbol] storage_class The target storage class.
+          #   Required if the type of the action is `SetStorageClass`. The
+          #   argument will be converted from symbols and lower-case to
+          #   upper-case strings.
+          # @param [Integer] age The age of a file (in days). This condition is
+          #   satisfied when a file reaches the specified age.
+          # @param [String,Date] created_before A date in RFC 3339 format with
+          #   only the date part (for instance, "2013-01-15"). This condition is
+          #   satisfied when a file is created before midnight of the specified
+          #   date in UTC.
+          # @param [Boolean] is_live Relevant only for versioned files. If the
+          #   value is `true`, this condition matches live files; if the value
+          #   is `false`, it matches archived files.
+          # @param [String,Symbol,Array<String,Symbol>] matches_storage_class
+          #   Files having any of the storage classes specified by this
+          #   condition will be matched. Values include `MULTI_REGIONAL`,
+          #   `REGIONAL`, `NEARLINE`, `COLDLINE`, `STANDARD`, and
+          #   `DURABLE_REDUCED_AVAILABILITY`. Arguments will be converted from
+          #   symbols and lower-case to upper-case strings.
+          # @param [Integer] num_newer_versions Relevant only for versioned
+          #   files. If the value is N, this condition is satisfied when there
+          #   are at least N versions (including the live version) newer than
+          #   this version of the file.
+          #
+          # @example
+          #   require "google/cloud/storage"
+          #
+          #   storage = Google::Cloud::Storage.new
+          #
+          #   bucket = storage.create_bucket "my-bucket" do |b|
+          #     b.lifecycle.add_set_storage_class_rule "COLDLINE", age: 10
+          #   end
+          #
+          def add_set_storage_class_rule storage_class, age: nil,
+                                         created_before: nil, is_live: nil,
+                                         matches_storage_class: nil,
+                                         num_newer_versions: nil
+            push Rule.new \
+              "SetStorageClass",
+              storage_class: storage_class_for(storage_class),
+              age: age, created_before: created_before, is_live: is_live,
+              matches_storage_class: storage_class_for(matches_storage_class),
+              num_newer_versions: num_newer_versions
+          end
+
+          ##
+          # Adds a SetStorageClass lifecycle rule to the Object Lifecycle
+          # Management rules for a bucket.
+          #
+          # @see https://cloud.google.com/storage/docs/lifecycle Object
+          #   Lifecycle Management
+          # @see https://cloud.google.com/storage/docs/managing-lifecycles
+          #   Managing Object Lifecycles
+          #
+          # @param [Integer] age The age of a file (in days). This condition is
+          #   satisfied when a file reaches the specified age.
+          # @param [String,Date] created_before A date in RFC 3339 format with
+          #   only the date part (for instance, "2013-01-15"). This condition is
+          #   satisfied when a file is created before midnight of the specified
+          #   date in UTC.
+          # @param [Boolean] is_live Relevant only for versioned files. If the
+          #   value is `true`, this condition matches live files; if the value
+          #   is `false`, it matches archived files.
+          # @param [String,Symbol,Array<String,Symbol>] matches_storage_class
+          #   Files having any of the storage classes specified by this
+          #   condition will be matched. Values include `MULTI_REGIONAL`,
+          #   `REGIONAL`, `NEARLINE`, `COLDLINE`, `STANDARD`, and
+          #   `DURABLE_REDUCED_AVAILABILITY`. Arguments will be converted from
+          #   symbols and lower-case to upper-case strings.
+          # @param [Integer] num_newer_versions Relevant only for versioned
+          #   files. If the value is N, this condition is satisfied when there
+          #   are at least N versions (including the live version) newer than
+          #   this version of the file.
+          #
+          # @example
+          #   require "google/cloud/storage"
+          #
+          #   storage = Google::Cloud::Storage.new
+          #
+          #   bucket = storage.create_bucket "my-bucket" do |b|
+          #     b.lifecycle.add_delete_rule age: 30, is_live: false
+          #   end
+          #
+          def add_delete_rule age: nil, created_before: nil, is_live: nil,
+                              matches_storage_class: nil,
+                              num_newer_versions: nil
+            push Rule.new \
+              "Delete",
+              age: age, created_before: created_before, is_live: is_live,
+              matches_storage_class: storage_class_for(matches_storage_class),
+              num_newer_versions: num_newer_versions
+          end
+
+          # @private
+          def to_gapi
+            Google::Apis::StorageV1::Bucket::Lifecycle.new(
+              rule: map(&:to_gapi)
+            )
+          end
+
+          # @private
+          def self.from_gapi gapi
+            gapi_list = gapi.rule if gapi
+            rules = Array(gapi_list).map do |rule_gapi|
+              Rule.from_gapi rule_gapi
+            end
+            new rules
+          end
+
+          # @private
+          def freeze
+            each(&:freeze)
+            super
+          end
+
+          ##
+          # # Bucket Lifecycle Rule
+          #
+          # Represents an Object Lifecycle Management rule for a bucket. The
+          # action for the rule will be taken when its conditions are met.
+          # Accessed via {Bucket#lifecycle}.
+          #
+          # @see https://cloud.google.com/storage/docs/lifecycle Object
+          #   Lifecycle Management
+          # @see https://cloud.google.com/storage/docs/managing-lifecycles
+          #   Managing Object Lifecycles
+          #
+          # @attr [String] action The type of action taken when the rule's
+          #   conditions are met. Currently, only `Delete` and `SetStorageClass`
+          #   are supported.
+          # @attr [String] storage_class The target storage class for the
+          #   action. Required only if the action is `SetStorageClass`.
+          # @attr [Integer] age The age of a file (in days). This condition is
+          #   satisfied when a file reaches the specified age.
+          # @attr [String,Date] created_before A date in RFC 3339 format with
+          #   only the date part (for instance, "2013-01-15"). This condition is
+          #   satisfied when a file is created before midnight of the specified
+          #   date in UTC.
+          # @attr [Boolean] is_live Relevant only for versioned files. If the
+          #   value is `true`, this condition matches live files; if the value
+          #   is `false`, it matches archived files.
+          # @attr [Array<String>] matches_storage_class Files having any of the
+          #   storage classes specified by this condition will be matched.
+          #   Values include `MULTI_REGIONAL`, `REGIONAL`, `NEARLINE`,
+          #   `COLDLINE`, `STANDARD`, and `DURABLE_REDUCED_AVAILABILITY`.
+          # @attr [Integer] num_newer_versions Relevant only for versioned
+          #   files. If the value is N, this condition is satisfied when there
+          #   are at least N versions (including the live version) newer than
+          #   this version of the file.
+          #
+          # @example Retrieving a bucket's lifecycle management rules.
+          #   require "google/cloud/storage"
+          #
+          #   storage = Google::Cloud::Storage.new
+          #   bucket = storage.bucket "my-bucket"
+          #
+          #   bucket.lifecycle.size #=> 2
+          #   rule = bucket.lifecycle.first
+          #   rule.action #=> "SetStorageClass"
+          #   rule.storage_class #=> "COLDLINE"
+          #   rule.age #=> 10
+          #   rule.matches_storage_class #=> ["MULTI_REGIONAL", "REGIONAL"]
+          #
+          # @example Updating the bucket's lifecycle rules in a block.
+          #   require "google/cloud/storage"
+          #
+          #   storage = Google::Cloud::Storage.new
+          #   bucket = storage.bucket "my-bucket"
+          #
+          #   bucket.update do |b|
+          #     b.lifecycle do |l|
+          #       # Remove the last rule from the array
+          #       l.pop
+          #       # Remove rules with the given condition
+          #       l.delete_if do |r|
+          #         r.matches_storage_class.include? "NEARLINE"
+          #       end
+          #       # Update rules
+          #       l.each do |r|
+          #         r.age = 90 if r.action == "Delete"
+          #       end
+          #       # Add a rule
+          #       l.add_set_storage_class_rule "COLDLINE", age: 10
+          #     end
+          #   end
+          #
+          class Rule
+            attr_accessor :action, :storage_class, :age, :created_before,
+                          :is_live, :matches_storage_class, :num_newer_versions
+
+            # @private
+            def initialize action, storage_class: nil, age: nil,
+                           created_before: nil, is_live: nil,
+                           matches_storage_class: nil, num_newer_versions: nil
+              @action = action
+              @storage_class = storage_class
+              @age = age
+              @created_before = created_before
+              @is_live = is_live
+              @matches_storage_class = Array(matches_storage_class)
+              @num_newer_versions = num_newer_versions
+            end
+
+            # @private
+            # @return [Google::Apis::StorageV1::Bucket::Lifecycle]
+            def to_gapi
+              condition = condition_gapi(age, created_before, is_live,
+                                         matches_storage_class,
+                                         num_newer_versions)
+              Google::Apis::StorageV1::Bucket::Lifecycle::Rule.new(
+                action: action_gapi(action, storage_class),
+                condition: condition
+              )
+            end
+
+            # @private
+            def action_gapi action, storage_class
+              Google::Apis::StorageV1::Bucket::Lifecycle::Rule::Action.new(
+                type: action, storage_class: storage_class
+              )
+            end
+
+            # @private
+            def condition_gapi age, created_before, is_live,
+                               matches_storage_class, num_newer_versions
+              Google::Apis::StorageV1::Bucket::Lifecycle::Rule::Condition.new(
+                age: age,
+                created_before: created_before,
+                is_live: is_live,
+                matches_storage_class: Array(matches_storage_class),
+                num_newer_versions: num_newer_versions
+              )
+            end
+
+            # @private
+            # @param [Google::Apis::StorageV1::Bucket::Rule] gapi
+            def self.from_gapi gapi
+              action = gapi.action
+              c = gapi.condition
+              new action.type, storage_class: action.storage_class,
+                               age: c.age,
+                               created_before: c.created_before,
+                               is_live: c.is_live,
+                               matches_storage_class: c.matches_storage_class,
+                               num_newer_versions: c.num_newer_versions
+            end
+
+            # @private
+            def freeze
+              @matches_storage_class.freeze
+              super
+            end
+          end
+        end
+      end
+    end
+  end
+end