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 +4 -4
- data/CHANGELOG.md +115 -0
- data/README.md +17 -3
- data/lib/fast_mcp_pubsub/addressing_patch.rb +54 -4
- data/lib/fast_mcp_pubsub/configuration.rb +4 -1
- data/lib/fast_mcp_pubsub/rack_transport_patch.rb +13 -5
- data/lib/fast_mcp_pubsub/version.rb +1 -1
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 39f015a5ee1eae5910299c59638bd5c0be6e2c7b25a08f20f19a333f939d8b6c
|
|
4
|
+
data.tar.gz: 6e842aaafd59fc7d8e3e0d524a508af81ca35ffc429ba9849f471b395fa45fb1
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
|
126
|
-
|
|
127
|
-
|
|
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
|
-
|
|
80
|
-
|
|
81
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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
|
|