pubsub_client 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f957900bdf24e83c57067bb4e1d21c0010bf0e7d6aacc45da639c2250c7fa1b4
-  data.tar.gz: 036d770cee6fa93d718bb5aa91236825eb8bfe510293a0e352c611c46645bed0
+  metadata.gz: a8c6a6eb0e136b4bb41d2a66b41f456ef0a86d7aa8668f22dfb8ea5092d54585
+  data.tar.gz: f9400d0ff957f6f6e1e54cc76478cf9a1e186d0ea5410fd6e5335d192f163427
 SHA512:
-  metadata.gz: 6f52651a2b7b2f7279266a96850a84e4ca3639d454ce5f6fa437276b545c8c79e5d7fa99cddd760f9b0987c18739003eca20efbeadebe17e9fa794c042f8c3b5
-  data.tar.gz: 8157eaf01bef5317607e77b687f107fa3579a1a4b251bc8e6d4922a600d177274436a9302130642de2f6f8d86f9f79ca6f42bed5b3a973b92f52874194e68d92
+  metadata.gz: 161710fca1c0efab48a708e6b61a3b619528b6f024eb4ae1b2fa063e484d0975400acb9b3cc300d032142cf535e5e5648aa3a7d64c8ba6557aabe75912231ed4
+  data.tar.gz: dbe4e34c082e49c4ac1843e733ff51fb848cc256e1242a074d9ce7367f0279613397c28bcad9fdea46b519d722841484bfd4ea2402c5f447c0eff8a8296125e2

data/CHANGELOG.txt

@@ -1,3 +1,14 @@
+Version 1.3.0 2020-10-23
+------------------------
+e9e87f7 This adds the ability to subscribe to a Pub/Sub topic. Of note, we expose two additional configuration params:
+- `concurrency`: the number of threads the subscriber will run to process messages (defaults to 8 threads)
+-  `auto_ack`: flag to auto ack messages (default is `true` and _will_ ack messages)
+
+These changes come with a handful of useful checks:
+- ensures credentials are configured prior to subscribing
+- raises an error if the target subscription does not exist
+- raises an error if attempting to subscribe to a topic that has already been subscribed to
+
 Version 1.2.0 2020-09-25
 ------------------------
 aede3ab Raise custom error if GOOGLE_APPLICATION_CREDENTIALS not set

data/README.md

@@ -32,9 +32,11 @@ end
 
 ## Usage
 
+### Publishing
+
 To publish a message to Pub/Sub, call `PubsubClient.publish(message, 'the-topic')`. This method takes any serializable object as an argument and yields a result object to a block. The `result` object has a method `#succeeded?` that returns `true` if the message was successfully published, otherwise `false`. In the latter case, there is a method `#error` that returns the error.
 
-### Example
+#### Example
 ```ruby
 PubsubClient.publish(message, 'some-topic') do |result|
   if result.succeeded?
@@ -45,6 +47,36 @@ PubsubClient.publish(message, 'some-topic') do |result|
 end
 ```
 
+### Subscribing
+
+To subscribe to a topic, a client must first get a handle to the subscriber object. After doing so, a call to `subscriber.listener` will yield two arguments: the data (most clients will only need this) and the full Pub/Sub message (for anything more robust). Documentation for the full message can be found [here](https://googleapis.dev/ruby/google-cloud-pubsub/latest/Google/Cloud/PubSub/ReceivedMessage.html).
+
+Optionally, a client can choose to handle exceptions raised by the subscriber. If a client chooses to do so, the listener **must** be configured before `on_error` since the latter needs a handler to the underlying listener.
+
+#### Example
+```ruby
+subscriber = PubsubClient.subscriber('some-topic')
+
+subscriber.listener(concurrency: 4, auto_ack: false) do |data, received_message|
+  # Most clients will only need the first yielded arg.
+  # It is the same as calling received_message.data
+end
+
+# Optional
+subscriber.on_error do |ex|
+  # Do something with the exception.
+end
+
+subscriber.subscribe # This will sleep
+```
+
+By default, the underlying subscriber will use a concurrency of `8` threads and will acknowledge all messages. If these defaults are acceptable to the client, no arguments need to be passed in the call to `listener`.
+```ruby
+subscriber.listener do |data, received_message|
+  # Do something
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/pubsub_client.rb

@@ -1,26 +1,46 @@
 require 'pubsub_client/version'
 require 'pubsub_client/null_publisher_factory'
+require 'pubsub_client/null_subscriber_factory'
 require 'pubsub_client/publisher_factory'
+require 'pubsub_client/subscriber_factory'
 
 module PubsubClient
   Error = Class.new(StandardError)
   ConfigurationError = Class.new(Error)
   CredentialsError = Class.new(Error)
   InvalidTopicError = Class.new(Error)
+  InvalidSubscriptionError = Class.new(Error)
 
   class << self
     def stub!
-      raise ConfigurationError, 'PubsubClient is already configured' if @publisher_factory
+      raise ConfigurationError, 'PubsubClient is already configured' if @publisher_factory || @subscriber_factory
       @publisher_factory = NullPublisherFactory.new
+      @subscriber_factory = NullSubscriberFactory.new
     end
 
+    # @param message [String] The message to publish.
+    # @param topic [String] The name of the topic to publish to.
     def publish(message, topic, &block)
-      unless ENV['GOOGLE_APPLICATION_CREDENTIALS']
-        raise CredentialsError, 'GOOGLE_APPLICATION_CREDENTIALS must be set'
-      end
+      ensure_credentials!
 
       @publisher_factory ||= PublisherFactory.new
       @publisher_factory.build(topic).publish(message, &block)
     end
+
+    # @param subscription [String] - The name of the topic to subscribe to.
+    def subscriber(subscription)
+      ensure_credentials!
+
+      @subscriber_factory ||= SubscriberFactory.new
+      @subscriber_factory.build(subscription)
+    end
+
+    private
+
+    def ensure_credentials!
+      unless ENV['GOOGLE_APPLICATION_CREDENTIALS']
+        raise CredentialsError, 'GOOGLE_APPLICATION_CREDENTIALS must be set'
+      end
+    end
   end
 end

data/lib/pubsub_client/null_subscriber.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module PubsubClient
+  # A null object to act as a subscriber when clients are in dev or test
+  class NullSubscriber
+    # This adds a subset of the available methods on the
+    # Google::Cloud::PubSub::ReceivedMessage, which is what
+    # gets yielded by the subscription when configuring the listener.
+    # For a list of methods, see the following link:
+    # https://googleapis.dev/ruby/google-cloud-pubsub/latest/Google/Cloud/PubSub/ReceivedMessage.html
+    NullResult = Struct.new(:acknowledge!) do
+      def data
+        '{"key":"value"}'
+      end
+
+      def published_at
+        Time.now
+      end
+    end
+
+    def listener(*, &block)
+      res = NullResult.new
+      yield res.data, res
+    end
+
+    def subscribe
+      # no-op
+    end
+
+    def on_error(&block)
+      # no-op
+    end
+  end
+end

data/lib/pubsub_client/null_subscriber_factory.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'null_subscriber'
+
+module PubsubClient
+  # A null object to act as a subscriber factory when clients are in dev or test
+  class NullSubscriberFactory
+    def build(*)
+      NullSubscriber.new
+    end
+  end
+end

data/lib/pubsub_client/publisher.rb

@@ -4,6 +4,7 @@ require 'google/cloud/pubsub'
 
 module PubsubClient
   class Publisher
+    # @param topic [Google::Cloud::PubSub::Topic]
     def initialize(topic)
       @topic = topic
     end

data/lib/pubsub_client/publisher_factory.rb

@@ -10,6 +10,8 @@ module PubsubClient
       @publishers = {}
     end
 
+    # @param topic_name [String]
+    # @return [Publisher]
     def build(topic_name)
       # GRPC fails when attempting to use a connection created in a process that gets
       # forked with the message

data/lib/pubsub_client/subscriber.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'google/cloud/pubsub'
+
+module PubsubClient
+  class Subscriber
+    DEFAULT_CONCURRENCY = 8
+
+    # @param subscription [Google::Cloud::PubSub::Subscription]
+    def initialize(subscription)
+      @subscription = subscription
+    end
+
+    # @param concurrency [Integer] - The number of threads to run the subscriber with. Default is 8.
+    # @param auto_ack [Boolean] - Flag to acknowledge the Pub/Sub message. A message must be acked
+    # to remove it from the topic. Default is `true`.
+    #
+    # @return [Google::Cloud::PubSub::Subscriber]
+    def listener(concurrency: DEFAULT_CONCURRENCY, auto_ack: true, &block)
+      @listener ||= begin
+        @subscription.listen(threads: { callback: concurrency }) do |received_message|
+          yield received_message.data, received_message
+          received_message.acknowledge! if auto_ack
+        end
+      end
+    end
+
+    def subscribe
+      raise ConfigurationError, 'A listener must be configured' unless @listener
+
+      begin
+        @listener.start
+
+        sleep
+      rescue SignalException
+        @listener.stop.wait!
+      end
+    end
+
+    def on_error(&block)
+      raise ConfigurationError, 'A listener must be configured' unless @listener
+
+      @listener.on_error do |exception|
+        yield exception
+      end
+    end
+  end
+end

data/lib/pubsub_client/subscriber_factory.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'subscriber'
+
+module PubsubClient
+  class SubscriberFactory
+    def initialize
+      @subscribers = {}
+    end
+
+    # @param subscription_name [String]
+    # @retrun [Subscriber]
+    def build(subscription_name)
+      if @subscribers.key?(subscription_name)
+        raise ConfigurationError, "PubsubClient already subscribed to #{subscription_name}"
+      end
+
+      @subscribers[subscription_name] = build_subscriber(subscription_name)
+    end
+
+    private
+
+    def build_subscriber(subscription_name)
+      pubsub = Google::Cloud::PubSub.new
+      subscription = pubsub.subscription(subscription_name)
+      raise InvalidSubscriptionError, "The subscription #{subscription_name} does not exist" unless subscription
+      Subscriber.new(subscription)
+    end
+  end
+end

data/lib/pubsub_client/version.rb

@@ -1,3 +1,3 @@
 module PubsubClient
-  VERSION = '1.2.0'
+  VERSION = '1.3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pubsub_client
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Apartment List Platforms
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-09-29 00:00:00.000000000 Z
+date: 2020-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -88,8 +88,12 @@ files:
 - lib/pubsub_client.rb
 - lib/pubsub_client/null_publisher.rb
 - lib/pubsub_client/null_publisher_factory.rb
+- lib/pubsub_client/null_subscriber.rb
+- lib/pubsub_client/null_subscriber_factory.rb
 - lib/pubsub_client/publisher.rb
 - lib/pubsub_client/publisher_factory.rb
+- lib/pubsub_client/subscriber.rb
+- lib/pubsub_client/subscriber_factory.rb
 - lib/pubsub_client/version.rb
 - pubsub_client.gemspec
 homepage: https://github.com/apartmentlist/pubsub_client