gcloud 0.4.1 → 0.5.0

data/lib/gcloud/pubsub/subscription.rb

@@ -90,9 +90,7 @@ module Gcloud
       #
       def topic
         ensure_gapi!
-        # Always disable autocreate, we don't want to recreate a topic that
-        # was intentionally deleted.
-        Topic.new_lazy @gapi["topic"], connection, autocreate: false
+        Topic.new_lazy @gapi["topic"], connection
       end
 
       ##
@@ -193,9 +191,6 @@ module Gcloud
         end
       end
 
-      # rubocop:disable Metrics/MethodLength
-      # Disabled rubocop because these lines are needed.
-
       ##
       # Pulls messages from the server. Returns an empty list if there are no
       # messages available in the backlog. Raises an ApiError with status
@@ -271,8 +266,6 @@ module Gcloud
         []
       end
 
-      # rubocop:enable Metrics/MethodLength
-
       ##
       # Pulls from the server while waiting for messages to become available.
       # This is the same as:
@@ -476,11 +469,11 @@ module Gcloud
       # A hash that conforms to the following structure:
       #
       #   {
+      #     "etag"=>"CAE=",
       #     "bindings" => [{
       #       "role" => "roles/viewer",
       #       "members" => ["serviceAccount:your-service-account"]
-      #     }],
-      #     "rules" => []
+      #     }]
       #   }
       #
       # === Examples
@@ -513,7 +506,7 @@ module Gcloud
         @policy ||= begin
           ensure_connection!
           resp = connection.get_subscription_policy name
-          policy = resp.data["policy"]
+          policy = resp.data
           policy = policy.to_hash if policy.respond_to? :to_hash
           policy
         end
@@ -531,8 +524,7 @@ module Gcloud
       #       "bindings" => [{
       #         "role" => "roles/viewer",
       #         "members" => ["serviceAccount:your-service-account"]
-      #       }],
-      #       "rules" => []
+      #       }]
       #     }
       #
       # === Example
@@ -562,6 +554,46 @@ module Gcloud
         end
       end
 
+      ##
+      # Tests the specified permissions against the {Cloud
+      # IAM}[https://cloud.google.com/iam/] access control policy. See
+      # {Managing Policies}[https://cloud.google.com/iam/docs/managing-policies]
+      # for more information.
+      #
+      # === Parameters
+      #
+      # +permissions+::
+      #   The set of permissions to check access for. Permissions with wildcards
+      #   (such as +*+ or +storage.*+) are not allowed.
+      #   (String or Array of Strings)
+      #
+      # === Returns
+      #
+      # The permissions that have access. (Array of Strings)
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   pubsub = gcloud.pubsub
+      #   sub = pubsub.subscription "my-subscription"
+      #   perms = sub.test_permissions "projects.subscriptions.list",
+      #                                "projects.subscriptions.pull"
+      #   perms.include? "projects.subscriptions.list" #=> true
+      #   perms.include? "projects.subscriptions.pull" #=> false
+      #
+      def test_permissions *permissions
+        permissions = Array(permissions).flatten
+        ensure_connection!
+        resp = connection.test_subscription_permissions name, permissions
+        if resp.success?
+          Array(resp.data["permissions"])
+        else
+          fail ApiError.from_response(resp)
+        end
+      end
+
       ##
       # New Subscription from a Google API Client object.
       def self.from_gapi gapi, conn #:nodoc:

data/lib/gcloud/pubsub/subscription/list.rb

@@ -13,6 +13,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "delegate"
+
 module Gcloud
   module Pubsub
     class Subscription

data/lib/gcloud/pubsub/topic.rb

@@ -48,20 +48,17 @@ module Gcloud
         @connection = nil
         @gapi = {}
         @name = nil
-        @autocreate = nil
         @exists = nil
       end
 
       ##
       # New lazy Topic object without making an HTTP request.
       def self.new_lazy name, conn, options = {} #:nodoc:
-        options[:autocreate] = true if options[:autocreate].nil?
         new.tap do |t|
           t.gapi = nil
           t.connection = conn
           t.instance_eval do
             @name = conn.topic_path(name, options)
-            @autocreate = options[:autocreate]
           end
         end
       end
@@ -167,27 +164,28 @@ module Gcloud
         else
           fail ApiError.from_response(resp)
         end
-      rescue Gcloud::Pubsub::NotFoundError => e
-        retry if lazily_create_topic!
-        raise e
       end
       alias_method :create_subscription, :subscribe
       alias_method :new_subscription, :subscribe
 
       ##
       # Retrieves subscription by name.
-      # The difference between this method and Topic#get_subscription is
-      # that this method does not make an API call to Pub/Sub to verify the
-      # subscription exists.
       #
       # === Parameters
       #
       # +subscription_name+::
       #   Name of a subscription. (+String+)
+      # +options+::
+      #   An optional Hash for controlling additional behavior. (+Hash+)
+      # <code>options[:skip_lookup]</code>::
+      #   Optionally create a Subscription object without verifying the
+      #   subscription resource exists on the Pub/Sub service. Calls made on
+      #   this object will raise errors if the service resource does not exist.
+      #   Default is +false+. (+Boolean+)
       #
       # === Returns
       #
-      # Gcloud::Pubsub::Subscription
+      # Gcloud::Pubsub::Subscription or nil if subscription does not exist
       #
       # === Example
       #
@@ -200,48 +198,30 @@ module Gcloud
       #   subscription = topic.subscription "my-topic-subscription"
       #   puts subscription.name
       #
-      def subscription subscription_name
-        ensure_connection!
-
-        Subscription.new_lazy subscription_name, connection
-      end
-
-      ##
-      # Retrieves a subscription by name.
-      # The difference between this method and Topic#subscription is that
-      # this method makes an API call to Pub/Sub to verify the subscription
-      # exists.
-      #
-      # === Parameters
-      #
-      # +subscription_name+::
-      #   Name of a subscription. (+String+)
-      #
-      # === Returns
-      #
-      # Gcloud::Pubsub::Subscription or nil if subscription does not exist
-      #
-      # === Example
+      # The lookup against the Pub/Sub service can be skipped using the
+      # +skip_lookup+ option:
       #
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   pubsub = gcloud.pubsub
       #
-      #   topic = pubsub.topic "my-topic"
-      #   subscription = topic.get_subscription "my-topic-subscription"
+      #   # No API call is made to retrieve the subscription information.
+      #   subscription = pubsub.subscription "my-sub", skip_lookup: true
       #   puts subscription.name
       #
-      def get_subscription subscription_name
+      def subscription subscription_name, options = {}
         ensure_connection!
-        resp = connection.get_subscription subscription_name
-        if resp.success?
-          Subscription.from_gapi resp.data, connection
-        else
-          nil
+        if options[:skip_lookup]
+          return Subscription.new_lazy(subscription_name, connection, options)
         end
+        resp = connection.get_subscription subscription_name
+        return Subscription.from_gapi(resp.data, connection) if resp.success?
+        return nil if resp.status == 404
+        fail ApiError.from_response(resp)
       end
-      alias_method :find_subscription, :get_subscription
+      alias_method :get_subscription, :subscription
+      alias_method :find_subscription, :subscription
 
       ##
       # Retrieves a list of subscription names for the given project.
@@ -259,7 +239,7 @@ module Gcloud
       #
       # === Returns
       #
-      # Array of Subscription objects (Subscription::List)
+      # Array of Subscription objects (See Subscription::List)
       #
       # === Examples
       #
@@ -364,9 +344,6 @@ module Gcloud
         yield batch if block_given?
         return nil if batch.messages.count.zero?
         publish_batch_messages batch
-      rescue Gcloud::Pubsub::NotFoundError => e
-        retry if lazily_create_topic!
-        raise e
       end
 
       ##
@@ -387,11 +364,11 @@ module Gcloud
       # A hash that conforms to the following structure:
       #
       #   {
+      #     "etag"=>"CAE=",
       #     "bindings" => [{
       #       "role" => "roles/viewer",
       #       "members" => ["serviceAccount:your-service-account"]
-      #     }],
-      #     "rules" => []
+      #     }]
       #   }
       #
       # === Examples
@@ -424,7 +401,7 @@ module Gcloud
         @policy ||= begin
           ensure_connection!
           resp = connection.get_topic_policy name
-          policy = resp.data["policy"]
+          policy = resp.data
           policy = policy.to_hash if policy.respond_to? :to_hash
           policy
         end
@@ -442,8 +419,7 @@ module Gcloud
       #       "bindings" => [{
       #         "role" => "roles/viewer",
       #         "members" => ["serviceAccount:your-service-account"]
-      #       }],
-      #       "rules" => []
+      #       }]
       #     }
       #
       # === Example
@@ -473,6 +449,46 @@ module Gcloud
         end
       end
 
+      ##
+      # Tests the specified permissions against the {Cloud
+      # IAM}[https://cloud.google.com/iam/] access control policy. See
+      # {Managing Policies}[https://cloud.google.com/iam/docs/managing-policies]
+      # for more information.
+      #
+      # === Parameters
+      #
+      # +permissions+::
+      #   The set of permissions to check access for. Permissions with wildcards
+      #   (such as +*+ or +storage.*+) are not allowed.
+      #   (String or Array of Strings)
+      #
+      # === Returns
+      #
+      # The permissions that have access. (Array of Strings)
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   pubsub = gcloud.pubsub
+      #   topic = pubsub.topic "my-topic"
+      #   perms = topic.test_permissions "projects.topic.list",
+      #                                  "projects.topic.publish"
+      #   perms.include? "projects.topic.list" #=> true
+      #   perms.include? "projects.topic.publish" #=> false
+      #
+      def test_permissions *permissions
+        permissions = Array(permissions).flatten
+        ensure_connection!
+        resp = connection.test_topic_permissions name, permissions
+        if resp.success?
+          Array(resp.data["permissions"])
+        else
+          fail ApiError.from_response(resp)
+        end
+      end
+
       ##
       # Determines whether the topic exists in the Pub/Sub service.
       #
@@ -512,29 +528,6 @@ module Gcloud
         @gapi.nil?
       end
 
-      # rubocop:disable Style/TrivialAccessors
-      # Disabled rubocop because you can't use "?" in an attr.
-
-      ##
-      # Determines whether the lazy topic object should create a topic on the
-      # Pub/Sub service.
-      #
-      # === Example
-      #
-      #   require "gcloud"
-      #
-      #   gcloud = Gcloud.new
-      #   pubsub = gcloud.pubsub
-      #
-      #   topic = pubsub.topic "my-topic"
-      #   topic.autocreate? #=> true
-      #
-      def autocreate? #:nodoc:
-        @autocreate
-      end
-
-      # rubocop:enable Style/TrivialAccessors
-
       ##
       # New Topic from a Google API Client object.
       def self.from_gapi gapi, conn #:nodoc:
@@ -561,18 +554,6 @@ module Gcloud
         @gapi = resp.data if resp.success?
       end
 
-      ##
-      def lazily_create_topic!
-        if lazy? && autocreate?
-          resp = connection.create_topic name
-          if resp.success?
-            @gapi = resp.data
-            return true
-          end
-        end
-        nil
-      end
-
       ##
       # Call the publish API with arrays of data data and attrs.
       def publish_batch_messages batch

data/lib/gcloud/pubsub/topic/list.rb

@@ -13,6 +13,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "delegate"
+
 module Gcloud
   module Pubsub
     class Topic

data/lib/gcloud/resource_manager.rb

@@ -0,0 +1,244 @@
+# 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.
+
+require "gcloud"
+require "gcloud/resource_manager/manager"
+
+#--
+# Google Cloud Resource Manager
+module Gcloud
+  ##
+  # Creates a new +Project+ instance connected to the Resource Manager service.
+  # Each call creates a new connection.
+  #
+  # === Parameters
+  #
+  # +keyfile+::
+  #   Keyfile downloaded from Google Cloud. If file path the file must be
+  #   readable. (+String+ or +Hash+)
+  # +options+::
+  #   An optional Hash for controlling additional behavior. (+Hash+)
+  # <code>options[:scope]</code>::
+  #   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]. (+String+
+  #   or +Array+)
+  #
+  #   The default scope is:
+  #
+  #   * +https://www.googleapis.com/auth/cloud-platform+
+  #
+  # === Returns
+  #
+  # Gcloud::ResourceManager::Manager
+  #
+  # === Example
+  #
+  #   require "gcloud/resource_manager"
+  #
+  #   resource_manager = Gcloud.resource_manager
+  #   resource_manager.projects.each do |project|
+  #     puts projects.project_id
+  #   end
+  #
+  def self.resource_manager keyfile = nil, options = {}
+    if keyfile.nil?
+      credentials = Gcloud::ResourceManager::Credentials.default options
+    else
+      credentials = Gcloud::ResourceManager::Credentials.new keyfile, options
+    end
+    Gcloud::ResourceManager::Manager.new credentials
+  end
+
+  # rubocop:disable Metrics/LineLength
+  # Disabled because there are links in the docs that are long.
+
+  ##
+  # = Google Cloud Resource Manager
+  #
+  # The Resource Manager API provides methods that you can use to
+  # programmatically manage your projects in the Google Cloud Platform. You may
+  # be familiar with managing projects in the {Developers
+  # Console}[https://developers.google.com/console/help/new/]. With this API you
+  # can do the following:
+  #
+  # * Get a list of all projects associated with an account
+  # * Create new projects
+  # * Update existing projects
+  # * Delete projects
+  # * Undelete, or recover, projects that you don't want to delete
+  #
+  # The Resource Manager API is a Beta release and is not covered by any SLA or
+  # deprecation policy and may be subject to backward-incompatible changes.
+  #
+  # == Accessing the Service
+  #
+  # Currently, the full functionality of the Resource Manager API is available
+  # only to whitelisted users. (Contact your account manager or a member of the
+  # Google Cloud sales team if you are interested in access.) Read-only methods
+  # such as ResourceManager::Manager#projects and
+  # ResourceManager::Manager#project are accessible to any user who enables the
+  # Resource Manager API in the {Developers
+  # Console}[https://console.developers.google.com].
+  #
+  # == Authentication
+  #
+  # The Resource Manager API currently requires authentication of a {User
+  # Account}[https://developers.google.com/identity/protocols/OAuth2], and
+  # cannot currently be accessed with a {Service
+  # Account}[https://developers.google.com/identity/protocols/OAuth2ServiceAccount].
+  # To use a User Account install the {Google Cloud
+  # SDK}[http://cloud.google.com/sdk] and authenticate with the following:
+  #
+  #   $ gcloud auth login
+  #
+  # Also make sure all +GCLOUD+ environment variables are cleared of any service
+  # accounts. Then gcloud will be able to detect the user authentication and
+  # connect with those credentials.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   resource_manager = gcloud.resource_manager
+  #
+  # == Listing Projects
+  #
+  # Project is a collection of settings, credentials, and metadata about the
+  # application or applications you're working on. You can retrieve and inspect
+  # all projects that you have permissions to. (See Manager#projects)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   resource_manager = gcloud.resource_manager
+  #   resource_manager.projects.each do |project|
+  #     puts projects.project_id
+  #   end
+  #
+  # == Managing Projects with Labels
+  #
+  # Labels can be added to or removed from projects. (See Project#labels)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   resource_manager = gcloud.resource_manager
+  #   project = resource_manager.project "tokyo-rain-123"
+  #   # Label the project as production
+  #   project.update do |p|
+  #     p.labels["env"] = "production"
+  #   end
+  #
+  # Projects can then be filtered by labels. (See Manager#projects)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   resource_manager = gcloud.resource_manager
+  #   # Find only the productions projects
+  #   projects = resource_manager.projects filter: "labels.env:production"
+  #   projects.each do |project|
+  #     puts project.project_id
+  #   end
+  #
+  # == Creating a Project
+  #
+  # You can also use the API to create new projects. (See
+  # Manager#create_project)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   resource_manager = gcloud.resource_manager
+  #   project = resource_manager.create_project "tokyo-rain-123",
+  #                                             name: "Todos Development",
+  #                                             labels: {env: :development}
+  #
+  # == Deleting a Project
+  #
+  # You can delete projects when they are no longer needed. (See
+  # Manager#delete and Project#delete)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   resource_manager = gcloud.resource_manager
+  #   resource_manager.delete "tokyo-rain-123"
+  #
+  # == Undeleting a Project
+  #
+  # You can also restore a deleted project within the waiting period that
+  # starts when the project was deleted. Restoring a project returns it to the
+  # state it was in prior to being deleted. (See Manager#undelete and
+  # Project#undelete)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   resource_manager = gcloud.resource_manager
+  #   resource_manager.undelete "tokyo-rain-123"
+  #
+  # == Managing IAM Policies
+  #
+  # Google Cloud Identity and Access Management ({Cloud
+  # IAM}[https://cloud.google.com/iam/]) access control policies can be managed
+  # on projects. These policies allow project owners to manage _who_ (identity)
+  # has access to _what_ (role). See {Cloud IAM
+  # Overview}[https://cloud.google.com/iam/docs/overview] for more information.
+  #
+  # A project's access control policy can be retrieved. (See Project#policy)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   resource_manager = gcloud.resource_manager
+  #   project = resource_manager.project "tokyo-rain-123"
+  #   policy = project.policy
+  #
+  # A project's access control policy can also be set. (See Project#policy=)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   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
+  #
+  # And permissions can be tested on a project. (See Project#test_permissions)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   resource_manager = gcloud.resource_manager
+  #   project = resource_manager.project "tokyo-rain-123"
+  #   perms = project.test_permissions "resourcemanager.projects.get",
+  #                                    "resourcemanager.projects.delete"
+  #   perms.include? "resourcemanager.projects.get"    #=> true
+  #   perms.include? "resourcemanager.projects.delete" #=> false
+  #
+  # For more information about using access control policies see {Managing
+  # Policies}[https://cloud.google.com/iam/docs/managing-policies].
+  #
+  module ResourceManager
+  end
+
+  # rubocop:enable Metrics/LineLength
+end