fast_mcp_pubsub 1.1.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db696202b8d3b7dae7c2231fcb132d6dba086b20e578eac993aac24bb92d820b
-  data.tar.gz: 67f0d7bf55c87fcc35a1f9a9cc2686fef93329ff958c4377e823027670724aea
+  metadata.gz: 9a955c6fc8f0b93d011d31fd196d7605b4925eb114d1355f99232ee2f8a15efb
+  data.tar.gz: 5b5ceaa86be4ecdb6cf74d2d913b0efb12b1f7a0668e0fb171a92d859cff1993
 SHA512:
-  metadata.gz: 50b8171fab26238c6177e7d450eef9218adc02b76bb1e6434e65a80ef4c0ff998e43f2c3e538fccadde7097ac8928ff0b20c129aba73d36ec8d2a128a213ab2d
-  data.tar.gz: d386411918a12d71f91cb2b9a40a2b3aaa6bf11d527bb637c231a3bc5c9dc76e53814d91a222d418c8dea02ced23ad41aff72bb5db94d48f1982083e65000fca
+  metadata.gz: 67bc13d26facefac99906e013bf444805412422690e444037a3d11779703c879f225038e32813614d6f84f58b50f13d77ac88266d67e4729902e69880ccdbb0d
+  data.tar.gz: eaa38f519aad1c30c7aaac06c35dff2e120b27623f7e1097728a70f442de167b0f9fe0b91f1b4f36f93af51f70a8301d99c4ae96a7c2f27dc8e15ae50b7b42ae

data/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.0] - 2026-08-20
+
+### Fixed
+- **A JSON-RPC response no longer reaches every connected SSE client.** Every
+  response was published as a bare NOTIFY payload and then written into every
+  entry of every worker's `@sse_clients`, so one client's answer landed in every
+  other client's stream — across projects and across users. The only thing
+  keeping clients apart was JSON-RPC id matching on the client side, which
+  collides whenever two clients open fresh sessions at the same moment and both
+  begin counting ids from 1. Observed in production as a runner installed for
+  one project picking up a task belonging to another.
+- `stop_listener` now clears `@listener_thread` when the thread has already died
+  instead of leaving a dead reference behind, which callers read as "a listener
+  is running".
+
+### Added
+- `FastMcpPubsub::CurrentClient` — thread-local record of which SSE client the
+  request being served belongs to.
+- `FastMcpPubsub::AddressingPatch` — the three pieces that carry FastMcp's
+  `client_id` end to end: it is appended to the endpoint URL handed to the client
+  on connect, captured from the client's POSTs, and used to deliver a response to
+  that one client via the new `send_local_message_to`.
+- `_pubsub_target` on the NOTIFY envelope, so every worker can tell whether a
+  message is addressed to a client it holds.
+
+### Compatibility
+- A message with no target still fans out, so genuine notifications and clients
+  that supply no id behave exactly as before.
+- Bare, un-enveloped payloads from a worker still running an older gem are
+  recognised and delivered, so a rolling restart does not drop messages.
+
 ## [1.0.0] - 2025-08-19
 
 ### Added

data/README.md

@@ -104,6 +104,28 @@ FastMcpPubsub::Service.listener_thread&.alive?
 3. **Listener threads**: Each worker has a dedicated listener thread
 4. **Local delivery**: Messages are delivered to local SSE clients in each worker
 
+### Addressing
+
+A JSON-RPC **response** is delivered only to the client that asked for it; a
+**notification** still reaches everyone. FastMcp answers over SSE and writes each
+message to every open stream, so without addressing one client's response lands
+in every other client's session — and the only thing separating them is
+JSON-RPC id matching, which collides as soon as two clients open fresh sessions
+at the same moment and both start counting ids from 1.
+
+The gem closes that by carrying FastMcp's own `client_id` end to end:
+
+- the endpoint URL handed to a client on connect carries its `client_id`
+- the client's POSTs come back with it, and it is held in `CurrentClient` for the
+  length of the request
+- `send_message` stamps it onto the NOTIFY envelope as `_pubsub_target`
+- each worker delivers a targeted message only to that client, and ignores one
+  addressed to a client another worker holds
+
+A message with no target — a genuine notification, or a request from a client
+that supplied no id — falls back to the previous fan-out, so older clients keep
+working.
+
 ## Configuration Options
 
 | Option | Default | Description |

data/lib/fast_mcp_pubsub/addressing_patch.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module FastMcpPubsub
+  # The half of the RackTransport patch that makes a response reachable by the one
+  # client that asked for it.
+  #
+  # FastMcp answers a JSON-RPC request over SSE and writes every message to every
+  # connected stream, so before this the only thing keeping two clients apart was
+  # JSON-RPC id matching — which fails the moment two of them open fresh sessions
+  # in the same minute and both start counting ids from 1.
+  #
+  # Correlating a response with its client takes three pieces, and none of them
+  # works alone: the client id has to reach the client (the endpoint URL), come
+  # back on its POSTs (the capture), and have somewhere to be delivered to (the
+  # targeted send).
+  module AddressingPatch
+    def self.apply!
+      add_targeted_send
+      add_sse_writer
+      add_client_id_capture
+      add_endpoint_client_id
+    end
+
+    # Delivery to one named SSE client, the counterpart of FastMcp's own
+    # send_message. Returns false when this worker does not hold the client,
+    # which is the normal answer on every worker but one.
+    def self.add_targeted_send
+      FastMcp::Transports::RackTransport.class_eval do
+        return if method_defined?(:send_local_message_to)
+
+        define_method(:send_local_message_to) do |client_id, message|
+          client = @sse_clients[client_id]
+          return false unless client
+
+          write_sse_payload(client, message.is_a?(String) ? message : JSON.generate(message))
+        rescue StandardError => e
+          FastMcpPubsub.logger.info "RackTransport: Client #{client_id} unreachable (#{e.message}), unregistering"
+          unregister_sse_client(client_id)
+          false
+        end
+      end
+    end
+
+    def self.add_sse_writer
+      FastMcp::Transports::RackTransport.class_eval do
+        return if method_defined?(:write_sse_payload)
+
+        define_method(:write_sse_payload) do |client, json_message|
+          stream = client[:stream]
+          mutex = client[:mutex]
+          return false if stream.nil? || mutex.nil? || (stream.respond_to?(:closed?) && stream.closed?)
+
+          mutex.synchronize do
+            stream.write("data: #{json_message}\n\n")
+            stream.flush if stream.respond_to?(:flush)
+          end
+          true
+        end
+        private :write_sse_payload
+      end
+    end
+
+    # Records which client the POST belongs to, so send_message can address the
+    # response FastMcp is about to write.
+    #
+    # request.GET rather than request.params on purpose: params merges the POST
+    # body, and reading the body here would leave nothing for the JSON parse that
+    # follows.
+    def self.add_client_id_capture
+      FastMcp::Transports::RackTransport.class_eval do
+        return unless private_method_defined?(:handle_message_request_with_server)
+        return if private_method_defined?(:handle_message_request_without_pubsub)
+
+        alias_method :handle_message_request_without_pubsub, :handle_message_request_with_server
+
+        define_method(:handle_message_request_with_server) do |request, server|
+          FastMcpPubsub::CurrentClient.with(request.GET["client_id"]) do
+            handle_message_request_without_pubsub(request, server)
+          end
+        end
+        private :handle_message_request_with_server
+      end
+    end
+
+    # Puts the client id into the endpoint URL FastMcp hands the client on
+    # connect, so the client's POSTs come back carrying it.
+    #
+    # FastMcp echoes the SSE request's own query string into that endpoint and
+    # never adds the id it just generated, so without this the capture above has
+    # nothing to read and every response falls back to the fan-out.
+    def self.add_endpoint_client_id
+      FastMcp::Transports::RackTransport.class_eval do
+        return unless private_method_defined?(:setup_sse_connection)
+        return if private_method_defined?(:setup_sse_connection_without_pubsub)
+
+        alias_method :setup_sse_connection_without_pubsub, :setup_sse_connection
+
+        define_method(:setup_sse_connection) do |client_id, io, env|
+          query = FastMcpPubsub::AddressingPatch.query_with_client_id(env["QUERY_STRING"], client_id)
+          setup_sse_connection_without_pubsub(client_id, io, env.merge("QUERY_STRING" => query))
+        end
+        private :setup_sse_connection
+      end
+    end
+
+    # Appends client_id to an SSE query string, leaving a client that named its
+    # own id alone — FastMcp honours that one, so overriding it would hand back an
+    # endpoint pointing at a different session than the stream it arrived on.
+    def self.query_with_client_id(query_string, client_id)
+      return query_string if query_string.to_s.match?(/(\A|&)client_id=/)
+
+      [query_string, "client_id=#{CGI.escape(client_id.to_s)}"].reject { |part| part.to_s.empty? }.join("&")
+    end
+  end
+end

data/lib/fast_mcp_pubsub/current_client.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module FastMcpPubsub
+  # Thread-local record of which SSE client the request being served belongs to.
+  #
+  # FastMcp answers a JSON-RPC request over the client's SSE stream rather than in
+  # the POST body, and MCP::Server#send_response has no idea which stream that is.
+  # The transport does know: the client id arrives as a query parameter on the
+  # POST. Stashing it here for the length of the request is what lets the response
+  # be addressed instead of broadcast.
+  #
+  # A thread local is the right scope because FastMcp handles the POST
+  # synchronously — handle_request calls send_response on the very thread that
+  # entered handle_message_request_with_server, so the value set on the way in is
+  # still there on the way out.
+  module CurrentClient
+    KEY = :fast_mcp_pubsub_client_id
+
+    class << self
+      # The client id of the request being served, or nil outside one — which is
+      # what a genuine notification looks like, and those really are for everyone.
+      def id
+        Thread.current[KEY]
+      end
+
+      # Runs the block with client_id in scope, restoring whatever was there
+      # before. Restoring rather than clearing keeps nesting honest; Puma reuses
+      # its threads, and a stale id left behind would address the next request's
+      # response to the previous request's client.
+      def with(client_id)
+        previous = Thread.current[KEY]
+        Thread.current[KEY] = client_id
+        yield
+      ensure
+        Thread.current[KEY] = previous
+      end
+    end
+  end
+end

data/lib/fast_mcp_pubsub/delivery.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module FastMcpPubsub
+  # What a worker does with a message that arrives on the channel.
+  #
+  # Every worker receives every NOTIFY, so this is where a message is matched to
+  # the clients it is actually for: an addressed one reaches the single client
+  # that asked, and only on the worker holding it, while an unaddressed one — a
+  # genuine notification — still fans out. See AddressingPatch for how the target
+  # gets onto the envelope in the first place.
+  module Delivery
+    private
+
+    def handle_notification(pid, payload)
+      FastMcpPubsub.logger.debug "FastMcpPubsub: Received notification from PID #{pid}: #{payload}"
+
+      begin
+        envelope = JSON.parse(payload)
+        message = unwrap(envelope)
+        return unless message # Reference already expired
+
+        deliver_to_transports(message, target_of(envelope))
+      rescue JSON::ParserError => e
+        FastMcpPubsub.logger.error "FastMcpPubsub: Invalid JSON payload: #{e.message}"
+      rescue StandardError => e
+        FastMcpPubsub.logger.error "FastMcpPubsub: Error handling notification: #{e.message}"
+      end
+    end
+
+    # The client this message is addressed to, or nil for a fan-out.
+    def target_of(envelope)
+      envelope["_pubsub_target"] if envelope.is_a?(Hash)
+    end
+
+    # Unwraps the three shapes that arrive on the channel: an inline message, a
+    # database reference for one too large to fit in a NOTIFY, and a bare
+    # JSON-RPC message with no envelope at all — which is what a worker still
+    # running an older gem publishes during a rolling restart.
+    def unwrap(envelope)
+      return envelope unless envelope.is_a?(Hash)
+      return envelope["_pubsub_message"] if envelope.key?("_pubsub_message")
+      return envelope unless envelope.key?("_pubsub_ref")
+
+      stored_payload = MessageStore.fetch(envelope["_pubsub_ref"])
+      stored_payload && JSON.parse(stored_payload)
+    end
+
+    def deliver_to_transports(message, client_id = nil)
+      # Find active RackTransport instances and send to local clients
+      return unless defined?(FastMcp::Transports::RackTransport)
+
+      transports = transport_instances
+      FastMcpPubsub.logger.debug "FastMcpPubsub: Found #{transports.size} transport instances"
+
+      transports.each do |transport|
+        FastMcpPubsub.logger.debug "FastMcpPubsub: Sending message to transport #{transport.object_id}"
+        next transport.send_local_message_to(client_id, message) if client_id
+
+        transport.send_local_message(message)
+      end
+    end
+
+    def transport_instances
+      # Find all RackTransport instances - don't filter by running? since it's not reliably implemented
+      ObjectSpace.each_object(FastMcp::Transports::RackTransport).to_a
+    rescue StandardError
+      []
+    end
+  end
+end

data/lib/fast_mcp_pubsub/message_store.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module FastMcpPubsub
+  class MessageStore
+    TABLE_NAME = "fast_mcp_pubsub_messages"
+
+    class << self
+      def store(payload)
+        ensure_table_exists
+        id = SecureRandom.uuid
+        ActiveRecord::Base.connection.execute(
+          "INSERT INTO #{TABLE_NAME} (id, payload, created_at) VALUES (#{quote(id)}, #{quote(payload)}, NOW())"
+        )
+        id
+      end
+
+      def fetch(id)
+        ensure_table_exists
+        ActiveRecord::Base.connection.select_value(
+          "SELECT payload FROM #{TABLE_NAME} WHERE id = #{quote(id)}"
+        )
+      end
+
+      def cleanup(older_than: Time.now - 300)
+        return unless @table_exists
+
+        ActiveRecord::Base.connection.execute(
+          "DELETE FROM #{TABLE_NAME} WHERE created_at < #{quote(older_than.iso8601)}"
+        )
+      end
+
+      def ensure_table_exists
+        return if @table_exists
+
+        unless ActiveRecord::Base.connection.table_exists?(TABLE_NAME)
+          ActiveRecord::Base.connection.execute(<<~SQL)
+            CREATE TABLE IF NOT EXISTS #{TABLE_NAME} (
+              id UUID PRIMARY KEY,
+              payload TEXT NOT NULL,
+              created_at TIMESTAMP NOT NULL DEFAULT NOW()
+            )
+          SQL
+        end
+        @table_exists = true
+      end
+
+      private
+
+      def quote(value)
+        ActiveRecord::Base.connection.quote(value)
+      end
+    end
+  end
+end

data/lib/fast_mcp_pubsub/rack_transport_patch.rb

@@ -30,6 +30,7 @@ module FastMcpPubsub
       add_basic_methods
       add_send_message_override
       add_fallback_method
+      AddressingPatch.apply!
     end
 
     def self.add_basic_methods
@@ -46,7 +47,9 @@ module FastMcpPubsub
         alias_method :send_message_original, :send_message if method_defined?(:send_message)
 
         define_method(:send_message) do |message|
-          FastMcpPubsub.config.enabled ? broadcast_with_fallback(message) : send_local_message(message)
+          return send_local_message(message) unless FastMcpPubsub.config.enabled
+
+          broadcast_with_fallback(message, FastMcpPubsub::CurrentClient.id)
         end
 
         alias_method :send_message_with_pubsub, :send_message
@@ -57,12 +60,15 @@ module FastMcpPubsub
       FastMcp::Transports::RackTransport.class_eval do
         return if method_defined?(:broadcast_with_fallback)
 
-        define_method(:broadcast_with_fallback) do |message|
+        define_method(:broadcast_with_fallback) do |message, client_id = nil|
           FastMcpPubsub.logger.debug "RackTransport: Broadcasting message via PostgreSQL PubSub"
-          FastMcpPubsub::Service.broadcast(message)
+          FastMcpPubsub::Service.broadcast(message, client_id)
         rescue StandardError => e
           FastMcpPubsub.logger.error "RackTransport: Error broadcasting message: #{e.message}"
-          send_local_message(message)
+          # An addressed message stays addressed even when the cluster hop fails.
+          # Falling back to the fan-out would answer every other open session with
+          # this client's data, which is the failure the addressing exists to end.
+          client_id ? send_local_message_to(client_id, message) : send_local_message(message)
         end
       end
     end

data/lib/fast_mcp_pubsub/railtie.rb

@@ -27,6 +27,27 @@ module FastMcpPubsub
       FastMcpPubsub::RackTransportPatch.apply_patch!
     end
 
+    # Handle hot-reload in development mode - stop/restart listener to avoid connection pool issues
+    initializer "fast_mcp_pubsub.reloader_hooks" do |app|
+      railtie = self
+
+      # Stop listener before hot-reload to release dedicated connection
+      app.reloader.before_class_unload do
+        if FastMcpPubsub::Service.listener_thread&.alive?
+          Rails.logger.info "FastMcpPubsub: Stopping listener before code reload"
+          FastMcpPubsub::Service.stop_listener
+        end
+      end
+
+      # Restart listener after hot-reload completes
+      app.reloader.to_complete do
+        if railtie.send(:should_restart_listener?)
+          Rails.logger.info "FastMcpPubsub: Restarting listener after code reload"
+          FastMcpPubsub::Service.start_listener
+        end
+      end
+    end
+
     # NOTE: For cluster mode, add FastMcpPubsub::Service.start_listener to your
     # on_worker_boot hook in config/puma/production.rb
 
@@ -40,8 +61,25 @@ module FastMcpPubsub
         !instance_variable_get(:@listener_started)
     end
 
+    def should_restart_listener?
+      # For reloader - don't check @listener_started, just basic conditions
+      web_server_environment? &&
+        !cluster_mode? &&
+        FastMcpPubsub.config.enabled &&
+        FastMcpPubsub.config.auto_start &&
+        !FastMcpPubsub::Service.listener_thread&.alive?
+    end
+
     def web_server_environment?
-      defined?(Rails::Server) || defined?(Puma) || ENV["MCP_SERVER_AUTO_START"] == "true"
+      defined?(Rails::Server) || puma_cli_running? || ENV["MCP_SERVER_AUTO_START"] == "true"
+    end
+
+    def puma_cli_running?
+      # defined?(Puma) is true whenever Puma gem is loaded (even in test runner, rake tasks, etc.)
+      # Puma.cli_config is only set when Puma was actually started via CLI (rails server, puma command)
+      defined?(Puma) &&
+        Puma.respond_to?(:cli_config) &&
+        !Puma.cli_config.nil?
     end
 
     def cluster_mode?

data/lib/fast_mcp_pubsub/service.rb

@@ -6,12 +6,22 @@ module FastMcpPubsub
     MAX_PAYLOAD_SIZE = 7800 # PostgreSQL NOTIFY limit is 8000 bytes, leave some margin
 
     class << self
-      attr_reader :listener_thread
-
-      def broadcast(message)
-        payload = message.to_json
-
-        payload_too_large?(payload) ? send_error_response(message, payload) : send_payload(payload)
+      include Delivery
+
+      attr_reader :listener_thread, :dedicated_connection
+      attr_accessor :shutdown_requested
+
+      # Publishes one MCP message to the cluster.
+      #
+      # client_id names the SSE client the message answers; nil means it is for
+      # everyone, which is what a genuine notification is. A response carries an
+      # id because every worker receives every NOTIFY, and without one the worker
+      # holding an unrelated session would write this answer into it.
+      def broadcast(message, client_id = nil)
+        envelope = envelope_for(message)
+        envelope[:_pubsub_target] = client_id if client_id
+
+        send_payload(envelope.to_json)
       rescue StandardError => e
         FastMcpPubsub.logger.error "FastMcpPubsub: Error broadcasting message: #{e.message}"
         raise
@@ -40,16 +50,51 @@ module FastMcpPubsub
       end
 
       def stop_listener
-        return unless @listener_thread&.alive?
+        # A thread that has already died on its own still leaves its reference
+        # behind, and every caller reads that reference as "a listener is
+        # running". Clearing it is part of stopping, not a separate errand.
+        return @listener_thread = nil unless @listener_thread&.alive?
 
         FastMcpPubsub.logger.info "FastMcpPubsub: Stopping listener thread for PID #{Process.pid}"
-        @listener_thread.kill
-        @listener_thread.join(5) # Wait max 5 seconds
-        @listener_thread = nil
+        @shutdown_requested = true
+
+        wake_listener
+        join_listener
+        discard_dedicated_connection
+        @shutdown_requested = false
       end
 
       private
 
+      # Cancels the in-flight wait_for_notify so the thread reaches its next
+      # shutdown check instead of sitting out the rest of the timeout.
+      def wake_listener
+        @dedicated_connection&.cancel
+      rescue StandardError
+        nil
+      end
+
+      # Five seconds to notice, then it is taken down: a thread stuck inside
+      # PG.connect during a reconnect never notices on its own.
+      def join_listener
+        @listener_thread.join(5)
+
+        if @listener_thread&.alive?
+          @listener_thread.kill
+          @listener_thread.join(1)
+        end
+
+        @listener_thread = nil
+      end
+
+      def discard_dedicated_connection
+        @dedicated_connection&.close
+      rescue StandardError
+        nil
+      ensure
+        @dedicated_connection = nil
+      end
+
       def send_payload(payload)
         channel = FastMcpPubsub.config.channel_name
         FastMcpPubsub.logger.debug "FastMcpPubsub: Broadcasting message to #{channel}: #{payload.bytesize} bytes"
@@ -63,83 +108,88 @@ module FastMcpPubsub
         payload.bytesize > MAX_PAYLOAD_SIZE
       end
 
-      def send_error_response(message, payload)
-        FastMcpPubsub.logger.error "FastMcpPubsub: Payload too large (#{payload.bytesize} bytes > #{MAX_PAYLOAD_SIZE} bytes)"
-
-        error_message = {
-          jsonrpc: "2.0",
-          id: message[:id],
-          error: {
-            code: -32_001,
-            message: "Response too large for PostgreSQL NOTIFY. Try requesting smaller page size."
-          }
-        }
+      # Wraps the message for the wire: inline when it fits in a NOTIFY, a
+      # database reference when it does not. The envelope is also what gives the
+      # target somewhere to live.
+      def envelope_for(message)
+        payload = message.to_json
+        return { _pubsub_message: message } unless payload_too_large?(payload)
 
-        send_payload(error_message.to_json)
+        ref_id = MessageStore.store(payload)
+        FastMcpPubsub.logger.debug "FastMcpPubsub: Payload too large (#{payload.bytesize} bytes), stored as #{ref_id}"
+        { _pubsub_ref: ref_id }
       end
 
+      # The listener thread's whole life. `retry` re-enters the begin block
+      # without running the ensure, which is what lets a reconnect keep the
+      # LISTEN it is about to re-establish — so the split below has to keep the
+      # begin/rescue/ensure here rather than push it into a helper.
       def listen_loop
         channel = FastMcpPubsub.config.channel_name
 
         begin
-          ActiveRecord::Base.connection_pool.with_connection do |conn|
-            raw_conn = conn.raw_connection
-
-            FastMcpPubsub.logger.info "FastMcpPubsub: Listening on #{channel} for PID #{Process.pid}"
-            raw_conn.async_exec("LISTEN #{channel}")
-
-            begin
-              loop do
-                raw_conn.wait_for_notify do |channel, pid, payload|
-                  handle_notification(channel, pid, payload)
-                end
-              end
-            ensure
-              begin
-                raw_conn.async_exec("UNLISTEN #{channel}")
-              rescue StandardError => e
-                FastMcpPubsub.logger.error "FastMcpPubsub: Error during UNLISTEN: #{e.message}"
-              end
-            end
-          end
+          open_listener(channel)
+          consume_notifications
         rescue StandardError => e
-          FastMcpPubsub.logger.error "FastMcpPubsub: Listener error: #{e.message}"
-          FastMcpPubsub.logger.error e.backtrace.join("\n")
-
-          # Restart after error
-          sleep 1
-          retry
+          retry if listener_should_recover?(e)
+        ensure
+          close_listener(channel)
         end
       end
 
-      def handle_notification(_channel, pid, payload)
-        FastMcpPubsub.logger.debug "FastMcpPubsub: Received notification from PID #{pid}: #{payload}"
+      def open_listener(channel)
+        @dedicated_connection = create_dedicated_connection
 
-        begin
-          message = JSON.parse(payload)
+        FastMcpPubsub.logger.info "FastMcpPubsub: Listening on #{channel} for PID #{Process.pid}"
+        @dedicated_connection.exec("LISTEN #{channel}")
+      end
+
+      def consume_notifications
+        loop do
+          break if @shutdown_requested
 
-          # Find active RackTransport instances and send to local clients
-          if defined?(FastMcp::Transports::RackTransport)
-            transports = transport_instances
-            FastMcpPubsub.logger.debug "FastMcpPubsub: Found #{transports.size} transport instances"
+          @cleanup_counter = (@cleanup_counter || 0) + 1
+          MessageStore.cleanup if (@cleanup_counter % 60).zero? # Every ~60s (1s per loop)
 
-            transports.each do |transport|
-              FastMcpPubsub.logger.debug "FastMcpPubsub: Sending message to transport #{transport.object_id}"
-              transport.send_local_message(message)
-            end
+          @dedicated_connection.wait_for_notify(1) do |_channel, pid, payload|
+            handle_notification(pid, payload)
           end
-        rescue JSON::ParserError => e
-          FastMcpPubsub.logger.error "FastMcpPubsub: Invalid JSON payload: #{e.message}"
-        rescue StandardError => e
-          FastMcpPubsub.logger.error "FastMcpPubsub: Error handling notification: #{e.message}"
         end
       end
 
-      def transport_instances
-        # Find all RackTransport instances - don't filter by running? since it's not reliably implemented
-        ObjectSpace.each_object(FastMcp::Transports::RackTransport).to_a
-      rescue StandardError
-        []
+      # Reports whether the loop should come back up, having logged and paused if
+      # so. A shutdown in progress is not an error to recover from — it is the
+      # exit, and the error is the connection being cancelled out from under us.
+      def listener_should_recover?(error)
+        return false if @shutdown_requested
+
+        FastMcpPubsub.logger.error "FastMcpPubsub: Listener error: #{error.message}"
+        FastMcpPubsub.logger.error error.backtrace.join("\n")
+        sleep 1
+        true
+      end
+
+      def close_listener(channel)
+        @dedicated_connection&.exec("UNLISTEN #{channel}")
+        @dedicated_connection&.close
+      rescue StandardError => e
+        FastMcpPubsub.logger.error "FastMcpPubsub: Error during cleanup: #{e.message}"
+      ensure
+        @dedicated_connection = nil
+      end
+
+      def create_dedicated_connection
+        db_config = ActiveRecord::Base.connection_db_config.configuration_hash
+
+        conn_params = {
+          host: db_config[:host],
+          port: db_config[:port],
+          dbname: db_config[:database],
+          user: db_config[:username],
+          password: db_config[:password]
+        }.compact
+
+        PG.connect(conn_params)
       end
     end
   end

data/lib/fast_mcp_pubsub/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FastMcpPubsub
-  VERSION = "1.1.0"
+  VERSION = "1.4.0"
 end

data/lib/fast_mcp_pubsub.rb

@@ -2,6 +2,9 @@
 
 require_relative "fast_mcp_pubsub/version"
 require_relative "fast_mcp_pubsub/configuration"
+require_relative "fast_mcp_pubsub/current_client"
+require_relative "fast_mcp_pubsub/message_store"
+require_relative "fast_mcp_pubsub/delivery"
 require_relative "fast_mcp_pubsub/service"
 
 # PostgreSQL NOTIFY/LISTEN clustering support for FastMcp RackTransport.
@@ -30,5 +33,6 @@ module FastMcpPubsub
 end
 
 # Load patch after module is fully defined
+require_relative "fast_mcp_pubsub/addressing_patch"
 require_relative "fast_mcp_pubsub/rack_transport_patch"
 require_relative "fast_mcp_pubsub/railtie" if defined?(Rails)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: fast_mcp_pubsub
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.4.0
 platform: ruby
 authors:
 - josefchmel
 bindir: exe
 cert_chain: []
-date: 2025-10-02 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -115,17 +115,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".mcp.json"
-- ".rubocop.yml"
-- ".ruby-version"
 - CHANGELOG.md
-- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
-- lib/.DS_Store
 - lib/fast_mcp_pubsub.rb
+- lib/fast_mcp_pubsub/addressing_patch.rb
 - lib/fast_mcp_pubsub/configuration.rb
+- lib/fast_mcp_pubsub/current_client.rb
+- lib/fast_mcp_pubsub/delivery.rb
+- lib/fast_mcp_pubsub/message_store.rb
 - lib/fast_mcp_pubsub/rack_transport_patch.rb
 - lib/fast_mcp_pubsub/railtie.rb
 - lib/fast_mcp_pubsub/service.rb
@@ -154,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.6
 specification_version: 4
 summary: PostgreSQL NOTIFY/LISTEN clustering support for FastMcp RackTransport
 test_files: []

data/.mcp.json

@@ -1,30 +0,0 @@
-{
-  "mcpServers": {
-    "workvector-production": {
-      "type": "sse",
-      "name": "WorkVector Production",
-      "url": "https://workvector.com/mcp/sse",
-      "headers": {
-        "Authorization": "Bearer ${WORKVECTOR_TOKEN}"
-      }
-    },
-    "filesystem-project": {
-      "type": "stdio",
-      "name": "Filesystem",
-      "command": "npx",
-      "args": [
-        "-y",
-        "@modelcontextprotocol/server-filesystem",
-        "${PWD}"
-      ]
-    },
-    "llmmn-production": {
-      "type": "sse",
-      "name": "LLM Memory Notes Production",
-      "url": "https://llm-memory.com/mcp/sse",
-      "headers": {
-        "Authorization": "Bearer ${LLMMN_TOKEN}"
-      }
-    }
-  }
-}

data/.rubocop.yml

@@ -1,40 +0,0 @@
-AllCops:
-  TargetRubyVersion: 3.1
-  NewCops: enable
-  SuggestExtensions: false
-
-plugins:
-  - rubocop-minitest
-
-Layout/LineLength:
-  Max: 200
-
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes
-
-# Relax some metrics for reasonable code
-Metrics/ClassLength:
-  Max: 150
-
-Metrics/MethodLength:
-  Max: 30
-
-Metrics/AbcSize:
-  Max: 35
-
-# Allow development dependencies in gemspec for gems
-Gemspec/DevelopmentDependencies:
-  Enabled: false
-
-Style/Documentation:
-  Enabled: false
-
-# Allow longer blocks for configuration and setup
-Metrics/BlockLength:
-  Exclude:
-    - "test/**/*"
-    - "*.gemspec"
-    - "lib/fast_mcp_pubsub/railtie.rb"  # Debug logging temporarily increases block length

data/.ruby-version

@@ -1 +0,0 @@
-ruby-3.4.2

data/CLAUDE.md

@@ -1,108 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code when working with the `fast_mcp_pubsub` gem.
-
-## Gem Overview
-
-FastMcp PubSub provides PostgreSQL NOTIFY/LISTEN clustering support for FastMcp RackTransport, enabling message broadcasting across multiple Puma workers in cluster mode.
-
-## Code Conventions
-
-### Code Quality
-- Max 200 chars/line (soft limit - prefer readability over strict compliance)
-  - breaking Ruby chain calls destroys the natural sentence flow and readability
-- 14 lines/method, 110 lines/class
-- Comments and tests in English
-- KEEP CODE DRY (Don't Repeat Yourself)
-
-### Error Handling
-- Use meaningful exception classes (not generic StandardError)
-- Log errors with context using the configured logger
-- Proper error propagation with fallback mechanisms
-- Use `rescue_from` for common exceptions in Rails integration
-
-### Performance Considerations
-- Use database connection pooling efficiently
-- Avoid blocking operations in main threads
-- Cache expensive operations
-- Monitor thread lifecycle and cleanup
-
-### Thread Safety
-- All operations must be thread-safe for cluster mode
-- Use proper synchronization when accessing shared resources
-- Handle thread lifecycle correctly (creation, monitoring, cleanup)
-- Use connection checkout/checkin pattern for database operations
-
-### Gem Specific Guidelines
-
-#### Configuration
-- Use configuration object pattern for all settings
-- Provide sensible defaults that work out of the box
-- Make all components configurable but not required
-- Support both programmatic and initializer-based configuration
-
-#### Rails Integration
-- Use Railtie for automatic Rails integration
-- Hook into appropriate Rails lifecycle events
-- Respect Rails conventions for logging and error handling
-- Provide manual configuration options for non-Rails usage
-
-#### Error Recovery
-- Implement automatic retry with backoff for transient errors
-- Provide fallback mechanisms when PubSub fails
-- Log errors appropriately without flooding logs
-- Handle connection failures gracefully
-
-#### Testing
-- Test all public interfaces
-- Mock external dependencies (PostgreSQL, FastMcp)
-- Test error conditions and edge cases
-- Provide test helpers for gem users
-- Test both Rails and non-Rails usage
-
-## Architecture
-
-### Components
-
-1. **FastMcpPubsub::Service** - Core PostgreSQL NOTIFY/LISTEN service
-2. **FastMcpPubsub::Configuration** - Configuration management
-3. **FastMcpPubsub::RackTransportPatch** - Monkey patch for FastMcp transport
-4. **FastMcpPubsub::Railtie** - Rails integration and lifecycle management
-
-### Message Flow
-
-1. `RackTransport#send_message` → `FastMcpPubsub::Service.broadcast`
-2. `Service.broadcast` → PostgreSQL NOTIFY
-3. Each worker's listener thread receives NOTIFY
-4. Listener calls `RackTransport#send_local_message` for local clients
-
-### Thread Management
-
-- One listener thread per worker process
-- Thread cleanup on process exit
-- Automatic restart on listener errors
-- Connection pooling for database operations
-
-## Dependencies
-
-- **Rails** (>= 7.0) - Core framework integration
-- **PostgreSQL** (via pg gem >= 1.0) - Database NOTIFY/LISTEN
-- **ActiveRecord** - Connection pooling and database access
-- **FastMcp** - The transport being patched (development/test dependency)
-
-## Development
-
-### Running Tests
-```bash
-bundle exec rake test
-```
-
-### Linting
-```bash
-bundle exec rubocop
-```
-
-### Console
-```bash
-bundle exec rake console
-```