pgmq-ruby 0.7.1 → 0.8.0

data/lib/pgmq/contracts/multi_queue.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module PGMQ
+  module Contracts
+    # Validates the arguments of operations that span several queues
+    #
+    # Each key is optional, so one contract serves every multi-queue operation. Queue names themselves are validated
+    # by {PGMQ::QueueName}.
+    class MultiQueue < Contractable::Contract
+      # Maximum number of queues in one multi-queue operation
+      MAX_QUEUES = 50
+
+      self.error_messages = Contracts.error_messages("multi_queue")
+
+      optional(:queue_names) do |queue_names|
+        next :format unless queue_names.is_a?(Array)
+        next :empty if queue_names.empty?
+        next :too_many if queue_names.size > MAX_QUEUES
+
+        true
+      end
+
+      %i[deletions archives updates].each do |key|
+        optional(key) { |value| value.is_a?(Hash) }
+      end
+    end
+  end
+end

data/lib/pgmq/contracts.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module PGMQ
+  # Contracts that validate user input before it reaches PostgreSQL
+  module Contracts
+    class << self
+      # @param scope [String] contract key under `en.validations` in `config/locales/errors.yml`
+      # @return [Hash{String => String}] error messages of one contract
+      def error_messages(scope)
+        @error_messages ||= YAML.safe_load_file(File.join(PGMQ.gem_root, "config", "locales", "errors.yml"))
+
+        @error_messages.fetch("en").fetch("validations").fetch(scope)
+      end
+    end
+  end
+end

data/lib/pgmq/errors.rb

@@ -6,25 +6,51 @@ module PGMQ
     # Base error class for all PGMQ errors
     class BaseError < StandardError; end
 
-    # Raised when connection to PostgreSQL fails or is lost
+    # Raised when a database call fails, not only when the connection to PostgreSQL fails or is lost.
+    # {PGMQ::Connection#with_connection} wraps every `PG::Error` (for example a missing queue, invalid JSON or an
+    # invalid integer) in this class, with the message "Database connection error: ...". It also raises it for
+    # connection pool timeouts and a closed pool. Outside a transaction, the original error is in `#cause`.
+    # {PGMQ::Client#transaction} raises it when the transaction fails. Then `#cause` is the error raised in the block;
+    # for a database error that is the inner {ConnectionError}, with the `PG::Error` in its own `#cause`.
     class ConnectionError < BaseError; end
 
     # Raised when a queue operation is attempted on a non-existent queue
+    #
+    # @note Not raised by PGMQ-Ruby. A database error for a missing queue raises {ConnectionError}.
     class QueueNotFoundError < BaseError; end
 
     # Raised when a message cannot be found
+    #
+    # @note Not raised by PGMQ-Ruby.
     class MessageNotFoundError < BaseError; end
 
     # Raised when message serialization fails
+    #
+    # @note Not raised by PGMQ-Ruby.
     class SerializationError < BaseError; end
 
     # Raised when message deserialization fails
+    #
+    # @note Not raised by PGMQ-Ruby.
     class DeserializationError < BaseError; end
 
     # Raised when configuration is invalid
     class ConfigurationError < BaseError; end
 
+    # Raised when a message, headers or a batch to produce do not match {PGMQ::Contracts::Message} or
+    # {PGMQ::Contracts::Batch}
+    class MessageInvalidError < BaseError; end
+
+    # Raised when the arguments of a multi-queue operation do not match {PGMQ::Contracts::MultiQueue}
+    class MultiQueueInvalidError < BaseError; end
+
+    # Raised when autovacuum settings do not match {PGMQ::Contracts::Autovacuum}
+    class AutovacuumSettingsInvalidError < BaseError; end
+
     # Raised when an invalid queue name is provided
     class InvalidQueueNameError < BaseError; end
+
+    # Raised when a transactional client is used outside its transaction (another thread/fiber, or after the block)
+    class TransactionError < BaseError; end
   end
 end

data/lib/pgmq/metrics.rb

@@ -5,6 +5,11 @@ require "time"
 module PGMQ
   # Represents metrics for a PGMQ queue
   #
+  # `queue_visible_length` (messages whose visibility timeout has passed) needs PGMQ v1.5.0+.
+  # `default_partition_length` (estimated rows in the default partitions of a partitioned queue
+  # and its archive) needs PGMQ v1.13.0+ and is `nil` for non-partitioned queues. A non-zero value
+  # means pg_partman maintenance is failing. On older PGMQ versions both are `nil`.
+  #
   # @example Getting queue metrics
   #   metrics = client.metrics("my_queue")
   #   puts metrics.queue_length        # => 42
@@ -15,7 +20,9 @@ module PGMQ
     :newest_msg_age_sec,
     :oldest_msg_age_sec,
     :total_messages,
-    :scrape_time
+    :scrape_time,
+    :queue_visible_length,
+    :default_partition_length
   )
     class << self
       # Creates a new Metrics object from a database row
@@ -29,7 +36,9 @@ module PGMQ
           newest_msg_age_sec: row["newest_msg_age_sec"],
           oldest_msg_age_sec: row["oldest_msg_age_sec"],
           total_messages: row["total_messages"],
-          scrape_time: row["scrape_time"]
+          scrape_time: row["scrape_time"],
+          queue_visible_length: row["queue_visible_length"],
+          default_partition_length: row["default_partition_length"]
         )
       end
     end

data/lib/pgmq/queue_name.rb

@@ -126,13 +126,12 @@ module PGMQ
     # a digit), truncates to fit {MAX_LENGTH}, and falls back to {SANITIZE_FALLBACK} when nothing usable remains. The
     # return value always satisfies {.valid?}.
     #
+    # @param name [String, #to_s] arbitrary input
+    # @return [String] a guaranteed-valid queue name
     # @note Because it coerces rather than rejects, distinct inputs can map to the *same* name (e.g. +"a/b"+ and
     #   +"a-b"+ both become +"a_b"+; +"!!!"+ and +""+ both become +"queue"+). If your name selects a queue table,
     #   that means two logically different inputs could share one queue. When that matters - especially for untrusted
     #   input - prefer {.sanitize!}, which raises instead of substituting.
-    #
-    # @param name [String, #to_s] arbitrary input
-    # @return [String] a guaranteed-valid queue name
     def sanitize(name)
       cleaned = name.to_s.downcase
         .gsub(/[^a-z0-9_]+/, "_").squeeze("_")

data/lib/pgmq/transaction.rb

@@ -20,14 +20,20 @@ module PGMQ
   #     txn.produce("orders", '{"order_id":123}')
   #     raise "Error"  # Both operations rolled back
   #   end
+  #
+  # @note The transactional client is bound to the fiber (and thread) that opened the transaction and is valid only
+  #   inside the block. Using it from another thread or fiber, or after the block returns, raises
+  #   {PGMQ::Errors::TransactionError} instead of silently running the operation outside the transaction.
   module Transaction
     # Executes PGMQ operations atomically within a database transaction
     #
     # Obtains a connection from the pool, starts a transaction, and yields a client that uses that transaction for all
-    # operations.
+    # operations made from the calling thread/fiber while the block runs. The yielded client raises
+    # {PGMQ::Errors::TransactionError} when used from another thread or fiber, or after the block has returned.
     #
     # @yield [PGMQ::Client] transactional client using the same connection
     # @return [Object] result of the block
+    # @raise [PGMQ::Errors::TransactionError] if the transactional client was misused and the error was not rescued
     # @raise [PGMQ::Errors::ConnectionError] if transaction fails
     #
     # @example
@@ -38,9 +44,17 @@ module PGMQ
     def transaction
       @connection.with_connection do |conn|
         conn.transaction do
-          yield TransactionalClient.new(self, conn)
+          txn = TransactionalClient.new(self, conn)
+
+          begin
+            yield txn
+          ensure
+            txn.finish!
+          end
         end
       end
+    rescue PGMQ::Errors::TransactionError
+      raise
     rescue PG::Error, StandardError => e
       raise PGMQ::Errors::ConnectionError, "Transaction failed: #{e.message}"
     end
@@ -57,13 +71,19 @@ module PGMQ
       )
         @parent = parent
         @conn = conn
+        @owner = Fiber.current
+        @finished = false
       end
 
       # Forward all method calls to parent, but use our transaction connection
       # @param method [Symbol] method name
       # @return [Object] result of method call
+      # @raise [PGMQ::Errors::TransactionError] if used off the owner fiber or after the transaction ended
       def method_missing(method, ...)
-        @parent.respond_to?(method, true) ? @parent.__send__(method, ...) : super
+        return super unless @parent.respond_to?(method, true)
+
+        ensure_usable!(method)
+        @parent.__send__(method, ...)
       end
 
       # Check if method exists on parent
@@ -78,7 +98,9 @@ module PGMQ
       end
 
       # Inject our transaction connection instead of using the pool
+      # @raise [PGMQ::Errors::TransactionError] if used off the owner fiber or after the transaction ended
       def with_connection
+        ensure_usable!(:with_connection)
         yield @conn
       end
 
@@ -86,6 +108,31 @@ module PGMQ
       def connection
         @parent.connection
       end
+
+      # Marks the transaction as ended so any further use raises
+      # @return [void]
+      def finish!
+        @finished = true
+      end
+
+      private
+
+      # Parent operations reach the transaction connection only through the pool's re-entrant checkout, which is keyed
+      # on the current fiber. Another thread/fiber would get a different connection and commit outside the transaction.
+      #
+      # @param method [Symbol] method being called, for the error message
+      # @raise [PGMQ::Errors::TransactionError] if used off the owner fiber or after the transaction ended
+      def ensure_usable!(method)
+        if @finished
+          raise PGMQ::Errors::TransactionError, "Cannot call ##{method}: the transaction has already ended"
+        end
+
+        return if Fiber.current.equal?(@owner)
+
+        raise PGMQ::Errors::TransactionError,
+          "Cannot call ##{method} from another thread or fiber: the transactional client is bound to the fiber " \
+          "that opened the transaction"
+      end
     end
   end
 end

data/lib/pgmq/version.rb

@@ -2,5 +2,5 @@
 
 module PGMQ
   # Current version of the pgmq-ruby gem
-  VERSION = "0.7.1"
+  VERSION = "0.8.0"
 end

data/lib/pgmq.rb

@@ -2,13 +2,13 @@
 
 require "zeitwerk"
 require "time"
+require "yaml"
 
 loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect(
   "pgmq" => "PGMQ"
 )
 loader.setup
-loader.eager_load
 
 # PGMQ - Low-level Ruby client for Postgres Message Queue
 #
@@ -38,6 +38,11 @@ loader.eager_load
 #   client.drop_queue('orders')
 module PGMQ
   class << self
+    # @return [String] root path of this gem
+    def gem_root
+      File.expand_path("..", __dir__)
+    end
+
     # Convenience method to create a new client
     #
     # @return [PGMQ::Client] new client instance
@@ -50,3 +55,5 @@ module PGMQ
     end
   end
 end
+
+loader.eager_load

data/pgmq-ruby.gemspec

@@ -22,11 +22,11 @@ Gem::Specification.new do |spec|
   spec.metadata["documentation_uri"] = "https://github.com/mensfeld/pgmq-ruby#readme"
   spec.metadata["rubygems_mfa_required"] = "true"
 
-  spec.files = Dir["lib/**/*", "CHANGELOG.md", "LICENSE", "README.md", "pgmq-ruby.gemspec"]
+  spec.files = Dir["lib/**/*", "config/**/*", "CHANGELOG.md", "LICENSE", "README.md", "pgmq-ruby.gemspec"]
   spec.require_paths = ["lib"]
 
   # Runtime dependencies
-  spec.add_dependency "connection_pool", "~> 2.4"
+  spec.add_dependency "connection_pool", ">= 2.4", "< 4"
   spec.add_dependency "pg", "~> 1.5"
   spec.add_dependency "zeitwerk", "~> 2.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgmq-ruby
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -13,16 +13,22 @@ dependencies:
   name: connection_pool
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
@@ -62,6 +68,7 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- config/locales/errors.yml
 - lib/pgmq.rb
 - lib/pgmq/client.rb
 - lib/pgmq/client/autovacuum.rb
@@ -74,6 +81,18 @@ files:
 - lib/pgmq/client/queue_management.rb
 - lib/pgmq/client/topics.rb
 - lib/pgmq/connection.rb
+- lib/pgmq/consumer.rb
+- lib/pgmq/contractable.rb
+- lib/pgmq/contractable/contract.rb
+- lib/pgmq/contractable/result.rb
+- lib/pgmq/contractable/rule.rb
+- lib/pgmq/contracts.rb
+- lib/pgmq/contracts/autovacuum.rb
+- lib/pgmq/contracts/batch.rb
+- lib/pgmq/contracts/connection.rb
+- lib/pgmq/contracts/consumer.rb
+- lib/pgmq/contracts/message.rb
+- lib/pgmq/contracts/multi_queue.rb
 - lib/pgmq/errors.rb
 - lib/pgmq/message.rb
 - lib/pgmq/metrics.rb
@@ -107,7 +126,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Ruby client for PGMQ (Postgres Message Queue)
 test_files: []