pgmq-ruby 0.4.0 → 0.6.0

data/lib/pgmq/client/topics.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+module PGMQ
+  class Client
+    # Topic routing operations (AMQP-like patterns)
+    #
+    # This module provides AMQP-style topic routing for PGMQ, allowing messages
+    # to be routed to multiple queues based on pattern matching.
+    #
+    # Topic patterns support wildcards:
+    # - `*` matches exactly one word between dots (e.g., `orders.*` matches `orders.new`)
+    # - `#` matches zero or more words (e.g., `orders.#` matches `orders.new.urgent`)
+    #
+    # @note Requires PGMQ v1.11.0+
+    module Topics
+      # Binds a topic pattern to a queue
+      #
+      # Messages sent with routing keys matching this pattern will be delivered
+      # to the specified queue.
+      #
+      # @param pattern [String] topic pattern with optional wildcards (* or #)
+      # @param queue_name [String] name of the queue to bind
+      # @return [void]
+      #
+      # @example Bind exact routing key
+      #   client.bind_topic("orders.new", "new_orders")
+      #
+      # @example Bind with single-word wildcard
+      #   client.bind_topic("orders.*", "all_order_events")
+      #
+      # @example Bind with multi-word wildcard
+      #   client.bind_topic("orders.#", "order_audit_log")
+      def bind_topic(pattern, queue_name)
+        validate_queue_name!(queue_name)
+
+        with_connection do |conn|
+          conn.exec_params(
+            "SELECT pgmq.bind_topic($1::text, $2::text)",
+            [pattern, queue_name]
+          )
+        end
+
+        nil
+      end
+
+      # Unbinds a topic pattern from a queue
+      #
+      # @param pattern [String] topic pattern to unbind
+      # @param queue_name [String] name of the queue to unbind from
+      # @return [Boolean] true if the binding was removed, false if it didn't exist
+      #
+      # @example
+      #   client.unbind_topic("orders.new", "new_orders")
+      def unbind_topic(pattern, queue_name)
+        validate_queue_name!(queue_name)
+
+        result = with_connection do |conn|
+          conn.exec_params(
+            "SELECT pgmq.unbind_topic($1::text, $2::text)",
+            [pattern, queue_name]
+          )
+        end
+
+        result[0]["unbind_topic"] == "t"
+      end
+
+      # Sends a message via topic routing
+      #
+      # The message will be delivered to all queues whose bound patterns match
+      # the routing key.
+      #
+      # @param routing_key [String] dot-separated routing key (e.g., "orders.new.priority")
+      # @param message [String] message as JSON string
+      # @param headers [String, nil] optional headers as JSON string
+      # @param delay [Integer] delay in seconds before message becomes visible
+      # @return [Integer] count of queues the message was delivered to
+      #
+      # @example Basic topic send
+      #   count = client.produce_topic("orders.new", '{"order_id":123}')
+      #
+      # @example With headers and delay
+      #   count = client.produce_topic("orders.new.priority",
+      #     '{"order_id":123}',
+      #     headers: '{"trace_id":"abc"}',
+      #     delay: 30)
+      def produce_topic(routing_key, message, headers: nil, delay: 0)
+        result = with_connection do |conn|
+          if headers
+            conn.exec_params(
+              "SELECT pgmq.send_topic($1::text, $2::jsonb, $3::jsonb, $4::integer)",
+              [routing_key, message, headers, delay]
+            )
+          elsif delay > 0
+            conn.exec_params(
+              "SELECT pgmq.send_topic($1::text, $2::jsonb, $3::integer)",
+              [routing_key, message, delay]
+            )
+          else
+            conn.exec_params(
+              "SELECT pgmq.send_topic($1::text, $2::jsonb)",
+              [routing_key, message]
+            )
+          end
+        end
+
+        result[0]["send_topic"].to_i
+      end
+
+      # Sends multiple messages via topic routing
+      #
+      # All messages will be delivered to all queues whose bound patterns match
+      # the routing key.
+      #
+      # @param routing_key [String] dot-separated routing key
+      # @param messages [Array<String>] array of message payloads as JSON strings
+      # @param headers [Array<String>, nil] optional array of headers as JSON strings
+      # @param delay [Integer] delay in seconds before messages become visible
+      # @return [Array<Hash>] array of hashes with :queue_name and :msg_id
+      #
+      # @example Batch topic send
+      #   results = client.produce_batch_topic("orders.new", [
+      #     '{"order_id":1}',
+      #     '{"order_id":2}'
+      #   ])
+      #   # => [{ queue_name: "new_orders", msg_id: "1" }, ...]
+      def produce_batch_topic(routing_key, messages, headers: nil, delay: 0)
+        return [] if messages.empty?
+
+        if headers && headers.length != messages.length
+          raise ArgumentError,
+            "headers array length (#{headers.length}) must match messages array length (#{messages.length})"
+        end
+
+        result = with_connection do |conn|
+          encoder = PG::TextEncoder::Array.new
+          encoded_messages = encoder.encode(messages)
+
+          if headers
+            encoded_headers = encoder.encode(headers)
+            conn.exec_params(
+              "SELECT * FROM pgmq.send_batch_topic($1::text, $2::jsonb[], $3::jsonb[], $4::integer)",
+              [routing_key, encoded_messages, encoded_headers, delay]
+            )
+          elsif delay > 0
+            conn.exec_params(
+              "SELECT * FROM pgmq.send_batch_topic($1::text, $2::jsonb[], $3::integer)",
+              [routing_key, encoded_messages, delay]
+            )
+          else
+            conn.exec_params(
+              "SELECT * FROM pgmq.send_batch_topic($1::text, $2::jsonb[])",
+              [routing_key, encoded_messages]
+            )
+          end
+        end
+
+        result.map do |row|
+          { queue_name: row["queue_name"], msg_id: row["msg_id"] }
+        end
+      end
+
+      # Lists all topic bindings
+      #
+      # @param queue_name [String, nil] optional queue name to filter by
+      # @return [Array<Hash>] array of binding hashes with pattern, queue_name, bound_at
+      #
+      # @example List all bindings
+      #   bindings = client.list_topic_bindings
+      #   # => [{ pattern: "orders.*", queue_name: "orders", bound_at: "..." }, ...]
+      #
+      # @example List bindings for specific queue
+      #   bindings = client.list_topic_bindings(queue_name: "orders")
+      def list_topic_bindings(queue_name: nil)
+        result = with_connection do |conn|
+          if queue_name
+            validate_queue_name!(queue_name)
+            conn.exec_params(
+              "SELECT pattern, queue_name, bound_at FROM pgmq.list_topic_bindings($1::text)",
+              [queue_name]
+            )
+          else
+            conn.exec("SELECT pattern, queue_name, bound_at FROM pgmq.list_topic_bindings()")
+          end
+        end
+
+        result.map do |row|
+          {
+            pattern: row["pattern"],
+            queue_name: row["queue_name"],
+            bound_at: row["bound_at"]
+          }
+        end
+      end
+
+      # Tests which queues a routing key would match
+      #
+      # Useful for debugging topic routing configurations.
+      #
+      # @param routing_key [String] routing key to test
+      # @return [Array<Hash>] array of matched bindings with pattern and queue_name
+      #
+      # @example Test routing
+      #   matches = client.test_routing("orders.new.priority")
+      #   # => [{ pattern: "orders.*", queue_name: "new_orders" }, ...]
+      def test_routing(routing_key)
+        result = with_connection do |conn|
+          conn.exec_params(
+            "SELECT pattern, queue_name FROM pgmq.test_routing($1::text)",
+            [routing_key]
+          )
+        end
+
+        result.map do |row|
+          { pattern: row["pattern"], queue_name: row["queue_name"] }
+        end
+      end
+
+      # Validates a routing key
+      #
+      # Routing keys are dot-separated words (no wildcards allowed).
+      # Returns false for invalid routing keys (PGMQ raises an error for invalid keys).
+      #
+      # @param routing_key [String] routing key to validate
+      # @return [Boolean] true if valid, false if invalid
+      #
+      # @example
+      #   client.validate_routing_key("orders.new.priority")  # => true
+      #   client.validate_routing_key("orders.*")             # => false (wildcards not allowed)
+      def validate_routing_key(routing_key)
+        result = with_connection do |conn|
+          conn.exec_params(
+            "SELECT pgmq.validate_routing_key($1::text)",
+            [routing_key]
+          )
+        end
+
+        result[0]["validate_routing_key"] == "t"
+      rescue PGMQ::Errors::ConnectionError => e
+        # PGMQ raises an error for invalid routing keys
+        return false if e.message.include?("invalid characters")
+
+        raise
+      end
+
+      # Validates a topic pattern
+      #
+      # Topic patterns can include wildcards: * (single word) or # (zero or more words).
+      #
+      # @param pattern [String] topic pattern to validate
+      # @return [Boolean] true if valid
+      #
+      # @example
+      #   client.validate_topic_pattern("orders.*")    # => true
+      #   client.validate_topic_pattern("orders.#")    # => true
+      #   client.validate_topic_pattern("orders.new")  # => true
+      def validate_topic_pattern(pattern)
+        result = with_connection do |conn|
+          conn.exec_params(
+            "SELECT pgmq.validate_topic_pattern($1::text)",
+            [pattern]
+          )
+        end
+
+        result[0]["validate_topic_pattern"] == "t"
+      end
+    end
+  end
+end

data/lib/pgmq/client.rb

@@ -31,8 +31,9 @@ module PGMQ
     include Consumer             # Single-queue reading operations
     include MultiQueue           # Multi-queue operations
     include MessageLifecycle     # Message state transitions (pop, delete, archive)
-    include Maintenance          # Queue maintenance (purge, detach_archive)
+    include Maintenance          # Queue maintenance (purge, notifications)
     include Metrics              # Monitoring and metrics
+    include Topics               # Topic routing (AMQP-like patterns, PGMQ v1.11.0+)
 
     # Default visibility timeout in seconds
     DEFAULT_VT = 30
@@ -65,15 +66,15 @@ module PGMQ
       auto_reconnect: true
     )
       @connection = if conn_params.is_a?(Connection)
-                      conn_params
-                    else
-                      Connection.new(
-                        conn_params,
-                        pool_size: pool_size,
-                        pool_timeout: pool_timeout,
-                        auto_reconnect: auto_reconnect
-                      )
-                    end
+        conn_params
+      else
+        Connection.new(
+          conn_params,
+          pool_size: pool_size,
+          pool_timeout: pool_timeout,
+          auto_reconnect: auto_reconnect
+        )
+      end
     end
 
     # Closes all connections in the pool
@@ -109,7 +110,7 @@ module PGMQ
       if queue_name.nil? || queue_name.to_s.strip.empty?
         raise(
           Errors::InvalidQueueNameError,
-          'Queue name cannot be empty'
+          "Queue name cannot be empty"
         )
       end
 
@@ -131,7 +132,7 @@ module PGMQ
       raise(
         Errors::InvalidQueueNameError,
         "Invalid queue name '#{queue_name}': must start with a letter or underscore " \
-        'and contain only letters, digits, and underscores'
+        "and contain only letters, digits, and underscores"
       )
     end
   end

data/lib/pgmq/connection.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require 'pg'
-require 'connection_pool'
+require "pg"
+require "connection_pool"
 
 module PGMQ
   # Manages database connections for PGMQ
@@ -45,7 +45,7 @@ module PGMQ
       if conn_params.nil?
         raise(
           PGMQ::Errors::ConfigurationError,
-          'Connection parameters are required'
+          "Connection parameters are required"
         )
       end
 
@@ -113,12 +113,12 @@ module PGMQ
     def connection_lost_error?(error)
       # Common connection lost errors
       lost_connection_messages = [
-        'server closed the connection',
-        'connection not open',
-        'no connection to the server',
-        'terminating connection',
-        'connection to server was lost',
-        'could not receive data from server'
+        "server closed the connection",
+        "connection not open",
+        "no connection to the server",
+        "terminating connection",
+        "connection to server was lost",
+        "could not receive data from server"
       ]
 
       message = error.message.downcase
@@ -145,7 +145,7 @@ module PGMQ
       return parse_connection_string(params) if params.is_a?(String)
       return params if params.is_a?(Hash) && !params.empty?
 
-      raise PGMQ::Errors::ConfigurationError, 'Invalid connection parameters format'
+      raise PGMQ::Errors::ConfigurationError, "Invalid connection parameters format"
     end
 
     # Parses a PostgreSQL connection string
@@ -169,11 +169,34 @@ module PGMQ
     # @return [ConnectionPool]
     def create_pool
       params = @conn_params
+      seen_connections = ObjectSpace::WeakKeyMap.new
+      seen_mutex = Mutex.new
 
       ConnectionPool.new(size: @pool_size, timeout: @pool_timeout) do
-        create_connection(params)
+        conn = create_connection(params)
+
+        # Detect shared connections: if a callable returns the same PG::Connection
+        # object to multiple pool slots, concurrent use will corrupt libpq state
+        # (nil results, segfaults, wrong data). Fail fast with a clear message.
+        if conn.is_a?(PG::Connection)
+          seen_mutex.synchronize do
+            if seen_connections.key?(conn)
+              raise PGMQ::Errors::ConfigurationError,
+                "Connection callable returned the same PG::Connection object " \
+                "(object_id: #{conn.object_id}) to multiple pool slots. " \
+                "PG::Connection is NOT thread-safe — concurrent use causes nil results, " \
+                "segfaults, and data corruption. Ensure your callable returns a unique " \
+                "PG::Connection instance on each invocation (for example, by calling " \
+                "PG.connect inside the callable)."
+            end
+
+            seen_connections[conn] = true
+          end
+        end
+
+        conn
       end
-    rescue StandardError => e
+    rescue => e
       raise PGMQ::Errors::ConnectionError, "Failed to create connection pool: #{e.message}"
     end
 

data/lib/pgmq/message.rb

@@ -11,12 +11,13 @@ module PGMQ
   #   puts msg.msg_id         # => "123" (String from PG)
   #   puts msg.read_ct        # => "1" (String from PG)
   #   puts msg.enqueued_at    # => "2025-01-15 10:30:00+00" (String from PG)
+  #   puts msg.last_read_at   # => "2025-01-15 10:31:00+00" (String from PG, nil if never read)
   #   puts msg.vt             # => "2025-01-15 10:30:30+00" (String from PG)
   #   puts msg.message        # => "{\"order_id\":456}" (Raw JSONB string)
   #   puts msg.headers        # => "{\"trace_id\":\"abc123\"}" (Raw JSONB string, optional)
   #   puts msg.queue_name     # => "my_queue" (only present for multi-queue operations)
   class Message < Data.define(
-    :msg_id, :read_ct, :enqueued_at, :vt, :message, :headers, :queue_name
+    :msg_id, :read_ct, :enqueued_at, :last_read_at, :vt, :message, :headers, :queue_name
   )
     class << self
       # Creates a new Message from a database row
@@ -27,19 +28,20 @@ module PGMQ
         # No parsing, no deserialization, no transformation
         # The pg gem returns JSONB as String by default
         super(
-          msg_id: row['msg_id'],
-          read_ct: row['read_ct'],
-          enqueued_at: row['enqueued_at'],
-          vt: row['vt'],
-          message: row['message'],
-          headers: row['headers'], # JSONB column for metadata (optional)
-          queue_name: row['queue_name'] # nil for single-queue operations
+          msg_id: row["msg_id"],
+          read_ct: row["read_ct"],
+          enqueued_at: row["enqueued_at"],
+          last_read_at: row["last_read_at"], # nil if message has never been read
+          vt: row["vt"],
+          message: row["message"],
+          headers: row["headers"], # JSONB column for metadata (optional)
+          queue_name: row["queue_name"] # nil for single-queue operations
         )
       end
     end
 
     # Alias for msg_id (common in messaging systems)
     # @return [String]
-    alias id msg_id
+    alias_method :id, :msg_id
   end
 end

data/lib/pgmq/metrics.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'time'
+require "time"
 
 module PGMQ
   # Represents metrics for a PGMQ queue
@@ -24,12 +24,12 @@ module PGMQ
       def new(row, **)
         # Return raw values as-is from PostgreSQL
         super(
-          queue_name: row['queue_name'],
-          queue_length: row['queue_length'],
-          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']
+          queue_name: row["queue_name"],
+          queue_length: row["queue_length"],
+          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"]
         )
       end
     end

data/lib/pgmq/queue_metadata.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'time'
+require "time"
 
 module PGMQ
   # Represents metadata about a PGMQ queue
@@ -18,20 +18,20 @@ module PGMQ
       def new(row, **)
         # Return raw values as-is from PostgreSQL
         super(
-          queue_name: row['queue_name'],
-          created_at: row['created_at'],
-          is_partitioned: row['is_partitioned'],
-          is_unlogged: row['is_unlogged']
+          queue_name: row["queue_name"],
+          created_at: row["created_at"],
+          is_partitioned: row["is_partitioned"],
+          is_unlogged: row["is_unlogged"]
         )
       end
     end
 
     # Alias for is_partitioned
     # @return [String] 't' or 'f' from PostgreSQL
-    alias partitioned? is_partitioned
+    alias_method :partitioned?, :is_partitioned
 
     # Alias for is_unlogged
     # @return [String] 't' or 'f' from PostgreSQL
-    alias unlogged? is_unlogged
+    alias_method :unlogged?, :is_unlogged
   end
 end

data/lib/pgmq/version.rb

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

data/lib/pgmq.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require 'zeitwerk'
-require 'time'
+require "zeitwerk"
+require "time"
 
 loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect(
-  'pgmq' => 'PGMQ'
+  "pgmq" => "PGMQ"
 )
 loader.setup
 loader.eager_load

data/pgmq-ruby.gemspec

@@ -1,32 +1,32 @@
 # frozen_string_literal: true
 
-require_relative 'lib/pgmq/version'
+require_relative "lib/pgmq/version"
 
 Gem::Specification.new do |spec|
-  spec.name = 'pgmq-ruby'
+  spec.name = "pgmq-ruby"
   spec.version = PGMQ::VERSION
-  spec.authors = ['Maciej Mensfeld']
-  spec.email = ['maciej@mensfeld.pl']
+  spec.authors = ["Maciej Mensfeld"]
+  spec.email = ["maciej@mensfeld.pl"]
 
-  spec.summary = 'Ruby client for PGMQ (Postgres Message Queue)'
-  spec.description = 'A Ruby driver for PGMQ - a lightweight message queue built on PostgreSQL. ' \
-                     'Like AWS SQS and RSMQ, but on Postgres.'
-  spec.homepage = 'https://github.com/mensfeld/pgmq-ruby'
-  spec.license = 'LGPL-3.0'
-  spec.required_ruby_version = '>= 3.2.0'
+  spec.summary = "Ruby client for PGMQ (Postgres Message Queue)"
+  spec.description = "A Ruby driver for PGMQ - a lightweight message queue built on PostgreSQL. " \
+                     "Like AWS SQS and RSMQ, but on Postgres."
+  spec.homepage = "https://github.com/mensfeld/pgmq-ruby"
+  spec.license = "LGPL-3.0"
+  spec.required_ruby_version = ">= 3.3.0"
 
-  spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['source_code_uri'] = 'https://github.com/mensfeld/pgmq-ruby'
-  spec.metadata['changelog_uri'] = 'https://github.com/mensfeld/pgmq-ruby/blob/master/CHANGELOG.md'
-  spec.metadata['bug_tracker_uri'] = 'https://github.com/mensfeld/pgmq-ruby/issues'
-  spec.metadata['documentation_uri'] = 'https://github.com/mensfeld/pgmq-ruby#readme'
-  spec.metadata['rubygems_mfa_required'] = 'true'
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/mensfeld/pgmq-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/mensfeld/pgmq-ruby/blob/master/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/mensfeld/pgmq-ruby/issues"
+  spec.metadata["documentation_uri"] = "https://github.com/mensfeld/pgmq-ruby#readme"
+  spec.metadata["rubygems_mfa_required"] = "true"
 
-  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(spec|examples)/}) }
-  spec.require_paths = ['lib']
+  spec.files = Dir["lib/**/*", "CHANGELOG.md", "LICENSE", "README.md", "pgmq-ruby.gemspec"]
+  spec.require_paths = ["lib"]
 
   # Runtime dependencies
-  spec.add_dependency 'connection_pool', '~> 2.4'
-  spec.add_dependency 'pg', '~> 1.5'
-  spec.add_dependency 'zeitwerk', '~> 2.6'
+  spec.add_dependency "connection_pool", "~> 2.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.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -59,20 +59,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".coditsu/ci.yml"
-- ".github/workflows/ci.yml"
-- ".github/workflows/push.yml"
-- ".gitignore"
-- ".rspec"
-- ".ruby-version"
-- ".yard-lint.yml"
 - CHANGELOG.md
-- Gemfile
-- Gemfile.lock
 - LICENSE
 - README.md
-- Rakefile
-- docker-compose.yml
 - lib/pgmq.rb
 - lib/pgmq/client.rb
 - lib/pgmq/client/consumer.rb
@@ -82,6 +71,7 @@ files:
 - lib/pgmq/client/multi_queue.rb
 - lib/pgmq/client/producer.rb
 - lib/pgmq/client/queue_management.rb
+- lib/pgmq/client/topics.rb
 - lib/pgmq/connection.rb
 - lib/pgmq/errors.rb
 - lib/pgmq/message.rb
@@ -90,7 +80,6 @@ files:
 - lib/pgmq/transaction.rb
 - lib/pgmq/version.rb
 - pgmq-ruby.gemspec
-- renovate.json
 homepage: https://github.com/mensfeld/pgmq-ruby
 licenses:
 - LGPL-3.0
@@ -108,14 +97,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Ruby client for PGMQ (Postgres Message Queue)
 test_files: []

data/.coditsu/ci.yml

@@ -1,3 +0,0 @@
-repository_id: '401d7537-5ac7-4691-ae02-f11fb24646d9'
-api_key: <%= ENV['CODITSU_API_KEY'] %>
-api_secret: <%= ENV['CODITSU_API_SECRET'] %>