fast_mcp_pubsub 1.4.0 → 1.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 9a955c6fc8f0b93d011d31fd196d7605b4925eb114d1355f99232ee2f8a15efb
4
- data.tar.gz: 5b5ceaa86be4ecdb6cf74d2d913b0efb12b1f7a0668e0fb171a92d859cff1993
3
+ metadata.gz: 39f015a5ee1eae5910299c59638bd5c0be6e2c7b25a08f20f19a333f939d8b6c
4
+ data.tar.gz: 6e842aaafd59fc7d8e3e0d524a508af81ca35ffc429ba9849f471b395fa45fb1
5
5
  SHA512:
6
- metadata.gz: 67bc13d26facefac99906e013bf444805412422690e444037a3d11779703c879f225038e32813614d6f84f58b50f13d77ac88266d67e4729902e69880ccdbb0d
7
- data.tar.gz: eaa38f519aad1c30c7aaac06c35dff2e120b27623f7e1097728a70f442de167b0f9fe0b91f1b4f36f93af51f70a8301d99c4ae96a7c2f27dc8e15ae50b7b42ae
6
+ metadata.gz: 1f6fbcaf8cbf946b6f3d4c27eee3845ebd360327d86f28e1856fcd010e706743afc417fc89e51d8f0d0ff710b97f11c91a10f2b835e909dc7dbc5e3df87fe3ac
7
+ data.tar.gz: 3906ac97d0f5b95a759179853d1372152fcdf1906d49f09e69d4904e0b4c3265d4450c1e1439dca3e18a822fb4a97634a0fe1b7007b72eb2fbae39cd560cd7fa
data/CHANGELOG.md CHANGED
@@ -5,6 +5,34 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [1.4.1] - 2026-11-18
9
+
10
+ ### Fixed
11
+ - **A client that vanished no longer stalls every SSE response on its worker.**
12
+ The hijacked SSE socket had no write timeout, so a write to a client that
13
+ disappeared without closing its TCP connection blocked until TCP gave up
14
+ (56 s observed in production). That write runs on the worker's PubSub listener
15
+ thread, so every response for that worker waited behind it, and FastMcp's
16
+ keep-alive thread blocked the same way. The socket now gets `IO#timeout`
17
+ (`sse_write_timeout`, 10 s by default); a blocked write raises
18
+ `IO::TimeoutError`, and the client is unregistered as disconnected.
19
+ - **A response with no client in scope is no longer fanned out.** A POST to the
20
+ messages endpoint without `client_id` left `CurrentClient` empty, and its
21
+ response went to every SSE client on every worker. Such a POST is now refused
22
+ with HTTP 400 (JSON-RPC `-32600`) before it runs, and logged with the caller's
23
+ IP and user agent. Every endpoint the server hands out carries `client_id`, so
24
+ only a client that ignored its endpoint is affected.
25
+ - With PubSub disabled, an addressed response went to every local SSE client;
26
+ it now goes only to its own client, as it does with PubSub enabled.
27
+
28
+ ### Added
29
+ - `sse_write_timeout` configuration option (seconds, default `10`, `nil` for no
30
+ timeout). An IO that takes no timeout (Ruby < 3.2) is logged as a warning.
31
+ - `FastMcpPubsub::UnaddressedResponseError`, raised when a JSON-RPC response
32
+ (a message with `result` or `error`) is sent with no client in scope. It is
33
+ never written to any client. Notifications and server-to-client requests
34
+ still fan out.
35
+
8
36
  ## [1.4.0] - 2026-08-20
9
37
 
10
38
  ### Fixed
@@ -36,6 +64,93 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
36
64
  - Bare, un-enveloped payloads from a worker still running an older gem are
37
65
  recognised and delivered, so a rolling restart does not drop messages.
38
66
 
67
+ ## [1.3.3] - 2026-03-02
68
+
69
+ ### Fixed
70
+ - The listener no longer starts under the test runner or a rake task. The
71
+ Railtie checked `defined?(Puma)`, which is true whenever the gem is merely
72
+ loaded; it now checks `Puma.cli_config`, so only a Puma actually launched via
73
+ its CLI counts.
74
+ - `stop_listener` force-kills the listener thread after the five-second join,
75
+ so a process can always exit even when `PG.connect` blocks during a reconnect.
76
+
77
+ ## [1.3.2] - 2026-02-06
78
+
79
+ ### Fixed
80
+ - Multi-worker race on database-stored payloads. `MessageStore` deleted the row
81
+ as it read it, so of all the workers a NOTIFY woke, exactly one got the
82
+ payload — and when that was a worker holding no SSE clients, the message was
83
+ simply lost and the client timed out. Reading no longer deletes; the periodic
84
+ cleanup handles removal. Cleanup also guards against a missing table.
85
+
86
+ ## [1.3.1] - 2026-02-06
87
+
88
+ ### Fixed
89
+ - Unix socket connections with peer authentication. Hardcoded host and port
90
+ defaults forced a TCP connection; only the parameters actually present in the
91
+ Rails config are passed to `PG.connect` now, so an absent host means the
92
+ socket, as production expects.
93
+
94
+ ## [1.3.0] - 2026-02-06
95
+
96
+ ### Added
97
+ - Database overflow for responses larger than PostgreSQL NOTIFY's 8000-byte
98
+ limit. Payloads under 7800 bytes still go straight down the channel; larger
99
+ ones are stored via the new `MessageStore` and the NOTIFY carries a UUID
100
+ reference. Stored rows are cleaned up roughly every 60 seconds by the listener.
101
+
102
+ ## [1.2.0] - 2026-01-29
103
+
104
+ ### Fixed
105
+ - "Lost synchronization with server" crashes during development hot-reload. The
106
+ listener took its raw PostgreSQL connection from the ActiveRecord pool and so
107
+ could share it with the main Rails thread. It now opens a dedicated connection
108
+ outside the pool.
109
+
110
+ ### Changed
111
+ - Shutdown is cooperative — a `@shutdown_requested` flag and a one-second
112
+ `wait_for_notify` timeout instead of `Thread.kill` — and reloader hooks stop
113
+ and restart the listener across a hot-reload.
114
+
115
+ ## [1.1.0] - 2025-08-20
116
+
117
+ ### Changed
118
+ - **Breaking.** Cluster mode is configured by hand: add
119
+ `FastMcpPubsub::Service.start_listener` to your `on_worker_boot` hook. The
120
+ automatic worker detection of 1.0.3–1.0.5 never became reliable and is gone;
121
+ the Railtie now only keeps the listener out of the master process.
122
+
123
+ ## [1.0.5] - 2025-08-20
124
+
125
+ ### Fixed
126
+ - Worker detection reworked around an `after_initialize` callback, replacing the
127
+ `Puma.cli_config` hook registration that did not fire dependably.
128
+
129
+ ## [1.0.4] - 2025-08-20
130
+
131
+ ### Fixed
132
+ - `NoMethodError` on Puma's `UserFileDefaultOptions`, which has no `dig`.
133
+
134
+ ## [1.0.3] - 2025-08-20
135
+
136
+ ### Fixed
137
+ - The listener started in the master process rather than the workers. Cluster
138
+ mode is detected and worker boot hooks registered so it starts only in a
139
+ worker.
140
+
141
+ ## [1.0.2] - 2025-08-20
142
+
143
+ ### Changed
144
+ - Extensive debug logging around listener startup, added to diagnose workers
145
+ that never began listening in production cluster mode.
146
+
147
+ ## [1.0.1] - 2025-08-20
148
+
149
+ ### Fixed
150
+ - No messages reached SSE clients in production. `transport_instances` filtered
151
+ on `running?`, which production transports never set, so the list came back
152
+ empty. The filter is gone.
153
+
39
154
  ## [1.0.0] - 2025-08-19
40
155
 
41
156
  ### Added
data/README.md CHANGED
@@ -58,6 +58,7 @@ FastMcpPubsub.configure do |config|
58
58
  config.channel_name = 'my_custom_channel' # Custom PostgreSQL NOTIFY channel
59
59
  config.auto_start = true # Start listener automatically (default: true)
60
60
  config.connection_pool_size = 10 # Database connection pool size
61
+ config.sse_write_timeout = 10 # Seconds a write to one SSE client may block
61
62
  end
62
63
  ```
63
64
 
@@ -122,9 +123,21 @@ The gem closes that by carrying FastMcp's own `client_id` end to end:
122
123
  - each worker delivers a targeted message only to that client, and ignores one
123
124
  addressed to a client another worker holds
124
125
 
125
- A message with no target — a genuine notification, or a request from a client
126
- that supplied no id — falls back to the previous fan-out, so older clients keep
127
- working.
126
+ A notification (or a server-to-client request) has no target and still fans
127
+ out. A response never does:
128
+
129
+ - a POST without `client_id` is refused with HTTP 400 before it runs, and logged
130
+ with the caller's IP and user agent
131
+ - a response sent with no client in scope raises
132
+ `FastMcpPubsub::UnaddressedResponseError` and is written to no client
133
+
134
+ ### Write timeout
135
+
136
+ Each SSE socket gets `IO#timeout = sse_write_timeout`. A client that vanished
137
+ without closing its TCP connection would otherwise block a write until TCP gives
138
+ up, and that write runs on the worker's PubSub listener thread, so every SSE
139
+ response on the worker would wait behind it. With the timeout, the blocked write
140
+ raises `IO::TimeoutError` and the client is unregistered.
128
141
 
129
142
  ## Configuration Options
130
143
 
@@ -134,6 +147,7 @@ working.
134
147
  | `channel_name` | `'mcp_broadcast'` | PostgreSQL NOTIFY channel name |
135
148
  | `auto_start` | `true` | Start listener automatically |
136
149
  | `connection_pool_size` | `5` | Database connection pool size |
150
+ | `sse_write_timeout` | `10` | Seconds a write to one SSE client may block before the client counts as gone; `nil` for no timeout |
137
151
 
138
152
  **Note**: Logging is handled automatically via `FastMcpPubsub.logger` which returns `Rails.logger`.
139
153
 
@@ -3,6 +3,10 @@
3
3
  require "cgi"
4
4
 
5
5
  module FastMcpPubsub
6
+ # Raised when a JSON-RPC response is sent with no client in scope. Delivering
7
+ # it anyway would mean writing it to every connected SSE client.
8
+ class UnaddressedResponseError < Error; end
9
+
6
10
  # The half of the RackTransport patch that makes a response reachable by the one
7
11
  # client that asked for it.
8
12
  #
@@ -16,6 +20,10 @@ module FastMcpPubsub
16
20
  # back on its POSTs (the capture), and have somewhere to be delivered to (the
17
21
  # targeted send).
18
22
  module AddressingPatch
23
+ # The members that make a JSON-RPC message a response rather than a
24
+ # notification or a request.
25
+ RESPONSE_KEYS = %w[result error].freeze
26
+
19
27
  def self.apply!
20
28
  add_targeted_send
21
29
  add_sse_writer
@@ -65,6 +73,11 @@ module FastMcpPubsub
65
73
  # Records which client the POST belongs to, so send_message can address the
66
74
  # response FastMcp is about to write.
67
75
  #
76
+ # A POST without a client_id is refused before it runs. Every endpoint the
77
+ # server hands out carries one, so such a POST comes from a client that
78
+ # ignored its endpoint, and the only place its response could go is every
79
+ # open stream: one client's data in everybody's session.
80
+ #
68
81
  # request.GET rather than request.params on purpose: params merges the POST
69
82
  # body, and reading the body here would leave nothing for the JSON parse that
70
83
  # follows.
@@ -76,11 +89,17 @@ module FastMcpPubsub
76
89
  alias_method :handle_message_request_without_pubsub, :handle_message_request_with_server
77
90
 
78
91
  define_method(:handle_message_request_with_server) do |request, server|
79
- FastMcpPubsub::CurrentClient.with(request.GET["client_id"]) do
80
- handle_message_request_without_pubsub(request, server)
81
- end
92
+ client_id = request.GET["client_id"]
93
+ return missing_client_id_response(request) if client_id.to_s.empty?
94
+
95
+ FastMcpPubsub::CurrentClient.with(client_id) { handle_message_request_without_pubsub(request, server) }
96
+ end
97
+
98
+ define_method(:missing_client_id_response) do |request|
99
+ FastMcpPubsub.logger.warn "FastMcpPubsub: Refused #{request.request_method} #{request.path} without client_id from #{request.ip} (#{request.user_agent})"
100
+ json_rpc_error_response(400, -32_600, "Invalid Request: client_id is missing; POST to the endpoint URL the SSE stream sent")
82
101
  end
83
- private :handle_message_request_with_server
102
+ private :handle_message_request_with_server, :missing_client_id_response
84
103
  end
85
104
  end
86
105
 
@@ -98,6 +117,7 @@ module FastMcpPubsub
98
117
  alias_method :setup_sse_connection_without_pubsub, :setup_sse_connection
99
118
 
100
119
  define_method(:setup_sse_connection) do |client_id, io, env|
120
+ FastMcpPubsub::AddressingPatch.apply_write_timeout(io)
101
121
  query = FastMcpPubsub::AddressingPatch.query_with_client_id(env["QUERY_STRING"], client_id)
102
122
  setup_sse_connection_without_pubsub(client_id, io, env.merge("QUERY_STRING" => query))
103
123
  end
@@ -105,6 +125,36 @@ module FastMcpPubsub
105
125
  end
106
126
  end
107
127
 
128
+ # Bounds how long a write to one SSE client may block. A client that vanished
129
+ # without closing its TCP connection otherwise blocks the writer until TCP
130
+ # gives up (56 s in production), and that writer is the worker's PubSub
131
+ # listener thread, so every SSE response on the worker waits behind it.
132
+ #
133
+ # A blocked write then raises IO::TimeoutError, an IOError, which
134
+ # send_local_message_to and FastMcp's keep-alive loop already treat as a
135
+ # disconnect. IO#timeout= exists since Ruby 3.2; an IO without it is logged
136
+ # rather than quietly left unbounded.
137
+ def self.apply_write_timeout(io)
138
+ if io.respond_to?(:timeout=)
139
+ io.timeout = FastMcpPubsub.config.sse_write_timeout
140
+ else
141
+ FastMcpPubsub.logger.warn "FastMcpPubsub: #{io.class} takes no write timeout; a vanished SSE client can block its writer"
142
+ end
143
+ end
144
+
145
+ # A JSON-RPC response belongs to the client whose request produced it. With no
146
+ # client in scope the only delivery left is every open stream, so the
147
+ # response is refused loudly instead. Notifications and server-to-client
148
+ # requests carry a method rather than a result, and still fan out.
149
+ def self.ensure_addressed!(message, client_id)
150
+ return if client_id
151
+
152
+ fields = message.is_a?(String) ? JSON.parse(message) : message
153
+ return unless fields.is_a?(Hash) && fields.keys.map(&:to_s).intersect?(RESPONSE_KEYS)
154
+
155
+ raise UnaddressedResponseError, "JSON-RPC response id=#{(fields[:id] || fields["id"]).inspect} has no client in scope; it would reach every SSE client"
156
+ end
157
+
108
158
  # Appends client_id to an SSE query string, leaving a client that named its
109
159
  # own id alone — FastMcp honours that one, so overriding it would hand back an
110
160
  # endpoint pointing at a different session than the stream it arrived on.
@@ -3,13 +3,16 @@
3
3
  module FastMcpPubsub
4
4
  # Configuration class for FastMcpPubsub gem settings
5
5
  class Configuration
6
- attr_accessor :enabled, :channel_name, :auto_start, :connection_pool_size
6
+ attr_accessor :enabled, :channel_name, :auto_start, :connection_pool_size, :sse_write_timeout
7
7
 
8
8
  def initialize
9
9
  @enabled = true
10
10
  @channel_name = "mcp_broadcast"
11
11
  @auto_start = true
12
12
  @connection_pool_size = 5
13
+ # Seconds a write to one SSE client may block before that client counts as
14
+ # gone; nil waits for TCP to give up. See AddressingPatch.apply_write_timeout.
15
+ @sse_write_timeout = 10
13
16
  end
14
17
  end
15
18
  end
@@ -47,9 +47,11 @@ module FastMcpPubsub
47
47
  alias_method :send_message_original, :send_message if method_defined?(:send_message)
48
48
 
49
49
  define_method(:send_message) do |message|
50
- return send_local_message(message) unless FastMcpPubsub.config.enabled
50
+ client_id = FastMcpPubsub::CurrentClient.id
51
+ FastMcpPubsub::AddressingPatch.ensure_addressed!(message, client_id)
52
+ return broadcast_with_fallback(message, client_id) if FastMcpPubsub.config.enabled
51
53
 
52
- broadcast_with_fallback(message, FastMcpPubsub::CurrentClient.id)
54
+ deliver_locally(message, client_id)
53
55
  end
54
56
 
55
57
  alias_method :send_message_with_pubsub, :send_message
@@ -65,11 +67,17 @@ module FastMcpPubsub
65
67
  FastMcpPubsub::Service.broadcast(message, client_id)
66
68
  rescue StandardError => e
67
69
  FastMcpPubsub.logger.error "RackTransport: Error broadcasting message: #{e.message}"
68
- # An addressed message stays addressed even when the cluster hop fails.
69
- # Falling back to the fan-out would answer every other open session with
70
- # this client's data, which is the failure the addressing exists to end.
70
+ deliver_locally(message, client_id)
71
+ end
72
+
73
+ # An addressed message stays addressed without the cluster hop too: when
74
+ # PubSub is disabled or the broadcast fails. Falling back to the fan-out
75
+ # would answer every other open session with this client's data, which is
76
+ # the failure the addressing exists to end.
77
+ define_method(:deliver_locally) do |message, client_id|
71
78
  client_id ? send_local_message_to(client_id, message) : send_local_message(message)
72
79
  end
80
+ private :deliver_locally
73
81
  end
74
82
  end
75
83
 
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module FastMcpPubsub
4
- VERSION = "1.4.0"
4
+ VERSION = "1.4.1"
5
5
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: fast_mcp_pubsub
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.4.0
4
+ version: 1.4.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - josefchmel