gcloud 0.11.0 → 0.12.0

data/lib/gcloud/resource_manager/policy.rb

@@ -0,0 +1,211 @@
+# 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.
+
+
+require "gcloud/errors"
+require "google/apis/cloudresourcemanager_v1beta1"
+
+module Gcloud
+  module ResourceManager
+    ##
+    # # Policy
+    #
+    # Represents a Cloud IAM Policy for the Resource Manager service.
+    #
+    # A common pattern for updating a resource's metadata, such as its Policy,
+    # is to read the current data from the service, update the data locally, and
+    # then send the modified data for writing. This pattern may result in a
+    # conflict if two or more processes attempt the sequence simultaneously. IAM
+    # solves this problem with the {Gcloud::ResourceManager::Policy#etag}
+    # property, which is used to verify whether the policy has changed since the
+    # last request. When you make a request to with an `etag` value, Cloud IAM
+    # compares the `etag` value in the request with the existing `etag` value
+    # associated with the policy. It writes the policy only if the `etag` values
+    # match.
+    #
+    # When you update a policy, first read the policy (and its current `etag`)
+    # from the service, then modify the policy locally, and then write the
+    # modified policy to the service. See
+    # {Gcloud::ResourceManager::Project#policy} and
+    # {Gcloud::ResourceManager::Project#policy=}.
+    #
+    # @see https://cloud.google.com/iam/docs/managing-policies Managing policies
+    # @see https://cloud.google.com/resource-manager/reference/rest/v1beta1/projects/setIamPolicy
+    #   projects.setIamPolicy
+    #
+    # @attr [String] etag Used to verify whether the policy has changed since
+    #   the last request. The policy will be written only if the `etag` values
+    #   match.
+    # @attr [Hash{String => Array<String>}] roles The bindings that associate
+    #   roles with an array of members. See [Understanding
+    #   Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
+    #   listing of primitive and curated roles.
+    #   See [Binding](https://cloud.google.com/resource-manager/reference/rpc/google.iam.v1#binding)
+    #   for a listing of values and patterns for members.
+    #
+    # @example
+    #   require "gcloud"
+    #
+    #   gcloud = Gcloud.new
+    #   resource_manager = gcloud.resource_manager
+    #   project = resource_manager.project "tokyo-rain-123"
+    #
+    #   policy = project.policy # API call
+    #
+    #   policy.remove "roles/owner", "user:owner@example.com" # Local call
+    #   policy.add "roles/owner", "user:newowner@example.com" # Local call
+    #   policy.roles["roles/viewer"] = ["allUsers"] # Local call
+    #
+    #   project.policy = policy # API call
+    #
+    class Policy
+      ##
+      # Alias to the Google Client API module
+      API = Google::Apis::CloudresourcemanagerV1
+
+      attr_reader :etag, :roles
+
+      ##
+      # @private Creates a Policy object.
+      def initialize etag, roles
+        @etag = etag
+        @roles = roles
+      end
+
+      ##
+      # Convenience method for adding a member to a binding on this policy.
+      # See [Understanding
+      # Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
+      # listing of primitive and curated roles.
+      # See [Binding](https://cloud.google.com/resource-manager/reference/rpc/google.iam.v1#binding)
+      # for a listing of values and patterns for members.
+      #
+      # @param [String] role_name A Cloud IAM role, such as `"roles/owner"`.
+      # @param [String] member A Cloud IAM identity, such as
+      #   `"user:owner@example.com"`.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   resource_manager = gcloud.resource_manager
+      #   project = resource_manager.project "tokyo-rain-123"
+      #
+      #   policy = project.policy # API call
+      #
+      #   policy.add "roles/owner", "user:newowner@example.com" # Local call
+      #
+      #   project.policy = policy # API call
+      #
+      def add role_name, member
+        role(role_name) << member
+      end
+
+      ##
+      # Convenience method for removing a member from a binding on this policy.
+      # See [Understanding
+      # Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
+      # listing of primitive and curated roles.
+      # See [Binding](https://cloud.google.com/resource-manager/reference/rpc/google.iam.v1#binding)
+      # for a listing of values and patterns for members.
+      #
+      # @param [String] role_name A Cloud IAM role, such as `"roles/owner"`.
+      # @param [String] member A Cloud IAM identity, such as
+      #   `"user:owner@example.com"`.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   resource_manager = gcloud.resource_manager
+      #   project = resource_manager.project "tokyo-rain-123"
+      #
+      #   policy = project.policy # API call
+      #
+      #   policy.remove "roles/owner", "user:owner@example.com" # Local call
+      #
+      #   project.policy = policy # API call
+      #
+      def remove role_name, member
+        role(role_name).delete member
+      end
+
+      ##
+      # Convenience method returning the array of members bound to a role in
+      # this policy, or an empty array if no value is present for the role in
+      # {#roles}. See [Understanding
+      # Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
+      # listing of primitive and curated roles. See
+      # [Binding](https://cloud.google.com/resource-manager/reference/rpc/google.iam.v1#binding)
+      # for a listing of values and patterns for members.
+      #
+      # @return [Array<String>] The members strings, or an empty array.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   resource_manager = gcloud.resource_manager
+      #   project = resource_manager.project "tokyo-rain-123"
+      #
+      #   policy = project.policy
+      #
+      #   policy.role("roles/viewer") << "user:viewer@example.com"
+      #
+      def role role_name
+        roles[role_name] ||= []
+      end
+
+      ##
+      # Returns a deep copy of the policy.
+      #
+      # @return [Policy]
+      #
+      def deep_dup
+        dup.tap do |p|
+          roles_dup = p.roles.each_with_object({}) do |(k, v), memo|
+            memo[k] = v.dup rescue value
+          end
+          p.instance_variable_set "@roles", roles_dup
+        end
+      end
+
+      ##
+      # @private Convert the Policy to a
+      # Google::Apis::CloudresourcemanagerV1::Policy.
+      def to_gapi
+        API::Policy.new(
+          etag: etag,
+          bindings: roles.keys.map do |role_name|
+            next if roles[role_name].empty?
+            API::Binding.new(
+              role: role_name,
+              members: roles[role_name]
+            )
+          end
+        )
+      end
+
+      ##
+      # @private New Policy from a
+      # Google::Apis::CloudresourcemanagerV1::Policy object.
+      def self.from_gapi gapi
+        roles = gapi.bindings.each_with_object({}) do |binding, memo|
+          memo[binding.role] = binding.members.to_a
+        end
+        new gapi.etag, roles
+      end
+    end
+  end
+end

data/lib/gcloud/resource_manager/project.rb

@@ -14,9 +14,9 @@
 
 
 require "time"
-require "gcloud/resource_manager/errors"
 require "gcloud/resource_manager/project/list"
 require "gcloud/resource_manager/project/updater"
+require "gcloud/resource_manager/policy"
 
 module Gcloud
   module ResourceManager
@@ -40,8 +40,8 @@ module Gcloud
     #
     class Project
       ##
-      # @private The Connection object.
-      attr_accessor :connection
+      # @private The Service object.
+      attr_accessor :service
 
       ##
       # @private The Google API Client object.
@@ -50,8 +50,8 @@ module Gcloud
       ##
       # @private Create an empty Project object.
       def initialize
-        @connection = nil
-        @gapi = {}
+        @service = nil
+        @gapi = Gcloud::ResourceManager::Service::API::Project.new
       end
 
       ##
@@ -60,21 +60,21 @@ module Gcloud
       # Trailing hyphens are prohibited. e.g. tokyo-rain-123
       #
       def project_id
-        @gapi["projectId"]
+        @gapi.project_id
       end
 
       ##
       # The number uniquely identifying the project. e.g. 415104041262
       #
       def project_number
-        @gapi["projectNumber"]
+        @gapi.project_number
       end
 
       ##
       # The user-assigned name of the project.
       #
       def name
-        @gapi["name"]
+        @gapi.name
       end
 
       ##
@@ -93,14 +93,9 @@ module Gcloud
       #   project.name = "My Project"
       #
       def name= new_name
-        ensure_connection!
-        @gapi["name"] = new_name
-        resp = connection.update_project @gapi
-        if resp.success?
-          @gapi = resp.data
-        else
-          fail ApiError.from_response(resp)
-        end
+        ensure_service!
+        @gapi.name = new_name
+        @gapi = service.update_project @gapi
       end
 
       ##
@@ -138,8 +133,7 @@ module Gcloud
       #   end
       #
       def labels
-        labels = @gapi["labels"]
-        labels = labels.to_hash if labels.respond_to? :to_hash
+        labels = @gapi.labels.to_h
         if block_given?
           yielded_labels = labels.dup
           yield yielded_labels
@@ -170,21 +164,16 @@ module Gcloud
       #   project.labels = { "env" => "production" }
       #
       def labels= new_labels
-        ensure_connection!
-        @gapi["labels"] = new_labels
-        resp = connection.update_project @gapi
-        if resp.success?
-          @gapi = resp.data
-        else
-          fail ApiError.from_response(resp)
-        end
+        ensure_service!
+        @gapi.labels = new_labels
+        @gapi = service.update_project @gapi
       end
 
       ##
       # The time that this project was created.
       #
       def created_at
-        Time.parse @gapi["createTime"]
+        Time.parse @gapi.create_time
       rescue
         nil
       end
@@ -194,16 +183,16 @@ module Gcloud
       #
       # Possible values are:
       # * `ACTIVE` - The normal and active state.
-      # * `LIFECYCLE_STATE_UNSPECIFIED` - Unspecified state. This is only
-      #   used/useful for distinguishing unset values.
       # * `DELETE_REQUESTED` - The project has been marked for deletion by the
-      #   user (by invoking DeleteProject) or by the system (Google Cloud
-      #   Platform). This can generally be reversed by invoking UndeleteProject.
+      #   user (by invoking ##delete) or by the system (Google Cloud
+      #   Platform). This can generally be reversed by invoking {#undelete}.
       # * `DELETE_IN_PROGRESS` - The process of deleting the project has begun.
       #   Reversing the deletion is no longer possible.
+      # * `LIFECYCLE_STATE_UNSPECIFIED` - Unspecified state. This is only
+      #   used/useful for distinguishing unset values.
       #
       def state
-        @gapi["lifecycleState"]
+        @gapi.lifecycle_state
       end
 
       ##
@@ -255,12 +244,10 @@ module Gcloud
       def update
         updater = Updater.from_project self
         yield updater
-        resp = connection.update_project updater.gapi
-        if resp.success?
-          @gapi = resp.data
-        else
-          fail ApiError.from_response(resp)
+        if updater.gapi.to_h != @gapi.to_h # changed
+          @gapi = service.update_project updater.gapi
         end
+        self
       end
 
       ##
@@ -276,12 +263,7 @@ module Gcloud
       #   project.reload!
       #
       def reload!
-        resp = connection.get_project project_id
-        if resp.success?
-          @gapi = resp.data
-        else
-          fail ApiError.from_response(resp)
-        end
+        @gapi = service.get_project project_id
       end
       alias_method :refresh!, :reload!
 
@@ -317,13 +299,9 @@ module Gcloud
       #   project.delete_requested? #=> true
       #
       def delete
-        resp = connection.delete_project project_id
-        if resp.success?
-          reload!
-          true
-        else
-          fail ApiError.from_response(resp)
-        end
+        service.delete_project project_id
+        reload!
+        true
       end
 
       ##
@@ -346,85 +324,92 @@ module Gcloud
       #   project.active? #=> true
       #
       def undelete
-        resp = connection.undelete_project project_id
-        if resp.success?
-          reload!
-          true
-        else
-          fail ApiError.from_response(resp)
-        end
+        service.undelete_project project_id
+        reload!
+        true
       end
 
       ##
-      # Gets the [Cloud IAM](https://cloud.google.com/iam/) access control
-      # policy. Returns a hash that conforms to the following structure:
-      #
-      #   {
-      #     "bindings" => [{
-      #       "role" => "roles/viewer",
-      #       "members" => ["serviceAccount:your-service-account"]
-      #     }],
-      #     "version" => 0,
-      #     "etag" => "CAE="
-      #   }
+      # Gets and updates the [Cloud IAM](https://cloud.google.com/iam/) access
+      # control policy for this project.
       #
       # @see https://cloud.google.com/iam/docs/managing-policies Managing
       #   Policies
+      # @see https://cloud.google.com/resource-manager/reference/rest/v1beta1/projects/setIamPolicy
+      #   projects.setIamPolicy
       #
       # @param [Boolean] force Force load the latest policy when `true`.
       #   Otherwise the policy will be memoized to reduce the number of API
       #   calls made. The default is `false`.
       #
-      # @return [Hash] See description
+      # @yield [policy] A block for updating the policy. The latest policy will
+      #   be read from the service and passed to the block. After the block
+      #   completes, the modified policy will be written to the service.
+      # @yieldparam [Policy] policy the current Cloud IAM Policy for this
+      #   project
+      #
+      # @return [Policy] the current Cloud IAM Policy for this project
       #
-      # @example Policy values are memoized by default:
+      # @example Policy values are memoized to reduce the number of API calls:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   resource_manager = gcloud.resource_manager
       #   project = resource_manager.project "tokyo-rain-123"
-      #   policy = project.policy
       #
-      #   puts policy["bindings"]
-      #   puts policy["version"]
-      #   puts policy["etag"]
+      #   policy = project.policy # API call
+      #   policy_2 = project.policy # No API call
       #
-      # @example Use the `force` option to retrieve the latest policy:
+      # @example Use `force` to retrieve the latest policy from the service:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   resource_manager = gcloud.resource_manager
       #   project = resource_manager.project "tokyo-rain-123"
-      #   policy = project.policy force: true
+      #
+      #   policy = project.policy force: true # API call
+      #   policy_2 = project.policy force: true # API call
+      #
+      # @example Update the policy by passing a block:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   resource_manager = gcloud.resource_manager
+      #   project = resource_manager.project "tokyo-rain-123"
+      #
+      #   policy = project.policy do |p|
+      #     p.add "roles/owner", "user:owner@example.com"
+      #   end # 2 API calls
       #
       def policy force: false
-        @policy = nil if force
+        @policy = nil if force || block_given?
         @policy ||= begin
-          ensure_connection!
-          resp = connection.get_policy project_id
-          fail ApiError.from_response(resp) unless resp.success?
-          policy = resp.data
-          policy = policy.to_hash if policy.respond_to? :to_hash
-          policy
+          ensure_service!
+          gapi = service.get_policy project_id
+          Policy.from_gapi gapi
         end
+        return @policy unless block_given?
+        p = @policy.deep_dup
+        yield p
+        self.policy = p
       end
 
       ##
-      # Sets the [Cloud IAM](https://cloud.google.com/iam/) access control
-      # policy.
+      # Updates the [Cloud IAM](https://cloud.google.com/iam/) access control
+      # policy for this project. The policy should be read from {#policy}.
+      # See {Gcloud::ResourceManager::Policy} for an explanation of the policy
+      # `etag` property and how to modify policies.
+      #
+      # You can also update the policy by passing a block to {#policy}, which
+      # will call this method internally after the block completes.
       #
       # @see https://cloud.google.com/iam/docs/managing-policies Managing
       #   Policies
+      # @see https://cloud.google.com/resource-manager/reference/rest/v1beta1/projects/setIamPolicy
+      #   projects.setIamPolicy
       #
-      # @param [String] new_policy A hash that conforms to the following
-      #   structure:
-      #
-      #     {
-      #       "bindings" => [{
-      #         "role" => "roles/viewer",
-      #         "members" => ["serviceAccount:your-service-account"]
-      #       }]
-      #     }
+      # @param [Policy] new_policy a new or modified Cloud IAM Policy for this
+      #   project
       #
       # @example
       #   require "gcloud"
@@ -433,23 +418,18 @@ module Gcloud
       #   resource_manager = gcloud.resource_manager
       #   project = resource_manager.project "tokyo-rain-123"
       #
-      #   viewer_policy = {
-      #     "bindings" => [{
-      #       "role" => "roles/viewer",
-      #       "members" => ["serviceAccount:your-service-account"]
-      #     }]
-      #   }
-      #   project.policy = viewer_policy
+      #   policy = project.policy # API call
+      #
+      #   policy.add "roles/owner", "user:owner@example.com"
+      #
+      #   project.policy = policy # API call
       #
       def policy= new_policy
-        ensure_connection!
-        resp = connection.set_policy project_id, new_policy
-        if resp.success?
-          @policy = resp.data
-          @policy = @policy.to_hash if @policy.respond_to? :to_hash
-        else
-          fail ApiError.from_response(resp)
-        end
+        ensure_service!
+        gapi = service.set_policy project_id, new_policy.to_gapi
+        # Convert symbols to strings for backwards compatibility.
+        # This will go away when we add a ResourceManager::Policy class.
+        @policy = Policy.from_gapi gapi
       end
 
       ##
@@ -478,30 +458,26 @@ module Gcloud
       #
       def test_permissions *permissions
         permissions = Array(permissions).flatten
-        ensure_connection!
-        resp = connection.test_permissions project_id, permissions
-        if resp.success?
-          Array(resp.data["permissions"])
-        else
-          fail ApiError.from_response(resp)
-        end
+        ensure_service!
+        gapi = service.test_permissions project_id, permissions
+        gapi.permissions
       end
 
       ##
       # @private New Change from a Google API Client object.
-      def self.from_gapi gapi, connection
+      def self.from_gapi gapi, service
         new.tap do |p|
           p.gapi = gapi
-          p.connection = connection
+          p.service = service
         end
       end
 
       protected
 
       ##
-      # Raise an error unless an active connection is available.
-      def ensure_connection!
-        fail "Must have active connection" unless connection
+      # Raise an error unless an active service is available.
+      def ensure_service!
+        fail "Must have active connection" unless service
       end
     end
   end