gcloud 0.4.1 → 0.5.0

data/lib/gcloud/resource_manager/connection.rb

@@ -0,0 +1,124 @@
+#--
+# 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/version"
+require "google/api_client"
+
+module Gcloud
+  module ResourceManager
+    ##
+    # Represents the connection to Resource Manager, as well as expose the API
+    # calls.
+    class Connection #:nodoc:
+      API_VERSION = "v1beta1"
+
+      attr_accessor :credentials #:nodoc:
+
+      ##
+      # Creates a new Connection instance.
+      def initialize credentials #:nodoc:
+        @credentials = credentials
+        @client = Google::APIClient.new application_name:    "gcloud-ruby",
+                                        application_version: Gcloud::VERSION
+        @client.authorization = @credentials.client
+        @res_man = @client.discovered_api "cloudresourcemanager", API_VERSION
+      end
+
+      def list_project options = {}
+        params = { filter: options.delete(:filter),
+                   pageToken: options.delete(:token),
+                   maxResults: options.delete(:max)
+                 }.delete_if { |_, v| v.nil? }
+
+        @client.execute(
+          api_method: @res_man.projects.list,
+          parameters: params
+        )
+      end
+
+      def get_project project_id
+        @client.execute(
+          api_method: @res_man.projects.get,
+          parameters: { projectId: project_id }
+        )
+      end
+
+      def create_project project_id, name, labels
+        project_gapi = { projectId: project_id, name: name,
+                         labels: labels }.delete_if { |_, v| v.nil? }
+
+        @client.execute(
+          api_method: @res_man.projects.create,
+          body_object: project_gapi
+        )
+      end
+
+      ##
+      # Updated the project, given the project Google API Client object/hash.
+      # We try not to pass the gapi objects, but there is no PATCH, so we need
+      # to pass in a complete Project object.
+      def update_project project_gapi
+        project_id = project_gapi["projectId"]
+
+        @client.execute(
+          api_method: @res_man.projects.update,
+          parameters: { projectId: project_id },
+          body_object: project_gapi
+        )
+      end
+
+      def delete_project project_id
+        @client.execute(
+          api_method: @res_man.projects.delete,
+          parameters: { projectId: project_id }
+        )
+      end
+
+      def undelete_project project_id
+        @client.execute(
+          api_method: @res_man.projects.undelete,
+          parameters: { projectId: project_id }
+        )
+      end
+
+      def get_policy project_id
+        @client.execute(
+          api_method: @res_man.projects.get_iam_policy,
+          parameters: { resource: project_id }
+        )
+      end
+
+      def set_policy project_id, new_policy
+        @client.execute(
+          api_method: @res_man.projects.set_iam_policy,
+          parameters: { resource: project_id },
+          body_object: { policy: new_policy }
+        )
+      end
+
+      def test_permissions project_id, permissions
+        @client.execute(
+          api_method: @res_man.projects.test_iam_permissions,
+          parameters: { resource: project_id },
+          body_object: { permissions: permissions }
+        )
+      end
+
+      def inspect #:nodoc:
+        "#{self.class}(#{@project})"
+      end
+    end
+  end
+end

data/lib/gcloud/resource_manager/credentials.rb

@@ -0,0 +1,30 @@
+#--
+# 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/credentials"
+
+module Gcloud
+  module ResourceManager
+    ##
+    # Represents the Oauth2 signing logic for Resource Manager.
+    class Credentials < Gcloud::Credentials #:nodoc:
+      SCOPE = ["https://www.googleapis.com/auth/cloud-platform"]
+      PATH_ENV_VARS = %w(RESOURCE_MANAGER_KEYFILE
+                         GCLOUD_KEYFILE GOOGLE_CLOUD_KEYFILE)
+      JSON_ENV_VARS = %w(RESOURCE_MANAGER_KEYFILE_JSON GCLOUD_KEYFILE_JSON
+                         GOOGLE_CLOUD_KEYFILE_JSON)
+    end
+  end
+end

data/lib/gcloud/resource_manager/errors.rb

@@ -0,0 +1,64 @@
+#--
+# 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/errors"
+
+module Gcloud
+  module ResourceManager
+    ##
+    # Base Resource Manager exception class.
+    class Error < Gcloud::Error
+    end
+
+    ##
+    # Raised when an API call is not successful.
+    class ApiError < Error
+      ##
+      # The code of the error.
+      attr_reader :code
+
+      ##
+      # The errors encountered.
+      attr_reader :errors
+
+      def initialize message, code, errors = [] #:nodoc:
+        super message
+        @code   = code
+        @errors = errors
+      end
+
+      def self.from_response resp #:nodoc:
+        if resp.data? && resp.data["error"]
+          from_response_data resp.data["error"]
+        else
+          from_response_status resp
+        end
+      end
+
+      def self.from_response_data error #:nodoc:
+        new error["message"], error["code"], error["errors"]
+      end
+
+      def self.from_response_status resp #:nodoc:
+        if resp.status == 404
+          new "#{resp.error_message}: #{resp.request.uri.request_uri}",
+              resp.status
+        else
+          new resp.error_message, resp.status
+        end
+      end
+    end
+  end
+end

data/lib/gcloud/resource_manager/manager.rb

@@ -0,0 +1,319 @@
+#--
+# 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/resource_manager/credentials"
+require "gcloud/resource_manager/connection"
+require "gcloud/resource_manager/errors"
+require "gcloud/resource_manager/project"
+
+module Gcloud
+  module ResourceManager
+    ##
+    # = Manager
+    #
+    # Provides methods for creating, retrieving, and updating projects.
+    #
+    #   require "gcloud"
+    #
+    #   gcloud = Gcloud.new
+    #   resource_manager = gcloud.resource_manager
+    #   resource_manager.projects.each do |project|
+    #     puts projects.project_id
+    #   end
+    #
+    # See Gcloud#resource_manager
+    class Manager
+      ##
+      # The Connection object.
+      attr_accessor :connection #:nodoc:
+
+      ##
+      # Creates a new Connection instance.
+      #
+      # See Gcloud.resource_manager
+      def initialize credentials #:nodoc:
+        @connection = Connection.new credentials
+      end
+
+      ##
+      # Retrieves the projects that are visible to the user and satisfy the
+      # specified filter. This method returns projects in an unspecified order.
+      # New projects do not necessarily appear at the end of the list.
+      #
+      # === Parameters
+      #
+      # +options+::
+      #   An optional Hash for controlling additional behavior. (+Hash+)
+      # <code>options[:filter]</code>::
+      #   An expression for filtering the results of the request. Filter rules
+      #   are case insensitive. (+String+)
+      #
+      #   The fields eligible for filtering are:
+      #   * +name+
+      #   * +id+
+      #   * +labels.key+ - where +key+ is the name of a label
+      #
+      #   Some examples of using labels as filters:
+      #   * +name:*+ - The project has a name.
+      #   * +name:Howl+ - The project's name is Howl or howl.
+      #   * +name:HOWL+ - Equivalent to above.
+      #   * +NAME:howl+ - Equivalent to above.
+      #   * +labels.color:*+ - The project has the label color.
+      #   * +labels.color:red+ - The project's label color has the value red.
+      #   * <code>labels.color:red labels.size:big</code> - The project's label
+      #     color has the value red and its label size has the value big.
+      # <code>options[:token]</code>::
+      #   A previously-returned page token representing part of the larger set
+      #   of results to view. (+String+)
+      # <code>options[:max]</code>::
+      #   Maximum number of projects to return. (+Integer+)
+      #
+      # === Returns
+      #
+      # Array of Gcloud::ResourceManager::Project
+      # (See Gcloud::ResourceManager::Project::List)
+      #
+      # === Examples
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   resource_manager = gcloud.resource_manager
+      #   projects = resource_manager.projects
+      #   projects.each do |project|
+      #     puts project.project_id
+      #   end
+      #
+      # Projects can be filtered using the +filter+ option:
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   resource_manager = gcloud.resource_manager
+      #   projects = resource_manager.projects filter: "labels.env:production"
+      #   projects.each do |project|
+      #     puts project.project_id
+      #   end
+      #
+      # If you have a significant number of projects, you may need to paginate
+      # through them: (See Gcloud::ResourceManager::Project::List)
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   resource_manager = gcloud.resource_manager
+      #   projects = resource_manager.projects.all
+      #   projects.each do |project|
+      #     puts project.project_id
+      #   end
+      #
+      def projects options = {}
+        resp = connection.list_project options
+        if resp.success?
+          Project::List.from_response resp, self
+        else
+          fail ApiError.from_response(resp)
+        end
+      end
+
+      ##
+      # Retrieves the project identified by the specified +project_id+.
+      #
+      # === Parameters
+      #
+      # +project_id+::
+      #   The ID of the project. (+String+)
+      #
+      # === Returns
+      #
+      # Gcloud::ResourceManager::Project, or +nil+ if the project does not exist
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   resource_manager = gcloud.resource_manager
+      #   project = resource_manager.project "tokyo-rain-123"
+      #   project.project_id #=> "tokyo-rain-123"
+      #
+      def project project_id
+        resp = connection.get_project project_id
+        if resp.success?
+          Project.from_gapi resp.data, connection
+        else
+          nil
+        end
+      end
+
+      ##
+      # Creates a project resource.
+      #
+      # Initially, the project resource is owned by its creator exclusively. The
+      # creator can later grant permission to others to read or update the
+      # project.
+      #
+      # Several APIs are activated automatically for the project, including
+      # Google Cloud Storage.
+      #
+      # === Parameters
+      #
+      # +project_id+::
+      #   The unique, user-assigned ID of the project. It must be 6 to 30
+      #   lowercase letters, digits, or hyphens. It must start with a letter.
+      #   Trailing hyphens are prohibited. (+String+)
+      # +options+::
+      #   An optional Hash for controlling additional behavior. (+Hash+)
+      # <code>options[:name]</code>::
+      #   The user-assigned name of the project. This field is optional and can
+      #   remain unset.
+      #
+      #   Allowed characters are: lowercase and uppercase letters, numbers,
+      #   hyphen, single-quote, double-quote, space, and exclamation point.
+      #   (+String+)
+      # <code>options[:labels]</code>::
+      #   The labels associated with this project.
+      #
+      #   Label keys must be between 1 and 63 characters long and must conform
+      #   to the following regular expression:
+      #   <code>[a-z]([-a-z0-9]*[a-z0-9])?</code>.
+      #
+      #   Label values must be between 0 and 63 characters long and must conform
+      #   to the regular expression <code>([a-z]([-a-z0-9]*[a-z0-9])?)?</code>.
+      #
+      #   No more than 256 labels can be associated with a given resource.
+      #   (+Hash+)
+      #
+      # === Returns
+      #
+      # Gcloud::ResourceManager::Project
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   resource_manager = gcloud.resource_manager
+      #   project = resource_manager.create_project "tokyo-rain-123"
+      #
+      # A project can also be created with a +name+ and +labels+.
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   resource_manager = gcloud.resource_manager
+      #   project = resource_manager.create_project "tokyo-rain-123",
+      #                                             name: "Todos Development",
+      #                                             labels: {env: :development}
+      #
+      def create_project project_id, options = {}
+        resp = connection.create_project project_id,
+                                         options[:name],
+                                         options[:labels]
+        if resp.success?
+          Project.from_gapi resp.data, connection
+        else
+          fail ApiError.from_response(resp)
+        end
+      end
+
+      ##
+      # Marks the project for deletion. This method will only affect the project
+      # if the following criteria are met:
+      #
+      # * The project does not have a billing account associated with it.
+      # * The project has a lifecycle state of +ACTIVE+.
+      # * This method changes the project's lifecycle state from +ACTIVE+ to
+      #   +DELETE_REQUESTED+. The deletion starts at an unspecified time, at
+      #   which point the lifecycle state changes to +DELETE_IN_PROGRESS+.
+      #
+      # Until the deletion completes, you can check the lifecycle state by
+      # retrieving the project with Manager#project. The project remains visible
+      # to Manager#project and Manager#projects, but cannot be updated.
+      #
+      # After the deletion completes, the project is not retrievable by the
+      # Manager#project and Manager#projects methods.
+      #
+      # The caller must have modify permissions for this project.
+      #
+      # === Parameters
+      #
+      # +project_id+::
+      #   The ID of the project. (+String+)
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   resource_manager = gcloud.resource_manager
+      #   resource_manager.delete "tokyo-rain-123"
+      #
+      def delete project_id
+        resp = connection.delete_project project_id
+        if resp.success?
+          true
+        else
+          fail ApiError.from_response(resp)
+        end
+      end
+
+      ##
+      # Restores the project. You can only use this method for a project that
+      # has a lifecycle state of +DELETE_REQUESTED+. After deletion starts, as
+      # indicated by a lifecycle state of +DELETE_IN_PROGRESS+, the project
+      # cannot be restored.
+      #
+      # The caller must have modify permissions for this project.
+      #
+      # === Parameters
+      #
+      # +project_id+::
+      #   The ID of the project. (+String+)
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   resource_manager = gcloud.resource_manager
+      #   resource_manager.undelete "tokyo-rain-123"
+      #
+      def undelete project_id
+        resp = connection.undelete_project project_id
+        if resp.success?
+          true
+        else
+          fail ApiError.from_response(resp)
+        end
+      end
+
+      protected
+
+      ##
+      # Create an options hash from the projects parameters.
+      def list_projects_options filter, options
+        # Handle only sending in options
+        if filter.is_a?(::Hash) && options.empty?
+          options = filter
+          filter = nil
+        end
+        # Give named parameter priority
+        options[:filter] = filter || options[:filter]
+        options
+      end
+    end
+  end
+end