gcloud 0.4.1 → 0.5.0

data/lib/gcloud/pubsub/connection.rb

@@ -101,6 +101,14 @@ module Gcloud
         )
       end
 
+      def test_topic_permissions topic_name, permissions, options = {}
+        @client.execute(
+          api_method: @pubsub.projects.topics.test_iam_permissions,
+          parameters: { resource: topic_path(topic_name, options) },
+          body_object: { permissions: permissions }
+        )
+      end
+
       ##
       # Creates a subscription on a given topic for a given subscriber.
       def create_subscription topic, subscription_name, options = {}
@@ -177,6 +185,16 @@ module Gcloud
         )
       end
 
+      def test_subscription_permissions subscription_name,
+                                        permissions, options = {}
+        @client.execute(
+          api_method: @pubsub.projects.subscriptions.test_iam_permissions,
+          parameters: {
+            resource: subscription_path(subscription_name, options) },
+          body_object: { permissions: permissions }
+        )
+      end
+
       ##
       # Adds one or more messages to the topic.
       # Returns NOT_FOUND if the topic does not exist.
@@ -188,7 +206,7 @@ module Gcloud
         end
         @client.execute(
           api_method:  @pubsub.projects.topics.publish,
-          parameters:  { topic: topic },
+          parameters:  { topic: topic_path(topic) },
           body_object: { messages: gapi_msgs }
         )
       end
@@ -264,7 +282,7 @@ module Gcloud
         endpoint   = options[:endpoint]
         attributes = hashify options[:attributes]
 
-        data = { topic: topic }
+        data = { topic: topic_path(topic) }
         data[:ackDeadlineSeconds] = deadline if deadline
         if endpoint
           data[:pushConfig] = { pushEndpoint: endpoint,

data/lib/gcloud/pubsub/project.rb

@@ -80,42 +80,6 @@ module Gcloud
 
       ##
       # Retrieves topic by name.
-      # The difference between this method and Project#topic is that this
-      # method makes an API call to Pub/Sub to verify the topic exists.
-      #
-      # === Parameters
-      #
-      # +topic_name+::
-      #   Name of a topic. (+String+)
-      #
-      # === Returns
-      #
-      # Gcloud::Pubsub::Topic or nil if topic does not exist
-      #
-      # === Example
-      #
-      #   require "gcloud"
-      #
-      #   gcloud = Gcloud.new
-      #   pubsub = gcloud.pubsub
-      #   topic = pubsub.get_topic "my-topic"
-      #
-      def get_topic topic_name
-        ensure_connection!
-        resp = connection.get_topic topic_name
-        if resp.success?
-          Topic.from_gapi resp.data, connection
-        else
-          return nil if resp.data["error"]["code"] == 404
-          fail ApiError.from_response(resp)
-        end
-      end
-      alias_method :find_topic, :get_topic
-
-      ##
-      # Retrieves topic by name.
-      # The difference between this method and Project#get_topic is that this
-      # method does not make an API call to Pub/Sub to verify the topic exists.
       #
       # === Parameters
       #
@@ -124,16 +88,24 @@ module Gcloud
       # +options+::
       #   An optional Hash for controlling additional behavior. (+Hash+)
       # <code>options[:autocreate]</code>::
-      #   Flag to control whether the topic should be created when needed.
-      #   The default value is +true+. (+Boolean+)
+      #   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+)
       # <code>options[:project]</code>::
       #   If the topic belongs to a project other than the one currently
       #   connected to, the alternate project ID can be specified here.
       #   (+String+)
+      # <code>options[:skip_lookup]</code>::
+      #   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
+      # 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
       #
@@ -142,25 +114,24 @@ module Gcloud
       #   gcloud = Gcloud.new
       #   pubsub = gcloud.pubsub
       #   topic = pubsub.topic "existing-topic"
-      #   msg = topic.publish "This is the first API call to Pub/Sub."
       #
-      # By default the topic will be created in Pub/Sub when needed.
+      # By default +nil+ will be returned if the topic does not exist.
+      # the topic will be created in Pub/Sub when needed.
       #
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   pubsub = gcloud.pubsub
-      #   topic = pubsub.topic "non-existing-topic"
-      #   msg = topic.publish "This will create the topic in Pub/Sub."
+      #   topic = pubsub.topic "non-existing-topic" #=> nil
       #
-      # Setting the +autocomplete+ flag to false will not create the topic.
+      # The topic will be created if the topic does not exist and the
+      # +autocreate+ option is set to true.
       #
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   pubsub = gcloud.pubsub
-      #   topic = pubsub.topic "non-existing-topic"
-      #   msg = topic.publish "This raises." #=> Gcloud::Pubsub::NotFoundError
+      #   topic = pubsub.topic "non-existing-topic", autocreate: true
       #
       # A topic in a different project can be created using the +project+ flag.
       #
@@ -170,11 +141,30 @@ module Gcloud
       #   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:
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   pubsub = gcloud.pubsub
+      #   topic = pubsub.topic "another-topic", skip_lookup: true
+      #
       def topic topic_name, options = {}
         ensure_connection!
-
-        Topic.new_lazy topic_name, connection, options
+        if options[:skip_lookup]
+          return Topic.new_lazy(topic_name, connection, options)
+        end
+        resp = connection.get_topic topic_name
+        return Topic.from_gapi(resp.data, connection) if resp.success?
+        if resp.status == 404
+          return create_topic(topic_name) if options[:autocreate]
+          return nil
+        end
+        fail ApiError.from_response(resp)
       end
+      alias_method :get_topic, :topic
+      alias_method :find_topic, :topic
 
       ##
       # Creates a new topic.
@@ -224,7 +214,7 @@ module Gcloud
       #
       # === Returns
       #
-      # Array of Gcloud::Pubsub::Topic (Gcloud::Pubsub::Topic::List)
+      # Array of Gcloud::Pubsub::Topic (See Gcloud::Pubsub::Topic::List)
       #
       # === Examples
       #
@@ -271,46 +261,189 @@ module Gcloud
       alias_method :list_topics, :topics
 
       ##
-      # Retrieves subscription by name.
-      # The difference between this method and Project#get_subscription is
-      # that this method does not make an API call to Pub/Sub to verify the
-      # subscription exists.
+      # Publishes one or more messages to the given topic.
       #
       # === 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
+      #
+      # Message object when called without a block,
+      # Array of Message objects when called with a block
+      #
+      # === Examples
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   pubsub = gcloud.pubsub
+      #
+      #   msg = pubsub.publish "my-topic", "new-message"
+      #
+      # Additionally, a message can be published with attributes:
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   pubsub = gcloud.pubsub
+      #
+      #   msg = pubsub.publish "my-topic", "new-message", foo: :bar,
+      #                                                   this: :that
+      #
+      # Multiple messages can be published at the same time by passing a block:
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   pubsub = gcloud.pubsub
+      #
+      #   msgs = pubsub.publish "my-topic" do |batch|
+      #     batch.publish "new-message-1", foo: :bar
+      #     batch.publish "new-message-2", foo: :baz
+      #     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.
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   pubsub = gcloud.pubsub
+      #
+      #   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?
+          attributes = data
+          data = nil
+        end
+        # extract autocreate option
+        autocreate = attributes.delete :autocreate
+        ensure_connection!
+        batch = Topic::Batch.new data, attributes
+        yield batch if block_given?
+        return nil if batch.messages.count.zero?
+        publish_batch_messages topic_name, batch, autocreate
+      end
+
+      ##
+      # Creates a new Subscription object for the provided topic.
+      #
+      # === Parameters
+      #
+      # +topic_name+::
+      #   Name of a topic. (+String+)
       # +subscription_name+::
-      #   Name of a subscription. (+String+)
+      #   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+)
+      # +options+::
+      #   An optional Hash for controlling additional behavior. (+Hash+)
+      # <code>options[:deadline]</code>::
+      #   The maximum number of seconds after a subscriber receives a message
+      #   before the subscriber should acknowledge the message. (+Integer+)
+      # <code>options[:endpoint]</code>::
+      #   A URL locating the endpoint to which messages should be pushed.
+      #   e.g. "https://example.com/push" (+String+)
+      # <code>attributes[:autocreate]</code>::
+      #   Flag to control whether the topic will be created if it does not
+      #   exist.
       #
       # === Returns
       #
       # Gcloud::Pubsub::Subscription
       #
-      # === Example
+      # === Examples
       #
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   pubsub = gcloud.pubsub
       #
-      #   subscription = pubsub.get_subscription "my-topic-subscription"
-      #   puts subscription.name
+      #   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.
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   pubsub = gcloud.pubsub
+      #
+      #   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
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   pubsub = gcloud.pubsub
       #
-      def subscription subscription_name
+      #   sub = pubsub.subscribe "my-topic", "my-topic-sub",
+      #                          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.
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   pubsub = gcloud.pubsub
+      #
+      #   sub = pubsub.subscribe "new-topic", "new-topic-sub", autocreate: true
+      #
+      def subscribe topic_name, subscription_name, options = {}
         ensure_connection!
-
-        Subscription.new_lazy subscription_name, connection
+        resp = connection.create_subscription topic_name,
+                                              subscription_name, options
+        return Subscription.from_gapi(resp.data, connection) if resp.success?
+        if options[:autocreate] && resp.status == 404
+          create_topic topic_name
+          return subscribe(topic_name, subscription_name,
+                           options.merge(autocreate: false))
+        end
+        fail ApiError.from_response(resp)
       end
+      alias_method :create_subscription, :subscribe
+      alias_method :new_subscription, :subscribe
 
       ##
       # Retrieves subscription by name.
-      # The difference between this method and Project#subscription is that
-      # this method makes an API call to Pub/Sub to verify the subscription
-      # exists.
       #
       # === Parameters
       #
       # +subscription_name+::
       #   Name of a subscription. (+String+)
+      # +options+::
+      #   An optional Hash for controlling additional behavior. (+Hash+)
+      # <code>options[:project]</code>::
+      #   If the subscription belongs to a project other than the one currently
+      #   connected to, the alternate project ID can be specified here.
+      #   (+String+)
+      # <code>options[:skip_lookup]</code>::
+      #   Optionally create a Subscription object without verifying the
+      #   subscription resource exists on the Pub/Sub service. Calls made on
+      #   this object will raise errors if the service resource does not exist.
+      #   Default is +false+. (+Boolean+)
       #
       # === Returns
       #
@@ -323,19 +456,33 @@ module Gcloud
       #   gcloud = Gcloud.new
       #   pubsub = gcloud.pubsub
       #
-      #   subscription = pubsub.get_subscription "my-topic-subscription"
+      #   subscription = pubsub.subscription "my-sub"
+      #   puts subscription.name
+      #
+      # The lookup against the Pub/Sub service can be skipped using the
+      # +skip_lookup+ option:
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   pubsub = gcloud.pubsub
+      #
+      #   # No API call is made to retrieve the subscription information.
+      #   subscription = pubsub.subscription "my-sub", skip_lookup: true
       #   puts subscription.name
       #
-      def get_subscription subscription_name
+      def subscription subscription_name, options = {}
         ensure_connection!
-        resp = connection.get_subscription subscription_name
-        if resp.success?
-          Subscription.from_gapi resp.data, connection
-        else
-          nil
+        if options[:skip_lookup]
+          return Subscription.new_lazy(subscription_name, connection, options)
         end
+        resp = connection.get_subscription subscription_name
+        return Subscription.from_gapi(resp.data, connection) if resp.success?
+        return nil if resp.status == 404
+        fail ApiError.from_response(resp)
       end
-      alias_method :find_subscription, :get_subscription
+      alias_method :get_subscription, :subscription
+      alias_method :find_subscription, :subscription
 
       ##
       # Retrieves a list of subscriptions for the given project.
@@ -356,7 +503,7 @@ module Gcloud
       # === Returns
       #
       # Array of Gcloud::Pubsub::Subscription
-      # (Gcloud::Pubsub::Subscription::List)
+      # (See Gcloud::Pubsub::Subscription::List)
       #
       # === Examples
       #
@@ -409,6 +556,20 @@ module Gcloud
       def ensure_connection!
         fail "Must have active connection" unless connection
       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
+          create_topic topic_name
+          publish_batch_messages topic_name, batch, false
+        else
+          fail ApiError.from_response(resp)
+        end
+      end
     end
   end
 end