gcloud 0.6.3 → 0.7.0

data/lib/gcloud/pubsub/credentials.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,13 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud/credentials"
 
 module Gcloud
   module Pubsub
     ##
-    # Represents the OAuth 2.0 signing logic for Pub/Sub.
-    class Credentials < Gcloud::Credentials #:nodoc:
+    # @private Represents the OAuth 2.0 signing logic for Pub/Sub.
+    class Credentials < Gcloud::Credentials
       SCOPE = ["https://www.googleapis.com/auth/pubsub"]
       PATH_ENV_VARS = %w(PUBSUB_KEYFILE GCLOUD_KEYFILE GOOGLE_CLOUD_KEYFILE)
       JSON_ENV_VARS = %w(PUBSUB_KEYFILE_JSON GCLOUD_KEYFILE_JSON

data/lib/gcloud/pubsub/message.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,20 +12,22 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "gcloud/pubsub/errors"
+
+require "gcloud/errors"
 
 module Gcloud
   module Pubsub
     ##
-    # = Message
+    # # Message
     #
     # Represents a Pub/Sub Message.
     #
-    # Message objects are created by Topic#publish.
-    # Subscription#pull returns an array of ReceivedMessage objects, each of
-    # which contains a Message object. Each ReceivedMessage object can be
+    # Message objects are created by {Topic#publish}.
+    # {Subscription#pull} returns an array of {ReceivedMessage} objects, each of
+    # which contains a Message object. Each {ReceivedMessage} object can be
     # acknowledged and/or delayed.
     #
+    # @example
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
@@ -44,45 +45,50 @@ module Gcloud
     #
     class Message
       ##
-      # The Google API Client object.
-      attr_accessor :gapi #:nodoc:
+      # @private The gRPC Google::Pubsub::V1::PubsubMessage object.
+      attr_accessor :grpc
 
       ##
       # Create an empty Message object.
       # This can be used to publish several messages in bulk.
       def initialize data = nil, attributes = {}
-        @gapi               = {}
-        @gapi["data"]       = data
-        @gapi["attributes"] = attributes
+        # Convert attributes to strings to match the protobuf definition
+        attributes = Hash[attributes.map { |k, v| [String(k), String(v)] }]
+
+        @grpc = Google::Pubsub::V1::PubsubMessage.new(
+          data: String(data).encode("ASCII-8BIT"),
+          attributes: attributes)
       end
 
       ##
       # The received data.
       def data
-        @gapi["data"]
+        @grpc.data
       end
 
       ##
       # The received attributes.
       def attributes
-        attrs = @gapi["attributes"]
-        attrs = attrs.to_hash if attrs.respond_to? :to_hash
-        attrs
+        return @grpc.attributes.to_h if @grpc.attributes.respond_to? :to_h
+        # Enumerable doesn't have to_h on Ruby 2.0, so fallback to this
+        Hash[@grpc.attributes.to_a]
       end
 
       ##
       # The ID of this message, assigned by the server at publication time.
       # Guaranteed to be unique within the topic.
       def message_id
-        @gapi["messageId"]
+        @grpc.message_id
       end
       alias_method :msg_id, :message_id
 
       ##
-      # New Topic from a Google API Client object.
-      def self.from_gapi gapi #:nodoc:
-        new.tap do |f|
-          f.gapi = gapi
+      # @private New Message from a Google::Pubsub::V1::PubsubMessage object.
+      def self.from_grpc grpc
+        new.tap do |m|
+          m.instance_eval do
+            @grpc = grpc
+          end
         end
       end
     end

data/lib/gcloud/pubsub/project.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,24 +12,28 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud/gce"
-require "gcloud/pubsub/connection"
+require "gcloud/errors"
+require "gcloud/pubsub/service"
 require "gcloud/pubsub/credentials"
-require "gcloud/pubsub/errors"
 require "gcloud/pubsub/topic"
 
 module Gcloud
   module Pubsub
     ##
-    # = Project
+    # # Project
     #
     # Represents the project that pubsub messages are pushed to and pulled from.
-    # Topic is a named resource to which messages are sent by publishers.
-    # Subscription is a named resource representing the stream of messages from
-    # a single, specific topic, to be delivered to the subscribing application.
-    # Message is a combination of data and attributes that a publisher sends to
-    # a topic and is eventually delivered to subscribers.
+    # {Topic} is a named resource to which messages are sent by publishers.
+    # {Subscription} is a named resource representing the stream of messages
+    # from a single, specific topic, to be delivered to the subscribing
+    # application. {Message} is a combination of data and attributes that a
+    # publisher sends to a topic and is eventually delivered to subscribers.
+    #
+    # See {Gcloud#pubsub}
     #
+    # @example
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
@@ -39,24 +42,22 @@ module Gcloud
     #   topic = pubsub.topic "my-topic"
     #   topic.publish "task completed"
     #
-    # See Gcloud#pubsub
     class Project
       ##
-      # The Connection object.
-      attr_accessor :connection #:nodoc:
+      # @private The gRPC Service object.
+      attr_accessor :service
 
       ##
-      # Creates a new Connection instance.
-      def initialize project, credentials #:nodoc:
+      # @private Creates a new Connection instance.
+      def initialize project, credentials
         project = project.to_s # Always cast to a string
         fail ArgumentError, "project is missing" if project.empty?
-        @connection = Connection.new project, credentials
+        @service = Service.new project, credentials
       end
 
       # The Pub/Sub project connected to.
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new "my-todo-project",
@@ -66,12 +67,12 @@ module Gcloud
       #   pubsub.project #=> "my-todo-project"
       #
       def project
-        connection.project
+        service.project
       end
 
       ##
-      # Default project.
-      def self.default_project #:nodoc:
+      # @private Default project.
+      def self.default_project
         ENV["PUBSUB_PROJECT"] ||
           ENV["GCLOUD_PROJECT"] ||
           ENV["GOOGLE_CLOUD_PROJECT"] ||
@@ -81,67 +82,54 @@ module Gcloud
       ##
       # Retrieves topic by name.
       #
-      # === Parameters
-      #
-      # +topic_name+::
-      #   Name of a topic. (+String+)
-      # +autocreate+::
-      #   Flag to control whether the requested topic will be created if it does
-      #   not exist. Ignored if +skip_lookup+ is +true+. The default value is
-      #   +false+. (+Boolean+)
-      # +project+::
-      #   If the topic belongs to a project other than the one currently
-      #   connected to, the alternate project ID can be specified here.
-      #   (+String+)
-      # +skip_lookup+::
-      #   Optionally create a Topic object without verifying the topic resource
-      #   exists on the Pub/Sub service. Calls made on this object will raise
-      #   errors if the topic resource does not exist. Default is +false+.
-      #   (+Boolean+)
-      #
-      # === Returns
-      #
-      # Gcloud::Pubsub::Topic or nil if topic does not exist. Will return a
-      # newly created Gcloud::Pubsub::Topic if the topic does not exist and
-      # +autocreate+ is set to +true+.
-      #
-      # === Examples
-      #
+      # The topic will be created if the topic does not exist and the
+      # `autocreate` option is set to true.
+      #
+      # @param [String] topic_name Name of a topic.
+      # @param [Boolean] autocreate Flag to control whether the requested topic
+      #   will be created if it does not exist. Ignored if `skip_lookup` is
+      #   `true`. The default value is `false`.
+      # @param [String] project If the topic belongs to a project other than the
+      #   one currently connected to, the alternate project ID can be specified
+      #   here.
+      # @param [Boolean] skip_lookup Optionally create a {Topic} object without
+      #   verifying the topic resource exists on the Pub/Sub service. Calls made
+      #   on this object will raise errors if the topic resource does not exist.
+      #   Default is `false`.
+      #
+      # @return [Gcloud::Pubsub::Topic, nil] Returns `nil` if topic does not
+      #   exist. Will return a newly created{ Gcloud::Pubsub::Topic} if the
+      #   topic does not exist and `autocreate` is set to `true`.
+      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   pubsub = gcloud.pubsub
       #   topic = pubsub.topic "existing-topic"
       #
-      # By default +nil+ will be returned if the topic does not exist.
-      # the topic will be created in Pub/Sub when needed.
-      #
+      # @example By default `nil` will be returned if the topic does not exist.
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   pubsub = gcloud.pubsub
       #   topic = pubsub.topic "non-existing-topic" #=> nil
       #
-      # The topic will be created if the topic does not exist and the
-      # +autocreate+ option is set to true.
-      #
+      # @example With the `autocreate` option set to `true`.
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   pubsub = gcloud.pubsub
       #   topic = pubsub.topic "non-existing-topic", autocreate: true
       #
-      # A topic in a different project can be created using the +project+ flag.
-      #
+      # @example Create a topic in a different project with the `project` flag.
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   pubsub = gcloud.pubsub
       #   topic = pubsub.topic "another-topic", project: "another-project"
       #
-      # 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
@@ -149,16 +137,17 @@ module Gcloud
       #   topic = pubsub.topic "another-topic", skip_lookup: true
       #
       def topic topic_name, autocreate: nil, project: nil, skip_lookup: nil
-        ensure_connection!
+        ensure_service!
         options = { project: project }
-        return Topic.new_lazy(topic_name, connection, options) if skip_lookup
-        resp = connection.get_topic topic_name
-        return Topic.from_gapi(resp.data, connection) if resp.success?
-        if resp.status == 404
+        return Topic.new_lazy(topic_name, service, options) if skip_lookup
+        grpc = service.get_topic topic_name
+        Topic.from_grpc grpc, service
+      rescue GRPC::BadStatus => e
+        if e.code == 5
           return create_topic(topic_name) if autocreate
           return nil
         end
-        fail ApiError.from_response(resp)
+        raise Error.from_error(e)
       end
       alias_method :get_topic, :topic
       alias_method :find_topic, :topic
@@ -166,17 +155,11 @@ module Gcloud
       ##
       # Creates a new topic.
       #
-      # === Parameters
-      #
-      # +topic_name+::
-      #   Name of a topic. (+String+)
-      #
-      # === Returns
+      # @param [String] topic_name Name of a topic.
       #
-      # Gcloud::Pubsub::Topic
-      #
-      # === Examples
+      # @return [Gcloud::Pubsub::Topic]
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -184,34 +167,26 @@ module Gcloud
       #   topic = pubsub.create_topic "my-topic"
       #
       def create_topic topic_name
-        ensure_connection!
-        resp = connection.create_topic topic_name
-        if resp.success?
-          Topic.from_gapi resp.data, connection
-        else
-          fail ApiError.from_response(resp)
-        end
+        ensure_service!
+        grpc = service.create_topic topic_name
+        Topic.from_grpc grpc, service
+      rescue GRPC::BadStatus => e
+        raise Error.from_error(e)
       end
       alias_method :new_topic, :create_topic
 
       ##
       # Retrieves a list of topics for the given project.
       #
-      # === Parameters
+      # @param [String] token The `token` value returned by the last call to
+      #   `topics`; 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 topics to return.
       #
-      # +token+::
-      #   The +token+ value returned by the last call to +topics+; 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 topics to return. (+Integer+)
-      #
-      # === Returns
-      #
-      # Array of Gcloud::Pubsub::Topic (See Gcloud::Pubsub::Topic::List)
-      #
-      # === Examples
+      # @return [Array<Gcloud::Pubsub::Topic>] (See
+      #   {Gcloud::Pubsub::Topic::List})
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -222,9 +197,7 @@ module Gcloud
       #     puts topic.name
       #   end
       #
-      # If you have a significant number of topics, you may need to paginate
-      # through them: (See Topic::List#token)
-      #
+      # @example With pagination: (See {Topic::List#token})
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -243,40 +216,37 @@ module Gcloud
       #   end
       #
       def topics token: nil, max: nil
-        ensure_connection!
+        ensure_service!
         options = { token: token, max: max }
-        resp = connection.list_topics options
-        if resp.success?
-          Topic::List.from_response resp, connection
-        else
-          fail ApiError.from_response(resp)
-        end
+        grpc = service.list_topics options
+        Topic::List.from_grpc grpc, service
+      rescue GRPC::BadStatus => e
+        raise Error.from_error(e)
       end
       alias_method :find_topics, :topics
       alias_method :list_topics, :topics
 
       ##
-      # Publishes one or more messages to the given topic.
+      # Publishes one or more messages to the given topic. The topic will be
+      # created if the topic does previously not exist and the `autocreate`
+      # option is provided.
       #
-      # === Parameters
-      #
-      # +topic_name+::
-      #   Name of a topic. (+String+)
-      # +data+::
-      #   The message data. (+String+)
-      # +attributes+::
-      #   Optional attributes for the message. (+Hash+)
-      # <code>attributes[:autocreate]</code>::
-      #   Flag to control whether the provided topic will be created if it does
-      #   not exist.
-      #
-      # === Returns
+      # A note about auto-creating the topic: Any message published to a topic
+      # without a subscription will be lost.
       #
-      # Message object when called without a block,
-      # Array of Message objects when called with a block
+      # @param [String] topic_name Name of a topic.
+      # @param [String] data The message data.
+      # @param [Hash] attributes Optional attributes for the message.
+      # @option attributes [Boolean] :autocreate Flag to control whether the
+      #   provided topic will be created if it does not exist.
+      # @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
@@ -284,8 +254,7 @@ module Gcloud
       #
       #   msg = pubsub.publish "my-topic", "new-message"
       #
-      # Additionally, a message can be published with attributes:
-      #
+      # @example Additionally, a message can be published with attributes:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -294,8 +263,7 @@ module Gcloud
       #   msg = pubsub.publish "my-topic", "new-message", 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
@@ -307,9 +275,7 @@ module Gcloud
       #     batch.publish "new-message-3", foo: :bif
       #   end
       #
-      # Additionally, the topic will be created if the topic does previously not
-      # exist and the +autocreate+ option is provided.
-      #
+      # @example With `autocreate`:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -317,9 +283,6 @@ module Gcloud
       #
       #   msg = pubsub.publish "new-topic", "new-message", autocreate: true
       #
-      # A note about auto-creating the topic: Any message published to a topic
-      # without a subscription will be lost.
-      #
       def publish topic_name, data = nil, attributes = {}
         # Fix parameters
         if data.is_a?(::Hash) && attributes.empty?
@@ -328,7 +291,7 @@ module Gcloud
         end
         # extract autocreate option
         autocreate = attributes.delete :autocreate
-        ensure_connection!
+        ensure_service!
         batch = Topic::Batch.new data, attributes
         yield batch if block_given?
         return nil if batch.messages.count.zero?
@@ -336,34 +299,27 @@ module Gcloud
       end
 
       ##
-      # Creates a new Subscription object for the provided topic.
-      #
-      # === Parameters
-      #
-      # +topic_name+::
-      #   Name of a topic. (+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". (+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+)
-      # +autocreate+::
-      #   Flag to control whether the topic will be created if it does not
-      #   exist.
-      #
-      # === Returns
-      #
-      # Gcloud::Pubsub::Subscription
-      #
-      # === Examples
-      #
+      # Creates a new {Subscription} object for the provided topic. The topic
+      # will be created if the topic does previously not exist and the
+      # `autocreate` option is provided.
+      #
+      # @param [String] topic_name Name of a 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.
+      # @param [String] autocreate Flag to control whether the topic will be
+      #   created if it does not exist.
+      #
+      # @return [Gcloud::Pubsub::Subscription]
+      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -372,8 +328,7 @@ module Gcloud
       #   sub = pubsub.subscribe "my-topic", "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
@@ -382,9 +337,7 @@ module Gcloud
       #   sub = pubsub.subscribe "my-topic"
       #   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
@@ -394,9 +347,7 @@ module Gcloud
       #                          deadline: 120,
       #                          endpoint: "https://example.com/push"
       #
-      # Additionally, the topic will be created if the topic does previously not
-      # exist and the +autocreate+ option is provided.
-      #
+      # @example With `autocreate`:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -406,18 +357,19 @@ module Gcloud
       #
       def subscribe topic_name, subscription_name, deadline: nil, endpoint: nil,
                     autocreate: nil
-        ensure_connection!
+        ensure_service!
         options = { deadline: deadline, endpoint: endpoint }
-        resp = connection.create_subscription topic_name,
-                                              subscription_name, options
-        return Subscription.from_gapi(resp.data, connection) if resp.success?
-        if autocreate && resp.status == 404
+        grpc = service.create_subscription topic_name,
+                                           subscription_name, options
+        Subscription.from_grpc grpc, service
+      rescue GRPC::BadStatus => e
+        if autocreate && e.code == 5
           create_topic topic_name
           return subscribe(topic_name, subscription_name,
                            deadline: deadline, endpoint: endpoint,
                            autocreate: false)
         end
-        fail ApiError.from_response(resp)
+        raise Error.from_error(e)
       end
       alias_method :create_subscription, :subscribe
       alias_method :new_subscription, :subscribe
@@ -425,26 +377,19 @@ module Gcloud
       ##
       # Retrieves subscription by name.
       #
-      # === Parameters
-      #
-      # +subscription_name+::
-      #   Name of a subscription. (+String+)
-      # +project+::
-      #   If the subscription belongs to a project other than the one currently
-      #   connected to, the alternate project ID can be specified here.
-      #   (+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+)
+      # @param [String] subscription_name Name of a subscription.
+      # @param [String] project If the subscription belongs to a project other
+      #   than the one currently connected to, the alternate project ID can be
+      #   specified here.
+      # @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`.
       #
-      # === Returns
-      #
-      # Gcloud::Pubsub::Subscription or +nil+ if the subscription does not exist
-      #
-      # === Example
+      # @return [Gcloud::Pubsub::Subscription, nil] Returns `nil` if the
+      #   subscription does not exist
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -453,9 +398,7 @@ module Gcloud
       #   subscription = pubsub.subscription "my-sub"
       #   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
@@ -466,15 +409,16 @@ module Gcloud
       #   puts subscription.name
       #
       def subscription subscription_name, project: nil, skip_lookup: nil
-        ensure_connection!
+        ensure_service!
         options = { project: project }
         if skip_lookup
-          return Subscription.new_lazy(subscription_name, connection, options)
+          return Subscription.new_lazy subscription_name, service, 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)
+        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
@@ -482,24 +426,16 @@ module Gcloud
       ##
       # Retrieves a list of subscriptions for the given project.
       #
-      # === Parameters
+      # @param [String] prefix Filter results to subscriptions whose names begin
+      #   with this prefix.
+      # @param [String] token A previously-returned page token representing part
+      #   of the larger set of results to view.
+      # @param [Integer] max Maximum number of subscriptions to return.
       #
-      # +prefix+::
-      #   Filter results to subscriptions whose names begin with this prefix.
-      #   (+String+)
-      # +token+::
-      #   A previously-returned page token representing part of the larger set
-      #   of results to view. (+String+)
-      # +max+::
-      #   Maximum number of subscriptions to return. (+Integer+)
-      #
-      # === Returns
-      #
-      # Array of Gcloud::Pubsub::Subscription
-      # (See Gcloud::Pubsub::Subscription::List)
-      #
-      # === Examples
+      # @return [Array<Gcloud::Pubsub::Subscription>] (See
+      #   {Gcloud::Pubsub::Subscription::List})
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -510,9 +446,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
@@ -531,14 +465,12 @@ module Gcloud
       #   end
       #
       def subscriptions prefix: nil, token: nil, max: nil
-        ensure_connection!
+        ensure_service!
         options = { prefix: prefix, token: token, max: max }
-        resp = connection.list_subscriptions options
-        if resp.success?
-          Subscription::List.from_response resp, connection
-        else
-          fail ApiError.from_response(resp)
-        end
+        grpc = service.list_subscriptions 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
@@ -546,22 +478,23 @@ module Gcloud
       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
 
       ##
       # Call the publish API with arrays of data data and attrs.
       def publish_batch_messages topic_name, batch, autocreate = false
-        resp = connection.publish topic_name, batch.messages
-        if resp.success?
-          batch.to_gcloud_messages resp.data["messageIds"]
-        elsif autocreate && resp.status == 404
+        grpc = service.publish topic_name, batch.messages
+        batch.to_gcloud_messages Array(grpc.message_ids)
+      rescue GRPC::BadStatus => e
+        if autocreate && e.code == 5
           create_topic topic_name
           publish_batch_messages topic_name, batch, false
         else
-          fail ApiError.from_response(resp)
+          raise Error.from_error(e)
         end
       end
     end