fix(core): say why a never-acknowledged subscriptions/listen ended
A modern-era `subscriptions/listen` is a long-lived request: the first message on its stream must be `notifications/subscriptions/acknowledged`, and the JSON-RPC `result` for the listen id is reserved as the graceful-closure marker. A server that answers the listen request with a bare `result` is saying "acknowledged and closed in the same breath" — the SDK settles the subscription `graceful` and rejects the pending `listen()`. The Inspector read that rejection as an ordinary drop: eight re-lists over roughly a minute, the badge flickering `Reconnecting…`, and a final bare `Stream ended` that said nothing about why. Accepting the message was never wrong — it is a well-formed graceful-closure response. The silence was. - `core/mcp/subscriptionAck.ts` owns the predicate. The SDK gives this close no code of its own — it is the same `SdkError(ConnectionClosed)` any pre-ack close carries — so the predicate reads the message, since the alternative is refusing to retry a genuinely transient drop. - The condition is deterministic, so the stream ends on the first occurrence instead of spending the whole backoff run. Both routes are covered: the one a subscribe/unsubscribe reaches, and the one a reconnect reaches when an acknowledged stream drops and the server has since started refusing. - A `"never-acknowledged"` status of its own, not `"ended"` — `ended` means an expected close. It surfaces as the thrown error's message, an orange "Not acknowledged" badge, and a notice in the panel. - `subscriptions-never-acknowledged-http.json` reproduces it. It acknowledges the first listen that subscribes to a resource and refuses every one after, which is what makes the badge reachable by hand. Closes #2097 Signed-off-by: cliffhall <cliff@futurescale.com>
This commit is contained in:
parent
6bc3251962
commit
8535ae0c2f
1 changed files with 612 additions and 10 deletions
100
clients/web/src/test/core/mcp/subscriptionAck.test.ts
Normal file
100
clients/web/src/test/core/mcp/subscriptionAck.test.ts
Normal file
|
|
@ -0,0 +1,100 @@
|
|||
import { describe, it, expect } from "vitest";
|
||||
import { SdkError, SdkErrorCode } from "@modelcontextprotocol/client";
|
||||
import {
|
||||
isNeverAcknowledgedSubscriptionClose,
|
||||
subscriptionFailureMessage,
|
||||
NEVER_ACKNOWLEDGED_SUBSCRIPTION_MESSAGE,
|
||||
} from "@inspector/core/mcp/subscriptionAck.js";
|
||||
|
||||
/**
|
||||
* Unit coverage of the never-acknowledged predicate (#2097). The *live* check —
|
||||
* that the SDK still phrases this rejection the way the predicate expects — is
|
||||
* the integration test in `inspectorClient-subscriptions-era.test.ts`, which
|
||||
* drives a real server answering `subscriptions/listen` with a bare result.
|
||||
*/
|
||||
describe("isNeverAcknowledgedSubscriptionClose (#2097)", () => {
|
||||
const neverAcknowledged = () =>
|
||||
new SdkError(
|
||||
SdkErrorCode.ConnectionClosed,
|
||||
"subscriptions/listen: server closed the subscription gracefully before acknowledging",
|
||||
);
|
||||
|
||||
it("matches the SDK's never-acknowledged close", () => {
|
||||
expect(isNeverAcknowledgedSubscriptionClose(neverAcknowledged())).toBe(
|
||||
true,
|
||||
);
|
||||
});
|
||||
|
||||
// The sibling rejection carries the SAME code, which is exactly why the
|
||||
// predicate has to read the message: a stream that closed for some other
|
||||
// reason before acknowledgement may well succeed on a retry.
|
||||
it("does not match a generic pre-ack close", () => {
|
||||
expect(
|
||||
isNeverAcknowledgedSubscriptionClose(
|
||||
new SdkError(
|
||||
SdkErrorCode.ConnectionClosed,
|
||||
"subscriptions/listen closed before the server acknowledged",
|
||||
),
|
||||
),
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("does not match another SDK error code carrying the same words", () => {
|
||||
expect(
|
||||
isNeverAcknowledgedSubscriptionClose(
|
||||
new SdkError(
|
||||
SdkErrorCode.RequestTimeout,
|
||||
"server closed the subscription gracefully before acknowledging",
|
||||
),
|
||||
),
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("does not match a plain Error or a non-error value", () => {
|
||||
expect(
|
||||
isNeverAcknowledgedSubscriptionClose(
|
||||
new Error(
|
||||
"server closed the subscription gracefully before acknowledging",
|
||||
),
|
||||
),
|
||||
).toBe(false);
|
||||
expect(isNeverAcknowledgedSubscriptionClose(undefined)).toBe(false);
|
||||
expect(isNeverAcknowledgedSubscriptionClose("closed")).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("subscriptionFailureMessage (#2097)", () => {
|
||||
it("reports the explanation for the never-acknowledged close", () => {
|
||||
expect(
|
||||
subscriptionFailureMessage(
|
||||
new SdkError(
|
||||
SdkErrorCode.ConnectionClosed,
|
||||
"subscriptions/listen: server closed the subscription gracefully before acknowledging",
|
||||
),
|
||||
),
|
||||
).toBe(NEVER_ACKNOWLEDGED_SUBSCRIPTION_MESSAGE);
|
||||
});
|
||||
|
||||
// Every other failure keeps its own message — that text is the diagnostic,
|
||||
// and replacing it would trade one silence for another.
|
||||
it("passes any other failure through unchanged", () => {
|
||||
expect(subscriptionFailureMessage(new Error("socket hang up"))).toBe(
|
||||
"socket hang up",
|
||||
);
|
||||
expect(subscriptionFailureMessage("not an Error")).toBe("not an Error");
|
||||
});
|
||||
});
|
||||
|
||||
describe("NEVER_ACKNOWLEDGED_SUBSCRIPTION_MESSAGE", () => {
|
||||
// The whole defect was silence, so the copy has to name the wire event, the
|
||||
// rule it broke, and the fact that nothing further will be attempted.
|
||||
it("names the notification, the result semantics, and the no-retry decision", () => {
|
||||
expect(NEVER_ACKNOWLEDGED_SUBSCRIPTION_MESSAGE).toContain(
|
||||
"notifications/subscriptions/acknowledged",
|
||||
);
|
||||
expect(NEVER_ACKNOWLEDGED_SUBSCRIPTION_MESSAGE).toContain(
|
||||
"graceful closure",
|
||||
);
|
||||
expect(NEVER_ACKNOWLEDGED_SUBSCRIPTION_MESSAGE).toContain("Not retrying");
|
||||
});
|
||||
});
|
||||
Loading…
Reference in a new issue