cloudenvoy 0.1.0.dev → 0.4.0

data/lib/cloudenvoy.rb

@@ -1,8 +1,102 @@
 # frozen_string_literal: true
 
+require 'active_support/core_ext/string/inflections'
+
 require 'cloudenvoy/version'
+require 'cloudenvoy/config'
+
+require 'cloudenvoy/authentication_error'
+require 'cloudenvoy/invalid_subscriber_error'
+
+require 'cloudenvoy/middleware/chain'
+require 'cloudenvoy/authenticator'
+require 'cloudenvoy/topic'
+require 'cloudenvoy/subscription'
+require 'cloudenvoy/pub_sub_client'
+require 'cloudenvoy/logger_wrapper'
+require 'cloudenvoy/publisher_logger'
+require 'cloudenvoy/subscriber_logger'
+require 'cloudenvoy/message'
+require 'cloudenvoy/publisher'
+require 'cloudenvoy/subscriber'
 
+# Define and manage Cloud Pub/Sub publishers and subscribers
 module Cloudenvoy
-  class Error < StandardError; end
-  # Your code goes here...
+  attr_writer :config
+
+  #
+  # Cloudenvoy configurator.
+  #
+  def self.configure
+    yield(config)
+  end
+
+  #
+  # Return the Cloudenvoy configuration.
+  #
+  # @return [Cloudenvoy::Config] The Cloudenvoy configuration.
+  #
+  def self.config
+    @config ||= Config.new
+  end
+
+  #
+  # Return the Cloudenvoy logger.
+  #
+  # @return [Logger] The Cloudenvoy logger.
+  #
+  def self.logger
+    config.logger
+  end
+
+  #
+  # Publish a message to a topic. Shorthand method to Cloudenvoy::PubSubClient#publish.
+  #
+  # @param [String] topic The name of the topic
+  # @param [Hash, String] payload The message content.
+  # @param [Hash] attrs The message attributes.
+  #
+  # @return [Cloudenvoy::Message] The created message.
+  #
+  def self.publish(topic, payload, attrs = {})
+    PubSubClient.publish(topic, payload, attrs)
+  end
+
+  #
+  # Return the list of registered publishers.
+  #
+  # @return [Set<Cloudenvoy::Subscriber>] The list of registered publishers.
+  #
+  def self.publishers
+    @publishers ||= Set.new
+  end
+
+  #
+  # Return the list of registered subscribers.
+  #
+  # @return [Set<Cloudenvoy::Subscriber>] The list of registered subscribers.
+  #
+  def self.subscribers
+    @subscribers ||= Set.new
+  end
+
+  #
+  # Create/update subscriptions for all registered subscribers.
+  #
+  # @return [Array<Cloudenvoy::Subscription>] The upserted subscriptions.
+  #
+  def self.setup_subscribers
+    subscribers.flat_map(&:setup)
+  end
+
+  #
+  # Create/update default topics for all registered publishers.
+  #
+  # @return [Array<Cloudenvoy::Subscription>] The upserted topics.
+  #
+  def self.setup_publishers
+    publishers.flat_map(&:setup)
+  end
 end
+
+require 'cloudenvoy/engine' if defined?(::Rails::Engine)

data/lib/cloudenvoy/authentication_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Cloudenvoy
+  class AuthenticationError < StandardError
+  end
+end

data/lib/cloudenvoy/authenticator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'jwt'
+
+module Cloudenvoy
+  # Manage token generation and verification
+  module Authenticator
+    module_function
+
+    # Algorithm used to sign the verification token
+    JWT_ALG = 'HS256'
+
+    #
+    # Return the cloudenvoy configuration. See Cloudenvoy#configure.
+    #
+    # @return [Cloudenvoy::Config] The library configuration.
+    #
+    def config
+      Cloudenvoy.config
+    end
+
+    #
+    # A Json Web Token (JWT) which is embedded as part of the receiving endpoint
+    # and will be used by the processor to authenticate the source of the message.
+    #
+    # @return [String] The jwt token
+    #
+    def verification_token
+      JWT.encode({ iat: Time.now.to_i }, config.secret, JWT_ALG)
+    end
+
+    #
+    # Verify a bearer token (jwt token)
+    #
+    # @param [String] bearer_token The token to verify.
+    #
+    # @return [Boolean] Return true if the token is valid
+    #
+    def verify(bearer_token)
+      JWT.decode(bearer_token, config.secret)
+    rescue JWT::VerificationError, JWT::DecodeError
+      false
+    end
+
+    #
+    # Verify a bearer token and raise a `Cloudenvoy::AuthenticationError`
+    # if the token is invalid.
+    #
+    # @param [String] bearer_token The token to verify.
+    #
+    # @return [Boolean] Return true if the token is valid
+    #
+    def verify!(bearer_token)
+      verify(bearer_token) || raise(AuthenticationError)
+    end
+  end
+end

data/lib/cloudenvoy/backend/google_pub_sub.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'google/cloud/pubsub'
+
+module Cloudenvoy
+  module Backend
+    # Interface to GCP Pub/Sub and Pub/Sub local emulator
+    module GooglePubSub
+      module_function
+
+      #
+      # Return the cloudenvoy configuration. See Cloudenvoy#configure.
+      #
+      # @return [Cloudenvoy::Config] The library configuration.
+      #
+      def config
+        Cloudenvoy.config
+      end
+
+      #
+      # Return true if the current config mode is development.
+      #
+      # @return [Boolean] True if Cloudenvoy is run in development mode.
+      #
+      def development?
+        config.mode == :development
+      end
+
+      #
+      # Return the backend to use for sending messages.
+      #
+      # @return [Google::Cloud::Pub] The low level client instance.
+      #
+      def backend
+        @backend ||= Google::Cloud::PubSub.new({
+          project_id: config.gcp_project_id,
+          emulator_host: development? ? Cloudenvoy::Config::EMULATOR_HOST : nil
+        }.compact)
+      end
+
+      #
+      # Return an authenticated endpoint for processing Pub/Sub webhooks.
+      #
+      # @return [String] An authenticated endpoint.
+      #
+      def webhook_url
+        "#{config.processor_url}?token=#{Authenticator.verification_token}"
+      end
+
+      #
+      # Publish a message to a topic.
+      #
+      # @param [String] topic The name of the topic
+      # @param [Hash, String] payload The message content.
+      # @param [Hash] metadata The message attributes.
+      #
+      # @return [Cloudenvoy::Message] The created message.
+      #
+      def publish(topic, payload, metadata = {})
+        # Retrieve the topic
+        ps_topic = backend.topic(topic, skip_lookup: true)
+
+        # Publish the message
+        ps_msg = ps_topic.publish(payload.to_json, metadata.to_h)
+
+        # Return formatted message
+        Message.new(
+          id: ps_msg.message_id,
+          payload: payload,
+          metadata: metadata,
+          topic: topic
+        )
+      end
+
+      #
+      # Create or update a subscription for a specific topic.
+      #
+      # @param [String] topic The name of the topic
+      # @param [String] name The name of the subscription
+      # @param [Hash] opts The subscription configuration options
+      # @option opts [Integer] :deadline The maximum number of seconds after a subscriber receives a message
+      #   before the subscriber should acknowledge the message.
+      # @option opts [Boolean] :retain_acked Indicates whether to retain acknowledged messages. If true,
+      #   then messages are not expunged from the subscription's backlog, even if they are acknowledged,
+      #   until they fall out of the retention window. Default is false.
+      # @option opts [<Type>] :retention How long to retain unacknowledged messages in the subscription's
+      #   backlog, from the moment a message is published. If retain_acked is true, then this also configures
+      #   the retention of acknowledged messages, and thus configures how far back in time a Subscription#seek
+      #   can be done. Cannot be more than 604,800 seconds (7 days) or less than 600 seconds (10 minutes).
+      #   Default is 604,800 seconds (7 days).
+      # @option opts [String] :filter An expression written in the Cloud Pub/Sub filter language.
+      #   If non-empty, then only Message instances whose attributes field matches the filter are delivered
+      #   on this subscription. If empty, then no messages are filtered out. Optional.
+      #
+      # @return [Cloudenvoy::Subscription] The upserted subscription.
+      #
+      def upsert_subscription(topic, name, opts = {})
+        sub_config = opts.to_h.merge(endpoint: webhook_url)
+
+        # Auto-create topic in development. In non-development environments
+        # the create subscription action raises an error if the topic does
+        # not exist
+        upsert_topic(topic) if development?
+
+        # Create subscription
+        ps_sub =
+          begin
+            # Retrieve the topic
+            ps_topic = backend.topic(topic, skip_lookup: true)
+
+            # Attempt to create the subscription
+            ps_topic.subscribe(name, sub_config)
+          rescue Google::Cloud::AlreadyExistsError
+            # Update endpoint on subscription
+            # Topic is not updated as it is name-dependent
+            backend.subscription(name).tap do |e|
+              sub_config.each do |k, v|
+                e.send("#{k}=", v)
+              end
+            end
+          end
+
+        # Return formatted subscription
+        Subscription.new(name: ps_sub.name, original: ps_sub)
+      end
+
+      #
+      # Create or update a topic.
+      #
+      # @param [String] topic The topic name.
+      #
+      # @return [Cloudenvoy::Topic] The upserted topic.
+      #
+      def upsert_topic(topic)
+        ps_topic = begin
+          backend.create_topic(topic)
+                   rescue Google::Cloud::AlreadyExistsError
+                     backend.topic(topic)
+        end
+
+        # Return formatted subscription
+        Topic.new(name: ps_topic.name, original: ps_topic)
+      end
+    end
+  end
+end

data/lib/cloudenvoy/backend/memory_pub_sub.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'google/cloud/pubsub'
+
+module Cloudenvoy
+  module Backend
+    # Store messages in a memory queue. Used for testing
+    module MemoryPubSub
+      module_function
+
+      #
+      # Return the message queue for a specific topic.
+      #
+      # @param [String] name The topic to retrieve.
+      #
+      # @return [Array] The list of messages for the provided topic
+      #
+      def queue(topic)
+        @queues ||= {}
+        @queues[topic.to_s] ||= []
+      end
+
+      #
+      # Clear all messages in a specific topic.
+      #
+      # @param [String] name The topic to clear.
+      #
+      # @return [Array] The cleared array.
+      #
+      def clear(topic)
+        queue(topic).clear
+      end
+
+      #
+      # Clear all messages across all topics.
+      #
+      # @param [String] name The topic to clear.
+      #
+      def clear_all
+        @queues&.values&.each { |e| e.clear }
+      end
+
+      #
+      # Publish a message to a topic.
+      #
+      # @param [String] topic The name of the topic
+      # @param [Hash, String] payload The message content.
+      # @param [Hash] attrs The message attributes.
+      #
+      # @return [Cloudenvoy::Message] The created message.
+      #
+      def publish(topic, payload, metadata = {})
+        msg = Message.new(
+          id: SecureRandom.uuid,
+          payload: payload,
+          metadata: metadata,
+          topic: topic
+        )
+        queue(topic).push(msg)
+
+        msg
+      end
+
+      #
+      # Create or update a subscription for a specific topic.
+      #
+      # @param [String] topic The name of the topic
+      # @param [String] name The name of the subscription
+      # @param [Hash] opts The subscription configuration options
+      #
+      # @return [Cloudenvoy::Subscription] The upserted subscription.
+      #
+      def upsert_subscription(_topic, name, _opts)
+        Subscription.new(name: name)
+      end
+
+      #
+      # Create or update a topic.
+      #
+      # @param [String] topic The topic name.
+      #
+      # @return [Cloudenvoy::Topic] The upserted topic.
+      #
+      def upsert_topic(topic)
+        Topic.new(name: topic)
+      end
+    end
+  end
+end

data/lib/cloudenvoy/config.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Cloudenvoy
+  # Holds cloudenvoy configuration. See Cloudenvoy#configure
+  class Config
+    attr_writer :secret, :gcp_project_id,
+                :gcp_sub_prefix, :processor_path, :logger, :mode
+
+    # Emulator host
+    EMULATOR_HOST = ENV['PUBSUB_EMULATOR_HOST'] || 'localhost:8085'
+
+    # Default application path used for processing messages
+    DEFAULT_PROCESSOR_PATH = '/cloudenvoy/receive'
+
+    PROCESSOR_HOST_MISSING = <<~DOC
+      Missing host for processing.
+      Please specify a processor hostname in form of `https://some-public-dns.example.com`'
+    DOC
+    SUB_PREFIX_MISSING_ERROR = <<~DOC
+      Missing GCP subscription prefix.
+      Please specify a subscription prefix in the form of `my-app`.
+    DOC
+    PROJECT_ID_MISSING_ERROR = <<~DOC
+      Missing GCP project ID.
+      Please specify a project ID in the cloudenvoy configurator.
+    DOC
+    SECRET_MISSING_ERROR = <<~DOC
+      Missing cloudenvoy secret.
+      Please specify a secret in the cloudenvoy initializer or add Rails secret_key_base in your credentials
+    DOC
+
+    #
+    # The operating mode.
+    #   - :production => send messages to GCP Pub/Sub
+    #   - :development => send message to gcloud CLI Pub/Sub emulator
+    #
+    # @return [<Type>] <description>
+    #
+    def mode
+      @mode ||= environment == 'development' ? :development : :production
+    end
+
+    #
+    # Return the current environment.
+    #
+    # @return [String] The environment name.
+    #
+    def environment
+      ENV['CLOUDENVOY_ENV'] || ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'development'
+    end
+
+    #
+    # Return the Cloudenvoy logger.
+    #
+    # @return [Logger, any] The cloudenvoy logger.
+    #
+    def logger
+      @logger ||= defined?(Rails) ? Rails.logger : ::Logger.new(STDOUT)
+    end
+
+    #
+    # Return the full URL of the processor. Message payloads will be sent
+    # to this URL.
+    #
+    # @return [String] The processor URL.
+    #
+    def processor_url
+      File.join(processor_host, processor_path)
+    end
+
+    #
+    # Set the processor host. In the context of Rails the host will
+    # also be added to the list of authorized Rails hosts.
+    #
+    # @param [String] val The processor host to set.
+    #
+    def processor_host=(val)
+      @processor_host = val
+
+      # Check if Rails supports host filtering
+      return unless val &&
+                    defined?(Rails) &&
+                    Rails.application.config.respond_to?(:hosts) &&
+                    Rails.application.config.hosts&.any?
+
+      # Add processor host to the list of authorized hosts
+      Rails.application.config.hosts << val.gsub(%r{https?://}, '')
+    end
+
+    #
+    # The hostname of the application processing the messages. The hostname must
+    # be reachable from Cloud Pub/Sub.
+    #
+    # @return [String] The processor host.
+    #
+    def processor_host
+      @processor_host || raise(StandardError, PROCESSOR_HOST_MISSING)
+    end
+
+    #
+    # The path on the host when message payloads will be sent.
+    # Default to `/cloudenvoy/receive`
+    #
+    #
+    # @return [String] The processor path
+    #
+    def processor_path
+      @processor_path || DEFAULT_PROCESSOR_PATH
+    end
+
+    #
+    # Return the prefix used for queues.
+    #
+    # @return [String] The prefix used when creating subscriptions.
+    #
+    def gcp_sub_prefix
+      @gcp_sub_prefix || raise(StandardError, SUB_PREFIX_MISSING_ERROR)
+    end
+
+    #
+    # Return the GCP project ID.
+    #
+    # @return [String] The ID of the project where pub/sub messages are hosted.
+    #
+    def gcp_project_id
+      @gcp_project_id || raise(StandardError, PROJECT_ID_MISSING_ERROR)
+    end
+
+    #
+    # Return the secret to use to sign the verification tokens
+    # attached to messages.
+    #
+    # @return [String] The cloudenvoy secret
+    #
+    def secret
+      @secret || (
+        defined?(Rails) && Rails.application.credentials&.dig(:secret_key_base)
+      ) || raise(StandardError, SECRET_MISSING_ERROR)
+    end
+
+    #
+    # Return the chain of publisher middlewares.
+    #
+    # @return [Cloudenvoy::Middleware::Chain] The chain of middlewares.
+    #
+    def publisher_middleware
+      @publisher_middleware ||= Middleware::Chain.new
+      yield @publisher_middleware if block_given?
+      @publisher_middleware
+    end
+
+    #
+    # Return the chain of subscriber middlewares.
+    #
+    # @return [Cloudenvoy::Middleware::Chain] The chain of middlewares.
+    #
+    def subscriber_middleware
+      @subscriber_middleware ||= Middleware::Chain.new
+      yield @subscriber_middleware if block_given?
+      @subscriber_middleware
+    end
+  end
+end