pgmq-ruby 0.4.0 → 0.5.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
@@ -173,7 +173,7 @@ module PGMQ
       ConnectionPool.new(size: @pool_size, timeout: @pool_timeout) do
         create_connection(params)
       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.5.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