gcloud 0.6.3 → 0.7.0

data/lib/gcloud/pubsub/subscription.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 "gcloud/pubsub/errors"
+
+require "gcloud/errors"
 require "gcloud/pubsub/subscription/list"
 require "gcloud/pubsub/received_message"
 
 module Gcloud
   module Pubsub
     ##
-    # = Subscription
+    # # Subscription
     #
     # A named resource representing the stream of messages from a single,
-    # specific topic, to be delivered to the subscribing application.
+    # specific {Topic}, to be delivered to the subscribing application.
     #
+    # @example
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
@@ -36,31 +37,31 @@ module Gcloud
     #
     class Subscription
       ##
-      # 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::Subscription object.
+      attr_accessor :grpc
 
       ##
-      # Create an empty Subscription object.
-      def initialize #:nodoc:
-        @connection = nil
-        @gapi = {}
+      # @private Create an empty {Subscription} object.
+      def initialize
+        @service = nil
+        @grpc = Google::Pubsub::V1::Subscription.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 = {}
         sub = new.tap do |f|
-          f.gapi = nil
-          f.connection = conn
+          f.grpc = nil
+          f.service = service
         end
         sub.instance_eval do
-          @name = conn.subscription_path(name, options)
+          @name = service.subscription_path(name, options)
         end
         sub
       end
@@ -68,18 +69,15 @@ module Gcloud
       ##
       # The name of the subscription.
       def name
-        @gapi ? @gapi["name"] : @name
+        @grpc ? @grpc.name : @name
       end
 
       ##
-      # The Topic from which this subscription receives messages.
-      #
-      # === Returns
-      #
-      # Topic
+      # The {Topic} from which this subscription receives messages.
       #
-      # === Example
+      # @return [Topic]
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -89,43 +87,43 @@ module Gcloud
       #   sub.topic.name #=> "projects/my-project/topics/my-topic"
       #
       def topic
-        ensure_gapi!
-        Topic.new_lazy @gapi["topic"], connection
+        ensure_grpc!
+        Topic.new_lazy @grpc.topic, service
       end
 
       ##
       # This value is the maximum number of seconds after a subscriber receives
       # a message before the subscriber should acknowledge the message.
       def deadline
-        ensure_gapi!
-        @gapi["ackDeadlineSeconds"]
+        ensure_grpc!
+        @grpc.ack_deadline_seconds
       end
 
       ##
       # Returns the URL locating the endpoint to which messages should be
       # pushed.
       def endpoint
-        ensure_gapi!
-        @gapi["pushConfig"]["pushEndpoint"] if @gapi["pushConfig"]
+        ensure_grpc!
+        @grpc.push_config.push_endpoint if @grpc.push_config
       end
 
       ##
       # Sets the URL locating the endpoint to which messages should be pushed.
       def endpoint= new_endpoint
-        ensure_connection!
-        resp = connection.modify_push_config name, new_endpoint, {}
-        if resp.success?
-          @gapi["pushConfig"]["pushEndpoint"] = new_endpoint if @gapi
-        else
-          fail ApiError.from_response(resp)
-        end
+        ensure_service!
+        service.modify_push_config name, new_endpoint, {}
+        @grpc.push_config = Google::Pubsub::V1::PushConfig.new(
+          push_endpoint: new_endpoint,
+          attributes: {}
+        ) if @grpc
+      rescue GRPC::BadStatus => e
+        raise Error.from_error(e)
       end
 
       ##
       # Determines whether the subscription exists in the Pub/Sub service.
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -135,22 +133,22 @@ module Gcloud
       #   sub.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?
-      rescue NotFoundError
+        ensure_grpc!
+        @exists = !@grpc.nil?
+      rescue Gcloud::NotFoundError
         @exists = false
       end
 
       ##
+      # @private
       # Determines whether the subscription object was created with an
       # HTTP call.
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -159,20 +157,17 @@ module Gcloud
       #   sub = pubsub.get_subscription "my-topic-sub"
       #   sub.lazy? #=> false
       #
-      def lazy? #:nodoc:
-        @gapi.nil?
+      def lazy?
+        @grpc.nil?
       end
 
       ##
       # Deletes an existing subscription.
       # All pending messages in the subscription are immediately dropped.
       #
-      # === Returns
-      #
-      # +true+ if the subscription was deleted.
-      #
-      # === Example
+      # @return [Boolean] Returns `true` if the subscription was deleted.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -182,42 +177,33 @@ module Gcloud
       #   sub.delete
       #
       def delete
-        ensure_connection!
-        resp = connection.delete_subscription name
-        if resp.success?
-          true
-        else
-          fail ApiError.from_response(resp)
-        end
+        ensure_service!
+        service.delete_subscription name
+        return true
+      rescue GRPC::BadStatus => e
+        raise Error.from_error(e)
       end
 
       ##
       # Pulls messages from the server. Returns an empty list if there are no
       # messages available in the backlog. Raises an ApiError with status
-      # +UNAVAILABLE+ if there are too many concurrent pull requests pending
+      # `UNAVAILABLE` if there are too many concurrent pull requests pending
       # for the given subscription.
       #
-      # === Parameters
-      #
-      # +immediate+::
-      #   When +true+ the system will respond immediately even if it is not able
-      #   to return messages. When +false+ the system is allowed to wait until
-      #   it can return least one message. No messages are returned when a
-      #   request times out. The default value is +true+. (+Boolean+)
-      # +max+::
-      #   The maximum number of messages to return for this request. The Pub/Sub
-      #   system may return fewer than the number specified. The default value
-      #   is +100+, the maximum value is +1000+. (+Integer+)
-      # +autoack+::
-      #   Automatically acknowledge the message as it is pulled. The default
-      #   value is +false+. (+Boolean+)
-      #
-      # === Returns
+      # @param [Boolean] immediate When `true` the system will respond
+      #   immediately even if it is not able to return messages. When `false`
+      #   the system is allowed to wait until it can return least one message.
+      #   No messages are returned when a request times out. The default value
+      #   is `true`.
+      # @param [Integer] max The maximum number of messages to return for this
+      #   request. The Pub/Sub system may return fewer than the number
+      #   specified. The default value is `100`, the maximum value is `1000`.
+      # @param [Boolean] autoack Automatically acknowledge the message as it is
+      #   pulled. The default value is `false`.
       #
-      # Array of Gcloud::Pubsub::ReceivedMessage
-      #
-      # === Examples
+      # @return [Array<Gcloud::Pubsub::ReceivedMessage>]
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -226,8 +212,7 @@ module Gcloud
       #   sub = pubsub.subscription "my-topic-sub"
       #   sub.pull.each { |msg| msg.acknowledge! }
       #
-      # A maximum number of messages returned can also be specified:
-      #
+      # @example A maximum number of messages returned can also be specified:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -236,9 +221,7 @@ module Gcloud
       #   sub = pubsub.subscription "my-topic-sub", max: 10
       #   sub.pull.each { |msg| msg.acknowledge! }
       #
-      # The call can block until messages are available by setting the
-      # +:immediate+ option to +false+:
-      #
+      # @example The call can block until messages are available:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -249,18 +232,16 @@ module Gcloud
       #   msgs.each { |msg| msg.acknowledge! }
       #
       def pull immediate: true, max: 100, autoack: false
-        ensure_connection!
+        ensure_service!
         options = { immediate: immediate, max: max }
-        resp = connection.pull name, options
-        if resp.success?
-          messages = Array(resp.data["receivedMessages"]).map do |gapi|
-            ReceivedMessage.from_gapi gapi, self
-          end
-          acknowledge messages if autoack
-          messages
-        else
-          fail ApiError.from_response(resp)
+        list_grpc = service.pull name, options
+        messages = Array(list_grpc.received_messages).map do |msg_grpc|
+          ReceivedMessage.from_grpc msg_grpc, self
         end
+        acknowledge messages if autoack
+        messages
+      rescue GRPC::BadStatus => e
+        raise Error.from_error(e)
       rescue Faraday::TimeoutError
         []
       end
@@ -271,22 +252,15 @@ module Gcloud
       #
       #   subscription.pull immediate: false
       #
-      # === Parameters
-      #
-      # +max+::
-      #   The maximum number of messages to return for this request. The Pub/Sub
-      #   system may return fewer than the number specified. The default value
-      #   is +100+, the maximum value is +1000+. (+Integer+)
-      # +autoack+::
-      #   Automatically acknowledge the message as it is pulled. The default
-      #   value is +false+. (+Boolean+)
-      #
-      # === Returns
+      # @param [Integer] max The maximum number of messages to return for this
+      #   request. The Pub/Sub system may return fewer than the number
+      #   specified. The default value is `100`, the maximum value is `1000`.
+      # @param [Boolean] autoack Automatically acknowledge the message as it is
+      #   pulled. The default value is `false`.
       #
-      # Array of Gcloud::Pubsub::ReceivedMessage
-      #
-      # === Example
+      # @return [Array<Gcloud::Pubsub::ReceivedMessage>]
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -304,22 +278,18 @@ module Gcloud
       # Poll the backend for new messages. This runs a loop to ping the API,
       # blocking indefinitely, yielding retrieved messages as they are received.
       #
-      # === Parameters
-      #
-      # +max+::
-      #   The maximum number of messages to return for this request. The Pub/Sub
-      #   system may return fewer than the number specified. The default value
-      #   is +100+, the maximum value is +1000+. (+Integer+)
-      # +autoack+::
-      #   Automatically acknowledge the message as it is pulled. The default
-      #   value is +false+. (+Boolean+)
-      # +delay+::
-      #   The number of seconds to pause between requests when the Google Cloud
-      #   service has no messages to return. The default value is +1+.
-      #   (+Number+)
-      #
-      # === Examples
-      #
+      # @param [Integer] max The maximum number of messages to return for this
+      #   request. The Pub/Sub system may return fewer than the number
+      #   specified. The default value is `100`, the maximum value is `1000`.
+      # @param [Boolean] autoack Automatically acknowledge the message as it is
+      #   pulled. The default value is `false`.
+      # @param [Number] delay The number of seconds to pause between requests
+      #   when the Google Cloud service has no messages to return. The default
+      #   value is `1`.
+      # @yield [msg] a block for processing new messages
+      # @yieldparam [ReceivedMessage] msg the newly received message
+      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -330,9 +300,7 @@ module Gcloud
       #     # process msg
       #   end
       #
-      # The number of messages pulled per batch can be set with the +max+
-      # option:
-      #
+      # @example Limit the number of messages pulled per batch with `max`:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -343,9 +311,7 @@ module Gcloud
       #     # process msg
       #   end
       #
-      # Messages can be automatically acknowledged as they are pulled with the
-      # +autoack+ option:
-      #
+      # @example Automatically acknowledge messages with `autoack`:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -375,14 +341,10 @@ module Gcloud
       # Acknowledging a message more than once will not result in an error.
       # This is only used for messages received via pull.
       #
-      # === Parameters
-      #
-      # +messages+::
-      #   One or more ReceivedMessage objects or ack_id values.
-      #   (+ReceivedMessage+ or +ack_id+)
-      #
-      # === Example
+      # @param [ReceivedMessage, String] messages One or more {ReceivedMessage}
+      #   objects or ack_id values.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -394,13 +356,11 @@ module Gcloud
       #
       def acknowledge *messages
         ack_ids = coerce_ack_ids messages
-        ensure_connection!
-        resp = connection.acknowledge name, *ack_ids
-        if resp.success?
-          true
-        else
-          fail ApiError.from_response(resp)
-        end
+        ensure_service!
+        service.acknowledge name, *ack_ids
+        true
+      rescue GRPC::BadStatus => e
+        raise Error.from_error(e)
       end
       alias_method :ack, :acknowledge
 
@@ -411,20 +371,15 @@ module Gcloud
       # make the messages available for redelivery if the processing was
       # interrupted.
       #
-      # === Parameters
-      #
-      # +new_deadline+::
-      #   The new ack deadline in seconds from the time this request is sent
-      #   to the Pub/Sub system. Must be >= 0. For example, if the value is
-      #   +10+, the new ack deadline will expire 10 seconds after the call is
-      #   made. Specifying +0+ may immediately make the messages available for
-      #   another pull request. (+Integer+)
-      # +messages+::
-      #   One or more ReceivedMessage objects or ack_id values.
-      #   (+ReceivedMessage+ or +ack_id+)
-      #
-      # === Example
+      # @param [Integer] new_deadline The new ack deadline in seconds from the
+      #   time this request is sent to the Pub/Sub system. Must be >= 0. For
+      #   example, if the value is `10`, the new ack deadline will expire 10
+      #   seconds after the call is made. Specifying `0` may immediately make
+      #   the message available for another pull request.
+      # @param [ReceivedMessage, String] messages One or more {ReceivedMessage}
+      #   objects or ack_id values.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -436,29 +391,25 @@ module Gcloud
       #
       def delay new_deadline, *messages
         ack_ids = coerce_ack_ids messages
-        ensure_connection!
-        resp = connection.modify_ack_deadline name, ack_ids, new_deadline
-        if resp.success?
-          true
-        else
-          fail ApiError.from_response(resp)
-        end
+        ensure_service!
+        service.modify_ack_deadline name, ack_ids, new_deadline
+        return true
+      rescue GRPC::BadStatus => e
+        raise Error.from_error(e)
       end
 
       ##
       # 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+)
+      # By default, the policy values are memoized to reduce the number of API
+      # calls to the Pub/Sub service.
       #
-      # === Returns
+      # @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`.
       #
-      # A hash that conforms to the following structure:
+      # @return [Hash] Returns a hash that conforms to the following structure:
       #
       #   {
       #     "etag"=>"CAE=",
@@ -468,11 +419,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
@@ -482,9 +429,7 @@ module Gcloud
       #   puts subscription.policy["bindings"]
       #   puts subscription.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
@@ -496,22 +441,19 @@ module Gcloud
       def policy force: nil
         @policy = nil if force
         @policy ||= begin
-          ensure_connection!
-          resp = connection.get_subscription_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_subscription_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" => [{
@@ -520,8 +462,7 @@ module Gcloud
       #       }]
       #     }
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -537,28 +478,23 @@ module Gcloud
       #   subscription.policy = viewer_policy
       #
       def policy= new_policy
-        ensure_connection!
-        resp = connection.set_subscription_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_subscription_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 subscription are:
       #
@@ -569,12 +505,9 @@ module Gcloud
       #   * pubsub.subscriptions.getIamPolicy
       #   * pubsub.subscriptions.setIamPolicy
       #
-      # === Returns
-      #
-      # The permissions that have access. (Array of Strings)
-      #
-      # === Example
+      # @return [Array<String>] The permissions that have access.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -587,48 +520,45 @@ module Gcloud
       #
       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
+        ensure_service!
+        grpc = service.test_subscription_permissions name, permissions
+        grpc.permissions
+      rescue GRPC::BadStatus => e
+        raise Error.from_error(e)
       end
 
       ##
-      # New Subscription from a Google API Client object.
-      def self.from_gapi gapi, conn #:nodoc:
+      # @private New Subscription from a Google::Pubsub::V1::Subscription
+      # 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_subscription @name
-        if resp.success?
-          @gapi = resp.data
-        else
-          fail ApiError.from_response(resp)
-        end
+      # Ensures a Google::Pubsub::V1::Subscription object exists.
+      def ensure_grpc!
+        ensure_service!
+        return @grpc if @grpc
+        @grpc = service.get_subscription @name
+      rescue GRPC::BadStatus => e
+        raise Error.from_error(e)
       end
 
       ##
-      # Makes sure the values are the +ack_id+.
-      # If given several ReceivedMessage objects extract the +ack_id+ values.
+      # Makes sure the values are the `ack_id`.
+      # If given several {ReceivedMessage} objects extract the `ack_id` values.
       def coerce_ack_ids messages
         Array(messages).flatten.map do |msg|
           msg.respond_to?(:ack_id) ? msg.ack_id : msg.to_s