gcloud 0.6.3 → 0.7.0

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

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "delegate"
 
 module Gcloud
@@ -24,7 +24,7 @@ module Gcloud
         ##
         # If not empty, indicates that there are more subscriptions
         # that match the request and this value should be passed to
-        # the next Gcloud::PubSub::Topic#subscriptions to continue.
+        # the next {Gcloud::Pubsub::Topic#subscriptions} to continue.
         attr_accessor :token
 
         ##
@@ -32,19 +32,21 @@ module Gcloud
         def initialize arr = [], token = nil
           super arr
           @token = token
+          @token = nil if @token == ""
         end
 
         ##
-        # New Subscription::List from a response object.
-        def self.from_response resp, conn #:nodoc:
-          subs = Array(resp.data["subscriptions"]).map do |gapi_object|
-            if gapi_object.is_a? String
-              Subscription.new_lazy gapi_object, conn
+        # @private New Subscriptions::List from a
+        # Google::Pubsub::V1::ListSubscriptionsRequest object.
+        def self.from_grpc grpc_list, service
+          subs = Array(grpc_list.subscriptions).map do |grpc|
+            if grpc.is_a? String
+              Subscription.new_lazy grpc, service
             else
-              Subscription.from_gapi gapi_object, conn
+              Subscription.from_grpc grpc, service
             end
           end
-          new subs, resp.data["nextPageToken"]
+          new subs, grpc_list.next_page_token
         end
       end
     end

data/lib/gcloud/pubsub/topic.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,18 +12,20 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "json"
-require "gcloud/pubsub/errors"
+
+require "gcloud/errors"
+require "gcloud/pubsub/topic/batch"
 require "gcloud/pubsub/topic/list"
 require "gcloud/pubsub/subscription"
 
 module Gcloud
   module Pubsub
     ##
-    # = Topic
+    # # Topic
     #
     # A named resource to which messages are published.
     #
+    # @example
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
@@ -35,30 +36,30 @@ module Gcloud
     #
     class Topic
       ##
-      # The Connection object.
-      attr_accessor :connection #:nodoc:
+      # @private The gRPC Service object.
+      attr_accessor :service
 
       ##
-      # The Google API Client object.
-      attr_accessor :gapi #:nodoc:
+      # @private The gRPC Google::Pubsub::V1::Topic object.
+      attr_accessor :grpc
 
       ##
-      # Create an empty Topic object.
-      def initialize #:nodoc:
-        @connection = nil
-        @gapi = {}
+      # @private Create an empty {Topic} object.
+      def initialize
+        @service = nil
+        @grpc = Google::Pubsub::V1::Topic.new
         @name = nil
         @exists = nil
       end
 
       ##
-      # New lazy Topic object without making an HTTP request.
-      def self.new_lazy name, conn, options = {} #:nodoc:
+      # @private New lazy {Topic} object without making an HTTP request.
+      def self.new_lazy name, service, options = {}
         new.tap do |t|
-          t.gapi = nil
-          t.connection = conn
+          t.grpc = nil
+          t.service = service
           t.instance_eval do
-            @name = conn.topic_path(name, options)
+            @name = service.topic_path(name, options)
           end
         end
       end
@@ -67,18 +68,15 @@ module Gcloud
       # The name of the topic in the form of
       # "/projects/project-identifier/topics/topic-name".
       def name
-        @gapi ? @gapi["name"] : @name
+        @grpc ? @grpc.name : @name
       end
 
       ##
       # Permanently deletes the topic.
       #
-      # === Returns
-      #
-      # +true+ if the topic was deleted.
-      #
-      # === Example
+      # @return [Boolean] Returns `true` if the topic was deleted.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -88,39 +86,30 @@ module Gcloud
       #   topic.delete
       #
       def delete
-        ensure_connection!
-        resp = connection.delete_topic name
-        if resp.success?
-          true
-        else
-          fail ApiError.from_response(resp)
-        end
+        ensure_service!
+        service.delete_topic name
+        return true
+      rescue GRPC::BadStatus => e
+        raise Error.from_error(e)
       end
 
       ##
-      # Creates a new Subscription object on the current Topic.
-      #
-      # === Parameters
-      #
-      # +subscription_name+::
-      #   Name of the new subscription. Must start with a letter, and contain
-      #   only letters ([A-Za-z]), numbers ([0-9], dashes (-), underscores (_),
-      #   periods (.), tildes (~), plus (+) or percent signs (%). It must be
-      #   between 3 and 255 characters in length, and it must not start with
-      #   "goog". (+String+)
-      # +deadline+::
-      #   The maximum number of seconds after a subscriber receives a message
-      #   before the subscriber should acknowledge the message. (+Integer+)
-      # +endpoint+::
-      #   A URL locating the endpoint to which messages should be pushed.
-      #   e.g. "https://example.com/push" (+String+)
-      #
-      # === Returns
-      #
-      # Gcloud::Pubsub::Subscription
-      #
-      # === Examples
-      #
+      # Creates a new {Subscription} object on the current Topic.
+      #
+      # @param [String] subscription_name Name of the new subscription. Must
+      #   start with a letter, and contain only letters ([A-Za-z]), numbers
+      #   ([0-9], dashes (-), underscores (_), periods (.), tildes (~), plus (+)
+      #   or percent signs (%). It must be between 3 and 255 characters in
+      #   length, and it must not start with "goog".
+      # @param [Integer] deadline The maximum number of seconds after a
+      #   subscriber receives a message before the subscriber should acknowledge
+      #   the message.
+      # @param [String] endpoint A URL locating the endpoint to which messages
+      #   should be pushed.
+      #
+      # @return [Gcloud::Pubsub::Subscription]
+      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -130,8 +119,7 @@ module Gcloud
       #   sub = topic.subscribe "my-topic-sub"
       #   puts sub.name # => "my-topic-sub"
       #
-      # The name is optional, and will be generated if not given.
-      #
+      # @example The name is optional, and will be generated if not given:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -141,9 +129,7 @@ module Gcloud
       #   sub = topic.subscribe "my-topic-sub"
       #   puts sub.name # => "generated-sub-name"
       #
-      # The subscription can be created that waits two minutes for
-      # acknowledgement and pushed all messages to an endpoint
-      #
+      # @example Wait 2 minutes for acknowledgement and push all to an endpoint:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -155,14 +141,12 @@ module Gcloud
       #                         endpoint: "https://example.com/push"
       #
       def subscribe subscription_name, deadline: nil, endpoint: nil
-        ensure_connection!
+        ensure_service!
         options = { deadline: deadline, endpoint: endpoint }
-        resp = connection.create_subscription name, subscription_name, options
-        if resp.success?
-          Subscription.from_gapi resp.data, connection
-        else
-          fail ApiError.from_response(resp)
-        end
+        grpc = service.create_subscription name, subscription_name, options
+        Subscription.from_grpc grpc, service
+      rescue GRPC::BadStatus => e
+        raise Error.from_error(e)
       end
       alias_method :create_subscription, :subscribe
       alias_method :new_subscription, :subscribe
@@ -170,22 +154,16 @@ module Gcloud
       ##
       # Retrieves subscription by name.
       #
-      # === Parameters
-      #
-      # +subscription_name+::
-      #   Name of a subscription. (+String+)
-      # +skip_lookup+::
-      #   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
+      # @param [String] subscription_name Name of a subscription.
+      # @param [Boolean] skip_lookup 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`.
       #
-      # Gcloud::Pubsub::Subscription or nil if subscription does not exist
-      #
-      # === Example
+      # @return [Gcloud::Pubsub::Subscription, nil] Returns `nil` if
+      #   the subscription does not exist.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -195,9 +173,7 @@ module Gcloud
       #   subscription = topic.subscription "my-topic-subscription"
       #   puts subscription.name
       #
-      # The lookup against the Pub/Sub service can be skipped using the
-      # +skip_lookup+ option:
-      #
+      # @example Skip the lookup against the service with `skip_lookup`:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -208,14 +184,13 @@ module Gcloud
       #   puts subscription.name
       #
       def subscription subscription_name, skip_lookup: nil
-        ensure_connection!
-        if skip_lookup
-          return Subscription.new_lazy(subscription_name, connection)
-        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)
+        ensure_service!
+        return Subscription.new_lazy subscription_name, service if skip_lookup
+        grpc = service.get_subscription subscription_name
+        Subscription.from_grpc grpc, service
+      rescue GRPC::BadStatus => e
+        return nil if e.code == 5
+        raise Error.from_error(e)
       end
       alias_method :get_subscription, :subscription
       alias_method :find_subscription, :subscription
@@ -223,21 +198,14 @@ module Gcloud
       ##
       # Retrieves a list of subscription names for the given project.
       #
-      # === Parameters
-      #
-      # +token+::
-      #   The +token+ value returned by the last call to +subscriptions+;
-      #   indicates that this is a continuation of a call, and that the system
-      #   should return the next page of data. (+String+)
-      # +max+::
-      #   Maximum number of subscriptions to return. (+Integer+)
+      # @param [String] token The `token` value returned by the last call to
+      #   `subscriptions`; indicates that this is a continuation of a call, and
+      #   that the system should return the next page of data.
+      # @param [Integer] max Maximum number of subscriptions to return.
       #
-      # === Returns
-      #
-      # Array of Subscription objects (See Subscription::List)
-      #
-      # === Examples
+      # @return [Array<Subscription>] (See {Subscription::List})
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -249,9 +217,7 @@ module Gcloud
       #     puts subscription.name
       #   end
       #
-      # If you have a significant number of subscriptions, you may need to
-      # paginate through them: (See Subscription::List#token)
-      #
+      # @example With pagination: (See {Subscription::List#token})
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -271,14 +237,12 @@ module Gcloud
       #   end
       #
       def subscriptions token: nil, max: nil
-        ensure_connection!
+        ensure_service!
         options = { token: token, max: max }
-        resp = connection.list_topics_subscriptions name, options
-        if resp.success?
-          Subscription::List.from_response resp, connection
-        else
-          fail ApiError.from_response(resp)
-        end
+        grpc = service.list_topics_subscriptions name, options
+        Subscription::List.from_grpc grpc, service
+      rescue GRPC::BadStatus => e
+        raise Error.from_error(e)
       end
       alias_method :find_subscriptions, :subscriptions
       alias_method :list_subscriptions, :subscriptions
@@ -286,20 +250,16 @@ module Gcloud
       ##
       # Publishes one or more messages to the topic.
       #
-      # === Parameters
-      #
-      # +data+::
-      #   The message data. (+String+)
-      # +attributes+::
-      #   Optional attributes for the message. (+Hash+)
-      #
-      # === Returns
-      #
-      # Message object when called without a block,
-      # Array of Message objects when called with a block
+      # @param [String] data The message data.
+      # @param [Hash] attributes Optional attributes for the message.
+      # @yield [batch] a block for publishing multiple messages in one request
+      # @yieldparam [Topic::Batch] batch the batch object
       #
-      # === Examples
+      # @return [Message, Array<Message>] Returns the published message when
+      #   called without a block, or an array of messages when called with a
+      #   block.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -308,8 +268,7 @@ module Gcloud
       #   topic = pubsub.topic "my-topic"
       #   msg = topic.publish "new-message"
       #
-      # Additionally, a message can be published with attributes:
-      #
+      # @example Additionally, a message can be published with attributes:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -320,8 +279,7 @@ module Gcloud
       #                       foo: :bar,
       #                       this: :that
       #
-      # Multiple messages can be published at the same time by passing a block:
-      #
+      # @example Multiple messages can be sent at the same time using a block:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -335,7 +293,7 @@ module Gcloud
       #   end
       #
       def publish data = nil, attributes = {}
-        ensure_connection!
+        ensure_service!
         batch = Batch.new data, attributes
         yield batch if block_given?
         return nil if batch.messages.count.zero?
@@ -345,17 +303,12 @@ module Gcloud
       ##
       # Gets the access control policy.
       #
-      # === Parameters
-      #
-      # +force+::
-      #   Force the latest policy to be retrieved from the Pub/Sub service when
-      #   +true. Otherwise the policy will be memoized to reduce the number of
-      #   API calls made to the Pub/Sub service. The default is +false+.
-      #   (+Boolean+)
+      # @param [Boolean] force Force the latest policy to be retrieved from the
+      #   Pub/Sub service when `true`. Otherwise the policy will be memoized to
+      #   reduce the number of API calls made to the Pub/Sub service. The
+      #   default is `false`.
       #
-      # === Returns
-      #
-      # A hash that conforms to the following structure:
+      # @return [Hash] Returns a hash that conforms to the following structure:
       #
       #   {
       #     "etag"=>"CAE=",
@@ -365,11 +318,7 @@ module Gcloud
       #     }]
       #   }
       #
-      # === Examples
-      #
-      # By default, the policy values are memoized to reduce the number of API
-      # calls to the Pub/Sub service.
-      #
+      # @example Policy values are memoized to reduce the number of API calls:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -379,9 +328,7 @@ module Gcloud
       #   puts topic.policy["bindings"]
       #   puts topic.policy["rules"]
       #
-      # To retrieve the latest policy from the Pub/Sub service, use the +force+
-      # flag.
-      #
+      # @example Use `force` to retrieve the latest policy from the service:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -393,22 +340,19 @@ module Gcloud
       def policy force: nil
         @policy = nil if force
         @policy ||= begin
-          ensure_connection!
-          resp = connection.get_topic_policy name
-          fail ApiError.from_response(resp) unless resp.success?
-          policy = resp.data
-          policy = policy.to_hash if policy.respond_to? :to_hash
-          policy
+          ensure_service!
+          grpc = service.get_topic_policy name
+          JSON.parse(Google::Iam::V1::Policy.encode_json(grpc))
+        rescue GRPC::BadStatus => e
+          raise Error.from_error(e)
         end
       end
 
       ##
       # Sets the access control policy.
       #
-      # === Parameters
-      #
-      # +new_policy+::
-      #   A hash that conforms to the following structure:
+      # @param [String] new_policy A hash that conforms to the following
+      #   structure:
       #
       #     {
       #       "bindings" => [{
@@ -417,8 +361,7 @@ module Gcloud
       #       }]
       #     }
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -434,28 +377,23 @@ module Gcloud
       #   topic.policy = viewer_policy
       #
       def policy= new_policy
-        ensure_connection!
-        resp = connection.set_topic_policy name, new_policy
-        if resp.success?
-          @policy = resp.data["policy"]
-          @policy = @policy.to_hash if @policy.respond_to? :to_hash
-        else
-          fail ApiError.from_response(resp)
-        end
+        ensure_service!
+        grpc = service.set_topic_policy name, new_policy
+        @policy = JSON.parse(Google::Iam::V1::Policy.encode_json(grpc))
+      rescue GRPC::BadStatus => e
+        raise Error.from_error(e)
       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.
+      # Tests the specified permissions against the [Cloud
+      # IAM](https://cloud.google.com/iam/) access control policy.
       #
-      # === Parameters
+      # @see https://cloud.google.com/iam/docs/managing-policies Managing
+      #   Policies
       #
-      # +permissions+::
-      #   The set of permissions to check access for. Permissions with wildcards
-      #   (such as +*+ or +storage.*+) are not allowed.
-      #   (String or Array of Strings)
+      # @param [String, Array<String>] permissions The set of permissions to
+      #   check access for. Permissions with wildcards (such as `*` or
+      #   `storage.*`) are not allowed.
       #
       #   The permissions that can be checked on a topic are:
       #
@@ -467,12 +405,9 @@ module Gcloud
       #   * pubsub.topics.getIamPolicy
       #   * pubsub.topics.setIamPolicy
       #
-      # === Returns
-      #
-      # The permissions that have access. (Array of Strings)
-      #
-      # === Example
+      # @return [Array<Strings>] The permissions that have access.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -485,20 +420,18 @@ module Gcloud
       #
       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
+        permissions = Array(permissions).flatten
+        ensure_service!
+        grpc = service.test_topic_permissions name, permissions
+        grpc.permissions
+      rescue GRPC::BadStatus => e
+        raise Error.from_error(e)
       end
 
       ##
       # Determines whether the topic exists in the Pub/Sub service.
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -508,19 +441,19 @@ module Gcloud
       #   topic.exists? #=> true
       #
       def exists?
-        # Always true if we have a gapi object
-        return true unless @gapi.nil?
+        # Always true if we have a grpc object
+        return true unless @grpc.nil?
         # If we have a value, return it
         return @exists unless @exists.nil?
-        ensure_gapi!
-        @exists = !@gapi.nil?
+        ensure_grpc!
+        @exists = !@grpc.nil?
       end
 
       ##
+      # @private
       # Determines whether the topic object was created with an HTTP call.
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -529,98 +462,46 @@ module Gcloud
       #   topic = pubsub.topic "my-topic"
       #   topic.lazy? #=> false
       #
-      def lazy? #:nodoc:
-        @gapi.nil?
+      def lazy?
+        @grpc.nil?
       end
 
       ##
-      # New Topic from a Google API Client object.
-      def self.from_gapi gapi, conn #:nodoc:
+      # @private New Topic from a Google::Pubsub::V1::Topic object.
+      def self.from_grpc grpc, service
         new.tap do |f|
-          f.gapi = gapi
-          f.connection = conn
+          f.grpc = grpc
+          f.service = service
         end
       end
 
       protected
 
       ##
-      # Raise an error unless an active connection is available.
-      def ensure_connection!
-        fail "Must have active connection" unless connection
+      # @private Raise an error unless an active connection to the service is
+      # available.
+      def ensure_service!
+        fail "Must have active connection to service" unless service
       end
 
       ##
-      # Ensures a Google API object exists.
-      def ensure_gapi!
-        ensure_connection!
-        return @gapi if @gapi
-        resp = connection.get_topic @name
-        @gapi = resp.data if resp.success?
+      # Ensures a Google::Pubsub::V1::Topic object exists.
+      def ensure_grpc!
+        ensure_service!
+        return @grpc if @grpc
+        @grpc = service.get_topic @name
+      rescue GRPC::BadStatus => e
+        return nil if e.code == 5
+        raise Error.from_error(e)
       end
 
       ##
       # Call the publish API with arrays of data data and attrs.
       def publish_batch_messages batch
-        resp = connection.publish name, batch.messages
-        if resp.success?
-          batch.to_gcloud_messages resp.data["messageIds"]
-        else
-          fail ApiError.from_response(resp)
-        end
-      end
-
-      ##
-      # Batch object used to publish multiple messages at once.
-      class Batch
-        ##
-        # The messages to publish
-        attr_reader :messages #:nodoc:
-
-        ##
-        # Create a new instance of the object.
-        def initialize data = nil, attributes = {} #:nodoc:
-          @messages = []
-          @mode = :batch
-          return if data.nil?
-          @mode = :single
-          publish data, attributes
-        end
-
-        ##
-        # Add multiple messages to the topic.
-        # All messages added will be published at once.
-        # See Gcloud::Pubsub::Topic#publish
-        def publish data, attributes = {}
-          @messages << [data, attributes]
-        end
-
-        ##
-        # Create Message objects with message ids.
-        def to_gcloud_messages message_ids #:nodoc:
-          msgs = @messages.zip(Array(message_ids)).map do |arr, id|
-            Message.from_gapi "data"       => arr[0],
-                              "attributes" => jsonify_hash(arr[1]),
-                              "messageId"  => id
-          end
-          # Return just one Message if a single publish,
-          # otherwise return the array of Messages.
-          if @mode == :single && msgs.count <= 1
-            msgs.first
-          else
-            msgs
-          end
-        end
-
-        protected
-
-        ##
-        # Make the hash look like it was returned from the Cloud API.
-        def jsonify_hash hash
-          hash = (hash || {}).to_h
-          return hash if hash.empty?
-          JSON.parse(JSON.dump(hash))
-        end
+        grpc = service.publish name, batch.messages
+        batch.to_gcloud_messages Array(grpc.message_ids)
+      rescue GRPC::BadStatus => e
+        raise Error.from_error(e)
       end
     end
   end