From ea5e7c5fff2bd797d8bf0cd5333fcccf59219ed3 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 10:09:54 +0200 Subject: [PATCH 01/37] feat(core): Events extension (SEP-3415) wire schemas and core subpath --- examples/client-quickstart/tsconfig.json | 3 + examples/server-quickstart/tsconfig.json | 3 + examples/shared/tsconfig.json | 3 + examples/tsconfig.json | 1 + packages/client/tsconfig.json | 1 + .../test/packageTopologyPins.test.ts | 8 +- packages/core-internal/tsconfig.json | 3 +- packages/core/package.json | 13 + packages/core/src/ext/events/capability.ts | 22 + packages/core/src/ext/events/constants.ts | 138 +++++++ packages/core/src/ext/events/index.ts | 82 ++++ packages/core/src/ext/events/schemas.ts | 391 ++++++++++++++++++ packages/core/src/ext/events/types.ts | 284 +++++++++++++ packages/core/test/ext/events/schemas.test.ts | 56 +++ packages/core/tsdown.config.ts | 2 +- packages/middleware/express/tsconfig.json | 3 + packages/middleware/fastify/tsconfig.json | 3 + packages/middleware/hono/tsconfig.json | 3 + packages/middleware/node/tsconfig.json | 3 + packages/server-legacy/tsconfig.json | 1 + packages/server/tsconfig.json | 1 + test/conformance/tsconfig.json | 3 + test/e2e/tsconfig.json | 3 + test/helpers/tsconfig.json | 3 + test/integration/tsconfig.json | 3 + 25 files changed, 1030 insertions(+), 6 deletions(-) create mode 100644 packages/core/src/ext/events/capability.ts create mode 100644 packages/core/src/ext/events/constants.ts create mode 100644 packages/core/src/ext/events/index.ts create mode 100644 packages/core/src/ext/events/schemas.ts create mode 100644 packages/core/src/ext/events/types.ts create mode 100644 packages/core/test/ext/events/schemas.test.ts diff --git a/examples/client-quickstart/tsconfig.json b/examples/client-quickstart/tsconfig.json index e227905f23..c60bc6e553 100644 --- a/examples/client-quickstart/tsconfig.json +++ b/examples/client-quickstart/tsconfig.json @@ -19,6 +19,9 @@ "@modelcontextprotocol/core/ext/skills": [ "./node_modules/@modelcontextprotocol/client/node_modules/@modelcontextprotocol/core/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core/ext/events": [ + "./node_modules/@modelcontextprotocol/client/node_modules/@modelcontextprotocol/core/src/ext/events/index.ts" + ], "@modelcontextprotocol/core-internal/public": [ "./node_modules/@modelcontextprotocol/client/node_modules/@modelcontextprotocol/core-internal/src/exports/public/index.ts" ], diff --git a/examples/server-quickstart/tsconfig.json b/examples/server-quickstart/tsconfig.json index ad7cceae55..8e266c8ae9 100644 --- a/examples/server-quickstart/tsconfig.json +++ b/examples/server-quickstart/tsconfig.json @@ -19,6 +19,9 @@ "@modelcontextprotocol/core/ext/skills": [ "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core/ext/events": [ + "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/ext/events/index.ts" + ], "@modelcontextprotocol/core-internal/public": [ "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core-internal/src/exports/public/index.ts" ], diff --git a/examples/shared/tsconfig.json b/examples/shared/tsconfig.json index 75cedeee6c..c73340848f 100644 --- a/examples/shared/tsconfig.json +++ b/examples/shared/tsconfig.json @@ -19,6 +19,9 @@ "@modelcontextprotocol/core/ext/skills": [ "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core/ext/events": [ + "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/ext/events/index.ts" + ], "@modelcontextprotocol/core-internal/public": [ "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core-internal/src/exports/public/index.ts" ], diff --git a/examples/tsconfig.json b/examples/tsconfig.json index 28288e5c6d..adac127abe 100644 --- a/examples/tsconfig.json +++ b/examples/tsconfig.json @@ -28,6 +28,7 @@ ], "@modelcontextprotocol/core/internal": ["./node_modules/@modelcontextprotocol/core/src/internal.ts"], "@modelcontextprotocol/core/ext/skills": ["./node_modules/@modelcontextprotocol/core/src/ext/skills/index.ts"], + "@modelcontextprotocol/core/ext/events": ["./node_modules/@modelcontextprotocol/core/src/ext/events/index.ts"], "@modelcontextprotocol/core-internal/public": [ "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core-internal/src/exports/public/index.ts" ], diff --git a/packages/client/tsconfig.json b/packages/client/tsconfig.json index 4fb474f8fb..d718285cd1 100644 --- a/packages/client/tsconfig.json +++ b/packages/client/tsconfig.json @@ -8,6 +8,7 @@ "@modelcontextprotocol/core-internal": ["./node_modules/@modelcontextprotocol/core-internal/src/index.ts"], "@modelcontextprotocol/core/internal": ["./node_modules/@modelcontextprotocol/core/src/internal.ts"], "@modelcontextprotocol/core/ext/skills": ["./node_modules/@modelcontextprotocol/core/src/ext/skills/index.ts"], + "@modelcontextprotocol/core/ext/events": ["./node_modules/@modelcontextprotocol/core/src/ext/events/index.ts"], "@modelcontextprotocol/core-internal/public": [ "./node_modules/@modelcontextprotocol/core-internal/src/exports/public/index.ts" ], diff --git a/packages/core-internal/test/packageTopologyPins.test.ts b/packages/core-internal/test/packageTopologyPins.test.ts index 5bc882e8e3..6c53cfba63 100644 --- a/packages/core-internal/test/packageTopologyPins.test.ts +++ b/packages/core-internal/test/packageTopologyPins.test.ts @@ -60,10 +60,10 @@ const PUBLIC_PACKAGES: Record; + +/** + * A webhook delivery failure category. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type DeliveryErrorCategory = z.infer; + +/** + * An event type as `events/list` describes it. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type EventDescriptor = z.infer; + +/** + * One delivered event. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type EventOccurrence = z.infer; + +/** + * The error object Events carries in notifications and the webhook `terminated` body. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type EventsErrorObject = z.infer; + +/** + * Params of `events/list`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type ListEventsRequestParams = z.infer; + +/** + * Result of `events/list`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type ListEventsResult = z.infer; + +/** + * Params of `events/poll`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type PollEventsRequestParams = z.infer; + +/** + * Result of `events/poll`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type PollEventsResult = z.infer; + +/** + * Params of `events/stream`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type StreamEventsRequestParams = z.infer; + +/** + * Result of `events/stream`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type StreamEventsResult = z.infer; + +/** + * The `delivery` object of `events/subscribe`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type WebhookDelivery = z.infer; + +/** + * The `delivery` object of `events/unsubscribe`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type WebhookTarget = z.infer; + +/** + * Params of `events/subscribe`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type SubscribeEventsRequestParams = z.infer; + +/** + * Result of `events/subscribe`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type SubscribeEventsResult = z.infer; + +/** + * Webhook delivery health, as an `events/subscribe` refresh may report it. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type DeliveryStatus = z.infer; + +/** + * Params of `events/unsubscribe`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type UnsubscribeEventsRequestParams = z.infer; + +/** + * Result of `events/unsubscribe`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type UnsubscribeEventsResult = z.infer; + +/** + * Params of `notifications/events/active`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type EventsActiveNotificationParams = z.infer; + +/** + * Params of `notifications/events/event`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type EventNotificationParams = z.infer; + +/** + * Params of `notifications/events/heartbeat`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type EventsHeartbeatNotificationParams = z.infer; + +/** + * Params of `notifications/events/error`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type EventsErrorNotificationParams = z.infer; + +/** + * Params of `notifications/events/terminated`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type EventsTerminatedNotificationParams = z.infer; + +/** + * Webhook `gap` control body. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type WebhookGapBody = z.infer; + +/** + * Webhook `terminated` control body. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type WebhookTerminatedBody = z.infer; + +/** + * Webhook `verification` control body. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type WebhookVerificationBody = z.infer; + +/** + * Any webhook control body, discriminated on `type`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type WebhookControlBody = z.infer; + +/** + * The value at `capabilities.extensions["io.modelcontextprotocol/events"]`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type EventsCapability = z.infer; diff --git a/packages/core/test/ext/events/schemas.test.ts b/packages/core/test/ext/events/schemas.test.ts new file mode 100644 index 0000000000..6a8b8532f4 --- /dev/null +++ b/packages/core/test/ext/events/schemas.test.ts @@ -0,0 +1,56 @@ +import { describe, expect, it } from 'vitest'; + +import { + EventDescriptorSchema, + eventsCapabilityOf, + PollEventsRequestParamsSchema, + PollEventsResultSchema, + SubscribeEventsRequestParamsSchema, + WebhookControlBodySchema +} from '../../../src/ext/events/index'; + +describe('Events wire schemas', () => { + it('parses the SEP poll result and keeps unknown keys', () => { + const parsed = PollEventsResultSchema.parse({ + resultType: 'complete', + events: [{ eventId: 'evt_001', name: 'email.received', timestamp: '2026-02-19T15:30:00Z', data: { messageId: 'msg_xyz' } }], + cursor: 'historyId_99842', + truncated: false, + hasMore: false, + nextPollMs: 30000, + future: 1 + }); + expect(parsed.events[0]?.eventId).toBe('evt_001'); + expect((parsed as Record).future).toBe(1); + }); + + it('treats an absent cursor like null', () => { + expect(PollEventsRequestParamsSchema.parse({ name: 'x' }).cursor).toBeUndefined(); + expect(PollEventsRequestParamsSchema.parse({ name: 'x', cursor: null }).cursor).toBeNull(); + }); + + it('rejects a descriptor with no delivery mode', () => { + expect(EventDescriptorSchema.safeParse({ name: 'x', delivery: [], inputSchema: {}, payloadSchema: {} }).success).toBe(false); + }); + + it('accepts ttlMs: null and only webhook delivery on subscribe', () => { + const base = { name: 'x', delivery: { mode: 'webhook', url: 'https://h.example/hook', secret: 'whsec_AAAA' } }; + expect(SubscribeEventsRequestParamsSchema.parse({ ...base, ttlMs: null }).ttlMs).toBeNull(); + expect(SubscribeEventsRequestParamsSchema.safeParse({ ...base, delivery: { ...base.delivery, mode: 'poll' } }).success).toBe(false); + }); + + it('discriminates control bodies and refuses an occurrence as one', () => { + expect(WebhookControlBodySchema.parse({ type: 'gap', cursor: 'c2' }).type).toBe('gap'); + expect(WebhookControlBodySchema.parse({ type: 'verification', challenge: 'n' }).type).toBe('verification'); + expect(WebhookControlBodySchema.safeParse({ eventId: 'e', name: 'x', timestamp: 't', data: {} }).success).toBe(false); + }); + + it('reads the capability', () => { + expect(eventsCapabilityOf({ extensions: { 'io.modelcontextprotocol/events': {} } })).toEqual({}); + expect(eventsCapabilityOf({ extensions: { 'io.modelcontextprotocol/events': { listChanged: true } } })).toEqual({ + listChanged: true + }); + expect(eventsCapabilityOf({ extensions: { 'io.modelcontextprotocol/events': { listChanged: 'yes' } } })).toBeUndefined(); + expect(eventsCapabilityOf({})).toBeUndefined(); + }); +}); diff --git a/packages/core/tsdown.config.ts b/packages/core/tsdown.config.ts index dec96674ef..dbcebdd7ce 100644 --- a/packages/core/tsdown.config.ts +++ b/packages/core/tsdown.config.ts @@ -8,7 +8,7 @@ import { defineConfig } from 'tsdown'; // makes a node-only dependency leaking in fail the build here instead of silently shipping. export default defineConfig({ failOnWarn: 'ci-only', - entry: ['src/index.ts', 'src/internal.ts', 'src/ext/skills/index.ts'], + entry: ['src/index.ts', 'src/internal.ts', 'src/ext/skills/index.ts', 'src/ext/events/index.ts'], format: ['esm', 'cjs'], fixedExtension: true, outDir: 'dist', diff --git a/packages/middleware/express/tsconfig.json b/packages/middleware/express/tsconfig.json index aa149835df..bf911499b6 100644 --- a/packages/middleware/express/tsconfig.json +++ b/packages/middleware/express/tsconfig.json @@ -16,6 +16,9 @@ "@modelcontextprotocol/core/ext/skills": [ "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core/ext/events": [ + "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/ext/events/index.ts" + ], "@modelcontextprotocol/core-internal/public": [ "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core-internal/src/exports/public/index.ts" ], diff --git a/packages/middleware/fastify/tsconfig.json b/packages/middleware/fastify/tsconfig.json index de34390e99..3a8546b9e1 100644 --- a/packages/middleware/fastify/tsconfig.json +++ b/packages/middleware/fastify/tsconfig.json @@ -15,6 +15,9 @@ ], "@modelcontextprotocol/core/ext/skills": [ "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/ext/skills/index.ts" + ], + "@modelcontextprotocol/core/ext/events": [ + "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/ext/events/index.ts" ] } } diff --git a/packages/middleware/hono/tsconfig.json b/packages/middleware/hono/tsconfig.json index aa149835df..bf911499b6 100644 --- a/packages/middleware/hono/tsconfig.json +++ b/packages/middleware/hono/tsconfig.json @@ -16,6 +16,9 @@ "@modelcontextprotocol/core/ext/skills": [ "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core/ext/events": [ + "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/ext/events/index.ts" + ], "@modelcontextprotocol/core-internal/public": [ "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core-internal/src/exports/public/index.ts" ], diff --git a/packages/middleware/node/tsconfig.json b/packages/middleware/node/tsconfig.json index 6c35df5027..34baa88d22 100644 --- a/packages/middleware/node/tsconfig.json +++ b/packages/middleware/node/tsconfig.json @@ -14,6 +14,9 @@ "@modelcontextprotocol/core/ext/skills": [ "./node_modules/@modelcontextprotocol/core-internal/node_modules/@modelcontextprotocol/core/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core/ext/events": [ + "./node_modules/@modelcontextprotocol/core-internal/node_modules/@modelcontextprotocol/core/src/ext/events/index.ts" + ], "@modelcontextprotocol/core-internal/public": [ "./node_modules/@modelcontextprotocol/core-internal/src/exports/public/index.ts" ], diff --git a/packages/server-legacy/tsconfig.json b/packages/server-legacy/tsconfig.json index 832ad0ea9e..513a244283 100644 --- a/packages/server-legacy/tsconfig.json +++ b/packages/server-legacy/tsconfig.json @@ -8,6 +8,7 @@ "@modelcontextprotocol/core-internal": ["./node_modules/@modelcontextprotocol/core-internal/src/index.ts"], "@modelcontextprotocol/core/internal": ["./node_modules/@modelcontextprotocol/core/src/internal.ts"], "@modelcontextprotocol/core/ext/skills": ["./node_modules/@modelcontextprotocol/core/src/ext/skills/index.ts"], + "@modelcontextprotocol/core/ext/events": ["./node_modules/@modelcontextprotocol/core/src/ext/events/index.ts"], "@modelcontextprotocol/core-internal/public": ["./node_modules/@modelcontextprotocol/core-internal/src/exports/public/index.ts"] } } diff --git a/packages/server/tsconfig.json b/packages/server/tsconfig.json index 54f3389a5f..ea7a9a6212 100644 --- a/packages/server/tsconfig.json +++ b/packages/server/tsconfig.json @@ -8,6 +8,7 @@ "@modelcontextprotocol/core-internal": ["./node_modules/@modelcontextprotocol/core-internal/src/index.ts"], "@modelcontextprotocol/core/internal": ["./node_modules/@modelcontextprotocol/core/src/internal.ts"], "@modelcontextprotocol/core/ext/skills": ["./node_modules/@modelcontextprotocol/core/src/ext/skills/index.ts"], + "@modelcontextprotocol/core/ext/events": ["./node_modules/@modelcontextprotocol/core/src/ext/events/index.ts"], "@modelcontextprotocol/core-internal/public": [ "./node_modules/@modelcontextprotocol/core-internal/src/exports/public/index.ts" ], diff --git a/test/conformance/tsconfig.json b/test/conformance/tsconfig.json index 01cfe3ef37..933dc19474 100644 --- a/test/conformance/tsconfig.json +++ b/test/conformance/tsconfig.json @@ -12,6 +12,9 @@ "@modelcontextprotocol/core/ext/skills": [ "./node_modules/@modelcontextprotocol/core-internal/node_modules/@modelcontextprotocol/core/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core/ext/events": [ + "./node_modules/@modelcontextprotocol/core-internal/node_modules/@modelcontextprotocol/core/src/ext/events/index.ts" + ], "@modelcontextprotocol/core-internal/public": [ "./node_modules/@modelcontextprotocol/core-internal/src/exports/public/index.ts" ], diff --git a/test/e2e/tsconfig.json b/test/e2e/tsconfig.json index 13094c9b35..c67f7ffdd4 100644 --- a/test/e2e/tsconfig.json +++ b/test/e2e/tsconfig.json @@ -12,6 +12,9 @@ "@modelcontextprotocol/core/ext/skills": [ "./node_modules/@modelcontextprotocol/core-internal/node_modules/@modelcontextprotocol/core/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core/ext/events": [ + "./node_modules/@modelcontextprotocol/core-internal/node_modules/@modelcontextprotocol/core/src/ext/events/index.ts" + ], "@modelcontextprotocol/core-internal/public": [ "./node_modules/@modelcontextprotocol/core-internal/src/exports/public/index.ts" ], diff --git a/test/helpers/tsconfig.json b/test/helpers/tsconfig.json index e6108eaf1f..17d2a84368 100644 --- a/test/helpers/tsconfig.json +++ b/test/helpers/tsconfig.json @@ -12,6 +12,9 @@ "@modelcontextprotocol/core/ext/skills": [ "./node_modules/@modelcontextprotocol/core-internal/node_modules/@modelcontextprotocol/core/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core/ext/events": [ + "./node_modules/@modelcontextprotocol/core-internal/node_modules/@modelcontextprotocol/core/src/ext/events/index.ts" + ], "@modelcontextprotocol/core-internal/public": [ "./node_modules/@modelcontextprotocol/core-internal/src/exports/public/index.ts" ], diff --git a/test/integration/tsconfig.json b/test/integration/tsconfig.json index a15fa93ad5..fe97ace79b 100644 --- a/test/integration/tsconfig.json +++ b/test/integration/tsconfig.json @@ -12,6 +12,9 @@ "@modelcontextprotocol/core/ext/skills": [ "./node_modules/@modelcontextprotocol/core-internal/node_modules/@modelcontextprotocol/core/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core/ext/events": [ + "./node_modules/@modelcontextprotocol/core-internal/node_modules/@modelcontextprotocol/core/src/ext/events/index.ts" + ], "@modelcontextprotocol/core-internal/public": [ "./node_modules/@modelcontextprotocol/core-internal/src/exports/public/index.ts" ], From 235ecfa0de000064821ac2bd644b2ff6e79f8c7a Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 10:28:42 +0200 Subject: [PATCH 02/37] feat(core-internal): Events shared internals: EventsError, canonical JSON, Standard Webhooks, Mcp-Name rows --- examples/client-quickstart/tsconfig.json | 3 + examples/server-quickstart/tsconfig.json | 3 + examples/shared/tsconfig.json | 3 + examples/tsconfig.json | 3 + packages/client/tsconfig.json | 3 + packages/core-internal/package.json | 4 + .../src/ext/events/canonicalJson.ts | 16 +++ .../core-internal/src/ext/events/codes.ts | 18 ++++ .../core-internal/src/ext/events/errors.ts | 47 +++++++++ .../core-internal/src/ext/events/index.ts | 18 ++++ .../src/ext/events/webhookSignature.ts | 88 +++++++++++++++++ .../src/shared/inboundClassification.ts | 14 ++- .../test/ext/events/canonicalJson.test.ts | 33 +++++++ .../test/ext/events/errors.test.ts | 57 +++++++++++ .../test/ext/events/webhookSignature.test.ts | 98 +++++++++++++++++++ .../shared/standardHeaderValidation.test.ts | 8 +- .../test/types/errorSurfacePins.test.ts | 2 + packages/middleware/express/tsconfig.json | 3 + packages/middleware/hono/tsconfig.json | 3 + packages/middleware/node/tsconfig.json | 3 + packages/server/tsconfig.json | 3 + test/conformance/tsconfig.json | 3 + test/e2e/tsconfig.json | 3 + test/helpers/tsconfig.json | 3 + test/integration/tsconfig.json | 3 + 25 files changed, 436 insertions(+), 6 deletions(-) create mode 100644 packages/core-internal/src/ext/events/canonicalJson.ts create mode 100644 packages/core-internal/src/ext/events/codes.ts create mode 100644 packages/core-internal/src/ext/events/errors.ts create mode 100644 packages/core-internal/src/ext/events/index.ts create mode 100644 packages/core-internal/src/ext/events/webhookSignature.ts create mode 100644 packages/core-internal/test/ext/events/canonicalJson.test.ts create mode 100644 packages/core-internal/test/ext/events/errors.test.ts create mode 100644 packages/core-internal/test/ext/events/webhookSignature.test.ts diff --git a/examples/client-quickstart/tsconfig.json b/examples/client-quickstart/tsconfig.json index c60bc6e553..44c6809493 100644 --- a/examples/client-quickstart/tsconfig.json +++ b/examples/client-quickstart/tsconfig.json @@ -27,6 +27,9 @@ ], "@modelcontextprotocol/core-internal/ext/skills": [ "./node_modules/@modelcontextprotocol/client/node_modules/@modelcontextprotocol/core-internal/src/ext/skills/index.ts" + ], + "@modelcontextprotocol/core-internal/ext/events": [ + "./node_modules/@modelcontextprotocol/client/node_modules/@modelcontextprotocol/core-internal/src/ext/events/index.ts" ] } }, diff --git a/examples/server-quickstart/tsconfig.json b/examples/server-quickstart/tsconfig.json index 8e266c8ae9..73a0c577b3 100644 --- a/examples/server-quickstart/tsconfig.json +++ b/examples/server-quickstart/tsconfig.json @@ -27,6 +27,9 @@ ], "@modelcontextprotocol/core-internal/ext/skills": [ "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core-internal/src/ext/skills/index.ts" + ], + "@modelcontextprotocol/core-internal/ext/events": [ + "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core-internal/src/ext/events/index.ts" ] } }, diff --git a/examples/shared/tsconfig.json b/examples/shared/tsconfig.json index c73340848f..5b671ede94 100644 --- a/examples/shared/tsconfig.json +++ b/examples/shared/tsconfig.json @@ -28,6 +28,9 @@ "@modelcontextprotocol/core-internal/ext/skills": [ "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core-internal/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core-internal/ext/events": [ + "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core-internal/src/ext/events/index.ts" + ], "@modelcontextprotocol/eslint-config": ["./node_modules/@modelcontextprotocol/eslint-config/tsconfig.json"], "@modelcontextprotocol/vitest-config": ["./node_modules/@modelcontextprotocol/vitest-config/tsconfig.json"], "@modelcontextprotocol/test-helpers": ["./node_modules/@modelcontextprotocol/test-helpers/src/index.ts"], diff --git a/examples/tsconfig.json b/examples/tsconfig.json index adac127abe..36e52b0a1e 100644 --- a/examples/tsconfig.json +++ b/examples/tsconfig.json @@ -35,6 +35,9 @@ "@modelcontextprotocol/core-internal/ext/skills": [ "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core-internal/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core-internal/ext/events": [ + "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core-internal/src/ext/events/index.ts" + ], "@mcp-examples/shared": ["./node_modules/@mcp-examples/shared/src/index.ts"] } } diff --git a/packages/client/tsconfig.json b/packages/client/tsconfig.json index d718285cd1..84fc56fc35 100644 --- a/packages/client/tsconfig.json +++ b/packages/client/tsconfig.json @@ -15,6 +15,9 @@ "@modelcontextprotocol/core-internal/ext/skills": [ "./node_modules/@modelcontextprotocol/core-internal/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core-internal/ext/events": [ + "./node_modules/@modelcontextprotocol/core-internal/src/ext/events/index.ts" + ], "@modelcontextprotocol/core-internal/validators/ajv": [ "./node_modules/@modelcontextprotocol/core-internal/src/validators/ajvProvider.ts" ], diff --git a/packages/core-internal/package.json b/packages/core-internal/package.json index 5e7612b729..a9a2c642fa 100644 --- a/packages/core-internal/package.json +++ b/packages/core-internal/package.json @@ -37,6 +37,10 @@ "types": "./src/ext/skills/index.ts", "import": "./src/ext/skills/index.ts" }, + "./ext/events": { + "types": "./src/ext/events/index.ts", + "import": "./src/ext/events/index.ts" + }, "./validators/ajv": { "types": "./src/validators/ajvProvider.ts", "import": "./src/validators/ajvProvider.ts" diff --git a/packages/core-internal/src/ext/events/canonicalJson.ts b/packages/core-internal/src/ext/events/canonicalJson.ts new file mode 100644 index 0000000000..b353ab37df --- /dev/null +++ b/packages/core-internal/src/ext/events/canonicalJson.ts @@ -0,0 +1,16 @@ +function serialize(json: unknown): string { + if (Array.isArray(json)) return `[${json.map(item => serialize(item)).join(',')}]`; + if (typeof json !== 'object' || json === null) return JSON.stringify(json); + const members = Object.keys(json) + .toSorted() + .map(name => `${JSON.stringify(name)}:${serialize((json as Record)[name])}`); + return `{${members.join(',')}}`; +} + +/** `JSON.stringify(value)` with object keys sorted by UTF-16 code unit at every depth; `TypeError` when there is no JSON text. */ +export function canonicalJson(value: unknown): string { + const text = JSON.stringify(value) as string | undefined; + if (text === undefined) throw new TypeError('canonicalJson: the value has no JSON text'); + // Parsing the standard text first applies every JSON.stringify rule (toJSON, dropped members, NaN to null). + return serialize(JSON.parse(text)); +} diff --git a/packages/core-internal/src/ext/events/codes.ts b/packages/core-internal/src/ext/events/codes.ts new file mode 100644 index 0000000000..820b0b606d --- /dev/null +++ b/packages/core-internal/src/ext/events/codes.ts @@ -0,0 +1,18 @@ +/** + * What went wrong in an Events (SEP-3415) request or subscription: the SEP's error vocabulary. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type EventsErrorKind = 'invalidParams' | 'notFound' | 'forbidden' | 'resourceExhausted' | 'unsupported' | 'callbackEndpointError'; + +/** The provisional JSON-RPC code of each {@linkcode EventsErrorKind} (SEP-3415 open question 5 may renumber them). */ +export const EVENTS_ERROR_CODES: Readonly> = { + invalidParams: -32_602, + notFound: -32_023, + forbidden: -32_024, + resourceExhausted: -32_025, + unsupported: -32_026, + callbackEndpointError: -32_027 +}; diff --git a/packages/core-internal/src/ext/events/errors.ts b/packages/core-internal/src/ext/events/errors.ts new file mode 100644 index 0000000000..105a0af0fe --- /dev/null +++ b/packages/core-internal/src/ext/events/errors.ts @@ -0,0 +1,47 @@ +import { ProtocolError } from '../../types/errors'; +import type { EventsErrorKind } from './codes'; +import { EVENTS_ERROR_CODES } from './codes'; + +function kindOf(code: number): EventsErrorKind | undefined { + return (Object.keys(EVENTS_ERROR_CODES) as EventsErrorKind[]).find(kind => EVENTS_ERROR_CODES[kind] === code); +} + +/** + * An Events (SEP-3415) error. It crosses the wire as an error response, and inside + * `notifications/events/error`, `notifications/events/terminated` and the webhook `terminated` body. + * + * Branch on {@linkcode EventsError.kind}: it is the API. The inherited `code` is provisional + * (SEP-3415 open question 5 may renumber these errors or fold them into `-32602` with typed `data`). + * `instanceof` checks are brand-matched and work across separately bundled copies of the SDK. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export class EventsError extends ProtocolError { + static { + Object.defineProperty(this, 'mcpBrand', { value: 'mcp.EventsError' }); + } + + constructor(kind: EventsErrorKind, message: string, data?: Record) { + super(EVENTS_ERROR_CODES[kind], message, data); + } + + /** What went wrong. */ + get kind(): EventsErrorKind { + return kindOf(this.code)!; + } + + /** + * The `EventsError` for a `ProtocolError` received from an `events/*` request, by its code; + * `undefined` for a code outside the Events error table. Data that is not an object is dropped. + */ + static fromProtocolError(error: ProtocolError): EventsError | undefined { + const kind = kindOf(error.code); + if (kind === undefined) return undefined; + const { data } = error; + const objectData = + typeof data === 'object' && data !== null && !Array.isArray(data) ? (data as Record) : undefined; + return new EventsError(kind, error.message, objectData); + } +} diff --git a/packages/core-internal/src/ext/events/index.ts b/packages/core-internal/src/ext/events/index.ts new file mode 100644 index 0000000000..dc109e4c8a --- /dev/null +++ b/packages/core-internal/src/ext/events/index.ts @@ -0,0 +1,18 @@ +// @modelcontextprotocol/core-internal/ext/events +// +// Internal layer of the MCP Events extension (SEP-3415), shared by the client +// and server packages: the error table and `EventsError`, canonical JSON, and +// Standard Webhooks signing. Not on core-internal's root barrel: import it from +// this subpath, so it stays out of the client and server root module graphs. +export { canonicalJson } from './canonicalJson'; +export type { EventsErrorKind } from './codes'; +export { EVENTS_ERROR_CODES } from './codes'; +export { EventsError } from './errors'; +export { + generateWebhookId, + generateWebhookSecret, + parseWebhookSecret, + signWebhook, + timingSafeEqualString, + verifyWebhookSignature +} from './webhookSignature'; diff --git a/packages/core-internal/src/ext/events/webhookSignature.ts b/packages/core-internal/src/ext/events/webhookSignature.ts new file mode 100644 index 0000000000..2f0cebdb2a --- /dev/null +++ b/packages/core-internal/src/ext/events/webhookSignature.ts @@ -0,0 +1,88 @@ +import type { WebhookControlBody } from '@modelcontextprotocol/core/ext/events'; + +const SECRET_PREFIX = 'whsec_'; +const PADDED_BASE64 = /^(?:[\d+/A-Za-z]{4})*(?:[\d+/A-Za-z]{2}==|[\d+/A-Za-z]{3}=)?$/; +const encoder = new TextEncoder(); + +function toBase64(bytes: Uint8Array): string { + let binary = ''; + for (const byte of bytes) binary += String.fromCodePoint(byte); + return btoa(binary); +} + +function randomBytes(length: number): Uint8Array { + return globalThis.crypto.getRandomValues(new Uint8Array(length)); +} + +async function hmacSignatures( + secrets: readonly Uint8Array[], + webhookId: string, + timestampSeconds: number, + body: string +): Promise { + const content = encoder.encode(`${webhookId}.${timestampSeconds}.${body}`); + return Promise.all( + secrets.map(async secret => { + // Copied so WebCrypto never sees a view over a SharedArrayBuffer. + const key = await globalThis.crypto.subtle.importKey('raw', new Uint8Array(secret), { name: 'HMAC', hash: 'SHA-256' }, false, [ + 'sign' + ]); + return toBase64(new Uint8Array(await globalThis.crypto.subtle.sign('HMAC', key, content))); + }) + ); +} + +/** The bytes of a Standard Webhooks secret: `whsec_` and padded base64 of 24 to 64 bytes; otherwise `undefined`. */ +export function parseWebhookSecret(secret: string): Uint8Array | undefined { + if (!secret.startsWith(SECRET_PREFIX)) return undefined; + const encoded = secret.slice(SECRET_PREFIX.length); + if (!PADDED_BASE64.test(encoded)) return undefined; + const bytes = Uint8Array.from(atob(encoded), char => char.codePointAt(0)!); + return bytes.length >= 24 && bytes.length <= 64 ? bytes : undefined; +} + +/** A new Standard Webhooks secret: `whsec_` and base64 of 32 random bytes. */ +export function generateWebhookSecret(): string { + return `${SECRET_PREFIX}${toBase64(randomBytes(32))}`; +} + +/** A new `webhook-id`: `msg_` and base64url of 16 random bytes, or `msg__…` for a control body. */ +export function generateWebhookId(controlType?: WebhookControlBody['type']): string { + const random = toBase64(randomBytes(16)).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, ''); + return controlType === undefined ? `msg_${random}` : `msg_${controlType}_${random}`; +} + +/** The `webhook-signature` header: `v1,` per secret, space-separated. */ +export async function signWebhook( + secrets: readonly Uint8Array[], + webhookId: string, + timestampSeconds: number, + body: string +): Promise { + const signatures = await hmacSignatures(secrets, webhookId, timestampSeconds, body); + return signatures.map(signature => `v1,${signature}`).join(' '); +} + +/** Whether any `v1,` entry of a `webhook-signature` header matches the raw body under any of the secrets. */ +export async function verifyWebhookSignature( + secrets: readonly Uint8Array[], + webhookId: string, + timestampSeconds: number, + rawBody: string, + signatureHeader: string +): Promise { + const expected = await hmacSignatures(secrets, webhookId, timestampSeconds, rawBody); + const received = signatureHeader + .split(' ') + .filter(entry => entry.startsWith('v1,')) + .map(entry => entry.slice('v1,'.length)); + return received.some(signature => expected.some(candidate => timingSafeEqualString(signature, candidate))); +} + +/** Whether two strings are equal, in time that does not depend on where they differ. */ +export function timingSafeEqualString(a: string, b: string): boolean { + if (a.length !== b.length) return false; + let difference = 0; + for (let index = 0; index < a.length; index++) difference |= a.codePointAt(index)! ^ b.codePointAt(index)!; + return difference === 0; +} diff --git a/packages/core-internal/src/shared/inboundClassification.ts b/packages/core-internal/src/shared/inboundClassification.ts index 4f20e8cb41..24d1a264e9 100644 --- a/packages/core-internal/src/shared/inboundClassification.ts +++ b/packages/core-internal/src/shared/inboundClassification.ts @@ -478,9 +478,11 @@ export type McpNameSourceField = 'name' | 'uri' | 'taskId'; * Streamable HTTP binding ("the client MUST set the `Mcp-Name` header to the * value of `params.taskId`" for `tasks/get` / `tasks/update` / * `tasks/cancel`, so intermediaries can route every request for a task to the - * instance holding its state). Shared by the client transport (header - * emission) and the server ladder (validation) so both sides derive from one - * table. + * instance holding its state); the `events/*` rows come from SEP-3415's + * Streamable HTTP routing headers (`params.name`, the event name, for + * `events/poll` / `events/stream` / `events/subscribe` / `events/unsubscribe`). + * Shared by the client transport (header emission) and the server ladder + * (validation) so both sides derive from one table. */ export const MCP_NAME_HEADER_SOURCE: Readonly> = { 'tools/call': 'name', @@ -488,7 +490,11 @@ export const MCP_NAME_HEADER_SOURCE: Readonly 'resources/read': 'uri', 'tasks/get': 'taskId', 'tasks/update': 'taskId', - 'tasks/cancel': 'taskId' + 'tasks/cancel': 'taskId', + 'events/poll': 'name', + 'events/stream': 'name', + 'events/subscribe': 'name', + 'events/unsubscribe': 'name' }; /** diff --git a/packages/core-internal/test/ext/events/canonicalJson.test.ts b/packages/core-internal/test/ext/events/canonicalJson.test.ts new file mode 100644 index 0000000000..ef5069a1fd --- /dev/null +++ b/packages/core-internal/test/ext/events/canonicalJson.test.ts @@ -0,0 +1,33 @@ +import { describe, expect, it } from 'vitest'; + +import { canonicalJson } from '../../../src/ext/events/canonicalJson'; + +describe('canonicalJson', () => { + it('sorts object keys at every depth, keeps array order and drops undefined members', () => { + expect(canonicalJson({ b: 1, a: { d: 2, c: [3, { f: 1, e: 2 }] }, z: undefined })).toBe( + '{"a":{"c":[3,{"e":2,"f":1}],"d":2},"b":1}' + ); + }); + + it('does not depend on key insertion order', () => { + expect(canonicalJson({ x: 1, y: 2 })).toBe(canonicalJson({ y: 2, x: 1 })); + }); + + it('sorts integer-like keys as strings', () => { + expect(canonicalJson({ 9: 'b', 10: 'a', a: 'c' })).toBe('{"10":"a","9":"b","a":"c"}'); + }); + + it('otherwise follows JSON.stringify', () => { + const values = [undefined, () => 1, Number.NaN, 'é\n"', new Date(0), null, true, -0.5]; + expect(canonicalJson(values)).toBe(JSON.stringify(values)); + expect(canonicalJson({ when: new Date(0), nested: { toJSON: () => ({ b: 1, a: 2 }) } })).toBe( + '{"nested":{"a":2,"b":1},"when":"1970-01-01T00:00:00.000Z"}' + ); + expect(canonicalJson('x')).toBe('"x"'); + expect(() => canonicalJson({ big: 1n })).toThrow(TypeError); + }); + + it('throws for a value with no JSON text', () => { + expect(() => canonicalJson(undefined)).toThrow(TypeError); + }); +}); diff --git a/packages/core-internal/test/ext/events/errors.test.ts b/packages/core-internal/test/ext/events/errors.test.ts new file mode 100644 index 0000000000..8e330fb80c --- /dev/null +++ b/packages/core-internal/test/ext/events/errors.test.ts @@ -0,0 +1,57 @@ +import { describe, expect, it, vi } from 'vitest'; + +import type { EventsErrorKind } from '../../../src/ext/events/codes'; +import { EVENTS_ERROR_CODES } from '../../../src/ext/events/codes'; +import { EventsError } from '../../../src/ext/events/errors'; +import { ProtocolError } from '../../../src/types/errors'; + +describe('EventsError', () => { + it('fills in the code for its kind and keeps message and data', () => { + const err = new EventsError('forbidden', 'Forbidden', { reason: 'Access revoked' }); + expect([err.code, err.kind, err.data]).toEqual([-32024, 'forbidden', { reason: 'Access revoked' }]); + expect(err.message).toBe('Forbidden'); + expect(err).toBeInstanceOf(ProtocolError); + expect(EventsError.isInstance(err)).toBe(true); + expect(EventsError.isInstance(new ProtocolError(-32024, 'Forbidden'))).toBe(false); + }); + + it('uses the provisional code table for every kind', () => { + expect(EVENTS_ERROR_CODES).toEqual({ + invalidParams: -32602, + notFound: -32023, + forbidden: -32024, + resourceExhausted: -32025, + unsupported: -32026, + callbackEndpointError: -32027 + }); + for (const [kind, code] of Object.entries(EVENTS_ERROR_CODES)) { + const err = new EventsError(kind as EventsErrorKind, kind); + expect([err.code, err.kind]).toEqual([code, kind]); + } + }); + + it('converts a ProtocolError by code, and leaves codes outside the table alone', () => { + const notFound = EventsError.fromProtocolError(new ProtocolError(-32023, 'NotFound', { kind: 'event' })); + expect([notFound?.kind, notFound?.message, notFound?.data]).toEqual(['notFound', 'NotFound', { kind: 'event' }]); + expect(EventsError.fromProtocolError(new ProtocolError(-32602, 'bad'))?.kind).toBe('invalidParams'); + expect(EventsError.fromProtocolError(new ProtocolError(-32603, 'boom'))).toBeUndefined(); + }); + + it('keeps only object data when converting', () => { + expect(EventsError.fromProtocolError(new ProtocolError(-32025, 'ResourceExhausted', 'subscriptions'))?.data).toBeUndefined(); + expect(EventsError.fromProtocolError(new ProtocolError(-32025, 'ResourceExhausted', ['subscriptions']))?.data).toBeUndefined(); + }); + + it('matches across separately loaded module copies', async () => { + vi.resetModules(); + const foreign = await import('../../../src/ext/events/errors'); + const foreignTypes = await import('../../../src/types/errors'); + // Guard the premise: a cached module would make the checks pass through prototype identity. + expect(foreign.EventsError).not.toBe(EventsError); + const err = new foreign.EventsError('unsupported', 'Unsupported', { feature: 'deliveryMode', value: 'push' }); + expect(err instanceof EventsError).toBe(true); + expect(err instanceof ProtocolError).toBe(true); + expect(EventsError.isInstance(err)).toBe(true); + expect(new foreignTypes.ProtocolError(-32026, 'Unsupported') instanceof EventsError).toBe(false); + }); +}); diff --git a/packages/core-internal/test/ext/events/webhookSignature.test.ts b/packages/core-internal/test/ext/events/webhookSignature.test.ts new file mode 100644 index 0000000000..5268d02441 --- /dev/null +++ b/packages/core-internal/test/ext/events/webhookSignature.test.ts @@ -0,0 +1,98 @@ +import { describe, expect, it } from 'vitest'; + +import { + generateWebhookId, + generateWebhookSecret, + parseWebhookSecret, + signWebhook, + timingSafeEqualString, + verifyWebhookSignature +} from '../../../src/ext/events/webhookSignature'; + +const bytesOf = (length: number): string => btoa('x'.repeat(length)); + +describe('Standard Webhooks signing', () => { + it('reproduces the Standard Webhooks reference vector', async () => { + const secret = parseWebhookSecret('whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw')!; + expect(secret.length).toBe(24); + expect(await signWebhook([secret], 'msg_p5jXN8AQM9LWM0D4loKWxJek', 1614265330, '{"test": 2432232314}')).toBe( + 'v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=' + ); + expect( + await verifyWebhookSignature( + [secret], + 'msg_p5jXN8AQM9LWM0D4loKWxJek', + 1614265330, + '{"test": 2432232314}', + 'v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=' + ) + ).toBe(true); + }); + + it('signs once per secret during rotation; either verifies, a re-serialized body does not', async () => { + const secret = parseWebhookSecret('whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw')!; + const other = parseWebhookSecret(generateWebhookSecret())!; + const header = await signWebhook([secret, other], 'msg_x', 1, '{"a": 1}'); + expect(header.split(' ')).toHaveLength(2); + expect(await verifyWebhookSignature([secret], 'msg_x', 1, '{"a": 1}', header)).toBe(true); + expect(await verifyWebhookSignature([other], 'msg_x', 1, '{"a": 1}', header)).toBe(true); + expect(await verifyWebhookSignature([other], 'msg_x', 1, '{"a":1}', header)).toBe(false); + }); + + it('binds the id and timestamp, and ignores entries that are not v1', async () => { + const secret = parseWebhookSecret(generateWebhookSecret())!; + const header = await signWebhook([secret], 'msg_x', 1, '{}'); + const signature = header.slice('v1,'.length); + expect(await verifyWebhookSignature([secret], 'msg_y', 1, '{}', header)).toBe(false); + expect(await verifyWebhookSignature([secret], 'msg_x', 2, '{}', header)).toBe(false); + expect(await verifyWebhookSignature([secret], 'msg_x', 1, '{}', `v1a,${signature} junk ${header}`)).toBe(true); + expect(await verifyWebhookSignature([secret], 'msg_x', 1, '{}', `v2,${signature}`)).toBe(false); + expect(await verifyWebhookSignature([secret], 'msg_x', 1, '{}', signature)).toBe(false); + expect(await verifyWebhookSignature([], 'msg_x', 1, '{}', header)).toBe(false); + }); +}); + +describe('parseWebhookSecret', () => { + it('accepts whsec_ and padded base64 of 24 to 64 bytes', () => { + expect(parseWebhookSecret(`whsec_${bytesOf(24)}`)?.length).toBe(24); + expect(parseWebhookSecret(`whsec_${bytesOf(25)}`)?.length).toBe(25); + expect(parseWebhookSecret(`whsec_${bytesOf(64)}`)?.length).toBe(64); + }); + + it('rejects anything else', () => { + expect(parseWebhookSecret(`whsec_${bytesOf(23)}`)).toBeUndefined(); + expect(parseWebhookSecret(`whsec_${bytesOf(65)}`)).toBeUndefined(); + expect(parseWebhookSecret(bytesOf(32))).toBeUndefined(); + expect(parseWebhookSecret('whsec_***')).toBeUndefined(); + expect(parseWebhookSecret(`whsec_${bytesOf(25).replace(/=+$/, '')}`)).toBeUndefined(); + expect(parseWebhookSecret(`whsec_ ${bytesOf(32)}`)).toBeUndefined(); + expect(parseWebhookSecret(`whsec_${'-_'.repeat(16)}`)).toBeUndefined(); + }); +}); + +describe('generators', () => { + it('generates a whsec_ secret of 32 random bytes', () => { + const secret = generateWebhookSecret(); + expect(secret).toMatch(/^whsec_[A-Za-z0-9+/]{43}=$/); + expect(parseWebhookSecret(secret)?.length).toBe(32); + expect(generateWebhookSecret()).not.toBe(secret); + }); + + it('generates header-safe webhook ids, typed for control bodies', () => { + expect(generateWebhookId()).toMatch(/^msg_[A-Za-z0-9_-]{22}$/); + expect(generateWebhookId('gap')).toMatch(/^msg_gap_[A-Za-z0-9_-]{22}$/); + expect(generateWebhookId('terminated')).toMatch(/^msg_terminated_[A-Za-z0-9_-]{22}$/); + expect(generateWebhookId('verification')).toMatch(/^msg_verification_[A-Za-z0-9_-]{22}$/); + expect(generateWebhookId()).not.toBe(generateWebhookId()); + }); +}); + +describe('timingSafeEqualString', () => { + it('is true only for identical strings', () => { + expect(timingSafeEqualString('', '')).toBe(true); + expect(timingSafeEqualString('v1,abc', 'v1,abc')).toBe(true); + expect(timingSafeEqualString('v1,abc', 'v1,abd')).toBe(false); + expect(timingSafeEqualString('v1,abc', 'v1,ab')).toBe(false); + expect(timingSafeEqualString('😀', '😁')).toBe(false); + }); +}); diff --git a/packages/core-internal/test/shared/standardHeaderValidation.test.ts b/packages/core-internal/test/shared/standardHeaderValidation.test.ts index 3cb4e7f893..b4bd3e11e4 100644 --- a/packages/core-internal/test/shared/standardHeaderValidation.test.ts +++ b/packages/core-internal/test/shared/standardHeaderValidation.test.ts @@ -276,14 +276,18 @@ describe('SEP-2243 standard-header validation (Mcp-Name presence and cross-check expect(validateStandardRequestHeaders(request, route)).toBeUndefined(); }); - test('the Mcp-Name source map covers exactly the spec table (SEP-2243 core + SEP-2663 tasks)', () => { + test('the Mcp-Name source map covers exactly the spec table (SEP-2243 core + SEP-2663 tasks + SEP-3415 events)', () => { expect(MCP_NAME_HEADER_SOURCE).toEqual({ 'tools/call': 'name', 'prompts/get': 'name', 'resources/read': 'uri', 'tasks/get': 'taskId', 'tasks/update': 'taskId', - 'tasks/cancel': 'taskId' + 'tasks/cancel': 'taskId', + 'events/poll': 'name', + 'events/stream': 'name', + 'events/subscribe': 'name', + 'events/unsubscribe': 'name' }); }); diff --git a/packages/core-internal/test/types/errorSurfacePins.test.ts b/packages/core-internal/test/types/errorSurfacePins.test.ts index e2f52c2410..c73221ce8d 100644 --- a/packages/core-internal/test/types/errorSurfacePins.test.ts +++ b/packages/core-internal/test/types/errorSurfacePins.test.ts @@ -95,6 +95,7 @@ describe('cross-bundle brand strings', () => { test('pins every core error brand (renaming one severs cross-version matching — must be deliberate)', async () => { const { OAuthError } = await import('../../src/auth/errors'); const { SdkError, SdkHttpError } = await import('../../src/errors/sdkErrors'); + const { EventsError } = await import('../../src/ext/events/errors'); const { MissingRequiredClientCapabilityError, ProtocolError: PE, @@ -111,6 +112,7 @@ describe('cross-bundle brand strings', () => { expect(brand(SdkError)).toBe('mcp.SdkError'); expect(brand(SdkHttpError)).toBe('mcp.SdkHttpError'); expect(brand(OAuthError)).toBe('mcp.OAuthError'); + expect(brand(EventsError)).toBe('mcp.EventsError'); }); }); diff --git a/packages/middleware/express/tsconfig.json b/packages/middleware/express/tsconfig.json index bf911499b6..d4e49880d6 100644 --- a/packages/middleware/express/tsconfig.json +++ b/packages/middleware/express/tsconfig.json @@ -24,6 +24,9 @@ ], "@modelcontextprotocol/core-internal/ext/skills": [ "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core-internal/src/ext/skills/index.ts" + ], + "@modelcontextprotocol/core-internal/ext/events": [ + "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core-internal/src/ext/events/index.ts" ] } } diff --git a/packages/middleware/hono/tsconfig.json b/packages/middleware/hono/tsconfig.json index bf911499b6..d4e49880d6 100644 --- a/packages/middleware/hono/tsconfig.json +++ b/packages/middleware/hono/tsconfig.json @@ -24,6 +24,9 @@ ], "@modelcontextprotocol/core-internal/ext/skills": [ "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core-internal/src/ext/skills/index.ts" + ], + "@modelcontextprotocol/core-internal/ext/events": [ + "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core-internal/src/ext/events/index.ts" ] } } diff --git a/packages/middleware/node/tsconfig.json b/packages/middleware/node/tsconfig.json index 34baa88d22..9a4001de59 100644 --- a/packages/middleware/node/tsconfig.json +++ b/packages/middleware/node/tsconfig.json @@ -23,6 +23,9 @@ "@modelcontextprotocol/core-internal/ext/skills": [ "./node_modules/@modelcontextprotocol/core-internal/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core-internal/ext/events": [ + "./node_modules/@modelcontextprotocol/core-internal/src/ext/events/index.ts" + ], "@modelcontextprotocol/test-helpers": ["./node_modules/@modelcontextprotocol/test-helpers/src/index.ts"] } } diff --git a/packages/server/tsconfig.json b/packages/server/tsconfig.json index ea7a9a6212..8292e2e3b8 100644 --- a/packages/server/tsconfig.json +++ b/packages/server/tsconfig.json @@ -15,6 +15,9 @@ "@modelcontextprotocol/core-internal/ext/skills": [ "./node_modules/@modelcontextprotocol/core-internal/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core-internal/ext/events": [ + "./node_modules/@modelcontextprotocol/core-internal/src/ext/events/index.ts" + ], "@modelcontextprotocol/core-internal/validators/ajv": [ "./node_modules/@modelcontextprotocol/core-internal/src/validators/ajvProvider.ts" ], diff --git a/test/conformance/tsconfig.json b/test/conformance/tsconfig.json index 933dc19474..279537aae2 100644 --- a/test/conformance/tsconfig.json +++ b/test/conformance/tsconfig.json @@ -21,6 +21,9 @@ "@modelcontextprotocol/core-internal/ext/skills": [ "./node_modules/@modelcontextprotocol/core-internal/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core-internal/ext/events": [ + "./node_modules/@modelcontextprotocol/core-internal/src/ext/events/index.ts" + ], "@modelcontextprotocol/client": ["./node_modules/@modelcontextprotocol/client/src/index.ts"], "@modelcontextprotocol/client/_shims": ["./node_modules/@modelcontextprotocol/client/src/shimsNode.ts"], "@modelcontextprotocol/server": ["./node_modules/@modelcontextprotocol/server/src/index.ts"], diff --git a/test/e2e/tsconfig.json b/test/e2e/tsconfig.json index c67f7ffdd4..c014cafe91 100644 --- a/test/e2e/tsconfig.json +++ b/test/e2e/tsconfig.json @@ -21,6 +21,9 @@ "@modelcontextprotocol/core-internal/ext/skills": [ "./node_modules/@modelcontextprotocol/core-internal/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core-internal/ext/events": [ + "./node_modules/@modelcontextprotocol/core-internal/src/ext/events/index.ts" + ], "@modelcontextprotocol/core-internal/validators/cfWorker": [ "./node_modules/@modelcontextprotocol/core-internal/src/validators/cfWorkerProvider.ts" ], diff --git a/test/helpers/tsconfig.json b/test/helpers/tsconfig.json index 17d2a84368..2f9324ab9c 100644 --- a/test/helpers/tsconfig.json +++ b/test/helpers/tsconfig.json @@ -21,6 +21,9 @@ "@modelcontextprotocol/core-internal/ext/skills": [ "./node_modules/@modelcontextprotocol/core-internal/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core-internal/ext/events": [ + "./node_modules/@modelcontextprotocol/core-internal/src/ext/events/index.ts" + ], "@modelcontextprotocol/vitest-config": ["./node_modules/@modelcontextprotocol/vitest-config/tsconfig.json"] } } diff --git a/test/integration/tsconfig.json b/test/integration/tsconfig.json index fe97ace79b..2f985e654a 100644 --- a/test/integration/tsconfig.json +++ b/test/integration/tsconfig.json @@ -21,6 +21,9 @@ "@modelcontextprotocol/core-internal/ext/skills": [ "./node_modules/@modelcontextprotocol/core-internal/src/ext/skills/index.ts" ], + "@modelcontextprotocol/core-internal/ext/events": [ + "./node_modules/@modelcontextprotocol/core-internal/src/ext/events/index.ts" + ], "@modelcontextprotocol/core-internal/validators/ajv": [ "./node_modules/@modelcontextprotocol/core-internal/src/validators/ajvProvider.ts" ], From b25890a56a06764ebc41cd3ffc2bea7d81691f27 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 10:56:11 +0200 Subject: [PATCH 03/37] feat(server): EventsExtension registration, attach, events/list and era gate --- examples/tsconfig.json | 1 + .../test/packageTopologyPins.test.ts | 14 +- packages/server/package.json | 13 + packages/server/src/ext/events/context.ts | 27 ++ packages/server/src/ext/events/eraGate.ts | 9 + packages/server/src/ext/events/extension.ts | 261 ++++++++++++++++ packages/server/src/ext/events/index.ts | 70 +++++ packages/server/src/ext/events/registry.ts | 111 +++++++ packages/server/src/ext/events/testHook.ts | 23 ++ packages/server/src/ext/events/types.ts | 287 ++++++++++++++++++ .../server/src/server/modernOnlyExtensions.ts | 22 ++ packages/server/src/server/server.ts | 3 +- packages/server/test/ext/events/harness.ts | 133 ++++++++ .../test/ext/events/registration.test.ts | 273 +++++++++++++++++ .../server/test/server/barrelClean.test.ts | 33 +- .../test/server/errorBrandConformance.test.ts | 8 +- packages/server/tsdown.config.ts | 12 +- test/conformance/tsconfig.json | 1 + test/e2e/tsconfig.json | 1 + test/integration/tsconfig.json | 1 + 20 files changed, 1288 insertions(+), 15 deletions(-) create mode 100644 packages/server/src/ext/events/context.ts create mode 100644 packages/server/src/ext/events/eraGate.ts create mode 100644 packages/server/src/ext/events/extension.ts create mode 100644 packages/server/src/ext/events/index.ts create mode 100644 packages/server/src/ext/events/registry.ts create mode 100644 packages/server/src/ext/events/testHook.ts create mode 100644 packages/server/src/ext/events/types.ts create mode 100644 packages/server/src/server/modernOnlyExtensions.ts create mode 100644 packages/server/test/ext/events/harness.ts create mode 100644 packages/server/test/ext/events/registration.test.ts diff --git a/examples/tsconfig.json b/examples/tsconfig.json index 36e52b0a1e..ac0f4c3588 100644 --- a/examples/tsconfig.json +++ b/examples/tsconfig.json @@ -18,6 +18,7 @@ "@modelcontextprotocol/client/ext/skills": ["./node_modules/@modelcontextprotocol/client/src/ext/skills/index.ts"], "@modelcontextprotocol/server/ext/skills": ["./node_modules/@modelcontextprotocol/server/src/ext/skills/index.ts"], "@modelcontextprotocol/server/ext/skills/node": ["./node_modules/@modelcontextprotocol/server/src/ext/skills/node.ts"], + "@modelcontextprotocol/server/ext/events": ["./node_modules/@modelcontextprotocol/server/src/ext/events/index.ts"], "@modelcontextprotocol/core": ["./node_modules/@modelcontextprotocol/core/src/index.ts"], "@modelcontextprotocol/express": ["./node_modules/@modelcontextprotocol/express/src/index.ts"], "@modelcontextprotocol/fastify": ["./node_modules/@modelcontextprotocol/fastify/src/index.ts"], diff --git a/packages/core-internal/test/packageTopologyPins.test.ts b/packages/core-internal/test/packageTopologyPins.test.ts index 6c53cfba63..3a9398f878 100644 --- a/packages/core-internal/test/packageTopologyPins.test.ts +++ b/packages/core-internal/test/packageTopologyPins.test.ts @@ -44,8 +44,18 @@ const PUBLIC_PACKAGES: Record; +} + +type DefaultSchema = StandardSchemaWithJSON>; + +const EVENTS_METHODS = [EVENTS_LIST_METHOD, EVENTS_POLL_METHOD, EVENTS_STREAM_METHOD, EVENTS_SUBSCRIBE_METHOD, EVENTS_UNSUBSCRIBE_METHOD]; + +const NUMERIC_OPTIONS = [ + 'webhookTtlMs', + 'pollSubscriptionTtlMs', + 'heartbeatMs', + 'checkIntervalMs', + 'defaultNextPollMs', + 'maxSubscriptions' +] as const; + +// Servers with an events extension attached: one per server, as SEP-3371 rejects a duplicate extension identifier. +const eventsServers = new WeakSet(); + +const ONE_PER_SERVER = 'another events extension is already attached to this server; attach one per server'; + +function assertPositive(name: string, value: unknown): void { + if (value !== undefined && !(typeof value === 'number' && Number.isFinite(value) && value > 0)) { + throw new TypeError(`${name} must be a positive finite number (got ${String(value)})`); + } +} + +function assertOrigin(origin: string): void { + let parsed: string | undefined; + try { + parsed = new URL(origin).origin; + } catch { + parsed = undefined; + } + if (parsed !== origin) { + throw new TypeError(`trustedOrigins entries must be exact origins such as "http://127.0.0.1:9000" (got ${JSON.stringify(origin)})`); + } +} + +function assertWebhookOptions(options: EventsOptions): void { + if ((options.webhookTtlMs === undefined) !== (options.webhookSender === undefined)) { + throw new TypeError('set webhookTtlMs and webhookSender together, or neither'); + } + if (options.webhookTtlMs !== undefined && options.getPrincipal === undefined) { + throw new TypeError('webhook delivery needs getPrincipal: set it with webhookTtlMs and webhookSender'); + } +} + +// The two kinds, checked at runtime for plain JavaScript as the types check them for TypeScript. +function assertKind(name: string, definition: AnyEventDefinition): void { + const hasCheck = definition.check !== undefined; + const filters = definition.match !== undefined || definition.transform !== undefined; + if (definition.emitOnly === true ? hasCheck : !hasCheck || filters) { + throw new TypeError(`event '${name}': pass check(), or emitOnly: true and call emit() on the returned handle`); + } +} + +// Stderr, so a report never corrupts a stdio transport. +function defaultOnerror(error: Error): void { + // eslint-disable-next-line no-console -- the documented default sink for events errors + console.warn(`[mcp-sdk] events: ${error.message}`); +} + +/** + * The MCP Events extension (SEP-3415). Register event types with + * {@linkcode EventsExtension.registerEvent}, then call + * {@linkcode EventsExtension.attach} on each server before connecting it; one + * instance serves any number of servers. Events is served only on protocol + * revision `2026-07-28` and later. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export class EventsExtension { + readonly id = EVENTS_EXTENSION_ID; + readonly #registry = new EventRegistry(); + readonly #sources: SubscriptionSource[] = []; + readonly #attached = new WeakSet(); + readonly #trustedOrigins: Set; + readonly #webhookEnabled: boolean; + readonly #onerror: (error: Error) => void; + // Clears process-memory state on a simulated restart; each delivery mode adds its own. + readonly #restarts: Array<() => void> = []; + #generation = 1; + + /** Throws `TypeError` for an invalid option, including webhook options set only in part. */ + constructor(options: EventsOptions = {}) { + assertWebhookOptions(options); + for (const name of NUMERIC_OPTIONS) assertPositive(name, options[name]); + assertPositive('emitBuffer.maxAgeMs', options.emitBuffer?.maxAgeMs); + assertPositive('emitBuffer.maxEvents', options.emitBuffer?.maxEvents); + for (const origin of options.trustedOrigins ?? []) assertOrigin(origin); + this.#trustedOrigins = new Set(options.trustedOrigins); + this.#webhookEnabled = options.webhookTtlMs !== undefined; + this.#onerror = options.onerror ?? defaultOnerror; + installTestHook(this, { + generation: () => this.#generation, + restart: () => { + this.#generation += 1; + for (const clear of this.#restarts) clear(); + }, + state: () => ({ trustedOrigins: [...this.#trustedOrigins] }), + addTrustedOrigin: origin => { + assertOrigin(origin); + this.#trustedOrigins.add(origin); + }, + addSource: source => { + this.#sources.push(source); + } + }); + } + + /** + * Serves these event types on `mcp`: registers the `events/*` methods, + * then declares the capability. Must run before connecting. Calling it + * again for the same server does nothing. One events extension per + * server: attaching another one throws and leaves the server as it was, + * as does attaching to a server that already handles one of the + * `events/*` methods. A legacy `initialize` result does not advertise + * Events, and `events/*` requests without a `2026-07-28` envelope are + * answered `-32601`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ + attach(mcp: McpServer): void { + if (this.#attached.has(mcp)) return; + if (mcp.isConnected()) throw new Error('attach events before connecting the server'); + if (eventsServers.has(mcp)) throw new Error(ONE_PER_SERVER); + const server = mcp.server; + // Check before changing anything; declare the capability last, so a server never advertises events it does not serve. + for (const method of EVENTS_METHODS) server.assertCanSetRequestHandler(method); + server.setRequestHandler(EVENTS_LIST_METHOD, { params: ListEventsRequestParamsSchema }, (_params, ctx) => this.#list(ctx)); + server.registerCapabilities({ extensions: { [EVENTS_EXTENSION_ID]: {} } }); + markModernOnlyExtension(server, EVENTS_EXTENSION_ID); + this.#attached.add(mcp); + eventsServers.add(mcp); + } + + /** + * Registers an event type: pass `check` for the default kind, or + * `emitOnly: true` and call `emit()` on the returned handle. A mistake in + * the definition throws `TypeError`, as does registering a name again with + * the same schemas. Registering it with a different `inputSchema` or + * `payloadSchema` replaces the event type and ends its live subscriptions + * with an `unsupported` error (`reason: 'schema_changed'`). + */ + registerEvent( + name: string, + definition: EmitOnlyEventDefinition + ): EmitOnlyEventHandle>; + registerEvent( + name: string, + definition: CheckEventDefinition + ): EventHandle; + registerEvent(name: string, definition: AnyEventDefinition): EventHandle { + assertKind(name, definition); + if (deliveryModes(definition.delivery, this.#webhookEnabled).length === 0) { + throw new TypeError(`event '${name}': delivery turns off every mode this server offers`); + } + const previous = this.#registry.get(name); + let current = this.#registry.register(name, definition); + this.#checkHeaders(current); + if (previous !== undefined) { + const feature = changedSchema(previous, current)!; + this.#terminateLater( + name, + new EventsError('unsupported', `Event type ${feature} changed`, { feature, reason: 'schema_changed' }) + ); + } + return { + name, + update: changes => { + if (this.#registry.get(name) !== current) { + throw new Error(`event '${name}': this handle's registration was removed or replaced`); + } + current = this.#registry.update(current, changes); + if (changes.inputSchema !== undefined) this.#checkHeaders(current); + }, + remove: () => { + if (this.#registry.get(name) !== current) return; + this.#registry.remove(name); + this.#terminateLater(name, new EventsError('notFound', 'Event type removed', { kind: 'event' })); + }, + terminate: (error, options) => this.#terminate(name, error, options?.subscriptionId) + }; + } + + #list(ctx: ServerContext): ListEventsResult { + assertModernRequest(ctx); + return { events: this.#registry.list().map(entry => this.#describe(entry)) }; + } + + #describe(entry: RegisteredEvent): EventDescriptor { + const { description, _meta } = entry.definition; + return { + name: entry.name, + ...(description === undefined ? {} : { description }), + delivery: entry.modes(this.#webhookEnabled), + inputSchema: entry.inputJson, + payloadSchema: entry.payloadJson, + ...(_meta === undefined ? {} : { _meta }) + }; + } + + #checkHeaders(entry: RegisteredEvent): void { + const scan = scanXMcpHeaderDeclarations(entry.inputJson); + if (scan.valid) return; + this.#report( + new Error( + `event '${entry.name}' carries an invalid x-mcp-header declaration and will be excluded by ` + + `conforming Streamable HTTP clients: ${scan.reason}` + ) + ); + } + + async #terminate(name: string, error: EventsError, subscriptionId: string | undefined): Promise { + await Promise.all(this.#sources.map(source => source.terminate(name, error, subscriptionId))); + } + + // For callers that cannot wait: a failed termination goes to onerror. + #terminateLater(name: string, error: EventsError): void { + this.#terminate(name, error, undefined).catch((error_: unknown) => + this.#report(error_ instanceof Error ? error_ : new Error(String(error_))) + ); + } + + #report(error: Error): void { + try { + this.#onerror(error); + } catch { + // A throwing onerror must not break the caller it reports for. + } + } +} diff --git a/packages/server/src/ext/events/index.ts b/packages/server/src/ext/events/index.ts new file mode 100644 index 0000000000..9c162cf799 --- /dev/null +++ b/packages/server/src/ext/events/index.ts @@ -0,0 +1,70 @@ +// @modelcontextprotocol/server/ext/events +// +// Server side of the MCP Events extension (SEP-3415). + +export { EventsExtension } from './extension'; +export type { + CheckContext, + CheckEventDefinition, + EmitOnlyEventDefinition, + EmitOnlyEventHandle, + EventContext, + EventDefinition, + EventHandle, + EventInput, + EventResult, + EventsOptions, + WebhookSender, + WebhookSendOutcome, + WebhookSendRequest, + WebhookSubscriptionRecord, + WebhookSubscriptionStore +} from './types'; +export type { + DeliveryErrorCategory, + DeliveryMode, + DeliveryStatus, + EventDescriptor, + EventNotificationParams, + EventOccurrence, + EventsActiveNotificationParams, + EventsCapability, + EventsErrorNotificationParams, + EventsErrorObject, + EventsHeartbeatNotificationParams, + EventsTerminatedNotificationParams, + ListEventsRequestParams, + ListEventsResult, + PollEventsRequestParams, + PollEventsResult, + StreamEventsRequestParams, + StreamEventsResult, + SubscribeEventsRequestParams, + SubscribeEventsResult, + UnsubscribeEventsRequestParams, + UnsubscribeEventsResult, + WebhookControlBody, + WebhookDelivery, + WebhookGapBody, + WebhookTarget, + WebhookTerminatedBody, + WebhookVerificationBody +} from '@modelcontextprotocol/core/ext/events'; +export { + DELIVERY_ERROR_CATEGORIES, + DELIVERY_MODES, + EVENTS_ACTIVE_NOTIFICATION, + EVENTS_ERROR_NOTIFICATION, + EVENTS_EVENT_NOTIFICATION, + EVENTS_EXTENSION_ID, + EVENTS_HEARTBEAT_NOTIFICATION, + EVENTS_LIST_METHOD, + EVENTS_POLL_METHOD, + EVENTS_STREAM_METHOD, + EVENTS_SUBSCRIBE_METHOD, + EVENTS_TERMINATED_NOTIFICATION, + EVENTS_UNSUBSCRIBE_METHOD, + WEBHOOK_SUBSCRIPTION_ID_HEADER +} from '@modelcontextprotocol/core/ext/events'; +export type { EventsErrorKind } from '@modelcontextprotocol/core-internal/ext/events'; +export { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; diff --git a/packages/server/src/ext/events/registry.ts b/packages/server/src/ext/events/registry.ts new file mode 100644 index 0000000000..a5bdeb70e4 --- /dev/null +++ b/packages/server/src/ext/events/registry.ts @@ -0,0 +1,111 @@ +import type { DeliveryMode } from '@modelcontextprotocol/core/ext/events'; +import type { StandardSchemaWithJSON } from '@modelcontextprotocol/core-internal'; +import { standardSchemaToJsonSchema, validateStandardSchema } from '@modelcontextprotocol/core-internal'; +import { canonicalJson, EventsError } from '@modelcontextprotocol/core-internal/ext/events'; + +import type { EventDefinition, EventHandle } from './types'; + +export type AnyEventDefinition = EventDefinition; + +export type EventChanges = Parameters[0]; + +export interface RegisteredEvent { + readonly name: string; + readonly kind: 'check' | 'emitOnly'; + readonly definition: AnyEventDefinition; + readonly inputJson: Record; + readonly payloadJson: Record; + modes(webhookEnabled: boolean): DeliveryMode[]; + parseArguments(args: unknown): Promise>; + parsePayload(data: unknown): Promise<{ ok: true; data: Record } | { ok: false; error: string }>; +} + +// Poll and push unless turned off; webhook only when the server sends webhooks and it is not turned off. +export function deliveryModes(delivery: AnyEventDefinition['delivery'], webhookEnabled: boolean): DeliveryMode[] { + const modes: DeliveryMode[] = []; + if (delivery?.poll !== false) modes.push('poll'); + if (delivery?.push !== false) modes.push('push'); + if (webhookEnabled && delivery?.webhook !== false) modes.push('webhook'); + return modes; +} + +// The schema that differs between two registrations of one name, by their generated JSON Schemas. +export function changedSchema(previous: RegisteredEvent, next: RegisteredEvent): 'inputSchema' | 'payloadSchema' | undefined { + if (canonicalJson(previous.inputJson) !== canonicalJson(next.inputJson)) return 'inputSchema'; + if (canonicalJson(previous.payloadJson) !== canonicalJson(next.payloadJson)) return 'payloadSchema'; + return undefined; +} + +function isObject(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value); +} + +function createEntry(name: string, definition: AnyEventDefinition): RegisteredEvent { + const { inputSchema, payloadSchema } = definition; + const entry: RegisteredEvent = { + name, + kind: definition.emitOnly === true ? 'emitOnly' : 'check', + definition, + inputJson: inputSchema === undefined ? { type: 'object' } : standardSchemaToJsonSchema(inputSchema, 'input'), + payloadJson: standardSchemaToJsonSchema(payloadSchema, 'output'), + modes: webhookEnabled => deliveryModes(definition.delivery, webhookEnabled), + parseArguments: async args => { + const value = args ?? {}; + if (inputSchema === undefined) { + if (isObject(value)) return value; + throw new EventsError('invalidParams', `Invalid arguments for event ${name}: expected an object`); + } + const parsed = await validateStandardSchema(inputSchema, value); + if (!parsed.success) throw new EventsError('invalidParams', `Invalid arguments for event ${name}: ${parsed.error}`); + return parsed.data as Record; + }, + parsePayload: async data => { + const parsed = await validateStandardSchema(payloadSchema, data); + return parsed.success ? { ok: true, data: parsed.data as Record } : { ok: false, error: parsed.error }; + } + }; + return Object.freeze(entry); +} + +export class EventRegistry { + readonly #entries = new Map(); + + // Adds an event type, or replaces one whose schemas differ; the same schemas again is a TypeError. + register(name: string, definition: AnyEventDefinition): RegisteredEvent { + const entry = createEntry(name, definition); + const previous = this.#entries.get(name); + if (previous !== undefined && changedSchema(previous, entry) === undefined) { + throw new TypeError(`event '${name}' is already registered`); + } + this.#entries.set(name, entry); + return entry; + } + + // Rebuilds a registered event type with the defined fields of `changes` replaced. + update(entry: RegisteredEvent, changes: EventChanges): RegisteredEvent { + const defined = Object.fromEntries(Object.entries(changes).filter(([, value]) => value !== undefined)); + const next = createEntry(entry.name, { ...entry.definition, ...defined }); + this.#entries.set(entry.name, next); + return next; + } + + get(name: string): RegisteredEvent | undefined { + return this.#entries.get(name); + } + + require(name: string): RegisteredEvent { + const entry = this.#entries.get(name); + if (entry === undefined) throw new EventsError('notFound', `Unknown event type: ${name}`, { kind: 'event' }); + return entry; + } + + list(): RegisteredEvent[] { + return [...this.#entries.values()]; + } + + remove(name: string): RegisteredEvent | undefined { + const entry = this.#entries.get(name); + this.#entries.delete(name); + return entry; + } +} diff --git a/packages/server/src/ext/events/testHook.ts b/packages/server/src/ext/events/testHook.ts new file mode 100644 index 0000000000..e568b962ae --- /dev/null +++ b/packages/server/src/ext/events/testHook.ts @@ -0,0 +1,23 @@ +import type { SubscriptionSource } from './extension'; + +// Where an EventsExtension keeps its test hook; `Symbol.for` so separately bundled copies find it. +export const EVENTS_TEST_HOOK = Symbol.for('mcp.events.testHook'); + +export interface EventsTestState { + readonly trustedOrigins: readonly string[]; +} + +// Internal controls for tests and the conformance fixture; never part of the public API or its declarations. +export interface EventsTestHook { + // Bumped by every simulated restart. + generation(): number; + // Drops the extension's process-memory state, as a process restart would. + restart(): void; + state(): EventsTestState; + addTrustedOrigin(origin: string): void; + addSource(source: SubscriptionSource): void; +} + +export function installTestHook(target: object, hook: EventsTestHook): void { + Object.defineProperty(target, EVENTS_TEST_HOOK, { value: hook, enumerable: false }); +} diff --git a/packages/server/src/ext/events/types.ts b/packages/server/src/ext/events/types.ts new file mode 100644 index 0000000000..896d118fae --- /dev/null +++ b/packages/server/src/ext/events/types.ts @@ -0,0 +1,287 @@ +import type { DeliveryMode } from '@modelcontextprotocol/core/ext/events'; +import type { ServerContext, StandardSchemaWithJSON } from '@modelcontextprotocol/core-internal'; +import type { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; + +type InferInput = StandardSchemaWithJSON.InferInput; +type InferOutput = StandardSchemaWithJSON.InferOutput; + +/** + * The `ctx` of every event callback: the subscription it runs for. There is no + * client request behind many calls (a webhook `check` timer, `emit()`, a lease + * expiring), so it carries no request-scoped API. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export interface EventContext { + /** The event type name. */ + readonly name: string; + /** An opaque id the SDK assigns to the subscription; pass it to a targeted `emit` or `terminate`. */ + readonly subscriptionId: string; + /** The subscriber, from `getPrincipal`; `null` without one. */ + readonly principal: string | null; + /** How the subscription's events are delivered. */ + readonly mode: DeliveryMode; + /** Aborts when the request or the subscription ends. */ + readonly signal: AbortSignal; +} + +/** + * The `ctx` of `check`: an {@linkcode EventContext} plus the client's hints. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export interface CheckContext extends EventContext { + /** Return at most this many events, and set `hasMore` when more are waiting. */ + readonly maxEvents?: number; + /** The client wants no events older than this many milliseconds. */ + readonly maxAgeMs?: number; +} + +/** + * One event as an author produces it. The SDK fills `name` and `cursor`, and + * `eventId` and `timestamp` when absent. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export interface EventInput

> { + /** A unique id; the SDK generates one when absent. */ + eventId?: string; + /** ISO 8601 time of the occurrence; the SDK uses the current time when absent. */ + timestamp?: string; + /** The payload, valid against the event type's `payloadSchema`. */ + data: P; + _meta?: Record; +} + +/** + * What `check` returns: the events since the cursor it was given, and the cursor to resume from. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export interface EventResult

> { + events: EventInput

[]; + /** Where the next `check` resumes; `null` when the upstream cannot resume. */ + cursor: string | null; + /** How long a poll client should wait before polling again. */ + nextPollMs?: number; + /** The upstream lost history since the cursor it was given. */ + truncated?: boolean; + /** More events are waiting beyond `ctx.maxEvents`. */ + hasMore?: boolean; +} + +interface EventDefinitionBase { + description?: string; + /** Schema for the subscription `arguments`; absent means any object. */ + inputSchema?: I; + /** Schema for `data` in delivered events. */ + payloadSchema: P; + _meta?: Record; + /** Runs when a subscription starts. Throw an `EventsError` to refuse it. */ + onSubscribe?(ctx: EventContext, args: InferOutput): void | Promise; + /** Runs when a subscription ends, by request, expiry or termination. */ + onUnsubscribe?(ctx: EventContext, args: InferOutput): void | Promise; + /** Turns delivery modes off; every mode the server offers is on otherwise. */ + delivery?: { poll?: false; push?: false; webhook?: false }; +} + +/** + * The default kind of event type: the SDK calls `check` to read what happened + * since a cursor. After a disconnect or a restart, clients resume from their + * cursor for as long as the upstream still accepts it. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export interface CheckEventDefinition + extends EventDefinitionBase { + emitOnly?: false; + /** The events since `cursor`; with `cursor: null`, only the current cursor (no events). */ + check(ctx: CheckContext, args: InferOutput, cursor: string | null): EventResult> | Promise>>; + match?: never; + transform?: never; +} + +/** + * An event type fed by `emit()` on its handle. Poll clients read a bounded + * in-memory buffer; events emitted before a restart are lost, and so is + * anything older than the buffer holds. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export interface EmitOnlyEventDefinition + extends EventDefinitionBase { + emitOnly: true; + check?: never; + /** Whether a broadcast event goes to a subscription with these arguments; absent means every subscription. */ + match?(ctx: EventContext, event: EventInput>, args: InferOutput): boolean; + /** The event as this subscription receives it. */ + transform?(ctx: EventContext, event: EventInput>, args: InferOutput): EventInput>; +} + +/** + * An event type definition: `check` for the default kind, or `emitOnly: true`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type EventDefinition = + | CheckEventDefinition + | EmitOnlyEventDefinition; + +/** + * The handle `registerEvent` returns. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export interface EventHandle { + readonly name: string; + /** + * Changes the listed fields; live subscriptions continue. Only additive + * schema changes belong here: register the name again for a breaking one. + */ + update( + changes: Partial< + Pick< + EventDefinitionBase, + 'description' | 'inputSchema' | 'payloadSchema' | '_meta' + > + > + ): void; + /** Stops offering the event type and ends its subscriptions with a `notFound` error. */ + remove(): void; + /** Ends one subscription (`options.subscriptionId`), or every subscription of the type, with `error`. */ + terminate(error: EventsError, options?: { subscriptionId?: string }): Promise; +} + +/** + * The handle of an emit-only event type. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export interface EmitOnlyEventHandle

extends EventHandle { + /** Publishes one event to every matching subscription, or to the one with `options.subscriptionId`. */ + emit(input: EventInput

, options?: { subscriptionId?: string }): Promise; +} + +/** + * One webhook POST for a {@linkcode WebhookSender} to send. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export interface WebhookSendRequest { + url: string; + headers: Readonly>; + body: string; + /** The URL's origin is in `trustedOrigins`, so the `https` and private-address rules do not apply. */ + trusted: boolean; + signal: AbortSignal; +} + +/** + * The receiver's answer, or why there was none. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type WebhookSendOutcome = { status: number; body: string } | { error: 'connection_refused' | 'timeout' | 'tls_error' }; + +/** + * Sends webhook POSTs. Webhook delivery is on only when one is configured. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type WebhookSender = (request: WebhookSendRequest) => Promise; + +/** + * A stored webhook subscription. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export interface WebhookSubscriptionRecord { + id: string; + principal: string; + name: string; + arguments: Record; + url: string; + secret: string; + previousSecret?: { secret: string; expiresAt: number }; + expiresAt: number; + createdAt: number; +} + +/** + * Where webhook subscriptions live. Records hold webhook secrets: protect the + * storage accordingly. The SDK treats a record with `expiresAt <= now` as + * expired: it deletes it and calls the event type's `onUnsubscribe`. Several + * server replicas may share one store. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export interface WebhookSubscriptionStore { + get(id: string): Promise; + put(record: WebhookSubscriptionRecord): Promise; + /** Resolves `true` when a record was deleted. */ + delete(id: string): Promise; + listByName(name: string): AsyncIterable; +} + +/** + * Options for `new EventsExtension(options)`. Durations are in milliseconds; + * every number must be positive and finite. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export interface EventsOptions { + /** The longest webhook subscription TTL granted. Set it with `webhookSender` (and `getPrincipal`) to turn webhook delivery on. */ + webhookTtlMs?: number; + /** Sends webhook POSTs; set together with `webhookTtlMs`. */ + webhookSender?: WebhookSender; + /** Where webhook subscriptions live; in memory by default. */ + webhookStore?: WebhookSubscriptionStore; + /** Exact origins (`scheme://host:port`) exempt from the `https` and private-address rules for webhook URLs. For development. */ + trustedOrigins?: readonly string[]; + /** Who the request is from. Required for webhook delivery; poll and push use it when set. There is no default. */ + getPrincipal?: (ctx: ServerContext) => string | null | Promise; + /** Bounds of the in-memory buffer that emit-only event types are polled from. */ + emitBuffer?: { maxAgeMs?: number; maxEvents?: number }; + /** How long a poll subscription lives without a poll. */ + pollSubscriptionTtlMs?: number; + /** The push heartbeat interval granted when the client suggests none, and the longest granted. */ + heartbeatMs?: number; + /** How often `check` runs for push and webhook subscriptions. */ + checkIntervalMs?: number; + /** The `nextPollMs` sent when `check` gives none. */ + defaultNextPollMs?: number; + /** The most subscriptions served at once; more are refused with `resourceExhausted`. */ + maxSubscriptions?: number; + /** Receives errors nothing else can report (dropped payloads, hook failures, invalid `x-mcp-header` annotations). Default: `console.warn`. */ + onerror?: (error: Error) => void; +} diff --git a/packages/server/src/server/modernOnlyExtensions.ts b/packages/server/src/server/modernOnlyExtensions.ts new file mode 100644 index 0000000000..7b5bab7abd --- /dev/null +++ b/packages/server/src/server/modernOnlyExtensions.ts @@ -0,0 +1,22 @@ +import type { ServerCapabilities } from '@modelcontextprotocol/core-internal'; + +import type { Server } from './server'; + +// Extension ids each server serves only on protocol 2026-07-28 and later. +const modernOnly = new WeakMap>(); + +// Keeps `id` out of the capabilities `server` advertises in a legacy `initialize` result. +export function markModernOnlyExtension(server: Server, id: string): void { + const ids = modernOnly.get(server) ?? new Set(); + ids.add(id); + modernOnly.set(server, ids); +} + +// `capabilities` without the extensions marked modern-only on `server`, and without `extensions` when none remain. +export function legacyAdvertisedCapabilities(server: Server, capabilities: ServerCapabilities): ServerCapabilities { + const ids = modernOnly.get(server); + if (ids === undefined || capabilities.extensions === undefined) return capabilities; + const { extensions, ...rest } = capabilities; + const kept = Object.fromEntries(Object.entries(extensions).filter(([id]) => !ids.has(id))); + return Object.keys(kept).length === 0 ? rest : { ...rest, extensions: kept }; +} diff --git a/packages/server/src/server/server.ts b/packages/server/src/server/server.ts index aa03cb427a..b412710612 100644 --- a/packages/server/src/server/server.ts +++ b/packages/server/src/server/server.ts @@ -67,6 +67,7 @@ import { import { DefaultJsonSchemaValidator } from '@modelcontextprotocol/server/_shims'; import { coerceEmbeddedInputRequest, LegacyInputRequiredShim, resolveLegacyShimOptions } from './legacyInputRequiredShim'; +import { legacyAdvertisedCapabilities } from './modernOnlyExtensions'; import { defaultInstrumentation } from './openTelemetry'; import { perRequestClassificationOf } from './perRequestTransport'; @@ -949,7 +950,7 @@ export class Server extends Protocol { return { protocolVersion, - capabilities: this.getCapabilities(), + capabilities: legacyAdvertisedCapabilities(this, this.getCapabilities()), serverInfo: this._serverInfo, ...(this._instructions && { instructions: this._instructions }) }; diff --git a/packages/server/test/ext/events/harness.ts b/packages/server/test/ext/events/harness.ts new file mode 100644 index 0000000000..93dcea1de8 --- /dev/null +++ b/packages/server/test/ext/events/harness.ts @@ -0,0 +1,133 @@ +import type { + AuthInfo, + JSONRPCErrorResponse, + JSONRPCMessage, + JSONRPCNotification, + JSONRPCRequest, + JSONRPCResponse +} from '@modelcontextprotocol/core-internal'; +import { + CLIENT_CAPABILITIES_META_KEY, + CLIENT_INFO_META_KEY, + MCP_NAME_HEADER_SOURCE, + PROTOCOL_VERSION_META_KEY +} from '@modelcontextprotocol/core-internal'; + +import type { EventsExtension } from '../../../src/ext/events/index'; +import { createMcpHandler } from '../../../src/server/createMcpHandler'; +import { McpServer } from '../../../src/server/mcp'; + +export const MODERN = '2026-07-28'; +export const LEGACY = '2025-11-25'; + +const ENVELOPE = { + [PROTOCOL_VERSION_META_KEY]: MODERN, + [CLIENT_INFO_META_KEY]: { name: 'events-test-client', version: '1.0.0' }, + [CLIENT_CAPABILITIES_META_KEY]: {} +}; + +/** Per-request options: the era (default `'modern'`), extra headers, and an abort signal. */ +export interface PostInit { + era?: 'modern' | 'legacy'; + headers?: Record; + signal?: AbortSignal; +} + +export interface Served { + /** Posts one JSON-RPC message; modern messages carry the envelope and the standard headers derived from the body. */ + post(message: JSONRPCRequest | JSONRPCNotification, init?: PostInit): Promise; + /** Sends a request and resolves with its response, read from a JSON body or from the SSE stream. */ + rpc(method: string, params?: object, init?: PostInit): Promise; +} + +let nextId = 1; + +function modernHeaders(message: JSONRPCRequest | JSONRPCNotification): Record { + const headers: Record = { 'mcp-protocol-version': MODERN, 'mcp-method': message.method }; + const field = MCP_NAME_HEADER_SOURCE[message.method]; + const name = field === undefined ? undefined : (message.params as Record | undefined)?.[field]; + if (typeof name === 'string') headers['mcp-name'] = name; + return headers; +} + +/** Serves `events` through `createMcpHandler`, attaching it to the fresh `McpServer` built for each request. */ +export function serve(events: EventsExtension, options: { authInfo?: AuthInfo; responseMode?: 'auto' | 'json' } = {}): Served { + const handler = createMcpHandler( + () => { + const mcp = new McpServer({ name: 'events-test', version: '1.0.0' }); + events.attach(mcp); + return mcp; + }, + options.responseMode === undefined ? {} : { responseMode: options.responseMode } + ); + + const post = (message: JSONRPCRequest | JSONRPCNotification, init: PostInit = {}): Promise => { + const modern = (init.era ?? 'modern') === 'modern'; + const params = (message.params ?? {}) as Record; + const body = modern + ? { ...message, params: { ...params, _meta: { ...ENVELOPE, ...(params._meta as object | undefined) } } } + : message; + const request = new Request('http://localhost/mcp', { + method: 'POST', + headers: { + 'content-type': 'application/json', + accept: 'application/json, text/event-stream', + ...(modern ? modernHeaders(message) : {}), + ...init.headers + }, + body: JSON.stringify(body), + ...(init.signal === undefined ? {} : { signal: init.signal }) + }); + return handler.fetch(request, options.authInfo === undefined ? undefined : { authInfo: options.authInfo }); + }; + + const rpc = async (method: string, params: object = {}, init?: PostInit): Promise => { + const id = nextId++; + const response = await post({ jsonrpc: '2.0', id, method, params } as JSONRPCRequest, init); + if (!(response.headers.get('content-type') ?? '').includes('text/event-stream')) return (await response.json()) as JSONRPCResponse; + for await (const message of readFrames(response)) { + if ('id' in message && message.id === id && ('result' in message || 'error' in message)) return message as JSONRPCResponse; + } + throw new Error(`${method}: the stream ended without a response`); + }; + + return { post, rpc }; +} + +/** The JSON-RPC messages of an SSE response, parsed from its `data:` lines as frames arrive. */ +export async function* readFrames(response: Response): AsyncGenerator { + const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader(); + let buffer = ''; + try { + for (;;) { + const { done, value } = await reader.read(); + if (done) return; + buffer += value; + let end: number; + while ((end = buffer.indexOf('\n\n')) !== -1) { + const frame = buffer.slice(0, end); + buffer = buffer.slice(end + 2); + const data = frame + .split('\n') + .filter(line => line.startsWith('data:')) + .map(line => line.slice(5).trimStart()) + .join('\n'); + if (data !== '') yield JSON.parse(data) as JSONRPCMessage; + } + } + } finally { + await reader.cancel().catch(() => {}); + } +} + +/** The result of a response that must succeed. */ +export function resultOf(reply: JSONRPCResponse): Record { + if (!('result' in reply)) throw new Error(`expected a result, got ${JSON.stringify(reply)}`); + return reply.result as Record; +} + +/** The error of a response that must fail. */ +export function errorOf(reply: JSONRPCResponse): JSONRPCErrorResponse['error'] { + if (!('error' in reply)) throw new Error(`expected an error, got ${JSON.stringify(reply)}`); + return reply.error; +} diff --git a/packages/server/test/ext/events/registration.test.ts b/packages/server/test/ext/events/registration.test.ts new file mode 100644 index 0000000000..e8fc327660 --- /dev/null +++ b/packages/server/test/ext/events/registration.test.ts @@ -0,0 +1,273 @@ +import type { DiscoverResult, InitializeResult } from '@modelcontextprotocol/core-internal'; +import { InMemoryTransport } from '@modelcontextprotocol/core-internal'; +import { describe, expect, expectTypeOf, it, vi } from 'vitest'; +import * as z from 'zod/v4'; + +import type { SubscriptionSource } from '../../../src/ext/events/extension'; +import type { EventInput, ListEventsResult } from '../../../src/ext/events/index'; +import { EventsError, EventsExtension } from '../../../src/ext/events/index'; +import type { EventsTestHook } from '../../../src/ext/events/testHook'; +import { McpServer } from '../../../src/server/mcp'; +import { legacyAdvertisedCapabilities } from '../../../src/server/modernOnlyExtensions'; +import { errorOf, LEGACY, resultOf, serve } from './harness'; + +const P = z.object({ n: z.number() }); +const tick = () => ({ events: [], cursor: '0' }); +const webhookSender = async () => ({ status: 200, body: '' }); + +function testHook(events: EventsExtension): EventsTestHook { + return (events as unknown as Record)[Symbol.for('mcp.events.testHook')]!; +} + +async function listOf(events: EventsExtension): Promise { + return resultOf(await serve(events).rpc('events/list')) as ListEventsResult; +} + +describe('discovery', () => { + it('declares {} on server/discover and nothing on legacy initialize', async () => { + const events = new EventsExtension(); + events.registerEvent('tick', { payloadSchema: P, check: tick }); + const { rpc } = serve(events); + const discover = resultOf(await rpc('server/discover')) as DiscoverResult; + expect(discover.capabilities.extensions?.['io.modelcontextprotocol/events']).toEqual({}); + const init = resultOf( + await rpc( + 'initialize', + { protocolVersion: LEGACY, capabilities: {}, clientInfo: { name: 't', version: '1' } }, + { era: 'legacy' } + ) + ) as InitializeResult; + expect(init.capabilities.extensions?.['io.modelcontextprotocol/events']).toBeUndefined(); + }); + + it('hides only the modern-only extensions from the legacy capabilities', () => { + const mcp = new McpServer({ name: 't', version: '1' }, { capabilities: { extensions: { 'example.com/other': {} } } }); + new EventsExtension().attach(mcp); + expect(legacyAdvertisedCapabilities(mcp.server, mcp.server.getCapabilities()).extensions).toEqual({ 'example.com/other': {} }); + const alone = new McpServer({ name: 't', version: '1' }); + new EventsExtension().attach(alone); + expect(legacyAdvertisedCapabilities(alone.server, alone.server.getCapabilities())).not.toHaveProperty('extensions'); + }); + + it('answers -32601 to a legacy events request', async () => { + const events = new EventsExtension(); + events.registerEvent('tick', { payloadSchema: P, check: tick }); + const reply = await serve(events).rpc('events/list', {}, { era: 'legacy' }); + expect(errorOf(reply)).toMatchObject({ code: -32_601, message: 'Method not found' }); + }); + + it('lists descriptors with JSON schemas and computed delivery', async () => { + const plain = new EventsExtension(); + plain.registerEvent('tick', { + description: 'Ticks', + inputSchema: z.object({ every: z.number().optional() }), + payloadSchema: P, + _meta: { 'example.com/key': 1 }, + check: tick + }); + plain.registerEvent('quiet', { emitOnly: true, payloadSchema: P, delivery: { push: false } }); + const list = await listOf(plain); + expect(list).toMatchObject({ resultType: 'complete' }); + expect(list.nextCursor).toBeUndefined(); + expect(list.events).toMatchObject([ + { + name: 'tick', + description: 'Ticks', + delivery: ['poll', 'push'], + inputSchema: { type: 'object', properties: { every: { type: 'number' } } }, + payloadSchema: { type: 'object', properties: { n: { type: 'number' } }, required: ['n'] }, + _meta: { 'example.com/key': 1 } + }, + { name: 'quiet', delivery: ['poll'], inputSchema: { type: 'object' } } + ]); + expect(list.events[1]).not.toHaveProperty('description'); + + const webhook = new EventsExtension({ webhookTtlMs: 60_000, webhookSender, getPrincipal: () => 'alice' }); + webhook.registerEvent('tick', { payloadSchema: P, check: tick }); + webhook.registerEvent('hooked', { payloadSchema: P, check: tick, delivery: { poll: false, push: false } }); + expect((await listOf(webhook)).events.map(event => event.delivery)).toEqual([['poll', 'push', 'webhook'], ['webhook']]); + }); + + it('reports an invalid x-mcp-header to onerror and still lists the event', async () => { + const onerror = vi.fn(); + const events = new EventsExtension({ onerror }); + events.registerEvent('r', { + inputSchema: z.object({ r: z.object({}).meta({ 'x-mcp-header': 'R' }) }), + payloadSchema: P, + check: tick + }); + expect(onerror).toHaveBeenCalledOnce(); + expect(onerror.mock.calls[0]![0]).toBeInstanceOf(Error); + expect(onerror.mock.calls[0]![0].message).toMatch( + /^event 'r' carries an invalid x-mcp-header declaration and will be excluded by conforming Streamable HTTP clients: / + ); + const [listed] = (await listOf(events)).events; + expect(listed).toMatchObject({ name: 'r', inputSchema: { properties: { r: { 'x-mcp-header': 'R' } } } }); + }); +}); + +describe('options', () => { + it('refuses partial webhook configuration', () => { + expect(() => new EventsExtension({ webhookTtlMs: 60_000 })).toThrow(TypeError); + expect(() => new EventsExtension({ webhookSender })).toThrow(TypeError); + expect(() => new EventsExtension({ webhookTtlMs: 60_000, webhookSender })).toThrow(TypeError); + expect(() => new EventsExtension({ getPrincipal: () => 'alice' })).not.toThrow(); + expect(() => new EventsExtension({ webhookTtlMs: 60_000, webhookSender, getPrincipal: () => 'alice' })).not.toThrow(); + }); + + it.each([0, -1, Number.NaN, Number.POSITIVE_INFINITY])('refuses %s for a numeric option', value => { + expect(() => new EventsExtension({ heartbeatMs: value })).toThrow(TypeError); + expect(() => new EventsExtension({ maxSubscriptions: value })).toThrow(TypeError); + expect(() => new EventsExtension({ emitBuffer: { maxEvents: value } })).toThrow(TypeError); + expect(() => new EventsExtension({ webhookTtlMs: value, webhookSender, getPrincipal: () => 'alice' })).toThrow(TypeError); + }); + + it('accepts only exact origins as trustedOrigins', () => { + expect(() => new EventsExtension({ trustedOrigins: ['http://127.0.0.1:9000', 'https://example.com'] })).not.toThrow(); + for (const origin of ['http://127.0.0.1:9000/', 'https://example.com/hook', 'HTTPS://EXAMPLE.COM', 'example.com', 'not a url']) { + expect(() => new EventsExtension({ trustedOrigins: [origin] })).toThrow(TypeError); + } + }); +}); + +describe('registerEvent', () => { + it('enforces the two kinds at runtime', () => { + const events = new EventsExtension(); + const message = /pass check\(\), or emitOnly: true and call emit\(\) on the returned handle/; + // @ts-expect-error check with emitOnly + expect(() => events.registerEvent('a', { emitOnly: true, payloadSchema: P, check: tick })).toThrow(/emitOnly: true/); + // @ts-expect-error neither check nor emitOnly + expect(() => events.registerEvent('b', { payloadSchema: P })).toThrow(TypeError); + // @ts-expect-error match without emitOnly + expect(() => events.registerEvent('c', { payloadSchema: P, check: tick, match: () => true })).toThrow(message); + // @ts-expect-error transform without emitOnly + expect(() => events.registerEvent('d', { payloadSchema: P, check: tick, transform: (_ctx, event) => event })).toThrow(message); + const noMode = { payloadSchema: P, check: tick, delivery: { poll: false, push: false } } as const; + expect(() => events.registerEvent('e', noMode)).toThrow(/delivery turns off every mode/); + }); + + it('types emit() only on emit-only handles', () => { + const events = new EventsExtension(); + const checkHandle = events.registerEvent('a', { payloadSchema: P, check: () => ({ events: [], cursor: null }) }); + // @ts-expect-error no emit on a check type + void checkHandle.emit; + expectTypeOf(events.registerEvent('b', { emitOnly: true, payloadSchema: z.object({ n: z.number() }) }).emit) + .parameter(0) + .toEqualTypeOf>(); + expectTypeOf(checkHandle.update).toBeCallableWith({ description: 'v2' }); + }); + + it('refuses the same schemas again and terminates live subscriptions when a schema changes', async () => { + const events = new EventsExtension(); + const terminate = vi.fn(async () => {}); + testHook(events).addSource({ terminate }); + events.registerEvent('tick', { payloadSchema: P, check: tick }); + expect(() => events.registerEvent('tick', { emitOnly: true, payloadSchema: P })).toThrow(/already registered/); + expect(terminate).not.toHaveBeenCalled(); + + events.registerEvent('tick', { payloadSchema: z.object({ n: z.string() }), check: tick }); + expect(terminate).toHaveBeenLastCalledWith('tick', expect.any(EventsError), undefined); + expect(terminate.mock.lastCall![1]).toMatchObject({ + kind: 'unsupported', + data: { feature: 'payloadSchema', reason: 'schema_changed' } + }); + + events.registerEvent('tick', { inputSchema: z.object({ q: z.string() }), payloadSchema: z.object({ n: z.string() }), check: tick }); + expect(terminate.mock.lastCall![1]).toMatchObject({ + kind: 'unsupported', + data: { feature: 'inputSchema', reason: 'schema_changed' } + }); + expect((await listOf(events)).events).toMatchObject([ + { + name: 'tick', + inputSchema: { properties: { q: { type: 'string' } } }, + payloadSchema: { properties: { n: { type: 'string' } } } + } + ]); + }); + + it('update() changes the description; remove() drops the event', async () => { + const events = new EventsExtension(); + const terminate = vi.fn(async () => {}); + testHook(events).addSource({ terminate }); + const handle = events.registerEvent('tick', { description: 'v1', payloadSchema: P, check: tick }); + events.registerEvent('other', { payloadSchema: P, check: tick }); + expect(handle.name).toBe('tick'); + + handle.update({ description: 'v2', inputSchema: z.object({ q: z.string().optional() }) }); + expect((await listOf(events)).events).toMatchObject([ + { name: 'tick', description: 'v2', inputSchema: { properties: { q: { type: 'string' } } } }, + { name: 'other' } + ]); + expect(terminate).not.toHaveBeenCalled(); + + handle.remove(); + expect((await listOf(events)).events.map(event => event.name)).toEqual(['other']); + expect(terminate).toHaveBeenCalledOnce(); + expect(terminate).toHaveBeenCalledWith('tick', expect.any(EventsError), undefined); + expect(terminate.mock.lastCall![1]).toMatchObject({ kind: 'notFound', message: 'Event type removed', data: { kind: 'event' } }); + + expect(() => handle.update({ description: 'v3' })).toThrow(/removed or replaced/); + handle.remove(); + expect(terminate).toHaveBeenCalledOnce(); + }); + + it('terminate() reaches every subscription source', async () => { + const events = new EventsExtension(); + const first = vi.fn(async () => {}); + const second = vi.fn(async () => {}); + testHook(events).addSource({ terminate: first }); + testHook(events).addSource({ terminate: second }); + const handle = events.registerEvent('tick', { payloadSchema: P, check: tick }); + const revoked = new EventsError('forbidden', 'Access revoked'); + await expect(handle.terminate(revoked, { subscriptionId: 'sub-1' })).resolves.toBeUndefined(); + expect(first).toHaveBeenCalledWith('tick', revoked, 'sub-1'); + expect(second).toHaveBeenCalledWith('tick', revoked, 'sub-1'); + await handle.terminate(revoked); + expect(first).toHaveBeenLastCalledWith('tick', revoked, undefined); + }); +}); + +describe('attach', () => { + it('follows the Skills attach rules', async () => { + const events = new EventsExtension(); + const mcp = new McpServer({ name: 't', version: '1' }); + events.attach(mcp); + events.attach(mcp); + expect(mcp.server.getCapabilities().extensions).toEqual({ 'io.modelcontextprotocol/events': {} }); + expect(() => new EventsExtension().attach(mcp)).toThrow( + 'another events extension is already attached to this server; attach one per server' + ); + + const connected = new McpServer({ name: 't', version: '1' }); + const [, serverSide] = InMemoryTransport.createLinkedPair(); + await connected.connect(serverSide); + expect(() => events.attach(connected)).toThrow('attach events before connecting the server'); + await connected.close(); + + const taken = new McpServer({ name: 't', version: '1' }); + taken.server.setRequestHandler('events/poll', { params: z.object({}) }, () => ({})); + expect(() => events.attach(taken)).toThrow('A request handler for events/poll already exists, which would be overridden'); + expect(taken.server.getCapabilities().extensions).toBeUndefined(); + expect(() => taken.server.assertCanSetRequestHandler('events/list')).not.toThrow(); + }); +}); + +describe('test hook', () => { + it('is reachable by its symbol only, and restart() bumps the generation', () => { + const events = new EventsExtension({ trustedOrigins: ['http://127.0.0.1:9000'] }); + const hook = testHook(events); + expect(Object.getOwnPropertyDescriptor(events, Symbol.for('mcp.events.testHook'))).toMatchObject({ enumerable: false }); + expect(Object.getOwnPropertySymbols({ ...events })).toEqual([]); + const generation = hook.generation(); + hook.restart(); + expect(hook.generation()).toBe(generation + 1); + }); + + it('adds trusted origins to the live set with the constructor validation', () => { + const hook = testHook(new EventsExtension({ trustedOrigins: ['http://127.0.0.1:9000'] })); + hook.addTrustedOrigin('http://localhost:8080'); + expect(hook.state().trustedOrigins).toEqual(['http://127.0.0.1:9000', 'http://localhost:8080']); + expect(() => hook.addTrustedOrigin('http://localhost:8080/hook')).toThrow(TypeError); + }); +}); diff --git a/packages/server/test/server/barrelClean.test.ts b/packages/server/test/server/barrelClean.test.ts index 72fc4221bf..d0fbb499d8 100644 --- a/packages/server/test/server/barrelClean.test.ts +++ b/packages/server/test/server/barrelClean.test.ts @@ -122,18 +122,21 @@ describe('@modelcontextprotocol/server root entry is browser-safe', () => { }); }); -describe('@modelcontextprotocol/server root and ext/skills are runtime-neutral', () => { +describe('@modelcontextprotocol/server root, ext/skills and ext/events are runtime-neutral', () => { beforeAll(async () => { await ensureBuilt(pkgDir); }, 180_000); - test.each(['index.mjs', 'ext/skills/index.mjs'])('%s and every chunk it imports have no node: imports', entry => { - for (const file of moduleGraphOf(join(distDir, entry))) { - expect({ file, content: readFileSync(file, 'utf8') }).not.toEqual( - expect.objectContaining({ content: expect.stringMatching(NODE_BUILTIN_IMPORT) }) - ); + test.each(['index.mjs', 'ext/skills/index.mjs', 'ext/events/index.mjs'])( + '%s and every chunk it imports have no node: imports', + entry => { + for (const file of moduleGraphOf(join(distDir, entry))) { + expect({ file, content: readFileSync(file, 'utf8') }).not.toEqual( + expect.objectContaining({ content: expect.stringMatching(NODE_BUILTIN_IMPORT) }) + ); + } } - }); + ); test('ext/skills/node exports the folder adapter and is where the node: imports live', () => { const node = join(distDir, 'ext/skills/node.mjs'); @@ -149,6 +152,22 @@ describe('@modelcontextprotocol/server root and ext/skills are runtime-neutral', ); }); + test('the root entry does not export the events extension', () => { + expect(rootExportBlockOf(readFileSync(join(distDir, 'index.mjs'), 'utf8'))).not.toMatch( + /\b(?:EventsExtension|InMemoryWebhookSubscriptionStore)\b/ + ); + }); + + test('the ext/events declarations carry no test hook', () => { + const graph = declarationGraphOf(join(distDir, 'ext/events/index.d.mts')); + expect(graph.some(file => /\bdeclare class EventsExtension\b/.test(readFileSync(file, 'utf8')))).toBe(true); + for (const file of graph) { + expect({ file, content: readFileSync(file, 'utf8') }).not.toEqual( + expect.objectContaining({ content: expect.stringMatching(/testHook|TestHook/) }) + ); + } + }); + test('dist/index.mjs and every chunk it imports carry no skills code and no @modelcontextprotocol/core/ext/skills import', () => { // Users who never import ext/skills must not load (or bundle) the frontmatter parser or the skills schemas. for (const file of moduleGraphOf(join(distDir, 'index.mjs'))) { diff --git a/packages/server/test/server/errorBrandConformance.test.ts b/packages/server/test/server/errorBrandConformance.test.ts index 37800695e0..14cbe39eeb 100644 --- a/packages/server/test/server/errorBrandConformance.test.ts +++ b/packages/server/test/server/errorBrandConformance.test.ts @@ -1,11 +1,12 @@ import { describe, expect, it, vi } from 'vitest'; +import * as events from '../../src/ext/events/index'; import * as skills from '../../src/ext/skills/index'; import * as skillsNode from '../../src/ext/skills/node'; import * as barrel from '../../src/index'; -/** Every public entry that can export an error class: the root and the skills extension's subpaths. */ -const SURFACES: ReadonlyArray> = [barrel, skills, skillsNode]; +/** Every public entry that can export an error class: the root and the extensions' subpaths. */ +const SURFACES: ReadonlyArray> = [barrel, skills, skillsNode, events]; /** * Server-side twin of the client's errorBrandConformance test: every error @@ -39,6 +40,7 @@ describe('error brand conformance (server export surface)', () => { expect(classes.length).toBeGreaterThanOrEqual(5); expect(classes.map(([n]) => n)).toContain('ProtocolError'); expect(classes.map(([n]) => n)).toContain('SkillCatalogError'); + expect(classes.map(([n]) => n)).toContain('EventsError'); }); it('every exported error class is branded (or explicitly allowlisted)', () => { @@ -85,7 +87,7 @@ describe('error brand conformance (server export surface)', () => { 'UnsupportedProtocolVersionError', 'UrlElicitationRequiredError' ]); - const SERVER_LOCAL_BRANDS: Record = { SkillCatalogError: 'mcp.SkillCatalogError' }; + const SERVER_LOCAL_BRANDS: Record = { EventsError: 'mcp.EventsError', SkillCatalogError: 'mcp.SkillCatalogError' }; it('pins every server-local brand string (add new entries here — renames must be deliberate)', () => { const brands = Object.fromEntries( diff --git a/packages/server/tsdown.config.ts b/packages/server/tsdown.config.ts index 06137a4560..08200ea2f2 100644 --- a/packages/server/tsdown.config.ts +++ b/packages/server/tsdown.config.ts @@ -11,7 +11,8 @@ export default defineConfig({ 'src/validators/ajv.ts', 'src/validators/cfWorker.ts', 'src/ext/skills/index.ts', - 'src/ext/skills/node.ts' + 'src/ext/skills/node.ts', + 'src/ext/events/index.ts' ], format: ['esm', 'cjs'], fixedExtension: true, @@ -29,9 +30,11 @@ export default defineConfig({ paths: { 'fast-uri': ['../core-internal/src/validators/fastUriShim.d.ts'], '@modelcontextprotocol/core/ext/skills': ['../core/src/ext/skills/index.ts'], + '@modelcontextprotocol/core/ext/events': ['../core/src/ext/events/index.ts'], '@modelcontextprotocol/core-internal': ['../core-internal/src/index.ts'], '@modelcontextprotocol/core-internal/public': ['../core-internal/src/exports/public/index.ts'], '@modelcontextprotocol/core-internal/ext/skills': ['../core-internal/src/ext/skills/index.ts'], + '@modelcontextprotocol/core-internal/ext/events': ['../core-internal/src/ext/events/index.ts'], '@modelcontextprotocol/core-internal/validators/ajv': ['../core-internal/src/validators/ajvProvider.ts'], '@modelcontextprotocol/core-internal/validators/cfWorker': ['../core-internal/src/validators/cfWorkerProvider.ts'] } @@ -41,5 +44,10 @@ export default defineConfig({ // The schema modules live in @modelcontextprotocol/core (a real runtime dependency); the // bundled core-internal shims import them via the './internal' subpath, which must stay an // external import (explicit entry — the tsconfig paths alias would otherwise inline it). - external: ['@modelcontextprotocol/server/_shims', '@modelcontextprotocol/core/internal', '@modelcontextprotocol/core/ext/skills'] + external: [ + '@modelcontextprotocol/server/_shims', + '@modelcontextprotocol/core/internal', + '@modelcontextprotocol/core/ext/skills', + '@modelcontextprotocol/core/ext/events' + ] }); diff --git a/test/conformance/tsconfig.json b/test/conformance/tsconfig.json index 279537aae2..59f6fb2b6e 100644 --- a/test/conformance/tsconfig.json +++ b/test/conformance/tsconfig.json @@ -30,6 +30,7 @@ "@modelcontextprotocol/server/_shims": ["./node_modules/@modelcontextprotocol/server/src/shimsNode.ts"], "@modelcontextprotocol/client/ext/skills": ["./node_modules/@modelcontextprotocol/client/src/ext/skills/index.ts"], "@modelcontextprotocol/server/ext/skills": ["./node_modules/@modelcontextprotocol/server/src/ext/skills/index.ts"], + "@modelcontextprotocol/server/ext/events": ["./node_modules/@modelcontextprotocol/server/src/ext/events/index.ts"], "@modelcontextprotocol/express": ["./node_modules/@modelcontextprotocol/express/src/index.ts"], "@modelcontextprotocol/node": ["./node_modules/@modelcontextprotocol/node/src/index.ts"], "@modelcontextprotocol/vitest-config": ["./node_modules/@modelcontextprotocol/vitest-config/tsconfig.json"], diff --git a/test/e2e/tsconfig.json b/test/e2e/tsconfig.json index c014cafe91..5208150f7c 100644 --- a/test/e2e/tsconfig.json +++ b/test/e2e/tsconfig.json @@ -39,6 +39,7 @@ "@modelcontextprotocol/server/validators/ajv": ["./node_modules/@modelcontextprotocol/server/src/validators/ajv.ts"], "@modelcontextprotocol/server/validators/cf-worker": ["./node_modules/@modelcontextprotocol/server/src/validators/cfWorker.ts"], "@modelcontextprotocol/server/ext/skills": ["./node_modules/@modelcontextprotocol/server/src/ext/skills/index.ts"], + "@modelcontextprotocol/server/ext/events": ["./node_modules/@modelcontextprotocol/server/src/ext/events/index.ts"], "@modelcontextprotocol/server-legacy": ["./node_modules/@modelcontextprotocol/server-legacy/src/index.ts"], "@modelcontextprotocol/server-legacy/sse": ["./node_modules/@modelcontextprotocol/server-legacy/src/sse/index.ts"], "@modelcontextprotocol/express": ["./node_modules/@modelcontextprotocol/express/src/index.ts"], diff --git a/test/integration/tsconfig.json b/test/integration/tsconfig.json index 2f985e654a..e92659d52d 100644 --- a/test/integration/tsconfig.json +++ b/test/integration/tsconfig.json @@ -43,6 +43,7 @@ "@modelcontextprotocol/client/ext/skills": ["./node_modules/@modelcontextprotocol/client/src/ext/skills/index.ts"], "@modelcontextprotocol/server/ext/skills": ["./node_modules/@modelcontextprotocol/server/src/ext/skills/index.ts"], "@modelcontextprotocol/server/ext/skills/node": ["./node_modules/@modelcontextprotocol/server/src/ext/skills/node.ts"], + "@modelcontextprotocol/server/ext/events": ["./node_modules/@modelcontextprotocol/server/src/ext/events/index.ts"], "@modelcontextprotocol/express": ["./node_modules/@modelcontextprotocol/express/src/index.ts"], "@modelcontextprotocol/node": ["./node_modules/@modelcontextprotocol/node/src/index.ts"], "@modelcontextprotocol/vitest-config": ["./node_modules/@modelcontextprotocol/vitest-config/tsconfig.json"], From 65be2c3867bfb68f5f48d6cb4e703763d3607e5a Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 11:22:37 +0200 Subject: [PATCH 04/37] feat(server): events/poll with emit buffer, cursors and poll leases --- packages/server/src/ext/events/emitBuffer.ts | 135 +++++ packages/server/src/ext/events/extension.ts | 99 +++- packages/server/src/ext/events/leases.ts | 94 +++ packages/server/src/ext/events/poll.ts | 212 +++++++ packages/server/src/ext/events/testHook.ts | 7 +- packages/server/src/ext/events/validation.ts | 66 +++ .../server/test/ext/events/emitBuffer.test.ts | 178 ++++++ packages/server/test/ext/events/poll.test.ts | 540 ++++++++++++++++++ 8 files changed, 1318 insertions(+), 13 deletions(-) create mode 100644 packages/server/src/ext/events/emitBuffer.ts create mode 100644 packages/server/src/ext/events/leases.ts create mode 100644 packages/server/src/ext/events/poll.ts create mode 100644 packages/server/src/ext/events/validation.ts create mode 100644 packages/server/test/ext/events/emitBuffer.test.ts create mode 100644 packages/server/test/ext/events/poll.test.ts diff --git a/packages/server/src/ext/events/emitBuffer.ts b/packages/server/src/ext/events/emitBuffer.ts new file mode 100644 index 0000000000..27b950ff89 --- /dev/null +++ b/packages/server/src/ext/events/emitBuffer.ts @@ -0,0 +1,135 @@ +import type { EventOccurrence } from '@modelcontextprotocol/core/ext/events'; + +// One emitted event; `target` is the subscriptionId of a targeted emit. +export interface BufferedEvent { + readonly occurrence: EventOccurrence; + readonly target?: string; +} + +export interface BufferRead { + events: EventOccurrence[]; + cursor: string; + truncated: boolean; + hasMore: boolean; +} + +interface Entry { + readonly at: number; + readonly event: BufferedEvent; +} + +// The entries of one event type hold the sequence numbers `evicted + 1` through `last`. +interface Ring { + readonly entries: Entry[]; + last: number; + evicted: number; +} + +const CURSOR = /^e([0-9a-f]{8})\.(0|[1-9]\d*)$/; + +function newEpoch(): string { + return globalThis.crypto.getRandomValues(new Uint32Array(1))[0]!.toString(16).padStart(8, '0'); +} + +// Per-type in-memory ring of emitted events; cursors `e.` are valid only for this instance's epoch. +export class EmitBuffer { + readonly #maxAgeMs: number; + readonly #maxEvents: number; + readonly #now: () => number; + readonly #rings = new Map(); + #epoch = newEpoch(); + + constructor(limits: { maxAgeMs: number; maxEvents: number }, now: () => number = () => Date.now()) { + this.#maxAgeMs = limits.maxAgeMs; + this.#maxEvents = limits.maxEvents; + this.#now = now; + } + + // Returns the position just before the appended event (the previous head). + append(name: string, event: BufferedEvent): string { + let ring = this.#rings.get(name); + if (ring === undefined) { + ring = { entries: [], last: 0, evicted: 0 }; + this.#rings.set(name, ring); + } + const previous = this.#format(ring.last); + ring.last += 1; + ring.entries.push({ at: this.#now(), event }); + this.#evict(ring); + return previous; + } + + head(name: string): string { + return this.#format(this.#rings.get(name)?.last ?? 0); + } + + // A cursor this buffer cannot serve from reads as a gap: no events, `truncated`, and the oldest servable position. + read( + name: string, + cursor: string | null, + options: { maxEvents: number; maxAgeMs?: number; select(event: BufferedEvent): EventOccurrence | undefined } + ): BufferRead { + const ring = this.#rings.get(name) ?? { entries: [], last: 0, evicted: 0 }; + this.#evict(ring); + if (cursor === null) return { events: [], cursor: this.#format(ring.last), truncated: false, hasMore: false }; + const parsed = this.#parse(cursor); + const valid = parsed !== undefined && parsed >= ring.evicted && parsed <= ring.last; + let index = valid ? parsed - ring.evicted : 0; + let skipped = false; + if (options.maxAgeMs !== undefined) { + const floor = this.#now() - options.maxAgeMs; + while (index < ring.entries.length && ring.entries[index]!.at < floor) { + index += 1; + skipped = true; + } + } + if (!valid) { + const position = ring.evicted + index; + return { events: [], cursor: this.#format(position), truncated: true, hasMore: position < ring.last }; + } + const events: EventOccurrence[] = []; + while (index < ring.entries.length && events.length < options.maxEvents) { + const selected = options.select(ring.entries[index]!.event); + index += 1; + if (selected !== undefined) events.push(selected); + } + const position = ring.evicted + index; + return { events, cursor: this.#format(position), truncated: skipped, hasMore: position < ring.last }; + } + + // Retained events per event type. + sizes(): Record { + const sizes: Record = {}; + for (const [name, ring] of this.#rings) { + this.#evict(ring); + sizes[name] = ring.entries.length; + } + return sizes; + } + + // Drops every event and starts a new epoch, as a process restart would. + clear(): void { + this.#rings.clear(); + this.#epoch = newEpoch(); + } + + #evict(ring: Ring): void { + const floor = this.#now() - this.#maxAgeMs; + let drop = 0; + while (drop < ring.entries.length && (ring.entries.length - drop > this.#maxEvents || ring.entries[drop]!.at < floor)) drop += 1; + if (drop === 0) return; + ring.entries.splice(0, drop); + ring.evicted += drop; + } + + #format(sequence: number): string { + return `e${this.#epoch}.${sequence}`; + } + + #parse(cursor: string): number | undefined { + const match = CURSOR.exec(cursor); + if (match === null || match[1] !== this.#epoch) return undefined; + const sequence = Number(match[2]); + return Number.isSafeInteger(sequence) ? sequence : undefined; + } +} diff --git a/packages/server/src/ext/events/extension.ts b/packages/server/src/ext/events/extension.ts index ca895eb555..edb4f31099 100644 --- a/packages/server/src/ext/events/extension.ts +++ b/packages/server/src/ext/events/extension.ts @@ -6,7 +6,8 @@ import { EVENTS_STREAM_METHOD, EVENTS_SUBSCRIBE_METHOD, EVENTS_UNSUBSCRIBE_METHOD, - ListEventsRequestParamsSchema + ListEventsRequestParamsSchema, + PollEventsRequestParamsSchema } from '@modelcontextprotocol/core/ext/events'; import type { ServerContext, StandardSchemaWithJSON } from '@modelcontextprotocol/core-internal'; import { scanXMcpHeaderDeclarations } from '@modelcontextprotocol/core-internal'; @@ -14,17 +15,24 @@ import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; import type { McpServer } from '../../server/mcp'; import { markModernOnlyExtension } from '../../server/modernOnlyExtensions'; +import type { BufferedEvent } from './emitBuffer'; +import { EmitBuffer } from './emitBuffer'; import { assertModernRequest } from './eraGate'; +import { PollSource, toOccurrence } from './poll'; import type { AnyEventDefinition, RegisteredEvent } from './registry'; import { changedSchema, deliveryModes, EventRegistry } from './registry'; import { installTestHook } from './testHook'; -import type { CheckEventDefinition, EmitOnlyEventDefinition, EmitOnlyEventHandle, EventHandle, EventsOptions } from './types'; +import type { CheckEventDefinition, EmitOnlyEventDefinition, EmitOnlyEventHandle, EventHandle, EventInput, EventsOptions } from './types'; +import { SubscriptionValidator } from './validation'; // The live subscriptions of one delivery mode, which `remove()`, a schema change and `terminate()` end. export interface SubscriptionSource { terminate(name: string, error: EventsError, subscriptionId?: string): Promise; } +// Receives each emitted event once it is buffered: `cursor` is the position after it, `previous` the one before. +export type EmitFanOut = (name: string, buffered: BufferedEvent, positions: { cursor: string; previous: string }) => void | Promise; + type DefaultSchema = StandardSchemaWithJSON>; const EVENTS_METHODS = [EVENTS_LIST_METHOD, EVENTS_POLL_METHOD, EVENTS_STREAM_METHOD, EVENTS_SUBSCRIBE_METHOD, EVENTS_UNSUBSCRIBE_METHOD]; @@ -38,6 +46,11 @@ const NUMERIC_OPTIONS = [ 'maxSubscriptions' ] as const; +const DEFAULT_EMIT_BUFFER_MAX_AGE_MS = 600_000; +const DEFAULT_EMIT_BUFFER_MAX_EVENTS = 10_000; +const DEFAULT_POLL_SUBSCRIPTION_TTL_MS = 300_000; +const DEFAULT_NEXT_POLL_MS = 30_000; + // Servers with an events extension attached: one per server, as SEP-3371 rejects a duplicate extension identifier. const eventsServers = new WeakSet(); @@ -104,6 +117,11 @@ export class EventsExtension { readonly #trustedOrigins: Set; readonly #webhookEnabled: boolean; readonly #onerror: (error: Error) => void; + readonly #buffer: EmitBuffer; + readonly #validator: SubscriptionValidator; + readonly #poll: PollSource; + // Each emitted event is handed to these after it is buffered; push and webhook delivery add theirs. + readonly #fanOuts: EmitFanOut[] = []; // Clears process-memory state on a simulated restart; each delivery mode adds its own. readonly #restarts: Array<() => void> = []; #generation = 1; @@ -118,19 +136,45 @@ export class EventsExtension { this.#trustedOrigins = new Set(options.trustedOrigins); this.#webhookEnabled = options.webhookTtlMs !== undefined; this.#onerror = options.onerror ?? defaultOnerror; + this.#buffer = new EmitBuffer({ + maxAgeMs: options.emitBuffer?.maxAgeMs ?? DEFAULT_EMIT_BUFFER_MAX_AGE_MS, + maxEvents: options.emitBuffer?.maxEvents ?? DEFAULT_EMIT_BUFFER_MAX_EVENTS + }); + this.#validator = new SubscriptionValidator({ + registry: this.#registry, + webhookEnabled: this.#webhookEnabled, + getPrincipal: options.getPrincipal, + maxSubscriptions: options.maxSubscriptions, + subscriptionCount: () => this.#poll.size + }); + this.#poll = new PollSource({ + validator: this.#validator, + buffer: this.#buffer, + pollSubscriptionTtlMs: options.pollSubscriptionTtlMs ?? DEFAULT_POLL_SUBSCRIPTION_TTL_MS, + defaultNextPollMs: options.defaultNextPollMs ?? DEFAULT_NEXT_POLL_MS, + report: error => this.#report(error) + }); + this.#sources.push(this.#poll); + this.#restarts.push( + () => this.#buffer.clear(), + () => this.#poll.clear() + ); installTestHook(this, { generation: () => this.#generation, restart: () => { this.#generation += 1; for (const clear of this.#restarts) clear(); }, - state: () => ({ trustedOrigins: [...this.#trustedOrigins] }), + state: () => ({ trustedOrigins: [...this.#trustedOrigins], emitBuffer: this.#buffer.sizes(), pollLeases: this.#poll.size }), addTrustedOrigin: origin => { assertOrigin(origin); this.#trustedOrigins.add(origin); }, addSource: source => { this.#sources.push(source); + }, + addFanOut: fanOut => { + this.#fanOuts.push(fanOut); } }); } @@ -157,6 +201,9 @@ export class EventsExtension { // Check before changing anything; declare the capability last, so a server never advertises events it does not serve. for (const method of EVENTS_METHODS) server.assertCanSetRequestHandler(method); server.setRequestHandler(EVENTS_LIST_METHOD, { params: ListEventsRequestParamsSchema }, (_params, ctx) => this.#list(ctx)); + server.setRequestHandler(EVENTS_POLL_METHOD, { params: PollEventsRequestParamsSchema }, (params, ctx) => + this.#poll.handlePoll(params, ctx) + ); server.registerCapabilities({ extensions: { [EVENTS_EXTENSION_ID]: {} } }); markModernOnlyExtension(server, EVENTS_EXTENSION_ID); this.#attached.add(mcp); @@ -194,12 +241,15 @@ export class EventsExtension { new EventsError('unsupported', `Event type ${feature} changed`, { feature, reason: 'schema_changed' }) ); } - return { + const assertCurrent = (): void => { + if (this.#registry.get(name) !== current) { + throw new Error(`event '${name}': this handle's registration was removed or replaced`); + } + }; + const handle: EventHandle = { name, update: changes => { - if (this.#registry.get(name) !== current) { - throw new Error(`event '${name}': this handle's registration was removed or replaced`); - } + assertCurrent(); current = this.#registry.update(current, changes); if (changes.inputSchema !== undefined) this.#checkHeaders(current); }, @@ -210,6 +260,15 @@ export class EventsExtension { }, terminate: (error, options) => this.#terminate(name, error, options?.subscriptionId) }; + if (definition.emitOnly !== true) return handle; + const emitOnly: EmitOnlyEventHandle = { + ...handle, + emit: async (input, options) => { + assertCurrent(); + await this.#emit(current, input, options?.subscriptionId); + } + }; + return emitOnly; } #list(ctx: ServerContext): ListEventsResult { @@ -240,20 +299,36 @@ export class EventsExtension { ); } + // Validates and buffers the event, then hands it to every fan-out; nobody listening is not an error. + async #emit(entry: RegisteredEvent, input: EventInput, subscriptionId: string | undefined): Promise { + const occurrence = await toOccurrence(entry, input, error => this.#report(error)); + if (occurrence === undefined) return; + const buffered: BufferedEvent = subscriptionId === undefined ? { occurrence } : { occurrence, target: subscriptionId }; + const previous = this.#buffer.append(entry.name, buffered); + const positions = { cursor: this.#buffer.head(entry.name), previous }; + await Promise.all( + this.#fanOuts.map(async fanOut => { + try { + await fanOut(entry.name, buffered, positions); + } catch (error) { + this.#report(error); + } + }) + ); + } + async #terminate(name: string, error: EventsError, subscriptionId: string | undefined): Promise { await Promise.all(this.#sources.map(source => source.terminate(name, error, subscriptionId))); } // For callers that cannot wait: a failed termination goes to onerror. #terminateLater(name: string, error: EventsError): void { - this.#terminate(name, error, undefined).catch((error_: unknown) => - this.#report(error_ instanceof Error ? error_ : new Error(String(error_))) - ); + this.#terminate(name, error, undefined).catch((error_: unknown) => this.#report(error_)); } - #report(error: Error): void { + #report(error: unknown): void { try { - this.#onerror(error); + this.#onerror(error instanceof Error ? error : new Error(String(error))); } catch { // A throwing onerror must not break the caller it reports for. } diff --git a/packages/server/src/ext/events/leases.ts b/packages/server/src/ext/events/leases.ts new file mode 100644 index 0000000000..dd55c52b24 --- /dev/null +++ b/packages/server/src/ext/events/leases.ts @@ -0,0 +1,94 @@ +import type { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; +import { canonicalJson } from '@modelcontextprotocol/core-internal/ext/events'; + +// setTimeout fires at once for longer delays; a longer lease re-arms when the timer fires early. +const MAX_TIMER_DELAY_MS = 2 ** 31 - 1; + +export interface Lease { + readonly subscriptionId: string; + readonly name: string; + readonly principal: string | null; + readonly args: Record; + terminated?: EventsError; +} + +// One lease per (principal or null, event name, canonical arguments), as SEP-3415 Appendix A keys poll subscriptions. +export function leaseKey(principal: string | null, name: string, args: Record): string { + return `${principal ?? ''}\u0000${name}\u0000${canonicalJson(args)}`; +} + +interface Slot { + readonly lease: L; + expiresAt: number; + timer?: ReturnType; +} + +// Poll leases: `touch` creates or renews one, and a lease expires `ttlMs` after its last touch. +export class LeaseTable { + readonly #slots = new Map>(); + readonly #ttlMs: number; + readonly #onExpire: (lease: L) => void; + readonly #now: () => number; + + constructor(ttlMs: number, onExpire: (lease: L) => void, now: () => number = () => Date.now()) { + this.#ttlMs = ttlMs; + this.#onExpire = onExpire; + this.#now = now; + } + + get size(): number { + return this.#slots.size; + } + + get(key: string): L | undefined { + return this.#slots.get(key)?.lease; + } + + touch(key: string, create: () => L): { lease: L; created: boolean } { + const existing = this.#slots.get(key); + if (existing !== undefined) { + existing.expiresAt = this.#now() + this.#ttlMs; + return { lease: existing.lease, created: false }; + } + const slot: Slot = { lease: create(), expiresAt: this.#now() + this.#ttlMs }; + this.#slots.set(key, slot); + this.#arm(key, slot); + return { lease: slot.lease, created: true }; + } + + forEach(name: string, fn: (lease: L) => void): void { + for (const { lease } of this.#slots.values()) { + if (lease.name === name) fn(lease); + } + } + + delete(key: string): void { + const slot = this.#slots.get(key); + if (slot === undefined) return; + clearTimeout(slot.timer); + this.#slots.delete(key); + } + + // Drops every lease without expiring it, as a process restart would. + clear(): void { + for (const slot of this.#slots.values()) clearTimeout(slot.timer); + this.#slots.clear(); + } + + #arm(key: string, slot: Slot): void { + const delay = Math.min(Math.max(slot.expiresAt - this.#now(), 0), MAX_TIMER_DELAY_MS); + slot.timer = setTimeout(() => this.#fire(key, slot), delay); + (slot.timer as { unref?: () => void }).unref?.(); + } + + // One timer per lease: a touch moves `expiresAt`, and the timer re-arms until it is reached. + #fire(key: string, slot: Slot): void { + if (this.#slots.get(key) !== slot) return; + if (slot.expiresAt > this.#now()) { + this.#arm(key, slot); + return; + } + this.#slots.delete(key); + this.#onExpire(slot.lease); + } +} diff --git a/packages/server/src/ext/events/poll.ts b/packages/server/src/ext/events/poll.ts new file mode 100644 index 0000000000..0d87c2b810 --- /dev/null +++ b/packages/server/src/ext/events/poll.ts @@ -0,0 +1,212 @@ +import type { EventOccurrence, PollEventsRequestParams, PollEventsResult } from '@modelcontextprotocol/core/ext/events'; +import type { ServerContext } from '@modelcontextprotocol/core-internal'; +import type { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; + +import { makeContext } from './context'; +import type { BufferedEvent, EmitBuffer } from './emitBuffer'; +import type { SubscriptionSource } from './extension'; +import type { Lease } from './leases'; +import { leaseKey, LeaseTable } from './leases'; +import type { RegisteredEvent } from './registry'; +import type { EventContext, EventInput } from './types'; +import type { SubscriptionValidator } from './validation'; + +const DEFAULT_MAX_EVENTS = 100; + +// Carries the registration whose onSubscribe ran, so onUnsubscribe pairs with it after a removal or re-registration. +interface PollLease extends Lease { + readonly entry: RegisteredEvent; + // Aborts when the subscription ends; onSubscribe's `ctx.signal`. + readonly ended: AbortController; +} + +export interface PollDeps { + readonly validator: SubscriptionValidator; + readonly buffer: EmitBuffer; + readonly pollSubscriptionTtlMs: number; + readonly defaultNextPollMs: number; + report(error: unknown): void; +} + +// The occurrence the SDK sends for an author's event, or `undefined` (reported) when its data fails `payloadSchema`. +export async function toOccurrence( + entry: RegisteredEvent, + input: EventInput, + report: (error: unknown) => void +): Promise { + const parsed = await entry.parsePayload(input.data); + if (!parsed.ok) { + report(new Error(`event '${entry.name}': dropped an event whose data does not match payloadSchema: ${parsed.error}`)); + return undefined; + } + return { + eventId: input.eventId ?? globalThis.crypto.randomUUID(), + name: entry.name, + timestamp: input.timestamp ?? new Date().toISOString(), + data: parsed.data, + ...(input._meta === undefined ? {} : { _meta: input._meta }) + }; +} + +// `events/poll`: every request carries one subscription, and leases drive `onSubscribe` / `onUnsubscribe` (SEP-3415 Appendix A). +export class PollSource implements SubscriptionSource { + readonly #deps: PollDeps; + readonly #leases: LeaseTable; + // First-sight onSubscribe calls in flight, so a concurrent poll for the same lease waits for the outcome. + readonly #starting = new Map>(); + + constructor(deps: PollDeps) { + this.#deps = deps; + this.#leases = new LeaseTable(deps.pollSubscriptionTtlMs, lease => { + if (lease.terminated === undefined) void this.#unsubscribe(lease); + }); + } + + get size(): number { + return this.#leases.size; + } + + async handlePoll(params: PollEventsRequestParams, ctx: ServerContext): Promise { + let key = ''; + const { entry, principal, args } = await this.#deps.validator.validate('poll', params, ctx, (principal, rawArgs) => { + key = leaseKey(principal, params.name, rawArgs); + this.#throwTerminated(key); + }); + const lease = await this.#lease(key, entry, principal, args); + const fields = { + name: entry.name, + subscriptionId: lease.subscriptionId, + principal, + mode: 'poll' as const, + signal: ctx.mcpReq.signal + }; + const maxEvents = params.maxEvents ?? DEFAULT_MAX_EVENTS; + const cursor = params.cursor ?? null; + const { check } = entry.definition; + if (check === undefined) { + const selectCtx = makeContext(fields); + const read = this.#deps.buffer.read(entry.name, cursor, { + maxEvents, + maxAgeMs: params.maxAgeMs, + select: buffered => this.#select(entry, selectCtx, args, buffered) + }); + return { ...read, nextPollMs: this.#deps.defaultNextPollMs }; + } + + const result = await check(makeContext({ ...fields, maxEvents, maxAgeMs: params.maxAgeMs }), args, cursor); + const nextPollMs = result.nextPollMs ?? this.#deps.defaultNextPollMs; + if (cursor === null) return { events: [], cursor: result.cursor, truncated: false, hasMore: false, nextPollMs }; + const floor = params.maxAgeMs === undefined ? undefined : Date.now() - params.maxAgeMs; + let truncated = result.truncated === true; + const events: EventOccurrence[] = []; + for (const input of result.events) { + const occurrence = await toOccurrence(entry, input, this.#deps.report); + if (occurrence === undefined) continue; + if (floor !== undefined && Date.parse(occurrence.timestamp) < floor) { + truncated = true; + continue; + } + events.push(occurrence); + } + return { events, cursor: result.cursor, truncated, hasMore: result.hasMore === true, nextPollMs }; + } + + // Marks the leases; their next poll answers with `error`, and onUnsubscribe runs now. + async terminate(name: string, error: EventsError, subscriptionId?: string): Promise { + const ended: PollLease[] = []; + // eslint-disable-next-line unicorn/no-array-for-each, unicorn/no-array-callback-reference, unicorn/no-array-method-this-argument -- LeaseTable.forEach(name, fn), not Array#forEach + this.#leases.forEach(name, lease => { + if (lease.terminated !== undefined || (subscriptionId !== undefined && lease.subscriptionId !== subscriptionId)) return; + lease.terminated = error; + ended.push(lease); + }); + await Promise.all(ended.map(lease => this.#unsubscribe(lease))); + } + + // Drops every lease without onUnsubscribe, as a process restart would. + clear(): void { + this.#leases.clear(); + this.#starting.clear(); + } + + // A terminated lease answers its error once, then is gone. + #throwTerminated(key: string): void { + const terminated = this.#leases.get(key)?.terminated; + if (terminated === undefined) return; + this.#leases.delete(key); + throw terminated; + } + + // Renews the lease, or on first sight checks the quota and runs onSubscribe. + async #lease(key: string, entry: RegisteredEvent, principal: string | null, args: Record): Promise { + const pending = this.#starting.get(key); + // Await only a pending start: an unconditional await would let a concurrent first poll in before `touch`. + if (pending !== undefined) await pending; + if (this.#leases.get(key) === undefined) this.#deps.validator.assertCapacity(); + const { lease, created } = this.#leases.touch(key, () => ({ + subscriptionId: globalThis.crypto.randomUUID(), + name: entry.name, + principal, + args, + entry, + ended: new AbortController() + })); + if (!created) return lease; + const ctx = makeContext({ + name: entry.name, + subscriptionId: lease.subscriptionId, + principal, + mode: 'poll', + signal: lease.ended.signal + }); + const starting = (async () => entry.definition.onSubscribe?.(ctx, args))(); + this.#starting.set(key, starting); + try { + await starting; + } catch (error) { + this.#leases.delete(key); + throw error; + } finally { + this.#starting.delete(key); + } + return lease; + } + + // Broadcast events pass `match`; targeted ones reach only their subscription. A throwing hook skips the event. + #select( + entry: RegisteredEvent, + ctx: EventContext, + args: Record, + buffered: BufferedEvent + ): EventOccurrence | undefined { + const { occurrence, target } = buffered; + if (target !== undefined && target !== ctx.subscriptionId) return undefined; + const { match, transform } = entry.definition; + try { + if (target === undefined && match !== undefined && !match(ctx, occurrence, args)) return undefined; + if (transform === undefined) return occurrence; + const shaped = transform(ctx, occurrence, args); + return { + eventId: shaped.eventId ?? occurrence.eventId, + name: occurrence.name, + timestamp: shaped.timestamp ?? occurrence.timestamp, + data: shaped.data as Record, + ...(shaped._meta === undefined ? {} : { _meta: shaped._meta }) + }; + } catch (error) { + this.#deps.report(error); + return undefined; + } + } + + async #unsubscribe(lease: PollLease): Promise { + const { name, subscriptionId, principal, args, entry, ended } = lease; + ended.abort(); + const ctx = makeContext({ name, subscriptionId, principal, mode: 'poll', signal: ended.signal }); + try { + await entry.definition.onUnsubscribe?.(ctx, args); + } catch (error) { + this.#deps.report(error); + } + } +} diff --git a/packages/server/src/ext/events/testHook.ts b/packages/server/src/ext/events/testHook.ts index e568b962ae..c2980c6c79 100644 --- a/packages/server/src/ext/events/testHook.ts +++ b/packages/server/src/ext/events/testHook.ts @@ -1,10 +1,14 @@ -import type { SubscriptionSource } from './extension'; +import type { EmitFanOut, SubscriptionSource } from './extension'; // Where an EventsExtension keeps its test hook; `Symbol.for` so separately bundled copies find it. export const EVENTS_TEST_HOOK = Symbol.for('mcp.events.testHook'); export interface EventsTestState { readonly trustedOrigins: readonly string[]; + // Events the emit buffer holds, per event type. + readonly emitBuffer: Readonly>; + // Live poll leases. + readonly pollLeases: number; } // Internal controls for tests and the conformance fixture; never part of the public API or its declarations. @@ -16,6 +20,7 @@ export interface EventsTestHook { state(): EventsTestState; addTrustedOrigin(origin: string): void; addSource(source: SubscriptionSource): void; + addFanOut(fanOut: EmitFanOut): void; } export function installTestHook(target: object, hook: EventsTestHook): void { diff --git a/packages/server/src/ext/events/validation.ts b/packages/server/src/ext/events/validation.ts new file mode 100644 index 0000000000..b1fb004450 --- /dev/null +++ b/packages/server/src/ext/events/validation.ts @@ -0,0 +1,66 @@ +import type { DeliveryMode } from '@modelcontextprotocol/core/ext/events'; +import type { ServerContext } from '@modelcontextprotocol/core-internal'; +import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; + +import { assertModernRequest } from './eraGate'; +import type { EventRegistry, RegisteredEvent } from './registry'; +import type { EventsOptions } from './types'; + +export interface ValidatorDeps { + readonly registry: EventRegistry; + readonly webhookEnabled: boolean; + readonly getPrincipal: EventsOptions['getPrincipal']; + readonly maxSubscriptions: number | undefined; + // Subscriptions served now, across every delivery mode. + subscriptionCount(): number; +} + +export interface SubscriptionRequest { + readonly name: string; + readonly arguments?: Record; +} + +export interface ValidSubscription { + readonly entry: RegisteredEvent; + readonly principal: string | null; + readonly args: Record; +} + +// The checks every subscription request shares, so poll, push and webhook do not repeat them. +export class SubscriptionValidator { + readonly #deps: ValidatorDeps; + + constructor(deps: ValidatorDeps) { + this.#deps = deps; + } + + // Era gate, principal, event exists, mode offered, `beforeParse` (poll: a terminated lease), then the arguments. + async validate( + mode: DeliveryMode, + params: SubscriptionRequest, + ctx: ServerContext, + beforeParse?: (principal: string | null, rawArgs: Record) => void + ): Promise { + assertModernRequest(ctx); + const principal = (await this.#deps.getPrincipal?.(ctx)) ?? null; + const entry = this.#deps.registry.require(params.name); + if (!entry.modes(this.#deps.webhookEnabled).includes(mode)) { + throw new EventsError('unsupported', `Event type ${params.name} does not offer ${mode} delivery`, { + feature: 'deliveryMode', + value: mode + }); + } + const rawArgs = params.arguments ?? {}; + beforeParse?.(principal, rawArgs); + const args = await entry.parseArguments(rawArgs); + return { entry, principal, args }; + } + + // The `maxSubscriptions` quota; call it before a new subscription's `onSubscribe`. + assertCapacity(): void { + const max = this.#deps.maxSubscriptions; + if (max !== undefined && this.#deps.subscriptionCount() >= max) { + throw new EventsError('resourceExhausted', 'Subscription limit reached', { limit: 'subscriptions', max }); + } + } +} diff --git a/packages/server/test/ext/events/emitBuffer.test.ts b/packages/server/test/ext/events/emitBuffer.test.ts new file mode 100644 index 0000000000..d1f1f4bdee --- /dev/null +++ b/packages/server/test/ext/events/emitBuffer.test.ts @@ -0,0 +1,178 @@ +import type { EventOccurrence } from '@modelcontextprotocol/core/ext/events'; +import { describe, expect, it } from 'vitest'; + +import type { BufferedEvent } from '../../../src/ext/events/emitBuffer'; +import { EmitBuffer } from '../../../src/ext/events/emitBuffer'; + +function occurrence(n: number): EventOccurrence { + return { eventId: `evt_${n}`, name: 'i', timestamp: '2026-01-01T00:00:00.000Z', data: { n } }; +} + +const all = (event: BufferedEvent): EventOccurrence => event.occurrence; +const ids = (events: EventOccurrence[]): string[] => events.map(event => event.eventId); + +function filled(count: number, limits = { maxAgeMs: 60_000, maxEvents: 100 }, now?: () => number): EmitBuffer { + const buffer = new EmitBuffer(limits, now); + for (let n = 1; n <= count; n++) buffer.append('i', { occurrence: occurrence(n) }); + return buffer; +} + +describe('EmitBuffer', () => { + it('appends and reads events in order', () => { + const buffer = new EmitBuffer({ maxAgeMs: 60_000, maxEvents: 100 }); + const start = buffer.head('i'); + for (let n = 1; n <= 3; n++) buffer.append('i', { occurrence: occurrence(n) }); + const read = buffer.read('i', start, { maxEvents: 10, select: all }); + expect(read).toEqual({ + events: [occurrence(1), occurrence(2), occurrence(3)], + cursor: buffer.head('i'), + truncated: false, + hasMore: false + }); + expect(buffer.read('i', read.cursor, { maxEvents: 10, select: all })).toEqual({ + events: [], + cursor: read.cursor, + truncated: false, + hasMore: false + }); + }); + + it('answers a null cursor with the head and no events', () => { + const buffer = filled(2); + expect(buffer.read('i', null, { maxEvents: 10, select: all })).toEqual({ + events: [], + cursor: buffer.head('i'), + truncated: false, + hasMore: false + }); + }); + + it('returns the previous head from append', () => { + const buffer = filled(1); + const before = buffer.head('i'); + expect(buffer.append('i', { occurrence: occurrence(2) })).toBe(before); + expect(buffer.head('i')).not.toBe(before); + expect(ids(buffer.read('i', before, { maxEvents: 10, select: all }).events)).toEqual(['evt_2']); + }); + + it('keeps one sequence per event type', () => { + const buffer = filled(2); + const other = buffer.head('j'); + buffer.append('j', { occurrence: { ...occurrence(9), name: 'j' } }); + expect(ids(buffer.read('j', other, { maxEvents: 10, select: all }).events)).toEqual(['evt_9']); + expect(buffer.read('i', buffer.head('i'), { maxEvents: 10, select: all }).events).toEqual([]); + }); + + it('pages with maxEvents and resumes at the next event', () => { + const buffer = new EmitBuffer({ maxAgeMs: 60_000, maxEvents: 100 }); + const start = buffer.head('i'); + for (let n = 1; n <= 3; n++) buffer.append('i', { occurrence: occurrence(n) }); + const first = buffer.read('i', start, { maxEvents: 1, select: all }); + expect(first).toMatchObject({ truncated: false, hasMore: true }); + expect(ids(first.events)).toEqual(['evt_1']); + const second = buffer.read('i', first.cursor, { maxEvents: 1, select: all }); + expect(ids(second.events)).toEqual(['evt_2']); + expect(second.hasMore).toBe(true); + const third = buffer.read('i', second.cursor, { maxEvents: 1, select: all }); + expect(ids(third.events)).toEqual(['evt_3']); + expect(third).toMatchObject({ cursor: buffer.head('i'), hasMore: false }); + }); + + it('skips the events select drops and still advances past them', () => { + const buffer = new EmitBuffer({ maxAgeMs: 60_000, maxEvents: 100 }); + const start = buffer.head('i'); + for (let n = 1; n <= 4; n++) buffer.append('i', { occurrence: occurrence(n), ...(n === 2 ? { target: 'sub-a' } : {}) }); + const read = buffer.read('i', start, { + maxEvents: 10, + select: event => (event.target === undefined ? event.occurrence : undefined) + }); + expect(ids(read.events)).toEqual(['evt_1', 'evt_3', 'evt_4']); + expect(read.cursor).toBe(buffer.head('i')); + }); + + it('evicts beyond the count bound', () => { + const buffer = new EmitBuffer({ maxAgeMs: 60_000, maxEvents: 2 }); + const start = buffer.head('i'); + const positions = [1, 2, 3].map(n => buffer.append('i', { occurrence: occurrence(n) })); + const gap = buffer.read('i', start, { maxEvents: 10, select: all }); + expect(gap).toEqual({ events: [], cursor: positions[1], truncated: true, hasMore: true }); + expect(ids(buffer.read('i', gap.cursor, { maxEvents: 10, select: all }).events)).toEqual(['evt_2', 'evt_3']); + }); + + it('evicts beyond the age bound', () => { + let now = 0; + const buffer = new EmitBuffer({ maxAgeMs: 1000, maxEvents: 100 }, () => now); + const start = buffer.head('i'); + buffer.append('i', { occurrence: occurrence(1) }); + now = 500; + const second = buffer.append('i', { occurrence: occurrence(2) }); + now = 1001; + const gap = buffer.read('i', start, { maxEvents: 10, select: all }); + expect(gap).toEqual({ events: [], cursor: second, truncated: true, hasMore: true }); + expect(ids(buffer.read('i', gap.cursor, { maxEvents: 10, select: all }).events)).toEqual(['evt_2']); + now = 1501; + expect(buffer.read('i', gap.cursor, { maxEvents: 10, select: all })).toEqual({ + events: [], + cursor: buffer.head('i'), + truncated: true, + hasMore: false + }); + }); + + it.each([ + ['older than the oldest retained event', (buffer: EmitBuffer) => buffer.head('i')], + ['from another EmitBuffer', () => filled(1).head('i')], + ['garbage', () => 'garbage'], + ['ahead of the head', (buffer: EmitBuffer) => buffer.head('i').replace(/\.\d+$/, '.99')] + ])('reads a cursor %s as a gap from the oldest retained position (Review Focus 5)', (_label, cursorOf) => { + const buffer = new EmitBuffer({ maxAgeMs: 60_000, maxEvents: 2 }); + const cursor = cursorOf(buffer); + const positions = [1, 2, 3].map(n => buffer.append('i', { occurrence: occurrence(n) })); + const oldestRetained = positions[1]; + expect(buffer.read('i', cursor, { maxEvents: 10, select: all })).toEqual({ + events: [], + cursor: oldestRetained, + truncated: true, + hasMore: true + }); + }); + + it('starts replay at the maxAgeMs floor and flags the skip', () => { + let now = 0; + const buffer = new EmitBuffer({ maxAgeMs: 60_000, maxEvents: 100 }, () => now); + const start = buffer.head('i'); + buffer.append('i', { occurrence: occurrence(1) }); + now = 10_000; + buffer.append('i', { occurrence: occurrence(2) }); + now = 12_000; + const read = buffer.read('i', start, { maxEvents: 10, maxAgeMs: 5000, select: all }); + expect(ids(read.events)).toEqual(['evt_2']); + expect(read).toMatchObject({ cursor: buffer.head('i'), truncated: true, hasMore: false }); + expect(buffer.read('i', start, { maxEvents: 10, maxAgeMs: 20_000, select: all }).truncated).toBe(false); + }); + + it('clear() drops every event and starts a new epoch', () => { + const buffer = filled(2); + const before = buffer.head('i'); + buffer.clear(); + expect(buffer.sizes()).toEqual({}); + const after = buffer.head('i'); + expect(after).not.toBe(before); + expect(buffer.read('i', before, { maxEvents: 10, select: all })).toEqual({ + events: [], + cursor: after, + truncated: true, + hasMore: false + }); + }); + + it('reports how many events each type holds', () => { + const buffer = filled(3, { maxAgeMs: 60_000, maxEvents: 2 }); + buffer.append('j', { occurrence: { ...occurrence(1), name: 'j' } }); + expect(buffer.sizes()).toEqual({ i: 2, j: 1 }); + }); + + it('formats cursors as e.', () => { + expect(filled(2).head('i')).toMatch(/^e[0-9a-f]{8}\.2$/); + }); +}); diff --git a/packages/server/test/ext/events/poll.test.ts b/packages/server/test/ext/events/poll.test.ts new file mode 100644 index 0000000000..0fd31ad545 --- /dev/null +++ b/packages/server/test/ext/events/poll.test.ts @@ -0,0 +1,540 @@ +import { afterEach, describe, expect, it, vi } from 'vitest'; +import * as z from 'zod/v4'; + +import type { EmitFanOut } from '../../../src/ext/events/extension'; +import type { CheckContext, EventContext, EventsOptions, PollEventsResult } from '../../../src/ext/events/index'; +import { EventsError, EventsExtension } from '../../../src/ext/events/index'; +import type { EventsTestHook } from '../../../src/ext/events/testHook'; +import { errorOf, resultOf, serve } from './harness'; + +const P = z.object({ n: z.number() }); +const tick = () => ({ events: [], cursor: 'h0' }); + +function testHook(events: EventsExtension): EventsTestHook { + return (events as unknown as Record)[Symbol.for('mcp.events.testHook')]!; +} + +// A result without the `_meta` the server adds to every result. +function bodyOf(reply: Parameters[0]): Record { + const { _meta, ...body } = resultOf(reply); + return body; +} + +function poller(events: EventsExtension, options?: Parameters[1]) { + const { rpc } = serve(events, options); + return { + poll: async (params: Record) => resultOf(await rpc('events/poll', params)) as PollEventsResult, + fail: async (params: Record) => errorOf(await rpc('events/poll', params)), + rpc + }; +} + +afterEach(() => { + vi.useRealTimers(); +}); + +describe('events/poll for a check type', () => { + it('bootstraps a check type with cursor null', async () => { + const events = new EventsExtension(); + const check = vi.fn(() => ({ events: [{ data: { n: 1 } }], cursor: 'h1' })); + events.registerEvent('t', { payloadSchema: P, check }); + const { rpc } = poller(events); + expect(bodyOf(await rpc('events/poll', { name: 't', cursor: null }))).toEqual({ + resultType: 'complete', + events: [], + cursor: 'h1', + truncated: false, + hasMore: false, + nextPollMs: 30_000 + }); + expect(check).toHaveBeenCalledOnce(); + expect(check.mock.calls[0]).toEqual([expect.objectContaining({ name: 't', mode: 'poll' }), {}, null]); + }); + + it('treats an absent cursor as null', async () => { + const events = new EventsExtension(); + const check = vi.fn((_ctx: CheckContext, _args: unknown, _cursor: string | null) => ({ events: [], cursor: 'h1' })); + events.registerEvent('t', { payloadSchema: P, check }); + expect(await poller(events).poll({ name: 't' })).toMatchObject({ events: [], cursor: 'h1' }); + expect(check.mock.calls[0]![2]).toBeNull(); + }); + + it('fills name, timestamp and eventId on check events', async () => { + const events = new EventsExtension({ defaultNextPollMs: 1000 }); + events.registerEvent('t', { + payloadSchema: P, + check: () => ({ + events: [ + { data: { n: 1 } }, + { eventId: 'upstream-2', timestamp: '2026-01-01T00:00:00.000Z', data: { n: 2 }, _meta: { k: 1 } } + ], + cursor: 'h2', + nextPollMs: 5000 + }) + }); + const result = await poller(events).poll({ name: 't', cursor: 'h1' }); + const [first, second] = result.events; + expect(first!.eventId).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/); + expect(first).toMatchObject({ name: 't', data: { n: 1 } }); + expect(new Date(first!.timestamp).toISOString()).toBe(first!.timestamp); + expect(first).not.toHaveProperty('cursor'); + expect(second).toEqual({ + eventId: 'upstream-2', + name: 't', + timestamp: '2026-01-01T00:00:00.000Z', + data: { n: 2 }, + _meta: { k: 1 } + }); + expect(result).toMatchObject({ cursor: 'h2', truncated: false, hasMore: false, nextPollMs: 5000 }); + }); + + it('passes hasMore and truncated through from check', async () => { + const events = new EventsExtension(); + events.registerEvent('t', { payloadSchema: P, check: () => ({ events: [], cursor: 'h2', hasMore: true, truncated: true }) }); + expect(await poller(events).poll({ name: 't', cursor: 'h1' })).toMatchObject({ truncated: true, hasMore: true }); + }); + + it('applies the maxAgeMs floor and flags truncated', async () => { + const events = new EventsExtension(); + const old = new Date(Date.now() - 600_000).toISOString(); + events.registerEvent('t', { + payloadSchema: P, + check: () => ({ + events: [ + { eventId: 'old', timestamp: old, data: { n: 1 } }, + { eventId: 'new', data: { n: 2 } } + ], + cursor: 'h2' + }) + }); + const { poll } = poller(events); + const bounded = await poll({ name: 't', cursor: 'h1', maxAgeMs: 300_000 }); + expect(bounded.events.map(event => event.eventId)).toEqual(['new']); + expect(bounded.truncated).toBe(true); + const unbounded = await poll({ name: 't', cursor: 'h1' }); + expect(unbounded.events.map(event => event.eventId)).toEqual(['old', 'new']); + expect(unbounded.truncated).toBe(false); + }); + + it('drops an off-schema check payload and reports it', async () => { + const onerror = vi.fn(); + const events = new EventsExtension({ onerror }); + events.registerEvent('t', { + payloadSchema: P, + check: () => ({ + events: [ + { eventId: 'bad', data: { n: 'x' } as unknown as { n: number } }, + { eventId: 'good', data: { n: 2 } } + ], + cursor: 'h2' + }) + }); + const result = await poller(events).poll({ name: 't', cursor: 'h1' }); + expect(result.events.map(event => event.eventId)).toEqual(['good']); + expect(onerror).toHaveBeenCalledOnce(); + expect(onerror.mock.calls[0]![0]).toBeInstanceOf(Error); + expect(onerror.mock.calls[0]![0].message).toMatch(/^event 't': dropped an event whose data does not match payloadSchema: /); + }); + + it('passes principal and maxEvents in the context', async () => { + const getPrincipal: EventsOptions['getPrincipal'] = ctx => (ctx.http?.authInfo?.extra?.sub as string | undefined) ?? null; + const events = new EventsExtension({ getPrincipal }); + const check = vi.fn<(ctx: CheckContext) => { events: never[]; cursor: string }>(() => ({ events: [], cursor: 'h1' })); + events.registerEvent('t', { payloadSchema: P, check }); + const authInfo = { token: 'tok', clientId: 'client', scopes: [], extra: { sub: 'u1' } }; + const { poll } = poller(events, { authInfo }); + await poll({ name: 't', cursor: 'h0', maxEvents: 25, maxAgeMs: 1000 }); + const ctx = check.mock.calls[0]![0]; + expect(ctx).toMatchObject({ name: 't', principal: 'u1', mode: 'poll', maxEvents: 25, maxAgeMs: 1000 }); + expect(ctx.subscriptionId).toEqual(expect.any(String)); + expect(Object.isFrozen(ctx)).toBe(true); + await poll({ name: 't', cursor: 'h0' }); + expect(check.mock.calls[1]![0]).toMatchObject({ maxEvents: 100 }); + expect(check.mock.calls[1]![0]).not.toHaveProperty('maxAgeMs'); + expect(check.mock.calls[1]![0].subscriptionId).toBe(ctx.subscriptionId); + + const anonymous = new EventsExtension(); + const anonymousCheck = vi.fn<(ctx: CheckContext) => { events: never[]; cursor: string }>(() => ({ events: [], cursor: 'h1' })); + anonymous.registerEvent('t', { payloadSchema: P, check: anonymousCheck }); + await poller(anonymous, { authInfo }).poll({ name: 't', cursor: null }); + expect(anonymousCheck.mock.calls[0]![0].principal).toBeNull(); + }); +}); + +describe('events/poll for an emit-only type', () => { + const Incident = z.object({ severity: z.string(), reporter: z.string().nullable() }); + + it('serves an emit-only type from the buffer with match and transform', async () => { + const events = new EventsExtension(); + const seen: EventContext[] = []; + const handle = events.registerEvent('incident', { + emitOnly: true, + inputSchema: z.object({ severity: z.string().optional(), redact: z.boolean().optional() }), + payloadSchema: Incident, + match: (ctx, event, args) => { + seen.push(ctx); + return args.severity === undefined || event.data.severity === args.severity; + }, + transform: (_ctx, event, args) => (args.redact ? { ...event, data: { ...event.data, reporter: null } } : event) + }); + const { poll } = poller(events); + const args = { severity: 'P1', redact: true }; + const { cursor } = await poll({ name: 'incident', arguments: args, cursor: null }); + await handle.emit({ eventId: 'inc-1', data: { severity: 'P1', reporter: 'ann' } }); + await handle.emit({ eventId: 'inc-3', data: { severity: 'P3', reporter: 'bob' } }); + const result = await poll({ name: 'incident', arguments: args, cursor }); + expect(result.events).toEqual([ + { eventId: 'inc-1', name: 'incident', timestamp: expect.any(String), data: { severity: 'P1', reporter: null } } + ]); + expect(result).toMatchObject({ truncated: false, hasMore: false, nextPollMs: 30_000 }); + expect(seen[0]).toMatchObject({ name: 'incident', mode: 'poll', principal: null }); + + const all = await poll({ name: 'incident', cursor }); + expect(all.events.map(event => [event.eventId, event.data.reporter])).toEqual([ + ['inc-1', 'ann'], + ['inc-3', 'bob'] + ]); + }); + + it('resolves emit() with no subscribers and serves it later (Review Focus 2)', async () => { + const events = new EventsExtension(); + const h = events.registerEvent('i', { emitOnly: true, payloadSchema: P }); + await expect(h.emit({ data: { n: 1 } })).resolves.toBeUndefined(); + const { poll } = poller(events); + const { cursor: c0 } = await poll({ name: 'i', cursor: null }); + await expect(h.emit({ data: { n: 2 } })).resolves.toBeUndefined(); + const result = await poll({ name: 'i', cursor: c0 }); + expect(result.events).toHaveLength(1); + expect(result.events[0]).toMatchObject({ name: 'i', data: { n: 2 } }); + expect(result.events[0]!.eventId).toEqual(expect.any(String)); + }); + + it('reports a gap for a cursor from before a restart (Review Focus 5)', async () => { + const events = new EventsExtension(); + const h = events.registerEvent('i', { emitOnly: true, payloadSchema: P }); + const { poll, rpc } = poller(events); + const { cursor: c0 } = await poll({ name: 'i', cursor: null }); + await h.emit({ data: { n: 1 } }); + await h.emit({ data: { n: 2 } }); + const reply = await rpc('events/poll', { name: 'i', cursor: 'e00000000.5' }); + expect(bodyOf(reply)).toEqual({ + resultType: 'complete', + events: [], + cursor: c0, + truncated: true, + hasMore: true, + nextPollMs: 30_000 + }); + expect((await poll({ name: 'i', cursor: c0 })).events.map(event => event.data)).toEqual([{ n: 1 }, { n: 2 }]); + expect(await poll({ name: 'i', cursor: 'garbage' })).toMatchObject({ events: [], cursor: c0, truncated: true }); + }); + + it('drains with maxEvents and hasMore', async () => { + const events = new EventsExtension(); + const h = events.registerEvent('i', { emitOnly: true, payloadSchema: P }); + const { poll } = poller(events); + const { cursor } = await poll({ name: 'i', cursor: null }); + for (let n = 1; n <= 3; n++) await h.emit({ data: { n } }); + const first = await poll({ name: 'i', cursor, maxEvents: 2 }); + expect(first.events.map(event => event.data)).toEqual([{ n: 1 }, { n: 2 }]); + expect(first.hasMore).toBe(true); + const second = await poll({ name: 'i', cursor: first.cursor, maxEvents: 2 }); + expect(second.events.map(event => event.data)).toEqual([{ n: 3 }]); + expect(second.hasMore).toBe(false); + }); + + it('delivers a targeted emit only to its subscription', async () => { + const events = new EventsExtension(); + const ids = new Map(); + const h = events.registerEvent('i', { + emitOnly: true, + inputSchema: z.object({ who: z.string() }), + payloadSchema: P, + onSubscribe: (ctx, args) => { + ids.set(args.who, ctx.subscriptionId); + } + }); + const { poll } = poller(events); + const a = await poll({ name: 'i', arguments: { who: 'a' }, cursor: null }); + const b = await poll({ name: 'i', arguments: { who: 'b' }, cursor: null }); + await h.emit({ data: { n: 1 } }, { subscriptionId: ids.get('b')! }); + await h.emit({ data: { n: 2 } }); + expect((await poll({ name: 'i', arguments: { who: 'a' }, cursor: a.cursor })).events.map(event => event.data)).toEqual([{ n: 2 }]); + expect((await poll({ name: 'i', arguments: { who: 'b' }, cursor: b.cursor })).events.map(event => event.data)).toEqual([ + { n: 1 }, + { n: 2 } + ]); + }); + + it('drops an off-schema emit and reports it', async () => { + const onerror = vi.fn(); + const events = new EventsExtension({ onerror }); + const h = events.registerEvent('i', { emitOnly: true, payloadSchema: P }); + const { poll } = poller(events); + const { cursor } = await poll({ name: 'i', cursor: null }); + await expect(h.emit({ data: { n: 'x' } as unknown as { n: number } })).resolves.toBeUndefined(); + expect(onerror).toHaveBeenCalledOnce(); + expect(onerror.mock.calls[0]![0].message).toMatch(/^event 'i': dropped an event whose data does not match payloadSchema: /); + expect(await poll({ name: 'i', cursor })).toMatchObject({ events: [], cursor }); + }); + + it('skips an event whose match throws and reports it', async () => { + const onerror = vi.fn(); + const events = new EventsExtension({ onerror }); + const h = events.registerEvent('i', { + emitOnly: true, + payloadSchema: P, + match: (_ctx, event) => { + if (event.data.n === 1) throw new Error('match failed'); + return true; + } + }); + const { poll } = poller(events); + const { cursor } = await poll({ name: 'i', cursor: null }); + await h.emit({ data: { n: 1 } }); + await h.emit({ data: { n: 2 } }); + expect((await poll({ name: 'i', cursor })).events.map(event => event.data)).toEqual([{ n: 2 }]); + expect(onerror).toHaveBeenCalledWith(expect.objectContaining({ message: 'match failed' })); + }); + + it('hands each emit to the fan-out with its positions and reports a failing one', async () => { + const onerror = vi.fn(); + const events = new EventsExtension({ onerror }); + const fanOut = vi.fn(async () => {}); + testHook(events).addFanOut(fanOut); + testHook(events).addFanOut(async () => { + throw new Error('push failed'); + }); + const h = events.registerEvent('i', { emitOnly: true, payloadSchema: P }); + const { cursor: c0 } = await poller(events).poll({ name: 'i', cursor: null }); + await expect(h.emit({ eventId: 'x', data: { n: 1 } }, { subscriptionId: 'sub-1' })).resolves.toBeUndefined(); + expect(fanOut).toHaveBeenCalledOnce(); + const [name, buffered, positions] = fanOut.mock.calls[0]!; + expect(name).toBe('i'); + expect(buffered).toEqual({ occurrence: expect.objectContaining({ eventId: 'x', name: 'i', data: { n: 1 } }), target: 'sub-1' }); + expect(positions.previous).toBe(c0); + expect(positions.cursor).not.toBe(c0); + expect(onerror).toHaveBeenCalledWith(expect.objectContaining({ message: 'push failed' })); + }); + + it('rejects emit() on a handle whose registration was removed', async () => { + const events = new EventsExtension(); + const h = events.registerEvent('i', { emitOnly: true, payloadSchema: P }); + h.remove(); + await expect(h.emit({ data: { n: 1 } })).rejects.toThrow("event 'i': this handle's registration was removed or replaced"); + expect(testHook(events).state().emitBuffer).toEqual({}); + }); +}); + +describe('events/poll errors', () => { + it('answers -32601 to a legacy poll', async () => { + const events = new EventsExtension(); + events.registerEvent('t', { payloadSchema: P, check: tick }); + const reply = await serve(events).rpc('events/poll', { name: 't', cursor: null }, { era: 'legacy' }); + expect(errorOf(reply)).toMatchObject({ code: -32_601, message: 'Method not found' }); + }); + + it('maps errors to SEP codes', async () => { + const onSubscribe = vi.fn(); + const events = new EventsExtension({ maxSubscriptions: 1 }); + events.registerEvent('t', { inputSchema: z.object({ a: z.number().optional() }), payloadSchema: P, check: tick, onSubscribe }); + events.registerEvent('push-only', { payloadSchema: P, check: tick, delivery: { poll: false } }); + const { fail, poll } = poller(events); + expect(await fail({ name: 'missing' })).toMatchObject({ code: -32_023, data: { kind: 'event' } }); + expect(await fail({ name: 't', arguments: { a: 'x' } })).toMatchObject({ code: -32_602 }); + expect(await fail({ name: 'push-only' })).toMatchObject({ code: -32_026, data: { feature: 'deliveryMode', value: 'poll' } }); + await poll({ name: 't', arguments: { a: 1 } }); + expect(await fail({ name: 't', arguments: { a: 2 } })).toMatchObject({ code: -32_025, data: { limit: 'subscriptions' } }); + expect(onSubscribe).toHaveBeenCalledOnce(); + await poll({ name: 't', arguments: { a: 1 } }); + }); + + it('answers -32023 after remove()', async () => { + const events = new EventsExtension(); + const handle = events.registerEvent('t', { payloadSchema: P, check: tick }); + const { fail, poll } = poller(events); + await poll({ name: 't' }); + handle.remove(); + expect(await fail({ name: 't' })).toMatchObject({ code: -32_023, data: { kind: 'event' } }); + }); + + it('refuses the subscription when onSubscribe throws and keeps no lease', async () => { + const onSubscribe = vi + .fn() + .mockImplementationOnce(() => { + throw new EventsError('forbidden', 'Forbidden', { reason: 'sync' }); + }) + .mockRejectedValueOnce(new EventsError('forbidden', 'Forbidden', { reason: 'async' })); + const events = new EventsExtension(); + events.registerEvent('t', { payloadSchema: P, check: tick, onSubscribe }); + const { fail, poll } = poller(events); + expect(await fail({ name: 't' })).toMatchObject({ code: -32_024, data: { reason: 'sync' } }); + expect(await fail({ name: 't' })).toMatchObject({ code: -32_024, data: { reason: 'async' } }); + await poll({ name: 't' }); + expect(onSubscribe).toHaveBeenCalledTimes(3); + }); +}); + +describe('poll leases', () => { + it('keeps one lease for the same arguments in any key order (Review Focus 4)', async () => { + const onSubscribe = vi.fn(); + const events = new EventsExtension(); + events.registerEvent('t', { payloadSchema: P, check: tick, onSubscribe }); + const { poll } = poller(events); + await poll({ name: 't', arguments: { a: 1, b: 2 } }); + await poll({ name: 't', arguments: { b: 2, a: 1 } }); + expect(onSubscribe).toHaveBeenCalledOnce(); + expect(onSubscribe.mock.calls[0]![0]).toMatchObject({ name: 't', mode: 'poll', principal: null }); + expect(onSubscribe.mock.calls[0]![1]).toEqual({ a: 1, b: 2 }); + await poll({ name: 't', arguments: { a: 1 } }); + expect(onSubscribe).toHaveBeenCalledTimes(2); + }); + + it('keys leases by principal', async () => { + const onSubscribe = vi.fn(); + const events = new EventsExtension({ getPrincipal: ctx => (ctx.http?.authInfo?.extra?.sub as string | undefined) ?? null }); + events.registerEvent('t', { payloadSchema: P, check: tick, onSubscribe }); + const as = (sub: string) => poller(events, { authInfo: { token: 'tok', clientId: 'client', scopes: [], extra: { sub } } }); + await as('u1').poll({ name: 't' }); + await as('u1').poll({ name: 't' }); + await as('u2').poll({ name: 't' }); + expect(onSubscribe.mock.calls.map(([ctx]) => (ctx as EventContext).principal)).toEqual(['u1', 'u2']); + }); + + it('runs onSubscribe once for concurrent first polls of one lease', async () => { + let release!: () => void; + const onSubscribe = vi.fn(() => new Promise(resolve => (release = resolve))); + const check = vi.fn(tick); + const events = new EventsExtension(); + events.registerEvent('t', { payloadSchema: P, check, onSubscribe }); + const { poll } = poller(events); + const first = poll({ name: 't', cursor: 'h0' }); + const second = poll({ name: 't', cursor: 'h0' }); + await vi.waitFor(() => expect(onSubscribe).toHaveBeenCalledOnce()); + expect(check).not.toHaveBeenCalled(); + release(); + await expect(Promise.all([first, second])).resolves.toHaveLength(2); + expect(onSubscribe).toHaveBeenCalledOnce(); + expect(check).toHaveBeenCalledTimes(2); + }); + + it('expires a lease and calls onUnsubscribe', async () => { + vi.useFakeTimers(); + const onSubscribe = vi.fn(); + const onUnsubscribe = vi.fn(); + const events = new EventsExtension({ pollSubscriptionTtlMs: 300_000 }); + events.registerEvent('t', { payloadSchema: P, check: tick, onSubscribe, onUnsubscribe }); + const { poll } = poller(events); + await poll({ name: 't', arguments: { a: 1 } }); + const subscribed = onSubscribe.mock.calls[0]![0] as EventContext; + await vi.advanceTimersByTimeAsync(299_999); + expect(onUnsubscribe).not.toHaveBeenCalled(); + expect(subscribed.signal.aborted).toBe(false); + await vi.advanceTimersByTimeAsync(2); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + const [ctx, args] = onUnsubscribe.mock.calls[0]! as [EventContext, unknown]; + expect(ctx).toMatchObject({ name: 't', mode: 'poll', principal: null, subscriptionId: subscribed.subscriptionId }); + expect(ctx.signal.aborted).toBe(true); + expect(subscribed.signal.aborted).toBe(true); + expect(args).toEqual({ a: 1 }); + }); + + it('renews a lease on every poll', async () => { + vi.useFakeTimers(); + const onUnsubscribe = vi.fn(); + const events = new EventsExtension({ pollSubscriptionTtlMs: 300_000 }); + events.registerEvent('t', { payloadSchema: P, check: tick, onUnsubscribe }); + const { poll } = poller(events); + await poll({ name: 't' }); + await vi.advanceTimersByTimeAsync(200_000); + await poll({ name: 't' }); + await vi.advanceTimersByTimeAsync(200_000); + expect(onUnsubscribe).not.toHaveBeenCalled(); + await vi.advanceTimersByTimeAsync(100_001); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + }); + + it('reports a failing onUnsubscribe on expiry', async () => { + vi.useFakeTimers(); + const onerror = vi.fn(); + const events = new EventsExtension({ onerror, pollSubscriptionTtlMs: 1000 }); + events.registerEvent('t', { + payloadSchema: P, + check: tick, + onUnsubscribe: () => { + throw new Error('teardown failed'); + } + }); + await poller(events).poll({ name: 't' }); + await vi.advanceTimersByTimeAsync(1001); + expect(onerror).toHaveBeenCalledWith(expect.objectContaining({ message: 'teardown failed' })); + }); + + it('delivers a termination on the next poll', async () => { + const onSubscribe = vi.fn(); + const onUnsubscribe = vi.fn(); + const events = new EventsExtension(); + const handle = events.registerEvent('t', { payloadSchema: P, check: tick, onSubscribe, onUnsubscribe }); + const { fail, poll } = poller(events); + await poll({ name: 't' }); + await handle.terminate(new EventsError('forbidden', 'Forbidden', { reason: 'Access revoked' })); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + expect((onUnsubscribe.mock.calls[0]![0] as EventContext).signal.aborted).toBe(true); + expect(await fail({ name: 't' })).toEqual({ code: -32_024, message: 'Forbidden', data: { reason: 'Access revoked' } }); + await poll({ name: 't' }); + expect(onSubscribe).toHaveBeenCalledTimes(2); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + }); + + it('terminates only the lease with the given subscriptionId', async () => { + const ids = new Map(); + const events = new EventsExtension(); + const handle = events.registerEvent('t', { + inputSchema: z.object({ a: z.number() }), + payloadSchema: P, + check: tick, + onSubscribe: (ctx, args) => { + ids.set(args.a, ctx.subscriptionId); + } + }); + const { fail, poll } = poller(events); + await poll({ name: 't', arguments: { a: 1 } }); + await poll({ name: 't', arguments: { a: 2 } }); + await handle.terminate(new EventsError('forbidden', 'Forbidden'), { subscriptionId: ids.get(2)! }); + await poll({ name: 't', arguments: { a: 1 } }); + expect(await fail({ name: 't', arguments: { a: 2 } })).toMatchObject({ code: -32_024 }); + }); + + it('answers a schema change with -32026 even when the old arguments no longer parse (D18)', async () => { + const events = new EventsExtension(); + events.registerEvent('t', { inputSchema: z.object({ a: z.number() }), payloadSchema: P, check: tick }); + const { fail, poll } = poller(events); + await poll({ name: 't', arguments: { a: 1 } }); + events.registerEvent('t', { inputSchema: z.object({ b: z.string() }), payloadSchema: P, check: tick }); + expect(await fail({ name: 't', arguments: { a: 1 } })).toMatchObject({ + code: -32_026, + data: { feature: 'inputSchema', reason: 'schema_changed' } + }); + expect(await fail({ name: 't', arguments: { a: 1 } })).toMatchObject({ code: -32_602 }); + }); +}); + +describe('test hook', () => { + it('reports the emit buffer and poll leases, and restart() clears both', async () => { + const onSubscribe = vi.fn(); + const events = new EventsExtension(); + const h = events.registerEvent('i', { emitOnly: true, payloadSchema: P, onSubscribe }); + const hook = testHook(events); + const { poll } = poller(events); + const { cursor: c0 } = await poll({ name: 'i', cursor: null }); + await h.emit({ data: { n: 1 } }); + expect(hook.state()).toEqual({ trustedOrigins: [], emitBuffer: { i: 1 }, pollLeases: 1 }); + + hook.restart(); + expect(hook.state()).toEqual({ trustedOrigins: [], emitBuffer: {}, pollLeases: 0 }); + const after = await poll({ name: 'i', cursor: c0 }); + expect(after).toMatchObject({ events: [], truncated: true, hasMore: false }); + expect(after.cursor).not.toBe(c0); + expect(onSubscribe).toHaveBeenCalledTimes(2); + }); +}); From ba9d89829233a8b1dabb3bb6dc2ce7d12e83250b Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 11:53:11 +0200 Subject: [PATCH 05/37] feat(server): events/stream push delivery, streamed in every HTTP response mode --- packages/server/src/ext/events/extension.ts | 34 +- packages/server/src/ext/events/poll.ts | 94 ++-- packages/server/src/ext/events/push.ts | 328 +++++++++++ packages/server/src/ext/events/testHook.ts | 2 + .../server/src/server/createMcpHandler.ts | 12 +- .../server/src/server/streamingMethods.ts | 15 + packages/server/test/ext/events/harness.ts | 8 +- packages/server/test/ext/events/poll.test.ts | 4 +- packages/server/test/ext/events/push.test.ts | 528 ++++++++++++++++++ 9 files changed, 971 insertions(+), 54 deletions(-) create mode 100644 packages/server/src/ext/events/push.ts create mode 100644 packages/server/src/server/streamingMethods.ts create mode 100644 packages/server/test/ext/events/push.test.ts diff --git a/packages/server/src/ext/events/extension.ts b/packages/server/src/ext/events/extension.ts index edb4f31099..4a5ea5167c 100644 --- a/packages/server/src/ext/events/extension.ts +++ b/packages/server/src/ext/events/extension.ts @@ -7,7 +7,8 @@ import { EVENTS_SUBSCRIBE_METHOD, EVENTS_UNSUBSCRIBE_METHOD, ListEventsRequestParamsSchema, - PollEventsRequestParamsSchema + PollEventsRequestParamsSchema, + StreamEventsRequestParamsSchema } from '@modelcontextprotocol/core/ext/events'; import type { ServerContext, StandardSchemaWithJSON } from '@modelcontextprotocol/core-internal'; import { scanXMcpHeaderDeclarations } from '@modelcontextprotocol/core-internal'; @@ -15,10 +16,12 @@ import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; import type { McpServer } from '../../server/mcp'; import { markModernOnlyExtension } from '../../server/modernOnlyExtensions'; +import { markStreamingMethod } from '../../server/streamingMethods'; import type { BufferedEvent } from './emitBuffer'; import { EmitBuffer } from './emitBuffer'; import { assertModernRequest } from './eraGate'; import { PollSource, toOccurrence } from './poll'; +import { StreamSet } from './push'; import type { AnyEventDefinition, RegisteredEvent } from './registry'; import { changedSchema, deliveryModes, EventRegistry } from './registry'; import { installTestHook } from './testHook'; @@ -50,6 +53,8 @@ const DEFAULT_EMIT_BUFFER_MAX_AGE_MS = 600_000; const DEFAULT_EMIT_BUFFER_MAX_EVENTS = 10_000; const DEFAULT_POLL_SUBSCRIPTION_TTL_MS = 300_000; const DEFAULT_NEXT_POLL_MS = 30_000; +const DEFAULT_HEARTBEAT_MS = 30_000; +const DEFAULT_CHECK_INTERVAL_MS = 5000; // Servers with an events extension attached: one per server, as SEP-3371 rejects a duplicate extension identifier. const eventsServers = new WeakSet(); @@ -120,6 +125,7 @@ export class EventsExtension { readonly #buffer: EmitBuffer; readonly #validator: SubscriptionValidator; readonly #poll: PollSource; + readonly #push: StreamSet; // Each emitted event is handed to these after it is buffered; push and webhook delivery add theirs. readonly #fanOuts: EmitFanOut[] = []; // Clears process-memory state on a simulated restart; each delivery mode adds its own. @@ -145,7 +151,7 @@ export class EventsExtension { webhookEnabled: this.#webhookEnabled, getPrincipal: options.getPrincipal, maxSubscriptions: options.maxSubscriptions, - subscriptionCount: () => this.#poll.size + subscriptionCount: () => this.#poll.size + this.#push.size }); this.#poll = new PollSource({ validator: this.#validator, @@ -154,10 +160,19 @@ export class EventsExtension { defaultNextPollMs: options.defaultNextPollMs ?? DEFAULT_NEXT_POLL_MS, report: error => this.#report(error) }); - this.#sources.push(this.#poll); + this.#push = new StreamSet({ + validator: this.#validator, + buffer: this.#buffer, + heartbeatMs: options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS, + checkIntervalMs: options.checkIntervalMs ?? DEFAULT_CHECK_INTERVAL_MS, + report: error => this.#report(error) + }); + this.#sources.push(this.#poll, this.#push); + this.#fanOuts.push((name, buffered, { cursor }) => this.#push.fanOut(name, buffered, cursor)); this.#restarts.push( () => this.#buffer.clear(), - () => this.#poll.clear() + () => this.#poll.clear(), + () => this.#push.closeAll() ); installTestHook(this, { generation: () => this.#generation, @@ -165,7 +180,12 @@ export class EventsExtension { this.#generation += 1; for (const clear of this.#restarts) clear(); }, - state: () => ({ trustedOrigins: [...this.#trustedOrigins], emitBuffer: this.#buffer.sizes(), pollLeases: this.#poll.size }), + state: () => ({ + trustedOrigins: [...this.#trustedOrigins], + emitBuffer: this.#buffer.sizes(), + pollLeases: this.#poll.size, + pushStreams: this.#push.size + }), addTrustedOrigin: origin => { assertOrigin(origin); this.#trustedOrigins.add(origin); @@ -204,8 +224,12 @@ export class EventsExtension { server.setRequestHandler(EVENTS_POLL_METHOD, { params: PollEventsRequestParamsSchema }, (params, ctx) => this.#poll.handlePoll(params, ctx) ); + server.setRequestHandler(EVENTS_STREAM_METHOD, { params: StreamEventsRequestParamsSchema }, (params, ctx) => + this.#push.open(params, ctx) + ); server.registerCapabilities({ extensions: { [EVENTS_EXTENSION_ID]: {} } }); markModernOnlyExtension(server, EVENTS_EXTENSION_ID); + markStreamingMethod(server, EVENTS_STREAM_METHOD); this.#attached.add(mcp); eventsServers.add(mcp); } diff --git a/packages/server/src/ext/events/poll.ts b/packages/server/src/ext/events/poll.ts index 0d87c2b810..03b09d569f 100644 --- a/packages/server/src/ext/events/poll.ts +++ b/packages/server/src/ext/events/poll.ts @@ -8,7 +8,7 @@ import type { SubscriptionSource } from './extension'; import type { Lease } from './leases'; import { leaseKey, LeaseTable } from './leases'; import type { RegisteredEvent } from './registry'; -import type { EventContext, EventInput } from './types'; +import type { EventContext, EventInput, EventResult } from './types'; import type { SubscriptionValidator } from './validation'; const DEFAULT_MAX_EVENTS = 100; @@ -48,6 +48,56 @@ export async function toOccurrence( }; } +// A check result's events to send: off-schema ones dropped (reported), ones older than `maxAgeMs` skipped with `truncated`. +export async function checkedEvents( + entry: RegisteredEvent, + result: EventResult, + maxAgeMs: number | undefined, + report: (error: unknown) => void +): Promise<{ events: EventOccurrence[]; truncated: boolean }> { + const floor = maxAgeMs === undefined ? undefined : Date.now() - maxAgeMs; + let truncated = result.truncated === true; + const events: EventOccurrence[] = []; + for (const input of result.events) { + const occurrence = await toOccurrence(entry, input, report); + if (occurrence === undefined) continue; + if (floor !== undefined && Date.parse(occurrence.timestamp) < floor) { + truncated = true; + continue; + } + events.push(occurrence); + } + return { events, truncated }; +} + +// What one subscription receives of an emitted event: broadcasts pass `match`, targeted ones reach only their subscription. A throwing hook skips the event. +export function selectEvent( + entry: RegisteredEvent, + ctx: EventContext, + args: Record, + buffered: BufferedEvent, + report: (error: unknown) => void +): EventOccurrence | undefined { + const { occurrence, target } = buffered; + if (target !== undefined && target !== ctx.subscriptionId) return undefined; + const { match, transform } = entry.definition; + try { + if (target === undefined && match !== undefined && !match(ctx, occurrence, args)) return undefined; + if (transform === undefined) return occurrence; + const shaped = transform(ctx, occurrence, args); + return { + eventId: shaped.eventId ?? occurrence.eventId, + name: occurrence.name, + timestamp: shaped.timestamp ?? occurrence.timestamp, + data: shaped.data as Record, + ...(shaped._meta === undefined ? {} : { _meta: shaped._meta }) + }; + } catch (error) { + report(error); + return undefined; + } +} + // `events/poll`: every request carries one subscription, and leases drive `onSubscribe` / `onUnsubscribe` (SEP-3415 Appendix A). export class PollSource implements SubscriptionSource { readonly #deps: PollDeps; @@ -88,7 +138,7 @@ export class PollSource implements SubscriptionSource { const read = this.#deps.buffer.read(entry.name, cursor, { maxEvents, maxAgeMs: params.maxAgeMs, - select: buffered => this.#select(entry, selectCtx, args, buffered) + select: buffered => selectEvent(entry, selectCtx, args, buffered, this.#deps.report) }); return { ...read, nextPollMs: this.#deps.defaultNextPollMs }; } @@ -96,18 +146,7 @@ export class PollSource implements SubscriptionSource { const result = await check(makeContext({ ...fields, maxEvents, maxAgeMs: params.maxAgeMs }), args, cursor); const nextPollMs = result.nextPollMs ?? this.#deps.defaultNextPollMs; if (cursor === null) return { events: [], cursor: result.cursor, truncated: false, hasMore: false, nextPollMs }; - const floor = params.maxAgeMs === undefined ? undefined : Date.now() - params.maxAgeMs; - let truncated = result.truncated === true; - const events: EventOccurrence[] = []; - for (const input of result.events) { - const occurrence = await toOccurrence(entry, input, this.#deps.report); - if (occurrence === undefined) continue; - if (floor !== undefined && Date.parse(occurrence.timestamp) < floor) { - truncated = true; - continue; - } - events.push(occurrence); - } + const { events, truncated } = await checkedEvents(entry, result, params.maxAgeMs, this.#deps.report); return { events, cursor: result.cursor, truncated, hasMore: result.hasMore === true, nextPollMs }; } @@ -172,33 +211,6 @@ export class PollSource implements SubscriptionSource { return lease; } - // Broadcast events pass `match`; targeted ones reach only their subscription. A throwing hook skips the event. - #select( - entry: RegisteredEvent, - ctx: EventContext, - args: Record, - buffered: BufferedEvent - ): EventOccurrence | undefined { - const { occurrence, target } = buffered; - if (target !== undefined && target !== ctx.subscriptionId) return undefined; - const { match, transform } = entry.definition; - try { - if (target === undefined && match !== undefined && !match(ctx, occurrence, args)) return undefined; - if (transform === undefined) return occurrence; - const shaped = transform(ctx, occurrence, args); - return { - eventId: shaped.eventId ?? occurrence.eventId, - name: occurrence.name, - timestamp: shaped.timestamp ?? occurrence.timestamp, - data: shaped.data as Record, - ...(shaped._meta === undefined ? {} : { _meta: shaped._meta }) - }; - } catch (error) { - this.#deps.report(error); - return undefined; - } - } - async #unsubscribe(lease: PollLease): Promise { const { name, subscriptionId, principal, args, entry, ended } = lease; ended.abort(); diff --git a/packages/server/src/ext/events/push.ts b/packages/server/src/ext/events/push.ts new file mode 100644 index 0000000000..8c0f807e7a --- /dev/null +++ b/packages/server/src/ext/events/push.ts @@ -0,0 +1,328 @@ +import type { + EventOccurrence, + EventsErrorObject, + StreamEventsRequestParams, + StreamEventsResult +} from '@modelcontextprotocol/core/ext/events'; +import { + EVENTS_ACTIVE_NOTIFICATION, + EVENTS_ERROR_NOTIFICATION, + EVENTS_EVENT_NOTIFICATION, + EVENTS_HEARTBEAT_NOTIFICATION, + EVENTS_TERMINATED_NOTIFICATION +} from '@modelcontextprotocol/core/ext/events'; +import type { RequestId, ServerContext } from '@modelcontextprotocol/core-internal'; +import { ProtocolErrorCode, SUBSCRIPTION_ID_META_KEY } from '@modelcontextprotocol/core-internal'; +import type { EventsErrorKind } from '@modelcontextprotocol/core-internal/ext/events'; +import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; + +import { makeContext } from './context'; +import type { BufferedEvent, EmitBuffer } from './emitBuffer'; +import type { SubscriptionSource } from './extension'; +import { checkedEvents, selectEvent } from './poll'; +import type { RegisteredEvent } from './registry'; +import type { CheckContext, EventResult } from './types'; +import type { SubscriptionValidator } from './validation'; + +// The shortest heartbeat granted, whatever the client suggests (D33). +const HEARTBEAT_FLOOR_MS = 5000; + +// A check that throws one of these ends its streams; any other error is sent on the stream and the loop goes on. +const TERMINAL_KINDS: ReadonlySet = new Set(['forbidden', 'notFound', 'unsupported']); + +export interface PushDeps { + readonly validator: SubscriptionValidator; + readonly buffer: EmitBuffer; + // The grant when the client suggests none, and the longest granted. + readonly heartbeatMs: number; + readonly checkIntervalMs: number; + report(error: unknown): void; +} + +interface PushStream { + readonly entry: RegisteredEvent; + readonly args: Record; + readonly requestId: RequestId; + readonly grant: number; + readonly notify: ServerContext['mcpReq']['notify']; + // Aborts when the stream ends; the `signal` of every callback's ctx. + readonly ended: AbortController; + readonly ctx: CheckContext; + // Resolves once the stream has ended and its last message is written. + readonly done: Promise; + finish(): void; + // From the first `active` on; until then an end is only recorded, and `open` acts on it. + live: boolean; + stopped?: { error?: EventsError }; + // The position checked up to, which a heartbeat carries. + position: string | null; + // Notifications in the order they were sent. + queue: Promise; + heartbeat?: ReturnType; + checkTimer?: ReturnType; +} + +// What a stream sends next: `active` at `cursor` when one is due, then `events`, after which it is at `position`. +interface Batch { + readonly cursor: string | null; + readonly truncated: boolean; + readonly events: readonly EventOccurrence[]; + readonly position: string | null; +} + +// Timers never keep the process alive on their own. +function unref(timer: ReturnType): ReturnType { + (timer as { unref?: () => void }).unref?.(); + return timer; +} + +// The `error` of `notifications/events/{error,terminated}`: an `EventsError` as it is, anything else as -32603. +function errorObject(error: unknown): EventsErrorObject { + if (error instanceof EventsError) { + return { + code: error.code, + message: error.message, + ...(error.data === undefined ? {} : { data: error.data as Record }) + }; + } + return { code: ProtocolErrorCode.InternalError, message: error instanceof Error ? error.message : String(error) }; +} + +// `events/stream`: one long-lived request per subscription, answered with `notifications/events/*` until it ends (SEP-3415 §Push). +export class StreamSet implements SubscriptionSource { + readonly #deps: PushDeps; + readonly #streams = new Set(); + + constructor(deps: PushDeps) { + this.#deps = deps; + } + + get size(): number { + return this.#streams.size; + } + + async open(params: StreamEventsRequestParams, ctx: ServerContext): Promise { + const { entry, principal, args } = await this.#deps.validator.validate('push', params, ctx); + this.#deps.validator.assertCapacity(); + const stream = this.#create(entry, principal, args, params, ctx); + const result = { _meta: { [SUBSCRIPTION_ID_META_KEY]: ctx.mcpReq.id } }; + try { + await entry.definition.onSubscribe?.(stream.ctx, args); + } catch (error) { + this.#streams.delete(stream); + stream.ended.abort(); + throw error; + } + let checked: Batch | undefined; + try { + if (entry.kind === 'check' && stream.stopped === undefined) checked = await this.#checkStart(stream, params); + } catch (error) { + await this.#abandon(stream); + throw error; + } + // Ended before `active`: no stream opened, so a termination answers as the request's error. + if (stream.stopped !== undefined) { + await this.#abandon(stream); + if (stream.stopped.error !== undefined) throw stream.stopped.error; + return result; + } + // Synchronous from the replay read to going live, so no emit falls between them. + stream.live = true; + this.#send(stream, checked ?? this.#replay(stream, params), true); + this.#scheduleCheck(stream); + await stream.done; + return result; + } + + // Delivers an emitted event to every live stream of its type; it only queues writes. + fanOut(name: string, buffered: BufferedEvent, cursor: string): void { + for (const stream of this.#streams) { + if (!stream.live || stream.entry.name !== name) continue; + stream.position = cursor; + const occurrence = selectEvent(stream.entry, stream.ctx, stream.args, buffered, this.#deps.report); + if (occurrence !== undefined) this.#write(stream, EVENTS_EVENT_NOTIFICATION, { ...occurrence, cursor }); + } + } + + // Sends `terminated` on each matching stream, runs onUnsubscribe, and ends the request with its final result. + async terminate(name: string, error: EventsError, subscriptionId?: string): Promise { + const ending: Promise[] = []; + for (const stream of this.#streams) { + if (stream.entry.name !== name || (subscriptionId !== undefined && stream.ctx.subscriptionId !== subscriptionId)) continue; + ending.push(this.#end(stream, error)); + } + await Promise.all(ending); + } + + // Ends every stream with its final result and runs onUnsubscribe, for a simulated restart. + closeAll(): void { + for (const stream of this.#streams) void this.#end(stream); + } + + #create( + entry: RegisteredEvent, + principal: string | null, + args: Record, + params: StreamEventsRequestParams, + ctx: ServerContext + ): PushStream { + let finish!: () => void; + const done = new Promise(resolve => (finish = resolve)); + const ended = new AbortController(); + const max = this.#deps.heartbeatMs; + const stream: PushStream = { + entry, + args, + requestId: ctx.mcpReq.id, + grant: Math.min(Math.max(params.heartbeatMs ?? max, HEARTBEAT_FLOOR_MS), max), + notify: ctx.mcpReq.notify, + ended, + ctx: makeContext({ + name: entry.name, + subscriptionId: globalThis.crypto.randomUUID(), + principal, + mode: 'push', + signal: ended.signal + }), + done, + finish, + live: false, + position: null, + queue: Promise.resolve() + }; + this.#streams.add(stream); + // The client went away: an HTTP abort or `notifications/cancelled`. + const { signal } = ctx.mcpReq; + signal.addEventListener('abort', () => void this.#end(stream), { once: true }); + if (signal.aborted) void this.#end(stream); + return stream; + } + + // Where a check type starts: `null` takes the current cursor, a cursor replays the events since it first. + async #checkStart(stream: PushStream, params: StreamEventsRequestParams): Promise { + const check = stream.entry.definition.check!; + const from = params.cursor ?? null; + if (from === null) { + const { cursor } = await check(stream.ctx, stream.args, null); + return { cursor, truncated: false, events: [], position: cursor }; + } + const result = await check(makeContext({ ...stream.ctx, maxAgeMs: params.maxAgeMs }), stream.args, from); + return this.#batch(stream, from, result, params.maxAgeMs); + } + + // A check batch's cursors stay at `from` until its last event, so no cursor runs ahead of an event still to be sent. + async #batch(stream: PushStream, from: string | null, result: EventResult, maxAgeMs?: number): Promise { + const { events, truncated } = await checkedEvents(stream.entry, result, maxAgeMs, this.#deps.report); + const last = events.length - 1; + return { + cursor: last === -1 ? result.cursor : from, + truncated, + events: events.map((occurrence, index) => ({ ...occurrence, cursor: index === last ? result.cursor : from })), + position: result.cursor + }; + } + + // Where an emit-only type starts: `null` is the buffer head, a cursor replays the buffer since it, each event at its own position. + #replay(stream: PushStream, params: StreamEventsRequestParams): Batch { + const { buffer, report } = this.#deps; + const { name } = stream.entry; + const from = params.cursor ?? null; + if (from === null) { + const head = buffer.head(name); + return { cursor: head, truncated: false, events: [], position: head }; + } + const select = (buffered: BufferedEvent) => selectEvent(stream.entry, stream.ctx, stream.args, buffered, report); + // `maxEvents: 0` finds where replay starts (after a gap or the `maxAgeMs` floor) without reading an event. + const start = buffer.read(name, from, { maxEvents: 0, maxAgeMs: params.maxAgeMs, select }); + const events: EventOccurrence[] = []; + let { cursor: position, hasMore } = start; + while (hasMore) { + const read = buffer.read(name, position, { maxEvents: 1, select }); + for (const occurrence of read.events) events.push({ ...occurrence, cursor: read.cursor }); + ({ cursor: position, hasMore } = read); + } + return { cursor: events.length === 0 ? position : start.cursor, truncated: start.truncated, events, position }; + } + + #send(stream: PushStream, batch: Batch, active: boolean): void { + if (active) { + this.#write(stream, EVENTS_ACTIVE_NOTIFICATION, { + cursor: batch.cursor, + truncated: batch.truncated, + heartbeatMs: stream.grant + }); + } + for (const event of batch.events) this.#write(stream, EVENTS_EVENT_NOTIFICATION, event); + stream.position = batch.position; + } + + #scheduleCheck(stream: PushStream): void { + if (!stream.live || stream.entry.kind !== 'check') return; + stream.checkTimer = unref(setTimeout(() => void this.#check(stream), this.#deps.checkIntervalMs)); + } + + async #check(stream: PushStream): Promise { + const from = stream.position; + try { + const result = await stream.entry.definition.check!(stream.ctx, stream.args, from); + const batch = await this.#batch(stream, from, result); + if (!stream.live) return; + this.#send(stream, batch, batch.truncated); + } catch (error) { + if (!stream.live) return; + if (error instanceof EventsError && TERMINAL_KINDS.has(error.kind)) { + void this.#end(stream, error); + return; + } + this.#write(stream, EVENTS_ERROR_NOTIFICATION, { error: errorObject(error) }); + } + this.#scheduleCheck(stream); + } + + #write(stream: PushStream, method: string, params: Record): void { + const notification = { method, params: { ...params, _meta: { [SUBSCRIPTION_ID_META_KEY]: stream.requestId } } }; + // A failed write means the client is gone. + stream.queue = stream.queue.then(() => stream.notify(notification)).catch(() => void this.#end(stream)); + if (!stream.live) return; + clearTimeout(stream.heartbeat); + stream.heartbeat = unref( + setTimeout(() => this.#write(stream, EVENTS_HEARTBEAT_NOTIFICATION, { cursor: stream.position }), stream.grant) + ); + } + + // Ends a stream once. A live one sends `terminated` for an error, runs onUnsubscribe, then lets `open` return. + #end(stream: PushStream, error?: EventsError): Promise { + if (!this.#streams.delete(stream)) return Promise.resolve(); + stream.ended.abort(); + clearTimeout(stream.heartbeat); + clearTimeout(stream.checkTimer); + if (!stream.live) { + stream.stopped = error === undefined ? {} : { error }; + return Promise.resolve(); + } + stream.live = false; + if (error !== undefined) this.#write(stream, EVENTS_TERMINATED_NOTIFICATION, { error: errorObject(error) }); + return this.#close(stream); + } + + async #close(stream: PushStream): Promise { + await this.#unsubscribe(stream); + await stream.queue; + stream.finish(); + } + + // A stream that ended before `active`, after its onSubscribe ran. + async #abandon(stream: PushStream): Promise { + this.#streams.delete(stream); + stream.ended.abort(); + await this.#unsubscribe(stream); + } + + async #unsubscribe(stream: PushStream): Promise { + try { + await stream.entry.definition.onUnsubscribe?.(stream.ctx, stream.args); + } catch (error) { + this.#deps.report(error); + } + } +} diff --git a/packages/server/src/ext/events/testHook.ts b/packages/server/src/ext/events/testHook.ts index c2980c6c79..8ac44ac7fc 100644 --- a/packages/server/src/ext/events/testHook.ts +++ b/packages/server/src/ext/events/testHook.ts @@ -9,6 +9,8 @@ export interface EventsTestState { readonly emitBuffer: Readonly>; // Live poll leases. readonly pollLeases: number; + // Open push streams, counting those still starting. + readonly pushStreams: number; } // Internal controls for tests and the conformance fixture; never part of the public API or its declarations. diff --git a/packages/server/src/server/createMcpHandler.ts b/packages/server/src/server/createMcpHandler.ts index 4ef836c636..fdf626e721 100644 --- a/packages/server/src/server/createMcpHandler.ts +++ b/packages/server/src/server/createMcpHandler.ts @@ -71,6 +71,7 @@ import type { ServerEventBus, ServerNotifier } from './serverEventBus'; import { createServerNotifier, InMemoryServerEventBus } from './serverEventBus'; import { DEFAULT_SSE_KEEP_ALIVE_MS } from './sseKeepAlive'; import { WebStandardStreamableHTTPServerTransport } from './streamableHttp'; +import { isStreamingMethod } from './streamingMethods'; /* ------------------------------------------------------------------------ * * Factory and handler types @@ -177,8 +178,9 @@ export interface CreateMcpHandlerOptions { * - `'sse'` — always stream. * - `'json'` — never stream. **Mid-call notifications (progress, logging, * any related message emitted before the result) are dropped** — only the - * terminal result is delivered. Listen-class subscription streams are - * always served over SSE regardless of this setting. + * terminal result is delivered. `subscriptions/listen` streams and the + * Events extension's `events/stream` streams are always served over SSE + * regardless of this setting. */ responseMode?: PerRequestResponseMode; /** @@ -716,7 +718,7 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa if (responseMode === 'json') { // eslint-disable-next-line no-console console.warn( - "responseMode: 'json' drops mid-call notifications. subscriptions/listen streams are always served over SSE regardless; " + + "responseMode: 'json' drops mid-call notifications. subscriptions/listen and events/stream are always streamed regardless; " + 'other notifications emitted before a result are dropped.' ); } @@ -890,12 +892,14 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa }; server.onclose = onExchangeClose; + // A method the instance marks as streaming (`events/stream`) upgrades to SSE even under 'json'. + const exchangeMode = responseMode === 'json' && isStreamingMethod(server, route.message.method) ? 'auto' : responseMode; try { const response = await invoke(product, route.message, { classification: route.classification, request, ...(authInfo !== undefined && { authInfo }), - ...(responseMode !== undefined && { responseMode }), + ...(exchangeMode !== undefined && { responseMode: exchangeMode }), ...(options.keepAliveMs !== undefined && { keepAliveMs: options.keepAliveMs }) }); if (route.messageKind === 'notification') { diff --git a/packages/server/src/server/streamingMethods.ts b/packages/server/src/server/streamingMethods.ts new file mode 100644 index 0000000000..f443ce3012 --- /dev/null +++ b/packages/server/src/server/streamingMethods.ts @@ -0,0 +1,15 @@ +import type { Server } from './server'; + +// Methods each server answers as a stream whatever `responseMode` says, as `createMcpHandler` streams `subscriptions/listen`. +const streamingMethods = new WeakMap>(); + +// Makes `createMcpHandler` serve `method` on `server` with `'auto'` where `responseMode: 'json'` is configured. +export function markStreamingMethod(server: Server, method: string): void { + const methods = streamingMethods.get(server) ?? new Set(); + methods.add(method); + streamingMethods.set(server, methods); +} + +export function isStreamingMethod(server: Server, method: string): boolean { + return streamingMethods.get(server)?.has(method) === true; +} diff --git a/packages/server/test/ext/events/harness.ts b/packages/server/test/ext/events/harness.ts index 93dcea1de8..dfb23f0d8c 100644 --- a/packages/server/test/ext/events/harness.ts +++ b/packages/server/test/ext/events/harness.ts @@ -50,12 +50,16 @@ function modernHeaders(message: JSONRPCRequest | JSONRPCNotification): Record void } = {} +): Served { const handler = createMcpHandler( () => { const mcp = new McpServer({ name: 'events-test', version: '1.0.0' }); events.attach(mcp); + options.setup?.(mcp); return mcp; }, options.responseMode === undefined ? {} : { responseMode: options.responseMode } diff --git a/packages/server/test/ext/events/poll.test.ts b/packages/server/test/ext/events/poll.test.ts index 0fd31ad545..bb6a7f5410 100644 --- a/packages/server/test/ext/events/poll.test.ts +++ b/packages/server/test/ext/events/poll.test.ts @@ -528,10 +528,10 @@ describe('test hook', () => { const { poll } = poller(events); const { cursor: c0 } = await poll({ name: 'i', cursor: null }); await h.emit({ data: { n: 1 } }); - expect(hook.state()).toEqual({ trustedOrigins: [], emitBuffer: { i: 1 }, pollLeases: 1 }); + expect(hook.state()).toEqual({ trustedOrigins: [], emitBuffer: { i: 1 }, pollLeases: 1, pushStreams: 0 }); hook.restart(); - expect(hook.state()).toEqual({ trustedOrigins: [], emitBuffer: {}, pollLeases: 0 }); + expect(hook.state()).toEqual({ trustedOrigins: [], emitBuffer: {}, pollLeases: 0, pushStreams: 0 }); const after = await poll({ name: 'i', cursor: c0 }); expect(after).toMatchObject({ events: [], truncated: true, hasMore: false }); expect(after.cursor).not.toBe(c0); diff --git a/packages/server/test/ext/events/push.test.ts b/packages/server/test/ext/events/push.test.ts new file mode 100644 index 0000000000..ea6532f829 --- /dev/null +++ b/packages/server/test/ext/events/push.test.ts @@ -0,0 +1,528 @@ +import type { JSONRPCMessage, JSONRPCRequest } from '@modelcontextprotocol/core-internal'; +import { afterEach, describe, expect, it, vi } from 'vitest'; +import * as z from 'zod/v4'; + +import type { CheckContext, EventContext, EventResult, PollEventsResult } from '../../../src/ext/events/index'; +import { EventsError, EventsExtension } from '../../../src/ext/events/index'; +import type { EventsTestHook } from '../../../src/ext/events/testHook'; +import type { PostInit, Served } from './harness'; +import { errorOf, readFrames, resultOf, serve } from './harness'; + +const P = z.object({ n: z.number() }); +const SUB = 'io.modelcontextprotocol/subscriptionId'; +const ACTIVE = 'notifications/events/active'; +const EVENT = 'notifications/events/event'; +const HEARTBEAT = 'notifications/events/heartbeat'; +const ERROR = 'notifications/events/error'; +const TERMINATED = 'notifications/events/terminated'; +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/; + +type Check = (ctx: CheckContext, args: Record, cursor: string | null) => EventResult<{ n: number }>; + +interface OpenStream { + id: number; + response: Response; + frames: AsyncGenerator; + abort(): void; +} + +// Every stream a test opens; afterEach aborts them, as a client going away would. +const opened: AbortController[] = []; +let nextId = 1000; + +function testHook(events: EventsExtension): EventsTestHook { + return (events as unknown as Record)[Symbol.for('mcp.events.testHook')]!; +} + +async function open(served: Served, params: Record, init: PostInit & { id?: number } = {}): Promise { + const id = init.id ?? nextId++; + const controller = new AbortController(); + opened.push(controller); + const response = await served.post({ jsonrpc: '2.0', id, method: 'events/stream', params } as JSONRPCRequest, { + ...init, + signal: controller.signal + }); + return { id, response, frames: readFrames(response), abort: () => controller.abort() }; +} + +async function next(stream: OpenStream): Promise { + const { value, done } = await stream.frames.next(); + if (done) throw new Error('the stream ended'); + return value; +} + +// The params of a frame that must be a notification. +function paramsOf(frame: JSONRPCMessage): Record { + if (!('method' in frame) || 'id' in frame) throw new Error(`expected a notification, got ${JSON.stringify(frame)}`); + return frame.params ?? {}; +} + +// The frames left on a stream the server is ending. +async function rest(stream: OpenStream): Promise { + const frames: JSONRPCMessage[] = []; + for await (const frame of stream.frames) frames.push(frame); + return frames; +} + +function finalResult(id: number) { + return { jsonrpc: '2.0', id, result: { resultType: 'complete', _meta: expect.objectContaining({ [SUB]: id }) } }; +} + +function notification(method: string, id: number, params: Record) { + return { jsonrpc: '2.0', method, params: { ...params, _meta: expect.objectContaining({ [SUB]: id }) } }; +} + +afterEach(async () => { + for (const controller of opened.splice(0)) controller.abort(); + await new Promise(resolve => setImmediate(resolve)); + vi.useRealTimers(); + vi.restoreAllMocks(); +}); + +describe('events/stream: opening', () => { + it('sends active first with the default grant and the request id', async () => { + const events = new EventsExtension(); + events.registerEvent('tick', { payloadSchema: P, check: () => ({ events: [], cursor: 'h0' }) }); + const stream = await open(serve(events), { name: 'tick', cursor: null }, { id: 7 }); + expect(stream.response.headers.get('content-type')).toContain('text/event-stream'); + expect(await next(stream)).toEqual(notification(ACTIVE, 7, { cursor: 'h0', truncated: false, heartbeatMs: 30_000 })); + }); + + it.each([ + [10_000, 10_000], + [1000, 5000], + [120_000, 30_000] + ])('grants %i as %i', async (asked, granted) => { + const events = new EventsExtension(); + events.registerEvent('tick', { payloadSchema: P, check: () => ({ events: [], cursor: 'h0' }) }); + const stream = await open(serve(events), { name: 'tick', cursor: null, heartbeatMs: asked }); + expect(await next(stream)).toMatchObject({ method: ACTIVE, params: { heartbeatMs: granted } }); + }); + + it('answers validation errors at once and opens no stream', async () => { + const onSubscribe = vi.fn((_ctx: EventContext, args: Record) => { + if (args.deny === true) throw new EventsError('forbidden', 'Forbidden', { reason: 'denied' }); + }); + const events = new EventsExtension({ maxSubscriptions: 2 }); + events.registerEvent('i', { + emitOnly: true, + inputSchema: z.object({ deny: z.boolean().optional(), a: z.number().optional() }), + payloadSchema: P, + onSubscribe + }); + events.registerEvent('poll-only', { emitOnly: true, payloadSchema: P, delivery: { push: false } }); + const served = serve(events); + const fail = async (params: Record) => { + const response = await served.post({ jsonrpc: '2.0', id: nextId++, method: 'events/stream', params }); + expect(response.headers.get('content-type')).toContain('application/json'); + return ((await response.json()) as { error: unknown }).error; + }; + expect(await fail({ name: 'missing' })).toMatchObject({ code: -32_023, data: { kind: 'event' } }); + expect(await fail({ name: 'poll-only' })).toMatchObject({ code: -32_026, data: { feature: 'deliveryMode', value: 'push' } }); + expect(await fail({ name: 'i', arguments: { a: 'x' } })).toMatchObject({ code: -32_602 }); + expect(errorOf(await served.rpc('events/stream', { name: 'i' }, { era: 'legacy' }))).toMatchObject({ code: -32_601 }); + expect(await fail({ name: 'i', arguments: { deny: true } })).toMatchObject({ code: -32_024, data: { reason: 'denied' } }); + expect(testHook(events).state().pushStreams).toBe(0); + + // maxSubscriptions counts poll leases and push streams together. + resultOf(await served.rpc('events/poll', { name: 'i', arguments: { a: 1 } })); + await next(await open(served, { name: 'i', arguments: { a: 2 } })); + expect(await fail({ name: 'i', arguments: { a: 3 } })).toMatchObject({ code: -32_025, data: { limit: 'subscriptions', max: 2 } }); + expect(onSubscribe).toHaveBeenCalledTimes(3); + }); + + it('answers a check that fails before active as the request error, after onUnsubscribe', async () => { + const onUnsubscribe = vi.fn(); + const check = vi + .fn() + .mockImplementationOnce(() => { + throw new Error('upstream down'); + }) + .mockImplementationOnce(() => { + throw new EventsError('forbidden', 'Forbidden'); + }); + const events = new EventsExtension(); + events.registerEvent('tick', { payloadSchema: P, check, onUnsubscribe }); + const { rpc } = serve(events); + expect(errorOf(await rpc('events/stream', { name: 'tick', cursor: null }))).toMatchObject({ + code: -32_603, + message: 'upstream down' + }); + expect(errorOf(await rpc('events/stream', { name: 'tick', cursor: 'h1' }))).toMatchObject({ code: -32_024 }); + expect(onUnsubscribe).toHaveBeenCalledTimes(2); + expect(testHook(events).state().pushStreams).toBe(0); + }); + + it('answers a termination that arrives while the stream starts as the request error', async () => { + let release!: () => void; + const onSubscribe = vi.fn(() => new Promise(resolve => (release = resolve))); + const onUnsubscribe = vi.fn(); + const events = new EventsExtension(); + const handle = events.registerEvent('i', { emitOnly: true, payloadSchema: P, onSubscribe, onUnsubscribe }); + const reply = serve(events).rpc('events/stream', { name: 'i', cursor: null }); + await vi.waitFor(() => expect(onSubscribe).toHaveBeenCalledOnce()); + await handle.terminate(new EventsError('forbidden', 'Forbidden', { reason: 'Access revoked' })); + expect(onUnsubscribe).not.toHaveBeenCalled(); + release(); + expect(errorOf(await reply)).toEqual({ code: -32_024, message: 'Forbidden', data: { reason: 'Access revoked' } }); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + expect((onUnsubscribe.mock.calls[0]![0] as EventContext).signal.aborted).toBe(true); + }); +}); + +describe('events/stream: a check type', () => { + it('sends a heartbeat with the checked cursor after a silent grant', async () => { + vi.useFakeTimers({ shouldAdvanceTime: true }); + const check = vi.fn().mockReturnValueOnce({ events: [], cursor: 'h0' }).mockReturnValue({ events: [], cursor: 'h1' }); + const events = new EventsExtension(); + events.registerEvent('tick', { payloadSchema: P, check }); + const stream = await open(serve(events), { name: 'tick', cursor: null }); + expect(await next(stream)).toMatchObject({ method: ACTIVE, params: { cursor: 'h0' } }); + let heartbeat: JSONRPCMessage | undefined; + const pending = next(stream).then(frame => (heartbeat = frame)); + await vi.advanceTimersByTimeAsync(29_000); + expect(heartbeat).toBeUndefined(); + await vi.advanceTimersByTimeAsync(1000); + expect(await pending).toEqual(notification(HEARTBEAT, stream.id, { cursor: 'h1' })); + expect(check.mock.calls.slice(1).map(([ctx, , cursor]) => [ctx.mode, cursor])).toEqual([ + ['push', 'h0'], + ['push', 'h1'], + ['push', 'h1'], + ['push', 'h1'], + ['push', 'h1'], + ['push', 'h1'] + ]); + }); + + it('replays from a cursor first, then reports a gap mid-stream with a fresh active', async () => { + vi.useFakeTimers({ shouldAdvanceTime: true }); + const check = vi + .fn() + .mockReturnValueOnce({ + events: [ + { eventId: 'a', data: { n: 1 } }, + { eventId: 'b', data: { n: 2 } } + ], + cursor: 'h3' + }) + .mockReturnValueOnce({ events: [{ eventId: 'c', data: { n: 3 } }], cursor: 'h9', truncated: true }) + .mockReturnValue({ events: [], cursor: 'h9' }); + const events = new EventsExtension(); + events.registerEvent('tick', { payloadSchema: P, check }); + const stream = await open(serve(events), { name: 'tick', cursor: 'h1' }); + // No cursor runs ahead of an event still to come: a batch's events carry its start cursor until the last. + expect(await next(stream)).toEqual(notification(ACTIVE, stream.id, { cursor: 'h1', truncated: false, heartbeatMs: 30_000 })); + expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'a', name: 'tick', data: { n: 1 }, cursor: 'h1' } }); + expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'b', data: { n: 2 }, cursor: 'h3' } }); + const gap = next(stream); + await vi.advanceTimersByTimeAsync(5000); + expect(await gap).toEqual(notification(ACTIVE, stream.id, { cursor: 'h3', truncated: true, heartbeatMs: 30_000 })); + expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'c', cursor: 'h9' } }); + expect(check.mock.calls.map(call => call[2])).toEqual(['h1', 'h3']); + }); + + it('applies the maxAgeMs floor to the replay and flags truncated', async () => { + const old = new Date(Date.now() - 600_000).toISOString(); + const check = vi.fn(() => ({ + events: [ + { eventId: 'old', timestamp: old, data: { n: 1 } }, + { eventId: 'new', data: { n: 2 } } + ], + cursor: 'h2' + })); + const events = new EventsExtension(); + events.registerEvent('tick', { payloadSchema: P, check }); + const stream = await open(serve(events), { name: 'tick', cursor: 'h1', maxAgeMs: 300_000 }); + expect(await next(stream)).toMatchObject({ method: ACTIVE, params: { cursor: 'h1', truncated: true } }); + expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'new', cursor: 'h2' } }); + expect(check.mock.calls[0]![0]).toMatchObject({ mode: 'push', maxAgeMs: 300_000 }); + }); + + it('keeps the stream open after a transient check error', async () => { + vi.useFakeTimers({ shouldAdvanceTime: true }); + const check = vi + .fn() + .mockReturnValueOnce({ events: [], cursor: 'h0' }) + .mockImplementationOnce(() => { + throw new Error('Gmail API 503'); + }) + .mockReturnValueOnce({ events: [{ eventId: 'e1', data: { n: 1 } }], cursor: 'h1' }) + .mockReturnValue({ events: [], cursor: 'h1' }); + const events = new EventsExtension(); + events.registerEvent('tick', { payloadSchema: P, check }); + const stream = await open(serve(events), { name: 'tick', cursor: null }); + await next(stream); + const error = next(stream); + await vi.advanceTimersByTimeAsync(5000); + expect(await error).toEqual(notification(ERROR, stream.id, { error: { code: -32_603, message: 'Gmail API 503' } })); + const event = next(stream); + await vi.advanceTimersByTimeAsync(5000); + expect(await event).toMatchObject({ method: EVENT, params: { eventId: 'e1', cursor: 'h1', _meta: { [SUB]: stream.id } } }); + expect(check.mock.calls.map(call => call[2])).toEqual([null, 'h0', 'h0']); + }); + + it('terminates when check throws forbidden', async () => { + vi.useFakeTimers({ shouldAdvanceTime: true }); + const onUnsubscribe = vi.fn(); + const check = vi + .fn() + .mockReturnValueOnce({ events: [], cursor: 'h0' }) + .mockImplementation(() => { + throw new EventsError('forbidden', 'Forbidden', { reason: 'Access revoked' }); + }); + const events = new EventsExtension(); + events.registerEvent('tick', { payloadSchema: P, check, onUnsubscribe }); + const stream = await open(serve(events), { name: 'tick', cursor: null }); + await next(stream); + const remaining = rest(stream); + await vi.advanceTimersByTimeAsync(5000); + expect(await remaining).toEqual([ + notification(TERMINATED, stream.id, { error: { code: -32_024, message: 'Forbidden', data: { reason: 'Access revoked' } } }), + finalResult(stream.id) + ]); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + await vi.advanceTimersByTimeAsync(60_000); + expect(check).toHaveBeenCalledTimes(2); + }); + + it('stops everything when the client vanishes (Review Focus 1)', async () => { + vi.useFakeTimers({ shouldAdvanceTime: true }); + const check = vi.fn(() => ({ events: [], cursor: 'h0' })); + const onSubscribe = vi.fn(); + const onUnsubscribe = vi.fn(); + const events = new EventsExtension(); + events.registerEvent('tick', { payloadSchema: P, check, onSubscribe, onUnsubscribe }); + const stream = await open(serve(events), { name: 'tick', cursor: null }); + await next(stream); + await vi.advanceTimersByTimeAsync(5000); + expect(check).toHaveBeenCalledTimes(2); + stream.abort(); + await vi.waitFor(() => expect(onUnsubscribe).toHaveBeenCalledOnce()); + await vi.advanceTimersByTimeAsync(60_000); + expect(check).toHaveBeenCalledTimes(2); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + expect(vi.getTimerCount()).toBe(0); + expect(testHook(events).state().pushStreams).toBe(0); + const subscribed = onSubscribe.mock.calls[0]![0] as EventContext; + const unsubscribed = onUnsubscribe.mock.calls[0]![0] as EventContext; + expect(subscribed).toMatchObject({ name: 'tick', mode: 'push', principal: null }); + expect(subscribed.subscriptionId).toMatch(UUID); + expect(unsubscribed.subscriptionId).toBe(subscribed.subscriptionId); + expect(unsubscribed.signal.aborted).toBe(true); + }); +}); + +describe('events/stream: an emit-only type', () => { + it('fans emits out per stream with match, transform and targeted emits', async () => { + const ids = new Map(); + const events = new EventsExtension(); + const handle = events.registerEvent('incident', { + emitOnly: true, + inputSchema: z.object({ severity: z.string(), redact: z.boolean().optional() }), + payloadSchema: z.object({ severity: z.string(), reporter: z.string().nullable() }), + onSubscribe: (ctx, args) => { + ids.set(args.severity, ctx.subscriptionId); + }, + match: (_ctx, event, args) => event.data.severity === args.severity, + transform: (_ctx, event, args) => (args.redact ? { ...event, data: { ...event.data, reporter: null } } : event) + }); + const served = serve(events); + const p1 = await open(served, { name: 'incident', arguments: { severity: 'P1', redact: true }, cursor: null }); + const p3 = await open(served, { name: 'incident', arguments: { severity: 'P3' }, cursor: null }); + const head = paramsOf(await next(p1)).cursor; + await next(p3); + await handle.emit({ eventId: 'inc-1', data: { severity: 'P1', reporter: 'ann' } }); + await handle.emit({ eventId: 'inc-3', data: { severity: 'P3', reporter: 'bob' } }); + await handle.emit({ eventId: 'direct', data: { severity: 'P3', reporter: 'cy' } }, { subscriptionId: ids.get('P1')! }); + await handle.emit({ eventId: 'inc-3b', data: { severity: 'P3', reporter: 'dee' } }); + + const first = await next(p1); + expect(first).toEqual( + notification(EVENT, p1.id, { + eventId: 'inc-1', + name: 'incident', + timestamp: expect.any(String), + data: { severity: 'P1', reporter: null }, + cursor: expect.any(String) + }) + ); + expect(paramsOf(first).cursor).not.toBe(head); + expect(await next(p1)).toMatchObject({ params: { eventId: 'direct', data: { severity: 'P3', reporter: null } } }); + expect(await next(p3)).toMatchObject({ params: { eventId: 'inc-3', data: { reporter: 'bob' }, _meta: { [SUB]: p3.id } } }); + expect(await next(p3)).toMatchObject({ params: { eventId: 'inc-3b' } }); + expect(ids.get('P1')).not.toBe(ids.get('P3')); + }); + + it('replays from a cursor with each event at its own position, then goes live', async () => { + const events = new EventsExtension(); + const handle = events.registerEvent('i', { emitOnly: true, payloadSchema: P }); + const served = serve(events); + const poll = async (params: Record) => resultOf(await served.rpc('events/poll', params)) as PollEventsResult; + const { cursor: c0 } = await poll({ name: 'i', cursor: null }); + await handle.emit({ eventId: 'e1', data: { n: 1 } }); + await handle.emit({ eventId: 'e2', data: { n: 2 } }); + const { cursor: c1 } = await poll({ name: 'i', cursor: c0, maxEvents: 1 }); + const { cursor: c2 } = await poll({ name: 'i', cursor: c1 }); + + const stream = await open(served, { name: 'i', cursor: c0 }); + expect(await next(stream)).toMatchObject({ method: ACTIVE, params: { cursor: c0, truncated: false } }); + expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'e1', cursor: c1 } }); + expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'e2', cursor: c2 } }); + await handle.emit({ eventId: 'e3', data: { n: 3 } }); + const live = paramsOf(await next(stream)); + expect(live.eventId).toBe('e3'); + expect([c0, c1, c2]).not.toContain(live.cursor); + + const gap = await open(served, { name: 'i', cursor: 'e00000000.5' }); + expect(await next(gap)).toMatchObject({ method: ACTIVE, params: { cursor: c0, truncated: true } }); + expect(await next(gap)).toMatchObject({ params: { eventId: 'e1', cursor: c1 } }); + }); + + it('sends the advanced position on the heartbeat when no event matches', async () => { + vi.useFakeTimers({ shouldAdvanceTime: true }); + const events = new EventsExtension({ heartbeatMs: 10_000 }); + const handle = events.registerEvent('i', { emitOnly: true, payloadSchema: P, match: () => false }); + const stream = await open(serve(events), { name: 'i', cursor: null }); + const head = paramsOf(await next(stream)).cursor; + await handle.emit({ data: { n: 1 } }); + const heartbeat = next(stream); + await vi.advanceTimersByTimeAsync(10_000); + const frame = await heartbeat; + expect(frame).toMatchObject({ method: HEARTBEAT }); + expect(paramsOf(frame).cursor).not.toBe(head); + }); + + it('does not terminate on update()', async () => { + const events = new EventsExtension(); + const handle = events.registerEvent('i', { emitOnly: true, payloadSchema: P }); + const stream = await open(serve(events), { name: 'i', cursor: null }); + await next(stream); + handle.update({ description: 'changed' }); + await handle.emit({ eventId: 'after', data: { n: 1 } }); + expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'after' } }); + }); + + it('holds several streams open at once', async () => { + const events = new EventsExtension(); + const handle = events.registerEvent('i', { emitOnly: true, payloadSchema: P }); + const served = serve(events); + const streams = await Promise.all([1, 2, 3].map(() => open(served, { name: 'i', cursor: null }))); + for (const stream of streams) await next(stream); + expect(testHook(events).state().pushStreams).toBe(3); + await handle.emit({ eventId: 'all', data: { n: 1 } }); + for (const stream of streams) { + expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'all', _meta: { [SUB]: stream.id } } }); + } + }); +}); + +describe('events/stream: termination', () => { + it('terminates on handle.terminate, remove and a schema change', async () => { + const onUnsubscribe = vi.fn(); + const events = new EventsExtension(); + const a = events.registerEvent('a', { emitOnly: true, payloadSchema: P, onUnsubscribe }); + const b = events.registerEvent('b', { emitOnly: true, payloadSchema: P, onUnsubscribe }); + events.registerEvent('c', { emitOnly: true, payloadSchema: P, onUnsubscribe }); + const served = serve(events); + const [sa, sb, sc] = await Promise.all(['a', 'b', 'c'].map(name => open(served, { name, cursor: null }))); + for (const stream of [sa!, sb!, sc!]) await next(stream); + + await a.terminate(new EventsError('forbidden', 'Forbidden', { reason: 'Access revoked' })); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + b.remove(); + events.registerEvent('c', { emitOnly: true, payloadSchema: z.object({ n: z.string() }) }); + + expect(await rest(sa!)).toEqual([ + notification(TERMINATED, sa!.id, { error: { code: -32_024, message: 'Forbidden', data: { reason: 'Access revoked' } } }), + finalResult(sa!.id) + ]); + expect(await rest(sb!)).toEqual([ + notification(TERMINATED, sb!.id, { error: { code: -32_023, message: 'Event type removed', data: { kind: 'event' } } }), + finalResult(sb!.id) + ]); + expect(await rest(sc!)).toEqual([ + notification(TERMINATED, sc!.id, { + error: { + code: -32_026, + message: 'Event type payloadSchema changed', + data: { feature: 'payloadSchema', reason: 'schema_changed' } + } + }), + finalResult(sc!.id) + ]); + expect(onUnsubscribe).toHaveBeenCalledTimes(3); + expect(testHook(events).state().pushStreams).toBe(0); + }); + + it('terminates only the stream with the given subscriptionId', async () => { + const ids: string[] = []; + const events = new EventsExtension(); + const handle = events.registerEvent('i', { + emitOnly: true, + payloadSchema: P, + onSubscribe: ctx => { + ids.push(ctx.subscriptionId); + } + }); + const served = serve(events); + const first = await open(served, { name: 'i', cursor: null }); + const second = await open(served, { name: 'i', cursor: null }); + await next(first); + await next(second); + await handle.terminate(new EventsError('forbidden', 'Forbidden'), { subscriptionId: ids[1]! }); + expect(await rest(second)).toEqual([ + notification(TERMINATED, second.id, { error: { code: -32_024, message: 'Forbidden' } }), + finalResult(second.id) + ]); + await handle.emit({ eventId: 'still', data: { n: 1 } }); + expect(await next(first)).toMatchObject({ params: { eventId: 'still' } }); + }); + + it('closes open streams on a simulated restart and fires onUnsubscribe', async () => { + const onUnsubscribe = vi.fn(); + const events = new EventsExtension(); + events.registerEvent('i', { emitOnly: true, payloadSchema: P, onUnsubscribe }); + const stream = await open(serve(events), { name: 'i', cursor: null }); + await next(stream); + const hook = testHook(events); + expect(hook.state()).toEqual({ trustedOrigins: [], emitBuffer: {}, pollLeases: 0, pushStreams: 1 }); + hook.restart(); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + expect(await rest(stream)).toEqual([finalResult(stream.id)]); + expect(hook.state().pushStreams).toBe(0); + }); +}); + +describe('events/stream: response modes', () => { + it("streams under responseMode: 'json' (Decision 11)", async () => { + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}); + const events = new EventsExtension(); + events.registerEvent('tick', { payloadSchema: P, check: () => ({ events: [], cursor: 'h0' }) }); + const served = serve(events, { + responseMode: 'json', + setup: mcp => + mcp.registerTool('progress', { inputSchema: z.object({}) }, async (_args, ctx) => { + await ctx.mcpReq.notify({ method: 'notifications/progress', params: { progressToken: 'tok', progress: 1 } }); + return { content: [{ type: 'text', text: 'done' }] }; + }) + }); + expect(warn).toHaveBeenCalledWith( + "responseMode: 'json' drops mid-call notifications. subscriptions/listen and events/stream are always streamed regardless; " + + 'other notifications emitted before a result are dropped.' + ); + + const stream = await open(served, { name: 'tick', cursor: null }); + expect(stream.response.headers.get('content-type')).toContain('text/event-stream'); + expect(await next(stream)).toMatchObject({ method: ACTIVE, params: { cursor: 'h0' } }); + + const missing = await served.post({ jsonrpc: '2.0', id: 1, method: 'events/stream', params: { name: 'missing' } }); + expect(missing.headers.get('content-type')).toContain('application/json'); + expect(await missing.json()).toMatchObject({ id: 1, error: { code: -32_023 } }); + + const tool = await served.post({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'progress', arguments: {} } }); + expect(tool.headers.get('content-type')).toContain('application/json'); + const text = await tool.text(); + expect(text).not.toContain('notifications/progress'); + expect(JSON.parse(text)).toMatchObject({ id: 2, result: { content: [{ type: 'text', text: 'done' }] } }); + }); +}); From 367f4f84025e9ad3f18b29776007997df9db9621 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 12:02:02 +0200 Subject: [PATCH 06/37] fix(server): fresh cursor on a truncated events/stream batch --- packages/server/src/ext/events/push.ts | 7 ++++--- packages/server/test/ext/events/push.test.ts | 19 +++++++++++++++---- 2 files changed, 19 insertions(+), 7 deletions(-) diff --git a/packages/server/src/ext/events/push.ts b/packages/server/src/ext/events/push.ts index 8c0f807e7a..bb5c60a294 100644 --- a/packages/server/src/ext/events/push.ts +++ b/packages/server/src/ext/events/push.ts @@ -210,14 +210,15 @@ export class StreamSet implements SubscriptionSource { return this.#batch(stream, from, result, params.maxAgeMs); } - // A check batch's cursors stay at `from` until its last event, so no cursor runs ahead of an event still to be sent. + // A batch's cursors stay at `from` until its last event, so none runs ahead of an unsent event; a truncated batch carries the fresh cursor throughout. async #batch(stream: PushStream, from: string | null, result: EventResult, maxAgeMs?: number): Promise { const { events, truncated } = await checkedEvents(stream.entry, result, maxAgeMs, this.#deps.report); const last = events.length - 1; + const cursorAt = (index: number) => (truncated || index === last ? result.cursor : from); return { - cursor: last === -1 ? result.cursor : from, + cursor: cursorAt(-1), truncated, - events: events.map((occurrence, index) => ({ ...occurrence, cursor: index === last ? result.cursor : from })), + events: events.map((occurrence, index) => ({ ...occurrence, cursor: cursorAt(index) })), position: result.cursor }; } diff --git a/packages/server/test/ext/events/push.test.ts b/packages/server/test/ext/events/push.test.ts index ea6532f829..dfeb944f99 100644 --- a/packages/server/test/ext/events/push.test.ts +++ b/packages/server/test/ext/events/push.test.ts @@ -205,7 +205,14 @@ describe('events/stream: a check type', () => { ], cursor: 'h3' }) - .mockReturnValueOnce({ events: [{ eventId: 'c', data: { n: 3 } }], cursor: 'h9', truncated: true }) + .mockReturnValueOnce({ + events: [ + { eventId: 'c', data: { n: 3 } }, + { eventId: 'd', data: { n: 4 } } + ], + cursor: 'h9', + truncated: true + }) .mockReturnValue({ events: [], cursor: 'h9' }); const events = new EventsExtension(); events.registerEvent('tick', { payloadSchema: P, check }); @@ -216,8 +223,10 @@ describe('events/stream: a check type', () => { expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'b', data: { n: 2 }, cursor: 'h3' } }); const gap = next(stream); await vi.advanceTimersByTimeAsync(5000); - expect(await gap).toEqual(notification(ACTIVE, stream.id, { cursor: 'h3', truncated: true, heartbeatMs: 30_000 })); + // A truncated batch carries the fresh cursor on its active and on every event, so the cursor never moves back. + expect(await gap).toEqual(notification(ACTIVE, stream.id, { cursor: 'h9', truncated: true, heartbeatMs: 30_000 })); expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'c', cursor: 'h9' } }); + expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'd', cursor: 'h9' } }); expect(check.mock.calls.map(call => call[2])).toEqual(['h1', 'h3']); }); @@ -226,15 +235,17 @@ describe('events/stream: a check type', () => { const check = vi.fn(() => ({ events: [ { eventId: 'old', timestamp: old, data: { n: 1 } }, - { eventId: 'new', data: { n: 2 } } + { eventId: 'new', data: { n: 2 } }, + { eventId: 'newer', data: { n: 3 } } ], cursor: 'h2' })); const events = new EventsExtension(); events.registerEvent('tick', { payloadSchema: P, check }); const stream = await open(serve(events), { name: 'tick', cursor: 'h1', maxAgeMs: 300_000 }); - expect(await next(stream)).toMatchObject({ method: ACTIVE, params: { cursor: 'h1', truncated: true } }); + expect(await next(stream)).toMatchObject({ method: ACTIVE, params: { cursor: 'h2', truncated: true } }); expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'new', cursor: 'h2' } }); + expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'newer', cursor: 'h2' } }); expect(check.mock.calls[0]![0]).toMatchObject({ mode: 'push', maxAgeMs: 300_000 }); }); From a5804c14432bb21a1ee9f4bfb280926c11e21e81 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 12:24:46 +0200 Subject: [PATCH 07/37] feat(server): Events webhook delivery engine --- packages/server/src/ext/events/extension.ts | 20 +- packages/server/src/ext/events/testHook.ts | 2 + packages/server/src/ext/events/types.ts | 5 + .../server/src/ext/events/webhookEngine.ts | 369 +++++++++++ packages/server/test/ext/events/poll.test.ts | 4 +- packages/server/test/ext/events/push.test.ts | 2 +- .../test/ext/events/webhookEngine.test.ts | 620 ++++++++++++++++++ 7 files changed, 1016 insertions(+), 6 deletions(-) create mode 100644 packages/server/src/ext/events/webhookEngine.ts create mode 100644 packages/server/test/ext/events/webhookEngine.test.ts diff --git a/packages/server/src/ext/events/extension.ts b/packages/server/src/ext/events/extension.ts index 4a5ea5167c..6f3a7c1d7b 100644 --- a/packages/server/src/ext/events/extension.ts +++ b/packages/server/src/ext/events/extension.ts @@ -27,13 +27,14 @@ import { changedSchema, deliveryModes, EventRegistry } from './registry'; import { installTestHook } from './testHook'; import type { CheckEventDefinition, EmitOnlyEventDefinition, EmitOnlyEventHandle, EventHandle, EventInput, EventsOptions } from './types'; import { SubscriptionValidator } from './validation'; +import { WebhookEngine } from './webhookEngine'; // The live subscriptions of one delivery mode, which `remove()`, a schema change and `terminate()` end. export interface SubscriptionSource { terminate(name: string, error: EventsError, subscriptionId?: string): Promise; } -// Receives each emitted event once it is buffered: `cursor` is the position after it, `previous` the one before. +// Receives each emitted event once it is buffered (`cursor` the position after it, `previous` the one before); it queues delivery and returns, never waiting on a receiver. export type EmitFanOut = (name: string, buffered: BufferedEvent, positions: { cursor: string; previous: string }) => void | Promise; type DefaultSchema = StandardSchemaWithJSON>; @@ -126,6 +127,8 @@ export class EventsExtension { readonly #validator: SubscriptionValidator; readonly #poll: PollSource; readonly #push: StreamSet; + // Webhook delivery, given a sender and a store. + readonly #webhooks: WebhookEngine | undefined; // Each emitted event is handed to these after it is buffered; push and webhook delivery add theirs. readonly #fanOuts: EmitFanOut[] = []; // Clears process-memory state on a simulated restart; each delivery mode adds its own. @@ -167,12 +170,22 @@ export class EventsExtension { checkIntervalMs: options.checkIntervalMs ?? DEFAULT_CHECK_INTERVAL_MS, report: error => this.#report(error) }); + this.#webhooks = + options.webhookSender === undefined || options.webhookStore === undefined + ? undefined + : new WebhookEngine({ + sender: options.webhookSender, + store: options.webhookStore, + trustedOrigins: this.#trustedOrigins, + onerror: error => this.#report(error) + }); this.#sources.push(this.#poll, this.#push); this.#fanOuts.push((name, buffered, { cursor }) => this.#push.fanOut(name, buffered, cursor)); this.#restarts.push( () => this.#buffer.clear(), () => this.#poll.clear(), - () => this.#push.closeAll() + () => this.#push.closeAll(), + () => this.#webhooks?.clear() ); installTestHook(this, { generation: () => this.#generation, @@ -184,7 +197,8 @@ export class EventsExtension { trustedOrigins: [...this.#trustedOrigins], emitBuffer: this.#buffer.sizes(), pollLeases: this.#poll.size, - pushStreams: this.#push.size + pushStreams: this.#push.size, + webhookSubscriptions: this.#webhooks?.size ?? 0 }), addTrustedOrigin: origin => { assertOrigin(origin); diff --git a/packages/server/src/ext/events/testHook.ts b/packages/server/src/ext/events/testHook.ts index 8ac44ac7fc..e7367f6f2d 100644 --- a/packages/server/src/ext/events/testHook.ts +++ b/packages/server/src/ext/events/testHook.ts @@ -11,6 +11,8 @@ export interface EventsTestState { readonly pollLeases: number; // Open push streams, counting those still starting. readonly pushStreams: number; + // Webhook subscriptions this process holds delivery state (watermark, status, retries) for. + readonly webhookSubscriptions: number; } // Internal controls for tests and the conformance fixture; never part of the public API or its declarations. diff --git a/packages/server/src/ext/events/types.ts b/packages/server/src/ext/events/types.ts index 896d118fae..2ba8577f0f 100644 --- a/packages/server/src/ext/events/types.ts +++ b/packages/server/src/ext/events/types.ts @@ -193,6 +193,7 @@ export interface WebhookSendRequest { body: string; /** The URL's origin is in `trustedOrigins`, so the `https` and private-address rules do not apply. */ trusted: boolean; + /** Aborts when the SDK stops delivering to the subscription. */ signal: AbortSignal; } @@ -207,6 +208,10 @@ export type WebhookSendOutcome = { status: number; body: string } | { error: 'co /** * Sends webhook POSTs. Webhook delivery is on only when one is configured. + * It sends the request as given, follows no redirects, and gives up after its + * own timeout with `{ error: 'timeout' }`: the SDK waits as long as it takes. + * It should resolve rather than reject; an event delivery whose sender rejects + * is reported to `onerror` and retried. * * Experimental: Events (SEP-3415) is new; this API may change in a minor release. * diff --git a/packages/server/src/ext/events/webhookEngine.ts b/packages/server/src/ext/events/webhookEngine.ts new file mode 100644 index 0000000000..81e0c0f0f9 --- /dev/null +++ b/packages/server/src/ext/events/webhookEngine.ts @@ -0,0 +1,369 @@ +import type { DeliveryErrorCategory, DeliveryStatus, EventOccurrence, WebhookControlBody } from '@modelcontextprotocol/core/ext/events'; +import { WEBHOOK_SUBSCRIPTION_ID_HEADER } from '@modelcontextprotocol/core/ext/events'; +import { + EventsError, + generateWebhookId, + parseWebhookSecret, + signWebhook, + timingSafeEqualString +} from '@modelcontextprotocol/core-internal/ext/events'; + +import type { WebhookSender, WebhookSendOutcome, WebhookSubscriptionRecord, WebhookSubscriptionStore } from './types'; + +// The waits between the five attempts of one message; after the last it is abandoned. +const RETRY_DELAYS_MS = [5000, 30_000, 120_000, 300_000]; +const MAX_BODY_BYTES = 262_144; +// Delivery is suspended once more than 95 % of at least 100 attempts in the last 60 minutes failed. +const SUSPENSION_WINDOW_MS = 3_600_000; +const SUSPENSION_MIN_ATTEMPTS = 100; +const SUSPENSION_FAILURE_PERCENT = 95; + +const encoder = new TextEncoder(); + +export interface WebhookEngineOptions { + readonly sender: WebhookSender; + readonly store: WebhookSubscriptionStore; + // Read at every send, so origins added later count. + readonly trustedOrigins: ReadonlySet; + onerror(error: Error): void; + readonly now?: () => number; +} + +// One event POST to one subscription, under one webhook-id until it is acknowledged or abandoned. +interface Message { + readonly webhookId: string; + readonly occurrence: EventOccurrence; + // The subscription's position after this event. + readonly position: string | null; + attempts: number; + done: boolean; + retry?: ReturnType; +} + +// What this process holds for one subscription it delivers to. +interface Tracked { + readonly id: string; + // Aborts the subscription's sends in flight once it is forgotten. + readonly ended: AbortController; + // Every event at or before this position is acknowledged or abandoned. + watermark: string | null; + // Messages not yet acknowledged or abandoned, in position order. + readonly pending: Message[]; + // Messages that came due while delivery was suspended. + parked: Message[]; + active: boolean; + lastDeliveryAt: string | null; + lastError: DeliveryErrorCategory | null; + // The first failure since the last acknowledgement. + failedSince?: string; + // The attempts of the last SUSPENSION_WINDOW_MS, oldest first, and how many of them failed. + recent: Array<{ readonly at: number; readonly failed: boolean }>; + recentFailures: number; +} + +// Retry timers never keep the process alive on their own. +function unref(timer: ReturnType): ReturnType { + (timer as { unref?: () => void }).unref?.(); + return timer; +} + +function byteLength(text: string): number { + return encoder.encode(text).byteLength; +} + +function isSuccess(status: number): boolean { + return status >= 200 && status < 300; +} + +// The bytes of a `whsec_` secret; records and subscribe requests carry only valid ones. +function signingKey(secret: string): Uint8Array { + const key = parseWebhookSecret(secret); + if (key === undefined) throw new TypeError('a webhook secret is not a Standard Webhooks secret (whsec_ and base64 of 24 to 64 bytes)'); + return key; +} + +// A single-use verification challenge: base64url of 32 random bytes. +function challengeNonce(): string { + let binary = ''; + for (const byte of globalThis.crypto.getRandomValues(new Uint8Array(32))) binary += String.fromCodePoint(byte); + return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, ''); +} + +// Whether a verification answer is a 2xx whose JSON body echoes the challenge. +function echoes(outcome: { status: number; body: string }, challenge: string): boolean { + if (!isSuccess(outcome.status)) return false; + let echoed: unknown; + try { + echoed = (JSON.parse(outcome.body) as { challenge?: unknown } | null)?.challenge; + } catch { + return false; + } + return typeof echoed === 'string' && timingSafeEqualString(echoed, challenge); +} + +function verificationError(reason: DeliveryErrorCategory): EventsError { + return new EventsError('callbackEndpointError', `Webhook endpoint verification failed: ${reason}`, { reason }); +} + +// Sends webhook POSTs: endpoint verification, signed event deliveries with per-message retries and the watermark cursor, and control bodies. +export class WebhookEngine { + readonly #sender: WebhookSender; + readonly #store: WebhookSubscriptionStore; + readonly #trustedOrigins: ReadonlySet; + readonly #onerror: (error: Error) => void; + readonly #now: () => number; + readonly #tracked = new Map(); + // Each verified `principal\0url` with the subscription ids it covers; it lasts while one of them does. + readonly #verified = new Map>(); + readonly #verifiedKeyOf = new Map(); + // Aborts verification and control sends in flight on clear(). + #lifetime = new AbortController(); + + constructor(options: WebhookEngineOptions) { + this.#sender = options.sender; + this.#store = options.store; + this.#trustedOrigins = options.trustedOrigins; + this.#onerror = options.onerror; + this.#now = options.now ?? (() => Date.now()); + } + + // Subscriptions this process holds delivery state for. + get size(): number { + return this.#tracked.size; + } + + // Throws `callbackEndpointError` with the failure category as `data.reason`. + async verify(principal: string, url: string, secret: string, subscriptionId: string): Promise { + const key = `${principal}\u0000${url}`; + let covered = this.#verified.get(key); + if (covered === undefined) { + const challenge = challengeNonce(); + const body = JSON.stringify({ type: 'verification', challenge }); + const webhookId = generateWebhookId('verification'); + const outcome = await this.#post(url, subscriptionId, [signingKey(secret)], webhookId, body, this.#lifetime.signal); + if ('error' in outcome) throw verificationError(outcome.error); + if (!echoes(outcome, challenge)) throw verificationError('challenge_failed'); + covered = this.#verified.get(key) ?? new Set(); + this.#verified.set(key, covered); + } + covered.add(subscriptionId); + this.#verifiedKeyOf.set(subscriptionId, key); + } + + // Starts the subscription's watermark at `startCursor`, dropping whatever this process held for it. + track(id: string, startCursor: string | null): void { + this.#drop(id); + this.#start(id, startCursor); + } + + // Queues one event POST and returns; `seed` is the watermark to start from when this process does not track `record.id`. + deliver(record: WebhookSubscriptionRecord, occurrence: EventOccurrence, position: string | null, seed: string | null): void { + const tracked = this.#tracked.get(record.id) ?? this.#start(record.id, seed); + const message: Message = { webhookId: generateWebhookId(), occurrence, position, attempts: 0, done: false }; + tracked.pending.push(message); + this.#attempt(tracked, message, record); + } + + // One signed POST of a control body, not retried; rejects for a body over the cap. + async sendControl(record: WebhookSubscriptionRecord, body: WebhookControlBody): Promise { + const text = JSON.stringify(body); + if (byteLength(text) > MAX_BODY_BYTES) { + throw new Error(`webhook subscription ${record.id}: the ${body.type} body is over ${MAX_BODY_BYTES} bytes`); + } + return this.#post(record.url, record.id, this.#signingKeys(record), generateWebhookId(body.type), text, this.#lifetime.signal); + } + + watermark(id: string): string | null | undefined { + return this.#tracked.get(id)?.watermark; + } + + status(id: string): DeliveryStatus | undefined { + const tracked = this.#tracked.get(id); + if (tracked === undefined) return undefined; + const { active, lastDeliveryAt, lastError, failedSince } = tracked; + return failedSince === undefined ? { active, lastDeliveryAt, lastError } : { active, lastDeliveryAt, lastError, failedSince }; + } + + // Reactivates a suspended subscription and retries the messages that waited. + resume(id: string): void { + const tracked = this.#tracked.get(id); + if (tracked === undefined || tracked.active) return; + tracked.active = true; + tracked.recent = []; + tracked.recentFailures = 0; + const parked = tracked.parked; + tracked.parked = []; + for (const message of parked) this.#attempt(tracked, message); + } + + // Drops the subscription's delivery state; the last subscription of a (principal, url) also drops its verification. + forget(id: string): void { + this.#drop(id); + const key = this.#verifiedKeyOf.get(id); + if (key === undefined) return; + this.#verifiedKeyOf.delete(id); + const covered = this.#verified.get(key); + if (covered === undefined) return; + covered.delete(id); + if (covered.size === 0) this.#verified.delete(key); + } + + // Drops all in-memory state, as a process restart would. + clear(): void { + for (const id of this.#tracked.keys()) this.#drop(id); + this.#verified.clear(); + this.#verifiedKeyOf.clear(); + this.#lifetime.abort(); + this.#lifetime = new AbortController(); + } + + #start(id: string, watermark: string | null): Tracked { + const tracked: Tracked = { + id, + ended: new AbortController(), + watermark, + pending: [], + parked: [], + active: true, + lastDeliveryAt: null, + lastError: null, + recent: [], + recentFailures: 0 + }; + this.#tracked.set(id, tracked); + return tracked; + } + + #drop(id: string): void { + const tracked = this.#tracked.get(id); + if (tracked === undefined) return; + this.#tracked.delete(id); + tracked.ended.abort(); + for (const message of tracked.pending) clearTimeout(message.retry); + } + + #isCurrent(tracked: Tracked): boolean { + return this.#tracked.get(tracked.id) === tracked; + } + + // Runs one attempt off the caller's path; an unexpected failure is reported and retried like a failed send. + #attempt(tracked: Tracked, message: Message, record?: WebhookSubscriptionRecord): void { + this.#try(tracked, message, record).catch((error: unknown) => { + if (!this.#isCurrent(tracked)) return; + this.#onerror(error instanceof Error ? error : new Error(String(error))); + this.#retry(tracked, message); + }); + } + + async #try(tracked: Tracked, message: Message, supplied: WebhookSubscriptionRecord | undefined): Promise { + if (!tracked.active) { + tracked.parked.push(message); + return; + } + message.attempts += 1; + const record = supplied ?? (await this.#store.get(tracked.id)); + if (!this.#isCurrent(tracked)) return; + // A record gone from the store, or expired, ends what this process holds for the subscription. + if (record === undefined || record.expiresAt <= this.#now()) { + this.forget(tracked.id); + return; + } + const body = JSON.stringify({ ...message.occurrence, cursor: tracked.watermark }); + if (byteLength(body) > MAX_BODY_BYTES) { + this.#onerror( + new Error( + `webhook subscription ${tracked.id}: abandoned event ${message.occurrence.eventId}, whose body is over ${MAX_BODY_BYTES} bytes` + ) + ); + this.#settle(tracked, message); + return; + } + const outcome = await this.#post(record.url, record.id, this.#signingKeys(record), message.webhookId, body, tracked.ended.signal); + if (!this.#isCurrent(tracked)) return; + if (this.#observe(tracked, outcome)) this.#retry(tracked, message); + else this.#settle(tracked, message); + } + + #retry(tracked: Tracked, message: Message): void { + const delay = RETRY_DELAYS_MS[message.attempts - 1]; + if (delay === undefined) { + this.#settle(tracked, message); + return; + } + message.retry = unref(setTimeout(() => this.#attempt(tracked, message), delay)); + } + + // Marks the message acknowledged or abandoned, and moves the watermark past the finished messages at the front. + #settle(tracked: Tracked, message: Message): void { + message.done = true; + let head = tracked.pending[0]; + while (head?.done === true) { + tracked.pending.shift(); + tracked.watermark = head.position; + head = tracked.pending[0]; + } + } + + // Records one outcome in the delivery status and returns whether to retry; 410 and 413 end the message, setting lastError only. + #observe(tracked: Tracked, outcome: WebhookSendOutcome): boolean { + const now = this.#now(); + if ('error' in outcome) { + tracked.lastError = outcome.error; + } else if (isSuccess(outcome.status)) { + tracked.lastDeliveryAt = new Date(now).toISOString(); + tracked.lastError = null; + tracked.failedSince = undefined; + this.#count(tracked, now, false); + return false; + } else { + tracked.lastError = outcome.status >= 500 ? 'http_5xx' : 'http_4xx'; + if (outcome.status === 410 || outcome.status === 413) return false; + } + tracked.failedSince ??= new Date(now).toISOString(); + this.#count(tracked, now, true); + return true; + } + + // Adds one attempt to the window and suspends delivery when the failures in it pass the threshold. + #count(tracked: Tracked, now: number, failed: boolean): void { + tracked.recent.push({ at: now, failed }); + if (failed) tracked.recentFailures += 1; + let oldest = tracked.recent[0]; + while (oldest !== undefined && oldest.at <= now - SUSPENSION_WINDOW_MS) { + tracked.recent.shift(); + if (oldest.failed) tracked.recentFailures -= 1; + oldest = tracked.recent[0]; + } + const total = tracked.recent.length; + if (failed && total >= SUSPENSION_MIN_ATTEMPTS && tracked.recentFailures * 100 > SUSPENSION_FAILURE_PERCENT * total) { + tracked.active = false; + } + } + + // The record's secret, and its previous one during the rotation grace window. + #signingKeys(record: WebhookSubscriptionRecord): Uint8Array[] { + const keys = [signingKey(record.secret)]; + const previous = record.previousSecret; + if (previous !== undefined && this.#now() < previous.expiresAt) keys.push(signingKey(previous.secret)); + return keys; + } + + async #post( + url: string, + subscriptionId: string, + keys: readonly Uint8Array[], + webhookId: string, + body: string, + signal: AbortSignal + ): Promise { + const timestamp = Math.floor(this.#now() / 1000); + const headers = { + 'Content-Type': 'application/json', + 'webhook-id': webhookId, + 'webhook-timestamp': String(timestamp), + 'webhook-signature': await signWebhook(keys, webhookId, timestamp, body), + [WEBHOOK_SUBSCRIPTION_ID_HEADER]: subscriptionId + }; + return this.#sender({ url, headers, body, trusted: this.#trustedOrigins.has(new URL(url).origin), signal }); + } +} diff --git a/packages/server/test/ext/events/poll.test.ts b/packages/server/test/ext/events/poll.test.ts index bb6a7f5410..ba615fbf36 100644 --- a/packages/server/test/ext/events/poll.test.ts +++ b/packages/server/test/ext/events/poll.test.ts @@ -528,10 +528,10 @@ describe('test hook', () => { const { poll } = poller(events); const { cursor: c0 } = await poll({ name: 'i', cursor: null }); await h.emit({ data: { n: 1 } }); - expect(hook.state()).toEqual({ trustedOrigins: [], emitBuffer: { i: 1 }, pollLeases: 1, pushStreams: 0 }); + expect(hook.state()).toEqual({ trustedOrigins: [], emitBuffer: { i: 1 }, pollLeases: 1, pushStreams: 0, webhookSubscriptions: 0 }); hook.restart(); - expect(hook.state()).toEqual({ trustedOrigins: [], emitBuffer: {}, pollLeases: 0, pushStreams: 0 }); + expect(hook.state()).toEqual({ trustedOrigins: [], emitBuffer: {}, pollLeases: 0, pushStreams: 0, webhookSubscriptions: 0 }); const after = await poll({ name: 'i', cursor: c0 }); expect(after).toMatchObject({ events: [], truncated: true, hasMore: false }); expect(after.cursor).not.toBe(c0); diff --git a/packages/server/test/ext/events/push.test.ts b/packages/server/test/ext/events/push.test.ts index dfeb944f99..27a4e55247 100644 --- a/packages/server/test/ext/events/push.test.ts +++ b/packages/server/test/ext/events/push.test.ts @@ -496,7 +496,7 @@ describe('events/stream: termination', () => { const stream = await open(serve(events), { name: 'i', cursor: null }); await next(stream); const hook = testHook(events); - expect(hook.state()).toEqual({ trustedOrigins: [], emitBuffer: {}, pollLeases: 0, pushStreams: 1 }); + expect(hook.state()).toEqual({ trustedOrigins: [], emitBuffer: {}, pollLeases: 0, pushStreams: 1, webhookSubscriptions: 0 }); hook.restart(); expect(onUnsubscribe).toHaveBeenCalledOnce(); expect(await rest(stream)).toEqual([finalResult(stream.id)]); diff --git a/packages/server/test/ext/events/webhookEngine.test.ts b/packages/server/test/ext/events/webhookEngine.test.ts new file mode 100644 index 0000000000..4f0ec06291 --- /dev/null +++ b/packages/server/test/ext/events/webhookEngine.test.ts @@ -0,0 +1,620 @@ +import type { EventOccurrence } from '@modelcontextprotocol/core/ext/events'; +import { WebhookControlBodySchema } from '@modelcontextprotocol/core/ext/events'; +import { + EventsError, + generateWebhookSecret, + parseWebhookSecret, + verifyWebhookSignature +} from '@modelcontextprotocol/core-internal/ext/events'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; + +import type { + WebhookSendOutcome, + WebhookSendRequest, + WebhookSubscriptionRecord, + WebhookSubscriptionStore +} from '../../../src/ext/events/types'; +import { WebhookEngine } from '../../../src/ext/events/webhookEngine'; + +const HOOK_URL = 'https://hooks.example.com/mcp'; +const ID = 'sub_1'; +const SECRET = generateWebhookSecret(); +const MESSAGE_ID = /^msg_[\w-]+$/; +const DELAYS = [5000, 30_000, 120_000, 300_000]; + +type Respond = (request: WebhookSendRequest) => WebhookSendOutcome | Promise; + +interface Sent extends WebhookSendRequest { + readonly at: number; +} + +class MapStore implements WebhookSubscriptionStore { + readonly records = new Map(); + get(id: string): Promise { + return Promise.resolve(this.records.get(id)); + } + put(record: WebhookSubscriptionRecord): Promise { + this.records.set(record.id, record); + return Promise.resolve(); + } + delete(id: string): Promise { + return Promise.resolve(this.records.delete(id)); + } + async *listByName(name: string): AsyncIterable { + for (const record of this.records.values()) if (record.name === name) yield record; + } +} + +const ok: Respond = () => ({ status: 200, body: '' }); + +// Answers a verification challenge by echoing it, and anything else with 200. +const echo: Respond = request => { + const body = JSON.parse(request.body) as { type?: string; challenge?: string }; + return { status: 200, body: body.type === 'verification' ? JSON.stringify({ challenge: body.challenge }) : '' }; +}; + +const engines: WebhookEngine[] = []; + +function occurrence(eventId: string, data?: Record): EventOccurrence { + return { eventId, name: 'e', timestamp: '2026-11-18T00:00:00.000Z', data: data ?? { n: 1 } }; +} + +function recordFor(overrides: Partial = {}): WebhookSubscriptionRecord { + return { + id: ID, + principal: 'u', + name: 'e', + arguments: {}, + url: HOOK_URL, + secret: SECRET, + expiresAt: Date.now() + 3_600_000, + createdAt: Date.now(), + ...overrides + }; +} + +// An engine over a store holding `recordFor()`, with a sender that records each request and answers with `respond`. +function setup(respond: Respond = ok, trustedOrigins: Set = new Set()) { + const store = new MapStore(); + const record = recordFor(); + store.records.set(record.id, record); + const requests: Sent[] = []; + const waiters: Array<{ count: number; resolve(): void }> = []; + const sender = vi.fn((request: WebhookSendRequest): Promise => { + requests.push({ ...request, at: Date.now() }); + for (const waiter of waiters.filter(w => requests.length >= w.count)) waiter.resolve(); + return Promise.resolve(respond(request)); + }); + // Resolves once `count` requests were sent; signing runs off the fake clock, so tests wait for sends. + const until = (count: number): Promise => + new Promise(resolve => { + if (requests.length >= count) resolve(); + else waiters.push({ count, resolve }); + }); + const onerror = vi.fn(); + const engine = new WebhookEngine({ sender, store, trustedOrigins, onerror }); + engines.push(engine); + return { engine, store, record, sender, requests, until, onerror }; +} + +// Lets the engine act on answers already received, without moving the clock. +const settle = (): Promise => vi.advanceTimersByTimeAsync(0); + +function verifies(request: WebhookSendRequest, secret: string): Promise { + const headers = request.headers; + return verifyWebhookSignature( + [parseWebhookSecret(secret)!], + headers['webhook-id']!, + Number(headers['webhook-timestamp']), + request.body, + headers['webhook-signature']! + ); +} + +function bodyOf(request: WebhookSendRequest): Record { + return JSON.parse(request.body) as Record; +} + +beforeEach(() => { + vi.useFakeTimers(); +}); + +afterEach(() => { + for (const engine of engines.splice(0)) engine.clear(); + vi.useRealTimers(); +}); + +describe('endpoint verification', () => { + it('verifies with a signed challenge and caches per principal and url', async () => { + const { engine, requests } = setup(echo); + await engine.verify('u', HOOK_URL, SECRET, ID); + expect(requests).toHaveLength(1); + const [request] = requests; + expect(bodyOf(request!)).toEqual({ type: 'verification', challenge: expect.stringMatching(/^[\w-]{43}$/) }); + expect(request!.headers).toMatchObject({ + 'Content-Type': 'application/json', + 'webhook-id': expect.stringMatching(/^msg_verification_[\w-]+$/), + 'webhook-timestamp': String(Math.floor(Date.now() / 1000)), + 'X-MCP-Subscription-Id': ID + }); + expect(await verifies(request!, SECRET)).toBe(true); + + await engine.verify('u', HOOK_URL, SECRET, 'sub_2'); + expect(requests).toHaveLength(1); + await engine.verify('v', HOOK_URL, SECRET, 'sub_3'); + expect(requests).toHaveLength(2); + expect(bodyOf(requests[1]!).challenge).not.toBe(bodyOf(request!).challenge); + }); + + const failures: Array<[WebhookSendOutcome, string]> = [ + [{ status: 200, body: '{"challenge":"wrong"}' }, 'challenge_failed'], + [{ status: 200, body: 'not json' }, 'challenge_failed'], + [{ status: 404, body: '' }, 'challenge_failed'], + [{ error: 'connection_refused' }, 'connection_refused'], + [{ error: 'timeout' }, 'timeout'], + [{ error: 'tls_error' }, 'tls_error'] + ]; + it.each(failures)('fails verification with %o as %s', async (outcome, reason) => { + const { engine, requests } = setup(() => outcome); + await expect(engine.verify('u', HOOK_URL, SECRET, ID)).rejects.toMatchObject({ code: -32_027, data: { reason } }); + await expect(engine.verify('u', HOOK_URL, SECRET, ID)).rejects.toBeInstanceOf(EventsError); + expect(requests).toHaveLength(2); + }); + + it('fails verification when a 404 echoes the challenge', async () => { + const { engine } = setup(request => ({ status: 404, body: JSON.stringify({ challenge: bodyOf(request).challenge }) })); + await expect(engine.verify('u', HOOK_URL, SECRET, ID)).rejects.toMatchObject({ data: { reason: 'challenge_failed' } }); + }); + + it('verifies a trusted origin too, and reads the live trusted set (D24, F5)', async () => { + const trustedOrigins = new Set(['http://127.0.0.1:9000']); + const { engine, record, requests, until } = setup(echo, trustedOrigins); + await engine.verify('u', 'http://127.0.0.1:9000/hook', SECRET, ID); + expect(requests).toHaveLength(1); + expect(requests[0]!.trusted).toBe(true); + + engine.deliver(record, occurrence('evt_1'), 'p1', 'p0'); + await until(2); + expect(requests[1]!.trusted).toBe(false); + trustedOrigins.add('https://hooks.example.com'); + engine.deliver(record, occurrence('evt_2'), 'p2', 'p1'); + await until(3); + expect(requests[2]!.trusted).toBe(true); + }); +}); + +describe('event delivery', () => { + it('signs the raw body and keeps webhook-id across retries', async () => { + let answer: WebhookSendOutcome = { status: 500, body: '' }; + const { engine, record, requests, until } = setup(() => answer); + engine.track(ID, 'p0'); + engine.deliver(record, occurrence('evt_1'), 'p1', null); + await until(1); + await settle(); + answer = { status: 200, body: '' }; + await vi.advanceTimersByTimeAsync(5000); + await until(2); + + const [first, second] = requests; + expect(first!.headers['webhook-id']).toMatch(MESSAGE_ID); + expect(second!.headers['webhook-id']).toBe(first!.headers['webhook-id']); + expect(Number(second!.headers['webhook-timestamp']) - Number(first!.headers['webhook-timestamp'])).toBe(5); + expect(second!.headers['webhook-signature']).not.toBe(first!.headers['webhook-signature']); + for (const request of requests) { + expect(request.headers).toMatchObject({ 'Content-Type': 'application/json', 'X-MCP-Subscription-Id': ID }); + expect(await verifies(request, SECRET)).toBe(true); + expect(bodyOf(request)).toEqual({ ...occurrence('evt_1'), cursor: 'p0' }); + } + }); + + it('gives each message its own webhook-id, never derived from eventId', async () => { + const { engine, store, record, requests, until } = setup(); + const other = recordFor({ id: 'sub_2' }); + await store.put(other); + engine.deliver(record, occurrence('evt_1'), 'p1', 'p0'); + engine.deliver(other, occurrence('evt_1'), 'p1', 'p0'); + await until(2); + const ids = requests.map(request => request.headers['webhook-id']!); + expect(new Set(ids).size).toBe(2); + for (const id of ids) { + expect(id).toMatch(MESSAGE_ID); + expect(id).not.toContain('evt_1'); + } + }); + + it('retries on the documented schedule then abandons', async () => { + const { engine, record, requests, until } = setup(() => ({ status: 503, body: '' })); + const start = Date.now(); + engine.track(ID, 'p0'); + engine.deliver(record, occurrence('evt_1'), 'p1', null); + await until(1); + for (const [index, delay] of DELAYS.entries()) { + await settle(); + await vi.advanceTimersByTimeAsync(delay); + await until(index + 2); + } + await settle(); + + expect(requests.map(request => request.at - start)).toEqual([0, 5000, 35_000, 155_000, 455_000]); + expect(new Set(requests.map(request => request.headers['webhook-id'])).size).toBe(1); + expect(engine.watermark(ID)).toBe('p1'); + expect(engine.status(ID)).toMatchObject({ active: true, lastError: 'http_5xx' }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(3_600_000); + expect(requests).toHaveLength(5); + }); + + it.each([410, 413])('treats %i as final for the message', async status => { + const { engine, store, record, requests, until } = setup(() => ({ status, body: '' })); + const put = vi.spyOn(store, 'put'); + const remove = vi.spyOn(store, 'delete'); + engine.track(ID, 'p0'); + engine.deliver(record, occurrence('evt_1'), 'p1', null); + await until(1); + await settle(); + + expect(engine.watermark(ID)).toBe('p1'); + expect(engine.status(ID)).toEqual({ active: true, lastDeliveryAt: null, lastError: 'http_4xx' }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(600_000); + expect(requests).toHaveLength(1); + expect(store.records.get(ID)).toBe(record); + expect(put).not.toHaveBeenCalled(); + expect(remove).not.toHaveBeenCalled(); + }); + + it('records a hanging receiver as timeout and retries (Review Focus 3)', async () => { + // Like a sender whose request timer fires: no answer for 5 s, then `timeout`. + let hang = true; + const { engine, record, requests, until } = setup(() => + hang ? new Promise(resolve => setTimeout(() => resolve({ error: 'timeout' }), 5000)) : { status: 204, body: '' } + ); + const start = Date.now(); + engine.deliver(record, occurrence('evt_1'), 'p1', 'p0'); + await until(1); + await vi.advanceTimersByTimeAsync(5000); + expect(engine.status(ID)).toEqual({ + active: true, + lastDeliveryAt: null, + lastError: 'timeout', + failedSince: new Date(start + 5000).toISOString() + }); + expect(engine.watermark(ID)).toBe('p0'); + + hang = false; + await vi.advanceTimersByTimeAsync(4999); + expect(requests).toHaveLength(1); + await vi.advanceTimersByTimeAsync(1); + await until(2); + await settle(); + expect(requests[1]!.at - start).toBe(10_000); + expect(engine.status(ID)).toEqual({ active: true, lastDeliveryAt: new Date(start + 10_000).toISOString(), lastError: null }); + expect(engine.watermark(ID)).toBe('p1'); + }); + + it('holds the watermark behind an unacknowledged event', async () => { + let failFirst = true; + const { engine, record, requests, until } = setup(request => + failFirst && bodyOf(request).eventId === 'evt_1' ? { status: 500, body: '' } : { status: 200, body: '' } + ); + engine.track(ID, 'p0'); + engine.deliver(record, occurrence('evt_1'), 'p1', null); + engine.deliver(record, occurrence('evt_2'), 'p2', null); + engine.deliver(record, occurrence('evt_3'), 'p3', null); + await until(3); + await settle(); + expect(engine.watermark(ID)).toBe('p0'); + expect(requests.map(request => bodyOf(request).cursor)).toEqual(['p0', 'p0', 'p0']); + + failFirst = false; + await vi.advanceTimersByTimeAsync(5000); + await until(4); + await settle(); + expect(engine.watermark(ID)).toBe('p3'); + + engine.deliver(record, occurrence('evt_4'), 'p4', null); + await until(5); + expect(bodyOf(requests[4]!).cursor).toBe('p3'); + }); + + it('tracks an unknown subscription from the seed, so every POST carries a cursor (F3a)', async () => { + const { engine, record, requests, until } = setup(); + expect(engine.watermark(ID)).toBeUndefined(); + expect(engine.status(ID)).toBeUndefined(); + engine.deliver(record, occurrence('evt_1'), 'p1', 'p0'); + engine.deliver(record, occurrence('evt_2'), 'p2', 'p1'); + await until(2); + await settle(); + expect(requests.map(request => bodyOf(request).cursor)).toEqual(['p0', 'p0']); + expect(engine.watermark(ID)).toBe('p2'); + expect(engine.status(ID)).toEqual({ active: true, lastDeliveryAt: new Date().toISOString(), lastError: null }); + }); + + it('sends cursor null for an event type without replay', async () => { + const { engine, record, requests, until } = setup(); + engine.deliver(record, occurrence('evt_1'), null, null); + await until(1); + await settle(); + expect(bodyOf(requests[0]!)).toHaveProperty('cursor', null); + expect(engine.watermark(ID)).toBeNull(); + }); + + it('queues each delivery and returns without waiting for the receiver', async () => { + const answers = new Map void>(); + const { engine, record, until } = setup(request => new Promise(resolve => answers.set(bodyOf(request).eventId as string, resolve))); + expect(engine.deliver(record, occurrence('evt_1'), 'p1', 'p0')).toBeUndefined(); + expect(engine.deliver(record, occurrence('evt_2'), 'p2', 'p0')).toBeUndefined(); + await until(2); + answers.get('evt_2')!({ status: 200, body: '' }); + await settle(); + expect(engine.watermark(ID)).toBe('p0'); + answers.get('evt_1')!({ status: 200, body: '' }); + await settle(); + expect(engine.watermark(ID)).toBe('p2'); + }); + + it('dual-signs during the rotation grace window', async () => { + const previous = generateWebhookSecret(); + const { engine, store, record, requests, until } = setup(); + const rotated = { ...record, previousSecret: { secret: previous, expiresAt: Date.now() + 300_000 } }; + await store.put(rotated); + engine.deliver(rotated, occurrence('evt_1'), 'p1', 'p0'); + await until(1); + const signatures = requests[0]!.headers['webhook-signature']!.split(' '); + expect(signatures).toHaveLength(2); + expect(signatures.every(signature => signature.startsWith('v1,'))).toBe(true); + expect(await verifies(requests[0]!, SECRET)).toBe(true); + expect(await verifies(requests[0]!, previous)).toBe(true); + + await vi.advanceTimersByTimeAsync(300_000); + engine.deliver(rotated, occurrence('evt_2'), 'p2', 'p1'); + await until(2); + expect(requests[1]!.headers['webhook-signature']!.split(' ')).toHaveLength(1); + expect(await verifies(requests[1]!, SECRET)).toBe(true); + expect(await verifies(requests[1]!, previous)).toBe(false); + }); + + it('signs each retry with the record as the store holds it then', async () => { + let answer: WebhookSendOutcome = { status: 500, body: '' }; + const { engine, store, record, requests, until } = setup(() => answer); + engine.deliver(record, occurrence('evt_1'), 'p1', 'p0'); + await until(1); + await settle(); + const next = generateWebhookSecret(); + await store.put({ ...record, secret: next, previousSecret: { secret: SECRET, expiresAt: Date.now() + 300_000 } }); + answer = { status: 200, body: '' }; + await vi.advanceTimersByTimeAsync(5000); + await until(2); + expect(requests[1]!.headers['webhook-signature']!.split(' ')).toHaveLength(2); + expect(await verifies(requests[1]!, next)).toBe(true); + }); + + it.each(['deleted', 'expired'])('stops retrying once the record is %s', async change => { + const { engine, store, record, requests, until } = setup(() => ({ status: 500, body: '' })); + engine.deliver(record, occurrence('evt_1'), 'p1', 'p0'); + await until(1); + await settle(); + await (change === 'deleted' ? store.delete(ID) : store.put({ ...record, expiresAt: Date.now() + 4000 })); + await vi.advanceTimersByTimeAsync(600_000); + expect(requests).toHaveLength(1); + expect(engine.watermark(ID)).toBeUndefined(); + }); + + it('never sends a body over 256 KiB', async () => { + const { engine, record, requests, until, onerror } = setup(); + const empty = JSON.stringify({ ...occurrence('evt_max', { blob: '' }), cursor: 'p0' }); + engine.deliver(record, occurrence('evt_max', { blob: 'x'.repeat(262_144 - empty.length) }), 'p1', 'p0'); + await until(1); + expect(new TextEncoder().encode(requests[0]!.body).byteLength).toBe(262_144); + + // 131 072 two-byte characters: under the cap in UTF-16 code units, over it in UTF-8 bytes. + engine.deliver(record, occurrence('evt_big', { blob: 'é'.repeat(131_072) }), 'p2', 'p1'); + await settle(); + expect(requests).toHaveLength(1); + expect(onerror).toHaveBeenCalledTimes(1); + expect(onerror.mock.calls[0]![0]).toBeInstanceOf(Error); + expect((onerror.mock.calls[0]![0] as Error).message).toContain('262144'); + expect(engine.watermark(ID)).toBe('p2'); + }); + + it('reports a sender that throws and retries the message', async () => { + let fail = true; + const { engine, record, until, onerror } = setup(() => { + if (fail) throw new Error('sender broke'); + return { status: 200, body: '' }; + }); + engine.deliver(record, occurrence('evt_1'), 'p1', 'p0'); + await until(1); + await settle(); + expect(onerror).toHaveBeenCalledWith(expect.objectContaining({ message: 'sender broke' })); + expect(engine.status(ID)).toEqual({ active: true, lastDeliveryAt: null, lastError: null }); + fail = false; + await vi.advanceTimersByTimeAsync(5000); + await until(2); + await settle(); + expect(engine.watermark(ID)).toBe('p1'); + }); +}); + +describe('delivery status', () => { + const categories: Array<[WebhookSendOutcome, string]> = [ + [{ error: 'connection_refused' }, 'connection_refused'], + [{ error: 'tls_error' }, 'tls_error'], + [{ status: 302, body: '' }, 'http_4xx'], + [{ status: 404, body: 'not here' }, 'http_4xx'], + [{ status: 500, body: 'oops' }, 'http_5xx'] + ]; + it.each(categories)('reports %o as lastError %s', async (outcome, category) => { + const { engine, record, until } = setup(() => outcome); + engine.deliver(record, occurrence('evt_1'), 'p1', 'p0'); + await until(1); + await settle(); + expect(engine.status(ID)).toEqual({ + active: true, + lastDeliveryAt: null, + lastError: category, + failedSince: new Date().toISOString() + }); + }); + + it('suspends when more than 95 % of at least 100 attempts in the last hour failed, and resume() retries what waited', async () => { + let healthy = false; + const { engine, record, requests, until } = setup(request => + healthy || Number((bodyOf(request).eventId as string).slice(4)) <= 5 ? { status: 200, body: '' } : { status: 503, body: '' } + ); + engine.track(ID, 'p0'); + for (let n = 1; n <= 100; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await until(100); + await settle(); + // 95 of 100 attempts failed: not more than 95 %. + expect(engine.status(ID)).toMatchObject({ active: true }); + + const failedAt = Date.now(); + engine.deliver(record, occurrence('evt_101'), 'p101', null); + await until(101); + await settle(); + expect(engine.status(ID)).toEqual({ + active: false, + lastDeliveryAt: new Date(failedAt).toISOString(), + lastError: 'http_5xx', + failedSince: new Date(failedAt).toISOString() + }); + + engine.deliver(record, occurrence('evt_102'), 'p102', null); + await vi.advanceTimersByTimeAsync(600_000); + expect(requests).toHaveLength(101); + expect(engine.watermark(ID)).toBe('p5'); + + healthy = true; + engine.resume(ID); + await until(101 + 97); + await settle(); + expect(engine.status(ID)).toEqual({ active: true, lastDeliveryAt: new Date().toISOString(), lastError: null }); + expect(engine.watermark(ID)).toBe('p102'); + }); + + it('counts only the attempts of the last 60 minutes', async () => { + let failing = true; + const { engine, store, until } = setup(() => (failing ? { status: 503, body: '' } : { status: 200, body: '' })); + const record = recordFor({ expiresAt: Date.now() + 86_400_000 }); + await store.put(record); + engine.track(ID, 'p0'); + for (let n = 1; n <= 99; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await until(99); + await settle(); + failing = false; + await vi.advanceTimersByTimeAsync(5000); + await until(198); + await settle(); + expect(engine.watermark(ID)).toBe('p99'); + + // Counted with the hour before, these would be 199 failures in 298 attempts; alone they are 100 in 100. + await vi.advanceTimersByTimeAsync(3_600_000); + failing = true; + for (let n = 100; n <= 199; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await until(298); + await settle(); + expect(engine.status(ID)).toMatchObject({ active: false }); + }); + + it('resume() does nothing for an active or unknown subscription', async () => { + const { engine, record, requests, until } = setup(); + engine.resume(ID); + expect(engine.status(ID)).toBeUndefined(); + engine.deliver(record, occurrence('evt_1'), 'p1', 'p0'); + await until(1); + await settle(); + engine.resume(ID); + await settle(); + expect(requests).toHaveLength(1); + expect(engine.status(ID)).toMatchObject({ active: true }); + }); +}); + +describe('control bodies', () => { + it('sends gap and terminated control bodies', async () => { + const { engine, record, requests } = setup(() => ({ status: 202, body: '' })); + expect(await engine.sendControl(record, { type: 'gap', cursor: 'p9' })).toEqual({ status: 202, body: '' }); + expect(await engine.sendControl(record, { type: 'terminated', error: { code: -32_024, message: 'Forbidden' } })).toEqual({ + status: 202, + body: '' + }); + + expect(requests.map(request => request.headers['webhook-id'])).toEqual([ + expect.stringMatching(/^msg_gap_[\w-]+$/), + expect.stringMatching(/^msg_terminated_[\w-]+$/) + ]); + expect(bodyOf(requests[0]!)).toEqual({ type: 'gap', cursor: 'p9' }); + for (const request of requests) { + expect(WebhookControlBodySchema.safeParse(bodyOf(request)).success).toBe(true); + expect(request.headers).toMatchObject({ 'Content-Type': 'application/json', 'X-MCP-Subscription-Id': ID }); + expect(await verifies(request, SECRET)).toBe(true); + } + }); + + it('returns a failed outcome as it is', async () => { + const { engine, record } = setup(() => ({ error: 'connection_refused' })); + expect(await engine.sendControl(record, { type: 'gap', cursor: null })).toEqual({ error: 'connection_refused' }); + }); +}); + +describe('forget and clear', () => { + it('forget() stops the retries, and the last subscription of a url ends its verification', async () => { + const { engine, record, requests, until } = setup(request => + bodyOf(request).type === 'verification' ? echo(request) : { status: 500, body: '' } + ); + await engine.verify('u', HOOK_URL, SECRET, ID); + await engine.verify('u', HOOK_URL, SECRET, 'sub_2'); + engine.deliver(record, occurrence('evt_1'), 'p1', 'p0'); + await until(2); + await settle(); + + engine.forget(ID); + expect(engine.watermark(ID)).toBeUndefined(); + expect(engine.status(ID)).toBeUndefined(); + await vi.advanceTimersByTimeAsync(600_000); + expect(requests).toHaveLength(2); + await engine.verify('u', HOOK_URL, SECRET, 'sub_3'); + expect(requests).toHaveLength(2); + + engine.forget('sub_2'); + engine.forget('sub_3'); + await engine.verify('u', HOOK_URL, SECRET, ID); + expect(requests).toHaveLength(3); + }); + + it('clear() drops every watermark, status, pending retry and verification, and aborts sends in flight', async () => { + const answers: Array<(outcome: WebhookSendOutcome) => void> = []; + const { engine, record, requests, until } = setup(request => + bodyOf(request).type === 'verification' ? echo(request) : new Promise(resolve => answers.push(resolve)) + ); + await engine.verify('u', HOOK_URL, SECRET, ID); + engine.deliver(record, occurrence('evt_1'), 'p1', 'p0'); + await until(2); + expect(requests[1]!.signal.aborted).toBe(false); + + engine.clear(); + expect(requests[1]!.signal.aborted).toBe(true); + expect(engine.watermark(ID)).toBeUndefined(); + expect(engine.status(ID)).toBeUndefined(); + expect(engine.size).toBe(0); + answers[0]!({ status: 500, body: '' }); + await vi.advanceTimersByTimeAsync(600_000); + expect(requests).toHaveLength(2); + expect(engine.status(ID)).toBeUndefined(); + + await engine.verify('u', HOOK_URL, SECRET, ID); + expect(requests).toHaveLength(3); + }); + + it('track() starts the watermark again for a subscription it already tracks', async () => { + const { engine, record, until } = setup(); + engine.deliver(record, occurrence('evt_1'), 'p1', 'p0'); + await until(1); + await settle(); + expect(engine.watermark(ID)).toBe('p1'); + engine.track(ID, 'c7'); + expect(engine.watermark(ID)).toBe('c7'); + expect(engine.size).toBe(1); + }); +}); From fb1a3452a5c39122d23abe88d883e5672a5c59db Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 12:38:43 +0200 Subject: [PATCH 08/37] fix(server): retry webhook control envelopes, bound parked deliveries --- .../server/src/ext/events/webhookEngine.ts | 136 +++++++++++++++--- .../test/ext/events/webhookEngine.test.ts | 132 ++++++++++++++++- 2 files changed, 242 insertions(+), 26 deletions(-) diff --git a/packages/server/src/ext/events/webhookEngine.ts b/packages/server/src/ext/events/webhookEngine.ts index 81e0c0f0f9..b778f55d72 100644 --- a/packages/server/src/ext/events/webhookEngine.ts +++ b/packages/server/src/ext/events/webhookEngine.ts @@ -12,7 +12,11 @@ import type { WebhookSender, WebhookSendOutcome, WebhookSubscriptionRecord, Webh // The waits between the five attempts of one message; after the last it is abandoned. const RETRY_DELAYS_MS = [5000, 30_000, 120_000, 300_000]; +// Non-2xx answers that end a message without a retry. +const FINAL_STATUSES: ReadonlySet = new Set([410, 413]); const MAX_BODY_BYTES = 262_144; +// The most messages a suspended subscription holds: as many as the emit buffer holds by default. +const MAX_PARKED_MESSAGES = 10_000; // Delivery is suspended once more than 95 % of at least 100 attempts in the last 60 minutes failed. const SUSPENSION_WINDOW_MS = 3_600_000; const SUSPENSION_MIN_ATTEMPTS = 100; @@ -40,6 +44,19 @@ interface Message { retry?: ReturnType; } +// One control body to one subscription, under one webhook-id until it is answered or abandoned; it never touches the watermark. +interface Control { + readonly record: WebhookSubscriptionRecord; + readonly webhookId: string; + readonly body: string; + // Aborts its send in flight once it is stopped. + readonly ended: AbortController; + attempts: number; + last?: WebhookSendOutcome; + retry?: ReturnType; + readonly resolve: (outcome: WebhookSendOutcome | undefined) => void; +} + // What this process holds for one subscription it delivers to. interface Tracked { readonly id: string; @@ -49,7 +66,7 @@ interface Tracked { watermark: string | null; // Messages not yet acknowledged or abandoned, in position order. readonly pending: Message[]; - // Messages that came due while delivery was suspended. + // Messages that came due while delivery was suspended, oldest first. parked: Message[]; active: boolean; lastDeliveryAt: string | null; @@ -75,6 +92,14 @@ function isSuccess(status: number): boolean { return status >= 200 && status < 300; } +function isRetryable(outcome: WebhookSendOutcome): boolean { + return 'error' in outcome || (!isSuccess(outcome.status) && !FINAL_STATUSES.has(outcome.status)); +} + +function toError(error: unknown): Error { + return error instanceof Error ? error : new Error(String(error)); +} + // The bytes of a `whsec_` secret; records and subscribe requests carry only valid ones. function signingKey(secret: string): Uint8Array { const key = parseWebhookSecret(secret); @@ -113,10 +138,11 @@ export class WebhookEngine { readonly #onerror: (error: Error) => void; readonly #now: () => number; readonly #tracked = new Map(); + readonly #controls = new Set(); // Each verified `principal\0url` with the subscription ids it covers; it lasts while one of them does. readonly #verified = new Map>(); readonly #verifiedKeyOf = new Map(); - // Aborts verification and control sends in flight on clear(). + // Aborts verification sends in flight on clear(). #lifetime = new AbortController(); constructor(options: WebhookEngineOptions) { @@ -132,7 +158,7 @@ export class WebhookEngine { return this.#tracked.size; } - // Throws `callbackEndpointError` with the failure category as `data.reason`. + // One attempt, which the subscribe call waits for; throws `callbackEndpointError` with the failure category as `data.reason`. async verify(principal: string, url: string, secret: string, subscriptionId: string): Promise { const key = `${principal}\u0000${url}`; let covered = this.#verified.get(key); @@ -140,7 +166,7 @@ export class WebhookEngine { const challenge = challengeNonce(); const body = JSON.stringify({ type: 'verification', challenge }); const webhookId = generateWebhookId('verification'); - const outcome = await this.#post(url, subscriptionId, [signingKey(secret)], webhookId, body, this.#lifetime.signal); + const outcome = await this.#post(url, subscriptionId, [secret], webhookId, body, this.#lifetime.signal); if ('error' in outcome) throw verificationError(outcome.error); if (!echoes(outcome, challenge)) throw verificationError('challenge_failed'); covered = this.#verified.get(key) ?? new Set(); @@ -156,7 +182,7 @@ export class WebhookEngine { this.#start(id, startCursor); } - // Queues one event POST and returns; `seed` is the watermark to start from when this process does not track `record.id`. + // Queues one event POST and returns; calls for one subscription come in position order, and `seed` starts the watermark of an untracked id. deliver(record: WebhookSubscriptionRecord, occurrence: EventOccurrence, position: string | null, seed: string | null): void { const tracked = this.#tracked.get(record.id) ?? this.#start(record.id, seed); const message: Message = { webhookId: generateWebhookId(), occurrence, position, attempts: 0, done: false }; @@ -164,13 +190,25 @@ export class WebhookEngine { this.#attempt(tracked, message, record); } - // One signed POST of a control body, not retried; rejects for a body over the cap. - async sendControl(record: WebhookSubscriptionRecord, body: WebhookControlBody): Promise { + // Queues a control body, retried like an event, and resolves with its last answer (`undefined` without one); request paths must not await it. + sendControl(record: WebhookSubscriptionRecord, body: WebhookControlBody): Promise { const text = JSON.stringify(body); if (byteLength(text) > MAX_BODY_BYTES) { - throw new Error(`webhook subscription ${record.id}: the ${body.type} body is over ${MAX_BODY_BYTES} bytes`); + this.#onerror(new Error(`webhook subscription ${record.id}: did not send a ${body.type} body over ${MAX_BODY_BYTES} bytes`)); + return Promise.resolve(undefined); } - return this.#post(record.url, record.id, this.#signingKeys(record), generateWebhookId(body.type), text, this.#lifetime.signal); + return new Promise(resolve => { + const control: Control = { + record, + webhookId: generateWebhookId(body.type), + body: text, + ended: new AbortController(), + attempts: 0, + resolve + }; + this.#controls.add(control); + this.#sendControl(control); + }); } watermark(id: string): string | null | undefined { @@ -196,9 +234,10 @@ export class WebhookEngine { for (const message of parked) this.#attempt(tracked, message); } - // Drops the subscription's delivery state; the last subscription of a (principal, url) also drops its verification. + // Drops the subscription's delivery state and stops its control bodies; its last subscription also drops a (principal, url) verification. forget(id: string): void { this.#drop(id); + for (const control of this.#controls) if (control.record.id === id) this.#stopControl(control); const key = this.#verifiedKeyOf.get(id); if (key === undefined) return; this.#verifiedKeyOf.delete(id); @@ -211,6 +250,7 @@ export class WebhookEngine { // Drops all in-memory state, as a process restart would. clear(): void { for (const id of this.#tracked.keys()) this.#drop(id); + for (const control of this.#controls) this.#stopControl(control); this.#verified.clear(); this.#verifiedKeyOf.clear(); this.#lifetime.abort(); @@ -250,16 +290,12 @@ export class WebhookEngine { #attempt(tracked: Tracked, message: Message, record?: WebhookSubscriptionRecord): void { this.#try(tracked, message, record).catch((error: unknown) => { if (!this.#isCurrent(tracked)) return; - this.#onerror(error instanceof Error ? error : new Error(String(error))); + this.#onerror(toError(error)); this.#retry(tracked, message); }); } async #try(tracked: Tracked, message: Message, supplied: WebhookSubscriptionRecord | undefined): Promise { - if (!tracked.active) { - tracked.parked.push(message); - return; - } message.attempts += 1; const record = supplied ?? (await this.#store.get(tracked.id)); if (!this.#isCurrent(tracked)) return; @@ -268,6 +304,12 @@ export class WebhookEngine { this.forget(tracked.id); return; } + if (!tracked.active) { + // A parked message keeps this attempt for the resume. + message.attempts -= 1; + this.#park(tracked, message); + return; + } const body = JSON.stringify({ ...message.occurrence, cursor: tracked.watermark }); if (byteLength(body) > MAX_BODY_BYTES) { this.#onerror( @@ -278,7 +320,7 @@ export class WebhookEngine { this.#settle(tracked, message); return; } - const outcome = await this.#post(record.url, record.id, this.#signingKeys(record), message.webhookId, body, tracked.ended.signal); + const outcome = await this.#post(record.url, record.id, this.#secretsOf(record), message.webhookId, body, tracked.ended.signal); if (!this.#isCurrent(tracked)) return; if (this.#observe(tracked, outcome)) this.#retry(tracked, message); else this.#settle(tracked, message); @@ -293,6 +335,13 @@ export class WebhookEngine { message.retry = unref(setTimeout(() => this.#attempt(tracked, message), delay)); } + // Holds a message until resume(); past the cap the oldest one held is abandoned. + #park(tracked: Tracked, message: Message): void { + tracked.parked.push(message); + const oldest = tracked.parked.length > MAX_PARKED_MESSAGES ? tracked.parked.shift() : undefined; + if (oldest !== undefined) this.#settle(tracked, oldest); + } + // Marks the message acknowledged or abandoned, and moves the watermark past the finished messages at the front. #settle(tracked: Tracked, message: Message): void { message.done = true; @@ -317,7 +366,7 @@ export class WebhookEngine { return false; } else { tracked.lastError = outcome.status >= 500 ? 'http_5xx' : 'http_4xx'; - if (outcome.status === 410 || outcome.status === 413) return false; + if (FINAL_STATUSES.has(outcome.status)) return false; } tracked.failedSince ??= new Date(now).toISOString(); this.#count(tracked, now, true); @@ -340,28 +389,69 @@ export class WebhookEngine { } } + // One attempt of a control body; it is signed with the record it was queued with. + #sendControl(control: Control): void { + control.attempts += 1; + const { record } = control; + this.#post(record.url, record.id, this.#secretsOf(record), control.webhookId, control.body, control.ended.signal).then( + outcome => { + if (!this.#controls.has(control)) return; + control.last = outcome; + if (isRetryable(outcome)) this.#retryControl(control); + else this.#endControl(control); + }, + (error: unknown) => { + if (!this.#controls.has(control)) return; + this.#onerror(toError(error)); + this.#retryControl(control); + } + ); + } + + #retryControl(control: Control): void { + const delay = RETRY_DELAYS_MS[control.attempts - 1]; + if (delay === undefined) this.#endControl(control); + else control.retry = unref(setTimeout(() => this.#sendControl(control), delay)); + } + + #stopControl(control: Control): void { + control.ended.abort(); + this.#endControl(control); + } + + // Resolves a control body with its last answer and drops it. + #endControl(control: Control): void { + this.#controls.delete(control); + clearTimeout(control.retry); + control.resolve(control.last); + } + // The record's secret, and its previous one during the rotation grace window. - #signingKeys(record: WebhookSubscriptionRecord): Uint8Array[] { - const keys = [signingKey(record.secret)]; + #secretsOf(record: WebhookSubscriptionRecord): string[] { const previous = record.previousSecret; - if (previous !== undefined && this.#now() < previous.expiresAt) keys.push(signingKey(previous.secret)); - return keys; + return previous !== undefined && this.#now() < previous.expiresAt ? [record.secret, previous.secret] : [record.secret]; } async #post( url: string, subscriptionId: string, - keys: readonly Uint8Array[], + secrets: readonly string[], webhookId: string, body: string, signal: AbortSignal ): Promise { const timestamp = Math.floor(this.#now() / 1000); + const signature = await signWebhook( + secrets.map(secret => signingKey(secret)), + webhookId, + timestamp, + body + ); const headers = { 'Content-Type': 'application/json', 'webhook-id': webhookId, 'webhook-timestamp': String(timestamp), - 'webhook-signature': await signWebhook(keys, webhookId, timestamp, body), + 'webhook-signature': signature, [WEBHOOK_SUBSCRIPTION_ID_HEADER]: subscriptionId }; return this.#sender({ url, headers, body, trusted: this.#trustedOrigins.has(new URL(url).origin), signal }); diff --git a/packages/server/test/ext/events/webhookEngine.test.ts b/packages/server/test/ext/events/webhookEngine.test.ts index 4f0ec06291..4c5c850b8d 100644 --- a/packages/server/test/ext/events/webhookEngine.test.ts +++ b/packages/server/test/ext/events/webhookEngine.test.ts @@ -517,6 +517,57 @@ describe('delivery status', () => { expect(engine.status(ID)).toMatchObject({ active: false }); }); + it('holds at most 10 000 messages while suspended, abandoning the oldest', async () => { + let healthy = false; + const { engine, record, requests, until } = setup(() => (healthy ? { status: 200, body: '' } : { status: 503, body: '' })); + engine.track(ID, 'p0'); + // 20 events, five failed attempts each: the 100th attempt suspends delivery as the last retries give up. + for (let n = 1; n <= 20; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await until(20); + for (const [index, delay] of DELAYS.entries()) { + await settle(); + await vi.advanceTimersByTimeAsync(delay); + await until(20 * (index + 2)); + } + await settle(); + expect(engine.status(ID)).toMatchObject({ active: false }); + expect(engine.watermark(ID)).toBe('p20'); + + for (let n = 21; n <= 10_021; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + expect(engine.watermark(ID)).toBe('p21'); + expect(requests).toHaveLength(100); + + healthy = true; + engine.resume(ID); + await until(100 + 10_000); + await settle(); + expect(requests).toHaveLength(100 + 10_000); + expect(requests.some(request => bodyOf(request).eventId === 'evt_21')).toBe(false); + expect(engine.watermark(ID)).toBe('p10021'); + }); + + it.each(['a due retry', 'a new delivery'])('releases a suspended subscription whose record expired, on %s', async path => { + const { engine, store, record, requests, until } = setup(() => ({ status: 503, body: '' })); + engine.track(ID, 'p0'); + for (let n = 1; n <= 100; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await until(100); + await settle(); + expect(engine.status(ID)).toMatchObject({ active: false }); + + const expired = { ...record, expiresAt: Date.now() + 1000 }; + await store.put(expired); + if (path === 'a due retry') await vi.advanceTimersByTimeAsync(5000); + else { + await vi.advanceTimersByTimeAsync(1000); + engine.deliver(expired, occurrence('evt_101'), 'p101', null); + } + await settle(); + expect(engine.size).toBe(0); + expect(engine.watermark(ID)).toBeUndefined(); + expect(vi.getTimerCount()).toBe(0); + expect(requests).toHaveLength(100); + }); + it('resume() does nothing for an active or unknown subscription', async () => { const { engine, record, requests, until } = setup(); engine.resume(ID); @@ -552,9 +603,84 @@ describe('control bodies', () => { } }); - it('returns a failed outcome as it is', async () => { - const { engine, record } = setup(() => ({ error: 'connection_refused' })); - expect(await engine.sendControl(record, { type: 'gap', cursor: null })).toEqual({ error: 'connection_refused' }); + it('retries a control body under one webhook-id, with a fresh timestamp and signature', async () => { + let answer: WebhookSendOutcome = { status: 503, body: '' }; + const { engine, record, requests, until } = setup(() => answer); + const outcome = engine.sendControl(record, { type: 'terminated', error: { code: -32_024, message: 'Forbidden' } }); + await until(1); + await settle(); + answer = { status: 200, body: '' }; + await vi.advanceTimersByTimeAsync(5000); + await until(2); + expect(await outcome).toEqual({ status: 200, body: '' }); + + const [first, second] = requests; + expect(second!.headers['webhook-id']).toBe(first!.headers['webhook-id']); + expect(Number(second!.headers['webhook-timestamp']) - Number(first!.headers['webhook-timestamp'])).toBe(5); + expect(second!.headers['webhook-signature']).not.toBe(first!.headers['webhook-signature']); + for (const request of requests) expect(await verifies(request, SECRET)).toBe(true); + }); + + it('resolves with the last answer once the retries run out', async () => { + const { engine, record, requests, until } = setup(() => ({ error: 'connection_refused' })); + const outcome = engine.sendControl(record, { type: 'gap', cursor: null }); + await until(1); + for (const [index, delay] of DELAYS.entries()) { + await settle(); + await vi.advanceTimersByTimeAsync(delay); + await until(index + 2); + } + expect(await outcome).toEqual({ error: 'connection_refused' }); + expect(new Set(requests.map(request => request.headers['webhook-id'])).size).toBe(1); + expect(vi.getTimerCount()).toBe(0); + }); + + it.each([410, 413])('treats %i as final for a control body', async status => { + const { engine, record, requests } = setup(() => ({ status, body: '' })); + expect(await engine.sendControl(record, { type: 'gap', cursor: 'p9' })).toEqual({ status, body: '' }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(600_000); + expect(requests).toHaveLength(1); + }); + + it('never moves the watermark or the delivery status', async () => { + const answers: Array<(outcome: WebhookSendOutcome) => void> = []; + const { engine, record, until } = setup(request => + 'type' in bodyOf(request) ? { status: 200, body: '' } : new Promise(resolve => answers.push(resolve)) + ); + await engine.sendControl(recordFor({ id: 'sub_2' }), { type: 'gap', cursor: 'p9' }); + expect(engine.size).toBe(0); + + engine.track(ID, 'p0'); + engine.deliver(record, occurrence('evt_1'), 'p1', null); + await until(2); + expect(await engine.sendControl(record, { type: 'gap', cursor: 'p9' })).toEqual({ status: 200, body: '' }); + expect(engine.watermark(ID)).toBe('p0'); + expect(engine.status(ID)).toEqual({ active: true, lastDeliveryAt: null, lastError: null }); + answers[0]!({ status: 200, body: '' }); + await settle(); + expect(engine.watermark(ID)).toBe('p1'); + }); + + it.each(['forget', 'clear'])('stops retrying a control body on %s()', async stop => { + const { engine, record, requests, until } = setup(() => ({ status: 503, body: '' })); + const outcome = engine.sendControl(record, { type: 'gap', cursor: 'p9' }); + await until(1); + await settle(); + if (stop === 'forget') engine.forget(ID); + else engine.clear(); + expect(await outcome).toEqual({ status: 503, body: '' }); + expect(requests[0]!.signal.aborted).toBe(true); + await vi.advanceTimersByTimeAsync(600_000); + expect(requests).toHaveLength(1); + }); + + it('never sends a control body over 256 KiB', async () => { + const { engine, record, sender, onerror } = setup(); + const error = { code: -32_024, message: 'Forbidden', data: { blob: 'x'.repeat(262_144) } }; + expect(await engine.sendControl(record, { type: 'terminated', error })).toBeUndefined(); + expect(sender).not.toHaveBeenCalled(); + expect((onerror.mock.calls[0]![0] as Error).message).toContain('262144'); }); }); From db1177318d77e8323907815b6ea820024382fc0e Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 13:23:27 +0200 Subject: [PATCH 09/37] feat(server): Events webhook subscriptions, InMemoryWebhookSubscriptionStore and fan-out --- packages/server/src/ext/events/extension.ts | 52 +- packages/server/src/ext/events/index.ts | 1 + packages/server/src/ext/events/push.ts | 80 +- packages/server/src/ext/events/store.ts | 31 + packages/server/src/ext/events/testHook.ts | 2 + packages/server/src/ext/events/types.ts | 5 +- packages/server/src/ext/events/validation.ts | 16 +- .../server/src/ext/events/webhookEngine.ts | 6 + .../src/ext/events/webhookSubscriptions.ts | 539 ++++++++++ packages/server/test/ext/events/poll.test.ts | 18 +- packages/server/test/ext/events/push.test.ts | 9 +- packages/server/test/ext/events/store.test.ts | 57 ++ .../test/ext/events/webhookEngine.test.ts | 25 + .../ext/events/webhookSubscriptions.test.ts | 937 ++++++++++++++++++ 14 files changed, 1723 insertions(+), 55 deletions(-) create mode 100644 packages/server/src/ext/events/store.ts create mode 100644 packages/server/src/ext/events/webhookSubscriptions.ts create mode 100644 packages/server/test/ext/events/store.test.ts create mode 100644 packages/server/test/ext/events/webhookSubscriptions.test.ts diff --git a/packages/server/src/ext/events/extension.ts b/packages/server/src/ext/events/extension.ts index 6f3a7c1d7b..cc3a1b2f44 100644 --- a/packages/server/src/ext/events/extension.ts +++ b/packages/server/src/ext/events/extension.ts @@ -8,7 +8,9 @@ import { EVENTS_UNSUBSCRIBE_METHOD, ListEventsRequestParamsSchema, PollEventsRequestParamsSchema, - StreamEventsRequestParamsSchema + StreamEventsRequestParamsSchema, + SubscribeEventsRequestParamsSchema, + UnsubscribeEventsRequestParamsSchema } from '@modelcontextprotocol/core/ext/events'; import type { ServerContext, StandardSchemaWithJSON } from '@modelcontextprotocol/core-internal'; import { scanXMcpHeaderDeclarations } from '@modelcontextprotocol/core-internal'; @@ -24,10 +26,12 @@ import { PollSource, toOccurrence } from './poll'; import { StreamSet } from './push'; import type { AnyEventDefinition, RegisteredEvent } from './registry'; import { changedSchema, deliveryModes, EventRegistry } from './registry'; +import { InMemoryWebhookSubscriptionStore } from './store'; import { installTestHook } from './testHook'; import type { CheckEventDefinition, EmitOnlyEventDefinition, EmitOnlyEventHandle, EventHandle, EventInput, EventsOptions } from './types'; +import type { SubscriptionRequest } from './validation'; import { SubscriptionValidator } from './validation'; -import { WebhookEngine } from './webhookEngine'; +import { WebhookSubscriptions } from './webhookSubscriptions'; // The live subscriptions of one delivery mode, which `remove()`, a schema change and `terminate()` end. export interface SubscriptionSource { @@ -127,8 +131,8 @@ export class EventsExtension { readonly #validator: SubscriptionValidator; readonly #poll: PollSource; readonly #push: StreamSet; - // Webhook delivery, given a sender and a store. - readonly #webhooks: WebhookEngine | undefined; + // Webhook subscriptions and delivery, in webhook mode. + readonly #webhooks: WebhookSubscriptions | undefined; // Each emitted event is handed to these after it is buffered; push and webhook delivery add theirs. readonly #fanOuts: EmitFanOut[] = []; // Clears process-memory state on a simulated restart; each delivery mode adds its own. @@ -154,7 +158,7 @@ export class EventsExtension { webhookEnabled: this.#webhookEnabled, getPrincipal: options.getPrincipal, maxSubscriptions: options.maxSubscriptions, - subscriptionCount: () => this.#poll.size + this.#push.size + subscriptionCount: () => this.#poll.size + this.#push.size + (this.#webhooks?.size ?? 0) }); this.#poll = new PollSource({ validator: this.#validator, @@ -170,17 +174,28 @@ export class EventsExtension { checkIntervalMs: options.checkIntervalMs ?? DEFAULT_CHECK_INTERVAL_MS, report: error => this.#report(error) }); - this.#webhooks = - options.webhookSender === undefined || options.webhookStore === undefined + const { webhookTtlMs, webhookSender } = options; + const webhooks = + webhookTtlMs === undefined || webhookSender === undefined ? undefined - : new WebhookEngine({ - sender: options.webhookSender, - store: options.webhookStore, + : new WebhookSubscriptions({ + validator: this.#validator, + registry: this.#registry, + buffer: this.#buffer, + sender: webhookSender, + store: options.webhookStore ?? new InMemoryWebhookSubscriptionStore(), trustedOrigins: this.#trustedOrigins, - onerror: error => this.#report(error) + webhookTtlMs, + checkIntervalMs: options.checkIntervalMs ?? DEFAULT_CHECK_INTERVAL_MS, + report: error => this.#report(error) }); + this.#webhooks = webhooks; this.#sources.push(this.#poll, this.#push); this.#fanOuts.push((name, buffered, { cursor }) => this.#push.fanOut(name, buffered, cursor)); + if (webhooks !== undefined) { + this.#sources.push(webhooks); + this.#fanOuts.push((name, buffered, positions) => webhooks.fanOut(name, buffered, positions)); + } this.#restarts.push( () => this.#buffer.clear(), () => this.#poll.clear(), @@ -198,7 +213,8 @@ export class EventsExtension { emitBuffer: this.#buffer.sizes(), pollLeases: this.#poll.size, pushStreams: this.#push.size, - webhookSubscriptions: this.#webhooks?.size ?? 0 + webhookSubscriptions: this.#webhooks?.delivering ?? 0, + webhookExpiryTimers: this.#webhooks?.size ?? 0 }), addTrustedOrigin: origin => { assertOrigin(origin); @@ -241,6 +257,12 @@ export class EventsExtension { server.setRequestHandler(EVENTS_STREAM_METHOD, { params: StreamEventsRequestParamsSchema }, (params, ctx) => this.#push.open(params, ctx) ); + server.setRequestHandler(EVENTS_SUBSCRIBE_METHOD, { params: SubscribeEventsRequestParamsSchema }, (params, ctx) => + this.#webhooks === undefined ? this.#refuseWebhook(params, ctx) : this.#webhooks.subscribe(params, ctx) + ); + server.setRequestHandler(EVENTS_UNSUBSCRIBE_METHOD, { params: UnsubscribeEventsRequestParamsSchema }, (params, ctx) => + this.#webhooks === undefined ? this.#refuseWebhook(params, ctx) : this.#webhooks.unsubscribe(params, ctx) + ); server.registerCapabilities({ extensions: { [EVENTS_EXTENSION_ID]: {} } }); markModernOnlyExtension(server, EVENTS_EXTENSION_ID); markStreamingMethod(server, EVENTS_STREAM_METHOD); @@ -309,6 +331,12 @@ export class EventsExtension { return emitOnly; } + // Without webhook mode the shared checks refuse every webhook request: the era gate, then `unsupported`. + async #refuseWebhook(params: SubscriptionRequest, ctx: ServerContext): Promise { + await this.#validator.validate('webhook', params, ctx); + throw new TypeError('webhook mode is off, yet validate() accepted a webhook request'); + } + #list(ctx: ServerContext): ListEventsResult { assertModernRequest(ctx); return { events: this.#registry.list().map(entry => this.#describe(entry)) }; diff --git a/packages/server/src/ext/events/index.ts b/packages/server/src/ext/events/index.ts index 9c162cf799..4b72c5ff0d 100644 --- a/packages/server/src/ext/events/index.ts +++ b/packages/server/src/ext/events/index.ts @@ -3,6 +3,7 @@ // Server side of the MCP Events extension (SEP-3415). export { EventsExtension } from './extension'; +export { InMemoryWebhookSubscriptionStore } from './store'; export type { CheckContext, CheckEventDefinition, diff --git a/packages/server/src/ext/events/push.ts b/packages/server/src/ext/events/push.ts index bb5c60a294..128b504e5e 100644 --- a/packages/server/src/ext/events/push.ts +++ b/packages/server/src/ext/events/push.ts @@ -27,8 +27,8 @@ import type { SubscriptionValidator } from './validation'; // The shortest heartbeat granted, whatever the client suggests (D33). const HEARTBEAT_FLOOR_MS = 5000; -// A check that throws one of these ends its streams; any other error is sent on the stream and the loop goes on. -const TERMINAL_KINDS: ReadonlySet = new Set(['forbidden', 'notFound', 'unsupported']); +// A check that throws one of these ends its subscription; any other error leaves the loop running. +export const TERMINAL_KINDS: ReadonlySet = new Set(['forbidden', 'notFound', 'unsupported']); export interface PushDeps { readonly validator: SubscriptionValidator; @@ -62,8 +62,8 @@ interface PushStream { checkTimer?: ReturnType; } -// What a stream sends next: `active` at `cursor` when one is due, then `events`, after which it is at `position`. -interface Batch { +// What a subscription sends next: its start or gap at `cursor` when one is due, then `events`, after which it is at `position`. +export interface Batch { readonly cursor: string | null; readonly truncated: boolean; readonly events: readonly EventOccurrence[]; @@ -76,8 +76,8 @@ function unref(timer: ReturnType): ReturnType, + maxAgeMs: number | undefined, + report: (error: unknown) => void +): Promise { + const { events, truncated } = await checkedEvents(entry, result, maxAgeMs, report); + const last = events.length - 1; + const cursorAt = (index: number) => (truncated || index === last ? result.cursor : from); + return { + cursor: cursorAt(-1), + truncated, + events: events.map((occurrence, index) => ({ ...occurrence, cursor: cursorAt(index) })), + position: result.cursor + }; +} + +// Where a check type starts: `null` takes the current cursor, a cursor replays the events since it first. +export async function startCheck( + entry: RegisteredEvent, + ctx: CheckContext, + args: Record, + from: string | null, + maxAgeMs: number | undefined, + report: (error: unknown) => void +): Promise { + const check = entry.definition.check!; + if (from === null) { + const { cursor } = await check(ctx, args, null); + return { cursor, truncated: false, events: [], position: cursor }; + } + const result = await check(makeContext({ ...ctx, maxAgeMs }), args, from); + return checkedBatch(entry, from, result, maxAgeMs, report); +} + // `events/stream`: one long-lived request per subscription, answered with `notifications/events/*` until it ends (SEP-3415 §Push). export class StreamSet implements SubscriptionSource { readonly #deps: PushDeps; @@ -115,7 +152,9 @@ export class StreamSet implements SubscriptionSource { } let checked: Batch | undefined; try { - if (entry.kind === 'check' && stream.stopped === undefined) checked = await this.#checkStart(stream, params); + if (entry.kind === 'check' && stream.stopped === undefined) { + checked = await startCheck(entry, stream.ctx, args, params.cursor ?? null, params.maxAgeMs, this.#deps.report); + } } catch (error) { await this.#abandon(stream); throw error; @@ -198,31 +237,6 @@ export class StreamSet implements SubscriptionSource { return stream; } - // Where a check type starts: `null` takes the current cursor, a cursor replays the events since it first. - async #checkStart(stream: PushStream, params: StreamEventsRequestParams): Promise { - const check = stream.entry.definition.check!; - const from = params.cursor ?? null; - if (from === null) { - const { cursor } = await check(stream.ctx, stream.args, null); - return { cursor, truncated: false, events: [], position: cursor }; - } - const result = await check(makeContext({ ...stream.ctx, maxAgeMs: params.maxAgeMs }), stream.args, from); - return this.#batch(stream, from, result, params.maxAgeMs); - } - - // A batch's cursors stay at `from` until its last event, so none runs ahead of an unsent event; a truncated batch carries the fresh cursor throughout. - async #batch(stream: PushStream, from: string | null, result: EventResult, maxAgeMs?: number): Promise { - const { events, truncated } = await checkedEvents(stream.entry, result, maxAgeMs, this.#deps.report); - const last = events.length - 1; - const cursorAt = (index: number) => (truncated || index === last ? result.cursor : from); - return { - cursor: cursorAt(-1), - truncated, - events: events.map((occurrence, index) => ({ ...occurrence, cursor: cursorAt(index) })), - position: result.cursor - }; - } - // Where an emit-only type starts: `null` is the buffer head, a cursor replays the buffer since it, each event at its own position. #replay(stream: PushStream, params: StreamEventsRequestParams): Batch { const { buffer, report } = this.#deps; @@ -266,7 +280,7 @@ export class StreamSet implements SubscriptionSource { const from = stream.position; try { const result = await stream.entry.definition.check!(stream.ctx, stream.args, from); - const batch = await this.#batch(stream, from, result); + const batch = await checkedBatch(stream.entry, from, result, undefined, this.#deps.report); if (!stream.live) return; this.#send(stream, batch, batch.truncated); } catch (error) { diff --git a/packages/server/src/ext/events/store.ts b/packages/server/src/ext/events/store.ts new file mode 100644 index 0000000000..d77cd7909c --- /dev/null +++ b/packages/server/src/ext/events/store.ts @@ -0,0 +1,31 @@ +import type { WebhookSubscriptionRecord, WebhookSubscriptionStore } from './types'; + +/** + * The default {@linkcode WebhookSubscriptionStore}: webhook subscriptions in + * this process's memory. They are lost on restart, and replicas do not share + * them; give replicas one shared store instead. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export class InMemoryWebhookSubscriptionStore implements WebhookSubscriptionStore { + readonly #records = new Map(); + + get(id: string): Promise { + return Promise.resolve(this.#records.get(id)); + } + + put(record: WebhookSubscriptionRecord): Promise { + this.#records.set(record.id, record); + return Promise.resolve(); + } + + delete(id: string): Promise { + return Promise.resolve(this.#records.delete(id)); + } + + async *listByName(name: string): AsyncIterable { + for (const record of this.#records.values()) if (record.name === name) yield record; + } +} diff --git a/packages/server/src/ext/events/testHook.ts b/packages/server/src/ext/events/testHook.ts index e7367f6f2d..89887cf288 100644 --- a/packages/server/src/ext/events/testHook.ts +++ b/packages/server/src/ext/events/testHook.ts @@ -13,6 +13,8 @@ export interface EventsTestState { readonly pushStreams: number; // Webhook subscriptions this process holds delivery state (watermark, status, retries) for. readonly webhookSubscriptions: number; + // Webhook subscriptions this process watches with an expiry timer (and a check type's loop), after handling their subscribe or refresh. + readonly webhookExpiryTimers: number; } // Internal controls for tests and the conformance fixture; never part of the public API or its declarations. diff --git a/packages/server/src/ext/events/types.ts b/packages/server/src/ext/events/types.ts index 2ba8577f0f..4148a82460 100644 --- a/packages/server/src/ext/events/types.ts +++ b/packages/server/src/ext/events/types.ts @@ -285,7 +285,10 @@ export interface EventsOptions { checkIntervalMs?: number; /** The `nextPollMs` sent when `check` gives none. */ defaultNextPollMs?: number; - /** The most subscriptions served at once; more are refused with `resourceExhausted`. */ + /** + * The most subscriptions this process serves at once, counting poll leases, push streams and the webhook + * subscriptions whose subscribe or refresh it handled; more are refused with `resourceExhausted`. + */ maxSubscriptions?: number; /** Receives errors nothing else can report (dropped payloads, hook failures, invalid `x-mcp-header` annotations). Default: `console.warn`. */ onerror?: (error: Error) => void; diff --git a/packages/server/src/ext/events/validation.ts b/packages/server/src/ext/events/validation.ts index b1fb004450..812d17f5d8 100644 --- a/packages/server/src/ext/events/validation.ts +++ b/packages/server/src/ext/events/validation.ts @@ -11,10 +11,14 @@ export interface ValidatorDeps { readonly webhookEnabled: boolean; readonly getPrincipal: EventsOptions['getPrincipal']; readonly maxSubscriptions: number | undefined; - // Subscriptions served now, across every delivery mode. + // Subscriptions this process serves now: poll leases, push streams, and the webhook subscriptions whose subscribe or refresh it handled. subscriptionCount(): number; } +function notOffered(message: string, mode: DeliveryMode): EventsError { + return new EventsError('unsupported', message, { feature: 'deliveryMode', value: mode }); +} + export interface SubscriptionRequest { readonly name: string; readonly arguments?: Record; @@ -34,7 +38,7 @@ export class SubscriptionValidator { this.#deps = deps; } - // Era gate, principal, event exists, mode offered, `beforeParse` (poll: a terminated lease), then the arguments. + // Era gate, webhook mode (webhook only), principal (required for webhook), event exists, mode offered, `beforeParse`, then the arguments. async validate( mode: DeliveryMode, params: SubscriptionRequest, @@ -42,13 +46,13 @@ export class SubscriptionValidator { beforeParse?: (principal: string | null, rawArgs: Record) => void ): Promise { assertModernRequest(ctx); + const webhook = mode === 'webhook'; + if (webhook && !this.#deps.webhookEnabled) throw notOffered('This server does not offer webhook delivery', mode); const principal = (await this.#deps.getPrincipal?.(ctx)) ?? null; + if (webhook && principal === null) throw new EventsError('forbidden', 'Webhook subscriptions need an authenticated principal'); const entry = this.#deps.registry.require(params.name); if (!entry.modes(this.#deps.webhookEnabled).includes(mode)) { - throw new EventsError('unsupported', `Event type ${params.name} does not offer ${mode} delivery`, { - feature: 'deliveryMode', - value: mode - }); + throw notOffered(`Event type ${params.name} does not offer ${mode} delivery`, mode); } const rawArgs = params.arguments ?? {}; beforeParse?.(principal, rawArgs); diff --git a/packages/server/src/ext/events/webhookEngine.ts b/packages/server/src/ext/events/webhookEngine.ts index b778f55d72..c3ad39a061 100644 --- a/packages/server/src/ext/events/webhookEngine.ts +++ b/packages/server/src/ext/events/webhookEngine.ts @@ -215,6 +215,12 @@ export class WebhookEngine { return this.#tracked.get(id)?.watermark; } + // Moves the watermark to `position` when no message is pending, so a quiet upstream still advances it; it never passes an unsettled message. + advance(id: string, position: string | null): void { + const tracked = this.#tracked.get(id); + if (tracked !== undefined && tracked.pending.length === 0) tracked.watermark = position; + } + status(id: string): DeliveryStatus | undefined { const tracked = this.#tracked.get(id); if (tracked === undefined) return undefined; diff --git a/packages/server/src/ext/events/webhookSubscriptions.ts b/packages/server/src/ext/events/webhookSubscriptions.ts new file mode 100644 index 0000000000..f20c3d45be --- /dev/null +++ b/packages/server/src/ext/events/webhookSubscriptions.ts @@ -0,0 +1,539 @@ +import type { + SubscribeEventsRequestParams, + SubscribeEventsResult, + UnsubscribeEventsRequestParams, + UnsubscribeEventsResult +} from '@modelcontextprotocol/core/ext/events'; +import type { ServerContext } from '@modelcontextprotocol/core-internal'; +import { canonicalJson, EventsError, parseWebhookSecret } from '@modelcontextprotocol/core-internal/ext/events'; + +import { makeContext } from './context'; +import type { BufferedEvent, EmitBuffer } from './emitBuffer'; +import type { SubscriptionSource } from './extension'; +import { selectEvent } from './poll'; +import type { Batch } from './push'; +import { checkedBatch, errorObject, startCheck, TERMINAL_KINDS } from './push'; +import type { EventRegistry, RegisteredEvent } from './registry'; +import type { CheckContext, WebhookSender, WebhookSubscriptionRecord, WebhookSubscriptionStore } from './types'; +import type { SubscriptionValidator, ValidSubscription } from './validation'; +import { WebhookEngine } from './webhookEngine'; + +// The shortest TTL granted, whatever the client suggests. +const TTL_FLOOR_MS = 60_000; +// How long deliveries stay signed with the previous secret too after a rotation. +const ROTATION_GRACE_MS = 300_000; +// setTimeout fires at once for longer delays; a longer grant re-arms when the timer fires early. +const MAX_TIMER_DELAY_MS = 2 ** 31 - 1; + +const encoder = new TextEncoder(); +// The `signal` of callbacks for a stored subscription this process does not watch. +const UNWATCHED = new AbortController().signal; + +export interface WebhookDeps { + readonly validator: SubscriptionValidator; + readonly registry: EventRegistry; + readonly buffer: EmitBuffer; + readonly sender: WebhookSender; + readonly store: WebhookSubscriptionStore; + // Read at every subscribe and send, so origins added later count. + readonly trustedOrigins: ReadonlySet; + // The longest TTL granted. + readonly webhookTtlMs: number; + readonly checkIntervalMs: number; + report(error: unknown): void; +} + +// What this process runs for a subscription whose subscribe or refresh it handled: the expiry timer, and a check type's loop. +interface Watched { + readonly id: string; + // The registration it serves, so onUnsubscribe pairs with it after a removal or re-registration. + readonly entry: RegisteredEvent; + // Aborts when this process stops serving the subscription; the `signal` of its callbacks. + readonly ended: AbortController; + readonly ctx: CheckContext; + expiry?: ReturnType; + // A check type's loop: the position checked up to, and the next check. + position: string | null; + checkTimer?: ReturnType; +} + +// A subscribe request in flight for one id, from the id's derivation until it answers. +interface Subscribing { + readonly id: string; + readonly name: string; + // A termination that reached it meanwhile, which the request applies before or after its write. + terminated?: EventsError; +} + +type Queues = Map>; + +// Takes the termination that reached a subscribe in flight, so it is applied once. +function takeTermination(subscribing: Subscribing): EventsError | undefined { + const { terminated } = subscribing; + subscribing.terminated = undefined; + return terminated; +} + +// Timers never keep the process alive on their own. +function unref(timer: ReturnType): ReturnType { + (timer as { unref?: () => void }).unref?.(); + return timer; +} + +// Runs `task` once the tasks queued before it under `key` have settled. +function enqueue(queues: Queues, key: string, task: () => Promise): Promise { + const run = (queues.get(key) ?? Promise.resolve()).then(task); + const settled = run.then( + () => {}, + () => {} + ); + queues.set(key, settled); + void settled.then(() => { + if (queues.get(key) === settled) queues.delete(key); + }); + return run; +} + +function isExpired(record: WebhookSubscriptionRecord): boolean { + return record.expiresAt <= Date.now(); +} + +// No suggestion or `null` gets the cap; a suggestion is clamped up to the floor and down to the cap. +function grantMs(ttlMs: number | null | undefined, maxMs: number): number { + return ttlMs === undefined || ttlMs === null ? maxMs : Math.min(maxMs, Math.max(TTL_FLOOR_MS, ttlMs)); +} + +// `sub_` and 22 base64url characters of the SHA-256 of the canonical key, so every replica derives the same id. +async function subscriptionIdOf(principal: string, url: string, name: string, args: Record): Promise { + const digest = await globalThis.crypto.subtle.digest('SHA-256', encoder.encode(canonicalJson([principal, url, name, args]))); + let binary = ''; + for (const byte of new Uint8Array(digest)) binary += String.fromCodePoint(byte); + return `sub_${btoa(binary).replaceAll('+', '-').replaceAll('/', '_').slice(0, 22)}`; +} + +function notFound(): EventsError { + return new EventsError('notFound', 'Subscription not found', { kind: 'subscription' }); +} + +// `events/subscribe` and `events/unsubscribe`: webhook subscriptions in the store, their expiry and check loops, the emit fan-out and termination (SEP-3415 §Webhook-Based Delivery). +export class WebhookSubscriptions implements SubscriptionSource { + readonly #deps: WebhookDeps; + readonly #engine: WebhookEngine; + readonly #watched = new Map(); + // Subscribe, unsubscribe and expiry of one subscription run one at a time in this process; termination does not queue, so a hook that terminates never waits on itself. + readonly #byId: Queues = new Map(); + // Subscribes in flight: a termination that reaches one is applied by it, never stored over. Replicas can still race: the store has no compare-and-set (§5.9). + readonly #subscribing = new Set(); + // The fan-out of one event type runs one emit at a time, so each subscription's deliveries reach the engine in position order. + readonly #byName: Queues = new Map(); + + constructor(deps: WebhookDeps) { + this.#deps = deps; + this.#engine = new WebhookEngine({ + sender: deps.sender, + store: deps.store, + trustedOrigins: deps.trustedOrigins, + onerror: error => deps.report(error) + }); + } + + // Subscriptions this process watches (an expiry timer each), after handling their subscribe or refresh. + get size(): number { + return this.#watched.size; + } + + // Subscriptions this process holds delivery state for. + get delivering(): number { + return this.#engine.size; + } + + async subscribe(params: SubscribeEventsRequestParams, ctx: ServerContext): Promise { + const { url, secret } = params.delivery; + const valid = await this.#deps.validator.validate('webhook', params, ctx, () => { + this.#assertCallback(url); + if (parseWebhookSecret(secret) === undefined) { + throw new EventsError('invalidParams', 'delivery.secret must be whsec_ followed by base64 of 24 to 64 bytes'); + } + }); + // validate('webhook', …) refuses a request without a principal. + const id = await subscriptionIdOf(valid.principal!, url, valid.entry.name, valid.args); + const ttl = grantMs(params.ttlMs, this.#deps.webhookTtlMs); + const subscribing: Subscribing = { id, name: valid.entry.name }; + this.#subscribing.add(subscribing); + try { + return await enqueue(this.#byId, id, async () => { + const existing = await this.#unexpired(id); + return existing === undefined + ? this.#create(id, valid, params, ttl, subscribing) + : this.#refresh(existing, valid.entry, params, ttl, subscribing); + }); + } finally { + this.#subscribing.delete(subscribing); + // A termination this request did not apply, because it failed or answered first, is applied now. + const left = takeTermination(subscribing); + if (left !== undefined) await this.#end(id, subscribing.name, left).catch((error: unknown) => this.#deps.report(error)); + } + } + + async unsubscribe(params: UnsubscribeEventsRequestParams, ctx: ServerContext): Promise { + const { entry, principal, args } = await this.#deps.validator.validate('webhook', params, ctx); + const id = await subscriptionIdOf(principal!, params.delivery.url, entry.name, args); + return enqueue(this.#byId, id, async () => { + const record = await this.#unexpired(id); + if (record === undefined || !(await this.#deps.store.delete(id))) throw notFound(); + const watched = this.#watched.get(id); + this.#release(id); + await this.#unsubscribed(record, watched); + return {}; + }); + } + + // Hands an emitted event to the engine for each matching stored subscription, after the earlier emits of its type; it never waits on a receiver. + fanOut(name: string, buffered: BufferedEvent, { cursor, previous }: { cursor: string; previous: string }): void { + const entry = this.#deps.registry.get(name); + if (entry === undefined) return; + enqueue(this.#byName, name, () => this.#deliverEmitted(entry, buffered, cursor, previous)).catch((error: unknown) => + this.#deps.report(error) + ); + } + + // Sends a `terminated` envelope to each matching subscription in the store, deletes it and runs onUnsubscribe. + async terminate(name: string, error: EventsError, subscriptionId?: string): Promise { + const ids = new Set(); + if (subscriptionId === undefined) { + for await (const record of this.#deps.store.listByName(name)) ids.add(record.id); + // Subscribes still in flight end too, as push ends the streams still starting. + for (const subscribing of this.#subscribing) if (subscribing.name === name) ids.add(subscribing.id); + } else { + ids.add(subscriptionId); + } + await Promise.all([...ids].map(id => this.#end(id, name, error))); + } + + // Drops what this process holds, without onUnsubscribe, as a process restart would; the store keeps its records. + clear(): void { + for (const watched of this.#watched.values()) this.#stop(watched); + this.#watched.clear(); + this.#subscribing.clear(); + this.#engine.clear(); + } + + // An absolute `https` URL, or one whose exact origin is trusted. + #assertCallback(url: string): void { + let parsed: URL | undefined; + try { + parsed = new URL(url); + } catch { + parsed = undefined; + } + if (parsed !== undefined && (parsed.protocol === 'https:' || this.#deps.trustedOrigins.has(parsed.origin))) return; + throw new EventsError('invalidParams', 'delivery.url must be an absolute https URL, or one whose origin is in trustedOrigins'); + } + + // Quota, verification and onSubscribe, then the start position, tracked before the record is stored; a termination meanwhile fails it. + async #create( + id: string, + valid: ValidSubscription, + params: SubscribeEventsRequestParams, + ttl: number, + subscribing: Subscribing + ): Promise { + const { entry, args } = valid; + const principal = valid.principal!; + const { url, secret } = params.delivery; + // A watch left over here belongs to a subscription that ended elsewhere: its record is gone. + this.#release(id); + this.#deps.validator.assertCapacity(); + await this.#engine.verify(principal, url, secret, id); + const watched = this.#watch(id, entry, principal); + try { + await entry.definition.onSubscribe?.(watched.ctx, args); + } catch (error) { + watched.ended.abort(); + this.#engine.forget(id); + throw error; + } + const from = params.cursor ?? null; + const now = Date.now(); + const record: WebhookSubscriptionRecord = { + id, + principal, + name: entry.name, + arguments: args, + url, + secret, + expiresAt: now + ttl, + createdAt: now + }; + let start: Batch; + try { + start = + entry.kind === 'check' + ? await this.#startCheck(record, watched, from, params.maxAgeMs, subscribing) + : await enqueue(this.#byName, entry.name, () => this.#startEmitOnly(record, from, subscribing)); + const terminated = takeTermination(subscribing); + if (terminated !== undefined) { + await this.#deps.store.delete(id); + throw terminated; + } + } catch (error) { + watched.ended.abort(); + this.#engine.forget(id); + await this.#unsubscribed(record, watched); + throw error; + } + this.#watched.set(id, watched); + this.#arm(watched, record.expiresAt); + this.#send(record, start, start.cursor); + if (entry.kind === 'check') { + watched.position = start.position; + this.#schedule(watched); + } + return { id, refreshBefore: new Date(record.expiresAt).toISOString(), cursor: start.cursor, truncated: start.truncated }; + } + + async #startCheck( + record: WebhookSubscriptionRecord, + watched: Watched, + from: string | null, + maxAgeMs: number | undefined, + subscribing: Subscribing + ): Promise { + const start = await startCheck(watched.entry, watched.ctx, record.arguments, from, maxAgeMs, this.#deps.report); + const terminated = takeTermination(subscribing); + if (terminated !== undefined) throw terminated; + this.#engine.track(record.id, start.cursor); + await this.#deps.store.put(record); + return start; + } + + // Runs in line with the fan-out: an emit either comes before the head read here or finds the stored record. Nothing is replayed. + async #startEmitOnly(record: WebhookSubscriptionRecord, from: string | null, subscribing: Subscribing): Promise { + const terminated = takeTermination(subscribing); + if (terminated !== undefined) throw terminated; + const head = this.#deps.buffer.head(record.name); + this.#engine.track(record.id, head); + await this.#deps.store.put(record); + return { cursor: head, truncated: from !== null && from !== head, events: [], position: head }; + } + + // A new grant and a rotated secret; the client's cursor seeds the watermark only where this process tracks none. + async #refresh( + record: WebhookSubscriptionRecord, + entry: RegisteredEvent, + params: SubscribeEventsRequestParams, + ttl: number, + subscribing: Subscribing + ): Promise { + const { id } = record; + const now = Date.now(); + const { secret } = params.delivery; + const rotated = + secret === record.secret ? {} : { secret, previousSecret: { secret: record.secret, expiresAt: now + ROTATION_GRACE_MS } }; + const refreshed: WebhookSubscriptionRecord = { ...record, ...rotated, expiresAt: now + ttl }; + await this.#endIfTerminated(subscribing, record); + await this.#deps.store.put(refreshed); + await this.#endIfTerminated(subscribing, refreshed); + // Read before resume(), so a suspension shows as `active: false` on the refresh that ends it. + const deliveryStatus = this.#engine.status(id); + const from = params.cursor ?? null; + if (this.#engine.watermark(id) === undefined) this.#engine.track(id, from); + this.#engine.resume(id); + this.#keep(refreshed, entry, from); + return { + id, + refreshBefore: new Date(refreshed.expiresAt).toISOString(), + cursor: this.#engine.watermark(id) ?? null, + truncated: false, + ...(deliveryStatus === undefined ? {} : { deliveryStatus }) + }; + } + + // Re-arms a refreshed subscription's timer, or starts watching it here (a check type's loop from `from`) when this process had not. + #keep(record: WebhookSubscriptionRecord, entry: RegisteredEvent, from: string | null): void { + let watched = this.#watched.get(record.id); + if (watched === undefined) { + watched = this.#watch(record.id, entry, record.principal); + watched.position = from; + this.#watched.set(record.id, watched); + if (entry.kind === 'check') this.#schedule(watched); + } + this.#arm(watched, record.expiresAt); + } + + #watch(id: string, entry: RegisteredEvent, principal: string): Watched { + const ended = new AbortController(); + const ctx = makeContext({ name: entry.name, subscriptionId: id, principal, mode: 'webhook', signal: ended.signal }); + return { id, entry, ended, ctx, position: null }; + } + + #arm(watched: Watched, expiresAt: number): void { + clearTimeout(watched.expiry); + const delay = Math.min(Math.max(expiresAt - Date.now(), 0), MAX_TIMER_DELAY_MS); + watched.expiry = unref(setTimeout(() => this.#later(watched.id, () => this.#recheck(watched.id)), delay)); + } + + // Queues a task for one subscription off the caller's path; a failure goes to onerror. + #later(id: string, task: () => Promise): void { + enqueue(this.#byId, id, task).catch((error: unknown) => this.#deps.report(error)); + } + + // The stored record, after expiring it if its grant passed. + async #unexpired(id: string): Promise { + const record = await this.#deps.store.get(id); + if (record === undefined || !isExpired(record)) return record; + await this.#expire(record); + return undefined; + } + + // Reads the record again: gone ends what this process runs for it, a later expiry re-arms the timer, a passed one expires it. + async #recheck(id: string): Promise { + const record = await this.#deps.store.get(id); + if (record === undefined) { + this.#release(id); + return; + } + if (isExpired(record)) { + await this.#expire(record); + return; + } + const watched = this.#watched.get(id); + if (watched !== undefined) this.#arm(watched, record.expiresAt); + } + + // onUnsubscribe runs only after a delete that removed the record, so once per subscription. + async #expire(record: WebhookSubscriptionRecord): Promise { + const deleted = await this.#deps.store.delete(record.id); + const watched = this.#watched.get(record.id); + this.#release(record.id); + if (deleted) await this.#unsubscribed(record, watched); + } + + // Ends one subscription of event type `name` with `error`: delete, a `terminated` envelope, onUnsubscribe. + async #end(id: string, name: string, error: EventsError): Promise { + // A subscribe in flight for it applies the termination itself, so it never stores what this ended. + let deferred = false; + for (const subscribing of this.#subscribing) { + if (subscribing.id !== id || subscribing.name !== name) continue; + subscribing.terminated ??= error; + deferred = true; + } + if (deferred) return; + const record = await this.#deps.store.get(id); + if (record?.name !== name) return; + if (isExpired(record)) { + await this.#expire(record); + return; + } + await this.#endStored(record, error); + } + + // A termination that reached this refresh ends `record`, and the refresh answers with its error. + async #endIfTerminated(subscribing: Subscribing, record: WebhookSubscriptionRecord): Promise { + const terminated = takeTermination(subscribing); + if (terminated === undefined) return; + await this.#endStored(record, terminated); + throw terminated; + } + + // Only the process whose delete removed the record sends the envelope and runs onUnsubscribe. + async #endStored(record: WebhookSubscriptionRecord, error: EventsError): Promise { + if (!(await this.#deps.store.delete(record.id))) return; + const watched = this.#watched.get(record.id); + // Forget first: forget() stops the control bodies queued before it. + this.#release(record.id); + void this.#engine.sendControl(record, { type: 'terminated', error: errorObject(error) }); + await this.#unsubscribed(record, watched); + } + + // Stops what this process runs for the subscription and drops its delivery state. + #release(id: string): void { + const watched = this.#watched.get(id); + if (watched !== undefined) { + this.#watched.delete(id); + this.#stop(watched); + } + this.#engine.forget(id); + } + + #stop(watched: Watched): void { + watched.ended.abort(); + clearTimeout(watched.expiry); + clearTimeout(watched.checkTimer); + } + + async #unsubscribed(record: WebhookSubscriptionRecord, watched: Watched | undefined): Promise { + const entry = watched?.entry ?? this.#deps.registry.get(record.name); + const ctx = watched?.ctx ?? this.#contextOf(record, AbortSignal.abort()); + try { + await entry?.definition.onUnsubscribe?.(ctx, record.arguments); + } catch (error) { + this.#deps.report(error); + } + } + + #contextOf(record: WebhookSubscriptionRecord, signal: AbortSignal): CheckContext { + return makeContext({ name: record.name, subscriptionId: record.id, principal: record.principal, mode: 'webhook', signal }); + } + + async #deliverEmitted(entry: RegisteredEvent, buffered: BufferedEvent, cursor: string, previous: string): Promise { + for await (const record of this.#recordsFor(entry.name, buffered.target)) { + if (isExpired(record)) { + this.#later(record.id, () => this.#recheck(record.id)); + continue; + } + const ctx = this.#watched.get(record.id)?.ctx ?? this.#contextOf(record, UNWATCHED); + const occurrence = selectEvent(entry, ctx, record.arguments, buffered, this.#deps.report); + if (occurrence !== undefined) this.#engine.deliver(record, occurrence, cursor, previous); + } + } + + // Every stored subscription of the type, or only the target of a targeted emit. + async *#recordsFor(name: string, target: string | undefined): AsyncIterable { + if (target === undefined) { + yield* this.#deps.store.listByName(name); + return; + } + const record = await this.#deps.store.get(target); + if (record?.name === name) yield record; + } + + #send(record: WebhookSubscriptionRecord, batch: Batch, seed: string | null): void { + for (const event of batch.events) this.#engine.deliver(record, event, event.cursor ?? null, seed); + } + + #schedule(watched: Watched): void { + watched.checkTimer = unref(setTimeout(() => void this.#check(watched), this.#deps.checkIntervalMs)); + } + + // One run of a check type's loop: the events since the last run, and a `gap` envelope for a truncated result. + async #check(watched: Watched): Promise { + const { id, entry } = watched; + const from = watched.position; + try { + const record = await this.#deps.store.get(id); + if (this.#watched.get(id) !== watched) return; + if (record === undefined || isExpired(record)) { + // The expiry path decides; it stops this loop unless the record was refreshed meanwhile. + this.#later(id, () => this.#recheck(id)); + } else { + const result = await entry.definition.check!(watched.ctx, record.arguments, from); + const batch = await checkedBatch(entry, from, result, undefined, this.#deps.report); + if (this.#watched.get(id) !== watched) return; + if (batch.truncated) void this.#engine.sendControl(record, { type: 'gap', cursor: batch.cursor }); + this.#send(record, batch, from); + // A quiet batch moves the watermark to the upstream cursor once nothing awaits an answer, so the refresh cursor advances. + if (batch.events.length === 0) this.#engine.advance(id, batch.position); + watched.position = batch.position; + } + } catch (error) { + if (this.#watched.get(id) !== watched) return; + if (error instanceof EventsError && TERMINAL_KINDS.has(error.kind)) { + this.#end(id, entry.name, error).catch((error_: unknown) => this.#deps.report(error_)); + return; + } + this.#deps.report(error); + } + this.#schedule(watched); + } +} diff --git a/packages/server/test/ext/events/poll.test.ts b/packages/server/test/ext/events/poll.test.ts index ba615fbf36..dd3b4d614c 100644 --- a/packages/server/test/ext/events/poll.test.ts +++ b/packages/server/test/ext/events/poll.test.ts @@ -528,10 +528,24 @@ describe('test hook', () => { const { poll } = poller(events); const { cursor: c0 } = await poll({ name: 'i', cursor: null }); await h.emit({ data: { n: 1 } }); - expect(hook.state()).toEqual({ trustedOrigins: [], emitBuffer: { i: 1 }, pollLeases: 1, pushStreams: 0, webhookSubscriptions: 0 }); + expect(hook.state()).toEqual({ + trustedOrigins: [], + emitBuffer: { i: 1 }, + pollLeases: 1, + pushStreams: 0, + webhookSubscriptions: 0, + webhookExpiryTimers: 0 + }); hook.restart(); - expect(hook.state()).toEqual({ trustedOrigins: [], emitBuffer: {}, pollLeases: 0, pushStreams: 0, webhookSubscriptions: 0 }); + expect(hook.state()).toEqual({ + trustedOrigins: [], + emitBuffer: {}, + pollLeases: 0, + pushStreams: 0, + webhookSubscriptions: 0, + webhookExpiryTimers: 0 + }); const after = await poll({ name: 'i', cursor: c0 }); expect(after).toMatchObject({ events: [], truncated: true, hasMore: false }); expect(after.cursor).not.toBe(c0); diff --git a/packages/server/test/ext/events/push.test.ts b/packages/server/test/ext/events/push.test.ts index 27a4e55247..09925c0c0b 100644 --- a/packages/server/test/ext/events/push.test.ts +++ b/packages/server/test/ext/events/push.test.ts @@ -496,7 +496,14 @@ describe('events/stream: termination', () => { const stream = await open(serve(events), { name: 'i', cursor: null }); await next(stream); const hook = testHook(events); - expect(hook.state()).toEqual({ trustedOrigins: [], emitBuffer: {}, pollLeases: 0, pushStreams: 1, webhookSubscriptions: 0 }); + expect(hook.state()).toEqual({ + trustedOrigins: [], + emitBuffer: {}, + pollLeases: 0, + pushStreams: 1, + webhookSubscriptions: 0, + webhookExpiryTimers: 0 + }); hook.restart(); expect(onUnsubscribe).toHaveBeenCalledOnce(); expect(await rest(stream)).toEqual([finalResult(stream.id)]); diff --git a/packages/server/test/ext/events/store.test.ts b/packages/server/test/ext/events/store.test.ts new file mode 100644 index 0000000000..ae3ec9ec8c --- /dev/null +++ b/packages/server/test/ext/events/store.test.ts @@ -0,0 +1,57 @@ +import { describe, expect, it } from 'vitest'; + +import type { WebhookSubscriptionRecord } from '../../../src/ext/events/index'; +import { InMemoryWebhookSubscriptionStore } from '../../../src/ext/events/index'; + +function recordFor(id: string, name = 'e'): WebhookSubscriptionRecord { + return { + id, + principal: 'u1', + name, + arguments: { a: 1 }, + url: 'https://hooks.example.com/mcp', + secret: 'whsec_c2VjcmV0LXNlY3JldC1zZWNyZXQtc2VjcmV0', + expiresAt: 2_000_000_000_000, + createdAt: 1_900_000_000_000 + }; +} + +async function listed(store: InMemoryWebhookSubscriptionStore, name: string): Promise { + const ids: string[] = []; + for await (const record of store.listByName(name)) ids.push(record.id); + return ids; +} + +describe('InMemoryWebhookSubscriptionStore', () => { + it('round-trips put, get and delete', async () => { + const store = new InMemoryWebhookSubscriptionStore(); + const record = recordFor('sub_1'); + await store.put(record); + expect(await store.get('sub_1')).toEqual(record); + + const refreshed = { ...record, expiresAt: record.expiresAt + 1 }; + await store.put(refreshed); + expect(await store.get('sub_1')).toEqual(refreshed); + + expect(await store.delete('sub_1')).toBe(true); + expect(await store.get('sub_1')).toBeUndefined(); + }); + + it('lists only the records of one event name', async () => { + const store = new InMemoryWebhookSubscriptionStore(); + await store.put(recordFor('sub_1', 'e')); + await store.put(recordFor('sub_2', 'other')); + await store.put(recordFor('sub_3', 'e')); + expect(await listed(store, 'e')).toEqual(['sub_1', 'sub_3']); + expect(await listed(store, 'other')).toEqual(['sub_2']); + expect(await listed(store, 'missing')).toEqual([]); + }); + + it('answers false when deleting an unknown id', async () => { + const store = new InMemoryWebhookSubscriptionStore(); + expect(await store.delete('sub_missing')).toBe(false); + await store.put(recordFor('sub_1')); + expect(await store.delete('sub_1')).toBe(true); + expect(await store.delete('sub_1')).toBe(false); + }); +}); diff --git a/packages/server/test/ext/events/webhookEngine.test.ts b/packages/server/test/ext/events/webhookEngine.test.ts index 4c5c850b8d..d88243894d 100644 --- a/packages/server/test/ext/events/webhookEngine.test.ts +++ b/packages/server/test/ext/events/webhookEngine.test.ts @@ -317,6 +317,31 @@ describe('event delivery', () => { expect(bodyOf(requests[4]!).cursor).toBe('p3'); }); + it('advance() moves an idle watermark, and is ignored while a message is pending', async () => { + let answer: WebhookSendOutcome = { status: 500, body: '' }; + const { engine, record, requests, until } = setup(() => answer); + engine.advance(ID, 'p9'); + expect(engine.watermark(ID)).toBeUndefined(); + engine.track(ID, 'p0'); + engine.advance(ID, 'p1'); + expect(engine.watermark(ID)).toBe('p1'); + + engine.deliver(record, occurrence('evt_2'), 'p2', null); + await until(1); + await settle(); + engine.advance(ID, 'p5'); + expect(engine.watermark(ID)).toBe('p1'); + + answer = { status: 200, body: '' }; + await vi.advanceTimersByTimeAsync(5000); + await until(2); + await settle(); + expect(engine.watermark(ID)).toBe('p2'); + expect(bodyOf(requests[1]!).cursor).toBe('p1'); + engine.advance(ID, 'p5'); + expect(engine.watermark(ID)).toBe('p5'); + }); + it('tracks an unknown subscription from the seed, so every POST carries a cursor (F3a)', async () => { const { engine, record, requests, until } = setup(); expect(engine.watermark(ID)).toBeUndefined(); diff --git a/packages/server/test/ext/events/webhookSubscriptions.test.ts b/packages/server/test/ext/events/webhookSubscriptions.test.ts new file mode 100644 index 0000000000..ec59bf1e5e --- /dev/null +++ b/packages/server/test/ext/events/webhookSubscriptions.test.ts @@ -0,0 +1,937 @@ +import { createHash } from 'node:crypto'; + +import { generateWebhookSecret, parseWebhookSecret, verifyWebhookSignature } from '@modelcontextprotocol/core-internal/ext/events'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import * as z from 'zod/v4'; + +import type { + CheckContext, + EventContext, + EventResult, + EventsOptions, + ListEventsResult, + PollEventsResult, + SubscribeEventsResult, + WebhookSendOutcome, + WebhookSendRequest, + WebhookSubscriptionRecord +} from '../../../src/ext/events/index'; +import { EventsError, EventsExtension, InMemoryWebhookSubscriptionStore } from '../../../src/ext/events/index'; +import type { EventsTestHook } from '../../../src/ext/events/testHook'; +import { errorOf, resultOf, serve } from './harness'; + +const P = z.object({ n: z.number() }); +const HOOK = 'https://hooks.example.com/mcp'; +const OTHER_HOOK = 'https://other.example.com/hook'; +const SECRET = generateWebhookSecret(); +const SUB_ID = /^sub_[\w-]{22}$/; +const UNSUPPORTED = { code: -32_026, data: { feature: 'deliveryMode', value: 'webhook' } }; + +type Respond = (request: WebhookSendRequest) => WebhookSendOutcome | Promise; +type Check = (ctx: CheckContext, args: Record, cursor: string | null) => EventResult<{ n: number }>; + +interface SubscribeInput { + name?: string; + arguments?: Record; + url?: string; + secret?: string; + cursor?: string | null; + ttlMs?: number | null; + maxAgeMs?: number; +} + +const getPrincipal: EventsOptions['getPrincipal'] = ctx => (ctx.http?.authInfo?.extra?.sub as string | undefined) ?? null; + +function testHook(events: EventsExtension): EventsTestHook { + return (events as unknown as Record)[Symbol.for('mcp.events.testHook')]!; +} + +function bodyOf(request: WebhookSendRequest): Record { + return JSON.parse(request.body) as Record; +} + +function isVerification(request: WebhookSendRequest): boolean { + return bodyOf(request).type === 'verification'; +} + +// Echoes a verification challenge, and answers anything else with `answer()`. +function echo(answer: () => WebhookSendOutcome = () => ({ status: 200, body: '' })): Respond { + return request => { + const body = bodyOf(request); + return body.type === 'verification' ? { status: 200, body: JSON.stringify({ challenge: body.challenge }) } : answer(); + }; +} + +// A sender that records each request and answers with `respond`; signing runs off the fake clock, so tests wait with `until`. +function receiver(respond: Respond) { + const requests: WebhookSendRequest[] = []; + const waiters: Array<{ count: number; resolve(): void }> = []; + const sender = (request: WebhookSendRequest): Promise => { + requests.push(request); + for (const waiter of waiters) if (requests.length >= waiter.count) waiter.resolve(); + return Promise.resolve(respond(request)); + }; + const until = (count: number): Promise => + new Promise(resolve => { + if (requests.length >= count) resolve(); + else waiters.push({ count, resolve }); + }); + return { sender, requests, until, deliveries: () => requests.filter(request => !isVerification(request)) }; +} + +const extensions: EventsExtension[] = []; + +// One server process in webhook mode, with its own recording sender. +function replica(options: Partial & { respond?: Respond } = {}) { + const { respond = echo(), ...rest } = options; + const post = receiver(respond); + const events = new EventsExtension({ webhookTtlMs: 1_800_000, webhookSender: post.sender, getPrincipal, ...rest }); + extensions.push(events); + return { events, post, hook: testHook(events) }; +} + +// Requests as one principal; `null` sends no auth info. +function client(events: EventsExtension, principal: string | null = 'u1') { + const authInfo = { token: 'tok', clientId: 'app', scopes: [], extra: { sub: principal } }; + const { rpc } = serve(events, principal === null ? {} : { authInfo }); + return { + rpc, + subscribe: ({ name = 'e', url = HOOK, secret = SECRET, ...rest }: SubscribeInput = {}) => + rpc('events/subscribe', { name, delivery: { mode: 'webhook', url, secret }, ...rest }), + unsubscribe: ({ name = 'e', url = HOOK, ...rest }: { name?: string; arguments?: Record; url?: string } = {}) => + rpc('events/unsubscribe', { name, delivery: { url }, ...rest }) + }; +} + +function subscribed(reply: Parameters[0]): SubscribeEventsResult { + return resultOf(reply) as SubscribeEventsResult; +} + +async function stored(store: InMemoryWebhookSubscriptionStore, name = 'e'): Promise { + const records: WebhookSubscriptionRecord[] = []; + for await (const record of store.listByName(name)) records.push(record); + return records; +} + +function verifies(request: WebhookSendRequest, secret: string): Promise { + const { headers } = request; + return verifyWebhookSignature( + [parseWebhookSecret(secret)!], + headers['webhook-id']!, + Number(headers['webhook-timestamp']), + request.body, + headers['webhook-signature']! + ); +} + +// Lets queued work act on answers already received, without moving the clock. +const settle = (): Promise => vi.advanceTimersByTimeAsync(0); + +const REVOKED = { code: -32_024, message: 'Forbidden', data: { reason: 'Access revoked' } }; + +function revoked(): EventsError { + return new EventsError('forbidden', 'Forbidden', { reason: 'Access revoked' }); +} + +// A store whose next `get` or `put` waits for the test, which can act while a subscribe is between its read and its write. +class GatedStore extends InMemoryWebhookSubscriptionStore { + #held: { method: 'get' | 'put'; reached(): void; released: Promise } | undefined; + + hold(method: 'get' | 'put'): { reached: Promise; release(): void } { + let reached!: () => void; + let release!: () => void; + const arrived = new Promise(resolve => (reached = resolve)); + this.#held = { method, reached, released: new Promise(resolve => (release = resolve)) }; + return { reached: arrived, release }; + } + + override async get(id: string): Promise { + await this.#wait('get'); + return super.get(id); + } + + override async put(record: WebhookSubscriptionRecord): Promise { + await this.#wait('put'); + return super.put(record); + } + + async #wait(method: 'get' | 'put'): Promise { + const held = this.#held; + if (held?.method !== method) return; + this.#held = undefined; + held.reached(); + await held.released; + } +} + +beforeEach(() => { + vi.useFakeTimers(); +}); + +afterEach(() => { + for (const events of extensions.splice(0)) testHook(events).restart(); + vi.useRealTimers(); +}); + +describe('events/subscribe: validation', () => { + it('needs webhook mode and a principal, checked before the event type (F12)', async () => { + const plain = new EventsExtension({ getPrincipal }); + plain.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const off = client(plain); + const list = resultOf(await off.rpc('events/list')) as ListEventsResult; + expect(list.events[0]!.delivery).toEqual(['poll', 'push']); + expect(errorOf(await off.subscribe())).toMatchObject(UNSUPPORTED); + expect(errorOf(await off.subscribe({ name: 'missing' }))).toMatchObject(UNSUPPORTED); + expect(errorOf(await off.unsubscribe())).toMatchObject(UNSUPPORTED); + const legacy = { name: 'e', delivery: { mode: 'webhook', url: HOOK, secret: SECRET } }; + expect(errorOf(await off.rpc('events/subscribe', legacy, { era: 'legacy' }))).toMatchObject({ code: -32_601 }); + + const { events, post } = replica(); + events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + events.registerEvent('no-hook', { emitOnly: true, payloadSchema: P, delivery: { webhook: false } }); + const anonymous = client(events, null); + expect(errorOf(await anonymous.subscribe())).toMatchObject({ code: -32_024 }); + expect(errorOf(await anonymous.subscribe({ name: 'missing' }))).toMatchObject({ code: -32_024 }); + expect(errorOf(await anonymous.unsubscribe())).toMatchObject({ code: -32_024 }); + const alice = client(events); + expect(errorOf(await alice.subscribe({ name: 'missing' }))).toMatchObject({ code: -32_023, data: { kind: 'event' } }); + expect(errorOf(await alice.subscribe({ name: 'no-hook', url: 'http://example.com/hook' }))).toMatchObject(UNSUPPORTED); + expect(errorOf(await alice.rpc('events/subscribe', legacy, { era: 'legacy' }))).toMatchObject({ code: -32_601 }); + expect(post.requests).toHaveLength(0); + }); + + it('requires https unless the exact origin is trusted', async () => { + const { events, post } = replica({ trustedOrigins: ['http://127.0.0.1:9000'] }); + events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const alice = client(events); + for (const url of [ + 'http://example.com/hook', + 'hooks.example.com/mcp', + 'http://127.0.0.1:9001/hook', + 'http://localhost:9000/hook' + ]) { + expect(errorOf(await alice.subscribe({ url }))).toMatchObject({ code: -32_602 }); + } + expect(post.requests).toHaveLength(0); + subscribed(await alice.subscribe({ url: 'http://127.0.0.1:9000/hook' })); + subscribed(await alice.subscribe({ url: HOOK })); + expect(post.requests.map(request => [request.url, request.trusted])).toEqual([ + ['http://127.0.0.1:9000/hook', true], + [HOOK, false] + ]); + }); + + it('validates the secret', async () => { + const { events, post } = replica(); + events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const alice = client(events); + const secrets = ['whsec_short', `whsec_${btoa('x'.repeat(23))}`, `whsec_${btoa('x'.repeat(65))}`, btoa('x'.repeat(32))]; + for (const secret of secrets) expect(errorOf(await alice.subscribe({ secret }))).toMatchObject({ code: -32_602 }); + expect(post.requests).toHaveLength(0); + }); + + it('derives one stable id per (principal, url, name, arguments) (Review Focus 4)', async () => { + const onSubscribe = vi.fn(); + const { events, post } = replica(); + events.registerEvent('e', { emitOnly: true, payloadSchema: P, onSubscribe }); + events.registerEvent('f', { emitOnly: true, payloadSchema: P }); + const alice = client(events); + const first = subscribed(await alice.subscribe({ arguments: { a: 1, b: { c: 2 } } })); + const reordered = subscribed(await alice.subscribe({ arguments: { b: { c: 2 }, a: 1 } })); + const digest = createHash('sha256') + .update(JSON.stringify(['u1', HOOK, 'e', { a: 1, b: { c: 2 } }])) + .digest('base64url'); + expect(first.id).toBe(`sub_${digest.slice(0, 22)}`); + expect(first.id).toMatch(SUB_ID); + expect(reordered.id).toBe(first.id); + expect(onSubscribe).toHaveBeenCalledOnce(); + expect(onSubscribe.mock.calls[0]![0]).toMatchObject({ name: 'e', subscriptionId: first.id, principal: 'u1', mode: 'webhook' }); + expect(post.requests[0]!.headers['X-MCP-Subscription-Id']).toBe(first.id); + + const others = [ + subscribed(await client(events, 'u2').subscribe({ arguments: { a: 1, b: { c: 2 } } })).id, + subscribed(await alice.subscribe({ arguments: { a: 1, b: { c: 2 } }, url: OTHER_HOOK })).id, + subscribed(await alice.subscribe({ name: 'f', arguments: { a: 1, b: { c: 2 } } })).id, + subscribed(await alice.subscribe({ arguments: { a: 1, b: { c: 3 } } })).id + ]; + expect(new Set([first.id, ...others]).size).toBe(5); + }); + + it.each([ + [3_600_000, 1_800_000], + [1000, 60_000], + [null, 1_800_000], + [undefined, 1_800_000] + ])('grants ttlMs %s as %i', async (ttlMs, ms) => { + const store = new InMemoryWebhookSubscriptionStore(); + const { events } = replica({ webhookStore: store }); + events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const reply = subscribed(await client(events).subscribe({ ttlMs })); + expect(reply.refreshBefore).toBe(new Date(Date.now() + ms).toISOString()); + expect((await store.get(reply.id))?.expiresAt).toBe(Date.now() + ms); + }); +}); + +describe('events/subscribe: creating', () => { + it('checks the quota before verification and onSubscribe', async () => { + const onSubscribe = vi.fn(); + const { events, post } = replica({ maxSubscriptions: 1 }); + events.registerEvent('e', { emitOnly: true, payloadSchema: P, onSubscribe }); + const alice = client(events); + subscribed(await alice.subscribe({ arguments: { a: 1 } })); + expect(errorOf(await alice.subscribe({ arguments: { a: 2 }, url: OTHER_HOOK }))).toMatchObject({ + code: -32_025, + data: { limit: 'subscriptions', max: 1 } + }); + expect(post.requests).toHaveLength(1); + expect(onSubscribe).toHaveBeenCalledOnce(); + + // A refresh is never refused, and the webhook subscription counts against poll too. + subscribed(await alice.subscribe({ arguments: { a: 1 } })); + expect(errorOf(await alice.rpc('events/poll', { name: 'e' }))).toMatchObject({ code: -32_025 }); + }); + + it('stores nothing when verification fails', async () => { + const onSubscribe = vi.fn(); + const store = new InMemoryWebhookSubscriptionStore(); + const { events, post, hook } = replica({ webhookStore: store, respond: () => ({ status: 200, body: '{"challenge":"wrong"}' }) }); + events.registerEvent('e', { emitOnly: true, payloadSchema: P, onSubscribe }); + expect(errorOf(await client(events).subscribe())).toMatchObject({ code: -32_027, data: { reason: 'challenge_failed' } }); + expect(post.requests).toHaveLength(1); + expect(onSubscribe).not.toHaveBeenCalled(); + expect(await stored(store)).toEqual([]); + expect(hook.state()).toMatchObject({ webhookSubscriptions: 0, webhookExpiryTimers: 0 }); + }); + + it('forgets a create that onSubscribe refuses after verification', async () => { + let refuse = true; + const onUnsubscribe = vi.fn(); + const store = new InMemoryWebhookSubscriptionStore(); + const { events, post, hook } = replica({ webhookStore: store }); + events.registerEvent('e', { + emitOnly: true, + payloadSchema: P, + onSubscribe: () => { + if (refuse) throw new EventsError('forbidden', 'Forbidden', { reason: 'denied' }); + }, + onUnsubscribe + }); + expect(errorOf(await client(events).subscribe())).toEqual({ code: -32_024, message: 'Forbidden', data: { reason: 'denied' } }); + expect(await stored(store)).toEqual([]); + expect(hook.state()).toMatchObject({ webhookSubscriptions: 0, webhookExpiryTimers: 0 }); + expect(onUnsubscribe).not.toHaveBeenCalled(); + + // The verification it added went with it, so the next create verifies again. + refuse = false; + subscribed(await client(events).subscribe()); + expect(post.requests.filter(request => isVerification(request))).toHaveLength(2); + }); + + it('starts an emit-only subscription at the buffer head and flags skipped events as truncated', async () => { + const { events } = replica(); + const handle = events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const alice = client(events); + const fresh = subscribed(await alice.subscribe({ arguments: { k: 1 } })); + expect(fresh).toMatchObject({ cursor: expect.any(String), truncated: false }); + await handle.emit({ data: { n: 1 } }); + + const behind = subscribed(await alice.subscribe({ arguments: { k: 2 }, cursor: fresh.cursor })); + expect(behind.truncated).toBe(true); + expect(behind.cursor).not.toBe(fresh.cursor); + const current = subscribed(await alice.subscribe({ arguments: { k: 3 }, cursor: behind.cursor })); + expect(current).toMatchObject({ cursor: behind.cursor, truncated: false }); + expect(subscribed(await alice.subscribe({ arguments: { k: 4 }, cursor: 'e00000000.0' })).truncated).toBe(true); + }); +}); + +describe('events/subscribe: refreshing', () => { + it('refreshes idempotently and rotates the secret', async () => { + const onSubscribe = vi.fn(); + const store = new InMemoryWebhookSubscriptionStore(); + const { events, post } = replica({ webhookStore: store }); + const handle = events.registerEvent('e', { emitOnly: true, payloadSchema: P, onSubscribe }); + const alice = client(events); + const first = subscribed(await alice.subscribe({ ttlMs: 600_000 })); + await vi.advanceTimersByTimeAsync(60_000); + const next = generateWebhookSecret(); + const refreshed = subscribed(await alice.subscribe({ ttlMs: 600_000, secret: next })); + expect(refreshed.id).toBe(first.id); + expect(refreshed.refreshBefore).toBe(new Date(Date.now() + 600_000).toISOString()); + expect(refreshed.refreshBefore).not.toBe(first.refreshBefore); + expect(onSubscribe).toHaveBeenCalledOnce(); + expect(post.requests).toHaveLength(1); + expect(await store.get(first.id)).toMatchObject({ + secret: next, + previousSecret: { secret: SECRET, expiresAt: Date.now() + 300_000 } + }); + + await handle.emit({ data: { n: 1 } }); + await post.until(2); + const rotated = post.requests[1]!; + expect(rotated.headers['webhook-signature']!.split(' ')).toHaveLength(2); + expect(await verifies(rotated, next)).toBe(true); + expect(await verifies(rotated, SECRET)).toBe(true); + + await vi.advanceTimersByTimeAsync(300_000); + await handle.emit({ data: { n: 2 } }); + await post.until(3); + const settled = post.requests[2]!; + expect(settled.headers['webhook-signature']!.split(' ')).toHaveLength(1); + expect(await verifies(settled, next)).toBe(true); + expect(await verifies(settled, SECRET)).toBe(false); + }); + + it('reports deliveryStatus and the watermark on refresh', async () => { + let answer: WebhookSendOutcome = { status: 500, body: '' }; + const store = new InMemoryWebhookSubscriptionStore(); + const a = replica({ webhookStore: store, respond: echo(() => answer) }); + const b = replica({ webhookStore: store }); + const handle = a.events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + b.events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const alice = client(a.events); + const first = subscribed(await alice.subscribe()); + expect(first).not.toHaveProperty('deliveryStatus'); + await handle.emit({ data: { n: 1 } }); + await a.post.until(2); + await settle(); + + const failing = subscribed(await alice.subscribe({ cursor: first.cursor })); + expect(failing).toMatchObject({ id: first.id, cursor: first.cursor, truncated: false }); + expect(failing.deliveryStatus).toEqual({ + active: true, + lastDeliveryAt: null, + lastError: 'http_5xx', + failedSince: new Date().toISOString() + }); + + answer = { status: 200, body: '' }; + await vi.advanceTimersByTimeAsync(5000); + await a.post.until(3); + await settle(); + const healthy = subscribed(await alice.subscribe({ cursor: first.cursor })); + const { cursor: head } = resultOf(await alice.rpc('events/poll', { name: 'e', cursor: null })) as PollEventsResult; + expect(healthy.cursor).toBe(head); + expect(healthy.cursor).not.toBe(first.cursor); + expect(healthy.deliveryStatus).toEqual({ active: true, lastDeliveryAt: new Date().toISOString(), lastError: null }); + + // A replica that holds no delivery state for it answers with the client's cursor and no deliveryStatus (Decision 7). + const elsewhere = subscribed(await client(b.events).subscribe({ cursor: 'client-cursor' })); + expect(elsewhere).toMatchObject({ id: first.id, cursor: 'client-cursor', truncated: false }); + expect(elsewhere).not.toHaveProperty('deliveryStatus'); + }); + + it('reports a suspension on the refresh that ends it', async () => { + const { events, post } = replica({ respond: echo(() => ({ status: 503, body: '' })) }); + const handle = events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const alice = client(events); + subscribed(await alice.subscribe()); + for (let n = 1; n <= 100; n++) await handle.emit({ data: { n } }); + await post.until(101); + await settle(); + expect(subscribed(await alice.subscribe()).deliveryStatus).toMatchObject({ active: false, lastError: 'http_5xx' }); + expect(subscribed(await alice.subscribe()).deliveryStatus).toMatchObject({ active: true, lastError: 'http_5xx' }); + }); +}); + +describe('events/unsubscribe', () => { + it('unsubscribes by key and reports unknown keys', async () => { + const onUnsubscribe = vi.fn(); + const store = new InMemoryWebhookSubscriptionStore(); + const { events, hook } = replica({ webhookStore: store }); + events.registerEvent('e', { emitOnly: true, payloadSchema: P, onUnsubscribe }); + const alice = client(events); + const { id } = subscribed(await alice.subscribe({ arguments: { a: 1 } })); + const unknown = { code: -32_023, data: { kind: 'subscription' } }; + expect(errorOf(await client(events, 'u2').unsubscribe({ arguments: { a: 1 } }))).toMatchObject(unknown); + expect(errorOf(await alice.unsubscribe({ arguments: { a: 2 } }))).toMatchObject(unknown); + expect(errorOf(await alice.unsubscribe({ arguments: { a: 1 }, url: OTHER_HOOK }))).toMatchObject(unknown); + expect(onUnsubscribe).not.toHaveBeenCalled(); + + const { _meta, ...done } = resultOf(await alice.unsubscribe({ arguments: { a: 1 } })); + expect(done).toEqual({ resultType: 'complete' }); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + const [ctx, args] = onUnsubscribe.mock.calls[0]! as [EventContext, unknown]; + expect(ctx).toMatchObject({ name: 'e', subscriptionId: id, principal: 'u1', mode: 'webhook' }); + expect(ctx.signal.aborted).toBe(true); + expect(args).toEqual({ a: 1 }); + expect(await store.get(id)).toBeUndefined(); + expect(hook.state()).toMatchObject({ webhookSubscriptions: 0, webhookExpiryTimers: 0 }); + + expect(errorOf(await alice.unsubscribe({ arguments: { a: 1 } }))).toMatchObject(unknown); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + }); +}); + +describe('several replicas sharing one store', () => { + it('expires without refresh and follows a refresh made on another replica', async () => { + const store = new InMemoryWebhookSubscriptionStore(); + const a = replica({ webhookStore: store }); + const b = replica({ webhookStore: store }); + const onA = vi.fn(); + const onB = vi.fn(); + a.events.registerEvent('e', { emitOnly: true, payloadSchema: P, onUnsubscribe: onA }); + b.events.registerEvent('e', { emitOnly: true, payloadSchema: P, onUnsubscribe: onB }); + + const lapsing = subscribed(await client(a.events).subscribe({ arguments: { k: 1 }, ttlMs: 60_000 })); + await vi.advanceTimersByTimeAsync(59_999); + expect(await store.get(lapsing.id)).toBeDefined(); + await vi.advanceTimersByTimeAsync(1); + expect(await store.get(lapsing.id)).toBeUndefined(); + expect(onA).toHaveBeenCalledOnce(); + expect(onA.mock.calls[0]![0]).toMatchObject({ subscriptionId: lapsing.id, mode: 'webhook' }); + expect(a.hook.state()).toMatchObject({ webhookSubscriptions: 0, webhookExpiryTimers: 0 }); + + const kept = subscribed(await client(a.events).subscribe({ arguments: { k: 2 }, ttlMs: 60_000 })); + await vi.advanceTimersByTimeAsync(30_000); + subscribed(await client(b.events).subscribe({ arguments: { k: 2 }, ttlMs: 60_000 })); + await vi.advanceTimersByTimeAsync(30_000); + expect(await store.get(kept.id)).toBeDefined(); + expect(onA).toHaveBeenCalledOnce(); + expect(onB).not.toHaveBeenCalled(); + expect(a.hook.state().webhookExpiryTimers).toBe(1); + + // At the refreshed grant both replicas look again; one deletes the record and runs onUnsubscribe. + await vi.advanceTimersByTimeAsync(30_000); + expect(await store.get(kept.id)).toBeUndefined(); + expect(onA.mock.calls.length + onB.mock.calls.length).toBe(2); + expect(a.hook.state().webhookExpiryTimers + b.hook.state().webhookExpiryTimers).toBe(0); + }); + + it('delivers an emit made on another replica', async () => { + const store = new InMemoryWebhookSubscriptionStore(); + const a = replica({ webhookStore: store }); + const b = replica({ webhookStore: store }); + a.events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const handle = b.events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const { id } = subscribed(await client(a.events).subscribe()); + await handle.emit({ eventId: 'evt_1', data: { n: 1 } }); + await b.post.until(1); + await settle(); + expect(b.post.requests).toHaveLength(1); + const [delivery] = b.post.requests; + expect(delivery!.url).toBe(HOOK); + expect(delivery!.headers['X-MCP-Subscription-Id']).toBe(id); + expect(bodyOf(delivery!)).toMatchObject({ eventId: 'evt_1', name: 'e', data: { n: 1 }, cursor: expect.any(String) }); + expect(await verifies(delivery!, SECRET)).toBe(true); + expect(a.post.deliveries()).toEqual([]); + }); + + it('stops retries on A after an unsubscribe on B', async () => { + const store = new InMemoryWebhookSubscriptionStore(); + const a = replica({ webhookStore: store, respond: echo(() => ({ status: 500, body: '' })) }); + const b = replica({ webhookStore: store }); + const onA = vi.fn(); + const onB = vi.fn(); + const handle = a.events.registerEvent('e', { emitOnly: true, payloadSchema: P, onUnsubscribe: onA }); + b.events.registerEvent('e', { emitOnly: true, payloadSchema: P, onUnsubscribe: onB }); + subscribed(await client(a.events).subscribe()); + await handle.emit({ data: { n: 1 } }); + await a.post.until(2); + await settle(); + + resultOf(await client(b.events).unsubscribe()); + expect(onB).toHaveBeenCalledOnce(); + await vi.advanceTimersByTimeAsync(600_000); + expect(a.post.requests).toHaveLength(2); + expect(a.hook.state().webhookSubscriptions).toBe(0); + + // A's timer finds the record gone at the grant and lets it go without a second onUnsubscribe. + await vi.advanceTimersByTimeAsync(1_800_000); + expect(a.hook.state().webhookExpiryTimers).toBe(0); + expect(onA).not.toHaveBeenCalled(); + }); + + it('expires a record lazily where no timer watches it, running onUnsubscribe once (F3b)', async () => { + const store = new InMemoryWebhookSubscriptionStore(); + const a = replica({ webhookStore: store }); + const b = replica({ webhookStore: store }); + const onSubscribeA = vi.fn(); + const onA = vi.fn(); + const onB = vi.fn(); + a.events.registerEvent('e', { emitOnly: true, payloadSchema: P, onSubscribe: onSubscribeA, onUnsubscribe: onA }); + const handle = b.events.registerEvent('e', { emitOnly: true, payloadSchema: P, onUnsubscribe: onB }); + const first = subscribed(await client(a.events).subscribe({ arguments: { k: 1 }, ttlMs: 60_000 })); + const second = subscribed(await client(a.events).subscribe({ arguments: { k: 2 }, ttlMs: 60_000 })); + // A restarts and loses its timers; the records stay in the store past their grant. + a.hook.restart(); + await vi.advanceTimersByTimeAsync(60_000); + expect(await stored(store)).toHaveLength(2); + + // Read by a subscribe: the expired record ends, then a fresh one starts. + subscribed(await client(a.events).subscribe({ arguments: { k: 1 }, ttlMs: 60_000 })); + expect(onA).toHaveBeenCalledOnce(); + expect(onA.mock.calls[0]![0]).toMatchObject({ subscriptionId: first.id }); + expect(onSubscribeA).toHaveBeenCalledTimes(3); + + // Read by an emit's fan-out on another replica. + await handle.emit({ data: { n: 1 } }); + await b.post.until(1); + await settle(); + expect(onB).toHaveBeenCalledOnce(); + const [ctx] = onB.mock.calls[0]! as [EventContext]; + expect(ctx).toMatchObject({ subscriptionId: second.id, mode: 'webhook' }); + expect(ctx.signal.aborted).toBe(true); + expect((await stored(store)).map(record => record.id)).toEqual([first.id]); + + await handle.emit({ data: { n: 2 } }); + await b.post.until(2); + await settle(); + expect(onB).toHaveBeenCalledOnce(); + expect(b.post.requests.map(request => request.headers['X-MCP-Subscription-Id'])).toEqual([first.id, first.id]); + }); +}); + +describe('fan-out', () => { + it('applies match and transform under each subscription, and a targeted emit reaches only its id', async () => { + const seen: EventContext[] = []; + const { events, post } = replica(); + const handle = events.registerEvent('e', { + emitOnly: true, + inputSchema: z.object({ min: z.number().optional() }), + payloadSchema: P, + match: (ctx, event, args) => { + seen.push(ctx); + return event.data.n >= (args.min ?? 0); + }, + transform: (_ctx, event) => ({ ...event, data: { n: event.data.n * 10 } }) + }); + const alice = client(events); + const low = subscribed(await alice.subscribe({ arguments: {} })); + const high = subscribed(await alice.subscribe({ arguments: { min: 5 } })); + await handle.emit({ eventId: 'small', data: { n: 1 } }); + await post.until(2); + await settle(); + expect(seen.map(ctx => [ctx.subscriptionId, ctx.principal, ctx.mode])).toEqual([ + [low.id, 'u1', 'webhook'], + [high.id, 'u1', 'webhook'] + ]); + + await handle.emit({ eventId: 'direct', data: { n: 1 } }, { subscriptionId: high.id }); + await post.until(3); + await settle(); + expect(seen).toHaveLength(2); + expect( + post.deliveries().map(request => [request.headers['X-MCP-Subscription-Id'], bodyOf(request).eventId, bodyOf(request).data]) + ).toEqual([ + [low.id, 'small', { n: 10 }], + [high.id, 'direct', { n: 10 }] + ]); + }); +}); + +describe('check-kind webhook subscriptions', () => { + it('runs a check loop for a check-kind webhook subscription and stops it on expiry', async () => { + const check = vi + .fn() + .mockReturnValueOnce({ events: [], cursor: 'c0' }) + .mockReturnValueOnce({ events: [{ eventId: 'evt_1', data: { n: 1 } }], cursor: 'c1' }) + .mockReturnValue({ events: [], cursor: 'c1' }); + const { events, post, hook } = replica(); + events.registerEvent('t', { payloadSchema: P, check }); + const reply = subscribed(await client(events).subscribe({ name: 't', ttlMs: 60_000 })); + expect(reply).toMatchObject({ cursor: 'c0', truncated: false }); + expect(check).toHaveBeenCalledOnce(); + const [ctx, , cursor] = check.mock.calls[0]!; + expect(ctx).toMatchObject({ name: 't', subscriptionId: reply.id, principal: 'u1', mode: 'webhook' }); + expect(cursor).toBeNull(); + + await vi.advanceTimersByTimeAsync(4999); + expect(check).toHaveBeenCalledOnce(); + await vi.advanceTimersByTimeAsync(1); + expect(check.mock.calls[1]![2]).toBe('c0'); + await post.until(2); + await settle(); + expect(bodyOf(post.requests[1]!)).toMatchObject({ eventId: 'evt_1', name: 't', data: { n: 1 }, cursor: 'c0' }); + await vi.advanceTimersByTimeAsync(5000); + expect(check.mock.calls[2]![2]).toBe('c1'); + + // The grant passes without a refresh: the loop stops. + await vi.advanceTimersByTimeAsync(50_000); + const calls = check.mock.calls.length; + expect(hook.state().webhookExpiryTimers).toBe(0); + await vi.advanceTimersByTimeAsync(60_000); + expect(check).toHaveBeenCalledTimes(calls); + expect(post.requests).toHaveLength(2); + }); + + it('replays from a cursor on create, and sends a gap envelope for a gap between refreshes', async () => { + const check = vi.fn((_ctx, _args, cursor) => { + if (cursor === 'c0') return { events: [{ eventId: 'evt_1', data: { n: 1 } }], cursor: 'c1' }; + if (cursor === 'c1' || cursor === 'old') return { events: [], cursor: 'c5', truncated: true }; + return { events: [], cursor: 'c5' }; + }); + const { events, post } = replica(); + events.registerEvent('t', { payloadSchema: P, check }); + const alice = client(events); + const replayed = subscribed(await alice.subscribe({ name: 't', arguments: { k: 1 }, cursor: 'c0', maxAgeMs: 300_000 })); + expect(replayed).toMatchObject({ cursor: 'c0', truncated: false }); + expect(check.mock.calls[0]![0]).toMatchObject({ maxAgeMs: 300_000 }); + await post.until(2); + await settle(); + expect(bodyOf(post.requests[1]!)).toMatchObject({ eventId: 'evt_1', cursor: 'c0' }); + + await vi.advanceTimersByTimeAsync(5000); + await post.until(3); + const gap = post.requests[2]!; + expect(check.mock.calls[1]![0]).not.toHaveProperty('maxAgeMs'); + expect(bodyOf(gap)).toEqual({ type: 'gap', cursor: 'c5' }); + expect(gap.headers).toMatchObject({ + 'webhook-id': expect.stringMatching(/^msg_gap_[\w-]+$/), + 'X-MCP-Subscription-Id': replayed.id + }); + expect(await verifies(gap, SECRET)).toBe(true); + + const gapped = subscribed(await alice.subscribe({ name: 't', arguments: { k: 2 }, cursor: 'old' })); + expect(gapped).toMatchObject({ cursor: 'c5', truncated: true }); + }); + + it('advances the refresh cursor over quiet check batches, never past an unacknowledged event', async () => { + let acknowledge!: (outcome: WebhookSendOutcome) => void; + const respond: Respond = request => + isVerification(request) ? echo()(request) : new Promise(resolve => (acknowledge = resolve)); + const check = vi + .fn() + .mockReturnValueOnce({ events: [], cursor: 'c0' }) + .mockReturnValueOnce({ events: [], cursor: 'c1' }) + .mockReturnValueOnce({ events: [{ eventId: 'evt_2', data: { n: 2 } }], cursor: 'c2' }) + .mockReturnValueOnce({ events: [], cursor: 'c3' }) + .mockReturnValue({ events: [], cursor: 'c4' }); + const { events, post } = replica({ checkIntervalMs: 100_000, respond }); + events.registerEvent('t', { payloadSchema: P, check }); + const alice = client(events); + const refreshCursor = async () => subscribed(await alice.subscribe({ name: 't' })).cursor; + expect(await refreshCursor()).toBe('c0'); + + // A quiet batch whose upstream cursor moved. + await vi.advanceTimersByTimeAsync(100_000); + expect(await refreshCursor()).toBe('c1'); + + // evt_2 waits for its answer, so the next quiet batch leaves the watermark behind it. + await vi.advanceTimersByTimeAsync(100_000); + await post.until(2); + await vi.advanceTimersByTimeAsync(100_000); + expect(check).toHaveBeenCalledTimes(4); + expect(await refreshCursor()).toBe('c1'); + + // Once evt_2 is acknowledged, the watermark reaches it, and the next quiet batch catches up. + acknowledge({ status: 200, body: '' }); + await settle(); + expect(await refreshCursor()).toBe('c2'); + await vi.advanceTimersByTimeAsync(100_000); + expect(await refreshCursor()).toBe('c4'); + }); +}); + +describe('termination', () => { + it('terminates with a signed envelope and forgets the subscription', async () => { + const onSubscribe = vi.fn(); + const onUnsubscribe = vi.fn(); + const store = new InMemoryWebhookSubscriptionStore(); + const { events, post, hook } = replica({ webhookStore: store }); + const handle = events.registerEvent('e', { emitOnly: true, payloadSchema: P, onSubscribe, onUnsubscribe }); + const alice = client(events); + const { id } = subscribed(await alice.subscribe()); + await handle.terminate(new EventsError('forbidden', 'Forbidden', { reason: 'Access revoked' })); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + expect((onUnsubscribe.mock.calls[0]![0] as EventContext).signal.aborted).toBe(true); + expect(await store.get(id)).toBeUndefined(); + expect(hook.state()).toMatchObject({ webhookSubscriptions: 0, webhookExpiryTimers: 0 }); + + await post.until(2); + const terminated = post.requests[1]!; + expect(bodyOf(terminated)).toEqual({ + type: 'terminated', + error: { code: -32_024, message: 'Forbidden', data: { reason: 'Access revoked' } } + }); + expect(terminated.headers).toMatchObject({ + 'webhook-id': expect.stringMatching(/^msg_terminated_[\w-]+$/), + 'X-MCP-Subscription-Id': id + }); + expect(await verifies(terminated, SECRET)).toBe(true); + + const again = subscribed(await alice.subscribe()); + expect(again.id).toBe(id); + expect(onSubscribe).toHaveBeenCalledTimes(2); + expect(post.requests.filter(request => isVerification(request))).toHaveLength(2); + }); + + it('terminates only the subscription with the given subscriptionId, and remove() ends the rest', async () => { + const store = new InMemoryWebhookSubscriptionStore(); + const { events, post } = replica({ webhookStore: store }); + const handle = events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const alice = client(events); + const one = subscribed(await alice.subscribe({ arguments: { k: 1 } })); + const two = subscribed(await alice.subscribe({ arguments: { k: 2 } })); + await handle.terminate(new EventsError('forbidden', 'Forbidden'), { subscriptionId: two.id }); + expect((await stored(store)).map(record => record.id)).toEqual([one.id]); + await post.until(2); + expect(post.deliveries().map(request => request.headers['X-MCP-Subscription-Id'])).toEqual([two.id]); + + handle.remove(); + await post.until(3); + await settle(); + expect(bodyOf(post.requests[2]!)).toMatchObject({ type: 'terminated', error: { code: -32_023, data: { kind: 'event' } } }); + expect(post.requests[2]!.headers['X-MCP-Subscription-Id']).toBe(one.id); + expect(await stored(store)).toEqual([]); + }); + + it('ends a check-kind subscription whose check throws forbidden, and reports other errors', async () => { + const onerror = vi.fn(); + const onUnsubscribe = vi.fn(); + const check = vi + .fn() + .mockReturnValueOnce({ events: [], cursor: 'c0' }) + .mockImplementationOnce(() => { + throw new Error('upstream down'); + }) + .mockImplementation(() => { + throw new EventsError('forbidden', 'Forbidden', { reason: 'Access revoked' }); + }); + const store = new InMemoryWebhookSubscriptionStore(); + const { events, post } = replica({ webhookStore: store, onerror }); + events.registerEvent('t', { payloadSchema: P, check, onUnsubscribe }); + const { id } = subscribed(await client(events).subscribe({ name: 't' })); + + await vi.advanceTimersByTimeAsync(5000); + expect(onerror).toHaveBeenCalledWith(expect.objectContaining({ message: 'upstream down' })); + expect(await store.get(id)).toBeDefined(); + + await vi.advanceTimersByTimeAsync(5000); + await post.until(2); + await settle(); + expect(bodyOf(post.requests[1]!)).toEqual({ + type: 'terminated', + error: { code: -32_024, message: 'Forbidden', data: { reason: 'Access revoked' } } + }); + expect(await store.get(id)).toBeUndefined(); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + await vi.advanceTimersByTimeAsync(60_000); + expect(check).toHaveBeenCalledTimes(3); + }); + + it('never makes a subscribe wait on a termination its own onSubscribe awaits', async () => { + let terminate = true; + const onUnsubscribe = vi.fn(); + const store = new InMemoryWebhookSubscriptionStore(); + const { events } = replica({ webhookStore: store }); + const handle = events.registerEvent('e', { + emitOnly: true, + payloadSchema: P, + onSubscribe: async ctx => { + if (terminate) await handle.terminate(revoked(), { subscriptionId: ctx.subscriptionId }); + }, + onUnsubscribe + }); + const alice = client(events); + expect(errorOf(await alice.subscribe())).toEqual(REVOKED); + expect(await stored(store)).toEqual([]); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + // Nothing is left holding the line for this subscription. + terminate = false; + expect(subscribed(await alice.subscribe()).id).toMatch(SUB_ID); + }); + + it.each(['get', 'put'] as const)('lets no refresh store a record that a termination ended during its %s', async method => { + const onUnsubscribe = vi.fn(); + const store = new GatedStore(); + const { events, post } = replica({ webhookStore: store }); + const handle = events.registerEvent('e', { emitOnly: true, payloadSchema: P, onUnsubscribe }); + const alice = client(events); + const { id } = subscribed(await alice.subscribe()); + + const gate = store.hold(method); + const refresh = alice.subscribe(); + await gate.reached; + await handle.terminate(revoked()); + gate.release(); + expect(errorOf(await refresh)).toEqual(REVOKED); + expect(await store.get(id)).toBeUndefined(); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + await post.until(2); + expect(bodyOf(post.requests[1]!)).toEqual({ type: 'terminated', error: REVOKED }); + + // The next subscribe starts afresh. + subscribed(await alice.subscribe()); + expect(await store.get(id)).toBeDefined(); + }); + + it('fails a create that a termination reaches while it writes, storing nothing', async () => { + const onUnsubscribe = vi.fn(); + const store = new GatedStore(); + const { events, post, hook } = replica({ webhookStore: store }); + const handle = events.registerEvent('e', { emitOnly: true, payloadSchema: P, onUnsubscribe }); + const gate = store.hold('put'); + const creating = client(events).subscribe(); + await gate.reached; + await handle.terminate(revoked()); + gate.release(); + expect(errorOf(await creating)).toEqual(REVOKED); + expect(await stored(store)).toEqual([]); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + expect(hook.state()).toMatchObject({ webhookSubscriptions: 0, webhookExpiryTimers: 0 }); + await settle(); + expect(post.deliveries()).toEqual([]); + }); + + it('fails a create that a termination reaches during onSubscribe, storing nothing', async () => { + let release!: () => void; + let reached!: () => void; + const arrived = new Promise(resolve => (reached = resolve)); + const onUnsubscribe = vi.fn(); + const store = new InMemoryWebhookSubscriptionStore(); + const { events } = replica({ webhookStore: store }); + const handle = events.registerEvent('e', { + emitOnly: true, + payloadSchema: P, + onSubscribe: () => + new Promise(resolve => { + release = resolve; + reached(); + }), + onUnsubscribe + }); + const creating = client(events).subscribe(); + await arrived; + await handle.terminate(revoked()); + release(); + expect(errorOf(await creating)).toEqual(REVOKED); + expect(await stored(store)).toEqual([]); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + }); +}); + +describe('test hook', () => { + it('drops its webhook state on restart() and keeps the store (F4)', async () => { + const onSubscribe = vi.fn(); + const store = new InMemoryWebhookSubscriptionStore(); + const { events, post, hook } = replica({ webhookStore: store, respond: echo(() => ({ status: 500, body: '' })) }); + const handle = events.registerEvent('e', { emitOnly: true, payloadSchema: P, onSubscribe }); + const { id } = subscribed(await client(events).subscribe()); + await handle.emit({ data: { n: 1 } }); + await post.until(2); + await settle(); + expect(hook.state()).toMatchObject({ webhookSubscriptions: 1, webhookExpiryTimers: 1 }); + + hook.restart(); + expect(hook.state()).toMatchObject({ webhookSubscriptions: 0, webhookExpiryTimers: 0 }); + await vi.advanceTimersByTimeAsync(600_000); + expect(post.requests).toHaveLength(2); + expect(await store.get(id)).toBeDefined(); + + // The stored record survives, so the next subscribe refreshes it: no verification, no onSubscribe. + subscribed(await client(events).subscribe()); + expect(onSubscribe).toHaveBeenCalledOnce(); + expect(post.requests).toHaveLength(2); + expect(hook.state().webhookExpiryTimers).toBe(1); + }); + + it('admits a callback whose origin the test hook trusted (F5)', async () => { + const { events, post, hook } = replica(); + events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const url = 'http://127.0.0.1:9000/hook'; + expect(errorOf(await client(events).subscribe({ url }))).toMatchObject({ code: -32_602 }); + hook.addTrustedOrigin('http://127.0.0.1:9000'); + subscribed(await client(events).subscribe({ url })); + expect(post.requests.map(request => [request.url, request.trusted])).toEqual([[url, true]]); + }); +}); From 149198203f1a420866085b740e8124ced787b7e8 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 13:37:47 +0200 Subject: [PATCH 10/37] fix(server): count in-flight webhook creates and key ids on client arguments --- packages/server/src/ext/events/extension.ts | 2 +- packages/server/src/ext/events/types.ts | 2 +- packages/server/src/ext/events/validation.ts | 2 +- .../src/ext/events/webhookSubscriptions.ts | 114 ++++++++++-------- .../ext/events/webhookSubscriptions.test.ts | 114 +++++++++++++++++- 5 files changed, 177 insertions(+), 57 deletions(-) diff --git a/packages/server/src/ext/events/extension.ts b/packages/server/src/ext/events/extension.ts index cc3a1b2f44..a24b7292d6 100644 --- a/packages/server/src/ext/events/extension.ts +++ b/packages/server/src/ext/events/extension.ts @@ -214,7 +214,7 @@ export class EventsExtension { pollLeases: this.#poll.size, pushStreams: this.#push.size, webhookSubscriptions: this.#webhooks?.delivering ?? 0, - webhookExpiryTimers: this.#webhooks?.size ?? 0 + webhookExpiryTimers: this.#webhooks?.watching ?? 0 }), addTrustedOrigin: origin => { assertOrigin(origin); diff --git a/packages/server/src/ext/events/types.ts b/packages/server/src/ext/events/types.ts index 4148a82460..03f839d6f8 100644 --- a/packages/server/src/ext/events/types.ts +++ b/packages/server/src/ext/events/types.ts @@ -287,7 +287,7 @@ export interface EventsOptions { defaultNextPollMs?: number; /** * The most subscriptions this process serves at once, counting poll leases, push streams and the webhook - * subscriptions whose subscribe or refresh it handled; more are refused with `resourceExhausted`. + * subscriptions whose subscribe or refresh it handled or is still creating; more are refused with `resourceExhausted`. */ maxSubscriptions?: number; /** Receives errors nothing else can report (dropped payloads, hook failures, invalid `x-mcp-header` annotations). Default: `console.warn`. */ diff --git a/packages/server/src/ext/events/validation.ts b/packages/server/src/ext/events/validation.ts index 812d17f5d8..7f4e6c22b7 100644 --- a/packages/server/src/ext/events/validation.ts +++ b/packages/server/src/ext/events/validation.ts @@ -11,7 +11,7 @@ export interface ValidatorDeps { readonly webhookEnabled: boolean; readonly getPrincipal: EventsOptions['getPrincipal']; readonly maxSubscriptions: number | undefined; - // Subscriptions this process serves now: poll leases, push streams, and the webhook subscriptions whose subscribe or refresh it handled. + // Subscriptions this process serves now: poll leases, push streams, and the webhook subscriptions whose subscribe or refresh it handled or is still creating. subscriptionCount(): number; } diff --git a/packages/server/src/ext/events/webhookSubscriptions.ts b/packages/server/src/ext/events/webhookSubscriptions.ts index f20c3d45be..84547810ff 100644 --- a/packages/server/src/ext/events/webhookSubscriptions.ts +++ b/packages/server/src/ext/events/webhookSubscriptions.ts @@ -103,9 +103,9 @@ function grantMs(ttlMs: number | null | undefined, maxMs: number): number { return ttlMs === undefined || ttlMs === null ? maxMs : Math.min(maxMs, Math.max(TTL_FLOOR_MS, ttlMs)); } -// `sub_` and 22 base64url characters of the SHA-256 of the canonical key, so every replica derives the same id. -async function subscriptionIdOf(principal: string, url: string, name: string, args: Record): Promise { - const digest = await globalThis.crypto.subtle.digest('SHA-256', encoder.encode(canonicalJson([principal, url, name, args]))); +// `sub_` and 22 base64url characters of the SHA-256 of the canonical key, with the arguments as the client sent them, so every replica and schema version derives the same id. +async function subscriptionIdOf(principal: string, url: string, name: string, rawArgs: Record): Promise { + const digest = await globalThis.crypto.subtle.digest('SHA-256', encoder.encode(canonicalJson([principal, url, name, rawArgs]))); let binary = ''; for (const byte of new Uint8Array(digest)) binary += String.fromCodePoint(byte); return `sub_${btoa(binary).replaceAll('+', '-').replaceAll('/', '_').slice(0, 22)}`; @@ -124,6 +124,8 @@ export class WebhookSubscriptions implements SubscriptionSource { readonly #byId: Queues = new Map(); // Subscribes in flight: a termination that reaches one is applied by it, never stored over. Replicas can still race: the store has no compare-and-set (§5.9). readonly #subscribing = new Set(); + // Creates past the quota check that have no watch yet. + readonly #starting = new Set(); // The fan-out of one event type runs one emit at a time, so each subscription's deliveries reach the engine in position order. readonly #byName: Queues = new Map(); @@ -137,8 +139,13 @@ export class WebhookSubscriptions implements SubscriptionSource { }); } - // Subscriptions this process watches (an expiry timer each), after handling their subscribe or refresh. + // What `maxSubscriptions` counts here: the subscriptions this process watches, and the creates still starting. get size(): number { + return this.#watched.size + this.#starting.size; + } + + // Subscriptions this process watches (an expiry timer each), after handling their subscribe or refresh. + get watching(): number { return this.#watched.size; } @@ -156,7 +163,7 @@ export class WebhookSubscriptions implements SubscriptionSource { } }); // validate('webhook', …) refuses a request without a principal. - const id = await subscriptionIdOf(valid.principal!, url, valid.entry.name, valid.args); + const id = await subscriptionIdOf(valid.principal!, url, valid.entry.name, params.arguments ?? {}); const ttl = grantMs(params.ttlMs, this.#deps.webhookTtlMs); const subscribing: Subscribing = { id, name: valid.entry.name }; this.#subscribing.add(subscribing); @@ -176,8 +183,8 @@ export class WebhookSubscriptions implements SubscriptionSource { } async unsubscribe(params: UnsubscribeEventsRequestParams, ctx: ServerContext): Promise { - const { entry, principal, args } = await this.#deps.validator.validate('webhook', params, ctx); - const id = await subscriptionIdOf(principal!, params.delivery.url, entry.name, args); + const { entry, principal } = await this.#deps.validator.validate('webhook', params, ctx); + const id = await subscriptionIdOf(principal!, params.delivery.url, entry.name, params.arguments ?? {}); return enqueue(this.#byId, id, async () => { const record = await this.#unexpired(id); if (record === undefined || !(await this.#deps.store.delete(id))) throw notFound(); @@ -215,6 +222,7 @@ export class WebhookSubscriptions implements SubscriptionSource { for (const watched of this.#watched.values()) this.#stop(watched); this.#watched.clear(); this.#subscribing.clear(); + this.#starting.clear(); this.#engine.clear(); } @@ -244,52 +252,58 @@ export class WebhookSubscriptions implements SubscriptionSource { // A watch left over here belongs to a subscription that ended elsewhere: its record is gone. this.#release(id); this.#deps.validator.assertCapacity(); - await this.#engine.verify(principal, url, secret, id); - const watched = this.#watch(id, entry, principal); - try { - await entry.definition.onSubscribe?.(watched.ctx, args); - } catch (error) { - watched.ended.abort(); - this.#engine.forget(id); - throw error; - } - const from = params.cursor ?? null; - const now = Date.now(); - const record: WebhookSubscriptionRecord = { - id, - principal, - name: entry.name, - arguments: args, - url, - secret, - expiresAt: now + ttl, - createdAt: now - }; - let start: Batch; + // Counted from the quota check on, so concurrent creates cannot all pass it; the watch takes the count over in one step. + this.#starting.add(subscribing); try { - start = - entry.kind === 'check' - ? await this.#startCheck(record, watched, from, params.maxAgeMs, subscribing) - : await enqueue(this.#byName, entry.name, () => this.#startEmitOnly(record, from, subscribing)); - const terminated = takeTermination(subscribing); - if (terminated !== undefined) { - await this.#deps.store.delete(id); - throw terminated; + await this.#engine.verify(principal, url, secret, id); + const watched = this.#watch(id, entry, principal); + try { + await entry.definition.onSubscribe?.(watched.ctx, args); + } catch (error) { + watched.ended.abort(); + this.#engine.forget(id); + throw error; } - } catch (error) { - watched.ended.abort(); - this.#engine.forget(id); - await this.#unsubscribed(record, watched); - throw error; - } - this.#watched.set(id, watched); - this.#arm(watched, record.expiresAt); - this.#send(record, start, start.cursor); - if (entry.kind === 'check') { - watched.position = start.position; - this.#schedule(watched); + const from = params.cursor ?? null; + const now = Date.now(); + const record: WebhookSubscriptionRecord = { + id, + principal, + name: entry.name, + arguments: args, + url, + secret, + expiresAt: now + ttl, + createdAt: now + }; + let start: Batch; + try { + start = + entry.kind === 'check' + ? await this.#startCheck(record, watched, from, params.maxAgeMs, subscribing) + : await enqueue(this.#byName, entry.name, () => this.#startEmitOnly(record, from, subscribing)); + const terminated = takeTermination(subscribing); + if (terminated !== undefined) { + await this.#deps.store.delete(id); + throw terminated; + } + } catch (error) { + watched.ended.abort(); + this.#engine.forget(id); + await this.#unsubscribed(record, watched); + throw error; + } + this.#watched.set(id, watched); + this.#arm(watched, record.expiresAt); + this.#send(record, start, start.cursor); + if (entry.kind === 'check') { + watched.position = start.position; + this.#schedule(watched); + } + return { id, refreshBefore: new Date(record.expiresAt).toISOString(), cursor: start.cursor, truncated: start.truncated }; + } finally { + this.#starting.delete(subscribing); } - return { id, refreshBefore: new Date(record.expiresAt).toISOString(), cursor: start.cursor, truncated: start.truncated }; } async #startCheck( diff --git a/packages/server/test/ext/events/webhookSubscriptions.test.ts b/packages/server/test/ext/events/webhookSubscriptions.test.ts index ec59bf1e5e..bf146ba2c1 100644 --- a/packages/server/test/ext/events/webhookSubscriptions.test.ts +++ b/packages/server/test/ext/events/webhookSubscriptions.test.ts @@ -103,6 +103,11 @@ function client(events: EventsExtension, principal: string | null = 'u1') { }; } +// The expected id, computed apart from the SDK: `key` is written with its object keys already sorted. +function idOf(key: unknown[]): string { + return `sub_${createHash('sha256').update(JSON.stringify(key)).digest('base64url').slice(0, 22)}`; +} + function subscribed(reply: Parameters[0]): SubscribeEventsResult { return resultOf(reply) as SubscribeEventsResult; } @@ -238,10 +243,7 @@ describe('events/subscribe: validation', () => { const alice = client(events); const first = subscribed(await alice.subscribe({ arguments: { a: 1, b: { c: 2 } } })); const reordered = subscribed(await alice.subscribe({ arguments: { b: { c: 2 }, a: 1 } })); - const digest = createHash('sha256') - .update(JSON.stringify(['u1', HOOK, 'e', { a: 1, b: { c: 2 } }])) - .digest('base64url'); - expect(first.id).toBe(`sub_${digest.slice(0, 22)}`); + expect(first.id).toBe(idOf(['u1', HOOK, 'e', { a: 1, b: { c: 2 } }])); expect(first.id).toMatch(SUB_ID); expect(reordered.id).toBe(first.id); expect(onSubscribe).toHaveBeenCalledOnce(); @@ -257,6 +259,37 @@ describe('events/subscribe: validation', () => { expect(new Set([first.id, ...others]).size).toBe(5); }); + it('derives the id from the arguments as the client sent them, and keeps the parsed ones for the hooks', async () => { + const onSubscribe = vi.fn(); + const store = new InMemoryWebhookSubscriptionStore(); + const { events } = replica({ webhookStore: store }); + events.registerEvent('e', { emitOnly: true, inputSchema: z.object({ a: z.number() }), payloadSchema: P, onSubscribe }); + const alice = client(events); + const plain = subscribed(await alice.subscribe({ arguments: { a: 1 } })); + const extra = subscribed(await alice.subscribe({ arguments: { a: 1, x: 2 } })); + expect(plain.id).toBe(idOf(['u1', HOOK, 'e', { a: 1 }])); + expect(extra.id).toBe(idOf(['u1', HOOK, 'e', { a: 1, x: 2 }])); + expect(onSubscribe.mock.calls.map(([, args]) => args as unknown)).toEqual([{ a: 1 }, { a: 1 }]); + expect((await store.get(extra.id))?.arguments).toEqual({ a: 1 }); + + // Unsubscribing one key leaves the other. + resultOf(await alice.unsubscribe({ arguments: { a: 1 } })); + expect((await stored(store)).map(record => record.id)).toEqual([extra.id]); + }); + + it('keeps the id when the schema gains a default, as after a restart with a new version', async () => { + const before = replica(); + before.events.registerEvent('e', { emitOnly: true, inputSchema: z.object({ a: z.number() }), payloadSchema: P }); + const after = replica(); + after.events.registerEvent('e', { + emitOnly: true, + inputSchema: z.object({ a: z.number(), flag: z.boolean().default(false) }), + payloadSchema: P + }); + const { id } = subscribed(await client(before.events).subscribe({ arguments: { a: 1 } })); + expect(subscribed(await client(after.events).subscribe({ arguments: { a: 1 } })).id).toBe(id); + }); + it.each([ [3_600_000, 1_800_000], [1000, 60_000], @@ -291,6 +324,79 @@ describe('events/subscribe: creating', () => { expect(errorOf(await alice.rpc('events/poll', { name: 'e' }))).toMatchObject({ code: -32_025 }); }); + it('counts a create from its quota check on, so concurrent creates cannot both pass it', async () => { + let release!: () => void; + const held = new Promise(resolve => (release = resolve)); + let holdNext = true; + const respond: Respond = async request => { + if (isVerification(request) && holdNext) { + holdNext = false; + await held; + } + return echo()(request); + }; + const onSubscribe = vi.fn(); + const { events, post } = replica({ maxSubscriptions: 1, respond }); + events.registerEvent('e', { emitOnly: true, payloadSchema: P, onSubscribe }); + const alice = client(events); + const first = alice.subscribe({ arguments: { a: 1 } }); + await post.until(1); + expect(errorOf(await alice.subscribe({ arguments: { a: 2 } }))).toMatchObject({ + code: -32_025, + data: { limit: 'subscriptions', max: 1 } + }); + release(); + subscribed(await first); + expect(post.requests).toHaveLength(1); + expect(onSubscribe).toHaveBeenCalledOnce(); + }); + + it('counts each webhook subscription once after its create', async () => { + const { events } = replica({ maxSubscriptions: 2 }); + events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const alice = client(events); + subscribed(await alice.subscribe({ arguments: { a: 1 } })); + subscribed(await alice.subscribe({ arguments: { a: 2 } })); + expect(errorOf(await alice.subscribe({ arguments: { a: 3 } }))).toMatchObject({ code: -32_025 }); + }); + + it.each(['verification', 'onSubscribe', 'termination', 'check'] as const)( + 'frees the quota of a create that fails at %s', + async failure => { + let failing = true; + // True once, at `failure`: the first create fails there and the next one succeeds. + const failNow = (at: typeof failure): boolean => { + if (at !== failure || !failing) return false; + failing = false; + return true; + }; + const respond: Respond = request => + isVerification(request) && failNow('verification') ? { status: 200, body: '{"challenge":"wrong"}' } : echo()(request); + const { events, hook } = replica({ maxSubscriptions: 1, respond }); + const handle = events.registerEvent('e', { + emitOnly: true, + payloadSchema: P, + onSubscribe: async ctx => { + if (failNow('onSubscribe')) throw new EventsError('forbidden', 'Forbidden'); + if (failNow('termination')) await handle.terminate(revoked(), { subscriptionId: ctx.subscriptionId }); + } + }); + events.registerEvent('t', { + payloadSchema: P, + check: () => { + if (failNow('check')) throw new Error('upstream down'); + return { events: [], cursor: 'c0' }; + } + }); + const name = failure === 'check' ? 't' : 'e'; + const alice = client(events); + errorOf(await alice.subscribe({ name, arguments: { a: 1 } })); + expect(hook.state()).toMatchObject({ webhookSubscriptions: 0, webhookExpiryTimers: 0 }); + subscribed(await alice.subscribe({ name, arguments: { a: 2 } })); + expect(hook.state()).toMatchObject({ webhookExpiryTimers: 1 }); + } + ); + it('stores nothing when verification fails', async () => { const onSubscribe = vi.fn(); const store = new InMemoryWebhookSubscriptionStore(); From 6364fe8a6ca0e4bc13e165c0e541489979614671 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 14:02:37 +0200 Subject: [PATCH 11/37] feat(server): SSRF-hardened nodeWebhookSender at ext/events/node --- examples/tsconfig.json | 1 + .../test/packageTopologyPins.test.ts | 4 +- packages/server/package.json | 13 + packages/server/src/ext/events/node.ts | 131 +++++++++ .../server/src/ext/events/specialAddresses.ts | 103 +++++++ packages/server/test/ext/events/node.test.ts | 271 ++++++++++++++++++ .../test/ext/events/specialAddresses.test.ts | 83 ++++++ .../server/test/server/barrelClean.test.ts | 6 + packages/server/tsdown.config.ts | 3 +- test/conformance/tsconfig.json | 1 + test/e2e/tsconfig.json | 1 + test/integration/tsconfig.json | 1 + 12 files changed, 616 insertions(+), 2 deletions(-) create mode 100644 packages/server/src/ext/events/node.ts create mode 100644 packages/server/src/ext/events/specialAddresses.ts create mode 100644 packages/server/test/ext/events/node.test.ts create mode 100644 packages/server/test/ext/events/specialAddresses.test.ts diff --git a/examples/tsconfig.json b/examples/tsconfig.json index ac0f4c3588..62c4a6dcfb 100644 --- a/examples/tsconfig.json +++ b/examples/tsconfig.json @@ -19,6 +19,7 @@ "@modelcontextprotocol/server/ext/skills": ["./node_modules/@modelcontextprotocol/server/src/ext/skills/index.ts"], "@modelcontextprotocol/server/ext/skills/node": ["./node_modules/@modelcontextprotocol/server/src/ext/skills/node.ts"], "@modelcontextprotocol/server/ext/events": ["./node_modules/@modelcontextprotocol/server/src/ext/events/index.ts"], + "@modelcontextprotocol/server/ext/events/node": ["./node_modules/@modelcontextprotocol/server/src/ext/events/node.ts"], "@modelcontextprotocol/core": ["./node_modules/@modelcontextprotocol/core/src/index.ts"], "@modelcontextprotocol/express": ["./node_modules/@modelcontextprotocol/express/src/index.ts"], "@modelcontextprotocol/fastify": ["./node_modules/@modelcontextprotocol/fastify/src/index.ts"], diff --git a/packages/core-internal/test/packageTopologyPins.test.ts b/packages/core-internal/test/packageTopologyPins.test.ts index 3a9398f878..0ae77c0981 100644 --- a/packages/core-internal/test/packageTopologyPins.test.ts +++ b/packages/core-internal/test/packageTopologyPins.test.ts @@ -45,13 +45,15 @@ const PUBLIC_PACKAGES: Record { + const url = URL.canParse(request.url) ? new URL(request.url) : undefined; + // Only a trusted origin may use plain http. + if (url === undefined || !(url.protocol === 'https:' || (request.trusted && url.protocol === 'http:'))) return REFUSED; + if (request.signal.aborted) return REFUSED; + const deadline = new AbortController(); + let timedOut = false; + const timer = setTimeout(() => { + timedOut = true; + deadline.abort(); + }, TIMEOUT_MS); + const stop = (): void => deadline.abort(); + request.signal.addEventListener('abort', stop, { once: true }); + try { + let lookup: LookupFunction | undefined; + if (!request.trusted) { + const addresses = await untilAborted(dns.promises.lookup(hostnameOf(url), { all: true }), deadline.signal); + const [first] = addresses; + if (first === undefined || addresses.some(({ address }) => isSpecialPurposeAddress(address))) return REFUSED; + lookup = pinnedTo(first); + } + return await post(url, request, lookup, deadline.signal); + } catch (error) { + return timedOut ? { error: 'timeout' } : failureOf(error); + } finally { + clearTimeout(timer); + request.signal.removeEventListener('abort', stop); + } +} + +// One POST; it rejects on a connection or TLS failure, and once `signal` aborts. +function post(url: URL, request: WebhookSendRequest, lookup: LookupFunction | undefined, signal: AbortSignal): Promise { + return new Promise((resolve, reject) => { + const onResponse = (response: IncomingMessage): void => { + const chunks: Buffer[] = []; + let size = 0; + const answer = (): void => + resolve({ status: response.statusCode!, body: Buffer.concat(chunks).toString('utf8', 0, MAX_RESPONSE_BYTES) }); + response.on('data', (chunk: Buffer) => { + chunks.push(chunk); + size += chunk.byteLength; + if (size < MAX_RESPONSE_BYTES) return; + answer(); + outgoing.destroy(); + }); + response.on('end', answer); + response.on('error', reject); + }; + // A fresh agent per request, so no pooled socket or global agent setting bypasses the pinned address; Host and SNI come from the URL. + const options: https.RequestOptions = { method: 'POST', headers: request.headers, agent: false, ...(lookup && { lookup }) }; + const outgoing = url.protocol === 'https:' ? https.request(url, options, onResponse) : http.request(url, options, onResponse); + outgoing.on('error', reject); + signal.addEventListener( + 'abort', + () => { + reject(signal.reason); + outgoing.destroy(); + }, + { once: true } + ); + outgoing.end(request.body); + }); +} + +// Settles as `promise` does, or rejects once `signal` aborts; a DNS lookup cannot itself be cancelled. +function untilAborted(promise: Promise, signal: AbortSignal): Promise { + return new Promise((resolve, reject) => { + const abort = (): void => reject(signal.reason); + signal.addEventListener('abort', abort, { once: true }); + promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort)); + }); +} + +// URL keeps the brackets of an IPv6 literal host; the resolver takes the bare address. +function hostnameOf(url: URL): string { + return url.hostname.startsWith('[') ? url.hostname.slice(1, -1) : url.hostname; +} + +// A lookup that answers with the checked address only, so the connection goes nowhere else. +function pinnedTo({ address, family }: LookupAddress): LookupFunction { + return (_hostname, options, callback) => { + if (options.all) callback(null, [{ address, family }]); + else callback(null, address, family); + }; +} + +// Certificate, verification and handshake failures are tls_error; every other failure (refused, reset, unreachable, unresolved) is connection_refused. +function failureOf(error: unknown): WebhookSendOutcome { + const code = (error as { code?: unknown } | null | undefined)?.code; + return typeof code === 'string' && TLS_FAILURE_CODE.test(code) ? { error: 'tls_error' } : REFUSED; +} diff --git a/packages/server/src/ext/events/specialAddresses.ts b/packages/server/src/ext/events/specialAddresses.ts new file mode 100644 index 0000000000..4cc0e940fd --- /dev/null +++ b/packages/server/src/ext/events/specialAddresses.ts @@ -0,0 +1,103 @@ +const OCTET = String.raw`(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)`; +const IPV4 = new RegExp(String.raw`^${OCTET}\.${OCTET}\.${OCTET}\.${OCTET}$`); +const HEX_GROUP = /^[\da-f]{1,4}$/i; + +interface Block { + readonly prefix: bigint; + readonly shift: bigint; +} + +function blockOf(cidr: string, bits: bigint, parse: (text: string) => bigint | undefined): Block { + const [address = '', length = ''] = cidr.split('/'); + const shift = bits - BigInt(length); + return { prefix: parse(address)! >> shift, shift }; +} + +function within(address: bigint, blocks: readonly Block[]): boolean { + return blocks.some(({ prefix, shift }) => address >> shift === prefix); +} + +function parseIpv4(text: string): bigint | undefined { + const octets = IPV4.exec(text)?.slice(1); + if (octets === undefined) return undefined; + let value = 0n; + for (const octet of octets) value = (value << 8n) | BigInt(octet); + return value; +} + +// The 16-bit groups of one side of `::`; a dotted IPv4 tail is allowed only at the very end of the address. +function groupsOf(part: string, last: boolean): number[] | undefined { + if (part === '') return []; + const pieces = part.split(':'); + const groups: number[] = []; + for (const [index, piece] of pieces.entries()) { + if (HEX_GROUP.test(piece)) { + groups.push(Number.parseInt(piece, 16)); + continue; + } + const ipv4 = last && index === pieces.length - 1 ? parseIpv4(piece) : undefined; + if (ipv4 === undefined) return undefined; + groups.push(Number(ipv4 >> 16n), Number(ipv4 & 0xff_ffn)); + } + return groups; +} + +function parseIpv6(text: string): bigint | undefined { + // A zone id (`fe80::1%en0`) does not change which range the address is in. + const halves = text.split('%', 1)[0]!.split('::'); + if (halves.length > 2) return undefined; + const head = groupsOf(halves[0]!, halves.length === 1); + const tail = halves.length === 2 ? groupsOf(halves[1]!, true) : []; + if (head === undefined || tail === undefined) return undefined; + const zeros = 8 - head.length - tail.length; + if (halves.length === 1 ? zeros !== 0 : zeros < 1) return undefined; + let value = 0n; + for (const group of [...head, ...Array.from({ length: halves.length === 2 ? zeros : 0 }, () => 0), ...tail]) { + value = (value << 16n) | BigInt(group); + } + return value; +} + +// Where webhooks are not delivered: ranges from the IANA IPv4 and IPv6 Special-Purpose Address Registries, and multicast. +const IPV4_SPECIAL = [ + '0.0.0.0/8', + '10.0.0.0/8', + '100.64.0.0/10', + '127.0.0.0/8', + '169.254.0.0/16', + '172.16.0.0/12', + '192.0.0.0/24', + '192.0.2.0/24', + '192.88.99.0/24', + '192.168.0.0/16', + '198.18.0.0/15', + '198.51.100.0/24', + '203.0.113.0/24', + '224.0.0.0/4', + '240.0.0.0/4' +].map(cidr => blockOf(cidr, 32n, parseIpv4)); +const IPV6_SPECIAL = [ + '::/128', + '::1/128', + '64:ff9b::/96', + '64:ff9b:1::/48', + '100::/64', + '2001::/23', + '2001:db8::/32', + '2002::/16', + '3fff::/20', + '5f00::/16', + 'fc00::/7', + 'fe80::/10', + 'ff00::/8' +].map(cidr => blockOf(cidr, 128n, parseIpv6)); + +// Whether `ip` is in a special-purpose range, an IPv4-mapped IPv6 address (`::ffff:0:0/96`) by its IPv4 part; anything that is not an IP address counts as special. +export function isSpecialPurposeAddress(ip: string): boolean { + const ipv4 = parseIpv4(ip); + if (ipv4 !== undefined) return within(ipv4, IPV4_SPECIAL); + const ipv6 = parseIpv6(ip); + if (ipv6 === undefined) return true; + if (ipv6 >> 32n === 0xff_ffn) return within(ipv6 & 0xff_ff_ff_ffn, IPV4_SPECIAL); + return within(ipv6, IPV6_SPECIAL); +} diff --git a/packages/server/test/ext/events/node.test.ts b/packages/server/test/ext/events/node.test.ts new file mode 100644 index 0000000000..afa9f0d790 --- /dev/null +++ b/packages/server/test/ext/events/node.test.ts @@ -0,0 +1,271 @@ +import dns from 'node:dns'; +import http from 'node:http'; +import https from 'node:https'; +import type { AddressInfo } from 'node:net'; +import net from 'node:net'; +import { Writable } from 'node:stream'; + +import type { MockInstance } from 'vitest'; +import { afterEach, describe, expect, it, vi } from 'vitest'; + +import { nodeWebhookSender } from '../../../src/ext/events/node'; +import { isSpecialPurposeAddress } from '../../../src/ext/events/specialAddresses'; +import type { WebhookSendRequest } from '../../../src/ext/events/types'; + +vi.mock('../../../src/ext/events/specialAddresses', async importOriginal => { + const actual = await importOriginal(); + return { isSpecialPurposeAddress: vi.fn(actual.isSpecialPurposeAddress) }; +}); + +const HEADERS = { + 'Content-Type': 'application/json', + 'webhook-id': 'msg_2KWPBgLlAfxdpx2AI54pPJ85f4W', + 'webhook-timestamp': '1763460000', + 'webhook-signature': 'v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=', + 'X-MCP-Subscription-Id': 'sub_1' +}; +const BODY = JSON.stringify({ eventId: 'e1', name: 'e', timestamp: '2026-11-18T00:00:00.000Z', data: { n: 1 }, cursor: 'c1' }); +const REFUSED = { error: 'connection_refused' }; + +const servers: net.Server[] = []; + +afterEach(async () => { + vi.restoreAllMocks(); + vi.mocked(isSpecialPurposeAddress).mockReset(); + await Promise.all( + servers.splice(0).map( + server => + new Promise(resolve => { + if (server instanceof http.Server) server.closeAllConnections(); + server.close(() => resolve()); + }) + ) + ); +}); + +async function listen(server: net.Server): Promise { + servers.push(server); + await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); + return (server.address() as AddressInfo).port; +} + +// A raw TCP server that counts connections and closes each one at once. +async function countingServer(): Promise<{ port: number; connections: () => number }> { + let connections = 0; + const port = await listen( + net.createServer(socket => { + connections += 1; + socket.destroy(); + }) + ); + return { port, connections: () => connections }; +} + +function sendRequest(url: string, trusted: boolean, signal = new AbortController().signal): WebhookSendRequest { + return { url, headers: HEADERS, body: BODY, trusted, signal }; +} + +// Each call of dns.promises.lookup answers with the next list of addresses; a call past them fails with ENOTFOUND. +function stubLookup(...answers: string[][]): MockInstance { + const lookup = vi.spyOn(dns.promises, 'lookup') as unknown as MockInstance< + (hostname: string, options: dns.LookupAllOptions) => Promise + >; + lookup.mockRejectedValue(Object.assign(new Error('getaddrinfo ENOTFOUND'), { code: 'ENOTFOUND' })); + for (const answer of answers) lookup.mockResolvedValueOnce(answer.map(address => ({ address, family: net.isIP(address) }))); + return lookup; +} + +// Classifies `ip` as a public address, so a loopback server can stand in for a remote receiver. +async function treatAsPublic(ip: string): Promise { + const actual = await vi.importActual( + '../../../src/ext/events/specialAddresses' + ); + vi.mocked(isSpecialPurposeAddress).mockImplementation(address => address !== ip && actual.isSpecialPurposeAddress(address)); +} + +// A stand-in for the outgoing request that fails with `code` once its body is sent. +function failingRequest(code: string): http.ClientRequest { + const outgoing = new Writable({ + write: (_chunk, _encoding, callback) => callback(), + final: callback => callback(Object.assign(new Error(code), { code })) + }); + return outgoing as unknown as http.ClientRequest; +} + +describe('nodeWebhookSender', () => { + it('posts to a trusted http origin with the given headers and body', async () => { + let seen: { method?: string; url?: string; headers: http.IncomingHttpHeaders; body: string } | undefined; + const port = await listen( + http.createServer((req, res) => { + let body = ''; + req.setEncoding('utf8'); + req.on('data', (chunk: string) => (body += chunk)); + req.on('end', () => { + seen = { method: req.method, url: req.url, headers: req.headers, body }; + res.writeHead(200, { 'Content-Type': 'application/json' }).end('{"ok":true}'); + }); + }) + ); + + const outcome = await nodeWebhookSender()(sendRequest(`http://127.0.0.1:${port}/hooks/mcp?tenant=1`, true)); + + expect(outcome).toEqual({ status: 200, body: '{"ok":true}' }); + expect(seen).toMatchObject({ + method: 'POST', + url: '/hooks/mcp?tenant=1', + body: BODY, + headers: { + ...Object.fromEntries(Object.entries(HEADERS).map(([name, value]) => [name.toLowerCase(), value])), + host: `127.0.0.1:${port}` + } + }); + }); + + it('refuses an untrusted loopback url without connecting', async () => { + const receiver = await countingServer(); + + expect(await nodeWebhookSender()(sendRequest(`https://127.0.0.1:${receiver.port}/x`, false))).toEqual(REFUSED); + expect(receiver.connections()).toBe(0); + }); + + it('checks the address of an IPv6 literal host', async () => { + const lookup = vi.spyOn(dns.promises, 'lookup'); + + expect(await nodeWebhookSender()(sendRequest('https://[::1]:8443/x', false))).toEqual(REFUSED); + expect(lookup).toHaveBeenCalledWith('::1', { all: true }); + }); + + it('refuses http for an untrusted origin', async () => { + const lookup = stubLookup(); + + expect(await nodeWebhookSender()(sendRequest('http://example.com/hooks', false))).toEqual(REFUSED); + expect(lookup).not.toHaveBeenCalled(); + }); + + it('refuses when any resolved address is special, without connecting', async () => { + const receiver = await countingServer(); + await treatAsPublic('127.0.0.1'); + stubLookup(['127.0.0.1', '10.0.0.1']); + + expect(await nodeWebhookSender()(sendRequest(`https://hooks.example.test:${receiver.port}/x`, false))).toEqual(REFUSED); + expect(receiver.connections()).toBe(0); + }); + + it('connects to the checked address and sends the URL host name as TLS SNI', async () => { + let clientHello: Buffer | undefined; + const port = await listen( + net.createServer(socket => + socket.once('data', (chunk: Buffer) => { + clientHello = chunk; + socket.destroy(); + }) + ) + ); + await treatAsPublic('127.0.0.1'); + const lookup = stubLookup(['127.0.0.1']); + + // The receiver resets the connection after reading the ClientHello. + expect(await nodeWebhookSender()(sendRequest(`https://hooks.example.test:${port}/x`, false))).toEqual(REFUSED); + expect(lookup).toHaveBeenCalledWith('hooks.example.test', { all: true }); + expect(clientHello?.includes('hooks.example.test')).toBe(true); + }); + + it('checks the resolved address at every send', async () => { + const receiver = await countingServer(); + await treatAsPublic('127.0.0.1'); + stubLookup(['127.0.0.1'], ['10.0.0.1']); + const send = nodeWebhookSender(); + + await send(sendRequest(`https://hooks.example.test:${receiver.port}/x`, false)); + expect(receiver.connections()).toBe(1); + expect(await send(sendRequest(`https://hooks.example.test:${receiver.port}/x`, false))).toEqual(REFUSED); + expect(receiver.connections()).toBe(1); + }); + + it('does not follow redirects', async () => { + let followed = 0; + const other = await listen( + http.createServer((_req, res) => { + followed += 1; + res.end(); + }) + ); + const port = await listen( + http.createServer((req, res) => { + req.resume(); + res.writeHead(302, { Location: `http://127.0.0.1:${other}/next` }).end(); + }) + ); + + expect(await nodeWebhookSender()(sendRequest(`http://127.0.0.1:${port}/x`, true))).toEqual({ status: 302, body: '' }); + expect(followed).toBe(0); + }); + + it('times out a hanging receiver after 5 s', async () => { + const port = await listen(http.createServer(() => {})); + const started = Date.now(); + + expect(await nodeWebhookSender()(sendRequest(`http://127.0.0.1:${port}/x`, true))).toEqual({ error: 'timeout' }); + expect(Date.now() - started).toBeGreaterThanOrEqual(4900); + }, 10_000); + + it('reads at most 65 536 bytes of the response body', async () => { + const port = await listen( + http.createServer((req, res) => { + req.resume(); + res.end('a'.repeat(100_000)); + }) + ); + + expect(await nodeWebhookSender()(sendRequest(`http://127.0.0.1:${port}/x`, true))).toEqual({ + status: 200, + body: 'a'.repeat(65_536) + }); + }); + + it('reports a receiver that does not speak TLS as tls_error', async () => { + const port = await listen(http.createServer((_req, res) => res.end())); + + expect(await nodeWebhookSender()(sendRequest(`https://127.0.0.1:${port}/x`, true))).toEqual({ error: 'tls_error' }); + }); + + it.each([ + ['UNABLE_TO_VERIFY_LEAF_SIGNATURE', 'tls_error'], + ['INVALID_CA', 'tls_error'], + ['SELF_SIGNED_CERT_IN_CHAIN', 'tls_error'], + ['DEPTH_ZERO_SELF_SIGNED_CERT', 'tls_error'], + ['CERT_HAS_EXPIRED', 'tls_error'], + ['ERR_TLS_CERT_ALTNAME_INVALID', 'tls_error'], + ['ERR_SSL_WRONG_VERSION_NUMBER', 'tls_error'], + ['EPROTO', 'tls_error'], + ['ECONNREFUSED', 'connection_refused'], + ['ECONNRESET', 'connection_refused'], + ['EHOSTUNREACH', 'connection_refused'], + ['ENOTFOUND', 'connection_refused'] + ])('maps a request that fails with %s to %s', async (code, category) => { + vi.spyOn(https, 'request').mockImplementation(() => failingRequest(code)); + + expect(await nodeWebhookSender()(sendRequest('https://127.0.0.1:8443/x', true))).toEqual({ error: category }); + }); + + it('reports a closed port as connection_refused', async () => { + const server = net.createServer(); + const port = await listen(server); + await new Promise(resolve => server.close(() => resolve())); + + expect(await nodeWebhookSender()(sendRequest(`http://127.0.0.1:${port}/x`, true))).toEqual(REFUSED); + }); + + it('resolves rather than rejects when its signal aborts', async () => { + let received!: () => void; + const arrived = new Promise(resolve => (received = resolve)); + const port = await listen(http.createServer(() => received())); + const controller = new AbortController(); + + const outcome = nodeWebhookSender()(sendRequest(`http://127.0.0.1:${port}/x`, true, controller.signal)); + await arrived; + controller.abort(); + + expect(await outcome).toEqual(REFUSED); + }); +}); diff --git a/packages/server/test/ext/events/specialAddresses.test.ts b/packages/server/test/ext/events/specialAddresses.test.ts new file mode 100644 index 0000000000..b97796a815 --- /dev/null +++ b/packages/server/test/ext/events/specialAddresses.test.ts @@ -0,0 +1,83 @@ +import { describe, expect, it } from 'vitest'; + +import { isSpecialPurposeAddress } from '../../../src/ext/events/specialAddresses'; + +describe('isSpecialPurposeAddress', () => { + it.each([ + '127.0.0.1', + '10.1.2.3', + '169.254.169.254', + '192.168.1.1', + '100.64.0.1', + '::1', + 'fe80::1', + 'fd00::1', + '::ffff:127.0.0.1', + '2001:db8::1' + ])('flags %s', ip => { + expect(isSpecialPurposeAddress(ip)).toBe(true); + }); + + it.each(['8.8.8.8', '1.1.1.1', '2606:4700:4700::1111'])('allows %s', ip => expect(isSpecialPurposeAddress(ip)).toBe(false)); + + it.each([ + ['0.0.0.0/8', '0.255.255.255'], + ['10.0.0.0/8', '10.255.255.255'], + ['100.64.0.0/10', '100.127.255.255'], + ['127.0.0.0/8', '127.255.255.255'], + ['169.254.0.0/16', '169.254.0.0'], + ['172.16.0.0/12', '172.31.255.255'], + ['192.0.0.0/24', '192.0.0.255'], + ['192.0.2.0/24', '192.0.2.1'], + ['192.88.99.0/24', '192.88.99.1'], + ['192.168.0.0/16', '192.168.255.255'], + ['198.18.0.0/15', '198.19.255.255'], + ['198.51.100.0/24', '198.51.100.1'], + ['203.0.113.0/24', '203.0.113.1'], + ['224.0.0.0/4', '239.255.255.255'], + ['240.0.0.0/4', '255.255.255.255'], + ['::/128', '::'], + ['::1/128', '0:0:0:0:0:0:0:1'], + ['64:ff9b::/96', '64:ff9b::808:808'], + ['64:ff9b:1::/48', '64:ff9b:1:ffff::1'], + ['100::/64', '100::ffff:ffff:ffff:ffff'], + ['2001::/23', '2001:1ff::1'], + ['2001:db8::/32', '2001:DB8:ffff::1'], + ['2002::/16', '2002:c000:204::1'], + ['3fff::/20', '3fff:fff:ffff::1'], + ['5f00::/16', '5f00:ffff::1'], + ['fc00::/7', 'fdff::1'], + ['fe80::/10', 'febf::1'], + ['ff00::/8', 'ff02::1'], + ['::ffff:0:0/96 by its IPv4 part', '::ffff:a00:1'], + ['a zone id', 'fe80::1%lo0'] + ])('flags an address in %s (%s)', (_range, ip) => { + expect(isSpecialPurposeAddress(ip)).toBe(true); + }); + + it.each([ + '9.255.255.255', + '11.0.0.0', + '100.128.0.0', + '172.15.255.255', + '172.32.0.0', + '198.20.0.0', + '223.255.255.255', + '::2', + '64:ff9b:2::1', + '2001:200::1', + '2003::1', + '3fff:1000::1', + '5f01::1', + '::ffff:8.8.8.8' + ])('allows %s next to a special range', ip => { + expect(isSpecialPurposeAddress(ip)).toBe(false); + }); + + it.each(['example.com', '', '256.0.0.1', '01.2.3.4', '1.2.3', '1::2::3', '1:2:3:4:5:6:7:8:9', '12345::', '::1.2.3.4.5'])( + 'counts %j, which is not an IP address, as special', + text => { + expect(isSpecialPurposeAddress(text)).toBe(true); + } + ); +}); diff --git a/packages/server/test/server/barrelClean.test.ts b/packages/server/test/server/barrelClean.test.ts index d0fbb499d8..a59db62c96 100644 --- a/packages/server/test/server/barrelClean.test.ts +++ b/packages/server/test/server/barrelClean.test.ts @@ -146,6 +146,12 @@ describe('@modelcontextprotocol/server root, ext/skills and ext/events are runti expect(moduleGraphOf(node).some(file => NODE_BUILTIN_IMPORT.test(readFileSync(file, 'utf8')))).toBe(true); }); + test('ext/events/node exports only the webhook sender, and its node: imports live in that entry alone', () => { + const node = join(distDir, 'ext/events/node.mjs'); + expect(rootExportBlockOf(readFileSync(node, 'utf8')).trim()).toBe('export { nodeWebhookSender };'); + expect(moduleGraphOf(node).filter(file => NODE_BUILTIN_IMPORT.test(readFileSync(file, 'utf8')))).toEqual([node]); + }); + test('the root entry does not export the skills extension', () => { expect(rootExportBlockOf(readFileSync(join(distDir, 'index.mjs'), 'utf8'))).not.toMatch( /\b(?:SkillsExtension|SkillCatalog|loadSkills|nodeSkillFiles)\b/ diff --git a/packages/server/tsdown.config.ts b/packages/server/tsdown.config.ts index 08200ea2f2..992660abf7 100644 --- a/packages/server/tsdown.config.ts +++ b/packages/server/tsdown.config.ts @@ -12,7 +12,8 @@ export default defineConfig({ 'src/validators/cfWorker.ts', 'src/ext/skills/index.ts', 'src/ext/skills/node.ts', - 'src/ext/events/index.ts' + 'src/ext/events/index.ts', + 'src/ext/events/node.ts' ], format: ['esm', 'cjs'], fixedExtension: true, diff --git a/test/conformance/tsconfig.json b/test/conformance/tsconfig.json index 59f6fb2b6e..12844d5236 100644 --- a/test/conformance/tsconfig.json +++ b/test/conformance/tsconfig.json @@ -31,6 +31,7 @@ "@modelcontextprotocol/client/ext/skills": ["./node_modules/@modelcontextprotocol/client/src/ext/skills/index.ts"], "@modelcontextprotocol/server/ext/skills": ["./node_modules/@modelcontextprotocol/server/src/ext/skills/index.ts"], "@modelcontextprotocol/server/ext/events": ["./node_modules/@modelcontextprotocol/server/src/ext/events/index.ts"], + "@modelcontextprotocol/server/ext/events/node": ["./node_modules/@modelcontextprotocol/server/src/ext/events/node.ts"], "@modelcontextprotocol/express": ["./node_modules/@modelcontextprotocol/express/src/index.ts"], "@modelcontextprotocol/node": ["./node_modules/@modelcontextprotocol/node/src/index.ts"], "@modelcontextprotocol/vitest-config": ["./node_modules/@modelcontextprotocol/vitest-config/tsconfig.json"], diff --git a/test/e2e/tsconfig.json b/test/e2e/tsconfig.json index 5208150f7c..5f0ed70e04 100644 --- a/test/e2e/tsconfig.json +++ b/test/e2e/tsconfig.json @@ -40,6 +40,7 @@ "@modelcontextprotocol/server/validators/cf-worker": ["./node_modules/@modelcontextprotocol/server/src/validators/cfWorker.ts"], "@modelcontextprotocol/server/ext/skills": ["./node_modules/@modelcontextprotocol/server/src/ext/skills/index.ts"], "@modelcontextprotocol/server/ext/events": ["./node_modules/@modelcontextprotocol/server/src/ext/events/index.ts"], + "@modelcontextprotocol/server/ext/events/node": ["./node_modules/@modelcontextprotocol/server/src/ext/events/node.ts"], "@modelcontextprotocol/server-legacy": ["./node_modules/@modelcontextprotocol/server-legacy/src/index.ts"], "@modelcontextprotocol/server-legacy/sse": ["./node_modules/@modelcontextprotocol/server-legacy/src/sse/index.ts"], "@modelcontextprotocol/express": ["./node_modules/@modelcontextprotocol/express/src/index.ts"], diff --git a/test/integration/tsconfig.json b/test/integration/tsconfig.json index e92659d52d..e2fc237c71 100644 --- a/test/integration/tsconfig.json +++ b/test/integration/tsconfig.json @@ -44,6 +44,7 @@ "@modelcontextprotocol/server/ext/skills": ["./node_modules/@modelcontextprotocol/server/src/ext/skills/index.ts"], "@modelcontextprotocol/server/ext/skills/node": ["./node_modules/@modelcontextprotocol/server/src/ext/skills/node.ts"], "@modelcontextprotocol/server/ext/events": ["./node_modules/@modelcontextprotocol/server/src/ext/events/index.ts"], + "@modelcontextprotocol/server/ext/events/node": ["./node_modules/@modelcontextprotocol/server/src/ext/events/node.ts"], "@modelcontextprotocol/express": ["./node_modules/@modelcontextprotocol/express/src/index.ts"], "@modelcontextprotocol/node": ["./node_modules/@modelcontextprotocol/node/src/index.ts"], "@modelcontextprotocol/vitest-config": ["./node_modules/@modelcontextprotocol/vitest-config/tsconfig.json"], From 364930934ed2b5696b1c9efe01e61abda382da52 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 14:10:54 +0200 Subject: [PATCH 12/37] fix(server): classify NAT64 well-known prefix by its embedded IPv4 --- packages/server/src/ext/events/specialAddresses.ts | 7 ++++--- packages/server/test/ext/events/specialAddresses.test.ts | 4 +++- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/packages/server/src/ext/events/specialAddresses.ts b/packages/server/src/ext/events/specialAddresses.ts index 4cc0e940fd..f3862e210f 100644 --- a/packages/server/src/ext/events/specialAddresses.ts +++ b/packages/server/src/ext/events/specialAddresses.ts @@ -79,7 +79,6 @@ const IPV4_SPECIAL = [ const IPV6_SPECIAL = [ '::/128', '::1/128', - '64:ff9b::/96', '64:ff9b:1::/48', '100::/64', '2001::/23', @@ -91,13 +90,15 @@ const IPV6_SPECIAL = [ 'fe80::/10', 'ff00::/8' ].map(cidr => blockOf(cidr, 128n, parseIpv6)); +// IPv4-mapped (`::ffff:0:0/96`) and well-known-prefix NAT64 (`64:ff9b::/96`) addresses carry an IPv4 address in their low 32 bits. +const EMBEDS_IPV4 = ['::ffff:0:0/96', '64:ff9b::/96'].map(cidr => blockOf(cidr, 128n, parseIpv6)); -// Whether `ip` is in a special-purpose range, an IPv4-mapped IPv6 address (`::ffff:0:0/96`) by its IPv4 part; anything that is not an IP address counts as special. +// Whether `ip` is in a special-purpose range, an address that embeds an IPv4 address by that IPv4 part; anything that is not an IP address counts as special. export function isSpecialPurposeAddress(ip: string): boolean { const ipv4 = parseIpv4(ip); if (ipv4 !== undefined) return within(ipv4, IPV4_SPECIAL); const ipv6 = parseIpv6(ip); if (ipv6 === undefined) return true; - if (ipv6 >> 32n === 0xff_ffn) return within(ipv6 & 0xff_ff_ff_ffn, IPV4_SPECIAL); + if (within(ipv6, EMBEDS_IPV4)) return within(ipv6 & 0xff_ff_ff_ffn, IPV4_SPECIAL); return within(ipv6, IPV6_SPECIAL); } diff --git a/packages/server/test/ext/events/specialAddresses.test.ts b/packages/server/test/ext/events/specialAddresses.test.ts index b97796a815..0e00af14ac 100644 --- a/packages/server/test/ext/events/specialAddresses.test.ts +++ b/packages/server/test/ext/events/specialAddresses.test.ts @@ -38,7 +38,8 @@ describe('isSpecialPurposeAddress', () => { ['240.0.0.0/4', '255.255.255.255'], ['::/128', '::'], ['::1/128', '0:0:0:0:0:0:0:1'], - ['64:ff9b::/96', '64:ff9b::808:808'], + ['64:ff9b::/96 by its IPv4 part', '64:ff9b::a00:1'], + ['64:ff9b::/96 by its IPv4 part', '64:ff9b::127.0.0.1'], ['64:ff9b:1::/48', '64:ff9b:1:ffff::1'], ['100::/64', '100::ffff:ffff:ffff:ffff'], ['2001::/23', '2001:1ff::1'], @@ -64,6 +65,7 @@ describe('isSpecialPurposeAddress', () => { '198.20.0.0', '223.255.255.255', '::2', + '64:ff9b::808:808', '64:ff9b:2::1', '2001:200::1', '2003::1', From 199befc707bc5f4cbada801407bc3efe0da8c7b8 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 14:22:02 +0200 Subject: [PATCH 13/37] feat(server): validate Mcp-Param headers on events requests --- packages/server/src/ext/events/extension.ts | 7 +- .../server/src/server/createMcpHandler.ts | 21 +++-- .../server/src/server/paramHeaderSources.ts | 18 ++++ .../server/test/ext/events/mcpParam.test.ts | 92 +++++++++++++++++++ 4 files changed, 131 insertions(+), 7 deletions(-) create mode 100644 packages/server/src/server/paramHeaderSources.ts create mode 100644 packages/server/test/ext/events/mcpParam.test.ts diff --git a/packages/server/src/ext/events/extension.ts b/packages/server/src/ext/events/extension.ts index a24b7292d6..3baeff45bb 100644 --- a/packages/server/src/ext/events/extension.ts +++ b/packages/server/src/ext/events/extension.ts @@ -18,6 +18,7 @@ import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; import type { McpServer } from '../../server/mcp'; import { markModernOnlyExtension } from '../../server/modernOnlyExtensions'; +import { registerParamHeaderSource } from '../../server/paramHeaderSources'; import { markStreamingMethod } from '../../server/streamingMethods'; import type { BufferedEvent } from './emitBuffer'; import { EmitBuffer } from './emitBuffer'; @@ -43,7 +44,10 @@ export type EmitFanOut = (name: string, buffered: BufferedEvent, positions: { cu type DefaultSchema = StandardSchemaWithJSON>; -const EVENTS_METHODS = [EVENTS_LIST_METHOD, EVENTS_POLL_METHOD, EVENTS_STREAM_METHOD, EVENTS_SUBSCRIBE_METHOD, EVENTS_UNSUBSCRIBE_METHOD]; +// The `events/*` requests that name an event type in `params.name`. +const NAMED_EVENT_METHODS = [EVENTS_POLL_METHOD, EVENTS_STREAM_METHOD, EVENTS_SUBSCRIBE_METHOD, EVENTS_UNSUBSCRIBE_METHOD]; + +const EVENTS_METHODS = [EVENTS_LIST_METHOD, ...NAMED_EVENT_METHODS]; const NUMERIC_OPTIONS = [ 'webhookTtlMs', @@ -266,6 +270,7 @@ export class EventsExtension { server.registerCapabilities({ extensions: { [EVENTS_EXTENSION_ID]: {} } }); markModernOnlyExtension(server, EVENTS_EXTENSION_ID); markStreamingMethod(server, EVENTS_STREAM_METHOD); + registerParamHeaderSource(mcp, NAMED_EVENT_METHODS, name => this.#registry.get(name)?.inputJson); this.#attached.add(mcp); eventsServers.add(mcp); } diff --git a/packages/server/src/server/createMcpHandler.ts b/packages/server/src/server/createMcpHandler.ts index fdf626e721..33febddabf 100644 --- a/packages/server/src/server/createMcpHandler.ts +++ b/packages/server/src/server/createMcpHandler.ts @@ -62,6 +62,7 @@ import { import { invoke } from './invoke'; import { createListenRouter, DEFAULT_MAX_SUBSCRIPTIONS } from './listenRouter'; import { McpServer } from './mcp'; +import { paramHeaderSchemaFor } from './paramHeaderSources'; import type { PerRequestResponseMode } from './perRequestTransport'; import { DEFAULT_MAX_REQUEST_BODY_SIZE, readRequestBody, requestBodyTooLargeMessage, resolveMaxRequestBodySize } from './requestBody'; import { createScopeChallengeResponse, findScopeChallenge, scopeChallengeResourceMetadataUrl } from './scopeChallenge'; @@ -817,8 +818,10 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa } // SEP-2243 `Mcp-Param-*` server-side validation (pre-dispatch ladder - // rung): for a `tools/call`, look up the named tool's JSON inputSchema - // on the just-produced instance and compare every `x-mcp-header` + // rung): look up the JSON inputSchema that `params.name` names on the + // just-produced instance (for a `tools/call` the named tool's; for + // another method the one an extension registered a lookup for, see + // `paramHeaderSources.ts`) and compare every `x-mcp-header` // declaration against the request's `Mcp-Param-{Name}` headers and the // body `arguments`. A mismatch (or a missing header for a present body // value, or an invalid Base64 sentinel) emits the same `400` / @@ -826,13 +829,19 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa // applied when the factory returns an `McpServer` (the registry is the // schema source); a low-level `Server` factory has no registry, so // there is nothing to validate against. - if (route.messageKind === 'request' && route.message.method === 'tools/call' && product instanceof McpServer) { + if (route.messageKind === 'request' && product instanceof McpServer) { + const { method } = route.message; const callParams = route.message.params as { name?: string; arguments?: Record } | undefined; - const toolName = typeof callParams?.name === 'string' ? callParams.name : undefined; - const inputSchema = toolName === undefined ? undefined : product.toolInputSchemaJson(toolName); + const name = typeof callParams?.name === 'string' ? callParams.name : undefined; + const inputSchema = + name === undefined + ? undefined + : method === 'tools/call' + ? product.toolInputSchemaJson(name) + : paramHeaderSchemaFor(product, method, name); if (inputSchema !== undefined) { const scan = scanXMcpHeaderDeclarations(inputSchema); - // A tool that is invalid only for a `number`-typed declaration is still checked. + // A schema that is invalid only for a `number`-typed declaration is still checked. if (scan.declarations !== undefined && scan.declarations.length > 0) { const rejection = validateMcpParamHeaders(scan.declarations, callParams?.arguments, request.headers); if (rejection !== undefined) { diff --git a/packages/server/src/server/paramHeaderSources.ts b/packages/server/src/server/paramHeaderSources.ts new file mode 100644 index 0000000000..89281a748b --- /dev/null +++ b/packages/server/src/server/paramHeaderSources.ts @@ -0,0 +1,18 @@ +import type { McpServer } from './mcp'; + +type ParamHeaderSchemaLookup = (name: string) => Record | undefined; + +// Per server, the methods besides `tools/call` whose `Mcp-Param-*` headers `createMcpHandler` validates, each with its schema lookup by `params.name`. +const sources = new WeakMap>(); + +// Makes `createMcpHandler` validate `Mcp-Param-*` headers on `methods` against the JSON inputSchema `resolve` returns for `params.name`. +export function registerParamHeaderSource(mcp: McpServer, methods: readonly string[], resolve: ParamHeaderSchemaLookup): void { + const lookups = sources.get(mcp) ?? new Map(); + for (const method of methods) lookups.set(method, resolve); + sources.set(mcp, lookups); +} + +// The JSON inputSchema whose `x-mcp-header` declarations a `method` request naming `name` is checked against, if one was registered. +export function paramHeaderSchemaFor(mcp: McpServer, method: string, name: string): Record | undefined { + return sources.get(mcp)?.get(method)?.(name); +} diff --git a/packages/server/test/ext/events/mcpParam.test.ts b/packages/server/test/ext/events/mcpParam.test.ts new file mode 100644 index 0000000000..42dd885643 --- /dev/null +++ b/packages/server/test/ext/events/mcpParam.test.ts @@ -0,0 +1,92 @@ +import type { JSONRPCRequest } from '@modelcontextprotocol/core-internal'; +import { encodeMcpParamValue } from '@modelcontextprotocol/core-internal'; +import { describe, expect, it } from 'vitest'; +import * as z from 'zod/v4'; + +import { EventsExtension } from '../../../src/ext/events/index'; +import { serve } from './harness'; + +const P = z.object({ n: z.number() }); +const INPUT = z.object({ region: z.string().meta({ 'x-mcp-header': 'Region' }), severity: z.string().optional() }); +const NAME = 'incident.created'; +const HOOK = 'https://hooks.example.com/mcp'; +const SECRET = `whsec_${btoa('x'.repeat(32))}`; + +let nextId = 1; + +function request(method: string, params: Record): JSONRPCRequest { + return { jsonrpc: '2.0', id: nextId++, method, params }; +} + +function pollRequest(args: Record): JSONRPCRequest { + return request('events/poll', { name: NAME, arguments: args, cursor: null }); +} + +// One event type with a Region header annotation, served beside a tool with the same annotation. +function served() { + const events = new EventsExtension(); + events.registerEvent(NAME, { inputSchema: INPUT, payloadSchema: P, check: () => ({ events: [], cursor: 'h1' }) }); + return serve(events, { + setup: mcp => mcp.registerTool('route', { inputSchema: INPUT }, async () => ({ content: [] })) + }); +} + +interface Reply { + result?: Record; + error?: { code: number; data?: { mismatch?: { header?: string } } }; +} + +describe('Mcp-Param headers on events requests', () => { + it('rejects a poll whose Mcp-Param-Region is missing', async () => { + const { post } = served(); + const res = await post(pollRequest({ region: 'us-west1' })); + expect(res.status).toBe(400); + const reply = (await res.json()) as Reply; + expect(reply.error?.code).toBe(-32_020); + expect(reply.error?.data?.mismatch?.header).toBe('Mcp-Param-Region'); + }); + + it('accepts a matching header', async () => { + const { post } = served(); + const res = await post(pollRequest({ region: 'us-west1', severity: 'high' }), { headers: { 'Mcp-Param-Region': 'us-west1' } }); + expect(res.status).toBe(200); + expect(((await res.json()) as Reply).result).toMatchObject({ events: [], cursor: 'h1' }); + }); + + it('accepts a non-ASCII value in the base64 sentinel (Review Focus 4)', async () => { + const { post } = served(); + const header = encodeMcpParamValue('zürich'); + expect(header).toMatch(/^=\?base64\?.+\?=$/); + const res = await post(pollRequest({ region: 'zürich' }), { headers: { 'Mcp-Param-Region': header } }); + expect(res.status).toBe(200); + expect(((await res.json()) as Reply).result).toMatchObject({ cursor: 'h1' }); + }); + + it.each([ + ['events/stream', {}], + ['events/subscribe', { delivery: { mode: 'webhook', url: HOOK, secret: SECRET } }], + ['events/unsubscribe', { delivery: { url: HOOK } }] + ])('rejects a mismatch on %s too', async (method, extra) => { + const { post } = served(); + // Ends the stream an unvalidated events/stream would open. + const controller = new AbortController(); + try { + const res = await post(request(method, { name: NAME, arguments: { region: 'us-west1' }, ...extra }), { + headers: { 'Mcp-Param-Region': 'eu-west1' }, + signal: controller.signal + }); + expect(res.status).toBe(400); + expect(((await res.json()) as Reply).error?.code).toBe(-32_020); + } finally { + controller.abort(); + } + }); + + it('leaves tools/call validation unchanged', async () => { + const { post } = served(); + const call = request('tools/call', { name: 'route', arguments: { region: 'us-west1' } }); + const res = await post(call, { headers: { 'Mcp-Param-Region': 'eu-west1' } }); + expect(res.status).toBe(400); + expect(((await res.json()) as Reply).error?.code).toBe(-32_020); + }); +}); From d328c39ff8b8b477e70ca08c6d215936bdff1954 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 14:40:15 +0200 Subject: [PATCH 14/37] feat(client): internal long-lived request streams --- packages/client/src/client/client.ts | 101 +++++++ .../client/test/client/openStream.test.ts | 260 ++++++++++++++++++ 2 files changed, 361 insertions(+) create mode 100644 packages/client/test/client/openStream.test.ts diff --git a/packages/client/src/client/client.ts b/packages/client/src/client/client.ts index f071b13e50..71f41ec58e 100644 --- a/packages/client/src/client/client.ts +++ b/packages/client/src/client/client.ts @@ -437,8 +437,23 @@ const LIST_CHANGED_EVICTIONS: Readonly> = { const DEFAULT_LIST_MAX_PAGES = 64; +// How an `openStream` request ended: `local` on close(), `graceful` on a result, else `remote` (`error` on an error response or failed send). +export type StreamEnd = { cause: 'local' } | { cause: 'graceful'; result: Record } | { cause: 'remote'; error?: Error }; + +// A long-lived request opened by `clientInternals.openStream`; `id` is its JSON-RPC id and the subscription id its frames carry. +export interface StreamHandle { + readonly id: string; + close(): Promise; +} + // Package-internal (not exported from the package): what the `ext/` clients share with Client. Set in Client's static block. export const clientInternals = {} as { + openStream( + client: Client, + request: { method: string; params: Record }, + handlers: { onNotification(notification: JSONRPCNotification): void; onEnd(end: StreamEnd): void }, + options?: { headers?: Readonly> } + ): StreamHandle; enforceStrictCapabilities(client: Client): boolean; walkPages( client: Client, @@ -585,12 +600,16 @@ export class Client extends Protocol { */ private _listenState = new Map(); private _nextListenId = 0; + // Live `openStream` requests keyed by their `stream:N` id; an entry is removed when its stream ends. + private _streamState = new Map(); + private _nextStreamId = 0; /** The auto-opened subscription backing ClientOptions.listChanged on a modern connection. */ private _autoOpenedSubscription?: McpSubscription; /** Backing store for {@linkcode getDiscoverResult}. Per-connection. */ private _discoverResult?: DiscoverResult; static { + clientInternals.openStream = (client, request, handlers, options) => client._openStream(request, handlers, options); clientInternals.enforceStrictCapabilities = client => client._enforceStrictCapabilities; clientInternals.walkPages = (client, method, fetchPage, items) => client._walkPages(method, fetchPage, items); clientInternals.readResource = (client, params, options) => client._readResource(params, options); @@ -624,6 +643,7 @@ export class Client extends Protocol { } } this._listenState.clear(); + this._endStreams(); // Debounce timers are connection-scoped: a callback armed on a // connection that is now gone must not fire onto whatever connection // (if any) replaces it. @@ -2182,6 +2202,69 @@ export class Client extends Protocol { return { honoredFilter: honored, close, closed }; } + // `clientInternals.openStream`: a request that stays open with no timer, sent directly on the transport as listen() is. + private _openStream( + request: { method: string; params: Record }, + handlers: { onNotification(notification: JSONRPCNotification): void; onEnd(end: StreamEnd): void }, + options?: { headers?: Readonly> } + ): StreamHandle { + const transport = this.transport; + if (transport === undefined) { + throw new SdkError(SdkErrorCode.NotConnected, 'Not connected'); + } + // A string id from a Client-owned counter, like `listen:N`, so it cannot collide with Protocol's numeric ids. + const id = `stream:${this._nextStreamId++}`; + const requestAbort = new AbortController(); + // Unregisters the stream and aborts its request; false when it has already ended. + const detach = (): boolean => { + if (!this._streamState.delete(id)) return false; + requestAbort.abort(); + return true; + }; + const end = (outcome: StreamEnd): void => { + if (detach()) handlers.onEnd(outcome); + }; + // Registered before the send so a synchronously delivered frame or response finds it. + this._streamState.set(id, { onNotification: handlers.onNotification, end }); + + const callerMeta = request.params['_meta'] as Record | undefined; + const message: JSONRPCRequest = { + jsonrpc: '2.0', + id, + method: request.method, + params: { ...request.params, _meta: { ...this._outboundMetaEnvelope(), ...callerMeta } } + }; + const onSendFailure = (error: unknown): void => + end({ cause: 'remote', error: error instanceof Error ? error : new Error(String(error)) }); + try { + transport + .send(message, { + requestSignal: requestAbort.signal, + onRequestStreamEnd: () => end({ cause: 'remote' }), + headers: options?.headers + }) + .catch(onSendFailure); + } catch (error) { + onSendFailure(error); + } + + return { + id, + close: async () => { + if (!detach()) return; + await this.notification({ method: 'notifications/cancelled', params: { requestId: id } }).catch(() => {}); + handlers.onEnd({ cause: 'local' }); + } + }; + } + + // Ends every live `openStream` request as `remote`: the connection it was sent on is gone. + private _endStreams(): void { + for (const stream of this._streamState.values()) { + stream.end({ cause: 'remote' }); + } + } + /** * The subscription auto-opened by `ClientOptions.listChanged` on a modern * connection — the listen filter is the intersection of the configured @@ -2207,6 +2290,13 @@ export class Client extends Protocol { * being silently swallowed. */ protected override _onnotification(raw: JSONRPCNotification, extra?: MessageExtraInfo): void { + // A frame of a live `openStream` request goes to that stream only, never to the global handlers. + const streamId = (raw.params as { _meta?: Record } | undefined)?._meta?.[SUBSCRIPTION_ID_META_KEY]; + const stream = typeof streamId === 'string' ? this._streamState.get(streamId) : undefined; + if (stream !== undefined) { + stream.onNotification(raw); + return; + } // Response-cache invalidation: a `list_changed` notification means the // matching cached list result is stale. Evict (do NOT refetch) before // dispatch so a handler that reaches the cache observes the cleared @@ -2281,6 +2371,16 @@ export class Client extends Protocol { */ protected override _onresponse(response: JSONRPCResponse): void { const id = response.id; + // A response to a live `openStream` request ends it: a result gracefully, an error response remotely. + const stream = typeof id === 'string' ? this._streamState.get(id) : undefined; + if (stream !== undefined) { + stream.end( + isJSONRPCErrorResponse(response) + ? { cause: 'remote', error: ProtocolError.fromError(response.error.code, response.error.message, response.error.data) } + : { cause: 'graceful', result: response.result } + ); + return; + } const entry = typeof id === 'string' ? this._listenState.get(id) : undefined; if (entry !== undefined) { if (isJSONRPCErrorResponse(response)) { @@ -2328,6 +2428,7 @@ export class Client extends Protocol { } this._listenState.clear(); } + this._endStreams(); super._onclose(); } diff --git a/packages/client/test/client/openStream.test.ts b/packages/client/test/client/openStream.test.ts new file mode 100644 index 0000000000..2f0c6bbf78 --- /dev/null +++ b/packages/client/test/client/openStream.test.ts @@ -0,0 +1,260 @@ +/** + * `clientInternals.openStream`: the package-internal long-lived request (no timeout, `stream:N` ids, frames routed by + * the subscription id in `_meta`) that the Events client's push mode opens `events/stream` with. + */ +import type { JSONRPCMessage, JSONRPCNotification, JSONRPCRequest, TransportSendOptions } from '@modelcontextprotocol/core-internal'; +import { + InMemoryTransport, + PROTOCOL_VERSION_META_KEY, + ProtocolError, + SdkError, + SdkErrorCode, + SUBSCRIPTION_ID_META_KEY +} from '@modelcontextprotocol/core-internal'; +import { afterEach, describe, expect, it, vi } from 'vitest'; +import * as z from 'zod/v4'; + +import type { StreamEnd } from '../../src/client/client'; +import { Client, clientInternals } from '../../src/client/client'; + +const MODERN = '2026-07-28'; +const EVENT = 'notifications/events/event'; +const flush = () => new Promise(resolve => setTimeout(resolve, 0)); + +/** A scripted 2026-07-28 server: answers `server/discover`, records every other message and never answers it. */ +async function scriptedServer() { + const [clientTx, serverTx] = InMemoryTransport.createLinkedPair(); + const received: JSONRPCMessage[] = []; + serverTx.onmessage = message => { + const request = message as JSONRPCRequest; + if (request.method === 'server/discover') { + void serverTx.send({ + jsonrpc: '2.0', + id: request.id, + result: { + resultType: 'complete', + supportedVersions: [MODERN], + capabilities: {}, + _meta: { 'io.modelcontextprotocol/serverInfo': { name: 'scripted', version: '1.0.0' } } + } + }); + return; + } + received.push(message); + }; + await serverTx.start(); + const frame = (subscriptionId: string, params: Record = {}) => + serverTx.send({ jsonrpc: '2.0', method: EVENT, params: { ...params, _meta: { [SUBSCRIPTION_ID_META_KEY]: subscriptionId } } }); + return { clientTx, serverTx, received, frame }; +} + +async function scriptedStreams() { + const server = await scriptedServer(); + const client = new Client({ name: 'stream-test-client', version: '1.0.0' }, { versionNegotiation: { mode: { pin: MODERN } } }); + await client.connect(server.clientTx); + return { client, ...server }; +} + +function recorder() { + const notifications: JSONRPCNotification[] = []; + const ends: StreamEnd[] = []; + return { + notifications, + ends, + handlers: { + onNotification: (notification: JSONRPCNotification) => void notifications.push(notification), + onEnd: (end: StreamEnd) => void ends.push(end) + } + }; +} + +const streamRequest = (name: string) => ({ method: 'events/stream', params: { name, arguments: {}, cursor: null } }); + +function sendOptions(send: { mock: { calls: unknown[][] } }, id: string): TransportSendOptions { + const call = send.mock.calls.find(([message]) => (message as { id?: unknown }).id === id); + return call![1] as TransportSendOptions; +} + +describe('clientInternals.openStream', () => { + afterEach(() => { + vi.useRealTimers(); + }); + + it('routes notifications to the stream that owns the id', async () => { + const { client, received, frame } = await scriptedStreams(); + const global: unknown[] = []; + client.setNotificationHandler(EVENT, { params: z.looseObject({}) }, params => void global.push(params)); + const first = recorder(); + const second = recorder(); + + const a = clientInternals.openStream(client, streamRequest('a'), first.handlers); + const b = clientInternals.openStream( + client, + { method: 'events/stream', params: { name: 'b', _meta: { 'example.com/trace': 't1' } } }, + second.handlers + ); + + expect([a.id, b.id]).toEqual(['stream:0', 'stream:1']); + expect(received).toMatchObject([ + { id: 'stream:0', method: 'events/stream', params: { name: 'a', _meta: { [PROTOCOL_VERSION_META_KEY]: MODERN } } }, + { + id: 'stream:1', + method: 'events/stream', + params: { name: 'b', _meta: { [PROTOCOL_VERSION_META_KEY]: MODERN, 'example.com/trace': 't1' } } + } + ]); + + await frame('stream:1', { eventId: 'e1' }); + await frame('stream:7', { eventId: 'e2' }); + await flush(); + expect(first.notifications).toEqual([]); + expect(second.notifications).toMatchObject([ + { method: EVENT, params: { eventId: 'e1', _meta: { [SUBSCRIPTION_ID_META_KEY]: 'stream:1' } } } + ]); + // Only the frame no live stream owns reaches the global handler. + expect(global).toMatchObject([{ eventId: 'e2' }]); + await client.close(); + }); + + it('arms no timeout', async () => { + const { client, frame } = await scriptedStreams(); + vi.useFakeTimers(); + const stream = recorder(); + + clientInternals.openStream(client, streamRequest('a'), stream.handlers); + + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(120_000); + expect(stream.ends).toEqual([]); + await frame('stream:0', { eventId: 'e1' }); + expect(stream.notifications).toHaveLength(1); + vi.useRealTimers(); + await client.close(); + }); + + it('ends gracefully on a result and remotely on an error response', async () => { + const { client, serverTx } = await scriptedStreams(); + const graceful = recorder(); + const failed = recorder(); + clientInternals.openStream(client, streamRequest('a'), graceful.handlers); + clientInternals.openStream(client, streamRequest('b'), failed.handlers); + const result = { resultType: 'complete', _meta: { [SUBSCRIPTION_ID_META_KEY]: 'stream:0' } }; + + await serverTx.send({ jsonrpc: '2.0', id: 'stream:0', result }); + await serverTx.send({ jsonrpc: '2.0', id: 'stream:1', error: { code: -32_024, message: 'Forbidden' } }); + + expect(graceful.ends).toEqual([{ cause: 'graceful', result }]); + expect(failed.ends).toEqual([{ cause: 'remote', error: expect.any(ProtocolError) }]); + expect(failed.ends).toEqual([{ cause: 'remote', error: expect.objectContaining({ code: -32_024 }) }]); + await client.close(); + expect(graceful.ends).toHaveLength(1); + expect(failed.ends).toHaveLength(1); + }); + + it('cancels with notifications/cancelled on close()', async () => { + const { client, clientTx, received, frame } = await scriptedStreams(); + const send = vi.spyOn(clientTx, 'send'); + const ends: StreamEnd[] = []; + let sentBeforeEnd: JSONRPCMessage[] = []; + const handle = clientInternals.openStream(client, streamRequest('a'), { + onNotification: () => {}, + onEnd: end => { + ends.push(end); + sentBeforeEnd = [...received]; + } + }); + const signal = sendOptions(send, 'stream:0').requestSignal!; + received.length = 0; + + await handle.close(); + + expect(signal.aborted).toBe(true); + expect(received).toMatchObject([ + { method: 'notifications/cancelled', params: { requestId: 'stream:0', _meta: { [PROTOCOL_VERSION_META_KEY]: MODERN } } } + ]); + expect(ends).toEqual([{ cause: 'local' }]); + expect(sentBeforeEnd).toEqual(received); + await handle.close(); + await frame('stream:0', { eventId: 'late' }); + expect(received).toHaveLength(1); + expect(ends).toHaveLength(1); + await client.close(); + }); + + it('ends remotely when the transport closes', async () => { + const { client, clientTx } = await scriptedStreams(); + const stream = recorder(); + const handle = clientInternals.openStream(client, streamRequest('a'), stream.handlers); + + await clientTx.close(); + + expect(stream.ends).toStrictEqual([{ cause: 'remote' }]); + await handle.close(); + await client.close(); + expect(stream.ends).toHaveLength(1); + }); + + it('ends remotely when the request stream ends', async () => { + const { client, clientTx } = await scriptedStreams(); + const send = vi.spyOn(clientTx, 'send'); + const stream = recorder(); + clientInternals.openStream(client, streamRequest('a'), stream.handlers); + const options = sendOptions(send, 'stream:0'); + + options.onRequestStreamEnd!(); + + expect(stream.ends).toStrictEqual([{ cause: 'remote' }]); + expect(options.requestSignal!.aborted).toBe(true); + await client.close(); + }); + + it('ends remotely when the client reconnects', async () => { + const { client } = await scriptedStreams(); + const stream = recorder(); + clientInternals.openStream(client, streamRequest('a'), stream.handlers); + + await client.connect((await scriptedServer()).clientTx); + + expect(stream.ends).toStrictEqual([{ cause: 'remote' }]); + await client.close(); + }); + + it('ends remotely with the send error when the send fails', async () => { + const { client, clientTx } = await scriptedStreams(); + const failure = new Error('send failed'); + clientTx.send = () => Promise.reject(failure); + const stream = recorder(); + + clientInternals.openStream(client, streamRequest('a'), stream.handlers); + await flush(); + + expect(stream.ends).toEqual([{ cause: 'remote', error: failure }]); + await client.close(); + }); + + it('passes per-request headers to the transport', async () => { + const { client, clientTx } = await scriptedStreams(); + const send = vi.spyOn(clientTx, 'send'); + + clientInternals.openStream(client, streamRequest('a'), recorder().handlers, { headers: { 'Mcp-Param-Region': 'eu-west-1' } }); + + expect(sendOptions(send, 'stream:0').headers).toEqual({ 'Mcp-Param-Region': 'eu-west-1' }); + await client.close(); + }); + + it('throws NotConnected when not connected', async () => { + const client = new Client({ name: 'stream-test-client', version: '1.0.0' }); + const stream = recorder(); + + let error: unknown; + try { + clientInternals.openStream(client, streamRequest('a'), stream.handlers); + } catch (thrown) { + error = thrown; + } + + expect(error).toBeInstanceOf(SdkError); + expect((error as SdkError).code).toBe(SdkErrorCode.NotConnected); + expect(stream.ends).toEqual([]); + }); +}); From 49324edabfe1c57409b78e080cd3e4569053c8f9 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 14:50:36 +0200 Subject: [PATCH 15/37] fix(client): end request streams from a snapshot and always run base teardown --- packages/client/src/client/client.ts | 28 ++++++--- .../client/test/client/openStream.test.ts | 59 +++++++++++++++++++ 2 files changed, 78 insertions(+), 9 deletions(-) diff --git a/packages/client/src/client/client.ts b/packages/client/src/client/client.ts index 71f41ec58e..8845c81126 100644 --- a/packages/client/src/client/client.ts +++ b/packages/client/src/client/client.ts @@ -2260,8 +2260,14 @@ export class Client extends Protocol { // Ends every live `openStream` request as `remote`: the connection it was sent on is gone. private _endStreams(): void { - for (const stream of this._streamState.values()) { - stream.end({ cause: 'remote' }); + // A snapshot, so a stream that an `onEnd` reopens is not ended (and reopened again) by this same loop. + const live = [...this._streamState.values()]; + for (const stream of live) { + try { + stream.end({ cause: 'remote' }); + } catch (error) { + this.onerror?.(error instanceof Error ? error : new Error(String(error))); + } } } @@ -2421,15 +2427,19 @@ export class Client extends Protocol { * hanging. */ protected override _onclose(): void { - if (this._listenState.size > 0) { - const reason = new SdkError(SdkErrorCode.ConnectionClosed, 'Connection closed'); - for (const entry of this._listenState.values()) { - entry.settle({ cause: 'remote', error: reason }); + try { + if (this._listenState.size > 0) { + const reason = new SdkError(SdkErrorCode.ConnectionClosed, 'Connection closed'); + for (const entry of this._listenState.values()) { + entry.settle({ cause: 'remote', error: reason }); + } + this._listenState.clear(); } - this._listenState.clear(); + this._endStreams(); + } finally { + // Base teardown runs even if a callback above throws, so pending requests and timers are always settled. + super._onclose(); } - this._endStreams(); - super._onclose(); } /** diff --git a/packages/client/test/client/openStream.test.ts b/packages/client/test/client/openStream.test.ts index 2f0c6bbf78..121117facb 100644 --- a/packages/client/test/client/openStream.test.ts +++ b/packages/client/test/client/openStream.test.ts @@ -194,6 +194,65 @@ describe('clientInternals.openStream', () => { expect(stream.ends).toHaveLength(1); }); + it('does not loop when onEnd reopens synchronously on transport close', async () => { + const { client, clientTx } = await scriptedStreams(); + const ends: StreamEnd[] = []; + const refused: unknown[] = []; + let opens = 0; + const open = (): void => { + try { + clientInternals.openStream(client, streamRequest('a'), { + onNotification: () => {}, + onEnd: end => { + ends.push(end); + // Capped so a regression fails the assertions below instead of hanging the run. + if (ends.length < 20) open(); + } + }); + opens++; + } catch (error) { + refused.push(error); + } + }; + open(); + + await clientTx.close(); + await flush(); + + // The reopen inside the teardown is sent on the closing transport and ends when that send fails; the next is refused. + expect(opens).toBe(2); + expect(ends).toHaveLength(2); + expect(ends[0]).toStrictEqual({ cause: 'remote' }); + expect(ends[1]).toMatchObject({ cause: 'remote', error: expect.objectContaining({ code: SdkErrorCode.NotConnected }) }); + expect(refused).toEqual([expect.objectContaining({ code: SdkErrorCode.NotConnected })]); + await client.close(); + }); + + it('a throwing onEnd on transport close still ends the other streams and pending requests', async () => { + const { client, clientTx, received } = await scriptedStreams(); + const errors: Error[] = []; + client.onerror = error => void errors.push(error); + const failure = new Error('onEnd failed'); + clientInternals.openStream(client, streamRequest('a'), { + onNotification: () => {}, + onEnd: () => { + throw failure; + } + }); + const other = recorder(); + clientInternals.openStream(client, streamRequest('b'), other.handlers); + const pending = client.request({ method: 'tools/list', params: {} }); + await flush(); + expect(received.map(message => (message as JSONRPCRequest).method)).toEqual(['events/stream', 'events/stream', 'tools/list']); + + await clientTx.close(); + + expect(other.ends).toStrictEqual([{ cause: 'remote' }]); + await expect(pending).rejects.toMatchObject({ code: SdkErrorCode.ConnectionClosed }); + expect(errors).toEqual([failure]); + await client.close(); + }); + it('ends remotely when the request stream ends', async () => { const { client, clientTx } = await scriptedStreams(); const send = vi.spyOn(clientTx, 'send'); From cc6791c608b108ca1062ee890e34206bc0a5abdd Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 15:21:27 +0200 Subject: [PATCH 16/37] feat(client): EventsClientExtension with list, gating, mode selection and poll --- examples/tsconfig.json | 1 + packages/client/package.json | 13 + packages/client/src/ext/events/errors.ts | 35 +++ packages/client/src/ext/events/extension.ts | 172 +++++++++++ packages/client/src/ext/events/index.ts | 56 ++++ packages/client/src/ext/events/poll.ts | 116 +++++++ packages/client/src/ext/events/request.ts | 109 +++++++ .../client/src/ext/events/subscription.ts | 247 +++++++++++++++ .../client/test/client/barrelClean.test.ts | 18 ++ .../test/client/errorBrandConformance.test.ts | 9 +- .../client/test/ext/events/extension.test.ts | 166 ++++++++++ packages/client/test/ext/events/poll.test.ts | 283 ++++++++++++++++++ packages/client/test/ext/events/scripted.ts | 171 +++++++++++ packages/client/tsdown.config.ts | 12 +- .../test/packageTopologyPins.test.ts | 5 +- test/conformance/tsconfig.json | 1 + test/e2e/tsconfig.json | 1 + test/integration/tsconfig.json | 1 + 18 files changed, 1410 insertions(+), 6 deletions(-) create mode 100644 packages/client/src/ext/events/errors.ts create mode 100644 packages/client/src/ext/events/extension.ts create mode 100644 packages/client/src/ext/events/index.ts create mode 100644 packages/client/src/ext/events/poll.ts create mode 100644 packages/client/src/ext/events/request.ts create mode 100644 packages/client/src/ext/events/subscription.ts create mode 100644 packages/client/test/ext/events/extension.test.ts create mode 100644 packages/client/test/ext/events/poll.test.ts create mode 100644 packages/client/test/ext/events/scripted.ts diff --git a/examples/tsconfig.json b/examples/tsconfig.json index 62c4a6dcfb..16d71de6a9 100644 --- a/examples/tsconfig.json +++ b/examples/tsconfig.json @@ -16,6 +16,7 @@ "@modelcontextprotocol/client/stdio": ["./node_modules/@modelcontextprotocol/client/src/stdio.ts"], "@modelcontextprotocol/client/_shims": ["./node_modules/@modelcontextprotocol/client/src/shimsNode.ts"], "@modelcontextprotocol/client/ext/skills": ["./node_modules/@modelcontextprotocol/client/src/ext/skills/index.ts"], + "@modelcontextprotocol/client/ext/events": ["./node_modules/@modelcontextprotocol/client/src/ext/events/index.ts"], "@modelcontextprotocol/server/ext/skills": ["./node_modules/@modelcontextprotocol/server/src/ext/skills/index.ts"], "@modelcontextprotocol/server/ext/skills/node": ["./node_modules/@modelcontextprotocol/server/src/ext/skills/node.ts"], "@modelcontextprotocol/server/ext/events": ["./node_modules/@modelcontextprotocol/server/src/ext/events/index.ts"], diff --git a/packages/client/package.json b/packages/client/package.json index 636456879d..c6ebe72551 100644 --- a/packages/client/package.json +++ b/packages/client/package.json @@ -50,6 +50,16 @@ "default": "./dist/ext/skills/index.cjs" } }, + "./ext/events": { + "import": { + "types": "./dist/ext/events/index.d.mts", + "default": "./dist/ext/events/index.mjs" + }, + "require": { + "types": "./dist/ext/events/index.d.cts", + "default": "./dist/ext/events/index.cjs" + } + }, "./validators/ajv": { "import": { "types": "./dist/validators/ajv.d.mts", @@ -120,6 +130,9 @@ "ext/skills": [ "dist/ext/skills/index.d.mts" ], + "ext/events": [ + "dist/ext/events/index.d.mts" + ], "validators/ajv": [ "dist/validators/ajv.d.mts" ], diff --git a/packages/client/src/ext/events/errors.ts b/packages/client/src/ext/events/errors.ts new file mode 100644 index 0000000000..83a7f8b3ee --- /dev/null +++ b/packages/client/src/ext/events/errors.ts @@ -0,0 +1,35 @@ +import type { DeliveryMode } from '@modelcontextprotocol/core/ext/events'; +import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal/public'; + +/** + * No delivery mode the event type offers is usable by this client: webhook + * needs the `webhook` option, and a forced `delivery` narrows the client to + * that one mode. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export class NoCompatibleDeliveryModeError extends SdkError { + static { + Object.defineProperty(this, 'mcpBrand', { value: 'mcp.NoCompatibleDeliveryModeError' }); + } + + readonly eventName: string; + /** The modes the event type's descriptor lists. */ + readonly offered: readonly DeliveryMode[]; + /** The modes this client could use for the request. */ + readonly usable: readonly DeliveryMode[]; + + constructor(eventName: string, offered: readonly DeliveryMode[], usable: readonly DeliveryMode[]) { + super( + SdkErrorCode.CapabilityNotSupported, + `No delivery mode fits event type '${eventName}': the server offers ${offered.join(', ')}; this client can use ${usable.length > 0 ? usable.join(', ') : 'none'}`, + { eventName, offered, usable } + ); + this.name = 'NoCompatibleDeliveryModeError'; + this.eventName = eventName; + this.offered = offered; + this.usable = usable; + } +} diff --git a/packages/client/src/ext/events/extension.ts b/packages/client/src/ext/events/extension.ts new file mode 100644 index 0000000000..f4b7a92513 --- /dev/null +++ b/packages/client/src/ext/events/extension.ts @@ -0,0 +1,172 @@ +import type { DeliveryMode, ListEventsResult } from '@modelcontextprotocol/core/ext/events'; +import { EVENTS_EXTENSION_ID, EVENTS_LIST_METHOD, eventsCapabilityOf } from '@modelcontextprotocol/core/ext/events'; +import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; +import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal/public'; + +import type { Client } from '../../client/client'; +import { NoCompatibleDeliveryModeError } from './errors'; +import { PollDriver } from './poll'; +import { EventsConnection } from './request'; +import type { Driver, DriverContext, EventSubscription, SubscribeOptions } from './subscription'; +import { SubscriptionQueue } from './subscription'; + +const DEFAULT_POLL_INTERVAL_FLOOR_MS = 1000; + +// Most preferred first (SEP-3415 Appendix A). +const PREFERENCE: readonly DeliveryMode[] = ['webhook', 'push', 'poll']; + +/** + * Options for {@linkcode EventsClientExtension}. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export interface EventsClientOptions { + /** + * Webhook delivery: the callback URL the server POSTs events to, and + * optionally the source of each subscription's `whsec_` signing secret. + * With it set, a subscription prefers webhook where the event type offers it. + */ + webhook?: { url: string; secretProvider?: () => string }; + /** The shortest wait between two polls, whatever `nextPollMs` the server recommends. Default 1000. */ + pollIntervalFloorMs?: number; +} + +// The delivery mode for a subscription; throws NoCompatibleDeliveryModeError when none fits. +export function selectDeliveryMode( + eventName: string, + offered: readonly DeliveryMode[], + forced: DeliveryMode | undefined, + webhookConfigured: boolean +): DeliveryMode { + const usable = PREFERENCE.filter(mode => (mode !== 'webhook' || webhookConfigured) && (forced === undefined || mode === forced)); + const mode = usable.find(candidate => offered.includes(candidate)); + if (mode === undefined) throw new NoCompatibleDeliveryModeError(eventName, offered, usable); + return mode; +} + +/** + * Client side of the MCP Events extension (SEP-3415): lists a server's event + * types and subscribes to them. Each subscription picks a delivery mode, + * preferring webhook (when configured), then push, then poll, and runs it, + * deduplicating by `eventId` and tracking the cursor. Events is used only on + * protocol revision `2026-07-28` and later. + * + * @example + * ```ts + * const events = new EventsClientExtension(); + * events.attach(client); + * await client.connect(transport); + * const subscription = await events.subscribe({ name: 'incident.created', arguments: { severity: 'P1' } }); + * for await (const event of subscription) { + * console.log(event.data); + * } + * ``` + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export class EventsClientExtension { + /** The extension identifier the client declares. */ + readonly id = EVENTS_EXTENSION_ID; + readonly #options: EventsClientOptions; + readonly #floorMs: number; + #connection: EventsConnection | undefined; + + /** @throws {TypeError} when `pollIntervalFloorMs` is not a positive finite number. */ + constructor(options: EventsClientOptions = {}) { + const floorMs = options.pollIntervalFloorMs ?? DEFAULT_POLL_INTERVAL_FLOOR_MS; + if (!(Number.isFinite(floorMs) && floorMs > 0)) { + throw new TypeError(`pollIntervalFloorMs must be a positive finite number (got ${String(floorMs)})`); + } + this.#options = options; + this.#floorMs = floorMs; + } + + /** + * Declares the extension in `client`'s capabilities. Call it before + * `client.connect()`; one client per instance, and attaching to the same + * client again does nothing. + * + * @throws {Error} after `client` connected, or when already attached to another client. + */ + attach(client: Client): void { + if (this.#connection?.client === client) return; + if (this.#connection !== undefined) throw new Error('This EventsClientExtension is already attached to another client'); + client.registerCapabilities({ extensions: { [EVENTS_EXTENSION_ID]: {} } }); + this.#connection = new EventsConnection(client); + } + + /** The server advertised the extension and the connection is on protocol `2026-07-28` or later. `false` before connect. */ + get supported(): boolean { + const client = this.#connection?.client; + return ( + client !== undefined && client.getProtocolEra() === 'modern' && eventsCapabilityOf(client.getServerCapabilities()) !== undefined + ); + } + + /** + * Lists the server's event types, walking every page unless given a + * cursor. Event types whose `x-mcp-header` annotations are invalid are + * left out, with a warning. + * + * @throws {EventsError} when the server refuses the request. + * @throws {SdkError} `CapabilityNotSupported` when {@linkcode EventsClientExtension.supported} is `false`. + */ + async list(params: { cursor?: string } = {}): Promise { + return this.#require(EVENTS_LIST_METHOD).list(params.cursor); + } + + /** + * Subscribes to an event type, looking its descriptor up in the last + * `events/list` (fetched again when it is not there), and resolves once + * the first exchange with the server succeeds (for poll, the first + * `events/poll` response). A transient failure of that exchange (a + * transport error, or a JSON-RPC error that is not an Events kind) does + * not reject: delivery is retried in the background. Once subscribed, the + * server ending the subscription ends its loop (see {@linkcode EventSubscription}). + * + * @throws {EventsError} when the server refuses the subscription: `notFound` for an event type it does not list or + * no longer serves, `invalidParams` for arguments its `inputSchema` rejects, `forbidden`, or another kind. + * @throws {NoCompatibleDeliveryModeError} when no delivery mode the event type offers is usable here. + * @throws {SdkError} `CapabilityNotSupported` when {@linkcode EventsClientExtension.supported} is `false`, or + * another code when the first exchange fails in the SDK (for example a request timeout). + */ + async subscribe>(options: SubscribeOptions): Promise> { + const connection = this.#require('subscribe'); + let descriptor = connection.descriptor(options.name); + if (descriptor === undefined) { + await connection.list(); + descriptor = connection.descriptor(options.name); + } + if (descriptor === undefined) throw new EventsError('notFound', 'Event type not found', { kind: 'event' }); + const mode = selectDeliveryMode(options.name, descriptor.delivery, options.delivery, this.#options.webhook !== undefined); + const queue = new SubscriptionQueue(mode, options.cursor ?? null); + try { + await queue.run(this.#driver(mode, { subscription: { ...options }, queue, connection })); + } catch (error) { + await queue.cancel(); + throw error; + } + return queue; + } + + #driver(mode: DeliveryMode, context: DriverContext): Driver { + if (mode === 'poll') return new PollDriver(context, this.#floorMs); + throw new SdkError(SdkErrorCode.CapabilityNotSupported, `${mode} delivery is not available yet`); + } + + #require(method: string): EventsConnection { + const connection = this.#connection; + if (connection === undefined) throw new Error(`Call attach(client) before ${method}`); + if (!this.supported) { + throw new SdkError( + SdkErrorCode.CapabilityNotSupported, + `Server does not support the ${EVENTS_EXTENSION_ID} extension (required for ${method})` + ); + } + return connection; + } +} diff --git a/packages/client/src/ext/events/index.ts b/packages/client/src/ext/events/index.ts new file mode 100644 index 0000000000..c24cc4e048 --- /dev/null +++ b/packages/client/src/ext/events/index.ts @@ -0,0 +1,56 @@ +// @modelcontextprotocol/client/ext/events +// +// Client side of the MCP Events extension (SEP-3415). + +export { NoCompatibleDeliveryModeError } from './errors'; +export type { EventsClientOptions } from './extension'; +export { EventsClientExtension } from './extension'; +export type { EventSubscription, SubscribeOptions } from './subscription'; +export type { + DeliveryErrorCategory, + DeliveryMode, + DeliveryStatus, + EventDescriptor, + EventNotificationParams, + EventOccurrence, + EventsActiveNotificationParams, + EventsCapability, + EventsErrorNotificationParams, + EventsErrorObject, + EventsHeartbeatNotificationParams, + EventsTerminatedNotificationParams, + ListEventsRequestParams, + ListEventsResult, + PollEventsRequestParams, + PollEventsResult, + StreamEventsRequestParams, + StreamEventsResult, + SubscribeEventsRequestParams, + SubscribeEventsResult, + UnsubscribeEventsRequestParams, + UnsubscribeEventsResult, + WebhookControlBody, + WebhookDelivery, + WebhookGapBody, + WebhookTarget, + WebhookTerminatedBody, + WebhookVerificationBody +} from '@modelcontextprotocol/core/ext/events'; +export { + DELIVERY_ERROR_CATEGORIES, + DELIVERY_MODES, + EVENTS_ACTIVE_NOTIFICATION, + EVENTS_ERROR_NOTIFICATION, + EVENTS_EVENT_NOTIFICATION, + EVENTS_EXTENSION_ID, + EVENTS_HEARTBEAT_NOTIFICATION, + EVENTS_LIST_METHOD, + EVENTS_POLL_METHOD, + EVENTS_STREAM_METHOD, + EVENTS_SUBSCRIBE_METHOD, + EVENTS_TERMINATED_NOTIFICATION, + EVENTS_UNSUBSCRIBE_METHOD, + WEBHOOK_SUBSCRIPTION_ID_HEADER +} from '@modelcontextprotocol/core/ext/events'; +export type { EventsErrorKind } from '@modelcontextprotocol/core-internal/ext/events'; +export { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; diff --git a/packages/client/src/ext/events/poll.ts b/packages/client/src/ext/events/poll.ts new file mode 100644 index 0000000000..1129952c39 --- /dev/null +++ b/packages/client/src/ext/events/poll.ts @@ -0,0 +1,116 @@ +import type { PollEventsResult } from '@modelcontextprotocol/core/ext/events'; +import { EVENTS_POLL_METHOD, PollEventsResultSchema } from '@modelcontextprotocol/core/ext/events'; + +import type { Driver, DriverContext } from './subscription'; +import { recoveryFor, refusesSubscription, stillOffered } from './subscription'; + +const MAX_RETRY_DELAY_MS = 60_000; +// setTimeout fires at once beyond this, which would bypass the floor. +const MAX_TIMER_DELAY_MS = 2_147_483_647; + +// Poll delivery (spec §6.3): one `events/poll` loop, again at once on `hasMore`, otherwise after `nextPollMs` but never sooner than the floor. +export class PollDriver implements Driver { + readonly #context: DriverContext; + readonly #floorMs: number; + readonly #abort = new AbortController(); + #cursor: string | null; + // Sent until a poll succeeds. + #maxAgeMs: number | undefined; + #nextPollMs: number | undefined; + #wake: (() => void) | undefined; + #running: Promise = Promise.resolve(); + + constructor(context: DriverContext, floorMs: number) { + this.#context = context; + this.#floorMs = floorMs; + this.#cursor = context.subscription.cursor ?? null; + this.#maxAgeMs = context.subscription.maxAgeMs; + } + + start(): Promise { + let settle!: { resolve(): void; reject(error: unknown): void }; + const first = new Promise((resolve, reject) => (settle = { resolve, reject })); + this.#running = this.#run(settle.resolve).then(settle.resolve, (error: unknown) => { + settle.reject(error); + this.#context.queue.fail(error); + }); + return first; + } + + async stop(): Promise { + this.#abort.abort(); + this.#wake?.(); + await this.#running; + } + + // Calls `subscribed` after the first exchange unless it refuses the subscription, which rejects instead. + async #run(subscribed: () => void): Promise { + const { connection, queue, subscription } = this.#context; + let first = true; + let failures = 0; + while (!this.#abort.signal.aborted) { + let result: PollEventsResult; + try { + result = await this.#poll(); + } catch (error) { + if (this.#abort.signal.aborted) return; + if (first && refusesSubscription(error)) throw error; + first = false; + subscribed(); + const recovery = recoveryFor(error); + const gone = + recovery === 'fail' || + (recovery === 'relist' && (await stillOffered(connection, subscription.name, 'poll', this.#abort.signal)) === false); + if (gone) { + queue.fail(error); + return; + } + await this.#sleep(this.#retryDelay(failures++)); + continue; + } + failures = 0; + this.#deliver(result); + first = false; + subscribed(); + if (result.hasMore !== true) await this.#sleep(Math.max(result.nextPollMs ?? this.#floorMs, this.#floorMs)); + } + } + + #poll(): Promise { + const { name, arguments: args } = this.#context.subscription; + const mirror = { name, ...(args !== undefined && { arguments: args }) }; + const params = { ...mirror, cursor: this.#cursor, ...(this.#maxAgeMs !== undefined && { maxAgeMs: this.#maxAgeMs }) }; + return this.#context.connection.request(EVENTS_POLL_METHOD, params, PollEventsResultSchema, mirror, { signal: this.#abort.signal }); + } + + #deliver(result: PollEventsResult): void { + const { queue, subscription } = this.#context; + const cursor = result.cursor ?? null; + this.#maxAgeMs = undefined; + this.#nextPollMs = result.nextPollMs; + // A type without replay has no position to have skipped past (SEP: ignore `truncated`). + if (result.truncated === true && cursor !== null) subscription.onGap?.(cursor); + for (const event of result.events) queue.push(event); + this.#cursor = cursor; + queue.setCursor(cursor); + } + + // max(floor, nextPollMs), doubling per consecutive failure up to 60 s, never below that base. + #retryDelay(failures: number): number { + const base = Math.max(this.#floorMs, this.#nextPollMs ?? this.#floorMs); + return Math.max(base, Math.min(MAX_RETRY_DELAY_MS, base * 2 ** failures)); + } + + #sleep(ms: number): Promise { + return new Promise(resolve => { + if (this.#abort.signal.aborted) return resolve(); + const wake = (): void => { + clearTimeout(timer); + this.#wake = undefined; + resolve(); + }; + const timer = setTimeout(wake, Math.min(ms, MAX_TIMER_DELAY_MS)); + this.#wake = wake; + }); + } +} diff --git a/packages/client/src/ext/events/request.ts b/packages/client/src/ext/events/request.ts new file mode 100644 index 0000000000..0964e7558b --- /dev/null +++ b/packages/client/src/ext/events/request.ts @@ -0,0 +1,109 @@ +import type { EventDescriptor, ListEventsResult } from '@modelcontextprotocol/core/ext/events'; +import { EVENTS_LIST_METHOD, ListEventsResultSchema } from '@modelcontextprotocol/core/ext/events'; +import type { RequestOptions, StandardSchemaV1, XMcpHeaderDeclaration } from '@modelcontextprotocol/core-internal'; +import { + buildMcpParamHeaders, + HEADER_MISMATCH_ERROR_CODE, + ProtocolError, + scanXMcpHeaderDeclarations +} from '@modelcontextprotocol/core-internal'; +import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; + +import type { Client } from '../../client/client'; +import { clientInternals } from '../../client/client'; +import { detectProbeEnvironment, detectProbeTransportKind } from '../../client/versionNegotiation'; + +// The event type a request is about, whose annotated arguments become `Mcp-Param` headers. +export interface ParamMirror { + name: string; + arguments?: Record; +} + +// An events-coded `ProtocolError` as the `EventsError` it stands for; anything else unchanged. +function asEventsError(error: unknown): unknown { + if (!(error instanceof ProtocolError) || error instanceof EventsError) return error; + return EventsError.fromProtocolError(error) ?? error; +} + +// One client's `events/*` requests, and the descriptors (by name) of its last `events/list` that `Mcp-Param` headers are built from. +export class EventsConnection { + readonly client: Client; + readonly #descriptors = new Map(); + + constructor(client: Client) { + this.client = client; + } + + descriptor(name: string): EventDescriptor | undefined { + return this.#descriptors.get(name)?.descriptor; + } + + // Every page (no cursor) or that one page; drops event types with invalid `x-mcp-header` annotations and caches the rest. + async list(cursor?: string, options?: RequestOptions): Promise { + const fetchPage = (at: string | undefined): Promise => + this.request(EVENTS_LIST_METHOD, at === undefined ? {} : { cursor: at }, ListEventsResultSchema, undefined, options); + let result: ListEventsResult; + if (cursor === undefined) { + result = await clientInternals.walkPages(this.client, EVENTS_LIST_METHOD, fetchPage, page => page.events); + delete result.nextCursor; + this.#descriptors.clear(); + } else { + result = await fetchPage(cursor); + } + result.events = result.events.filter(descriptor => this.#cache(descriptor)); + return result; + } + + // `Mcp-Param-{Name}` headers for a request about `name`, from its cached descriptor; none while mirroring is off. + paramHeadersFor(name: string, args: Record | undefined): Record { + const declarations = this.#mirroring() ? this.#descriptors.get(name)?.declarations : undefined; + return declarations === undefined || declarations.length === 0 ? {} : buildMcpParamHeaders(declarations, args); + } + + // With `mirror`, carries its `Mcp-Param` headers and after a `-32020` re-lists once and retries. Events-coded errors become `EventsError`. + async request( + method: string, + params: Record, + schema: S, + mirror: ParamMirror | undefined, + options?: RequestOptions + ): Promise> { + const send = (): Promise> => { + const headers = mirror === undefined ? {} : this.paramHeadersFor(mirror.name, mirror.arguments); + const sendOptions = Object.keys(headers).length === 0 ? options : { ...options, headers: { ...options?.headers, ...headers } }; + return this.client.request({ method, params }, schema, sendOptions); + }; + try { + try { + return await send(); + } catch (error) { + const mismatch = error instanceof ProtocolError && error.code === HEADER_MISMATCH_ERROR_CODE; + if (mirror === undefined || !mismatch || !this.#mirroring()) throw error; + await this.list(undefined, options); + return await send(); + } + } catch (error) { + throw asEventsError(error); + } + } + + #mirroring(): boolean { + return this.client.getProtocolEra() === 'modern' && detectProbeEnvironment() !== 'browser'; + } + + // As `tools/list` does: exclusion applies except on stdio, which carries no headers. + #cache(descriptor: EventDescriptor): boolean { + const scan = scanXMcpHeaderDeclarations(descriptor.inputSchema); + const transport = this.client.transport; + if (!scan.valid && transport !== undefined && detectProbeTransportKind(transport) !== 'stdio') { + this.#descriptors.delete(descriptor.name); + // eslint-disable-next-line no-console -- the warning the SEP asks for, as tools/list gives it + console.warn( + `[mcp-sdk] excluding event type '${descriptor.name}' from events/list: invalid x-mcp-header declaration — ${scan.reason}` + ); + return false; + } + this.#descriptors.set(descriptor.name, { descriptor, declarations: scan.valid ? scan.declarations : [] }); + return true; + } +} diff --git a/packages/client/src/ext/events/subscription.ts b/packages/client/src/ext/events/subscription.ts new file mode 100644 index 0000000000..fc8a8f6998 --- /dev/null +++ b/packages/client/src/ext/events/subscription.ts @@ -0,0 +1,247 @@ +import type { DeliveryMode, DeliveryStatus, EventOccurrence } from '@modelcontextprotocol/core/ext/events'; +import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; +import { SdkError } from '@modelcontextprotocol/core-internal/public'; + +import type { EventsConnection } from './request'; + +/** + * What to subscribe to, and how. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export interface SubscribeOptions { + /** The event type, as `events/list` names it. */ + name: string; + /** Subscription arguments, valid against the event type's `inputSchema`. */ + arguments?: Record; + /** Forces one delivery mode instead of the default preference (webhook, then push, then poll). */ + delivery?: DeliveryMode; + /** Resumes from a persisted {@linkcode EventSubscription.cursor}; `null` or absent starts from now. */ + cursor?: string | null; + /** Replays no event older than this many milliseconds, however old `cursor` is. */ + maxAgeMs?: number; + /** Called with the fresh cursor when the server reports that events were skipped (`truncated`). */ + onGap?: (cursor: string | null) => void; +} + +/** + * One subscription's events. The `for await` loop is the same for every + * delivery mode. A refusal of the subscription itself comes from + * `subscribe()`; once subscribed, the loop ends with an `EventsError` when the + * server ends the subscription (`kind` says why: `forbidden`, + * `invalidParams`, or `notFound` and a schema change once the event type is no + * longer listed). Other failures are retried. `T` types `data` and is not + * checked against the event type's `payloadSchema`. Leaving the loop early + * cancels the subscription. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export interface EventSubscription> extends AsyncIterable { + /** + * The newest cursor that is safe to persist: it covers every event the + * loop has finished with (an event is finished when the loop asks for the + * next one). `null` for event types that do not support replay. + */ + readonly cursor: string | null; + readonly deliveryMode: DeliveryMode; + /** Webhook delivery health, as the server last reported it. */ + readonly deliveryStatus?: DeliveryStatus; + /** Stops delivery and ends the loop. */ + cancel(): Promise; +} + +// Runs one subscription's delivery mode into its queue. +export interface Driver { + // Settles after the mode's first exchange: rejects with a refusesSubscription() error, leaving nothing running; otherwise resolves and keeps delivering. + start(): Promise; + // Resolves once nothing more arrives. + stop(): Promise; +} + +// What a driver runs: the subscription, the queue its events go into, and the connection it requests through. +export interface DriverContext { + readonly subscription: SubscribeOptions; + readonly queue: SubscriptionQueue; + readonly connection: EventsConnection; +} + +// An error of the first exchange that subscribe() rejects with; any other (transport, non-Events JSON-RPC) is retried in the background. +export function refusesSubscription(error: unknown): boolean { + return error instanceof EventsError || error instanceof SdkError; +} + +// After a server error once subscribed (spec §6.3): re-list and go on if the event type is still offered, end the subscription, or retry later. +export function recoveryFor(error: unknown): 'relist' | 'fail' | 'retry' { + if (!(error instanceof EventsError)) return 'retry'; + const data = error.data as Record | undefined; + switch (error.kind) { + case 'notFound': { + return 'relist'; + } + case 'unsupported': { + return data?.['reason'] === 'schema_changed' ? 'relist' : 'retry'; + } + case 'forbidden': + case 'invalidParams': { + return 'fail'; + } + default: { + return 'retry'; + } + } +} + +// Re-lists, then whether `name` is still listed with `mode`; `undefined` when the list fails. +export async function stillOffered( + connection: EventsConnection, + name: string, + mode: DeliveryMode, + signal: AbortSignal +): Promise { + try { + await connection.list(undefined, { signal }); + } catch { + return undefined; + } + return connection.descriptor(name)?.delivery.includes(mode) === true; +} + +type Item = EventOccurrence & { data: T }; + +// In delivery order: an event, or a cursor that becomes current once the loop has moved past the events before it. +type Entry = { event: Item } | { cursor: string | null }; + +const DEDUPE_WINDOW = 1000; + +// The `EventSubscription` a driver delivers into. +export class SubscriptionQueue implements EventSubscription { + readonly deliveryMode: DeliveryMode; + #cursor: string | null; + #deliveryStatus: DeliveryStatus | undefined; + readonly #entries: Entry[] = []; + readonly #seen = new Set(); + readonly #waiters: Array<{ resolve(result: IteratorResult>): void; reject(error: unknown): void }> = []; + // The loop holds an event it has not finished with. + #holding = false; + // Set by fail() or end(); delivered after the queued events. + #finish: { error: unknown } | 'end' | undefined; + #closed = false; + #driver: Driver | undefined; + #cancelled: Promise | undefined; + + constructor(deliveryMode: DeliveryMode, cursor: string | null) { + this.deliveryMode = deliveryMode; + this.#cursor = cursor; + } + + get cursor(): string | null { + return this.#cursor; + } + + get deliveryStatus(): DeliveryStatus | undefined { + return this.#deliveryStatus; + } + + // Starts `driver`, which cancel() stops; settles as its first exchange does. + run(driver: Driver): Promise { + this.#driver = driver; + return driver.start(); + } + + // Queues an event unless its eventId is among the last 1 000 queued. + push(event: EventOccurrence): void { + if (this.#done() || this.#seen.has(event.eventId)) return; + this.#seen.add(event.eventId); + if (this.#seen.size > DEDUPE_WINDOW) this.#seen.delete(this.#seen.values().next().value!); + const item = event as Item; + const waiter = this.#waiters.shift(); + if (waiter === undefined) { + this.#entries.push({ event: item }); + return; + } + this.#holding = true; + waiter.resolve({ done: false, value: item }); + } + + setCursor(cursor: string | null): void { + if (this.#done()) return; + if (this.#entries.length === 0 && !this.#holding) this.#cursor = cursor; + else this.#entries.push({ cursor }); + } + + setDeliveryStatus(status: DeliveryStatus): void { + this.#deliveryStatus = status; + } + + // Ends the loop with `error` once the queued events are delivered. + fail(error: unknown): void { + if (this.#done()) return; + this.#finish = { error }; + this.#settleWaiters(); + } + + // Ends the loop once the queued events are delivered. + end(): void { + if (this.#done()) return; + this.#finish = 'end'; + this.#settleWaiters(); + } + + cancel(): Promise { + this.#cancelled ??= (async () => { + this.#closed = true; + this.#entries.length = 0; + for (const waiter of this.#waiters.splice(0)) waiter.resolve({ done: true, value: undefined }); + await this.#driver?.stop(); + })(); + return this.#cancelled; + } + + [Symbol.asyncIterator](): AsyncIterator> { + return { + next: () => this.#next(), + return: async () => { + await this.cancel(); + return { done: true, value: undefined }; + } + }; + } + + #done(): boolean { + return this.#closed || this.#finish !== undefined; + } + + #next(): Promise>> { + this.#holding = false; + let entry = this.#entries.shift(); + while (entry !== undefined && 'cursor' in entry) { + this.#cursor = entry.cursor; + entry = this.#entries.shift(); + } + if (entry !== undefined) { + this.#holding = true; + return Promise.resolve({ done: false, value: entry.event }); + } + if (this.#closed) return Promise.resolve({ done: true, value: undefined }); + if (this.#finish !== undefined) return this.#deliverFinish(); + return new Promise((resolve, reject) => this.#waiters.push({ resolve, reject })); + } + + // Waiters exist only while nothing is queued, so the finish reaches them at once. + #settleWaiters(): void { + const waiter = this.#waiters.shift(); + if (waiter === undefined) return; + this.#deliverFinish().then(waiter.resolve, waiter.reject); + for (const rest of this.#waiters.splice(0)) rest.resolve({ done: true, value: undefined }); + } + + #deliverFinish(): Promise>> { + const finish = this.#finish; + this.#closed = true; + return finish === 'end' || finish === undefined ? Promise.resolve({ done: true, value: undefined }) : Promise.reject(finish.error); + } +} diff --git a/packages/client/test/client/barrelClean.test.ts b/packages/client/test/client/barrelClean.test.ts index 94412bba87..4315db1e27 100644 --- a/packages/client/test/client/barrelClean.test.ts +++ b/packages/client/test/client/barrelClean.test.ts @@ -130,3 +130,21 @@ describe('@modelcontextprotocol/client root leaves the skills extension out', () expect(graph.some(content => SKILLS_CODE.test(content))).toBe(true); }); }); + +describe('@modelcontextprotocol/client root leaves the events extension out', () => { + beforeAll(async () => { + await ensureBuilt(pkgDir); + }, 180_000); + + test('the root entry does not export the events extension', () => { + expect(rootExportBlockOf(readFileSync(join(distDir, 'index.mjs'), 'utf8'))).not.toMatch( + /\b(?:EventsClientExtension|NoCompatibleDeliveryModeError)\b/ + ); + }); + + test('ext/events exports the events extension (guards the pattern)', () => { + const exports = rootExportBlockOf(readFileSync(join(distDir, 'ext/events/index.mjs'), 'utf8')); + expect(exports).toMatch(/\bEventsClientExtension\b/); + expect(exports).toMatch(/\bNoCompatibleDeliveryModeError\b/); + }); +}); diff --git a/packages/client/test/client/errorBrandConformance.test.ts b/packages/client/test/client/errorBrandConformance.test.ts index 2e709a749a..d8d0bd16a7 100644 --- a/packages/client/test/client/errorBrandConformance.test.ts +++ b/packages/client/test/client/errorBrandConformance.test.ts @@ -1,10 +1,11 @@ import { describe, expect, it, vi } from 'vitest'; +import * as events from '../../src/ext/events/index'; import * as skills from '../../src/ext/skills/index'; import * as barrel from '../../src/index'; -/** Every public entry that can export an error class: the root and the skills extension's subpath. */ -const SURFACES: ReadonlyArray> = [barrel, skills]; +/** Every public entry that can export an error class: the root and the extensions' subpaths. */ +const SURFACES: ReadonlyArray> = [barrel, skills, events]; /** * Enforces the cross-bundle branding participation criterion from @@ -41,6 +42,8 @@ describe('error brand conformance (client export surface)', () => { expect(classes.map(([n]) => n)).toContain('ProtocolError'); expect(classes.map(([n]) => n)).toContain('OAuthClientFlowError'); expect(classes.map(([n]) => n)).toContain('SkillVerificationError'); + expect(classes.map(([n]) => n)).toContain('EventsError'); + expect(classes.map(([n]) => n)).toContain('NoCompatibleDeliveryModeError'); }); it('every exported error class is branded (or explicitly allowlisted)', () => { @@ -84,9 +87,11 @@ describe('error brand conformance (client export surface)', () => { ); expect(brands).toEqual({ AuthorizationServerMismatchError: 'mcp.AuthorizationServerMismatchError', + EventsError: 'mcp.EventsError', InsecureTokenEndpointError: 'mcp.InsecureTokenEndpointError', InsufficientScopeError: 'mcp.InsufficientScopeError', IssuerMismatchError: 'mcp.IssuerMismatchError', + NoCompatibleDeliveryModeError: 'mcp.NoCompatibleDeliveryModeError', OAuthClientFlowError: 'mcp.OAuthClientFlowError', RegistrationRejectedError: 'mcp.RegistrationRejectedError', SkillVerificationError: 'mcp.SkillVerificationError', diff --git a/packages/client/test/ext/events/extension.test.ts b/packages/client/test/ext/events/extension.test.ts new file mode 100644 index 0000000000..fc3a9f1ff6 --- /dev/null +++ b/packages/client/test/ext/events/extension.test.ts @@ -0,0 +1,166 @@ +import { EVENTS_EXTENSION_ID } from '@modelcontextprotocol/core/ext/events'; +import { ProtocolError, SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal'; +import { afterEach, describe, expect, it, vi } from 'vitest'; + +import { Client } from '../../../src/client/client'; +import { selectDeliveryMode } from '../../../src/ext/events/extension'; +import type { EventSubscription } from '../../../src/ext/events/index'; +import { EventsClientExtension, EventsError, NoCompatibleDeliveryModeError } from '../../../src/ext/events/index'; +import type { Handler } from './scripted'; +import { callsTo, connectEvents, descriptor, LEGACY, listing, occurrence, quietPoll, RpcError, script, scriptedClient } from './scripted'; + +const UNSUPPORTED = 'Server does not support the io.modelcontextprotocol/events extension (required for events/list)'; + +const subscriptions: EventSubscription[] = []; +afterEach(async () => { + await Promise.all(subscriptions.splice(0).map(subscription => subscription.cancel())); + vi.restoreAllMocks(); +}); + +async function track(subscription: Promise>): Promise> { + const resolved = await subscription; + subscriptions.push(resolved as EventSubscription); + return resolved; +} + +describe('EventsClientExtension gating', () => { + it('refuses calls when the server lacks the extension or the connection is legacy', async () => { + for (const setup of [{ capabilities: {} }, { revision: LEGACY }] as const) { + const { events, calls } = await connectEvents({ 'events/list': listing(descriptor('tick')) }, setup); + expect(events.supported).toBe(false); + await expect(events.list()).rejects.toMatchObject({ code: SdkErrorCode.CapabilityNotSupported, message: UNSUPPORTED }); + await expect(events.subscribe({ name: 'tick' })).rejects.toMatchObject({ code: SdkErrorCode.CapabilityNotSupported }); + expect(calls.filter(call => call.method.startsWith('events/'))).toEqual([]); + } + const { events } = await connectEvents({}); + expect(events.supported).toBe(true); + }); + + it('declares itself in the per-request client capabilities', async () => { + const { events, calls } = await connectEvents({ 'events/list': listing() }); + await events.list(); + const meta = callsTo(calls, 'events/list')[0]!.params['_meta'] as Record }>; + expect(meta['io.modelcontextprotocol/clientCapabilities']!.extensions[EVENTS_EXTENSION_ID]).toEqual({}); + }); + + it('throws when attached after connect or to a second client', async () => { + const { client } = await scriptedClient({}); + expect(() => new EventsClientExtension().attach(client)).toThrow('Cannot register capabilities after connecting to transport'); + const events = new EventsClientExtension(); + const first = new Client({ name: 'a', version: '1.0.0' }); + events.attach(first); + expect(() => events.attach(first)).not.toThrow(); + expect(() => events.attach(new Client({ name: 'b', version: '1.0.0' }))).toThrow(Error); + }); + + it('rejects a pollIntervalFloorMs that is not a positive number', () => { + for (const pollIntervalFloorMs of [0, -1, Number.NaN, Number.POSITIVE_INFINITY]) { + expect(() => new EventsClientExtension({ pollIntervalFloorMs })).toThrow(TypeError); + } + }); +}); + +describe('EventsClientExtension.list', () => { + it('walks list pages and drops invalid x-mcp-header event types', async () => { + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}); + const bad = descriptor('bad', { + inputSchema: { type: 'object', properties: { region: { type: 'number', 'x-mcp-header': 'Region' } } } + }); + const pages: Handler = params => + params['cursor'] === 'p2' ? { events: [bad, descriptor('tock')] } : { events: [descriptor('tick')], nextCursor: 'p2' }; + const { events, calls } = await connectEvents({ 'events/list': pages }); + + const all = await events.list(); + expect(all.events.map(event => event.name)).toEqual(['tick', 'tock']); + expect(all).not.toHaveProperty('nextCursor'); + expect(callsTo(calls, 'events/list').map(call => call.params['cursor'])).toEqual([undefined, 'p2']); + expect(warn).toHaveBeenCalledWith(expect.stringContaining("'bad'")); + + // With a cursor: that one page, its nextCursor kept, the invalid type dropped there too. + expect(await events.list({ cursor: 'p1' })).toEqual({ events: [descriptor('tick')], nextCursor: 'p2' }); + expect(await events.list({ cursor: 'p2' })).toEqual({ events: [descriptor('tock')] }); + + // The dropped type is not subscribable: it is not in the cache, and the refetch excludes it again. + await expect(events.subscribe({ name: 'bad' })).rejects.toMatchObject({ kind: 'notFound' }); + }); +}); + +describe('EventsClientExtension requests', () => { + it('mirrors annotated arguments into Mcp-Param headers and retries once on -32020', async () => { + const annotated = descriptor('tick', { + inputSchema: { type: 'object', properties: { region: { type: 'string', 'x-mcp-header': 'Region' } } } + }); + // The first listing predates the annotation, so the first poll goes out without the header. + const lists = [descriptor('tick'), annotated]; + const { events, calls } = await connectEvents({ + 'events/list': () => ({ events: [lists.length > 1 ? lists.shift()! : lists[0]!] }), + 'events/poll': (_params, call) => { + if (call.headers['Mcp-Param-Region'] !== 'us-west1') throw new RpcError(-32_020, 'Mcp-Param-Region header mismatch'); + return { events: [occurrence('e1')], cursor: 'c1', nextPollMs: 60_000 }; + } + }); + const sub = await track(events.subscribe({ name: 'tick', arguments: { region: 'us-west1' }, delivery: 'poll' })); + const first = await sub[Symbol.asyncIterator]().next(); + + expect(first.value).toMatchObject({ eventId: 'e1' }); + expect(callsTo(calls, 'events/list')).toHaveLength(2); + expect(callsTo(calls, 'events/poll').map(call => call.headers['Mcp-Param-Region'])).toEqual([undefined, 'us-west1']); + expect(calls.map(call => call.method)).toEqual(['events/list', 'events/poll', 'events/list', 'events/poll']); + }); + + it('turns events error codes into EventsError', async () => { + const { events } = await connectEvents({ + 'events/list': listing(descriptor('tick')), + 'events/poll': script(new RpcError(-32_024, 'Forbidden', { reason: 'Access revoked' })) + }); + const error = await events.subscribe({ name: 'tick', delivery: 'poll' }).catch((error_: unknown) => error_); + expect(error).toBeInstanceOf(EventsError); + expect(error).toMatchObject({ kind: 'forbidden', code: -32_024, data: { reason: 'Access revoked' } }); + + const failing = await connectEvents({ 'events/list': script(new RpcError(-32_026, 'Unsupported'), new RpcError(-32_603, 'boom')) }); + const unsupported = await failing.events.list().catch((error_: unknown) => error_); + expect(unsupported).toBeInstanceOf(EventsError); + expect(unsupported).toMatchObject({ kind: 'unsupported' }); + const internal = await failing.events.list().catch((error_: unknown) => error_); + expect(internal).toBeInstanceOf(ProtocolError); + expect(internal).not.toBeInstanceOf(EventsError); + expect(internal).toMatchObject({ code: -32_603, message: 'boom' }); + }); +}); + +describe('EventsClientExtension.subscribe', () => { + it('selects webhook, then push, then poll, and explains when nothing fits', async () => { + const { events } = await connectEvents({ + 'events/list': listing(descriptor('tick', { delivery: ['webhook', 'poll'] })), + 'events/poll': quietPoll + }); + const sub = await track(events.subscribe({ name: 'tick' })); + expect(sub.deliveryMode).toBe('poll'); + + const error = await events.subscribe({ name: 'tick', delivery: 'push' }).catch((error_: unknown) => error_); + expect(error).toBeInstanceOf(NoCompatibleDeliveryModeError); + expect(error).toBeInstanceOf(SdkError); + expect(error).toMatchObject({ eventName: 'tick', offered: ['webhook', 'poll'], usable: ['push'] }); + + expect(selectDeliveryMode('tick', ['poll', 'push', 'webhook'], undefined, true)).toBe('webhook'); + expect(selectDeliveryMode('tick', ['poll', 'push', 'webhook'], undefined, false)).toBe('push'); + expect(selectDeliveryMode('tick', ['poll', 'push'], undefined, true)).toBe('push'); + expect(selectDeliveryMode('tick', ['poll', 'push', 'webhook'], 'poll', true)).toBe('poll'); + expect(() => selectDeliveryMode('tick', ['webhook'], undefined, false)).toThrow( + expect.objectContaining({ offered: ['webhook'], usable: ['push', 'poll'] }) + ); + expect(() => selectDeliveryMode('tick', ['webhook', 'poll'], 'webhook', false)).toThrow(expect.objectContaining({ usable: [] })); + }); + + it('refetches events/list for an uncached name and refuses one the server does not list', async () => { + const { events, calls } = await connectEvents({ 'events/list': listing(descriptor('tick')), 'events/poll': quietPoll }); + await track(events.subscribe({ name: 'tick' })); + await track(events.subscribe({ name: 'tick' })); + expect(callsTo(calls, 'events/list')).toHaveLength(1); + + const error = await events.subscribe({ name: 'missing' }).catch((error_: unknown) => error_); + expect(error).toBeInstanceOf(EventsError); + expect(error).toMatchObject({ kind: 'notFound', message: 'Event type not found', data: { kind: 'event' } }); + expect(callsTo(calls, 'events/list')).toHaveLength(2); + }); +}); diff --git a/packages/client/test/ext/events/poll.test.ts b/packages/client/test/ext/events/poll.test.ts new file mode 100644 index 0000000000..606aa1eaf0 --- /dev/null +++ b/packages/client/test/ext/events/poll.test.ts @@ -0,0 +1,283 @@ +import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; + +import type { EventSubscription, SubscribeOptions } from '../../../src/ext/events/index'; +import { EventsError } from '../../../src/ext/events/index'; +import type { Call, Handler, Notification } from './scripted'; +import { callsTo, connectEvents, descriptor, listing, occurrence, RpcError, script } from './scripted'; + +const subscriptions: EventSubscription[] = []; + +beforeEach(() => { + vi.useFakeTimers(); +}); + +afterEach(async () => { + await Promise.all(subscriptions.splice(0).map(subscription => subscription.cancel())); + vi.useRealTimers(); +}); + +/** Lets every in-flight request and its response settle without moving the clock. */ +const settle = () => vi.advanceTimersByTimeAsync(0); + +/** The eventId of the loop's next event, `undefined` when the loop is done. */ +async function nextEventId(iterator: AsyncIterator<{ eventId: string }>): Promise { + const result = await iterator.next(); + return result.done ? undefined : result.value.eventId; +} + +async function pollWith( + poll: Handler, + list: Handler = listing(descriptor('tick')) +): Promise<{ + calls: Call[]; + notifications: Notification[]; + polls: () => Call[]; + subscribe: (options?: Partial) => Promise; +}> { + const { events, calls, notifications } = await connectEvents({ 'events/list': list, 'events/poll': poll }); + return { + calls, + notifications, + polls: () => callsTo(calls, 'events/poll'), + subscribe: async (options = {}) => { + const subscription = await events.subscribe({ name: 'tick', delivery: 'poll', ...options }); + subscriptions.push(subscription); + await settle(); + return subscription; + } + }; +} + +describe('poll delivery', () => { + it('drains hasMore at once and waits max(nextPollMs, floor) otherwise', async () => { + const { polls, subscribe } = await pollWith( + script( + { events: [occurrence('e1')], cursor: 'c1', hasMore: true, nextPollMs: 30_000 }, + { events: [occurrence('e2')], cursor: 'c2', nextPollMs: 0 }, + { events: [], cursor: 'c3', nextPollMs: 5000 }, + { events: [], cursor: 'c4', nextPollMs: 5000 } + ) + ); + const sub = await subscribe({ arguments: { severity: 'P1' }, maxAgeMs: 300_000 }); + + expect(polls().map(call => call.params)).toEqual([ + expect.objectContaining({ name: 'tick', arguments: { severity: 'P1' }, cursor: null, maxAgeMs: 300_000 }), + expect.not.objectContaining({ maxAgeMs: expect.anything() }) + ]); + expect(polls()[1]!.params).toMatchObject({ name: 'tick', arguments: { severity: 'P1' }, cursor: 'c1' }); + + await vi.advanceTimersByTimeAsync(999); + expect(polls()).toHaveLength(2); + await vi.advanceTimersByTimeAsync(1); + expect(polls()).toHaveLength(3); + expect(polls()[2]!.params['cursor']).toBe('c2'); + + await vi.advanceTimersByTimeAsync(4999); + expect(polls()).toHaveLength(3); + await vi.advanceTimersByTimeAsync(1); + expect(polls()).toHaveLength(4); + + const iterator = sub[Symbol.asyncIterator](); + expect([await nextEventId(iterator), await nextEventId(iterator)]).toEqual(['e1', 'e2']); + }); + + it('reports truncated through onGap and persists the fresh cursor', async () => { + const onGap = vi.fn(); + const { polls, subscribe } = await pollWith(script({ events: [], cursor: 'c5', truncated: true, nextPollMs: 60_000 })); + const sub = await subscribe({ cursor: 'c0', onGap }); + + expect(polls()[0]!.params['cursor']).toBe('c0'); + expect(onGap).toHaveBeenCalledExactlyOnceWith('c5'); + expect(sub.cursor).toBe('c5'); + }); + + it('moves the cursor past events only once the loop has moved past them', async () => { + const { subscribe } = await pollWith(script({ events: [occurrence('e1'), occurrence('e2')], cursor: 'c2', nextPollMs: 60_000 })); + const sub = await subscribe({ cursor: 'c0' }); + const iterator = sub[Symbol.asyncIterator](); + + expect(sub.cursor).toBe('c0'); + await iterator.next(); + expect(sub.cursor).toBe('c0'); + await iterator.next(); + expect(sub.cursor).toBe('c0'); + void iterator.next(); + expect(sub.cursor).toBe('c2'); + }); + + it('delivers each eventId once', async () => { + const { subscribe } = await pollWith( + script( + { events: [occurrence('e1')], cursor: 'c1', hasMore: true }, + { events: [occurrence('e1'), occurrence('e2')], cursor: 'c2', nextPollMs: 60_000 } + ) + ); + const sub = await subscribe(); + const iterator = sub[Symbol.asyncIterator](); + expect(await nextEventId(iterator)).toBe('e1'); + expect(await nextEventId(iterator)).toBe('e2'); + + let settled = false; + void iterator.next().then(() => (settled = true)); + await settle(); + expect(settled).toBe(false); + }); + + it('keeps cursor null for a non-replayable type', async () => { + const { polls, subscribe } = await pollWith( + script({ events: [occurrence('e1')], cursor: null, nextPollMs: 0 }, { events: [], nextPollMs: 60_000 }) + ); + const sub = await subscribe(); + await sub[Symbol.asyncIterator]().next(); + await vi.advanceTimersByTimeAsync(1000); + + expect(polls()).toHaveLength(2); + expect(polls()[1]!.params).toHaveProperty('cursor', null); + expect(sub.cursor).toBeNull(); + }); + + it('resubscribes after schema_changed and fails on forbidden', async () => { + const { calls, polls, subscribe } = await pollWith( + script( + { events: [], cursor: 'c1', nextPollMs: 0 }, + new RpcError(-32_026, 'Unsupported', { feature: 'payloadSchema', reason: 'schema_changed' }), + { events: [occurrence('e1')], cursor: 'c2', nextPollMs: 0 }, + new RpcError(-32_024, 'Forbidden', { reason: 'Access revoked' }) + ) + ); + const sub = await subscribe(); + await vi.advanceTimersByTimeAsync(1000); + expect(polls()).toHaveLength(2); + expect(callsTo(calls, 'events/list')).toHaveLength(2); + + await vi.advanceTimersByTimeAsync(1000); + expect(polls()).toHaveLength(3); + expect(polls()[2]!.params['cursor']).toBe('c1'); + + await vi.advanceTimersByTimeAsync(1000); + expect(polls()).toHaveLength(4); + const iterator = sub[Symbol.asyncIterator](); + expect(await nextEventId(iterator)).toBe('e1'); + const error = await iterator.next().catch((error_: unknown) => error_); + expect(error).toBeInstanceOf(EventsError); + expect(error).toMatchObject({ kind: 'forbidden' }); + expect(await iterator.next()).toEqual({ done: true, value: undefined }); + + await vi.advanceTimersByTimeAsync(120_000); + expect(polls()).toHaveLength(4); + }); + + it('ends the loop with notFound once the event type is no longer listed', async () => { + const lists = [[descriptor('tick')], []]; + const { calls, subscribe } = await pollWith( + script({ events: [], cursor: 'c1', nextPollMs: 0 }, new RpcError(-32_023, 'Not found', { kind: 'event' })), + () => ({ events: lists.shift() ?? [] }) + ); + const sub = await subscribe(); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + await vi.advanceTimersByTimeAsync(1000); + + const error = await pending; + expect(error).toBeInstanceOf(EventsError); + expect(error).toMatchObject({ kind: 'notFound', data: { kind: 'event' } }); + expect(callsTo(calls, 'events/list')).toHaveLength(2); + }); + + it('retries other errors after max(floor, nextPollMs), doubling to 60 s', async () => { + const failures = Array.from({ length: 9 }, () => new RpcError(-32_603, 'Internal error')); + const { polls, subscribe } = await pollWith( + script({ events: [], cursor: 'c1', nextPollMs: 2000 }, ...failures, { events: [occurrence('e1')], cursor: 'c2', nextPollMs: 0 }) + ); + const sub = await subscribe(); + + for (const delay of [2000, 2000, 4000, 8000, 16_000, 32_000, 60_000, 60_000, 60_000, 60_000]) { + const before = polls().length; + await vi.advanceTimersByTimeAsync(delay - 1); + expect(polls()).toHaveLength(before); + await vi.advanceTimersByTimeAsync(1); + expect(polls()).toHaveLength(before + 1); + } + expect(polls()[0]!.params['cursor']).toBeNull(); + expect( + polls() + .slice(1) + .every(call => call.params['cursor'] === 'c1') + ).toBe(true); + expect(await nextEventId(sub[Symbol.asyncIterator]())).toBe('e1'); + }); + + it('rejects subscribe() when the first poll is refused, leaving nothing running', async () => { + const refusals = [ + new RpcError(-32_023, 'Not found', { kind: 'event' }), + new RpcError(-32_602, 'Invalid arguments'), + new RpcError(-32_024, 'Forbidden'), + new RpcError(-32_026, 'Unsupported', { feature: 'payloadSchema', reason: 'schema_changed' }) + ]; + for (const refusal of refusals) { + const { calls, polls, subscribe } = await pollWith(script(refusal)); + const error = await subscribe().catch((error_: unknown) => error_); + expect(error).toBeInstanceOf(EventsError); + expect(error).toMatchObject({ code: refusal.code }); + + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(120_000); + expect(polls()).toHaveLength(1); + expect(callsTo(calls, 'events/list')).toHaveLength(1); + } + }); + + it('rejects subscribe() when the first poll fails in the SDK', async () => { + const { polls, subscribe } = await pollWith(script({ events: 'not an array' })); + const error = await subscribe().catch((error_: unknown) => error_); + expect(error).toBeInstanceOf(SdkError); + expect(error).toMatchObject({ code: SdkErrorCode.InvalidResult }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(120_000); + expect(polls()).toHaveLength(1); + }); + + it('resolves subscribe() after a transient first-poll failure and delivers after the retry', async () => { + const { polls, subscribe } = await pollWith( + script(new RpcError(-32_603, 'Internal error'), { events: [occurrence('e1')], cursor: 'c1', nextPollMs: 60_000 }) + ); + const sub = await subscribe(); + expect(polls()).toHaveLength(1); + + await vi.advanceTimersByTimeAsync(1000); + expect(polls()).toHaveLength(2); + expect(await nextEventId(sub[Symbol.asyncIterator]())).toBe('e1'); + }); + + it('stops polling on cancel()', async () => { + const { polls, subscribe } = await pollWith(script({ events: [], cursor: 'c1', nextPollMs: 0 })); + const sub = await subscribe(); + expect(polls()).toHaveLength(1); + const pending = sub[Symbol.asyncIterator]().next(); + + await sub.cancel(); + await vi.advanceTimersByTimeAsync(10_000); + expect(polls()).toHaveLength(1); + expect(await pending).toEqual({ done: true, value: undefined }); + }); + + it('stops polling when the loop breaks, and aborts a poll in flight', async () => { + const { notifications, polls, subscribe } = await pollWith(script({ events: [occurrence('e1')], cursor: 'c1', nextPollMs: 0 })); + const sub = await subscribe(); + await vi.advanceTimersByTimeAsync(1000); + expect(polls()).toHaveLength(2); + + for await (const event of sub) { + expect(event.eventId).toBe('e1'); + break; + } + await vi.advanceTimersByTimeAsync(10_000); + expect(polls()).toHaveLength(2); + expect(notifications).toContainEqual({ + method: 'notifications/cancelled', + params: expect.objectContaining({ requestId: polls()[1]!.id }) + }); + }); +}); diff --git a/packages/client/test/ext/events/scripted.ts b/packages/client/test/ext/events/scripted.ts new file mode 100644 index 0000000000..de28b6aacd --- /dev/null +++ b/packages/client/test/ext/events/scripted.ts @@ -0,0 +1,171 @@ +import type { EventDescriptor, EventOccurrence } from '@modelcontextprotocol/core/ext/events'; +import { EVENTS_EXTENSION_ID } from '@modelcontextprotocol/core/ext/events'; +import type { JSONRPCRequest, RequestId, ServerCapabilities, Transport } from '@modelcontextprotocol/core-internal'; +import { InMemoryTransport } from '@modelcontextprotocol/core-internal'; + +import type { ClientOptions } from '../../../src/client/client'; +import { Client } from '../../../src/client/client'; +import type { EventsClientOptions } from '../../../src/ext/events/index'; +import { EventsClientExtension } from '../../../src/ext/events/index'; + +export const MODERN = '2026-07-28'; +export const LEGACY = '2025-11-25'; + +export const EVENTS_CAPABILITIES: ServerCapabilities = { extensions: { [EVENTS_EXTENSION_ID]: {} } }; + +/** One request the scripted server received, with the per-request headers the client handed its transport. */ +export interface Call { + id: RequestId; + method: string; + params: Record; + headers: Record; +} + +/** A notification the scripted server received. */ +export interface Notification { + method: string; + params: Record; +} + +export type Handler = (params: Record, call: Call) => Record | Promise>; + +/** A JSON-RPC error for the scripted server to answer with. */ +export class RpcError extends Error { + constructor( + readonly code: number, + message: string, + readonly data?: Record + ) { + super(message); + } +} + +export interface ScriptedOptions { + /** What `server/discover` (or `initialize`) declares. Default: the events extension. */ + capabilities?: ServerCapabilities; + revision?: typeof MODERN | typeof LEGACY; + clientOptions?: ClientOptions; + /** Runs on the client before it connects. */ + beforeConnect?: (client: Client) => void; +} + +/** + * A client connected over an in-memory pair to a scripted server: the handshake declares + * `capabilities`, every other request goes to `handlers` and is recorded in `calls`. On + * 2026-07-28 results carry `resultType: "complete"`, as a conforming server's do. + */ +export async function scriptedClient( + handlers: Record, + options: ScriptedOptions = {} +): Promise<{ client: Client; calls: Call[]; notifications: Notification[] }> { + const { capabilities = EVENTS_CAPABILITIES, revision = MODERN } = options; + const [clientTx, serverTx] = InMemoryTransport.createLinkedPair(); + const calls: Call[] = []; + const notifications: Notification[] = []; + const headersById = new Map>(); + const transport: Transport = clientTx; + const send = transport.send.bind(transport); + transport.send = (message, sendOptions) => { + if ('id' in message && 'method' in message) headersById.set(message.id, { ...sendOptions?.headers }); + return send(message, sendOptions); + }; + const answer = async (request: JSONRPCRequest): Promise> => { + if (revision === MODERN && request.method === 'server/discover') { + return { + supportedVersions: [MODERN], + capabilities, + _meta: { 'io.modelcontextprotocol/serverInfo': { name: 'scripted', version: '1.0.0' } } + }; + } + if (revision === LEGACY && request.method === 'initialize') { + return { protocolVersion: LEGACY, capabilities, serverInfo: { name: 'scripted', version: '1.0.0' } }; + } + const call = { + id: request.id, + method: request.method, + params: (request.params ?? {}) as Record, + headers: headersById.get(request.id) ?? {} + }; + calls.push(call); + const handler = handlers[request.method]; + if (handler === undefined) throw new RpcError(-32_601, `Method not found: ${request.method}`); + return handler(call.params, call); + }; + serverTx.onmessage = message => { + const request = message as JSONRPCRequest; + if (request.id === undefined) { + notifications.push({ method: request.method, params: (request.params ?? {}) as Record }); + return; + } + void answer(request).then( + result => + serverTx.send({ + jsonrpc: '2.0', + id: request.id, + result: revision === MODERN ? { resultType: 'complete', ...result } : result + }), + (error: unknown) => + serverTx.send({ + jsonrpc: '2.0', + id: request.id, + error: { + code: error instanceof RpcError ? error.code : -32_603, + message: error instanceof Error ? error.message : String(error), + ...(error instanceof RpcError && error.data !== undefined && { data: error.data }) + } + }) + ); + }; + await serverTx.start(); + const client = new Client( + { name: 'events-test-client', version: '1.0.0' }, + revision === MODERN ? { versionNegotiation: { mode: { pin: MODERN } }, ...options.clientOptions } : options.clientOptions + ); + options.beforeConnect?.(client); + await client.connect(clientTx); + return { client, calls, notifications }; +} + +/** An `EventsClientExtension` attached to a scripted client before it connects. */ +export async function connectEvents( + handlers: Record, + options: ScriptedOptions & { events?: EventsClientOptions } = {} +): Promise<{ events: EventsClientExtension; client: Client; calls: Call[]; notifications: Notification[] }> { + const events = new EventsClientExtension(options.events); + const connected = await scriptedClient(handlers, { ...options, beforeConnect: client => events.attach(client) }); + return { events, ...connected }; +} + +export function descriptor(name: string, overrides: Partial = {}): EventDescriptor { + return { + name, + delivery: ['poll'], + inputSchema: { type: 'object' }, + payloadSchema: { type: 'object' }, + ...overrides + }; +} + +export function occurrence(eventId: string, name = 'tick'): EventOccurrence { + return { eventId, name, timestamp: '2026-11-18T00:00:00Z', data: { id: eventId } }; +} + +/** An `events/list` handler serving `events` in one page. */ +export function listing(...events: EventDescriptor[]): Handler { + return () => ({ events }); +} + +/** An `events/poll` handler with nothing to deliver, asking for the next poll in a minute. */ +export const quietPoll: Handler = () => ({ events: [], cursor: null, nextPollMs: 60_000 }); + +/** Answers each request with the next scripted result or error; once they run out, never answers. */ +export function script(...answers: Array | RpcError>): Handler { + return () => { + const next = answers.shift(); + if (next === undefined) return new Promise(() => {}); + if (next instanceof RpcError) throw next; + return next; + }; +} + +export const callsTo = (calls: Call[], method: string): Call[] => calls.filter(call => call.method === method); diff --git a/packages/client/tsdown.config.ts b/packages/client/tsdown.config.ts index d4a8de998a..c8dd21bdb4 100644 --- a/packages/client/tsdown.config.ts +++ b/packages/client/tsdown.config.ts @@ -10,7 +10,8 @@ export default defineConfig({ 'src/shimsBrowser.ts', 'src/validators/ajv.ts', 'src/validators/cfWorker.ts', - 'src/ext/skills/index.ts' + 'src/ext/skills/index.ts', + 'src/ext/events/index.ts' ], format: ['esm', 'cjs'], fixedExtension: true, @@ -28,9 +29,11 @@ export default defineConfig({ paths: { 'fast-uri': ['../core-internal/src/validators/fastUriShim.d.ts'], '@modelcontextprotocol/core/ext/skills': ['../core/src/ext/skills/index.ts'], + '@modelcontextprotocol/core/ext/events': ['../core/src/ext/events/index.ts'], '@modelcontextprotocol/core-internal': ['../core-internal/src/index.ts'], '@modelcontextprotocol/core-internal/public': ['../core-internal/src/exports/public/index.ts'], '@modelcontextprotocol/core-internal/ext/skills': ['../core-internal/src/ext/skills/index.ts'], + '@modelcontextprotocol/core-internal/ext/events': ['../core-internal/src/ext/events/index.ts'], '@modelcontextprotocol/core-internal/validators/ajv': ['../core-internal/src/validators/ajvProvider.ts'], '@modelcontextprotocol/core-internal/validators/cfWorker': ['../core-internal/src/validators/cfWorkerProvider.ts'] } @@ -40,5 +43,10 @@ export default defineConfig({ // The schema modules live in @modelcontextprotocol/core (a real runtime dependency); the // bundled core-internal shims import them via the './internal' subpath, which must stay an // external import (explicit entry — the tsconfig paths alias would otherwise inline it). - external: ['@modelcontextprotocol/client/_shims', '@modelcontextprotocol/core/internal', '@modelcontextprotocol/core/ext/skills'] + external: [ + '@modelcontextprotocol/client/_shims', + '@modelcontextprotocol/core/internal', + '@modelcontextprotocol/core/ext/skills', + '@modelcontextprotocol/core/ext/events' + ] }); diff --git a/packages/core-internal/test/packageTopologyPins.test.ts b/packages/core-internal/test/packageTopologyPins.test.ts index 0ae77c0981..35196ee426 100644 --- a/packages/core-internal/test/packageTopologyPins.test.ts +++ b/packages/core-internal/test/packageTopologyPins.test.ts @@ -38,8 +38,9 @@ const PUBLIC_PACKAGES: Record Date: Wed, 18 Nov 2026 15:40:30 +0200 Subject: [PATCH 17/37] fix(client): end event subscriptions on close and recover from stale cursors --- packages/client/src/client/client.ts | 20 +++ packages/client/src/ext/events/extension.ts | 15 +- packages/client/src/ext/events/poll.ts | 64 +++++++- packages/client/src/ext/events/request.ts | 16 ++ .../client/src/ext/events/subscription.ts | 51 ++++--- .../client/test/client/openStream.test.ts | 40 ++++- packages/client/test/ext/events/poll.test.ts | 139 +++++++++++++++++- 7 files changed, 309 insertions(+), 36 deletions(-) diff --git a/packages/client/src/client/client.ts b/packages/client/src/client/client.ts index 8845c81126..aef67ba4f6 100644 --- a/packages/client/src/client/client.ts +++ b/packages/client/src/client/client.ts @@ -454,6 +454,8 @@ export const clientInternals = {} as { handlers: { onNotification(notification: JSONRPCNotification): void; onEnd(end: StreamEnd): void }, options?: { headers?: Readonly> } ): StreamHandle; + // Runs `listener` whenever the client's connection closes, until the returned function removes it. + onClose(client: Client, listener: () => void): () => void; enforceStrictCapabilities(client: Client): boolean; walkPages( client: Client, @@ -603,6 +605,8 @@ export class Client extends Protocol { // Live `openStream` requests keyed by their `stream:N` id; an entry is removed when its stream ends. private _streamState = new Map(); private _nextStreamId = 0; + // Run by `_onclose` after the request streams end; added through `clientInternals.onClose`. + private _closeListeners = new Set<() => void>(); /** The auto-opened subscription backing ClientOptions.listChanged on a modern connection. */ private _autoOpenedSubscription?: McpSubscription; /** Backing store for {@linkcode getDiscoverResult}. Per-connection. */ @@ -610,6 +614,10 @@ export class Client extends Protocol { static { clientInternals.openStream = (client, request, handlers, options) => client._openStream(request, handlers, options); + clientInternals.onClose = (client, listener) => { + client._closeListeners.add(listener); + return () => void client._closeListeners.delete(listener); + }; clientInternals.enforceStrictCapabilities = client => client._enforceStrictCapabilities; clientInternals.walkPages = (client, method, fetchPage, items) => client._walkPages(method, fetchPage, items); clientInternals.readResource = (client, params, options) => client._readResource(params, options); @@ -2258,6 +2266,17 @@ export class Client extends Protocol { }; } + // Runs the `clientInternals.onClose` listeners from a snapshot; a throwing one goes to `onerror` and the rest still run. + private _runCloseListeners(): void { + for (const listener of this._closeListeners) { + try { + listener(); + } catch (error) { + this.onerror?.(error instanceof Error ? error : new Error(String(error))); + } + } + } + // Ends every live `openStream` request as `remote`: the connection it was sent on is gone. private _endStreams(): void { // A snapshot, so a stream that an `onEnd` reopens is not ended (and reopened again) by this same loop. @@ -2436,6 +2455,7 @@ export class Client extends Protocol { this._listenState.clear(); } this._endStreams(); + this._runCloseListeners(); } finally { // Base teardown runs even if a callback above throws, so pending requests and timers are always settled. super._onclose(); diff --git a/packages/client/src/ext/events/extension.ts b/packages/client/src/ext/events/extension.ts index f4b7a92513..2cceacca02 100644 --- a/packages/client/src/ext/events/extension.ts +++ b/packages/client/src/ext/events/extension.ts @@ -125,14 +125,19 @@ export class EventsClientExtension { * the first exchange with the server succeeds (for poll, the first * `events/poll` response). A transient failure of that exchange (a * transport error, or a JSON-RPC error that is not an Events kind) does - * not reject: delivery is retried in the background. Once subscribed, the - * server ending the subscription ends its loop (see {@linkcode EventSubscription}). + * not reject: delivery is retried in the background. A `cursor` the + * server refuses because the event type's schema changed is dropped: the + * event types are listed again, the subscription starts from now, and + * `onGap` reports the fresh cursor. Once subscribed, the server ending the + * subscription ends its loop (see {@linkcode EventSubscription}). * * @throws {EventsError} when the server refuses the subscription: `notFound` for an event type it does not list or * no longer serves, `invalidParams` for arguments its `inputSchema` rejects, `forbidden`, or another kind. - * @throws {NoCompatibleDeliveryModeError} when no delivery mode the event type offers is usable here. - * @throws {SdkError} `CapabilityNotSupported` when {@linkcode EventsClientExtension.supported} is `false`, or - * another code when the first exchange fails in the SDK (for example a request timeout). + * @throws {NoCompatibleDeliveryModeError} when no delivery mode the event type offers is usable here, also when + * the schema change that refused `cursor` left the event type without the selected mode. + * @throws {SdkError} `CapabilityNotSupported` when {@linkcode EventsClientExtension.supported} is `false`, + * `ConnectionClosed` when the client closes before the first exchange answers, or another code when that + * exchange fails in the SDK (for example a request timeout). */ async subscribe>(options: SubscribeOptions): Promise> { const connection = this.#require('subscribe'); diff --git a/packages/client/src/ext/events/poll.ts b/packages/client/src/ext/events/poll.ts index 1129952c39..919e4581b2 100644 --- a/packages/client/src/ext/events/poll.ts +++ b/packages/client/src/ext/events/poll.ts @@ -1,8 +1,10 @@ import type { PollEventsResult } from '@modelcontextprotocol/core/ext/events'; import { EVENTS_POLL_METHOD, PollEventsResultSchema } from '@modelcontextprotocol/core/ext/events'; +import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; +import { NoCompatibleDeliveryModeError } from './errors'; import type { Driver, DriverContext } from './subscription'; -import { recoveryFor, refusesSubscription, stillOffered } from './subscription'; +import { closedError, connectionClosed, isSchemaChange, recoveryFor, refusesSubscription, stillOffered } from './subscription'; const MAX_RETRY_DELAY_MS = 60_000; // setTimeout fires at once beyond this, which would bypass the floor. @@ -17,6 +19,12 @@ export class PollDriver implements Driver { // Sent until a poll succeeds. #maxAgeMs: number | undefined; #nextPollMs: number | undefined; + // A schema change has refused a poll since the last successful one. + #schemaChanged = false; + // The cursor was reset to now; the next successful poll reports the gap. + #reset = false; + // Set by the connection's close listener; ends the loop at once. + #closed = false; #wake: (() => void) | undefined; #running: Promise = Promise.resolve(); @@ -30,10 +38,16 @@ export class PollDriver implements Driver { start(): Promise { let settle!: { resolve(): void; reject(error: unknown): void }; const first = new Promise((resolve, reject) => (settle = { resolve, reject })); - this.#running = this.#run(settle.resolve).then(settle.resolve, (error: unknown) => { - settle.reject(error); - this.#context.queue.fail(error); + const removeCloseListener = this.#context.connection.onClose(() => { + this.#closed = true; + this.#wake?.(); }); + this.#running = this.#run(settle.resolve) + .then(settle.resolve, (error: unknown) => { + settle.reject(error); + this.#context.queue.fail(error); + }) + .finally(removeCloseListener); return first; } @@ -43,17 +57,24 @@ export class PollDriver implements Driver { await this.#running; } - // Calls `subscribed` after the first exchange unless it refuses the subscription, which rejects instead. + // Calls `subscribed` after the first exchange; throws, ending the subscription, on a first-exchange refusal or a closed connection. async #run(subscribed: () => void): Promise { const { connection, queue, subscription } = this.#context; let first = true; let failures = 0; while (!this.#abort.signal.aborted) { + if (this.#closed) throw closedError(); let result: PollEventsResult; try { result = await this.#poll(); } catch (error) { if (this.#abort.signal.aborted) return; + const closed = connectionClosed(connection, error); + if (closed !== undefined) throw closed; + if (first && isSchemaChange(error) && this.#cursor !== null) { + await this.#restartFromNow(); + continue; + } if (first && refusesSubscription(error)) throw error; first = false; subscribed(); @@ -65,6 +86,7 @@ export class PollDriver implements Driver { queue.fail(error); return; } + if (isSchemaChange(error)) this.#schemaChange(); await this.#sleep(this.#retryDelay(failures++)); continue; } @@ -83,13 +105,41 @@ export class PollDriver implements Driver { return this.#context.connection.request(EVENTS_POLL_METHOD, params, PollEventsResultSchema, mirror, { signal: this.#abort.signal }); } + // The first poll's cursor was refused for a schema change (a stale one passed to subscribe()): re-list, then poll from now or throw why not. + async #restartFromNow(): Promise { + const { connection, subscription } = this.#context; + try { + await connection.list(undefined, { signal: this.#abort.signal }); + } catch (error) { + throw connectionClosed(connection, error) ?? error; + } + const descriptor = connection.descriptor(subscription.name); + if (descriptor === undefined) throw new EventsError('notFound', 'Event type not found', { kind: 'event' }); + if (!descriptor.delivery.includes('poll')) + throw new NoCompatibleDeliveryModeError(subscription.name, descriptor.delivery, ['poll']); + this.#cursor = null; + this.#reset = true; + } + + // A second schema change in a row means the last cursor is refused (SEP: a stale schema epoch), so start again from now. + #schemaChange(): void { + if (this.#schemaChanged && this.#cursor !== null) { + this.#cursor = null; + this.#reset = true; + } + this.#schemaChanged = true; + } + #deliver(result: PollEventsResult): void { const { queue, subscription } = this.#context; const cursor = result.cursor ?? null; + const reset = this.#reset; this.#maxAgeMs = undefined; this.#nextPollMs = result.nextPollMs; + this.#schemaChanged = false; + this.#reset = false; // A type without replay has no position to have skipped past (SEP: ignore `truncated`). - if (result.truncated === true && cursor !== null) subscription.onGap?.(cursor); + if (reset || (result.truncated === true && cursor !== null)) subscription.onGap?.(cursor); for (const event of result.events) queue.push(event); this.#cursor = cursor; queue.setCursor(cursor); @@ -103,7 +153,7 @@ export class PollDriver implements Driver { #sleep(ms: number): Promise { return new Promise(resolve => { - if (this.#abort.signal.aborted) return resolve(); + if (this.#abort.signal.aborted || this.#closed) return resolve(); const wake = (): void => { clearTimeout(timer); this.#wake = undefined; diff --git a/packages/client/src/ext/events/request.ts b/packages/client/src/ext/events/request.ts index 0964e7558b..e8c7bcbbe7 100644 --- a/packages/client/src/ext/events/request.ts +++ b/packages/client/src/ext/events/request.ts @@ -29,9 +29,25 @@ function asEventsError(error: unknown): unknown { export class EventsConnection { readonly client: Client; readonly #descriptors = new Map(); + readonly #closeListeners = new Set<() => void>(); constructor(client: Client) { this.client = client; + clientInternals.onClose(client, () => { + for (const listener of this.#closeListeners) { + try { + listener(); + } catch (error) { + client.onerror?.(error instanceof Error ? error : new Error(String(error))); + } + } + }); + } + + // Runs `listener` when the client's connection closes, until the returned function removes it. + onClose(listener: () => void): () => void { + this.#closeListeners.add(listener); + return () => void this.#closeListeners.delete(listener); } descriptor(name: string): EventDescriptor | undefined { diff --git a/packages/client/src/ext/events/subscription.ts b/packages/client/src/ext/events/subscription.ts index fc8a8f6998..39d217dbc8 100644 --- a/packages/client/src/ext/events/subscription.ts +++ b/packages/client/src/ext/events/subscription.ts @@ -1,6 +1,6 @@ import type { DeliveryMode, DeliveryStatus, EventOccurrence } from '@modelcontextprotocol/core/ext/events'; import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; -import { SdkError } from '@modelcontextprotocol/core-internal/public'; +import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal/public'; import type { EventsConnection } from './request'; @@ -32,9 +32,12 @@ export interface SubscribeOptions { * `subscribe()`; once subscribed, the loop ends with an `EventsError` when the * server ends the subscription (`kind` says why: `forbidden`, * `invalidParams`, or `notFound` and a schema change once the event type is no - * longer listed). Other failures are retried. `T` types `data` and is not - * checked against the event type's `payloadSchema`. Leaving the loop early - * cancels the subscription. + * longer listed). Other failures are retried. Closing the client ends its + * subscriptions: the loop rejects with an `SdkError` (`ConnectionClosed`) at + * once when a request is in flight, otherwise when the next one would be sent; + * after reconnecting, subscribe again and pass {@linkcode EventSubscription.cursor}. + * `T` types `data` and is not checked against the event type's + * `payloadSchema`. Leaving the loop early cancels the subscription. * * Experimental: Events (SEP-3415) is new; this API may change in a minor release. * @@ -74,25 +77,33 @@ export function refusesSubscription(error: unknown): boolean { return error instanceof EventsError || error instanceof SdkError; } +// What a subscription ends with when its client's connection closes. +export function closedError(cause?: unknown): SdkError { + return new SdkError(SdkErrorCode.ConnectionClosed, 'Connection closed', undefined, cause === undefined ? undefined : { cause }); +} + +// The SdkError a subscription ends with when its client's connection is gone, judged at a failed request; `undefined` while connected. +export function connectionClosed(connection: EventsConnection, error: unknown): SdkError | undefined { + if (error instanceof SdkError && error.code === SdkErrorCode.ConnectionClosed) return error; + const notConnected = error instanceof SdkError && error.code === SdkErrorCode.NotConnected; + if (!notConnected && connection.client.transport !== undefined) return undefined; + return closedError(error); +} + +// An `unsupported` error saying the event type's schema changed in place. +export function isSchemaChange(error: unknown): boolean { + return ( + error instanceof EventsError && + error.kind === 'unsupported' && + (error.data as { reason?: unknown } | undefined)?.reason === 'schema_changed' + ); +} + // After a server error once subscribed (spec §6.3): re-list and go on if the event type is still offered, end the subscription, or retry later. export function recoveryFor(error: unknown): 'relist' | 'fail' | 'retry' { if (!(error instanceof EventsError)) return 'retry'; - const data = error.data as Record | undefined; - switch (error.kind) { - case 'notFound': { - return 'relist'; - } - case 'unsupported': { - return data?.['reason'] === 'schema_changed' ? 'relist' : 'retry'; - } - case 'forbidden': - case 'invalidParams': { - return 'fail'; - } - default: { - return 'retry'; - } - } + if (error.kind === 'notFound' || isSchemaChange(error)) return 'relist'; + return error.kind === 'forbidden' || error.kind === 'invalidParams' ? 'fail' : 'retry'; } // Re-lists, then whether `name` is still listed with `mode`; `undefined` when the list fails. diff --git a/packages/client/test/client/openStream.test.ts b/packages/client/test/client/openStream.test.ts index 121117facb..c94cf58717 100644 --- a/packages/client/test/client/openStream.test.ts +++ b/packages/client/test/client/openStream.test.ts @@ -1,6 +1,7 @@ /** * `clientInternals.openStream`: the package-internal long-lived request (no timeout, `stream:N` ids, frames routed by - * the subscription id in `_meta`) that the Events client's push mode opens `events/stream` with. + * the subscription id in `_meta`) that the Events client's push mode opens `events/stream` with; and + * `clientInternals.onClose`, the connection-closed listeners the Events client ends its subscriptions with. */ import type { JSONRPCMessage, JSONRPCNotification, JSONRPCRequest, TransportSendOptions } from '@modelcontextprotocol/core-internal'; import { @@ -317,3 +318,40 @@ describe('clientInternals.openStream', () => { expect(stream.ends).toEqual([]); }); }); + +describe('clientInternals.onClose', () => { + it('runs listeners when the connection closes, after the request streams end, unless removed', async () => { + const { client, clientTx } = await scriptedStreams(); + const order: string[] = []; + clientInternals.openStream(client, streamRequest('a'), { onNotification: () => {}, onEnd: () => void order.push('stream end') }); + clientInternals.onClose(client, () => void order.push('listener')); + const remove = clientInternals.onClose(client, () => void order.push('removed listener')); + remove(); + + await clientTx.close(); + + expect(order).toEqual(['stream end', 'listener']); + await client.close(); + }); + + it('a throwing listener goes to onerror and the other listeners and pending requests still settle', async () => { + const { client, clientTx } = await scriptedStreams(); + const errors: Error[] = []; + client.onerror = error => void errors.push(error); + const failure = new Error('listener failed'); + clientInternals.onClose(client, () => { + throw failure; + }); + const after = vi.fn(); + clientInternals.onClose(client, after); + const pending = client.request({ method: 'tools/list', params: {} }); + await flush(); + + await clientTx.close(); + + expect(after).toHaveBeenCalledOnce(); + await expect(pending).rejects.toMatchObject({ code: SdkErrorCode.ConnectionClosed }); + expect(errors).toEqual([failure]); + await client.close(); + }); +}); diff --git a/packages/client/test/ext/events/poll.test.ts b/packages/client/test/ext/events/poll.test.ts index 606aa1eaf0..7ffc8d5d5e 100644 --- a/packages/client/test/ext/events/poll.test.ts +++ b/packages/client/test/ext/events/poll.test.ts @@ -1,8 +1,9 @@ import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import type { Client } from '../../../src/client/client'; import type { EventSubscription, SubscribeOptions } from '../../../src/ext/events/index'; -import { EventsError } from '../../../src/ext/events/index'; +import { EventsError, NoCompatibleDeliveryModeError } from '../../../src/ext/events/index'; import type { Call, Handler, Notification } from './scripted'; import { callsTo, connectEvents, descriptor, listing, occurrence, RpcError, script } from './scripted'; @@ -30,13 +31,15 @@ async function pollWith( poll: Handler, list: Handler = listing(descriptor('tick')) ): Promise<{ + client: Client; calls: Call[]; notifications: Notification[]; polls: () => Call[]; subscribe: (options?: Partial) => Promise; }> { - const { events, calls, notifications } = await connectEvents({ 'events/list': list, 'events/poll': poll }); + const { events, client, calls, notifications } = await connectEvents({ 'events/list': list, 'events/poll': poll }); return { + client, calls, notifications, polls: () => callsTo(calls, 'events/poll'), @@ -138,6 +141,7 @@ describe('poll delivery', () => { }); it('resubscribes after schema_changed and fails on forbidden', async () => { + const onGap = vi.fn(); const { calls, polls, subscribe } = await pollWith( script( { events: [], cursor: 'c1', nextPollMs: 0 }, @@ -146,14 +150,16 @@ describe('poll delivery', () => { new RpcError(-32_024, 'Forbidden', { reason: 'Access revoked' }) ) ); - const sub = await subscribe(); + const sub = await subscribe({ onGap }); await vi.advanceTimersByTimeAsync(1000); expect(polls()).toHaveLength(2); expect(callsTo(calls, 'events/list')).toHaveLength(2); + // This server still accepts the last cursor after the change: no reset, no gap. await vi.advanceTimersByTimeAsync(1000); expect(polls()).toHaveLength(3); expect(polls()[2]!.params['cursor']).toBe('c1'); + expect(onGap).not.toHaveBeenCalled(); await vi.advanceTimersByTimeAsync(1000); expect(polls()).toHaveLength(4); @@ -168,6 +174,26 @@ describe('poll delivery', () => { expect(polls()).toHaveLength(4); }); + it('starts again from now when the server keeps refusing the last cursor after a schema change', async () => { + const onGap = vi.fn(); + const schemaChanged = new RpcError(-32_026, 'Unsupported', { feature: 'payloadSchema', reason: 'schema_changed' }); + // Cursors of the old schema epoch ('c…') are refused once the schema has changed; 'v2:…' cursors are the new epoch. + const { calls, polls, subscribe } = await pollWith(params => { + if (params['cursor'] === 'c0') return { events: [], cursor: 'c1', nextPollMs: 0 }; + if (params['cursor'] === 'c1') throw schemaChanged; + if (params['cursor'] === null) return { events: [], cursor: 'v2:0', nextPollMs: 0 }; + return { events: [occurrence('e1')], cursor: 'v2:1', nextPollMs: 60_000 }; + }); + const sub = await subscribe({ cursor: 'c0', onGap }); + await vi.advanceTimersByTimeAsync(10_000); + + expect(polls().map(call => call.params['cursor'])).toEqual(['c0', 'c1', 'c1', null, 'v2:0']); + expect(callsTo(calls, 'events/list')).toHaveLength(3); + expect(onGap).toHaveBeenCalledExactlyOnceWith('v2:0'); + expect(await nextEventId(sub[Symbol.asyncIterator]())).toBe('e1'); + expect(sub.cursor).toBe('v2:0'); + }); + it('ends the loop with notFound once the event type is no longer listed', async () => { const lists = [[descriptor('tick')], []]; const { calls, subscribe } = await pollWith( @@ -214,6 +240,8 @@ describe('poll delivery', () => { new RpcError(-32_023, 'Not found', { kind: 'event' }), new RpcError(-32_602, 'Invalid arguments'), new RpcError(-32_024, 'Forbidden'), + new RpcError(-32_026, 'Unsupported', { feature: 'deliveryMode', value: 'poll' }), + // Without a cursor there is no stale one to drop, so a schema change refuses too. new RpcError(-32_026, 'Unsupported', { feature: 'payloadSchema', reason: 'schema_changed' }) ]; for (const refusal of refusals) { @@ -251,6 +279,111 @@ describe('poll delivery', () => { expect(await nextEventId(sub[Symbol.asyncIterator]())).toBe('e1'); }); + it('ends the loop with ConnectionClosed when the client closes during a poll', async () => { + const { client, polls, subscribe } = await pollWith(script({ events: [], cursor: 'c1', nextPollMs: 0 })); + const sub = await subscribe(); + await vi.advanceTimersByTimeAsync(1000); + expect(polls()).toHaveLength(2); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + + await client.close(); + const error = await pending; + expect(error).toBeInstanceOf(SdkError); + expect(error).toMatchObject({ code: SdkErrorCode.ConnectionClosed }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(120_000); + expect(polls()).toHaveLength(2); + }); + + it('ends the loop with ConnectionClosed when the client closes during a backoff wait', async () => { + const { client, polls, subscribe } = await pollWith( + script({ events: [], cursor: 'c1', nextPollMs: 0 }, new RpcError(-32_603, 'Internal error'), { events: [], cursor: 'c2' }) + ); + const sub = await subscribe(); + await vi.advanceTimersByTimeAsync(1000); + expect(polls()).toHaveLength(2); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + + await client.close(); + const error = await pending; + expect(error).toBeInstanceOf(SdkError); + expect(error).toMatchObject({ code: SdkErrorCode.ConnectionClosed }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(120_000); + expect(polls()).toHaveLength(2); + }); + + it('ends the loop with ConnectionClosed at once when the client closes during a long nextPollMs wait', async () => { + const { client, polls, subscribe } = await pollWith(script({ events: [], cursor: 'c1', nextPollMs: 600_000 })); + const sub = await subscribe(); + expect(polls()).toHaveLength(1); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + + await client.close(); + const error = await pending; + expect(error).toBeInstanceOf(SdkError); + expect(error).toMatchObject({ code: SdkErrorCode.ConnectionClosed }); + expect(vi.getTimerCount()).toBe(0); + expect(polls()).toHaveLength(1); + }); + + it('rejects subscribe() with ConnectionClosed when the client closes before the first poll answers', async () => { + const { client, polls, subscribe } = await pollWith(script()); + const subscribing = subscribe().catch((error_: unknown) => error_); + await settle(); + expect(polls()).toHaveLength(1); + + await client.close(); + const error = await subscribing; + expect(error).toBeInstanceOf(SdkError); + expect(error).toMatchObject({ code: SdkErrorCode.ConnectionClosed }); + expect(vi.getTimerCount()).toBe(0); + }); + + it('drops a stale cursor that the first poll refuses for a schema change, and starts from now', async () => { + const onGap = vi.fn(); + const { calls, polls, subscribe } = await pollWith(params => { + if (params['cursor'] === 'stale') + throw new RpcError(-32_026, 'Unsupported', { feature: 'inputSchema', reason: 'schema_changed' }); + if (params['cursor'] === null) return { events: [], cursor: 'v2:0', nextPollMs: 0 }; + return { events: [occurrence('e1')], cursor: 'v2:1', nextPollMs: 60_000 }; + }); + const sub = await subscribe({ cursor: 'stale', onGap }); + + expect(polls().map(call => call.params['cursor'])).toEqual(['stale', null]); + expect(callsTo(calls, 'events/list')).toHaveLength(2); + expect(onGap).toHaveBeenCalledExactlyOnceWith('v2:0'); + expect(sub.cursor).toBe('v2:0'); + await vi.advanceTimersByTimeAsync(1000); + expect(await nextEventId(sub[Symbol.asyncIterator]())).toBe('e1'); + expect(onGap).toHaveBeenCalledOnce(); + }); + + it('rejects subscribe() after a schema change refuses its cursor when the type is gone or no longer polled', async () => { + // The first poll refuses the stale cursor; the re-list that follows returns `relisted`. + const staleCursorAgainst = async (relisted: ReturnType[]) => { + const lists = [[descriptor('tick')], relisted]; + const schemaChanged = new RpcError(-32_026, 'Unsupported', { feature: 'payloadSchema', reason: 'schema_changed' }); + const { polls, subscribe } = await pollWith(script(schemaChanged), () => ({ events: lists.shift() ?? relisted })); + const error = await subscribe({ cursor: 'stale' }).catch((error_: unknown) => error_); + return { error, polls: polls().length, timers: vi.getTimerCount() }; + }; + + const gone = await staleCursorAgainst([]); + expect(gone.error).toBeInstanceOf(EventsError); + expect(gone).toMatchObject({ error: { kind: 'notFound', data: { kind: 'event' } }, polls: 1, timers: 0 }); + + const pushOnly = await staleCursorAgainst([descriptor('tick', { delivery: ['push'] })]); + expect(pushOnly.error).toBeInstanceOf(NoCompatibleDeliveryModeError); + expect(pushOnly).toMatchObject({ error: { eventName: 'tick', offered: ['push'], usable: ['poll'] }, polls: 1, timers: 0 }); + }); + it('stops polling on cancel()', async () => { const { polls, subscribe } = await pollWith(script({ events: [], cursor: 'c1', nextPollMs: 0 })); const sub = await subscribe(); From 9aa9fbcb47aab913499beede876fdcc8d550a989 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 16:19:44 +0200 Subject: [PATCH 18/37] feat(client): Events push driver and shared recovery rules --- packages/client/src/client/client.ts | 8 +- packages/client/src/ext/events/extension.ts | 11 +- packages/client/src/ext/events/poll.ts | 33 +- packages/client/src/ext/events/push.ts | 312 ++++++++++ packages/client/src/ext/events/request.ts | 26 +- .../client/src/ext/events/subscription.ts | 83 ++- .../client/test/client/openStream.test.ts | 25 + packages/client/test/ext/events/poll.test.ts | 98 ++- packages/client/test/ext/events/push.test.ts | 560 ++++++++++++++++++ packages/client/test/ext/events/scripted.ts | 100 ++-- .../test/ext/events/subscription.test.ts | 51 ++ 11 files changed, 1214 insertions(+), 93 deletions(-) create mode 100644 packages/client/src/ext/events/push.ts create mode 100644 packages/client/test/ext/events/push.test.ts create mode 100644 packages/client/test/ext/events/subscription.test.ts diff --git a/packages/client/src/client/client.ts b/packages/client/src/client/client.ts index aef67ba4f6..030b2fef75 100644 --- a/packages/client/src/client/client.ts +++ b/packages/client/src/client/client.ts @@ -454,7 +454,7 @@ export const clientInternals = {} as { handlers: { onNotification(notification: JSONRPCNotification): void; onEnd(end: StreamEnd): void }, options?: { headers?: Readonly> } ): StreamHandle; - // Runs `listener` whenever the client's connection closes, until the returned function removes it. + // Runs `listener` whenever the client's connection closes or a fresh connect replaces it, until the returned function removes it. onClose(client: Client, listener: () => void): () => void; enforceStrictCapabilities(client: Client): boolean; walkPages( @@ -605,7 +605,7 @@ export class Client extends Protocol { // Live `openStream` requests keyed by their `stream:N` id; an entry is removed when its stream ends. private _streamState = new Map(); private _nextStreamId = 0; - // Run by `_onclose` after the request streams end; added through `clientInternals.onClose`. + // Run by `_onclose` and `_resetConnectionState` after the request streams end; added through `clientInternals.onClose`. private _closeListeners = new Set<() => void>(); /** The auto-opened subscription backing ClientOptions.listChanged on a modern connection. */ private _autoOpenedSubscription?: McpSubscription; @@ -652,6 +652,7 @@ export class Client extends Protocol { } this._listenState.clear(); this._endStreams(); + this._runCloseListeners(); // Debounce timers are connection-scoped: a callback armed on a // connection that is now gone must not fire onto whatever connection // (if any) replaces it. @@ -2268,7 +2269,8 @@ export class Client extends Protocol { // Runs the `clientInternals.onClose` listeners from a snapshot; a throwing one goes to `onerror` and the rest still run. private _runCloseListeners(): void { - for (const listener of this._closeListeners) { + const listeners = [...this._closeListeners]; + for (const listener of listeners) { try { listener(); } catch (error) { diff --git a/packages/client/src/ext/events/extension.ts b/packages/client/src/ext/events/extension.ts index 2cceacca02..5b529b1006 100644 --- a/packages/client/src/ext/events/extension.ts +++ b/packages/client/src/ext/events/extension.ts @@ -6,6 +6,7 @@ import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal/publ import type { Client } from '../../client/client'; import { NoCompatibleDeliveryModeError } from './errors'; import { PollDriver } from './poll'; +import { PushDriver } from './push'; import { EventsConnection } from './request'; import type { Driver, DriverContext, EventSubscription, SubscribeOptions } from './subscription'; import { SubscriptionQueue } from './subscription'; @@ -123,13 +124,15 @@ export class EventsClientExtension { * Subscribes to an event type, looking its descriptor up in the last * `events/list` (fetched again when it is not there), and resolves once * the first exchange with the server succeeds (for poll, the first - * `events/poll` response). A transient failure of that exchange (a + * `events/poll` response; for push, the first + * `notifications/events/active`). A transient failure of that exchange (a * transport error, or a JSON-RPC error that is not an Events kind) does * not reject: delivery is retried in the background. A `cursor` the * server refuses because the event type's schema changed is dropped: the * event types are listed again, the subscription starts from now, and - * `onGap` reports the fresh cursor. Once subscribed, the server ending the - * subscription ends its loop (see {@linkcode EventSubscription}). + * `onGap` reports the fresh cursor. A `-32020` lists the event types again + * and retries once. Once subscribed, every mode recovers from errors as + * {@linkcode EventSubscription} describes. * * @throws {EventsError} when the server refuses the subscription: `notFound` for an event type it does not list or * no longer serves, `invalidParams` for arguments its `inputSchema` rejects, `forbidden`, or another kind. @@ -138,6 +141,7 @@ export class EventsClientExtension { * @throws {SdkError} `CapabilityNotSupported` when {@linkcode EventsClientExtension.supported} is `false`, * `ConnectionClosed` when the client closes before the first exchange answers, or another code when that * exchange fails in the SDK (for example a request timeout). + * @throws {ProtocolError} `-32020` when the server rejects the `Mcp-Param` headers again after a re-list. */ async subscribe>(options: SubscribeOptions): Promise> { const connection = this.#require('subscribe'); @@ -160,6 +164,7 @@ export class EventsClientExtension { #driver(mode: DeliveryMode, context: DriverContext): Driver { if (mode === 'poll') return new PollDriver(context, this.#floorMs); + if (mode === 'push') return new PushDriver(context); throw new SdkError(SdkErrorCode.CapabilityNotSupported, `${mode} delivery is not available yet`); } diff --git a/packages/client/src/ext/events/poll.ts b/packages/client/src/ext/events/poll.ts index 919e4581b2..531711a8fe 100644 --- a/packages/client/src/ext/events/poll.ts +++ b/packages/client/src/ext/events/poll.ts @@ -1,14 +1,20 @@ import type { PollEventsResult } from '@modelcontextprotocol/core/ext/events'; import { EVENTS_POLL_METHOD, PollEventsResultSchema } from '@modelcontextprotocol/core/ext/events'; -import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; -import { NoCompatibleDeliveryModeError } from './errors'; import type { Driver, DriverContext } from './subscription'; -import { closedError, connectionClosed, isSchemaChange, recoveryFor, refusesSubscription, stillOffered } from './subscription'; +import { + closedError, + connectionClosed, + isSchemaChange, + MAX_TIMER_DELAY_MS, + recoveryFor, + refusesSubscription, + reportGap, + requireOffered, + stillOffered +} from './subscription'; const MAX_RETRY_DELAY_MS = 60_000; -// setTimeout fires at once beyond this, which would bypass the floor. -const MAX_TIMER_DELAY_MS = 2_147_483_647; // Poll delivery (spec §6.3): one `events/poll` loop, again at once on `hasMore`, otherwise after `nextPollMs` but never sooner than the floor. export class PollDriver implements Driver { @@ -79,8 +85,10 @@ export class PollDriver implements Driver { first = false; subscribed(); const recovery = recoveryFor(error); + // A -32020 here is the second: the request already re-listed once and retried with fresh headers. const gone = recovery === 'fail' || + recovery === 'mismatch' || (recovery === 'relist' && (await stillOffered(connection, subscription.name, 'poll', this.#abort.signal)) === false); if (gone) { queue.fail(error); @@ -107,16 +115,7 @@ export class PollDriver implements Driver { // The first poll's cursor was refused for a schema change (a stale one passed to subscribe()): re-list, then poll from now or throw why not. async #restartFromNow(): Promise { - const { connection, subscription } = this.#context; - try { - await connection.list(undefined, { signal: this.#abort.signal }); - } catch (error) { - throw connectionClosed(connection, error) ?? error; - } - const descriptor = connection.descriptor(subscription.name); - if (descriptor === undefined) throw new EventsError('notFound', 'Event type not found', { kind: 'event' }); - if (!descriptor.delivery.includes('poll')) - throw new NoCompatibleDeliveryModeError(subscription.name, descriptor.delivery, ['poll']); + await requireOffered(this.#context.connection, this.#context.subscription.name, 'poll', this.#abort.signal); this.#cursor = null; this.#reset = true; } @@ -131,7 +130,7 @@ export class PollDriver implements Driver { } #deliver(result: PollEventsResult): void { - const { queue, subscription } = this.#context; + const { connection, queue, subscription } = this.#context; const cursor = result.cursor ?? null; const reset = this.#reset; this.#maxAgeMs = undefined; @@ -139,7 +138,7 @@ export class PollDriver implements Driver { this.#schemaChanged = false; this.#reset = false; // A type without replay has no position to have skipped past (SEP: ignore `truncated`). - if (reset || (result.truncated === true && cursor !== null)) subscription.onGap?.(cursor); + if (reset || (result.truncated === true && cursor !== null)) reportGap(subscription, connection, cursor); for (const event of result.events) queue.push(event); this.#cursor = cursor; queue.setCursor(cursor); diff --git a/packages/client/src/ext/events/push.ts b/packages/client/src/ext/events/push.ts new file mode 100644 index 0000000000..7855959223 --- /dev/null +++ b/packages/client/src/ext/events/push.ts @@ -0,0 +1,312 @@ +import type { EventOccurrence, EventsActiveNotificationParams } from '@modelcontextprotocol/core/ext/events'; +import { + EventNotificationParamsSchema, + EVENTS_ACTIVE_NOTIFICATION, + EVENTS_EVENT_NOTIFICATION, + EVENTS_HEARTBEAT_NOTIFICATION, + EVENTS_STREAM_METHOD, + EVENTS_TERMINATED_NOTIFICATION, + EventsActiveNotificationParamsSchema, + EventsHeartbeatNotificationParamsSchema, + EventsTerminatedNotificationParamsSchema +} from '@modelcontextprotocol/core/ext/events'; +import type { JSONRPCNotification } from '@modelcontextprotocol/core-internal'; +import { ProtocolError, SUBSCRIPTION_ID_META_KEY } from '@modelcontextprotocol/core-internal'; +import type * as z from 'zod/v4'; + +import type { StreamEnd, StreamHandle } from '../../client/client'; +import { clientInternals } from '../../client/client'; +import { asEventsError } from './request'; +import type { Driver, DriverContext } from './subscription'; +import { + closedError, + connectionClosed, + isSchemaChange, + MAX_TIMER_DELAY_MS, + recoveryFor, + refusesSubscription, + reportGap, + requireOffered, + stillOffered +} from './subscription'; + +// No message for this many granted heartbeat intervals, counted from `active`, means the stream is dead (SEP-3415 §Push). +const DEAD_AFTER_HEARTBEATS = 3; +const RECONNECT_BASE_MS = 1000; +const RECONNECT_MAX_MS = 30_000; + +// How a stream ended: with the server's error (a `terminated` frame or an error response) or a failed send, or without an error. +interface Ending { + error?: unknown; +} + +function endingOf(end: StreamEnd): Ending { + return end.cause === 'remote' && end.error !== undefined ? { error: asEventsError(end.error) } : {}; +} + +// A pushed event as every mode yields it: without the stream's subscription id in `_meta`, and without `_meta` when nothing else is in it. +function withoutStreamId(event: EventOccurrence): EventOccurrence { + if (event._meta === undefined || !(SUBSCRIPTION_ID_META_KEY in event._meta)) return event; + const { _meta: meta, ...occurrence } = event; + const rest = Object.fromEntries(Object.entries(meta).filter(([key]) => key !== SUBSCRIPTION_ID_META_KEY)); + return Object.keys(rest).length === 0 ? occurrence : { ...occurrence, _meta: rest }; +} + +// Push delivery (spec §6.3): one `events/stream` at a time, reopened from the last cursor after a jittered delay whenever it ends. +export class PushDriver implements Driver { + readonly #context: DriverContext; + // Aborts a re-list in flight on stop() or a closed connection. + readonly #abort = new AbortController(); + #cursor: string | null; + // Sent until a stream is active. + #maxAgeMs: number | undefined; + // Until the first `active`, or a transient failure of a stream before it. + #first = true; + #subscribed: () => void = () => {}; + // Reconnect delays taken since the last `active`. + #attempt = 0; + // A schema change has refused the subscription since the last `active`. + #schemaChanged = false; + // A -32020 has been re-listed for since the last `active`. + #mismatched = false; + // The cursor was reset to now; the next `active` reports the gap. + #reset = false; + #stopped = false; + // Set by the connection's close listener, which ends the subscription at once. + #closed = false; + // The stream last opened; a terminated one stays registered until its final result arrives. + #handle: StreamHandle | undefined; + // Ends the wait for the open stream. + #end: ((ending: Ending) => void) | undefined; + // The open stream's heartbeat grant, from its last `active`. + #grantMs: number | undefined; + #dead: ReturnType | undefined; + #wake: (() => void) | undefined; + #running: Promise = Promise.resolve(); + + constructor(context: DriverContext) { + this.#context = context; + this.#cursor = context.subscription.cursor ?? null; + this.#maxAgeMs = context.subscription.maxAgeMs; + } + + start(): Promise { + let settle!: { resolve(): void; reject(error: unknown): void }; + const first = new Promise((resolve, reject) => (settle = { resolve, reject })); + const fail = (error: unknown): void => { + settle.reject(error); + this.#context.queue.fail(error); + }; + this.#subscribed = () => { + this.#first = false; + settle.resolve(); + }; + const removeCloseListener = this.#context.connection.onClose(() => { + this.#closed = true; + this.#interrupt(); + fail(closedError()); + }); + this.#running = this.#run().then(settle.resolve, fail).finally(removeCloseListener); + return first; + } + + async stop(): Promise { + this.#stopped = true; + this.#interrupt(); + await this.#handle?.close(); + await this.#running; + } + + // Ends what the loop waits for: the open stream, a re-list or a reconnect delay. + #interrupt(): void { + this.#abort.abort(); + this.#wake?.(); + this.#end?.({}); + } + + // Reopens after every end until stopped; throws, ending the subscription, when an end calls for it. + async #run(): Promise { + while (!this.#stopped && !this.#closed) { + const { error } = await this.#open(); + if (this.#stopped || this.#closed) return; + if (error === undefined) this.#subscribed(); + else await this.#recover(error); + await this.#sleep(this.#reconnectDelay()); + } + } + + // After a stream ended with `error` (spec §6.3): throws when that ends the subscription, otherwise readies the reopen. + async #recover(error: unknown): Promise { + const { connection, subscription } = this.#context; + const closed = connectionClosed(connection, error); + if (closed !== undefined) throw closed; + const recovery = recoveryFor(error); + if (recovery === 'mismatch') { + if (this.#mismatched) throw error; + this.#mismatched = true; + await connection.list(undefined, { signal: this.#abort.signal }).catch(() => {}); + return; + } + if (this.#first) { + // A stale cursor passed to subscribe(): drop it and start from now, if the event type is still pushed. + if (isSchemaChange(error) && this.#cursor !== null) { + await requireOffered(connection, subscription.name, 'push', this.#abort.signal); + this.#restartFromNow(); + return; + } + if (refusesSubscription(error)) throw error; + this.#subscribed(); + return; + } + if (recovery === 'retry') return; + if (recovery === 'fail') throw error; + const offered = await stillOffered(connection, subscription.name, 'push', this.#abort.signal); + if (offered === false) throw error; + if (offered === true && isSchemaChange(error)) this.#schemaChange(); + } + + #restartFromNow(): void { + this.#cursor = null; + this.#reset = true; + } + + // A second schema change in a row means the last cursor is refused (SEP: a stale schema epoch), so start again from now. + #schemaChange(): void { + if (this.#schemaChanged && this.#cursor !== null) this.#restartFromNow(); + this.#schemaChanged = true; + } + + // Opens `events/stream` from the last cursor (no `heartbeatMs` suggestion) and resolves with how it ended. + #open(): Promise { + const { connection, subscription } = this.#context; + const { name, arguments: args } = subscription; + const params = { + name, + ...(args !== undefined && { arguments: args }), + cursor: this.#cursor, + ...(this.#maxAgeMs !== undefined && { maxAgeMs: this.#maxAgeMs }) + }; + const headers = connection.paramHeadersFor(name, args); + // A terminated stream whose final result has not arrived. + void this.#handle?.close(); + this.#grantMs = undefined; + return new Promise(resolve => { + let ended = false; + const end = (ending: Ending): void => { + if (ended) return; + ended = true; + clearTimeout(this.#dead); + this.#end = undefined; + resolve(ending); + }; + this.#end = end; + try { + this.#handle = clientInternals.openStream( + connection.client, + { method: EVENTS_STREAM_METHOD, params }, + { + onNotification: notification => { + if (!ended) this.#frame(notification, end); + }, + onEnd: streamEnd => end(endingOf(streamEnd)) + }, + Object.keys(headers).length === 0 ? undefined : { headers } + ); + } catch (error) { + end({ error }); + } + }); + } + + // One frame of the open stream. `terminated` ends it with the server's error; `notifications/events/error` changes nothing. + #frame(notification: JSONRPCNotification, end: (ending: Ending) => void): void { + switch (notification.method) { + case EVENTS_ACTIVE_NOTIFICATION: { + const params = this.#parse(EventsActiveNotificationParamsSchema, notification); + if (params !== undefined) this.#active(params); + break; + } + case EVENTS_EVENT_NOTIFICATION: { + const params = this.#parse(EventNotificationParamsSchema, notification); + if (params === undefined) break; + this.#context.queue.push(withoutStreamId(params)); + this.#setCursor(params.cursor ?? null); + break; + } + case EVENTS_HEARTBEAT_NOTIFICATION: { + const params = this.#parse(EventsHeartbeatNotificationParamsSchema, notification); + if (params !== undefined) this.#setCursor(params.cursor ?? null); + break; + } + case EVENTS_TERMINATED_NOTIFICATION: { + const params = this.#parse(EventsTerminatedNotificationParamsSchema, notification); + if (params === undefined) break; + const { code, message, data } = params.error; + end({ error: asEventsError(ProtocolError.fromError(code, message, data)) }); + return; + } + } + this.#alive(end); + } + + // Every `active` carries the heartbeat grant and the position delivery starts from; `truncated` reports a gap. + #active(params: EventsActiveNotificationParams): void { + const { connection, subscription } = this.#context; + const cursor = params.cursor ?? null; + const reset = this.#reset; + this.#grantMs = params.heartbeatMs; + this.#attempt = 0; + this.#schemaChanged = false; + this.#mismatched = false; + this.#reset = false; + this.#maxAgeMs = undefined; + // A type without replay has no position to have skipped past (SEP: ignore `truncated`). + if (reset || (params.truncated === true && cursor !== null)) reportGap(subscription, connection, cursor); + this.#setCursor(cursor); + this.#subscribed(); + } + + // From `active` on, every message restarts the countdown to declaring the stream dead and reconnecting. + #alive(end: (ending: Ending) => void): void { + if (this.#grantMs === undefined) return; + clearTimeout(this.#dead); + this.#dead = setTimeout( + () => { + end({}); + void this.#handle?.close(); + }, + Math.min(DEAD_AFTER_HEARTBEATS * this.#grantMs, MAX_TIMER_DELAY_MS) + ); + } + + #setCursor(cursor: string | null): void { + this.#cursor = cursor; + this.#context.queue.setCursor(cursor); + } + + // The frame's params, or `undefined` (reported to onerror) when they do not match the schema. + #parse(schema: S, notification: JSONRPCNotification): z.output | undefined { + const parsed = schema.safeParse(notification.params); + if (parsed.success) return parsed.data; + this.#context.connection.report(new Error(`Invalid ${notification.method} params: ${parsed.error.message}`)); + return undefined; + } + + // random() × min(30 s, 1 s × 2^attempt), attempts counted since the last `active` (SEP: jitter before reconnecting). + #reconnectDelay(): number { + return Math.random() * Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** this.#attempt++); + } + + #sleep(ms: number): Promise { + return new Promise(resolve => { + if (this.#stopped || this.#closed) return resolve(); + const wake = (): void => { + clearTimeout(timer); + this.#wake = undefined; + resolve(); + }; + const timer = setTimeout(wake, ms); + this.#wake = wake; + }); + } +} diff --git a/packages/client/src/ext/events/request.ts b/packages/client/src/ext/events/request.ts index e8c7bcbbe7..8f4d269813 100644 --- a/packages/client/src/ext/events/request.ts +++ b/packages/client/src/ext/events/request.ts @@ -1,17 +1,13 @@ import type { EventDescriptor, ListEventsResult } from '@modelcontextprotocol/core/ext/events'; import { EVENTS_LIST_METHOD, ListEventsResultSchema } from '@modelcontextprotocol/core/ext/events'; import type { RequestOptions, StandardSchemaV1, XMcpHeaderDeclaration } from '@modelcontextprotocol/core-internal'; -import { - buildMcpParamHeaders, - HEADER_MISMATCH_ERROR_CODE, - ProtocolError, - scanXMcpHeaderDeclarations -} from '@modelcontextprotocol/core-internal'; +import { buildMcpParamHeaders, ProtocolError, scanXMcpHeaderDeclarations } from '@modelcontextprotocol/core-internal'; import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; import type { Client } from '../../client/client'; import { clientInternals } from '../../client/client'; import { detectProbeEnvironment, detectProbeTransportKind } from '../../client/versionNegotiation'; +import { isHeaderMismatch } from './subscription'; // The event type a request is about, whose annotated arguments become `Mcp-Param` headers. export interface ParamMirror { @@ -20,7 +16,7 @@ export interface ParamMirror { } // An events-coded `ProtocolError` as the `EventsError` it stands for; anything else unchanged. -function asEventsError(error: unknown): unknown { +export function asEventsError(error: unknown): unknown { if (!(error instanceof ProtocolError) || error instanceof EventsError) return error; return EventsError.fromProtocolError(error) ?? error; } @@ -34,22 +30,29 @@ export class EventsConnection { constructor(client: Client) { this.client = client; clientInternals.onClose(client, () => { - for (const listener of this.#closeListeners) { + // A snapshot, so a listener that adds or removes another does not change who runs this time. + const listeners = [...this.#closeListeners]; + for (const listener of listeners) { try { listener(); } catch (error) { - client.onerror?.(error instanceof Error ? error : new Error(String(error))); + this.report(error); } } }); } - // Runs `listener` when the client's connection closes, until the returned function removes it. + // Runs `listener` when the client's connection closes or a fresh connect replaces it, until the returned function removes it. onClose(listener: () => void): () => void { this.#closeListeners.add(listener); return () => void this.#closeListeners.delete(listener); } + // Hands an error nothing else can surface to the client's onerror. + report(error: unknown): void { + this.client.onerror?.(error instanceof Error ? error : new Error(String(error))); + } + descriptor(name: string): EventDescriptor | undefined { return this.#descriptors.get(name)?.descriptor; } @@ -93,8 +96,7 @@ export class EventsConnection { try { return await send(); } catch (error) { - const mismatch = error instanceof ProtocolError && error.code === HEADER_MISMATCH_ERROR_CODE; - if (mirror === undefined || !mismatch || !this.#mirroring()) throw error; + if (mirror === undefined || !isHeaderMismatch(error)) throw error; await this.list(undefined, options); return await send(); } diff --git a/packages/client/src/ext/events/subscription.ts b/packages/client/src/ext/events/subscription.ts index 39d217dbc8..98d0ceeff4 100644 --- a/packages/client/src/ext/events/subscription.ts +++ b/packages/client/src/ext/events/subscription.ts @@ -1,9 +1,14 @@ import type { DeliveryMode, DeliveryStatus, EventOccurrence } from '@modelcontextprotocol/core/ext/events'; +import { HEADER_MISMATCH_ERROR_CODE, ProtocolError } from '@modelcontextprotocol/core-internal'; import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal/public'; +import { NoCompatibleDeliveryModeError } from './errors'; import type { EventsConnection } from './request'; +// setTimeout fires at once beyond this. +export const MAX_TIMER_DELAY_MS = 2_147_483_647; + /** * What to subscribe to, and how. * @@ -22,20 +27,40 @@ export interface SubscribeOptions { cursor?: string | null; /** Replays no event older than this many milliseconds, however old `cursor` is. */ maxAgeMs?: number; - /** Called with the fresh cursor when the server reports that events were skipped (`truncated`). */ + /** + * Called with the fresh cursor when events may have been skipped: the + * server reports `truncated`, or delivery started again from now after a + * schema change. An error it throws goes to the client's `onerror`, and + * delivery goes on. + */ onGap?: (cursor: string | null) => void; } /** - * One subscription's events. The `for await` loop is the same for every - * delivery mode. A refusal of the subscription itself comes from - * `subscribe()`; once subscribed, the loop ends with an `EventsError` when the - * server ends the subscription (`kind` says why: `forbidden`, - * `invalidParams`, or `notFound` and a schema change once the event type is no - * longer listed). Other failures are retried. Closing the client ends its - * subscriptions: the loop rejects with an `SdkError` (`ConnectionClosed`) at - * once when a request is in flight, otherwise when the next one would be sent; - * after reconnecting, subscribe again and pass {@linkcode EventSubscription.cursor}. + * One subscription's events. The `for await` loop, and how a subscription + * recovers from errors, are the same in every delivery mode. A refusal of the + * subscription itself comes from `subscribe()`. Once subscribed, a server + * error is handled by its kind: + * + * - `notFound`, or `unsupported` for a schema change: the event types are + * listed again, and delivery goes on while the event type is still listed + * with this delivery mode; otherwise the loop ends with that `EventsError`. + * After a schema change delivery resumes from the last cursor; when the + * server refuses that cursor too, it starts again from now and `onGap` + * reports it. + * - Any other `EventsError` (`forbidden`, `invalidParams`, `resourceExhausted`, + * `callbackEndpointError`, any other `unsupported`): the loop ends with it, + * and `kind` says why. + * - A `ProtocolError` `-32020` (the `Mcp-Param` headers do not match the + * arguments): the event types are listed again and the request is retried + * once with fresh headers; a second `-32020` ends the loop with it. + * - Anything else (a network or transport failure, another JSON-RPC error, a + * push stream that ends or goes silent): retried after a backoff. + * + * Closing the client, or connecting it again, ends its subscriptions: the loop + * rejects with an `SdkError` (`ConnectionClosed`) at once when a request is in + * flight, otherwise when the next one would be sent; after reconnecting, + * subscribe again and pass {@linkcode EventSubscription.cursor}. * `T` types `data` and is not checked against the event type's * `payloadSchema`. Leaving the loop early cancels the subscription. * @@ -72,9 +97,14 @@ export interface DriverContext { readonly connection: EventsConnection; } -// An error of the first exchange that subscribe() rejects with; any other (transport, non-Events JSON-RPC) is retried in the background. +// An error of the first exchange that subscribe() rejects with (a -32020 only once its re-list is spent); any other (transport, non-Events JSON-RPC) is retried in the background. export function refusesSubscription(error: unknown): boolean { - return error instanceof EventsError || error instanceof SdkError; + return error instanceof EventsError || error instanceof SdkError || isHeaderMismatch(error); +} + +// A -32020: the request's `Mcp-Param` headers do not match its arguments (D26). +export function isHeaderMismatch(error: unknown): boolean { + return error instanceof ProtocolError && error.code === HEADER_MISMATCH_ERROR_CODE; } // What a subscription ends with when its client's connection closes. @@ -99,11 +129,32 @@ export function isSchemaChange(error: unknown): boolean { ); } -// After a server error once subscribed (spec §6.3): re-list and go on if the event type is still offered, end the subscription, or retry later. -export function recoveryFor(error: unknown): 'relist' | 'fail' | 'retry' { +// Every mode's recovery once subscribed (spec §6.3): `relist` and go on while still offered, `mismatch` (re-list and retry once, then end), `fail` (end with the error), or `retry` later. +export function recoveryFor(error: unknown): 'relist' | 'mismatch' | 'fail' | 'retry' { + if (isHeaderMismatch(error)) return 'mismatch'; if (!(error instanceof EventsError)) return 'retry'; - if (error.kind === 'notFound' || isSchemaChange(error)) return 'relist'; - return error.kind === 'forbidden' || error.kind === 'invalidParams' ? 'fail' : 'retry'; + return error.kind === 'notFound' || isSchemaChange(error) ? 'relist' : 'fail'; +} + +// Reports a possible gap at `cursor` through onGap; a throwing onGap goes to the client's onerror, and delivery goes on. +export function reportGap(subscription: SubscribeOptions, connection: EventsConnection, cursor: string | null): void { + try { + subscription.onGap?.(cursor); + } catch (error) { + connection.report(error); + } +} + +// Re-lists, then throws why `name` cannot be subscribed with `mode`: notFound when unlisted, NoCompatibleDeliveryModeError when `mode` is not offered. +export async function requireOffered(connection: EventsConnection, name: string, mode: DeliveryMode, signal: AbortSignal): Promise { + try { + await connection.list(undefined, { signal }); + } catch (error) { + throw connectionClosed(connection, error) ?? error; + } + const descriptor = connection.descriptor(name); + if (descriptor === undefined) throw new EventsError('notFound', 'Event type not found', { kind: 'event' }); + if (!descriptor.delivery.includes(mode)) throw new NoCompatibleDeliveryModeError(name, descriptor.delivery, [mode]); } // Re-lists, then whether `name` is still listed with `mode`; `undefined` when the list fails. diff --git a/packages/client/test/client/openStream.test.ts b/packages/client/test/client/openStream.test.ts index c94cf58717..00b8b428e3 100644 --- a/packages/client/test/client/openStream.test.ts +++ b/packages/client/test/client/openStream.test.ts @@ -334,6 +334,31 @@ describe('clientInternals.onClose', () => { await client.close(); }); + it('runs listeners when the client reconnects without closing, after the request streams end', async () => { + const { client } = await scriptedStreams(); + const order: string[] = []; + clientInternals.openStream(client, streamRequest('a'), { onNotification: () => {}, onEnd: () => void order.push('stream end') }); + clientInternals.onClose(client, () => void order.push('listener')); + const next = await scriptedServer(); + + await client.connect(next.clientTx); + + expect(order).toEqual(['stream end', 'listener']); + await client.close(); + }); + + it('runs the listeners registered when the connection closed, not those they add', async () => { + const { client, clientTx } = await scriptedStreams(); + const added = vi.fn(); + clientInternals.onClose(client, () => void clientInternals.onClose(client, added)); + + await clientTx.close(); + + expect(added).not.toHaveBeenCalled(); + await client.close(); + expect(added).toHaveBeenCalled(); + }); + it('a throwing listener goes to onerror and the other listeners and pending requests still settle', async () => { const { client, clientTx } = await scriptedStreams(); const errors: Error[] = []; diff --git a/packages/client/test/ext/events/poll.test.ts b/packages/client/test/ext/events/poll.test.ts index 7ffc8d5d5e..d4f79aa2d1 100644 --- a/packages/client/test/ext/events/poll.test.ts +++ b/packages/client/test/ext/events/poll.test.ts @@ -1,4 +1,4 @@ -import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal'; +import { ProtocolError, SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; import type { Client } from '../../../src/client/client'; @@ -34,14 +34,16 @@ async function pollWith( client: Client; calls: Call[]; notifications: Notification[]; + reconnect: () => Promise; polls: () => Call[]; subscribe: (options?: Partial) => Promise; }> { - const { events, client, calls, notifications } = await connectEvents({ 'events/list': list, 'events/poll': poll }); + const { events, client, calls, notifications, reconnect } = await connectEvents({ 'events/list': list, 'events/poll': poll }); return { client, calls, notifications, + reconnect, polls: () => callsTo(calls, 'events/poll'), subscribe: async (options = {}) => { const subscription = await events.subscribe({ name: 'tick', delivery: 'poll', ...options }); @@ -212,6 +214,82 @@ describe('poll delivery', () => { expect(callsTo(calls, 'events/list')).toHaveLength(2); }); + it('ends the loop on resourceExhausted, callbackEndpointError and an unsupported that is not a schema change', async () => { + for (const refusal of [ + new RpcError(-32_025, 'Too many subscriptions', { limit: 'subscriptions' }), + new RpcError(-32_027, 'Callback endpoint error', { reason: 'timeout' }), + new RpcError(-32_026, 'Unsupported', { feature: 'deliveryMode', value: 'poll' }) + ]) { + const { calls, polls, subscribe } = await pollWith(script({ events: [], cursor: 'c1', nextPollMs: 0 }, refusal)); + const sub = await subscribe(); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + await vi.advanceTimersByTimeAsync(1000); + + const error = await pending; + expect(error).toBeInstanceOf(EventsError); + expect(error).toMatchObject({ code: refusal.code }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(120_000); + expect(polls()).toHaveLength(2); + expect(callsTo(calls, 'events/list')).toHaveLength(1); + } + }); + + it('ends the loop on a second -32020 after the re-list', async () => { + const mismatch = new RpcError(-32_020, 'Mcp-Param-Region header mismatch'); + const { calls, polls, subscribe } = await pollWith(script({ events: [], cursor: 'c1', nextPollMs: 0 }, mismatch, mismatch)); + const sub = await subscribe(); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + await vi.advanceTimersByTimeAsync(1000); + + const error = await pending; + expect(error).toBeInstanceOf(ProtocolError); + expect(error).toMatchObject({ code: -32_020 }); + expect(polls()).toHaveLength(3); + expect(callsTo(calls, 'events/list')).toHaveLength(2); + expect(vi.getTimerCount()).toBe(0); + }); + + it('rejects subscribe() when the first poll mismatches Mcp-Param headers again after a re-list', async () => { + const mismatch = new RpcError(-32_020, 'Mcp-Param-Region header mismatch'); + const { calls, polls, subscribe } = await pollWith(script(mismatch, mismatch)); + const error = await subscribe().catch((error_: unknown) => error_); + + expect(error).toBeInstanceOf(ProtocolError); + expect(error).toMatchObject({ code: -32_020 }); + expect(polls()).toHaveLength(2); + expect(callsTo(calls, 'events/list')).toHaveLength(2); + expect(vi.getTimerCount()).toBe(0); + }); + + it('reports a throwing onGap to onerror and keeps polling', async () => { + const failure = new Error('onGap failed'); + const { client, polls, subscribe } = await pollWith( + script( + { events: [], cursor: 'c5', truncated: true, nextPollMs: 0 }, + { events: [occurrence('e1')], cursor: 'c6', nextPollMs: 60_000 } + ) + ); + const errors: Error[] = []; + client.onerror = error => void errors.push(error); + const sub = await subscribe({ + cursor: 'c0', + onGap: () => { + throw failure; + } + }); + + expect(errors).toEqual([failure]); + expect(sub.cursor).toBe('c5'); + await vi.advanceTimersByTimeAsync(1000); + expect(polls()).toHaveLength(2); + expect(await nextEventId(sub[Symbol.asyncIterator]())).toBe('e1'); + }); + it('retries other errors after max(floor, nextPollMs), doubling to 60 s', async () => { const failures = Array.from({ length: 9 }, () => new RpcError(-32_603, 'Internal error')); const { polls, subscribe } = await pollWith( @@ -333,6 +411,22 @@ describe('poll delivery', () => { expect(polls()).toHaveLength(1); }); + it('ends the loop with ConnectionClosed when the client reconnects without closing', async () => { + const { polls, reconnect, subscribe } = await pollWith(script({ events: [], cursor: 'c1', nextPollMs: 600_000 })); + const sub = await subscribe(); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + + await reconnect(); + const error = await pending; + expect(error).toBeInstanceOf(SdkError); + expect(error).toMatchObject({ code: SdkErrorCode.ConnectionClosed }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(600_000); + expect(polls()).toHaveLength(1); + }); + it('rejects subscribe() with ConnectionClosed when the client closes before the first poll answers', async () => { const { client, polls, subscribe } = await pollWith(script()); const subscribing = subscribe().catch((error_: unknown) => error_); diff --git a/packages/client/test/ext/events/push.test.ts b/packages/client/test/ext/events/push.test.ts new file mode 100644 index 0000000000..27a5fbf6a3 --- /dev/null +++ b/packages/client/test/ext/events/push.test.ts @@ -0,0 +1,560 @@ +import type { TransportSendOptions } from '@modelcontextprotocol/core-internal'; +import { ProtocolError, SdkError, SdkErrorCode, SUBSCRIPTION_ID_META_KEY } from '@modelcontextprotocol/core-internal'; +import type { MockInstance } from 'vitest'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; + +import type { EventSubscription, SubscribeOptions } from '../../../src/ext/events/index'; +import { EventsError, NoCompatibleDeliveryModeError } from '../../../src/ext/events/index'; +import type { Call, Handler } from './scripted'; +import { callsTo, connectEvents, descriptor, listing, occurrence } from './scripted'; + +const subscriptions: EventSubscription[] = []; + +beforeEach(() => { + vi.useFakeTimers(); + vi.spyOn(Math, 'random').mockReturnValue(0.5); +}); + +afterEach(async () => { + await Promise.all(subscriptions.splice(0).map(subscription => subscription.cancel())); + vi.useRealTimers(); + vi.restoreAllMocks(); +}); + +/** Lets every in-flight request and its response settle without moving the clock. */ +const settle = () => vi.advanceTimersByTimeAsync(0); + +/** The eventId of the loop's next event, `undefined` when the loop is done. */ +async function nextEventId(iterator: AsyncIterator<{ eventId: string }>): Promise { + const result = await iterator.next(); + return result.done ? undefined : result.value.eventId; +} + +const tick = descriptor('tick', { delivery: ['push'] }); +const schemaChanged = { code: -32_026, message: 'Unsupported', data: { feature: 'payloadSchema', reason: 'schema_changed' } }; + +/** One `events/stream` the scripted server holds open: the test sends its frames and ends it. */ +interface ServerStream { + call: Call; + frame(method: string, params?: Record): Promise; + active(params?: Record): Promise; + /** The empty `StreamEventsResult`. */ + end(): Promise; + /** A JSON-RPC error response. */ + fail(error: { code: number; message: string; data?: Record }): Promise; +} + +async function pushWith(list: Handler = listing(tick)) { + const scripted = await connectEvents({ 'events/list': list, 'events/stream': () => new Promise(() => {}) }); + const { events, calls, send } = scripted; + const serverStream = (call: Call): ServerStream => { + const meta = { [SUBSCRIPTION_ID_META_KEY]: call.id }; + const frame = (method: string, params: Record = {}) => + send({ jsonrpc: '2.0', method, params: { ...params, _meta: { ...(params['_meta'] as object | undefined), ...meta } } }); + return { + call, + frame, + active: params => frame('notifications/events/active', { cursor: null, truncated: false, heartbeatMs: 30_000, ...params }), + end: () => send({ jsonrpc: '2.0', id: call.id, result: { resultType: 'complete', _meta: meta } }), + fail: error => send({ jsonrpc: '2.0', id: call.id, error }) + }; + }; + const streams = () => callsTo(calls, 'events/stream').map(call => serverStream(call)); + const last = () => streams().at(-1)!; + return { + ...scripted, + streams, + last, + lists: () => callsTo(calls, 'events/list'), + /** Subscribes, answering the first stream with `first` (default: `active`). */ + subscribe: async (options: Partial = {}, first: (stream: ServerStream) => Promise = s => s.active()) => { + const subscribing = events.subscribe({ name: 'tick', delivery: 'push', ...options }); + await settle(); + await first(last()); + const subscription = await subscribing; + subscriptions.push(subscription); + await settle(); + return subscription; + } + }; +} + +/** Ends the request stream of `id` the way a dropped HTTP response stream does. */ +function endRequestStream(send: MockInstance, id: Call['id']): void { + const call = send.mock.calls.find(([message]) => (message as { id?: unknown }).id === id)!; + (call[1] as TransportSendOptions).onRequestStreamEnd!(); +} + +describe('push delivery', () => { + it('opens events/stream with the subscription, its Mcp-Param headers and maxAgeMs, and no heartbeatMs', async () => { + const annotated = descriptor('tick', { + delivery: ['poll', 'push'], + inputSchema: { type: 'object', properties: { region: { type: 'string', 'x-mcp-header': 'Region' } } } + }); + const { last, streams, subscribe } = await pushWith(listing(annotated)); + const sub = await subscribe({ delivery: undefined, arguments: { region: 'us-west1' }, cursor: 'c0', maxAgeMs: 300_000 }, s => + s.active({ cursor: 'c1' }) + ); + + expect(sub.deliveryMode).toBe('push'); + expect(streams()[0]!.call.params).toEqual({ + name: 'tick', + arguments: { region: 'us-west1' }, + cursor: 'c0', + maxAgeMs: 300_000, + _meta: expect.any(Object) + }); + expect(streams()[0]!.call.headers).toEqual({ 'Mcp-Param-Region': 'us-west1' }); + + await last().end(); + await vi.advanceTimersByTimeAsync(500); + expect(streams()).toHaveLength(2); + expect(last().call.params).toEqual({ name: 'tick', arguments: { region: 'us-west1' }, cursor: 'c1', _meta: expect.any(Object) }); + expect(last().call.headers).toEqual({ 'Mcp-Param-Region': 'us-west1' }); + }); + + it('delivers each eventId once, moves the cursor past events the loop is done with, and reports truncated through onGap', async () => { + const onGap = vi.fn(); + const { last, subscribe } = await pushWith(); + const sub = await subscribe({ cursor: 'c0', onGap }, s => s.active({ cursor: 'c5', truncated: true })); + expect(onGap).toHaveBeenCalledExactlyOnceWith('c5'); + expect(sub.cursor).toBe('c5'); + + await last().frame('notifications/events/event', { ...occurrence('e1'), cursor: 'c6' }); + await last().frame('notifications/events/error', { error: { code: -32_603, message: 'UpstreamError' } }); + await last().frame('notifications/events/event', { ...occurrence('e1'), cursor: 'c6' }); + await last().frame('notifications/events/event', { ...occurrence('e2'), cursor: 'c7' }); + await last().active({ cursor: 'c9', truncated: true }); + expect(onGap).toHaveBeenLastCalledWith('c9'); + + const iterator = sub[Symbol.asyncIterator](); + expect(sub.cursor).toBe('c5'); + expect(await nextEventId(iterator)).toBe('e1'); + expect(await nextEventId(iterator)).toBe('e2'); + expect(sub.cursor).toBe('c6'); + let settled = false; + void iterator.next().then(() => (settled = true)); + await settle(); + expect(settled).toBe(false); + expect(sub.cursor).toBe('c9'); + }); + + it('yields events without the stream subscription id in _meta, keeping the author _meta', async () => { + const { last, subscribe } = await pushWith(); + const sub = await subscribe(); + await last().frame('notifications/events/event', { ...occurrence('e1'), cursor: 'c1', _meta: { 'com.example/trace': 't1' } }); + await last().frame('notifications/events/event', { ...occurrence('e2'), cursor: 'c2' }); + + const iterator = sub[Symbol.asyncIterator](); + const first = await iterator.next(); + const second = await iterator.next(); + expect(first.value).toEqual({ ...occurrence('e1'), cursor: 'c1', _meta: { 'com.example/trace': 't1' } }); + expect(second.value).toEqual({ ...occurrence('e2'), cursor: 'c2' }); + expect(second.value).not.toHaveProperty('_meta'); + }); + + it('reports a malformed frame and a throwing onGap to onerror, and keeps delivering', async () => { + const failure = new Error('onGap failed'); + const { client, last, subscribe } = await pushWith(); + const errors: Error[] = []; + client.onerror = error => void errors.push(error); + const sub = await subscribe( + { + cursor: 'c0', + onGap: () => { + throw failure; + } + }, + s => s.active({ cursor: 'c1', truncated: true }) + ); + + await last().frame('notifications/events/event', { name: 'tick', cursor: 'c2' }); + await last().frame('notifications/events/event', { ...occurrence('e1'), cursor: 'c3' }); + expect(errors).toEqual([failure, expect.objectContaining({ message: expect.stringContaining('notifications/events/event') })]); + expect(await nextEventId(sub[Symbol.asyncIterator]())).toBe('e1'); + expect(sub.cursor).toBe('c1'); + }); + + it('advances the cursor on heartbeats', async () => { + const { last, subscribe } = await pushWith(); + const sub = await subscribe({}, s => s.active({ cursor: 'c1' })); + expect(sub.cursor).toBe('c1'); + + await last().frame('notifications/events/heartbeat', { cursor: 'c9' }); + expect(sub.cursor).toBe('c9'); + }); + + it('reconnects with the last cursor after 3 × the granted heartbeat', async () => { + const { notifications, last, streams, subscribe } = await pushWith(); + await subscribe({}, s => s.active({ cursor: 'c1', heartbeatMs: 5000 })); + + await vi.advanceTimersByTimeAsync(15_499); + expect(streams()).toHaveLength(1); + expect(notifications).toContainEqual({ + method: 'notifications/cancelled', + params: expect.objectContaining({ requestId: streams()[0]!.call.id }) + }); + await vi.advanceTimersByTimeAsync(1); + expect(streams()).toHaveLength(2); + expect(last().call.params['cursor']).toBe('c1'); + }); + + it('counts the silence from the last message, with the grant of the last active', async () => { + const { last, streams, subscribe } = await pushWith(); + await subscribe({}, s => s.active({ cursor: 'c1', heartbeatMs: 5000 })); + + await vi.advanceTimersByTimeAsync(10_000); + await last().frame('notifications/events/heartbeat', { cursor: 'c2' }); + await vi.advanceTimersByTimeAsync(10_000); + await last().active({ cursor: 'c3', truncated: true, heartbeatMs: 10_000 }); + await vi.advanceTimersByTimeAsync(29_999); + expect(streams()).toHaveLength(1); + await vi.advanceTimersByTimeAsync(501); + expect(streams()).toHaveLength(2); + expect(last().call.params['cursor']).toBe('c3'); + }); + + it('waits a jittered delay before reconnecting', async () => { + const { client, last, streams, subscribe } = await pushWith(); + const send = vi.spyOn(client.transport!, 'send'); + await subscribe({}, s => s.active({ cursor: 'c1' })); + + endRequestStream(send, last().call.id); + await vi.advanceTimersByTimeAsync(499); + expect(streams()).toHaveLength(1); + await vi.advanceTimersByTimeAsync(1); + expect(streams()).toHaveLength(2); + expect(last().call.params['cursor']).toBe('c1'); + }); + + it('doubles the reconnect delay up to 30 s until a stream is active again', async () => { + const { last, streams, subscribe } = await pushWith(); + const sub = await subscribe({}, s => s.active({ cursor: 'c1' })); + await last().end(); + + // random() is 0.5: half of min(30 s, 1 s × 2^attempt). + for (const delay of [500, 1000, 2000, 4000, 8000, 15_000, 15_000]) { + const before = streams().length; + await vi.advanceTimersByTimeAsync(delay - 1); + expect(streams()).toHaveLength(before); + await vi.advanceTimersByTimeAsync(1); + expect(streams()).toHaveLength(before + 1); + expect(last().call.params['cursor']).toBe('c1'); + await last().end(); + } + await vi.advanceTimersByTimeAsync(15_000); + await last().active({ cursor: 'c2' }); + await last().end(); + await vi.advanceTimersByTimeAsync(500); + expect(last().call.params['cursor']).toBe('c2'); + expect(sub.cursor).toBe('c2'); + }); + + it('reconnects with the last cursor after an error that is not an Events kind', async () => { + const { last, streams, subscribe } = await pushWith(); + const sub = await subscribe({}, s => s.active({ cursor: 'c1' })); + + await last().fail({ code: -32_603, message: 'Internal error' }); + await vi.advanceTimersByTimeAsync(500); + expect(streams()).toHaveLength(2); + expect(last().call.params['cursor']).toBe('c1'); + await last().active({ cursor: 'c2' }); + await last().frame('notifications/events/event', { ...occurrence('e1'), cursor: 'c3' }); + expect(await nextEventId(sub[Symbol.asyncIterator]())).toBe('e1'); + }); + + it('fails the iterator on terminated forbidden', async () => { + const { last, streams, subscribe } = await pushWith(); + const sub = await subscribe(); + await last().frame('notifications/events/event', { ...occurrence('e1'), cursor: 'c1' }); + await last().frame('notifications/events/terminated', { + error: { code: -32_024, message: 'Forbidden', data: { reason: 'Access revoked' } } + }); + await last().end(); + + const iterator = sub[Symbol.asyncIterator](); + expect(await nextEventId(iterator)).toBe('e1'); + const error = await iterator.next().catch((error_: unknown) => error_); + expect(error).toBeInstanceOf(EventsError); + expect(error).toMatchObject({ kind: 'forbidden', data: { reason: 'Access revoked' } }); + expect(await iterator.next()).toEqual({ done: true, value: undefined }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(60_000); + expect(streams()).toHaveLength(1); + }); + + it('fails the iterator when a reopen is refused with an Events kind other than notFound or a schema change', async () => { + for (const refusal of [ + { code: -32_024, message: 'Forbidden' }, + { code: -32_602, message: 'Invalid arguments' }, + { code: -32_025, message: 'Too many subscriptions', data: { limit: 'subscriptions' } }, + { code: -32_026, message: 'Unsupported', data: { feature: 'deliveryMode', value: 'push' } }, + { code: -32_027, message: 'Callback endpoint error', data: { reason: 'timeout' } } + ]) { + const { lists, last, streams, subscribe } = await pushWith(); + const sub = await subscribe({}, s => s.active({ cursor: 'c1' })); + await last().end(); + await vi.advanceTimersByTimeAsync(500); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + + await last().fail(refusal); + const error = await pending; + expect(error).toBeInstanceOf(EventsError); + expect(error).toMatchObject({ code: refusal.code }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(60_000); + expect(streams()).toHaveLength(2); + expect(lists()).toHaveLength(1); + } + }); + + it('reconnects after schema_changed when the event is still listed', async () => { + const onGap = vi.fn(); + const { lists, last, streams, subscribe } = await pushWith(); + const sub = await subscribe({ onGap }, s => s.active({ cursor: 'c1' })); + + await last().frame('notifications/events/terminated', { error: schemaChanged }); + await last().end(); + await settle(); + expect(lists()).toHaveLength(2); + await vi.advanceTimersByTimeAsync(500); + expect(streams()).toHaveLength(2); + expect(last().call.params['cursor']).toBe('c1'); + + // This server still accepts the last cursor after the change: no reset, no gap. + await last().active({ cursor: 'c1' }); + await last().frame('notifications/events/event', { ...occurrence('e1'), cursor: 'c2' }); + expect(await nextEventId(sub[Symbol.asyncIterator]())).toBe('e1'); + expect(onGap).not.toHaveBeenCalled(); + }); + + it('starts again from now when the server keeps refusing the last cursor after a schema change', async () => { + const onGap = vi.fn(); + const { lists, last, streams, subscribe } = await pushWith(); + const sub = await subscribe({ onGap }, s => s.active({ cursor: 'c1' })); + + await last().frame('notifications/events/terminated', { error: schemaChanged }); + await last().end(); + await vi.advanceTimersByTimeAsync(500); + await last().fail(schemaChanged); + await vi.advanceTimersByTimeAsync(1000); + + expect(streams().map(stream => stream.call.params['cursor'])).toEqual([null, 'c1', null]); + expect(lists()).toHaveLength(3); + await last().active({ cursor: 'v2:0' }); + expect(onGap).toHaveBeenCalledExactlyOnceWith('v2:0'); + expect(sub.cursor).toBe('v2:0'); + }); + + it('reopens after notFound while the event is listed, and fails once it is not', async () => { + const listed = [[tick], [tick], []]; + const { lists, last, streams, subscribe } = await pushWith(() => ({ events: listed.shift() ?? [] })); + const sub = await subscribe({}, s => s.active({ cursor: 'c1' })); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + const notFound = { code: -32_023, message: 'Not found', data: { kind: 'event' } }; + + await last().frame('notifications/events/terminated', { error: notFound }); + await last().end(); + await vi.advanceTimersByTimeAsync(500); + expect(streams()).toHaveLength(2); + expect(last().call.params['cursor']).toBe('c1'); + + await last().fail(notFound); + const error = await pending; + expect(error).toBeInstanceOf(EventsError); + expect(error).toMatchObject({ kind: 'notFound', data: { kind: 'event' } }); + expect(lists()).toHaveLength(3); + expect(vi.getTimerCount()).toBe(0); + }); + + it('re-lists once after -32020 and reopens with fresh Mcp-Param headers, failing on a second mismatch', async () => { + const annotated = descriptor('tick', { + delivery: ['push'], + inputSchema: { type: 'object', properties: { region: { type: 'string', 'x-mcp-header': 'Region' } } } + }); + // The first listing predates the annotation, so the first stream goes out without the header. + const listed = [tick, annotated]; + const { lists, last, streams, subscribe } = await pushWith(() => ({ events: [listed.length > 1 ? listed.shift()! : listed[0]!] })); + const mismatch = { code: -32_020, message: 'Mcp-Param-Region header mismatch' }; + const sub = await subscribe({ arguments: { region: 'us-west1' } }, async first => { + await first.fail(mismatch); + await vi.advanceTimersByTimeAsync(500); + await last().active({ cursor: 'c1' }); + }); + + expect(lists()).toHaveLength(2); + expect(streams().map(stream => stream.call.headers['Mcp-Param-Region'])).toEqual([undefined, 'us-west1']); + + // A mismatch after a stream was active again re-lists again; the next one in a row fails the loop. + await last().end(); + await vi.advanceTimersByTimeAsync(500); + await last().fail(mismatch); + await vi.advanceTimersByTimeAsync(1000); + expect(lists()).toHaveLength(3); + expect(streams()).toHaveLength(4); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + await last().fail(mismatch); + const error = await pending; + expect(error).toBeInstanceOf(ProtocolError); + expect(error).toMatchObject({ code: -32_020 }); + expect(vi.getTimerCount()).toBe(0); + }); + + it('rejects subscribe() when the first stream is refused, leaving nothing running', async () => { + const refusals = [ + { code: -32_023, message: 'Not found', data: { kind: 'event' } }, + { code: -32_602, message: 'Invalid arguments' }, + { code: -32_024, message: 'Forbidden' }, + { code: -32_025, message: 'Too many subscriptions', data: { limit: 'subscriptions' } }, + { code: -32_026, message: 'Unsupported', data: { feature: 'deliveryMode', value: 'push' } }, + // Without a cursor there is no stale one to drop, so a schema change refuses too. + schemaChanged + ]; + for (const refusal of refusals) { + const { events, lists, last, streams } = await pushWith(); + const subscribing = events.subscribe({ name: 'tick', delivery: 'push' }).catch((error_: unknown) => error_); + await settle(); + await last().fail(refusal); + + const error = await subscribing; + expect(error).toBeInstanceOf(EventsError); + expect(error).toMatchObject({ code: refusal.code }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(120_000); + expect(streams()).toHaveLength(1); + expect(lists()).toHaveLength(1); + } + }); + + it('rejects subscribe() when the first stream mismatches Mcp-Param headers again after a re-list', async () => { + const { events, lists, last, streams } = await pushWith(); + const mismatch = { code: -32_020, message: 'Mcp-Param-Region header mismatch' }; + const subscribing = events.subscribe({ name: 'tick', delivery: 'push' }).catch((error_: unknown) => error_); + await settle(); + await last().fail(mismatch); + await vi.advanceTimersByTimeAsync(500); + await last().fail(mismatch); + + const error = await subscribing; + expect(error).toBeInstanceOf(ProtocolError); + expect(error).toMatchObject({ code: -32_020 }); + expect(streams()).toHaveLength(2); + expect(lists()).toHaveLength(2); + expect(vi.getTimerCount()).toBe(0); + }); + + it('resolves subscribe() after a transient first-stream failure and delivers after the reconnect', async () => { + const { last, streams, subscribe } = await pushWith(); + const sub = await subscribe({ cursor: 'c0' }, first => first.fail({ code: -32_603, message: 'Internal error' })); + expect(streams()).toHaveLength(1); + expect(sub.cursor).toBe('c0'); + + await vi.advanceTimersByTimeAsync(500); + expect(streams()).toHaveLength(2); + expect(last().call.params['cursor']).toBe('c0'); + await last().active({ cursor: 'c1' }); + await last().frame('notifications/events/event', { ...occurrence('e1'), cursor: 'c2' }); + expect(await nextEventId(sub[Symbol.asyncIterator]())).toBe('e1'); + }); + + it('drops a stale cursor that the first stream refuses for a schema change, and starts from now', async () => { + const onGap = vi.fn(); + const { lists, last, streams, subscribe } = await pushWith(); + const sub = await subscribe({ cursor: 'stale', onGap }, async first => { + await first.fail(schemaChanged); + await vi.advanceTimersByTimeAsync(500); + await last().active({ cursor: 'v2:0' }); + }); + + expect(streams().map(stream => stream.call.params['cursor'])).toEqual(['stale', null]); + expect(lists()).toHaveLength(2); + expect(onGap).toHaveBeenCalledExactlyOnceWith('v2:0'); + expect(sub.cursor).toBe('v2:0'); + }); + + it('rejects subscribe() after a schema change refuses its cursor when the type is gone or no longer pushed', async () => { + const staleCursorAgainst = async (relisted: ReturnType[]) => { + const listed = [[tick], relisted]; + const { events, last, streams } = await pushWith(() => ({ events: listed.shift() ?? relisted })); + const subscribing = events.subscribe({ name: 'tick', delivery: 'push', cursor: 'stale' }).catch((error_: unknown) => error_); + await settle(); + await last().fail(schemaChanged); + return { error: await subscribing, streams: streams().length, timers: vi.getTimerCount() }; + }; + + const gone = await staleCursorAgainst([]); + expect(gone.error).toBeInstanceOf(EventsError); + expect(gone).toMatchObject({ error: { kind: 'notFound', data: { kind: 'event' } }, streams: 1, timers: 0 }); + + const pollOnly = await staleCursorAgainst([descriptor('tick', { delivery: ['poll'] })]); + expect(pollOnly.error).toBeInstanceOf(NoCompatibleDeliveryModeError); + expect(pollOnly).toMatchObject({ error: { eventName: 'tick', offered: ['poll'], usable: ['push'] }, streams: 1, timers: 0 }); + }); + + it('rejects subscribe() with ConnectionClosed when the client closes before the first active', async () => { + const { client, events, streams } = await pushWith(); + const subscribing = events.subscribe({ name: 'tick', delivery: 'push' }).catch((error_: unknown) => error_); + await settle(); + expect(streams()).toHaveLength(1); + + await client.close(); + const error = await subscribing; + expect(error).toBeInstanceOf(SdkError); + expect(error).toMatchObject({ code: SdkErrorCode.ConnectionClosed }); + expect(vi.getTimerCount()).toBe(0); + }); + + it('ends the loop with ConnectionClosed when the client closes', async () => { + const { client, streams, subscribe } = await pushWith(); + const sub = await subscribe({}, s => s.active({ heartbeatMs: 5000 })); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + + await client.close(); + const error = await pending; + expect(error).toBeInstanceOf(SdkError); + expect(error).toMatchObject({ code: SdkErrorCode.ConnectionClosed }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(60_000); + expect(streams()).toHaveLength(1); + }); + + it('ends the loop with ConnectionClosed when the client reconnects without closing', async () => { + const { reconnect, streams, subscribe } = await pushWith(); + const sub = await subscribe({}, s => s.active({ cursor: 'c1', heartbeatMs: 5000 })); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + + await reconnect(); + const error = await pending; + expect(error).toBeInstanceOf(SdkError); + expect(error).toMatchObject({ code: SdkErrorCode.ConnectionClosed }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(60_000); + expect(streams()).toHaveLength(1); + }); + + it('sends cancellation on cancel()', async () => { + const { notifications, streams, subscribe } = await pushWith(); + const sub = await subscribe({}, s => s.active({ heartbeatMs: 5000 })); + const pending = sub[Symbol.asyncIterator]().next(); + + await sub.cancel(); + expect(notifications).toContainEqual({ + method: 'notifications/cancelled', + params: expect.objectContaining({ requestId: streams()[0]!.call.id }) + }); + expect(await pending).toEqual({ done: true, value: undefined }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(60_000); + expect(streams()).toHaveLength(1); + }); +}); diff --git a/packages/client/test/ext/events/scripted.ts b/packages/client/test/ext/events/scripted.ts index de28b6aacd..87700c6988 100644 --- a/packages/client/test/ext/events/scripted.ts +++ b/packages/client/test/ext/events/scripted.ts @@ -1,6 +1,6 @@ import type { EventDescriptor, EventOccurrence } from '@modelcontextprotocol/core/ext/events'; import { EVENTS_EXTENSION_ID } from '@modelcontextprotocol/core/ext/events'; -import type { JSONRPCRequest, RequestId, ServerCapabilities, Transport } from '@modelcontextprotocol/core-internal'; +import type { JSONRPCMessage, JSONRPCRequest, RequestId, ServerCapabilities, Transport } from '@modelcontextprotocol/core-internal'; import { InMemoryTransport } from '@modelcontextprotocol/core-internal'; import type { ClientOptions } from '../../../src/client/client'; @@ -49,26 +49,27 @@ export interface ScriptedOptions { beforeConnect?: (client: Client) => void; } +/** A scripted client, with the scripted server's side of its connection. */ +export interface Scripted { + client: Client; + calls: Call[]; + notifications: Notification[]; + /** Sends a message from the server on the current connection. */ + send(message: JSONRPCMessage): Promise; + /** Connects the client again over a fresh pair to the same scripted server, without closing it first. */ + reconnect(): Promise; +} + /** * A client connected over an in-memory pair to a scripted server: the handshake declares * `capabilities`, every other request goes to `handlers` and is recorded in `calls`. On * 2026-07-28 results carry `resultType: "complete"`, as a conforming server's do. */ -export async function scriptedClient( - handlers: Record, - options: ScriptedOptions = {} -): Promise<{ client: Client; calls: Call[]; notifications: Notification[] }> { +export async function scriptedClient(handlers: Record, options: ScriptedOptions = {}): Promise { const { capabilities = EVENTS_CAPABILITIES, revision = MODERN } = options; - const [clientTx, serverTx] = InMemoryTransport.createLinkedPair(); const calls: Call[] = []; const notifications: Notification[] = []; const headersById = new Map>(); - const transport: Transport = clientTx; - const send = transport.send.bind(transport); - transport.send = (message, sendOptions) => { - if ('id' in message && 'method' in message) headersById.set(message.id, { ...sendOptions?.headers }); - return send(message, sendOptions); - }; const answer = async (request: JSONRPCRequest): Promise> => { if (revision === MODERN && request.method === 'server/discover') { return { @@ -91,46 +92,65 @@ export async function scriptedClient( if (handler === undefined) throw new RpcError(-32_601, `Method not found: ${request.method}`); return handler(call.params, call); }; - serverTx.onmessage = message => { - const request = message as JSONRPCRequest; - if (request.id === undefined) { - notifications.push({ method: request.method, params: (request.params ?? {}) as Record }); - return; - } - void answer(request).then( - result => - serverTx.send({ - jsonrpc: '2.0', - id: request.id, - result: revision === MODERN ? { resultType: 'complete', ...result } : result - }), - (error: unknown) => - serverTx.send({ - jsonrpc: '2.0', - id: request.id, - error: { - code: error instanceof RpcError ? error.code : -32_603, - message: error instanceof Error ? error.message : String(error), - ...(error instanceof RpcError && error.data !== undefined && { data: error.data }) - } - }) - ); + let serverTx: Transport | undefined; + // A fresh in-memory pair to the scripted server; its server side becomes the one `send` uses. + const link = async (): Promise => { + const [clientTx, server] = InMemoryTransport.createLinkedPair(); + serverTx = server; + const transport: Transport = clientTx; + const send = transport.send.bind(transport); + transport.send = (message, sendOptions) => { + if ('id' in message && 'method' in message) headersById.set(message.id, { ...sendOptions?.headers }); + return send(message, sendOptions); + }; + server.onmessage = message => { + const request = message as JSONRPCRequest; + if (request.id === undefined) { + notifications.push({ method: request.method, params: (request.params ?? {}) as Record }); + return; + } + void answer(request).then( + result => + server.send({ + jsonrpc: '2.0', + id: request.id, + result: revision === MODERN ? { resultType: 'complete', ...result } : result + }), + (error: unknown) => + server.send({ + jsonrpc: '2.0', + id: request.id, + error: { + code: error instanceof RpcError ? error.code : -32_603, + message: error instanceof Error ? error.message : String(error), + ...(error instanceof RpcError && error.data !== undefined && { data: error.data }) + } + }) + ); + }; + await server.start(); + return transport; }; - await serverTx.start(); const client = new Client( { name: 'events-test-client', version: '1.0.0' }, revision === MODERN ? { versionNegotiation: { mode: { pin: MODERN } }, ...options.clientOptions } : options.clientOptions ); options.beforeConnect?.(client); - await client.connect(clientTx); - return { client, calls, notifications }; + await client.connect(await link()); + return { + client, + calls, + notifications, + send: message => serverTx!.send(message), + reconnect: async () => client.connect(await link()) + }; } /** An `EventsClientExtension` attached to a scripted client before it connects. */ export async function connectEvents( handlers: Record, options: ScriptedOptions & { events?: EventsClientOptions } = {} -): Promise<{ events: EventsClientExtension; client: Client; calls: Call[]; notifications: Notification[] }> { +): Promise { const events = new EventsClientExtension(options.events); const connected = await scriptedClient(handlers, { ...options, beforeConnect: client => events.attach(client) }); return { events, ...connected }; diff --git a/packages/client/test/ext/events/subscription.test.ts b/packages/client/test/ext/events/subscription.test.ts new file mode 100644 index 0000000000..5c889b463f --- /dev/null +++ b/packages/client/test/ext/events/subscription.test.ts @@ -0,0 +1,51 @@ +import { ProtocolError, SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal'; +import { describe, expect, it, vi } from 'vitest'; + +import { EventsError } from '../../../src/ext/events/index'; +import type { EventsConnection } from '../../../src/ext/events/request'; +import { recoveryFor, refusesSubscription, reportGap } from '../../../src/ext/events/subscription'; + +describe('the recovery rules every delivery mode shares', () => { + it.each([ + ['notFound', 'relist', true, new EventsError('notFound', 'Not found', { kind: 'event' })], + [ + 'unsupported, schema changed', + 'relist', + true, + new EventsError('unsupported', 'Unsupported', { feature: 'payloadSchema', reason: 'schema_changed' }) + ], + ['unsupported, other', 'fail', true, new EventsError('unsupported', 'Unsupported', { feature: 'deliveryMode', value: 'push' })], + ['forbidden', 'fail', true, new EventsError('forbidden', 'Forbidden')], + ['invalidParams', 'fail', true, new EventsError('invalidParams', 'Invalid arguments')], + ['resourceExhausted', 'fail', true, new EventsError('resourceExhausted', 'Too many', { limit: 'subscriptions' })], + ['callbackEndpointError', 'fail', true, new EventsError('callbackEndpointError', 'Unreachable', { reason: 'timeout' })], + ['-32020', 'mismatch', true, new ProtocolError(-32_020, 'Mcp-Param-Region header mismatch')], + ['another JSON-RPC error', 'retry', false, new ProtocolError(-32_603, 'Internal error')], + ['an SDK error', 'retry', true, new SdkError(SdkErrorCode.RequestTimeout, 'Request timed out')], + ['a transport error', 'retry', false, new Error('fetch failed')] + ] as const)('%s → %s once subscribed; refuses a first exchange: %s', (_name, recovery, refuses, error) => { + expect(recoveryFor(error)).toBe(recovery); + expect(refusesSubscription(error)).toBe(refuses); + }); + + it('reports a gap through onGap, and a throwing onGap to the client onerror', () => { + const connection = { report: vi.fn() } as unknown as EventsConnection; + const onGap = vi.fn(); + reportGap({ name: 'tick', onGap }, connection, 'c1'); + expect(onGap).toHaveBeenCalledExactlyOnceWith('c1'); + expect(connection.report).not.toHaveBeenCalled(); + + const failure = new Error('onGap failed'); + reportGap( + { + name: 'tick', + onGap: () => { + throw failure; + } + }, + connection, + null + ); + expect(connection.report).toHaveBeenCalledExactlyOnceWith(failure); + }); +}); From 4641d0d189c5d22ad13e7d8164c4e7415e1c94c5 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 16:32:02 +0200 Subject: [PATCH 19/37] fix(client): never re-arm the push dead-stream timer after the stream ended --- packages/client/src/ext/events/push.ts | 4 +-- packages/client/test/ext/events/push.test.ts | 35 ++++++++++++++++++++ 2 files changed, 37 insertions(+), 2 deletions(-) diff --git a/packages/client/src/ext/events/push.ts b/packages/client/src/ext/events/push.ts index 7855959223..7f5ba3f9b9 100644 --- a/packages/client/src/ext/events/push.ts +++ b/packages/client/src/ext/events/push.ts @@ -266,9 +266,9 @@ export class PushDriver implements Driver { this.#subscribed(); } - // From `active` on, every message restarts the countdown to declaring the stream dead and reconnecting. + // From `active` on, every message restarts the countdown to declaring the stream dead, unless a callback in the frame already ended it. #alive(end: (ending: Ending) => void): void { - if (this.#grantMs === undefined) return; + if (this.#grantMs === undefined || this.#end !== end) return; clearTimeout(this.#dead); this.#dead = setTimeout( () => { diff --git a/packages/client/test/ext/events/push.test.ts b/packages/client/test/ext/events/push.test.ts index 27a5fbf6a3..0d82c4f101 100644 --- a/packages/client/test/ext/events/push.test.ts +++ b/packages/client/test/ext/events/push.test.ts @@ -175,6 +175,41 @@ describe('push delivery', () => { expect(sub.cursor).toBe('c1'); }); + it('leaves no timer and no reopen when a callback cancels the subscription inside a frame', async () => { + // `trigger` sends frames on a subscription whose onGap (or client.onerror) calls cancel() synchronously. + const cancelledInside = async ( + via: 'onGap' | 'onerror', + trigger: (last: () => ServerStream) => Promise + ): Promise<{ timers: number; streams: number }> => { + const { client, last, streams, subscribe } = await pushWith(); + const subscribed: { sub?: EventSubscription } = {}; + const cancel = () => void subscribed.sub?.cancel(); + if (via === 'onerror') client.onerror = cancel; + subscribed.sub = await subscribe({ cursor: 'c0', ...(via === 'onGap' && { onGap: cancel }) }, s => + s.active({ cursor: 'c1', heartbeatMs: 5000 }) + ); + await trigger(last); + await settle(); + const timers = vi.getTimerCount(); + await vi.advanceTimersByTimeAsync(120_000); + return { timers, streams: streams().length }; + }; + + // The truncated `active` that opens a reconnected stream. + const reopened = await cancelledInside('onGap', async last => { + await last().end(); + await vi.advanceTimersByTimeAsync(500); + await last().active({ cursor: 'c2', truncated: true, heartbeatMs: 5000 }); + }); + const midStream = await cancelledInside('onGap', last => last().active({ cursor: 'c2', truncated: true, heartbeatMs: 5000 })); + const malformed = await cancelledInside('onerror', last => last().frame('notifications/events/event', { name: 'tick' })); + expect({ reopened, midStream, malformed }).toEqual({ + reopened: { timers: 0, streams: 2 }, + midStream: { timers: 0, streams: 1 }, + malformed: { timers: 0, streams: 1 } + }); + }); + it('advances the cursor on heartbeats', async () => { const { last, subscribe } = await pushWith(); const sub = await subscribe({}, s => s.active({ cursor: 'c1' })); From 23225ed2c59eeb5fe0deca696ac05b8b632b17ee Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 17:23:44 +0200 Subject: [PATCH 20/37] feat(client): Events webhook driver, receiver and shared driver recovery --- packages/client/src/ext/events/extension.ts | 53 +- packages/client/src/ext/events/poll.ts | 136 +--- packages/client/src/ext/events/push.ts | 160 +---- packages/client/src/ext/events/receiver.ts | 160 +++++ packages/client/src/ext/events/recovery.ts | 261 +++++++ packages/client/src/ext/events/request.ts | 2 +- .../client/src/ext/events/subscription.ts | 107 +-- packages/client/src/ext/events/webhook.ts | 282 ++++++++ .../client/test/ext/events/receiver.test.ts | 183 +++++ ...{subscription.test.ts => recovery.test.ts} | 2 +- packages/client/test/ext/events/scripted.ts | 29 +- .../client/test/ext/events/webhook.test.ts | 642 ++++++++++++++++++ 12 files changed, 1669 insertions(+), 348 deletions(-) create mode 100644 packages/client/src/ext/events/receiver.ts create mode 100644 packages/client/src/ext/events/recovery.ts create mode 100644 packages/client/src/ext/events/webhook.ts create mode 100644 packages/client/test/ext/events/receiver.test.ts rename packages/client/test/ext/events/{subscription.test.ts => recovery.test.ts} (98%) create mode 100644 packages/client/test/ext/events/webhook.test.ts diff --git a/packages/client/src/ext/events/extension.ts b/packages/client/src/ext/events/extension.ts index 5b529b1006..28ec54f6ff 100644 --- a/packages/client/src/ext/events/extension.ts +++ b/packages/client/src/ext/events/extension.ts @@ -7,9 +7,11 @@ import type { Client } from '../../client/client'; import { NoCompatibleDeliveryModeError } from './errors'; import { PollDriver } from './poll'; import { PushDriver } from './push'; +import { WebhookReceiver } from './receiver'; import { EventsConnection } from './request'; import type { Driver, DriverContext, EventSubscription, SubscribeOptions } from './subscription'; import { SubscriptionQueue } from './subscription'; +import { WebhookSubscriptions } from './webhook'; const DEFAULT_POLL_INTERVAL_FLOOR_MS = 1000; @@ -25,12 +27,20 @@ const PREFERENCE: readonly DeliveryMode[] = ['webhook', 'push', 'poll']; */ export interface EventsClientOptions { /** - * Webhook delivery: the callback URL the server POSTs events to, and - * optionally the source of each subscription's `whsec_` signing secret. - * With it set, a subscription prefers webhook where the event type offers it. + * Webhook delivery: the callback URL the server POSTs events to, where + * {@linkcode EventsClientExtension.createWebhookHandler} is mounted. Each + * server subscription signs with its own `whsec_` secret, random unless + * `secretProvider` supplies it; a value that is not a Standard Webhooks + * secret (`whsec_` and base64 of 24 to 64 bytes) makes `subscribe()` + * throw `TypeError`. With it set, a subscription prefers webhook where the + * event type offers it. */ webhook?: { url: string; secretProvider?: () => string }; - /** The shortest wait between two polls, whatever `nextPollMs` the server recommends. Default 1000. */ + /** + * The shortest wait between two polls, whatever `nextPollMs` the server + * recommends, and between two webhook refreshes, whatever the grant + * (a skewed clock cannot make them back to back). Default 1000. + */ pollIntervalFloorMs?: number; } @@ -74,6 +84,8 @@ export class EventsClientExtension { readonly id = EVENTS_EXTENSION_ID; readonly #options: EventsClientOptions; readonly #floorMs: number; + readonly #receiver = new WebhookReceiver(); + readonly #webhooks: WebhookSubscriptions | undefined; #connection: EventsConnection | undefined; /** @throws {TypeError} when `pollIntervalFloorMs` is not a positive finite number. */ @@ -84,6 +96,7 @@ export class EventsClientExtension { } this.#options = options; this.#floorMs = floorMs; + this.#webhooks = options.webhook === undefined ? undefined : new WebhookSubscriptions(options.webhook, this.#receiver, floorMs); } /** @@ -125,7 +138,8 @@ export class EventsClientExtension { * `events/list` (fetched again when it is not there), and resolves once * the first exchange with the server succeeds (for poll, the first * `events/poll` response; for push, the first - * `notifications/events/active`). A transient failure of that exchange (a + * `notifications/events/active`; for webhook, the `events/subscribe` + * response). A transient failure of that exchange (a * transport error, or a JSON-RPC error that is not an Events kind) does * not reject: delivery is retried in the background. A `cursor` the * server refuses because the event type's schema changed is dropped: the @@ -134,6 +148,14 @@ export class EventsClientExtension { * and retries once. Once subscribed, every mode recovers from errors as * {@linkcode EventSubscription} describes. * + * Webhook subscriptions with the same name and arguments are one server + * subscription. A later one joins the open one rather than sending + * `events/subscribe` (its `cursor` and `maxAgeMs` are not sent; `onGap` + * reports a `cursor` of its own that is not where the shared one is) and + * settles as that one's first exchange does. Each gets every event in its + * own loop, an end of the shared one ends them all, and + * `events/unsubscribe` goes out when the last of them is cancelled. + * * @throws {EventsError} when the server refuses the subscription: `notFound` for an event type it does not list or * no longer serves, `invalidParams` for arguments its `inputSchema` rejects, `forbidden`, or another kind. * @throws {NoCompatibleDeliveryModeError} when no delivery mode the event type offers is usable here, also when @@ -142,6 +164,7 @@ export class EventsClientExtension { * `ConnectionClosed` when the client closes before the first exchange answers, or another code when that * exchange fails in the SDK (for example a request timeout). * @throws {ProtocolError} `-32020` when the server rejects the `Mcp-Param` headers again after a re-list. + * @throws {TypeError} when `webhook.secretProvider` returns something that is not a Standard Webhooks secret. */ async subscribe>(options: SubscribeOptions): Promise> { const connection = this.#require('subscribe'); @@ -162,10 +185,28 @@ export class EventsClientExtension { return queue; } + /** + * The receiver for webhook delivery, a `(request: Request) => Promise` + * to mount at `webhook.url` in any fetch-style server; every handler it + * returns serves this instance's subscriptions. It verifies each POST's + * Standard Webhooks signature over the raw body, answers the server's + * verification challenge, delivers each `webhook-id` once, and routes + * events and `gap` and `terminated` bodies into their subscription. + * Answers: `405` to anything but POST, `413` to a body over 256 KiB, + * `400` to a missing header, a timestamp more than 5 minutes off or a + * malformed body, `401` to a bad signature, and `503` to a subscription + * id it does not route (yet), which the server retries. + */ + createWebhookHandler(): (request: Request) => Promise { + const receiver = this.#receiver; + return request => receiver.handle(request); + } + #driver(mode: DeliveryMode, context: DriverContext): Driver { if (mode === 'poll') return new PollDriver(context, this.#floorMs); if (mode === 'push') return new PushDriver(context); - throw new SdkError(SdkErrorCode.CapabilityNotSupported, `${mode} delivery is not available yet`); + // Webhook is selected only with the `webhook` option set. + return this.#webhooks!.driver(context); } #require(method: string): EventsConnection { diff --git a/packages/client/src/ext/events/poll.ts b/packages/client/src/ext/events/poll.ts index 531711a8fe..ffac652f19 100644 --- a/packages/client/src/ext/events/poll.ts +++ b/packages/client/src/ext/events/poll.ts @@ -1,147 +1,68 @@ import type { PollEventsResult } from '@modelcontextprotocol/core/ext/events'; import { EVENTS_POLL_METHOD, PollEventsResultSchema } from '@modelcontextprotocol/core/ext/events'; +import { DriverLoop } from './recovery'; import type { Driver, DriverContext } from './subscription'; -import { - closedError, - connectionClosed, - isSchemaChange, - MAX_TIMER_DELAY_MS, - recoveryFor, - refusesSubscription, - reportGap, - requireOffered, - stillOffered -} from './subscription'; const MAX_RETRY_DELAY_MS = 60_000; // Poll delivery (spec §6.3): one `events/poll` loop, again at once on `hasMore`, otherwise after `nextPollMs` but never sooner than the floor. export class PollDriver implements Driver { readonly #context: DriverContext; + readonly #loop: DriverLoop; readonly #floorMs: number; - readonly #abort = new AbortController(); - #cursor: string | null; - // Sent until a poll succeeds. - #maxAgeMs: number | undefined; #nextPollMs: number | undefined; - // A schema change has refused a poll since the last successful one. - #schemaChanged = false; - // The cursor was reset to now; the next successful poll reports the gap. - #reset = false; - // Set by the connection's close listener; ends the loop at once. - #closed = false; - #wake: (() => void) | undefined; - #running: Promise = Promise.resolve(); constructor(context: DriverContext, floorMs: number) { this.#context = context; + this.#loop = new DriverLoop(context, 'poll'); this.#floorMs = floorMs; - this.#cursor = context.subscription.cursor ?? null; - this.#maxAgeMs = context.subscription.maxAgeMs; } start(): Promise { - let settle!: { resolve(): void; reject(error: unknown): void }; - const first = new Promise((resolve, reject) => (settle = { resolve, reject })); - const removeCloseListener = this.#context.connection.onClose(() => { - this.#closed = true; - this.#wake?.(); - }); - this.#running = this.#run(settle.resolve) - .then(settle.resolve, (error: unknown) => { - settle.reject(error); - this.#context.queue.fail(error); - }) - .finally(removeCloseListener); - return first; + return this.#loop.start(() => this.#run()); } - async stop(): Promise { - this.#abort.abort(); - this.#wake?.(); - await this.#running; + stop(): Promise { + return this.#loop.stop(); } - // Calls `subscribed` after the first exchange; throws, ending the subscription, on a first-exchange refusal or a closed connection. - async #run(subscribed: () => void): Promise { - const { connection, queue, subscription } = this.#context; - let first = true; + // Polls until stopped; throws, ending the subscription, when a failure calls for it. + async #run(): Promise { + const loop = this.#loop; let failures = 0; - while (!this.#abort.signal.aborted) { - if (this.#closed) throw closedError(); + while (!loop.ended) { let result: PollEventsResult; try { result = await this.#poll(); } catch (error) { - if (this.#abort.signal.aborted) return; - const closed = connectionClosed(connection, error); - if (closed !== undefined) throw closed; - if (first && isSchemaChange(error) && this.#cursor !== null) { - await this.#restartFromNow(); - continue; - } - if (first && refusesSubscription(error)) throw error; - first = false; - subscribed(); - const recovery = recoveryFor(error); - // A -32020 here is the second: the request already re-listed once and retried with fresh headers. - const gone = - recovery === 'fail' || - recovery === 'mismatch' || - (recovery === 'relist' && (await stillOffered(connection, subscription.name, 'poll', this.#abort.signal)) === false); - if (gone) { - queue.fail(error); - return; - } - if (isSchemaChange(error)) this.#schemaChange(); - await this.#sleep(this.#retryDelay(failures++)); + if (loop.ended) return; + if ((await loop.recover(error)) === 'restarted') continue; + await loop.sleep(this.#retryDelay(failures++)); continue; } + if (loop.ended) return; failures = 0; this.#deliver(result); - first = false; - subscribed(); - if (result.hasMore !== true) await this.#sleep(Math.max(result.nextPollMs ?? this.#floorMs, this.#floorMs)); + loop.subscribed(); + if (result.hasMore !== true) await loop.sleep(Math.max(result.nextPollMs ?? this.#floorMs, this.#floorMs)); } } #poll(): Promise { const { name, arguments: args } = this.#context.subscription; + const loop = this.#loop; const mirror = { name, ...(args !== undefined && { arguments: args }) }; - const params = { ...mirror, cursor: this.#cursor, ...(this.#maxAgeMs !== undefined && { maxAgeMs: this.#maxAgeMs }) }; - return this.#context.connection.request(EVENTS_POLL_METHOD, params, PollEventsResultSchema, mirror, { signal: this.#abort.signal }); - } - - // The first poll's cursor was refused for a schema change (a stale one passed to subscribe()): re-list, then poll from now or throw why not. - async #restartFromNow(): Promise { - await requireOffered(this.#context.connection, this.#context.subscription.name, 'poll', this.#abort.signal); - this.#cursor = null; - this.#reset = true; - } - - // A second schema change in a row means the last cursor is refused (SEP: a stale schema epoch), so start again from now. - #schemaChange(): void { - if (this.#schemaChanged && this.#cursor !== null) { - this.#cursor = null; - this.#reset = true; - } - this.#schemaChanged = true; + const params = { ...mirror, cursor: loop.cursor, ...(loop.maxAgeMs !== undefined && { maxAgeMs: loop.maxAgeMs }) }; + return this.#context.connection.request(EVENTS_POLL_METHOD, params, PollEventsResultSchema, mirror, { signal: loop.signal }); } #deliver(result: PollEventsResult): void { - const { connection, queue, subscription } = this.#context; const cursor = result.cursor ?? null; - const reset = this.#reset; - this.#maxAgeMs = undefined; this.#nextPollMs = result.nextPollMs; - this.#schemaChanged = false; - this.#reset = false; - // A type without replay has no position to have skipped past (SEP: ignore `truncated`). - if (reset || (result.truncated === true && cursor !== null)) reportGap(subscription, connection, cursor); - for (const event of result.events) queue.push(event); - this.#cursor = cursor; - queue.setCursor(cursor); + this.#loop.succeeded(cursor, result.truncated === true); + for (const event of result.events) this.#context.queue.push(event); + this.#loop.setCursor(cursor); } // max(floor, nextPollMs), doubling per consecutive failure up to 60 s, never below that base. @@ -149,17 +70,4 @@ export class PollDriver implements Driver { const base = Math.max(this.#floorMs, this.#nextPollMs ?? this.#floorMs); return Math.max(base, Math.min(MAX_RETRY_DELAY_MS, base * 2 ** failures)); } - - #sleep(ms: number): Promise { - return new Promise(resolve => { - if (this.#abort.signal.aborted || this.#closed) return resolve(); - const wake = (): void => { - clearTimeout(timer); - this.#wake = undefined; - resolve(); - }; - const timer = setTimeout(wake, Math.min(ms, MAX_TIMER_DELAY_MS)); - this.#wake = wake; - }); - } } diff --git a/packages/client/src/ext/events/push.ts b/packages/client/src/ext/events/push.ts index 7f5ba3f9b9..8746d154c1 100644 --- a/packages/client/src/ext/events/push.ts +++ b/packages/client/src/ext/events/push.ts @@ -16,24 +16,12 @@ import type * as z from 'zod/v4'; import type { StreamEnd, StreamHandle } from '../../client/client'; import { clientInternals } from '../../client/client'; +import { DriverLoop, isHeaderMismatch, jitteredDelay, MAX_TIMER_DELAY_MS } from './recovery'; import { asEventsError } from './request'; import type { Driver, DriverContext } from './subscription'; -import { - closedError, - connectionClosed, - isSchemaChange, - MAX_TIMER_DELAY_MS, - recoveryFor, - refusesSubscription, - reportGap, - requireOffered, - stillOffered -} from './subscription'; // No message for this many granted heartbeat intervals, counted from `active`, means the stream is dead (SEP-3415 §Push). const DEAD_AFTER_HEARTBEATS = 3; -const RECONNECT_BASE_MS = 1000; -const RECONNECT_MAX_MS = 30_000; // How a stream ended: with the server's error (a `terminated` frame or an error response) or a failed send, or without an error. interface Ending { @@ -55,25 +43,11 @@ function withoutStreamId(event: EventOccurrence): EventOccurrence { // Push delivery (spec §6.3): one `events/stream` at a time, reopened from the last cursor after a jittered delay whenever it ends. export class PushDriver implements Driver { readonly #context: DriverContext; - // Aborts a re-list in flight on stop() or a closed connection. - readonly #abort = new AbortController(); - #cursor: string | null; - // Sent until a stream is active. - #maxAgeMs: number | undefined; - // Until the first `active`, or a transient failure of a stream before it. - #first = true; - #subscribed: () => void = () => {}; + readonly #loop: DriverLoop; // Reconnect delays taken since the last `active`. #attempt = 0; - // A schema change has refused the subscription since the last `active`. - #schemaChanged = false; // A -32020 has been re-listed for since the last `active`. #mismatched = false; - // The cursor was reset to now; the next `active` reports the gap. - #reset = false; - #stopped = false; - // Set by the connection's close listener, which ends the subscription at once. - #closed = false; // The stream last opened; a terminated one stays registered until its final result arrives. #handle: StreamHandle | undefined; // Ends the wait for the open stream. @@ -81,110 +55,55 @@ export class PushDriver implements Driver { // The open stream's heartbeat grant, from its last `active`. #grantMs: number | undefined; #dead: ReturnType | undefined; - #wake: (() => void) | undefined; - #running: Promise = Promise.resolve(); constructor(context: DriverContext) { this.#context = context; - this.#cursor = context.subscription.cursor ?? null; - this.#maxAgeMs = context.subscription.maxAgeMs; + this.#loop = new DriverLoop(context, 'push'); } start(): Promise { - let settle!: { resolve(): void; reject(error: unknown): void }; - const first = new Promise((resolve, reject) => (settle = { resolve, reject })); - const fail = (error: unknown): void => { - settle.reject(error); - this.#context.queue.fail(error); - }; - this.#subscribed = () => { - this.#first = false; - settle.resolve(); - }; - const removeCloseListener = this.#context.connection.onClose(() => { - this.#closed = true; - this.#interrupt(); - fail(closedError()); - }); - this.#running = this.#run().then(settle.resolve, fail).finally(removeCloseListener); - return first; + return this.#loop.start(() => this.#run(), { interrupt: () => this.#end?.({}) }); } - async stop(): Promise { - this.#stopped = true; - this.#interrupt(); - await this.#handle?.close(); - await this.#running; - } - - // Ends what the loop waits for: the open stream, a re-list or a reconnect delay. - #interrupt(): void { - this.#abort.abort(); - this.#wake?.(); - this.#end?.({}); + stop(): Promise { + return this.#loop.stop(async () => { + await this.#handle?.close(); + }); } // Reopens after every end until stopped; throws, ending the subscription, when an end calls for it. async #run(): Promise { - while (!this.#stopped && !this.#closed) { + const loop = this.#loop; + while (!loop.ended) { const { error } = await this.#open(); - if (this.#stopped || this.#closed) return; - if (error === undefined) this.#subscribed(); + if (loop.ended) return; + if (error === undefined) loop.subscribed(); else await this.#recover(error); - await this.#sleep(this.#reconnectDelay()); + await loop.sleep(jitteredDelay(this.#attempt++)); } } // After a stream ended with `error` (spec §6.3): throws when that ends the subscription, otherwise readies the reopen. async #recover(error: unknown): Promise { - const { connection, subscription } = this.#context; - const closed = connectionClosed(connection, error); - if (closed !== undefined) throw closed; - const recovery = recoveryFor(error); - if (recovery === 'mismatch') { - if (this.#mismatched) throw error; + // An `events/stream` is not sent through `request()`, so its first -32020 since the last `active` re-lists here. + if (isHeaderMismatch(error) && !this.#mismatched) { this.#mismatched = true; - await connection.list(undefined, { signal: this.#abort.signal }).catch(() => {}); - return; - } - if (this.#first) { - // A stale cursor passed to subscribe(): drop it and start from now, if the event type is still pushed. - if (isSchemaChange(error) && this.#cursor !== null) { - await requireOffered(connection, subscription.name, 'push', this.#abort.signal); - this.#restartFromNow(); - return; - } - if (refusesSubscription(error)) throw error; - this.#subscribed(); + await this.#context.connection.list(undefined, { signal: this.#loop.signal }).catch(() => {}); return; } - if (recovery === 'retry') return; - if (recovery === 'fail') throw error; - const offered = await stillOffered(connection, subscription.name, 'push', this.#abort.signal); - if (offered === false) throw error; - if (offered === true && isSchemaChange(error)) this.#schemaChange(); - } - - #restartFromNow(): void { - this.#cursor = null; - this.#reset = true; - } - - // A second schema change in a row means the last cursor is refused (SEP: a stale schema epoch), so start again from now. - #schemaChange(): void { - if (this.#schemaChanged && this.#cursor !== null) this.#restartFromNow(); - this.#schemaChanged = true; + await this.#loop.recover(error); } // Opens `events/stream` from the last cursor (no `heartbeatMs` suggestion) and resolves with how it ended. #open(): Promise { const { connection, subscription } = this.#context; const { name, arguments: args } = subscription; + const loop = this.#loop; const params = { name, ...(args !== undefined && { arguments: args }), - cursor: this.#cursor, - ...(this.#maxAgeMs !== undefined && { maxAgeMs: this.#maxAgeMs }) + cursor: loop.cursor, + ...(loop.maxAgeMs !== undefined && { maxAgeMs: loop.maxAgeMs }) }; const headers = connection.paramHeadersFor(name, args); // A terminated stream whose final result has not arrived. @@ -230,12 +149,12 @@ export class PushDriver implements Driver { const params = this.#parse(EventNotificationParamsSchema, notification); if (params === undefined) break; this.#context.queue.push(withoutStreamId(params)); - this.#setCursor(params.cursor ?? null); + this.#loop.setCursor(params.cursor ?? null); break; } case EVENTS_HEARTBEAT_NOTIFICATION: { const params = this.#parse(EventsHeartbeatNotificationParamsSchema, notification); - if (params !== undefined) this.#setCursor(params.cursor ?? null); + if (params !== undefined) this.#loop.setCursor(params.cursor ?? null); break; } case EVENTS_TERMINATED_NOTIFICATION: { @@ -251,19 +170,13 @@ export class PushDriver implements Driver { // Every `active` carries the heartbeat grant and the position delivery starts from; `truncated` reports a gap. #active(params: EventsActiveNotificationParams): void { - const { connection, subscription } = this.#context; const cursor = params.cursor ?? null; - const reset = this.#reset; this.#grantMs = params.heartbeatMs; this.#attempt = 0; - this.#schemaChanged = false; this.#mismatched = false; - this.#reset = false; - this.#maxAgeMs = undefined; - // A type without replay has no position to have skipped past (SEP: ignore `truncated`). - if (reset || (params.truncated === true && cursor !== null)) reportGap(subscription, connection, cursor); - this.#setCursor(cursor); - this.#subscribed(); + this.#loop.succeeded(cursor, params.truncated === true); + this.#loop.setCursor(cursor); + this.#loop.subscribed(); } // From `active` on, every message restarts the countdown to declaring the stream dead, unless a callback in the frame already ended it. @@ -279,11 +192,6 @@ export class PushDriver implements Driver { ); } - #setCursor(cursor: string | null): void { - this.#cursor = cursor; - this.#context.queue.setCursor(cursor); - } - // The frame's params, or `undefined` (reported to onerror) when they do not match the schema. #parse(schema: S, notification: JSONRPCNotification): z.output | undefined { const parsed = schema.safeParse(notification.params); @@ -291,22 +199,4 @@ export class PushDriver implements Driver { this.#context.connection.report(new Error(`Invalid ${notification.method} params: ${parsed.error.message}`)); return undefined; } - - // random() × min(30 s, 1 s × 2^attempt), attempts counted since the last `active` (SEP: jitter before reconnecting). - #reconnectDelay(): number { - return Math.random() * Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** this.#attempt++); - } - - #sleep(ms: number): Promise { - return new Promise(resolve => { - if (this.#stopped || this.#closed) return resolve(); - const wake = (): void => { - clearTimeout(timer); - this.#wake = undefined; - resolve(); - }; - const timer = setTimeout(wake, ms); - this.#wake = wake; - }); - } } diff --git a/packages/client/src/ext/events/receiver.ts b/packages/client/src/ext/events/receiver.ts new file mode 100644 index 0000000000..b37173724d --- /dev/null +++ b/packages/client/src/ext/events/receiver.ts @@ -0,0 +1,160 @@ +import type { EventOccurrence } from '@modelcontextprotocol/core/ext/events'; +import { + EventOccurrenceSchema, + WEBHOOK_SUBSCRIPTION_ID_HEADER, + WebhookControlBodySchema, + WebhookVerificationBodySchema +} from '@modelcontextprotocol/core/ext/events'; +import { ProtocolError } from '@modelcontextprotocol/core-internal'; +import { EventsError, parseWebhookSecret, verifyWebhookSignature } from '@modelcontextprotocol/core-internal/ext/events'; + +// Where the receiver routes one subscription's deliveries. +export interface WebhookSink { + event(occurrence: EventOccurrence): void; + gap(cursor: string | null): void; + // An Events kind arrives as `EventsError`. + terminated(error: ProtocolError): void; +} + +const MAX_BODY_BYTES = 262_144; +const TIMESTAMP_TOLERANCE_SECONDS = 300; +const DEDUPE_WINDOW = 1000; + +// Keeps every byte (a BOM too) and refuses invalid UTF-8, so the text signs as the raw body does. +const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }); + +function keyOf(secret: string): Uint8Array { + const key = parseWebhookSecret(secret); + if (key === undefined) throw new TypeError('Not a Standard Webhooks secret (whsec_ and base64 of 24 to 64 bytes)'); + return key; +} + +function status(code: number, headers?: Record): Response { + return new Response(null, { status: code, headers }); +} + +// The body as text; `undefined` once it is over the size cap. Throws on bytes that are not UTF-8. +async function readBody(request: Request): Promise { + if (request.body === null) return ''; + const reader = request.body.getReader(); + const chunks: Uint8Array[] = []; + let size = 0; + for (let chunk = await reader.read(); !chunk.done; chunk = await reader.read()) { + size += chunk.value.byteLength; + if (size > MAX_BODY_BYTES) { + await reader.cancel(); + return undefined; + } + chunks.push(chunk.value); + } + const bytes = new Uint8Array(size); + let offset = 0; + for (const chunk of chunks) { + bytes.set(chunk, offset); + offset += chunk.byteLength; + } + return decoder.decode(bytes); +} + +// The JSON object `text` holds; `undefined` for anything else. +function jsonObject(text: string): object | undefined { + try { + const value: unknown = JSON.parse(text); + return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined; + } catch { + return undefined; + } +} + +// One client's webhook endpoint (spec §6.4): verifies Standard Webhooks signatures, answers the verification challenge, and routes deliveries by `X-MCP-Subscription-Id`. +export class WebhookReceiver { + // Secrets of subscriptions whose id is not known yet. + readonly #pending = new Set<{ key: Uint8Array; onBind(id: string): void }>(); + // By subscription id: its secret, and where its deliveries go once bound. + readonly #bound = new Map(); + // The last 1 000 `webhook-id`s delivered, oldest first. + readonly #seen = new Set(); + + // Answers a verification signed with `secret` for an id not bound yet, then calls `onBind` with that id; the returned function withdraws the secret. + registerPending(secret: string, onBind: (id: string) => void): () => void { + const entry = { key: keyOf(secret), onBind }; + this.#pending.add(entry); + return () => void this.#pending.delete(entry); + } + + // Routes deliveries for `id`, signed with `secret`, to `sink`. + bind(id: string, secret: string, sink: WebhookSink): void { + this.#bound.set(id, { key: keyOf(secret), sink }); + } + + // Stops routing `id`; its deliveries are answered 503 from now on. + forget(id: string): void { + this.#bound.delete(id); + } + + async handle(request: Request): Promise { + if (request.method !== 'POST') return status(405, { Allow: 'POST' }); + const webhookId = request.headers.get('webhook-id'); + const timestamp = request.headers.get('webhook-timestamp'); + const signature = request.headers.get('webhook-signature'); + const id = request.headers.get(WEBHOOK_SUBSCRIPTION_ID_HEADER); + if (webhookId === null || timestamp === null || signature === null || id === null) return status(400); + const seconds = /^\d+$/.test(timestamp) ? Number(timestamp) : Number.NaN; + // Written so a timestamp that is not a number fails too. + if (!(Math.abs(Math.floor(Date.now() / 1000) - seconds) <= TIMESTAMP_TOLERANCE_SECONDS)) return status(400); + const raw = await readBody(request).catch(() => null); + if (raw === undefined) return status(413); + const body = raw === null ? undefined : jsonObject(raw); + if (raw === null || body === undefined) return status(400); + const verifies = (key: Uint8Array): Promise => verifyWebhookSignature([key], webhookId, seconds, raw, signature); + if ('type' in body && body.type === 'verification') return this.#verification(id, body, verifies); + + const target = this.#bound.get(id); + if (target?.sink === undefined) return status(503); + if (!(await verifies(target.key))) return status(401); + if (this.#seen.has(webhookId)) return status(200); + const route = this.#route(body, target.sink); + if (route === undefined) return status(400); + this.#remember(webhookId); + route(); + return status(200); + } + + // Tries the id's own secret (a server that lost its verification asks again), then every pending one. + async #verification(id: string, body: object, verifies: (key: Uint8Array) => Promise): Promise { + const parsed = WebhookVerificationBodySchema.safeParse(body); + if (!parsed.success) return status(400); + const answer = Response.json({ challenge: parsed.data.challenge }); + const bound = this.#bound.get(id); + if (bound !== undefined && (await verifies(bound.key))) return answer; + for (const entry of this.#pending) { + // Withdrawn while the signature was checked. + if (!(await verifies(entry.key)) || !this.#pending.delete(entry)) continue; + this.#bound.set(id, { ...this.#bound.get(id), key: entry.key }); + entry.onBind(id); + return answer; + } + return status(401); + } + + // Delivers a valid event, `gap` or `terminated` body to `sink`; `undefined` for any other body. + #route(body: object, sink: WebhookSink): (() => void) | undefined { + if (!('type' in body)) { + const occurrence = EventOccurrenceSchema.safeParse(body); + return occurrence.success ? () => sink.event(occurrence.data) : undefined; + } + const control = WebhookControlBodySchema.safeParse(body); + if (!control.success) return undefined; + const message = control.data; + if (message.type === 'gap') return () => sink.gap(message.cursor ?? null); + if (message.type !== 'terminated') return undefined; + const { code, message: text, data } = message.error; + const error = ProtocolError.fromError(code, text, data); + return () => sink.terminated(EventsError.fromProtocolError(error) ?? error); + } + + #remember(webhookId: string): void { + this.#seen.add(webhookId); + if (this.#seen.size > DEDUPE_WINDOW) this.#seen.delete(this.#seen.values().next().value!); + } +} diff --git a/packages/client/src/ext/events/recovery.ts b/packages/client/src/ext/events/recovery.ts new file mode 100644 index 0000000000..146cc5cb72 --- /dev/null +++ b/packages/client/src/ext/events/recovery.ts @@ -0,0 +1,261 @@ +import type { DeliveryMode } from '@modelcontextprotocol/core/ext/events'; +import { HEADER_MISMATCH_ERROR_CODE, ProtocolError } from '@modelcontextprotocol/core-internal'; +import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; +import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal/public'; + +import { NoCompatibleDeliveryModeError } from './errors'; +import type { EventsConnection } from './request'; +import type { DriverContext, SubscribeOptions } from './subscription'; + +// setTimeout fires at once beyond this. +export const MAX_TIMER_DELAY_MS = 2_147_483_647; +const RETRY_BASE_MS = 1000; +const RETRY_MAX_MS = 30_000; + +// An error of the first exchange that subscribe() rejects with (a -32020 only once its re-list is spent); any other (transport, non-Events JSON-RPC) is retried in the background. +export function refusesSubscription(error: unknown): boolean { + return error instanceof EventsError || error instanceof SdkError || isHeaderMismatch(error); +} + +// A -32020: the request's `Mcp-Param` headers do not match its arguments (D26). +export function isHeaderMismatch(error: unknown): boolean { + return error instanceof ProtocolError && error.code === HEADER_MISMATCH_ERROR_CODE; +} + +// What a subscription ends with when its client's connection closes. +export function closedError(cause?: unknown): SdkError { + return new SdkError(SdkErrorCode.ConnectionClosed, 'Connection closed', undefined, cause === undefined ? undefined : { cause }); +} + +// The SdkError a subscription ends with when its client's connection is gone, judged at a failed request; `undefined` while connected. +export function connectionClosed(connection: EventsConnection, error: unknown): SdkError | undefined { + if (error instanceof SdkError && error.code === SdkErrorCode.ConnectionClosed) return error; + const notConnected = error instanceof SdkError && error.code === SdkErrorCode.NotConnected; + if (!notConnected && connection.client.transport !== undefined) return undefined; + return closedError(error); +} + +// An `unsupported` error saying the event type's schema changed in place. +export function isSchemaChange(error: unknown): boolean { + return ( + error instanceof EventsError && + error.kind === 'unsupported' && + (error.data as { reason?: unknown } | undefined)?.reason === 'schema_changed' + ); +} + +// Every mode's recovery once subscribed (spec §6.3): `relist` and go on while still offered, `mismatch` (re-list and retry once, then end), `fail` (end with the error), or `retry` later. +export function recoveryFor(error: unknown): 'relist' | 'mismatch' | 'fail' | 'retry' { + if (isHeaderMismatch(error)) return 'mismatch'; + if (!(error instanceof EventsError)) return 'retry'; + return error.kind === 'notFound' || isSchemaChange(error) ? 'relist' : 'fail'; +} + +// Reports a possible gap at `cursor` through onGap; a throwing onGap goes to the client's onerror, and delivery goes on. +export function reportGap(subscription: SubscribeOptions, connection: EventsConnection, cursor: string | null): void { + try { + subscription.onGap?.(cursor); + } catch (error) { + connection.report(error); + } +} + +// Re-lists, then throws why `name` cannot be subscribed with `mode`: notFound when unlisted, NoCompatibleDeliveryModeError when `mode` is not offered. +export async function requireOffered(connection: EventsConnection, name: string, mode: DeliveryMode, signal: AbortSignal): Promise { + try { + await connection.list(undefined, { signal }); + } catch (error) { + throw connectionClosed(connection, error) ?? error; + } + const descriptor = connection.descriptor(name); + if (descriptor === undefined) throw new EventsError('notFound', 'Event type not found', { kind: 'event' }); + if (!descriptor.delivery.includes(mode)) throw new NoCompatibleDeliveryModeError(name, descriptor.delivery, [mode]); +} + +// Re-lists, then whether `name` is still listed with `mode`; `undefined` when the list fails. +export async function stillOffered( + connection: EventsConnection, + name: string, + mode: DeliveryMode, + signal: AbortSignal +): Promise { + try { + await connection.list(undefined, { signal }); + } catch { + return undefined; + } + return connection.descriptor(name)?.delivery.includes(mode) === true; +} + +// random() × min(30 s, 1 s × 2^attempt) (SEP: jitter before reconnecting). +export function jitteredDelay(attempt: number): number { + return Math.random() * Math.min(RETRY_MAX_MS, RETRY_BASE_MS * 2 ** attempt); +} + +// A mode's own steps: `interrupt` ends what its loop waits on besides sleep(), on stop() and on a close; `closed` runs on a close. +export interface LoopHooks { + interrupt?: () => void; + closed?: () => void; +} + +// The loop every mode's driver runs (spec §6.3): its cursor and the reset to now, the first exchange that settles start(), waits that stop() or a closed connection end at once, and the recovery rules. +export class DriverLoop { + readonly #context: DriverContext; + readonly #mode: DeliveryMode; + // Aborts requests in flight on stop(). + readonly #abort = new AbortController(); + #cursor: string | null; + // Sent until an exchange succeeds. + #maxAgeMs: number | undefined; + // Until an exchange succeeds, or the first one fails transiently. + #first = true; + // A schema change has refused the subscription since the last successful exchange. + #schemaChanged = false; + // The cursor was reset to now; the next successful exchange reports the gap. + #reset = false; + #stopped = false; + // Set by the connection's close listener, which ends the subscription at once. + #closed = false; + #settle: { resolve(): void; reject(error: unknown): void } = { resolve: () => {}, reject: () => {} }; + #hooks: LoopHooks = {}; + #wake: (() => void) | undefined; + #running: Promise = Promise.resolve(); + + constructor(context: DriverContext, mode: DeliveryMode) { + this.#context = context; + this.#mode = mode; + this.#cursor = context.subscription.cursor ?? null; + this.#maxAgeMs = context.subscription.maxAgeMs; + } + + get cursor(): string | null { + return this.#cursor; + } + + get maxAgeMs(): number | undefined { + return this.#maxAgeMs; + } + + get signal(): AbortSignal { + return this.#abort.signal; + } + + // stop() was called or the connection closed: the loop returns. + get ended(): boolean { + return this.#stopped || this.#closed; + } + + // Runs `run` until it returns, or throws the error that ends the subscription; settles as the first exchange does. + start(run: () => Promise, hooks: LoopHooks = {}): Promise { + const first = new Promise((resolve, reject) => (this.#settle = { resolve, reject })); + this.#hooks = hooks; + const removeCloseListener = this.#context.connection.onClose(() => { + this.#closed = true; + this.#interrupt(); + hooks.closed?.(); + this.#fail(closedError()); + }); + this.#running = run() + .then( + () => this.#settle.resolve(), + (error: unknown) => this.#fail(error) + ) + .finally(removeCloseListener); + return first; + } + + // Aborts requests in flight, ends the current wait, runs `cleanup`, and resolves once the loop has returned. + async stop(cleanup?: () => Promise): Promise { + this.#stopped = true; + this.#abort.abort(); + this.#interrupt(); + await cleanup?.(); + await this.#running; + } + + // The first exchange succeeded or failed transiently: start() resolves. + subscribed(): void { + this.#first = false; + this.#settle.resolve(); + } + + // An exchange succeeded at `cursor`: `maxAgeMs` is no longer sent, and a gap is reported on `truncated` or after a reset to now. + succeeded(cursor: string | null, truncated: boolean): void { + const reset = this.#reset; + this.#maxAgeMs = undefined; + this.#schemaChanged = false; + this.#reset = false; + // A type without replay has no position to have skipped past (SEP: ignore `truncated`). + if (reset || (truncated && cursor !== null)) reportGap(this.#context.subscription, this.#context.connection, cursor); + } + + setCursor(cursor: string | null): void { + this.#cursor = cursor; + this.#context.queue.setCursor(cursor); + } + + // Resolves after `ms`, or at once on wake(), stop() or a close. + sleep(ms: number): Promise { + return new Promise(resolve => { + if (this.ended) return resolve(); + const wake = (): void => { + clearTimeout(timer); + this.#wake = undefined; + resolve(); + }; + const timer = setTimeout(wake, Math.min(ms, MAX_TIMER_DELAY_MS)); + this.#wake = wake; + }); + } + + wake(): void { + this.#wake?.(); + } + + // After an exchange failed with `error` (spec §6.3): throws when that ends the subscription; `restarted` when the first exchange's stale cursor was dropped for now. + async recover(error: unknown): Promise<'restarted' | 'retry'> { + const { connection, subscription } = this.#context; + const closed = connectionClosed(connection, error); + if (closed !== undefined) throw closed; + if (this.#first) { + // A stale cursor passed to subscribe(): drop it and start from now, if the event type still offers this mode. + if (isSchemaChange(error) && this.#cursor !== null) { + await requireOffered(connection, subscription.name, this.#mode, this.#abort.signal); + this.#restartFromNow(); + return 'restarted'; + } + if (refusesSubscription(error)) throw error; + this.subscribed(); + return 'retry'; + } + const recovery = recoveryFor(error); + if (recovery === 'retry') return 'retry'; + // A -32020 here is the second: the mode has already re-listed once and retried with fresh headers. + if (recovery !== 'relist') throw error; + const offered = await stillOffered(connection, subscription.name, this.#mode, this.#abort.signal); + if (offered === false) throw error; + if (isSchemaChange(error)) this.#schemaChange(); + return 'retry'; + } + + #restartFromNow(): void { + this.#cursor = null; + this.#reset = true; + } + + // A second schema change in a row means the last cursor is refused (SEP: a stale schema epoch), so start again from now. + #schemaChange(): void { + if (this.#schemaChanged && this.#cursor !== null) this.#restartFromNow(); + this.#schemaChanged = true; + } + + #interrupt(): void { + this.#wake?.(); + this.#hooks.interrupt?.(); + } + + #fail(error: unknown): void { + this.#settle.reject(error); + this.#context.queue.fail(error); + } +} diff --git a/packages/client/src/ext/events/request.ts b/packages/client/src/ext/events/request.ts index 8f4d269813..814af26d52 100644 --- a/packages/client/src/ext/events/request.ts +++ b/packages/client/src/ext/events/request.ts @@ -7,7 +7,7 @@ import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; import type { Client } from '../../client/client'; import { clientInternals } from '../../client/client'; import { detectProbeEnvironment, detectProbeTransportKind } from '../../client/versionNegotiation'; -import { isHeaderMismatch } from './subscription'; +import { isHeaderMismatch } from './recovery'; // The event type a request is about, whose annotated arguments become `Mcp-Param` headers. export interface ParamMirror { diff --git a/packages/client/src/ext/events/subscription.ts b/packages/client/src/ext/events/subscription.ts index 98d0ceeff4..e11167f1ac 100644 --- a/packages/client/src/ext/events/subscription.ts +++ b/packages/client/src/ext/events/subscription.ts @@ -1,14 +1,7 @@ import type { DeliveryMode, DeliveryStatus, EventOccurrence } from '@modelcontextprotocol/core/ext/events'; -import { HEADER_MISMATCH_ERROR_CODE, ProtocolError } from '@modelcontextprotocol/core-internal'; -import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; -import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal/public'; -import { NoCompatibleDeliveryModeError } from './errors'; import type { EventsConnection } from './request'; -// setTimeout fires at once beyond this. -export const MAX_TIMER_DELAY_MS = 2_147_483_647; - /** * What to subscribe to, and how. * @@ -40,7 +33,8 @@ export interface SubscribeOptions { * One subscription's events. The `for await` loop, and how a subscription * recovers from errors, are the same in every delivery mode. A refusal of the * subscription itself comes from `subscribe()`. Once subscribed, a server - * error is handled by its kind: + * error (an error response, a push `terminated` frame or a webhook + * `terminated` body) is handled by its kind: * * - `notFound`, or `unsupported` for a schema change: the event types are * listed again, and delivery goes on while the event type is still listed @@ -57,10 +51,11 @@ export interface SubscribeOptions { * - Anything else (a network or transport failure, another JSON-RPC error, a * push stream that ends or goes silent): retried after a backoff. * - * Closing the client, or connecting it again, ends its subscriptions: the loop - * rejects with an `SdkError` (`ConnectionClosed`) at once when a request is in - * flight, otherwise when the next one would be sent; after reconnecting, - * subscribe again and pass {@linkcode EventSubscription.cursor}. + * Closing the client, or connecting it again without resuming its session, + * ends its subscriptions at once: the loop rejects with an `SdkError` + * (`ConnectionClosed`), and a webhook subscription is left to lapse on the + * server. After reconnecting, subscribe again and pass + * {@linkcode EventSubscription.cursor}. * `T` types `data` and is not checked against the event type's * `payloadSchema`. Leaving the loop early cancels the subscription. * @@ -76,9 +71,13 @@ export interface EventSubscription> extends AsyncIte */ readonly cursor: string | null; readonly deliveryMode: DeliveryMode; - /** Webhook delivery health, as the server last reported it. */ + /** Webhook delivery health, as the server last reported it in an `events/subscribe` result. */ readonly deliveryStatus?: DeliveryStatus; - /** Stops delivery and ends the loop. */ + /** + * Stops delivery and ends the loop. Cancelling the last of identical + * webhook subscriptions also removes the subscription on the server + * (`events/unsubscribe`). + */ cancel(): Promise; } @@ -90,88 +89,16 @@ export interface Driver { stop(): Promise; } +// What a driver delivers into: one subscription's queue, or (webhook) one that passes everything on to identical subscriptions. +export type DeliveryQueue = Pick, 'push' | 'setCursor' | 'setDeliveryStatus' | 'fail'>; + // What a driver runs: the subscription, the queue its events go into, and the connection it requests through. export interface DriverContext { readonly subscription: SubscribeOptions; - readonly queue: SubscriptionQueue; + readonly queue: DeliveryQueue; readonly connection: EventsConnection; } -// An error of the first exchange that subscribe() rejects with (a -32020 only once its re-list is spent); any other (transport, non-Events JSON-RPC) is retried in the background. -export function refusesSubscription(error: unknown): boolean { - return error instanceof EventsError || error instanceof SdkError || isHeaderMismatch(error); -} - -// A -32020: the request's `Mcp-Param` headers do not match its arguments (D26). -export function isHeaderMismatch(error: unknown): boolean { - return error instanceof ProtocolError && error.code === HEADER_MISMATCH_ERROR_CODE; -} - -// What a subscription ends with when its client's connection closes. -export function closedError(cause?: unknown): SdkError { - return new SdkError(SdkErrorCode.ConnectionClosed, 'Connection closed', undefined, cause === undefined ? undefined : { cause }); -} - -// The SdkError a subscription ends with when its client's connection is gone, judged at a failed request; `undefined` while connected. -export function connectionClosed(connection: EventsConnection, error: unknown): SdkError | undefined { - if (error instanceof SdkError && error.code === SdkErrorCode.ConnectionClosed) return error; - const notConnected = error instanceof SdkError && error.code === SdkErrorCode.NotConnected; - if (!notConnected && connection.client.transport !== undefined) return undefined; - return closedError(error); -} - -// An `unsupported` error saying the event type's schema changed in place. -export function isSchemaChange(error: unknown): boolean { - return ( - error instanceof EventsError && - error.kind === 'unsupported' && - (error.data as { reason?: unknown } | undefined)?.reason === 'schema_changed' - ); -} - -// Every mode's recovery once subscribed (spec §6.3): `relist` and go on while still offered, `mismatch` (re-list and retry once, then end), `fail` (end with the error), or `retry` later. -export function recoveryFor(error: unknown): 'relist' | 'mismatch' | 'fail' | 'retry' { - if (isHeaderMismatch(error)) return 'mismatch'; - if (!(error instanceof EventsError)) return 'retry'; - return error.kind === 'notFound' || isSchemaChange(error) ? 'relist' : 'fail'; -} - -// Reports a possible gap at `cursor` through onGap; a throwing onGap goes to the client's onerror, and delivery goes on. -export function reportGap(subscription: SubscribeOptions, connection: EventsConnection, cursor: string | null): void { - try { - subscription.onGap?.(cursor); - } catch (error) { - connection.report(error); - } -} - -// Re-lists, then throws why `name` cannot be subscribed with `mode`: notFound when unlisted, NoCompatibleDeliveryModeError when `mode` is not offered. -export async function requireOffered(connection: EventsConnection, name: string, mode: DeliveryMode, signal: AbortSignal): Promise { - try { - await connection.list(undefined, { signal }); - } catch (error) { - throw connectionClosed(connection, error) ?? error; - } - const descriptor = connection.descriptor(name); - if (descriptor === undefined) throw new EventsError('notFound', 'Event type not found', { kind: 'event' }); - if (!descriptor.delivery.includes(mode)) throw new NoCompatibleDeliveryModeError(name, descriptor.delivery, [mode]); -} - -// Re-lists, then whether `name` is still listed with `mode`; `undefined` when the list fails. -export async function stillOffered( - connection: EventsConnection, - name: string, - mode: DeliveryMode, - signal: AbortSignal -): Promise { - try { - await connection.list(undefined, { signal }); - } catch { - return undefined; - } - return connection.descriptor(name)?.delivery.includes(mode) === true; -} - type Item = EventOccurrence & { data: T }; // In delivery order: an event, or a cursor that becomes current once the loop has moved past the events before it. diff --git a/packages/client/src/ext/events/webhook.ts b/packages/client/src/ext/events/webhook.ts new file mode 100644 index 0000000000..9ce74d6083 --- /dev/null +++ b/packages/client/src/ext/events/webhook.ts @@ -0,0 +1,282 @@ +import type { DeliveryStatus, SubscribeEventsResult } from '@modelcontextprotocol/core/ext/events'; +import { + EVENTS_SUBSCRIBE_METHOD, + EVENTS_UNSUBSCRIBE_METHOD, + SubscribeEventsResultSchema, + UnsubscribeEventsResultSchema +} from '@modelcontextprotocol/core/ext/events'; +import type { ProtocolError } from '@modelcontextprotocol/core-internal'; +import { canonicalJson, generateWebhookSecret, parseWebhookSecret } from '@modelcontextprotocol/core-internal/ext/events'; +import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal/public'; + +import type { WebhookReceiver, WebhookSink } from './receiver'; +import { DriverLoop, jitteredDelay, MAX_TIMER_DELAY_MS, reportGap } from './recovery'; +import type { EventsConnection, ParamMirror } from './request'; +import type { DeliveryQueue, Driver, DriverContext } from './subscription'; + +// The share of each grant after which the subscription is refreshed. +const REFRESH_AT = 0.75; + +interface WebhookOptions { + url: string; + secretProvider?: () => string; +} + +// The webhook subscriptions of one extension: identical ones (the same name and canonical arguments, so the same server subscription) share one driver while any of them is open. +export class WebhookSubscriptions { + readonly #webhook: WebhookOptions; + readonly #receiver: WebhookReceiver; + readonly #floorMs: number; + readonly #open = new Map(); + + constructor(webhook: WebhookOptions, receiver: WebhookReceiver, floorMs: number) { + this.#webhook = webhook; + this.#receiver = receiver; + this.#floorMs = floorMs; + } + + // One subscription's driver: it joins the open server subscription for its name and arguments, or opens one (TypeError for a bad `secretProvider` value). + driver(context: DriverContext): Driver { + const key = canonicalJson([context.subscription.name, context.subscription.arguments ?? {}]); + let shared = this.#open.get(key); + if (shared === undefined) { + const opened = new SharedWebhook(context, this.#webhook, this.#receiver, this.#floorMs, () => { + if (this.#open.get(key) === opened) this.#open.delete(key); + }); + this.#open.set(key, opened); + shared = opened; + } + return shared.join(context); + } +} + +// One server webhook subscription: its driver delivers into the queue of every subscription that joined it. +class SharedWebhook { + readonly #members = new Set>(); + readonly #connection: EventsConnection; + readonly #driver: WebhookDriver; + // Takes this one out of the open subscriptions, so the next identical subscribe opens a new one. + readonly #close: () => void; + // Where delivery is: the first subscription's cursor until the server reports one. + #cursor: string | null; + #deliveryStatus: DeliveryStatus | undefined; + #started: Promise | undefined; + + constructor(first: DriverContext, webhook: WebhookOptions, receiver: WebhookReceiver, floorMs: number, close: () => void) { + const { connection, subscription } = first; + const members = this.#members; + this.#connection = connection; + this.#close = close; + this.#cursor = subscription.cursor ?? null; + const queue: DeliveryQueue = { + push: event => { + for (const member of members) member.queue.push(event); + }, + setCursor: cursor => { + this.#cursor = cursor; + for (const member of members) member.queue.setCursor(cursor); + }, + setDeliveryStatus: status => { + this.#deliveryStatus = status; + for (const member of members) member.queue.setDeliveryStatus(status); + }, + fail: error => { + close(); + for (const member of members) member.queue.fail(error); + } + }; + const onGap = (cursor: string | null): void => { + for (const member of members) reportGap(member.subscription, connection, cursor); + }; + this.#driver = new WebhookDriver({ subscription: { ...subscription, onGap }, queue, connection }, webhook, receiver, floorMs); + } + + // Delivers to `context` too; the driver returned settles with the shared first exchange, and its stop() ends the server subscription only for the last one. + join(context: DriverContext): Driver { + const late = this.#members.size > 0; + const from = this.#cursor; + this.#members.add(context); + return { + start: async () => { + this.#started ??= this.#driver.start(); + await this.#started; + if (!late) return; + // It starts where the shared subscription is; a cursor of its own anywhere else may have skipped events. + const own = context.subscription.cursor ?? null; + if (own !== null && own !== from) reportGap(context.subscription, this.#connection, this.#cursor); + context.queue.setCursor(this.#cursor); + if (this.#deliveryStatus !== undefined) context.queue.setDeliveryStatus(this.#deliveryStatus); + }, + stop: async () => { + if (!this.#members.delete(context) || this.#members.size > 0) return; + this.#close(); + await this.#driver.stop(); + } + }; + } +} + +// Webhook delivery (spec §6.3): `events/subscribe` with its own secret, sent again once ¾ of each grant has passed (never sooner than the floor); the receiver routes the server's POSTs here. +class WebhookDriver implements Driver { + readonly #context: DriverContext; + readonly #loop: DriverLoop; + readonly #receiver: WebhookReceiver; + readonly #floorMs: number; + readonly #url: string; + readonly #secret: string; + readonly #mirror: ParamMirror; + readonly #sink: WebhookSink; + // The id the server derived, from its verification challenge or the subscribe response. + #id: string | undefined; + // The server holds the subscription: a subscribe succeeded, and no `terminated` body, terminal failure or close came after it. + #live = false; + #withdrawPending: (() => void) | undefined; + // A `terminated` body routed here since the last subscribe went out. + #terminated: ProtocolError | undefined; + // Retry delays taken since the last successful subscribe. + #attempt = 0; + + // Throws TypeError when `secretProvider` gives something that is not a Standard Webhooks secret. + constructor(context: DriverContext, webhook: WebhookOptions, receiver: WebhookReceiver, floorMs: number) { + const secret = webhook.secretProvider?.() ?? generateWebhookSecret(); + if (parseWebhookSecret(secret) === undefined) { + throw new TypeError('webhook.secretProvider must return a Standard Webhooks secret: whsec_ and base64 of 24 to 64 bytes'); + } + const { name, arguments: args } = context.subscription; + this.#context = context; + this.#loop = new DriverLoop(context, 'webhook'); + this.#receiver = receiver; + this.#floorMs = floorMs; + this.#url = webhook.url; + this.#secret = secret; + this.#mirror = { name, ...(args !== undefined && { arguments: args }) }; + this.#sink = { + event: occurrence => { + if (this.#loop.ended) return; + context.queue.push(occurrence); + this.#loop.setCursor(occurrence.cursor ?? null); + }, + gap: cursor => { + if (this.#loop.ended) return; + // A type without replay has no position to have skipped past (SEP: ignore `truncated`). + if (cursor !== null) reportGap(context.subscription, context.connection, cursor); + this.#loop.setCursor(cursor); + }, + terminated: error => { + if (this.#loop.ended) return; + this.#terminated = error; + this.#loop.wake(); + } + }; + } + + start(): Promise { + this.#withdrawPending = this.#receiver.registerPending(this.#secret, id => this.#bind(id)); + return this.#loop.start(() => this.#run(), { + closed: () => { + this.#live = false; + this.#release(); + } + }); + } + + stop(): Promise { + return this.#loop.stop(async () => { + // Eager cleanup (SEP): otherwise the subscription lasts until its grant runs out. + if (this.#live) await this.#unsubscribe().catch(() => {}); + this.#release(); + }); + } + + // Subscribes until stopped; throws, ending the subscription and releasing the receiver, when a failure calls for it. + async #run(): Promise { + const loop = this.#loop; + try { + while (!loop.ended) { + const error = await this.#subscribeAndRefresh(); + if (loop.ended) return; + await loop.recover(error); + await loop.sleep(jitteredDelay(this.#attempt++)); + } + } catch (error) { + // Left to lapse: an identical subscribe after this end opens a new driver on the same server subscription. + this.#live = false; + this.#release(); + throw error; + } + } + + // Subscribes, then refreshes once ¾ of each grant has passed; resolves with the error of a failed subscribe or a `terminated` body. + async #subscribeAndRefresh(): Promise { + const loop = this.#loop; + while (!loop.ended) { + let result: SubscribeEventsResult; + try { + result = await this.#subscribe(); + } catch (error) { + return error; + } + if (loop.ended) break; + const expiresAt = result.refreshBefore === null ? undefined : Date.parse(result.refreshBefore); + if (Number.isNaN(expiresAt)) return new SdkError(SdkErrorCode.InvalidResult, `Invalid refreshBefore: ${result.refreshBefore}`); + this.#accept(result); + if (this.#terminated === undefined) { + // A `null` grant (no expiry, which this client never asks for) is refreshed after the longest timer; the floor stops a skewed clock from refreshing back to back. + await loop.sleep( + expiresAt === undefined ? MAX_TIMER_DELAY_MS : Math.max(this.#floorMs, REFRESH_AT * (expiresAt - Date.now())) + ); + } + if (this.#terminated !== undefined) { + this.#live = false; + return this.#terminated; + } + } + return undefined; + } + + // `events/subscribe` with no `ttlMs` suggestion, so the server grants its default. + #subscribe(): Promise { + const loop = this.#loop; + const params = { + ...this.#mirror, + delivery: { mode: 'webhook' as const, url: this.#url, secret: this.#secret }, + cursor: loop.cursor, + ...(loop.maxAgeMs !== undefined && { maxAgeMs: loop.maxAgeMs }) + }; + this.#terminated = undefined; + return this.#context.connection.request(EVENTS_SUBSCRIBE_METHOD, params, SubscribeEventsResultSchema, this.#mirror, { + signal: loop.signal + }); + } + + #unsubscribe(): Promise { + const params = { ...this.#mirror, delivery: { url: this.#url } }; + return this.#context.connection.request(EVENTS_UNSUBSCRIBE_METHOD, params, UnsubscribeEventsResultSchema, this.#mirror); + } + + // A subscribe succeeded: the receiver routes its id here, and the watermark, the delivery status and a gap are taken from it. + #accept(result: SubscribeEventsResult): void { + const loop = this.#loop; + const cursor = result.cursor ?? null; + this.#attempt = 0; + this.#live = true; + this.#bind(result.id); + this.#withdrawPending?.(); + if (result.deliveryStatus !== undefined) this.#context.queue.setDeliveryStatus(result.deliveryStatus); + loop.succeeded(cursor, result.truncated === true); + loop.setCursor(cursor); + loop.subscribed(); + } + + #bind(id: string): void { + this.#id = id; + this.#receiver.bind(id, this.#secret, this.#sink); + } + + // The receiver stops routing deliveries here and forgets the secret. + #release(): void { + this.#withdrawPending?.(); + if (this.#id !== undefined) this.#receiver.forget(this.#id); + this.#id = undefined; + } +} diff --git a/packages/client/test/ext/events/receiver.test.ts b/packages/client/test/ext/events/receiver.test.ts new file mode 100644 index 0000000000..e825204041 --- /dev/null +++ b/packages/client/test/ext/events/receiver.test.ts @@ -0,0 +1,183 @@ +import { ProtocolError } from '@modelcontextprotocol/core-internal'; +import { generateWebhookSecret } from '@modelcontextprotocol/core-internal/ext/events'; +import type { Mock } from 'vitest'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; + +import { EventsError } from '../../../src/ext/events/index'; +import type { WebhookSink } from '../../../src/ext/events/receiver'; +import { WebhookReceiver } from '../../../src/ext/events/receiver'; +import { occurrence, WEBHOOK_URL, webhookPost } from './scripted'; + +type MockSink = { [K in keyof WebhookSink]: Mock }; + +function sink(): MockSink { + return { event: vi.fn(), gap: vi.fn(), terminated: vi.fn() }; +} + +/** A receiver routing `sub_1` to a fresh sink. */ +function bound(): { receiver: WebhookReceiver; secret: string; target: MockSink } { + const receiver = new WebhookReceiver(); + const secret = generateWebhookSecret(); + const target = sink(); + receiver.bind('sub_1', secret, target); + return { receiver, secret, target }; +} + +const now = () => Math.floor(Date.now() / 1000); + +async function statusOf(receiver: WebhookReceiver, request: Promise): Promise { + const response = await receiver.handle(await request); + return response.status; +} + +// A frozen clock, so a second does not tick over between signing and receiving. +beforeEach(() => { + vi.useFakeTimers({ toFake: ['Date'] }); +}); + +afterEach(() => { + vi.useRealTimers(); +}); + +describe('WebhookReceiver', () => { + it('delivers a verified event once', async () => { + const { receiver, secret, target } = bound(); + const event = { ...occurrence('e1'), cursor: 'c1' }; + + const first = await receiver.handle(await webhookPost(event, secret, 'sub_1', { webhookId: 'msg_1' })); + expect(first.status).toBe(200); + expect(target.event).toHaveBeenCalledExactlyOnceWith(event); + + // A retry keeps its webhook-id and is signed again with a fresh timestamp. + const retry = await receiver.handle(await webhookPost(event, secret, 'sub_1', { webhookId: 'msg_1', timestamp: now() + 5 })); + expect(retry.status).toBe(200); + expect(target.event).toHaveBeenCalledOnce(); + // The signature is checked before the webhook-id. + const forged = await receiver.handle(await webhookPost(event, generateWebhookSecret(), 'sub_1', { webhookId: 'msg_1' })); + expect(forged.status).toBe(401); + }); + + it('remembers the last 1 000 webhook-ids', async () => { + const { receiver, secret, target } = bound(); + const post = (webhookId: string) => statusOf(receiver, webhookPost(occurrence('e1'), secret, 'sub_1', { webhookId })); + + expect(await post('msg_0')).toBe(200); + for (let index = 1; index < 1000; index++) await post(`msg_${index}`); + expect(await post('msg_0')).toBe(200); + expect(target.event).toHaveBeenCalledTimes(1000); + + await post('msg_1000'); + expect(await post('msg_0')).toBe(200); + expect(target.event).toHaveBeenCalledTimes(1002); + }); + + it('answers a challenge for a not-yet-bound id and binds it', async () => { + const receiver = new WebhookReceiver(); + const secret = generateWebhookSecret(); + const target = sink(); + const onBind = vi.fn((id: string) => receiver.bind(id, secret, target)); + const other = vi.fn(); + receiver.registerPending(generateWebhookSecret(), other); + receiver.registerPending(secret, onBind); + + const answer = await receiver.handle(await webhookPost({ type: 'verification', challenge: 'nonce-1' }, secret, 'sub_x')); + expect(answer.status).toBe(200); + expect(answer.headers.get('content-type')).toBe('application/json'); + expect(await answer.json()).toEqual({ challenge: 'nonce-1' }); + expect(onBind).toHaveBeenCalledExactlyOnceWith('sub_x'); + expect(other).not.toHaveBeenCalled(); + + const event = await receiver.handle(await webhookPost(occurrence('e1'), secret, 'sub_x')); + expect(event.status).toBe(200); + expect(target.event).toHaveBeenCalledOnce(); + + // A server that lost its verification (a restart) challenges the bound id again: that id's secret answers it. + const again = await receiver.handle(await webhookPost({ type: 'verification', challenge: 'nonce-2' }, secret, 'sub_x')); + expect(await again.json()).toEqual({ challenge: 'nonce-2' }); + expect(onBind).toHaveBeenCalledOnce(); + }); + + it('refuses a challenge no pending secret signs, and one for a withdrawn secret', async () => { + const receiver = new WebhookReceiver(); + const secret = generateWebhookSecret(); + const onBind = vi.fn(); + const withdraw = receiver.registerPending(secret, onBind); + + const unknown = await receiver.handle( + await webhookPost({ type: 'verification', challenge: 'n' }, generateWebhookSecret(), 'sub_x') + ); + expect(unknown.status).toBe(401); + withdraw(); + const withdrawn = await receiver.handle(await webhookPost({ type: 'verification', challenge: 'n' }, secret, 'sub_x')); + expect(withdrawn.status).toBe(401); + expect(onBind).not.toHaveBeenCalled(); + }); + + it('rejects bad signatures, stale timestamps and unknown ids', async () => { + const { receiver, secret, target } = bound(); + const status = (request: Promise) => statusOf(receiver, request); + const event = occurrence('e1'); + + expect(await status(webhookPost(event, generateWebhookSecret(), 'sub_1'))).toBe(401); + expect(await status(webhookPost(event, secret, 'sub_1', { timestamp: now() - 301 }))).toBe(400); + expect(await status(webhookPost(event, secret, 'sub_1', { timestamp: now() + 301 }))).toBe(400); + expect(await status(webhookPost(event, secret, 'sub_unknown'))).toBe(503); + // Verified, but not routed anywhere yet. + const pending = generateWebhookSecret(); + receiver.registerPending(pending, () => {}); + expect(await status(webhookPost({ type: 'verification', challenge: 'n' }, pending, 'sub_2'))).toBe(200); + expect(await status(webhookPost(event, pending, 'sub_2'))).toBe(503); + for (const omit of ['webhook-id', 'webhook-timestamp', 'webhook-signature', 'X-MCP-Subscription-Id']) { + expect(await status(webhookPost(event, secret, 'sub_1', { omit }))).toBe(400); + } + expect(target.event).not.toHaveBeenCalled(); + + expect(await status(webhookPost(event, secret, 'sub_1', { timestamp: now() - 300 }))).toBe(200); + receiver.forget('sub_1'); + expect(await status(webhookPost(occurrence('e2'), secret, 'sub_1'))).toBe(503); + expect(target.event).toHaveBeenCalledOnce(); + }); + + it('rejects non-POST and oversized bodies', async () => { + const { receiver, secret, target } = bound(); + const get = await receiver.handle(new Request(WEBHOOK_URL, { method: 'GET' })); + expect(get.status).toBe(405); + expect(get.headers.get('allow')).toBe('POST'); + + // A body of exactly the cap is accepted; one byte more is refused. + const sized = (bytes: number) => { + const base = JSON.stringify({ ...occurrence('e1'), data: { pad: '' } }).length; + return { ...occurrence('e1'), data: { pad: 'x'.repeat(bytes - base) } }; + }; + expect(await statusOf(receiver, webhookPost(sized(262_145), secret, 'sub_1'))).toBe(413); + expect(target.event).not.toHaveBeenCalled(); + expect(await statusOf(receiver, webhookPost(sized(262_144), secret, 'sub_1'))).toBe(200); + expect(target.event).toHaveBeenCalledOnce(); + }); + + it('routes gap and terminated bodies, and refuses malformed ones', async () => { + const { receiver, secret, target } = bound(); + const status = (body: unknown) => statusOf(receiver, webhookPost(body, secret, 'sub_1')); + + expect(await status({ type: 'gap', cursor: 'c9' })).toBe(200); + expect(await status({ type: 'gap' })).toBe(200); + expect(target.gap.mock.calls).toEqual([['c9'], [null]]); + + expect( + await status({ type: 'terminated', error: { code: -32_024, message: 'Forbidden', data: { reason: 'Access revoked' } } }) + ).toBe(200); + expect(await status({ type: 'terminated', error: { code: -32_603, message: 'Internal error' } })).toBe(200); + const [forbidden, internal] = target.terminated.mock.calls.map(([error]) => error); + expect(forbidden).toBeInstanceOf(EventsError); + expect(forbidden).toMatchObject({ kind: 'forbidden', data: { reason: 'Access revoked' } }); + expect(internal).toBeInstanceOf(ProtocolError); + expect(internal).not.toBeInstanceOf(EventsError); + + for (const malformed of ['not json', [], { name: 'tick' }, { type: 'unknown' }, { type: 'terminated' }]) { + expect(await status(malformed)).toBe(400); + } + expect(target.event).not.toHaveBeenCalled(); + expect(target.gap).toHaveBeenCalledTimes(2); + expect(target.terminated).toHaveBeenCalledTimes(2); + }); +}); diff --git a/packages/client/test/ext/events/subscription.test.ts b/packages/client/test/ext/events/recovery.test.ts similarity index 98% rename from packages/client/test/ext/events/subscription.test.ts rename to packages/client/test/ext/events/recovery.test.ts index 5c889b463f..88c7a86bb3 100644 --- a/packages/client/test/ext/events/subscription.test.ts +++ b/packages/client/test/ext/events/recovery.test.ts @@ -2,8 +2,8 @@ import { ProtocolError, SdkError, SdkErrorCode } from '@modelcontextprotocol/cor import { describe, expect, it, vi } from 'vitest'; import { EventsError } from '../../../src/ext/events/index'; +import { recoveryFor, refusesSubscription, reportGap } from '../../../src/ext/events/recovery'; import type { EventsConnection } from '../../../src/ext/events/request'; -import { recoveryFor, refusesSubscription, reportGap } from '../../../src/ext/events/subscription'; describe('the recovery rules every delivery mode shares', () => { it.each([ diff --git a/packages/client/test/ext/events/scripted.ts b/packages/client/test/ext/events/scripted.ts index 87700c6988..15fce2d373 100644 --- a/packages/client/test/ext/events/scripted.ts +++ b/packages/client/test/ext/events/scripted.ts @@ -1,7 +1,8 @@ import type { EventDescriptor, EventOccurrence } from '@modelcontextprotocol/core/ext/events'; -import { EVENTS_EXTENSION_ID } from '@modelcontextprotocol/core/ext/events'; +import { EVENTS_EXTENSION_ID, WEBHOOK_SUBSCRIPTION_ID_HEADER } from '@modelcontextprotocol/core/ext/events'; import type { JSONRPCMessage, JSONRPCRequest, RequestId, ServerCapabilities, Transport } from '@modelcontextprotocol/core-internal'; import { InMemoryTransport } from '@modelcontextprotocol/core-internal'; +import { generateWebhookId, parseWebhookSecret, signWebhook } from '@modelcontextprotocol/core-internal/ext/events'; import type { ClientOptions } from '../../../src/client/client'; import { Client } from '../../../src/client/client'; @@ -189,3 +190,29 @@ export function script(...answers: Array | RpcError>): H } export const callsTo = (calls: Call[], method: string): Call[] => calls.filter(call => call.method === method); + +export const WEBHOOK_URL = 'https://hooks.example.com/mcp/client123'; + +export interface WebhookPostOptions { + webhookId?: string; + /** Unix seconds; default now. */ + timestamp?: number; + /** A header to leave out. */ + omit?: string; +} + +/** A webhook POST as the server sends it: `body` (a raw string, or JSON) signed with `secret` for subscription `id`. */ +export async function webhookPost(body: unknown, secret: string, id: string, options: WebhookPostOptions = {}): Promise { + const raw = typeof body === 'string' ? body : JSON.stringify(body); + const webhookId = options.webhookId ?? generateWebhookId(); + const timestamp = options.timestamp ?? Math.floor(Date.now() / 1000); + const headers: Record = { + 'Content-Type': 'application/json', + 'webhook-id': webhookId, + 'webhook-timestamp': String(timestamp), + 'webhook-signature': await signWebhook([parseWebhookSecret(secret)!], webhookId, timestamp, raw), + [WEBHOOK_SUBSCRIPTION_ID_HEADER]: id + }; + if (options.omit !== undefined) delete headers[options.omit]; + return new Request(WEBHOOK_URL, { method: 'POST', headers, body: raw }); +} diff --git a/packages/client/test/ext/events/webhook.test.ts b/packages/client/test/ext/events/webhook.test.ts new file mode 100644 index 0000000000..ce0d158b25 --- /dev/null +++ b/packages/client/test/ext/events/webhook.test.ts @@ -0,0 +1,642 @@ +import { ProtocolError, SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal'; +import { generateWebhookSecret, parseWebhookSecret } from '@modelcontextprotocol/core-internal/ext/events'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; + +import type { EventSubscription, SubscribeOptions } from '../../../src/ext/events/index'; +import { EventsError, NoCompatibleDeliveryModeError } from '../../../src/ext/events/index'; +import type { Call, Handler } from './scripted'; +import { callsTo, connectEvents, descriptor, listing, occurrence, RpcError, WEBHOOK_URL, webhookPost } from './scripted'; + +const subscriptions: EventSubscription[] = []; + +beforeEach(() => { + vi.useFakeTimers(); + vi.spyOn(Math, 'random').mockReturnValue(0.5); +}); + +afterEach(async () => { + await Promise.all(subscriptions.splice(0).map(subscription => subscription.cancel())); + vi.useRealTimers(); + vi.restoreAllMocks(); +}); + +/** Lets every in-flight request and its response settle without moving the clock. */ +const settle = () => vi.advanceTimersByTimeAsync(0); + +/** The eventId of the loop's next event, `undefined` when the loop is done. */ +async function nextEventId(iterator: AsyncIterator<{ eventId: string }>): Promise { + const result = await iterator.next(); + return result.done ? undefined : result.value.eventId; +} + +const tick = descriptor('tick', { delivery: ['webhook'] }); +const schemaChange = { feature: 'payloadSchema', reason: 'schema_changed' }; + +const secretOf = (call: Call): string => (call.params['delivery'] as { secret: string }).secret; + +/** A grant of 60 s from now for `sub_1`, merged with `overrides`. */ +function grant(overrides: Record = {}): Record { + return { id: 'sub_1', refreshBefore: new Date(Date.now() + 60_000).toISOString(), cursor: null, truncated: false, ...overrides }; +} + +/** Answers each `events/subscribe` with a grant merged with the next answer, or throws it; once they run out, never answers. */ +function granting(...answers: Array | RpcError>): Handler { + return () => { + const next = answers.shift(); + if (next === undefined) return new Promise(() => {}); + if (next instanceof RpcError) throw next; + return grant(next); + }; +} + +async function webhookWith(subscribe: Handler, options: { list?: Handler; secretProvider?: () => string } = {}) { + const { secretProvider } = options; + const scripted = await connectEvents( + { 'events/list': options.list ?? listing(tick), 'events/subscribe': subscribe, 'events/unsubscribe': () => ({}) }, + { events: { webhook: { url: WEBHOOK_URL, ...(secretProvider !== undefined && { secretProvider }) } } } + ); + const handler = scripted.events.createWebhookHandler(); + const subscribes = () => callsTo(scripted.calls, 'events/subscribe'); + return { + ...scripted, + handler, + subscribes, + lists: () => callsTo(scripted.calls, 'events/list'), + unsubscribes: () => callsTo(scripted.calls, 'events/unsubscribe'), + /** POSTs `body` to the receiver as the server does (for `sub_1`, signed with the secret of the last `events/subscribe`); resolves with the status. */ + post: async (body: unknown, id = 'sub_1') => { + const response = await handler(await webhookPost(body, secretOf(subscribes().at(-1)!), id)); + return response.status; + }, + subscribe: async (options: Partial = {}) => { + const subscription = await scripted.events.subscribe({ name: 'tick', ...options }); + subscriptions.push(subscription); + await settle(); + return subscription; + } + }; +} + +describe('webhook delivery', () => { + it('subscribes with a generated whsec_ secret and refreshes at ¾ of the grant', async () => { + const { subscribes, subscribe } = await webhookWith(granting({ cursor: 'c1' }, { cursor: 'c2' }, { id: 'sub_2' })); + const sub = await subscribe({ arguments: { severity: 'P1' }, maxAgeMs: 300_000 }); + + expect(sub.deliveryMode).toBe('webhook'); + const first = subscribes()[0]!; + expect(first.params).toEqual({ + name: 'tick', + arguments: { severity: 'P1' }, + delivery: { mode: 'webhook', url: WEBHOOK_URL, secret: expect.stringMatching(/^whsec_/) }, + cursor: null, + maxAgeMs: 300_000, + _meta: expect.any(Object) + }); + expect(parseWebhookSecret(secretOf(first))).toHaveLength(32); + expect(sub.cursor).toBe('c1'); + + await vi.advanceTimersByTimeAsync(44_999); + expect(subscribes()).toHaveLength(1); + await vi.advanceTimersByTimeAsync(1); + expect(subscribes()).toHaveLength(2); + expect(subscribes()[1]!.params).toEqual({ + name: 'tick', + arguments: { severity: 'P1' }, + delivery: { mode: 'webhook', url: WEBHOOK_URL, secret: secretOf(first) }, + cursor: 'c1', + _meta: expect.any(Object) + }); + expect(sub.cursor).toBe('c2'); + + // Every subscription has its own secret. + await subscribe({ arguments: { severity: 'P2' } }); + expect(secretOf(subscribes()[2]!)).not.toBe(secretOf(first)); + }); + + it('exposes deliveryStatus from the refresh', async () => { + const failing = { + active: false, + lastDeliveryAt: '2026-11-18T00:00:00Z', + lastError: 'http_4xx', + failedSince: '2026-11-18T00:01:00Z' + }; + const { subscribe } = await webhookWith(granting({}, { deliveryStatus: failing }, {})); + const sub = await subscribe(); + expect(sub.deliveryStatus).toBeUndefined(); + + await vi.advanceTimersByTimeAsync(45_000); + expect(sub.deliveryStatus).toEqual(failing); + // A refresh answered without it (another replica) leaves the last one reported. + await vi.advanceTimersByTimeAsync(45_000); + expect(sub.deliveryStatus).toEqual(failing); + }); + + it('unsubscribes on cancel()', async () => { + const { post, subscribes, unsubscribes, subscribe } = await webhookWith(granting({})); + const sub = await subscribe({ arguments: { severity: 'P1' } }); + const pending = sub[Symbol.asyncIterator]().next(); + + await sub.cancel(); + expect(unsubscribes().map(call => call.params)).toEqual([ + { name: 'tick', arguments: { severity: 'P1' }, delivery: { url: WEBHOOK_URL }, _meta: expect.any(Object) } + ]); + expect(await pending).toEqual({ done: true, value: undefined }); + expect(await post(occurrence('e1'))).toBe(503); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(120_000); + expect(subscribes()).toHaveLength(1); + }); + + it('rejects a bad secretProvider value, and sends a good one as given', async () => { + const bad = await webhookWith(granting({}), { secretProvider: () => 'nope' }); + await expect(bad.events.subscribe({ name: 'tick' })).rejects.toThrow(TypeError); + expect(bad.subscribes()).toEqual([]); + + const secret = generateWebhookSecret(); + const good = await webhookWith(granting({}), { secretProvider: () => secret }); + await good.subscribe(); + expect(secretOf(good.subscribes()[0]!)).toBe(secret); + }); + + it('delivers events through the receiver once per eventId, persisting each watermark cursor', async () => { + const { post, subscribe } = await webhookWith(granting({ cursor: 'c0' })); + const sub = await subscribe(); + + expect(await post({ ...occurrence('e1'), cursor: 'c1' })).toBe(200); + // The same event under another webhook-id (as from another replica) is not delivered again. + expect(await post({ ...occurrence('e1'), cursor: 'c1' })).toBe(200); + expect(await post({ ...occurrence('e2'), cursor: 'c2' })).toBe(200); + + const iterator = sub[Symbol.asyncIterator](); + expect(await nextEventId(iterator)).toBe('e1'); + expect(await nextEventId(iterator)).toBe('e2'); + expect(sub.cursor).toBe('c1'); + let settled = false; + void iterator.next().then(() => (settled = true)); + await settle(); + expect(settled).toBe(false); + expect(sub.cursor).toBe('c2'); + }); + + it('answers the verification challenge sent during events/subscribe and routes deliveries that precede the response', async () => { + const challenges: unknown[] = []; + const early: number[] = []; + const receiver: { handle?: (request: Request) => Promise } = {}; + const { handler, subscribe } = await webhookWith(async params => { + const secret = (params['delivery'] as { secret: string }).secret; + const answer = await receiver.handle!(await webhookPost({ type: 'verification', challenge: 'nonce-1' }, secret, 'sub_1')); + challenges.push(await answer.json()); + const delivered = await receiver.handle!(await webhookPost({ ...occurrence('e1'), cursor: 'c1' }, secret, 'sub_1')); + early.push(delivered.status); + return grant({ cursor: 'c1' }); + }); + receiver.handle = handler; + const sub = await subscribe(); + + expect(challenges).toEqual([{ challenge: 'nonce-1' }]); + expect(early).toEqual([200]); + expect(await nextEventId(sub[Symbol.asyncIterator]())).toBe('e1'); + }); + + it('reports truncated and gap bodies through onGap and persists their cursor', async () => { + const onGap = vi.fn(); + const { post, subscribes, subscribe } = await webhookWith(granting({ cursor: 'c5', truncated: true })); + const sub = await subscribe({ cursor: 'c0', onGap }); + + expect(subscribes()[0]!.params['cursor']).toBe('c0'); + expect(onGap).toHaveBeenCalledExactlyOnceWith('c5'); + expect(sub.cursor).toBe('c5'); + + expect(await post({ type: 'gap', cursor: 'c9' })).toBe(200); + expect(onGap).toHaveBeenLastCalledWith('c9'); + expect(sub.cursor).toBe('c9'); + }); + + it('fails the iterator on a terminated body with forbidden, and stops refreshing', async () => { + const { post, subscribes, unsubscribes, subscribe } = await webhookWith(granting({})); + const sub = await subscribe(); + await post({ ...occurrence('e1'), cursor: 'c1' }); + await post({ type: 'terminated', error: { code: -32_024, message: 'Forbidden', data: { reason: 'Access revoked' } } }); + await settle(); + + const iterator = sub[Symbol.asyncIterator](); + expect(await nextEventId(iterator)).toBe('e1'); + const error = await iterator.next().catch((error_: unknown) => error_); + expect(error).toBeInstanceOf(EventsError); + expect(error).toMatchObject({ kind: 'forbidden', data: { reason: 'Access revoked' } }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(120_000); + expect(subscribes()).toHaveLength(1); + expect(await post(occurrence('e2'))).toBe(503); + + // The server no longer holds the subscription, so there is nothing to unsubscribe. + await sub.cancel(); + expect(unsubscribes()).toEqual([]); + }); + + it('resubscribes with the last cursor after a terminated notFound while the event is listed, and fails once it is not', async () => { + const listed = [[tick], [tick], []]; + const { lists, post, subscribes, subscribe } = await webhookWith(granting({ cursor: 'c1' }, { cursor: 'c2' }), { + list: () => ({ events: listed.shift() ?? [] }) + }); + const sub = await subscribe(); + const notFound = { code: -32_023, message: 'Not found', data: { kind: 'event' } }; + + await post({ type: 'terminated', error: notFound }); + await settle(); + expect(lists()).toHaveLength(2); + await vi.advanceTimersByTimeAsync(500); + expect(subscribes()).toHaveLength(2); + expect(subscribes()[1]!.params['cursor']).toBe('c1'); + + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + await post({ type: 'terminated', error: notFound }); + const error = await pending; + expect(error).toBeInstanceOf(EventsError); + expect(error).toMatchObject({ kind: 'notFound', data: { kind: 'event' } }); + expect(lists()).toHaveLength(3); + expect(vi.getTimerCount()).toBe(0); + }); + + it('starts again from now when the server keeps refusing the last cursor after a schema change', async () => { + const onGap = vi.fn(); + const { lists, post, subscribes, subscribe } = await webhookWith( + granting({ cursor: 'c1' }, new RpcError(-32_026, 'Unsupported', schemaChange), { cursor: 'v2:0' }) + ); + const sub = await subscribe({ onGap }); + + await post({ type: 'terminated', error: { code: -32_026, message: 'Unsupported', data: schemaChange } }); + await vi.advanceTimersByTimeAsync(500); + await vi.advanceTimersByTimeAsync(1000); + + expect(subscribes().map(call => call.params['cursor'])).toEqual([null, 'c1', null]); + expect(lists()).toHaveLength(3); + expect(onGap).toHaveBeenCalledExactlyOnceWith('v2:0'); + expect(sub.cursor).toBe('v2:0'); + }); + + it('fails the iterator when a refresh is refused with an Events kind other than notFound or a schema change', async () => { + for (const refusal of [ + new RpcError(-32_024, 'Forbidden'), + new RpcError(-32_602, 'Invalid arguments'), + new RpcError(-32_025, 'Too many subscriptions', { limit: 'subscriptions' }), + new RpcError(-32_026, 'Unsupported', { feature: 'deliveryMode', value: 'webhook' }), + new RpcError(-32_027, 'Callback endpoint error', { reason: 'challenge_failed' }) + ]) { + const { lists, post, subscribes, unsubscribes, subscribe } = await webhookWith(granting({}, refusal)); + const sub = await subscribe(); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + + await vi.advanceTimersByTimeAsync(45_000); + const error = await pending; + expect(error).toBeInstanceOf(EventsError); + expect(error).toMatchObject({ code: refusal.code }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(120_000); + expect(subscribes()).toHaveLength(2); + expect(lists()).toHaveLength(1); + expect(await post(occurrence('e1'))).toBe(503); + // Left to lapse: the next identical subscription could already be on the same server subscription. + await sub.cancel(); + expect(unsubscribes()).toEqual([]); + } + }); + + it('retries a refresh that fails transiently after a jittered delay, with the last cursor', async () => { + const internal = new RpcError(-32_603, 'Internal error'); + const { subscribes, subscribe } = await webhookWith(granting({ cursor: 'c1' }, internal, internal, { cursor: 'c2' }, internal, {})); + const sub = await subscribe(); + await vi.advanceTimersByTimeAsync(45_000); + expect(subscribes()).toHaveLength(2); + + // random() is 0.5: half of min(30 s, 1 s × 2^attempt). + for (const delay of [500, 1000]) { + const before = subscribes().length; + await vi.advanceTimersByTimeAsync(delay - 1); + expect(subscribes()).toHaveLength(before); + await vi.advanceTimersByTimeAsync(1); + expect(subscribes()).toHaveLength(before + 1); + } + expect(subscribes().map(call => call.params['cursor'])).toEqual([null, 'c1', 'c1', 'c1']); + expect(sub.cursor).toBe('c2'); + + // Back on the grant's schedule after the success, and the backoff starts over. + await vi.advanceTimersByTimeAsync(44_999); + expect(subscribes()).toHaveLength(4); + await vi.advanceTimersByTimeAsync(1); + expect(subscribes()).toHaveLength(5); + await vi.advanceTimersByTimeAsync(500); + expect(subscribes()).toHaveLength(6); + }); + + it('waits at most the longest timer before refreshing a far-off or null grant', async () => { + const { subscribes, subscribe } = await webhookWith( + granting({ refreshBefore: '2100-01-01T00:00:00Z' }, { refreshBefore: null }, {}) + ); + await subscribe(); + + for (const count of [2, 3]) { + await vi.advanceTimersByTimeAsync(2_147_483_646); + expect(subscribes()).toHaveLength(count - 1); + await vi.advanceTimersByTimeAsync(1); + expect(subscribes()).toHaveLength(count); + } + }); + + it('never refreshes sooner than pollIntervalFloorMs, even when refreshBefore has already passed', async () => { + // A server clock behind the client's by more than the grant. + const pastDue: Handler = () => grant({ refreshBefore: new Date(Date.now() - 10_000).toISOString() }); + const { subscribes, subscribe } = await webhookWith(pastDue); + await subscribe(); + expect(subscribes()).toHaveLength(1); + + for (const count of [2, 3, 4]) { + await vi.advanceTimersByTimeAsync(999); + expect(subscribes()).toHaveLength(count - 1); + await vi.advanceTimersByTimeAsync(1); + expect(subscribes()).toHaveLength(count); + } + }); + + it('shares one server subscription among identical webhook subscriptions, each with its own iterator', async () => { + const onGap = vi.fn(); + const firstGap = vi.fn(); + const { post, subscribes, subscribe } = await webhookWith(granting({ cursor: 'c1' }, { cursor: 'c4' }, {})); + const first = await subscribe({ arguments: { severity: 'P1', region: 'eu' }, onGap: firstGap }); + // The same arguments in another key order are the same server subscription. + const second = await subscribe({ arguments: { region: 'eu', severity: 'P1' }, cursor: 'old', onGap }); + + expect(subscribes()).toHaveLength(1); + // It joins where the shared subscription is; its own cursor was elsewhere, so events may have been skipped. + expect(onGap).toHaveBeenCalledExactlyOnceWith('c1'); + expect(second.cursor).toBe('c1'); + + expect(await post({ ...occurrence('e1'), cursor: 'c2' })).toBe(200); + expect(await post({ ...occurrence('e1'), cursor: 'c2' })).toBe(200); + expect(await post({ ...occurrence('e2'), cursor: 'c3' })).toBe(200); + // A gap reaches every one of them. + expect(await post({ type: 'gap', cursor: 'g1' })).toBe(200); + expect(firstGap.mock.calls).toEqual([['g1']]); + expect(onGap.mock.calls).toEqual([['c1'], ['g1']]); + const iterators = [first, second].map(sub => sub[Symbol.asyncIterator]()); + for (const iterator of iterators) { + expect([await nextEventId(iterator), await nextEventId(iterator)]).toEqual(['e1', 'e2']); + } + + // One refresh for both; its watermark reaches each once its loop is past e2. Other arguments are another server subscription. + await vi.advanceTimersByTimeAsync(45_000); + expect(subscribes()).toHaveLength(2); + for (const iterator of iterators) void iterator.next(); + expect([first.cursor, second.cursor]).toEqual(['c4', 'c4']); + await subscribe({ arguments: { severity: 'P2' } }); + expect(subscribes()).toHaveLength(3); + }); + + it('cancelling one of two identical webhook subscriptions keeps the other receiving; cancelling the last unsubscribes', async () => { + const { post, subscribes, unsubscribes, subscribe } = await webhookWith(granting({}, {})); + const first = await subscribe(); + const second = await subscribe(); + + await first.cancel(); + expect(unsubscribes()).toEqual([]); + expect(await post({ ...occurrence('e1'), cursor: 'c1' })).toBe(200); + expect(await nextEventId(second[Symbol.asyncIterator]())).toBe('e1'); + + await second.cancel(); + expect(unsubscribes()).toHaveLength(1); + expect(await post(occurrence('e2'))).toBe(503); + expect(vi.getTimerCount()).toBe(0); + + // Subscribing again opens a new server subscription. + await subscribe(); + expect(subscribes()).toHaveLength(2); + }); + + it('ends every identical webhook subscription with the same error on a termination or a close', async () => { + for (const end of ['terminated', 'close'] as const) { + const { client, post, subscribes, subscribe } = await webhookWith(granting({}, {})); + const subs = [await subscribe(), await subscribe()]; + const pending = subs.map(sub => + sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_) + ); + + await (end === 'terminated' ? post({ type: 'terminated', error: { code: -32_024, message: 'Forbidden' } }) : client.close()); + const [one, two] = await Promise.all(pending); + expect(one).toBeInstanceOf(end === 'terminated' ? EventsError : SdkError); + expect(two).toBe(one); + expect(vi.getTimerCount()).toBe(0); + // The next identical subscription opens a new server subscription rather than joining the ended one. + if (end === 'terminated') { + const again = await subscribe(); + expect(subscribes()).toHaveLength(2); + await again.cancel(); + } + } + }); + + it('settles a subscription that joins during the first exchange with that exchange', async () => { + const gate: { refuse?: () => void } = {}; + const { events, subscribes } = await webhookWith( + () => new Promise((_resolve, reject) => (gate.refuse = () => reject(new RpcError(-32_024, 'Forbidden')))) + ); + const one = events.subscribe({ name: 'tick' }).catch((error_: unknown) => error_); + const two = events.subscribe({ name: 'tick' }).catch((error_: unknown) => error_); + await settle(); + expect(subscribes()).toHaveLength(1); + + gate.refuse!(); + const [first, second] = await Promise.all([one, two]); + expect(first).toBeInstanceOf(EventsError); + expect(first).toMatchObject({ kind: 'forbidden' }); + expect(second).toBe(first); + expect(vi.getTimerCount()).toBe(0); + }); + + it('mirrors annotated arguments into Mcp-Param headers on subscribe, refresh and unsubscribe', async () => { + const annotated = descriptor('tick', { + delivery: ['webhook'], + inputSchema: { type: 'object', properties: { region: { type: 'string', 'x-mcp-header': 'Region' } } } + }); + const { subscribes, unsubscribes, subscribe } = await webhookWith(granting({}, {}), { list: listing(annotated) }); + const sub = await subscribe({ arguments: { region: 'us-west1' } }); + await vi.advanceTimersByTimeAsync(45_000); + await sub.cancel(); + + expect([...subscribes(), ...unsubscribes()].map(call => call.headers)).toEqual([ + { 'Mcp-Param-Region': 'us-west1' }, + { 'Mcp-Param-Region': 'us-west1' }, + { 'Mcp-Param-Region': 'us-west1' } + ]); + }); + + it('rejects subscribe() when events/subscribe mismatches Mcp-Param headers again after a re-list', async () => { + const mismatch = new RpcError(-32_020, 'Mcp-Param-Region header mismatch'); + const { events, lists, subscribes } = await webhookWith(granting(mismatch, mismatch)); + const error = await events.subscribe({ name: 'tick' }).catch((error_: unknown) => error_); + + expect(error).toBeInstanceOf(ProtocolError); + expect(error).toMatchObject({ code: -32_020 }); + expect(subscribes()).toHaveLength(2); + expect(lists()).toHaveLength(2); + expect(vi.getTimerCount()).toBe(0); + }); + + it('ends the loop on a refresh that mismatches Mcp-Param headers again after a re-list', async () => { + const mismatch = new RpcError(-32_020, 'Mcp-Param-Region header mismatch'); + const { lists, subscribes, subscribe } = await webhookWith(granting({}, mismatch, mismatch)); + const sub = await subscribe(); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + + await vi.advanceTimersByTimeAsync(45_000); + const error = await pending; + expect(error).toBeInstanceOf(ProtocolError); + expect(error).toMatchObject({ code: -32_020 }); + expect(subscribes()).toHaveLength(3); + expect(lists()).toHaveLength(2); + expect(vi.getTimerCount()).toBe(0); + }); + + it('rejects subscribe() when the first events/subscribe is refused, leaving nothing running', async () => { + const refusals = [ + new RpcError(-32_023, 'Not found', { kind: 'event' }), + new RpcError(-32_602, 'Invalid arguments'), + new RpcError(-32_024, 'Forbidden'), + new RpcError(-32_025, 'Too many subscriptions', { limit: 'subscriptions' }), + new RpcError(-32_026, 'Unsupported', { feature: 'deliveryMode', value: 'webhook' }), + new RpcError(-32_027, 'Callback endpoint error', { reason: 'challenge_failed' }), + // Without a cursor there is no stale one to drop, so a schema change refuses too. + new RpcError(-32_026, 'Unsupported', schemaChange) + ]; + for (const refusal of refusals) { + const { events, handler, lists, subscribes } = await webhookWith(granting(refusal)); + const error = await events.subscribe({ name: 'tick' }).catch((error_: unknown) => error_); + expect(error).toBeInstanceOf(EventsError); + expect(error).toMatchObject({ code: refusal.code }); + expect(vi.getTimerCount()).toBe(0); + + // The receiver no longer holds the secret. + const challenge = await handler( + await webhookPost({ type: 'verification', challenge: 'n' }, secretOf(subscribes()[0]!), 'sub_1') + ); + expect(challenge.status).toBe(401); + await vi.advanceTimersByTimeAsync(120_000); + expect(subscribes()).toHaveLength(1); + expect(lists()).toHaveLength(1); + } + }); + + it('rejects subscribe() on a refreshBefore that is not a date', async () => { + const { events, subscribes } = await webhookWith(granting({ refreshBefore: 'soon' })); + const error = await events.subscribe({ name: 'tick' }).catch((error_: unknown) => error_); + expect(error).toBeInstanceOf(SdkError); + expect(error).toMatchObject({ code: SdkErrorCode.InvalidResult }); + expect(vi.getTimerCount()).toBe(0); + expect(subscribes()).toHaveLength(1); + }); + + it('resolves subscribe() after a transient first failure and subscribes after a jittered delay', async () => { + const { post, subscribes, subscribe } = await webhookWith(granting(new RpcError(-32_603, 'Internal error'), { cursor: 'c1' })); + const sub = await subscribe({ cursor: 'c0' }); + expect(subscribes()).toHaveLength(1); + expect(sub.cursor).toBe('c0'); + + await vi.advanceTimersByTimeAsync(499); + expect(subscribes()).toHaveLength(1); + await vi.advanceTimersByTimeAsync(1); + expect(subscribes()).toHaveLength(2); + expect(subscribes()[1]!.params['cursor']).toBe('c0'); + expect(sub.cursor).toBe('c1'); + expect(await post({ ...occurrence('e1'), cursor: 'c2' })).toBe(200); + expect(await nextEventId(sub[Symbol.asyncIterator]())).toBe('e1'); + }); + + it('drops a stale cursor that the first events/subscribe refuses for a schema change, and starts from now', async () => { + const onGap = vi.fn(); + const { events, lists, subscribes } = await webhookWith( + granting(new RpcError(-32_026, 'Unsupported', { feature: 'inputSchema', reason: 'schema_changed' }), { cursor: 'v2:0' }) + ); + const subscribing = events.subscribe({ name: 'tick', cursor: 'stale', onGap }); + await settle(); + await vi.advanceTimersByTimeAsync(500); + const sub = await subscribing; + subscriptions.push(sub); + + expect(subscribes().map(call => call.params['cursor'])).toEqual(['stale', null]); + expect(lists()).toHaveLength(2); + expect(onGap).toHaveBeenCalledExactlyOnceWith('v2:0'); + expect(sub.cursor).toBe('v2:0'); + }); + + it('rejects subscribe() after a schema change refuses its cursor when the type no longer offers webhook', async () => { + const listed = [[tick], [descriptor('tick', { delivery: ['poll'] })]]; + const { events, subscribes } = await webhookWith(granting(new RpcError(-32_026, 'Unsupported', schemaChange)), { + list: () => ({ events: listed.shift() ?? [] }) + }); + const error = await events.subscribe({ name: 'tick', cursor: 'stale' }).catch((error_: unknown) => error_); + + expect(error).toBeInstanceOf(NoCompatibleDeliveryModeError); + expect(error).toMatchObject({ eventName: 'tick', offered: ['poll'], usable: ['webhook'] }); + expect(subscribes()).toHaveLength(1); + expect(vi.getTimerCount()).toBe(0); + }); + + it('rejects subscribe() with ConnectionClosed when the client closes before events/subscribe answers', async () => { + const { client, events, subscribes } = await webhookWith(granting()); + const subscribing = events.subscribe({ name: 'tick' }).catch((error_: unknown) => error_); + await settle(); + expect(subscribes()).toHaveLength(1); + + await client.close(); + const error = await subscribing; + expect(error).toBeInstanceOf(SdkError); + expect(error).toMatchObject({ code: SdkErrorCode.ConnectionClosed }); + expect(vi.getTimerCount()).toBe(0); + }); + + it('ends the loop with ConnectionClosed when the client closes, releasing the receiver and stopping refreshes', async () => { + const { client, post, subscribes, unsubscribes, subscribe } = await webhookWith(granting({})); + const sub = await subscribe(); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + + await client.close(); + const error = await pending; + expect(error).toBeInstanceOf(SdkError); + expect(error).toMatchObject({ code: SdkErrorCode.ConnectionClosed }); + expect(vi.getTimerCount()).toBe(0); + expect(await post(occurrence('e1'))).toBe(503); + await vi.advanceTimersByTimeAsync(120_000); + expect(subscribes()).toHaveLength(1); + await sub.cancel(); + expect(unsubscribes()).toEqual([]); + }); + + it('ends the loop with ConnectionClosed when the client reconnects without closing', async () => { + const { post, reconnect, subscribes, unsubscribes, subscribe } = await webhookWith(granting({})); + const sub = await subscribe(); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + + await reconnect(); + const error = await pending; + expect(error).toBeInstanceOf(SdkError); + expect(error).toMatchObject({ code: SdkErrorCode.ConnectionClosed }); + expect(vi.getTimerCount()).toBe(0); + expect(await post(occurrence('e1'))).toBe(503); + await vi.advanceTimersByTimeAsync(120_000); + expect(subscribes()).toHaveLength(1); + // Subscribing again on the new connection would reach the same server subscription; cancel() leaves it alone. + await sub.cancel(); + expect(unsubscribes()).toEqual([]); + }); +}); From 28a20febd6010dcef468c84bf72b8ba2a60c4881 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 17:41:40 +0200 Subject: [PATCH 21/37] fix(client): serialize identical webhook subscriptions and release only own binding --- packages/client/src/ext/events/receiver.ts | 6 +- packages/client/src/ext/events/webhook.ts | 40 +++++++--- .../client/test/ext/events/receiver.test.ts | 13 +++- packages/client/test/ext/events/scripted.ts | 39 +++++----- .../client/test/ext/events/webhook.test.ts | 77 ++++++++++++++++++- 5 files changed, 142 insertions(+), 33 deletions(-) diff --git a/packages/client/src/ext/events/receiver.ts b/packages/client/src/ext/events/receiver.ts index b37173724d..1b443aa518 100644 --- a/packages/client/src/ext/events/receiver.ts +++ b/packages/client/src/ext/events/receiver.ts @@ -87,9 +87,9 @@ export class WebhookReceiver { this.#bound.set(id, { key: keyOf(secret), sink }); } - // Stops routing `id`; its deliveries are answered 503 from now on. - forget(id: string): void { - this.#bound.delete(id); + // Stops routing `id` to `sink`, answering its deliveries 503 from now on; a binding another sink has taken over stays. + forget(id: string, sink: WebhookSink): void { + if (this.#bound.get(id)?.sink === sink) this.#bound.delete(id); } async handle(request: Request): Promise { diff --git a/packages/client/src/ext/events/webhook.ts b/packages/client/src/ext/events/webhook.ts index 9ce74d6083..814e464ddc 100644 --- a/packages/client/src/ext/events/webhook.ts +++ b/packages/client/src/ext/events/webhook.ts @@ -28,6 +28,8 @@ export class WebhookSubscriptions { readonly #receiver: WebhookReceiver; readonly #floorMs: number; readonly #open = new Map(); + // By key, until it settles: the stop (unsubscribe, then release) of the last one that ended, which the next identical one waits for. + readonly #stopping = new Map>(); constructor(webhook: WebhookOptions, receiver: WebhookReceiver, floorMs: number) { this.#webhook = webhook; @@ -40,8 +42,16 @@ export class WebhookSubscriptions { const key = canonicalJson([context.subscription.name, context.subscription.arguments ?? {}]); let shared = this.#open.get(key); if (shared === undefined) { - const opened = new SharedWebhook(context, this.#webhook, this.#receiver, this.#floorMs, () => { - if (this.#open.get(key) === opened) this.#open.delete(key); + const after = this.#stopping.get(key) ?? Promise.resolve(); + const opened = new SharedWebhook(context, this.#webhook, this.#receiver, this.#floorMs, after, stopping => { + // Already taken out by a failure, which leaves nothing to unsubscribe. + if (this.#open.get(key) !== opened) return; + this.#open.delete(key); + if (stopping === undefined) return; + this.#stopping.set(key, stopping); + void stopping.then(() => { + if (this.#stopping.get(key) === stopping) this.#stopping.delete(key); + }); }); this.#open.set(key, opened); shared = opened; @@ -55,17 +65,27 @@ class SharedWebhook { readonly #members = new Set>(); readonly #connection: EventsConnection; readonly #driver: WebhookDriver; - // Takes this one out of the open subscriptions, so the next identical subscribe opens a new one. - readonly #close: () => void; + // Settles once the previous identical one has stopped, so the server sees its `events/unsubscribe` before this one's `events/subscribe`. + readonly #after: Promise; + // Takes this one out of the open subscriptions, so the next identical subscribe opens a new one (after `stopping`, when given). + readonly #close: (stopping?: Promise) => void; // Where delivery is: the first subscription's cursor until the server reports one. #cursor: string | null; #deliveryStatus: DeliveryStatus | undefined; #started: Promise | undefined; - constructor(first: DriverContext, webhook: WebhookOptions, receiver: WebhookReceiver, floorMs: number, close: () => void) { + constructor( + first: DriverContext, + webhook: WebhookOptions, + receiver: WebhookReceiver, + floorMs: number, + after: Promise, + close: (stopping?: Promise) => void + ) { const { connection, subscription } = first; const members = this.#members; this.#connection = connection; + this.#after = after; this.#close = close; this.#cursor = subscription.cursor ?? null; const queue: DeliveryQueue = { @@ -98,7 +118,7 @@ class SharedWebhook { this.#members.add(context); return { start: async () => { - this.#started ??= this.#driver.start(); + this.#started ??= this.#after.then(() => this.#driver.start()); await this.#started; if (!late) return; // It starts where the shared subscription is; a cursor of its own anywhere else may have skipped events. @@ -109,8 +129,10 @@ class SharedWebhook { }, stop: async () => { if (!this.#members.delete(context) || this.#members.size > 0) return; - this.#close(); - await this.#driver.stop(); + const stopping = this.#driver.stop(); + // Settles however the unsubscribe ends (answered, refused, failed, or the client closed). + this.#close(stopping.catch(() => {})); + await stopping; } }; } @@ -276,7 +298,7 @@ class WebhookDriver implements Driver { // The receiver stops routing deliveries here and forgets the secret. #release(): void { this.#withdrawPending?.(); - if (this.#id !== undefined) this.#receiver.forget(this.#id); + if (this.#id !== undefined) this.#receiver.forget(this.#id, this.#sink); this.#id = undefined; } } diff --git a/packages/client/test/ext/events/receiver.test.ts b/packages/client/test/ext/events/receiver.test.ts index e825204041..7a9b74225d 100644 --- a/packages/client/test/ext/events/receiver.test.ts +++ b/packages/client/test/ext/events/receiver.test.ts @@ -133,11 +133,22 @@ describe('WebhookReceiver', () => { expect(target.event).not.toHaveBeenCalled(); expect(await status(webhookPost(event, secret, 'sub_1', { timestamp: now() - 300 }))).toBe(200); - receiver.forget('sub_1'); + receiver.forget('sub_1', target); expect(await status(webhookPost(occurrence('e2'), secret, 'sub_1'))).toBe(503); expect(target.event).toHaveBeenCalledOnce(); }); + it('forgets an id only for the sink it routes to', async () => { + const { receiver, secret, target } = bound(); + // A subscription that ended after another one took over the same id. + receiver.forget('sub_1', sink()); + expect(await statusOf(receiver, webhookPost(occurrence('e1'), secret, 'sub_1'))).toBe(200); + expect(target.event).toHaveBeenCalledOnce(); + + receiver.forget('sub_1', target); + expect(await statusOf(receiver, webhookPost(occurrence('e2'), secret, 'sub_1'))).toBe(503); + }); + it('rejects non-POST and oversized bodies', async () => { const { receiver, secret, target } = bound(); const get = await receiver.handle(new Request(WEBHOOK_URL, { method: 'GET' })); diff --git a/packages/client/test/ext/events/scripted.ts b/packages/client/test/ext/events/scripted.ts index 15fce2d373..600c7a02e5 100644 --- a/packages/client/test/ext/events/scripted.ts +++ b/packages/client/test/ext/events/scripted.ts @@ -110,24 +110,27 @@ export async function scriptedClient(handlers: Record, options: notifications.push({ method: request.method, params: (request.params ?? {}) as Record }); return; } - void answer(request).then( - result => - server.send({ - jsonrpc: '2.0', - id: request.id, - result: revision === MODERN ? { resultType: 'complete', ...result } : result - }), - (error: unknown) => - server.send({ - jsonrpc: '2.0', - id: request.id, - error: { - code: error instanceof RpcError ? error.code : -32_603, - message: error instanceof Error ? error.message : String(error), - ...(error instanceof RpcError && error.data !== undefined && { data: error.data }) - } - }) - ); + void answer(request) + .then( + result => + server.send({ + jsonrpc: '2.0', + id: request.id, + result: revision === MODERN ? { resultType: 'complete', ...result } : result + }), + (error: unknown) => + server.send({ + jsonrpc: '2.0', + id: request.id, + error: { + code: error instanceof RpcError ? error.code : -32_603, + message: error instanceof Error ? error.message : String(error), + ...(error instanceof RpcError && error.data !== undefined && { data: error.data }) + } + }) + ) + // An answer that comes after the client closed has no one to go to. + .catch(() => {}); }; await server.start(); return transport; diff --git a/packages/client/test/ext/events/webhook.test.ts b/packages/client/test/ext/events/webhook.test.ts index ce0d158b25..fe4c4a5329 100644 --- a/packages/client/test/ext/events/webhook.test.ts +++ b/packages/client/test/ext/events/webhook.test.ts @@ -49,10 +49,14 @@ function granting(...answers: Array | RpcError>): Handle }; } -async function webhookWith(subscribe: Handler, options: { list?: Handler; secretProvider?: () => string } = {}) { +async function webhookWith(subscribe: Handler, options: { list?: Handler; unsubscribe?: Handler; secretProvider?: () => string } = {}) { const { secretProvider } = options; const scripted = await connectEvents( - { 'events/list': options.list ?? listing(tick), 'events/subscribe': subscribe, 'events/unsubscribe': () => ({}) }, + { + 'events/list': options.list ?? listing(tick), + 'events/subscribe': subscribe, + 'events/unsubscribe': options.unsubscribe ?? (() => ({})) + }, { events: { webhook: { url: WEBHOOK_URL, ...(secretProvider !== undefined && { secretProvider }) } } } ); const handler = scripted.events.createWebhookHandler(); @@ -77,6 +81,26 @@ async function webhookWith(subscribe: Handler, options: { list?: Handler; secret }; } +/** A webhook client whose `events/unsubscribe` answers wait until the test gives them, and come at once after `answerAll()`. */ +async function heldUnsubscribe() { + const held: Array<(answer: Record | RpcError) => void> = []; + let holding = true; + const scripted = await webhookWith(granting({}, {}), { + unsubscribe: () => + holding + ? new Promise((resolve, reject) => held.push(answer => (answer instanceof RpcError ? reject(answer) : resolve(answer)))) + : {} + }); + const unsubscribe = { + answer: (answer: Record | RpcError) => held.shift()!(answer), + answerAll: () => { + holding = false; + for (const answer of held.splice(0)) answer({}); + } + }; + return { ...scripted, unsubscribe }; +} + describe('webhook delivery', () => { it('subscribes with a generated whsec_ secret and refreshes at ¾ of the grant', async () => { const { subscribes, subscribe } = await webhookWith(granting({ cursor: 'c1' }, { cursor: 'c2' }, { id: 'sub_2' })); @@ -416,6 +440,55 @@ describe('webhook delivery', () => { expect(subscribes()).toHaveLength(2); }); + it('opens an identical subscription only once an un-awaited cancel() has unsubscribed, however that is answered', async () => { + for (const answer of [{}, new RpcError(-32_023, 'Not found', { kind: 'subscription' })]) { + const { calls, post, subscribe, unsubscribe } = await heldUnsubscribe(); + try { + const old = await subscribe(); + const cancelling = old.cancel(); + const subscribing = subscribe(); + await settle(); + // Nothing goes out for the new one while the old events/unsubscribe is unanswered. + expect(calls.map(call => call.method)).toEqual(['events/list', 'events/subscribe', 'events/unsubscribe']); + + unsubscribe.answer(answer); + await cancelling; + const fresh = await subscribing; + expect(calls.map(call => call.method)).toEqual([ + 'events/list', + 'events/subscribe', + 'events/unsubscribe', + 'events/subscribe' + ]); + // Bound after the old one released the id: delivered, not 503. + expect(await post({ ...occurrence('e1'), cursor: 'c1' })).toBe(200); + expect(await nextEventId(fresh[Symbol.asyncIterator]())).toBe('e1'); + } finally { + unsubscribe.answerAll(); + } + } + }); + + it('ends an identical subscription waiting on an un-awaited cancel() with ConnectionClosed when the client closes', async () => { + const { calls, client, events, subscribe, unsubscribe } = await heldUnsubscribe(); + try { + const old = await subscribe(); + const cancelling = old.cancel(); + const subscribing = events.subscribe({ name: 'tick' }).catch((error_: unknown) => error_); + await settle(); + + await client.close(); + await cancelling; + const error = await subscribing; + expect(error).toBeInstanceOf(SdkError); + expect(error).toMatchObject({ code: SdkErrorCode.ConnectionClosed }); + expect(calls.map(call => call.method)).toEqual(['events/list', 'events/subscribe', 'events/unsubscribe']); + expect(vi.getTimerCount()).toBe(0); + } finally { + unsubscribe.answerAll(); + } + }); + it('ends every identical webhook subscription with the same error on a termination or a close', async () => { for (const end of ['terminated', 'close'] as const) { const { client, post, subscribes, subscribe } = await webhookWith(granting({}, {})); From a387a3400a9b615a6632b4fc5e7ebf65b06b2fa4 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 18:29:10 +0200 Subject: [PATCH 22/37] fix(server): gate events on the session's era and defer module-scope Workers-unsafe state --- packages/server/src/ext/events/emitBuffer.ts | 14 +++++--- packages/server/src/ext/events/eraGate.ts | 11 +++--- packages/server/src/ext/events/extension.ts | 34 +++++++++++++------ packages/server/src/ext/events/validation.ts | 4 +-- .../server/src/ext/events/webhookEngine.ts | 9 ++--- .../src/ext/events/webhookSubscriptions.ts | 11 ++++-- 6 files changed, 53 insertions(+), 30 deletions(-) diff --git a/packages/server/src/ext/events/emitBuffer.ts b/packages/server/src/ext/events/emitBuffer.ts index 27b950ff89..a990f6d1cb 100644 --- a/packages/server/src/ext/events/emitBuffer.ts +++ b/packages/server/src/ext/events/emitBuffer.ts @@ -37,7 +37,8 @@ export class EmitBuffer { readonly #maxEvents: number; readonly #now: () => number; readonly #rings = new Map(); - #epoch = newEpoch(); + // Drawn at first use: Cloudflare Workers refuse random values at module scope, where an extension is built. + #epoch: string | undefined; constructor(limits: { maxAgeMs: number; maxEvents: number }, now: () => number = () => Date.now()) { this.#maxAgeMs = limits.maxAgeMs; @@ -110,7 +111,7 @@ export class EmitBuffer { // Drops every event and starts a new epoch, as a process restart would. clear(): void { this.#rings.clear(); - this.#epoch = newEpoch(); + this.#epoch = undefined; } #evict(ring: Ring): void { @@ -122,13 +123,18 @@ export class EmitBuffer { ring.evicted += drop; } + #currentEpoch(): string { + this.#epoch ??= newEpoch(); + return this.#epoch; + } + #format(sequence: number): string { - return `e${this.#epoch}.${sequence}`; + return `e${this.#currentEpoch()}.${sequence}`; } #parse(cursor: string): number | undefined { const match = CURSOR.exec(cursor); - if (match === null || match[1] !== this.#epoch) return undefined; + if (match === null || match[1] !== this.#currentEpoch()) return undefined; const sequence = Number(match[2]); return Number.isSafeInteger(sequence) ? sequence : undefined; } diff --git a/packages/server/src/ext/events/eraGate.ts b/packages/server/src/ext/events/eraGate.ts index 20053a6074..8f5fb96dec 100644 --- a/packages/server/src/ext/events/eraGate.ts +++ b/packages/server/src/ext/events/eraGate.ts @@ -1,9 +1,10 @@ -import type { ServerContext } from '@modelcontextprotocol/core-internal'; -import { isModernProtocolVersion, PROTOCOL_VERSION_META_KEY, ProtocolError, ProtocolErrorCode } from '@modelcontextprotocol/core-internal'; +import { isModernProtocolVersion, ProtocolError, ProtocolErrorCode } from '@modelcontextprotocol/core-internal'; -// Events is served only on 2026-07-28 and later: a request without a modern envelope gets -32601. -export function assertModernRequest(ctx: ServerContext): void { - if (!isModernProtocolVersion(ctx.mcpReq.envelope?.[PROTOCOL_VERSION_META_KEY] ?? '')) { +import type { Server } from '../../server/server'; + +// Events is served only on 2026-07-28 and later: a server bound to an earlier revision answers -32601, whatever a request's `_meta` claims. +export function assertModernServer(server: Server): void { + if (!isModernProtocolVersion(server.getNegotiatedProtocolVersion() ?? '')) { throw new ProtocolError(ProtocolErrorCode.MethodNotFound, 'Method not found'); } } diff --git a/packages/server/src/ext/events/extension.ts b/packages/server/src/ext/events/extension.ts index 3baeff45bb..7d9f68214d 100644 --- a/packages/server/src/ext/events/extension.ts +++ b/packages/server/src/ext/events/extension.ts @@ -19,10 +19,11 @@ import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; import type { McpServer } from '../../server/mcp'; import { markModernOnlyExtension } from '../../server/modernOnlyExtensions'; import { registerParamHeaderSource } from '../../server/paramHeaderSources'; +import type { Server } from '../../server/server'; import { markStreamingMethod } from '../../server/streamingMethods'; import type { BufferedEvent } from './emitBuffer'; import { EmitBuffer } from './emitBuffer'; -import { assertModernRequest } from './eraGate'; +import { assertModernServer } from './eraGate'; import { PollSource, toOccurrence } from './poll'; import { StreamSet } from './push'; import type { AnyEventDefinition, RegisteredEvent } from './registry'; @@ -240,8 +241,8 @@ export class EventsExtension { * server: attaching another one throws and leaves the server as it was, * as does attaching to a server that already handles one of the * `events/*` methods. A legacy `initialize` result does not advertise - * Events, and `events/*` requests without a `2026-07-28` envelope are - * answered `-32601`. + * Events, and a server serving an earlier revision than `2026-07-28` + * answers `events/*` requests with `-32601`. * * Experimental: Events (SEP-3415) is new; this API may change in a minor release. * @@ -254,18 +255,24 @@ export class EventsExtension { const server = mcp.server; // Check before changing anything; declare the capability last, so a server never advertises events it does not serve. for (const method of EVENTS_METHODS) server.assertCanSetRequestHandler(method); - server.setRequestHandler(EVENTS_LIST_METHOD, { params: ListEventsRequestParamsSchema }, (_params, ctx) => this.#list(ctx)); + server.setRequestHandler(EVENTS_LIST_METHOD, { params: ListEventsRequestParamsSchema }, () => + this.#modernOnly(server, () => this.#list()) + ); server.setRequestHandler(EVENTS_POLL_METHOD, { params: PollEventsRequestParamsSchema }, (params, ctx) => - this.#poll.handlePoll(params, ctx) + this.#modernOnly(server, () => this.#poll.handlePoll(params, ctx)) ); server.setRequestHandler(EVENTS_STREAM_METHOD, { params: StreamEventsRequestParamsSchema }, (params, ctx) => - this.#push.open(params, ctx) + this.#modernOnly(server, () => this.#push.open(params, ctx)) ); server.setRequestHandler(EVENTS_SUBSCRIBE_METHOD, { params: SubscribeEventsRequestParamsSchema }, (params, ctx) => - this.#webhooks === undefined ? this.#refuseWebhook(params, ctx) : this.#webhooks.subscribe(params, ctx) + this.#modernOnly(server, () => + this.#webhooks === undefined ? this.#refuseWebhook(params, ctx) : this.#webhooks.subscribe(params, ctx) + ) ); server.setRequestHandler(EVENTS_UNSUBSCRIBE_METHOD, { params: UnsubscribeEventsRequestParamsSchema }, (params, ctx) => - this.#webhooks === undefined ? this.#refuseWebhook(params, ctx) : this.#webhooks.unsubscribe(params, ctx) + this.#modernOnly(server, () => + this.#webhooks === undefined ? this.#refuseWebhook(params, ctx) : this.#webhooks.unsubscribe(params, ctx) + ) ); server.registerCapabilities({ extensions: { [EVENTS_EXTENSION_ID]: {} } }); markModernOnlyExtension(server, EVENTS_EXTENSION_ID); @@ -336,14 +343,19 @@ export class EventsExtension { return emitOnly; } - // Without webhook mode the shared checks refuse every webhook request: the era gate, then `unsupported`. + // Runs `serve` only on a server bound to 2026-07-28 or later; the request's `_meta` envelope does not decide. + #modernOnly(server: Server, serve: () => T): T { + assertModernServer(server); + return serve(); + } + + // Without webhook mode the shared checks refuse every webhook request with `unsupported`. async #refuseWebhook(params: SubscriptionRequest, ctx: ServerContext): Promise { await this.#validator.validate('webhook', params, ctx); throw new TypeError('webhook mode is off, yet validate() accepted a webhook request'); } - #list(ctx: ServerContext): ListEventsResult { - assertModernRequest(ctx); + #list(): ListEventsResult { return { events: this.#registry.list().map(entry => this.#describe(entry)) }; } diff --git a/packages/server/src/ext/events/validation.ts b/packages/server/src/ext/events/validation.ts index 7f4e6c22b7..edf256220b 100644 --- a/packages/server/src/ext/events/validation.ts +++ b/packages/server/src/ext/events/validation.ts @@ -2,7 +2,6 @@ import type { DeliveryMode } from '@modelcontextprotocol/core/ext/events'; import type { ServerContext } from '@modelcontextprotocol/core-internal'; import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; -import { assertModernRequest } from './eraGate'; import type { EventRegistry, RegisteredEvent } from './registry'; import type { EventsOptions } from './types'; @@ -38,14 +37,13 @@ export class SubscriptionValidator { this.#deps = deps; } - // Era gate, webhook mode (webhook only), principal (required for webhook), event exists, mode offered, `beforeParse`, then the arguments. + // After the era gate in `attach`: webhook mode (webhook only), principal (required for webhook), event exists, mode offered, `beforeParse`, then the arguments. async validate( mode: DeliveryMode, params: SubscriptionRequest, ctx: ServerContext, beforeParse?: (principal: string | null, rawArgs: Record) => void ): Promise { - assertModernRequest(ctx); const webhook = mode === 'webhook'; if (webhook && !this.#deps.webhookEnabled) throw notOffered('This server does not offer webhook delivery', mode); const principal = (await this.#deps.getPrincipal?.(ctx)) ?? null; diff --git a/packages/server/src/ext/events/webhookEngine.ts b/packages/server/src/ext/events/webhookEngine.ts index c3ad39a061..462f38dfa2 100644 --- a/packages/server/src/ext/events/webhookEngine.ts +++ b/packages/server/src/ext/events/webhookEngine.ts @@ -142,8 +142,8 @@ export class WebhookEngine { // Each verified `principal\0url` with the subscription ids it covers; it lasts while one of them does. readonly #verified = new Map>(); readonly #verifiedKeyOf = new Map(); - // Aborts verification sends in flight on clear(). - #lifetime = new AbortController(); + // Aborts verification sends in flight on clear(); made at first use, as Cloudflare Workers refuse it at module scope. + #lifetime: AbortController | undefined; constructor(options: WebhookEngineOptions) { this.#sender = options.sender; @@ -166,6 +166,7 @@ export class WebhookEngine { const challenge = challengeNonce(); const body = JSON.stringify({ type: 'verification', challenge }); const webhookId = generateWebhookId('verification'); + this.#lifetime ??= new AbortController(); const outcome = await this.#post(url, subscriptionId, [secret], webhookId, body, this.#lifetime.signal); if ('error' in outcome) throw verificationError(outcome.error); if (!echoes(outcome, challenge)) throw verificationError('challenge_failed'); @@ -259,8 +260,8 @@ export class WebhookEngine { for (const control of this.#controls) this.#stopControl(control); this.#verified.clear(); this.#verifiedKeyOf.clear(); - this.#lifetime.abort(); - this.#lifetime = new AbortController(); + this.#lifetime?.abort(); + this.#lifetime = undefined; } #start(id: string, watermark: string | null): Tracked { diff --git a/packages/server/src/ext/events/webhookSubscriptions.ts b/packages/server/src/ext/events/webhookSubscriptions.ts index 84547810ff..a2736eb0f1 100644 --- a/packages/server/src/ext/events/webhookSubscriptions.ts +++ b/packages/server/src/ext/events/webhookSubscriptions.ts @@ -26,8 +26,13 @@ const ROTATION_GRACE_MS = 300_000; const MAX_TIMER_DELAY_MS = 2 ** 31 - 1; const encoder = new TextEncoder(); -// The `signal` of callbacks for a stored subscription this process does not watch. -const UNWATCHED = new AbortController().signal; +let unwatched: AbortSignal | undefined; + +// The `signal` of callbacks for a stored subscription this process does not watch; made at first use, as Cloudflare Workers refuse it at module scope. +function unwatchedSignal(): AbortSignal { + unwatched ??= new AbortController().signal; + return unwatched; +} export interface WebhookDeps { readonly validator: SubscriptionValidator; @@ -496,7 +501,7 @@ export class WebhookSubscriptions implements SubscriptionSource { this.#later(record.id, () => this.#recheck(record.id)); continue; } - const ctx = this.#watched.get(record.id)?.ctx ?? this.#contextOf(record, UNWATCHED); + const ctx = this.#watched.get(record.id)?.ctx ?? this.#contextOf(record, unwatchedSignal()); const occurrence = selectEvent(entry, ctx, record.arguments, buffered, this.#deps.report); if (occurrence !== undefined) this.#engine.deliver(record, occurrence, cursor, previous); } From 3bd3c4d462e36ab7970cd6653781baf198ce3feb Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 18:29:10 +0200 Subject: [PATCH 23/37] test: Events integration and wire-behaviour suites --- .../test/__fixtures__/eventsStdioServer.ts | 137 +++ .../test/events/eventsEndToEnd.test.ts | 790 ++++++++++++++++++ .../test/events/eventsWire.test.ts | 293 +++++++ .../test/server/cloudflareWorkers.test.ts | 18 +- 4 files changed, 1237 insertions(+), 1 deletion(-) create mode 100644 test/integration/test/__fixtures__/eventsStdioServer.ts create mode 100644 test/integration/test/events/eventsEndToEnd.test.ts create mode 100644 test/integration/test/events/eventsWire.test.ts diff --git a/test/integration/test/__fixtures__/eventsStdioServer.ts b/test/integration/test/__fixtures__/eventsStdioServer.ts new file mode 100644 index 0000000000..79460c957e --- /dev/null +++ b/test/integration/test/__fixtures__/eventsStdioServer.ts @@ -0,0 +1,137 @@ +/** + * An events server: one `EventsExtension` with an emit-only event type + * (`note.posted`) and a check-function one (`ticket.updated`), plus tools that + * drive it and report its subscription hooks. Run as a script, it serves over + * stdio through the dual-era `serveStdio` entry (spawned by + * `test/events/eventsEndToEnd.test.ts`); that suite also imports + * {@linkcode eventsFixture} to build the same server in process for its HTTP + * and in-memory arms. + */ +import { realpathSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; + +import { McpServer } from '@modelcontextprotocol/server'; +import type { EmitOnlyEventHandle, EventContext, EventsOptions } from '@modelcontextprotocol/server/ext/events'; +import { EventsError, EventsExtension } from '@modelcontextprotocol/server/ext/events'; +import { serveStdio } from '@modelcontextprotocol/server/stdio'; +import * as z from 'zod/v4'; + +export const NOTE = 'note.posted'; +export const TICKET = 'ticket.updated'; +// The push heartbeat every subscription is granted. +export const HEARTBEAT_MS = 500; +// How many emitted notes the poll and replay buffer keeps. +export const BUFFERED_NOTES = 3; +// How many tickets one check returns; more set `hasMore`. +const TICKET_PAGE = 2; + +export interface HookEntry { + hook: 'subscribe' | 'unsubscribe'; + name: string; + mode: EventContext['mode']; + tag: string; + subscriptionId: string; +} + +export interface EventsFixture { + readonly note: EmitOnlyEventHandle<{ tag: string; text: string }>; + // Every onSubscribe and onUnsubscribe call, in order. + readonly log: readonly HookEntry[]; + // Attaches the extension, and the tools that drive it, to one server. + attach(mcp: McpServer): void; +} + +// Every subscription names a tag, so tests sharing one server see only their own events and hooks. +const TagArgs = z.object({ tag: z.string() }); + +// Builds the extension with `options` (webhook delivery, a store) on top of the fixture's own. +export function eventsFixture(options: EventsOptions = {}): EventsFixture { + const events = new EventsExtension({ + heartbeatMs: HEARTBEAT_MS, + defaultNextPollMs: 50, + emitBuffer: { maxEvents: BUFFERED_NOTES }, + ...options + }); + const log: HookEntry[] = []; + const tickets = new Map(); + const hooks = { + onSubscribe: (ctx: EventContext, { tag }: { tag: string }) => { + log.push({ hook: 'subscribe', name: ctx.name, mode: ctx.mode, tag, subscriptionId: ctx.subscriptionId }); + }, + onUnsubscribe: (ctx: EventContext, { tag }: { tag: string }) => { + log.push({ hook: 'unsubscribe', name: ctx.name, mode: ctx.mode, tag, subscriptionId: ctx.subscriptionId }); + } + }; + const note = events.registerEvent(NOTE, { + emitOnly: true, + inputSchema: TagArgs, + payloadSchema: z.object({ tag: z.string(), text: z.string() }), + match: (_ctx, event, { tag }) => event.data.tag === tag, + ...hooks + }); + // The upstream is a list per tag; a cursor is the index of the next ticket. + const ticket = events.registerEvent(TICKET, { + inputSchema: TagArgs, + payloadSchema: z.object({ tag: z.string(), title: z.string() }), + check: (_ctx, { tag }, cursor) => { + const upstream = tickets.get(tag) ?? []; + if (cursor === null) return { events: [], cursor: String(upstream.length) }; + const from = Number(cursor); + const page = upstream.slice(from, from + TICKET_PAGE); + const next = from + page.length; + return { + events: page.map((title, index) => ({ eventId: `${tag}-${from + index}`, data: { tag, title } })), + cursor: String(next), + hasMore: next < upstream.length, + nextPollMs: 60_000 + }; + }, + ...hooks + }); + + const attach = (mcp: McpServer): void => { + events.attach(mcp); + mcp.registerTool('emit', { inputSchema: z.object({ tag: z.string(), texts: z.array(z.string()) }) }, async ({ tag, texts }) => { + for (const text of texts) await note.emit({ data: { tag, text } }); + return { content: [] }; + }); + mcp.registerTool('append', { inputSchema: z.object({ tag: z.string(), titles: z.array(z.string()) }) }, ({ tag, titles }) => { + tickets.set(tag, [...(tickets.get(tag) ?? []), ...titles]); + return { content: [] }; + }); + mcp.registerTool( + 'terminate', + { inputSchema: z.object({ name: z.string(), tag: z.string(), mode: z.enum(['poll', 'push']) }) }, + async ({ name, tag, mode }) => { + const entry = log.findLast(e => e.hook === 'subscribe' && e.name === name && e.tag === tag && e.mode === mode); + if (entry === undefined) throw new Error(`no ${mode} subscription to ${name} with tag ${tag}`); + const handle = name === NOTE ? note : ticket; + await handle.terminate(new EventsError('forbidden', 'Access revoked'), { subscriptionId: entry.subscriptionId }); + return { content: [] }; + } + ); + mcp.registerTool('hooks', { inputSchema: TagArgs }, ({ tag }) => ({ + content: [{ type: 'text', text: JSON.stringify(log.filter(entry => entry.tag === tag)) }] + })); + }; + return { note, log, attach }; +} + +// Run as a script (not imported): serve one stdio connection. +if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) { + const { attach } = eventsFixture(); + const handle = serveStdio(() => { + const mcp = new McpServer({ name: 'events-stdio-fixture', version: '1.0.0' }); + attach(mcp); + return mcp; + }); + + const exit = async () => { + await handle.close(); + // eslint-disable-next-line unicorn/no-process-exit + process.exit(0); + }; + + process.on('SIGINT', exit); + process.on('SIGTERM', exit); +} diff --git a/test/integration/test/events/eventsEndToEnd.test.ts b/test/integration/test/events/eventsEndToEnd.test.ts new file mode 100644 index 0000000000..fabac84d7d --- /dev/null +++ b/test/integration/test/events/eventsEndToEnd.test.ts @@ -0,0 +1,790 @@ +/** + * Events (SEP-3415) end to end, through public import paths only: a real + * `Client` with `EventsClientExtension` against a real `McpServer` with + * `EventsExtension`, over HTTP (`createMcpHandler`, `fetch` wired to the + * handler), stdio (a child process) and in memory (`serveStdio` over an + * `InMemoryTransport`), in every delivery mode. Webhook, replica and restart + * cases run over HTTP. + */ +import type { Server as HttpServer } from 'node:http'; +import { createServer } from 'node:http'; +import path from 'node:path'; + +import type { JSONRPCMessage } from '@modelcontextprotocol/client'; +import { + Client, + CLIENT_CAPABILITIES_META_KEY, + CLIENT_INFO_META_KEY, + InMemoryTransport, + PROTOCOL_VERSION_META_KEY, + SdkError, + SdkErrorCode, + StreamableHTTPClientTransport, + SUBSCRIPTION_ID_META_KEY +} from '@modelcontextprotocol/client'; +import type { EventsClientOptions, EventSubscription } from '@modelcontextprotocol/client/ext/events'; +import { EVENTS_EXTENSION_ID, EventsClientExtension, EventsError } from '@modelcontextprotocol/client/ext/events'; +import { StdioClientTransport } from '@modelcontextprotocol/client/stdio'; +import type { AuthInfo, CreateMcpHandlerOptions, McpHttpHandler } from '@modelcontextprotocol/server'; +import { createMcpHandler, McpServer } from '@modelcontextprotocol/server'; +import type { EventsOptions, WebhookSender } from '@modelcontextprotocol/server/ext/events'; +import { EventsError as ServerEventsError, InMemoryWebhookSubscriptionStore } from '@modelcontextprotocol/server/ext/events'; +import { nodeWebhookSender } from '@modelcontextprotocol/server/ext/events/node'; +import { serveStdio } from '@modelcontextprotocol/server/stdio'; +import { listenOnRandomPort } from '@modelcontextprotocol/test-helpers'; +import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'; +import * as z from 'zod/v4'; + +import type { EventsFixture, HookEntry } from '../__fixtures__/eventsStdioServer'; +import { BUFFERED_NOTES, eventsFixture, HEARTBEAT_MS, NOTE, TICKET } from '../__fixtures__/eventsStdioServer'; + +const LEGACY = '2025-11-25'; +const MODERN = '2026-07-28'; +const FIXTURES_DIR = path.resolve(__dirname, '../__fixtures__'); +const Loose = z.looseObject({}); +const HOOK_URL = 'https://hooks.example.com/mcp/events'; +const ALICE: AuthInfo = { token: 'alice-token', clientId: 'events-host', scopes: [], extra: { sub: 'alice' } }; +const SECRET = `whsec_${btoa('a'.repeat(32))}`; +const ROTATED = `whsec_${btoa('b'.repeat(32))}`; +// The client polls as often as the fixture's nextPollMs (50 ms) asks. +const CLIENT_OPTIONS: EventsClientOptions = { pollIntervalFloorMs: 20 }; + +type Arm = 'http' | 'stdio' | 'inMemory'; +type Note = { tag: string; text: string }; + +interface Connection { + readonly client: Client; + readonly events: EventsClientExtension; + // Every message the client's transport received and sent after connecting. + readonly received: JSONRPCMessage[]; + readonly sent: JSONRPCMessage[]; + close(): Promise; +} + +interface HttpConnection extends Connection { + // Each HTTP request, by the handler that served it and its Mcp-Method header. + readonly requests: Array<{ handler: McpHttpHandler; method: string | null }>; + // Ends every open events/stream response, as a dropped connection does. + dropStreams(): void; +} + +function clientFor(revision: string): Client { + return new Client( + { name: 'events-host', version: '1.0.0' }, + revision === MODERN ? { versionNegotiation: { mode: { pin: MODERN } } } : {} + ); +} + +// Records what the client's transport receives and sends from now on. +function tap(client: Client): Pick { + const transport = client.transport!; + const received: JSONRPCMessage[] = []; + const sent: JSONRPCMessage[] = []; + const onmessage = transport.onmessage; + transport.onmessage = (message, extra) => { + received.push(message); + onmessage?.(message, extra); + }; + const send = transport.send.bind(transport); + transport.send = (message, options) => { + sent.push(message); + return send(message, options); + }; + return { received, sent }; +} + +function handlerFor(attach: (mcp: McpServer) => void, options?: CreateMcpHandlerOptions): McpHttpHandler { + return createMcpHandler(() => { + const mcp = new McpServer({ name: 'events-http', version: '1.0.0' }); + attach(mcp); + return mcp; + }, options); +} + +// The response with a body the test can end, as a dropped connection ends it; the server sees the cancel. +function droppable(response: Response, drops: Set<() => void>): Response { + const reader = response.body!.getReader(); + let ended = false; + const body = new ReadableStream({ + start(controller) { + drops.add(() => { + if (ended) return; + ended = true; + void reader.cancel(); + controller.close(); + }); + }, + async pull(controller) { + const { done, value } = await reader.read(); + if (ended) return; + if (done) { + ended = true; + controller.close(); + } else { + controller.enqueue(value); + } + }, + cancel(reason) { + ended = true; + return reader.cancel(reason); + } + }); + return new Response(body, { status: response.status, headers: response.headers }); +} + +// `serve` picks the handler for each request, so a test can move the client between servers. +async function overHttp( + serve: () => McpHttpHandler, + options: { revision?: string; events?: EventsClientExtension; authInfo?: AuthInfo } = {} +): Promise { + const client = clientFor(options.revision ?? MODERN); + const events = options.events ?? new EventsClientExtension(CLIENT_OPTIONS); + events.attach(client); + const requests: HttpConnection['requests'] = []; + const drops = new Set<() => void>(); + const fetch = async (url: URL | string, init?: RequestInit): Promise => { + const request = new Request(url, init); + const handler = serve(); + const method = request.headers.get('mcp-method'); + requests.push({ handler, method }); + const response = await handler.fetch(request, options.authInfo === undefined ? undefined : { authInfo: options.authInfo }); + return method === 'events/stream' && response.body !== null ? droppable(response, drops) : response; + }; + await client.connect(new StreamableHTTPClientTransport(new URL('http://localhost/mcp'), { fetch })); + return { + client, + events, + ...tap(client), + requests, + dropStreams: () => { + for (const drop of drops) drop(); + drops.clear(); + }, + close: () => client.close() + }; +} + +async function overStdio(revision: string): Promise { + const client = clientFor(revision); + const events = new EventsClientExtension(CLIENT_OPTIONS); + events.attach(client); + await client.connect( + new StdioClientTransport({ command: process.execPath, args: ['--import', 'tsx', 'eventsStdioServer.ts'], cwd: FIXTURES_DIR }) + ); + return { client, events, ...tap(client), close: () => client.close() }; +} + +async function overMemory(revision: string): Promise { + const { attach } = eventsFixture(); + const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); + const handle = serveStdio( + () => { + const mcp = new McpServer({ name: 'events-in-memory', version: '1.0.0' }); + attach(mcp); + return mcp; + }, + { transport: serverTransport } + ); + const client = clientFor(revision); + const events = new EventsClientExtension(CLIENT_OPTIONS); + events.attach(client); + await client.connect(clientTransport); + return { + client, + events, + ...tap(client), + close: async () => { + await client.close(); + await handle.close(); + } + }; +} + +async function connect(arm: Arm, revision: string): Promise { + if (arm === 'stdio') return overStdio(revision); + if (arm === 'inMemory') return overMemory(revision); + const handler = handlerFor(eventsFixture().attach); + const connection = await overHttp(() => handler, { revision }); + return { + ...connection, + close: async () => { + await connection.close(); + await handler.close(); + } + }; +} + +// The fixture's tools, which drive the server the same way in every arm. +function driver(client: Client) { + const call = async (name: string, args: Record) => { + const result = await client.callTool({ name, arguments: args }); + if (result.isError === true) throw new Error(`${name} failed: ${JSON.stringify(result.content)}`); + return result; + }; + return { + emit: (tag: string, ...texts: string[]) => call('emit', { tag, texts }), + append: (tag: string, ...titles: string[]) => call('append', { tag, titles }), + terminate: (name: string, tag: string, mode: 'poll' | 'push') => call('terminate', { name, tag, mode }), + hooks: async (tag: string): Promise => { + const result = await call('hooks', { tag }); + const [content] = result.content as Array<{ text: string }>; + return JSON.parse(content!.text) as HookEntry[]; + } + }; +} + +// The next `count` events, leaving the subscription open. +async function next(subscription: EventSubscription, count = 1): Promise { + const iterator = subscription[Symbol.asyncIterator](); + const data: T[] = []; + while (data.length < count) { + const result = await iterator.next(); + if (result.done === true) throw new Error('the subscription ended'); + data.push(result.value.data); + } + return data; +} + +function texts(notes: Note[]): string[] { + return notes.map(note => note.text); +} + +function isEventsFrame(message: JSONRPCMessage): message is JSONRPCMessage & { method: string; params: Record } { + return 'method' in message && !('id' in message) && message.method.startsWith('notifications/events/'); +} + +function streamIdOf(frame: { params: Record }): unknown { + return (frame.params._meta as Record)[SUBSCRIPTION_ID_META_KEY]; +} + +function raw(client: Client, method: string, params?: Record): Promise> { + return client.request({ method, ...(params !== undefined && { params }) }, Loose); +} + +// A fresh stdio child takes about a second over its first requests, more on a loaded machine. +describe.each([['http'], ['stdio'], ['inMemory']] as const)('events over %s on 2026-07-28', { timeout: 15_000 }, arm => { + let connection: Connection; + let server: ReturnType; + + const subscribe = ( + name: string, + tag: string, + delivery: 'poll' | 'push', + more: { cursor?: string | null; onGap?: (cursor: string | null) => void } = {} + ) => connection.events.subscribe({ name, arguments: { tag }, delivery, ...more }); + + beforeAll(async () => { + connection = await connect(arm, MODERN); + server = driver(connection.client); + }, 30_000); + + afterAll(async () => { + await connection.close(); + }); + + describe('poll', () => { + it('polls again at once while the server reports hasMore', async () => { + await server.append('drain', 'a', 'b', 'c', 'd', 'e'); + const subscription = await connection.events.subscribe<{ title: string }>({ + name: TICKET, + arguments: { tag: 'drain' }, + delivery: 'poll', + cursor: '0' + }); + // Every page asks for nextPollMs 60 000: only hasMore brings the later pages within the test timeout. + const tickets = await next(subscription, 5); + expect(tickets.map(ticket => ticket.title)).toEqual(['a', 'b', 'c', 'd', 'e']); + await subscription.cancel(); + }); + + it('reports truncated through onGap after the buffer evicted its cursor, and goes on from the oldest note kept', async () => { + const first = await subscribe(NOTE, 'evicted', 'poll'); + const cursor = first.cursor; + await first.cancel(); + await server.emit('evicted', 'n1', 'n2', 'n3', 'n4'); + const gaps: Array = []; + const subscription = await subscribe(NOTE, 'evicted', 'poll', { cursor, onGap: gap => void gaps.push(gap) }); + expect(texts(await next(subscription, BUFFERED_NOTES))).toEqual(['n2', 'n3', 'n4']); + expect(gaps).toEqual([expect.any(String)]); + await subscription.cancel(); + }); + + it('resumes from a persisted cursor with what was emitted while it was away', async () => { + const first = await subscribe(NOTE, 'resume', 'poll'); + await server.emit('resume', 'seen'); + const iterator = first[Symbol.asyncIterator](); + const seen = await iterator.next(); + expect(seen.value?.data.text).toBe('seen'); + // Asking for the next event finishes with 'seen', so the cursor moves past it. + const pending = iterator.next(); + const persisted = first.cursor; + await first.cancel(); + await pending; + + await server.emit('resume', 'while away'); + const resumed = await subscribe(NOTE, 'resume', 'poll', { cursor: persisted }); + expect(texts(await next(resumed))).toEqual(['while away']); + await resumed.cancel(); + }); + }); + + describe('push', () => { + it('confirms the stream with the granted heartbeat, then sends heartbeats while it is quiet', async () => { + const mark = connection.received.length; + const subscription = await subscribe(NOTE, 'heartbeat', 'push'); + const frames = () => connection.received.slice(mark).filter(message => isEventsFrame(message)); + await vi.waitFor(() => expect(frames().map(frame => frame.method)).toContain('notifications/events/heartbeat'), { + timeout: 5000 + }); + const [active, ...rest] = frames(); + expect(active).toMatchObject({ + method: 'notifications/events/active', + params: { truncated: false, heartbeatMs: HEARTBEAT_MS } + }); + for (const frame of rest) { + expect(frame).toMatchObject({ method: 'notifications/events/heartbeat', params: { cursor: active!.params.cursor } }); + expect(streamIdOf(frame)).toBe(streamIdOf(active!)); + } + await subscription.cancel(); + }); + + it('reports a gap through onGap and replays the notes the buffer kept', async () => { + const first = await subscribe(NOTE, 'gap', 'push'); + const cursor = first.cursor; + await first.cancel(); + await server.emit('gap', 'n1', 'n2', 'n3', 'n4'); + const gaps: Array = []; + const subscription = await subscribe(NOTE, 'gap', 'push', { cursor, onGap: gap => void gaps.push(gap) }); + expect(texts(await next(subscription, BUFFERED_NOTES))).toEqual(['n2', 'n3', 'n4']); + expect(gaps).toEqual([expect.any(String)]); + await subscription.cancel(); + }); + + it('ends the server stream on cancel(), which calls onUnsubscribe', async () => { + const subscription = await subscribe(NOTE, 'cancel', 'push'); + const [opened] = await server.hooks('cancel'); + expect(opened).toMatchObject({ hook: 'subscribe', mode: 'push' }); + await subscription.cancel(); + await vi.waitFor(async () => expect(await server.hooks('cancel')).toEqual([opened, { ...opened, hook: 'unsubscribe' }])); + }); + + // Without an HTTP request stream to abort, the client cancels with a notification. + if (arm !== 'http') { + it('cancels with notifications/cancelled, and the server stops without answering the stream', async () => { + const mark = connection.sent.length; + const subscription = await subscribe(NOTE, 'cancelled', 'push'); + const stream = connection.sent.slice(mark).find(message => 'method' in message && message.method === 'events/stream'); + expect(stream).toMatchObject({ id: expect.any(String) }); + const id = (stream as { id: string }).id; + await subscription.cancel(); + expect(connection.sent).toContainEqual( + expect.objectContaining({ method: 'notifications/cancelled', params: expect.objectContaining({ requestId: id }) }) + ); + await vi.waitFor(async () => { + const entries = await server.hooks('cancelled'); + expect(entries.map(entry => entry.hook)).toEqual(['subscribe', 'unsubscribe']); + }); + // One more round trip: an answer to the stream would have been written before this one's. + await server.hooks('cancelled'); + expect(connection.received.filter(message => 'id' in message && message.id === id)).toEqual([]); + }); + } + + if (arm === 'http') { + it('reconnects from its cursor after the server-side stream drops', async () => { + const subscription = await subscribe(NOTE, 'drop', 'push'); + await server.emit('drop', 'before'); + expect(texts(await next(subscription))).toEqual(['before']); + const [opened] = await server.hooks('drop'); + (connection as HttpConnection).dropStreams(); + // The server releases the dropped stream, and the client opens a new one. + await vi.waitFor( + async () => { + const entries = await server.hooks('drop'); + expect(entries).toContainEqual({ ...opened, hook: 'unsubscribe' }); + expect(entries.filter(entry => entry.hook === 'subscribe')).toHaveLength(2); + }, + { timeout: 5000 } + ); + await server.emit('drop', 'after'); + expect(texts(await next(subscription))).toEqual(['after']); + await subscription.cancel(); + }); + + it("delivers under responseMode: 'json', where a subscription picks push by default", async () => { + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}); + const handler = handlerFor(eventsFixture().attach, { responseMode: 'json' }); + expect(warn).toHaveBeenCalledWith(expect.stringContaining('events/stream')); + warn.mockRestore(); + const json = await overHttp(() => handler); + try { + const subscription = await json.events.subscribe({ name: NOTE, arguments: { tag: 'json' } }); + expect(subscription.deliveryMode).toBe('push'); + await driver(json.client).emit('json', 'streamed'); + expect(texts(await next(subscription))).toEqual(['streamed']); + await subscription.cancel(); + } finally { + await json.close(); + await handler.close(); + } + }); + } + }); + + describe('termination', () => { + it.each(['poll', 'push'] as const)('ends a %s subscription with the error handle.terminate gives', async mode => { + const tag = `terminate-${mode}`; + const subscription = await subscribe(NOTE, tag, mode); + await server.terminate(NOTE, tag, mode); + const ended = next(subscription); + await expect(ended).rejects.toBeInstanceOf(EventsError); + await expect(ended).rejects.toMatchObject({ kind: 'forbidden', message: 'Access revoked' }); + const entries = await server.hooks(tag); + expect(entries.map(entry => entry.hook)).toEqual(['subscribe', 'unsubscribe']); + }); + }); +}); + +describe.each([['http'], ['stdio'], ['inMemory']] as const)('events over %s on 2025-11-25', arm => { + let connection: Connection; + + beforeAll(async () => { + connection = await connect(arm, LEGACY); + }, 30_000); + + afterAll(async () => { + await connection.close(); + }); + + it('advertises nothing, refuses events.list(), and answers a raw events/list with -32601', async () => { + expect(connection.client.getServerCapabilities()?.extensions?.[EVENTS_EXTENSION_ID]).toBeUndefined(); + expect(connection.events.supported).toBe(false); + const listed = connection.events.list(); + await expect(listed).rejects.toBeInstanceOf(SdkError); + await expect(listed).rejects.toMatchObject({ code: SdkErrorCode.CapabilityNotSupported }); + await expect(raw(connection.client, 'events/list')).rejects.toMatchObject({ code: -32_601 }); + }); + + // stdio and in memory pin the session to the era `initialize` opened; over HTTP each request is classified by its own envelope. + if (arm !== 'http') { + it('refuses events/* that claim 2026-07-28 in _meta on a session opened with initialize', async () => { + const envelope = { + [PROTOCOL_VERSION_META_KEY]: MODERN, + [CLIENT_INFO_META_KEY]: { name: 'events-host', version: '1.0.0' }, + [CLIENT_CAPABILITIES_META_KEY]: { extensions: { [EVENTS_EXTENSION_ID]: {} } } + }; + // Method not found, or the Protocol layer's unsupported-protocol-version error. + const codeOf = (request: Promise) => + request.then( + () => 'served', + (error: { code?: unknown }) => error.code + ); + expect([-32_601, -32_022]).toContain(await codeOf(raw(connection.client, 'events/list', { _meta: envelope }))); + expect([-32_601, -32_022]).toContain( + await codeOf( + raw(connection.client, 'events/poll', { name: NOTE, arguments: { tag: 'spoofed' }, cursor: null, _meta: envelope }) + ) + ); + }); + } +}); + +// One webhook POST, as the server's sender handed it over and the receiver answered it. +interface Post { + readonly headers: Readonly>; + readonly raw: string; + readonly body: Record; + // Set once the receiver has answered, which is after it handed an event to the subscription. + status?: number; + answer?: string; +} + +// A webhookSender that hands each POST to the client's receiver as a Request (no network), recording it as it is sent; `refuse` answers some 503 instead. +function inProcessSender( + receive: (request: Request) => Promise, + posts: Post[], + refuse: (body: Record) => boolean = () => false +): WebhookSender { + return async ({ url, headers, body }) => { + const post: Post = { headers, raw: body, body: JSON.parse(body) as Record }; + posts.push(post); + if (refuse(post.body)) { + Object.assign(post, { status: 503, answer: '' }); + return { status: 503, body: '' }; + } + const response = await receive(new Request(url, { method: 'POST', headers, body })); + Object.assign(post, { status: response.status, answer: await response.text() }); + return { status: post.status!, body: post.answer! }; + }; +} + +// `post` once the receiver's answer is recorded. +function answered(post: Post | undefined): Promise { + return vi.waitFor(() => { + expect(post?.status).toBeDefined(); + return post!; + }); +} + +// The receiver's handler served over node:http on 127.0.0.1; resolves with its origin. +async function listenLoopback(receive: () => (request: Request) => Promise): Promise<{ origin: string; server: HttpServer }> { + const server = createServer(async (req, res) => { + const chunks: Buffer[] = []; + for await (const chunk of req) chunks.push(chunk as Buffer); + const headers = Object.entries(req.headers).flatMap(([key, value]) => + typeof value === 'string' ? [[key, value] as [string, string]] : [] + ); + const response = await receive()( + new Request(`http://127.0.0.1${req.url}`, { method: req.method, headers, body: Buffer.concat(chunks) }) + ); + res.writeHead(response.status, Object.fromEntries(response.headers)); + res.end(Buffer.from(await response.arrayBuffer())); + }); + const url = await listenOnRandomPort(server); + return { origin: url.origin, server }; +} + +// The Standard Webhooks signature of `post` under `secret`: v1, base64 HMAC-SHA256 of `id.timestamp.body`. +async function signatureOf(secret: string, post: Post): Promise { + const keyBytes = Uint8Array.from(atob(secret.slice('whsec_'.length)), char => char.codePointAt(0)!); + const key = await crypto.subtle.importKey('raw', keyBytes, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']); + const signed = `${post.headers['webhook-id']}.${post.headers['webhook-timestamp']}.${post.raw}`; + const mac = new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(signed))); + return `v1,${btoa(String.fromCodePoint(...mac))}`; +} + +const getPrincipal: EventsOptions['getPrincipal'] = ctx => (ctx.http?.authInfo?.extra?.sub as string | undefined) ?? null; + +function eventPosts(posts: Post[], subscriptionId: string): Post[] { + return posts.filter(post => post.headers['X-MCP-Subscription-Id'] === subscriptionId && post.body.type === undefined); +} + +describe('webhook delivery over http', () => { + // A client set up for webhook delivery to HOOK_URL, the server webhook-enabled with an in-process sender to its receiver. + async function webhookPair(options: { ttlMs?: number; secret?: string; refuse?: (body: Record) => boolean } = {}) { + const events = new EventsClientExtension({ + ...CLIENT_OPTIONS, + webhook: { url: HOOK_URL, ...(options.secret !== undefined && { secretProvider: () => options.secret! }) } + }); + const posts: Post[] = []; + const store = new InMemoryWebhookSubscriptionStore(); + const fixture = eventsFixture({ + webhookTtlMs: options.ttlMs ?? 60_000, + webhookSender: inProcessSender(events.createWebhookHandler(), posts, options.refuse), + webhookStore: store, + getPrincipal + }); + const handler = handlerFor(fixture.attach); + const connection = await overHttp(() => handler, { events, authInfo: ALICE }); + return { + ...connection, + posts, + store, + fixture, + close: async () => { + await connection.close(); + await handler.close(); + } + }; + } + + const emit = (fixture: EventsFixture, tag: string, text: string) => fixture.note.emit({ data: { tag, text } }); + + it('verifies the endpoint, delivers signed events, refreshes and unsubscribes', async () => { + // A 2 s grant: the client refreshes after 1.5 s. + const pair = await webhookPair({ ttlMs: 2000, secret: SECRET }); + try { + const subscription = await pair.events.subscribe({ name: NOTE, arguments: { tag: 'hook' } }); + expect(subscription.deliveryMode).toBe('webhook'); + const [{ subscriptionId }] = pair.fixture.log as [HookEntry]; + // The subscribe answered after the receiver echoed the challenge. + expect(pair.posts).toHaveLength(1); + const [verification] = pair.posts as [Post]; + expect(verification).toMatchObject({ body: { type: 'verification', challenge: expect.any(String) }, status: 200 }); + expect(JSON.parse(verification.answer!)).toEqual({ challenge: verification.body.challenge }); + + await emit(pair.fixture, 'hook', 'signed'); + expect(texts(await next(subscription))).toEqual(['signed']); + const delivery = await answered(eventPosts(pair.posts, subscriptionId)[0]); + expect(delivery).toMatchObject({ status: 200, body: { name: NOTE, data: { tag: 'hook', text: 'signed' } } }); + expect(delivery.headers).toMatchObject({ + 'Content-Type': 'application/json', + 'webhook-id': expect.stringMatching(/^[\w-]+$/), + 'webhook-timestamp': expect.stringMatching(/^\d+$/) + }); + expect(delivery.headers['webhook-signature']).toBe(await signatureOf(SECRET, delivery)); + + // The refresh answer carries the delivery status this process holds. + await vi.waitFor( + () => + expect(subscription.deliveryStatus).toMatchObject({ + active: true, + lastError: null, + lastDeliveryAt: expect.any(String) + }), + { timeout: 5000 } + ); + expect(pair.requests.filter(request => request.method === 'events/subscribe').length).toBeGreaterThan(1); + + await subscription.cancel(); + expect(pair.requests.at(-1)?.method).toBe('events/unsubscribe'); + expect(await pair.store.get(subscriptionId)).toBeUndefined(); + expect(pair.fixture.log.map(entry => entry.hook)).toEqual(['subscribe', 'unsubscribe']); + } finally { + await pair.close(); + } + }); + + it('retries a delivery the receiver refused, under the same webhook-id', async () => { + let refused = false; + const pair = await webhookPair({ + refuse: body => { + if (refused || body.type !== undefined) return false; + refused = true; + return true; + } + }); + try { + const subscription = await pair.events.subscribe({ name: NOTE, arguments: { tag: 'retry' } }); + await emit(pair.fixture, 'retry', 'retried'); + // The engine's first retry waits 5 s. + expect(texts(await next(subscription))).toEqual(['retried']); + const attempts = eventPosts(pair.posts, pair.fixture.log[0]!.subscriptionId); + await answered(attempts[1]); + expect(attempts.map(post => post.status)).toEqual([503, 200]); + expect(attempts[1]!.headers['webhook-id']).toBe(attempts[0]!.headers['webhook-id']); + await subscription.cancel(); + } finally { + await pair.close(); + } + }, 15_000); + + it('ends a webhook subscription with the error handle.terminate gives', async () => { + const pair = await webhookPair(); + try { + const subscription = await pair.events.subscribe({ name: NOTE, arguments: { tag: 'terminate-webhook' } }); + const [{ subscriptionId }] = pair.fixture.log as [HookEntry]; + await pair.fixture.note.terminate(new ServerEventsError('forbidden', 'Access revoked'), { subscriptionId }); + const ended = next(subscription); + await expect(ended).rejects.toBeInstanceOf(EventsError); + await expect(ended).rejects.toMatchObject({ kind: 'forbidden', message: 'Access revoked' }); + expect(pair.posts.at(-1)).toMatchObject({ body: { type: 'terminated', error: { message: 'Access revoked' } } }); + expect(pair.fixture.log.map(entry => entry.hook)).toEqual(['subscribe', 'unsubscribe']); + } finally { + await pair.close(); + } + }); + + it('delivers an emit end to end through nodeWebhookSender to a receiver on loopback', async () => { + let receive: (request: Request) => Promise = async () => new Response(null, { status: 503 }); + const { origin, server } = await listenLoopback(() => receive); + const events = new EventsClientExtension({ ...CLIENT_OPTIONS, webhook: { url: `${origin}/hooks` } }); + receive = events.createWebhookHandler(); + const fixture = eventsFixture({ webhookTtlMs: 60_000, webhookSender: nodeWebhookSender(), trustedOrigins: [origin], getPrincipal }); + const handler = handlerFor(fixture.attach); + const connection = await overHttp(() => handler, { events, authInfo: ALICE }); + try { + const subscription = await events.subscribe({ name: NOTE, arguments: { tag: 'loopback' } }); + await emit(fixture, 'loopback', 'over the wire'); + expect(texts(await next(subscription))).toEqual(['over the wire']); + await subscription.cancel(); + } finally { + await connection.close(); + await handler.close(); + server.closeAllConnections(); + await new Promise(resolve => server.close(resolve)); + } + }); + + it('serves one subscription from two replicas sharing a store: refresh, rotation, emit and unsubscribe on the second', async () => { + const events = new EventsClientExtension({ ...CLIENT_OPTIONS, webhook: { url: HOOK_URL, secretProvider: () => SECRET } }); + const posts: Post[] = []; + const store = new InMemoryWebhookSubscriptionStore(); + // A 2 s grant: the client refreshes after 1.5 s. + const options = { + webhookTtlMs: 2000, + webhookSender: inProcessSender(events.createWebhookHandler(), posts), + webhookStore: store, + getPrincipal + }; + const first = eventsFixture(options); + const second = eventsFixture(options); + const firstHandler = handlerFor(first.attach); + const secondHandler = handlerFor(second.attach); + let target = firstHandler; + const connection = await overHttp(() => target, { events, authInfo: ALICE }); + try { + const subscription = await events.subscribe({ name: NOTE, arguments: { tag: 'replicas' } }); + // A second subscription served by the first replica, whose delivery shows the first has handled every emit before it. + const witness = await events.subscribe({ name: NOTE, arguments: { tag: 'witness' } }); + const { subscriptionId } = first.log.find(entry => entry.tag === 'replicas')!; + + target = secondHandler; + await vi.waitFor(() => expect(connection.requests).toContainEqual({ handler: secondHandler, method: 'events/subscribe' }), { + timeout: 5000 + }); + const rotated = await raw(connection.client, 'events/subscribe', { + name: NOTE, + arguments: { tag: 'replicas' }, + delivery: { mode: 'webhook', url: HOOK_URL, secret: ROTATED } + }); + expect(rotated).toMatchObject({ id: subscriptionId }); + const record = await store.get(subscriptionId); + // The client's own refreshes rotate back to its secret: either way both are in the record. + expect([record?.secret, record?.previousSecret?.secret].toSorted()).toEqual([SECRET, ROTATED].toSorted()); + + await emit(second, 'replicas', 'from the second'); + expect(texts(await next(subscription))).toEqual(['from the second']); + const [delivery] = eventPosts(posts, subscriptionId) as [Post]; + const signatures = delivery.headers['webhook-signature']!.split(' '); + expect(signatures).toHaveLength(2); + expect(signatures).toEqual(expect.arrayContaining([await signatureOf(SECRET, delivery), await signatureOf(ROTATED, delivery)])); + + await subscription.cancel(); + expect(connection.requests.at(-1)).toEqual({ handler: secondHandler, method: 'events/unsubscribe' }); + const delivered = posts.length; + await emit(first, 'replicas', 'after unsubscribe'); + await emit(first, 'witness', 'after unsubscribe'); + expect(texts(await next(witness))).toEqual(['after unsubscribe']); + expect(eventPosts(posts.slice(delivered), subscriptionId)).toEqual([]); + await witness.cancel(); + } finally { + await connection.close(); + await firstHandler.close(); + await secondHandler.close(); + } + }); + + it('keeps delivering to a stored subscription after a restart, without a resubscribe', async () => { + const events = new EventsClientExtension({ ...CLIENT_OPTIONS, webhook: { url: HOOK_URL } }); + const posts: Post[] = []; + const store = new InMemoryWebhookSubscriptionStore(); + const options = { + webhookTtlMs: 60_000, + webhookSender: inProcessSender(events.createWebhookHandler(), posts), + webhookStore: store, + getPrincipal + }; + const before = handlerFor(eventsFixture(options).attach); + let target = before; + const connection = await overHttp(() => target, { events, authInfo: ALICE }); + try { + const subscription = await events.subscribe({ name: NOTE, arguments: { tag: 'restart' } }); + await before.close(); + + const restarted = eventsFixture(options); + target = handlerFor(restarted.attach); + const requests = connection.requests.length; + const delivered = posts.length; + await emit(restarted, 'restart', 'after the restart'); + expect(texts(await next(subscription))).toEqual(['after the restart']); + expect(connection.requests.slice(requests)).toEqual([]); + expect(posts.slice(delivered).map(post => post.body.type ?? 'event')).toEqual(['event']); + await subscription.cancel(); + expect(restarted.log).toEqual([expect.objectContaining({ hook: 'unsubscribe', tag: 'restart' })]); + } finally { + await connection.close(); + await target.close(); + } + }); +}); diff --git a/test/integration/test/events/eventsWire.test.ts b/test/integration/test/events/eventsWire.test.ts new file mode 100644 index 0000000000..a92a29d1de --- /dev/null +++ b/test/integration/test/events/eventsWire.test.ts @@ -0,0 +1,293 @@ +/** + * Wire behaviour of the Events extension (SEP-3415) over Streamable HTTP: + * raw JSON-RPC and headers through `createMcpHandler`, and what a real + * `EventsClientExtension` sends. This suite is the contract for the version + * built on the extensions mechanism (#2820 / SEP-3371): it must pass + * unchanged against it. + */ +import { Client, isJsonContentType, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'; +import { EventsClientExtension } from '@modelcontextprotocol/client/ext/events'; +import type { McpHttpHandler } from '@modelcontextprotocol/server'; +import { createMcpHandler, McpServer } from '@modelcontextprotocol/server'; +import type { EmitOnlyEventHandle } from '@modelcontextprotocol/server/ext/events'; +import { EventsError, EventsExtension } from '@modelcontextprotocol/server/ext/events'; +import { afterEach, beforeAll, describe, expect, it } from 'vitest'; +import * as z from 'zod/v4'; + +const MODERN = '2026-07-28'; +const EXTENSION = 'io.modelcontextprotocol/events'; +const SUBSCRIPTION_ID = 'io.modelcontextprotocol/subscriptionId'; +const SERVER_INFO = 'io.modelcontextprotocol/serverInfo'; +const ENVELOPE = { + 'io.modelcontextprotocol/protocolVersion': MODERN, + 'io.modelcontextprotocol/clientInfo': { name: 'wire-client', version: '1.0.0' }, + 'io.modelcontextprotocol/clientCapabilities': { extensions: { [EXTENSION]: {} } } +}; +// A 2026-07-28 result carries the server's identity in `_meta`. +const RESULT_META = { [SERVER_INFO]: { name: 'events-wire', version: '1.0.0' } }; +const NAME = 'incident.created'; +const HOOK_URL = 'https://hooks.example.com/mcp'; +const SECRET = `whsec_${btoa('s'.repeat(32))}`; +const ARGUMENTS = { region: 'us-west1', severity: 'high' }; +const EVENTS_METHODS = ['events/list', 'events/poll', 'events/stream', 'events/subscribe', 'events/unsubscribe']; +const NAMED_METHODS = EVENTS_METHODS.slice(1); + +interface Served { + readonly handler: McpHttpHandler; + readonly incident: EmitOnlyEventHandle<{ title: string }>; +} + +interface Reply { + readonly status: number; + readonly body: { id?: unknown; result?: Record; error?: { code: number; data?: Record } }; +} + +// One emit-only event type whose `region` argument has an `x-mcp-header`; webhook delivery is on, and the sender answers verification challenges itself. +function served(): Served { + const events = new EventsExtension({ + webhookTtlMs: 60_000, + webhookSender: async ({ body }) => { + const { type, challenge } = JSON.parse(body) as { type?: string; challenge?: string }; + return { status: 200, body: type === 'verification' ? JSON.stringify({ challenge }) : '' }; + }, + getPrincipal: () => 'alice' + }); + const incident = events.registerEvent(NAME, { + emitOnly: true, + inputSchema: z.object({ region: z.string().meta({ 'x-mcp-header': 'Region' }), severity: z.string().optional() }), + payloadSchema: z.object({ title: z.string() }) + }); + const handler = createMcpHandler(() => { + const mcp = new McpServer({ name: 'events-wire', version: '1.0.0' }); + events.attach(mcp); + return mcp; + }); + return { handler, incident }; +} + +let nextId = 1; + +// A 2026-07-28 request with the envelope, Mcp-Method and, for a method that names an event type, Mcp-Name; `headers` adds to them. +function post( + handler: McpHttpHandler, + method: string, + params: Record, + headers: Record = {} +): { id: string; response: Promise } { + const id = `wire-${nextId++}`; + const request = new Request('http://localhost/mcp', { + method: 'POST', + headers: { + 'content-type': 'application/json', + accept: 'application/json, text/event-stream', + 'mcp-protocol-version': MODERN, + 'mcp-method': method, + ...(NAMED_METHODS.includes(method) && { 'mcp-name': params.name as string }), + ...headers + }, + body: JSON.stringify({ jsonrpc: '2.0', id, method, params: { ...params, _meta: ENVELOPE } }) + }); + return { id, response: handler.fetch(request) }; +} + +async function reply(response: Promise): Promise { + const answer = await response; + expect(answer.headers.get('content-type')).toContain('application/json'); + return { status: answer.status, body: (await answer.json()) as Reply['body'] }; +} + +// The JSON-RPC messages of an SSE response, as its `data:` frames arrive. +async function* frames(response: Response): AsyncGenerator> { + const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader(); + let buffer = ''; + try { + for (;;) { + const { done, value } = await reader.read(); + if (done) return; + buffer += value; + let end: number; + while ((end = buffer.indexOf('\n\n')) !== -1) { + const data = buffer + .slice(0, end) + .split('\n') + .filter(line => line.startsWith('data:')) + .map(line => line.slice(5).trimStart()) + .join('\n'); + buffer = buffer.slice(end + 2); + if (data !== '') yield JSON.parse(data) as Record; + } + } + } finally { + await reader.cancel().catch(() => {}); + } +} + +async function nextFrame(stream: AsyncGenerator>): Promise> { + const { done, value } = await stream.next(); + if (done === true) throw new Error('the stream ended'); + return value; +} + +const open: Array<{ close(): Promise }> = []; + +afterEach(async () => { + for (const closable of open.splice(0).toReversed()) await closable.close(); +}); + +function track(server: Served): Served { + open.push(server.handler); + return server; +} + +describe('events wire behaviour', () => { + it('declares the extension with an empty settings object', async () => { + const { handler } = track(served()); + const { status, body } = await reply(post(handler, 'server/discover', {}).response); + expect(status).toBe(200); + expect((body.result?.capabilities as { extensions?: Record }).extensions?.[EXTENSION]).toEqual({}); + }); + + it.each(NAMED_METHODS)('rejects a mismatched Mcp-Param-Region on %s with 400 and -32020', async method => { + const { handler } = track(served()); + const params = { + name: NAME, + arguments: ARGUMENTS, + ...(method === 'events/subscribe' && { delivery: { mode: 'webhook', url: HOOK_URL, secret: SECRET } }), + ...(method === 'events/unsubscribe' && { delivery: { url: HOOK_URL } }) + }; + const { status, body } = await reply(post(handler, method, params, { 'mcp-param-region': 'eu-west1' }).response); + expect(status).toBe(400); + expect(body.error).toMatchObject({ code: -32_020 }); + }); + + it('accepts a correctly headered events/subscribe on a webhook-enabled server', async () => { + const { handler } = track(served()); + const delivery = { mode: 'webhook', url: HOOK_URL, secret: SECRET }; + const { status, body } = await reply( + post(handler, 'events/subscribe', { name: NAME, arguments: ARGUMENTS, delivery }, { 'mcp-param-region': 'us-west1' }).response + ); + expect(status).toBe(200); + expect(body.result).toEqual({ + id: expect.stringMatching(/^[\w-]+$/), + refreshBefore: expect.any(String), + cursor: expect.any(String), + truncated: false, + resultType: 'complete', + _meta: RESULT_META + }); + }); + + it('opens events/stream with notifications/events/active, and ends it with the empty result when the server terminates it', async () => { + const { handler, incident } = track(served()); + const { id, response } = post( + handler, + 'events/stream', + { name: NAME, arguments: ARGUMENTS, cursor: null }, + { 'mcp-param-region': 'us-west1' } + ); + const answer = await response; + expect(answer.status).toBe(200); + expect(answer.headers.get('content-type')).toContain('text/event-stream'); + const stream = frames(answer); + const tagged = { _meta: { [SUBSCRIPTION_ID]: id } }; + + expect(await nextFrame(stream)).toEqual({ + jsonrpc: '2.0', + method: 'notifications/events/active', + params: { cursor: expect.any(String), truncated: false, heartbeatMs: 30_000, ...tagged } + }); + + await incident.emit({ eventId: 'inc-1', data: { title: 'Disk full' } }); + expect(await nextFrame(stream)).toEqual({ + jsonrpc: '2.0', + method: 'notifications/events/event', + params: { + eventId: 'inc-1', + name: NAME, + timestamp: expect.any(String), + data: { title: 'Disk full' }, + cursor: expect.any(String), + ...tagged + } + }); + + await incident.terminate(new EventsError('forbidden', 'Access revoked')); + expect(await nextFrame(stream)).toEqual({ + jsonrpc: '2.0', + method: 'notifications/events/terminated', + params: { error: { code: -32_024, message: 'Access revoked' }, ...tagged } + }); + expect(await nextFrame(stream)).toEqual({ + jsonrpc: '2.0', + id, + result: { resultType: 'complete', _meta: { ...RESULT_META, [SUBSCRIPTION_ID]: id } } + }); + const end = await stream.next(); + expect(end.done).toBe(true); + }); +}); + +describe('what a client sends', () => { + // Every HTTP exchange a client made: list, then a poll, a push and a webhook subscription, each cancelled. + const exchanges: Array<{ headers: Headers; body: { method?: string }; result?: Record }> = []; + + beforeAll(async () => { + const server = served(); + const client = new Client({ name: 'wire-client', version: '1.0.0' }, { versionNegotiation: { mode: { pin: MODERN } } }); + const events = new EventsClientExtension({ webhook: { url: HOOK_URL } }); + events.attach(client); + const fetch = async (url: URL | string, init?: RequestInit): Promise => { + const request = new Request(url, init); + const response = await server.handler.fetch(request); + const body = JSON.parse(init?.body as string) as { method?: string }; + const json = isJsonContentType(response.headers.get('content-type')); + const answer = json ? ((await response.clone().json()) as { result?: Record }) : undefined; + const result = answer?.result; + exchanges.push({ headers: request.headers, body, ...(result !== undefined && { result }) }); + return response; + }; + await client.connect(new StreamableHTTPClientTransport(new URL('http://localhost/mcp'), { fetch })); + await events.list(); + for (const delivery of ['poll', 'push', 'webhook'] as const) { + const subscription = await events.subscribe({ name: NAME, arguments: ARGUMENTS, delivery }); + await subscription.cancel(); + } + await client.close(); + await server.handler.close(); + }); + + const sent = (method: string) => exchanges.filter(exchange => exchange.body.method === method); + + it('sends Mcp-Method on every events/* request, and Mcp-Name with the event name on those that name one', () => { + for (const method of EVENTS_METHODS) { + expect(sent(method).length).toBeGreaterThan(0); + for (const { headers } of sent(method)) { + expect(headers.get('mcp-method')).toBe(method); + expect(headers.get('mcp-name')).toBe(method === 'events/list' ? null : NAME); + } + } + }); + + it('mirrors the annotated region argument as Mcp-Param-Region, and nothing else', () => { + for (const method of NAMED_METHODS) { + for (const { headers } of sent(method)) { + expect(headers.get('mcp-param-region')).toBe('us-west1'); + expect([...headers.keys()].filter(key => key.startsWith('mcp-param-'))).toEqual(['mcp-param-region']); + } + } + }); + + it('never sends subscriptions/listen', () => { + expect(exchanges.map(exchange => exchange.body.method)).not.toContain('subscriptions/listen'); + expect(exchanges.map(exchange => exchange.headers.get('mcp-method'))).not.toContain('subscriptions/listen'); + }); + + it("gets resultType 'complete' on every events/* result", () => { + // events/stream results are pinned above: the client ends its streams, so no result is sent to it. + for (const method of ['events/list', 'events/poll', 'events/subscribe', 'events/unsubscribe']) { + const results = sent(method).map(exchange => exchange.result); + expect(results.length).toBeGreaterThan(0); + for (const result of results) expect(result).toMatchObject({ resultType: 'complete' }); + } + }); +}); diff --git a/test/integration/test/server/cloudflareWorkers.test.ts b/test/integration/test/server/cloudflareWorkers.test.ts index a3366919af..93c796cb24 100644 --- a/test/integration/test/server/cloudflareWorkers.test.ts +++ b/test/integration/test/server/cloudflareWorkers.test.ts @@ -310,13 +310,21 @@ describe('Cloudflare Workers compatibility (no nodejs_compat)', () => { // Write server source. `/skills` also serves a skills catalog, loaded once at module scope // and attached to each per-request server (the shape the server guide recommends for - // Workers); `/runtime` reports the globals the skills extension feature-detects. + // Workers); `/runtime` reports the globals the skills extension feature-detects; `/events` + // reports the id of an events extension built at module scope with webhook delivery on. const serverSource = ` import { McpServer, WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server'; +import { EventsExtension } from '@modelcontextprotocol/server/ext/events'; import { memorySkillFiles, SkillsExtension } from '@modelcontextprotocol/server/ext/skills'; import { z } from 'zod'; const skills = await SkillsExtension.load(memorySkillFiles({ 'release-notes/SKILL.md': ${JSON.stringify(RELEASE_NOTES_MD)} })); +const events = new EventsExtension({ + webhookTtlMs: 60000, + webhookSender: async () => ({ error: 'connection_refused' }), + getPrincipal: () => null +}); +events.registerEvent('release.published', { emitOnly: true, payloadSchema: z.object({ tag: z.string() }) }); // A stateless transport serves one request: connect a new pair for each. async function connectPair(withSkills) { @@ -341,6 +349,9 @@ export default { if (pathname === '/runtime') { return new Response(JSON.stringify({ weakRef: typeof WeakRef }), { headers: { 'content-type': 'application/json' } }); } + if (pathname === '/events') { + return new Response(JSON.stringify({ id: events.id }), { headers: { 'content-type': 'application/json' } }); + } const transport = await connectPair(pathname === '/skills'); return transport.handleRequest(request); } @@ -419,4 +430,9 @@ export default { await client.close(); }, 30_000); + + it('loads the events extension subpath, whose extension the worker built with webhook delivery and an event type', async () => { + const response = await fetch(`http://127.0.0.1:${port}/events`); + expect(await response.json()).toEqual({ id: 'io.modelcontextprotocol/events' }); + }, 30_000); }); From 9459651e0e14be7a833f1c1aaa1d9f4e4ab21359 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 18:59:30 +0200 Subject: [PATCH 24/37] test(e2e): Events requirements and scenarios --- test/e2e/requirements.ts | 224 ++++++ test/e2e/scenarios/events.test.ts | 1216 +++++++++++++++++++++++++++++ 2 files changed, 1440 insertions(+) create mode 100644 test/e2e/scenarios/events.test.ts diff --git a/test/e2e/requirements.ts b/test/e2e/requirements.ts index d26f6524d2..fab03a0f8b 100644 --- a/test/e2e/requirements.ts +++ b/test/e2e/requirements.ts @@ -16,6 +16,17 @@ const STATEFUL_TRANSPORTS = ['inMemory', 'stdio', 'streamableHttp', 'sse'] as co const SKILLS_SPEC = 'https://github.com/modelcontextprotocol/ext-skills/blob/c1aa87e4c381c82b99aa37471d0eae4ab50f9985/specification/stable/skills.mdx?plain=1#'; +/** The Events extension (SEP-3415) at the commit the SDK implements; entries append `#`. */ +const EVENTS_SPEC = + 'https://github.com/modelcontextprotocol/modelcontextprotocol/blob/60b15c16f2e7265ea34ac51099dc5be62f734692/seps/3415-events-extension.md'; + +/** The cells every Events requirement runs on. */ +const EVENTS_CELLS = { + addedInSpecVersion: '2026-07-28', + transports: ['entryModern'], + note: "Events is served only on 2026-07-28, and entryModern is the arm whose client the harness pins to that revision; the other arms' 2026-07-28 cells connect a client that negotiates 2025-11-25 by default" +} as const; + export const REQUIREMENTS: Record = { // Lifecycle & version negotiation @@ -3628,6 +3639,219 @@ export const REQUIREMENTS: Record = { transports: ['entryModern'], supersedes: ['typescript:skills:catalog:reload-notifies'], note: 'Hosted by the test body via createMcpHandler so it can publish via handler.notify, as resources:listen:list-changed is.' + }, + + // Events extension (SEP-3415): served only on 2026-07-28. + + 'events:capability:declared': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#capability-negotiation`, + behavior: "A server with Events attached declares extensions['io.modelcontextprotocol/events'] as {}." + }, + 'events:fallback:method-not-found': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#capability-negotiation`, + behavior: 'A server without the extension answers events/* with -32601.' + }, + 'events:list:descriptors': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#listing-available-events`, + behavior: 'events/list returns name, description, delivery, inputSchema, payloadSchema and _meta per event type.' + }, + 'events:list:delivery': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#delivery-modes`, + behavior: 'delivery is a non-empty subset of poll, push, webhook.' + }, + 'typescript:events:delivery:inferred': { + ...EVENTS_CELLS, + source: 'sdk', + behavior: + 'delivery is computed from the configuration: poll and push unless the definition turns them off, webhook only when webhook delivery is configured and the definition does not turn it off; a definition that turns off every mode the server offers throws TypeError.' + }, + 'events:poll:bootstrap': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#poll-based-delivery`, + behavior: 'A poll with cursor: null returns no events and a fresh cursor.' + }, + 'events:poll:replay': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#poll-based-delivery`, + behavior: 'A poll with a cursor returns the events after it with hasMore and nextPollMs.' + }, + 'events:poll:has-more': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#poll-based-delivery`, + behavior: 'maxEvents caps a batch, sets hasMore and an intermediate cursor.' + }, + 'events:poll:truncated': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#cursor-lifecycle`, + behavior: 'A cursor past retention yields truncated: true and a fresh cursor, never an error.' + }, + 'events:poll:errors': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#error-handling`, + behavior: 'Unknown name -32023, bad arguments -32602, mode not offered -32026.' + }, + 'events:cursor:absent-is-null': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#cursor-lifecycle`, + behavior: 'An absent cursor is treated like null in requests and results.' + }, + 'events:cursor:max-age': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#cursor-lifecycle`, + behavior: + 'With maxAgeMs, replay starts at the later of the cursor and now − maxAgeMs, with truncated: true when that floor passes the cursor; with cursor: null it is ignored.' + }, + 'events:push:active-first': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#event-delivery`, + behavior: 'notifications/events/active is the first message on a stream, with the request id in _meta.' + }, + 'events:push:heartbeat-grant': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#lifecycle`, + behavior: 'The server grants heartbeatMs on every active and heartbeats within it.' + }, + 'events:push:delivery': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#event-delivery`, + behavior: 'Events arrive as notifications/events/event with a cursor.' + }, + 'events:push:terminated': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#subscription-termination`, + behavior: 'A server-ended stream sends notifications/events/terminated with the nested error.' + }, + 'events:push:cancel': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#lifecycle`, + behavior: 'Aborting the stream stops delivery and releases the subscription.' + }, + 'events:webhook:auth-required': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#subscription-identity`, + behavior: 'events/subscribe without a principal answers -32024.' + }, + 'events:webhook:https-required': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#webhook-security`, + behavior: 'A non-https callback answers -32602.' + }, + 'events:webhook:secret-format': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#subscribing-eventssubscribe`, + behavior: 'A secret that is not whsec_ + 24–64 bytes answers -32602.' + }, + 'events:webhook:identity': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#subscription-identity`, + behavior: 'The id is stable for (principal, url, name, arguments) across refreshes.' + }, + 'events:webhook:ttl': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#subscription-ttl`, + behavior: + "refreshBefore is at most the suggestion, except when clamped up to the server's floor, and at most the server cap; ttlMs: null gets a finite grant." + }, + 'events:webhook:refresh': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#subscription-identity`, + behavior: 'A refresh resets the TTL and rotates the secret with dual signing.' + }, + 'events:webhook:unsubscribe': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#unsubscribing-eventsunsubscribe`, + behavior: 'Unsubscribe removes the subscription; an unknown key answers -32023.' + }, + 'events:webhook:verification': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#webhook-security`, + behavior: 'Delivery starts only after the endpoint echoes the challenge.' + }, + 'events:webhook:signature': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#webhook-security`, + behavior: 'Deliveries carry Standard Webhooks headers and X-MCP-Subscription-Id, signed over the raw body.' + }, + 'events:webhook:webhook-id': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#webhook-security`, + behavior: 'webhook-id is per message, reused on retries, and not the eventId.' + }, + 'events:webhook:final-statuses': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#webhook-event-delivery`, + behavior: '410 and 413 are not retried.' + }, + 'events:webhook:terminated': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#subscription-termination`, + behavior: 'A server-ended webhook subscription receives a signed terminated body.' + }, + 'events:mcp-name': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#streamable-http-routing-headers`, + behavior: 'events/* requests that name an event carry Mcp-Name set to the event name; events/list carries none.' + }, + 'events:mcp-param': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#custom-headers-from-subscription-arguments`, + behavior: 'Annotated arguments are mirrored into Mcp-Param-*; a mismatch answers 400 / -32020.' + }, + 'events:client:gating': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#capability-negotiation`, + behavior: 'The client refuses events/* when the server did not declare the extension.' + }, + 'events:client:mode-selection': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#delivery-mode-selection`, + behavior: 'The client prefers webhook, then push, then poll among the modes it can use.' + }, + 'events:client:dedupe': { + ...EVENTS_CELLS, + source: `${EVENTS_SPEC}#event-occurrences`, + behavior: 'The client delivers each eventId once per subscription.' + }, + 'typescript:events:attach:rules': { + ...EVENTS_CELLS, + source: 'sdk', + behavior: 'attach is idempotent per server, refuses a second Events extension and refuses after connect.' + }, + 'typescript:events:definition:kinds': { + ...EVENTS_CELLS, + source: 'sdk', + behavior: 'registerEvent takes check or emitOnly: true, never both.' + }, + 'typescript:events:errors': { + ...EVENTS_CELLS, + source: 'sdk', + behavior: 'Events errors surface as EventsError with kind; no compatible mode is NoCompatibleDeliveryModeError.' + }, + 'typescript:events:store:replicas': { + ...EVENTS_CELLS, + source: 'sdk', + behavior: 'Two servers sharing a WebhookSubscriptionStore serve one subscription.' + }, + 'typescript:events:store:restart': { + ...EVENTS_CELLS, + source: 'sdk', + behavior: + 'A server rebuilt over the same WebhookSubscriptionStore keeps delivering to a stored subscription, without a resubscribe or a new verification.' + }, + 'typescript:events:trusted-origins': { + ...EVENTS_CELLS, + source: 'sdk', + behavior: 'trustedOrigins admits http: only for exact listed origins.' + }, + 'typescript:events:experimental:subpaths': { + ...EVENTS_CELLS, + source: 'sdk', + behavior: + 'The experimental Events API is exported only from the ext/events subpaths (and server/ext/events/node); the @modelcontextprotocol/server and @modelcontextprotocol/client roots export none of it.' } } satisfies Record; diff --git a/test/e2e/scenarios/events.test.ts b/test/e2e/scenarios/events.test.ts new file mode 100644 index 0000000000..c35abba69b --- /dev/null +++ b/test/e2e/scenarios/events.test.ts @@ -0,0 +1,1216 @@ +/** + * Self-contained test bodies for the Events extension (SEP-3415). + * + * Each body builds its own EventsExtension, attaches it inside the server + * factory (the entry builds a server per request, so one extension serves + * them all), wires a real Client and asserts through EventsClientExtension, + * raw events/* requests or the recorded HTTP exchanges. Webhook POSTs go to an + * in-process endpoint through the extension's webhookSender: the client's + * receiver, or a stand-in that echoes verification challenges. Bodies that + * send events/* pass EVENTS_WIRE so the wire sniffer permits them. + */ + +import type { JSONRPCMessage } from '@modelcontextprotocol/client'; +import { Client, SdkError, SdkErrorCode, SUBSCRIPTION_ID_META_KEY } from '@modelcontextprotocol/client'; +import type { EventsClientOptions, EventSubscription } from '@modelcontextprotocol/client/ext/events'; +import { + EVENTS_EXTENSION_ID, + EventsClientExtension, + EventsError, + NoCompatibleDeliveryModeError +} from '@modelcontextprotocol/client/ext/events'; +import { InMemoryTransport, McpServer } from '@modelcontextprotocol/server'; +import type { EventsOptions, WebhookSender } from '@modelcontextprotocol/server/ext/events'; +import { + EventsError as ServerEventsError, + EventsExtension, + InMemoryWebhookSubscriptionStore +} from '@modelcontextprotocol/server/ext/events'; +import { expect, vi } from 'vitest'; +import * as z from 'zod/v4'; + +import type { RecordedHttpExchange, Wired } from '../helpers/index'; +import { defined, modernEnvelopeMeta, modernStandardHeaders, tapWire, wire } from '../helpers/index'; +import { verifies } from '../helpers/verifies'; +import type { TestArgs } from '../types'; + +const EVENTS_WIRE = { allowCustomMethods: true } as const; +const NOTE = 'note'; +const HOOK_URL = 'https://hooks.example.com/mcp/events'; +const SECRET = `whsec_${btoa('a'.repeat(32))}`; +const ROTATED = `whsec_${btoa('b'.repeat(32))}`; +// The client polls as often as a test's server asks. +const FAST: EventsClientOptions = { pollIntervalFloorMs: 20 }; +const Loose = z.looseObject({}); +const NoteInput = z.object({ tag: z.string().optional() }); +const NotePayload = z.object({ text: z.string() }); + +type Note = z.infer; + +const newClient = (): Client => new Client({ name: 'c', version: '0' }); + +function serving(events: EventsExtension): () => McpServer { + return () => { + const s = new McpServer({ name: 's', version: '0' }); + events.attach(s); + return s; + }; +} + +/** An extension with one emit-only event type, `note`. */ +function noteEvents(options?: EventsOptions) { + const events = new EventsExtension(options); + const note = events.registerEvent(NOTE, { emitOnly: true, inputSchema: NoteInput, payloadSchema: NotePayload }); + return { events, note }; +} + +/** A client with an EventsClientExtension attached, ready for wire(). */ +function eventsClient(options: EventsClientOptions = FAST): { client: Client; clientEvents: EventsClientExtension } { + const client = newClient(); + const clientEvents = new EventsClientExtension(options); + clientEvents.attach(client); + return { client, clientEvents }; +} + +function raw(client: Client, method: string, params?: Record): Promise> { + return client.request({ method, ...(params !== undefined && { params }) }, Loose); +} + +/** The error a promise rejects with. */ +async function rejectionOf(promise: Promise): Promise { + try { + await promise; + } catch (error) { + return error; + } + throw new Error('expected the promise to reject'); +} + +/** The next `count` events' data, leaving the subscription open. */ +async function take(subscription: EventSubscription, count = 1): Promise { + const iterator = subscription[Symbol.asyncIterator](); + const data: T[] = []; + while (data.length < count) { + const result = await iterator.next(); + if (result.done === true) throw new Error('the subscription ended'); + data.push(result.value.data); + } + return data; +} + +const pause = (ms: number) => new Promise(resolve => setTimeout(resolve, ms)); + +type Frame = JSONRPCMessage & { method: string; params: Record & { _meta: Record } }; + +/** The ids of the events/stream requests the client sent. */ +function streamIds(tap: ReturnType): unknown[] { + return tap.sent.flatMap(message => ('id' in message && 'method' in message && message.method === 'events/stream' ? [message.id] : [])); +} + +/** The messages the client received for the events/stream request `id`, in order. */ +function framesOf(tap: ReturnType, id: unknown): Frame[] { + return tap.received.filter((message): message is Frame => { + const meta = 'params' in message ? (message.params?._meta as Record | undefined) : undefined; + return meta?.[SUBSCRIPTION_ID_META_KEY] === id; + }); +} + +/** The recorded HTTP exchanges for one MCP method, by their Mcp-Method header. */ +function exchangesFor(wired: Wired, method: string): RecordedHttpExchange[] { + return (wired.httpLog ?? []).filter(exchange => exchange.requestHeaders.get('mcp-method') === method); +} + +// ─────────────────────────────────────────────────────────────────────────────── +// Webhook plumbing: an in-process endpoint behind the server's webhookSender +// ─────────────────────────────────────────────────────────────────────────────── + +/** One webhook POST, as the server's sender handed it over, and the endpoint's answer. */ +interface Post { + readonly url: string; + readonly headers: Headers; + readonly body: string; + readonly json: Record; + readonly trusted: boolean; + status?: number; +} + +type Endpoint = (request: Request) => Promise; + +/** An endpoint that echoes verification challenges and acknowledges everything else. */ +async function echoing(request: Request): Promise { + const body = (await request.json()) as { type?: string; challenge?: string }; + return body.type === 'verification' ? Response.json({ challenge: body.challenge }) : new Response(null, { status: 200 }); +} + +/** A webhookSender that records each POST and hands it to `endpoint` as a Request (no network). */ +function senderTo(endpoint: Endpoint, posts: Post[]): WebhookSender { + return async ({ url, headers, body, trusted }) => { + const post: Post = { url, headers: new Headers(headers), body, json: JSON.parse(body) as Record, trusted }; + posts.push(post); + const response = await endpoint(new Request(url, { method: 'POST', headers, body })); + post.status = response.status; + return { status: response.status, body: await response.text() }; + }; +} + +/** Webhook mode on, every subscriber the principal `alice`. */ +function webhookOptions(sender: WebhookSender, more: EventsOptions = {}): EventsOptions { + return { webhookTtlMs: 60_000, webhookSender: sender, getPrincipal: () => 'alice', ...more }; +} + +function eventPosts(posts: Post[]): Post[] { + return posts.filter(post => post.json.type === undefined); +} + +function hook(secret = SECRET, url = HOOK_URL) { + return { mode: 'webhook', url, secret }; +} + +/** The Standard Webhooks signature of `post` under `secret`: v1, base64 HMAC-SHA256 of `id.timestamp.body`. */ +async function signatureOf(secret: string, post: Post): Promise { + const keyBytes = Uint8Array.from(atob(secret.slice('whsec_'.length)), char => char.codePointAt(0)!); + const key = await crypto.subtle.importKey('raw', keyBytes, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']); + const signed = `${post.headers.get('webhook-id')}.${post.headers.get('webhook-timestamp')}.${post.body}`; + const mac = new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(signed))); + return `v1,${btoa(String.fromCodePoint(...mac))}`; +} + +// ─────────────────────────────────────────────────────────────────────────────── +// Capability and discovery +// ─────────────────────────────────────────────────────────────────────────────── + +verifies('events:capability:declared', async ({ transport }: TestArgs) => { + const { events } = noteEvents(); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + + expect(client.getServerCapabilities()?.extensions).toEqual({ [EVENTS_EXTENSION_ID]: {} }); +}); + +verifies('events:fallback:method-not-found', async ({ transport }: TestArgs) => { + const client = newClient(); + await using wired = await wire(transport, () => new McpServer({ name: 's', version: '0' }), client, EVENTS_WIRE); + const requests: Array<[string, Record]> = [ + ['events/list', {}], + ['events/poll', { name: NOTE, cursor: null }], + ['events/stream', { name: NOTE, cursor: null }], + ['events/subscribe', { name: NOTE, delivery: hook() }], + ['events/unsubscribe', { name: NOTE, delivery: { url: HOOK_URL } }] + ]; + + for (const [method, params] of requests) { + await expect(raw(client, method, params)).rejects.toBeDefined(); + const [exchange] = exchangesFor(wired, method); + const answer = (await defined(exchange, method).response.json()) as { error?: { code: number } }; + expect(answer.error?.code).toBe(-32_601); + } +}); + +verifies('events:list:descriptors', async ({ transport }: TestArgs) => { + const events = new EventsExtension(); + events.registerEvent('incident.created', { + emitOnly: true, + description: 'Fires when an incident is created', + inputSchema: z.object({ severity: z.enum(['P1', 'P2']).optional() }), + payloadSchema: z.object({ incidentId: z.string() }), + _meta: { 'example.com/tier': 'gold' } + }); + events.registerEvent('tick', { payloadSchema: z.object({ n: z.number() }), check: (_ctx, _args, cursor) => ({ events: [], cursor }) }); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + + const listed = await raw(client, 'events/list'); + + expect(listed.events).toEqual([ + { + name: 'incident.created', + description: 'Fires when an incident is created', + delivery: ['poll', 'push'], + inputSchema: expect.objectContaining({ type: 'object', properties: { severity: { type: 'string', enum: ['P1', 'P2'] } } }), + payloadSchema: expect.objectContaining({ type: 'object', properties: { incidentId: { type: 'string' } } }), + _meta: { 'example.com/tier': 'gold' } + }, + { + name: 'tick', + delivery: ['poll', 'push'], + inputSchema: { type: 'object' }, + payloadSchema: expect.objectContaining({ type: 'object', properties: { n: { type: 'number' } } }) + } + ]); +}); + +verifies('events:list:delivery', async ({ transport }: TestArgs) => { + const MODES = ['poll', 'push', 'webhook']; + const optOuts = [{}, { poll: false }, { push: false }, { webhook: false }] as const; + const configurations = [ + { events: new EventsExtension(), optOuts }, + { events: new EventsExtension(webhookOptions(senderTo(echoing, []))), optOuts: [...optOuts, { poll: false, push: false }] } + ]; + for (const { events, optOuts: definitions } of configurations) { + for (const [index, delivery] of definitions.entries()) { + events.registerEvent(`e${index}`, { emitOnly: true, payloadSchema: NotePayload, delivery }); + } + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + + const { events: descriptors } = (await raw(client, 'events/list')) as { events: Array<{ delivery: string[] }> }; + + expect(descriptors).toHaveLength(definitions.length); + for (const { delivery } of descriptors) { + expect(delivery.length).toBeGreaterThan(0); + expect(new Set(delivery).size).toBe(delivery.length); + for (const mode of delivery) expect(MODES).toContain(mode); + } + } +}); + +verifies('typescript:events:delivery:inferred', async ({ transport }: TestArgs) => { + const configurations = [ + { events: new EventsExtension(), all: ['poll', 'push'] }, + { events: new EventsExtension(webhookOptions(senderTo(echoing, []))), all: ['poll', 'push', 'webhook'] } + ]; + for (const { events, all } of configurations) { + events.registerEvent('default', { emitOnly: true, payloadSchema: NotePayload }); + events.registerEvent('no-push', { emitOnly: true, payloadSchema: NotePayload, delivery: { push: false } }); + events.registerEvent('no-poll', { emitOnly: true, payloadSchema: NotePayload, delivery: { poll: false } }); + events.registerEvent('no-webhook', { emitOnly: true, payloadSchema: NotePayload, delivery: { webhook: false } }); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + + const { events: descriptors } = (await raw(client, 'events/list')) as { events: Array<{ name: string; delivery: string[] }> }; + + expect(Object.fromEntries(descriptors.map(({ name, delivery }) => [name, delivery]))).toEqual({ + default: all, + 'no-push': all.filter(mode => mode !== 'push'), + 'no-poll': all.filter(mode => mode !== 'poll'), + 'no-webhook': ['poll', 'push'] + }); + } + const plain = new EventsExtension(); + expect(() => + plain.registerEvent('nothing', { emitOnly: true, payloadSchema: NotePayload, delivery: { poll: false, push: false } }) + ).toThrow(TypeError); + const withWebhook = new EventsExtension(webhookOptions(senderTo(echoing, []))); + expect(() => + withWebhook.registerEvent('webhook-only', { emitOnly: true, payloadSchema: NotePayload, delivery: { poll: false, push: false } }) + ).not.toThrow(); +}); + +// ─────────────────────────────────────────────────────────────────────────────── +// Poll +// ─────────────────────────────────────────────────────────────────────────────── + +verifies('events:poll:bootstrap', async ({ transport }: TestArgs) => { + const { events, note } = noteEvents(); + // A check that would return events: a null cursor still answers with none. + events.registerEvent('ticket', { + payloadSchema: NotePayload, + check: () => ({ events: [{ data: { text: 'old' } }], cursor: 't1' }) + }); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + await note.emit({ data: { text: 'before' } }); + + const bootstrap = await raw(client, 'events/poll', { name: NOTE, cursor: null }); + expect(bootstrap).toMatchObject({ events: [], cursor: expect.any(String), truncated: false, hasMore: false }); + await expect(raw(client, 'events/poll', { name: 'ticket', cursor: null })).resolves.toMatchObject({ events: [], cursor: 't1' }); + + await note.emit({ data: { text: 'after' } }); + const next = await raw(client, 'events/poll', { name: NOTE, cursor: bootstrap.cursor }); + expect((next.events as Array<{ data: Note }>).map(event => event.data.text)).toEqual(['after']); +}); + +verifies('events:poll:replay', async ({ transport }: TestArgs) => { + const { events, note } = noteEvents({ defaultNextPollMs: 1234 }); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + const { cursor } = await raw(client, 'events/poll', { name: NOTE, cursor: null }); + await note.emit({ eventId: 'n1', data: { text: 'one' } }); + await note.emit({ eventId: 'n2', data: { text: 'two' } }); + + const replay = await raw(client, 'events/poll', { name: NOTE, cursor }); + + expect(replay).toMatchObject({ + events: [ + { eventId: 'n1', name: NOTE, timestamp: expect.any(String), data: { text: 'one' } }, + { eventId: 'n2', name: NOTE, timestamp: expect.any(String), data: { text: 'two' } } + ], + cursor: expect.any(String), + truncated: false, + hasMore: false, + nextPollMs: 1234 + }); + await expect(raw(client, 'events/poll', { name: NOTE, cursor: replay.cursor })).resolves.toMatchObject({ events: [], hasMore: false }); +}); + +verifies('events:poll:has-more', async ({ transport }: TestArgs) => { + const { events, note } = noteEvents(); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + let { cursor } = await raw(client, 'events/poll', { name: NOTE, cursor: null }); + for (const text of ['a', 'b', 'c', 'd', 'e']) await note.emit({ data: { text } }); + + const pages: Array<{ texts: string[]; hasMore: unknown }> = []; + for (let page = 0; page < 3; page++) { + const result = await raw(client, 'events/poll', { name: NOTE, cursor, maxEvents: 2 }); + expect(result.cursor).not.toBe(cursor); + pages.push({ texts: (result.events as Array<{ data: Note }>).map(event => event.data.text), hasMore: result.hasMore }); + cursor = result.cursor; + } + + expect(pages).toEqual([ + { texts: ['a', 'b'], hasMore: true }, + { texts: ['c', 'd'], hasMore: true }, + { texts: ['e'], hasMore: false } + ]); +}); + +verifies('events:poll:truncated', async ({ transport }: TestArgs) => { + const { events, note } = noteEvents({ emitBuffer: { maxEvents: 2 } }); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + const { cursor } = await raw(client, 'events/poll', { name: NOTE, cursor: null }); + for (const text of ['n1', 'n2', 'n3', 'n4']) await note.emit({ data: { text } }); + + const gap = await raw(client, 'events/poll', { name: NOTE, cursor }); + + expect(gap).toMatchObject({ events: [], truncated: true, cursor: expect.any(String) }); + expect(gap.cursor).not.toBe(cursor); + const resumed = await raw(client, 'events/poll', { name: NOTE, cursor: gap.cursor }); + expect(resumed).toMatchObject({ truncated: false, events: [{ data: { text: 'n3' } }, { data: { text: 'n4' } }] }); +}); + +verifies('events:poll:errors', async ({ transport }: TestArgs) => { + const { events } = noteEvents(); + events.registerEvent('push-only', { emitOnly: true, payloadSchema: NotePayload, delivery: { poll: false } }); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + + await expect(raw(client, 'events/poll', { name: 'missing', cursor: null })).rejects.toMatchObject({ code: -32_023 }); + await expect(raw(client, 'events/poll', { name: NOTE, arguments: { tag: 5 }, cursor: null })).rejects.toMatchObject({ code: -32_602 }); + await expect(raw(client, 'events/poll', { name: 'push-only', cursor: null })).rejects.toMatchObject({ + code: -32_026, + data: { feature: 'deliveryMode', value: 'poll' } + }); +}); + +// ─────────────────────────────────────────────────────────────────────────────── +// Cursors +// ─────────────────────────────────────────────────────────────────────────────── + +verifies('events:cursor:absent-is-null', async ({ transport }: TestArgs) => { + { + // Requests: no cursor field starts from now, as cursor: null does. + const { events, note } = noteEvents(webhookOptions(senderTo(echoing, []))); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + await note.emit({ data: { text: 'before' } }); + + const withNull = await raw(client, 'events/poll', { name: NOTE, cursor: null }); + await expect(raw(client, 'events/poll', { name: NOTE })).resolves.toMatchObject({ + events: [], + cursor: withNull.cursor, + truncated: false + }); + await expect(raw(client, 'events/subscribe', { name: NOTE, delivery: hook() })).resolves.toMatchObject({ + cursor: withNull.cursor, + truncated: false + }); + } + { + // Results: a server that never writes cursor; the client delivers, and polls from null after resuming from c5. + const polls: Array> = []; + const makeServer = () => { + const s = new McpServer({ name: 's', version: '0' }); + s.server.registerCapabilities({ extensions: { [EVENTS_EXTENSION_ID]: {} } }); + s.server.setRequestHandler('events/list', { params: Loose }, () => ({ + events: [{ name: NOTE, delivery: ['poll'], inputSchema: { type: 'object' }, payloadSchema: { type: 'object' } }] + })); + s.server.setRequestHandler('events/poll', { params: Loose }, params => { + polls.push(params); + const events = + polls.length === 2 ? [{ eventId: 'e1', name: NOTE, timestamp: new Date().toISOString(), data: { text: 'one' } }] : []; + return { events, nextPollMs: 0 }; + }); + return s; + }; + const { client, clientEvents } = eventsClient(); + await using _ = await wire(transport, makeServer, client, EVENTS_WIRE); + + const subscription = await clientEvents.subscribe({ name: NOTE, cursor: 'c5' }); + expect(await take(subscription)).toEqual([{ text: 'one' }]); + await vi.waitFor(() => expect(polls.length).toBeGreaterThan(2)); + expect(subscription.cursor).toBeNull(); + await subscription.cancel(); + expect(polls[0]?.cursor).toBe('c5'); + for (const params of polls.slice(1)) expect(params.cursor ?? null).toBeNull(); + } +}); + +verifies('events:cursor:max-age', async ({ transport }: TestArgs) => { + const { events, note } = noteEvents(); + // A check type whose upstream has one event ten minutes old and one from now. + events.registerEvent('ticket', { + payloadSchema: NotePayload, + check: (_ctx, _args, cursor) => + cursor === null + ? { events: [], cursor: 't0' } + : { + events: [ + { timestamp: new Date(Date.now() - 600_000).toISOString(), data: { text: 'stale' } }, + { timestamp: new Date().toISOString(), data: { text: 'fresh' } } + ], + cursor: 't2' + } + }); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + const texts = (result: Record) => (result.events as Array<{ data: Note }>).map(event => event.data.text); + const { cursor: start } = await raw(client, 'events/poll', { name: NOTE, cursor: null }); + await note.emit({ data: { text: 'old' } }); + const { cursor: afterOld } = await raw(client, 'events/poll', { name: NOTE, cursor: start }); + await pause(300); + await note.emit({ data: { text: 'new' } }); + + // The floor passes the cursor: replay starts at the floor, and says so. + const floored = await raw(client, 'events/poll', { name: NOTE, cursor: start, maxAgeMs: 150 }); + expect({ texts: texts(floored), truncated: floored.truncated }).toEqual({ texts: ['new'], truncated: true }); + // The cursor is later than the floor: replay starts at the cursor. + const later = await raw(client, 'events/poll', { name: NOTE, cursor: afterOld, maxAgeMs: 150_000 }); + expect({ texts: texts(later), truncated: later.truncated }).toEqual({ texts: ['new'], truncated: false }); + const unbounded = await raw(client, 'events/poll', { name: NOTE, cursor: start }); + expect({ texts: texts(unbounded), truncated: unbounded.truncated }).toEqual({ texts: ['old', 'new'], truncated: false }); + // With cursor: null it is ignored. + await expect(raw(client, 'events/poll', { name: NOTE, cursor: null, maxAgeMs: 150 })).resolves.toMatchObject({ + events: [], + truncated: false + }); + const checked = await raw(client, 'events/poll', { name: 'ticket', cursor: 't0', maxAgeMs: 60_000 }); + expect({ texts: texts(checked), truncated: checked.truncated }).toEqual({ texts: ['fresh'], truncated: true }); +}); + +// ─────────────────────────────────────────────────────────────────────────────── +// Push +// ─────────────────────────────────────────────────────────────────────────────── + +verifies('events:push:active-first', async ({ transport }: TestArgs) => { + const { events, note } = noteEvents(); + const { client, clientEvents } = eventsClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + const { cursor } = await raw(client, 'events/poll', { name: NOTE, cursor: null }); + await note.emit({ data: { text: 'a' } }); + await note.emit({ data: { text: 'b' } }); + const tap = tapWire(client); + + // A cursor with events after it: the replay still comes after active. + const subscription = await clientEvents.subscribe({ name: NOTE, delivery: 'push', cursor: cursor as string }); + expect(await take(subscription, 2)).toEqual([{ text: 'a' }, { text: 'b' }]); + + const [id] = streamIds(tap); + expect(id).toBeDefined(); + expect(framesOf(tap, id).map(frame => frame.method)).toEqual([ + 'notifications/events/active', + 'notifications/events/event', + 'notifications/events/event' + ]); + expect(framesOf(tap, id)[0]?.params._meta).toEqual({ [SUBSCRIPTION_ID_META_KEY]: id }); + await subscription.cancel(); +}); + +verifies('events:push:heartbeat-grant', async ({ transport }: TestArgs) => { + const GRANT = 150; + const events = new EventsExtension({ heartbeatMs: GRANT, checkIntervalMs: 50 }); + let checks = 0; + // The third check reports a gap, so the server sends a second active. + events.registerEvent('ticket', { + payloadSchema: NotePayload, + check: (_ctx, _args, cursor) => { + checks += 1; + if (cursor === null) return { events: [], cursor: 'c0' }; + return checks === 3 ? { events: [], cursor: 'c1', truncated: true } : { events: [], cursor }; + } + }); + const { client, clientEvents } = eventsClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + const tap = tapWire(client); + + const subscription = await clientEvents.subscribe({ name: 'ticket', delivery: 'push' }); + const [id] = streamIds(tap); + const frames = () => framesOf(tap, id); + await vi.waitFor(() => expect(frames().filter(frame => frame.method === 'notifications/events/active')).toHaveLength(2)); + const quietFrom = frames().length; + await pause(10 * GRANT); + + for (const active of frames().filter(frame => frame.method === 'notifications/events/active')) { + expect(active.params.heartbeatMs).toBe(GRANT); + } + const heartbeats = frames() + .slice(quietFrom) + .filter(frame => frame.method === 'notifications/events/heartbeat'); + // Ten quiet intervals; a server heartbeating at twice the grant would send five. + expect(heartbeats.length).toBeGreaterThanOrEqual(6); + for (const heartbeat of heartbeats) expect(heartbeat.params.cursor).toBe('c1'); + await subscription.cancel(); +}); + +verifies('events:push:delivery', async ({ transport }: TestArgs) => { + const { events, note } = noteEvents(); + const { client, clientEvents } = eventsClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + const tap = tapWire(client); + const subscription = await clientEvents.subscribe({ name: NOTE, delivery: 'push' }); + const [id] = streamIds(tap); + + await note.emit({ eventId: 'evt-1', data: { text: 'pushed' } }); + expect(await take(subscription)).toEqual([{ text: 'pushed' }]); + + const delivered = framesOf(tap, id).filter(frame => frame.method === 'notifications/events/event'); + expect(delivered).toEqual([ + expect.objectContaining({ + params: { + eventId: 'evt-1', + name: NOTE, + timestamp: expect.any(String), + data: { text: 'pushed' }, + cursor: expect.any(String), + _meta: { [SUBSCRIPTION_ID_META_KEY]: id } + } + }) + ]); + await subscription.cancel(); +}); + +verifies('events:push:terminated', async ({ transport }: TestArgs) => { + const { events, note } = noteEvents(); + const { client, clientEvents } = eventsClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + const tap = tapWire(client); + const subscription = await clientEvents.subscribe({ name: NOTE, delivery: 'push' }); + const [id] = streamIds(tap); + + await note.terminate(new ServerEventsError('forbidden', 'Access revoked', { reason: 'revoked' })); + + await expect(take(subscription)).rejects.toMatchObject({ kind: 'forbidden' }); + expect(framesOf(tap, id).at(-1)).toMatchObject({ + method: 'notifications/events/terminated', + params: { + error: { code: -32_024, message: 'Access revoked', data: { reason: 'revoked' } }, + _meta: { [SUBSCRIPTION_ID_META_KEY]: id } + } + }); +}); + +verifies('events:push:cancel', async ({ transport }: TestArgs) => { + const hooks: string[] = []; + const events = new EventsExtension(); + const note = events.registerEvent(NOTE, { + emitOnly: true, + payloadSchema: NotePayload, + onSubscribe: ctx => void hooks.push(`subscribe ${ctx.mode}`), + onUnsubscribe: ctx => void hooks.push(`unsubscribe ${ctx.mode}`) + }); + const { client, clientEvents } = eventsClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + const tap = tapWire(client); + const subscription = await clientEvents.subscribe({ name: NOTE, delivery: 'push' }); + const [id] = streamIds(tap); + + await subscription.cancel(); + + await vi.waitFor(() => expect(hooks).toEqual(['subscribe push', 'unsubscribe push'])); + const framesBefore = framesOf(tap, id).length; + await note.emit({ data: { text: 'after cancel' } }); + await pause(50); + expect(framesOf(tap, id)).toHaveLength(framesBefore); +}); + +// ─────────────────────────────────────────────────────────────────────────────── +// Webhook subscriptions +// ─────────────────────────────────────────────────────────────────────────────── + +verifies('events:webhook:auth-required', async ({ transport }: TestArgs) => { + const posts: Post[] = []; + const { events } = noteEvents({ ...webhookOptions(senderTo(echoing, posts)), getPrincipal: () => null }); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + + await expect(raw(client, 'events/subscribe', { name: NOTE, delivery: hook() })).rejects.toMatchObject({ code: -32_024 }); + expect(posts).toEqual([]); +}); + +verifies('events:webhook:https-required', async ({ transport }: TestArgs) => { + const posts: Post[] = []; + const { events } = noteEvents(webhookOptions(senderTo(echoing, posts))); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + + for (const url of ['http://hooks.example.com/mcp/events', 'ftp://hooks.example.com/mcp/events', 'hooks.example.com/mcp/events']) { + await expect(raw(client, 'events/subscribe', { name: NOTE, delivery: hook(SECRET, url) })).rejects.toMatchObject({ + code: -32_602 + }); + } + expect(posts).toEqual([]); + await expect(raw(client, 'events/subscribe', { name: NOTE, delivery: hook() })).resolves.toMatchObject({ id: expect.any(String) }); +}); + +verifies('events:webhook:secret-format', async ({ transport }: TestArgs) => { + const posts: Post[] = []; + const { events } = noteEvents(webhookOptions(senderTo(echoing, posts))); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + const subscribe = (secret: string, tag: string) => + raw(client, 'events/subscribe', { name: NOTE, arguments: { tag }, delivery: hook(secret) }); + + for (const secret of [ + '', + 'not-a-secret', + btoa('a'.repeat(32)), + `whsec_${btoa('a'.repeat(23))}`, + `whsec_${btoa('a'.repeat(65))}`, + 'whsec_!!!!' + ]) { + await expect(subscribe(secret, 'bad')).rejects.toMatchObject({ code: -32_602 }); + } + expect(posts).toEqual([]); + await expect(subscribe(`whsec_${btoa('a'.repeat(24))}`, 'shortest')).resolves.toMatchObject({ id: expect.any(String) }); + await expect(subscribe(`whsec_${btoa('a'.repeat(64))}`, 'longest')).resolves.toMatchObject({ id: expect.any(String) }); +}); + +verifies('events:webhook:identity', async ({ transport }: TestArgs) => { + let principal = 'alice'; + const { events } = noteEvents({ ...webhookOptions(senderTo(echoing, [])), getPrincipal: () => principal }); + events.registerEvent('other', { emitOnly: true, inputSchema: NoteInput, payloadSchema: NotePayload }); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + const idOf = async (params: Record) => { + const { id } = await raw(client, 'events/subscribe', params); + return id; + }; + const key = { name: NOTE, arguments: { tag: 'a' }, delivery: hook() }; + + const id = await idOf(key); + // Refreshes, with another secret and TTL too, keep the id. + expect(await idOf(key)).toBe(id); + expect(await idOf({ ...key, delivery: hook(ROTATED), ttlMs: 120_000 })).toBe(id); + + const others = [ + await idOf({ ...key, name: 'other' }), + await idOf({ ...key, arguments: { tag: 'b' } }), + await idOf({ ...key, delivery: hook(SECRET, 'https://hooks.example.com/mcp/other') }) + ]; + principal = 'bob'; + others.push(await idOf(key)); + expect(new Set([id, ...others]).size).toBe(5); +}); + +verifies('events:webhook:ttl', async ({ transport }: TestArgs) => { + const CAP = 600_000; + const FLOOR = 60_000; + const { events } = noteEvents({ ...webhookOptions(senderTo(echoing, [])), webhookTtlMs: CAP }); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + // The granted TTL, bounded by the request's start and end. + const grantOf = async (ttlMs: number | null) => { + const sent = Date.now(); + const { refreshBefore } = await raw(client, 'events/subscribe', { name: NOTE, delivery: hook(), ttlMs }); + const answered = Date.now(); + expect(refreshBefore).toEqual(expect.any(String)); + const expiry = Date.parse(refreshBefore as string); + return { min: expiry - answered, max: expiry - sent }; + }; + const within = (grant: { min: number; max: number }, ms: number) => grant.min <= ms && ms <= grant.max; + + expect(within(await grantOf(120_000), 120_000)).toBe(true); + expect(within(await grantOf(1000), FLOOR)).toBe(true); + expect(within(await grantOf(3_600_000), CAP)).toBe(true); + const unlimited = await grantOf(null); + expect(unlimited.max).toBeLessThanOrEqual(CAP); +}); + +verifies('events:webhook:refresh', async ({ transport }: TestArgs) => { + const posts: Post[] = []; + const { events, note } = noteEvents(webhookOptions(senderTo(echoing, posts))); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + const first = await raw(client, 'events/subscribe', { name: NOTE, delivery: hook(SECRET), ttlMs: 60_000 }); + await pause(20); + + const refreshed = await raw(client, 'events/subscribe', { name: NOTE, delivery: hook(ROTATED), ttlMs: 60_000 }); + + expect(refreshed.id).toBe(first.id); + expect(Date.parse(refreshed.refreshBefore as string)).toBeGreaterThan(Date.parse(first.refreshBefore as string)); + await note.emit({ data: { text: 'dual' } }); + const delivery = await vi.waitFor(() => defined(eventPosts(posts)[0], 'the event POST')); + const signatures = defined(delivery.headers.get('webhook-signature'), 'webhook-signature').split(' '); + expect(signatures.toSorted()).toEqual([await signatureOf(SECRET, delivery), await signatureOf(ROTATED, delivery)].toSorted()); +}); + +verifies('events:webhook:unsubscribe', async ({ transport }: TestArgs) => { + const posts: Post[] = []; + const { events, note } = noteEvents(webhookOptions(senderTo(echoing, posts))); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + await raw(client, 'events/subscribe', { name: NOTE, arguments: { tag: 'a' }, delivery: hook() }); + const target = { name: NOTE, arguments: { tag: 'a' }, delivery: { url: HOOK_URL } }; + + await expect(raw(client, 'events/unsubscribe', target)).resolves.toMatchObject({}); + await note.emit({ data: { text: 'after unsubscribe' } }); + await pause(50); + expect(eventPosts(posts)).toEqual([]); + + const notFound = { code: -32_023, data: { kind: 'subscription' } }; + await expect(raw(client, 'events/unsubscribe', target)).rejects.toMatchObject(notFound); + await expect(raw(client, 'events/unsubscribe', { ...target, arguments: { tag: 'never' } })).rejects.toMatchObject(notFound); +}); + +verifies('events:webhook:verification', async ({ transport }: TestArgs) => { + // A check type with a backlog behind the cursor, so a subscribe with that cursor has events to replay at once. + const ticket = { + payloadSchema: NotePayload, + check: (_ctx: unknown, _args: unknown, cursor: string | null) => + cursor === 'c0' ? { events: [{ data: { text: 'backlog' } }], cursor: 'c1' } : { events: [], cursor: cursor ?? 'c0' } + }; + { + // An endpoint that answers but does not echo the challenge. + const posts: Post[] = []; + const events = new EventsExtension(webhookOptions(senderTo(async () => Response.json({ challenge: 'wrong' }), posts))); + events.registerEvent('ticket', ticket); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + + await expect(raw(client, 'events/subscribe', { name: 'ticket', delivery: hook(), cursor: 'c0' })).rejects.toMatchObject({ + code: -32_027, + data: { reason: 'challenge_failed' } + }); + await pause(50); + expect(posts.map(post => post.json.type)).toEqual(['verification']); + } + { + const posts: Post[] = []; + const events = new EventsExtension(webhookOptions(senderTo(echoing, posts))); + events.registerEvent('ticket', ticket); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + + await raw(client, 'events/subscribe', { name: 'ticket', delivery: hook(), cursor: 'c0' }); + + await vi.waitFor(() => expect(posts.map(post => post.json.type ?? 'event')).toEqual(['verification', 'event'])); + expect(posts[1]?.json).toMatchObject({ data: { text: 'backlog' } }); + } +}); + +verifies('events:webhook:signature', async ({ transport }: TestArgs) => { + const posts: Post[] = []; + const { events, note } = noteEvents(webhookOptions(senderTo(echoing, posts))); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + const { id } = await raw(client, 'events/subscribe', { name: NOTE, delivery: hook() }); + await note.emit({ eventId: 'evt-1', data: { text: 'signed' } }); + + await vi.waitFor(() => expect(eventPosts(posts)).toHaveLength(1)); + const now = Math.floor(Date.now() / 1000); + // The verification challenge and the event delivery alike. + for (const post of posts) { + expect(post.headers.get('content-type')).toBe('application/json'); + expect(post.headers.get('webhook-id')).toMatch(/^[\w-]+$/); + expect(Math.abs(Number(post.headers.get('webhook-timestamp')) - now)).toBeLessThanOrEqual(5); + expect(post.headers.get('x-mcp-subscription-id')).toBe(id); + expect(post.headers.get('webhook-signature')).toBe(await signatureOf(SECRET, post)); + } + expect(eventPosts(posts)[0]?.json).toMatchObject({ + eventId: 'evt-1', + name: NOTE, + data: { text: 'signed' }, + cursor: expect.any(String) + }); +}); + +verifies('events:webhook:webhook-id', async ({ transport }: TestArgs) => { + const posts: Post[] = []; + let refused = false; + // The first event POST is refused with a 503, so it is retried after 5 s. + const endpoint: Endpoint = async request => { + const body = (await request.clone().json()) as { type?: string }; + if (body.type === undefined && !refused) { + refused = true; + return new Response(null, { status: 503 }); + } + return echoing(request); + }; + const { events, note } = noteEvents(webhookOptions(senderTo(endpoint, posts))); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + const a = await raw(client, 'events/subscribe', { name: NOTE, arguments: { tag: 'a' }, delivery: hook() }); + const b = await raw(client, 'events/subscribe', { name: NOTE, arguments: { tag: 'b' }, delivery: hook() }); + + await note.emit({ eventId: 'evt-1', data: { text: 'one' } }); + await note.emit({ eventId: 'evt-2', data: { text: 'two' } }); + const forA = () => eventPosts(posts).filter(post => post.headers.get('x-mcp-subscription-id') === a.id); + const forB = () => eventPosts(posts).filter(post => post.headers.get('x-mcp-subscription-id') === b.id); + await vi.waitFor(() => expect(forA().length + forB().length).toBe(5), { timeout: 10_000 }); + + const idOf = (post: Post | undefined) => defined(post, 'post').headers.get('webhook-id'); + const [refusedPost] = eventPosts(posts); + const attempts = eventPosts(posts).filter(post => idOf(post) === idOf(refusedPost)); + expect(attempts.map(post => post.status)).toEqual([503, 200]); + expect(attempts.map(post => post.json.eventId)).toEqual([refusedPost?.json.eventId, refusedPost?.json.eventId]); + // One webhook-id per message: two events on two subscriptions are four messages. + const messages = new Set(eventPosts(posts).map(post => idOf(post))); + expect(messages.size).toBe(4); + for (const post of eventPosts(posts)) expect(idOf(post)).not.toContain(String(post.json.eventId)); + for (const tag of ['a', 'b']) await raw(client, 'events/unsubscribe', { name: NOTE, arguments: { tag }, delivery: { url: HOOK_URL } }); +}); + +verifies('events:webhook:final-statuses', async ({ transport }: TestArgs) => { + const posts: Post[] = []; + const answers: Record = { gone: 410, 'too-large': 413, unavailable: 503 }; + // Each subscription's URL names the status its event POSTs get. + const endpoint: Endpoint = async request => { + const body = (await request.clone().json()) as { type?: string }; + const status = answers[new URL(request.url).pathname.slice(1)]; + return body.type === undefined && status !== undefined ? new Response(null, { status }) : echoing(request); + }; + const { events, note } = noteEvents(webhookOptions(senderTo(endpoint, posts))); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + for (const path of Object.keys(answers)) { + await raw(client, 'events/subscribe', { name: NOTE, delivery: hook(SECRET, `https://hooks.example.com/${path}`) }); + } + const attempts = (path: string) => eventPosts(posts).filter(post => post.url === `https://hooks.example.com/${path}`).length; + + await note.emit({ data: { text: 'refused' } }); + + // The 503 is retried after 5 s; by then the 410 and 413 would have been too. + await vi.waitFor(() => expect(attempts('unavailable')).toBe(2), { timeout: 10_000 }); + await pause(200); + expect({ gone: attempts('gone'), tooLarge: attempts('too-large') }).toEqual({ gone: 1, tooLarge: 1 }); + for (const path of Object.keys(answers)) { + await raw(client, 'events/unsubscribe', { name: NOTE, delivery: { url: `https://hooks.example.com/${path}` } }); + } +}); + +verifies('events:webhook:terminated', async ({ transport }: TestArgs) => { + const posts: Post[] = []; + const { events, note } = noteEvents(webhookOptions(senderTo(echoing, posts))); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + const { id } = await raw(client, 'events/subscribe', { name: NOTE, delivery: hook() }); + + await note.terminate(new ServerEventsError('forbidden', 'Access revoked', { reason: 'revoked' }), { subscriptionId: id as string }); + + const terminated = await vi.waitFor(() => + defined( + posts.find(post => post.json.type === 'terminated'), + 'the terminated POST' + ) + ); + expect(terminated.json).toEqual({ + type: 'terminated', + error: { code: -32_024, message: 'Access revoked', data: { reason: 'revoked' } } + }); + expect(terminated.headers.get('x-mcp-subscription-id')).toBe(id); + expect(terminated.headers.get('webhook-signature')).toBe(await signatureOf(SECRET, terminated)); + // The subscription no longer exists. + await expect(raw(client, 'events/unsubscribe', { name: NOTE, delivery: { url: HOOK_URL } })).rejects.toMatchObject({ code: -32_023 }); +}); + +// ─────────────────────────────────────────────────────────────────────────────── +// Streamable HTTP headers +// ─────────────────────────────────────────────────────────────────────────────── + +verifies('events:mcp-name', async ({ transport }: TestArgs) => { + const posts: Post[] = []; + const { client, clientEvents } = eventsClient({ ...FAST, webhook: { url: HOOK_URL } }); + const { events } = noteEvents(webhookOptions(senderTo(clientEvents.createWebhookHandler(), posts))); + await using wired = await wire(transport, serving(events), client, EVENTS_WIRE); + + for (const delivery of ['poll', 'push', 'webhook'] as const) { + const subscription = await clientEvents.subscribe({ name: NOTE, delivery }); + await subscription.cancel(); + } + + for (const method of ['events/poll', 'events/stream', 'events/subscribe', 'events/unsubscribe']) { + const exchanges = exchangesFor(wired, method); + expect(exchanges.length).toBeGreaterThan(0); + for (const exchange of exchanges) expect(exchange.requestHeaders.get('mcp-name')).toBe(NOTE); + } + const listed = exchangesFor(wired, 'events/list'); + expect(listed.length).toBeGreaterThan(0); + for (const exchange of listed) expect(exchange.requestHeaders.has('mcp-name')).toBe(false); +}); + +verifies('events:mcp-param', async ({ transport }: TestArgs) => { + const events = new EventsExtension(); + events.registerEvent('incident', { + emitOnly: true, + inputSchema: z.object({ region: z.string().meta({ 'x-mcp-header': 'Region' }), severity: z.string().optional() }), + payloadSchema: NotePayload + }); + const { client, clientEvents } = eventsClient(); + await using wired = await wire(transport, serving(events), client, EVENTS_WIRE); + const args = { region: 'us-west1', severity: 'P1' }; + + const subscription = await clientEvents.subscribe({ name: 'incident', arguments: args, delivery: 'poll' }); + await subscription.cancel(); + const [polled] = exchangesFor(wired, 'events/poll'); + const headers = defined(polled, 'the events/poll exchange').requestHeaders; + expect(headers.get('mcp-param-region')).toBe('us-west1'); + expect([...headers.keys()].filter(key => key.startsWith('mcp-param-'))).toEqual(['mcp-param-region']); + + const mismatch = await defined(wired.fetch, 'fetch')(defined(wired.url, 'url'), { + method: 'POST', + headers: { + 'content-type': 'application/json', + accept: 'application/json, text/event-stream', + ...modernStandardHeaders('events/poll', 'incident'), + 'mcp-param-region': 'eu-west1' + }, + body: JSON.stringify({ + jsonrpc: '2.0', + id: 1, + method: 'events/poll', + params: { name: 'incident', arguments: args, cursor: null, _meta: modernEnvelopeMeta() } + }) + }); + expect(mismatch.status).toBe(400); + expect(((await mismatch.json()) as { error: { code: number } }).error.code).toBe(-32_020); +}); + +// ─────────────────────────────────────────────────────────────────────────────── +// Client +// ─────────────────────────────────────────────────────────────────────────────── + +verifies('events:client:gating', async ({ transport }: TestArgs) => { + const { client, clientEvents } = eventsClient(); + // No EVENTS_WIRE: the sniffer itself rejects any events/* request the client might send. + await using _ = await wire(transport, () => new McpServer({ name: 's', version: '0' }), client); + const tap = tapWire(client); + + expect(clientEvents.supported).toBe(false); + const unsupported = { code: SdkErrorCode.CapabilityNotSupported }; + await expect(clientEvents.list()).rejects.toBeInstanceOf(SdkError); + await expect(clientEvents.list()).rejects.toMatchObject(unsupported); + await expect(clientEvents.subscribe({ name: NOTE })).rejects.toMatchObject(unsupported); + await pause(0); + expect(tap.sent.filter(message => 'method' in message && message.method.startsWith('events/'))).toEqual([]); +}); + +verifies('events:client:mode-selection', async ({ transport }: TestArgs) => { + const definitions = { + all: {}, + 'no-webhook': { webhook: false }, + 'poll-only': { push: false, webhook: false } + } as const; + const modesFor = async (clientEvents: EventsClientExtension) => { + const modes: Record = {}; + for (const name of Object.keys(definitions)) { + const subscription = await clientEvents.subscribe({ name }); + modes[name] = subscription.deliveryMode; + await subscription.cancel(); + } + return modes; + }; + { + const { client, clientEvents } = eventsClient({ ...FAST, webhook: { url: HOOK_URL } }); + const events = new EventsExtension(webhookOptions(senderTo(clientEvents.createWebhookHandler(), []))); + for (const [name, delivery] of Object.entries(definitions)) + events.registerEvent(name, { emitOnly: true, payloadSchema: NotePayload, delivery }); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + + expect(await modesFor(clientEvents)).toEqual({ all: 'webhook', 'no-webhook': 'push', 'poll-only': 'poll' }); + } + { + // Without the webhook option the client cannot use webhook. + const { client, clientEvents } = eventsClient(); + const events = new EventsExtension(webhookOptions(senderTo(echoing, []))); + for (const [name, delivery] of Object.entries(definitions)) + events.registerEvent(name, { emitOnly: true, payloadSchema: NotePayload, delivery }); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + + expect(await modesFor(clientEvents)).toEqual({ all: 'push', 'no-webhook': 'push', 'poll-only': 'poll' }); + } +}); + +verifies('events:client:dedupe', async ({ transport }: TestArgs) => { + const { events, note } = noteEvents(); + const { client, clientEvents } = eventsClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + const first = await clientEvents.subscribe({ name: NOTE, arguments: { tag: 'first' }, delivery: 'push' }); + const second = await clientEvents.subscribe({ name: NOTE, arguments: { tag: 'second' }, delivery: 'push' }); + + await note.emit({ eventId: 'evt-1', data: { text: 'one' } }); + await note.emit({ eventId: 'evt-1', data: { text: 'one again' } }); + await note.emit({ eventId: 'evt-2', data: { text: 'two' } }); + + // The repeat is dropped on each subscription; the other subscription still gets evt-1. + expect(await take(first, 2)).toEqual([{ text: 'one' }, { text: 'two' }]); + expect(await take(second, 2)).toEqual([{ text: 'one' }, { text: 'two' }]); + await first.cancel(); + await second.cancel(); +}); + +// ─────────────────────────────────────────────────────────────────────────────── +// TypeScript SDK surface +// ─────────────────────────────────────────────────────────────────────────────── + +verifies('typescript:events:attach:rules', async ({ transport }: TestArgs) => { + const { events: first } = noteEvents(); + const second = new EventsExtension(); + second.registerEvent('other', { emitOnly: true, payloadSchema: NotePayload }); + const makeServer = () => { + const s = new McpServer({ name: 's', version: '0' }); + first.attach(s); + first.attach(s); + expect(() => second.attach(s)).toThrow(/another events extension is already attached/); + return s; + }; + const client = newClient(); + await using _ = await wire(transport, makeServer, client, EVENTS_WIRE); + + const { events: listed } = (await raw(client, 'events/list')) as { events: Array<{ name: string }> }; + expect(listed.map(descriptor => descriptor.name)).toEqual([NOTE]); + + const connected = new McpServer({ name: 's', version: '0' }); + const [, serverTransport] = InMemoryTransport.createLinkedPair(); + await connected.connect(serverTransport); + expect(() => second.attach(connected)).toThrow('attach events before connecting the server'); + await connected.close(); +}); + +verifies('typescript:events:definition:kinds', async ({ transport }: TestArgs) => { + const events = new EventsExtension(); + // As plain JavaScript calls it, past the types that refuse these definitions. + const register = events.registerEvent.bind(events) as unknown as (name: string, definition: Record) => unknown; + const check = () => ({ events: [], cursor: null }); + const kinds = /pass check\(\), or emitOnly: true/; + + expect(() => register('both', { emitOnly: true, check, payloadSchema: NotePayload })).toThrow(TypeError); + expect(() => register('both', { emitOnly: true, check, payloadSchema: NotePayload })).toThrow(kinds); + expect(() => register('neither', { payloadSchema: NotePayload })).toThrow(kinds); + expect(() => register('filtered', { check, match: () => true, payloadSchema: NotePayload })).toThrow(kinds); + events.registerEvent('pulled', { payloadSchema: NotePayload, check }); + events.registerEvent('pushed', { emitOnly: true, payloadSchema: NotePayload }); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + + const { events: listed } = (await raw(client, 'events/list')) as { events: Array<{ name: string }> }; + expect(listed.map(descriptor => descriptor.name)).toEqual(['pulled', 'pushed']); +}); + +verifies('typescript:events:errors', async ({ transport }: TestArgs) => { + const { events, note } = noteEvents(); + const { client, clientEvents } = eventsClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + + const unknown = await rejectionOf(clientEvents.subscribe({ name: 'missing', delivery: 'poll' })); + expect(unknown).toBeInstanceOf(EventsError); + expect(unknown).toMatchObject({ kind: 'notFound' }); + const invalid = await rejectionOf(clientEvents.subscribe({ name: NOTE, arguments: { tag: 5 }, delivery: 'poll' })); + expect(invalid).toBeInstanceOf(EventsError); + expect(invalid).toMatchObject({ kind: 'invalidParams' }); + + const noMode = await rejectionOf(clientEvents.subscribe({ name: NOTE, delivery: 'webhook' })); + expect(noMode).toBeInstanceOf(NoCompatibleDeliveryModeError); + expect(noMode).toBeInstanceOf(SdkError); + expect(noMode).toMatchObject({ eventName: NOTE, offered: ['poll', 'push'], usable: [] }); + + // A subscription the server ends: the loop rejects with the kind. + const subscription = await clientEvents.subscribe({ name: NOTE, delivery: 'push' }); + await note.terminate(new ServerEventsError('forbidden', 'Access revoked')); + const ended = await rejectionOf(take(subscription)); + expect(ended).toBeInstanceOf(EventsError); + expect(ended).toMatchObject({ kind: 'forbidden', message: 'Access revoked' }); +}); + +verifies('typescript:events:store:replicas', async ({ transport }: TestArgs) => { + const posts: Post[] = []; + const { client, clientEvents } = eventsClient({ ...FAST, webhook: { url: HOOK_URL, secretProvider: () => SECRET } }); + const options = webhookOptions(senderTo(clientEvents.createWebhookHandler(), posts), { + webhookStore: new InMemoryWebhookSubscriptionStore() + }); + const a = noteEvents(options); + const b = noteEvents(options); + let replica = a; + const makeServer = () => serving(replica.events)(); + await using wired = await wire(transport, makeServer, client, EVENTS_WIRE); + const subscription = await clientEvents.subscribe({ name: NOTE }); + expect(subscription.deliveryMode).toBe('webhook'); + const id = defined(posts[0], 'the verification POST').headers.get('x-mcp-subscription-id'); + + replica = b; + // Refresh, delivery and unsubscribe on the second replica. + await expect(raw(client, 'events/subscribe', { name: NOTE, delivery: hook() })).resolves.toMatchObject({ id }); + await b.note.emit({ data: { text: 'from b' } }); + expect(await take(subscription)).toEqual([{ text: 'from b' }]); + expect(eventPosts(posts).map(post => post.headers.get('x-mcp-subscription-id'))).toEqual([id]); + await subscription.cancel(); + expect(exchangesFor(wired, 'events/unsubscribe')).toHaveLength(1); + + await a.note.emit({ data: { text: 'after unsubscribe' } }); + await pause(50); + expect(eventPosts(posts)).toHaveLength(1); + expect(posts.filter(post => post.json.type === 'verification')).toHaveLength(1); +}); + +verifies('typescript:events:store:restart', async ({ transport }: TestArgs) => { + const posts: Post[] = []; + const { client, clientEvents } = eventsClient({ ...FAST, webhook: { url: HOOK_URL } }); + const options = webhookOptions(senderTo(clientEvents.createWebhookHandler(), posts), { + webhookStore: new InMemoryWebhookSubscriptionStore() + }); + let server = noteEvents(options); + const makeServer = () => serving(server.events)(); + await using wired = await wire(transport, makeServer, client, EVENTS_WIRE); + const subscription = await clientEvents.subscribe({ name: NOTE }); + const requests = wired.httpLog?.length; + + // The process restarts: a new extension over the same store, nothing carried over in memory. + server = noteEvents(options); + await server.note.emit({ data: { text: 'after the restart' } }); + + expect(await take(subscription)).toEqual([{ text: 'after the restart' }]); + expect(wired.httpLog?.length).toBe(requests); + expect(posts.map(post => post.json.type ?? 'event')).toEqual(['verification', 'event']); + await subscription.cancel(); +}); + +verifies('typescript:events:trusted-origins', async ({ transport }: TestArgs) => { + const ORIGIN = 'http://127.0.0.1:9000'; + const posts: Post[] = []; + const { events } = noteEvents(webhookOptions(senderTo(echoing, posts), { trustedOrigins: [ORIGIN] })); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + const subscribe = (url: string) => raw(client, 'events/subscribe', { name: NOTE, delivery: hook(SECRET, url) }); + + await expect(subscribe(`${ORIGIN}/hooks`)).resolves.toMatchObject({ id: expect.any(String) }); + expect(posts.map(post => [post.url, post.trusted])).toEqual([[`${ORIGIN}/hooks`, true]]); + for (const url of ['http://127.0.0.1:9001/hooks', 'http://localhost:9000/hooks', 'http://127.0.0.2:9000/hooks']) { + await expect(subscribe(url)).rejects.toMatchObject({ code: -32_602 }); + } + await expect(subscribe(HOOK_URL)).resolves.toMatchObject({ id: expect.any(String) }); + expect(posts.at(-1)).toMatchObject({ url: HOOK_URL, trusted: false }); + // Only exact origins can be listed. + expect(() => new EventsExtension({ trustedOrigins: [`${ORIGIN}/hooks`] })).toThrow(TypeError); + expect(() => new EventsExtension({ trustedOrigins: ['127.0.0.1:9000'] })).toThrow(TypeError); +}); + +verifies('typescript:events:experimental:subpaths', async () => { + const [server, client, serverEvents, clientEvents, node] = await Promise.all([ + import('@modelcontextprotocol/server'), + import('@modelcontextprotocol/client'), + import('@modelcontextprotocol/server/ext/events'), + import('@modelcontextprotocol/client/ext/events'), + import('@modelcontextprotocol/server/ext/events/node') + ]); + + expect(Object.keys(serverEvents)).toEqual( + expect.arrayContaining(['EventsExtension', 'InMemoryWebhookSubscriptionStore', 'EventsError']) + ); + expect(Object.keys(clientEvents)).toEqual( + expect.arrayContaining(['EventsClientExtension', 'NoCompatibleDeliveryModeError', 'EventsError']) + ); + expect(Object.keys(node)).toEqual(['nodeWebhookSender']); + const eventsApi = new Set([...Object.keys(serverEvents), ...Object.keys(clientEvents), ...Object.keys(node)]); + expect(Object.keys(server).filter(name => eventsApi.has(name))).toEqual([]); + expect(Object.keys(client).filter(name => eventsApi.has(name))).toEqual([]); +}); From 2236e1eef8417696063ea88255b45fa9903be7ce Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 19:16:32 +0200 Subject: [PATCH 25/37] test(e2e): keep shared Events requirement wording to the SEP, add SDK-specific entries --- test/e2e/requirements.ts | 15 +++++++++++-- test/e2e/scenarios/events.test.ts | 37 +++++++++++++++++++++++++++++-- 2 files changed, 48 insertions(+), 4 deletions(-) diff --git a/test/e2e/requirements.ts b/test/e2e/requirements.ts index fab03a0f8b..54dca4c875 100644 --- a/test/e2e/requirements.ts +++ b/test/e2e/requirements.ts @@ -3646,7 +3646,13 @@ export const REQUIREMENTS: Record = { 'events:capability:declared': { ...EVENTS_CELLS, source: `${EVENTS_SPEC}#capability-negotiation`, - behavior: "A server with Events attached declares extensions['io.modelcontextprotocol/events'] as {}." + behavior: + "A server that offers Events declares extensions['io.modelcontextprotocol/events'] with a settings object; an absent or false listChanged means no list-change notifications." + }, + 'typescript:events:capability:empty': { + ...EVENTS_CELLS, + source: 'sdk', + behavior: "This SDK's server declares the Events capability as {}." }, 'events:fallback:method-not-found': { ...EVENTS_CELLS, @@ -3754,7 +3760,12 @@ export const REQUIREMENTS: Record = { ...EVENTS_CELLS, source: `${EVENTS_SPEC}#subscription-ttl`, behavior: - "refreshBefore is at most the suggestion, except when clamped up to the server's floor, and at most the server cap; ttlMs: null gets a finite grant." + "refreshBefore is at most the suggestion, except when clamped up to the server's floor, and at most the server cap; a server that does not grant no-expiry answers ttlMs: null with a finite refreshBefore." + }, + 'typescript:events:webhook:no-expiry-refused': { + ...EVENTS_CELLS, + source: 'sdk', + behavior: "This SDK's server never grants no-expiry: a ttlMs: null subscribe gets a finite refreshBefore within the cap." }, 'events:webhook:refresh': { ...EVENTS_CELLS, diff --git a/test/e2e/scenarios/events.test.ts b/test/e2e/scenarios/events.test.ts index c35abba69b..77511949e0 100644 --- a/test/e2e/scenarios/events.test.ts +++ b/test/e2e/scenarios/events.test.ts @@ -184,7 +184,19 @@ verifies('events:capability:declared', async ({ transport }: TestArgs) => { const client = newClient(); await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); - expect(client.getServerCapabilities()?.extensions).toEqual({ [EVENTS_EXTENSION_ID]: {} }); + const settings = client.getServerCapabilities()?.extensions?.[EVENTS_EXTENSION_ID]; + expect(settings).toBeTypeOf('object'); + expect(settings).not.toBeNull(); + expect(Array.isArray(settings)).toBe(false); + expect([undefined, false]).toContain((settings as { listChanged?: unknown }).listChanged); +}); + +verifies('typescript:events:capability:empty', async ({ transport }: TestArgs) => { + const { events } = noteEvents(); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + + expect(client.getServerCapabilities()?.extensions?.[EVENTS_EXTENSION_ID]).toEqual({}); }); verifies('events:fallback:method-not-found', async ({ transport }: TestArgs) => { @@ -723,8 +735,29 @@ verifies('events:webhook:ttl', async ({ transport }: TestArgs) => { expect(within(await grantOf(120_000), 120_000)).toBe(true); expect(within(await grantOf(1000), FLOOR)).toBe(true); expect(within(await grantOf(3_600_000), CAP)).toBe(true); + // This server does not grant no-expiry, so ttlMs: null gets a finite refreshBefore. const unlimited = await grantOf(null); - expect(unlimited.max).toBeLessThanOrEqual(CAP); + expect(unlimited.min).toBeLessThanOrEqual(CAP); +}); + +verifies('typescript:events:webhook:no-expiry-refused', async ({ transport }: TestArgs) => { + for (const cap of [60_000, 3_600_000]) { + const { events } = noteEvents({ ...webhookOptions(senderTo(echoing, [])), webhookTtlMs: cap }); + const client = newClient(); + await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); + + // The first subscribe and a refresh alike. + for (let attempt = 0; attempt < 2; attempt++) { + const { refreshBefore } = await raw(client, 'events/subscribe', { name: NOTE, delivery: hook(), ttlMs: null }); + const answered = Date.now(); + expect(refreshBefore).toEqual(expect.any(String)); + const expiry = Date.parse(refreshBefore as string); + expect(Number.isFinite(expiry)).toBe(true); + // The server read its clock before the answer arrived, so the grant is at most expiry − answered. + expect(expiry).toBeGreaterThan(answered); + expect(expiry - answered).toBeLessThanOrEqual(cap); + } + } }); verifies('events:webhook:refresh', async ({ transport }: TestArgs) => { From 7533cd640c47b072b7dc240d9a36ebaa22283333 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 19:23:24 +0200 Subject: [PATCH 26/37] test(e2e): test the Events capability rule through the listen acknowledgement --- test/e2e/scenarios/events.test.ts | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/test/e2e/scenarios/events.test.ts b/test/e2e/scenarios/events.test.ts index 77511949e0..43d5f6fee5 100644 --- a/test/e2e/scenarios/events.test.ts +++ b/test/e2e/scenarios/events.test.ts @@ -188,7 +188,19 @@ verifies('events:capability:declared', async ({ transport }: TestArgs) => { expect(settings).toBeTypeOf('object'); expect(settings).not.toBeNull(); expect(Array.isArray(settings)).toBe(false); - expect([undefined, false]).toContain((settings as { listChanged?: unknown }).listChanged); + // Without listChanged: true, a listen stream that asks for event-list changes is acknowledged without them. + if ((settings as { listChanged?: unknown }).listChanged !== true) { + const tap = tapWire(client); + const filter: Record = { eventsListChanged: true }; + const subscription = await client.listen(filter as Parameters[0]); + + const ack = tap.received.find(message => 'method' in message && message.method === 'notifications/subscriptions/acknowledged'); + expect(defined(ack, 'the acknowledgement')).toMatchObject({ params: { notifications: expect.any(Object) } }); + expect((ack as Frame).params.notifications).not.toHaveProperty('eventsListChanged'); + expect(subscription.honoredFilter).not.toHaveProperty('eventsListChanged'); + await subscription.close(); + await subscription.closed; + } }); verifies('typescript:events:capability:empty', async ({ transport }: TestArgs) => { @@ -753,7 +765,7 @@ verifies('typescript:events:webhook:no-expiry-refused', async ({ transport }: Te expect(refreshBefore).toEqual(expect.any(String)); const expiry = Date.parse(refreshBefore as string); expect(Number.isFinite(expiry)).toBe(true); - // The server read its clock before the answer arrived, so the grant is at most expiry − answered. + // expiry − answered is a lower bound on the grant (the server read its clock before the answer arrived). expect(expiry).toBeGreaterThan(answered); expect(expiry - answered).toBeLessThanOrEqual(cap); } From b1eaf1f2ce5bba2edfde6e64f6d964dbe6f2c12d Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 21:43:52 +0200 Subject: [PATCH 27/37] fix(server): no SSE comment keepalive on events/stream --- docs/troubleshooting.md | 2 +- .../server/src/server/createMcpHandler.ts | 11 +++-- .../server/src/server/streamingMethods.ts | 2 +- packages/server/test/ext/events/harness.ts | 7 +++- packages/server/test/ext/events/push.test.ts | 40 +++++++++++++++++++ 5 files changed, 55 insertions(+), 7 deletions(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index f17adf26e6..c8da05465b 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -166,7 +166,7 @@ The Resource Server helpers did not move there: `requireBearerAuth`, `mcpAuthMet ## `SSE stream disconnected: TypeError: terminated` -HTTP SSE streams emit a `: keepalive` comment every 15 seconds by default so client body-idle timeouts and intermediaries do not terminate an otherwise idle connection. Configure the interval with `keepAliveMs` on the transport or `createMcpHandler`; set it to `0` to disable heartbeats. +HTTP SSE streams emit a `: keepalive` comment every 15 seconds by default so client body-idle timeouts and intermediaries do not terminate an otherwise idle connection. Configure the interval with `keepAliveMs` on the transport or `createMcpHandler`; set it to `0` to disable heartbeats. The Events extension's `events/stream` streams are the exception: their `notifications/events/heartbeat` messages keep them alive instead. ## Recap diff --git a/packages/server/src/server/createMcpHandler.ts b/packages/server/src/server/createMcpHandler.ts index 33febddabf..c2406488a1 100644 --- a/packages/server/src/server/createMcpHandler.ts +++ b/packages/server/src/server/createMcpHandler.ts @@ -202,7 +202,9 @@ export interface CreateMcpHandlerOptions { maxSubscriptions?: number; /** * SSE comment-frame keepalive interval for every SSE stream this handler - * serves. In modern `auto` mode it starts after SSE upgrade. Set to `0` to disable. + * serves, except the Events extension's `events/stream` streams, whose + * heartbeat notifications keep them alive. In modern `auto` mode it starts + * after SSE upgrade. Set to `0` to disable. * @default 15000 */ keepAliveMs?: number; @@ -902,14 +904,17 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa server.onclose = onExchangeClose; // A method the instance marks as streaming (`events/stream`) upgrades to SSE even under 'json'. - const exchangeMode = responseMode === 'json' && isStreamingMethod(server, route.message.method) ? 'auto' : responseMode; + const streaming = isStreamingMethod(server, route.message.method); + const exchangeMode = responseMode === 'json' && streaming ? 'auto' : responseMode; + // Its own heartbeat notifications keep a marked stream alive, so it gets no SSE comment keepalive (SEP-3415 §Push). + const keepAliveMs = streaming ? 0 : options.keepAliveMs; try { const response = await invoke(product, route.message, { classification: route.classification, request, ...(authInfo !== undefined && { authInfo }), ...(exchangeMode !== undefined && { responseMode: exchangeMode }), - ...(options.keepAliveMs !== undefined && { keepAliveMs: options.keepAliveMs }) + ...(keepAliveMs !== undefined && { keepAliveMs }) }); if (route.messageKind === 'notification') { // Notification exchanges have no terminal response to ride the diff --git a/packages/server/src/server/streamingMethods.ts b/packages/server/src/server/streamingMethods.ts index f443ce3012..56959cc870 100644 --- a/packages/server/src/server/streamingMethods.ts +++ b/packages/server/src/server/streamingMethods.ts @@ -3,7 +3,7 @@ import type { Server } from './server'; // Methods each server answers as a stream whatever `responseMode` says, as `createMcpHandler` streams `subscriptions/listen`. const streamingMethods = new WeakMap>(); -// Makes `createMcpHandler` serve `method` on `server` with `'auto'` where `responseMode: 'json'` is configured. +// Makes `createMcpHandler` serve `method` on `server` with `'auto'` where `responseMode: 'json'` is configured, and without SSE comment keepalives. export function markStreamingMethod(server: Server, method: string): void { const methods = streamingMethods.get(server) ?? new Set(); methods.add(method); diff --git a/packages/server/test/ext/events/harness.ts b/packages/server/test/ext/events/harness.ts index dfb23f0d8c..c8913bbaf9 100644 --- a/packages/server/test/ext/events/harness.ts +++ b/packages/server/test/ext/events/harness.ts @@ -53,7 +53,7 @@ function modernHeaders(message: JSONRPCRequest | JSONRPCNotification): Record void } = {} + options: { authInfo?: AuthInfo; responseMode?: 'auto' | 'json'; keepAliveMs?: number; setup?: (mcp: McpServer) => void } = {} ): Served { const handler = createMcpHandler( () => { @@ -62,7 +62,10 @@ export function serve( options.setup?.(mcp); return mcp; }, - options.responseMode === undefined ? {} : { responseMode: options.responseMode } + { + ...(options.responseMode !== undefined && { responseMode: options.responseMode }), + ...(options.keepAliveMs !== undefined && { keepAliveMs: options.keepAliveMs }) + } ); const post = (message: JSONRPCRequest | JSONRPCNotification, init: PostInit = {}): Promise => { diff --git a/packages/server/test/ext/events/push.test.ts b/packages/server/test/ext/events/push.test.ts index 09925c0c0b..2781e83813 100644 --- a/packages/server/test/ext/events/push.test.ts +++ b/packages/server/test/ext/events/push.test.ts @@ -543,4 +543,44 @@ describe('events/stream: response modes', () => { expect(text).not.toContain('notifications/progress'); expect(JSON.parse(text)).toMatchObject({ id: 2, result: { content: [{ type: 'text', text: 'done' }] } }); }); + + it('sends no SSE comment keepalive on events/stream, while another SSE exchange still gets one (SEP-3415 §Push)', async () => { + const events = new EventsExtension(); + events.registerEvent('tick', { payloadSchema: P, check: () => ({ events: [], cursor: 'h0' }) }); + const served = serve(events, { + keepAliveMs: 20, + setup: mcp => + mcp.registerTool('slow', { inputSchema: z.object({}) }, async (_args, ctx) => { + await ctx.mcpReq.notify({ method: 'notifications/progress', params: { progressToken: 'tok', progress: 1 } }); + await new Promise(resolve => setTimeout(resolve, 150)); + return { content: [{ type: 'text', text: 'done' }] }; + }) + }); + + const stream = await open(served, { name: 'tick', cursor: null }); + expect(stream.response.headers.get('content-type')).toContain('text/event-stream'); + const streamed = await rawFor(stream.response, 150); + expect(streamed).toContain(ACTIVE); + expect(streamed).not.toMatch(/^:/m); + + const tool = await served.post({ jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'slow', arguments: {} } }); + expect(tool.headers.get('content-type')).toContain('text/event-stream'); + expect(await tool.text()).toMatch(/^: keepalive$/m); + }); }); + +// The raw SSE text a response delivers within `ms`, comment lines included. +async function rawFor(response: Response, ms: number): Promise { + const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader(); + const timer = setTimeout(() => void reader.cancel(), ms); + let text = ''; + try { + for (;;) { + const { done, value } = await reader.read(); + if (done) return text; + text += value; + } + } finally { + clearTimeout(timer); + } +} From e33b52591a836abd937014c28e877104bdc65353 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 21:43:52 +0200 Subject: [PATCH 28/37] test(conformance): Events fixture and client scenarios (local until released) --- test/conformance/expected-failures.yaml | 62 +++ test/conformance/package.json | 2 + .../scripts/run-server-conformance.sh | 2 +- test/conformance/src/events.ts | 372 ++++++++++++++++++ test/conformance/src/everythingClient.ts | 34 ++ test/conformance/src/everythingServer.ts | 5 + 6 files changed, 476 insertions(+), 1 deletion(-) create mode 100644 test/conformance/src/events.ts diff --git a/test/conformance/expected-failures.yaml b/test/conformance/expected-failures.yaml index bedba50604..de1375a097 100644 --- a/test/conformance/expected-failures.yaml +++ b/test/conformance/expected-failures.yaml @@ -54,6 +54,36 @@ client: # scenarios never match a --spec-version filter). # (SEP-1932 DPoP burned by the auth/dpop + auth/dpop-nonce client implementation.) - auth/wif-jwt-bearer + # + # --- Events (SEP-3415): local-only until released --- + # Run by `test:conformance:client:events` against a local build of + # conformance#541 (EVENTS_CONFORMANCE_DIR); no released referee has these + # scenarios, so the released legs never read these entries. + # The client never opens subscriptions/listen for list_changed (follow-up PR). + - events-client-poll:sep-3415-client-listen-opt-in + # Same: list_changed has no channel to arrive on, so the re-list is never triggered. + - events-client-poll:sep-3415-client-relist-on-list-changed + # + # --- Events: conformance#541 mock defects (reported upstream) --- + # The client stays strict; each row grades once the mock sends the field it names. + # The mock's descriptors omit payloadSchema (SEP l.15), so the client refuses events/list and never polls. + - events-client-poll:sep-3415-client-poll-drain-on-has-more + - events-client-poll:sep-3415-client-poll-respects-next-poll-ms + - events-client-poll:sep-3415-client-poll-floor + - events-client-poll:sep-3415-client-truncated-persists-fresh-cursor + - events-client-poll:sep-3415-client-null-cursor-not-replayed + - events-client-poll:sep-3415-client-cursor-absent-tolerated + - events-client-poll:sep-3415-client-mcp-name-set + - events-client-poll:sep-3415-client-mcp-name-base64 + # Descriptors omit payloadSchema (SEP l.15) and active omits heartbeatMs (SEP l.382), so no stream or reconnect. + - events-client-push:sep-3415-client-stream-reconnect-with-cursor + - events-client-push:sep-3415-client-null-cursor-not-replayed + # The mock's descriptors omit payloadSchema (SEP l.15), so the client refuses events/list and never streams. + - events-client-push:sep-3415-client-mcp-name-set + # The mock's descriptors omit payloadSchema (SEP l.15), so the client refuses events/list and never subscribes. + - events-client-webhook:sep-3415-client-refresh-before-expiry + - events-client-webhook:sep-3415-client-null-cursor-not-replayed + - events-client-webhook:sep-3415-client-mcp-name-set server: # --- SEP-2663 (io.modelcontextprotocol/tasks) — server SDK does not implement the tasks extension --- @@ -72,3 +102,35 @@ server: - tasks-dispatch-and-envelope - tasks-required-task-error - tasks-mrtr-composition + # + # --- Events (SEP-3415): local-only until released --- + # Run by `test:conformance:server:events` against a local build of + # conformance#541 (EVENTS_CONFORMANCE_DIR); no released referee has these + # scenarios, so the released legs never read these entries. + # The server grants only finite TTLs (no-expiry is a non-goal), so these have nothing to grade. + - events-webhook:sep-3415-ttl-no-expiry-persisted + - events-webhook:sep-3415-ttl-no-expiry-gc-terminated + # + # --- Events: events/list is one page --- + # The SDK serves events/list as one page (no page size), so the cursor round trip is reported untestable. + - events-discovery:sep-3415-list-pagination + # + # --- Events: untestable by the suite's own construction --- + # The referee reports these "Not testable" for a conformant server; each stays until it can grade them. + # Suspension shows only in the optional deliveryStatus, after sustained failure to a callback the suite controls. + - events-webhook:sep-3415-subscribe-refresh-reactivates + # Graded on the cursor:null bootstrap poll, which starts from now and so never has a backlog. + - events-poll:sep-3415-poll-next-poll-ms-ignored-when-has-more + # Needs truncated from the maxAgeMs probe, whose fresh cursor is never past the floor. + - events-poll:sep-3415-truncated-returns-fresh-cursor + # The harness cannot mint a stale cursor; reported untestable for every server. + - events-poll:sep-3415-max-age-ms-sets-truncated + - events-poll:sep-3415-replay-ceiling-sets-truncated + # The receiver cannot tell the verification POST's code path from a delivery's. + - events-webhook-delivery:sep-3415-verification-uses-ssrf-hardened-path + # Needs a second principal, a restart or a key-discovery origin the scenario does not set up. + - events-webhook-delivery:sep-3415-verification-cached-per-principal-url + - events-webhook-delivery:sep-3415-verification-persisted-for-no-expiry + - events-webhook-delivery:sep-3415-server-identity-key-discovery + # Needs a secret rotated while a delivery is in flight, which the harness cannot time. + - events-webhook-delivery:sep-3415-delivery-dual-sign-on-rotation diff --git a/test/conformance/package.json b/test/conformance/package.json index 7c237045d9..e2669d2fd7 100644 --- a/test/conformance/package.json +++ b/test/conformance/package.json @@ -30,6 +30,7 @@ "test:conformance:client:all": "conformance client --command 'node --import tsx ./src/everythingClient.ts' --suite all --expected-failures ./expected-failures.yaml", "test:conformance:client:2026": "conformance client --command 'node --import tsx ./src/everythingClient.ts' --suite all --spec-version 2026-07-28 --expected-failures ./expected-failures.2026-07-28.yaml", "test:conformance:client:skills:2026": "for s in sep-2640-client-verify-digest sep-2640-client-verify-size sep-2640-client-verify-frontmatter sep-2640-client-no-prefetch; do conformance client --command 'node --import tsx ./src/everythingClient.ts' --scenario $s --spec-version 2026-07-28 --force || exit 1; done", + "test:conformance:client:events": "export CONFORMANCE_CLI=\"node ${EVENTS_CONFORMANCE_DIR:?set EVENTS_CONFORMANCE_DIR to a built checkout of conformance#541}/dist/index.js\"; for s in events-client-poll events-client-push events-client-webhook events-client-no-extension; do $CONFORMANCE_CLI client --command 'node --import tsx ./src/everythingClient.ts' --scenario $s --spec-version 2026-07-28 --force --expected-failures ./expected-failures.yaml || exit 1; done", "test:conformance:client:run": "node --import tsx ./src/everythingClient.ts", "test:conformance:server": "scripts/run-server-conformance.sh --expected-failures ./expected-failures.yaml", "test:conformance:server:draft": "scripts/run-server-conformance.sh --suite draft --expected-failures ./expected-failures.yaml", @@ -37,6 +38,7 @@ "test:conformance:server:all": "scripts/run-server-conformance.sh --suite all --expected-failures ./expected-failures.yaml", "test:conformance:server:2026": "scripts/run-server-conformance.sh --suite all --spec-version 2026-07-28 --expected-failures ./expected-failures.2026-07-28.yaml", "test:conformance:server:skills:2025": "for s in sep-2640-skills-enumeration sep-2640-skills-manifest sep-2640-skills-directory; do scripts/run-server-conformance.sh --scenario $s --spec-version 2025-11-25 --force || exit 1; done", + "test:conformance:server:events": "export CONFORMANCE_CLI=\"node ${EVENTS_CONFORMANCE_DIR:?set EVENTS_CONFORMANCE_DIR to a built checkout of conformance#541}/dist/index.js\"; for s in events-discovery events-poll events-push events-webhook events-webhook-delivery; do scripts/run-server-conformance.sh --scenario $s --expected-failures ./expected-failures.yaml --timeout 60000 || exit 1; done", "test:conformance:server:run": "node --import tsx ./src/everythingServer.ts", "test:conformance:all": "pnpm run test:conformance:client:all && pnpm run test:conformance:server:all" }, diff --git a/test/conformance/scripts/run-server-conformance.sh b/test/conformance/scripts/run-server-conformance.sh index 7bd9931a4d..0e96f4ec41 100755 --- a/test/conformance/scripts/run-server-conformance.sh +++ b/test/conformance/scripts/run-server-conformance.sh @@ -57,6 +57,6 @@ done echo "Server is ready. Running conformance tests..." # Run conformance tests - pass through all arguments -npx @modelcontextprotocol/conformance server --url "${SERVER_URL}" "$@" +${CONFORMANCE_CLI:-npx @modelcontextprotocol/conformance} server --url "${SERVER_URL}" "$@" echo "Conformance tests completed." diff --git a/test/conformance/src/events.ts b/test/conformance/src/events.ts new file mode 100644 index 0000000000..3ec1d426f3 --- /dev/null +++ b/test/conformance/src/events.ts @@ -0,0 +1,372 @@ +/** + * Events (SEP-3415) served by the conformance server, and the thirteen + * `events_conformance_*` control tools the conformance#521 server suites + * drive. Three event types: a counter (a check type offering every mode), an + * emit-only alert feed, and a pulse with no replay (`cursor: null`). + */ +import { randomBytes } from 'node:crypto'; + +import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'; +import type { AuthInfo, CallToolResult, McpServer } from '@modelcontextprotocol/server'; +import { createMcpHandler, McpServer as Server } from '@modelcontextprotocol/server'; +import type { CheckContext, EventHandle, EventResult, WebhookSender } from '@modelcontextprotocol/server/ext/events'; +import { EventsError, EventsExtension, InMemoryWebhookSubscriptionStore } from '@modelcontextprotocol/server/ext/events'; +import { nodeWebhookSender } from '@modelcontextprotocol/server/ext/events/node'; +import * as z from 'zod/v4'; + +const COUNTER = 'conformance.counter'; +const ALERTS = 'conformance.alerts'; +const PULSE = 'conformance.pulse'; + +// The principal of every request, unless subscribe_as authenticates its own subscribe as another. +const PRINCIPAL = 'mcp-conformance'; +const PRINCIPAL_EXTRA = 'principal'; +const MAX_SUBSCRIPTIONS = 16; +const COUNTER_TICK_MS = 2000; +const COUNTER_RETENTION = 1000; +const ALERT_EVERY_MS = 3000; +const PULSE_EVERY_MS = 5000; + +// The callback origin conformance#521's events-webhook subscribes with; it exists only to be a distinct key. +const PLACEHOLDER_ORIGIN = 'https://conformance.invalid'; + +// Outside the extension's process state, so a simulated restart leaves webhook subscriptions in place. +const store = new InMemoryWebhookSubscriptionStore(); + +const nodeSender = nodeWebhookSender(); + +// Emulates the SEP's server-configured allowlist (verification path 2) for the suite's placeholder origin, as #521's allow_callback_origin JSDoc describes; the SDK itself only does the handshake. +const webhookSender: WebhookSender = async request => { + if (new URL(request.url).origin === PLACEHOLDER_ORIGIN) { + const body = JSON.parse(request.body) as { type?: unknown; challenge?: unknown }; + if (body.type === 'verification') return { status: 200, body: JSON.stringify({ challenge: body.challenge }) }; + } + return nodeSender(request); +}; + +export const conformanceEvents = new EventsExtension({ + webhookTtlMs: 3_600_000, + webhookSender, + webhookStore: store, + getPrincipal: ctx => (ctx.http?.authInfo?.extra?.[PRINCIPAL_EXTRA] as string | undefined) ?? PRINCIPAL, + // Under the counter's tick, so heartbeats show between events. + heartbeatMs: 1000, + // So a control's error or gap reaches a stream or webhook well within the suites' five-second waits. + checkIntervalMs: 1000, + maxSubscriptions: MAX_SUBSCRIPTIONS +}); + +// The internal controls the fixture needs from the extension (Symbol.for('mcp.events.testHook')). +interface EventsTestHook { + generation(): number; + restart(): void; + addTrustedOrigin(origin: string): void; +} + +const testHook = (conformanceEvents as unknown as Record)[Symbol.for('mcp.events.testHook')]!; + +// The counter's upstream: one tick every COUNTER_TICK_MS, the last COUNTER_RETENTION of them kept. +const ticks: { n: number; eventId: string; timestamp: string }[] = []; +let head = 0; +setInterval(() => { + head += 1; + ticks.push({ n: head, eventId: `tick-${head}`, timestamp: new Date().toISOString() }); + if (ticks.length > COUNTER_RETENTION) ticks.shift(); +}, COUNTER_TICK_MS).unref(); + +// Upstream conditions the controls ask for, keyed by event type or webhook subscription id, each taken by the next read. +const failNext = new Set(); +const gapNext = new Set(); + +function take(set: Set, ctx: CheckContext): boolean { + return set.delete(ctx.name) || set.delete(ctx.subscriptionId); +} + +function readCounter(ctx: CheckContext, cursor: string | null): EventResult<{ n: number }> { + if (cursor === null) return { events: [], cursor: String(head) }; + if (take(failNext, ctx)) throw new Error('counter upstream unavailable (events_conformance_yield_error)'); + const from = /^\d+$/.test(cursor) ? Number(cursor) : Number.NaN; + const oldest = ticks[0]?.n ?? head + 1; + // A gap, a cursor this counter never issued, or one older than its retention: resume from now. + if (take(gapNext, ctx) || !(from <= head) || from < oldest - 1) return { events: [], cursor: String(head), truncated: true }; + const since = ticks.filter(tick => tick.n > from); + const batch = since.slice(0, ctx.maxEvents ?? since.length); + return { + events: batch.map(({ n, eventId, timestamp }) => ({ eventId, timestamp, data: { n } })), + cursor: String(batch.at(-1)?.n ?? from), + hasMore: batch.length < since.length + }; +} + +const counter = conformanceEvents.registerEvent(COUNTER, { + description: 'A counter that ticks every two seconds; replays from a cursor.', + inputSchema: z.object({ label: z.string().optional() }), + payloadSchema: z.object({ n: z.number().int() }), + check: (ctx, _args, cursor) => readCounter(ctx, cursor) +}); + +const alerts = conformanceEvents.registerEvent(ALERTS, { + emitOnly: true, + description: 'Alerts emitted every three seconds, filtered by minimum severity; poll only.', + inputSchema: z.object({ minSeverity: z.number().int().min(0).max(3).optional() }), + payloadSchema: z.object({ severity: z.number().int(), message: z.string() }), + match: (_ctx, event, args) => event.data.severity >= (args.minSeverity ?? 0), + transform: (_ctx, event, args) => ({ + ...event, + data: { ...event.data, message: `[min ${args.minSeverity ?? 0}] ${event.data.message}` } + }), + delivery: { push: false, webhook: false } +}); +let alertCount = 0; +setInterval(() => { + alertCount += 1; + alerts.emit({ data: { severity: alertCount % 4, message: `alert ${alertCount}` } }).catch(() => {}); +}, ALERT_EVERY_MS).unref(); + +// The pulse has no history: each subscription gets the beats since its own previous read, and never a cursor. +let beat = 0; +setInterval(() => (beat += 1), PULSE_EVERY_MS).unref(); +const beatSeen = new Map(); + +const pulse = conformanceEvents.registerEvent(PULSE, { + description: 'A live pulse every five seconds with no replay; every cursor is null. Push and webhook only.', + inputSchema: z.object({}), + payloadSchema: z.object({ beat: z.number().int() }), + check: ctx => { + const seen = beatSeen.get(ctx.subscriptionId); + beatSeen.set(ctx.subscriptionId, beat); + return { events: seen === undefined || seen === beat ? [] : [{ data: { beat } }], cursor: null }; + }, + onUnsubscribe: ctx => void beatSeen.delete(ctx.subscriptionId), + delivery: { poll: false } +}); + +// The handle of every event type served, by name, so controls can update, remove or terminate it. +const handles = new Map([ + [COUNTER, counter], + [ALERTS, alerts], + [PULSE, pulse] +]); + +// Event types the catalog control added, and the payload revision of each. +const minted = new Map(); +let mintedCount = 0; + +function mint(name: string, revision: number): EventHandle { + return conformanceEvents.registerEvent(name, { + emitOnly: true, + description: `Added by events_conformance_catalog (payload revision ${revision}).`, + inputSchema: z.object({}), + payloadSchema: z.object({ revision: z.literal(revision) }) + }); +} + +// A subscribe sent on another principal's behalf, through a server serving the same extension and store. +const subscribeAsHandler = createMcpHandler(() => { + const server = new Server({ name: 'events-conformance-subscribe-as', version: '1.0.0' }); + conformanceEvents.attach(server); + return server; +}); + +async function subscribeAs(principal: string, name: string, url: string): Promise { + const authInfo: AuthInfo = { + token: 'events-conformance', + clientId: 'events-conformance', + scopes: [], + extra: { [PRINCIPAL_EXTRA]: principal } + }; + const client = new Client( + { name: 'events-conformance-subscribe-as', version: '1.0.0' }, + { versionNegotiation: { mode: { pin: '2026-07-28' } } } + ); + await client.connect( + new StreamableHTTPClientTransport(new URL('http://localhost/mcp'), { + fetch: (input, init) => subscribeAsHandler.fetch(new Request(input, init), { authInfo }) + }) + ); + try { + const secret = `whsec_${randomBytes(32).toString('base64')}`; + const result = await client.request( + { method: 'events/subscribe', params: { name, arguments: {}, delivery: { mode: 'webhook', url, secret } } }, + z.looseObject({ id: z.string() }) + ); + return result.id; + } finally { + await client.close(); + } +} + +async function liveRecord(id: string) { + const record = await store.get(id); + return record !== undefined && record.expiresAt > Date.now() ? record : undefined; +} + +const text = (value: string): CallToolResult => ({ content: [{ type: 'text', text: value }] }); +const refuse = (reason: string): CallToolResult => ({ isError: true, content: [{ type: 'text', text: reason }] }); + +function forbidden(control: string): EventsError { + return new EventsError('forbidden', `Ended by ${control}`); +} + +/** Registers the `events_conformance_*` control tools on `mcp`, each as conformance#521 `helpers.ts` defines it. */ +export function registerEventsControls(mcp: McpServer): void { + const named = z.object({ name: z.string() }); + const byId = z.object({ id: z.string() }); + const tenant = z.object({ principal: z.string(), name: z.string(), url: z.string() }); + const none = z.object({}); + + mcp.registerTool( + 'events_conformance_allow_callback_origin', + { description: 'Trusts one webhook callback origin for the rest of the process.', inputSchema: z.object({ origin: z.string() }) }, + ({ origin }) => { + try { + testHook.addTrustedOrigin(origin); + } catch (error) { + return refuse(String(error)); + } + return text('ok'); + } + ); + + mcp.registerTool( + 'events_conformance_catalog', + { + description: 'Adds an event type (answers "ok: "), or removes, retypes or extends one it added.', + inputSchema: z.object({ op: z.enum(['add', 'remove', 'retype', 'extend']), name: z.string().optional() }) + }, + ({ op, name }) => { + if (op === 'add') { + const added = `conformance.minted.${++mintedCount}`; + minted.set(added, 1); + handles.set(added, mint(added, 1)); + return text(`ok: ${added}`); + } + const revision = name === undefined ? undefined : minted.get(name); + const handle = name === undefined ? undefined : handles.get(name); + if (name === undefined || revision === undefined || handle === undefined) { + return refuse(`${op} needs the name of a type this control added`); + } + if (op === 'remove') { + handle.remove(); + minted.delete(name); + handles.delete(name); + } else if (op === 'retype') { + minted.set(name, revision + 1); + handles.set(name, mint(name, revision + 1)); + } else { + handle.update({ inputSchema: z.object({ note: z.string().optional() }) }); + } + return text('ok'); + } + ); + + mcp.registerTool('events_conformance_generation', { description: 'Answers the current restart generation.', inputSchema: none }, () => + text(String(testHook.generation())) + ); + + mcp.registerTool( + 'events_conformance_quota', + { description: 'Answers the subscription cap and an event type it applies to, as {"name", "max"}.', inputSchema: none }, + () => text(JSON.stringify({ name: COUNTER, max: MAX_SUBSCRIPTIONS })) + ); + + mcp.registerTool( + 'events_conformance_restart', + { + description: "Drops the extension's process state as a restart would, keeping the store; answers the new generation.", + inputSchema: none + }, + () => { + testHook.restart(); + return text(String(testHook.generation())); + } + ); + + mcp.registerTool( + 'events_conformance_subscribe_as', + { description: "Subscribes a webhook on another principal's behalf; answers the subscription id.", inputSchema: tenant }, + async ({ principal, name, url }) => { + try { + return text(await subscribeAs(principal, name, url)); + } catch (error) { + return refuse(String(error)); + } + } + ); + + mcp.registerTool( + 'events_conformance_subscription_exists', + { + description: 'Answers "true" while a principal\'s webhook subscription to a callback is registered, else "false".', + inputSchema: tenant + }, + async ({ principal, name, url }) => { + for await (const record of store.listByName(name)) { + if (record.principal === principal && record.url === url && record.expiresAt > Date.now()) return text('true'); + } + return text('false'); + } + ); + + mcp.registerTool( + 'events_conformance_subscription_state', + { description: 'Answers "active" or "absent" for a webhook subscription id.', inputSchema: byId }, + async ({ id }) => text((await liveRecord(id)) === undefined ? 'absent' : 'active') + ); + + mcp.registerTool( + 'events_conformance_terminate', + { description: 'Ends every live subscription to an event type with a forbidden error.', inputSchema: named }, + async ({ name }) => { + const handle = handles.get(name); + if (handle === undefined) return refuse(`no event type ${name}`); + await handle.terminate(forbidden('events_conformance_terminate')); + return text('ok'); + } + ); + + mcp.registerTool( + 'events_conformance_webhook_gap', + { description: 'Makes the next read of one counter webhook subscription report a gap, sent as a gap envelope.', inputSchema: byId }, + async ({ id }) => { + const record = await liveRecord(id); + if (record?.name !== COUNTER) return refuse(`no ${COUNTER} webhook subscription ${id}`); + gapNext.add(id); + return text('ok'); + } + ); + + mcp.registerTool( + 'events_conformance_webhook_terminate', + { description: 'Ends one webhook subscription with a forbidden error, sent as a terminated envelope.', inputSchema: byId }, + async ({ id }) => { + const record = await liveRecord(id); + const handle = record === undefined ? undefined : handles.get(record.name); + if (handle === undefined) return refuse(`no webhook subscription ${id}`); + await handle.terminate(forbidden('events_conformance_webhook_terminate'), { subscriptionId: id }); + return text('ok'); + } + ); + + mcp.registerTool( + 'events_conformance_yield_error', + { description: "Makes the counter's next read fail with a transient upstream error.", inputSchema: named }, + ({ name }) => { + if (name !== COUNTER) return refuse(`only ${COUNTER} has an upstream that can fail`); + failNext.add(name); + return text('ok'); + } + ); + + // The pulse has no position to skip past, so a gap on it changes nothing it reports. + mcp.registerTool( + 'events_conformance_yield_gap', + { description: "Makes the counter's next read report a gap (truncated, with a fresh cursor).", inputSchema: named }, + ({ name }) => { + if (name === PULSE) return text('ok'); + if (name !== COUNTER) return refuse(`only ${COUNTER} has history to lose`); + gapNext.add(name); + return text('ok'); + } + ); +} diff --git a/test/conformance/src/everythingClient.ts b/test/conformance/src/everythingClient.ts index 2c9849cf0a..dd972ca9df 100644 --- a/test/conformance/src/everythingClient.ts +++ b/test/conformance/src/everythingClient.ts @@ -20,6 +20,8 @@ import { requestJwtAuthorizationGrant, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'; +import type { EventSubscription } from '@modelcontextprotocol/client/ext/events'; +import { EventsClientExtension } from '@modelcontextprotocol/client/ext/events'; import { SkillsClient, SkillVerificationError } from '@modelcontextprotocol/client/ext/skills'; import * as z from 'zod/v4'; @@ -953,6 +955,38 @@ registerScenarios( ); registerScenario('sep-2640-client-no-prefetch', runSkillsNoPrefetchClient); +// ============================================================================ +// SEP-3415 Events +// ============================================================================ + +// The events-client-* harness never POSTs to the callback; it only watches the subscribe calls. +const EVENTS_WEBHOOK_URL = 'https://conformance-test.local/mcp-events'; + +// Subscribe to every listed event type for the scenario's durationMs, then cancel; send nothing without the extension. +async function runEventsClient(serverUrl: string): Promise { + const { durationMs } = z.object({ durationMs: z.number() }).parse(JSON.parse(process.env.MCP_CONFORMANCE_CONTEXT ?? '{}')); + const events = new EventsClientExtension({ webhook: { url: EVENTS_WEBHOOK_URL } }); + const client = new Client({ name: 'test-client', version: '1.0.0' }, { capabilities: {}, versionNegotiation: { mode: 'auto' } }); + events.attach(client); + await client.connect(new StreamableHTTPClientTransport(new URL(serverUrl))); + const subscriptions: EventSubscription[] = []; + if (events.supported) { + const listed = await events.list(); + for (const { name } of listed.events) { + void (async () => { + const subscription = await events.subscribe({ name }); + subscriptions.push(subscription); + for await (const event of subscription) logger.debug(`${name}: event ${event.eventId}`); + })().catch((error: unknown) => logger.debug(`${name}: subscription ended:`, error)); + } + } + await new Promise(resolve => setTimeout(resolve, durationMs)); + await Promise.all(subscriptions.map(subscription => subscription.cancel())); + await client.close(); +} + +registerScenarios(['events-client-poll', 'events-client-push', 'events-client-webhook', 'events-client-no-extension'], runEventsClient); + // ============================================================================ // Main entry point // ============================================================================ diff --git a/test/conformance/src/everythingServer.ts b/test/conformance/src/everythingServer.ts index 2aa3d31601..42634975c1 100644 --- a/test/conformance/src/everythingServer.ts +++ b/test/conformance/src/everythingServer.ts @@ -43,6 +43,7 @@ import type { Request, Response } from 'express'; import express from 'express'; import * as z from 'zod/v4'; +import { conformanceEvents, registerEventsControls } from './events'; import { conformanceSkills } from './skills'; // Server state @@ -172,6 +173,10 @@ function createMcpServer() { // SEP-2640: skills/list, skills/get, resources/directory/read and the skill:// resource template. conformanceSkills.attach(mcpServer); + // SEP-3415: events/* and the events_conformance_* control tools. + conformanceEvents.attach(mcpServer); + registerEventsControls(mcpServer); + // Helper to send log messages using the underlying server function sendLog( level: 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency', From 847ce2d7e9891d82d5b9b48298e0deb48e67e008 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 21:59:40 +0200 Subject: [PATCH 29/37] fix(server): no truncated flag on a null cursor (non-replayable event types) --- packages/server/src/ext/events/poll.ts | 5 +++-- packages/server/src/ext/events/types.ts | 2 +- packages/server/test/ext/events/poll.test.ts | 6 ++++++ packages/server/test/ext/events/push.test.ts | 14 ++++++++++++++ .../test/ext/events/webhookSubscriptions.test.ts | 12 ++++++++++++ test/conformance/src/events.ts | 13 ++++++++----- 6 files changed, 44 insertions(+), 8 deletions(-) diff --git a/packages/server/src/ext/events/poll.ts b/packages/server/src/ext/events/poll.ts index 03b09d569f..9d9db55c33 100644 --- a/packages/server/src/ext/events/poll.ts +++ b/packages/server/src/ext/events/poll.ts @@ -48,7 +48,7 @@ export async function toOccurrence( }; } -// A check result's events to send: off-schema ones dropped (reported), ones older than `maxAgeMs` skipped with `truncated`. +// A check result's events to send, for every mode: off-schema ones dropped (reported), ones older than `maxAgeMs` skipped with `truncated`. export async function checkedEvents( entry: RegisteredEvent, result: EventResult, @@ -67,7 +67,8 @@ export async function checkedEvents( } events.push(occurrence); } - return { events, truncated }; + // A `cursor: null` result (no replay) has no position to skip past, so it never reports `truncated` (SEP-3415 §Cursor Lifecycle). + return { events, truncated: truncated && result.cursor !== null }; } // What one subscription receives of an emitted event: broadcasts pass `match`, targeted ones reach only their subscription. A throwing hook skips the event. diff --git a/packages/server/src/ext/events/types.ts b/packages/server/src/ext/events/types.ts index 03f839d6f8..628018959d 100644 --- a/packages/server/src/ext/events/types.ts +++ b/packages/server/src/ext/events/types.ts @@ -72,7 +72,7 @@ export interface EventResult

> { cursor: string | null; /** How long a poll client should wait before polling again. */ nextPollMs?: number; - /** The upstream lost history since the cursor it was given. */ + /** The upstream lost history since the cursor it was given. Ignored with `cursor: null`, which has no position to skip past. */ truncated?: boolean; /** More events are waiting beyond `ctx.maxEvents`. */ hasMore?: boolean; diff --git a/packages/server/test/ext/events/poll.test.ts b/packages/server/test/ext/events/poll.test.ts index dd3b4d614c..b3444414de 100644 --- a/packages/server/test/ext/events/poll.test.ts +++ b/packages/server/test/ext/events/poll.test.ts @@ -94,6 +94,12 @@ describe('events/poll for a check type', () => { expect(await poller(events).poll({ name: 't', cursor: 'h1' })).toMatchObject({ truncated: true, hasMore: true }); }); + it('answers truncated: false for a result with cursor: null (SEP-3415 §Cursor Lifecycle)', async () => { + const events = new EventsExtension(); + events.registerEvent('t', { payloadSchema: P, check: () => ({ events: [], cursor: null, truncated: true }) }); + expect(await poller(events).poll({ name: 't', cursor: 'h1' })).toMatchObject({ events: [], cursor: null, truncated: false }); + }); + it('applies the maxAgeMs floor and flags truncated', async () => { const events = new EventsExtension(); const old = new Date(Date.now() - 600_000).toISOString(); diff --git a/packages/server/test/ext/events/push.test.ts b/packages/server/test/ext/events/push.test.ts index 2781e83813..6b10e6d34b 100644 --- a/packages/server/test/ext/events/push.test.ts +++ b/packages/server/test/ext/events/push.test.ts @@ -230,6 +230,20 @@ describe('events/stream: a check type', () => { expect(check.mock.calls.map(call => call[2])).toEqual(['h1', 'h3']); }); + it('confirms a cursor: null result with truncated: false, and sends no fresh active for its gaps (SEP-3415 §Cursor Lifecycle)', async () => { + vi.useFakeTimers({ shouldAdvanceTime: true }); + const check = vi.fn(() => ({ events: [], cursor: null, truncated: true })); + const events = new EventsExtension({ heartbeatMs: 10_000 }); + events.registerEvent('tick', { payloadSchema: P, check }); + const stream = await open(serve(events), { name: 'tick', cursor: 'h1' }); + expect(await next(stream)).toEqual(notification(ACTIVE, stream.id, { cursor: null, truncated: false, heartbeatMs: 10_000 })); + const frame = next(stream); + await vi.advanceTimersByTimeAsync(10_000); + // The check at 5 s reported a gap and sent nothing, so the next frame is the heartbeat. + expect(await frame).toEqual(notification(HEARTBEAT, stream.id, { cursor: null })); + expect(check.mock.calls.length).toBeGreaterThanOrEqual(2); + }); + it('applies the maxAgeMs floor to the replay and flags truncated', async () => { const old = new Date(Date.now() - 600_000).toISOString(); const check = vi.fn(() => ({ diff --git a/packages/server/test/ext/events/webhookSubscriptions.test.ts b/packages/server/test/ext/events/webhookSubscriptions.test.ts index bf146ba2c1..7e70f83428 100644 --- a/packages/server/test/ext/events/webhookSubscriptions.test.ts +++ b/packages/server/test/ext/events/webhookSubscriptions.test.ts @@ -791,6 +791,18 @@ describe('check-kind webhook subscriptions', () => { expect(gapped).toMatchObject({ cursor: 'c5', truncated: true }); }); + it('answers truncated: false and sends no gap envelope for a cursor: null result (SEP-3415 §Cursor Lifecycle)', async () => { + const check = vi.fn(() => ({ events: [], cursor: null, truncated: true })); + const { events, post } = replica(); + events.registerEvent('t', { payloadSchema: P, check }); + const reply = subscribed(await client(events).subscribe({ name: 't', cursor: 'c0' })); + expect(reply).toMatchObject({ cursor: null, truncated: false }); + await vi.advanceTimersByTimeAsync(10_000); + await settle(); + expect(check).toHaveBeenCalledTimes(3); + expect(post.deliveries()).toEqual([]); + }); + it('advances the refresh cursor over quiet check batches, never past an unacknowledged event', async () => { let acknowledge!: (outcome: WebhookSendOutcome) => void; const respond: Respond = request => diff --git a/test/conformance/src/events.ts b/test/conformance/src/events.ts index 3ec1d426f3..a1af46a05e 100644 --- a/test/conformance/src/events.ts +++ b/test/conformance/src/events.ts @@ -135,7 +135,9 @@ const pulse = conformanceEvents.registerEvent(PULSE, { check: ctx => { const seen = beatSeen.get(ctx.subscriptionId); beatSeen.set(ctx.subscriptionId, beat); - return { events: seen === undefined || seen === beat ? [] : [{ data: { beat } }], cursor: null }; + const events = seen === undefined || seen === beat ? [] : [{ data: { beat } }]; + // A gap yield_gap asked for comes out as `truncated` with `cursor: null`, which the SDK must not pass on (SEP l.713). + return take(gapNext, ctx) ? { events, cursor: null, truncated: true } : { events, cursor: null }; }, onUnsubscribe: ctx => void beatSeen.delete(ctx.subscriptionId), delivery: { poll: false } @@ -358,13 +360,14 @@ export function registerEventsControls(mcp: McpServer): void { } ); - // The pulse has no position to skip past, so a gap on it changes nothing it reports. mcp.registerTool( 'events_conformance_yield_gap', - { description: "Makes the counter's next read report a gap (truncated, with a fresh cursor).", inputSchema: named }, + { + description: 'Makes the next read of the counter (fresh cursor) or the pulse (cursor null) report a gap as truncated.', + inputSchema: named + }, ({ name }) => { - if (name === PULSE) return text('ok'); - if (name !== COUNTER) return refuse(`only ${COUNTER} has history to lose`); + if (name !== COUNTER && name !== PULSE) return refuse(`only ${COUNTER} and ${PULSE} read an upstream`); gapNext.add(name); return text('ok'); } From 6f42772c1a513509dc278a8de7df2261340366a8 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 22:42:40 +0200 Subject: [PATCH 30/37] fix: export Events types that exported symbols reference (typedoc) --- packages/client/src/ext/events/subscription.ts | 2 +- packages/client/src/ext/events/webhook.ts | 2 +- packages/server/src/ext/events/extension.ts | 2 +- packages/server/src/ext/events/types.ts | 6 +++--- packages/server/src/server/paramHeaderSources.ts | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/client/src/ext/events/subscription.ts b/packages/client/src/ext/events/subscription.ts index e11167f1ac..76b2407985 100644 --- a/packages/client/src/ext/events/subscription.ts +++ b/packages/client/src/ext/events/subscription.ts @@ -99,7 +99,7 @@ export interface DriverContext { readonly connection: EventsConnection; } -type Item = EventOccurrence & { data: T }; +export type Item = EventOccurrence & { data: T }; // In delivery order: an event, or a cursor that becomes current once the loop has moved past the events before it. type Entry = { event: Item } | { cursor: string | null }; diff --git a/packages/client/src/ext/events/webhook.ts b/packages/client/src/ext/events/webhook.ts index 814e464ddc..1369731b74 100644 --- a/packages/client/src/ext/events/webhook.ts +++ b/packages/client/src/ext/events/webhook.ts @@ -17,7 +17,7 @@ import type { DeliveryQueue, Driver, DriverContext } from './subscription'; // The share of each grant after which the subscription is refreshed. const REFRESH_AT = 0.75; -interface WebhookOptions { +export interface WebhookOptions { url: string; secretProvider?: () => string; } diff --git a/packages/server/src/ext/events/extension.ts b/packages/server/src/ext/events/extension.ts index 7d9f68214d..c52d80d9b2 100644 --- a/packages/server/src/ext/events/extension.ts +++ b/packages/server/src/ext/events/extension.ts @@ -43,7 +43,7 @@ export interface SubscriptionSource { // Receives each emitted event once it is buffered (`cursor` the position after it, `previous` the one before); it queues delivery and returns, never waiting on a receiver. export type EmitFanOut = (name: string, buffered: BufferedEvent, positions: { cursor: string; previous: string }) => void | Promise; -type DefaultSchema = StandardSchemaWithJSON>; +export type DefaultSchema = StandardSchemaWithJSON>; // The `events/*` requests that name an event type in `params.name`. const NAMED_EVENT_METHODS = [EVENTS_POLL_METHOD, EVENTS_STREAM_METHOD, EVENTS_SUBSCRIBE_METHOD, EVENTS_UNSUBSCRIBE_METHOD]; diff --git a/packages/server/src/ext/events/types.ts b/packages/server/src/ext/events/types.ts index 628018959d..93b9b13c7e 100644 --- a/packages/server/src/ext/events/types.ts +++ b/packages/server/src/ext/events/types.ts @@ -2,8 +2,8 @@ import type { DeliveryMode } from '@modelcontextprotocol/core/ext/events'; import type { ServerContext, StandardSchemaWithJSON } from '@modelcontextprotocol/core-internal'; import type { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; -type InferInput = StandardSchemaWithJSON.InferInput; -type InferOutput = StandardSchemaWithJSON.InferOutput; +export type InferInput = StandardSchemaWithJSON.InferInput; +export type InferOutput = StandardSchemaWithJSON.InferOutput; /** * The `ctx` of every event callback: the subscription it runs for. There is no @@ -78,7 +78,7 @@ export interface EventResult

> { hasMore?: boolean; } -interface EventDefinitionBase { +export interface EventDefinitionBase { description?: string; /** Schema for the subscription `arguments`; absent means any object. */ inputSchema?: I; diff --git a/packages/server/src/server/paramHeaderSources.ts b/packages/server/src/server/paramHeaderSources.ts index 89281a748b..614543968b 100644 --- a/packages/server/src/server/paramHeaderSources.ts +++ b/packages/server/src/server/paramHeaderSources.ts @@ -1,6 +1,6 @@ import type { McpServer } from './mcp'; -type ParamHeaderSchemaLookup = (name: string) => Record | undefined; +export type ParamHeaderSchemaLookup = (name: string) => Record | undefined; // Per server, the methods besides `tools/call` whose `Mcp-Param-*` headers `createMcpHandler` validates, each with its schema lookup by `params.name`. const sources = new WeakMap>(); From 2cfacad0e2d4b2769b21bd4cd4e0d937712486fc Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 22:42:40 +0200 Subject: [PATCH 31/37] docs(events): example story, guides and changeset --- .changeset/events-extension.md | 19 ++ docs/.vitepress/nav.ts | 4 +- docs/clients/events.md | 122 ++++++++ docs/servers/events.md | 215 ++++++++++++++ docs/serving/http.md | 2 +- examples/README.md | 1 + examples/events/README.md | 22 ++ examples/events/client.ts | 88 ++++++ examples/events/package.json | 27 ++ examples/events/server.ts | 108 +++++++ examples/guides/clients/events.examples.ts | 186 ++++++++++++ examples/guides/servers/events.examples.ts | 313 +++++++++++++++++++++ pnpm-lock.yaml | 25 ++ 13 files changed, 1130 insertions(+), 2 deletions(-) create mode 100644 .changeset/events-extension.md create mode 100644 docs/clients/events.md create mode 100644 docs/servers/events.md create mode 100644 examples/events/README.md create mode 100644 examples/events/client.ts create mode 100644 examples/events/package.json create mode 100644 examples/events/server.ts create mode 100644 examples/guides/clients/events.examples.ts create mode 100644 examples/guides/servers/events.examples.ts diff --git a/.changeset/events-extension.md b/.changeset/events-extension.md new file mode 100644 index 0000000000..9410c43a4a --- /dev/null +++ b/.changeset/events-extension.md @@ -0,0 +1,19 @@ +--- +'@modelcontextprotocol/core': minor +'@modelcontextprotocol/core-internal': minor +'@modelcontextprotocol/client': minor +'@modelcontextprotocol/server': minor +--- + +author: @KKonstantinov + +Add the Events extension (SEP-3415), reachable through new `ext/events` subpaths; package root exports are unchanged. The whole Events API is experimental and may change in a minor release. + +- `@modelcontextprotocol/server/ext/events`: `EventsExtension`, whose `registerEvent(name, definition)` takes a `check` function or `emitOnly: true` and returns a handle with `update()`, `remove()` and `terminate()` (and `emit()` for emit-only types), and whose `attach(server)` serves `events/list`, `events/poll`, `events/stream`, `events/subscribe` and `events/unsubscribe`; `InMemoryWebhookSubscriptionStore`; `EventsError`; the types `EventContext`, `CheckContext`, `EventInput`, `EventResult`, `EventDefinition`, `CheckEventDefinition`, `EmitOnlyEventDefinition`, `EventHandle`, `EmitOnlyEventHandle`, `EventsOptions`, `EventsErrorKind`, `WebhookSender`, `WebhookSendRequest`, `WebhookSendOutcome`, `WebhookSubscriptionStore` and `WebhookSubscriptionRecord`; and the wire types and constants. Push streams under every `createMcpHandler` `responseMode`, `'json'` included. Webhook delivery is on when `webhookTtlMs`, `webhookSender` and `getPrincipal` are all set; `trustedOrigins` exempts exact origins from the `https` and private-address rules, for development. +- `@modelcontextprotocol/server/ext/events/node`: `nodeWebhookSender()`, a `WebhookSender` for Node.js that requires `https`, resolves the host at every send, refuses IANA special-purpose addresses, follows no redirects and gives up after 5 seconds. +- `@modelcontextprotocol/client/ext/events`: `EventsClientExtension` with `list()`, `subscribe({ name, arguments, delivery?, cursor?, maxAgeMs?, onGap? })` and `createWebhookHandler()`; `NoCompatibleDeliveryModeError`; `EventsError`; the types `EventsClientOptions`, `SubscribeOptions`, `EventSubscription` (an async iterable with `cursor`, `deliveryMode`, `deliveryStatus` and `cancel()`) and `EventsErrorKind`; and the wire types and constants. A subscription prefers webhook (when configured), then push, then poll. +- `@modelcontextprotocol/core/ext/events`: the wire constants, a Zod schema and inferred type for every Events wire shape, and `EventsCapabilitySchema`, `EventsCapability` and `eventsCapabilityOf`. + +Clients now send `Mcp-Name` on `events/poll`, `events/stream`, `events/subscribe` and `events/unsubscribe`, and `createMcpHandler` requires it on 2026-07-28 (`400` / `-32020` when it is missing or does not match `params.name`), whether or not the server attaches Events. + +Events is served and used on protocol 2026-07-28 only. Not included: `notifications/events/list_changed`, and webhook grants without expiry (`refreshBefore: null`). With several replicas sharing a `WebhookSubscriptionStore`, `emit()` reaches push streams and the poll buffer only on the emitting process, and the `check` loop of a webhook subscription may run on more than one replica. diff --git a/docs/.vitepress/nav.ts b/docs/.vitepress/nav.ts index af7798e9a8..d3f1955aef 100644 --- a/docs/.vitepress/nav.ts +++ b/docs/.vitepress/nav.ts @@ -22,6 +22,7 @@ export const guideSidebar: DefaultTheme.SidebarItem[] = [ { text: 'Tools', link: '/servers/tools' }, { text: 'Resources', link: '/servers/resources' }, { text: 'Skills', link: '/servers/skills' }, + { text: 'Events', link: '/servers/events' }, { text: 'Prompts', link: '/servers/prompts' }, { text: 'Completion', link: '/servers/completion' }, { text: 'Logging, progress, cancellation', link: '/servers/logging-progress-cancellation' }, @@ -58,7 +59,8 @@ export const guideSidebar: DefaultTheme.SidebarItem[] = [ { text: 'Machine auth', link: '/clients/machine-auth' }, { text: 'Middleware', link: '/clients/middleware' }, { text: 'Caching', link: '/clients/caching' }, - { text: 'Skills', link: '/clients/skills' } + { text: 'Skills', link: '/clients/skills' }, + { text: 'Events', link: '/clients/events' } ] }, { text: 'Protocol versions', link: '/protocol-versions' }, diff --git a/docs/clients/events.md b/docs/clients/events.md new file mode 100644 index 0000000000..0252a589e4 --- /dev/null +++ b/docs/clients/events.md @@ -0,0 +1,122 @@ +--- +status: experimental +shape: how-to +--- + +# Events + +::: warning Experimental +Events (SEP-3415) is an accepted MCP extension. Its SDK API is new and may change in a minor release. +::: + +`EventsClientExtension` subscribes to a server's event types, and you read each **subscription** with `for await`. + +```ts source="../../examples/guides/clients/events.examples.ts#subscribe_basic" +import { Client } from '@modelcontextprotocol/client'; +import { EventsClientExtension } from '@modelcontextprotocol/client/ext/events'; + +const client = new Client({ name: 'ops-console', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } }); +const events = new EventsClientExtension(); +events.attach(client); +await client.connect(transport); + +const subscription = await events.subscribe({ name: 'ticket.updated', arguments: { queue: 'billing' } }); +for await (const event of subscription) { + console.log(event.name, event.data); + break; +} +``` + +When a ticket in the billing queue opens, it prints: + +```text +ticket.updated { ticketId: 'T-7', status: 'open' } +``` + +Attach the extension before `connect()`. `subscribe()` resolves once its first exchange with the server succeeds, and the subscription starts from now unless you pass a `cursor`. `list()` returns the server's event types with their schemas and delivery modes. + +Each subscription takes the first delivery mode the event type offers out of webhook (when you configure it), push and poll; `delivery` forces one, and `subscription.deliveryMode` says which it got. The loop is the same in every mode, drops a repeated `eventId`, and leaving it cancels the subscription. + +::: info +Events is used on protocol 2026-07-28 only, so create the client with `versionNegotiation: { mode: 'auto' }` or a pin — see [Protocol versions](../protocol-versions.md). +::: + +## Resume from a saved cursor + +`subscription.cursor` is the newest cursor that is safe to save; pass it back as `cursor` to pick up where the loop stopped. + +```ts source="../../examples/guides/clients/events.examples.ts#subscribe_cursor" +// Save the cursor; it covers every event the loop finished with. +const saved = subscription.cursor; + +// Later, maybe in a new process: resume from the saved cursor. +const resumed = await events.subscribe({ name: 'ticket.updated', arguments: { queue: 'billing' }, cursor: saved }); +for await (const event of resumed) { + console.log(event.name, event.data); + if (event.data.status === 'closed') break; +} +``` + +Meanwhile the ticket was closed. The resumed subscription delivers the event the first loop broke on again, then the change it missed: + +```text +ticket.updated { ticketId: 'T-7', status: 'open' } +ticket.updated { ticketId: 'T-7', status: 'closed' } +``` + +The cursor covers the events the loop finished with, and the loop finishes with an event when it asks for the next one, so a resumed subscription can repeat the last event: handle events idempotently, or skip an `eventId` you have handled. An event type that cannot resume has a `null` cursor, and there is nothing to save. + +`onGap` receives the fresh cursor when events may have been skipped: the server reported `truncated`, or delivery started again from now after a schema change made the server refuse your cursor. Closing the client, or connecting it again, ends every subscription, and the loop rejects with an `SdkError` (`ConnectionClosed`). After reconnecting, subscribe again and pass the cursor you saved. + +## Receive events by webhook + +Give the extension a webhook URL and serve its receiver there. + +```ts source="../../examples/guides/clients/events.examples.ts#webhook_receiver" +import { Hono } from 'hono'; + +const hooked = new EventsClientExtension({ webhook: { url: 'https://hooks.example.com/mcp/events' } }); +const handleWebhook = hooked.createWebhookHandler(); + +// Serve the receiver at the webhook URL from any fetch-style server; here, Hono. +const app = new Hono(); +app.post('/mcp/events', c => handleWebhook(c.req.raw)); +``` + +With `webhook` set, a subscription prefers webhook wherever the event type offers it: the server POSTs each event to the URL, and the receiver checks the signature and routes the event into its subscription's loop. The client makes a `whsec_` secret for each server subscription (or takes one from `secretProvider`), answers the server's verification challenge, and refreshes the subscription before it expires. `subscription.deliveryStatus` holds the delivery health the server last reported. + +Webhook subscriptions with the same name and arguments share one server subscription, and cancelling the last of them sends `events/unsubscribe`. The SDK's server accepts a webhook subscription only from an authenticated principal and answers `forbidden` otherwise. The receiver answers `503` to a subscription it does not know yet, and the server retries. + +## Handle errors + +Catch `EventsError` around `subscribe()` and the loop; `kind` says what went wrong. + +```ts source="../../examples/guides/clients/events.examples.ts#errors" +import { EventsError } from '@modelcontextprotocol/client/ext/events'; + +try { + const refused = await events.subscribe({ name: 'ticket.updated', arguments: { queue: 42 } }); + for await (const event of refused) console.log(event.data); +} catch (error) { + if (!(error instanceof EventsError)) throw error; + console.log(error.kind); +} +``` + +The server rejects `queue: 42` against the event type's `inputSchema`, so it prints: + +```text +invalidParams +``` + +`subscribe()` rejects with an `EventsError` when the server does not list the event type or refuses the subscription (`notFound`, `invalidParams`, `forbidden`, `unsupported`, `resourceExhausted` or `callbackEndpointError`), and with an `SdkError` when the exchange fails in the SDK, such as a closed connection; other failures of the first exchange are retried in the background. Once subscribed, the loop ends with an `EventsError` when the server ends the subscription, such as `forbidden` when access is revoked. A `notFound`, or an `unsupported` for a schema change, makes the client list the event types again and carry on while the type is still offered in that mode. + +`NoCompatibleDeliveryModeError` means no delivery mode the event type offers is usable here: webhook needs the `webhook` option, and `delivery` narrows the choice to one mode. Against a server without Events, or on a connection older than 2026-07-28, `events.supported` is `false`, and `list()` and `subscribe()` throw `SdkError` (`CapabilityNotSupported`). An error thrown from `onGap` goes to the client's `onerror`. + +## Recap + +- `new EventsClientExtension()`, `attach(client)` before `connect()`, then `subscribe({ name, arguments })` and `for await`. +- The loop is the same in every mode, and leaving it cancels the subscription. +- `subscription.cursor` is safe to save; pass it back as `cursor` to resume, and expect the last event again. +- `webhook: { url }`, with `createWebhookHandler()` served at that URL, turns on webhook delivery. +- `subscribe()` and the loop fail with an `EventsError` whose `kind` says why. diff --git a/docs/servers/events.md b/docs/servers/events.md new file mode 100644 index 0000000000..0f5bad3e37 --- /dev/null +++ b/docs/servers/events.md @@ -0,0 +1,215 @@ +--- +status: experimental +shape: how-to +--- + +# Events + +::: warning Experimental +Events (SEP-3415) is an accepted MCP extension. Its SDK API is new and may change in a minor release. +::: + +`registerEvent` with a `check` function publishes an **event type**: the SDK reads new events from your upstream for every client that subscribes. + +```ts source="../../examples/guides/servers/events.examples.ts#registerEvent_check" +import { EventsExtension } from '@modelcontextprotocol/server/ext/events'; +import * as z from 'zod/v4'; + +// Your upstream: here, a log of ticket changes, where a cursor is a position in the log. +const changes: Array<{ changeId: string; queue: string; ticketId: string; status: string }> = []; + +const events = new EventsExtension(); + +events.registerEvent('ticket.updated', { + description: 'A ticket in a queue changed status', + inputSchema: z.object({ queue: z.string() }), + payloadSchema: z.object({ ticketId: z.string(), status: z.string() }), + check: (ctx, { queue }, cursor) => { + if (cursor === null) return { events: [], cursor: String(changes.length) }; + const from = Number(cursor); + const to = Math.min(changes.length, from + (ctx.maxEvents ?? changes.length)); + const page = changes.slice(from, to).filter(change => change.queue === queue); + return { + events: page.map(({ changeId, ticketId, status }) => ({ eventId: changeId, data: { ticketId, status } })), + cursor: String(to), + hasMore: to < changes.length + }; + } +}); +``` + +Clients subscribe by poll (`events/poll`) or push (`events/stream`), or by webhook (`events/subscribe`) once you turn it on, and the SDK runs each mode from this one definition. `check` returns the events since `cursor` and the cursor to resume from; for a subscription that starts now the SDK passes `cursor: null` and sends only the cursor you return. Return at most `ctx.maxEvents` events, set `hasMore` when more are waiting, and set `truncated: true` when the upstream no longer has the history since `cursor`. + +Clients resume from their cursor after a disconnect or a restart, for as long as your upstream accepts it. A `check` that returns `cursor: null` marks a type that cannot resume, and the SDK never reports `truncated` for it. + +::: info +Events is served on protocol 2026-07-28 only; a 2025-11-25 connection sees no Events capability and gets `-32601` for `events/*` — see [Protocol versions](../protocol-versions.md). +::: + +## Emit events as they happen + +Pass `emitOnly: true` when your upstream pushes to you, and call `emit()` on the handle `registerEvent` returns. + +```ts source="../../examples/guides/servers/events.examples.ts#registerEvent_emitOnly" +// The open subscriptions, by the id the SDK gives each one. +const open = new Set(); + +const incidents = events.registerEvent('incident.created', { + emitOnly: true, + description: 'A new incident was opened', + inputSchema: z.object({ severity: z.enum(['P1', 'P2', 'P3']).optional() }), + payloadSchema: z.object({ incidentId: z.string(), title: z.string(), severity: z.enum(['P1', 'P2', 'P3']) }), + match: (ctx, event, { severity }) => severity === undefined || event.data.severity === severity, + onSubscribe: ctx => { + open.add(ctx.subscriptionId); + }, + onUnsubscribe: ctx => { + open.delete(ctx.subscriptionId); + } +}); + +// Wherever your upstream reports an incident, for example in its webhook handler: +await incidents.emit({ eventId: 'INC-7', data: { incidentId: 'INC-7', title: 'Checkout is down', severity: 'P1' } }); +``` + +`emit()` sends the event to every subscription that `match` accepts, or to one with `emit(event, { subscriptionId })`; `transform` reshapes it per subscription. The SDK drops an event whose `data` fails `payloadSchema` and reports it to `onerror`, for both kinds. + +Poll clients read emit-only events from an in-memory buffer (`emitBuffer`, by default the last 10 minutes and at most 10 000 events), so events emitted before a restart are lost. `onSubscribe` and `onUnsubscribe` run as a subscription starts and ends, in every mode, and `ctx.subscriptionId` names it. + +## Serve the event types from every server + +`attach` serves the event types on a server; one `EventsExtension` serves every server you attach it to. + +```ts source="../../examples/guides/servers/events.examples.ts#attach" +import { createMcpHandler, McpServer } from '@modelcontextprotocol/server'; + +const handler = createMcpHandler(() => { + const mcp = new McpServer({ name: 'helpdesk', version: '1.0.0' }); + events.attach(mcp); + return mcp; +}); +``` + +Attach before connecting the server. Push streams under every `responseMode`, `'json'` included, as `subscriptions/listen` does. + +A push stream carries no SSE comment keepalive. The server sends `notifications/events/heartbeat` whenever the stream has been quiet for the granted interval, `heartbeatMs` (30 seconds by default) or a shorter one the client asks for, and the SDK's client reconnects after three intervals of silence. Keep `heartbeatMs` below your load balancer's idle timeout. + +## Deliver events to webhooks + +Set `webhookTtlMs`, `webhookSender` and `getPrincipal` together to offer webhook delivery. + +```ts source="../../examples/guides/servers/events.examples.ts#webhook_setup" +import type { ServerContext } from '@modelcontextprotocol/server'; +import { nodeWebhookSender } from '@modelcontextprotocol/server/ext/events/node'; + +// The user your token verifier authenticated; this one puts the subject in AuthInfo.extra. +function principalOf(ctx: ServerContext): string | null { + const sub = ctx.http?.authInfo?.extra?.sub; + return typeof sub === 'string' ? sub : null; +} + +const webhookEvents = new EventsExtension({ + webhookTtlMs: 30 * 60_000, + webhookSender: nodeWebhookSender(), + getPrincipal: principalOf +}); +``` + +Setting `webhookTtlMs` or `webhookSender` without the other two throws `TypeError`. `getPrincipal` has no default, since `AuthInfo` has no subject field: return the user from wherever your token verifier puts it. A webhook subscription for which `getPrincipal` returns `null` is refused with `forbidden`, on stdio too; poll and push use the principal when there is one. + +`webhookTtlMs` is the longest a webhook subscription lives without a refresh, and clients refresh before it lapses. The SDK verifies each endpoint with a challenge before the first delivery, signs every POST (Standard Webhooks), and retries a failed delivery up to five attempts in all. `nodeWebhookSender()` requires `https`, resolves the host at every send, refuses IANA special-purpose addresses (loopback, private, link-local and the like) and connects to the address it checked; it follows no redirects and gives up after 5 seconds. + +::: warning +`trustedOrigins` is for development only. Its exact origins, such as `http://127.0.0.1:9000`, are exempt from the `https` rule and the private-address check, so a receiver on your machine can take deliveries; endpoint verification, signing and the no-redirect rule still apply. +::: + +## Share webhook subscriptions across replicas + +Webhook subscriptions live in a `WebhookSubscriptionStore`, in process memory by default; give every replica one shared store. + +```ts source="../../examples/guides/servers/events.examples.ts#webhook_store" +import type { WebhookSubscriptionRecord, WebhookSubscriptionStore } from '@modelcontextprotocol/server/ext/events'; + +// What the store needs from a database every replica shares, such as Redis. +interface SharedKeyValue { + get(key: string): Promise; + // The database deletes the key at expiresAt (with Redis: SET ... PXAT expiresAt). + set(key: string, value: string, expiresAt: number): Promise; + delete(key: string): Promise; + keys(prefix: string): AsyncIterable; +} + +function sharedWebhookStore(kv: SharedKeyValue): WebhookSubscriptionStore { + const read = async (id: string) => { + const json = await kv.get(`events:sub:${id}`); + return json === undefined ? undefined : (JSON.parse(json) as WebhookSubscriptionRecord); + }; + return { + get: read, + async put(record) { + await kv.set(`events:sub:${record.id}`, JSON.stringify(record), record.expiresAt); + await kv.set(`events:name:${record.name}:${record.id}`, '', record.expiresAt); + }, + async delete(id) { + const record = await read(id); + if (record !== undefined) await kv.delete(`events:name:${record.name}:${id}`); + return kv.delete(`events:sub:${id}`); + }, + async *listByName(name) { + const prefix = `events:name:${name}:`; + for await (const key of kv.keys(prefix)) { + const record = await read(key.slice(prefix.length)); + if (record !== undefined) yield record; + } + } + }; +} + +const replicated = new EventsExtension({ + webhookTtlMs: 30 * 60_000, + webhookSender: nodeWebhookSender(), + webhookStore: sharedWebhookStore(kv), + getPrincipal: principalOf +}); +``` + +Records hold each subscription's webhook secret, so protect the store as you protect credentials. The SDK deletes an expired record when it next reads it, or when the expiry timer of the replica that last granted it fires. A record that a stopped replica left behind stays until something reads it, so let the store expire records too, as the `expiresAt` passed to `set()` above does (with Redis, a key TTL). + +A replica runs `onUnsubscribe` after its `delete()` resolved `true`. Replicas racing on a store whose `delete()` is not atomic may each run it for one subscription, so keep `onUnsubscribe` idempotent. + +With a shared store, webhook subscribe, refresh, secret rotation and unsubscribe work on any replica, and `emit()` on any replica reaches every matching webhook subscription. Some state stays on one process: + +- `emit()` reaches push streams and the poll buffer on the emitting process only. A poll that lands on another replica gets `truncated: true` and a fresh cursor. +- A webhook subscription to a `check` type runs its `check` loop on every replica that handled its subscribe or a refresh, so its receiver may get an event more than once (same `eventId`, different `webhook-id`); the SDK's client drops the repeats by `eventId`. Prefer emit-only types for webhook subscribers, or run one replica. +- `remove()` on one replica may skip `onUnsubscribe` for subscriptions another replica handled. +- Retries, the delivery watermark and `deliveryStatus` stay with the replica that delivers. + +## End a subscription + +`terminate` ends subscriptions with an `EventsError`, for example when the subscriber lost access. + +```ts source="../../examples/guides/servers/events.examples.ts#terminate" +import { EventsError } from '@modelcontextprotocol/server/ext/events'; + +// Ends one subscription, by the id its hooks received as ctx.subscriptionId. +function revoke(subscriptionId: string): Promise { + return incidents.terminate(new EventsError('forbidden', 'Access revoked'), { subscriptionId }); +} +``` + +Without `subscriptionId`, `terminate` ends every subscription of the type. The client gets the error in its mode's form (a poll error response, a push `terminated` notification, a webhook `terminated` POST), and the SDK's client ends its loop with it, unless it is `notFound` and the type is still offered in that mode. `terminate` reaches webhook subscriptions on every replica through the store, and push and poll subscriptions on this process only. + +Throw an `EventsError` from `onSubscribe` to refuse a subscription, or `EventsError('forbidden', …)` from `check` to end one. Change an event type with the handle's `update()` for additive changes only; registering the name again with a different schema ends its subscriptions with `unsupported` (`reason: 'schema_changed'`), and `remove()` ends them with `notFound`. + +::: warning +An `EventsError` thrown from `onUnsubscribe`, `match` or `transform` only reaches `onerror`, since nothing waits for an answer there; a throwing `match` or `transform` also skips the event for that subscription. By default `onerror` writes to stderr with `console.warn`. +::: + +## Recap + +- `registerEvent(name, { check })` reads events from an upstream that can answer what happened since a cursor, and clients resume from their cursor. +- `emitOnly: true` and the handle's `emit()` publish events as they happen; poll reads them from a bounded in-memory buffer. +- One `EventsExtension` serves every server it is attached to by poll and push, and by webhook once configured, on 2026-07-28 only; push streams under every `responseMode`. +- Webhook delivery needs `webhookTtlMs`, `webhookSender` and `getPrincipal`; `trustedOrigins` is for development only. +- A shared `WebhookSubscriptionStore` holds webhook secrets and lets replicas share webhook subscriptions, while push streams and the poll buffer stay on one process. +- `terminate` ends subscriptions with an `EventsError`, such as `forbidden` when access is revoked. diff --git a/docs/serving/http.md b/docs/serving/http.md index e95552656a..13b4d8d5bb 100644 --- a/docs/serving/http.md +++ b/docs/serving/http.md @@ -106,7 +106,7 @@ The handler answers a request with a single JSON body and upgrades to an SSE str const jsonOnly = createMcpHandler(factory, { responseMode: 'json' }); ``` -`'json'` never streams: the SDK drops mid-call notifications and delivers only the terminal result. `'sse'` always streams. `subscriptions/listen` streams stay on SSE whichever you pick. +`'json'` never streams: the SDK drops mid-call notifications and delivers only the terminal result. `'sse'` always streams. `subscriptions/listen` streams and the Events extension's `events/stream` streams stay on SSE whichever you pick. ::: info The handler serves 2025-era clients statelessly from the same factory by default. The `legacy` option — and where the SSE transport went — is on [Support legacy clients](./legacy-clients.md). diff --git a/examples/README.md b/examples/README.md index 6563c03f01..531fc42dac 100644 --- a/examples/README.md +++ b/examples/README.md @@ -47,6 +47,7 @@ The one exception to the generic commands is the reference pair: [`cli-client/`] | [`custom-methods/`](./custom-methods/README.md) | Vendor-prefixed methods + custom notifications | stdio + http | dual | | [`extension-capabilities/`](./extension-capabilities/README.md) | Declaring `capabilities.extensions` and reading the negotiated map | stdio + http | dual | | [`skills/`](./skills/README.md) | Skills over MCP (SEP-2640): `loadSkills` a folder, `SkillsClient` lists, loads and verifies | stdio + http | dual | +| [`events/`](./events/README.md) | Events (SEP-3415): a `check` type and an emit-only type, `EventsClientExtension` subscribes by poll, push and (HTTP) webhook | stdio + http | modern | | [`schema-validators/`](./schema-validators/README.md) | ArkType, Valibot, Zod, and `outputSchema` | stdio + http | dual | | [`custom-version/`](./custom-version/README.md) | `supportedProtocolVersions` / version negotiation | stdio + http | legacy | | [`parallel-calls/`](./parallel-calls/README.md) | Multiple clients / parallel tool calls, per-client notifications | stdio + http | dual | diff --git a/examples/events/README.md b/examples/events/README.md new file mode 100644 index 0000000000..c51785c2bd --- /dev/null +++ b/examples/events/README.md @@ -0,0 +1,22 @@ +# events + +The server serves two event types with the Events extension (SEP-3415): +`counter.changed`, which the SDK reads through `check` from a counter the +`increment` tool bumps, and `timer.tick`, which a timer feeds through +`emit()`. The client subscribes to both in every delivery mode the leg offers +(poll and push over stdio; over HTTP also webhook, with its receiver on +`127.0.0.1:8599`, an origin the server trusts for development), bumps the +counter once and checks what each subscription receives. Events is served on +2026-07-28 only, so the story has no legacy leg. + +```bash +pnpm --filter @mcp-examples/events client # stdio leg +pnpm --filter @mcp-examples/events run server -- --http --port 3000 +pnpm --filter @mcp-examples/events client -- --http http://127.0.0.1:3000/mcp +``` + +The HTTP leg authenticates with the demo bearer token `demo-token`, whose +subject is the webhook principal. Set `EVENTS_RECEIVER_PORT` on both sides to +move the receiver off port 8599. + +See [Serve events](../../docs/servers/events.md) and [Subscribe to events](../../docs/clients/events.md). diff --git a/examples/events/client.ts b/examples/events/client.ts new file mode 100644 index 0000000000..b79e1e5fe6 --- /dev/null +++ b/examples/events/client.ts @@ -0,0 +1,88 @@ +/** + * Connects to `./server.ts` and subscribes to both of its event types in every + * delivery mode the leg offers: poll and push over stdio, and over HTTP also + * webhook, with the receiver served on 127.0.0.1. It bumps the counter once + * and checks what each subscription receives. + * + * Spawns the sibling `server.ts` over stdio by default, or connects to a + * running endpoint under `--http `. See `examples/CONTRIBUTING.md` for + * the canonical shape. + */ +import type { ServerType } from '@hono/node-server'; +import { serve } from '@hono/node-server'; +import { check, parseExampleArgs, siblingPath } from '@mcp-examples/shared'; +import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'; +import type { DeliveryMode, EventSubscription } from '@modelcontextprotocol/client/ext/events'; +import { EventsClientExtension } from '@modelcontextprotocol/client/ext/events'; +import { StdioClientTransport } from '@modelcontextprotocol/client/stdio'; + +// Where the webhook receiver listens; server.ts trusts this origin. +const RECEIVER_PORT = Number(process.env.EVENTS_RECEIVER_PORT ?? '8599'); + +const { transport, url } = parseExampleArgs(); +const http = transport === 'http'; + +// Events is a 2026-07-28 extension: negotiate the modern revision. +const client = new Client({ name: 'events-example-client', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } }); +// Webhook delivery needs a URL the server can POST to: this process, on the HTTP leg. +const events = new EventsClientExtension(http ? { webhook: { url: `http://127.0.0.1:${RECEIVER_PORT}/events` } } : {}); +events.attach(client); + +// The receiver is up before any subscribe, since the server verifies the endpoint first. +let receiver: ServerType | undefined; +if (http) { + receiver = await new Promise(resolve => { + const server = serve({ fetch: events.createWebhookHandler(), port: RECEIVER_PORT, hostname: '127.0.0.1' }, () => resolve(server)); + }); +} + +await client.connect( + http + ? new StreamableHTTPClientTransport(new URL(url), { authProvider: { token: async () => 'demo-token' } }) + : new StdioClientTransport({ command: 'npx', args: ['-y', 'tsx', siblingPath(import.meta.url, 'server.ts')] }) +); + +// 1. List: both event types, in every mode the server offers on this leg. +const modes: DeliveryMode[] = http ? ['poll', 'push', 'webhook'] : ['poll', 'push']; +const { events: types } = await events.list(); +check.deepEqual( + types.map(type => [type.name, type.delivery]), + [ + ['counter.changed', modes], + ['timer.tick', modes] + ] +); + +// 2. Subscribe to each type in each mode; every subscription starts from now. +const subscriptions: Array<[DeliveryMode, EventSubscription<{ value: number }>, EventSubscription<{ tick: number }>]> = []; +for (const delivery of modes) { + const counter = await events.subscribe<{ value: number }>({ name: 'counter.changed', delivery }); + const timer = await events.subscribe<{ tick: number }>({ name: 'timer.tick', delivery }); + subscriptions.push([delivery, counter, timer]); +} + +// 3. Bump the counter once, then read one event from each subscription. +await client.callTool({ name: 'increment', arguments: {} }); + +// Leaving a `for await` loop cancels the subscription (for webhook, `events/unsubscribe`). +async function firstEvent(subscription: EventSubscription) { + for await (const event of subscription) return event; + throw new Error('the subscription ended before its first event'); +} + +for (const [delivery, counter, timer] of subscriptions) { + check.equal(counter.deliveryMode, delivery); + check.equal(timer.deliveryMode, delivery); + // The check type reads the counter's history: value 1 reaches every mode. + const changed = await firstEvent(counter); + check.equal(changed.name, 'counter.changed'); + check.deepEqual(changed.data, { value: 1 }); + // The emit-only type delivers ticks emitted after the subscription started. + const ticked = await firstEvent(timer); + check.equal(ticked.name, 'timer.tick'); + check.ok(Number.isInteger(ticked.data.tick) && ticked.data.tick > 0); +} + +console.log(`[client] ${transport} leg: counter and timer events by ${modes.join(', ')}`); +await client.close(); +await new Promise(resolve => (receiver === undefined ? resolve(undefined) : receiver.close(resolve))); diff --git a/examples/events/package.json b/examples/events/package.json new file mode 100644 index 0000000000..619f3fdd50 --- /dev/null +++ b/examples/events/package.json @@ -0,0 +1,27 @@ +{ + "name": "@mcp-examples/events", + "private": true, + "type": "module", + "scripts": { + "server": "tsx server.ts", + "client": "tsx client.ts" + }, + "dependencies": { + "@hono/node-server": "catalog:runtimeServerOnly", + "@mcp-examples/shared": "workspace:*", + "@modelcontextprotocol/client": "workspace:*", + "@modelcontextprotocol/hono": "workspace:*", + "@modelcontextprotocol/server": "workspace:*", + "zod": "catalog:runtimeShared" + }, + "devDependencies": { + "tsx": "catalog:devTools" + }, + "example": { + "era": "modern", + "env": { + "EVENTS_RECEIVER_PORT": "8599" + }, + "//": "Poll and push on both legs; webhook on the HTTP leg with an authenticated principal." + } +} diff --git a/examples/events/server.ts b/examples/events/server.ts new file mode 100644 index 0000000000..041aae0997 --- /dev/null +++ b/examples/events/server.ts @@ -0,0 +1,108 @@ +/** + * Serves two event types with the Events extension (SEP-3415): + * `counter.changed`, which the SDK reads through `check` from a counter the + * `increment` tool bumps, and `timer.tick`, which a timer feeds through + * `emit()`. Clients take them by poll or push on either transport; on the HTTP + * leg, where a demo bearer token names the caller, also by webhook. + * + * One binary, either transport — selected by `--http --port ` (defaults to + * stdio). See `examples/CONTRIBUTING.md` for the canonical shape. + */ +import { serve } from '@hono/node-server'; +import { parseExampleArgs } from '@mcp-examples/shared'; +import { createMcpHonoApp } from '@modelcontextprotocol/hono'; +import type { AuthInfo, OAuthTokenVerifier } from '@modelcontextprotocol/server'; +import { createMcpHandler, McpServer, OAuthError, OAuthErrorCode, requireBearerAuth } from '@modelcontextprotocol/server'; +import { EventsExtension } from '@modelcontextprotocol/server/ext/events'; +import { nodeWebhookSender } from '@modelcontextprotocol/server/ext/events/node'; +import { serveStdio } from '@modelcontextprotocol/server/stdio'; +import * as z from 'zod/v4'; + +// Where the client's webhook receiver listens (see client.ts). +const RECEIVER_PORT = process.env.EVENTS_RECEIVER_PORT ?? '8599'; + +const { transport, port } = parseExampleArgs(); + +// One extension serves every server instance below. +const events = new EventsExtension({ + // The caller the bearer token names; stdio has none. + getPrincipal: ctx => { + const sub = ctx.http?.authInfo?.extra?.sub; + return typeof sub === 'string' ? sub : null; + }, + // Webhook delivery needs a principal, so only the HTTP leg offers it; the receiver's plain-http loopback origin is trusted for development only. + ...(transport === 'http' && { + webhookTtlMs: 60_000, + webhookSender: nodeWebhookSender(), + trustedOrigins: [`http://127.0.0.1:${RECEIVER_PORT}`] + }), + // Short intervals keep the story fast: push and webhook check every 250 ms, poll clients come back after 1 s. + checkIntervalMs: 250, + defaultNextPollMs: 1000 +}); + +// The upstream of the check type: a cursor is a count, and each step up from it is one event. +let count = 0; + +events.registerEvent('counter.changed', { + description: 'The counter went up', + payloadSchema: z.object({ value: z.number().int() }), + check: (ctx, _args, cursor) => { + if (cursor === null) return { events: [], cursor: String(count) }; + const from = Number(cursor); + // A cursor this counter never issued (it starts at 0 after a restart): start again from now and report the gap. + if (!Number.isInteger(from) || from < 0 || from > count) return { events: [], cursor: String(count), truncated: true }; + const to = Math.min(count, from + (ctx.maxEvents ?? count)); + const values = Array.from({ length: to - from }, (_, index) => from + index + 1); + return { events: values.map(value => ({ eventId: `value-${value}`, data: { value } })), cursor: String(to), hasMore: to < count }; + } +}); + +// The upstream of the emit-only type: a timer that emits a tick to every subscription. +const tick = events.registerEvent('timer.tick', { + emitOnly: true, + description: 'The server timer ticked', + payloadSchema: z.object({ tick: z.number().int() }) +}); +let ticks = 0; +setInterval(() => void tick.emit({ data: { tick: ++ticks } }), 200).unref(); + +function buildServer(): McpServer { + const mcp = new McpServer({ name: 'events-example', version: '1.0.0' }); + mcp.registerTool('increment', { description: 'Add one to the counter', inputSchema: z.object({}) }, () => { + count += 1; + return { content: [{ type: 'text', text: String(count) }] }; + }); + events.attach(mcp); + return mcp; +} + +if (transport === 'stdio') { + void serveStdio(buildServer); + console.error('[server] serving over stdio'); +} else { + // DEMO ONLY: one static token, whose subject becomes the principal; verify real tokens here. + const verifier: OAuthTokenVerifier = { + async verifyAccessToken(token): Promise { + if (token !== 'demo-token') throw new OAuthError(OAuthErrorCode.InvalidToken, 'unknown token'); + return { + token, + clientId: 'events-example-client', + scopes: [], + expiresAt: Math.floor(Date.now() / 1000) + 3600, + extra: { sub: 'demo-user' } + }; + } + }; + const gate = requireBearerAuth({ verifier }); + const handler = createMcpHandler(buildServer); + // `createMcpHonoApp()` arms localhost host/origin validation by default; bind loopback explicitly to match. + const app = createMcpHonoApp(); + app.all('/mcp', async c => { + const authInfo = await gate(c.req.raw); + return authInfo instanceof Response ? authInfo : handler.fetch(c.req.raw, { authInfo }); + }); + serve({ fetch: app.fetch, port, hostname: '127.0.0.1' }, () => { + console.error(`[server] listening on http://127.0.0.1:${port}/mcp`); + }); +} diff --git a/examples/guides/clients/events.examples.ts b/examples/guides/clients/events.examples.ts new file mode 100644 index 0000000000..16d8b5fe39 --- /dev/null +++ b/examples/guides/clients/events.examples.ts @@ -0,0 +1,186 @@ +/** + * Companion example for `docs/clients/events.md`. + * + * Every `ts` fence on that page is synced from a `//#region` in this file + * (`pnpm sync:snippets --check`). The file also runs (`pnpm docs:examples`) + * against a helpdesk server served in process (`handler.fetch`, no port) on + * 2026-07-28, and prints the output the page quotes. + * + * npx tsx guides/clients/events.examples.ts # from examples/ + * + * @module + */ +/* eslint-disable no-console */ +import { SdkError, SdkErrorCode, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'; +import { createMcpHandler, McpServer } from '@modelcontextprotocol/server'; +import { EventsError as ServerEventsError, EventsExtension } from '@modelcontextprotocol/server/ext/events'; +import * as z from 'zod/v4'; + +// --------------------------------------------------------------------------- +// Harness server (not shown on the page): ticket changes behind a check +// function, and webhook POSTs handed to the page's receiver in process. +// --------------------------------------------------------------------------- +const changes: Array<{ changeId: string; queue: string; ticketId: string; status: string }> = []; +let receive: (request: Request) => Promise = async () => new Response(null, { status: 503 }); +const helpdesk = new EventsExtension({ + checkIntervalMs: 50, + webhookTtlMs: 60_000, + webhookSender: async ({ url, headers, body }) => { + const response = await receive(new Request(url, { method: 'POST', headers, body })); + return { status: response.status, body: await response.text() }; + }, + getPrincipal: () => 'ops-console' +}); +let started = false; +const tickets = helpdesk.registerEvent('ticket.updated', { + inputSchema: z.object({ queue: z.string() }), + payloadSchema: z.object({ ticketId: z.string(), status: z.string() }), + check: (_ctx, { queue }, cursor) => { + if (cursor === null) return { events: [], cursor: String(changes.length) }; + const page = changes.slice(Number(cursor)).filter(change => change.queue === queue); + return { + events: page.map(({ changeId, ticketId, status }) => ({ eventId: changeId, data: { ticketId, status } })), + cursor: String(changes.length) + }; + }, + // The first subscription sets the queue moving: one change, once it has started. + onSubscribe: () => { + if (started) return; + started = true; + setTimeout(() => changes.push({ changeId: 'c1', queue: 'billing', ticketId: 'T-7', status: 'open' }), 0); + } +}); +const handler = createMcpHandler(() => { + const mcp = new McpServer({ name: 'helpdesk', version: '1.0.0' }); + helpdesk.attach(mcp); + return mcp; +}); +const inProcess = () => + new StreamableHTTPClientTransport(new URL('http://localhost/mcp'), { fetch: (url, init) => handler.fetch(new Request(url, init)) }); +const transport = inProcess(); + +// Every `console.log` line, recorded for the checks at the end. +const logged: string[] = []; +const realLog = console.log.bind(console); +console.log = (...args: unknown[]) => { + logged.push(args.map(arg => (typeof arg === 'string' ? arg : JSON.stringify(arg))).join(' ')); + realLog(...args); +}; + +//#region subscribe_basic +import { Client } from '@modelcontextprotocol/client'; +import { EventsClientExtension } from '@modelcontextprotocol/client/ext/events'; + +const client = new Client({ name: 'ops-console', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } }); +const events = new EventsClientExtension(); +events.attach(client); +await client.connect(transport); + +const subscription = await events.subscribe({ name: 'ticket.updated', arguments: { queue: 'billing' } }); +for await (const event of subscription) { + console.log(event.name, event.data); + break; +} +//#endregion subscribe_basic + +const firstMode = subscription.deliveryMode; +// While nothing is subscribed, the ticket is closed. +changes.push({ changeId: 'c2', queue: 'billing', ticketId: 'T-7', status: 'closed' }); + +//#region subscribe_cursor +// Save the cursor; it covers every event the loop finished with. +const saved = subscription.cursor; + +// Later, maybe in a new process: resume from the saved cursor. +const resumed = await events.subscribe({ name: 'ticket.updated', arguments: { queue: 'billing' }, cursor: saved }); +for await (const event of resumed) { + console.log(event.name, event.data); + if (event.data.status === 'closed') break; +} +//#endregion subscribe_cursor + +//#region webhook_receiver +import { Hono } from 'hono'; + +const hooked = new EventsClientExtension({ webhook: { url: 'https://hooks.example.com/mcp/events' } }); +const handleWebhook = hooked.createWebhookHandler(); + +// Serve the receiver at the webhook URL from any fetch-style server; here, Hono. +const app = new Hono(); +app.post('/mcp/events', c => handleWebhook(c.req.raw)); +//#endregion webhook_receiver + +//#region errors +import { EventsError } from '@modelcontextprotocol/client/ext/events'; + +try { + const refused = await events.subscribe({ name: 'ticket.updated', arguments: { queue: 42 } }); + for await (const event of refused) console.log(event.data); +} catch (error) { + if (!(error instanceof EventsError)) throw error; + console.log(error.kind); +} +//#endregion errors + +// Claims the page makes, checked on every run. +const claim = (ok: boolean, what: string): void => { + if (!ok) throw new Error(`clients/events.md: ${what}`); +}; +claim( + JSON.stringify(logged) === + JSON.stringify([ + 'ticket.updated {"ticketId":"T-7","status":"open"}', + 'ticket.updated {"ticketId":"T-7","status":"open"}', + 'ticket.updated {"ticketId":"T-7","status":"closed"}', + 'invalidParams' + ]), + 'the page quotes this output, in this order' +); +claim(events.supported && firstMode === 'push', 'without a webhook URL, a subscription picks push where the server offers it'); + +// The webhook client: attached and connected like the first one, its subscriptions take webhook. +const hookedClient = new Client({ name: 'ops-console', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } }); +hooked.attach(hookedClient); +await hookedClient.connect(inProcess()); +receive = async request => app.fetch(request); +const hook = await hooked.subscribe({ name: 'ticket.updated', arguments: { queue: 'billing' }, cursor: '0' }); +claim(hook.deliveryMode === 'webhook', 'with a webhook URL, a subscription prefers webhook'); +// Each event is its own POST, so they may arrive in either order. +const delivered: string[] = []; +for await (const event of hook) { + delivered.push(JSON.stringify(event.data)); + if (delivered.length === 2) break; +} +claim( + JSON.stringify(delivered.toSorted()) === JSON.stringify(['{"ticketId":"T-7","status":"closed"}', '{"ticketId":"T-7","status":"open"}']), + 'the receiver must deliver the webhook POSTs into the subscription' +); + +// A server that ends the subscription ends the loop with an EventsError saying why. +const watched = await events.subscribe({ name: 'ticket.updated', arguments: { queue: 'billing' } }); +await tickets.terminate(new ServerEventsError('forbidden', 'Access revoked')); +let ended: unknown; +try { + for await (const event of watched) console.log(event.data); +} catch (error) { + ended = error; +} +claim(ended instanceof EventsError && ended.kind === 'forbidden', 'a terminated subscription must end the loop with EventsError'); + +// Closing the client ends its subscriptions with SdkError(ConnectionClosed). +const last = await events.subscribe({ name: 'ticket.updated', arguments: { queue: 'billing' } }); +const next = last[Symbol.asyncIterator]().next(); +await client.close(); +let closed: unknown; +try { + await next; +} catch (error) { + closed = error; +} +claim( + closed instanceof SdkError && closed.code === SdkErrorCode.ConnectionClosed, + 'closing the client must end subscriptions with ConnectionClosed' +); + +await hookedClient.close(); +await handler.close(); diff --git a/examples/guides/servers/events.examples.ts b/examples/guides/servers/events.examples.ts new file mode 100644 index 0000000000..6ba18b6b5f --- /dev/null +++ b/examples/guides/servers/events.examples.ts @@ -0,0 +1,313 @@ +/** + * Companion example for `docs/servers/events.md`. + * + * Every `ts` fence on that page is synced from a `//#region` in this file + * (`pnpm sync:snippets --check`). The file also runs (`pnpm docs:examples`): + * clients subscribe in process (`handler.fetch`, no port) to what the regions + * define, and the checks at the end hold the page to its claims. + * + * npx tsx guides/servers/events.examples.ts # from examples/ + * + * @module + */ + +//#region registerEvent_check +import { EventsExtension } from '@modelcontextprotocol/server/ext/events'; +import * as z from 'zod/v4'; + +// Your upstream: here, a log of ticket changes, where a cursor is a position in the log. +const changes: Array<{ changeId: string; queue: string; ticketId: string; status: string }> = []; + +const events = new EventsExtension(); + +events.registerEvent('ticket.updated', { + description: 'A ticket in a queue changed status', + inputSchema: z.object({ queue: z.string() }), + payloadSchema: z.object({ ticketId: z.string(), status: z.string() }), + check: (ctx, { queue }, cursor) => { + if (cursor === null) return { events: [], cursor: String(changes.length) }; + const from = Number(cursor); + const to = Math.min(changes.length, from + (ctx.maxEvents ?? changes.length)); + const page = changes.slice(from, to).filter(change => change.queue === queue); + return { + events: page.map(({ changeId, ticketId, status }) => ({ eventId: changeId, data: { ticketId, status } })), + cursor: String(to), + hasMore: to < changes.length + }; + } +}); +//#endregion registerEvent_check + +//#region registerEvent_emitOnly +// The open subscriptions, by the id the SDK gives each one. +const open = new Set(); + +const incidents = events.registerEvent('incident.created', { + emitOnly: true, + description: 'A new incident was opened', + inputSchema: z.object({ severity: z.enum(['P1', 'P2', 'P3']).optional() }), + payloadSchema: z.object({ incidentId: z.string(), title: z.string(), severity: z.enum(['P1', 'P2', 'P3']) }), + match: (ctx, event, { severity }) => severity === undefined || event.data.severity === severity, + onSubscribe: ctx => { + open.add(ctx.subscriptionId); + }, + onUnsubscribe: ctx => { + open.delete(ctx.subscriptionId); + } +}); + +// Wherever your upstream reports an incident, for example in its webhook handler: +await incidents.emit({ eventId: 'INC-7', data: { incidentId: 'INC-7', title: 'Checkout is down', severity: 'P1' } }); +//#endregion registerEvent_emitOnly + +//#region attach +import { createMcpHandler, McpServer } from '@modelcontextprotocol/server'; + +const handler = createMcpHandler(() => { + const mcp = new McpServer({ name: 'helpdesk', version: '1.0.0' }); + events.attach(mcp); + return mcp; +}); +//#endregion attach + +// --------------------------------------------------------------------------- +// Harness (not shown on the page): clients that talk to a handler in process. +// --------------------------------------------------------------------------- +import type { McpHttpHandler } from '@modelcontextprotocol/server'; +import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'; +import type { EventsClientOptions, EventSubscription } from '@modelcontextprotocol/client/ext/events'; +import { EventsClientExtension, EventsError as ClientEventsError } from '@modelcontextprotocol/client/ext/events'; + +const claim = (ok: boolean, what: string): void => { + if (!ok) throw new Error(`servers/events.md: ${what}`); +}; + +// A 2026-07-28 client whose requests `target` serves in process. +async function connect( + target: McpHttpHandler, + options: EventsClientOptions = {} +): Promise<{ client: Client; subscriber: EventsClientExtension }> { + const client = new Client({ name: 'events-docs-check', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } }); + const subscriber = new EventsClientExtension(options); + subscriber.attach(client); + await client.connect( + new StreamableHTTPClientTransport(new URL('http://localhost/mcp'), { fetch: (url, init) => target.fetch(new Request(url, init)) }) + ); + return { client, subscriber }; +} + +// The next `count` events of `subscription`, then it is cancelled. +async function take(subscription: EventSubscription, count: number): Promise { + const data: T[] = []; + for await (const event of subscription) { + data.push(event.data); + if (data.length === count) break; + } + return data; +} + +// The check type, by push and by poll: both replay the billing changes since cursor '0'. +changes.push( + { changeId: 'c1', queue: 'billing', ticketId: 'T-7', status: 'open' }, + { changeId: 'c2', queue: 'shipping', ticketId: 'T-8', status: 'open' }, + { changeId: 'c3', queue: 'billing', ticketId: 'T-7', status: 'closed' } +); +const BILLING = JSON.stringify([ + { ticketId: 'T-7', status: 'open' }, + { ticketId: 'T-7', status: 'closed' } +]); +const helpdesk = await connect(handler); +const listed = await helpdesk.subscriber.list(); +claim( + JSON.stringify(listed.events.map(type => [type.name, type.delivery])) === + JSON.stringify([ + ['ticket.updated', ['poll', 'push']], + ['incident.created', ['poll', 'push']] + ]), + 'without webhook options, both types offer poll and push' +); +for (const delivery of ['push', 'poll'] as const) { + const tickets = await helpdesk.subscriber.subscribe({ name: 'ticket.updated', arguments: { queue: 'billing' }, cursor: '0', delivery }); + claim(JSON.stringify(await take(tickets, 2)) === BILLING, `${delivery}: check must deliver the billing changes since the cursor`); +} + +// Push still streams when the handler answers everything else as plain JSON. +const jsonOnly = createMcpHandler( + () => { + const mcp = new McpServer({ name: 'helpdesk', version: '1.0.0' }); + events.attach(mcp); + return mcp; + }, + { responseMode: 'json' } +); +const plain = await connect(jsonOnly); +const streamed = await plain.subscriber.subscribe({ name: 'ticket.updated', arguments: { queue: 'billing' }, cursor: '0' }); +claim(streamed.deliveryMode === 'push', "push is chosen under responseMode: 'json'"); +claim(JSON.stringify(await take(streamed, 2)) === BILLING, "push must stream under responseMode: 'json'"); + +// The emit-only type: match drops the P2, the hooks track the subscription. +const p1 = await helpdesk.subscriber.subscribe({ name: 'incident.created', arguments: { severity: 'P1' } }); +claim(open.size === 1, 'onSubscribe must run when the subscription starts'); +await incidents.emit({ eventId: 'INC-8', data: { incidentId: 'INC-8', title: 'Search is slow', severity: 'P2' } }); +await incidents.emit({ eventId: 'INC-9', data: { incidentId: 'INC-9', title: 'Login fails', severity: 'P1' } }); +claim( + JSON.stringify(await take(p1, 1)) === JSON.stringify([{ incidentId: 'INC-9', title: 'Login fails', severity: 'P1' }]), + 'match must keep the P2 incident from a P1 subscription' +); +claim(open.size === 0, 'onUnsubscribe must run when the subscription ends'); + +// Terminate one subscription; its client's loop ends with the error. +const revoked = await helpdesk.subscriber.subscribe({ name: 'incident.created', arguments: {} }); +const [revokedId] = open; + +//#region terminate +import { EventsError } from '@modelcontextprotocol/server/ext/events'; + +// Ends one subscription, by the id its hooks received as ctx.subscriptionId. +function revoke(subscriptionId: string): Promise { + return incidents.terminate(new EventsError('forbidden', 'Access revoked'), { subscriptionId }); +} +//#endregion terminate + +await revoke(revokedId!); +let ended: unknown; +try { + await take(revoked, 1); +} catch (error) { + ended = error; +} +claim(ended instanceof ClientEventsError && ended.kind === 'forbidden', "terminate must end the client's loop with its error"); +claim(open.size === 0, 'terminate must run onUnsubscribe'); + +//#region webhook_setup +import type { ServerContext } from '@modelcontextprotocol/server'; +import { nodeWebhookSender } from '@modelcontextprotocol/server/ext/events/node'; + +// The user your token verifier authenticated; this one puts the subject in AuthInfo.extra. +function principalOf(ctx: ServerContext): string | null { + const sub = ctx.http?.authInfo?.extra?.sub; + return typeof sub === 'string' ? sub : null; +} + +const webhookEvents = new EventsExtension({ + webhookTtlMs: 30 * 60_000, + webhookSender: nodeWebhookSender(), + getPrincipal: principalOf +}); +//#endregion webhook_setup + +let partial: unknown; +try { + new EventsExtension({ webhookTtlMs: 30 * 60_000, webhookSender: nodeWebhookSender() }); +} catch (error) { + partial = error; +} +claim(partial instanceof TypeError, 'webhook options without getPrincipal must throw TypeError'); + +// A stand-in for a shared database: string values, each deleted at its expiry. +const database = new Map(); +const kv = { + get: async (key: string) => { + const entry = database.get(key); + return entry !== undefined && entry.expiresAt > Date.now() ? entry.value : undefined; + }, + set: async (key: string, value: string, expiresAt: number) => { + database.set(key, { value, expiresAt }); + }, + delete: async (key: string) => database.delete(key), + keys: async function* (prefix: string) { + for (const key of database.keys()) if (key.startsWith(prefix)) yield key; + } +}; + +//#region webhook_store +import type { WebhookSubscriptionRecord, WebhookSubscriptionStore } from '@modelcontextprotocol/server/ext/events'; + +// What the store needs from a database every replica shares, such as Redis. +interface SharedKeyValue { + get(key: string): Promise; + // The database deletes the key at expiresAt (with Redis: SET ... PXAT expiresAt). + set(key: string, value: string, expiresAt: number): Promise; + delete(key: string): Promise; + keys(prefix: string): AsyncIterable; +} + +function sharedWebhookStore(kv: SharedKeyValue): WebhookSubscriptionStore { + const read = async (id: string) => { + const json = await kv.get(`events:sub:${id}`); + return json === undefined ? undefined : (JSON.parse(json) as WebhookSubscriptionRecord); + }; + return { + get: read, + async put(record) { + await kv.set(`events:sub:${record.id}`, JSON.stringify(record), record.expiresAt); + await kv.set(`events:name:${record.name}:${record.id}`, '', record.expiresAt); + }, + async delete(id) { + const record = await read(id); + if (record !== undefined) await kv.delete(`events:name:${record.name}:${id}`); + return kv.delete(`events:sub:${id}`); + }, + async *listByName(name) { + const prefix = `events:name:${name}:`; + for await (const key of kv.keys(prefix)) { + const record = await read(key.slice(prefix.length)); + if (record !== undefined) yield record; + } + } + }; +} + +const replicated = new EventsExtension({ + webhookTtlMs: 30 * 60_000, + webhookSender: nodeWebhookSender(), + webhookStore: sharedWebhookStore(kv), + getPrincipal: principalOf +}); +//#endregion webhook_store + +// Two replicas share the store; their webhook POSTs reach the client's receiver in process. +let receive: (request: Request) => Promise = async () => new Response(null, { status: 503 }); +function replica() { + const extension = new EventsExtension({ + webhookTtlMs: 60_000, + webhookSender: async ({ url, headers, body }) => { + const response = await receive(new Request(url, { method: 'POST', headers, body })); + return { status: response.status, body: await response.text() }; + }, + webhookStore: sharedWebhookStore(kv), + getPrincipal: () => 'ops' + }); + const feed = extension.registerEvent('incident.created', { + emitOnly: true, + payloadSchema: z.object({ incidentId: z.string(), title: z.string(), severity: z.enum(['P1', 'P2', 'P3']) }) + }); + return { extension, feed }; +} +const [first, second] = [replica(), replica()]; +const handlerOf = (extension: EventsExtension) => + createMcpHandler(() => { + const mcp = new McpServer({ name: 'helpdesk', version: '1.0.0' }); + extension.attach(mcp); + return mcp; + }); +const firstHandler = handlerOf(first.extension); +const hooked = await connect(firstHandler, { webhook: { url: 'https://hooks.example.com/mcp/events' } }); +receive = hooked.subscriber.createWebhookHandler(); +const hook = await hooked.subscriber.subscribe({ name: 'incident.created', arguments: {} }); +claim(hook.deliveryMode === 'webhook', 'a client with a webhook URL must subscribe by webhook'); +const stored = [...database.keys()].filter(key => key.startsWith('events:sub:')); +claim(stored.length === 1, 'the subscription must be stored in the shared store'); +const record = JSON.parse(database.get(stored[0]!)!.value) as WebhookSubscriptionRecord; +claim(record.secret.startsWith('whsec_'), 'the stored record must hold the webhook secret'); +// An emit on the other replica reaches the subscription made through the first. +await second.feed.emit({ eventId: 'INC-10', data: { incidentId: 'INC-10', title: 'Payments are down', severity: 'P1' } }); +claim( + JSON.stringify(await take(hook, 1)) === JSON.stringify([{ incidentId: 'INC-10', title: 'Payments are down', severity: 'P1' }]), + 'emit() on one replica must reach a webhook subscription made on another' +); +claim(database.size === 0, 'cancel must delete the record from the shared store'); + +for (const extension of [webhookEvents, replicated]) extension.attach(new McpServer({ name: 'docs-check', version: '1.0.0' })); +for (const { client } of [helpdesk, plain, hooked]) await client.close(); +for (const target of [handler, jsonOnly, firstHandler]) await target.close(); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index a095e50e80..5628b76179 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -625,6 +625,31 @@ importers: specifier: catalog:devTools version: 4.21.0 + examples/events: + dependencies: + '@hono/node-server': + specifier: catalog:runtimeServerOnly + version: 2.1.5(hono@4.12.9) + '@mcp-examples/shared': + specifier: workspace:* + version: link:../shared + '@modelcontextprotocol/client': + specifier: workspace:* + version: link:../../packages/client + '@modelcontextprotocol/hono': + specifier: workspace:* + version: link:../../packages/middleware/hono + '@modelcontextprotocol/server': + specifier: workspace:* + version: link:../../packages/server + zod: + specifier: catalog:runtimeShared + version: 4.3.6 + devDependencies: + tsx: + specifier: catalog:devTools + version: 4.21.0 + examples/extension-capabilities: dependencies: '@hono/node-server': From 707e9b608e51d64262fbf7b1a8e5bde78cb4b9d2 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Wed, 18 Nov 2026 23:49:05 +0200 Subject: [PATCH 32/37] =?UTF-8?q?fix(events):=20final=20review=20fixes=20?= =?UTF-8?q?=E2=80=94=20non-replayable=20poll=20delivery,=20verification=20?= =?UTF-8?q?rate=20limits,=20schema=20and=20address=20edges?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/clients/events.md | 1 - docs/servers/events.md | 12 +- docs/troubleshooting.md | 2 +- examples/guides/servers/events.examples.ts | 1 + packages/client/src/ext/events/extension.ts | 21 ++-- packages/client/src/ext/events/receiver.ts | 7 ++ packages/client/src/ext/events/recovery.ts | 10 +- packages/client/src/ext/events/webhook.ts | 16 ++- packages/client/test/ext/events/poll.test.ts | 23 ++++ .../client/test/ext/events/webhook.test.ts | 43 ++++++- packages/server/src/ext/events/emitBuffer.ts | 8 ++ packages/server/src/ext/events/extension.ts | 35 +++--- packages/server/src/ext/events/poll.ts | 45 +++++-- packages/server/src/ext/events/push.ts | 31 +++-- packages/server/src/ext/events/registry.ts | 7 +- .../server/src/ext/events/specialAddresses.ts | 5 +- packages/server/src/ext/events/types.ts | 12 +- packages/server/src/ext/events/validation.ts | 4 +- .../server/src/ext/events/webhookEngine.ts | 110 ++++++++++++++++-- .../src/ext/events/webhookSubscriptions.ts | 14 ++- .../server/test/ext/events/emitBuffer.test.ts | 22 ++++ packages/server/test/ext/events/poll.test.ts | 94 +++++++++++++++ packages/server/test/ext/events/push.test.ts | 47 ++++++++ .../test/ext/events/registration.test.ts | 28 +++++ .../test/ext/events/specialAddresses.test.ts | 7 +- .../test/ext/events/webhookEngine.test.ts | 81 ++++++++++++- .../ext/events/webhookSubscriptions.test.ts | 46 +++++++- test/conformance/src/events.ts | 1 + .../test/events/eventsEndToEnd.test.ts | 4 +- 29 files changed, 659 insertions(+), 78 deletions(-) diff --git a/docs/clients/events.md b/docs/clients/events.md index 0252a589e4..0c36600e88 100644 --- a/docs/clients/events.md +++ b/docs/clients/events.md @@ -1,5 +1,4 @@ --- -status: experimental shape: how-to --- diff --git a/docs/servers/events.md b/docs/servers/events.md index 0f5bad3e37..a2483821fa 100644 --- a/docs/servers/events.md +++ b/docs/servers/events.md @@ -1,5 +1,4 @@ --- -status: experimental shape: how-to --- @@ -40,7 +39,7 @@ events.registerEvent('ticket.updated', { Clients subscribe by poll (`events/poll`) or push (`events/stream`), or by webhook (`events/subscribe`) once you turn it on, and the SDK runs each mode from this one definition. `check` returns the events since `cursor` and the cursor to resume from; for a subscription that starts now the SDK passes `cursor: null` and sends only the cursor you return. Return at most `ctx.maxEvents` events, set `hasMore` when more are waiting, and set `truncated: true` when the upstream no longer has the history since `cursor`. -Clients resume from their cursor after a disconnect or a restart, for as long as your upstream accepts it. A `check` that returns `cursor: null` marks a type that cannot resume, and the SDK never reports `truncated` for it. +Clients resume from their cursor after a disconnect or a restart, for as long as your upstream accepts it. A `check` that returns `cursor: null` marks a type that cannot resume. The SDK then calls `check` with `cursor: null` every time: it drops the events of a subscription's first call, as for any subscription that starts now, and sends the events of every later call, so return what happened since the previous call for the same `ctx.subscriptionId`. The SDK never reports `truncated` for such a type, and ignores `maxAgeMs` for it. ::: info Events is served on protocol 2026-07-28 only; a 2025-11-25 connection sees no Events capability and gets `-32601` for `events/*` — see [Protocol versions](../protocol-versions.md). @@ -72,7 +71,7 @@ const incidents = events.registerEvent('incident.created', { await incidents.emit({ eventId: 'INC-7', data: { incidentId: 'INC-7', title: 'Checkout is down', severity: 'P1' } }); ``` -`emit()` sends the event to every subscription that `match` accepts, or to one with `emit(event, { subscriptionId })`; `transform` reshapes it per subscription. The SDK drops an event whose `data` fails `payloadSchema` and reports it to `onerror`, for both kinds. +`emit()` sends the event to every subscription that `match` accepts, or to one with `emit(event, { subscriptionId })`; `transform` reshapes it per subscription. The SDK drops an event whose `data` fails `payloadSchema`, or whose `transform` output does, and reports it to `onerror`, for both kinds. Poll clients read emit-only events from an in-memory buffer (`emitBuffer`, by default the last 10 minutes and at most 10 000 events), so events emitted before a restart are lost. `onSubscribe` and `onUnsubscribe` run as a subscription starts and ends, in every mode, and `ctx.subscriptionId` names it. @@ -94,6 +93,10 @@ Attach before connecting the server. Push streams under every `responseMode`, `' A push stream carries no SSE comment keepalive. The server sends `notifications/events/heartbeat` whenever the stream has been quiet for the granted interval, `heartbeatMs` (30 seconds by default) or a shorter one the client asks for, and the SDK's client reconnects after three intervals of silence. Keep `heartbeatMs` below your load balancer's idle timeout. +Both hold under `createMcpHandler`. A custom HTTP entry built directly on `PerRequestHTTPServerTransport` must stream `events/stream` itself: serve it with `responseMode` `'auto'` or `'sse'`, never `'json'`, and the transport's `keepAliveMs` applies to it as to any stream. + +One `EventsExtension` serves at most `maxSubscriptions` subscriptions at once, 1024 by default, counting its poll leases, push streams and the webhook subscriptions this process handles; it refuses more with `resourceExhausted`. + ## Deliver events to webhooks Set `webhookTtlMs`, `webhookSender` and `getPrincipal` together to offer webhook delivery. @@ -117,7 +120,7 @@ const webhookEvents = new EventsExtension({ Setting `webhookTtlMs` or `webhookSender` without the other two throws `TypeError`. `getPrincipal` has no default, since `AuthInfo` has no subject field: return the user from wherever your token verifier puts it. A webhook subscription for which `getPrincipal` returns `null` is refused with `forbidden`, on stdio too; poll and push use the principal when there is one. -`webhookTtlMs` is the longest a webhook subscription lives without a refresh, and clients refresh before it lapses. The SDK verifies each endpoint with a challenge before the first delivery, signs every POST (Standard Webhooks), and retries a failed delivery up to five attempts in all. `nodeWebhookSender()` requires `https`, resolves the host at every send, refuses IANA special-purpose addresses (loopback, private, link-local and the like) and connects to the address it checked; it follows no redirects and gives up after 5 seconds. +`webhookTtlMs` is the longest a webhook subscription lives without a refresh, and clients refresh before it lapses. The SDK verifies each endpoint with a challenge before the first delivery, signs every POST (Standard Webhooks), and retries a failed delivery up to five attempts in all. It sends each destination host one challenge at a time and at most ten in any 60 seconds, refusing a subscribe past that with `resourceExhausted` (`data.retryAfterMs` says when to try again), and answers a principal's subscribes to a URL whose challenge failed with that failure for 60 seconds, without another challenge. `nodeWebhookSender()` requires `https`, resolves the host at every send, refuses IANA special-purpose addresses (loopback, private, link-local and the like) and connects to the address it checked; it follows no redirects and gives up after 5 seconds. ::: warning `trustedOrigins` is for development only. Its exact origins, such as `http://127.0.0.1:9000`, are exempt from the `https` rule and the private-address check, so a receiver on your machine can take deliveries; endpoint verification, signing and the no-redirect rule still apply. @@ -165,6 +168,7 @@ function sharedWebhookStore(kv: SharedKeyValue): WebhookSubscriptionStore { }; } +// `kv` is your SharedKeyValue client for that database, connected at startup. const replicated = new EventsExtension({ webhookTtlMs: 30 * 60_000, webhookSender: nodeWebhookSender(), diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index c8da05465b..aeab987e1c 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -166,7 +166,7 @@ The Resource Server helpers did not move there: `requireBearerAuth`, `mcpAuthMet ## `SSE stream disconnected: TypeError: terminated` -HTTP SSE streams emit a `: keepalive` comment every 15 seconds by default so client body-idle timeouts and intermediaries do not terminate an otherwise idle connection. Configure the interval with `keepAliveMs` on the transport or `createMcpHandler`; set it to `0` to disable heartbeats. The Events extension's `events/stream` streams are the exception: their `notifications/events/heartbeat` messages keep them alive instead. +HTTP SSE streams emit a `: keepalive` comment every 15 seconds by default so client body-idle timeouts and intermediaries do not terminate an otherwise idle connection. Configure the interval with `keepAliveMs` on the transport or `createMcpHandler`; set it to `0` to disable heartbeats. The Events extension's `events/stream` streams are the exception under `createMcpHandler`: their `notifications/events/heartbeat` messages keep them alive instead. A custom HTTP entry built directly on `PerRequestHTTPServerTransport` applies the transport's `keepAliveMs` to them too, and must stream `events/stream` itself (`responseMode` `'auto'` or `'sse'`, never `'json'`). ## Recap diff --git a/examples/guides/servers/events.examples.ts b/examples/guides/servers/events.examples.ts index 6ba18b6b5f..c9a4052b1d 100644 --- a/examples/guides/servers/events.examples.ts +++ b/examples/guides/servers/events.examples.ts @@ -258,6 +258,7 @@ function sharedWebhookStore(kv: SharedKeyValue): WebhookSubscriptionStore { }; } +// `kv` is your SharedKeyValue client for that database, connected at startup. const replicated = new EventsExtension({ webhookTtlMs: 30 * 60_000, webhookSender: nodeWebhookSender(), diff --git a/packages/client/src/ext/events/extension.ts b/packages/client/src/ext/events/extension.ts index 28ec54f6ff..7e130365f1 100644 --- a/packages/client/src/ext/events/extension.ts +++ b/packages/client/src/ext/events/extension.ts @@ -30,16 +30,19 @@ export interface EventsClientOptions { * Webhook delivery: the callback URL the server POSTs events to, where * {@linkcode EventsClientExtension.createWebhookHandler} is mounted. Each * server subscription signs with its own `whsec_` secret, random unless - * `secretProvider` supplies it; a value that is not a Standard Webhooks - * secret (`whsec_` and base64 of 24 to 64 bytes) makes `subscribe()` - * throw `TypeError`. With it set, a subscription prefers webhook where the - * event type offers it. + * `secretProvider` supplies it. `subscribe()` rejects with `TypeError` + * when the value is not a Standard Webhooks secret (`whsec_` and base64 + * of 24 to 64 bytes), or when another open server subscription already + * signs with it, since the receiver could not tell their verification + * challenges apart: return a distinct secret each call. With it set, a + * subscription prefers webhook where the event type offers it. */ webhook?: { url: string; secretProvider?: () => string }; /** * The shortest wait between two polls, whatever `nextPollMs` the server * recommends, and between two webhook refreshes, whatever the grant - * (a skewed clock cannot make them back to back). Default 1000. + * (a skewed clock cannot make them back to back), unless it would reach + * the end of the grant: the refresh then comes at ¾ of it. Default 1000. */ pollIntervalFloorMs?: number; } @@ -164,7 +167,8 @@ export class EventsClientExtension { * `ConnectionClosed` when the client closes before the first exchange answers, or another code when that * exchange fails in the SDK (for example a request timeout). * @throws {ProtocolError} `-32020` when the server rejects the `Mcp-Param` headers again after a re-list. - * @throws {TypeError} when `webhook.secretProvider` returns something that is not a Standard Webhooks secret. + * @throws {TypeError} when `webhook.secretProvider` returns something that is not a Standard Webhooks secret, or a + * secret another open server subscription signs with. */ async subscribe>(options: SubscribeOptions): Promise> { const connection = this.#require('subscribe'); @@ -190,8 +194,9 @@ export class EventsClientExtension { * to mount at `webhook.url` in any fetch-style server; every handler it * returns serves this instance's subscriptions. It verifies each POST's * Standard Webhooks signature over the raw body, answers the server's - * verification challenge, delivers each `webhook-id` once, and routes - * events and `gap` and `terminated` bodies into their subscription. + * verification challenge, delivers each `webhook-id` once within the last + * 1 000 ids it delivered, and routes events and `gap` and `terminated` + * bodies into their subscription. * Answers: `405` to anything but POST, `413` to a body over 256 KiB, * `400` to a missing header, a timestamp more than 5 minutes off or a * malformed body, `401` to a bad signature, and `503` to a subscription diff --git a/packages/client/src/ext/events/receiver.ts b/packages/client/src/ext/events/receiver.ts index 1b443aa518..3bf3f1b6fe 100644 --- a/packages/client/src/ext/events/receiver.ts +++ b/packages/client/src/ext/events/receiver.ts @@ -82,6 +82,13 @@ export class WebhookReceiver { return () => void this.#pending.delete(entry); } + // Whether a subscription, pending or bound, already signs with `secret`. + holds(secret: string): boolean { + const key = keyOf(secret); + const same = (other: Uint8Array): boolean => other.length === key.length && other.every((byte, index) => byte === key[index]); + return [...this.#pending].some(entry => same(entry.key)) || [...this.#bound.values()].some(entry => same(entry.key)); + } + // Routes deliveries for `id`, signed with `secret`, to `sink`. bind(id: string, secret: string, sink: WebhookSink): void { this.#bound.set(id, { key: keyOf(secret), sink }); diff --git a/packages/client/src/ext/events/recovery.ts b/packages/client/src/ext/events/recovery.ts index 146cc5cb72..ce9b32fefc 100644 --- a/packages/client/src/ext/events/recovery.ts +++ b/packages/client/src/ext/events/recovery.ts @@ -220,7 +220,15 @@ export class DriverLoop { if (this.#first) { // A stale cursor passed to subscribe(): drop it and start from now, if the event type still offers this mode. if (isSchemaChange(error) && this.#cursor !== null) { - await requireOffered(connection, subscription.name, this.#mode, this.#abort.signal); + try { + await requireOffered(connection, subscription.name, this.#mode, this.#abort.signal); + } catch (listError) { + if (refusesSubscription(listError)) throw listError; + // A transient re-list failure is retried in the background, from now, as a transient first exchange is. + this.#restartFromNow(); + this.subscribed(); + return 'retry'; + } this.#restartFromNow(); return 'restarted'; } diff --git a/packages/client/src/ext/events/webhook.ts b/packages/client/src/ext/events/webhook.ts index 1369731b74..a9bcada632 100644 --- a/packages/client/src/ext/events/webhook.ts +++ b/packages/client/src/ext/events/webhook.ts @@ -193,6 +193,10 @@ class WebhookDriver implements Driver { } start(): Promise { + // Checked as the secret is registered: a verification signed with it could bind another subscription's id here. + if (this.#receiver.holds(this.#secret)) { + return Promise.reject(new TypeError('webhook.secretProvider must return a secret no other open subscription uses')); + } this.#withdrawPending = this.#receiver.registerPending(this.#secret, id => this.#bind(id)); return this.#loop.start(() => this.#run(), { closed: () => { @@ -243,10 +247,8 @@ class WebhookDriver implements Driver { if (Number.isNaN(expiresAt)) return new SdkError(SdkErrorCode.InvalidResult, `Invalid refreshBefore: ${result.refreshBefore}`); this.#accept(result); if (this.#terminated === undefined) { - // A `null` grant (no expiry, which this client never asks for) is refreshed after the longest timer; the floor stops a skewed clock from refreshing back to back. - await loop.sleep( - expiresAt === undefined ? MAX_TIMER_DELAY_MS : Math.max(this.#floorMs, REFRESH_AT * (expiresAt - Date.now())) - ); + // A `null` grant (no expiry, which this client never asks for) is refreshed after the longest timer. + await loop.sleep(expiresAt === undefined ? MAX_TIMER_DELAY_MS : this.#refreshDelay(expiresAt - Date.now())); } if (this.#terminated !== undefined) { this.#live = false; @@ -256,6 +258,12 @@ class WebhookDriver implements Driver { return undefined; } + // ¾ of the grant left, never sooner than the floor (so a skewed clock cannot refresh back to back), unless the floor would reach the grant's end. + #refreshDelay(remainingMs: number): number { + const delay = Math.max(this.#floorMs, REFRESH_AT * remainingMs); + return remainingMs > 0 && delay >= remainingMs ? REFRESH_AT * remainingMs : delay; + } + // `events/subscribe` with no `ttlMs` suggestion, so the server grants its default. #subscribe(): Promise { const loop = this.#loop; diff --git a/packages/client/test/ext/events/poll.test.ts b/packages/client/test/ext/events/poll.test.ts index d4f79aa2d1..d36194cb79 100644 --- a/packages/client/test/ext/events/poll.test.ts +++ b/packages/client/test/ext/events/poll.test.ts @@ -459,6 +459,29 @@ describe('poll delivery', () => { expect(onGap).toHaveBeenCalledOnce(); }); + it('resolves subscribe() when the re-list after a refused stale cursor fails transiently, and starts from now in the background', async () => { + const onGap = vi.fn(); + let lists = 0; + const list: Handler = () => { + lists += 1; + if (lists === 2) throw new RpcError(-32_603, 'Internal error'); + return { events: [descriptor('tick')] }; + }; + const { polls, subscribe } = await pollWith(params => { + if (params['cursor'] === 'stale') + throw new RpcError(-32_026, 'Unsupported', { feature: 'inputSchema', reason: 'schema_changed' }); + return { events: [], cursor: 'v2:0', nextPollMs: 60_000 }; + }, list); + const sub = await subscribe({ cursor: 'stale', onGap }); + + expect(polls().map(call => call.params['cursor'])).toEqual(['stale']); + expect(lists).toBe(2); + await vi.advanceTimersByTimeAsync(1000); + expect(polls().map(call => call.params['cursor'])).toEqual(['stale', null]); + expect(onGap).toHaveBeenCalledExactlyOnceWith('v2:0'); + expect(sub.cursor).toBe('v2:0'); + }); + it('rejects subscribe() after a schema change refuses its cursor when the type is gone or no longer polled', async () => { // The first poll refuses the stale cursor; the re-list that follows returns `relisted`. const staleCursorAgainst = async (relisted: ReturnType[]) => { diff --git a/packages/client/test/ext/events/webhook.test.ts b/packages/client/test/ext/events/webhook.test.ts index fe4c4a5329..301844e066 100644 --- a/packages/client/test/ext/events/webhook.test.ts +++ b/packages/client/test/ext/events/webhook.test.ts @@ -49,15 +49,23 @@ function granting(...answers: Array | RpcError>): Handle }; } -async function webhookWith(subscribe: Handler, options: { list?: Handler; unsubscribe?: Handler; secretProvider?: () => string } = {}) { - const { secretProvider } = options; +async function webhookWith( + subscribe: Handler, + options: { list?: Handler; unsubscribe?: Handler; secretProvider?: () => string; pollIntervalFloorMs?: number } = {} +) { + const { secretProvider, pollIntervalFloorMs } = options; const scripted = await connectEvents( { 'events/list': options.list ?? listing(tick), 'events/subscribe': subscribe, 'events/unsubscribe': options.unsubscribe ?? (() => ({})) }, - { events: { webhook: { url: WEBHOOK_URL, ...(secretProvider !== undefined && { secretProvider }) } } } + { + events: { + webhook: { url: WEBHOOK_URL, ...(secretProvider !== undefined && { secretProvider }) }, + ...(pollIntervalFloorMs !== undefined && { pollIntervalFloorMs }) + } + } ); const handler = scripted.events.createWebhookHandler(); const subscribes = () => callsTo(scripted.calls, 'events/subscribe'); @@ -182,6 +190,20 @@ describe('webhook delivery', () => { expect(secretOf(good.subscribes()[0]!)).toBe(secret); }); + it('rejects a secretProvider value that another open subscription already uses', async () => { + const secret = generateWebhookSecret(); + const { events, subscribes, subscribe } = await webhookWith(granting({}, { id: 'sub_2' }), { secretProvider: () => secret }); + const [first, second] = await Promise.allSettled([1, 2].map(a => events.subscribe({ name: 'tick', arguments: { a } }))); + expect(first?.status).toBe('fulfilled'); + expect(second).toMatchObject({ status: 'rejected', reason: expect.any(TypeError) }); + expect(subscribes()).toHaveLength(1); + + // Once that subscription has ended, its secret is free again. + await (first as PromiseFulfilledResult).value.cancel(); + await subscribe({ arguments: { a: 2 } }); + expect(subscribes()).toHaveLength(2); + }); + it('delivers events through the receiver once per eventId, persisting each watermark cursor', async () => { const { post, subscribe } = await webhookWith(granting({ cursor: 'c0' })); const sub = await subscribe(); @@ -386,6 +408,21 @@ describe('webhook delivery', () => { } }); + it('keeps a refresh before refreshBefore when pollIntervalFloorMs would reach it', async () => { + // A 60 s grant: a 50 s floor still fits before it, while a 60 s one would land on refreshBefore and falls back to ¾ of the grant. + for (const [pollIntervalFloorMs, refreshAt] of [ + [50_000, 50_000], + [60_000, 45_000] + ] as const) { + const { subscribes, subscribe } = await webhookWith(granting({}, {}), { pollIntervalFloorMs }); + await subscribe(); + await vi.advanceTimersByTimeAsync(refreshAt - 1); + expect(subscribes()).toHaveLength(1); + await vi.advanceTimersByTimeAsync(1); + expect(subscribes()).toHaveLength(2); + } + }); + it('shares one server subscription among identical webhook subscriptions, each with its own iterator', async () => { const onGap = vi.fn(); const firstGap = vi.fn(); diff --git a/packages/server/src/ext/events/emitBuffer.ts b/packages/server/src/ext/events/emitBuffer.ts index a990f6d1cb..f3d759acc8 100644 --- a/packages/server/src/ext/events/emitBuffer.ts +++ b/packages/server/src/ext/events/emitBuffer.ts @@ -108,6 +108,14 @@ export class EmitBuffer { return sizes; } + // Drops the events of one type but keeps its sequence, so a cursor from before its head reads as a gap. + drop(name: string): void { + const ring = this.#rings.get(name); + if (ring === undefined) return; + ring.entries.length = 0; + ring.evicted = ring.last; + } + // Drops every event and starts a new epoch, as a process restart would. clear(): void { this.#rings.clear(); diff --git a/packages/server/src/ext/events/extension.ts b/packages/server/src/ext/events/extension.ts index c52d80d9b2..c9cd69626e 100644 --- a/packages/server/src/ext/events/extension.ts +++ b/packages/server/src/ext/events/extension.ts @@ -50,14 +50,7 @@ const NAMED_EVENT_METHODS = [EVENTS_POLL_METHOD, EVENTS_STREAM_METHOD, EVENTS_SU const EVENTS_METHODS = [EVENTS_LIST_METHOD, ...NAMED_EVENT_METHODS]; -const NUMERIC_OPTIONS = [ - 'webhookTtlMs', - 'pollSubscriptionTtlMs', - 'heartbeatMs', - 'checkIntervalMs', - 'defaultNextPollMs', - 'maxSubscriptions' -] as const; +const NUMERIC_OPTIONS = ['webhookTtlMs', 'pollSubscriptionTtlMs', 'heartbeatMs', 'checkIntervalMs', 'defaultNextPollMs'] as const; const DEFAULT_EMIT_BUFFER_MAX_AGE_MS = 600_000; const DEFAULT_EMIT_BUFFER_MAX_EVENTS = 10_000; @@ -65,6 +58,8 @@ const DEFAULT_POLL_SUBSCRIPTION_TTL_MS = 300_000; const DEFAULT_NEXT_POLL_MS = 30_000; const DEFAULT_HEARTBEAT_MS = 30_000; const DEFAULT_CHECK_INTERVAL_MS = 5000; +// As `createMcpHandler` bounds `subscriptions/listen` streams. +const DEFAULT_MAX_SUBSCRIPTIONS = 1024; // Servers with an events extension attached: one per server, as SEP-3371 rejects a duplicate extension identifier. const eventsServers = new WeakSet(); @@ -77,6 +72,12 @@ function assertPositive(name: string, value: unknown): void { } } +function assertCount(name: string, value: unknown): void { + if (value !== undefined && !(typeof value === 'number' && Number.isInteger(value) && value > 0)) { + throw new TypeError(`${name} must be a positive integer (got ${String(value)})`); + } +} + function assertOrigin(origin: string): void { let parsed: string | undefined; try { @@ -148,8 +149,9 @@ export class EventsExtension { constructor(options: EventsOptions = {}) { assertWebhookOptions(options); for (const name of NUMERIC_OPTIONS) assertPositive(name, options[name]); + assertCount('maxSubscriptions', options.maxSubscriptions); assertPositive('emitBuffer.maxAgeMs', options.emitBuffer?.maxAgeMs); - assertPositive('emitBuffer.maxEvents', options.emitBuffer?.maxEvents); + assertCount('emitBuffer.maxEvents', options.emitBuffer?.maxEvents); for (const origin of options.trustedOrigins ?? []) assertOrigin(origin); this.#trustedOrigins = new Set(options.trustedOrigins); this.#webhookEnabled = options.webhookTtlMs !== undefined; @@ -162,7 +164,7 @@ export class EventsExtension { registry: this.#registry, webhookEnabled: this.#webhookEnabled, getPrincipal: options.getPrincipal, - maxSubscriptions: options.maxSubscriptions, + maxSubscriptions: options.maxSubscriptions ?? DEFAULT_MAX_SUBSCRIPTIONS, subscriptionCount: () => this.#poll.size + this.#push.size + (this.#webhooks?.size ?? 0) }); this.#poll = new PollSource({ @@ -243,10 +245,6 @@ export class EventsExtension { * `events/*` methods. A legacy `initialize` result does not advertise * Events, and a server serving an earlier revision than `2026-07-28` * answers `events/*` requests with `-32601`. - * - * Experimental: Events (SEP-3415) is new; this API may change in a minor release. - * - * @experimental */ attach(mcp: McpServer): void { if (this.#attached.has(mcp)) return; @@ -286,7 +284,8 @@ export class EventsExtension { * Registers an event type: pass `check` for the default kind, or * `emitOnly: true` and call `emit()` on the returned handle. A mistake in * the definition throws `TypeError`, as does registering a name again with - * the same schemas. Registering it with a different `inputSchema` or + * the same schemas; a schema that cannot be converted to JSON Schema + * throws an `Error`. Registering it with a different `inputSchema` or * `payloadSchema` replaces the event type and ends its live subscriptions * with an `unsupported` error (`reason: 'schema_changed'`). */ @@ -307,6 +306,8 @@ export class EventsExtension { let current = this.#registry.register(name, definition); this.#checkHeaders(current); if (previous !== undefined) { + // Buffered events have the replaced schemas; their cursors read as a gap from now on. + this.#buffer.drop(name); const feature = changedSchema(previous, current)!; this.#terminateLater( name, @@ -322,12 +323,16 @@ export class EventsExtension { name, update: changes => { assertCurrent(); + const previous = current; current = this.#registry.update(current, changes); + this.#push.update(previous, current); + this.#webhooks?.update(previous, current); if (changes.inputSchema !== undefined) this.#checkHeaders(current); }, remove: () => { if (this.#registry.get(name) !== current) return; this.#registry.remove(name); + this.#buffer.drop(name); this.#terminateLater(name, new EventsError('notFound', 'Event type removed', { kind: 'event' })); }, terminate: (error, options) => this.#terminate(name, error, options?.subscriptionId) diff --git a/packages/server/src/ext/events/poll.ts b/packages/server/src/ext/events/poll.ts index 9d9db55c33..f4d1addc5f 100644 --- a/packages/server/src/ext/events/poll.ts +++ b/packages/server/src/ext/events/poll.ts @@ -48,14 +48,14 @@ export async function toOccurrence( }; } -// A check result's events to send, for every mode: off-schema ones dropped (reported), ones older than `maxAgeMs` skipped with `truncated`. +// A check result's events to send, for every mode: off-schema ones dropped (reported), ones older than `maxAgeMs` skipped with `truncated` unless the result has no replay (`cursor: null`), which `maxAgeMs` does not apply to. export async function checkedEvents( entry: RegisteredEvent, result: EventResult, maxAgeMs: number | undefined, report: (error: unknown) => void ): Promise<{ events: EventOccurrence[]; truncated: boolean }> { - const floor = maxAgeMs === undefined ? undefined : Date.now() - maxAgeMs; + const floor = maxAgeMs === undefined || result.cursor === null ? undefined : Date.now() - maxAgeMs; let truncated = result.truncated === true; const events: EventOccurrence[] = []; for (const input of result.events) { @@ -99,6 +99,23 @@ export function selectEvent( } } +// A selected event whose `transform` output fails `payloadSchema` is dropped (reported), as an off-schema emit is; without a transform it was checked at emit. +export async function checkedSelection( + entry: RegisteredEvent, + occurrence: EventOccurrence, + report: (error: unknown) => void +): Promise { + if (entry.definition.transform === undefined) return occurrence; + try { + const parsed = await entry.parsePayload(occurrence.data); + if (parsed.ok) return { ...occurrence, data: parsed.data }; + report(new Error(`event '${entry.name}': dropped an event whose transform output does not match payloadSchema: ${parsed.error}`)); + } catch (error) { + report(error); + } + return undefined; +} + // `events/poll`: every request carries one subscription, and leases drive `onSubscribe` / `onUnsubscribe` (SEP-3415 Appendix A). export class PollSource implements SubscriptionSource { readonly #deps: PollDeps; @@ -123,7 +140,7 @@ export class PollSource implements SubscriptionSource { key = leaseKey(principal, params.name, rawArgs); this.#throwTerminated(key); }); - const lease = await this.#lease(key, entry, principal, args); + const { lease, created } = await this.#lease(key, entry, principal, args); const fields = { name: entry.name, subscriptionId: lease.subscriptionId, @@ -141,12 +158,17 @@ export class PollSource implements SubscriptionSource { maxAgeMs: params.maxAgeMs, select: buffered => selectEvent(entry, selectCtx, args, buffered, this.#deps.report) }); - return { ...read, nextPollMs: this.#deps.defaultNextPollMs }; + const checked = await Promise.all(read.events.map(occurrence => checkedSelection(entry, occurrence, this.#deps.report))); + const events = checked.filter((occurrence): occurrence is EventOccurrence => occurrence !== undefined); + return { ...read, events, nextPollMs: this.#deps.defaultNextPollMs }; } const result = await check(makeContext({ ...fields, maxEvents, maxAgeMs: params.maxAgeMs }), args, cursor); const nextPollMs = result.nextPollMs ?? this.#deps.defaultNextPollMs; - if (cursor === null) return { events: [], cursor: result.cursor, truncated: false, hasMore: false, nextPollMs }; + // `null` starts from now on a new lease or for a type with replay; on a lease's later polls a type without replay gets its events. + if (cursor === null && (created || result.cursor !== null)) { + return { events: [], cursor: result.cursor, truncated: false, hasMore: false, nextPollMs }; + } const { events, truncated } = await checkedEvents(entry, result, params.maxAgeMs, this.#deps.report); return { events, cursor: result.cursor, truncated, hasMore: result.hasMore === true, nextPollMs }; } @@ -177,8 +199,13 @@ export class PollSource implements SubscriptionSource { throw terminated; } - // Renews the lease, or on first sight checks the quota and runs onSubscribe. - async #lease(key: string, entry: RegisteredEvent, principal: string | null, args: Record): Promise { + // Renews the lease, or on first sight checks the quota and runs onSubscribe; `created` on first sight. + async #lease( + key: string, + entry: RegisteredEvent, + principal: string | null, + args: Record + ): Promise<{ lease: PollLease; created: boolean }> { const pending = this.#starting.get(key); // Await only a pending start: an unconditional await would let a concurrent first poll in before `touch`. if (pending !== undefined) await pending; @@ -191,7 +218,7 @@ export class PollSource implements SubscriptionSource { entry, ended: new AbortController() })); - if (!created) return lease; + if (!created) return { lease, created }; const ctx = makeContext({ name: entry.name, subscriptionId: lease.subscriptionId, @@ -209,7 +236,7 @@ export class PollSource implements SubscriptionSource { } finally { this.#starting.delete(key); } - return lease; + return { lease, created }; } async #unsubscribe(lease: PollLease): Promise { diff --git a/packages/server/src/ext/events/push.ts b/packages/server/src/ext/events/push.ts index 128b504e5e..823b4ddd92 100644 --- a/packages/server/src/ext/events/push.ts +++ b/packages/server/src/ext/events/push.ts @@ -19,7 +19,7 @@ import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; import { makeContext } from './context'; import type { BufferedEvent, EmitBuffer } from './emitBuffer'; import type { SubscriptionSource } from './extension'; -import { checkedEvents, selectEvent } from './poll'; +import { checkedEvents, checkedSelection, selectEvent } from './poll'; import type { RegisteredEvent } from './registry'; import type { CheckContext, EventResult } from './types'; import type { SubscriptionValidator } from './validation'; @@ -40,7 +40,8 @@ export interface PushDeps { } interface PushStream { - readonly entry: RegisteredEvent; + // The registration it serves; an update() replaces it with the updated one. + entry: RegisteredEvent; readonly args: Record; readonly requestId: RequestId; readonly grant: number; @@ -179,10 +180,15 @@ export class StreamSet implements SubscriptionSource { if (!stream.live || stream.entry.name !== name) continue; stream.position = cursor; const occurrence = selectEvent(stream.entry, stream.ctx, stream.args, buffered, this.#deps.report); - if (occurrence !== undefined) this.#write(stream, EVENTS_EVENT_NOTIFICATION, { ...occurrence, cursor }); + if (occurrence !== undefined) this.#writeEvent(stream, { ...occurrence, cursor }); } } + // Moves the streams of `previous` to its updated registration, so their next batch parses with its schemas. + update(previous: RegisteredEvent, next: RegisteredEvent): void { + for (const stream of this.#streams) if (stream.entry === previous) stream.entry = next; + } + // Sends `terminated` on each matching stream, runs onUnsubscribe, and ends the request with its final result. async terminate(name: string, error: EventsError, subscriptionId?: string): Promise { const ending: Promise[] = []; @@ -267,10 +273,15 @@ export class StreamSet implements SubscriptionSource { heartbeatMs: stream.grant }); } - for (const event of batch.events) this.#write(stream, EVENTS_EVENT_NOTIFICATION, event); + for (const event of batch.events) this.#writeEvent(stream, event); stream.position = batch.position; } + // Writes an event that checkedSelection passes, in order with the stream's other writes. + #writeEvent(stream: PushStream, event: EventOccurrence): void { + this.#write(stream, EVENTS_EVENT_NOTIFICATION, checkedSelection(stream.entry, event, this.#deps.report)); + } + #scheduleCheck(stream: PushStream): void { if (!stream.live || stream.entry.kind !== 'check') return; stream.checkTimer = unref(setTimeout(() => void this.#check(stream), this.#deps.checkIntervalMs)); @@ -294,10 +305,16 @@ export class StreamSet implements SubscriptionSource { this.#scheduleCheck(stream); } - #write(stream: PushStream, method: string, params: Record): void { - const notification = { method, params: { ...params, _meta: { [SUBSCRIPTION_ID_META_KEY]: stream.requestId } } }; + // Params that resolve to `undefined` (a dropped event) send nothing. + #write(stream: PushStream, method: string, params: Record | Promise | undefined>): void { + const _meta = { [SUBSCRIPTION_ID_META_KEY]: stream.requestId }; // A failed write means the client is gone. - stream.queue = stream.queue.then(() => stream.notify(notification)).catch(() => void this.#end(stream)); + stream.queue = stream.queue + .then(async () => { + const resolved = await params; + if (resolved !== undefined) await stream.notify({ method, params: { ...resolved, _meta } }); + }) + .catch(() => void this.#end(stream)); if (!stream.live) return; clearTimeout(stream.heartbeat); stream.heartbeat = unref( diff --git a/packages/server/src/ext/events/registry.ts b/packages/server/src/ext/events/registry.ts index a5bdeb70e4..d3532129d3 100644 --- a/packages/server/src/ext/events/registry.ts +++ b/packages/server/src/ext/events/registry.ts @@ -9,6 +9,9 @@ export type AnyEventDefinition = EventDefinition[0]; +// The fields update() changes; anything else on the object it is given is ignored. +const UPDATABLE = ['description', 'inputSchema', 'payloadSchema', '_meta'] as const; + export interface RegisteredEvent { readonly name: string; readonly kind: 'check' | 'emitOnly'; @@ -81,9 +84,9 @@ export class EventRegistry { return entry; } - // Rebuilds a registered event type with the defined fields of `changes` replaced. + // Rebuilds a registered event type with the defined updatable fields of `changes` replaced. update(entry: RegisteredEvent, changes: EventChanges): RegisteredEvent { - const defined = Object.fromEntries(Object.entries(changes).filter(([, value]) => value !== undefined)); + const defined = Object.fromEntries(UPDATABLE.filter(key => changes[key] !== undefined).map(key => [key, changes[key]])); const next = createEntry(entry.name, { ...entry.definition, ...defined }); this.#entries.set(entry.name, next); return next; diff --git a/packages/server/src/ext/events/specialAddresses.ts b/packages/server/src/ext/events/specialAddresses.ts index f3862e210f..c674650cb4 100644 --- a/packages/server/src/ext/events/specialAddresses.ts +++ b/packages/server/src/ext/events/specialAddresses.ts @@ -81,6 +81,7 @@ const IPV6_SPECIAL = [ '::1/128', '64:ff9b:1::/48', '100::/64', + '100:0:0:1::/64', '2001::/23', '2001:db8::/32', '2002::/16', @@ -90,8 +91,8 @@ const IPV6_SPECIAL = [ 'fe80::/10', 'ff00::/8' ].map(cidr => blockOf(cidr, 128n, parseIpv6)); -// IPv4-mapped (`::ffff:0:0/96`) and well-known-prefix NAT64 (`64:ff9b::/96`) addresses carry an IPv4 address in their low 32 bits. -const EMBEDS_IPV4 = ['::ffff:0:0/96', '64:ff9b::/96'].map(cidr => blockOf(cidr, 128n, parseIpv6)); +// IPv4-compatible (`::/96`, so `::` and `::1` too), IPv4-mapped (`::ffff:0:0/96`) and well-known-prefix NAT64 (`64:ff9b::/96`) addresses carry an IPv4 address in their low 32 bits. +const EMBEDS_IPV4 = ['::/96', '::ffff:0:0/96', '64:ff9b::/96'].map(cidr => blockOf(cidr, 128n, parseIpv6)); // Whether `ip` is in a special-purpose range, an address that embeds an IPv4 address by that IPv4 part; anything that is not an IP address counts as special. export function isSpecialPurposeAddress(ip: string): boolean { diff --git a/packages/server/src/ext/events/types.ts b/packages/server/src/ext/events/types.ts index 93b9b13c7e..ba779bab6e 100644 --- a/packages/server/src/ext/events/types.ts +++ b/packages/server/src/ext/events/types.ts @@ -105,7 +105,13 @@ export interface EventDefinitionBase extends EventDefinitionBase { emitOnly?: false; - /** The events since `cursor`; with `cursor: null`, only the current cursor (no events). */ + /** + * The events since `cursor`, and the cursor to resume from. A subscription that starts from now begins with + * a call with `cursor: null` whose events the SDK drops: it takes only the cursor returned. A type without + * replay returns `cursor: null`, so after that first call the SDK calls `check` with `null` every time and + * sends the events each call returns: return what happened since the previous call for the same + * `ctx.subscriptionId`. + */ check(ctx: CheckContext, args: InferOutput, cursor: string | null): EventResult> | Promise>>; match?: never; transform?: never; @@ -258,7 +264,8 @@ export interface WebhookSubscriptionStore { /** * Options for `new EventsExtension(options)`. Durations are in milliseconds; - * every number must be positive and finite. + * every number must be positive and finite, and the counts + * (`maxSubscriptions`, `emitBuffer.maxEvents`) whole numbers. * * Experimental: Events (SEP-3415) is new; this API may change in a minor release. * @@ -288,6 +295,7 @@ export interface EventsOptions { /** * The most subscriptions this process serves at once, counting poll leases, push streams and the webhook * subscriptions whose subscribe or refresh it handled or is still creating; more are refused with `resourceExhausted`. + * @default 1024 */ maxSubscriptions?: number; /** Receives errors nothing else can report (dropped payloads, hook failures, invalid `x-mcp-header` annotations). Default: `console.warn`. */ diff --git a/packages/server/src/ext/events/validation.ts b/packages/server/src/ext/events/validation.ts index edf256220b..ba8f6e5021 100644 --- a/packages/server/src/ext/events/validation.ts +++ b/packages/server/src/ext/events/validation.ts @@ -9,7 +9,7 @@ export interface ValidatorDeps { readonly registry: EventRegistry; readonly webhookEnabled: boolean; readonly getPrincipal: EventsOptions['getPrincipal']; - readonly maxSubscriptions: number | undefined; + readonly maxSubscriptions: number; // Subscriptions this process serves now: poll leases, push streams, and the webhook subscriptions whose subscribe or refresh it handled or is still creating. subscriptionCount(): number; } @@ -61,7 +61,7 @@ export class SubscriptionValidator { // The `maxSubscriptions` quota; call it before a new subscription's `onSubscribe`. assertCapacity(): void { const max = this.#deps.maxSubscriptions; - if (max !== undefined && this.#deps.subscriptionCount() >= max) { + if (this.#deps.subscriptionCount() >= max) { throw new EventsError('resourceExhausted', 'Subscription limit reached', { limit: 'subscriptions', max }); } } diff --git a/packages/server/src/ext/events/webhookEngine.ts b/packages/server/src/ext/events/webhookEngine.ts index 462f38dfa2..96a662654d 100644 --- a/packages/server/src/ext/events/webhookEngine.ts +++ b/packages/server/src/ext/events/webhookEngine.ts @@ -21,6 +21,15 @@ const MAX_PARKED_MESSAGES = 10_000; const SUSPENSION_WINDOW_MS = 3_600_000; const SUSPENSION_MIN_ATTEMPTS = 100; const SUSPENSION_FAILURE_PERCENT = 95; +// A failed verification of a (principal, url) is answered again for this long without a POST. +const FAILED_VERIFICATION_MS = 60_000; +// Verification POSTs to one destination host: one at a time, and at most 10 in any 60 s. +const VERIFICATIONS_PER_WINDOW = 10; +const VERIFICATION_WINDOW_MS = 60_000; +// The retry hint while another verification to the host is in flight: nodeWebhookSender's 5 s timeout. +const IN_FLIGHT_RETRY_MS = 5000; +// The most failed pairs and destination hosts the verification limits remember. +const MAX_REMEMBERED = 10_000; const encoder = new TextEncoder(); @@ -78,6 +87,22 @@ interface Tracked { recentFailures: number; } +// One destination host's verification POSTs: whether one is in flight, and the send times of the last window, oldest first. +interface HostVerifications { + inFlight: boolean; + readonly sent: number[]; +} + +// Adds `key` to `map`; at MAX_REMEMBERED it first drops the entries `stale` says are done, then the oldest. +function remember(map: Map, key: string, value: V, stale: (held: V) => boolean): void { + map.delete(key); + if (map.size >= MAX_REMEMBERED) { + for (const [held, entry] of map) if (stale(entry)) map.delete(held); + if (map.size >= MAX_REMEMBERED) map.delete(map.keys().next().value!); + } + map.set(key, value); +} + // Retry timers never keep the process alive on their own. function unref(timer: ReturnType): ReturnType { (timer as { unref?: () => void }).unref?.(); @@ -130,6 +155,13 @@ function verificationError(reason: DeliveryErrorCategory): EventsError { return new EventsError('callbackEndpointError', `Webhook endpoint verification failed: ${reason}`, { reason }); } +function verificationLimit(retryAfterMs: number): EventsError { + return new EventsError('resourceExhausted', 'Too many webhook endpoint verifications for this host', { + limit: 'verification', + retryAfterMs + }); +} + // Sends webhook POSTs: endpoint verification, signed event deliveries with per-message retries and the watermark cursor, and control bodies. export class WebhookEngine { readonly #sender: WebhookSender; @@ -142,6 +174,12 @@ export class WebhookEngine { // Each verified `principal\0url` with the subscription ids it covers; it lasts while one of them does. readonly #verified = new Map>(); readonly #verifiedKeyOf = new Map(); + // Each `principal\0url` handshake in flight, which another subscribe of the pair waits for. + readonly #handshakes = new Map>(); + // Each `principal\0url` whose verification failed lately: the failure, and until when it is answered without a POST. + readonly #failed = new Map(); + // By lower-cased destination hostname (SEP-3415: rate-limited per destination host). + readonly #hosts = new Map(); // Aborts verification sends in flight on clear(); made at first use, as Cloudflare Workers refuse it at module scope. #lifetime: AbortController | undefined; @@ -158,19 +196,13 @@ export class WebhookEngine { return this.#tracked.size; } - // One attempt, which the subscribe call waits for; throws `callbackEndpointError` with the failure category as `data.reason`. + // One attempt, which the subscribe call waits for; throws `callbackEndpointError` with the failure category as `data.reason`, or `resourceExhausted` at the host's limit. async verify(principal: string, url: string, secret: string, subscriptionId: string): Promise { const key = `${principal}\u0000${url}`; + if (!this.#verified.has(key)) await this.#verifyPair(key, url, secret, subscriptionId); let covered = this.#verified.get(key); if (covered === undefined) { - const challenge = challengeNonce(); - const body = JSON.stringify({ type: 'verification', challenge }); - const webhookId = generateWebhookId('verification'); - this.#lifetime ??= new AbortController(); - const outcome = await this.#post(url, subscriptionId, [secret], webhookId, body, this.#lifetime.signal); - if ('error' in outcome) throw verificationError(outcome.error); - if (!echoes(outcome, challenge)) throw verificationError('challenge_failed'); - covered = this.#verified.get(key) ?? new Set(); + covered = new Set(); this.#verified.set(key, covered); } covered.add(subscriptionId); @@ -260,10 +292,70 @@ export class WebhookEngine { for (const control of this.#controls) this.#stopControl(control); this.#verified.clear(); this.#verifiedKeyOf.clear(); + this.#handshakes.clear(); + this.#failed.clear(); + this.#hosts.clear(); this.#lifetime?.abort(); this.#lifetime = undefined; } + // The pair's handshake in flight, or a new one. + #verifyPair(key: string, url: string, secret: string, subscriptionId: string): Promise { + const pending = this.#handshakes.get(key); + if (pending !== undefined) return pending; + const handshake = this.#handshake(key, url, secret, subscriptionId).finally(() => { + if (this.#handshakes.get(key) === handshake) this.#handshakes.delete(key); + }); + this.#handshakes.set(key, handshake); + return handshake; + } + + // One verification POST, unless a failure of the pair is still remembered or the host is at its limit. + async #handshake(key: string, url: string, secret: string, subscriptionId: string): Promise { + const now = this.#now(); + const failed = this.#failed.get(key); + if (failed !== undefined && now < failed.until) throw verificationError(failed.reason); + this.#failed.delete(key); + const host = this.#claimHost(url, now); + this.#lifetime ??= new AbortController(); + const { signal } = this.#lifetime; + try { + const challenge = challengeNonce(); + const body = JSON.stringify({ type: 'verification', challenge }); + const outcome = await this.#post(url, subscriptionId, [secret], generateWebhookId('verification'), body, signal); + let reason: DeliveryErrorCategory | undefined; + if ('error' in outcome) reason = outcome.error; + else if (!echoes(outcome, challenge)) reason = 'challenge_failed'; + if (reason === undefined) return; + // A send that clear() aborted leaves nothing behind. + if (!signal.aborted) { + const until = this.#now() + FAILED_VERIFICATION_MS; + remember(this.#failed, key, { reason, until }, held => held.until <= this.#now()); + } + throw verificationError(reason); + } finally { + host.inFlight = false; + } + } + + // Takes the host's one verification slot and counts the POST, or throws `resourceExhausted` with a retry hint. + #claimHost(url: string, now: number): HostVerifications { + const name = new URL(url).hostname.toLowerCase(); + const start = now - VERIFICATION_WINDOW_MS; + let host = this.#hosts.get(name); + if (host === undefined) { + host = { inFlight: false, sent: [] }; + remember(this.#hosts, name, host, held => !held.inFlight && (held.sent.at(-1) ?? start) <= start); + } + const { sent } = host; + while (sent[0] !== undefined && sent[0] <= start) sent.shift(); + if (host.inFlight) throw verificationLimit(IN_FLIGHT_RETRY_MS); + if (sent.length >= VERIFICATIONS_PER_WINDOW) throw verificationLimit(sent[0]! - start); + host.inFlight = true; + sent.push(now); + return host; + } + #start(id: string, watermark: string | null): Tracked { const tracked: Tracked = { id, diff --git a/packages/server/src/ext/events/webhookSubscriptions.ts b/packages/server/src/ext/events/webhookSubscriptions.ts index a2736eb0f1..a083e42f99 100644 --- a/packages/server/src/ext/events/webhookSubscriptions.ts +++ b/packages/server/src/ext/events/webhookSubscriptions.ts @@ -10,7 +10,7 @@ import { canonicalJson, EventsError, parseWebhookSecret } from '@modelcontextpro import { makeContext } from './context'; import type { BufferedEvent, EmitBuffer } from './emitBuffer'; import type { SubscriptionSource } from './extension'; -import { selectEvent } from './poll'; +import { checkedSelection, selectEvent } from './poll'; import type { Batch } from './push'; import { checkedBatch, errorObject, startCheck, TERMINAL_KINDS } from './push'; import type { EventRegistry, RegisteredEvent } from './registry'; @@ -51,8 +51,8 @@ export interface WebhookDeps { // What this process runs for a subscription whose subscribe or refresh it handled: the expiry timer, and a check type's loop. interface Watched { readonly id: string; - // The registration it serves, so onUnsubscribe pairs with it after a removal or re-registration. - readonly entry: RegisteredEvent; + // The registration it serves, so onUnsubscribe pairs with it after a removal or re-registration; an update() replaces it with the updated one. + entry: RegisteredEvent; // Aborts when this process stops serving the subscription; the `signal` of its callbacks. readonly ended: AbortController; readonly ctx: CheckContext; @@ -209,6 +209,11 @@ export class WebhookSubscriptions implements SubscriptionSource { ); } + // Moves the watches of `previous` to its updated registration, so their next check parses with its schemas. + update(previous: RegisteredEvent, next: RegisteredEvent): void { + for (const watched of this.#watched.values()) if (watched.entry === previous) watched.entry = next; + } + // Sends a `terminated` envelope to each matching subscription in the store, deletes it and runs onUnsubscribe. async terminate(name: string, error: EventsError, subscriptionId?: string): Promise { const ids = new Set(); @@ -502,7 +507,8 @@ export class WebhookSubscriptions implements SubscriptionSource { continue; } const ctx = this.#watched.get(record.id)?.ctx ?? this.#contextOf(record, unwatchedSignal()); - const occurrence = selectEvent(entry, ctx, record.arguments, buffered, this.#deps.report); + const selected = selectEvent(entry, ctx, record.arguments, buffered, this.#deps.report); + const occurrence = selected === undefined ? undefined : await checkedSelection(entry, selected, this.#deps.report); if (occurrence !== undefined) this.#engine.deliver(record, occurrence, cursor, previous); } } diff --git a/packages/server/test/ext/events/emitBuffer.test.ts b/packages/server/test/ext/events/emitBuffer.test.ts index d1f1f4bdee..07cf4d39f6 100644 --- a/packages/server/test/ext/events/emitBuffer.test.ts +++ b/packages/server/test/ext/events/emitBuffer.test.ts @@ -166,6 +166,28 @@ describe('EmitBuffer', () => { }); }); + it('drop() drops the events of one type and keeps its sequence, so earlier cursors read as a gap', () => { + const buffer = filled(2); + buffer.append('j', { occurrence: { ...occurrence(1), name: 'j' } }); + const start = buffer.read('i', null, { maxEvents: 0, select: all }).cursor; + const middle = buffer.append('i', { occurrence: occurrence(3) }); + const head = buffer.head('i'); + buffer.drop('i'); + buffer.drop('missing'); + expect(buffer.sizes()).toEqual({ i: 0, j: 1 }); + expect(buffer.head('i')).toBe(head); + for (const cursor of [start, middle]) { + expect(buffer.read('i', cursor, { maxEvents: 10, select: all })).toEqual({ + events: [], + cursor: head, + truncated: true, + hasMore: false + }); + } + buffer.append('i', { occurrence: occurrence(4) }); + expect(ids(buffer.read('i', head, { maxEvents: 10, select: all }).events)).toEqual(['evt_4']); + }); + it('reports how many events each type holds', () => { const buffer = filled(3, { maxAgeMs: 60_000, maxEvents: 2 }); buffer.append('j', { occurrence: { ...occurrence(1), name: 'j' } }); diff --git a/packages/server/test/ext/events/poll.test.ts b/packages/server/test/ext/events/poll.test.ts index b3444414de..076d3a59f5 100644 --- a/packages/server/test/ext/events/poll.test.ts +++ b/packages/server/test/ext/events/poll.test.ts @@ -100,6 +100,55 @@ describe('events/poll for a check type', () => { expect(await poller(events).poll({ name: 't', cursor: 'h1' })).toMatchObject({ events: [], cursor: null, truncated: false }); }); + it('delivers what check(null) returns from the second poll of a lease on, for a type without replay', async () => { + vi.useFakeTimers(); + const onUnsubscribe = vi.fn(); + const events = new EventsExtension({ pollSubscriptionTtlMs: 300_000 }); + let beat = 0; + const check = vi.fn((_ctx: CheckContext, _args: unknown, _cursor: string | null) => { + beat += 1; + return { events: [{ eventId: `b${beat}`, data: { n: beat } }], cursor: null, hasMore: true }; + }); + events.registerEvent('pulse', { payloadSchema: P, check, onUnsubscribe }); + const { poll } = poller(events); + + expect(await poll({ name: 'pulse', cursor: null })).toMatchObject({ events: [], cursor: null, truncated: false, hasMore: false }); + const second = await poll({ name: 'pulse', cursor: null }); + expect(second.events.map(event => event.eventId)).toEqual(['b2']); + expect(second).toMatchObject({ cursor: null, truncated: false, hasMore: true }); + expect((await poll({ name: 'pulse' })).events.map(event => event.eventId)).toEqual(['b3']); + expect(check.mock.calls.map(([, , cursor]) => cursor)).toEqual([null, null, null]); + const [subscriptionId, ...others] = new Set(check.mock.calls.map(([ctx]) => ctx.subscriptionId)); + expect(others).toEqual([]); + + await vi.advanceTimersByTimeAsync(300_001); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + expect((onUnsubscribe.mock.calls[0]![0] as EventContext).subscriptionId).toBe(subscriptionId); + // The next poll starts a new lease, which bootstraps again. + expect(await poll({ name: 'pulse', cursor: null })).toMatchObject({ events: [], cursor: null }); + expect(check.mock.calls[3]![0].subscriptionId).not.toBe(subscriptionId); + }); + + it('starts a type with replay from now on every cursor: null poll', async () => { + const events = new EventsExtension(); + events.registerEvent('t', { payloadSchema: P, check: () => ({ events: [{ data: { n: 1 } }], cursor: 'h1' }) }); + const { poll } = poller(events); + expect(await poll({ name: 't', cursor: null })).toMatchObject({ events: [], cursor: 'h1' }); + expect(await poll({ name: 't', cursor: null })).toMatchObject({ events: [], cursor: 'h1' }); + }); + + it('ignores maxAgeMs for a result with cursor: null', async () => { + const events = new EventsExtension(); + const old = new Date(Date.now() - 600_000).toISOString(); + events.registerEvent('t', { + payloadSchema: P, + check: () => ({ events: [{ eventId: 'old', timestamp: old, data: { n: 1 } }], cursor: null }) + }); + const result = await poller(events).poll({ name: 't', cursor: 'h1', maxAgeMs: 300_000 }); + expect(result.events.map(event => event.eventId)).toEqual(['old']); + expect(result.truncated).toBe(false); + }); + it('applies the maxAgeMs floor and flags truncated', async () => { const events = new EventsExtension(); const old = new Date(Date.now() - 600_000).toISOString(); @@ -284,6 +333,30 @@ describe('events/poll for an emit-only type', () => { expect(await poll({ name: 'i', cursor })).toMatchObject({ events: [], cursor }); }); + it('drops a transform output that fails payloadSchema and reports it', async () => { + const onerror = vi.fn(); + const events = new EventsExtension({ onerror }); + const h = events.registerEvent('i', { + emitOnly: true, + payloadSchema: P, + transform: (_ctx, event) => ({ + ...event, + data: event.data.n === 1 ? ({ n: 'one' } as unknown as { n: number }) : { n: event.data.n * 10 } + }) + }); + const { poll } = poller(events); + const { cursor } = await poll({ name: 'i', cursor: null }); + await h.emit({ data: { n: 1 } }); + await h.emit({ data: { n: 2 } }); + const result = await poll({ name: 'i', cursor }); + expect(result.events.map(event => event.data)).toEqual([{ n: 20 }]); + expect(await poll({ name: 'i', cursor: result.cursor })).toMatchObject({ events: [] }); + expect(onerror).toHaveBeenCalledOnce(); + expect(onerror.mock.calls[0]![0].message).toMatch( + /^event 'i': dropped an event whose transform output does not match payloadSchema: / + ); + }); + it('skips an event whose match throws and reports it', async () => { const onerror = vi.fn(); const events = new EventsExtension({ onerror }); @@ -323,6 +396,27 @@ describe('events/poll for an emit-only type', () => { expect(onerror).toHaveBeenCalledWith(expect.objectContaining({ message: 'push failed' })); }); + it('drops buffered events on remove() and on a schema change, so earlier cursors read as a gap', async () => { + const events = new EventsExtension(); + const v1 = events.registerEvent('i', { emitOnly: true, payloadSchema: P }); + // Distinct arguments, so each poll has a lease of its own that no termination reached. + const { poll } = poller(events); + const { cursor: c0 } = await poll({ name: 'i', arguments: { k: 0 }, cursor: null }); + await v1.emit({ data: { n: 1 } }); + const { cursor: c1 } = await poll({ name: 'i', arguments: { k: 1 }, cursor: null }); + + const v2 = events.registerEvent('i', { emitOnly: true, payloadSchema: z.object({ n: z.number(), v: z.literal(2) }) }); + expect(testHook(events).state().emitBuffer).toEqual({ i: 0 }); + expect(await poll({ name: 'i', arguments: { k: 2 }, cursor: c0 })).toMatchObject({ events: [], cursor: c1, truncated: true }); + await v2.emit({ data: { n: 2, v: 2 } }); + expect((await poll({ name: 'i', arguments: { k: 3 }, cursor: c1 })).events.map(event => event.data)).toEqual([{ n: 2, v: 2 }]); + + v2.remove(); + expect(testHook(events).state().emitBuffer).toEqual({ i: 0 }); + events.registerEvent('i', { emitOnly: true, payloadSchema: P }); + expect(await poll({ name: 'i', arguments: { k: 4 }, cursor: c1 })).toMatchObject({ events: [], truncated: true }); + }); + it('rejects emit() on a handle whose registration was removed', async () => { const events = new EventsExtension(); const h = events.registerEvent('i', { emitOnly: true, payloadSchema: P }); diff --git a/packages/server/test/ext/events/push.test.ts b/packages/server/test/ext/events/push.test.ts index 6b10e6d34b..907b7c0470 100644 --- a/packages/server/test/ext/events/push.test.ts +++ b/packages/server/test/ext/events/push.test.ts @@ -286,6 +286,31 @@ describe('events/stream: a check type', () => { expect(check.mock.calls.map(call => call[2])).toEqual([null, 'h0', 'h0']); }); + it('parses the next batch of an open stream with the payloadSchema of an update()', async () => { + vi.useFakeTimers({ shouldAdvanceTime: true }); + const labelled = (eventId: string, n: number) => ({ eventId, data: { n, label: `#${n}` } as { n: number } }); + const check = vi + .fn() + .mockReturnValueOnce({ events: [], cursor: 'h0' }) + .mockReturnValueOnce({ events: [labelled('e1', 1)], cursor: 'h1' }) + .mockReturnValueOnce({ events: [labelled('e2', 2)], cursor: 'h2' }) + .mockReturnValue({ events: [], cursor: 'h2' }); + const events = new EventsExtension(); + const handle = events.registerEvent('tick', { payloadSchema: P, check }); + const stream = await open(serve(events), { name: 'tick', cursor: null }); + await next(stream); + const before = next(stream); + await vi.advanceTimersByTimeAsync(5000); + // The registered schema strips the unknown `label`. + expect(await before).toMatchObject({ method: EVENT, params: { eventId: 'e1' } }); + expect(paramsOf(await before)['data']).toEqual({ n: 1 }); + + handle.update({ payloadSchema: z.object({ n: z.number(), label: z.string().optional() }) }); + const after = next(stream); + await vi.advanceTimersByTimeAsync(5000); + expect(paramsOf(await after)['data']).toEqual({ n: 2, label: '#2' }); + }); + it('terminates when check throws forbidden', async () => { vi.useFakeTimers({ shouldAdvanceTime: true }); const onUnsubscribe = vi.fn(); @@ -378,6 +403,28 @@ describe('events/stream: an emit-only type', () => { expect(ids.get('P1')).not.toBe(ids.get('P3')); }); + it('drops a transform output that fails payloadSchema, replayed or live, and reports it', async () => { + const onerror = vi.fn(); + const events = new EventsExtension({ onerror }); + const handle = events.registerEvent('i', { + emitOnly: true, + payloadSchema: P, + transform: (_ctx, event) => + event.eventId?.startsWith('bad') === true ? { ...event, data: { n: 'x' } as unknown as { n: number } } : event + }); + const served = serve(events); + const { cursor } = resultOf(await served.rpc('events/poll', { name: 'i', cursor: null })) as PollEventsResult; + await handle.emit({ eventId: 'bad-1', data: { n: 1 } }); + await handle.emit({ eventId: 'good-2', data: { n: 2 } }); + const stream = await open(served, { name: 'i', cursor }); + expect(await next(stream)).toMatchObject({ method: ACTIVE }); + expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'good-2', data: { n: 2 } } }); + await handle.emit({ eventId: 'bad-3', data: { n: 3 } }); + await handle.emit({ eventId: 'good-4', data: { n: 4 } }); + expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'good-4' } }); + expect(onerror).toHaveBeenCalledTimes(2); + }); + it('replays from a cursor with each event at its own position, then goes live', async () => { const events = new EventsExtension(); const handle = events.registerEvent('i', { emitOnly: true, payloadSchema: P }); diff --git a/packages/server/test/ext/events/registration.test.ts b/packages/server/test/ext/events/registration.test.ts index e8fc327660..8130ff9c03 100644 --- a/packages/server/test/ext/events/registration.test.ts +++ b/packages/server/test/ext/events/registration.test.ts @@ -122,6 +122,24 @@ describe('options', () => { expect(() => new EventsExtension({ webhookTtlMs: value, webhookSender, getPrincipal: () => 'alice' })).toThrow(TypeError); }); + it.each([1.5, 0.5])('refuses %s for a count option', value => { + expect(() => new EventsExtension({ maxSubscriptions: value })).toThrow(/maxSubscriptions must be a positive integer/); + expect(() => new EventsExtension({ emitBuffer: { maxEvents: value } })).toThrow(TypeError); + expect(() => new EventsExtension({ heartbeatMs: value })).not.toThrow(); + }); + + it('serves at most 1024 subscriptions by default', async () => { + const events = new EventsExtension(); + events.registerEvent('tick', { payloadSchema: P, check: tick }); + const { rpc } = serve(events); + for (let n = 0; n < 1024; n++) resultOf(await rpc('events/poll', { name: 'tick', arguments: { n } })); + expect(errorOf(await rpc('events/poll', { name: 'tick', arguments: { n: 1024 } }))).toMatchObject({ + code: -32_025, + data: { limit: 'subscriptions', max: 1024 } + }); + resultOf(await rpc('events/poll', { name: 'tick', arguments: { n: 0 } })); + }); + it('accepts only exact origins as trustedOrigins', () => { expect(() => new EventsExtension({ trustedOrigins: ['http://127.0.0.1:9000', 'https://example.com'] })).not.toThrow(); for (const origin of ['http://127.0.0.1:9000/', 'https://example.com/hook', 'HTTPS://EXAMPLE.COM', 'example.com', 'not a url']) { @@ -212,6 +230,16 @@ describe('registerEvent', () => { expect(terminate).toHaveBeenCalledOnce(); }); + it('update() takes only the fields it lists, whatever else the object carries', async () => { + const events = new EventsExtension(); + const handle = events.registerEvent('tick', { payloadSchema: P, check: tick }); + const changes = { description: 'v2', delivery: { poll: false }, emitOnly: true, check: undefined }; + handle.update(changes); + expect((await listOf(events)).events).toMatchObject([{ name: 'tick', description: 'v2', delivery: ['poll', 'push'] }]); + // Still a check type: the poll runs check(), whose cursor is '0'. + expect(resultOf(await serve(events).rpc('events/poll', { name: 'tick', cursor: 'c' }))).toMatchObject({ cursor: '0' }); + }); + it('terminate() reaches every subscription source', async () => { const events = new EventsExtension(); const first = vi.fn(async () => {}); diff --git a/packages/server/test/ext/events/specialAddresses.test.ts b/packages/server/test/ext/events/specialAddresses.test.ts index 0e00af14ac..4f439dd4f7 100644 --- a/packages/server/test/ext/events/specialAddresses.test.ts +++ b/packages/server/test/ext/events/specialAddresses.test.ts @@ -42,6 +42,7 @@ describe('isSpecialPurposeAddress', () => { ['64:ff9b::/96 by its IPv4 part', '64:ff9b::127.0.0.1'], ['64:ff9b:1::/48', '64:ff9b:1:ffff::1'], ['100::/64', '100::ffff:ffff:ffff:ffff'], + ['100:0:0:1::/64', '100:0:0:1:ffff:ffff:ffff:ffff'], ['2001::/23', '2001:1ff::1'], ['2001:db8::/32', '2001:DB8:ffff::1'], ['2002::/16', '2002:c000:204::1'], @@ -51,6 +52,9 @@ describe('isSpecialPurposeAddress', () => { ['fe80::/10', 'febf::1'], ['ff00::/8', 'ff02::1'], ['::ffff:0:0/96 by its IPv4 part', '::ffff:a00:1'], + ['::/96 by its IPv4 part', '::7f00:1'], + ['::/96 by its IPv4 part', '::a00:1'], + ['::/96 by its IPv4 part', '::2'], ['a zone id', 'fe80::1%lo0'] ])('flags an address in %s (%s)', (_range, ip) => { expect(isSpecialPurposeAddress(ip)).toBe(true); @@ -64,9 +68,10 @@ describe('isSpecialPurposeAddress', () => { '172.32.0.0', '198.20.0.0', '223.255.255.255', - '::2', + '::808:808', '64:ff9b::808:808', '64:ff9b:2::1', + '100:0:0:2::1', '2001:200::1', '2003::1', '3fff:1000::1', diff --git a/packages/server/test/ext/events/webhookEngine.test.ts b/packages/server/test/ext/events/webhookEngine.test.ts index d88243894d..c08fcaad38 100644 --- a/packages/server/test/ext/events/webhookEngine.test.ts +++ b/packages/server/test/ext/events/webhookEngine.test.ts @@ -154,13 +154,75 @@ describe('endpoint verification', () => { [{ error: 'timeout' }, 'timeout'], [{ error: 'tls_error' }, 'tls_error'] ]; - it.each(failures)('fails verification with %o as %s', async (outcome, reason) => { + it.each(failures)('fails verification with %o as %s, and answers it again without a POST for 60 s', async (outcome, reason) => { const { engine, requests } = setup(() => outcome); await expect(engine.verify('u', HOOK_URL, SECRET, ID)).rejects.toMatchObject({ code: -32_027, data: { reason } }); + await vi.advanceTimersByTimeAsync(59_999); + await expect(engine.verify('u', HOOK_URL, SECRET, 'sub_2')).rejects.toMatchObject({ code: -32_027, data: { reason } }); + expect(requests).toHaveLength(1); + await vi.advanceTimersByTimeAsync(1); await expect(engine.verify('u', HOOK_URL, SECRET, ID)).rejects.toBeInstanceOf(EventsError); expect(requests).toHaveLength(2); }); + it('caches a failure per principal and url', async () => { + const { engine, requests } = setup(request => (request.url === HOOK_URL ? { error: 'connection_refused' } : echo(request))); + await expect(engine.verify('u', HOOK_URL, SECRET, ID)).rejects.toMatchObject({ data: { reason: 'connection_refused' } }); + await engine.verify('u', `${HOOK_URL}/other`, SECRET, 'sub_2'); + await expect(engine.verify('v', HOOK_URL, SECRET, 'sub_3')).rejects.toMatchObject({ data: { reason: 'connection_refused' } }); + expect(requests).toHaveLength(3); + }); + + it('still caches a success: later subscriptions of the pair send no POST and never reach the host limit', async () => { + const { engine, requests } = setup(echo); + await engine.verify('u', HOOK_URL, SECRET, ID); + for (let n = 2; n <= 20; n++) await engine.verify('u', HOOK_URL, SECRET, `sub_${n}`); + expect(requests).toHaveLength(1); + }); + + it('sends one verification POST to a host at a time, refusing another pair with resourceExhausted', async () => { + const answers: Array<() => void> = []; + const { engine, requests, until } = setup( + request => new Promise(resolve => answers.push(() => resolve(echo(request) as WebhookSendOutcome))) + ); + const first = engine.verify('u', HOOK_URL, SECRET, ID); + await until(1); + // The same pair waits for the handshake in flight; another pair to that host is refused; another host is not. + const samePair = engine.verify('u', HOOK_URL, SECRET, 'sub_2'); + const refused = await engine.verify('v', 'https://HOOKS.example.com/other', SECRET, 'sub_3').catch((error: unknown) => error); + expect(refused).toBeInstanceOf(EventsError); + expect(refused).toMatchObject({ code: -32_025, data: { limit: 'verification', retryAfterMs: expect.any(Number) } }); + const otherHost = engine.verify('v', 'https://elsewhere.example.com/mcp', SECRET, 'sub_4'); + await until(2); + expect(requests.map(request => request.url)).toEqual([HOOK_URL, 'https://elsewhere.example.com/mcp']); + + for (const answer of answers) answer(); + await expect(Promise.all([first, samePair, otherHost])).resolves.toEqual([undefined, undefined, undefined]); + expect(requests).toHaveLength(2); + const next = engine.verify('v', 'https://hooks.example.com/other', SECRET, 'sub_3'); + await until(3); + answers[2]!(); + await expect(next).resolves.toBeUndefined(); + }); + + it('sends at most 10 verification POSTs to a host per rolling 60 s', async () => { + const { engine, requests } = setup(echo); + for (let n = 1; n <= 10; n++) { + await engine.verify(`u${n}`, HOOK_URL, SECRET, `sub_${n}`); + await vi.advanceTimersByTimeAsync(1000); + } + await expect(engine.verify('u11', 'https://Hooks.Example.com/mcp', SECRET, 'sub_11')).rejects.toMatchObject({ + code: -32_025, + data: { limit: 'verification', retryAfterMs: 50_000 } + }); + await engine.verify('u11', 'https://elsewhere.example.com/mcp', SECRET, 'sub_12'); + expect(requests).toHaveLength(11); + + await vi.advanceTimersByTimeAsync(50_000); + await engine.verify('u11', HOOK_URL, SECRET, 'sub_11'); + expect(requests).toHaveLength(12); + }); + it('fails verification when a 404 echoes the challenge', async () => { const { engine } = setup(request => ({ status: 404, body: JSON.stringify({ challenge: bodyOf(request).challenge }) })); await expect(engine.verify('u', HOOK_URL, SECRET, ID)).rejects.toMatchObject({ data: { reason: 'challenge_failed' } }); @@ -758,6 +820,23 @@ describe('forget and clear', () => { expect(requests).toHaveLength(3); }); + it('clear() forgets failed verifications and the host limits', async () => { + let refuse = true; + const { engine, requests } = setup(request => (refuse ? { error: 'timeout' } : echo(request))); + await expect(engine.verify('u1', HOOK_URL, SECRET, 'sub_1')).rejects.toMatchObject({ data: { reason: 'timeout' } }); + for (let n = 2; n <= 10; n++) + await expect(engine.verify(`u${n}`, HOOK_URL, SECRET, `sub_${n}`)).rejects.toBeInstanceOf(EventsError); + await expect(engine.verify('u11', HOOK_URL, SECRET, 'sub_11')).rejects.toMatchObject({ code: -32_025 }); + await expect(engine.verify('u1', HOOK_URL, SECRET, 'sub_1')).rejects.toMatchObject({ code: -32_027 }); + expect(requests).toHaveLength(10); + + engine.clear(); + refuse = false; + await engine.verify('u1', HOOK_URL, SECRET, 'sub_1'); + await engine.verify('u11', HOOK_URL, SECRET, 'sub_11'); + expect(requests).toHaveLength(12); + }); + it('track() starts the watermark again for a subscription it already tracks', async () => { const { engine, record, until } = setup(); engine.deliver(record, occurrence('evt_1'), 'p1', 'p0'); diff --git a/packages/server/test/ext/events/webhookSubscriptions.test.ts b/packages/server/test/ext/events/webhookSubscriptions.test.ts index 7e70f83428..f3814f0a6a 100644 --- a/packages/server/test/ext/events/webhookSubscriptions.test.ts +++ b/packages/server/test/ext/events/webhookSubscriptions.test.ts @@ -392,7 +392,8 @@ describe('events/subscribe: creating', () => { const alice = client(events); errorOf(await alice.subscribe({ name, arguments: { a: 1 } })); expect(hook.state()).toMatchObject({ webhookSubscriptions: 0, webhookExpiryTimers: 0 }); - subscribed(await alice.subscribe({ name, arguments: { a: 2 } })); + // A failed verification is remembered for its principal and url, so that retry goes to another url. + subscribed(await alice.subscribe({ name, arguments: { a: 2 }, url: failure === 'verification' ? OTHER_HOOK : HOOK })); expect(hook.state()).toMatchObject({ webhookExpiryTimers: 1 }); } ); @@ -723,6 +724,25 @@ describe('fan-out', () => { [high.id, 'direct', { n: 10 }] ]); }); + + it('drops a transform output that fails payloadSchema and reports it', async () => { + const onerror = vi.fn(); + const { events, post } = replica({ onerror }); + const handle = events.registerEvent('e', { + emitOnly: true, + payloadSchema: P, + transform: (_ctx, event) => (event.eventId === 'bad' ? { ...event, data: { n: 'x' } as unknown as { n: number } } : event) + }); + subscribed(await client(events).subscribe()); + await handle.emit({ eventId: 'bad', data: { n: 1 } }); + await handle.emit({ eventId: 'good', data: { n: 2 } }); + await post.until(2); + await settle(); + expect(post.deliveries().map(request => bodyOf(request).eventId)).toEqual(['good']); + expect(onerror).toHaveBeenCalledWith( + expect.objectContaining({ message: expect.stringMatching(/transform output does not match/) }) + ); + }); }); describe('check-kind webhook subscriptions', () => { @@ -760,6 +780,30 @@ describe('check-kind webhook subscriptions', () => { expect(post.requests).toHaveLength(2); }); + it('parses the next check of a watched subscription with the payloadSchema of an update()', async () => { + const labelled = { eventId: 'evt_1', data: { n: 1, label: '#1' } as { n: number } }; + const check = vi + .fn() + .mockReturnValueOnce({ events: [], cursor: 'c0' }) + .mockReturnValueOnce({ events: [labelled], cursor: 'c1' }) + .mockReturnValueOnce({ events: [{ ...labelled, eventId: 'evt_2' }], cursor: 'c2' }) + .mockReturnValue({ events: [], cursor: 'c2' }); + const { events, post } = replica(); + const handle = events.registerEvent('t', { payloadSchema: P, check }); + subscribed(await client(events).subscribe({ name: 't' })); + await vi.advanceTimersByTimeAsync(5000); + await post.until(2); + await settle(); + expect(bodyOf(post.requests[1]!)).toMatchObject({ eventId: 'evt_1' }); + // The registered schema strips the unknown `label`. + expect(bodyOf(post.requests[1]!)['data']).toEqual({ n: 1 }); + + handle.update({ payloadSchema: z.object({ n: z.number(), label: z.string().optional() }) }); + await vi.advanceTimersByTimeAsync(5000); + await post.until(3); + expect(bodyOf(post.requests[2]!)['data']).toEqual({ n: 1, label: '#1' }); + }); + it('replays from a cursor on create, and sends a gap envelope for a gap between refreshes', async () => { const check = vi.fn((_ctx, _args, cursor) => { if (cursor === 'c0') return { events: [{ eventId: 'evt_1', data: { n: 1 } }], cursor: 'c1' }; diff --git a/test/conformance/src/events.ts b/test/conformance/src/events.ts index a1af46a05e..370e0b8bb3 100644 --- a/test/conformance/src/events.ts +++ b/test/conformance/src/events.ts @@ -140,6 +140,7 @@ const pulse = conformanceEvents.registerEvent(PULSE, { return take(gapNext, ctx) ? { events, cursor: null, truncated: true } : { events, cursor: null }; }, onUnsubscribe: ctx => void beatSeen.delete(ctx.subscriptionId), + // Poll would work; the suite's sep-3415-poll-mode-unsupported needs one type without it, and this is that type. delivery: { poll: false } }); diff --git a/test/integration/test/events/eventsEndToEnd.test.ts b/test/integration/test/events/eventsEndToEnd.test.ts index fabac84d7d..7c100d5f6e 100644 --- a/test/integration/test/events/eventsEndToEnd.test.ts +++ b/test/integration/test/events/eventsEndToEnd.test.ts @@ -697,7 +697,9 @@ describe('webhook delivery over http', () => { }); it('serves one subscription from two replicas sharing a store: refresh, rotation, emit and unsubscribe on the second', async () => { - const events = new EventsClientExtension({ ...CLIENT_OPTIONS, webhook: { url: HOOK_URL, secretProvider: () => SECRET } }); + // One secret per subscription, as the client requires: SECRET for the one under test, another for the witness. + const secrets = [SECRET, `whsec_${btoa('c'.repeat(32))}`]; + const events = new EventsClientExtension({ ...CLIENT_OPTIONS, webhook: { url: HOOK_URL, secretProvider: () => secrets.shift()! } }); const posts: Post[] = []; const store = new InMemoryWebhookSubscriptionStore(); // A 2 s grant: the client refreshes after 1.5 s. From 8d3ebd5ee614503a66e3879f898b038022e87f8e Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Thu, 19 Nov 2026 10:26:10 +0200 Subject: [PATCH 33/37] feat(events): install Events through the extensions option, drop attach EventsExtension and EventsClientExtension implement #2820's ServerExtension and ClientExtension: setup(ctx) registers the events/* handlers through ctx.setRequestHandler and keeps the era gate, the events/stream streaming mark and the Mcp-Param header source. attach() is gone, with its connect check, one-per-server set and idempotence, which the extensions mechanism covers (duplicate id) or makes impossible (setup runs at construction). Call sites, docs, guide snippets, the changeset and typescript:events:attach:rules (now typescript:events:extensions:rules) follow. --- .changeset/events-extension.md | 6 +- docs/clients/events.md | 7 +- docs/servers/events.md | 14 ++-- examples/events/client.ts | 8 ++- examples/events/server.ts | 3 +- examples/guides/clients/events.examples.ts | 14 ++-- examples/guides/servers/events.examples.ts | 35 ++++------ packages/client/src/ext/events/extension.ts | 33 ++++++---- .../client/test/ext/events/extension.test.ts | 17 ++--- packages/client/test/ext/events/scripted.ts | 7 +- packages/server/src/ext/events/extension.ts | 63 +++++++----------- packages/server/src/ext/events/validation.ts | 2 +- packages/server/test/ext/events/harness.ts | 5 +- .../test/ext/events/registration.test.ts | 42 +++++------- test/conformance/src/events.ts | 8 +-- test/conformance/src/everythingClient.ts | 6 +- test/conformance/src/everythingServer.ts | 7 +- test/e2e/requirements.ts | 5 +- test/e2e/scenarios/events.test.ts | 64 +++++++++---------- .../test/__fixtures__/eventsStdioServer.ts | 19 +++--- .../test/events/eventsEndToEnd.test.ts | 50 ++++++--------- .../test/events/eventsWire.test.ts | 12 ++-- 22 files changed, 182 insertions(+), 245 deletions(-) diff --git a/.changeset/events-extension.md b/.changeset/events-extension.md index 9410c43a4a..7cb1a5e726 100644 --- a/.changeset/events-extension.md +++ b/.changeset/events-extension.md @@ -9,11 +9,11 @@ author: @KKonstantinov Add the Events extension (SEP-3415), reachable through new `ext/events` subpaths; package root exports are unchanged. The whole Events API is experimental and may change in a minor release. -- `@modelcontextprotocol/server/ext/events`: `EventsExtension`, whose `registerEvent(name, definition)` takes a `check` function or `emitOnly: true` and returns a handle with `update()`, `remove()` and `terminate()` (and `emit()` for emit-only types), and whose `attach(server)` serves `events/list`, `events/poll`, `events/stream`, `events/subscribe` and `events/unsubscribe`; `InMemoryWebhookSubscriptionStore`; `EventsError`; the types `EventContext`, `CheckContext`, `EventInput`, `EventResult`, `EventDefinition`, `CheckEventDefinition`, `EmitOnlyEventDefinition`, `EventHandle`, `EmitOnlyEventHandle`, `EventsOptions`, `EventsErrorKind`, `WebhookSender`, `WebhookSendRequest`, `WebhookSendOutcome`, `WebhookSubscriptionStore` and `WebhookSubscriptionRecord`; and the wire types and constants. Push streams under every `createMcpHandler` `responseMode`, `'json'` included. Webhook delivery is on when `webhookTtlMs`, `webhookSender` and `getPrincipal` are all set; `trustedOrigins` exempts exact origins from the `https` and private-address rules, for development. +- `@modelcontextprotocol/server/ext/events`: `EventsExtension`, whose `registerEvent(name, definition)` takes a `check` function or `emitOnly: true` and returns a handle with `update()`, `remove()` and `terminate()` (and `emit()` for emit-only types), and which serves `events/list`, `events/poll`, `events/stream`, `events/subscribe` and `events/unsubscribe` on every `McpServer` constructed with it in the `extensions` option; `InMemoryWebhookSubscriptionStore`; `EventsError`; the types `EventContext`, `CheckContext`, `EventInput`, `EventResult`, `EventDefinition`, `CheckEventDefinition`, `EmitOnlyEventDefinition`, `EventHandle`, `EmitOnlyEventHandle`, `EventsOptions`, `EventsErrorKind`, `WebhookSender`, `WebhookSendRequest`, `WebhookSendOutcome`, `WebhookSubscriptionStore` and `WebhookSubscriptionRecord`; and the wire types and constants. Push streams under every `createMcpHandler` `responseMode`, `'json'` included. Webhook delivery is on when `webhookTtlMs`, `webhookSender` and `getPrincipal` are all set; `trustedOrigins` exempts exact origins from the `https` and private-address rules, for development. - `@modelcontextprotocol/server/ext/events/node`: `nodeWebhookSender()`, a `WebhookSender` for Node.js that requires `https`, resolves the host at every send, refuses IANA special-purpose addresses, follows no redirects and gives up after 5 seconds. -- `@modelcontextprotocol/client/ext/events`: `EventsClientExtension` with `list()`, `subscribe({ name, arguments, delivery?, cursor?, maxAgeMs?, onGap? })` and `createWebhookHandler()`; `NoCompatibleDeliveryModeError`; `EventsError`; the types `EventsClientOptions`, `SubscribeOptions`, `EventSubscription` (an async iterable with `cursor`, `deliveryMode`, `deliveryStatus` and `cancel()`) and `EventsErrorKind`; and the wire types and constants. A subscription prefers webhook (when configured), then push, then poll. +- `@modelcontextprotocol/client/ext/events`: `EventsClientExtension`, passed in one `Client`'s `extensions` option, with `list()`, `subscribe({ name, arguments, delivery?, cursor?, maxAgeMs?, onGap? })` and `createWebhookHandler()`; `NoCompatibleDeliveryModeError`; `EventsError`; the types `EventsClientOptions`, `SubscribeOptions`, `EventSubscription` (an async iterable with `cursor`, `deliveryMode`, `deliveryStatus` and `cancel()`) and `EventsErrorKind`; and the wire types and constants. A subscription prefers webhook (when configured), then push, then poll. - `@modelcontextprotocol/core/ext/events`: the wire constants, a Zod schema and inferred type for every Events wire shape, and `EventsCapabilitySchema`, `EventsCapability` and `eventsCapabilityOf`. -Clients now send `Mcp-Name` on `events/poll`, `events/stream`, `events/subscribe` and `events/unsubscribe`, and `createMcpHandler` requires it on 2026-07-28 (`400` / `-32020` when it is missing or does not match `params.name`), whether or not the server attaches Events. +Clients now send `Mcp-Name` on `events/poll`, `events/stream`, `events/subscribe` and `events/unsubscribe`, and `createMcpHandler` requires it on 2026-07-28 (`400` / `-32020` when it is missing or does not match `params.name`), whether or not the server serves Events. Events is served and used on protocol 2026-07-28 only. Not included: `notifications/events/list_changed`, and webhook grants without expiry (`refreshBefore: null`). With several replicas sharing a `WebhookSubscriptionStore`, `emit()` reaches push streams and the poll buffer only on the emitting process, and the `check` loop of a webhook subscription may run on more than one replica. diff --git a/docs/clients/events.md b/docs/clients/events.md index 0c36600e88..1842db12eb 100644 --- a/docs/clients/events.md +++ b/docs/clients/events.md @@ -14,9 +14,8 @@ Events (SEP-3415) is an accepted MCP extension. Its SDK API is new and may chang import { Client } from '@modelcontextprotocol/client'; import { EventsClientExtension } from '@modelcontextprotocol/client/ext/events'; -const client = new Client({ name: 'ops-console', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } }); const events = new EventsClientExtension(); -events.attach(client); +const client = new Client({ name: 'ops-console', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' }, extensions: [events] }); await client.connect(transport); const subscription = await events.subscribe({ name: 'ticket.updated', arguments: { queue: 'billing' } }); @@ -32,7 +31,7 @@ When a ticket in the billing queue opens, it prints: ticket.updated { ticketId: 'T-7', status: 'open' } ``` -Attach the extension before `connect()`. `subscribe()` resolves once its first exchange with the server succeeds, and the subscription starts from now unless you pass a `cursor`. `list()` returns the server's event types with their schemas and delivery modes. +Pass the extension in the client's `extensions` option: the client calls its `setup` while it is constructed, which ties the extension to that one client. `subscribe()` resolves once its first exchange with the server succeeds, and the subscription starts from now unless you pass a `cursor`. `list()` returns the server's event types with their schemas and delivery modes. Each subscription takes the first delivery mode the event type offers out of webhook (when you configure it), push and poll; `delivery` forces one, and `subscription.deliveryMode` says which it got. The loop is the same in every mode, drops a repeated `eventId`, and leaving it cancels the subscription. @@ -114,7 +113,7 @@ invalidParams ## Recap -- `new EventsClientExtension()`, `attach(client)` before `connect()`, then `subscribe({ name, arguments })` and `for await`. +- `new EventsClientExtension()` in the client's `extensions`, then `connect()`, `subscribe({ name, arguments })` and `for await`. - The loop is the same in every mode, and leaving it cancels the subscription. - `subscription.cursor` is safe to save; pass it back as `cursor` to resume, and expect the last event again. - `webhook: { url }`, with `createWebhookHandler()` served at that URL, turns on webhook delivery. diff --git a/docs/servers/events.md b/docs/servers/events.md index a2483821fa..a8bfe5fcae 100644 --- a/docs/servers/events.md +++ b/docs/servers/events.md @@ -77,19 +77,15 @@ Poll clients read emit-only events from an in-memory buffer (`emitBuffer`, by de ## Serve the event types from every server -`attach` serves the event types on a server; one `EventsExtension` serves every server you attach it to. +Pass the extension in each server's `extensions` option; one `EventsExtension` serves every server constructed with it. -```ts source="../../examples/guides/servers/events.examples.ts#attach" +```ts source="../../examples/guides/servers/events.examples.ts#extensions" import { createMcpHandler, McpServer } from '@modelcontextprotocol/server'; -const handler = createMcpHandler(() => { - const mcp = new McpServer({ name: 'helpdesk', version: '1.0.0' }); - events.attach(mcp); - return mcp; -}); +const handler = createMcpHandler(() => new McpServer({ name: 'helpdesk', version: '1.0.0' }, { extensions: [events] })); ``` -Attach before connecting the server. Push streams under every `responseMode`, `'json'` included, as `subscriptions/listen` does. +While it is constructed, each server advertises the extension and calls its `setup`, which registers the `events/*` methods (see [Extensions](../advanced/extensions.md)). Push streams under every `responseMode`, `'json'` included, as `subscriptions/listen` does. A push stream carries no SSE comment keepalive. The server sends `notifications/events/heartbeat` whenever the stream has been quiet for the granted interval, `heartbeatMs` (30 seconds by default) or a shorter one the client asks for, and the SDK's client reconnects after three intervals of silence. Keep `heartbeatMs` below your load balancer's idle timeout. @@ -213,7 +209,7 @@ An `EventsError` thrown from `onUnsubscribe`, `match` or `transform` only reache - `registerEvent(name, { check })` reads events from an upstream that can answer what happened since a cursor, and clients resume from their cursor. - `emitOnly: true` and the handle's `emit()` publish events as they happen; poll reads them from a bounded in-memory buffer. -- One `EventsExtension` serves every server it is attached to by poll and push, and by webhook once configured, on 2026-07-28 only; push streams under every `responseMode`. +- One `EventsExtension` serves every server constructed with it in `extensions` by poll and push, and by webhook once configured, on 2026-07-28 only; push streams under every `responseMode`. - Webhook delivery needs `webhookTtlMs`, `webhookSender` and `getPrincipal`; `trustedOrigins` is for development only. - A shared `WebhookSubscriptionStore` holds webhook secrets and lets replicas share webhook subscriptions, while push streams and the poll buffer stay on one process. - `terminate` ends subscriptions with an `EventsError`, such as `forbidden` when access is revoked. diff --git a/examples/events/client.ts b/examples/events/client.ts index b79e1e5fe6..6a0222853d 100644 --- a/examples/events/client.ts +++ b/examples/events/client.ts @@ -22,11 +22,13 @@ const RECEIVER_PORT = Number(process.env.EVENTS_RECEIVER_PORT ?? '8599'); const { transport, url } = parseExampleArgs(); const http = transport === 'http'; -// Events is a 2026-07-28 extension: negotiate the modern revision. -const client = new Client({ name: 'events-example-client', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } }); // Webhook delivery needs a URL the server can POST to: this process, on the HTTP leg. const events = new EventsClientExtension(http ? { webhook: { url: `http://127.0.0.1:${RECEIVER_PORT}/events` } } : {}); -events.attach(client); +// Events is a 2026-07-28 extension: negotiate the modern revision. +const client = new Client( + { name: 'events-example-client', version: '1.0.0' }, + { versionNegotiation: { mode: 'auto' }, extensions: [events] } +); // The receiver is up before any subscribe, since the server verifies the endpoint first. let receiver: ServerType | undefined; diff --git a/examples/events/server.ts b/examples/events/server.ts index 041aae0997..a21234ebc1 100644 --- a/examples/events/server.ts +++ b/examples/events/server.ts @@ -68,12 +68,11 @@ let ticks = 0; setInterval(() => void tick.emit({ data: { tick: ++ticks } }), 200).unref(); function buildServer(): McpServer { - const mcp = new McpServer({ name: 'events-example', version: '1.0.0' }); + const mcp = new McpServer({ name: 'events-example', version: '1.0.0' }, { extensions: [events] }); mcp.registerTool('increment', { description: 'Add one to the counter', inputSchema: z.object({}) }, () => { count += 1; return { content: [{ type: 'text', text: String(count) }] }; }); - events.attach(mcp); return mcp; } diff --git a/examples/guides/clients/events.examples.ts b/examples/guides/clients/events.examples.ts index 16d8b5fe39..346d62bfba 100644 --- a/examples/guides/clients/events.examples.ts +++ b/examples/guides/clients/events.examples.ts @@ -50,11 +50,7 @@ const tickets = helpdesk.registerEvent('ticket.updated', { setTimeout(() => changes.push({ changeId: 'c1', queue: 'billing', ticketId: 'T-7', status: 'open' }), 0); } }); -const handler = createMcpHandler(() => { - const mcp = new McpServer({ name: 'helpdesk', version: '1.0.0' }); - helpdesk.attach(mcp); - return mcp; -}); +const handler = createMcpHandler(() => new McpServer({ name: 'helpdesk', version: '1.0.0' }, { extensions: [helpdesk] })); const inProcess = () => new StreamableHTTPClientTransport(new URL('http://localhost/mcp'), { fetch: (url, init) => handler.fetch(new Request(url, init)) }); const transport = inProcess(); @@ -71,9 +67,8 @@ console.log = (...args: unknown[]) => { import { Client } from '@modelcontextprotocol/client'; import { EventsClientExtension } from '@modelcontextprotocol/client/ext/events'; -const client = new Client({ name: 'ops-console', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } }); const events = new EventsClientExtension(); -events.attach(client); +const client = new Client({ name: 'ops-console', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' }, extensions: [events] }); await client.connect(transport); const subscription = await events.subscribe({ name: 'ticket.updated', arguments: { queue: 'billing' } }); @@ -138,9 +133,8 @@ claim( ); claim(events.supported && firstMode === 'push', 'without a webhook URL, a subscription picks push where the server offers it'); -// The webhook client: attached and connected like the first one, its subscriptions take webhook. -const hookedClient = new Client({ name: 'ops-console', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } }); -hooked.attach(hookedClient); +// The webhook client: set up and connected like the first one, its subscriptions take webhook. +const hookedClient = new Client({ name: 'ops-console', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' }, extensions: [hooked] }); await hookedClient.connect(inProcess()); receive = async request => app.fetch(request); const hook = await hooked.subscribe({ name: 'ticket.updated', arguments: { queue: 'billing' }, cursor: '0' }); diff --git a/examples/guides/servers/events.examples.ts b/examples/guides/servers/events.examples.ts index c9a4052b1d..ca9f16be03 100644 --- a/examples/guides/servers/events.examples.ts +++ b/examples/guides/servers/events.examples.ts @@ -60,15 +60,11 @@ const incidents = events.registerEvent('incident.created', { await incidents.emit({ eventId: 'INC-7', data: { incidentId: 'INC-7', title: 'Checkout is down', severity: 'P1' } }); //#endregion registerEvent_emitOnly -//#region attach +//#region extensions import { createMcpHandler, McpServer } from '@modelcontextprotocol/server'; -const handler = createMcpHandler(() => { - const mcp = new McpServer({ name: 'helpdesk', version: '1.0.0' }); - events.attach(mcp); - return mcp; -}); -//#endregion attach +const handler = createMcpHandler(() => new McpServer({ name: 'helpdesk', version: '1.0.0' }, { extensions: [events] })); +//#endregion extensions // --------------------------------------------------------------------------- // Harness (not shown on the page): clients that talk to a handler in process. @@ -87,9 +83,11 @@ async function connect( target: McpHttpHandler, options: EventsClientOptions = {} ): Promise<{ client: Client; subscriber: EventsClientExtension }> { - const client = new Client({ name: 'events-docs-check', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } }); const subscriber = new EventsClientExtension(options); - subscriber.attach(client); + const client = new Client( + { name: 'events-docs-check', version: '1.0.0' }, + { versionNegotiation: { mode: 'auto' }, extensions: [subscriber] } + ); await client.connect( new StreamableHTTPClientTransport(new URL('http://localhost/mcp'), { fetch: (url, init) => target.fetch(new Request(url, init)) }) ); @@ -132,14 +130,9 @@ for (const delivery of ['push', 'poll'] as const) { } // Push still streams when the handler answers everything else as plain JSON. -const jsonOnly = createMcpHandler( - () => { - const mcp = new McpServer({ name: 'helpdesk', version: '1.0.0' }); - events.attach(mcp); - return mcp; - }, - { responseMode: 'json' } -); +const jsonOnly = createMcpHandler(() => new McpServer({ name: 'helpdesk', version: '1.0.0' }, { extensions: [events] }), { + responseMode: 'json' +}); const plain = await connect(jsonOnly); const streamed = await plain.subscriber.subscribe({ name: 'ticket.updated', arguments: { queue: 'billing' }, cursor: '0' }); claim(streamed.deliveryMode === 'push', "push is chosen under responseMode: 'json'"); @@ -287,11 +280,7 @@ function replica() { } const [first, second] = [replica(), replica()]; const handlerOf = (extension: EventsExtension) => - createMcpHandler(() => { - const mcp = new McpServer({ name: 'helpdesk', version: '1.0.0' }); - extension.attach(mcp); - return mcp; - }); + createMcpHandler(() => new McpServer({ name: 'helpdesk', version: '1.0.0' }, { extensions: [extension] })); const firstHandler = handlerOf(first.extension); const hooked = await connect(firstHandler, { webhook: { url: 'https://hooks.example.com/mcp/events' } }); receive = hooked.subscriber.createWebhookHandler(); @@ -309,6 +298,6 @@ claim( ); claim(database.size === 0, 'cancel must delete the record from the shared store'); -for (const extension of [webhookEvents, replicated]) extension.attach(new McpServer({ name: 'docs-check', version: '1.0.0' })); +for (const extension of [webhookEvents, replicated]) new McpServer({ name: 'docs-check', version: '1.0.0' }, { extensions: [extension] }); for (const { client } of [helpdesk, plain, hooked]) await client.close(); for (const target of [handler, jsonOnly, firstHandler]) await target.close(); diff --git a/packages/client/src/ext/events/extension.ts b/packages/client/src/ext/events/extension.ts index 7e130365f1..4d844fd813 100644 --- a/packages/client/src/ext/events/extension.ts +++ b/packages/client/src/ext/events/extension.ts @@ -3,7 +3,7 @@ import { EVENTS_EXTENSION_ID, EVENTS_LIST_METHOD, eventsCapabilityOf } from '@mo import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal/public'; -import type { Client } from '../../client/client'; +import type { ClientExtension, ClientExtensionContext } from '../../client/extension'; import { NoCompatibleDeliveryModeError } from './errors'; import { PollDriver } from './poll'; import { PushDriver } from './push'; @@ -65,12 +65,13 @@ export function selectDeliveryMode( * types and subscribes to them. Each subscription picks a delivery mode, * preferring webhook (when configured), then push, then poll, and runs it, * deduplicating by `eventId` and tracking the cursor. Events is used only on - * protocol revision `2026-07-28` and later. + * protocol revision `2026-07-28` and later. Pass it in one client's + * `extensions` option. * * @example * ```ts * const events = new EventsClientExtension(); - * events.attach(client); + * const client = new Client({ name: 'ops-console', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' }, extensions: [events] }); * await client.connect(transport); * const subscription = await events.subscribe({ name: 'incident.created', arguments: { severity: 'P1' } }); * for await (const event of subscription) { @@ -82,7 +83,7 @@ export function selectDeliveryMode( * * @experimental */ -export class EventsClientExtension { +export class EventsClientExtension implements ClientExtension { /** The extension identifier the client declares. */ readonly id = EVENTS_EXTENSION_ID; readonly #options: EventsClientOptions; @@ -103,17 +104,17 @@ export class EventsClientExtension { } /** - * Declares the extension in `client`'s capabilities. Call it before - * `client.connect()`; one client per instance, and attaching to the same - * client again does nothing. + * Binds this instance to the client that lists it in `extensions`: the + * client calls it once, while it is constructed, and declares the + * extension as `{}`. One client per instance. * - * @throws {Error} after `client` connected, or when already attached to another client. + * @throws {Error} when another client already holds this instance, which fails the new client's constructor. */ - attach(client: Client): void { - if (this.#connection?.client === client) return; - if (this.#connection !== undefined) throw new Error('This EventsClientExtension is already attached to another client'); - client.registerCapabilities({ extensions: { [EVENTS_EXTENSION_ID]: {} } }); - this.#connection = new EventsConnection(client); + setup(ctx: ClientExtensionContext): void { + if (this.#connection !== undefined) { + throw new Error("This EventsClientExtension is already in another client; pass a new one in each client's extensions option"); + } + this.#connection = new EventsConnection(ctx.client); } /** The server advertised the extension and the connection is on protocol `2026-07-28` or later. `false` before connect. */ @@ -216,7 +217,11 @@ export class EventsClientExtension { #require(method: string): EventsConnection { const connection = this.#connection; - if (connection === undefined) throw new Error(`Call attach(client) before ${method}`); + if (connection === undefined) { + throw new Error( + `No client was constructed with this EventsClientExtension; pass it in the client's extensions option before ${method}` + ); + } if (!this.supported) { throw new SdkError( SdkErrorCode.CapabilityNotSupported, diff --git a/packages/client/test/ext/events/extension.test.ts b/packages/client/test/ext/events/extension.test.ts index fc3a9f1ff6..68e4dadf80 100644 --- a/packages/client/test/ext/events/extension.test.ts +++ b/packages/client/test/ext/events/extension.test.ts @@ -7,7 +7,7 @@ import { selectDeliveryMode } from '../../../src/ext/events/extension'; import type { EventSubscription } from '../../../src/ext/events/index'; import { EventsClientExtension, EventsError, NoCompatibleDeliveryModeError } from '../../../src/ext/events/index'; import type { Handler } from './scripted'; -import { callsTo, connectEvents, descriptor, LEGACY, listing, occurrence, quietPoll, RpcError, script, scriptedClient } from './scripted'; +import { callsTo, connectEvents, descriptor, LEGACY, listing, occurrence, quietPoll, RpcError, script } from './scripted'; const UNSUPPORTED = 'Server does not support the io.modelcontextprotocol/events extension (required for events/list)'; @@ -43,14 +43,15 @@ describe('EventsClientExtension gating', () => { expect(meta['io.modelcontextprotocol/clientCapabilities']!.extensions[EVENTS_EXTENSION_ID]).toEqual({}); }); - it('throws when attached after connect or to a second client', async () => { - const { client } = await scriptedClient({}); - expect(() => new EventsClientExtension().attach(client)).toThrow('Cannot register capabilities after connecting to transport'); + it('serves one client, and refuses calls before a client is constructed with it', async () => { const events = new EventsClientExtension(); - const first = new Client({ name: 'a', version: '1.0.0' }); - events.attach(first); - expect(() => events.attach(first)).not.toThrow(); - expect(() => events.attach(new Client({ name: 'b', version: '1.0.0' }))).toThrow(Error); + await expect(events.list()).rejects.toThrow( + "No client was constructed with this EventsClientExtension; pass it in the client's extensions option before events/list" + ); + new Client({ name: 'a', version: '1.0.0' }, { extensions: [events] }); + expect(() => new Client({ name: 'b', version: '1.0.0' }, { extensions: [events] })).toThrow( + "This EventsClientExtension is already in another client; pass a new one in each client's extensions option" + ); }); it('rejects a pollIntervalFloorMs that is not a positive number', () => { diff --git a/packages/client/test/ext/events/scripted.ts b/packages/client/test/ext/events/scripted.ts index 600c7a02e5..7ea017871b 100644 --- a/packages/client/test/ext/events/scripted.ts +++ b/packages/client/test/ext/events/scripted.ts @@ -46,8 +46,6 @@ export interface ScriptedOptions { capabilities?: ServerCapabilities; revision?: typeof MODERN | typeof LEGACY; clientOptions?: ClientOptions; - /** Runs on the client before it connects. */ - beforeConnect?: (client: Client) => void; } /** A scripted client, with the scripted server's side of its connection. */ @@ -139,7 +137,6 @@ export async function scriptedClient(handlers: Record, options: { name: 'events-test-client', version: '1.0.0' }, revision === MODERN ? { versionNegotiation: { mode: { pin: MODERN } }, ...options.clientOptions } : options.clientOptions ); - options.beforeConnect?.(client); await client.connect(await link()); return { client, @@ -150,13 +147,13 @@ export async function scriptedClient(handlers: Record, options: }; } -/** An `EventsClientExtension` attached to a scripted client before it connects. */ +/** An `EventsClientExtension` in the `extensions` of a scripted client. */ export async function connectEvents( handlers: Record, options: ScriptedOptions & { events?: EventsClientOptions } = {} ): Promise { const events = new EventsClientExtension(options.events); - const connected = await scriptedClient(handlers, { ...options, beforeConnect: client => events.attach(client) }); + const connected = await scriptedClient(handlers, { ...options, clientOptions: { ...options.clientOptions, extensions: [events] } }); return { events, ...connected }; } diff --git a/packages/server/src/ext/events/extension.ts b/packages/server/src/ext/events/extension.ts index c9cd69626e..28c9a68f0f 100644 --- a/packages/server/src/ext/events/extension.ts +++ b/packages/server/src/ext/events/extension.ts @@ -16,7 +16,7 @@ import type { ServerContext, StandardSchemaWithJSON } from '@modelcontextprotoco import { scanXMcpHeaderDeclarations } from '@modelcontextprotocol/core-internal'; import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; -import type { McpServer } from '../../server/mcp'; +import type { ServerExtension, ServerExtensionContext } from '../../server/extension'; import { markModernOnlyExtension } from '../../server/modernOnlyExtensions'; import { registerParamHeaderSource } from '../../server/paramHeaderSources'; import type { Server } from '../../server/server'; @@ -48,8 +48,6 @@ export type DefaultSchema = StandardSchemaWithJSON>; // The `events/*` requests that name an event type in `params.name`. const NAMED_EVENT_METHODS = [EVENTS_POLL_METHOD, EVENTS_STREAM_METHOD, EVENTS_SUBSCRIBE_METHOD, EVENTS_UNSUBSCRIBE_METHOD]; -const EVENTS_METHODS = [EVENTS_LIST_METHOD, ...NAMED_EVENT_METHODS]; - const NUMERIC_OPTIONS = ['webhookTtlMs', 'pollSubscriptionTtlMs', 'heartbeatMs', 'checkIntervalMs', 'defaultNextPollMs'] as const; const DEFAULT_EMIT_BUFFER_MAX_AGE_MS = 600_000; @@ -61,11 +59,6 @@ const DEFAULT_CHECK_INTERVAL_MS = 5000; // As `createMcpHandler` bounds `subscriptions/listen` streams. const DEFAULT_MAX_SUBSCRIPTIONS = 1024; -// Servers with an events extension attached: one per server, as SEP-3371 rejects a duplicate extension identifier. -const eventsServers = new WeakSet(); - -const ONE_PER_SERVER = 'another events extension is already attached to this server; attach one per server'; - function assertPositive(name: string, value: unknown): void { if (value !== undefined && !(typeof value === 'number' && Number.isFinite(value) && value > 0)) { throw new TypeError(`${name} must be a positive finite number (got ${String(value)})`); @@ -116,20 +109,19 @@ function defaultOnerror(error: Error): void { /** * The MCP Events extension (SEP-3415). Register event types with - * {@linkcode EventsExtension.registerEvent}, then call - * {@linkcode EventsExtension.attach} on each server before connecting it; one - * instance serves any number of servers. Events is served only on protocol + * {@linkcode EventsExtension.registerEvent}, and pass the extension in each + * server's `extensions` option (`new McpServer(info, { extensions: [events] })`); + * one instance serves any number of servers. Events is served only on protocol * revision `2026-07-28` and later. * * Experimental: Events (SEP-3415) is new; this API may change in a minor release. * * @experimental */ -export class EventsExtension { +export class EventsExtension implements ServerExtension { readonly id = EVENTS_EXTENSION_ID; readonly #registry = new EventRegistry(); readonly #sources: SubscriptionSource[] = []; - readonly #attached = new WeakSet(); readonly #trustedOrigins: Set; readonly #webhookEnabled: boolean; readonly #onerror: (error: Error) => void; @@ -237,47 +229,36 @@ export class EventsExtension { } /** - * Serves these event types on `mcp`: registers the `events/*` methods, - * then declares the capability. Must run before connecting. Calling it - * again for the same server does nothing. One events extension per - * server: attaching another one throws and leaves the server as it was, - * as does attaching to a server that already handles one of the - * `events/*` methods. A legacy `initialize` result does not advertise - * Events, and a server serving an earlier revision than `2026-07-28` - * answers `events/*` requests with `-32601`. + * Serves these event types on a server that lists this extension in + * `extensions`: the server calls it once, while it is constructed, and + * advertises the extension as `{}`. A legacy `initialize` result does not + * advertise Events, and a server serving an earlier revision than + * `2026-07-28` answers `events/*` requests with `-32601`. */ - attach(mcp: McpServer): void { - if (this.#attached.has(mcp)) return; - if (mcp.isConnected()) throw new Error('attach events before connecting the server'); - if (eventsServers.has(mcp)) throw new Error(ONE_PER_SERVER); - const server = mcp.server; - // Check before changing anything; declare the capability last, so a server never advertises events it does not serve. - for (const method of EVENTS_METHODS) server.assertCanSetRequestHandler(method); - server.setRequestHandler(EVENTS_LIST_METHOD, { params: ListEventsRequestParamsSchema }, () => + setup(ctx: ServerExtensionContext): void { + const server = ctx.mcp.server; + ctx.setRequestHandler(EVENTS_LIST_METHOD, { params: ListEventsRequestParamsSchema }, () => this.#modernOnly(server, () => this.#list()) ); - server.setRequestHandler(EVENTS_POLL_METHOD, { params: PollEventsRequestParamsSchema }, (params, ctx) => - this.#modernOnly(server, () => this.#poll.handlePoll(params, ctx)) + ctx.setRequestHandler(EVENTS_POLL_METHOD, { params: PollEventsRequestParamsSchema }, (params, requestCtx) => + this.#modernOnly(server, () => this.#poll.handlePoll(params, requestCtx)) ); - server.setRequestHandler(EVENTS_STREAM_METHOD, { params: StreamEventsRequestParamsSchema }, (params, ctx) => - this.#modernOnly(server, () => this.#push.open(params, ctx)) + ctx.setRequestHandler(EVENTS_STREAM_METHOD, { params: StreamEventsRequestParamsSchema }, (params, requestCtx) => + this.#modernOnly(server, () => this.#push.open(params, requestCtx)) ); - server.setRequestHandler(EVENTS_SUBSCRIBE_METHOD, { params: SubscribeEventsRequestParamsSchema }, (params, ctx) => + ctx.setRequestHandler(EVENTS_SUBSCRIBE_METHOD, { params: SubscribeEventsRequestParamsSchema }, (params, requestCtx) => this.#modernOnly(server, () => - this.#webhooks === undefined ? this.#refuseWebhook(params, ctx) : this.#webhooks.subscribe(params, ctx) + this.#webhooks === undefined ? this.#refuseWebhook(params, requestCtx) : this.#webhooks.subscribe(params, requestCtx) ) ); - server.setRequestHandler(EVENTS_UNSUBSCRIBE_METHOD, { params: UnsubscribeEventsRequestParamsSchema }, (params, ctx) => + ctx.setRequestHandler(EVENTS_UNSUBSCRIBE_METHOD, { params: UnsubscribeEventsRequestParamsSchema }, (params, requestCtx) => this.#modernOnly(server, () => - this.#webhooks === undefined ? this.#refuseWebhook(params, ctx) : this.#webhooks.unsubscribe(params, ctx) + this.#webhooks === undefined ? this.#refuseWebhook(params, requestCtx) : this.#webhooks.unsubscribe(params, requestCtx) ) ); - server.registerCapabilities({ extensions: { [EVENTS_EXTENSION_ID]: {} } }); markModernOnlyExtension(server, EVENTS_EXTENSION_ID); markStreamingMethod(server, EVENTS_STREAM_METHOD); - registerParamHeaderSource(mcp, NAMED_EVENT_METHODS, name => this.#registry.get(name)?.inputJson); - this.#attached.add(mcp); - eventsServers.add(mcp); + registerParamHeaderSource(ctx.mcp, NAMED_EVENT_METHODS, name => this.#registry.get(name)?.inputJson); } /** diff --git a/packages/server/src/ext/events/validation.ts b/packages/server/src/ext/events/validation.ts index ba8f6e5021..82935b678a 100644 --- a/packages/server/src/ext/events/validation.ts +++ b/packages/server/src/ext/events/validation.ts @@ -37,7 +37,7 @@ export class SubscriptionValidator { this.#deps = deps; } - // After the era gate in `attach`: webhook mode (webhook only), principal (required for webhook), event exists, mode offered, `beforeParse`, then the arguments. + // After the era gate in `setup`'s handlers: webhook mode (webhook only), principal (required for webhook), event exists, mode offered, `beforeParse`, then the arguments. async validate( mode: DeliveryMode, params: SubscriptionRequest, diff --git a/packages/server/test/ext/events/harness.ts b/packages/server/test/ext/events/harness.ts index c8913bbaf9..3c5aef774c 100644 --- a/packages/server/test/ext/events/harness.ts +++ b/packages/server/test/ext/events/harness.ts @@ -50,15 +50,14 @@ function modernHeaders(message: JSONRPCRequest | JSONRPCNotification): Record void } = {} ): Served { const handler = createMcpHandler( () => { - const mcp = new McpServer({ name: 'events-test', version: '1.0.0' }); - events.attach(mcp); + const mcp = new McpServer({ name: 'events-test', version: '1.0.0' }, { extensions: [events] }); options.setup?.(mcp); return mcp; }, diff --git a/packages/server/test/ext/events/registration.test.ts b/packages/server/test/ext/events/registration.test.ts index 8130ff9c03..28317ef18a 100644 --- a/packages/server/test/ext/events/registration.test.ts +++ b/packages/server/test/ext/events/registration.test.ts @@ -1,5 +1,4 @@ import type { DiscoverResult, InitializeResult } from '@modelcontextprotocol/core-internal'; -import { InMemoryTransport } from '@modelcontextprotocol/core-internal'; import { describe, expect, expectTypeOf, it, vi } from 'vitest'; import * as z from 'zod/v4'; @@ -41,11 +40,12 @@ describe('discovery', () => { }); it('hides only the modern-only extensions from the legacy capabilities', () => { - const mcp = new McpServer({ name: 't', version: '1' }, { capabilities: { extensions: { 'example.com/other': {} } } }); - new EventsExtension().attach(mcp); + const mcp = new McpServer( + { name: 't', version: '1' }, + { capabilities: { extensions: { 'example.com/other': {} } }, extensions: [new EventsExtension()] } + ); expect(legacyAdvertisedCapabilities(mcp.server, mcp.server.getCapabilities()).extensions).toEqual({ 'example.com/other': {} }); - const alone = new McpServer({ name: 't', version: '1' }); - new EventsExtension().attach(alone); + const alone = new McpServer({ name: 't', version: '1' }, { extensions: [new EventsExtension()] }); expect(legacyAdvertisedCapabilities(alone.server, alone.server.getCapabilities())).not.toHaveProperty('extensions'); }); @@ -256,28 +256,20 @@ describe('registerEvent', () => { }); }); -describe('attach', () => { - it('follows the Skills attach rules', async () => { - const events = new EventsExtension(); - const mcp = new McpServer({ name: 't', version: '1' }); - events.attach(mcp); - events.attach(mcp); - expect(mcp.server.getCapabilities().extensions).toEqual({ 'io.modelcontextprotocol/events': {} }); - expect(() => new EventsExtension().attach(mcp)).toThrow( - 'another events extension is already attached to this server; attach one per server' +describe('extensions option', () => { + it('fails construction with a second Events extension', () => { + expect(() => new McpServer({ name: 't', version: '1' }, { extensions: [new EventsExtension(), new EventsExtension()] })).toThrow( + 'Extension "io.modelcontextprotocol/events" is listed more than once; pass each extension once' ); + }); - const connected = new McpServer({ name: 't', version: '1' }); - const [, serverSide] = InMemoryTransport.createLinkedPair(); - await connected.connect(serverSide); - expect(() => events.attach(connected)).toThrow('attach events before connecting the server'); - await connected.close(); - - const taken = new McpServer({ name: 't', version: '1' }); - taken.server.setRequestHandler('events/poll', { params: z.object({}) }, () => ({})); - expect(() => events.attach(taken)).toThrow('A request handler for events/poll already exists, which would be overridden'); - expect(taken.server.getCapabilities().extensions).toBeUndefined(); - expect(() => taken.server.assertCanSetRequestHandler('events/list')).not.toThrow(); + it('serves every server constructed with one instance', async () => { + const events = new EventsExtension(); + events.registerEvent('tick', { payloadSchema: P, check: tick }); + // Two handlers, each building a fresh server per request. + for (const { rpc } of [serve(events), serve(events)]) { + expect(resultOf(await rpc('events/list'))).toMatchObject({ events: [{ name: 'tick' }] }); + } }); }); diff --git a/test/conformance/src/events.ts b/test/conformance/src/events.ts index 370e0b8bb3..e987775624 100644 --- a/test/conformance/src/events.ts +++ b/test/conformance/src/events.ts @@ -165,11 +165,9 @@ function mint(name: string, revision: number): EventHandle { } // A subscribe sent on another principal's behalf, through a server serving the same extension and store. -const subscribeAsHandler = createMcpHandler(() => { - const server = new Server({ name: 'events-conformance-subscribe-as', version: '1.0.0' }); - conformanceEvents.attach(server); - return server; -}); +const subscribeAsHandler = createMcpHandler( + () => new Server({ name: 'events-conformance-subscribe-as', version: '1.0.0' }, { extensions: [conformanceEvents] }) +); async function subscribeAs(principal: string, name: string, url: string): Promise { const authInfo: AuthInfo = { diff --git a/test/conformance/src/everythingClient.ts b/test/conformance/src/everythingClient.ts index dd972ca9df..4203652596 100644 --- a/test/conformance/src/everythingClient.ts +++ b/test/conformance/src/everythingClient.ts @@ -966,8 +966,10 @@ const EVENTS_WEBHOOK_URL = 'https://conformance-test.local/mcp-events'; async function runEventsClient(serverUrl: string): Promise { const { durationMs } = z.object({ durationMs: z.number() }).parse(JSON.parse(process.env.MCP_CONFORMANCE_CONTEXT ?? '{}')); const events = new EventsClientExtension({ webhook: { url: EVENTS_WEBHOOK_URL } }); - const client = new Client({ name: 'test-client', version: '1.0.0' }, { capabilities: {}, versionNegotiation: { mode: 'auto' } }); - events.attach(client); + const client = new Client( + { name: 'test-client', version: '1.0.0' }, + { capabilities: {}, versionNegotiation: { mode: 'auto' }, extensions: [events] } + ); await client.connect(new StreamableHTTPClientTransport(new URL(serverUrl))); const subscriptions: EventSubscription[] = []; if (events.supported) { diff --git a/test/conformance/src/everythingServer.ts b/test/conformance/src/everythingServer.ts index b96c4afa9d..3959186550 100644 --- a/test/conformance/src/everythingServer.ts +++ b/test/conformance/src/everythingServer.ts @@ -166,15 +166,16 @@ function createMcpServer() { // request that carries requestState is verified before the handler // runs. A rejection answers a wire-level -32602 with // data.reason 'invalid_request_state'. - requestState: { verify: requestStateCodec.verify } + requestState: { verify: requestStateCodec.verify }, + // SEP-3415: events/*. + extensions: [conformanceEvents] } ); // SEP-2640: skills/list, skills/get, resources/directory/read and the skill:// resource template. conformanceSkills.attach(mcpServer); - // SEP-3415: events/* and the events_conformance_* control tools. - conformanceEvents.attach(mcpServer); + // SEP-3415: the events_conformance_* control tools. registerEventsControls(mcpServer); // Helper to send log messages using the underlying server diff --git a/test/e2e/requirements.ts b/test/e2e/requirements.ts index 943187eac7..472a733b1c 100644 --- a/test/e2e/requirements.ts +++ b/test/e2e/requirements.ts @@ -3864,10 +3864,11 @@ export const REQUIREMENTS: Record = { source: `${EVENTS_SPEC}#event-occurrences`, behavior: 'The client delivers each eventId once per subscription.' }, - 'typescript:events:attach:rules': { + 'typescript:events:extensions:rules': { ...EVENTS_CELLS, source: 'sdk', - behavior: 'attach is idempotent per server, refuses a second Events extension and refuses after connect.' + behavior: + "Two Events extensions in one server's extensions fail its construction; one EventsExtension serves every server constructed with it; an EventsClientExtension serves one client, and a second client constructed with it fails." }, 'typescript:events:definition:kinds': { ...EVENTS_CELLS, diff --git a/test/e2e/scenarios/events.test.ts b/test/e2e/scenarios/events.test.ts index 43d5f6fee5..fdeddba2dc 100644 --- a/test/e2e/scenarios/events.test.ts +++ b/test/e2e/scenarios/events.test.ts @@ -1,9 +1,9 @@ /** * Self-contained test bodies for the Events extension (SEP-3415). * - * Each body builds its own EventsExtension, attaches it inside the server - * factory (the entry builds a server per request, so one extension serves - * them all), wires a real Client and asserts through EventsClientExtension, + * Each body builds its own EventsExtension, passes it in the extensions of + * the servers its factory builds (the entry builds a server per request, so + * one extension serves them all), wires a real Client and asserts through EventsClientExtension, * raw events/* requests or the recorded HTTP exchanges. Webhook POSTs go to an * in-process endpoint through the extension's webhookSender: the client's * receiver, or a stand-in that echoes verification challenges. Bodies that @@ -19,7 +19,7 @@ import { EventsError, NoCompatibleDeliveryModeError } from '@modelcontextprotocol/client/ext/events'; -import { InMemoryTransport, McpServer } from '@modelcontextprotocol/server'; +import { McpServer } from '@modelcontextprotocol/server'; import type { EventsOptions, WebhookSender } from '@modelcontextprotocol/server/ext/events'; import { EventsError as ServerEventsError, @@ -50,11 +50,7 @@ type Note = z.infer; const newClient = (): Client => new Client({ name: 'c', version: '0' }); function serving(events: EventsExtension): () => McpServer { - return () => { - const s = new McpServer({ name: 's', version: '0' }); - events.attach(s); - return s; - }; + return () => new McpServer({ name: 's', version: '0' }, { extensions: [events] }); } /** An extension with one emit-only event type, `note`. */ @@ -64,11 +60,10 @@ function noteEvents(options?: EventsOptions) { return { events, note }; } -/** A client with an EventsClientExtension attached, ready for wire(). */ +/** A client with an EventsClientExtension in its extensions, ready for wire(). */ function eventsClient(options: EventsClientOptions = FAST): { client: Client; clientEvents: EventsClientExtension } { - const client = newClient(); const clientEvents = new EventsClientExtension(options); - clientEvents.attach(client); + const client = new Client({ name: 'c', version: '0' }, { extensions: [clientEvents] }); return { client, clientEvents }; } @@ -1098,28 +1093,33 @@ verifies('events:client:dedupe', async ({ transport }: TestArgs) => { // TypeScript SDK surface // ─────────────────────────────────────────────────────────────────────────────── -verifies('typescript:events:attach:rules', async ({ transport }: TestArgs) => { - const { events: first } = noteEvents(); - const second = new EventsExtension(); - second.registerEvent('other', { emitOnly: true, payloadSchema: NotePayload }); - const makeServer = () => { - const s = new McpServer({ name: 's', version: '0' }); - first.attach(s); - first.attach(s); - expect(() => second.attach(s)).toThrow(/another events extension is already attached/); - return s; - }; - const client = newClient(); - await using _ = await wire(transport, makeServer, client, EVENTS_WIRE); +verifies('typescript:events:extensions:rules', async ({ transport }: TestArgs) => { + const { events, note } = noteEvents(); + expect(() => new McpServer({ name: 's', version: '0' }, { extensions: [events, new EventsExtension()] })).toThrow( + 'Extension "io.modelcontextprotocol/events" is listed more than once; pass each extension once' + ); - const { events: listed } = (await raw(client, 'events/list')) as { events: Array<{ name: string }> }; - expect(listed.map(descriptor => descriptor.name)).toEqual([NOTE]); + // One instance serves every server constructed with it: one emit reaches a subscriber of each. + const first = eventsClient(); + const second = eventsClient(); + await using _ = await wire(transport, serving(events), first.client, EVENTS_WIRE); + { + await using _ = await wire(transport, serving(events), second.client, EVENTS_WIRE); + const subscriptions = [ + await first.clientEvents.subscribe({ name: NOTE, delivery: 'push' }), + await second.clientEvents.subscribe({ name: NOTE, delivery: 'push' }) + ]; + await note.emit({ eventId: 'evt-1', data: { text: 'both' } }); + for (const subscription of subscriptions) { + expect(await take(subscription)).toEqual([{ text: 'both' }]); + await subscription.cancel(); + } + } - const connected = new McpServer({ name: 's', version: '0' }); - const [, serverTransport] = InMemoryTransport.createLinkedPair(); - await connected.connect(serverTransport); - expect(() => second.attach(connected)).toThrow('attach events before connecting the server'); - await connected.close(); + // An EventsClientExtension serves one client: a second client constructed with it fails. + expect(() => new Client({ name: 'c2', version: '0' }, { extensions: [first.clientEvents] })).toThrow( + "This EventsClientExtension is already in another client; pass a new one in each client's extensions option" + ); }); verifies('typescript:events:definition:kinds', async ({ transport }: TestArgs) => { diff --git a/test/integration/test/__fixtures__/eventsStdioServer.ts b/test/integration/test/__fixtures__/eventsStdioServer.ts index 79460c957e..008ddb0ec9 100644 --- a/test/integration/test/__fixtures__/eventsStdioServer.ts +++ b/test/integration/test/__fixtures__/eventsStdioServer.ts @@ -37,8 +37,8 @@ export interface EventsFixture { readonly note: EmitOnlyEventHandle<{ tag: string; text: string }>; // Every onSubscribe and onUnsubscribe call, in order. readonly log: readonly HookEntry[]; - // Attaches the extension, and the tools that drive it, to one server. - attach(mcp: McpServer): void; + // A server with the extension, and the tools that drive it. + server(name: string): McpServer; } // Every subscription names a tag, so tests sharing one server see only their own events and hooks. @@ -89,8 +89,8 @@ export function eventsFixture(options: EventsOptions = {}): EventsFixture { ...hooks }); - const attach = (mcp: McpServer): void => { - events.attach(mcp); + const server = (name: string): McpServer => { + const mcp = new McpServer({ name, version: '1.0.0' }, { extensions: [events] }); mcp.registerTool('emit', { inputSchema: z.object({ tag: z.string(), texts: z.array(z.string()) }) }, async ({ tag, texts }) => { for (const text of texts) await note.emit({ data: { tag, text } }); return { content: [] }; @@ -113,18 +113,15 @@ export function eventsFixture(options: EventsOptions = {}): EventsFixture { mcp.registerTool('hooks', { inputSchema: TagArgs }, ({ tag }) => ({ content: [{ type: 'text', text: JSON.stringify(log.filter(entry => entry.tag === tag)) }] })); + return mcp; }; - return { note, log, attach }; + return { note, log, server }; } // Run as a script (not imported): serve one stdio connection. if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) { - const { attach } = eventsFixture(); - const handle = serveStdio(() => { - const mcp = new McpServer({ name: 'events-stdio-fixture', version: '1.0.0' }); - attach(mcp); - return mcp; - }); + const { server } = eventsFixture(); + const handle = serveStdio(() => server('events-stdio-fixture')); const exit = async () => { await handle.close(); diff --git a/test/integration/test/events/eventsEndToEnd.test.ts b/test/integration/test/events/eventsEndToEnd.test.ts index 7c100d5f6e..72bdb48792 100644 --- a/test/integration/test/events/eventsEndToEnd.test.ts +++ b/test/integration/test/events/eventsEndToEnd.test.ts @@ -26,7 +26,7 @@ import type { EventsClientOptions, EventSubscription } from '@modelcontextprotoc import { EVENTS_EXTENSION_ID, EventsClientExtension, EventsError } from '@modelcontextprotocol/client/ext/events'; import { StdioClientTransport } from '@modelcontextprotocol/client/stdio'; import type { AuthInfo, CreateMcpHandlerOptions, McpHttpHandler } from '@modelcontextprotocol/server'; -import { createMcpHandler, McpServer } from '@modelcontextprotocol/server'; +import { createMcpHandler } from '@modelcontextprotocol/server'; import type { EventsOptions, WebhookSender } from '@modelcontextprotocol/server/ext/events'; import { EventsError as ServerEventsError, InMemoryWebhookSubscriptionStore } from '@modelcontextprotocol/server/ext/events'; import { nodeWebhookSender } from '@modelcontextprotocol/server/ext/events/node'; @@ -68,10 +68,10 @@ interface HttpConnection extends Connection { dropStreams(): void; } -function clientFor(revision: string): Client { +function clientFor(revision: string, events: EventsClientExtension): Client { return new Client( { name: 'events-host', version: '1.0.0' }, - revision === MODERN ? { versionNegotiation: { mode: { pin: MODERN } } } : {} + revision === MODERN ? { versionNegotiation: { mode: { pin: MODERN } }, extensions: [events] } : { extensions: [events] } ); } @@ -93,12 +93,8 @@ function tap(client: Client): Pick { return { received, sent }; } -function handlerFor(attach: (mcp: McpServer) => void, options?: CreateMcpHandlerOptions): McpHttpHandler { - return createMcpHandler(() => { - const mcp = new McpServer({ name: 'events-http', version: '1.0.0' }); - attach(mcp); - return mcp; - }, options); +function handlerFor(fixture: EventsFixture, options?: CreateMcpHandlerOptions): McpHttpHandler { + return createMcpHandler(() => fixture.server('events-http'), options); } // The response with a body the test can end, as a dropped connection ends it; the server sees the cancel. @@ -137,9 +133,8 @@ async function overHttp( serve: () => McpHttpHandler, options: { revision?: string; events?: EventsClientExtension; authInfo?: AuthInfo } = {} ): Promise { - const client = clientFor(options.revision ?? MODERN); const events = options.events ?? new EventsClientExtension(CLIENT_OPTIONS); - events.attach(client); + const client = clientFor(options.revision ?? MODERN, events); const requests: HttpConnection['requests'] = []; const drops = new Set<() => void>(); const fetch = async (url: URL | string, init?: RequestInit): Promise => { @@ -165,9 +160,8 @@ async function overHttp( } async function overStdio(revision: string): Promise { - const client = clientFor(revision); const events = new EventsClientExtension(CLIENT_OPTIONS); - events.attach(client); + const client = clientFor(revision, events); await client.connect( new StdioClientTransport({ command: process.execPath, args: ['--import', 'tsx', 'eventsStdioServer.ts'], cwd: FIXTURES_DIR }) ); @@ -175,19 +169,11 @@ async function overStdio(revision: string): Promise { } async function overMemory(revision: string): Promise { - const { attach } = eventsFixture(); + const { server } = eventsFixture(); const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); - const handle = serveStdio( - () => { - const mcp = new McpServer({ name: 'events-in-memory', version: '1.0.0' }); - attach(mcp); - return mcp; - }, - { transport: serverTransport } - ); - const client = clientFor(revision); + const handle = serveStdio(() => server('events-in-memory'), { transport: serverTransport }); const events = new EventsClientExtension(CLIENT_OPTIONS); - events.attach(client); + const client = clientFor(revision, events); await client.connect(clientTransport); return { client, @@ -203,7 +189,7 @@ async function overMemory(revision: string): Promise { async function connect(arm: Arm, revision: string): Promise { if (arm === 'stdio') return overStdio(revision); if (arm === 'inMemory') return overMemory(revision); - const handler = handlerFor(eventsFixture().attach); + const handler = handlerFor(eventsFixture()); const connection = await overHttp(() => handler, { revision }); return { ...connection, @@ -413,7 +399,7 @@ describe.each([['http'], ['stdio'], ['inMemory']] as const)('events over %s on 2 it("delivers under responseMode: 'json', where a subscription picks push by default", async () => { const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}); - const handler = handlerFor(eventsFixture().attach, { responseMode: 'json' }); + const handler = handlerFor(eventsFixture(), { responseMode: 'json' }); expect(warn).toHaveBeenCalledWith(expect.stringContaining('events/stream')); warn.mockRestore(); const json = await overHttp(() => handler); @@ -574,7 +560,7 @@ describe('webhook delivery over http', () => { webhookStore: store, getPrincipal }); - const handler = handlerFor(fixture.attach); + const handler = handlerFor(fixture); const connection = await overHttp(() => handler, { events, authInfo: ALICE }); return { ...connection, @@ -681,7 +667,7 @@ describe('webhook delivery over http', () => { const events = new EventsClientExtension({ ...CLIENT_OPTIONS, webhook: { url: `${origin}/hooks` } }); receive = events.createWebhookHandler(); const fixture = eventsFixture({ webhookTtlMs: 60_000, webhookSender: nodeWebhookSender(), trustedOrigins: [origin], getPrincipal }); - const handler = handlerFor(fixture.attach); + const handler = handlerFor(fixture); const connection = await overHttp(() => handler, { events, authInfo: ALICE }); try { const subscription = await events.subscribe({ name: NOTE, arguments: { tag: 'loopback' } }); @@ -711,8 +697,8 @@ describe('webhook delivery over http', () => { }; const first = eventsFixture(options); const second = eventsFixture(options); - const firstHandler = handlerFor(first.attach); - const secondHandler = handlerFor(second.attach); + const firstHandler = handlerFor(first); + const secondHandler = handlerFor(second); let target = firstHandler; const connection = await overHttp(() => target, { events, authInfo: ALICE }); try { @@ -767,7 +753,7 @@ describe('webhook delivery over http', () => { webhookStore: store, getPrincipal }; - const before = handlerFor(eventsFixture(options).attach); + const before = handlerFor(eventsFixture(options)); let target = before; const connection = await overHttp(() => target, { events, authInfo: ALICE }); try { @@ -775,7 +761,7 @@ describe('webhook delivery over http', () => { await before.close(); const restarted = eventsFixture(options); - target = handlerFor(restarted.attach); + target = handlerFor(restarted); const requests = connection.requests.length; const delivered = posts.length; await emit(restarted, 'restart', 'after the restart'); diff --git a/test/integration/test/events/eventsWire.test.ts b/test/integration/test/events/eventsWire.test.ts index a92a29d1de..0a3e1a894c 100644 --- a/test/integration/test/events/eventsWire.test.ts +++ b/test/integration/test/events/eventsWire.test.ts @@ -57,11 +57,7 @@ function served(): Served { inputSchema: z.object({ region: z.string().meta({ 'x-mcp-header': 'Region' }), severity: z.string().optional() }), payloadSchema: z.object({ title: z.string() }) }); - const handler = createMcpHandler(() => { - const mcp = new McpServer({ name: 'events-wire', version: '1.0.0' }); - events.attach(mcp); - return mcp; - }); + const handler = createMcpHandler(() => new McpServer({ name: 'events-wire', version: '1.0.0' }, { extensions: [events] })); return { handler, incident }; } @@ -233,9 +229,11 @@ describe('what a client sends', () => { beforeAll(async () => { const server = served(); - const client = new Client({ name: 'wire-client', version: '1.0.0' }, { versionNegotiation: { mode: { pin: MODERN } } }); const events = new EventsClientExtension({ webhook: { url: HOOK_URL } }); - events.attach(client); + const client = new Client( + { name: 'wire-client', version: '1.0.0' }, + { versionNegotiation: { mode: { pin: MODERN } }, extensions: [events] } + ); const fetch = async (url: URL | string, init?: RequestInit): Promise => { const request = new Request(url, init); const response = await server.handler.fetch(request); From 1ac541532fd7e399dc8c6e51dc0bea459c85def9 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Thu, 19 Nov 2026 12:19:34 +0200 Subject: [PATCH 34/37] fix(events): address review findings on delivery, limits and DNS - Push merges the event's _meta with the stream's subscription id instead of replacing it. - Every interval the server sends is a wire-valid integer: nextPollMs from check is rounded up, clamped at 0 and capped at half of pollSubscriptionTtlMs; heartbeatMs, defaultNextPollMs and webhookTtlMs must be positive integers, and an explicit defaultNextPollMs above half the lease TTL throws. - The client ends a push stream whose active fails its schema, and bounds the wait for the first active by the request timeout. - A verification for a host with one in flight waits its turn (at most 10 waiting; a cancelled waiter leaves at once); the client retries resourceExhausted with limit 'verification' after retryAfterMs. - With getPrincipal set, each principal (and the callers without one, together) holds at most a quarter of maxSubscriptions, refused as limit 'principalSubscriptions'. - nodeWebhookSender resolves through a c-ares Resolver, cancelled at the deadline, instead of dns.lookup on the libuv thread pool. - A new webhook subscription to an emit-only type replays the buffer from its cursor, and each body carries the event's own cursor once nothing before it is unsettled. - Docs: poll limits for types without replay, the store keeps records a minute past expiresAt so onUnsubscribe runs, DNS resolution. --- docs/clients/events.md | 2 +- docs/servers/events.md | 18 +- examples/guides/servers/events.examples.ts | 6 +- packages/client/src/ext/events/extension.ts | 16 +- packages/client/src/ext/events/push.ts | 37 ++- packages/client/src/ext/events/recovery.ts | 24 +- .../client/src/ext/events/subscription.ts | 11 +- packages/client/src/ext/events/webhook.ts | 4 +- packages/client/test/ext/events/push.test.ts | 61 +++++ .../client/test/ext/events/recovery.test.ts | 12 + .../client/test/ext/events/webhook.test.ts | 30 +++ packages/server/src/ext/events/extension.ts | 24 +- packages/server/src/ext/events/leases.ts | 7 + packages/server/src/ext/events/node.ts | 47 ++-- packages/server/src/ext/events/poll.ts | 19 +- packages/server/src/ext/events/push.ts | 71 +++--- packages/server/src/ext/events/types.ts | 33 ++- packages/server/src/ext/events/validation.ts | 18 +- .../server/src/ext/events/webhookEngine.ts | 137 ++++++++--- .../src/ext/events/webhookSubscriptions.ts | 48 ++-- packages/server/test/ext/events/node.test.ts | 110 +++++++-- packages/server/test/ext/events/poll.test.ts | 89 ++++++++ packages/server/test/ext/events/push.test.ts | 34 ++- .../test/ext/events/registration.test.ts | 39 +++- .../test/ext/events/webhookEngine.test.ts | 109 +++++++-- .../ext/events/webhookSubscriptions.test.ts | 216 ++++++++++++++++-- test/e2e/scenarios/events.test.ts | 8 +- 27 files changed, 1031 insertions(+), 199 deletions(-) diff --git a/docs/clients/events.md b/docs/clients/events.md index 1842db12eb..91aab59333 100644 --- a/docs/clients/events.md +++ b/docs/clients/events.md @@ -107,7 +107,7 @@ The server rejects `queue: 42` against the event type's `inputSchema`, so it pri invalidParams ``` -`subscribe()` rejects with an `EventsError` when the server does not list the event type or refuses the subscription (`notFound`, `invalidParams`, `forbidden`, `unsupported`, `resourceExhausted` or `callbackEndpointError`), and with an `SdkError` when the exchange fails in the SDK, such as a closed connection; other failures of the first exchange are retried in the background. Once subscribed, the loop ends with an `EventsError` when the server ends the subscription, such as `forbidden` when access is revoked. A `notFound`, or an `unsupported` for a schema change, makes the client list the event types again and carry on while the type is still offered in that mode. +`subscribe()` rejects with an `EventsError` when the server does not list the event type or refuses the subscription (`notFound`, `invalidParams`, `forbidden`, `unsupported`, `resourceExhausted` or `callbackEndpointError`), and with an `SdkError` when the exchange fails in the SDK, such as a closed connection or a push stream with no valid `notifications/events/active` within the request timeout; other failures of the first exchange are retried in the background. The server's webhook verification limit (`resourceExhausted` with `data.limit: 'verification'`) is one of those: the client subscribes again after `data.retryAfterMs` (or its usual backoff without one), before and after the first exchange. Once subscribed, the loop ends with an `EventsError` when the server ends the subscription, such as `forbidden` when access is revoked. A `notFound`, or an `unsupported` for a schema change, makes the client list the event types again and carry on while the type is still offered in that mode. `NoCompatibleDeliveryModeError` means no delivery mode the event type offers is usable here: webhook needs the `webhook` option, and `delivery` narrows the choice to one mode. Against a server without Events, or on a connection older than 2026-07-28, `events.supported` is `false`, and `list()` and `subscribe()` throw `SdkError` (`CapabilityNotSupported`). An error thrown from `onGap` goes to the client's `onerror`. diff --git a/docs/servers/events.md b/docs/servers/events.md index a8bfe5fcae..4ad2be8a94 100644 --- a/docs/servers/events.md +++ b/docs/servers/events.md @@ -41,6 +41,8 @@ Clients subscribe by poll (`events/poll`) or push (`events/stream`), or by webho Clients resume from their cursor after a disconnect or a restart, for as long as your upstream accepts it. A `check` that returns `cursor: null` marks a type that cannot resume. The SDK then calls `check` with `cursor: null` every time: it drops the events of a subscription's first call, as for any subscription that starts now, and sends the events of every later call, so return what happened since the previous call for the same `ctx.subscriptionId`. The SDK never reports `truncated` for such a type, and ignores `maxAgeMs` for it. +Poll serves such a type one subscription per lease, keyed by principal, event name and arguments: clients that share a lease (every caller on a server without `getPrincipal`, or one user's several clients) split its events between them, and a client's first poll on an existing lease can return events from before it subscribed. The SDK caps every `nextPollMs` it sends at half of `pollSubscriptionTtlMs`, how long a lease lives without a poll (5 minutes by default), but a client that polls less often than that starts a new lease each time and gets nothing. Clients that need every event use push or webhook. + ::: info Events is served on protocol 2026-07-28 only; a 2025-11-25 connection sees no Events capability and gets `-32601` for `events/*` — see [Protocol versions](../protocol-versions.md). ::: @@ -73,7 +75,7 @@ await incidents.emit({ eventId: 'INC-7', data: { incidentId: 'INC-7', title: 'Ch `emit()` sends the event to every subscription that `match` accepts, or to one with `emit(event, { subscriptionId })`; `transform` reshapes it per subscription. The SDK drops an event whose `data` fails `payloadSchema`, or whose `transform` output does, and reports it to `onerror`, for both kinds. -Poll clients read emit-only events from an in-memory buffer (`emitBuffer`, by default the last 10 minutes and at most 10 000 events), so events emitted before a restart are lost. `onSubscribe` and `onUnsubscribe` run as a subscription starts and ends, in every mode, and `ctx.subscriptionId` names it. +Poll clients read emit-only events from an in-memory buffer (`emitBuffer`, by default the last 10 minutes and at most 10 000 events), so events emitted before a restart are lost. Push and webhook subscriptions that pass a cursor replay that buffer first. `onSubscribe` and `onUnsubscribe` run as a subscription starts and ends, in every mode, and `ctx.subscriptionId` names it. ## Serve the event types from every server @@ -91,7 +93,7 @@ A push stream carries no SSE comment keepalive. The server sends `notifications/ Both hold under `createMcpHandler`. A custom HTTP entry built directly on `PerRequestHTTPServerTransport` must stream `events/stream` itself: serve it with `responseMode` `'auto'` or `'sse'`, never `'json'`, and the transport's `keepAliveMs` applies to it as to any stream. -One `EventsExtension` serves at most `maxSubscriptions` subscriptions at once, 1024 by default, counting its poll leases, push streams and the webhook subscriptions this process handles; it refuses more with `resourceExhausted`. +One `EventsExtension` serves at most `maxSubscriptions` subscriptions at once, 1024 by default, counting its poll leases, push streams and the webhook subscriptions this process handles; it refuses more with `resourceExhausted` (`data.limit: 'subscriptions'`). With `getPrincipal` set, each principal may hold a quarter of them, and so may all callers without a principal together, refused past that with `data.limit: 'principalSubscriptions'`; without `getPrincipal` only the process-wide limit applies. ## Deliver events to webhooks @@ -116,7 +118,7 @@ const webhookEvents = new EventsExtension({ Setting `webhookTtlMs` or `webhookSender` without the other two throws `TypeError`. `getPrincipal` has no default, since `AuthInfo` has no subject field: return the user from wherever your token verifier puts it. A webhook subscription for which `getPrincipal` returns `null` is refused with `forbidden`, on stdio too; poll and push use the principal when there is one. -`webhookTtlMs` is the longest a webhook subscription lives without a refresh, and clients refresh before it lapses. The SDK verifies each endpoint with a challenge before the first delivery, signs every POST (Standard Webhooks), and retries a failed delivery up to five attempts in all. It sends each destination host one challenge at a time and at most ten in any 60 seconds, refusing a subscribe past that with `resourceExhausted` (`data.retryAfterMs` says when to try again), and answers a principal's subscribes to a URL whose challenge failed with that failure for 60 seconds, without another challenge. `nodeWebhookSender()` requires `https`, resolves the host at every send, refuses IANA special-purpose addresses (loopback, private, link-local and the like) and connects to the address it checked; it follows no redirects and gives up after 5 seconds. +`webhookTtlMs` is the longest a webhook subscription lives without a refresh, and clients refresh before it lapses. The SDK verifies each endpoint with a challenge before the first delivery, signs every POST (Standard Webhooks), and retries a failed delivery up to five attempts in all. It sends each destination host one challenge at a time, so a subscribe waits while another challenge to that host is in flight, and at most ten in any 60 seconds; past that, or when ten subscribes already wait for the host, it refuses with `resourceExhausted` (`data.limit: 'verification'`; `data.retryAfterMs` says when to try again, and the SDK's client does). It answers a principal's subscribes to a URL whose challenge failed with that failure for 60 seconds, without another challenge. `nodeWebhookSender()` requires `https`, resolves the host at every send by querying DNS directly (so `/etc/hosts` does not apply; origins in `trustedOrigins` skip resolution), refuses IANA special-purpose addresses (loopback, private, link-local and the like) and connects to the address it checked; it follows no redirects and gives up after 5 seconds. ::: warning `trustedOrigins` is for development only. Its exact origins, such as `http://127.0.0.1:9000`, are exempt from the `https` rule and the private-address check, so a receiver on your machine can take deliveries; endpoint verification, signing and the no-redirect rule still apply. @@ -146,8 +148,10 @@ function sharedWebhookStore(kv: SharedKeyValue): WebhookSubscriptionStore { return { get: read, async put(record) { - await kv.set(`events:sub:${record.id}`, JSON.stringify(record), record.expiresAt); - await kv.set(`events:name:${record.name}:${record.id}`, '', record.expiresAt); + // A minute past expiresAt, so the SDK's expiry timer still reads the record and runs onUnsubscribe. + const keepUntil = record.expiresAt + 60_000; + await kv.set(`events:sub:${record.id}`, JSON.stringify(record), keepUntil); + await kv.set(`events:name:${record.name}:${record.id}`, '', keepUntil); }, async delete(id) { const record = await read(id); @@ -173,13 +177,13 @@ const replicated = new EventsExtension({ }); ``` -Records hold each subscription's webhook secret, so protect the store as you protect credentials. The SDK deletes an expired record when it next reads it, or when the expiry timer of the replica that last granted it fires. A record that a stopped replica left behind stays until something reads it, so let the store expire records too, as the `expiresAt` passed to `set()` above does (with Redis, a key TTL). +Records hold each subscription's webhook secret, so protect the store as you protect credentials. The SDK deletes an expired record when it next reads it, or when the expiry timer of the replica that last granted it fires, and runs `onUnsubscribe` then. The store above keeps each record a minute past its `expiresAt`, because a record the database has already dropped is gone when that timer reads it, and `onUnsubscribe` never runs for it. A record that a stopped replica left behind stays until something reads it, so let the store expire records too, as the expiry passed to `set()` above does (with Redis, a key TTL). A replica runs `onUnsubscribe` after its `delete()` resolved `true`. Replicas racing on a store whose `delete()` is not atomic may each run it for one subscription, so keep `onUnsubscribe` idempotent. With a shared store, webhook subscribe, refresh, secret rotation and unsubscribe work on any replica, and `emit()` on any replica reaches every matching webhook subscription. Some state stays on one process: -- `emit()` reaches push streams and the poll buffer on the emitting process only. A poll that lands on another replica gets `truncated: true` and a fresh cursor. +- `emit()` reaches push streams and the poll buffer on the emitting process only. A poll, or a webhook subscribe that resumes from a cursor, that lands on another replica gets `truncated: true` and a fresh cursor. - A webhook subscription to a `check` type runs its `check` loop on every replica that handled its subscribe or a refresh, so its receiver may get an event more than once (same `eventId`, different `webhook-id`); the SDK's client drops the repeats by `eventId`. Prefer emit-only types for webhook subscribers, or run one replica. - `remove()` on one replica may skip `onUnsubscribe` for subscriptions another replica handled. - Retries, the delivery watermark and `deliveryStatus` stay with the replica that delivers. diff --git a/examples/guides/servers/events.examples.ts b/examples/guides/servers/events.examples.ts index ca9f16be03..a95506f0a1 100644 --- a/examples/guides/servers/events.examples.ts +++ b/examples/guides/servers/events.examples.ts @@ -233,8 +233,10 @@ function sharedWebhookStore(kv: SharedKeyValue): WebhookSubscriptionStore { return { get: read, async put(record) { - await kv.set(`events:sub:${record.id}`, JSON.stringify(record), record.expiresAt); - await kv.set(`events:name:${record.name}:${record.id}`, '', record.expiresAt); + // A minute past expiresAt, so the SDK's expiry timer still reads the record and runs onUnsubscribe. + const keepUntil = record.expiresAt + 60_000; + await kv.set(`events:sub:${record.id}`, JSON.stringify(record), keepUntil); + await kv.set(`events:name:${record.name}:${record.id}`, '', keepUntil); }, async delete(id) { const record = await read(id); diff --git a/packages/client/src/ext/events/extension.ts b/packages/client/src/ext/events/extension.ts index 4d844fd813..5ed8469fc1 100644 --- a/packages/client/src/ext/events/extension.ts +++ b/packages/client/src/ext/events/extension.ts @@ -142,10 +142,12 @@ export class EventsClientExtension implements ClientExtension { * `events/list` (fetched again when it is not there), and resolves once * the first exchange with the server succeeds (for poll, the first * `events/poll` response; for push, the first - * `notifications/events/active`; for webhook, the `events/subscribe` - * response). A transient failure of that exchange (a - * transport error, or a JSON-RPC error that is not an Events kind) does - * not reject: delivery is retried in the background. A `cursor` the + * `notifications/events/active`, within the request timeout; for webhook, + * the `events/subscribe` response). A transient failure of that exchange (a + * transport error, a JSON-RPC error that is not an Events kind, or the + * server's webhook verification limit, `resourceExhausted` with + * `data.limit: 'verification'`, retried after its `data.retryAfterMs` + * when given) does not reject: delivery is retried in the background. A `cursor` the * server refuses because the event type's schema changed is dropped: the * event types are listed again, the subscription starts from now, and * `onGap` reports the fresh cursor. A `-32020` lists the event types again @@ -161,12 +163,14 @@ export class EventsClientExtension implements ClientExtension { * `events/unsubscribe` goes out when the last of them is cancelled. * * @throws {EventsError} when the server refuses the subscription: `notFound` for an event type it does not list or - * no longer serves, `invalidParams` for arguments its `inputSchema` rejects, `forbidden`, or another kind. + * no longer serves, `invalidParams` for arguments its `inputSchema` rejects, `forbidden`, or another kind + * (`resourceExhausted` for any limit but the webhook verification limit). * @throws {NoCompatibleDeliveryModeError} when no delivery mode the event type offers is usable here, also when * the schema change that refused `cursor` left the event type without the selected mode. * @throws {SdkError} `CapabilityNotSupported` when {@linkcode EventsClientExtension.supported} is `false`, * `ConnectionClosed` when the client closes before the first exchange answers, or another code when that - * exchange fails in the SDK (for example a request timeout). + * exchange fails in the SDK (for example `RequestTimeout`, also when a push stream sends no valid + * `notifications/events/active` in time, or `InvalidResult` for an `active` that fails its schema). * @throws {ProtocolError} `-32020` when the server rejects the `Mcp-Param` headers again after a re-list. * @throws {TypeError} when `webhook.secretProvider` returns something that is not a Standard Webhooks secret, or a * secret another open server subscription signs with. diff --git a/packages/client/src/ext/events/push.ts b/packages/client/src/ext/events/push.ts index 8746d154c1..465fabb570 100644 --- a/packages/client/src/ext/events/push.ts +++ b/packages/client/src/ext/events/push.ts @@ -12,6 +12,7 @@ import { } from '@modelcontextprotocol/core/ext/events'; import type { JSONRPCNotification } from '@modelcontextprotocol/core-internal'; import { ProtocolError, SUBSCRIPTION_ID_META_KEY } from '@modelcontextprotocol/core-internal'; +import { DEFAULT_REQUEST_TIMEOUT_MSEC, SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal/public'; import type * as z from 'zod/v4'; import type { StreamEnd, StreamHandle } from '../../client/client'; @@ -54,6 +55,7 @@ export class PushDriver implements Driver { #end: ((ending: Ending) => void) | undefined; // The open stream's heartbeat grant, from its last `active`. #grantMs: number | undefined; + // Until the first valid `active`, the wait for it; from then on, the countdown to declaring the stream dead. #dead: ReturnType | undefined; constructor(context: DriverContext) { @@ -119,6 +121,21 @@ export class PushDriver implements Driver { resolve(ending); }; this.#end = end; + // Bounded as listen() bounds its ack: with no valid `active` in time, the stream fails as a timed-out request does. + this.#dead = setTimeout( + () => + this.#fault( + end, + new SdkError( + SdkErrorCode.RequestTimeout, + `${EVENTS_STREAM_METHOD}: no valid ${EVENTS_ACTIVE_NOTIFICATION} in time`, + { + timeout: DEFAULT_REQUEST_TIMEOUT_MSEC + } + ) + ), + DEFAULT_REQUEST_TIMEOUT_MSEC + ); try { this.#handle = clientInternals.openStream( connection.client, @@ -142,7 +159,11 @@ export class PushDriver implements Driver { switch (notification.method) { case EVENTS_ACTIVE_NOTIFICATION: { const params = this.#parse(EventsActiveNotificationParamsSchema, notification); - if (params !== undefined) this.#active(params); + if (params === undefined) { + this.#fault(end, new SdkError(SdkErrorCode.InvalidResult, `Invalid ${EVENTS_ACTIVE_NOTIFICATION} params`)); + return; + } + this.#active(params); break; } case EVENTS_EVENT_NOTIFICATION: { @@ -183,13 +204,13 @@ export class PushDriver implements Driver { #alive(end: (ending: Ending) => void): void { if (this.#grantMs === undefined || this.#end !== end) return; clearTimeout(this.#dead); - this.#dead = setTimeout( - () => { - end({}); - void this.#handle?.close(); - }, - Math.min(DEAD_AFTER_HEARTBEATS * this.#grantMs, MAX_TIMER_DELAY_MS) - ); + this.#dead = setTimeout(() => this.#fault(end, undefined), Math.min(DEAD_AFTER_HEARTBEATS * this.#grantMs, MAX_TIMER_DELAY_MS)); + } + + // Ends the open stream from this side, with `error` for the recovery to judge, and closes its request. + #fault(end: (ending: Ending) => void, error: unknown): void { + end(error === undefined ? {} : { error }); + void this.#handle?.close(); } // The frame's params, or `undefined` (reported to onerror) when they do not match the schema. diff --git a/packages/client/src/ext/events/recovery.ts b/packages/client/src/ext/events/recovery.ts index ce9b32fefc..956fed698f 100644 --- a/packages/client/src/ext/events/recovery.ts +++ b/packages/client/src/ext/events/recovery.ts @@ -12,9 +12,25 @@ export const MAX_TIMER_DELAY_MS = 2_147_483_647; const RETRY_BASE_MS = 1000; const RETRY_MAX_MS = 30_000; -// An error of the first exchange that subscribe() rejects with (a -32020 only once its re-list is spent); any other (transport, non-Events JSON-RPC) is retried in the background. +// An error of the first exchange that subscribe() rejects with (a -32020 only once its re-list is spent); any other (transport, non-Events JSON-RPC, a verification limit) is retried in the background. export function refusesSubscription(error: unknown): boolean { - return error instanceof EventsError || error instanceof SdkError || isHeaderMismatch(error); + return (error instanceof EventsError && !isVerificationLimit(error)) || error instanceof SdkError || isHeaderMismatch(error); +} + +// The server's webhook verification limit per destination host: the one `resourceExhausted` that passes with time, so it is retried. +export function isVerificationLimit(error: unknown): boolean { + return ( + error instanceof EventsError && + error.kind === 'resourceExhausted' && + (error.data as { limit?: unknown } | undefined)?.limit === 'verification' + ); +} + +// How long a verification limit asks to wait before the next attempt: its `data.retryAfterMs`, when a non-negative number. +export function retryAfterOf(error: unknown): number | undefined { + if (!isVerificationLimit(error)) return undefined; + const retryAfterMs = ((error as EventsError).data as { retryAfterMs?: unknown }).retryAfterMs; + return typeof retryAfterMs === 'number' && retryAfterMs >= 0 ? retryAfterMs : undefined; } // A -32020: the request's `Mcp-Param` headers do not match its arguments (D26). @@ -44,10 +60,10 @@ export function isSchemaChange(error: unknown): boolean { ); } -// Every mode's recovery once subscribed (spec §6.3): `relist` and go on while still offered, `mismatch` (re-list and retry once, then end), `fail` (end with the error), or `retry` later. +// Every mode's recovery once subscribed (spec §6.3): `relist` and go on while still offered, `mismatch` (re-list and retry once, then end), `fail` (end with the error), or `retry` later (anything but an Events kind, and a verification limit). export function recoveryFor(error: unknown): 'relist' | 'mismatch' | 'fail' | 'retry' { if (isHeaderMismatch(error)) return 'mismatch'; - if (!(error instanceof EventsError)) return 'retry'; + if (!(error instanceof EventsError) || isVerificationLimit(error)) return 'retry'; return error.kind === 'notFound' || isSchemaChange(error) ? 'relist' : 'fail'; } diff --git a/packages/client/src/ext/events/subscription.ts b/packages/client/src/ext/events/subscription.ts index 76b2407985..79adf3e16e 100644 --- a/packages/client/src/ext/events/subscription.ts +++ b/packages/client/src/ext/events/subscription.ts @@ -42,14 +42,17 @@ export interface SubscribeOptions { * After a schema change delivery resumes from the last cursor; when the * server refuses that cursor too, it starts again from now and `onGap` * reports it. - * - Any other `EventsError` (`forbidden`, `invalidParams`, `resourceExhausted`, - * `callbackEndpointError`, any other `unsupported`): the loop ends with it, - * and `kind` says why. + * - Any other `EventsError` (`forbidden`, `invalidParams`, `resourceExhausted` + * other than the webhook verification limit, `callbackEndpointError`, any + * other `unsupported`): the loop ends with it, and `kind` says why. * - A `ProtocolError` `-32020` (the `Mcp-Param` headers do not match the * arguments): the event types are listed again and the request is retried * once with fresh headers; a second `-32020` ends the loop with it. * - Anything else (a network or transport failure, another JSON-RPC error, a - * push stream that ends or goes silent): retried after a backoff. + * push stream that ends, goes silent or sends no valid `active`): retried + * after a backoff. The server's webhook verification limit + * (`resourceExhausted` with `data.limit: 'verification'`) is retried after + * its `data.retryAfterMs`, or after a backoff without one. * * Closing the client, or connecting it again without resuming its session, * ends its subscriptions at once: the loop rejects with an `SdkError` diff --git a/packages/client/src/ext/events/webhook.ts b/packages/client/src/ext/events/webhook.ts index a9bcada632..7e250ad4d9 100644 --- a/packages/client/src/ext/events/webhook.ts +++ b/packages/client/src/ext/events/webhook.ts @@ -10,7 +10,7 @@ import { canonicalJson, generateWebhookSecret, parseWebhookSecret } from '@model import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal/public'; import type { WebhookReceiver, WebhookSink } from './receiver'; -import { DriverLoop, jitteredDelay, MAX_TIMER_DELAY_MS, reportGap } from './recovery'; +import { DriverLoop, jitteredDelay, MAX_TIMER_DELAY_MS, reportGap, retryAfterOf } from './recovery'; import type { EventsConnection, ParamMirror } from './request'; import type { DeliveryQueue, Driver, DriverContext } from './subscription'; @@ -222,7 +222,7 @@ class WebhookDriver implements Driver { const error = await this.#subscribeAndRefresh(); if (loop.ended) return; await loop.recover(error); - await loop.sleep(jitteredDelay(this.#attempt++)); + await loop.sleep(retryAfterOf(error) ?? jitteredDelay(this.#attempt++)); } } catch (error) { // Left to lapse: an identical subscribe after this end opens a new driver on the same server subscription. diff --git a/packages/client/test/ext/events/push.test.ts b/packages/client/test/ext/events/push.test.ts index 0d82c4f101..03d5ced875 100644 --- a/packages/client/test/ext/events/push.test.ts +++ b/packages/client/test/ext/events/push.test.ts @@ -545,6 +545,67 @@ describe('push delivery', () => { expect(vi.getTimerCount()).toBe(0); }); + it('rejects subscribe() when no valid active arrives within the request timeout, and reopens once subscribed', async () => { + const first = await pushWith(); + let settled = false; + const subscribing = first.events + .subscribe({ name: 'tick', delivery: 'push' }) + .catch((error_: unknown) => error_) + .finally(() => (settled = true)); + await settle(); + await first.last().frame('notifications/events/heartbeat', { cursor: 'c0' }); + await vi.advanceTimersByTimeAsync(59_999); + expect(settled).toBe(false); + await vi.advanceTimersByTimeAsync(1); + const error = await subscribing; + expect(error).toBeInstanceOf(SdkError); + expect(error).toMatchObject({ code: SdkErrorCode.RequestTimeout }); + expect(first.notifications).toContainEqual({ + method: 'notifications/cancelled', + params: expect.objectContaining({ requestId: first.streams()[0]!.call.id }) + }); + expect(vi.getTimerCount()).toBe(0); + expect(first.streams()).toHaveLength(1); + + const later = await pushWith(); + await later.subscribe(); + await later.last().end(); + await vi.advanceTimersByTimeAsync(500); + expect(later.streams()).toHaveLength(2); + await vi.advanceTimersByTimeAsync(60_000 + 1000); + expect(later.streams()).toHaveLength(3); + }); + + it('ends the stream on an active that fails its schema: subscribe() rejects, and once subscribed it reopens', async () => { + const first = await pushWith(); + const errors: Error[] = []; + first.client.onerror = error => void errors.push(error); + const subscribing = first.events.subscribe({ name: 'tick', delivery: 'push' }).catch((error_: unknown) => error_); + await settle(); + await first.last().active({ heartbeatMs: 0 }); + const error = await subscribing; + expect(error).toBeInstanceOf(SdkError); + expect(error).toMatchObject({ code: SdkErrorCode.InvalidResult }); + expect(errors).toEqual([ + expect.objectContaining({ message: expect.stringContaining('Invalid notifications/events/active params') }) + ]); + expect(vi.getTimerCount()).toBe(0); + expect(first.streams()).toHaveLength(1); + + const later = await pushWith(); + await later.subscribe({}, s => s.active({ cursor: 'c1' })); + await later.last().end(); + await vi.advanceTimersByTimeAsync(500); + await later.last().active({ cursor: 'c2', heartbeatMs: 0 }); + expect(later.notifications).toContainEqual({ + method: 'notifications/cancelled', + params: expect.objectContaining({ requestId: later.streams()[1]!.call.id }) + }); + await vi.advanceTimersByTimeAsync(1000); + expect(later.streams()).toHaveLength(3); + expect(later.last().call.params['cursor']).toBe('c1'); + }); + it('ends the loop with ConnectionClosed when the client closes', async () => { const { client, streams, subscribe } = await pushWith(); const sub = await subscribe({}, s => s.active({ heartbeatMs: 5000 })); diff --git a/packages/client/test/ext/events/recovery.test.ts b/packages/client/test/ext/events/recovery.test.ts index 88c7a86bb3..4b4f885dbb 100644 --- a/packages/client/test/ext/events/recovery.test.ts +++ b/packages/client/test/ext/events/recovery.test.ts @@ -18,6 +18,18 @@ describe('the recovery rules every delivery mode shares', () => { ['forbidden', 'fail', true, new EventsError('forbidden', 'Forbidden')], ['invalidParams', 'fail', true, new EventsError('invalidParams', 'Invalid arguments')], ['resourceExhausted', 'fail', true, new EventsError('resourceExhausted', 'Too many', { limit: 'subscriptions' })], + [ + 'resourceExhausted, per principal', + 'fail', + true, + new EventsError('resourceExhausted', 'Too many', { limit: 'principalSubscriptions', max: 256 }) + ], + [ + 'resourceExhausted, verification', + 'retry', + false, + new EventsError('resourceExhausted', 'Too many verifications', { limit: 'verification', retryAfterMs: 5000 }) + ], ['callbackEndpointError', 'fail', true, new EventsError('callbackEndpointError', 'Unreachable', { reason: 'timeout' })], ['-32020', 'mismatch', true, new ProtocolError(-32_020, 'Mcp-Param-Region header mismatch')], ['another JSON-RPC error', 'retry', false, new ProtocolError(-32_603, 'Internal error')], diff --git a/packages/client/test/ext/events/webhook.test.ts b/packages/client/test/ext/events/webhook.test.ts index 301844e066..584885581f 100644 --- a/packages/client/test/ext/events/webhook.test.ts +++ b/packages/client/test/ext/events/webhook.test.ts @@ -668,6 +668,36 @@ describe('webhook delivery', () => { expect(await nextEventId(sub[Symbol.asyncIterator]())).toBe('e1'); }); + it("retries the server's verification limit after data.retryAfterMs, first and once subscribed; a subscriptions limit still rejects", async () => { + const limited = (retryAfterMs?: unknown) => + new RpcError(-32_025, 'Too many webhook endpoint verifications for this host', { + limit: 'verification', + ...(retryAfterMs !== undefined && { retryAfterMs }) + }); + const { subscribes, subscribe } = await webhookWith(granting(limited(7000), { cursor: 'c1' }, limited(12_000), limited(), {})); + const sub = await subscribe({ cursor: 'c0' }); + expect(subscribes()).toHaveLength(1); + await vi.advanceTimersByTimeAsync(6999); + expect(subscribes()).toHaveLength(1); + await vi.advanceTimersByTimeAsync(1); + expect(subscribes()).toHaveLength(2); + expect(sub.cursor).toBe('c1'); + + // The refresh at ¾ of the grant is limited too: it waits retryAfterMs, then the backoff when the hint is missing. + await vi.advanceTimersByTimeAsync(45_000); + expect(subscribes()).toHaveLength(3); + await vi.advanceTimersByTimeAsync(12_000); + expect(subscribes()).toHaveLength(4); + await vi.advanceTimersByTimeAsync(500); + expect(subscribes()).toHaveLength(5); + expect(subscribes().map(call => call.params['cursor'])).toEqual(['c0', 'c0', 'c1', 'c1', 'c1']); + + const refused = await webhookWith(granting(new RpcError(-32_025, 'Too many subscriptions', { limit: 'subscriptions' }))); + const error = await refused.events.subscribe({ name: 'tick' }).catch((error_: unknown) => error_); + expect(error).toBeInstanceOf(EventsError); + expect(error).toMatchObject({ kind: 'resourceExhausted', data: { limit: 'subscriptions' } }); + }); + it('drops a stale cursor that the first events/subscribe refuses for a schema change, and starts from now', async () => { const onGap = vi.fn(); const { events, lists, subscribes } = await webhookWith( diff --git a/packages/server/src/ext/events/extension.ts b/packages/server/src/ext/events/extension.ts index 28c9a68f0f..405c9a0bf7 100644 --- a/packages/server/src/ext/events/extension.ts +++ b/packages/server/src/ext/events/extension.ts @@ -48,7 +48,9 @@ export type DefaultSchema = StandardSchemaWithJSON>; // The `events/*` requests that name an event type in `params.name`. const NAMED_EVENT_METHODS = [EVENTS_POLL_METHOD, EVENTS_STREAM_METHOD, EVENTS_SUBSCRIBE_METHOD, EVENTS_UNSUBSCRIBE_METHOD]; -const NUMERIC_OPTIONS = ['webhookTtlMs', 'pollSubscriptionTtlMs', 'heartbeatMs', 'checkIntervalMs', 'defaultNextPollMs'] as const; +const DURATION_OPTIONS = ['pollSubscriptionTtlMs', 'checkIntervalMs'] as const; +// Durations that reach clients, so whole milliseconds as the wire schemas require. +const WIRE_DURATION_OPTIONS = ['webhookTtlMs', 'heartbeatMs', 'defaultNextPollMs'] as const; const DEFAULT_EMIT_BUFFER_MAX_AGE_MS = 600_000; const DEFAULT_EMIT_BUFFER_MAX_EVENTS = 10_000; @@ -83,6 +85,15 @@ function assertOrigin(origin: string): void { } } +// A poll client that waits a `defaultNextPollMs` set explicitly must find its lease still there; a defaulted one is capped per result. +function assertPollTiming(pollSubscriptionTtlMs: number, defaultNextPollMs: number | undefined): void { + if (defaultNextPollMs !== undefined && defaultNextPollMs > Math.floor(pollSubscriptionTtlMs / 2)) { + throw new TypeError( + `defaultNextPollMs (${defaultNextPollMs}) must be at most half of pollSubscriptionTtlMs (${pollSubscriptionTtlMs})` + ); + } +} + function assertWebhookOptions(options: EventsOptions): void { if ((options.webhookTtlMs === undefined) !== (options.webhookSender === undefined)) { throw new TypeError('set webhookTtlMs and webhookSender together, or neither'); @@ -140,10 +151,13 @@ export class EventsExtension implements ServerExtension { /** Throws `TypeError` for an invalid option, including webhook options set only in part. */ constructor(options: EventsOptions = {}) { assertWebhookOptions(options); - for (const name of NUMERIC_OPTIONS) assertPositive(name, options[name]); + for (const name of DURATION_OPTIONS) assertPositive(name, options[name]); + for (const name of WIRE_DURATION_OPTIONS) assertCount(name, options[name]); assertCount('maxSubscriptions', options.maxSubscriptions); assertPositive('emitBuffer.maxAgeMs', options.emitBuffer?.maxAgeMs); assertCount('emitBuffer.maxEvents', options.emitBuffer?.maxEvents); + const pollSubscriptionTtlMs = options.pollSubscriptionTtlMs ?? DEFAULT_POLL_SUBSCRIPTION_TTL_MS; + assertPollTiming(pollSubscriptionTtlMs, options.defaultNextPollMs); for (const origin of options.trustedOrigins ?? []) assertOrigin(origin); this.#trustedOrigins = new Set(options.trustedOrigins); this.#webhookEnabled = options.webhookTtlMs !== undefined; @@ -157,12 +171,14 @@ export class EventsExtension implements ServerExtension { webhookEnabled: this.#webhookEnabled, getPrincipal: options.getPrincipal, maxSubscriptions: options.maxSubscriptions ?? DEFAULT_MAX_SUBSCRIPTIONS, - subscriptionCount: () => this.#poll.size + this.#push.size + (this.#webhooks?.size ?? 0) + subscriptionCount: () => this.#poll.size + this.#push.size + (this.#webhooks?.size ?? 0), + principalSubscriptionCount: principal => + this.#poll.countOf(principal) + this.#push.countOf(principal) + (this.#webhooks?.countOf(principal) ?? 0) }); this.#poll = new PollSource({ validator: this.#validator, buffer: this.#buffer, - pollSubscriptionTtlMs: options.pollSubscriptionTtlMs ?? DEFAULT_POLL_SUBSCRIPTION_TTL_MS, + pollSubscriptionTtlMs, defaultNextPollMs: options.defaultNextPollMs ?? DEFAULT_NEXT_POLL_MS, report: error => this.#report(error) }); diff --git a/packages/server/src/ext/events/leases.ts b/packages/server/src/ext/events/leases.ts index dd55c52b24..f64fcd5889 100644 --- a/packages/server/src/ext/events/leases.ts +++ b/packages/server/src/ext/events/leases.ts @@ -44,6 +44,13 @@ export class LeaseTable { return this.#slots.get(key)?.lease; } + // The leases `principal` holds. + countOf(principal: string | null): number { + let count = 0; + for (const { lease } of this.#slots.values()) if (lease.principal === principal) count += 1; + return count; + } + touch(key: string, create: () => L): { lease: L; created: boolean } { const existing = this.#slots.get(key); if (existing !== undefined) { diff --git a/packages/server/src/ext/events/node.ts b/packages/server/src/ext/events/node.ts index 5185495820..0f885335e4 100644 --- a/packages/server/src/ext/events/node.ts +++ b/packages/server/src/ext/events/node.ts @@ -9,11 +9,15 @@ import type { IncomingMessage } from 'node:http'; import http from 'node:http'; import https from 'node:https'; import type { LookupFunction } from 'node:net'; +import net from 'node:net'; import { isSpecialPurposeAddress } from './specialAddresses'; import type { WebhookSender, WebhookSendOutcome, WebhookSendRequest } from './types'; const TIMEOUT_MS = 5000; +// The resolver's timeout per query and its tries per name server; the 5 s deadline cancels whatever resolution is left. +const RESOLVE_TIMEOUT_MS = 1000; +const RESOLVE_TRIES = 2; const MAX_RESPONSE_BYTES = 65_536; const REFUSED: WebhookSendOutcome = { error: 'connection_refused' }; // OpenSSL certificate and verification codes, Node's TLS and OpenSSL error codes, and EPROTO, which Node reports for a failed TLS handshake. @@ -22,13 +26,14 @@ const TLS_FAILURE_CODE = /CERT|UNABLE_TO_VERIFY|INVALID_CA|SELF_SIGNED|DEPTH_ZER /** * The default {@linkcode WebhookSender} for Node.js, hardened against * server-side request forgery. Unless the URL's origin is in `trustedOrigins`, - * it requires `https`, resolves the host at every send, refuses with - * `connection_refused` when any resolved address is in an IANA special-purpose - * range (loopback, private, link-local and the like), and connects to the - * checked address with the URL's host name in the `Host` header and TLS SNI. - * It follows no redirects (a 3xx answer is returned as it is), gives up after - * 5 seconds with `{ error: 'timeout' }`, and reads at most 64 KiB of the - * response body. + * it requires `https`, resolves the host's A and AAAA records at every send + * (with a DNS query, not `getaddrinfo`, so `/etc/hosts` does not apply), + * refuses with `connection_refused` when any resolved address is in an IANA + * special-purpose range (loopback, private, link-local and the like), and + * connects to the checked address with the URL's host name in the `Host` + * header and TLS SNI. It follows no redirects (a 3xx answer is returned as it + * is), gives up after 5 seconds with `{ error: 'timeout' }`, and reads at most + * 64 KiB of the response body. * * Experimental: Events (SEP-3415) is new; this API may change in a minor release. * @@ -54,7 +59,7 @@ async function send(request: WebhookSendRequest): Promise { try { let lookup: LookupFunction | undefined; if (!request.trusted) { - const addresses = await untilAborted(dns.promises.lookup(hostnameOf(url), { all: true }), deadline.signal); + const addresses = await resolve(hostnameOf(url), deadline.signal); const [first] = addresses; if (first === undefined || addresses.some(({ address }) => isSpecialPurposeAddress(address))) return REFUSED; lookup = pinnedTo(first); @@ -102,16 +107,26 @@ function post(url: URL, request: WebhookSendRequest, lookup: LookupFunction | un }); } -// Settles as `promise` does, or rejects once `signal` aborts; a DNS lookup cannot itself be cancelled. -function untilAborted(promise: Promise, signal: AbortSignal): Promise { - return new Promise((resolve, reject) => { - const abort = (): void => reject(signal.reason); - signal.addEventListener('abort', abort, { once: true }); - promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort)); - }); +// The host's A and AAAA addresses, from a resolver of its own (c-ares, off libuv's thread pool) that `signal` cancels; an IP literal is its own address. Rejects when neither family resolves. +async function resolve(hostname: string, signal: AbortSignal): Promise { + const family = net.isIP(hostname); + if (family !== 0) return [{ address: hostname, family }]; + const resolver = new dns.promises.Resolver({ timeout: RESOLVE_TIMEOUT_MS, tries: RESOLVE_TRIES }); + const cancel = (): void => resolver.cancel(); + signal.addEventListener('abort', cancel, { once: true }); + try { + const [v4, v6] = await Promise.allSettled([resolver.resolve4(hostname), resolver.resolve6(hostname)]); + if (v4.status === 'rejected' && v6.status === 'rejected') throw v4.reason; + return [ + ...(v4.status === 'fulfilled' ? v4.value.map(address => ({ address, family: 4 })) : []), + ...(v6.status === 'fulfilled' ? v6.value.map(address => ({ address, family: 6 })) : []) + ]; + } finally { + signal.removeEventListener('abort', cancel); + } } -// URL keeps the brackets of an IPv6 literal host; the resolver takes the bare address. +// URL keeps the brackets of an IPv6 literal host; net.isIP and the resolver take the bare address. function hostnameOf(url: URL): string { return url.hostname.startsWith('[') ? url.hostname.slice(1, -1) : url.hostname; } diff --git a/packages/server/src/ext/events/poll.ts b/packages/server/src/ext/events/poll.ts index f4d1addc5f..557709745e 100644 --- a/packages/server/src/ext/events/poll.ts +++ b/packages/server/src/ext/events/poll.ts @@ -122,9 +122,12 @@ export class PollSource implements SubscriptionSource { readonly #leases: LeaseTable; // First-sight onSubscribe calls in flight, so a concurrent poll for the same lease waits for the outcome. readonly #starting = new Map>(); + // The longest `nextPollMs` sent, so a client that waits it polls before its lease lapses. + readonly #maxNextPollMs: number; constructor(deps: PollDeps) { this.#deps = deps; + this.#maxNextPollMs = Math.floor(deps.pollSubscriptionTtlMs / 2); this.#leases = new LeaseTable(deps.pollSubscriptionTtlMs, lease => { if (lease.terminated === undefined) void this.#unsubscribe(lease); }); @@ -134,6 +137,10 @@ export class PollSource implements SubscriptionSource { return this.#leases.size; } + countOf(principal: string | null): number { + return this.#leases.countOf(principal); + } + async handlePoll(params: PollEventsRequestParams, ctx: ServerContext): Promise { let key = ''; const { entry, principal, args } = await this.#deps.validator.validate('poll', params, ctx, (principal, rawArgs) => { @@ -160,11 +167,11 @@ export class PollSource implements SubscriptionSource { }); const checked = await Promise.all(read.events.map(occurrence => checkedSelection(entry, occurrence, this.#deps.report))); const events = checked.filter((occurrence): occurrence is EventOccurrence => occurrence !== undefined); - return { ...read, events, nextPollMs: this.#deps.defaultNextPollMs }; + return { ...read, events, nextPollMs: this.#nextPollMs(undefined) }; } const result = await check(makeContext({ ...fields, maxEvents, maxAgeMs: params.maxAgeMs }), args, cursor); - const nextPollMs = result.nextPollMs ?? this.#deps.defaultNextPollMs; + const nextPollMs = this.#nextPollMs(result.nextPollMs); // `null` starts from now on a new lease or for a type with replay; on a lease's later polls a type without replay gets its events. if (cursor === null && (created || result.cursor !== null)) { return { events: [], cursor: result.cursor, truncated: false, hasMore: false, nextPollMs }; @@ -191,6 +198,12 @@ export class PollSource implements SubscriptionSource { this.#starting.clear(); } + // Whole milliseconds, at least 0 and at most #maxNextPollMs; anything but a finite number sends the default. + #nextPollMs(value: number | undefined): number { + const ms = typeof value === 'number' && Number.isFinite(value) ? Math.max(0, Math.ceil(value)) : this.#deps.defaultNextPollMs; + return Math.min(ms, this.#maxNextPollMs); + } + // A terminated lease answers its error once, then is gone. #throwTerminated(key: string): void { const terminated = this.#leases.get(key)?.terminated; @@ -209,7 +222,7 @@ export class PollSource implements SubscriptionSource { const pending = this.#starting.get(key); // Await only a pending start: an unconditional await would let a concurrent first poll in before `touch`. if (pending !== undefined) await pending; - if (this.#leases.get(key) === undefined) this.#deps.validator.assertCapacity(); + if (this.#leases.get(key) === undefined) this.#deps.validator.assertCapacity(principal); const { lease, created } = this.#leases.touch(key, () => ({ subscriptionId: globalThis.crypto.randomUUID(), name: entry.name, diff --git a/packages/server/src/ext/events/push.ts b/packages/server/src/ext/events/push.ts index 823b4ddd92..fc5983f791 100644 --- a/packages/server/src/ext/events/push.ts +++ b/packages/server/src/ext/events/push.ts @@ -21,7 +21,7 @@ import type { BufferedEvent, EmitBuffer } from './emitBuffer'; import type { SubscriptionSource } from './extension'; import { checkedEvents, checkedSelection, selectEvent } from './poll'; import type { RegisteredEvent } from './registry'; -import type { CheckContext, EventResult } from './types'; +import type { CheckContext, EventContext, EventResult } from './types'; import type { SubscriptionValidator } from './validation'; // The shortest heartbeat granted, whatever the client suggests (D33). @@ -126,6 +126,34 @@ export async function startCheck( return checkedBatch(entry, from, result, maxAgeMs, report); } +// Where an emit-only type starts: `null` is the buffer head, a cursor replays the buffer since it, each event at its own position. +export function replayBuffer( + buffer: EmitBuffer, + entry: RegisteredEvent, + ctx: EventContext, + args: Record, + from: string | null, + maxAgeMs: number | undefined, + report: (error: unknown) => void +): Batch { + const { name } = entry; + if (from === null) { + const head = buffer.head(name); + return { cursor: head, truncated: false, events: [], position: head }; + } + const select = (buffered: BufferedEvent) => selectEvent(entry, ctx, args, buffered, report); + // `maxEvents: 0` finds where replay starts (after a gap or the `maxAgeMs` floor) without reading an event. + const start = buffer.read(name, from, { maxEvents: 0, maxAgeMs, select }); + const events: EventOccurrence[] = []; + let { cursor: position, hasMore } = start; + while (hasMore) { + const read = buffer.read(name, position, { maxEvents: 1, select }); + for (const occurrence of read.events) events.push({ ...occurrence, cursor: read.cursor }); + ({ cursor: position, hasMore } = read); + } + return { cursor: events.length === 0 ? position : start.cursor, truncated: start.truncated, events, position }; +} + // `events/stream`: one long-lived request per subscription, answered with `notifications/events/*` until it ends (SEP-3415 §Push). export class StreamSet implements SubscriptionSource { readonly #deps: PushDeps; @@ -139,9 +167,15 @@ export class StreamSet implements SubscriptionSource { return this.#streams.size; } + countOf(principal: string | null): number { + let count = 0; + for (const stream of this.#streams) if (stream.ctx.principal === principal) count += 1; + return count; + } + async open(params: StreamEventsRequestParams, ctx: ServerContext): Promise { const { entry, principal, args } = await this.#deps.validator.validate('push', params, ctx); - this.#deps.validator.assertCapacity(); + this.#deps.validator.assertCapacity(principal); const stream = this.#create(entry, principal, args, params, ctx); const result = { _meta: { [SUBSCRIPTION_ID_META_KEY]: ctx.mcpReq.id } }; try { @@ -168,7 +202,9 @@ export class StreamSet implements SubscriptionSource { } // Synchronous from the replay read to going live, so no emit falls between them. stream.live = true; - this.#send(stream, checked ?? this.#replay(stream, params), true); + const { buffer, report } = this.#deps; + const from = params.cursor ?? null; + this.#send(stream, checked ?? replayBuffer(buffer, stream.entry, stream.ctx, stream.args, from, params.maxAgeMs, report), true); this.#scheduleCheck(stream); await stream.done; return result; @@ -243,28 +279,6 @@ export class StreamSet implements SubscriptionSource { return stream; } - // Where an emit-only type starts: `null` is the buffer head, a cursor replays the buffer since it, each event at its own position. - #replay(stream: PushStream, params: StreamEventsRequestParams): Batch { - const { buffer, report } = this.#deps; - const { name } = stream.entry; - const from = params.cursor ?? null; - if (from === null) { - const head = buffer.head(name); - return { cursor: head, truncated: false, events: [], position: head }; - } - const select = (buffered: BufferedEvent) => selectEvent(stream.entry, stream.ctx, stream.args, buffered, report); - // `maxEvents: 0` finds where replay starts (after a gap or the `maxAgeMs` floor) without reading an event. - const start = buffer.read(name, from, { maxEvents: 0, maxAgeMs: params.maxAgeMs, select }); - const events: EventOccurrence[] = []; - let { cursor: position, hasMore } = start; - while (hasMore) { - const read = buffer.read(name, position, { maxEvents: 1, select }); - for (const occurrence of read.events) events.push({ ...occurrence, cursor: read.cursor }); - ({ cursor: position, hasMore } = read); - } - return { cursor: events.length === 0 ? position : start.cursor, truncated: start.truncated, events, position }; - } - #send(stream: PushStream, batch: Batch, active: boolean): void { if (active) { this.#write(stream, EVENTS_ACTIVE_NOTIFICATION, { @@ -305,14 +319,15 @@ export class StreamSet implements SubscriptionSource { this.#scheduleCheck(stream); } - // Params that resolve to `undefined` (a dropped event) send nothing. + // Params that resolve to `undefined` (a dropped event) send nothing; an event's own `_meta` keys stay beside the stream's id. #write(stream: PushStream, method: string, params: Record | Promise | undefined>): void { - const _meta = { [SUBSCRIPTION_ID_META_KEY]: stream.requestId }; // A failed write means the client is gone. stream.queue = stream.queue .then(async () => { const resolved = await params; - if (resolved !== undefined) await stream.notify({ method, params: { ...resolved, _meta } }); + if (resolved === undefined) return; + const _meta = { ...(resolved._meta as Record | undefined), [SUBSCRIPTION_ID_META_KEY]: stream.requestId }; + await stream.notify({ method, params: { ...resolved, _meta } }); }) .catch(() => void this.#end(stream)); if (!stream.live) return; diff --git a/packages/server/src/ext/events/types.ts b/packages/server/src/ext/events/types.ts index ba779bab6e..151564d624 100644 --- a/packages/server/src/ext/events/types.ts +++ b/packages/server/src/ext/events/types.ts @@ -70,7 +70,10 @@ export interface EventResult

> { events: EventInput

[]; /** Where the next `check` resumes; `null` when the upstream cannot resume. */ cursor: string | null; - /** How long a poll client should wait before polling again. */ + /** + * How long a poll client should wait before polling again. It is sent rounded up to whole milliseconds and at + * most half of `pollSubscriptionTtlMs`; a value that is not a finite number sends `defaultNextPollMs`. + */ nextPollMs?: number; /** The upstream lost history since the cursor it was given. Ignored with `cursor: null`, which has no position to skip past. */ truncated?: boolean; @@ -110,7 +113,11 @@ export interface CheckEventDefinition, cursor: string | null): EventResult> | Promise>>; match?: never; @@ -119,7 +126,8 @@ export interface CheckEventDefinition string | null | Promise; - /** Bounds of the in-memory buffer that emit-only event types are polled from. */ + /** Bounds of the in-memory buffer that emit-only event types are polled and replayed from. */ emitBuffer?: { maxAgeMs?: number; maxEvents?: number }; - /** How long a poll subscription lives without a poll. */ + /** How long a poll subscription lives without a poll. Every `nextPollMs` sent is at most half of it. */ pollSubscriptionTtlMs?: number; /** The push heartbeat interval granted when the client suggests none, and the longest granted. */ heartbeatMs?: number; /** How often `check` runs for push and webhook subscriptions. */ checkIntervalMs?: number; - /** The `nextPollMs` sent when `check` gives none. */ + /** The `nextPollMs` sent when `check` gives none, capped at half of `pollSubscriptionTtlMs`; setting it over that half throws `TypeError`. */ defaultNextPollMs?: number; /** * The most subscriptions this process serves at once, counting poll leases, push streams and the webhook - * subscriptions whose subscribe or refresh it handled or is still creating; more are refused with `resourceExhausted`. + * subscriptions whose subscribe or refresh it handled or is still creating; more are refused with `resourceExhausted` + * (`data.limit: 'subscriptions'`). With `getPrincipal` set, each principal may hold a quarter of them (at least + * one), and so may all callers without a principal together; more are refused with + * `data.limit: 'principalSubscriptions'`. Without `getPrincipal` only the process-wide limit applies. * @default 1024 */ maxSubscriptions?: number; diff --git a/packages/server/src/ext/events/validation.ts b/packages/server/src/ext/events/validation.ts index 82935b678a..1729fa51dd 100644 --- a/packages/server/src/ext/events/validation.ts +++ b/packages/server/src/ext/events/validation.ts @@ -5,6 +5,9 @@ import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; import type { EventRegistry, RegisteredEvent } from './registry'; import type { EventsOptions } from './types'; +// With `getPrincipal`, each principal, and the callers without one together, may hold this share of `maxSubscriptions`. +const PRINCIPAL_SHARE_DIVISOR = 4; + export interface ValidatorDeps { readonly registry: EventRegistry; readonly webhookEnabled: boolean; @@ -12,6 +15,8 @@ export interface ValidatorDeps { readonly maxSubscriptions: number; // Subscriptions this process serves now: poll leases, push streams, and the webhook subscriptions whose subscribe or refresh it handled or is still creating. subscriptionCount(): number; + // Those of them held by `principal` (`null`: the callers without one). + principalSubscriptionCount(principal: string | null): number; } function notOffered(message: string, mode: DeliveryMode): EventsError { @@ -58,11 +63,20 @@ export class SubscriptionValidator { return { entry, principal, args }; } - // The `maxSubscriptions` quota; call it before a new subscription's `onSubscribe`. - assertCapacity(): void { + // The `maxSubscriptions` quota and, with `getPrincipal`, the principal's share of it; call it before a new subscription's `onSubscribe`. + assertCapacity(principal: string | null): void { const max = this.#deps.maxSubscriptions; if (this.#deps.subscriptionCount() >= max) { throw new EventsError('resourceExhausted', 'Subscription limit reached', { limit: 'subscriptions', max }); } + // Without getPrincipal every caller is in one bucket, so a share would only shrink the quota. + if (this.#deps.getPrincipal === undefined) return; + const share = Math.max(1, Math.floor(max / PRINCIPAL_SHARE_DIVISOR)); + if (this.#deps.principalSubscriptionCount(principal) >= share) { + throw new EventsError('resourceExhausted', 'Subscription limit for this principal reached', { + limit: 'principalSubscriptions', + max: share + }); + } } } diff --git a/packages/server/src/ext/events/webhookEngine.ts b/packages/server/src/ext/events/webhookEngine.ts index 96a662654d..dc27fae520 100644 --- a/packages/server/src/ext/events/webhookEngine.ts +++ b/packages/server/src/ext/events/webhookEngine.ts @@ -23,11 +23,11 @@ const SUSPENSION_MIN_ATTEMPTS = 100; const SUSPENSION_FAILURE_PERCENT = 95; // A failed verification of a (principal, url) is answered again for this long without a POST. const FAILED_VERIFICATION_MS = 60_000; -// Verification POSTs to one destination host: one at a time, and at most 10 in any 60 s. +// Verification POSTs to one destination host: one at a time, and at most 10 in any 60 s; at most 10 more wait their turn. const VERIFICATIONS_PER_WINDOW = 10; const VERIFICATION_WINDOW_MS = 60_000; -// The retry hint while another verification to the host is in flight: nodeWebhookSender's 5 s timeout. -const IN_FLIGHT_RETRY_MS = 5000; +// The retry hint when the host's wait is full: nodeWebhookSender's 5 s timeout, by when the verification in flight has ended. +const QUEUE_FULL_RETRY_MS = 5000; // The most failed pairs and destination hosts the verification limits remember. const MAX_REMEMBERED = 10_000; @@ -87,9 +87,17 @@ interface Tracked { recentFailures: number; } -// One destination host's verification POSTs: whether one is in flight, and the send times of the last window, oldest first. +// One `principal\0url` handshake in flight: the subscribes waiting for it, and the abort that pulls it from the host's queue once all of them were cancelled. +interface Handshake { + readonly done: Promise; + readonly abandoned: AbortController; + callers: number; +} + +// One destination host's verification POSTs: whether one holds the slot, the verifications waiting for it (oldest first), and the send times of the last window, oldest first. interface HostVerifications { inFlight: boolean; + readonly waiting: Array<{ resolve(): void; reject(error: unknown): void }>; readonly sent: number[]; } @@ -155,6 +163,17 @@ function verificationError(reason: DeliveryErrorCategory): EventsError { return new EventsError('callbackEndpointError', `Webhook endpoint verification failed: ${reason}`, { reason }); } +// Settles as `promise` does, or rejects with its reason once `signal` aborts. +function untilAborted(promise: Promise, signal: AbortSignal | undefined): Promise { + if (signal === undefined) return promise; + return new Promise((resolve, reject) => { + const abort = (): void => reject(signal.reason); + if (signal.aborted) abort(); + signal.addEventListener('abort', abort, { once: true }); + promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort)); + }); +} + function verificationLimit(retryAfterMs: number): EventsError { return new EventsError('resourceExhausted', 'Too many webhook endpoint verifications for this host', { limit: 'verification', @@ -175,7 +194,7 @@ export class WebhookEngine { readonly #verified = new Map>(); readonly #verifiedKeyOf = new Map(); // Each `principal\0url` handshake in flight, which another subscribe of the pair waits for. - readonly #handshakes = new Map>(); + readonly #handshakes = new Map(); // Each `principal\0url` whose verification failed lately: the failure, and until when it is answered without a POST. readonly #failed = new Map(); // By lower-cased destination hostname (SEP-3415: rate-limited per destination host). @@ -196,10 +215,10 @@ export class WebhookEngine { return this.#tracked.size; } - // One attempt, which the subscribe call waits for; throws `callbackEndpointError` with the failure category as `data.reason`, or `resourceExhausted` at the host's limit. - async verify(principal: string, url: string, secret: string, subscriptionId: string): Promise { + // One attempt, which the subscribe call waits for, after the host's verification in flight; throws `callbackEndpointError` with the failure category as `data.reason`, or `resourceExhausted` at the host's limit. + async verify(principal: string, url: string, secret: string, subscriptionId: string, signal?: AbortSignal): Promise { const key = `${principal}\u0000${url}`; - if (!this.#verified.has(key)) await this.#verifyPair(key, url, secret, subscriptionId); + if (!this.#verified.has(key)) await this.#verifyPair(key, url, secret, subscriptionId, signal); let covered = this.#verified.get(key); if (covered === undefined) { covered = new Set(); @@ -294,29 +313,39 @@ export class WebhookEngine { this.#verifiedKeyOf.clear(); this.#handshakes.clear(); this.#failed.clear(); + for (const host of this.#hosts.values()) + for (const waiter of host.waiting.splice(0)) waiter.reject(verificationLimit(QUEUE_FULL_RETRY_MS)); this.#hosts.clear(); this.#lifetime?.abort(); this.#lifetime = undefined; } - // The pair's handshake in flight, or a new one. - #verifyPair(key: string, url: string, secret: string, subscriptionId: string): Promise { - const pending = this.#handshakes.get(key); - if (pending !== undefined) return pending; - const handshake = this.#handshake(key, url, secret, subscriptionId).finally(() => { - if (this.#handshakes.get(key) === handshake) this.#handshakes.delete(key); - }); - this.#handshakes.set(key, handshake); - return handshake; + // The pair's handshake in flight, or a new one; `signal` (the subscribe request's) stops this caller waiting for it. + async #verifyPair(key: string, url: string, secret: string, subscriptionId: string, signal: AbortSignal | undefined): Promise { + let handshake = this.#handshakes.get(key); + if (handshake === undefined) { + const abandoned = new AbortController(); + const done = this.#handshake(key, url, secret, subscriptionId, abandoned.signal).finally(() => { + if (this.#handshakes.get(key)?.done === done) this.#handshakes.delete(key); + }); + handshake = { done, abandoned, callers: 0 }; + this.#handshakes.set(key, handshake); + } + handshake.callers += 1; + try { + await untilAborted(handshake.done, signal); + } finally { + handshake.callers -= 1; + if (handshake.callers === 0 && signal?.aborted === true) handshake.abandoned.abort(signal.reason); + } } - // One verification POST, unless a failure of the pair is still remembered or the host is at its limit. - async #handshake(key: string, url: string, secret: string, subscriptionId: string): Promise { - const now = this.#now(); + // One verification POST, unless a failure of the pair is still remembered, the host is at its limit, or every subscribe waiting for it was cancelled while it queued. + async #handshake(key: string, url: string, secret: string, subscriptionId: string, abandoned: AbortSignal): Promise { const failed = this.#failed.get(key); - if (failed !== undefined && now < failed.until) throw verificationError(failed.reason); + if (failed !== undefined && this.#now() < failed.until) throw verificationError(failed.reason); this.#failed.delete(key); - const host = this.#claimHost(url, now); + const host = await this.#claimHost(url, abandoned); this.#lifetime ??= new AbortController(); const { signal } = this.#lifetime; try { @@ -334,28 +363,72 @@ export class WebhookEngine { } throw verificationError(reason); } finally { - host.inFlight = false; + this.#releaseHost(host); } } - // Takes the host's one verification slot and counts the POST, or throws `resourceExhausted` with a retry hint. - #claimHost(url: string, now: number): HostVerifications { + // Waits for the host's one verification slot, leaving the queue when `abandoned` aborts, then counts the POST; throws `resourceExhausted` with a retry hint when the wait or the window is full. + async #claimHost(url: string, abandoned: AbortSignal): Promise { const name = new URL(url).hostname.toLowerCase(); - const start = now - VERIFICATION_WINDOW_MS; let host = this.#hosts.get(name); if (host === undefined) { - host = { inFlight: false, sent: [] }; + host = { inFlight: false, waiting: [], sent: [] }; + const start = this.#now() - VERIFICATION_WINDOW_MS; remember(this.#hosts, name, host, held => !held.inFlight && (held.sent.at(-1) ?? start) <= start); } + if (host.inFlight) { + if (host.waiting.length >= VERIFICATIONS_PER_WINDOW) throw verificationLimit(QUEUE_FULL_RETRY_MS); + await this.#waitTurn(host, abandoned); + // Handed the slot just as it was abandoned: pass it on without a POST. + if (abandoned.aborted) { + this.#releaseHost(host); + throw abandoned.reason; + } + } else { + host.inFlight = true; + } + const now = this.#now(); + const start = now - VERIFICATION_WINDOW_MS; const { sent } = host; while (sent[0] !== undefined && sent[0] <= start) sent.shift(); - if (host.inFlight) throw verificationLimit(IN_FLIGHT_RETRY_MS); - if (sent.length >= VERIFICATIONS_PER_WINDOW) throw verificationLimit(sent[0]! - start); - host.inFlight = true; + if (sent.length >= VERIFICATIONS_PER_WINDOW) { + this.#releaseHost(host); + throw verificationLimit(sent[0]! - start); + } sent.push(now); return host; } + // Resolves holding the slot, which #releaseHost hands over; rejects at once, out of the queue, when `abandoned` aborts. + #waitTurn(host: HostVerifications, abandoned: AbortSignal): Promise { + return new Promise((resolve, reject) => { + const leave = (): void => { + const index = host.waiting.indexOf(waiter); + if (index !== -1) host.waiting.splice(index, 1); + reject(abandoned.reason); + }; + const waiter = { + resolve: () => { + abandoned.removeEventListener('abort', leave); + resolve(); + }, + reject: (error: unknown) => { + abandoned.removeEventListener('abort', leave); + reject(error); + } + }; + host.waiting.push(waiter); + abandoned.addEventListener('abort', leave, { once: true }); + }); + } + + // Hands the host's slot to the verification that waited longest, or frees it. + #releaseHost(host: HostVerifications): void { + const next = host.waiting.shift(); + if (next === undefined) host.inFlight = false; + else next.resolve(); + } + #start(id: string, watermark: string | null): Tracked { const tracked: Tracked = { id, @@ -409,7 +482,9 @@ export class WebhookEngine { this.#park(tracked, message); return; } - const body = JSON.stringify({ ...message.occurrence, cursor: tracked.watermark }); + // Its own position once every event before it is settled (SEP-3415: cursor_N rides on event N then), else the watermark. + const cursor = tracked.pending[0] === message ? message.position : tracked.watermark; + const body = JSON.stringify({ ...message.occurrence, cursor }); if (byteLength(body) > MAX_BODY_BYTES) { this.#onerror( new Error( diff --git a/packages/server/src/ext/events/webhookSubscriptions.ts b/packages/server/src/ext/events/webhookSubscriptions.ts index a083e42f99..f35b9b9a14 100644 --- a/packages/server/src/ext/events/webhookSubscriptions.ts +++ b/packages/server/src/ext/events/webhookSubscriptions.ts @@ -12,7 +12,7 @@ import type { BufferedEvent, EmitBuffer } from './emitBuffer'; import type { SubscriptionSource } from './extension'; import { checkedSelection, selectEvent } from './poll'; import type { Batch } from './push'; -import { checkedBatch, errorObject, startCheck, TERMINAL_KINDS } from './push'; +import { checkedBatch, errorObject, replayBuffer, startCheck, TERMINAL_KINDS } from './push'; import type { EventRegistry, RegisteredEvent } from './registry'; import type { CheckContext, WebhookSender, WebhookSubscriptionRecord, WebhookSubscriptionStore } from './types'; import type { SubscriptionValidator, ValidSubscription } from './validation'; @@ -66,6 +66,9 @@ interface Watched { interface Subscribing { readonly id: string; readonly name: string; + readonly principal: string; + // Aborts when the client cancels the request. + readonly signal: AbortSignal; // A termination that reached it meanwhile, which the request applies before or after its write. terminated?: EventsError; } @@ -149,6 +152,14 @@ export class WebhookSubscriptions implements SubscriptionSource { return this.#watched.size + this.#starting.size; } + // Those of them `principal` holds. + countOf(principal: string | null): number { + let count = 0; + for (const watched of this.#watched.values()) if (watched.ctx.principal === principal) count += 1; + for (const subscribing of this.#starting) if (subscribing.principal === principal) count += 1; + return count; + } + // Subscriptions this process watches (an expiry timer each), after handling their subscribe or refresh. get watching(): number { return this.#watched.size; @@ -170,7 +181,7 @@ export class WebhookSubscriptions implements SubscriptionSource { // validate('webhook', …) refuses a request without a principal. const id = await subscriptionIdOf(valid.principal!, url, valid.entry.name, params.arguments ?? {}); const ttl = grantMs(params.ttlMs, this.#deps.webhookTtlMs); - const subscribing: Subscribing = { id, name: valid.entry.name }; + const subscribing: Subscribing = { id, name: valid.entry.name, principal: valid.principal!, signal: ctx.mcpReq.signal }; this.#subscribing.add(subscribing); try { return await enqueue(this.#byId, id, async () => { @@ -261,11 +272,11 @@ export class WebhookSubscriptions implements SubscriptionSource { const { url, secret } = params.delivery; // A watch left over here belongs to a subscription that ended elsewhere: its record is gone. this.#release(id); - this.#deps.validator.assertCapacity(); + this.#deps.validator.assertCapacity(principal); // Counted from the quota check on, so concurrent creates cannot all pass it; the watch takes the count over in one step. this.#starting.add(subscribing); try { - await this.#engine.verify(principal, url, secret, id); + await this.#engine.verify(principal, url, secret, id, subscribing.signal); const watched = this.#watch(id, entry, principal); try { await entry.definition.onSubscribe?.(watched.ctx, args); @@ -291,7 +302,7 @@ export class WebhookSubscriptions implements SubscriptionSource { start = entry.kind === 'check' ? await this.#startCheck(record, watched, from, params.maxAgeMs, subscribing) - : await enqueue(this.#byName, entry.name, () => this.#startEmitOnly(record, from, subscribing)); + : await this.#startEmitOnly(record, watched, from, params.maxAgeMs, subscribing); const terminated = takeTermination(subscribing); if (terminated !== undefined) { await this.#deps.store.delete(id); @@ -331,14 +342,25 @@ export class WebhookSubscriptions implements SubscriptionSource { return start; } - // Runs in line with the fan-out: an emit either comes before the head read here or finds the stored record. Nothing is replayed. - async #startEmitOnly(record: WebhookSubscriptionRecord, from: string | null, subscribing: Subscribing): Promise { - const terminated = takeTermination(subscribing); - if (terminated !== undefined) throw terminated; - const head = this.#deps.buffer.head(record.name); - this.#engine.track(record.id, head); - await this.#deps.store.put(record); - return { cursor: head, truncated: from !== null && from !== head, events: [], position: head }; + // Reads the replay as it queues behind the fan-out, so an emit is either replayed or finds the stored record; the replay reaches the engine before the next fan-out. + #startEmitOnly( + record: WebhookSubscriptionRecord, + watched: Watched, + from: string | null, + maxAgeMs: number | undefined, + subscribing: Subscribing + ): Promise { + const { buffer, report } = this.#deps; + const replay = replayBuffer(buffer, watched.entry, watched.ctx, record.arguments, from, maxAgeMs, report); + return enqueue(this.#byName, record.name, async () => { + const terminated = takeTermination(subscribing); + if (terminated !== undefined) throw terminated; + this.#engine.track(record.id, replay.cursor); + await this.#deps.store.put(record); + const checked = await Promise.all(replay.events.map(event => checkedSelection(watched.entry, event, report))); + for (const event of checked) if (event !== undefined) this.#engine.deliver(record, event, event.cursor ?? null, replay.cursor); + return { ...replay, events: [] }; + }); } // A new grant and a rotated secret; the client's cursor seeds the watermark only where this process tracks none. diff --git a/packages/server/test/ext/events/node.test.ts b/packages/server/test/ext/events/node.test.ts index afa9f0d790..79032e4356 100644 --- a/packages/server/test/ext/events/node.test.ts +++ b/packages/server/test/ext/events/node.test.ts @@ -30,6 +30,7 @@ const REFUSED = { error: 'connection_refused' }; const servers: net.Server[] = []; afterEach(async () => { + vi.useRealTimers(); vi.restoreAllMocks(); vi.mocked(isSpecialPurposeAddress).mockReset(); await Promise.all( @@ -65,14 +66,42 @@ function sendRequest(url: string, trusted: boolean, signal = new AbortController return { url, headers: HEADERS, body: BODY, trusted, signal }; } -// Each call of dns.promises.lookup answers with the next list of addresses; a call past them fails with ENOTFOUND. -function stubLookup(...answers: string[][]): MockInstance { - const lookup = vi.spyOn(dns.promises, 'lookup') as unknown as MockInstance< - (hostname: string, options: dns.LookupAllOptions) => Promise - >; - lookup.mockRejectedValue(Object.assign(new Error('getaddrinfo ENOTFOUND'), { code: 'ENOTFOUND' })); - for (const answer of answers) lookup.mockResolvedValueOnce(answer.map(address => ({ address, family: net.isIP(address) }))); - return lookup; +type Resolve = MockInstance<(hostname: string) => Promise>; + +function dnsError(code: string): Error { + return Object.assign(new Error(`query ${code}`), { code }); +} + +// Each send's resolve4 and resolve6 answer with the next list's addresses of their family, ENODATA without any; past the lists both fail with ENOTFOUND. +function stubResolver(...answers: string[][]): { resolve4: Resolve; resolve6: Resolve } { + const stub = (method: 'resolve4' | 'resolve6', family: number): Resolve => { + const spy = vi.spyOn(dns.promises.Resolver.prototype, method) as unknown as Resolve; + spy.mockRejectedValue(dnsError('ENOTFOUND')); + for (const answer of answers) { + const addresses = answer.filter(address => net.isIP(address) === family); + if (addresses.length === 0) spy.mockRejectedValueOnce(dnsError('ENODATA')); + else spy.mockResolvedValueOnce(addresses); + } + return spy; + }; + return { resolve4: stub('resolve4', 4), resolve6: stub('resolve6', 6) }; +} + +// Stands in for https.request: records the address its pinned lookup gives, and fails the connection. +function captureConnection(): { pinned: () => Promise<{ address: string; family: number }> } { + let lookup: net.LookupFunction | undefined; + vi.spyOn(https, 'request').mockImplementation(((_url: URL, options: https.RequestOptions) => { + lookup = options.lookup as net.LookupFunction; + return failingRequest('ECONNREFUSED'); + }) as unknown as typeof https.request); + return { + pinned: () => + new Promise((resolve, reject) => + lookup!('pinned.invalid', {}, (error, address, family) => + error ? reject(error) : resolve({ address: address as string, family: family! }) + ) + ) + }; } // Classifies `ip` as a public address, so a loopback server can stand in for a remote receiver. @@ -128,27 +157,70 @@ describe('nodeWebhookSender', () => { expect(receiver.connections()).toBe(0); }); - it('checks the address of an IPv6 literal host', async () => { - const lookup = vi.spyOn(dns.promises, 'lookup'); + it('checks an IP literal host without resolving it', async () => { + const { resolve4, resolve6 } = stubResolver(); + const connection = captureConnection(); expect(await nodeWebhookSender()(sendRequest('https://[::1]:8443/x', false))).toEqual(REFUSED); - expect(lookup).toHaveBeenCalledWith('::1', { all: true }); + expect(isSpecialPurposeAddress).toHaveBeenCalledWith('::1'); + expect(https.request).not.toHaveBeenCalled(); + expect(await nodeWebhookSender()(sendRequest('https://1.1.1.1:8443/x', false))).toEqual(REFUSED); + expect(await connection.pinned()).toEqual({ address: '1.1.1.1', family: 4 }); + expect(resolve4).not.toHaveBeenCalled(); + expect(resolve6).not.toHaveBeenCalled(); }); it('refuses http for an untrusted origin', async () => { - const lookup = stubLookup(); + const { resolve4 } = stubResolver(); expect(await nodeWebhookSender()(sendRequest('http://example.com/hooks', false))).toEqual(REFUSED); - expect(lookup).not.toHaveBeenCalled(); + expect(resolve4).not.toHaveBeenCalled(); }); - it('refuses when any resolved address is special, without connecting', async () => { + it('refuses when any resolved address, of either family, is special, without connecting', async () => { const receiver = await countingServer(); await treatAsPublic('127.0.0.1'); - stubLookup(['127.0.0.1', '10.0.0.1']); + stubResolver(['127.0.0.1', '10.0.0.1'], ['127.0.0.1', 'fe80::1'], ['2606:4700:4700::1111']); + const send = nodeWebhookSender(); - expect(await nodeWebhookSender()(sendRequest(`https://hooks.example.test:${receiver.port}/x`, false))).toEqual(REFUSED); + expect(await send(sendRequest(`https://hooks.example.test:${receiver.port}/x`, false))).toEqual(REFUSED); + expect(await send(sendRequest(`https://hooks.example.test:${receiver.port}/x`, false))).toEqual(REFUSED); expect(receiver.connections()).toBe(0); + const connection = captureConnection(); + expect(await send(sendRequest('https://hooks.example.test/x', false))).toEqual(REFUSED); + expect(await connection.pinned()).toEqual({ address: '2606:4700:4700::1111', family: 6 }); + }); + + it('uses an AAAA answer for a host without A records, and fails when neither family resolves', async () => { + const { resolve4, resolve6 } = stubResolver(['2606:4700:4700::1111']); + const connection = captureConnection(); + const send = nodeWebhookSender(); + + expect(await send(sendRequest('https://v6only.example.test/x', false))).toEqual(REFUSED); + expect(await connection.pinned()).toEqual({ address: '2606:4700:4700::1111', family: 6 }); + expect(resolve4).toHaveBeenCalledWith('v6only.example.test'); + expect(resolve6).toHaveBeenCalledWith('v6only.example.test'); + vi.mocked(https.request).mockClear(); + expect(await send(sendRequest('https://nowhere.example.test/x', false))).toEqual(REFUSED); + expect(https.request).not.toHaveBeenCalled(); + }); + + it('cancels resolution at the 5 s deadline and reports a timeout', async () => { + vi.useFakeTimers(); + const pending: Array<(error: Error) => void> = []; + const hang = () => new Promise((_resolve, reject) => pending.push(reject)); + vi.spyOn(dns.promises.Resolver.prototype, 'resolve4').mockImplementation(hang); + vi.spyOn(dns.promises.Resolver.prototype, 'resolve6').mockImplementation(hang); + const cancel = vi.spyOn(dns.promises.Resolver.prototype, 'cancel').mockImplementation(() => { + for (const reject of pending.splice(0)) reject(dnsError('ECANCELLED')); + }); + + const outcome = nodeWebhookSender()(sendRequest('https://silent.example.test/x', false)); + await vi.advanceTimersByTimeAsync(4999); + expect(cancel).not.toHaveBeenCalled(); + await vi.advanceTimersByTimeAsync(1); + expect(await outcome).toEqual({ error: 'timeout' }); + expect(cancel).toHaveBeenCalledOnce(); }); it('connects to the checked address and sends the URL host name as TLS SNI', async () => { @@ -162,18 +234,18 @@ describe('nodeWebhookSender', () => { ) ); await treatAsPublic('127.0.0.1'); - const lookup = stubLookup(['127.0.0.1']); + const { resolve4 } = stubResolver(['127.0.0.1']); // The receiver resets the connection after reading the ClientHello. expect(await nodeWebhookSender()(sendRequest(`https://hooks.example.test:${port}/x`, false))).toEqual(REFUSED); - expect(lookup).toHaveBeenCalledWith('hooks.example.test', { all: true }); + expect(resolve4).toHaveBeenCalledWith('hooks.example.test'); expect(clientHello?.includes('hooks.example.test')).toBe(true); }); it('checks the resolved address at every send', async () => { const receiver = await countingServer(); await treatAsPublic('127.0.0.1'); - stubLookup(['127.0.0.1'], ['10.0.0.1']); + stubResolver(['127.0.0.1'], ['10.0.0.1']); const send = nodeWebhookSender(); await send(sendRequest(`https://hooks.example.test:${receiver.port}/x`, false)); diff --git a/packages/server/test/ext/events/poll.test.ts b/packages/server/test/ext/events/poll.test.ts index 076d3a59f5..9b98c83ac7 100644 --- a/packages/server/test/ext/events/poll.test.ts +++ b/packages/server/test/ext/events/poll.test.ts @@ -1,3 +1,4 @@ +import { PollEventsResultSchema } from '@modelcontextprotocol/core/ext/events'; import { afterEach, describe, expect, it, vi } from 'vitest'; import * as z from 'zod/v4'; @@ -88,6 +89,32 @@ describe('events/poll for a check type', () => { expect(result).toMatchObject({ cursor: 'h2', truncated: false, hasMore: false, nextPollMs: 5000 }); }); + it.each([ + [5062.5, 5063], + [-1, 0], + [Number.NaN, 1000], + [Number.POSITIVE_INFINITY, 1000] + ])('sends a nextPollMs of %s from check as %i, which the wire schema accepts', async (given, sent) => { + const events = new EventsExtension({ defaultNextPollMs: 1000 }); + events.registerEvent('t', { payloadSchema: P, check: () => ({ events: [], cursor: 'h1', nextPollMs: given }) }); + const result = await poller(events).poll({ name: 't', cursor: 'h0' }); + expect(result.nextPollMs).toBe(sent); + expect(PollEventsResultSchema.safeParse(result).success).toBe(true); + }); + + it('caps nextPollMs at half of pollSubscriptionTtlMs, so a client that follows it keeps its lease', async () => { + // The default nextPollMs (30 s) is over half of this TTL, so it is capped too. + const events = new EventsExtension({ pollSubscriptionTtlMs: 50_001 }); + let nextPollMs: number | undefined = 600_000; + events.registerEvent('t', { payloadSchema: P, check: () => ({ events: [], cursor: 'h1', nextPollMs }) }); + events.registerEvent('i', { emitOnly: true, payloadSchema: P }); + const { poll } = poller(events); + expect((await poll({ name: 't', cursor: 'h0' })).nextPollMs).toBe(25_000); + nextPollMs = undefined; + expect((await poll({ name: 't', cursor: 'h0' })).nextPollMs).toBe(25_000); + expect((await poll({ name: 'i', cursor: null })).nextPollMs).toBe(25_000); + }); + it('passes hasMore and truncated through from check', async () => { const events = new EventsExtension(); events.registerEvent('t', { payloadSchema: P, check: () => ({ events: [], cursor: 'h2', hasMore: true, truncated: true }) }); @@ -501,6 +528,68 @@ describe('poll leases', () => { expect(onSubscribe.mock.calls.map(([ctx]) => (ctx as EventContext).principal)).toEqual(['u1', 'u2']); }); + it('serves callers that share a lease as one subscription of a type without replay, as documented', async () => { + const events = new EventsExtension(); + // An upstream without replay: each check(null) returns what happened since the previous call for the subscription. + const happened: number[] = []; + const read = new Map(); + events.registerEvent('pulse', { + payloadSchema: P, + check: ctx => { + const fresh = happened.slice(read.get(ctx.subscriptionId) ?? happened.length); + read.set(ctx.subscriptionId, happened.length); + return { events: fresh.map(n => ({ eventId: `e${n}`, data: { n } })), cursor: null }; + } + }); + const ids = async (client: ReturnType) => (await client.poll({ name: 'pulse' })).events.map(event => event.eventId); + const [first, second] = [poller(events), poller(events)]; + + expect(await ids(first)).toEqual([]); + happened.push(1); + // Without getPrincipal both share the lease: the second's first poll returns an event from before it subscribed. + expect(await ids(second)).toEqual(['e1']); + happened.push(2); + expect(await ids(first)).toEqual(['e2']); + expect(await ids(second)).toEqual([]); + expect(read.size).toBe(1); + }); + + it('holds each principal to a quarter of maxSubscriptions, the callers without one together, freed as leases end', async () => { + vi.useFakeTimers(); + const events = new EventsExtension({ + maxSubscriptions: 8, + pollSubscriptionTtlMs: 10_000, + defaultNextPollMs: 5000, + getPrincipal: ctx => (ctx.http?.authInfo?.extra?.sub as string | undefined) ?? null + }); + const handle = events.registerEvent('t', { payloadSchema: P, check: tick }); + const as = (sub: string | null) => + poller(events, sub === null ? {} : { authInfo: { token: 'tok', clientId: 'client', scopes: [], extra: { sub } } }); + const share = { code: -32_025, data: { limit: 'principalSubscriptions', max: 2 } }; + const [alice, bob, anonymous, other] = [as('alice'), as('bob'), as(null), as(null)]; + + await alice.poll({ name: 't', arguments: { a: 1 } }); + await alice.poll({ name: 't', arguments: { a: 2 } }); + expect(await alice.fail({ name: 't', arguments: { a: 3 } })).toMatchObject(share); + // A lease alice already holds still renews, and bob still subscribes. + await alice.poll({ name: 't', arguments: { a: 1 } }); + await bob.poll({ name: 't', arguments: { a: 1 } }); + + // Every caller without a principal shares one bucket. + await anonymous.poll({ name: 't', arguments: { a: 1 } }); + await other.poll({ name: 't', arguments: { a: 2 } }); + expect(await anonymous.fail({ name: 't', arguments: { a: 3 } })).toMatchObject(share); + + // A terminated lease frees its place once its error is answered, and an expired one at its expiry. + await handle.terminate(new EventsError('forbidden', 'Forbidden')); + expect(await alice.fail({ name: 't', arguments: { a: 1 } })).toMatchObject({ code: -32_024 }); + await alice.poll({ name: 't', arguments: { a: 3 } }); + await vi.advanceTimersByTimeAsync(10_001); + expect(testHook(events).state().pollLeases).toBe(0); + await anonymous.poll({ name: 't', arguments: { a: 3 } }); + await anonymous.poll({ name: 't', arguments: { a: 4 } }); + }); + it('runs onSubscribe once for concurrent first polls of one lease', async () => { let release!: () => void; const onSubscribe = vi.fn(() => new Promise(resolve => (release = resolve))); diff --git a/packages/server/test/ext/events/push.test.ts b/packages/server/test/ext/events/push.test.ts index 907b7c0470..bf52872eeb 100644 --- a/packages/server/test/ext/events/push.test.ts +++ b/packages/server/test/ext/events/push.test.ts @@ -124,7 +124,7 @@ describe('events/stream: opening', () => { expect(await fail({ name: 'i', arguments: { deny: true } })).toMatchObject({ code: -32_024, data: { reason: 'denied' } }); expect(testHook(events).state().pushStreams).toBe(0); - // maxSubscriptions counts poll leases and push streams together. + // maxSubscriptions counts poll leases and push streams together; without getPrincipal no per-principal share applies. resultOf(await served.rpc('events/poll', { name: 'i', arguments: { a: 1 } })); await next(await open(served, { name: 'i', arguments: { a: 2 } })); expect(await fail({ name: 'i', arguments: { a: 3 } })).toMatchObject({ code: -32_025, data: { limit: 'subscriptions', max: 2 } }); @@ -550,6 +550,38 @@ describe('events/stream: termination', () => { expect(await next(first)).toMatchObject({ params: { eventId: 'still' } }); }); + it("frees a stream's place in its principal's share when it ends, by termination, by the client or by a refused start", async () => { + let refuse = false; + const events = new EventsExtension({ maxSubscriptions: 4, getPrincipal: () => 'alice' }); + const handle = events.registerEvent('i', { + emitOnly: true, + payloadSchema: P, + onSubscribe: () => { + if (refuse) throw new EventsError('forbidden', 'Forbidden'); + } + }); + const served = serve(events); + const share = { code: -32_025, data: { limit: 'principalSubscriptions', max: 1 } }; + const refusal = async () => errorOf(await served.rpc('events/stream', { name: 'i', cursor: null })); + + const first = await open(served, { name: 'i', cursor: null }); + await next(first); + expect(await refusal()).toMatchObject(share); + await handle.terminate(new EventsError('forbidden', 'Forbidden')); + await rest(first); + + const second = await open(served, { name: 'i', cursor: null }); + await next(second); + expect(await refusal()).toMatchObject(share); + second.abort(); + await vi.waitFor(() => expect(testHook(events).state().pushStreams).toBe(0)); + + refuse = true; + expect(await refusal()).toMatchObject({ code: -32_024 }); + refuse = false; + await next(await open(served, { name: 'i', cursor: null })); + }); + it('closes open streams on a simulated restart and fires onUnsubscribe', async () => { const onUnsubscribe = vi.fn(); const events = new EventsExtension(); diff --git a/packages/server/test/ext/events/registration.test.ts b/packages/server/test/ext/events/registration.test.ts index 28317ef18a..5bad5661b9 100644 --- a/packages/server/test/ext/events/registration.test.ts +++ b/packages/server/test/ext/events/registration.test.ts @@ -122,13 +122,25 @@ describe('options', () => { expect(() => new EventsExtension({ webhookTtlMs: value, webhookSender, getPrincipal: () => 'alice' })).toThrow(TypeError); }); - it.each([1.5, 0.5])('refuses %s for a count option', value => { + it.each([1.5, 0.5])('refuses %s for a count option and for a duration clients receive', value => { expect(() => new EventsExtension({ maxSubscriptions: value })).toThrow(/maxSubscriptions must be a positive integer/); expect(() => new EventsExtension({ emitBuffer: { maxEvents: value } })).toThrow(TypeError); - expect(() => new EventsExtension({ heartbeatMs: value })).not.toThrow(); + expect(() => new EventsExtension({ heartbeatMs: value })).toThrow(/heartbeatMs must be a positive integer/); + expect(() => new EventsExtension({ defaultNextPollMs: value })).toThrow(TypeError); + expect(() => new EventsExtension({ webhookTtlMs: value, webhookSender, getPrincipal: () => 'alice' })).toThrow(TypeError); + expect(() => new EventsExtension({ checkIntervalMs: value, pollSubscriptionTtlMs: 60_000 + value })).not.toThrow(); + }); + + it('refuses a defaultNextPollMs set over half of pollSubscriptionTtlMs, and caps a defaulted one instead', () => { + expect(() => new EventsExtension({ pollSubscriptionTtlMs: 10_000, defaultNextPollMs: 5001 })).toThrow( + 'defaultNextPollMs (5001) must be at most half of pollSubscriptionTtlMs (10000)' + ); + expect(() => new EventsExtension({ pollSubscriptionTtlMs: 10_001, defaultNextPollMs: 5001 })).toThrow(TypeError); + expect(() => new EventsExtension({ pollSubscriptionTtlMs: 10_000, defaultNextPollMs: 5000 })).not.toThrow(); + expect(() => new EventsExtension({ pollSubscriptionTtlMs: 50_000 })).not.toThrow(); }); - it('serves at most 1024 subscriptions by default', async () => { + it('serves at most 1024 subscriptions by default, and without getPrincipal no share limits them', async () => { const events = new EventsExtension(); events.registerEvent('tick', { payloadSchema: P, check: tick }); const { rpc } = serve(events); @@ -140,6 +152,27 @@ describe('options', () => { resultOf(await rpc('events/poll', { name: 'tick', arguments: { n: 0 } })); }); + it('serves 256 subscriptions of the default 1024 to each principal when getPrincipal is set', async () => { + const events = new EventsExtension({ getPrincipal: ctx => (ctx.http?.authInfo?.extra?.sub as string | undefined) ?? null }); + events.registerEvent('tick', { payloadSchema: P, check: tick }); + const as = (sub: string) => serve(events, { authInfo: { token: 'tok', clientId: 'client', scopes: [], extra: { sub } } }).rpc; + const fill = async (rpc: ReturnType) => { + for (let n = 0; n < 256; n++) resultOf(await rpc('events/poll', { name: 'tick', arguments: { n } })); + }; + const u1 = as('u1'); + await fill(u1); + expect(errorOf(await u1('events/poll', { name: 'tick', arguments: { n: 256 } }))).toMatchObject({ + code: -32_025, + data: { limit: 'principalSubscriptions', max: 256 } + }); + for (const sub of ['u2', 'u3', 'u4']) await fill(as(sub)); + expect(errorOf(await as('u5')('events/poll', { name: 'tick', arguments: { n: 0 } }))).toMatchObject({ + code: -32_025, + data: { limit: 'subscriptions', max: 1024 } + }); + resultOf(await u1('events/poll', { name: 'tick', arguments: { n: 0 } })); + }); + it('accepts only exact origins as trustedOrigins', () => { expect(() => new EventsExtension({ trustedOrigins: ['http://127.0.0.1:9000', 'https://example.com'] })).not.toThrow(); for (const origin of ['http://127.0.0.1:9000/', 'https://example.com/hook', 'HTTPS://EXAMPLE.COM', 'example.com', 'not a url']) { diff --git a/packages/server/test/ext/events/webhookEngine.test.ts b/packages/server/test/ext/events/webhookEngine.test.ts index c08fcaad38..c14fdecd54 100644 --- a/packages/server/test/ext/events/webhookEngine.test.ts +++ b/packages/server/test/ext/events/webhookEngine.test.ts @@ -115,6 +115,11 @@ function bodyOf(request: WebhookSendRequest): Record { return JSON.parse(request.body) as Record; } +// The body cursor of each event POST by eventId; signing is asynchronous, so the sends need not come in delivery order. +function cursorsByEvent(requests: WebhookSendRequest[]): Record { + return Object.fromEntries(requests.map(request => [bodyOf(request).eventId, bodyOf(request).cursor])); +} + beforeEach(() => { vi.useFakeTimers(); }); @@ -180,29 +185,98 @@ describe('endpoint verification', () => { expect(requests).toHaveLength(1); }); - it('sends one verification POST to a host at a time, refusing another pair with resourceExhausted', async () => { + it('sends one verification POST to a host at a time: another pair waits its turn', async () => { const answers: Array<() => void> = []; const { engine, requests, until } = setup( request => new Promise(resolve => answers.push(() => resolve(echo(request) as WebhookSendOutcome))) ); const first = engine.verify('u', HOOK_URL, SECRET, ID); await until(1); - // The same pair waits for the handshake in flight; another pair to that host is refused; another host is not. + // The same pair waits for the handshake in flight; another pair to that host waits its turn; another host does not wait. const samePair = engine.verify('u', HOOK_URL, SECRET, 'sub_2'); - const refused = await engine.verify('v', 'https://HOOKS.example.com/other', SECRET, 'sub_3').catch((error: unknown) => error); - expect(refused).toBeInstanceOf(EventsError); - expect(refused).toMatchObject({ code: -32_025, data: { limit: 'verification', retryAfterMs: expect.any(Number) } }); + const otherPair = engine.verify('v', 'https://HOOKS.example.com/other', SECRET, 'sub_3'); const otherHost = engine.verify('v', 'https://elsewhere.example.com/mcp', SECRET, 'sub_4'); await until(2); + await settle(); expect(requests.map(request => request.url)).toEqual([HOOK_URL, 'https://elsewhere.example.com/mcp']); - for (const answer of answers) answer(); - await expect(Promise.all([first, samePair, otherHost])).resolves.toEqual([undefined, undefined, undefined]); - expect(requests).toHaveLength(2); - const next = engine.verify('v', 'https://hooks.example.com/other', SECRET, 'sub_3'); + answers[0]!(); + await expect(Promise.all([first, samePair])).resolves.toEqual([undefined, undefined]); await until(3); + expect(requests[2]!.url).toBe('https://HOOKS.example.com/other'); + answers[1]!(); answers[2]!(); - await expect(next).resolves.toBeUndefined(); + await expect(Promise.all([otherPair, otherHost])).resolves.toEqual([undefined, undefined]); + expect(requests).toHaveLength(3); + }); + + it('refuses a verification at once when 10 already wait for the host', async () => { + const answers: Array<() => void> = []; + const { engine, requests, until } = setup( + request => new Promise(resolve => answers.push(() => resolve(echo(request) as WebhookSendOutcome))) + ); + const outcome = (n: number) => + engine.verify(`u${n}`, HOOK_URL, SECRET, `sub_${n}`).then( + () => 'verified', + (error: unknown) => error + ); + const waiting = [outcome(0)]; + await until(1); + for (let n = 1; n <= 10; n++) waiting.push(outcome(n)); + await expect(engine.verify('u11', HOOK_URL, SECRET, 'sub_11')).rejects.toMatchObject({ + code: -32_025, + data: { limit: 'verification', retryAfterMs: 5000 } + }); + + // They go one at a time; the window's limit refuses the 11th POST in 60 s when its turn comes. + for (let n = 1; n <= 10; n++) { + answers[n - 1]!(); + await until(Math.min(n + 1, 10)); + await settle(); + } + answers[9]!(); + const outcomes = await Promise.all(waiting); + expect(outcomes.slice(0, 10)).toEqual(Array.from({ length: 10 }, () => 'verified')); + expect(outcomes[10]).toMatchObject({ code: -32_025, data: { limit: 'verification', retryAfterMs: 60_000 } }); + expect(requests).toHaveLength(10); + }); + + it('takes a queued verification whose subscribe is cancelled out of the queue at once, without a POST', async () => { + const answers: Array<() => void> = []; + const { engine, requests, until } = setup( + request => new Promise(resolve => answers.push(() => resolve(echo(request) as WebhookSendOutcome))) + ); + const first = engine.verify('u0', HOOK_URL, SECRET, 'sub_0'); + await until(1); + const cancel = new AbortController(); + const cancelled = engine.verify('u1', HOOK_URL, SECRET, 'sub_1', cancel.signal).catch((error: unknown) => error); + // Another subscribe of a pair keeps that pair's handshake queued when one of its callers is cancelled. + const sharedCancel = new AbortController(); + const sharedLeaving = engine.verify('u2', HOOK_URL, SECRET, 'sub_2', sharedCancel.signal).catch((error: unknown) => error); + const sharedStaying = engine.verify('u2', HOOK_URL, SECRET, 'sub_3'); + const reason = new Error('request cancelled'); + cancel.abort(reason); + sharedCancel.abort(reason); + expect(await cancelled).toBe(reason); + expect(await sharedLeaving).toBe(reason); + + answers[0]!(); + await first; + await until(2); + expect(requests[1]!.headers['X-MCP-Subscription-Id']).toBe('sub_2'); + answers[1]!(); + await expect(sharedStaying).resolves.toBeUndefined(); + await settle(); + expect(requests).toHaveLength(2); + }); + + it('rejects the verifications waiting for a host on clear()', async () => { + const { engine, until } = setup(() => new Promise(() => {})); + void engine.verify('u', HOOK_URL, SECRET, ID).catch(() => {}); + await until(1); + const waiting = engine.verify('v', HOOK_URL, SECRET, 'sub_2'); + engine.clear(); + await expect(waiting).rejects.toMatchObject({ code: -32_025, data: { limit: 'verification' } }); }); it('sends at most 10 verification POSTs to a host per rolling 60 s', async () => { @@ -265,7 +339,8 @@ describe('event delivery', () => { for (const request of requests) { expect(request.headers).toMatchObject({ 'Content-Type': 'application/json', 'X-MCP-Subscription-Id': ID }); expect(await verifies(request, SECRET)).toBe(true); - expect(bodyOf(request)).toEqual({ ...occurrence('evt_1'), cursor: 'p0' }); + // Nothing before it is unsettled, so it carries its own position. + expect(bodyOf(request)).toEqual({ ...occurrence('evt_1'), cursor: 'p1' }); } }); @@ -354,7 +429,7 @@ describe('event delivery', () => { expect(engine.watermark(ID)).toBe('p1'); }); - it('holds the watermark behind an unacknowledged event', async () => { + it('holds the watermark behind an unacknowledged event, and sends an event its own position once nothing before it is unsettled (SEP-3415)', async () => { let failFirst = true; const { engine, record, requests, until } = setup(request => failFirst && bodyOf(request).eventId === 'evt_1' ? { status: 500, body: '' } : { status: 200, body: '' } @@ -366,7 +441,8 @@ describe('event delivery', () => { await until(3); await settle(); expect(engine.watermark(ID)).toBe('p0'); - expect(requests.map(request => bodyOf(request).cursor)).toEqual(['p0', 'p0', 'p0']); + // The first carries its own position; the others, behind it while it is unsettled, the watermark. + expect(cursorsByEvent(requests)).toEqual({ evt_1: 'p1', evt_2: 'p0', evt_3: 'p0' }); failFirst = false; await vi.advanceTimersByTimeAsync(5000); @@ -374,9 +450,10 @@ describe('event delivery', () => { await settle(); expect(engine.watermark(ID)).toBe('p3'); + expect(bodyOf(requests[3]!).cursor).toBe('p1'); engine.deliver(record, occurrence('evt_4'), 'p4', null); await until(5); - expect(bodyOf(requests[4]!).cursor).toBe('p3'); + expect(bodyOf(requests[4]!).cursor).toBe('p4'); }); it('advance() moves an idle watermark, and is ignored while a message is pending', async () => { @@ -399,7 +476,7 @@ describe('event delivery', () => { await until(2); await settle(); expect(engine.watermark(ID)).toBe('p2'); - expect(bodyOf(requests[1]!).cursor).toBe('p1'); + expect(bodyOf(requests[1]!).cursor).toBe('p2'); engine.advance(ID, 'p5'); expect(engine.watermark(ID)).toBe('p5'); }); @@ -412,7 +489,7 @@ describe('event delivery', () => { engine.deliver(record, occurrence('evt_2'), 'p2', 'p1'); await until(2); await settle(); - expect(requests.map(request => bodyOf(request).cursor)).toEqual(['p0', 'p0']); + expect(cursorsByEvent(requests)).toEqual({ evt_1: 'p1', evt_2: 'p0' }); expect(engine.watermark(ID)).toBe('p2'); expect(engine.status(ID)).toEqual({ active: true, lastDeliveryAt: new Date().toISOString(), lastError: null }); }); diff --git a/packages/server/test/ext/events/webhookSubscriptions.test.ts b/packages/server/test/ext/events/webhookSubscriptions.test.ts index f3814f0a6a..afb4af83d8 100644 --- a/packages/server/test/ext/events/webhookSubscriptions.test.ts +++ b/packages/server/test/ext/events/webhookSubscriptions.test.ts @@ -138,11 +138,13 @@ function revoked(): EventsError { return new EventsError('forbidden', 'Forbidden', { reason: 'Access revoked' }); } -// A store whose next `get` or `put` waits for the test, which can act while a subscribe is between its read and its write. +type Gated = 'get' | 'put' | 'listByName'; + +// A store whose next `get`, `put` or `listByName` waits for the test, which can act while a subscribe or a fan-out is between its steps. class GatedStore extends InMemoryWebhookSubscriptionStore { - #held: { method: 'get' | 'put'; reached(): void; released: Promise } | undefined; + #held: { method: Gated; reached(): void; released: Promise } | undefined; - hold(method: 'get' | 'put'): { reached: Promise; release(): void } { + hold(method: Gated): { reached: Promise; release(): void } { let reached!: () => void; let release!: () => void; const arrived = new Promise(resolve => (reached = resolve)); @@ -160,7 +162,12 @@ class GatedStore extends InMemoryWebhookSubscriptionStore { return super.put(record); } - async #wait(method: 'get' | 'put'): Promise { + override async *listByName(name: string): AsyncIterable { + await this.#wait('listByName'); + yield* super.listByName(name); + } + + async #wait(method: Gated): Promise { const held = this.#held; if (held?.method !== method) return; this.#held = undefined; @@ -351,8 +358,102 @@ describe('events/subscribe: creating', () => { expect(onSubscribe).toHaveBeenCalledOnce(); }); + it("lets another principal's subscribe to the same host wait for the verification in flight, then verify", async () => { + let release!: () => void; + const held = new Promise(resolve => (release = resolve)); + let holdNext = true; + const respond: Respond = async request => { + if (isVerification(request) && holdNext) { + holdNext = false; + await held; + } + return echo()(request); + }; + const store = new GatedStore(); + const { events, post } = replica({ webhookStore: store, respond }); + events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const first = client(events, 'u1').subscribe(); + await post.until(1); + // From its store read on, the second subscribe runs without a timer or I/O until it reaches the host's queue. + const gate = store.hold('get'); + const second = client(events, 'u2').subscribe({ url: `${HOOK}/u2` }); + await gate.reached; + gate.release(); + await settle(); + expect(post.requests).toHaveLength(1); + + release(); + expect(subscribed(await first).id).toMatch(SUB_ID); + expect(subscribed(await second).id).toMatch(SUB_ID); + expect(post.requests.filter(request => isVerification(request)).map(request => request.url)).toEqual([HOOK, `${HOOK}/u2`]); + }); + + it('holds a principal to its share and frees a place on unsubscribe, termination and expiry, while another principal subscribes', async () => { + const { events } = replica({ maxSubscriptions: 4 }); + const handle = events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const [alice, bob] = [client(events, 'alice'), client(events, 'bob')]; + const share = { code: -32_025, data: { limit: 'principalSubscriptions', max: 1 } }; + + subscribed(await alice.subscribe({ arguments: { a: 1 } })); + expect(errorOf(await alice.subscribe({ arguments: { a: 2 } }))).toMatchObject(share); + subscribed(await bob.subscribe({ arguments: { a: 1 } })); + // A refresh of the one alice holds is never refused. + subscribed(await alice.subscribe({ arguments: { a: 1 } })); + + resultOf(await alice.unsubscribe({ arguments: { a: 1 } })); + subscribed(await alice.subscribe({ arguments: { a: 2 }, ttlMs: 60_000 })); + expect(errorOf(await alice.subscribe({ arguments: { a: 3 } }))).toMatchObject(share); + await vi.advanceTimersByTimeAsync(60_000); + subscribed(await alice.subscribe({ arguments: { a: 3 } })); + await handle.terminate(new EventsError('forbidden', 'Forbidden')); + subscribed(await alice.subscribe({ arguments: { a: 4 } })); + }); + + it('drops a subscribe cancelled while it waits for the host: no POST, no subscription, and the next waiter goes', async () => { + let release!: () => void; + const held = new Promise(resolve => (release = resolve)); + let holdNext = true; + const respond: Respond = async request => { + if (isVerification(request) && holdNext) { + holdNext = false; + await held; + } + return echo()(request); + }; + const onSubscribe = vi.fn(); + const store = new GatedStore(); + const { events, post, hook } = replica({ webhookStore: store, respond }); + events.registerEvent('e', { emitOnly: true, payloadSchema: P, onSubscribe }); + const first = client(events, 'u1').subscribe(); + await post.until(1); + const gate = store.hold('get'); + const cancel = new AbortController(); + const cancelled = client(events, 'u2') + .rpc( + 'events/subscribe', + { name: 'e', delivery: { mode: 'webhook', url: `${HOOK}/u2`, secret: SECRET } }, + { signal: cancel.signal } + ) + .catch((error: unknown) => error); + await gate.reached; + gate.release(); + await settle(); + const next = client(events, 'u3').subscribe({ url: `${HOOK}/u3` }); + await settle(); + cancel.abort(); + expect(await cancelled).toBeInstanceOf(Error); + + release(); + subscribed(await first); + subscribed(await next); + expect(post.requests.filter(request => isVerification(request)).map(request => request.url)).toEqual([HOOK, `${HOOK}/u3`]); + expect(onSubscribe.mock.calls.map(([ctx]) => (ctx as EventContext).principal)).toEqual(['u1', 'u3']); + expect((await stored(store)).map(record => record.principal).sort()).toEqual(['u1', 'u3']); + expect(hook.state()).toMatchObject({ webhookExpiryTimers: 2 }); + }); + it('counts each webhook subscription once after its create', async () => { - const { events } = replica({ maxSubscriptions: 2 }); + const { events } = replica({ maxSubscriptions: 8 }); events.registerEvent('e', { emitOnly: true, payloadSchema: P }); const alice = client(events); subscribed(await alice.subscribe({ arguments: { a: 1 } })); @@ -434,20 +535,103 @@ describe('events/subscribe: creating', () => { expect(post.requests.filter(request => isVerification(request))).toHaveLength(2); }); - it('starts an emit-only subscription at the buffer head and flags skipped events as truncated', async () => { - const { events } = replica(); + it('starts an emit-only subscription at the buffer head, or replays the buffer since a cursor, truncated only past what it holds', async () => { + const { events, post } = replica({ emitBuffer: { maxEvents: 2 } }); const handle = events.registerEvent('e', { emitOnly: true, payloadSchema: P }); const alice = client(events); const fresh = subscribed(await alice.subscribe({ arguments: { k: 1 } })); expect(fresh).toMatchObject({ cursor: expect.any(String), truncated: false }); - await handle.emit({ data: { n: 1 } }); + await handle.emit({ eventId: 'evt_1', data: { n: 1 } }); + await handle.emit({ eventId: 'evt_2', data: { n: 2 } }); + const { cursor: afterFirst } = resultOf( + await alice.rpc('events/poll', { name: 'e', cursor: fresh.cursor, maxEvents: 1 }) + ) as PollEventsResult; + + const resumed = subscribed(await alice.subscribe({ arguments: { k: 2 }, cursor: afterFirst })); + expect(resumed).toMatchObject({ cursor: afterFirst, truncated: false }); + await handle.emit({ eventId: 'evt_3', data: { n: 3 } }); + // The buffer now holds evt_2 and evt_3 only, so the fresh cursor is behind it. + const stale = subscribed(await alice.subscribe({ arguments: { k: 3 }, cursor: fresh.cursor })); + expect(stale).toMatchObject({ cursor: afterFirst, truncated: true }); + const otherEpoch = subscribed(await alice.subscribe({ arguments: { k: 4 }, cursor: 'e00000000.0' })); + expect(otherEpoch.truncated).toBe(true); + + // One verification, then k:1 live (3), k:2 replayed and live (2), k:3 and k:4 replayed (2 each). + await post.until(10); + await settle(); + expect(post.requests).toHaveLength(10); + const delivered = (id: string) => + post + .deliveries() + .filter(request => request.headers['X-MCP-Subscription-Id'] === id) + .map(request => bodyOf(request).eventId) + .sort(); + expect(delivered(fresh.id)).toEqual(['evt_1', 'evt_2', 'evt_3']); + expect(delivered(resumed.id)).toEqual(['evt_2', 'evt_3']); + expect(delivered(stale.id)).toEqual(['evt_2', 'evt_3']); + expect(delivered(otherEpoch.id)).toEqual(['evt_2', 'evt_3']); + }); + + it('reads an emit-only replay as it queues behind a fan-out in flight, so each event reaches it once and in order', async () => { + const store = new GatedStore(); + const { events, post } = replica({ webhookStore: store }); + let resumed!: () => void; + const queued = new Promise(resolve => (resumed = resolve)); + const handle = events.registerEvent('e', { + emitOnly: true, + payloadSchema: P, + onSubscribe: (_ctx, args) => { + if (args.k === 2) resumed(); + } + }); + const alice = client(events); + const { cursor } = subscribed(await alice.subscribe({ arguments: { k: 1 } })); - const behind = subscribed(await alice.subscribe({ arguments: { k: 2 }, cursor: fresh.cursor })); - expect(behind.truncated).toBe(true); - expect(behind.cursor).not.toBe(fresh.cursor); - const current = subscribed(await alice.subscribe({ arguments: { k: 3 }, cursor: behind.cursor })); - expect(current).toMatchObject({ cursor: behind.cursor, truncated: false }); - expect(subscribed(await alice.subscribe({ arguments: { k: 4 }, cursor: 'e00000000.0' })).truncated).toBe(true); + // The fan-out of `first` holds the type's queue while it lists the stored subscriptions. + const gate = store.hold('listByName'); + await handle.emit({ eventId: 'first', data: { n: 1 } }); + await gate.reached; + const resuming = alice.subscribe({ arguments: { k: 2 }, cursor }); + // After onSubscribe the resume reads its replay and queues behind that fan-out with no further wait. + await queued; + await settle(); + await handle.emit({ eventId: 'second', data: { n: 2 } }); + gate.release(); + const { id } = subscribed(await resuming); + + await post.until(5); + await settle(); + expect(post.requests).toHaveLength(5); + const sent = post.deliveries().filter(request => request.headers['X-MCP-Subscription-Id'] === id); + expect(sent.map(request => bodyOf(request).eventId).sort()).toEqual(['first', 'second']); + // `second` reached the engine behind the unsettled `first`, so its body carries the replay's start. + const cursorOf = (eventId: string) => bodyOf(sent.find(request => bodyOf(request).eventId === eventId)!).cursor; + expect(cursorOf('second')).toBe(cursor); + expect(cursorOf('first')).not.toBe(cursor); + }); + + it('delivers each event once across the seam between an emit-only replay and live fan-out', async () => { + const store = new GatedStore(); + const { events, post } = replica({ webhookStore: store }); + const handle = events.registerEvent('e', { emitOnly: true, payloadSchema: P, transform: (_ctx, event) => event }); + const alice = client(events); + const { cursor } = subscribed(await alice.subscribe({ arguments: { k: 1 } })); + await handle.emit({ eventId: 'before', data: { n: 1 } }); + + // An emit while the resumed subscription stores its record finds the record once it is stored. + const gate = store.hold('put'); + const resuming = alice.subscribe({ arguments: { k: 2 }, cursor }); + await gate.reached; + await handle.emit({ eventId: 'during', data: { n: 2 } }); + gate.release(); + const { id, truncated } = subscribed(await resuming); + expect(truncated).toBe(false); + await handle.emit({ eventId: 'after', data: { n: 3 } }); + + await post.until(7); + await settle(); + const sent = post.deliveries().filter(request => request.headers['X-MCP-Subscription-Id'] === id); + expect(sent.map(request => bodyOf(request).eventId).sort()).toEqual(['after', 'before', 'during']); }); }); @@ -767,7 +951,7 @@ describe('check-kind webhook subscriptions', () => { expect(check.mock.calls[1]![2]).toBe('c0'); await post.until(2); await settle(); - expect(bodyOf(post.requests[1]!)).toMatchObject({ eventId: 'evt_1', name: 't', data: { n: 1 }, cursor: 'c0' }); + expect(bodyOf(post.requests[1]!)).toMatchObject({ eventId: 'evt_1', name: 't', data: { n: 1 }, cursor: 'c1' }); await vi.advanceTimersByTimeAsync(5000); expect(check.mock.calls[2]![2]).toBe('c1'); @@ -818,7 +1002,7 @@ describe('check-kind webhook subscriptions', () => { expect(check.mock.calls[0]![0]).toMatchObject({ maxAgeMs: 300_000 }); await post.until(2); await settle(); - expect(bodyOf(post.requests[1]!)).toMatchObject({ eventId: 'evt_1', cursor: 'c0' }); + expect(bodyOf(post.requests[1]!)).toMatchObject({ eventId: 'evt_1', cursor: 'c1' }); await vi.advanceTimersByTimeAsync(5000); await post.until(3); diff --git a/test/e2e/scenarios/events.test.ts b/test/e2e/scenarios/events.test.ts index fdeddba2dc..0c04d03f40 100644 --- a/test/e2e/scenarios/events.test.ts +++ b/test/e2e/scenarios/events.test.ts @@ -580,8 +580,10 @@ verifies('events:push:delivery', async ({ transport }: TestArgs) => { const subscription = await clientEvents.subscribe({ name: NOTE, delivery: 'push' }); const [id] = streamIds(tap); - await note.emit({ eventId: 'evt-1', data: { text: 'pushed' } }); - expect(await take(subscription)).toEqual([{ text: 'pushed' }]); + await note.emit({ eventId: 'evt-1', data: { text: 'pushed' }, _meta: { 'vendor/k': 1 } }); + const received = await subscription[Symbol.asyncIterator]().next(); + expect(received.value).toMatchObject({ data: { text: 'pushed' } }); + expect(received.value?._meta).toEqual({ 'vendor/k': 1 }); const delivered = framesOf(tap, id).filter(frame => frame.method === 'notifications/events/event'); expect(delivered).toEqual([ @@ -592,7 +594,7 @@ verifies('events:push:delivery', async ({ transport }: TestArgs) => { timestamp: expect.any(String), data: { text: 'pushed' }, cursor: expect.any(String), - _meta: { [SUBSCRIPTION_ID_META_KEY]: id } + _meta: { 'vendor/k': 1, [SUBSCRIPTION_ID_META_KEY]: id } } }) ]); From 0791753cd103818d90f7e6303df31c2fb32616f1 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Thu, 19 Nov 2026 15:46:20 +0200 Subject: [PATCH 35/37] =?UTF-8?q?fix(events):=20second=20review=20round=20?= =?UTF-8?q?=E2=80=94=20DNS=20deadline=20and=20pinning,=20delivery=20limits?= =?UTF-8?q?,=20stable=20eventId?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - nodeWebhookSender fails a send whose deadline or cancel fires while one DNS family is still pending, and pins the connection to every checked address (by family when asked) instead of the first, so IPv6-only servers reach dual-stack receivers. - The webhook engine runs at most 10 event POSTs per subscription at a time, for replay, resume and live bursts. - check results must give every event an eventId; one without is dropped and reported. emit() still generates ids. - The client falls back from push to poll when the first push exchange fails for a reason other than an EventsError and the app did not choose a mode. - A refresh on any replica ends a suspension: the engine reactivates when the stored record's expiresAt moves past the one it saw at suspension. - A failing store listing during an emit's fan-out is retried up to 3 times without delivering twice. - Docs and the typescript:events:store:restart requirement describe restart behaviour as it is (check types resume at the next refresh, from the client's cursor), and the client docs say the receiver acknowledges once an event is queued. --- docs/clients/events.md | 6 +- docs/servers/events.md | 12 +- packages/client/src/ext/events/extension.ts | 47 ++++- packages/client/src/ext/events/push.ts | 21 +- packages/client/src/ext/events/recovery.ts | 5 + .../client/src/ext/events/subscription.ts | 2 +- packages/client/test/ext/events/push.test.ts | 74 ++++++- packages/server/src/ext/events/node.ts | 36 ++-- packages/server/src/ext/events/poll.ts | 7 +- packages/server/src/ext/events/types.ts | 10 +- .../server/src/ext/events/webhookEngine.ts | 62 +++++- .../src/ext/events/webhookSubscriptions.ts | 31 ++- packages/server/test/ext/events/node.test.ts | 126 ++++++++++-- packages/server/test/ext/events/poll.test.ts | 40 +++- packages/server/test/ext/events/push.test.ts | 16 ++ .../test/ext/events/registration.test.ts | 7 + .../test/ext/events/webhookEngine.test.ts | 161 ++++++++++++--- .../ext/events/webhookSubscriptions.test.ts | 189 +++++++++++++++++- test/conformance/src/events.ts | 2 +- test/e2e/requirements.ts | 2 +- test/e2e/scenarios/events.test.ts | 88 ++++++-- 21 files changed, 810 insertions(+), 134 deletions(-) diff --git a/docs/clients/events.md b/docs/clients/events.md index 91aab59333..00127cf36b 100644 --- a/docs/clients/events.md +++ b/docs/clients/events.md @@ -33,7 +33,7 @@ ticket.updated { ticketId: 'T-7', status: 'open' } Pass the extension in the client's `extensions` option: the client calls its `setup` while it is constructed, which ties the extension to that one client. `subscribe()` resolves once its first exchange with the server succeeds, and the subscription starts from now unless you pass a `cursor`. `list()` returns the server's event types with their schemas and delivery modes. -Each subscription takes the first delivery mode the event type offers out of webhook (when you configure it), push and poll; `delivery` forces one, and `subscription.deliveryMode` says which it got. The loop is the same in every mode, drops a repeated `eventId`, and leaving it cancels the subscription. +Each subscription takes the first delivery mode the event type offers out of webhook (when you configure it), push and poll; `delivery` forces one, and `subscription.deliveryMode` says which it got. Without `delivery`, when a push subscription's first stream fails before its first `notifications/events/active` with anything but an `EventsError` (no valid `active` within the request timeout, say, behind a host that buffers whole responses), the client reports the failure to its `onerror` and subscribes by poll instead, if the event type offers poll. The loop is the same in every mode, drops a repeated `eventId`, and leaving it cancels the subscription. ::: info Events is used on protocol 2026-07-28 only, so create the client with `versionNegotiation: { mode: 'auto' }` or a pin — see [Protocol versions](../protocol-versions.md). @@ -85,6 +85,8 @@ With `webhook` set, a subscription prefers webhook wherever the event type offer Webhook subscriptions with the same name and arguments share one server subscription, and cancelling the last of them sends `events/unsubscribe`. The SDK's server accepts a webhook subscription only from an authenticated principal and answers `forbidden` otherwise. The receiver answers `503` to a subscription it does not know yet, and the server retries. +The receiver answers `2xx` once it has queued an event in memory, so events queued but not yet read by your loop are lost if the process exits. Subscribing again within the grant, while the server still delivers to the subscription, continues from the server's position rather than from your saved cursor. + ## Handle errors Catch `EventsError` around `subscribe()` and the loop; `kind` says what went wrong. @@ -107,7 +109,7 @@ The server rejects `queue: 42` against the event type's `inputSchema`, so it pri invalidParams ``` -`subscribe()` rejects with an `EventsError` when the server does not list the event type or refuses the subscription (`notFound`, `invalidParams`, `forbidden`, `unsupported`, `resourceExhausted` or `callbackEndpointError`), and with an `SdkError` when the exchange fails in the SDK, such as a closed connection or a push stream with no valid `notifications/events/active` within the request timeout; other failures of the first exchange are retried in the background. The server's webhook verification limit (`resourceExhausted` with `data.limit: 'verification'`) is one of those: the client subscribes again after `data.retryAfterMs` (or its usual backoff without one), before and after the first exchange. Once subscribed, the loop ends with an `EventsError` when the server ends the subscription, such as `forbidden` when access is revoked. A `notFound`, or an `unsupported` for a schema change, makes the client list the event types again and carry on while the type is still offered in that mode. +`subscribe()` rejects with an `EventsError` when the server does not list the event type or refuses the subscription (`notFound`, `invalidParams`, `forbidden`, `unsupported`, `resourceExhausted` or `callbackEndpointError`), and with an `SdkError` when the exchange fails in the SDK, such as a closed connection or a push stream with no valid `notifications/events/active` within the request timeout; other failures of the first exchange are retried in the background. A push subscription that can fall back to poll, as above, does so instead on any of these failures but an `EventsError` or a closed connection. The server's webhook verification limit (`resourceExhausted` with `data.limit: 'verification'`) is one of those: the client subscribes again after `data.retryAfterMs` (or its usual backoff without one), before and after the first exchange. Once subscribed, the loop ends with an `EventsError` when the server ends the subscription, such as `forbidden` when access is revoked. A `notFound`, or an `unsupported` for a schema change, makes the client list the event types again and carry on while the type is still offered in that mode. `NoCompatibleDeliveryModeError` means no delivery mode the event type offers is usable here: webhook needs the `webhook` option, and `delivery` narrows the choice to one mode. Against a server without Events, or on a connection older than 2026-07-28, `events.supported` is `false`, and `list()` and `subscribe()` throw `SdkError` (`CapabilityNotSupported`). An error thrown from `onGap` goes to the client's `onerror`. diff --git a/docs/servers/events.md b/docs/servers/events.md index 4ad2be8a94..9e2817a6c7 100644 --- a/docs/servers/events.md +++ b/docs/servers/events.md @@ -37,7 +37,7 @@ events.registerEvent('ticket.updated', { }); ``` -Clients subscribe by poll (`events/poll`) or push (`events/stream`), or by webhook (`events/subscribe`) once you turn it on, and the SDK runs each mode from this one definition. `check` returns the events since `cursor` and the cursor to resume from; for a subscription that starts now the SDK passes `cursor: null` and sends only the cursor you return. Return at most `ctx.maxEvents` events, set `hasMore` when more are waiting, and set `truncated: true` when the upstream no longer has the history since `cursor`. +Clients subscribe by poll (`events/poll`) or push (`events/stream`), or by webhook (`events/subscribe`) once you turn it on, and the SDK runs each mode from this one definition. `check` returns the events since `cursor` and the cursor to resume from; for a subscription that starts now the SDK passes `cursor: null` and sends only the cursor you return. Return at most `ctx.maxEvents` events, set `hasMore` when more are waiting, and set `truncated: true` when the upstream no longer has the history since `cursor`. Give every event an `eventId` that stays the same whenever `check` returns that event again, so clients can drop a replayed one; the SDK drops an event without one and reports it to `onerror`. Clients resume from their cursor after a disconnect or a restart, for as long as your upstream accepts it. A `check` that returns `cursor: null` marks a type that cannot resume. The SDK then calls `check` with `cursor: null` every time: it drops the events of a subscription's first call, as for any subscription that starts now, and sends the events of every later call, so return what happened since the previous call for the same `ctx.subscriptionId`. The SDK never reports `truncated` for such a type, and ignores `maxAgeMs` for it. @@ -73,7 +73,7 @@ const incidents = events.registerEvent('incident.created', { await incidents.emit({ eventId: 'INC-7', data: { incidentId: 'INC-7', title: 'Checkout is down', severity: 'P1' } }); ``` -`emit()` sends the event to every subscription that `match` accepts, or to one with `emit(event, { subscriptionId })`; `transform` reshapes it per subscription. The SDK drops an event whose `data` fails `payloadSchema`, or whose `transform` output does, and reports it to `onerror`, for both kinds. +`emit()` sends the event to every subscription that `match` accepts, or to one with `emit(event, { subscriptionId })`; `transform` reshapes it per subscription. An event emitted without an `eventId` gets one the SDK generates, which every replay of it keeps. The SDK drops an event whose `data` fails `payloadSchema`, or whose `transform` output does, and reports it to `onerror`, for both kinds. Poll clients read emit-only events from an in-memory buffer (`emitBuffer`, by default the last 10 minutes and at most 10 000 events), so events emitted before a restart are lost. Push and webhook subscriptions that pass a cursor replay that buffer first. `onSubscribe` and `onUnsubscribe` run as a subscription starts and ends, in every mode, and `ctx.subscriptionId` names it. @@ -87,7 +87,7 @@ import { createMcpHandler, McpServer } from '@modelcontextprotocol/server'; const handler = createMcpHandler(() => new McpServer({ name: 'helpdesk', version: '1.0.0' }, { extensions: [events] })); ``` -While it is constructed, each server advertises the extension and calls its `setup`, which registers the `events/*` methods (see [Extensions](../advanced/extensions.md)). Push streams under every `responseMode`, `'json'` included, as `subscriptions/listen` does. +While it is constructed, each server advertises the extension and calls its `setup`, which registers the `events/*` methods (see [Extensions](../advanced/extensions.md)). Push streams under every `responseMode`, `'json'` included, as `subscriptions/listen` does. On a host that buffers whole responses push cannot work: the SDK's client falls back to poll once its first push stream times out, or set `delivery: { push: false }` on the event type so clients choose poll at once. A push stream carries no SSE comment keepalive. The server sends `notifications/events/heartbeat` whenever the stream has been quiet for the granted interval, `heartbeatMs` (30 seconds by default) or a shorter one the client asks for, and the SDK's client reconnects after three intervals of silence. Keep `heartbeatMs` below your load balancer's idle timeout. @@ -118,7 +118,7 @@ const webhookEvents = new EventsExtension({ Setting `webhookTtlMs` or `webhookSender` without the other two throws `TypeError`. `getPrincipal` has no default, since `AuthInfo` has no subject field: return the user from wherever your token verifier puts it. A webhook subscription for which `getPrincipal` returns `null` is refused with `forbidden`, on stdio too; poll and push use the principal when there is one. -`webhookTtlMs` is the longest a webhook subscription lives without a refresh, and clients refresh before it lapses. The SDK verifies each endpoint with a challenge before the first delivery, signs every POST (Standard Webhooks), and retries a failed delivery up to five attempts in all. It sends each destination host one challenge at a time, so a subscribe waits while another challenge to that host is in flight, and at most ten in any 60 seconds; past that, or when ten subscribes already wait for the host, it refuses with `resourceExhausted` (`data.limit: 'verification'`; `data.retryAfterMs` says when to try again, and the SDK's client does). It answers a principal's subscribes to a URL whose challenge failed with that failure for 60 seconds, without another challenge. `nodeWebhookSender()` requires `https`, resolves the host at every send by querying DNS directly (so `/etc/hosts` does not apply; origins in `trustedOrigins` skip resolution), refuses IANA special-purpose addresses (loopback, private, link-local and the like) and connects to the address it checked; it follows no redirects and gives up after 5 seconds. +`webhookTtlMs` is the longest a webhook subscription lives without a refresh, and clients refresh before it lapses. The SDK verifies each endpoint with a challenge before the first delivery, signs every POST (Standard Webhooks), and retries a failed delivery up to five attempts in all. It keeps at most ten event deliveries per subscription in progress, waits between retries included, so a replayed backlog goes out ten at a time. It sends each destination host one challenge at a time, so a subscribe waits while another challenge to that host is in flight, and at most ten in any 60 seconds; past that, or when ten subscribes already wait for the host, it refuses with `resourceExhausted` (`data.limit: 'verification'`; `data.retryAfterMs` says when to try again, and the SDK's client does). It answers a principal's subscribes to a URL whose challenge failed with that failure for 60 seconds, without another challenge. `nodeWebhookSender()` requires `https`, resolves the host at every send by querying DNS directly (so `/etc/hosts` does not apply; origins in `trustedOrigins` skip resolution), refuses IANA special-purpose addresses (loopback, private, link-local and the like) and connects only to the addresses it checked, IPv4 and IPv6; it follows no redirects and gives up after 5 seconds. ::: warning `trustedOrigins` is for development only. Its exact origins, such as `http://127.0.0.1:9000`, are exempt from the `https` rule and the private-address check, so a receiver on your machine can take deliveries; endpoint verification, signing and the no-redirect rule still apply. @@ -179,8 +179,12 @@ const replicated = new EventsExtension({ Records hold each subscription's webhook secret, so protect the store as you protect credentials. The SDK deletes an expired record when it next reads it, or when the expiry timer of the replica that last granted it fires, and runs `onUnsubscribe` then. The store above keeps each record a minute past its `expiresAt`, because a record the database has already dropped is gone when that timer reads it, and `onUnsubscribe` never runs for it. A record that a stopped replica left behind stays until something reads it, so let the store expire records too, as the expiry passed to `set()` above does (with Redis, a key TTL). +A store that outlives the process carries webhook subscriptions across a restart. Emit-only types keep delivering to the stored subscriptions, without a resubscribe or a new verification; a `check` type's loop starts again at the subscription's next refresh, from the cursor the client supplies. + A replica runs `onUnsubscribe` after its `delete()` resolved `true`. Replicas racing on a store whose `delete()` is not atomic may each run it for one subscription, so keep `onUnsubscribe` idempotent. +When a store read fails while `emit()` hands the event to its webhook subscriptions, the SDK lists them again, up to three tries within a few hundred milliseconds, and skips those it already reached. A store that keeps failing drops the emitted event for the webhook subscriptions it could not list, and the SDK reports the failure to `onerror`. + With a shared store, webhook subscribe, refresh, secret rotation and unsubscribe work on any replica, and `emit()` on any replica reaches every matching webhook subscription. Some state stays on one process: - `emit()` reaches push streams and the poll buffer on the emitting process only. A poll, or a webhook subscribe that resumes from a cursor, that lands on another replica gets `truncated: true` and a fresh cursor. diff --git a/packages/client/src/ext/events/extension.ts b/packages/client/src/ext/events/extension.ts index 5ed8469fc1..0ffbf93b9d 100644 --- a/packages/client/src/ext/events/extension.ts +++ b/packages/client/src/ext/events/extension.ts @@ -6,7 +6,7 @@ import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal/publ import type { ClientExtension, ClientExtensionContext } from '../../client/extension'; import { NoCompatibleDeliveryModeError } from './errors'; import { PollDriver } from './poll'; -import { PushDriver } from './push'; +import { PushDriver, PushUnavailableError } from './push'; import { WebhookReceiver } from './receiver'; import { EventsConnection } from './request'; import type { Driver, DriverContext, EventSubscription, SubscribeOptions } from './subscription'; @@ -147,7 +147,13 @@ export class EventsClientExtension implements ClientExtension { * transport error, a JSON-RPC error that is not an Events kind, or the * server's webhook verification limit, `resourceExhausted` with * `data.limit: 'verification'`, retried after its `data.retryAfterMs` - * when given) does not reject: delivery is retried in the background. A `cursor` the + * when given) does not reject: delivery is retried in the background. + * Without `delivery`, a push subscription whose first stream fails before + * its first `active` with anything but an `EventsError` (no valid `active` + * within the request timeout, as behind a host that buffers whole + * responses, a transport error, or an `active` that fails its schema) + * reports that failure to the client's `onerror` and subscribes by poll + * instead, once, when the event type offers poll. A `cursor` the * server refuses because the event type's schema changed is dropped: the * event types are listed again, the subscription starts from now, and * `onGap` reports the fresh cursor. A `-32020` lists the event types again @@ -169,8 +175,9 @@ export class EventsClientExtension implements ClientExtension { * the schema change that refused `cursor` left the event type without the selected mode. * @throws {SdkError} `CapabilityNotSupported` when {@linkcode EventsClientExtension.supported} is `false`, * `ConnectionClosed` when the client closes before the first exchange answers, or another code when that - * exchange fails in the SDK (for example `RequestTimeout`, also when a push stream sends no valid - * `notifications/events/active` in time, or `InvalidResult` for an `active` that fails its schema). + * exchange fails in the SDK (for example `RequestTimeout`, also when a push stream that does not fall back to + * poll sends no valid `notifications/events/active` in time, or `InvalidResult` for an `active` that fails its + * schema). * @throws {ProtocolError} `-32020` when the server rejects the `Mcp-Param` headers again after a re-list. * @throws {TypeError} when `webhook.secretProvider` returns something that is not a Standard Webhooks secret, or a * secret another open server subscription signs with. @@ -184,14 +191,15 @@ export class EventsClientExtension implements ClientExtension { } if (descriptor === undefined) throw new EventsError('notFound', 'Event type not found', { kind: 'event' }); const mode = selectDeliveryMode(options.name, descriptor.delivery, options.delivery, this.#options.webhook !== undefined); - const queue = new SubscriptionQueue(mode, options.cursor ?? null); + // Unless `delivery` forced push, a first push stream that cannot work hands the subscription to poll, once. + const fallback = options.delivery === undefined && mode === 'push' && descriptor.delivery.includes('poll'); try { - await queue.run(this.#driver(mode, { subscription: { ...options }, queue, connection })); + return await this.#start(mode, options, connection, fallback); } catch (error) { - await queue.cancel(); - throw error; + if (!(error instanceof PushUnavailableError)) throw error; + connection.report(error); + return this.#start('poll', options, connection, false); } - return queue; } /** @@ -212,9 +220,26 @@ export class EventsClientExtension implements ClientExtension { return request => receiver.handle(request); } - #driver(mode: DeliveryMode, context: DriverContext): Driver { + // Runs a subscription in `mode`, resolving once its first exchange succeeds. + async #start( + mode: DeliveryMode, + options: SubscribeOptions, + connection: EventsConnection, + fallback: boolean + ): Promise> { + const queue = new SubscriptionQueue(mode, options.cursor ?? null); + try { + await queue.run(this.#driver(mode, { subscription: { ...options }, queue, connection }, fallback)); + } catch (error) { + await queue.cancel(); + throw error; + } + return queue; + } + + #driver(mode: DeliveryMode, context: DriverContext, fallback: boolean): Driver { if (mode === 'poll') return new PollDriver(context, this.#floorMs); - if (mode === 'push') return new PushDriver(context); + if (mode === 'push') return new PushDriver(context, fallback); // Webhook is selected only with the `webhook` option set. return this.#webhooks!.driver(context); } diff --git a/packages/client/src/ext/events/push.ts b/packages/client/src/ext/events/push.ts index 465fabb570..7478fb1d0b 100644 --- a/packages/client/src/ext/events/push.ts +++ b/packages/client/src/ext/events/push.ts @@ -12,12 +12,13 @@ import { } from '@modelcontextprotocol/core/ext/events'; import type { JSONRPCNotification } from '@modelcontextprotocol/core-internal'; import { ProtocolError, SUBSCRIPTION_ID_META_KEY } from '@modelcontextprotocol/core-internal'; +import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; import { DEFAULT_REQUEST_TIMEOUT_MSEC, SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal/public'; import type * as z from 'zod/v4'; import type { StreamEnd, StreamHandle } from '../../client/client'; import { clientInternals } from '../../client/client'; -import { DriverLoop, isHeaderMismatch, jitteredDelay, MAX_TIMER_DELAY_MS } from './recovery'; +import { connectionClosed, DriverLoop, isHeaderMismatch, jitteredDelay, MAX_TIMER_DELAY_MS } from './recovery'; import { asEventsError } from './request'; import type { Driver, DriverContext } from './subscription'; @@ -29,6 +30,15 @@ interface Ending { error?: unknown; } +// The first stream of a subscription that may fall back ended before a valid `active`, with `cause`, which is not the server's refusal. +export class PushUnavailableError extends Error { + constructor(name: string, cause: unknown) { + super(`${EVENTS_STREAM_METHOD} for '${name}' failed before its first ${EVENTS_ACTIVE_NOTIFICATION}; subscribing by poll instead`, { + cause + }); + } +} + function endingOf(end: StreamEnd): Ending { return end.cause === 'remote' && end.error !== undefined ? { error: asEventsError(end.error) } : {}; } @@ -45,6 +55,8 @@ function withoutStreamId(event: EventOccurrence): EventOccurrence { export class PushDriver implements Driver { readonly #context: DriverContext; readonly #loop: DriverLoop; + // A first stream that cannot work rejects start() with PushUnavailableError, for subscribe() to poll instead. + readonly #fallback: boolean; // Reconnect delays taken since the last `active`. #attempt = 0; // A -32020 has been re-listed for since the last `active`. @@ -58,9 +70,10 @@ export class PushDriver implements Driver { // Until the first valid `active`, the wait for it; from then on, the countdown to declaring the stream dead. #dead: ReturnType | undefined; - constructor(context: DriverContext) { + constructor(context: DriverContext, fallback = false) { this.#context = context; this.#loop = new DriverLoop(context, 'push'); + this.#fallback = fallback; } start(): Promise { @@ -93,6 +106,10 @@ export class PushDriver implements Driver { await this.#context.connection.list(undefined, { signal: this.#loop.signal }).catch(() => {}); return; } + const { connection, subscription } = this.#context; + if (this.#fallback && this.#loop.first && !(error instanceof EventsError) && connectionClosed(connection, error) === undefined) { + throw new PushUnavailableError(subscription.name, error); + } await this.#loop.recover(error); } diff --git a/packages/client/src/ext/events/recovery.ts b/packages/client/src/ext/events/recovery.ts index 956fed698f..92a1805edc 100644 --- a/packages/client/src/ext/events/recovery.ts +++ b/packages/client/src/ext/events/recovery.ts @@ -152,6 +152,11 @@ export class DriverLoop { return this.#maxAgeMs; } + // start() has not settled: the first exchange has neither succeeded nor failed transiently. + get first(): boolean { + return this.#first; + } + get signal(): AbortSignal { return this.#abort.signal; } diff --git a/packages/client/src/ext/events/subscription.ts b/packages/client/src/ext/events/subscription.ts index 79adf3e16e..d0978f1757 100644 --- a/packages/client/src/ext/events/subscription.ts +++ b/packages/client/src/ext/events/subscription.ts @@ -14,7 +14,7 @@ export interface SubscribeOptions { name: string; /** Subscription arguments, valid against the event type's `inputSchema`. */ arguments?: Record; - /** Forces one delivery mode instead of the default preference (webhook, then push, then poll). */ + /** Forces one delivery mode instead of the default preference (webhook, then push, then poll) and the fallback from push to poll. */ delivery?: DeliveryMode; /** Resumes from a persisted {@linkcode EventSubscription.cursor}; `null` or absent starts from now. */ cursor?: string | null; diff --git a/packages/client/test/ext/events/push.test.ts b/packages/client/test/ext/events/push.test.ts index 03d5ced875..b9e3899bae 100644 --- a/packages/client/test/ext/events/push.test.ts +++ b/packages/client/test/ext/events/push.test.ts @@ -6,7 +6,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; import type { EventSubscription, SubscribeOptions } from '../../../src/ext/events/index'; import { EventsError, NoCompatibleDeliveryModeError } from '../../../src/ext/events/index'; import type { Call, Handler } from './scripted'; -import { callsTo, connectEvents, descriptor, listing, occurrence } from './scripted'; +import { callsTo, connectEvents, descriptor, listing, occurrence, RpcError, script } from './scripted'; const subscriptions: EventSubscription[] = []; @@ -576,6 +576,78 @@ describe('push delivery', () => { expect(later.streams()).toHaveLength(3); }); + describe('falling back to poll', () => { + const both = descriptor('tick', { delivery: ['push', 'poll'] }); + const FALLBACK = "events/stream for 'tick' failed before its first notifications/events/active; subscribing by poll instead"; + + async function pushOrPoll(stream: Handler) { + const scripted = await connectEvents({ + 'events/list': listing(both), + 'events/stream': stream, + 'events/poll': script({ events: [occurrence('e1')], cursor: 'c1', nextPollMs: 60_000 }) + }); + const errors: Error[] = []; + scripted.client.onerror = error => void errors.push(error); + return { + ...scripted, + errors, + streams: () => callsTo(scripted.calls, 'events/stream'), + polls: () => callsTo(scripted.calls, 'events/poll') + }; + } + + it.each([ + [ + 'no valid active arrives within the request timeout', + () => new Promise(() => {}), + { code: SdkErrorCode.RequestTimeout } + ], + [ + 'the stream fails with an error that is not an Events kind', + script(new RpcError(-32_603, 'Internal error')), + { code: -32_603 } + ] + ])('subscribes by poll when %s, and reports the push failure', async (_case, stream, cause) => { + const { events, errors, streams, polls } = await pushOrPoll(stream); + const subscribing = events.subscribe({ name: 'tick', cursor: 'c0' }); + await settle(); + await vi.advanceTimersByTimeAsync(60_000); + const subscription = await subscribing; + subscriptions.push(subscription); + + expect(subscription.deliveryMode).toBe('poll'); + expect(await nextEventId(subscription[Symbol.asyncIterator]())).toBe('e1'); + expect(streams()).toHaveLength(1); + expect(polls()[0]!.params['cursor']).toBe('c0'); + expect(errors).toEqual([expect.objectContaining({ message: FALLBACK, cause: expect.objectContaining(cause) })]); + }); + + it('rejects as before when delivery forces push', async () => { + const { events, errors, streams, polls } = await pushOrPoll(() => new Promise(() => {})); + const subscribing = events.subscribe({ name: 'tick', delivery: 'push' }).catch((error_: unknown) => error_); + await settle(); + await vi.advanceTimersByTimeAsync(60_000); + + const error = await subscribing; + expect(error).toBeInstanceOf(SdkError); + expect(error).toMatchObject({ code: SdkErrorCode.RequestTimeout }); + expect(streams()).toHaveLength(1); + expect(polls()).toHaveLength(0); + expect(errors).toEqual([]); + }); + + it('rejects as before when the first stream is refused with an EventsError', async () => { + const { events, errors, polls } = await pushOrPoll(script(new RpcError(-32_024, 'Forbidden'))); + const error = await events.subscribe({ name: 'tick' }).catch((error_: unknown) => error_); + + expect(error).toBeInstanceOf(EventsError); + expect(error).toMatchObject({ kind: 'forbidden' }); + expect(polls()).toHaveLength(0); + expect(errors).toEqual([]); + expect(vi.getTimerCount()).toBe(0); + }); + }); + it('ends the stream on an active that fails its schema: subscribe() rejects, and once subscribed it reopens', async () => { const first = await pushWith(); const errors: Error[] = []; diff --git a/packages/server/src/ext/events/node.ts b/packages/server/src/ext/events/node.ts index 0f885335e4..39bab1795e 100644 --- a/packages/server/src/ext/events/node.ts +++ b/packages/server/src/ext/events/node.ts @@ -30,10 +30,10 @@ const TLS_FAILURE_CODE = /CERT|UNABLE_TO_VERIFY|INVALID_CA|SELF_SIGNED|DEPTH_ZER * (with a DNS query, not `getaddrinfo`, so `/etc/hosts` does not apply), * refuses with `connection_refused` when any resolved address is in an IANA * special-purpose range (loopback, private, link-local and the like), and - * connects to the checked address with the URL's host name in the `Host` - * header and TLS SNI. It follows no redirects (a 3xx answer is returned as it - * is), gives up after 5 seconds with `{ error: 'timeout' }`, and reads at most - * 64 KiB of the response body. + * connects only to the addresses it checked, which Node tries in turn, with + * the URL's host name in the `Host` header and TLS SNI. It follows no + * redirects (a 3xx answer is returned as it is), gives up after 5 seconds + * with `{ error: 'timeout' }`, and reads at most 64 KiB of the response body. * * Experimental: Events (SEP-3415) is new; this API may change in a minor release. * @@ -60,9 +60,10 @@ async function send(request: WebhookSendRequest): Promise { let lookup: LookupFunction | undefined; if (!request.trusted) { const addresses = await resolve(hostnameOf(url), deadline.signal); - const [first] = addresses; - if (first === undefined || addresses.some(({ address }) => isSpecialPurposeAddress(address))) return REFUSED; - lookup = pinnedTo(first); + // An abort while one family was still resolving leaves the other family's addresses. + deadline.signal.throwIfAborted(); + if (addresses.length === 0 || addresses.some(({ address }) => isSpecialPurposeAddress(address))) return REFUSED; + lookup = pinnedTo(addresses); } return await post(url, request, lookup, deadline.signal); } catch (error) { @@ -73,9 +74,10 @@ async function send(request: WebhookSendRequest): Promise { } } -// One POST; it rejects on a connection or TLS failure, and once `signal` aborts. +// One POST; it rejects on a connection or TLS failure, and once `signal` aborts (at once, without a request, when it already has). function post(url: URL, request: WebhookSendRequest, lookup: LookupFunction | undefined, signal: AbortSignal): Promise { return new Promise((resolve, reject) => { + signal.throwIfAborted(); const onResponse = (response: IncomingMessage): void => { const chunks: Buffer[] = []; let size = 0; @@ -131,11 +133,19 @@ function hostnameOf(url: URL): string { return url.hostname.startsWith('[') ? url.hostname.slice(1, -1) : url.hostname; } -// A lookup that answers with the checked address only, so the connection goes nowhere else. -function pinnedTo({ address, family }: LookupAddress): LookupFunction { - return (_hostname, options, callback) => { - if (options.all) callback(null, [{ address, family }]); - else callback(null, address, family); +// A lookup that answers with checked addresses only, so the connection goes nowhere else: those of the family asked for, all of them when asked for all (Node then tries each), else the first. +function pinnedTo(addresses: readonly LookupAddress[]): LookupFunction { + return (hostname, options, callback) => { + const family = options.family === 'IPv4' ? 4 : options.family === 'IPv6' ? 6 : options.family; + const answers = family === 4 || family === 6 ? addresses.filter(address => address.family === family) : addresses; + const [first] = answers; + if (first === undefined) { + callback(Object.assign(new Error(`getaddrinfo ENOTFOUND ${hostname}`), { code: 'ENOTFOUND', hostname }), []); + } else if (options.all) { + callback(null, [...answers]); + } else { + callback(null, first.address, first.family); + } }; } diff --git a/packages/server/src/ext/events/poll.ts b/packages/server/src/ext/events/poll.ts index 557709745e..6113e25a9c 100644 --- a/packages/server/src/ext/events/poll.ts +++ b/packages/server/src/ext/events/poll.ts @@ -48,7 +48,7 @@ export async function toOccurrence( }; } -// A check result's events to send, for every mode: off-schema ones dropped (reported), ones older than `maxAgeMs` skipped with `truncated` unless the result has no replay (`cursor: null`), which `maxAgeMs` does not apply to. +// A check result's events to send, for every mode: ones without an eventId or off-schema dropped (reported), ones older than `maxAgeMs` skipped with `truncated` unless the result has no replay (`cursor: null`), which `maxAgeMs` does not apply to. export async function checkedEvents( entry: RegisteredEvent, result: EventResult, @@ -59,6 +59,11 @@ export async function checkedEvents( let truncated = result.truncated === true; const events: EventOccurrence[] = []; for (const input of result.events) { + // A generated id would differ on every read of the event, so only emit() makes one. + if (typeof input.eventId !== 'string' || input.eventId === '') { + report(new Error(`event '${entry.name}': dropped an event from check without an eventId`)); + continue; + } const occurrence = await toOccurrence(entry, input, report); if (occurrence === undefined) continue; if (floor !== undefined && Date.parse(occurrence.timestamp) < floor) { diff --git a/packages/server/src/ext/events/types.ts b/packages/server/src/ext/events/types.ts index 151564d624..2fb10ac26a 100644 --- a/packages/server/src/ext/events/types.ts +++ b/packages/server/src/ext/events/types.ts @@ -43,14 +43,14 @@ export interface CheckContext extends EventContext { /** * One event as an author produces it. The SDK fills `name` and `cursor`, and - * `eventId` and `timestamp` when absent. + * `timestamp` when absent; `emit()` also fills `eventId` when absent. * * Experimental: Events (SEP-3415) is new; this API may change in a minor release. * * @experimental */ export interface EventInput

> { - /** A unique id; the SDK generates one when absent. */ + /** The upstream event's stable id, for deduplication: required in a `check` result; `emit()` generates one when absent. */ eventId?: string; /** ISO 8601 time of the occurrence; the SDK uses the current time when absent. */ timestamp?: string; @@ -67,7 +67,11 @@ export interface EventInput

> { * @experimental */ export interface EventResult

> { - events: EventInput

[]; + /** + * Each with an `eventId` that stays the same whenever `check` returns the event again, as a replay does; the SDK + * drops an event without one (a non-empty string) and reports it to `onerror`. + */ + events: Array & { eventId: string }>; /** Where the next `check` resumes; `null` when the upstream cannot resume. */ cursor: string | null; /** diff --git a/packages/server/src/ext/events/webhookEngine.ts b/packages/server/src/ext/events/webhookEngine.ts index dc27fae520..f6d36e0b99 100644 --- a/packages/server/src/ext/events/webhookEngine.ts +++ b/packages/server/src/ext/events/webhookEngine.ts @@ -17,6 +17,8 @@ const FINAL_STATUSES: ReadonlySet = new Set([410, 413]); const MAX_BODY_BYTES = 262_144; // The most messages a suspended subscription holds: as many as the emit buffer holds by default. const MAX_PARKED_MESSAGES = 10_000; +// The most event messages of one subscription in progress at once, each from its first attempt until it is settled or parked. +const MAX_IN_FLIGHT_PER_SUBSCRIPTION = 10; // Delivery is suspended once more than 95 % of at least 100 attempts in the last 60 minutes failed. const SUSPENSION_WINDOW_MS = 3_600_000; const SUSPENSION_MIN_ATTEMPTS = 100; @@ -50,6 +52,8 @@ interface Message { readonly position: string | null; attempts: number; done: boolean; + // Holds one of the subscription's MAX_IN_FLIGHT_PER_SUBSCRIPTION slots. + running: boolean; retry?: ReturnType; } @@ -75,9 +79,14 @@ interface Tracked { watermark: string | null; // Messages not yet acknowledged or abandoned, in position order. readonly pending: Message[]; + // How many messages hold a slot, and the messages waiting for one, in position order. + running: number; + waiting: Message[]; // Messages that came due while delivery was suspended, oldest first. parked: Message[]; active: boolean; + // The record's expiresAt when delivery was suspended; a later one means a refresh, on any replica, since. + suspendedExpiresAt?: number; lastDeliveryAt: string | null; lastError: DeliveryErrorCategory | null; // The first failure since the last acknowledgement. @@ -237,9 +246,11 @@ export class WebhookEngine { // Queues one event POST and returns; calls for one subscription come in position order, and `seed` starts the watermark of an untracked id. deliver(record: WebhookSubscriptionRecord, occurrence: EventOccurrence, position: string | null, seed: string | null): void { const tracked = this.#tracked.get(record.id) ?? this.#start(record.id, seed); - const message: Message = { webhookId: generateWebhookId(), occurrence, position, attempts: 0, done: false }; + const message: Message = { webhookId: generateWebhookId(), occurrence, position, attempts: 0, done: false, running: false }; tracked.pending.push(message); - this.#attempt(tracked, message, record); + // A message that waits for a slot reads the record when it starts, as a retry does. + if (tracked.running < MAX_IN_FLIGHT_PER_SUBSCRIPTION) this.#begin(tracked, message, record); + else tracked.waiting.push(message); } // Queues a control body, retried like an event, and resolves with its last answer (`undefined` without one); request paths must not await it. @@ -280,16 +291,19 @@ export class WebhookEngine { return failedSince === undefined ? { active, lastDeliveryAt, lastError } : { active, lastDeliveryAt, lastError, failedSince }; } - // Reactivates a suspended subscription and retries the messages that waited. + // Reactivates a suspended subscription and retries the messages that waited, in position order as slots free. resume(id: string): void { const tracked = this.#tracked.get(id); if (tracked === undefined || tracked.active) return; tracked.active = true; + tracked.suspendedExpiresAt = undefined; tracked.recent = []; tracked.recentFailures = 0; - const parked = tracked.parked; + const parked = new Set(tracked.parked); tracked.parked = []; - for (const message of parked) this.#attempt(tracked, message); + // Parked messages had started, so they come before every message still waiting. + tracked.waiting = [...tracked.pending.filter(message => parked.has(message)), ...tracked.waiting]; + this.#fill(tracked); } // Drops the subscription's delivery state and stops its control bodies; its last subscription also drops a (principal, url) verification. @@ -435,6 +449,8 @@ export class WebhookEngine { ended: new AbortController(), watermark, pending: [], + running: 0, + waiting: [], parked: [], active: true, lastDeliveryAt: null, @@ -458,6 +474,30 @@ export class WebhookEngine { return this.#tracked.get(tracked.id) === tracked; } + // Gives `message` a slot and runs its first attempt. + #begin(tracked: Tracked, message: Message, record?: WebhookSubscriptionRecord): void { + message.running = true; + tracked.running += 1; + this.#attempt(tracked, message, record); + } + + // Starts waiting messages, oldest first, while a slot is free. + #fill(tracked: Tracked): void { + while (tracked.running < MAX_IN_FLIGHT_PER_SUBSCRIPTION) { + const next = tracked.waiting.shift(); + if (next === undefined) return; + this.#begin(tracked, next); + } + } + + // Frees the message's slot, if it holds one, for the next message waiting. + #release(tracked: Tracked, message: Message): void { + if (!message.running) return; + message.running = false; + tracked.running -= 1; + this.#fill(tracked); + } + // Runs one attempt off the caller's path; an unexpected failure is reported and retried like a failed send. #attempt(tracked: Tracked, message: Message, record?: WebhookSubscriptionRecord): void { this.#try(tracked, message, record).catch((error: unknown) => { @@ -476,6 +516,8 @@ export class WebhookEngine { this.forget(tracked.id); return; } + // A refresh served by another replica ends the suspension here too. + if (!tracked.active && record.expiresAt > tracked.suspendedExpiresAt!) this.resume(tracked.id); if (!tracked.active) { // A parked message keeps this attempt for the resume. message.attempts -= 1; @@ -496,7 +538,9 @@ export class WebhookEngine { } const outcome = await this.#post(record.url, record.id, this.#secretsOf(record), message.webhookId, body, tracked.ended.signal); if (!this.#isCurrent(tracked)) return; - if (this.#observe(tracked, outcome)) this.#retry(tracked, message); + const retry = this.#observe(tracked, outcome); + if (!tracked.active) tracked.suspendedExpiresAt ??= record.expiresAt; + if (retry) this.#retry(tracked, message); else this.#settle(tracked, message); } @@ -509,14 +553,15 @@ export class WebhookEngine { message.retry = unref(setTimeout(() => this.#attempt(tracked, message), delay)); } - // Holds a message until resume(); past the cap the oldest one held is abandoned. + // Holds a message until resume(), out of its slot; past the cap the oldest one held is abandoned. #park(tracked: Tracked, message: Message): void { tracked.parked.push(message); + this.#release(tracked, message); const oldest = tracked.parked.length > MAX_PARKED_MESSAGES ? tracked.parked.shift() : undefined; if (oldest !== undefined) this.#settle(tracked, oldest); } - // Marks the message acknowledged or abandoned, and moves the watermark past the finished messages at the front. + // Marks the message acknowledged or abandoned, moves the watermark past the finished messages at the front, and frees its slot. #settle(tracked: Tracked, message: Message): void { message.done = true; let head = tracked.pending[0]; @@ -525,6 +570,7 @@ export class WebhookEngine { tracked.watermark = head.position; head = tracked.pending[0]; } + this.#release(tracked, message); } // Records one outcome in the delivery status and returns whether to retry; 410 and 413 end the message, setting lastError only. diff --git a/packages/server/src/ext/events/webhookSubscriptions.ts b/packages/server/src/ext/events/webhookSubscriptions.ts index f35b9b9a14..b6e332fb1d 100644 --- a/packages/server/src/ext/events/webhookSubscriptions.ts +++ b/packages/server/src/ext/events/webhookSubscriptions.ts @@ -24,6 +24,8 @@ const TTL_FLOOR_MS = 60_000; const ROTATION_GRACE_MS = 300_000; // setTimeout fires at once for longer delays; a longer grant re-arms when the timer fires early. const MAX_TIMER_DELAY_MS = 2 ** 31 - 1; +// The waits between the three attempts of an emit's fan-out whose store read fails; after the last the failure is reported. +const FAN_OUT_RETRY_DELAYS_MS = [100, 200]; const encoder = new TextEncoder(); let unwatched: AbortSignal | undefined; @@ -522,16 +524,29 @@ export class WebhookSubscriptions implements SubscriptionSource { return makeContext({ name: record.name, subscriptionId: record.id, principal: record.principal, mode: 'webhook', signal }); } + // A failed store read lists the subscriptions again after a wait, skipping those this emit already reached; the last failure throws. async #deliverEmitted(entry: RegisteredEvent, buffered: BufferedEvent, cursor: string, previous: string): Promise { - for await (const record of this.#recordsFor(entry.name, buffered.target)) { - if (isExpired(record)) { - this.#later(record.id, () => this.#recheck(record.id)); - continue; + const reached = new Set(); + for (let attempt = 0; ; attempt++) { + try { + for await (const record of this.#recordsFor(entry.name, buffered.target)) { + if (reached.has(record.id)) continue; + reached.add(record.id); + if (isExpired(record)) { + this.#later(record.id, () => this.#recheck(record.id)); + continue; + } + const ctx = this.#watched.get(record.id)?.ctx ?? this.#contextOf(record, unwatchedSignal()); + const selected = selectEvent(entry, ctx, record.arguments, buffered, this.#deps.report); + const occurrence = selected === undefined ? undefined : await checkedSelection(entry, selected, this.#deps.report); + if (occurrence !== undefined) this.#engine.deliver(record, occurrence, cursor, previous); + } + return; + } catch (error) { + const delay = FAN_OUT_RETRY_DELAYS_MS[attempt]; + if (delay === undefined) throw error; + await new Promise(resolve => unref(setTimeout(resolve, delay))); } - const ctx = this.#watched.get(record.id)?.ctx ?? this.#contextOf(record, unwatchedSignal()); - const selected = selectEvent(entry, ctx, record.arguments, buffered, this.#deps.report); - const occurrence = selected === undefined ? undefined : await checkedSelection(entry, selected, this.#deps.report); - if (occurrence !== undefined) this.#engine.deliver(record, occurrence, cursor, previous); } } diff --git a/packages/server/test/ext/events/node.test.ts b/packages/server/test/ext/events/node.test.ts index 79032e4356..4af96d9201 100644 --- a/packages/server/test/ext/events/node.test.ts +++ b/packages/server/test/ext/events/node.test.ts @@ -3,6 +3,7 @@ import http from 'node:http'; import https from 'node:https'; import type { AddressInfo } from 'node:net'; import net from 'node:net'; +import os from 'node:os'; import { Writable } from 'node:stream'; import type { MockInstance } from 'vitest'; @@ -44,24 +45,27 @@ afterEach(async () => { ); }); -async function listen(server: net.Server): Promise { +async function listen(server: net.Server, host = '127.0.0.1'): Promise { servers.push(server); - await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); + await new Promise(resolve => server.listen(0, host, resolve)); return (server.address() as AddressInfo).port; } // A raw TCP server that counts connections and closes each one at once. -async function countingServer(): Promise<{ port: number; connections: () => number }> { +async function countingServer(host?: string): Promise<{ port: number; connections: () => number }> { let connections = 0; const port = await listen( net.createServer(socket => { connections += 1; socket.destroy(); - }) + }), + host ); return { port, connections: () => connections }; } +const hasIpv6Loopback = Object.values(os.networkInterfaces()).some(entries => entries?.some(entry => entry.address === '::1')); + function sendRequest(url: string, trusted: boolean, signal = new AbortController().signal): WebhookSendRequest { return { url, headers: HEADERS, body: BODY, trusted, signal }; } @@ -87,29 +91,51 @@ function stubResolver(...answers: string[][]): { resolve4: Resolve; resolve6: Re return { resolve4: stub('resolve4', 4), resolve6: stub('resolve6', 6) }; } -// Stands in for https.request: records the address its pinned lookup gives, and fails the connection. -function captureConnection(): { pinned: () => Promise<{ address: string; family: number }> } { - let lookup: net.LookupFunction | undefined; +type Answer = { address: string; family: number } | dns.LookupAddress[]; + +// Stands in for https.request: keeps the pinned lookup, which `lookup` calls with the options Node would pass, and fails the connection. +function captureConnection(): { pinned: () => Promise; lookup: (options: dns.LookupOptions) => Promise } { + let pinned: net.LookupFunction | undefined; vi.spyOn(https, 'request').mockImplementation(((_url: URL, options: https.RequestOptions) => { - lookup = options.lookup as net.LookupFunction; + pinned = options.lookup as net.LookupFunction; return failingRequest('ECONNREFUSED'); }) as unknown as typeof https.request); - return { - pinned: () => - new Promise((resolve, reject) => - lookup!('pinned.invalid', {}, (error, address, family) => - error ? reject(error) : resolve({ address: address as string, family: family! }) - ) - ) - }; + const lookup = (options: dns.LookupOptions): Promise => + new Promise((resolve, reject) => + pinned!('pinned.invalid', options, (error, address, family) => { + if (error) reject(error); + else resolve(Array.isArray(address) ? address : { address, family: family! }); + }) + ); + return { pinned: () => lookup({}), lookup }; } -// Classifies `ip` as a public address, so a loopback server can stand in for a remote receiver. -async function treatAsPublic(ip: string): Promise { +// Classifies `ips` as public addresses, so a loopback server can stand in for a remote receiver. +async function treatAsPublic(...ips: string[]): Promise { const actual = await vi.importActual( '../../../src/ext/events/specialAddresses' ); - vi.mocked(isSpecialPurposeAddress).mockImplementation(address => address !== ip && actual.isSpecialPurposeAddress(address)); + vi.mocked(isSpecialPurposeAddress).mockImplementation(address => !ips.includes(address) && actual.isSpecialPurposeAddress(address)); +} + +// A resolver whose `family` query answers at once with `addresses` and whose other query waits for cancel(). +function halfAnsweringResolver(family: 4 | 6, addresses: string[]): void { + const pending: Array<(error: Error) => void> = []; + const [answering, hanging] = family === 4 ? (['resolve4', 'resolve6'] as const) : (['resolve6', 'resolve4'] as const); + vi.spyOn(dns.promises.Resolver.prototype, answering).mockResolvedValue(addresses as never); + vi.spyOn(dns.promises.Resolver.prototype, hanging).mockImplementation( + () => new Promise((_resolve, reject) => pending.push(reject)) as never + ); + vi.spyOn(dns.promises.Resolver.prototype, 'cancel').mockImplementation(() => { + for (const reject of pending.splice(0)) reject(dnsError('ECANCELLED')); + }); +} + +// Stands in for https.request with a request that never answers. +function hangingRequests(): void { + vi.spyOn(https, 'request').mockImplementation( + () => new Writable({ write: (_chunk, _encoding, callback) => callback() }) as unknown as http.ClientRequest + ); } // A stand-in for the outgoing request that fails with `code` once its body is sent. @@ -223,6 +249,68 @@ describe('nodeWebhookSender', () => { expect(cancel).toHaveBeenCalledOnce(); }); + it('times out at the deadline without a request when one family answered and the other was still resolving', async () => { + vi.useFakeTimers(); + halfAnsweringResolver(4, ['1.1.1.1']); + hangingRequests(); + let settled: unknown; + void nodeWebhookSender()(sendRequest('https://half.example.test/x', false)).then(outcome => (settled = outcome)); + + await vi.advanceTimersByTimeAsync(4999); + expect(settled).toBeUndefined(); + await vi.advanceTimersByTimeAsync(1); + expect(settled).toEqual({ error: 'timeout' }); + expect(https.request).not.toHaveBeenCalled(); + }); + + it('sends nothing when its signal aborts while one family is still resolving', async () => { + halfAnsweringResolver(6, ['2606:4700:4700::1111']); + hangingRequests(); + const controller = new AbortController(); + + const outcome = nodeWebhookSender()(sendRequest('https://half.example.test/x', false, controller.signal)); + await vi.waitFor(() => expect(dns.promises.Resolver.prototype.resolve6).toHaveBeenCalled()); + controller.abort(); + + expect(await outcome).toEqual(REFUSED); + expect(https.request).not.toHaveBeenCalled(); + }); + + it('answers every checked address of both families when asked for all, and only those of the family asked for', async () => { + stubResolver(['1.1.1.1', '1.0.0.1', '2606:4700:4700::1111']); + const connection = captureConnection(); + + expect(await nodeWebhookSender()(sendRequest('https://dual.example.test/x', false))).toEqual(REFUSED); + expect(await connection.lookup({ all: true })).toEqual([ + { address: '1.1.1.1', family: 4 }, + { address: '1.0.0.1', family: 4 }, + { address: '2606:4700:4700::1111', family: 6 } + ]); + expect(await connection.lookup({ all: true, family: 6 })).toEqual([{ address: '2606:4700:4700::1111', family: 6 }]); + expect(await connection.lookup({ family: 6 })).toEqual({ address: '2606:4700:4700::1111', family: 6 }); + expect(await connection.lookup({ family: 'IPv4' })).toEqual({ address: '1.1.1.1', family: 4 }); + expect(await connection.lookup({})).toEqual({ address: '1.1.1.1', family: 4 }); + }); + + it('fails the lookup for a family with no checked address', async () => { + stubResolver(['1.1.1.1']); + const connection = captureConnection(); + + await nodeWebhookSender()(sendRequest('https://v4only.example.test/x', false)); + await expect(connection.lookup({ all: true, family: 6 })).rejects.toMatchObject({ code: 'ENOTFOUND' }); + await expect(connection.lookup({ family: 6 })).rejects.toMatchObject({ code: 'ENOTFOUND' }); + }); + + it.skipIf(!hasIpv6Loopback)('connects to the AAAA address when the A address refuses', async () => { + const receiver = await countingServer('::1'); + await treatAsPublic('127.0.0.1', '::1'); + stubResolver(['127.0.0.1', '::1']); + + // Nothing listens on 127.0.0.1 at the receiver's port; the receiver closes the connection it gets. + expect(await nodeWebhookSender()(sendRequest(`https://dual.example.test:${receiver.port}/x`, false))).toEqual(REFUSED); + expect(receiver.connections()).toBe(1); + }); + it('connects to the checked address and sends the URL host name as TLS SNI', async () => { let clientHello: Buffer | undefined; const port = await listen( diff --git a/packages/server/test/ext/events/poll.test.ts b/packages/server/test/ext/events/poll.test.ts index 9b98c83ac7..27341e4e77 100644 --- a/packages/server/test/ext/events/poll.test.ts +++ b/packages/server/test/ext/events/poll.test.ts @@ -37,7 +37,7 @@ afterEach(() => { describe('events/poll for a check type', () => { it('bootstraps a check type with cursor null', async () => { const events = new EventsExtension(); - const check = vi.fn(() => ({ events: [{ data: { n: 1 } }], cursor: 'h1' })); + const check = vi.fn(() => ({ events: [{ eventId: 'e1', data: { n: 1 } }], cursor: 'h1' })); events.registerEvent('t', { payloadSchema: P, check }); const { rpc } = poller(events); expect(bodyOf(await rpc('events/poll', { name: 't', cursor: null }))).toEqual({ @@ -60,13 +60,13 @@ describe('events/poll for a check type', () => { expect(check.mock.calls[0]![2]).toBeNull(); }); - it('fills name, timestamp and eventId on check events', async () => { + it('fills name and timestamp on check events', async () => { const events = new EventsExtension({ defaultNextPollMs: 1000 }); events.registerEvent('t', { payloadSchema: P, check: () => ({ events: [ - { data: { n: 1 } }, + { eventId: 'upstream-1', data: { n: 1 } }, { eventId: 'upstream-2', timestamp: '2026-01-01T00:00:00.000Z', data: { n: 2 }, _meta: { k: 1 } } ], cursor: 'h2', @@ -75,8 +75,7 @@ describe('events/poll for a check type', () => { }); const result = await poller(events).poll({ name: 't', cursor: 'h1' }); const [first, second] = result.events; - expect(first!.eventId).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/); - expect(first).toMatchObject({ name: 't', data: { n: 1 } }); + expect(first).toMatchObject({ eventId: 'upstream-1', name: 't', data: { n: 1 } }); expect(new Date(first!.timestamp).toISOString()).toBe(first!.timestamp); expect(first).not.toHaveProperty('cursor'); expect(second).toEqual({ @@ -158,7 +157,7 @@ describe('events/poll for a check type', () => { it('starts a type with replay from now on every cursor: null poll', async () => { const events = new EventsExtension(); - events.registerEvent('t', { payloadSchema: P, check: () => ({ events: [{ data: { n: 1 } }], cursor: 'h1' }) }); + events.registerEvent('t', { payloadSchema: P, check: () => ({ events: [{ eventId: 'e1', data: { n: 1 } }], cursor: 'h1' }) }); const { poll } = poller(events); expect(await poll({ name: 't', cursor: null })).toMatchObject({ events: [], cursor: 'h1' }); expect(await poll({ name: 't', cursor: null })).toMatchObject({ events: [], cursor: 'h1' }); @@ -198,6 +197,23 @@ describe('events/poll for a check type', () => { expect(unbounded.truncated).toBe(false); }); + it('drops a check event without an eventId and reports it', async () => { + const onerror = vi.fn(); + const events = new EventsExtension({ onerror }); + // As plain JavaScript returns them, past the type that requires eventId. + const unidentified = [{ data: { n: 1 } }, { eventId: '', data: { n: 2 } }] as Array<{ eventId: string; data: { n: number } }>; + events.registerEvent('t', { + payloadSchema: P, + check: () => ({ events: [...unidentified, { eventId: 'kept', data: { n: 3 } }], cursor: 'h2' }) + }); + const result = await poller(events).poll({ name: 't', cursor: 'h1' }); + expect(result.events.map(event => event.eventId)).toEqual(['kept']); + expect(onerror).toHaveBeenCalledTimes(2); + for (const [error] of onerror.mock.calls) { + expect((error as Error).message).toBe("event 't': dropped an event from check without an eventId"); + } + }); + it('drops an off-schema check payload and reports it', async () => { const onerror = vi.fn(); const events = new EventsExtension({ onerror }); @@ -291,6 +307,18 @@ describe('events/poll for an emit-only type', () => { expect(result.events[0]!.eventId).toEqual(expect.any(String)); }); + it('gives an emit without an eventId a generated one, the same on every read', async () => { + const events = new EventsExtension(); + const h = events.registerEvent('i', { emitOnly: true, payloadSchema: P }); + const { poll } = poller(events); + const { cursor } = await poll({ name: 'i', cursor: null }); + await h.emit({ data: { n: 1 } }); + const [first] = (await poll({ name: 'i', cursor })).events; + const [again] = (await poll({ name: 'i', cursor })).events; + expect(first!.eventId).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/); + expect(again!.eventId).toBe(first!.eventId); + }); + it('reports a gap for a cursor from before a restart (Review Focus 5)', async () => { const events = new EventsExtension(); const h = events.registerEvent('i', { emitOnly: true, payloadSchema: P }); diff --git a/packages/server/test/ext/events/push.test.ts b/packages/server/test/ext/events/push.test.ts index bf52872eeb..6a695723a2 100644 --- a/packages/server/test/ext/events/push.test.ts +++ b/packages/server/test/ext/events/push.test.ts @@ -263,6 +263,22 @@ describe('events/stream: a check type', () => { expect(check.mock.calls[0]![0]).toMatchObject({ mode: 'push', maxAgeMs: 300_000 }); }); + it('drops a check event without an eventId and reports it', async () => { + const onerror = vi.fn(); + // As plain JavaScript returns it, past the type that requires eventId. + const unidentified = { data: { n: 1 } } as { eventId: string; data: { n: number } }; + const check = vi.fn(() => ({ events: [unidentified, { eventId: 'kept', data: { n: 2 } }], cursor: 'h2' })); + const events = new EventsExtension({ onerror }); + events.registerEvent('tick', { payloadSchema: P, check }); + const stream = await open(serve(events), { name: 'tick', cursor: 'h1' }); + expect(await next(stream)).toMatchObject({ method: ACTIVE, params: { cursor: 'h1', truncated: false } }); + expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'kept', data: { n: 2 }, cursor: 'h2' } }); + expect(onerror).toHaveBeenCalledOnce(); + expect(onerror).toHaveBeenCalledWith( + expect.objectContaining({ message: "event 'tick': dropped an event from check without an eventId" }) + ); + }); + it('keeps the stream open after a transient check error', async () => { vi.useFakeTimers({ shouldAdvanceTime: true }); const check = vi diff --git a/packages/server/test/ext/events/registration.test.ts b/packages/server/test/ext/events/registration.test.ts index 5bad5661b9..a8adeb3ae5 100644 --- a/packages/server/test/ext/events/registration.test.ts +++ b/packages/server/test/ext/events/registration.test.ts @@ -208,6 +208,13 @@ describe('registerEvent', () => { expectTypeOf(checkHandle.update).toBeCallableWith({ description: 'v2' }); }); + it('requires an eventId on every event a check returns', () => { + const events = new EventsExtension(); + // @ts-expect-error a check event needs its eventId + events.registerEvent('a', { payloadSchema: P, check: () => ({ events: [{ data: { n: 1 } }], cursor: null }) }); + events.registerEvent('b', { payloadSchema: P, check: () => ({ events: [{ eventId: 'e1', data: { n: 1 } }], cursor: null }) }); + }); + it('refuses the same schemas again and terminates live subscriptions when a schema changes', async () => { const events = new EventsExtension(); const terminate = vi.fn(async () => {}); diff --git a/packages/server/test/ext/events/webhookEngine.test.ts b/packages/server/test/ext/events/webhookEngine.test.ts index c14fdecd54..2d3ea05efb 100644 --- a/packages/server/test/ext/events/webhookEngine.test.ts +++ b/packages/server/test/ext/events/webhookEngine.test.ts @@ -115,6 +115,49 @@ function bodyOf(request: WebhookSendRequest): Record { return JSON.parse(request.body) as Record; } +// Delivers events `from` to `to` (at positions p{from} to p{to}) to a receiver that fails them, and moves the clock through all five +// attempts of each, ten at a time, until the last is abandoned; `sent` counts the requests before, and the count after is returned. +async function failThrough( + engine: WebhookEngine, + record: WebhookSubscriptionRecord, + until: (count: number) => Promise, + sent: number, + from: number, + to: number +): Promise { + for (let n = from; n <= to; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + for (let left = to - from + 1; left > 0; left -= 10) { + const batch = Math.min(10, left); + sent += batch; + await until(sent); + for (const delay of DELAYS) { + await settle(); + await vi.advanceTimersByTimeAsync(delay); + sent += batch; + await until(sent); + } + await settle(); + } + return sent; +} + +// A responder that holds each event POST until the test answers it, counting how many are in flight at most. +function held() { + const answers: Array<() => void> = []; + let inFlight = 0; + let most = 0; + const respond: Respond = () => + new Promise(resolve => { + inFlight += 1; + most = Math.max(most, inFlight); + answers.push(() => { + inFlight -= 1; + resolve({ status: 200, body: '' }); + }); + }); + return { respond, answers, most: () => most }; +} + // The body cursor of each event POST by eventId; signing is asynchronous, so the sends need not come in delivery order. function cursorsByEvent(requests: WebhookSendRequest[]): Record { return Object.fromEntries(requests.map(request => [bodyOf(request).eventId, bodyOf(request).cursor])); @@ -503,6 +546,42 @@ describe('event delivery', () => { expect(engine.watermark(ID)).toBeNull(); }); + it('has at most 10 messages of a subscription in flight, a retry wait included, and starts the rest in position order', async () => { + let failing = true; + const hold = held(); + const { engine, record, requests, until } = setup(request => + failing && bodyOf(request).eventId === 'evt_1' ? { status: 503, body: '' } : hold.respond(request) + ); + engine.track(ID, 'p0'); + for (let n = 1; n <= 25; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await until(10); + await settle(); + expect(requests).toHaveLength(10); + // evt_1 keeps its slot while it waits for its retry; each other answer frees a slot for the next message. + for (let n = 0; n < 9; n++) { + hold.answers[n]!(); + await until(11 + n); + } + await settle(); + expect(requests).toHaveLength(19); + expect(requests.slice(10).map(request => bodyOf(request).eventId)).toEqual(Array.from({ length: 9 }, (_, n) => `evt_${11 + n}`)); + expect(engine.watermark(ID)).toBe('p0'); + + failing = false; + await vi.advanceTimersByTimeAsync(5000); + await until(20); + // Each answer frees a slot for the next message, which starts before the next answer. + for (let n = 9; n < 25; n++) { + hold.answers[n]!(); + await until(Math.min(n + 12, 26)); + } + await settle(); + expect(requests).toHaveLength(26); + expect(requests.slice(20).map(request => bodyOf(request).eventId)).toEqual(Array.from({ length: 6 }, (_, n) => `evt_${20 + n}`)); + expect(hold.most()).toBe(10); + expect(engine.watermark(ID)).toBe('p25'); + }); + it('queues each delivery and returns without waiting for the receiver', async () => { const answers = new Map void>(); const { engine, record, until } = setup(request => new Promise(resolve => answers.set(bodyOf(request).eventId as string, resolve))); @@ -626,35 +705,38 @@ describe('delivery status', () => { const { engine, record, requests, until } = setup(request => healthy || Number((bodyOf(request).eventId as string).slice(4)) <= 5 ? { status: 200, body: '' } : { status: 503, body: '' } ); + const start = Date.now(); engine.track(ID, 'p0'); - for (let n = 1; n <= 100; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); - await until(100); + for (let n = 1; n <= 5; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await until(5); await settle(); - // 95 of 100 attempts failed: not more than 95 %. + // 19 events abandoned after five failed attempts each: 95 of 100 attempts failed, not more than 95 %. + expect(await failThrough(engine, record, until, 5, 6, 24)).toBe(100); expect(engine.status(ID)).toMatchObject({ active: true }); + expect(engine.watermark(ID)).toBe('p24'); - const failedAt = Date.now(); - engine.deliver(record, occurrence('evt_101'), 'p101', null); + engine.deliver(record, occurrence('evt_25'), 'p25', null); await until(101); await settle(); expect(engine.status(ID)).toEqual({ active: false, - lastDeliveryAt: new Date(failedAt).toISOString(), + lastDeliveryAt: new Date(start).toISOString(), lastError: 'http_5xx', - failedSince: new Date(failedAt).toISOString() + failedSince: new Date(start).toISOString() }); - engine.deliver(record, occurrence('evt_102'), 'p102', null); + // evt_25's retry and evt_26 wait for the resume. + engine.deliver(record, occurrence('evt_26'), 'p26', null); await vi.advanceTimersByTimeAsync(600_000); expect(requests).toHaveLength(101); - expect(engine.watermark(ID)).toBe('p5'); + expect(engine.watermark(ID)).toBe('p24'); healthy = true; engine.resume(ID); - await until(101 + 97); + await until(103); await settle(); expect(engine.status(ID)).toEqual({ active: true, lastDeliveryAt: new Date().toISOString(), lastError: null }); - expect(engine.watermark(ID)).toBe('p102'); + expect(engine.watermark(ID)).toBe('p26'); }); it('counts only the attempts of the last 60 minutes', async () => { @@ -663,21 +745,19 @@ describe('delivery status', () => { const record = recordFor({ expiresAt: Date.now() + 86_400_000 }); await store.put(record); engine.track(ID, 'p0'); - for (let n = 1; n <= 99; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); - await until(99); + for (let n = 1; n <= 10; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await until(10); await settle(); failing = false; await vi.advanceTimersByTimeAsync(5000); - await until(198); + await until(20); await settle(); - expect(engine.watermark(ID)).toBe('p99'); + expect(engine.watermark(ID)).toBe('p10'); - // Counted with the hour before, these would be 199 failures in 298 attempts; alone they are 100 in 100. + // Counted with the hour before, these would be 110 failures in 120 attempts, not more than 95 %; alone they are 100 in 100. await vi.advanceTimersByTimeAsync(3_600_000); failing = true; - for (let n = 100; n <= 199; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); - await until(298); - await settle(); + await failThrough(engine, record, until, 20, 11, 30); expect(engine.status(ID)).toMatchObject({ active: false }); }); @@ -686,14 +766,7 @@ describe('delivery status', () => { const { engine, record, requests, until } = setup(() => (healthy ? { status: 200, body: '' } : { status: 503, body: '' })); engine.track(ID, 'p0'); // 20 events, five failed attempts each: the 100th attempt suspends delivery as the last retries give up. - for (let n = 1; n <= 20; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); - await until(20); - for (const [index, delay] of DELAYS.entries()) { - await settle(); - await vi.advanceTimersByTimeAsync(delay); - await until(20 * (index + 2)); - } - await settle(); + await failThrough(engine, record, until, 0, 1, 20); expect(engine.status(ID)).toMatchObject({ active: false }); expect(engine.watermark(ID)).toBe('p20'); @@ -713,8 +786,10 @@ describe('delivery status', () => { it.each(['a due retry', 'a new delivery'])('releases a suspended subscription whose record expired, on %s', async path => { const { engine, store, record, requests, until } = setup(() => ({ status: 503, body: '' })); engine.track(ID, 'p0'); - for (let n = 1; n <= 100; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); - await until(100); + // 95 failed attempts, then five first attempts that fail: the 100th suspends delivery while their retries are due. + const sent = await failThrough(engine, record, until, 0, 1, 19); + for (let n = 20; n <= 24; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await until(sent + 5); await settle(); expect(engine.status(ID)).toMatchObject({ active: false }); @@ -732,6 +807,34 @@ describe('delivery status', () => { expect(requests).toHaveLength(100); }); + it('resumes many parked messages at most 10 in flight, in position order', async () => { + let healthy = false; + const hold = held(); + const { engine, record, requests, until } = setup(request => (healthy ? hold.respond(request) : { status: 503, body: '' })); + engine.track(ID, 'p0'); + await failThrough(engine, record, until, 0, 1, 20); + expect(engine.status(ID)).toMatchObject({ active: false }); + for (let n = 21; n <= 50; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + expect(requests).toHaveLength(100); + + healthy = true; + engine.resume(ID); + await until(110); + await settle(); + expect(requests).toHaveLength(110); + // Each answer frees a slot for the next message waiting. + for (let n = 0; n < 30; n++) { + hold.answers[n]!(); + await until(Math.min(111 + n, 130)); + } + await settle(); + const resumed = requests.slice(100).map(request => bodyOf(request).eventId); + expect(resumed.slice(0, 10).sort()).toEqual(Array.from({ length: 10 }, (_, n) => `evt_${21 + n}`).sort()); + expect(resumed.slice(10)).toEqual(Array.from({ length: 20 }, (_, n) => `evt_${31 + n}`)); + expect(hold.most()).toBe(10); + expect(engine.watermark(ID)).toBe('p50'); + }); + it('resume() does nothing for an active or unknown subscription', async () => { const { engine, record, requests, until } = setup(); engine.resume(ID); diff --git a/packages/server/test/ext/events/webhookSubscriptions.test.ts b/packages/server/test/ext/events/webhookSubscriptions.test.ts index afb4af83d8..5386f2828c 100644 --- a/packages/server/test/ext/events/webhookSubscriptions.test.ts +++ b/packages/server/test/ext/events/webhookSubscriptions.test.ts @@ -6,6 +6,7 @@ import * as z from 'zod/v4'; import type { CheckContext, + EmitOnlyEventHandle, EventContext, EventResult, EventsOptions, @@ -25,6 +26,7 @@ const HOOK = 'https://hooks.example.com/mcp'; const OTHER_HOOK = 'https://other.example.com/hook'; const SECRET = generateWebhookSecret(); const SUB_ID = /^sub_[\w-]{22}$/; +const DELAYS = [5000, 30_000, 120_000, 300_000]; const UNSUPPORTED = { code: -32_026, data: { feature: 'deliveryMode', value: 'webhook' } }; type Respond = (request: WebhookSendRequest) => WebhookSendOutcome | Promise; @@ -132,6 +134,30 @@ function verifies(request: WebhookSendRequest, secret: string): Promise // Lets queued work act on answers already received, without moving the clock. const settle = (): Promise => vi.advanceTimersByTimeAsync(0); +// Emits `count` events that the receiver fails, and moves the clock through all five attempts of each, ten at a time, until the +// last is abandoned; `sent` counts the requests before, and the count after is returned. +async function emitFailing( + handle: EmitOnlyEventHandle<{ n: number }>, + until: (count: number) => Promise, + sent: number, + count: number +): Promise { + for (let n = 1; n <= count; n++) await handle.emit({ data: { n } }); + for (let left = count; left > 0; left -= 10) { + const batch = Math.min(10, left); + sent += batch; + await until(sent); + for (const delay of DELAYS) { + await settle(); + await vi.advanceTimersByTimeAsync(delay); + sent += batch; + await until(sent); + } + await settle(); + } + return sent; +} + const REVOKED = { code: -32_024, message: 'Forbidden', data: { reason: 'Access revoked' } }; function revoked(): EventsError { @@ -176,6 +202,31 @@ class GatedStore extends InMemoryWebhookSubscriptionStore { } } +// A store whose listByName throws after yielding `after` records on the next calls fail() asks for; `listings` counts the calls. +class FlakyStore extends InMemoryWebhookSubscriptionStore { + listings = 0; + #failing = 0; + #after = 0; + + fail(listings: number, after: number): void { + this.#failing = listings; + this.#after = after; + } + + override async *listByName(name: string): AsyncIterable { + this.listings += 1; + const failing = this.#failing > 0; + if (failing) this.#failing -= 1; + let yielded = 0; + for await (const record of super.listByName(name)) { + if (failing && yielded === this.#after) throw new Error('store unavailable'); + yield record; + yielded += 1; + } + if (failing) throw new Error('store unavailable'); + } +} + beforeEach(() => { vi.useFakeTimers(); }); @@ -610,6 +661,45 @@ describe('events/subscribe: creating', () => { expect(cursorOf('first')).not.toBe(cursor); }); + it('replays a backlog of 50 events at most 10 POSTs at a time, starting them in position order', async () => { + const answers: Array<() => void> = []; + let inFlight = 0; + let most = 0; + const { events, post } = replica({ + respond: request => + isVerification(request) + ? echo()(request) + : new Promise(resolve => { + inFlight += 1; + most = Math.max(most, inFlight); + answers.push(() => { + inFlight -= 1; + resolve({ status: 200, body: '' }); + }); + }) + }); + const handle = events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const alice = client(events); + const { cursor } = resultOf(await alice.rpc('events/poll', { name: 'e', cursor: null })) as PollEventsResult; + for (let n = 1; n <= 50; n++) await handle.emit({ eventId: `evt_${n}`, data: { n } }); + + subscribed(await alice.subscribe({ cursor })); + await post.until(11); + await settle(); + expect(post.deliveries()).toHaveLength(10); + // Each answer frees a slot for the next event, which starts before the next answer. + for (let n = 0; n < 50; n++) { + answers[n]!(); + await post.until(Math.min(12 + n, 51)); + } + await settle(); + const replayed = post.deliveries().map(request => bodyOf(request).eventId); + expect(replayed).toHaveLength(50); + expect(replayed.slice(0, 10).sort()).toEqual(Array.from({ length: 10 }, (_, n) => `evt_${n + 1}`).sort()); + expect(replayed.slice(10)).toEqual(Array.from({ length: 40 }, (_, n) => `evt_${n + 11}`)); + expect(most).toBe(10); + }); + it('delivers each event once across the seam between an emit-only replay and live fan-out', async () => { const store = new GatedStore(); const { events, post } = replica({ webhookStore: store }); @@ -716,9 +806,8 @@ describe('events/subscribe: refreshing', () => { const handle = events.registerEvent('e', { emitOnly: true, payloadSchema: P }); const alice = client(events); subscribed(await alice.subscribe()); - for (let n = 1; n <= 100; n++) await handle.emit({ data: { n } }); - await post.until(101); - await settle(); + // 20 events, five failed attempts each: the 100th suspends delivery. + await emitFailing(handle, post.until, 1, 20); expect(subscribed(await alice.subscribe()).deliveryStatus).toMatchObject({ active: false, lastError: 'http_5xx' }); expect(subscribed(await alice.subscribe()).deliveryStatus).toMatchObject({ active: true, lastError: 'http_5xx' }); }); @@ -807,6 +896,38 @@ describe('several replicas sharing one store', () => { expect(a.post.deliveries()).toEqual([]); }); + it('ends a suspension on A when B serves the refresh: A delivers its next emit and what it parked', async () => { + let healthy = false; + const store = new InMemoryWebhookSubscriptionStore(); + const a = replica({ webhookStore: store, respond: echo(() => (healthy ? { status: 200, body: '' } : { status: 503, body: '' })) }); + const b = replica({ webhookStore: store }); + const handle = a.events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + b.events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const { id } = subscribed(await client(a.events).subscribe()); + // 20 events, five failed attempts each: the 100th suspends delivery on A. + const sent = await emitFailing(handle, a.post.until, 1, 20); + await handle.emit({ eventId: 'parked', data: { n: 21 } }); + await settle(); + expect(a.post.requests).toHaveLength(sent); + + healthy = true; + const before = (await store.get(id))!.expiresAt; + subscribed(await client(b.events).subscribe()); + expect((await store.get(id))!.expiresAt).toBeGreaterThan(before); + await handle.emit({ eventId: 'after', data: { n: 22 } }); + await a.post.until(sent + 2); + await settle(); + expect( + a.post.requests + .slice(sent) + .map(request => bodyOf(request).eventId) + .sort() + ).toEqual(['after', 'parked']); + expect(b.post.requests).toHaveLength(0); + // A's own refresh now finds delivery active. + expect(subscribed(await client(a.events).subscribe()).deliveryStatus).toMatchObject({ active: true, lastError: null }); + }); + it('stops retries on A after an unsubscribe on B', async () => { const store = new InMemoryWebhookSubscriptionStore(); const a = replica({ webhookStore: store, respond: echo(() => ({ status: 500, body: '' })) }); @@ -909,6 +1030,51 @@ describe('fan-out', () => { ]); }); + it('lists again after a store read fails mid-fan-out, delivering to every subscription once', async () => { + const store = new FlakyStore(); + const onerror = vi.fn(); + const { events, post } = replica({ webhookStore: store, onerror }); + const handle = events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const alice = client(events); + const ids: string[] = []; + for (const k of [1, 2, 3]) ids.push(subscribed(await alice.subscribe({ arguments: { k } })).id); + + // The fan-out's first listing fails after handing one subscription to the engine. + store.fail(1, 1); + store.listings = 0; + await handle.emit({ eventId: 'evt_1', data: { n: 1 } }); + await vi.advanceTimersByTimeAsync(100); + await post.until(4); + await settle(); + expect(store.listings).toBe(2); + expect(post.deliveries().map(request => request.headers['X-MCP-Subscription-Id'])).toHaveLength(3); + expect(new Set(post.deliveries().map(request => request.headers['X-MCP-Subscription-Id']))).toEqual(new Set(ids)); + expect(onerror).not.toHaveBeenCalled(); + }); + + it('reports a fan-out whose store listing fails three times, and runs the next emit', async () => { + const store = new FlakyStore(); + const onerror = vi.fn(); + const { events, post } = replica({ webhookStore: store, onerror }); + const handle = events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + subscribed(await client(events).subscribe()); + + store.fail(3, 0); + store.listings = 0; + await handle.emit({ eventId: 'lost', data: { n: 1 } }); + await vi.advanceTimersByTimeAsync(299); + expect(onerror).not.toHaveBeenCalled(); + await vi.advanceTimersByTimeAsync(1); + expect(store.listings).toBe(3); + expect(onerror).toHaveBeenCalledOnce(); + expect(onerror).toHaveBeenCalledWith(expect.objectContaining({ message: 'store unavailable' })); + + await handle.emit({ eventId: 'next', data: { n: 2 } }); + await post.until(2); + await settle(); + expect(post.deliveries().map(request => bodyOf(request).eventId)).toEqual(['next']); + }); + it('drops a transform output that fails payloadSchema and reports it', async () => { const onerror = vi.fn(); const { events, post } = replica({ onerror }); @@ -988,6 +1154,23 @@ describe('check-kind webhook subscriptions', () => { expect(bodyOf(post.requests[2]!)['data']).toEqual({ n: 1, label: '#1' }); }); + it('drops a check event without an eventId and reports it', async () => { + const onerror = vi.fn(); + // As plain JavaScript returns it, past the type that requires eventId. + const unidentified = { data: { n: 1 } } as { eventId: string; data: { n: number } }; + const check = vi.fn(() => ({ events: [unidentified, { eventId: 'kept', data: { n: 2 } }], cursor: 'c1' })); + const { events, post } = replica({ onerror }); + events.registerEvent('t', { payloadSchema: P, check }); + subscribed(await client(events).subscribe({ name: 't', cursor: 'c0' })); + await post.until(2); + await settle(); + expect(post.deliveries().map(request => bodyOf(request).eventId)).toEqual(['kept']); + expect(onerror).toHaveBeenCalledOnce(); + expect(onerror).toHaveBeenCalledWith( + expect.objectContaining({ message: "event 't': dropped an event from check without an eventId" }) + ); + }); + it('replays from a cursor on create, and sends a gap envelope for a gap between refreshes', async () => { const check = vi.fn((_ctx, _args, cursor) => { if (cursor === 'c0') return { events: [{ eventId: 'evt_1', data: { n: 1 } }], cursor: 'c1' }; diff --git a/test/conformance/src/events.ts b/test/conformance/src/events.ts index e987775624..b52630bc9e 100644 --- a/test/conformance/src/events.ts +++ b/test/conformance/src/events.ts @@ -135,7 +135,7 @@ const pulse = conformanceEvents.registerEvent(PULSE, { check: ctx => { const seen = beatSeen.get(ctx.subscriptionId); beatSeen.set(ctx.subscriptionId, beat); - const events = seen === undefined || seen === beat ? [] : [{ data: { beat } }]; + const events = seen === undefined || seen === beat ? [] : [{ eventId: `beat-${beat}`, data: { beat } }]; // A gap yield_gap asked for comes out as `truncated` with `cursor: null`, which the SDK must not pass on (SEP l.713). return take(gapNext, ctx) ? { events, cursor: null, truncated: true } : { events, cursor: null }; }, diff --git a/test/e2e/requirements.ts b/test/e2e/requirements.ts index 472a733b1c..5125c8a143 100644 --- a/test/e2e/requirements.ts +++ b/test/e2e/requirements.ts @@ -3889,7 +3889,7 @@ export const REQUIREMENTS: Record = { ...EVENTS_CELLS, source: 'sdk', behavior: - 'A server rebuilt over the same WebhookSubscriptionStore keeps delivering to a stored subscription, without a resubscribe or a new verification.' + "A server rebuilt over the same WebhookSubscriptionStore keeps delivering an emit-only type to a stored subscription, without a resubscribe or a new verification; a check type resumes at the subscription's next refresh, from the cursor the client supplies." }, 'typescript:events:trusted-origins': { ...EVENTS_CELLS, diff --git a/test/e2e/scenarios/events.test.ts b/test/e2e/scenarios/events.test.ts index 0c04d03f40..80139e7619 100644 --- a/test/e2e/scenarios/events.test.ts +++ b/test/e2e/scenarios/events.test.ts @@ -324,7 +324,7 @@ verifies('events:poll:bootstrap', async ({ transport }: TestArgs) => { // A check that would return events: a null cursor still answers with none. events.registerEvent('ticket', { payloadSchema: NotePayload, - check: () => ({ events: [{ data: { text: 'old' } }], cursor: 't1' }) + check: () => ({ events: [{ eventId: 'old', data: { text: 'old' } }], cursor: 't1' }) }); const client = newClient(); await using _ = await wire(transport, serving(events), client, EVENTS_WIRE); @@ -476,8 +476,8 @@ verifies('events:cursor:max-age', async ({ transport }: TestArgs) => { ? { events: [], cursor: 't0' } : { events: [ - { timestamp: new Date(Date.now() - 600_000).toISOString(), data: { text: 'stale' } }, - { timestamp: new Date().toISOString(), data: { text: 'fresh' } } + { eventId: 'stale', timestamp: new Date(Date.now() - 600_000).toISOString(), data: { text: 'stale' } }, + { eventId: 'fresh', timestamp: new Date().toISOString(), data: { text: 'fresh' } } ], cursor: 't2' } @@ -810,7 +810,9 @@ verifies('events:webhook:verification', async ({ transport }: TestArgs) => { const ticket = { payloadSchema: NotePayload, check: (_ctx: unknown, _args: unknown, cursor: string | null) => - cursor === 'c0' ? { events: [{ data: { text: 'backlog' } }], cursor: 'c1' } : { events: [], cursor: cursor ?? 'c0' } + cursor === 'c0' + ? { events: [{ eventId: 'backlog', data: { text: 'backlog' } }], cursor: 'c1' } + : { events: [], cursor: cursor ?? 'c0' } }; { // An endpoint that answers but does not echo the challenge. @@ -1200,25 +1202,69 @@ verifies('typescript:events:store:replicas', async ({ transport }: TestArgs) => }); verifies('typescript:events:store:restart', async ({ transport }: TestArgs) => { - const posts: Post[] = []; - const { client, clientEvents } = eventsClient({ ...FAST, webhook: { url: HOOK_URL } }); - const options = webhookOptions(senderTo(clientEvents.createWebhookHandler(), posts), { - webhookStore: new InMemoryWebhookSubscriptionStore() - }); - let server = noteEvents(options); - const makeServer = () => serving(server.events)(); - await using wired = await wire(transport, makeServer, client, EVENTS_WIRE); - const subscription = await clientEvents.subscribe({ name: NOTE }); - const requests = wired.httpLog?.length; + { + const posts: Post[] = []; + const { client, clientEvents } = eventsClient({ ...FAST, webhook: { url: HOOK_URL } }); + const options = webhookOptions(senderTo(clientEvents.createWebhookHandler(), posts), { + webhookStore: new InMemoryWebhookSubscriptionStore() + }); + let server = noteEvents(options); + const makeServer = () => serving(server.events)(); + await using wired = await wire(transport, makeServer, client, EVENTS_WIRE); + const subscription = await clientEvents.subscribe({ name: NOTE }); + const requests = wired.httpLog?.length; + + // The process restarts: a new extension over the same store, nothing carried over in memory. + server = noteEvents(options); + await server.note.emit({ data: { text: 'after the restart' } }); + + expect(await take(subscription)).toEqual([{ text: 'after the restart' }]); + expect(wired.httpLog?.length).toBe(requests); + expect(posts.map(post => post.json.type ?? 'event')).toEqual(['verification', 'event']); + await subscription.cancel(); + } + { + // A check type: the rebuilt server runs its check loop from the client's next refresh, which a short grant brings soon. + const posts: Post[] = []; + const { client, clientEvents } = eventsClient({ ...FAST, webhook: { url: HOOK_URL } }); + const options = webhookOptions(senderTo(clientEvents.createWebhookHandler(), posts), { + webhookStore: new InMemoryWebhookSubscriptionStore(), + webhookTtlMs: 1000, + checkIntervalMs: 20 + }); + // The upstream outlives the process; a cursor counts its entries. + const upstream: string[] = []; + let current: EventsExtension | undefined; + const build = (): void => { + const events = new EventsExtension(options); + events.registerEvent('ticket', { + payloadSchema: NotePayload, + check: (_ctx, _args, cursor) => { + // The process that was replaced reads nothing more. + if (events !== current) return new Promise(() => {}); + const from = cursor === null ? upstream.length : Number(cursor); + const page = upstream.slice(from).map((text, index) => ({ eventId: `t${from + index}`, data: { text } })); + return { events: page, cursor: String(upstream.length) }; + } + }); + current = events; + }; + build(); + await using _ = await wire(transport, () => serving(current!)(), client, EVENTS_WIRE); + const tap = tapWire(client); + const subscription = await clientEvents.subscribe({ name: 'ticket' }); - // The process restarts: a new extension over the same store, nothing carried over in memory. - server = noteEvents(options); - await server.note.emit({ data: { text: 'after the restart' } }); + build(); + upstream.push('during the restart'); - expect(await take(subscription)).toEqual([{ text: 'after the restart' }]); - expect(wired.httpLog?.length).toBe(requests); - expect(posts.map(post => post.json.type ?? 'event')).toEqual(['verification', 'event']); - await subscription.cancel(); + expect(await take(subscription)).toEqual([{ text: 'during the restart' }]); + const subscribes = tap.sent.filter(message => 'method' in message && message.method === 'events/subscribe') as Frame[]; + // Delivered once the refresh, carrying the client's cursor, started the loop on the rebuilt server. + expect(subscribes.length).toBeGreaterThanOrEqual(2); + expect(subscribes.slice(0, 2).map(message => message.params['cursor'])).toEqual([null, '0']); + expect(posts.map(post => post.json.type ?? 'event')).toEqual(['verification', 'event']); + await subscription.cancel(); + } }); verifies('typescript:events:trusted-origins', async ({ transport }: TestArgs) => { From 88f5c1b4eaf805abb4a5c938f52a2464a246443a Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Thu, 19 Nov 2026 16:47:08 +0200 Subject: [PATCH 36/37] fix(events): bound held webhook messages and throttle abandon reports - A message holds one of a subscription's ten slots only while a POST attempt is in flight; a retry queues for a slot when it is due, so a failing receiver suspends within about 100 attempts again. - Messages waiting for a slot and parked messages share one cap of 10 000 per subscription; past it the oldest is abandoned. - Events abandoned past the cap or after their fifth failed attempt are reported to onerror at once for the first, then at most once a minute per subscription with how many. - Tests: the IPv6 fall-through resolves A to an unanswered TEST-NET address, the restart e2e runs on fake time with a bounded wait, and an invalid first active falls back to poll. --- docs/clients/events.md | 2 +- docs/servers/events.md | 2 +- packages/client/test/ext/events/push.test.ts | 23 ++ .../server/src/ext/events/webhookEngine.ts | 119 ++++++-- packages/server/test/ext/events/node.test.ts | 8 +- .../test/ext/events/webhookEngine.test.ts | 279 ++++++++++++------ .../ext/events/webhookSubscriptions.test.ts | 44 +-- test/e2e/scenarios/events.test.ts | 96 +++--- 8 files changed, 374 insertions(+), 199 deletions(-) diff --git a/docs/clients/events.md b/docs/clients/events.md index 00127cf36b..7a23518b01 100644 --- a/docs/clients/events.md +++ b/docs/clients/events.md @@ -109,7 +109,7 @@ The server rejects `queue: 42` against the event type's `inputSchema`, so it pri invalidParams ``` -`subscribe()` rejects with an `EventsError` when the server does not list the event type or refuses the subscription (`notFound`, `invalidParams`, `forbidden`, `unsupported`, `resourceExhausted` or `callbackEndpointError`), and with an `SdkError` when the exchange fails in the SDK, such as a closed connection or a push stream with no valid `notifications/events/active` within the request timeout; other failures of the first exchange are retried in the background. A push subscription that can fall back to poll, as above, does so instead on any of these failures but an `EventsError` or a closed connection. The server's webhook verification limit (`resourceExhausted` with `data.limit: 'verification'`) is one of those: the client subscribes again after `data.retryAfterMs` (or its usual backoff without one), before and after the first exchange. Once subscribed, the loop ends with an `EventsError` when the server ends the subscription, such as `forbidden` when access is revoked. A `notFound`, or an `unsupported` for a schema change, makes the client list the event types again and carry on while the type is still offered in that mode. +`subscribe()` rejects with an `EventsError` when the server does not list the event type or refuses the subscription (`notFound`, `invalidParams`, `forbidden`, `unsupported`, `resourceExhausted` or `callbackEndpointError`), and with an `SdkError` when the exchange fails in the SDK, such as a closed connection or a push stream with no valid `notifications/events/active` within the request timeout; other failures of the first exchange are retried in the background. The server's webhook verification limit (`resourceExhausted` with `data.limit: 'verification'`) is one of those: the client subscribes again after `data.retryAfterMs` (or its usual backoff without one), before and after the first exchange. A push subscription that can fall back to poll, as above, does so instead on any of these failures but an `EventsError` or a closed connection. Once subscribed, the loop ends with an `EventsError` when the server ends the subscription, such as `forbidden` when access is revoked. A `notFound`, or an `unsupported` for a schema change, makes the client list the event types again and carry on while the type is still offered in that mode. `NoCompatibleDeliveryModeError` means no delivery mode the event type offers is usable here: webhook needs the `webhook` option, and `delivery` narrows the choice to one mode. Against a server without Events, or on a connection older than 2026-07-28, `events.supported` is `false`, and `list()` and `subscribe()` throw `SdkError` (`CapabilityNotSupported`). An error thrown from `onGap` goes to the client's `onerror`. diff --git a/docs/servers/events.md b/docs/servers/events.md index 9e2817a6c7..0a74020c06 100644 --- a/docs/servers/events.md +++ b/docs/servers/events.md @@ -118,7 +118,7 @@ const webhookEvents = new EventsExtension({ Setting `webhookTtlMs` or `webhookSender` without the other two throws `TypeError`. `getPrincipal` has no default, since `AuthInfo` has no subject field: return the user from wherever your token verifier puts it. A webhook subscription for which `getPrincipal` returns `null` is refused with `forbidden`, on stdio too; poll and push use the principal when there is one. -`webhookTtlMs` is the longest a webhook subscription lives without a refresh, and clients refresh before it lapses. The SDK verifies each endpoint with a challenge before the first delivery, signs every POST (Standard Webhooks), and retries a failed delivery up to five attempts in all. It keeps at most ten event deliveries per subscription in progress, waits between retries included, so a replayed backlog goes out ten at a time. It sends each destination host one challenge at a time, so a subscribe waits while another challenge to that host is in flight, and at most ten in any 60 seconds; past that, or when ten subscribes already wait for the host, it refuses with `resourceExhausted` (`data.limit: 'verification'`; `data.retryAfterMs` says when to try again, and the SDK's client does). It answers a principal's subscribes to a URL whose challenge failed with that failure for 60 seconds, without another challenge. `nodeWebhookSender()` requires `https`, resolves the host at every send by querying DNS directly (so `/etc/hosts` does not apply; origins in `trustedOrigins` skip resolution), refuses IANA special-purpose addresses (loopback, private, link-local and the like) and connects only to the addresses it checked, IPv4 and IPv6; it follows no redirects and gives up after 5 seconds. +`webhookTtlMs` is the longest a webhook subscription lives without a refresh, and clients refresh before it lapses. The SDK verifies each endpoint with a challenge before the first delivery, signs every POST (Standard Webhooks), and retries a failed delivery up to five attempts in all. It sends at most ten event POSTs per subscription at a time, so a replayed backlog goes out ten at a time. Besides those waiting between retries, it holds at most 10 000 more of a subscription's events waiting for their turn or for a suspended delivery to resume, so a replay or `check` batch larger than that loses its oldest waiting events. It abandons an event past that cap or after its fifth failed attempt, and reports these to `onerror` at most once a minute per subscription, with how many. It sends each destination host one challenge at a time, so a subscribe waits while another challenge to that host is in flight, and at most ten in any 60 seconds; past that, or when ten subscribes already wait for the host, it refuses with `resourceExhausted` (`data.limit: 'verification'`; `data.retryAfterMs` says when to try again, and the SDK's client does). It answers a principal's subscribes to a URL whose challenge failed with that failure for 60 seconds, without another challenge. `nodeWebhookSender()` requires `https`, resolves the host at every send by querying DNS directly (so `/etc/hosts` does not apply; origins in `trustedOrigins` skip resolution), refuses IANA special-purpose addresses (loopback, private, link-local and the like) and connects only to the addresses it checked, IPv4 and IPv6; it follows no redirects and gives up after 5 seconds. ::: warning `trustedOrigins` is for development only. Its exact origins, such as `http://127.0.0.1:9000`, are exempt from the `https` rule and the private-address check, so a receiver on your machine can take deliveries; endpoint verification, signing and the no-redirect rule still apply. diff --git a/packages/client/test/ext/events/push.test.ts b/packages/client/test/ext/events/push.test.ts index b9e3899bae..76c868ac18 100644 --- a/packages/client/test/ext/events/push.test.ts +++ b/packages/client/test/ext/events/push.test.ts @@ -622,6 +622,29 @@ describe('push delivery', () => { expect(errors).toEqual([expect.objectContaining({ message: FALLBACK, cause: expect.objectContaining(cause) })]); }); + it('subscribes by poll when the first active fails its schema, and reports both failures', async () => { + const { events, errors, send, streams, polls } = await pushOrPoll(() => new Promise(() => {})); + const subscribing = events.subscribe({ name: 'tick' }); + await settle(); + const meta = { [SUBSCRIPTION_ID_META_KEY]: streams()[0]!.id }; + await send({ + jsonrpc: '2.0', + method: 'notifications/events/active', + params: { cursor: null, truncated: false, heartbeatMs: 0, _meta: meta } + }); + const subscription = await subscribing; + subscriptions.push(subscription); + + expect(subscription.deliveryMode).toBe('poll'); + expect(await nextEventId(subscription[Symbol.asyncIterator]())).toBe('e1'); + expect(streams()).toHaveLength(1); + expect(polls()).toHaveLength(1); + expect(errors).toEqual([ + expect.objectContaining({ message: expect.stringContaining('Invalid notifications/events/active params') }), + expect.objectContaining({ message: FALLBACK, cause: expect.objectContaining({ code: SdkErrorCode.InvalidResult }) }) + ]); + }); + it('rejects as before when delivery forces push', async () => { const { events, errors, streams, polls } = await pushOrPoll(() => new Promise(() => {})); const subscribing = events.subscribe({ name: 'tick', delivery: 'push' }).catch((error_: unknown) => error_); diff --git a/packages/server/src/ext/events/webhookEngine.ts b/packages/server/src/ext/events/webhookEngine.ts index f6d36e0b99..c3318199ff 100644 --- a/packages/server/src/ext/events/webhookEngine.ts +++ b/packages/server/src/ext/events/webhookEngine.ts @@ -15,10 +15,12 @@ const RETRY_DELAYS_MS = [5000, 30_000, 120_000, 300_000]; // Non-2xx answers that end a message without a retry. const FINAL_STATUSES: ReadonlySet = new Set([410, 413]); const MAX_BODY_BYTES = 262_144; -// The most messages a suspended subscription holds: as many as the emit buffer holds by default. -const MAX_PARKED_MESSAGES = 10_000; -// The most event messages of one subscription in progress at once, each from its first attempt until it is settled or parked. +// The most messages of one subscription waiting for a slot or parked, together: as many as the emit buffer holds by default. +const MAX_HELD_MESSAGES = 10_000; +// The most event POSTs of one subscription in flight at once. const MAX_IN_FLIGHT_PER_SUBSCRIPTION = 10; +// Abandoned events are reported at once, then counted and reported together at most this often per subscription. +const ABANDON_REPORT_INTERVAL_MS = 60_000; // Delivery is suspended once more than 95 % of at least 100 attempts in the last 60 minutes failed. const SUSPENSION_WINDOW_MS = 3_600_000; const SUSPENSION_MIN_ATTEMPTS = 100; @@ -44,6 +46,9 @@ export interface WebhookEngineOptions { readonly now?: () => number; } +// Where a message is: waiting for a slot, holding one while an attempt is in flight, waiting for its retry, parked while delivery is suspended, or acknowledged or abandoned. +type Place = 'waiting' | 'running' | 'retrying' | 'parked' | 'done'; + // One event POST to one subscription, under one webhook-id until it is acknowledged or abandoned. interface Message { readonly webhookId: string; @@ -51,9 +56,7 @@ interface Message { // The subscription's position after this event. readonly position: string | null; attempts: number; - done: boolean; - // Holds one of the subscription's MAX_IN_FLIGHT_PER_SUBSCRIPTION slots. - running: boolean; + place: Place; retry?: ReturnType; } @@ -79,7 +82,7 @@ interface Tracked { watermark: string | null; // Messages not yet acknowledged or abandoned, in position order. readonly pending: Message[]; - // How many messages hold a slot, and the messages waiting for one, in position order. + // How many messages hold a slot, and the messages waiting for one: first attempts in position order, each retry once it is due. running: number; waiting: Message[]; // Messages that came due while delivery was suspended, oldest first. @@ -87,6 +90,11 @@ interface Tracked { active: boolean; // The record's expiresAt when delivery was suspended; a later one means a refresh, on any replica, since. suspendedExpiresAt?: number; + // Events abandoned since the last report and the latest of them, when that report went out, and the timer of the next. + abandoned: number; + lastAbandoned?: string; + reportedAt?: number; + report?: ReturnType; lastDeliveryAt: string | null; lastError: DeliveryErrorCategory | null; // The first failure since the last acknowledgement. @@ -246,11 +254,9 @@ export class WebhookEngine { // Queues one event POST and returns; calls for one subscription come in position order, and `seed` starts the watermark of an untracked id. deliver(record: WebhookSubscriptionRecord, occurrence: EventOccurrence, position: string | null, seed: string | null): void { const tracked = this.#tracked.get(record.id) ?? this.#start(record.id, seed); - const message: Message = { webhookId: generateWebhookId(), occurrence, position, attempts: 0, done: false, running: false }; + const message: Message = { webhookId: generateWebhookId(), occurrence, position, attempts: 0, place: 'waiting' }; tracked.pending.push(message); - // A message that waits for a slot reads the record when it starts, as a retry does. - if (tracked.running < MAX_IN_FLIGHT_PER_SUBSCRIPTION) this.#begin(tracked, message, record); - else tracked.waiting.push(message); + this.#queue(tracked, message, record); } // Queues a control body, retried like an event, and resolves with its last answer (`undefined` without one); request paths must not await it. @@ -301,8 +307,10 @@ export class WebhookEngine { tracked.recentFailures = 0; const parked = new Set(tracked.parked); tracked.parked = []; - // Parked messages had started, so they come before every message still waiting. - tracked.waiting = [...tracked.pending.filter(message => parked.has(message)), ...tracked.waiting]; + // Parked messages go first, in position order. + const resumed = tracked.pending.filter(message => parked.has(message)); + for (const message of resumed) message.place = 'waiting'; + tracked.waiting = [...resumed, ...tracked.waiting]; this.#fill(tracked); } @@ -453,6 +461,7 @@ export class WebhookEngine { waiting: [], parked: [], active: true, + abandoned: 0, lastDeliveryAt: null, lastError: null, recent: [], @@ -468,20 +477,32 @@ export class WebhookEngine { this.#tracked.delete(id); tracked.ended.abort(); for (const message of tracked.pending) clearTimeout(message.retry); + clearTimeout(tracked.report); } #isCurrent(tracked: Tracked): boolean { return this.#tracked.get(tracked.id) === tracked; } - // Gives `message` a slot and runs its first attempt. + // Runs the message's next attempt in a free slot, or queues it behind the messages waiting; a message that waits reads the record when it starts. + #queue(tracked: Tracked, message: Message, record?: WebhookSubscriptionRecord): void { + if (tracked.running < MAX_IN_FLIGHT_PER_SUBSCRIPTION) { + this.#begin(tracked, message, record); + return; + } + message.place = 'waiting'; + tracked.waiting.push(message); + this.#cap(tracked); + } + + // Gives `message` a slot for one attempt. #begin(tracked: Tracked, message: Message, record?: WebhookSubscriptionRecord): void { - message.running = true; + message.place = 'running'; tracked.running += 1; this.#attempt(tracked, message, record); } - // Starts waiting messages, oldest first, while a slot is free. + // Starts the messages that waited longest while a slot is free. #fill(tracked: Tracked): void { while (tracked.running < MAX_IN_FLIGHT_PER_SUBSCRIPTION) { const next = tracked.waiting.shift(); @@ -490,14 +511,52 @@ export class WebhookEngine { } } - // Frees the message's slot, if it holds one, for the next message waiting. - #release(tracked: Tracked, message: Message): void { - if (!message.running) return; - message.running = false; + // Moves the message to `place`; one whose attempt ends hands its slot to the message that waited longest. + #release(tracked: Tracked, message: Message, place: 'retrying' | 'parked' | 'done'): void { + const held = message.place === 'running'; + message.place = place; + if (!held) return; tracked.running -= 1; this.#fill(tracked); } + // Past MAX_HELD_MESSAGES waiting or parked, abandons the oldest of them by position. + #cap(tracked: Tracked): void { + if (tracked.waiting.length + tracked.parked.length <= MAX_HELD_MESSAGES) return; + const oldest = tracked.pending.find(message => message.place === 'waiting' || message.place === 'parked')!; + const held = oldest.place === 'waiting' ? tracked.waiting : tracked.parked; + held.splice(held.indexOf(oldest), 1); + this.#abandon(tracked, oldest, `past the ${MAX_HELD_MESSAGES} messages it holds waiting or parked`); + } + + // Settles a message the engine gives up on, and reports it at once unless a report went out in the last ABANDON_REPORT_INTERVAL_MS; then it counts towards the next. + #abandon(tracked: Tracked, message: Message, reason: string): void { + this.#settle(tracked, message); + const { eventId } = message.occurrence; + const now = this.#now(); + if (tracked.report === undefined && (tracked.reportedAt === undefined || now - tracked.reportedAt >= ABANDON_REPORT_INTERVAL_MS)) { + tracked.reportedAt = now; + this.#onerror(new Error(`webhook subscription ${tracked.id}: abandoned event ${eventId} ${reason}`)); + return; + } + tracked.abandoned += 1; + tracked.lastAbandoned = eventId; + tracked.report ??= unref(setTimeout(() => this.#reportAbandoned(tracked), tracked.reportedAt! + ABANDON_REPORT_INTERVAL_MS - now)); + } + + // Reports how many events were abandoned since the last report, and the latest. + #reportAbandoned(tracked: Tracked): void { + const { abandoned, lastAbandoned } = tracked; + tracked.report = undefined; + tracked.reportedAt = this.#now(); + tracked.abandoned = 0; + this.#onerror( + new Error( + `webhook subscription ${tracked.id}: abandoned ${abandoned} more ${abandoned === 1 ? 'event' : 'events'} since the last report, the latest ${lastAbandoned}` + ) + ); + } + // Runs one attempt off the caller's path; an unexpected failure is reported and retried like a failed send. #attempt(tracked: Tracked, message: Message, record?: WebhookSubscriptionRecord): void { this.#try(tracked, message, record).catch((error: unknown) => { @@ -544,33 +603,33 @@ export class WebhookEngine { else this.#settle(tracked, message); } + // Waits out the retry delay out of its slot, then queues the next attempt; after the last it abandons the message. #retry(tracked: Tracked, message: Message): void { const delay = RETRY_DELAYS_MS[message.attempts - 1]; if (delay === undefined) { - this.#settle(tracked, message); + this.#abandon(tracked, message, `after ${message.attempts} failed attempts`); return; } - message.retry = unref(setTimeout(() => this.#attempt(tracked, message), delay)); + this.#release(tracked, message, 'retrying'); + message.retry = unref(setTimeout(() => this.#queue(tracked, message), delay)); } - // Holds a message until resume(), out of its slot; past the cap the oldest one held is abandoned. + // Holds a message until resume(), out of its slot. #park(tracked: Tracked, message: Message): void { + this.#release(tracked, message, 'parked'); tracked.parked.push(message); - this.#release(tracked, message); - const oldest = tracked.parked.length > MAX_PARKED_MESSAGES ? tracked.parked.shift() : undefined; - if (oldest !== undefined) this.#settle(tracked, oldest); + this.#cap(tracked); } - // Marks the message acknowledged or abandoned, moves the watermark past the finished messages at the front, and frees its slot. + // Marks the message acknowledged or abandoned, frees its slot, and moves the watermark past the finished messages at the front. #settle(tracked: Tracked, message: Message): void { - message.done = true; + this.#release(tracked, message, 'done'); let head = tracked.pending[0]; - while (head?.done === true) { + while (head?.place === 'done') { tracked.pending.shift(); tracked.watermark = head.position; head = tracked.pending[0]; } - this.#release(tracked, message); } // Records one outcome in the delivery status and returns whether to retry; 410 and 413 end the message, setting lastError only. diff --git a/packages/server/test/ext/events/node.test.ts b/packages/server/test/ext/events/node.test.ts index 4af96d9201..2805d73fa4 100644 --- a/packages/server/test/ext/events/node.test.ts +++ b/packages/server/test/ext/events/node.test.ts @@ -301,12 +301,12 @@ describe('nodeWebhookSender', () => { await expect(connection.lookup({ family: 6 })).rejects.toMatchObject({ code: 'ENOTFOUND' }); }); - it.skipIf(!hasIpv6Loopback)('connects to the AAAA address when the A address refuses', async () => { + it.skipIf(!hasIpv6Loopback)('connects to the AAAA address when the A address does not answer', async () => { const receiver = await countingServer('::1'); - await treatAsPublic('127.0.0.1', '::1'); - stubResolver(['127.0.0.1', '::1']); + await treatAsPublic('192.0.2.1', '::1'); + stubResolver(['192.0.2.1', '::1']); - // Nothing listens on 127.0.0.1 at the receiver's port; the receiver closes the connection it gets. + // 192.0.2.1 is TEST-NET-1, which nothing answers, so Node moves on to ::1; the receiver closes the connection it gets. expect(await nodeWebhookSender()(sendRequest(`https://dual.example.test:${receiver.port}/x`, false))).toEqual(REFUSED); expect(receiver.connections()).toBe(1); }); diff --git a/packages/server/test/ext/events/webhookEngine.test.ts b/packages/server/test/ext/events/webhookEngine.test.ts index 2d3ea05efb..4348a67b15 100644 --- a/packages/server/test/ext/events/webhookEngine.test.ts +++ b/packages/server/test/ext/events/webhookEngine.test.ts @@ -115,46 +115,25 @@ function bodyOf(request: WebhookSendRequest): Record { return JSON.parse(request.body) as Record; } -// Delivers events `from` to `to` (at positions p{from} to p{to}) to a receiver that fails them, and moves the clock through all five -// attempts of each, ten at a time, until the last is abandoned; `sent` counts the requests before, and the count after is returned. -async function failThrough( - engine: WebhookEngine, - record: WebhookSubscriptionRecord, - until: (count: number) => Promise, - sent: number, - from: number, - to: number -): Promise { - for (let n = from; n <= to; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); - for (let left = to - from + 1; left > 0; left -= 10) { - const batch = Math.min(10, left); - sent += batch; - await until(sent); - for (const delay of DELAYS) { - await settle(); - await vi.advanceTimersByTimeAsync(delay); - sent += batch; - await until(sent); - } - await settle(); - } - return sent; -} - -// A responder that holds each event POST until the test answers it, counting how many are in flight at most. -function held() { +// A responder that holds each event POST until the test answers it, counting the POSTs in flight at most; `fail` answers a POST with 503 at once. +function held(fail: (request: WebhookSendRequest) => boolean = () => false) { const answers: Array<() => void> = []; let inFlight = 0; let most = 0; - const respond: Respond = () => - new Promise(resolve => { - inFlight += 1; - most = Math.max(most, inFlight); + const respond: Respond = request => { + inFlight += 1; + most = Math.max(most, inFlight); + if (fail(request)) { + inFlight -= 1; + return { status: 503, body: '' }; + } + return new Promise(resolve => answers.push(() => { inFlight -= 1; resolve({ status: 200, body: '' }); - }); - }); + }) + ); + }; return { respond, answers, most: () => most }; } @@ -402,8 +381,8 @@ describe('event delivery', () => { } }); - it('retries on the documented schedule then abandons', async () => { - const { engine, record, requests, until } = setup(() => ({ status: 503, body: '' })); + it('retries on the documented schedule then abandons, reporting the event once', async () => { + const { engine, record, requests, until, onerror } = setup(() => ({ status: 503, body: '' })); const start = Date.now(); engine.track(ID, 'p0'); engine.deliver(record, occurrence('evt_1'), 'p1', null); @@ -422,6 +401,62 @@ describe('event delivery', () => { expect(vi.getTimerCount()).toBe(0); await vi.advanceTimersByTimeAsync(3_600_000); expect(requests).toHaveLength(5); + expect(onerror).toHaveBeenCalledExactlyOnceWith( + expect.objectContaining({ message: `webhook subscription ${ID}: abandoned event evt_1 after 5 failed attempts` }) + ); + }); + + it('reports the events abandoned within a minute of a report together, with how many and the latest', async () => { + const { engine, record, requests, until, onerror } = setup(() => ({ status: 503, body: '' })); + const reports = () => onerror.mock.calls.map(([error]) => (error as Error).message); + engine.track(ID, 'p0'); + // Three events a second apart, so each attempt of evt_2 and evt_3 comes one and two seconds after evt_1's. + for (let n = 1; n <= 3; n++) { + if (n > 1) await vi.advanceTimersByTimeAsync(1000); + engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await until(n); + await settle(); + } + let sent = 3; + for (const delay of DELAYS) { + await vi.advanceTimersByTimeAsync(delay - 2000); + for (let n = 1; n <= 3; n++) { + if (n > 1) await vi.advanceTimersByTimeAsync(1000); + await until(++sent); + await settle(); + } + } + expect(requests).toHaveLength(15); + // evt_1 gave up at 455 s and is reported at once; evt_2 and evt_3, a second and two later, wait for the minute to pass. + expect(reports()).toEqual([`webhook subscription ${ID}: abandoned event evt_1 after 5 failed attempts`]); + await vi.advanceTimersByTimeAsync(57_999); + expect(reports()).toHaveLength(1); + await vi.advanceTimersByTimeAsync(1); + expect(reports()).toEqual([ + `webhook subscription ${ID}: abandoned event evt_1 after 5 failed attempts`, + `webhook subscription ${ID}: abandoned 2 more events since the last report, the latest evt_3` + ]); + expect(engine.watermark(ID)).toBe('p3'); + expect(vi.getTimerCount()).toBe(0); + }); + + it('drops the count of a forgotten subscription without reporting it', async () => { + const { engine, record, until, onerror } = setup(() => ({ status: 503, body: '' })); + engine.track(ID, 'p0'); + engine.deliver(record, occurrence('evt_1'), 'p1', null); + engine.deliver(record, occurrence('evt_2'), 'p2', null); + await until(2); + for (const [index, delay] of DELAYS.entries()) { + await settle(); + await vi.advanceTimersByTimeAsync(delay); + await until(2 * (index + 2)); + } + await settle(); + expect(onerror).toHaveBeenCalledOnce(); + engine.forget(ID); + await vi.advanceTimersByTimeAsync(60_000); + expect(onerror).toHaveBeenCalledOnce(); + expect(vi.getTimerCount()).toBe(0); }); it.each([410, 413])('treats %i as final for the message', async status => { @@ -546,40 +581,69 @@ describe('event delivery', () => { expect(engine.watermark(ID)).toBeNull(); }); - it('has at most 10 messages of a subscription in flight, a retry wait included, and starts the rest in position order', async () => { - let failing = true; - const hold = held(); - const { engine, record, requests, until } = setup(request => - failing && bodyOf(request).eventId === 'evt_1' ? { status: 503, body: '' } : hold.respond(request) - ); + it('has at most 10 POSTs of a subscription in flight, retries included, and starts first attempts in position order', async () => { + let fails = 1; + const hold = held(request => bodyOf(request).eventId === 'evt_1' && fails-- > 0); + const { engine, record, requests, until } = setup(hold.respond); engine.track(ID, 'p0'); - for (let n = 1; n <= 25; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); - await until(10); + for (let n = 1; n <= 15; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + // evt_1 fails at once and waits for its retry out of its slot, which evt_11 takes. + await until(11); await settle(); - expect(requests).toHaveLength(10); - // evt_1 keeps its slot while it waits for its retry; each other answer frees a slot for the next message. - for (let n = 0; n < 9; n++) { + const eventIds = () => requests.map(request => bodyOf(request).eventId); + expect(eventIds().sort()).toEqual(Array.from({ length: 11 }, (_, n) => `evt_${n + 1}`).sort()); + // The retry is due while ten POSTs are in flight: it waits its turn behind evt_12 … evt_15. + await vi.advanceTimersByTimeAsync(5000); + expect(requests).toHaveLength(11); + for (let n = 0; n < 5; n++) { hold.answers[n]!(); - await until(11 + n); + await until(12 + n); } await settle(); - expect(requests).toHaveLength(19); - expect(requests.slice(10).map(request => bodyOf(request).eventId)).toEqual(Array.from({ length: 9 }, (_, n) => `evt_${11 + n}`)); + expect(eventIds().slice(11)).toEqual(['evt_12', 'evt_13', 'evt_14', 'evt_15', 'evt_1']); expect(engine.watermark(ID)).toBe('p0'); - failing = false; - await vi.advanceTimersByTimeAsync(5000); - await until(20); - // Each answer frees a slot for the next message, which starts before the next answer. - for (let n = 9; n < 25; n++) { + for (let n = 5; n < 15; n++) hold.answers[n]!(); + await settle(); + expect(hold.most()).toBe(10); + expect(engine.watermark(ID)).toBe('p15'); + }); + + it('holds at most 10 000 messages waiting for a slow receiver, abandoning the oldest and reporting them at most once a minute', async () => { + const hold = held(); + const { engine, record, requests, until, onerror } = setup(hold.respond); + const reports = () => onerror.mock.calls.map(([error]) => (error as Error).message); + engine.track(ID, 'p0'); + // Ten in flight, 10 000 waiting, and five more: the five oldest waiting are abandoned, and the first is reported at once. + for (let n = 1; n <= 10_015; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + expect(reports()).toEqual([ + `webhook subscription ${ID}: abandoned event evt_11 past the 10000 messages it holds waiting or parked` + ]); + // A minute after that report the other four are reported together. + await vi.advanceTimersByTimeAsync(59_999); + expect(reports()).toHaveLength(1); + await vi.advanceTimersByTimeAsync(1); + expect(reports()[1]).toBe(`webhook subscription ${ID}: abandoned 4 more events since the last report, the latest evt_15`); + // One more abandoned within a minute of that report waits for the next. + engine.deliver(record, occurrence('evt_10016'), 'p10016', null); + expect(reports()).toHaveLength(2); + await vi.advanceTimersByTimeAsync(60_000); + expect(reports()).toEqual([ + `webhook subscription ${ID}: abandoned event evt_11 past the 10000 messages it holds waiting or parked`, + `webhook subscription ${ID}: abandoned 4 more events since the last report, the latest evt_15`, + `webhook subscription ${ID}: abandoned 1 more event since the last report, the latest evt_16` + ]); + + await until(10); + for (let n = 0; n < 10; n++) { hold.answers[n]!(); - await until(Math.min(n + 12, 26)); + await until(11 + n); } await settle(); - expect(requests).toHaveLength(26); - expect(requests.slice(20).map(request => bodyOf(request).eventId)).toEqual(Array.from({ length: 6 }, (_, n) => `evt_${20 + n}`)); + // The oldest message kept starts next, and the abandoned ones no longer hold the watermark back. + expect(requests.slice(10).map(request => bodyOf(request).eventId)).toEqual(Array.from({ length: 10 }, (_, n) => `evt_${17 + n}`)); + expect(engine.watermark(ID)).toBe('p16'); expect(hold.most()).toBe(10); - expect(engine.watermark(ID)).toBe('p25'); }); it('queues each delivery and returns without waiting for the receiver', async () => { @@ -700,43 +764,56 @@ describe('delivery status', () => { }); }); + it('suspends a failing receiver on its first attempts, ten POSTs at a time, before any retry is due', async () => { + const hold = held(() => true); + const { engine, record, requests, until } = setup(hold.respond); + const start = Date.now(); + engine.track(ID, 'p0'); + for (let n = 1; n <= 150; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await until(100); + await settle(); + expect(engine.status(ID)).toMatchObject({ active: false }); + // Each a first attempt, at most nine of them past the 100th that suspended, with no clock time passed; the rest parked. + await settle(); + expect(requests.length).toBeLessThanOrEqual(109); + expect(new Set(requests.map(request => bodyOf(request).eventId)).size).toBe(requests.length); + expect(Date.now()).toBe(start); + }); + it('suspends when more than 95 % of at least 100 attempts in the last hour failed, and resume() retries what waited', async () => { let healthy = false; const { engine, record, requests, until } = setup(request => healthy || Number((bodyOf(request).eventId as string).slice(4)) <= 5 ? { status: 200, body: '' } : { status: 503, body: '' } ); - const start = Date.now(); engine.track(ID, 'p0'); - for (let n = 1; n <= 5; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); - await until(5); + for (let n = 1; n <= 100; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await until(100); await settle(); - // 19 events abandoned after five failed attempts each: 95 of 100 attempts failed, not more than 95 %. - expect(await failThrough(engine, record, until, 5, 6, 24)).toBe(100); + // 95 of 100 attempts failed: not more than 95 %. expect(engine.status(ID)).toMatchObject({ active: true }); - expect(engine.watermark(ID)).toBe('p24'); - engine.deliver(record, occurrence('evt_25'), 'p25', null); + const failedAt = Date.now(); + engine.deliver(record, occurrence('evt_101'), 'p101', null); await until(101); await settle(); expect(engine.status(ID)).toEqual({ active: false, - lastDeliveryAt: new Date(start).toISOString(), + lastDeliveryAt: new Date(failedAt).toISOString(), lastError: 'http_5xx', - failedSince: new Date(start).toISOString() + failedSince: new Date(failedAt).toISOString() }); - // evt_25's retry and evt_26 wait for the resume. - engine.deliver(record, occurrence('evt_26'), 'p26', null); + engine.deliver(record, occurrence('evt_102'), 'p102', null); await vi.advanceTimersByTimeAsync(600_000); expect(requests).toHaveLength(101); - expect(engine.watermark(ID)).toBe('p24'); + expect(engine.watermark(ID)).toBe('p5'); healthy = true; engine.resume(ID); - await until(103); + await until(101 + 97); await settle(); expect(engine.status(ID)).toEqual({ active: true, lastDeliveryAt: new Date().toISOString(), lastError: null }); - expect(engine.watermark(ID)).toBe('p26'); + expect(engine.watermark(ID)).toBe('p102'); }); it('counts only the attempts of the last 60 minutes', async () => { @@ -745,34 +822,48 @@ describe('delivery status', () => { const record = recordFor({ expiresAt: Date.now() + 86_400_000 }); await store.put(record); engine.track(ID, 'p0'); - for (let n = 1; n <= 10; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); - await until(10); + for (let n = 1; n <= 99; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await until(99); await settle(); failing = false; await vi.advanceTimersByTimeAsync(5000); - await until(20); + await until(198); await settle(); - expect(engine.watermark(ID)).toBe('p10'); + expect(engine.watermark(ID)).toBe('p99'); - // Counted with the hour before, these would be 110 failures in 120 attempts, not more than 95 %; alone they are 100 in 100. + // Counted with the hour before, these would be 199 failures in 298 attempts; alone they are 100 in 100. await vi.advanceTimersByTimeAsync(3_600_000); failing = true; - await failThrough(engine, record, until, 20, 11, 30); + for (let n = 100; n <= 199; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await until(298); + await settle(); expect(engine.status(ID)).toMatchObject({ active: false }); }); - it('holds at most 10 000 messages while suspended, abandoning the oldest', async () => { + it('holds at most 10 000 messages while suspended, abandoning the oldest and reporting it', async () => { let healthy = false; - const { engine, record, requests, until } = setup(() => (healthy ? { status: 200, body: '' } : { status: 503, body: '' })); + const { engine, record, requests, until, onerror } = setup(() => (healthy ? { status: 200, body: '' } : { status: 503, body: '' })); engine.track(ID, 'p0'); // 20 events, five failed attempts each: the 100th attempt suspends delivery as the last retries give up. - await failThrough(engine, record, until, 0, 1, 20); + for (let n = 1; n <= 20; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await until(20); + for (const [index, delay] of DELAYS.entries()) { + await settle(); + await vi.advanceTimersByTimeAsync(delay); + await until(20 * (index + 2)); + } + await settle(); expect(engine.status(ID)).toMatchObject({ active: false }); expect(engine.watermark(ID)).toBe('p20'); for (let n = 21; n <= 10_021; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); expect(engine.watermark(ID)).toBe('p21'); expect(requests).toHaveLength(100); + // The first of the 20 abandoned after five attempts was reported at once; the rest, and evt_21 past the cap, wait for the minute. + const reports = () => onerror.mock.calls.map(([error]) => (error as Error).message); + expect(reports()).toEqual([ + expect.stringMatching(new RegExp(`^webhook subscription ${ID}: abandoned event evt_\\d+ after 5 failed attempts$`)) + ]); healthy = true; engine.resume(ID); @@ -781,15 +872,15 @@ describe('delivery status', () => { expect(requests).toHaveLength(100 + 10_000); expect(requests.some(request => bodyOf(request).eventId === 'evt_21')).toBe(false); expect(engine.watermark(ID)).toBe('p10021'); + await vi.advanceTimersByTimeAsync(60_000); + expect(reports()[1]).toBe(`webhook subscription ${ID}: abandoned 20 more events since the last report, the latest evt_21`); }); it.each(['a due retry', 'a new delivery'])('releases a suspended subscription whose record expired, on %s', async path => { const { engine, store, record, requests, until } = setup(() => ({ status: 503, body: '' })); engine.track(ID, 'p0'); - // 95 failed attempts, then five first attempts that fail: the 100th suspends delivery while their retries are due. - const sent = await failThrough(engine, record, until, 0, 1, 19); - for (let n = 20; n <= 24; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); - await until(sent + 5); + for (let n = 1; n <= 100; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await until(100); await settle(); expect(engine.status(ID)).toMatchObject({ active: false }); @@ -809,12 +900,15 @@ describe('delivery status', () => { it('resumes many parked messages at most 10 in flight, in position order', async () => { let healthy = false; - const hold = held(); - const { engine, record, requests, until } = setup(request => (healthy ? hold.respond(request) : { status: 503, body: '' })); + const hold = held(() => !healthy); + const { engine, record, requests, until } = setup(hold.respond); engine.track(ID, 'p0'); - await failThrough(engine, record, until, 0, 1, 20); + for (let n = 1; n <= 100; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await until(100); + await settle(); expect(engine.status(ID)).toMatchObject({ active: false }); - for (let n = 21; n <= 50; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + for (let n = 101; n <= 130; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await settle(); expect(requests).toHaveLength(100); healthy = true; @@ -829,10 +923,9 @@ describe('delivery status', () => { } await settle(); const resumed = requests.slice(100).map(request => bodyOf(request).eventId); - expect(resumed.slice(0, 10).sort()).toEqual(Array.from({ length: 10 }, (_, n) => `evt_${21 + n}`).sort()); - expect(resumed.slice(10)).toEqual(Array.from({ length: 20 }, (_, n) => `evt_${31 + n}`)); + expect(resumed.slice(0, 10).sort()).toEqual(Array.from({ length: 10 }, (_, n) => `evt_${101 + n}`).sort()); + expect(resumed.slice(10)).toEqual(Array.from({ length: 20 }, (_, n) => `evt_${111 + n}`)); expect(hold.most()).toBe(10); - expect(engine.watermark(ID)).toBe('p50'); }); it('resume() does nothing for an active or unknown subscription', async () => { diff --git a/packages/server/test/ext/events/webhookSubscriptions.test.ts b/packages/server/test/ext/events/webhookSubscriptions.test.ts index 5386f2828c..7ff76d5ab2 100644 --- a/packages/server/test/ext/events/webhookSubscriptions.test.ts +++ b/packages/server/test/ext/events/webhookSubscriptions.test.ts @@ -6,7 +6,6 @@ import * as z from 'zod/v4'; import type { CheckContext, - EmitOnlyEventHandle, EventContext, EventResult, EventsOptions, @@ -26,7 +25,6 @@ const HOOK = 'https://hooks.example.com/mcp'; const OTHER_HOOK = 'https://other.example.com/hook'; const SECRET = generateWebhookSecret(); const SUB_ID = /^sub_[\w-]{22}$/; -const DELAYS = [5000, 30_000, 120_000, 300_000]; const UNSUPPORTED = { code: -32_026, data: { feature: 'deliveryMode', value: 'webhook' } }; type Respond = (request: WebhookSendRequest) => WebhookSendOutcome | Promise; @@ -134,30 +132,6 @@ function verifies(request: WebhookSendRequest, secret: string): Promise // Lets queued work act on answers already received, without moving the clock. const settle = (): Promise => vi.advanceTimersByTimeAsync(0); -// Emits `count` events that the receiver fails, and moves the clock through all five attempts of each, ten at a time, until the -// last is abandoned; `sent` counts the requests before, and the count after is returned. -async function emitFailing( - handle: EmitOnlyEventHandle<{ n: number }>, - until: (count: number) => Promise, - sent: number, - count: number -): Promise { - for (let n = 1; n <= count; n++) await handle.emit({ data: { n } }); - for (let left = count; left > 0; left -= 10) { - const batch = Math.min(10, left); - sent += batch; - await until(sent); - for (const delay of DELAYS) { - await settle(); - await vi.advanceTimersByTimeAsync(delay); - sent += batch; - await until(sent); - } - await settle(); - } - return sent; -} - const REVOKED = { code: -32_024, message: 'Forbidden', data: { reason: 'Access revoked' } }; function revoked(): EventsError { @@ -806,8 +780,9 @@ describe('events/subscribe: refreshing', () => { const handle = events.registerEvent('e', { emitOnly: true, payloadSchema: P }); const alice = client(events); subscribed(await alice.subscribe()); - // 20 events, five failed attempts each: the 100th suspends delivery. - await emitFailing(handle, post.until, 1, 20); + for (let n = 1; n <= 100; n++) await handle.emit({ data: { n } }); + await post.until(101); + await settle(); expect(subscribed(await alice.subscribe()).deliveryStatus).toMatchObject({ active: false, lastError: 'http_5xx' }); expect(subscribed(await alice.subscribe()).deliveryStatus).toMatchObject({ active: true, lastError: 'http_5xx' }); }); @@ -904,17 +879,22 @@ describe('several replicas sharing one store', () => { const handle = a.events.registerEvent('e', { emitOnly: true, payloadSchema: P }); b.events.registerEvent('e', { emitOnly: true, payloadSchema: P }); const { id } = subscribed(await client(a.events).subscribe()); - // 20 events, five failed attempts each: the 100th suspends delivery on A. - const sent = await emitFailing(handle, a.post.until, 1, 20); - await handle.emit({ eventId: 'parked', data: { n: 21 } }); + // 100 failed attempts suspend delivery on A. + for (let n = 1; n <= 100; n++) await handle.emit({ data: { n } }); + const sent = 101; + await a.post.until(sent); + await settle(); + await handle.emit({ eventId: 'parked', data: { n: 101 } }); await settle(); expect(a.post.requests).toHaveLength(sent); + // A second later, before any retry is due, B serves the refresh. healthy = true; + await vi.advanceTimersByTimeAsync(1000); const before = (await store.get(id))!.expiresAt; subscribed(await client(b.events).subscribe()); expect((await store.get(id))!.expiresAt).toBeGreaterThan(before); - await handle.emit({ eventId: 'after', data: { n: 22 } }); + await handle.emit({ eventId: 'after', data: { n: 102 } }); await a.post.until(sent + 2); await settle(); expect( diff --git a/test/e2e/scenarios/events.test.ts b/test/e2e/scenarios/events.test.ts index 80139e7619..260c285a22 100644 --- a/test/e2e/scenarios/events.test.ts +++ b/test/e2e/scenarios/events.test.ts @@ -1224,46 +1224,66 @@ verifies('typescript:events:store:restart', async ({ transport }: TestArgs) => { await subscription.cancel(); } { - // A check type: the rebuilt server runs its check loop from the client's next refresh, which a short grant brings soon. - const posts: Post[] = []; - const { client, clientEvents } = eventsClient({ ...FAST, webhook: { url: HOOK_URL } }); - const options = webhookOptions(senderTo(clientEvents.createWebhookHandler(), posts), { - webhookStore: new InMemoryWebhookSubscriptionStore(), - webhookTtlMs: 1000, - checkIntervalMs: 20 - }); - // The upstream outlives the process; a cursor counts its entries. - const upstream: string[] = []; - let current: EventsExtension | undefined; - const build = (): void => { - const events = new EventsExtension(options); - events.registerEvent('ticket', { - payloadSchema: NotePayload, - check: (_ctx, _args, cursor) => { - // The process that was replaced reads nothing more. - if (events !== current) return new Promise(() => {}); - const from = cursor === null ? upstream.length : Number(cursor); - const page = upstream.slice(from).map((text, index) => ({ eventId: `t${from + index}`, data: { text } })); - return { events: page, cursor: String(upstream.length) }; - } + // A check type: the rebuilt server runs its check loop from the client's next refresh. Fake timers bring that refresh + // at ¾ of the 60 s grant, while the grant runs in real time, so a slow run cannot turn the refresh into a create. + const realSetTimeout = globalThis.setTimeout; + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + try { + const posts: Post[] = []; + const { client, clientEvents } = eventsClient({ ...FAST, webhook: { url: HOOK_URL } }); + const options = webhookOptions(senderTo(clientEvents.createWebhookHandler(), posts), { + webhookStore: new InMemoryWebhookSubscriptionStore(), + checkIntervalMs: 1000 }); - current = events; - }; - build(); - await using _ = await wire(transport, () => serving(current!)(), client, EVENTS_WIRE); - const tap = tapWire(client); - const subscription = await clientEvents.subscribe({ name: 'ticket' }); - - build(); - upstream.push('during the restart'); + // The upstream outlives the process; a cursor counts its entries. + const upstream: string[] = []; + let current: EventsExtension | undefined; + const build = (): void => { + const events = new EventsExtension(options); + events.registerEvent('ticket', { + payloadSchema: NotePayload, + check: (_ctx, _args, cursor) => { + // The process that was replaced reads nothing more. + if (events !== current) return new Promise(() => {}); + const from = cursor === null ? upstream.length : Number(cursor); + const page = upstream.slice(from).map((text, index) => ({ eventId: `t${from + index}`, data: { text } })); + return { events: page, cursor: String(upstream.length) }; + } + }); + current = events; + }; + build(); + await using _ = await wire(transport, () => serving(current!)(), client, EVENTS_WIRE); + const tap = tapWire(client); + const subscribes = () => tap.sent.filter(message => 'method' in message && message.method === 'events/subscribe') as Frame[]; + const subscription = await clientEvents.subscribe({ name: 'ticket' }); + + build(); + upstream.push('during the restart'); + let taken: Note[] | undefined; + let failed: unknown; + void take(subscription).then( + data => (taken = data), + (error: unknown) => (failed = error) + ); + // Until the refresh, the rebuilt server runs no check loop for the stored subscription. + await vi.advanceTimersByTimeAsync(44_000); + expect({ taken, subscribes: subscribes().length }).toEqual({ taken: undefined, subscribes: 1 }); + // Then on in 100 ms steps, each with a moment of real time for the requests in between, up to 50 s of fake time. + for (let at = 44_000; taken === undefined && failed === undefined && at < 50_000; at += 100) { + await vi.advanceTimersByTimeAsync(100); + await new Promise(resolve => realSetTimeout(resolve, 5)); + } - expect(await take(subscription)).toEqual([{ text: 'during the restart' }]); - const subscribes = tap.sent.filter(message => 'method' in message && message.method === 'events/subscribe') as Frame[]; - // Delivered once the refresh, carrying the client's cursor, started the loop on the rebuilt server. - expect(subscribes.length).toBeGreaterThanOrEqual(2); - expect(subscribes.slice(0, 2).map(message => message.params['cursor'])).toEqual([null, '0']); - expect(posts.map(post => post.json.type ?? 'event')).toEqual(['verification', 'event']); - await subscription.cancel(); + expect(failed).toBeUndefined(); + expect(taken).toEqual([{ text: 'during the restart' }]); + // The refresh carried the client's cursor, and the loop it started delivered from there. + expect(subscribes().map(message => message.params['cursor'])).toEqual([null, '0']); + expect(posts.map(post => post.json.type ?? 'event')).toEqual(['verification', 'event']); + await subscription.cancel(); + } finally { + vi.useRealTimers(); + } } }); From 5ebb589b970bfc8f98e344e13299f8eb76ff8cd1 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Thu, 19 Nov 2026 19:15:58 +0200 Subject: [PATCH 37/37] =?UTF-8?q?fix(events):=20third=20review=20round=20?= =?UTF-8?q?=E2=80=94=20auth=20and=20retry=20endings,=20gaps,=20backlog=20a?= =?UTF-8?q?nd=20replica=20state?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Client: - An auth-seam error (UnauthorizedError from an authProvider, or a throwing token()) refuses the first exchange and ends a live subscription, instead of being retried with a fresh authorization redirect each time. - Retried failures are reported to onerror, the first at once and then at most once a minute with how many; -32601 and -32602 end the subscription. - A first exchange refused with unsupported deliveryMode re-lists once and selects again; an HTTP 5xx or 429 on the first exchange is retried like any transient failure. Server: - In every check batch, truncated or not, events before the last carry the cursor the batch was read from, and so does a truncated batch's own cursor, so no saved cursor passes an unsent event. - The pinned lookup honours ADDRCONFIG: only families the host has a non-loopback, non-link-local interface address of, unless that leaves none. - Events abandoned past the held cap, after the last retry, over the body size or answered 413 are signalled to the subscriber as a gap: a gap envelope at the watermark after the next acknowledged delivery, or truncated: true on the next refresh. - A replica that only delivers for a subscription re-reads its record at expiresAt and drops the state once the record is gone, expired or re-created; a re-created record restarts the state instead. - A push stream whose unread backlog passes 1 MiB is ended; the per-request transport exposes its queued byte count internally. The restart e2e block uses fake setTimeout with a real clock so the client's refresh lands at three quarters of the 60 s grant before the grant can lapse, and a slow run cannot turn the refresh into a create. --- docs/clients/events.md | 2 +- docs/servers/events.md | 4 +- packages/client/src/ext/events/extension.ts | 92 +++++++--- packages/client/src/ext/events/push.ts | 8 +- packages/client/src/ext/events/recovery.ts | 87 +++++++++- .../client/src/ext/events/subscription.ts | 16 +- .../client/test/ext/events/extension.test.ts | 36 ++++ packages/client/test/ext/events/poll.test.ts | 111 +++++++++++- packages/client/test/ext/events/push.test.ts | 39 ++++- .../client/test/ext/events/recovery.test.ts | 11 +- packages/client/test/ext/events/scripted.ts | 21 +++ .../client/test/ext/events/webhook.test.ts | 34 +++- packages/server/src/ext/events/extension.ts | 3 +- packages/server/src/ext/events/node.ts | 37 +++- packages/server/src/ext/events/push.ts | 22 ++- .../server/src/ext/events/webhookEngine.ts | 84 ++++++++- .../src/ext/events/webhookSubscriptions.ts | 10 +- .../server/src/server/perRequestTransport.ts | 35 ++-- packages/server/test/ext/events/node.test.ts | 61 +++++++ packages/server/test/ext/events/push.test.ts | 69 +++++++- .../test/ext/events/webhookEngine.test.ts | 124 ++++++++++++- .../ext/events/webhookSubscriptions.test.ts | 164 ++++++++++++++++++ test/e2e/scenarios/events.test.ts | 3 +- 23 files changed, 980 insertions(+), 93 deletions(-) diff --git a/docs/clients/events.md b/docs/clients/events.md index 7a23518b01..0d261122bf 100644 --- a/docs/clients/events.md +++ b/docs/clients/events.md @@ -109,7 +109,7 @@ The server rejects `queue: 42` against the event type's `inputSchema`, so it pri invalidParams ``` -`subscribe()` rejects with an `EventsError` when the server does not list the event type or refuses the subscription (`notFound`, `invalidParams`, `forbidden`, `unsupported`, `resourceExhausted` or `callbackEndpointError`), and with an `SdkError` when the exchange fails in the SDK, such as a closed connection or a push stream with no valid `notifications/events/active` within the request timeout; other failures of the first exchange are retried in the background. The server's webhook verification limit (`resourceExhausted` with `data.limit: 'verification'`) is one of those: the client subscribes again after `data.retryAfterMs` (or its usual backoff without one), before and after the first exchange. A push subscription that can fall back to poll, as above, does so instead on any of these failures but an `EventsError` or a closed connection. Once subscribed, the loop ends with an `EventsError` when the server ends the subscription, such as `forbidden` when access is revoked. A `notFound`, or an `unsupported` for a schema change, makes the client list the event types again and carry on while the type is still offered in that mode. +`subscribe()` rejects with an `EventsError` when the server does not list the event type or refuses the subscription (`notFound`, `invalidParams`, `forbidden`, `unsupported`, `resourceExhausted` or `callbackEndpointError`), with an `SdkError` when the exchange fails in the SDK, such as a closed connection, an HTTP error status other than `5xx` and `429`, or a push stream with no valid `notifications/events/active` within the request timeout, and with the transport's auth failure (such as `UnauthorizedError` for a `401` the `authProvider` cannot resolve) or a `ProtocolError` `-32601` from a server that does not serve the method; other failures of the first exchange, such as a transport error, an HTTP `5xx` or `429`, or another JSON-RPC error, are retried in the background. The server's webhook verification limit (`resourceExhausted` with `data.limit: 'verification'`) is one of those: the client subscribes again after `data.retryAfterMs` (or its usual backoff without one), before and after the first exchange. A push subscription that can fall back to poll, as above, does so instead on any of these failures but an `EventsError`, an auth failure, a `-32601` or a closed connection. Each retried failure, such as a transport error, an HTTP error status, another JSON-RPC error or the verification limit, before the first exchange succeeds or after, goes to the client's `onerror`: the first at once, then at most one report a minute with how many were retried since. A push stream that ends or goes silent is reopened without a report, and so is a request retried after the event types are listed again. When the server refuses the delivery mode the client selected (`unsupported` for `deliveryMode`, say after a deploy that dropped it), the client lists the event types again once and subscribes in the mode that listing selects; a mode you force with `delivery` is not changed. Once subscribed, the loop ends with an `EventsError` when the server ends the subscription, such as `forbidden` when access is revoked, and with an auth failure or a `-32601` as `subscribe()` would reject. A `notFound`, or an `unsupported` for a schema change, makes the client list the event types again and carry on while the type is still offered in that mode. `NoCompatibleDeliveryModeError` means no delivery mode the event type offers is usable here: webhook needs the `webhook` option, and `delivery` narrows the choice to one mode. Against a server without Events, or on a connection older than 2026-07-28, `events.supported` is `false`, and `list()` and `subscribe()` throw `SdkError` (`CapabilityNotSupported`). An error thrown from `onGap` goes to the client's `onerror`. diff --git a/docs/servers/events.md b/docs/servers/events.md index 0a74020c06..e821842446 100644 --- a/docs/servers/events.md +++ b/docs/servers/events.md @@ -93,6 +93,8 @@ A push stream carries no SSE comment keepalive. The server sends `notifications/ Both hold under `createMcpHandler`. A custom HTTP entry built directly on `PerRequestHTTPServerTransport` must stream `events/stream` itself: serve it with `responseMode` `'auto'` or `'sse'`, never `'json'`, and the transport's `keepAliveMs` applies to it as to any stream. +Over HTTP, a push stream whose client leaves more than 1 MiB unread ends before its next write, and the SDK's client reconnects from its cursor. + One `EventsExtension` serves at most `maxSubscriptions` subscriptions at once, 1024 by default, counting its poll leases, push streams and the webhook subscriptions this process handles; it refuses more with `resourceExhausted` (`data.limit: 'subscriptions'`). With `getPrincipal` set, each principal may hold a quarter of them, and so may all callers without a principal together, refused past that with `data.limit: 'principalSubscriptions'`; without `getPrincipal` only the process-wide limit applies. ## Deliver events to webhooks @@ -118,7 +120,7 @@ const webhookEvents = new EventsExtension({ Setting `webhookTtlMs` or `webhookSender` without the other two throws `TypeError`. `getPrincipal` has no default, since `AuthInfo` has no subject field: return the user from wherever your token verifier puts it. A webhook subscription for which `getPrincipal` returns `null` is refused with `forbidden`, on stdio too; poll and push use the principal when there is one. -`webhookTtlMs` is the longest a webhook subscription lives without a refresh, and clients refresh before it lapses. The SDK verifies each endpoint with a challenge before the first delivery, signs every POST (Standard Webhooks), and retries a failed delivery up to five attempts in all. It sends at most ten event POSTs per subscription at a time, so a replayed backlog goes out ten at a time. Besides those waiting between retries, it holds at most 10 000 more of a subscription's events waiting for their turn or for a suspended delivery to resume, so a replay or `check` batch larger than that loses its oldest waiting events. It abandons an event past that cap or after its fifth failed attempt, and reports these to `onerror` at most once a minute per subscription, with how many. It sends each destination host one challenge at a time, so a subscribe waits while another challenge to that host is in flight, and at most ten in any 60 seconds; past that, or when ten subscribes already wait for the host, it refuses with `resourceExhausted` (`data.limit: 'verification'`; `data.retryAfterMs` says when to try again, and the SDK's client does). It answers a principal's subscribes to a URL whose challenge failed with that failure for 60 seconds, without another challenge. `nodeWebhookSender()` requires `https`, resolves the host at every send by querying DNS directly (so `/etc/hosts` does not apply; origins in `trustedOrigins` skip resolution), refuses IANA special-purpose addresses (loopback, private, link-local and the like) and connects only to the addresses it checked, IPv4 and IPv6; it follows no redirects and gives up after 5 seconds. +`webhookTtlMs` is the longest a webhook subscription lives without a refresh, and clients refresh before it lapses. The SDK verifies each endpoint with a challenge before the first delivery, signs every POST (Standard Webhooks), and retries a failed delivery up to five attempts in all. It sends at most ten event POSTs per subscription at a time, so a replayed backlog goes out ten at a time. Besides those waiting between retries, it holds at most 10 000 more of a subscription's events waiting for their turn or for a suspended delivery to resume, so a replay or `check` batch larger than that loses its oldest waiting events. It abandons an event past that cap or after its fifth failed attempt, and reports these to `onerror` at most once a minute per subscription, with how many. The subscriber learns of an abandoned event, or of one the receiver answered `413` or whose body is over 256 KiB, as a gap: a `gap` POST at the watermark after the next delivery its receiver acknowledges, or `truncated: true` on the next refresh this process answers, whichever comes first. It sends each destination host one challenge at a time, so a subscribe waits while another challenge to that host is in flight, and at most ten in any 60 seconds; past that, or when ten subscribes already wait for the host, it refuses with `resourceExhausted` (`data.limit: 'verification'`; `data.retryAfterMs` says when to try again, and the SDK's client does). It answers a principal's subscribes to a URL whose challenge failed with that failure for 60 seconds, without another challenge. `nodeWebhookSender()` requires `https`, resolves the host at every send by querying DNS directly (so `/etc/hosts` does not apply; origins in `trustedOrigins` skip resolution), refuses IANA special-purpose addresses (loopback, private, link-local and the like) and connects only to the addresses it checked, IPv4 and IPv6 (only those of a family the host has an address of that is neither loopback nor link-local, unless that leaves none or the host's interfaces cannot be read); it follows no redirects and gives up after 5 seconds. ::: warning `trustedOrigins` is for development only. Its exact origins, such as `http://127.0.0.1:9000`, are exempt from the `https` rule and the private-address check, so a receiver on your machine can take deliveries; endpoint verification, signing and the no-redirect rule still apply. diff --git a/packages/client/src/ext/events/extension.ts b/packages/client/src/ext/events/extension.ts index 0ffbf93b9d..789b9899d9 100644 --- a/packages/client/src/ext/events/extension.ts +++ b/packages/client/src/ext/events/extension.ts @@ -1,4 +1,4 @@ -import type { DeliveryMode, ListEventsResult } from '@modelcontextprotocol/core/ext/events'; +import type { DeliveryMode, EventDescriptor, ListEventsResult } from '@modelcontextprotocol/core/ext/events'; import { EVENTS_EXTENSION_ID, EVENTS_LIST_METHOD, eventsCapabilityOf } from '@modelcontextprotocol/core/ext/events'; import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal/public'; @@ -8,6 +8,7 @@ import { NoCompatibleDeliveryModeError } from './errors'; import { PollDriver } from './poll'; import { PushDriver, PushUnavailableError } from './push'; import { WebhookReceiver } from './receiver'; +import { isModeRefusal } from './recovery'; import { EventsConnection } from './request'; import type { Driver, DriverContext, EventSubscription, SubscribeOptions } from './subscription'; import { SubscriptionQueue } from './subscription'; @@ -144,18 +145,25 @@ export class EventsClientExtension implements ClientExtension { * `events/poll` response; for push, the first * `notifications/events/active`, within the request timeout; for webhook, * the `events/subscribe` response). A transient failure of that exchange (a - * transport error, a JSON-RPC error that is not an Events kind, or the - * server's webhook verification limit, `resourceExhausted` with - * `data.limit: 'verification'`, retried after its `data.retryAfterMs` - * when given) does not reject: delivery is retried in the background. - * Without `delivery`, a push subscription whose first stream fails before - * its first `active` with anything but an `EventsError` (no valid `active` - * within the request timeout, as behind a host that buffers whole - * responses, a transport error, or an `active` that fails its schema) - * reports that failure to the client's `onerror` and subscribes by poll - * instead, once, when the event type offers poll. A `cursor` the - * server refuses because the event type's schema changed is dropped: the - * event types are listed again, the subscription starts from now, and + * transport error, an HTTP `5xx` or `429`, a JSON-RPC error other than an + * Events kind and `-32601`, or the server's webhook verification limit, + * `resourceExhausted` with `data.limit: 'verification'`, retried after its + * `data.retryAfterMs` when given) does not reject: it is reported to the + * client's `onerror`, and delivery is retried in the background. Without + * `delivery`, a push subscription whose first stream fails before its + * first `active` with anything but an `EventsError`, an auth failure or a + * `-32601` (no valid `active` within the request timeout, as behind a host + * that buffers whole responses, a transport error, or an `active` that + * fails its schema) reports that failure to the client's `onerror` and + * subscribes by poll instead, once, when the event type offers poll. An + * auth failure of the transport (such as the `UnauthorizedError` of a + * `401` its `authProvider` could not resolve) rejects, and so does a + * `-32601`. When the server refuses the selected delivery mode + * (`unsupported` with `data.feature: 'deliveryMode'`), the event types are + * listed again once and the mode selected again from that listing; a + * `delivery` the server refuses is not changed to another mode. A `cursor` + * the server refuses because the event type's schema changed is dropped: + * the event types are listed again, the subscription starts from now, and * `onGap` reports the fresh cursor. A `-32020` lists the event types again * and retries once. Once subscribed, every mode recovers from errors as * {@linkcode EventSubscription} describes. @@ -170,15 +178,20 @@ export class EventsClientExtension implements ClientExtension { * * @throws {EventsError} when the server refuses the subscription: `notFound` for an event type it does not list or * no longer serves, `invalidParams` for arguments its `inputSchema` rejects, `forbidden`, or another kind - * (`resourceExhausted` for any limit but the webhook verification limit). + * (`resourceExhausted` for any limit but the webhook verification limit, `unsupported` for a delivery mode it + * still refuses after the re-list). * @throws {NoCompatibleDeliveryModeError} when no delivery mode the event type offers is usable here, also when - * the schema change that refused `cursor` left the event type without the selected mode. + * the schema change that refused `cursor`, or the re-list after a refused delivery mode, left the event type + * without a usable mode. * @throws {SdkError} `CapabilityNotSupported` when {@linkcode EventsClientExtension.supported} is `false`, * `ConnectionClosed` when the client closes before the first exchange answers, or another code when that * exchange fails in the SDK (for example `RequestTimeout`, also when a push stream that does not fall back to - * poll sends no valid `notifications/events/active` in time, or `InvalidResult` for an `active` that fails its - * schema). - * @throws {ProtocolError} `-32020` when the server rejects the `Mcp-Param` headers again after a re-list. + * poll sends no valid `notifications/events/active` in time, `InvalidResult` for an `active` that fails its + * schema, or an `SdkHttpError` for an HTTP error status other than `5xx` and `429`). + * @throws {ProtocolError} `-32020` when the server rejects the `Mcp-Param` headers again after a re-list, or + * `-32601` when it does not serve the method. + * @throws {Error} the transport's auth failure (such as `UnauthorizedError`) when the first exchange is not + * authorized. * @throws {TypeError} when `webhook.secretProvider` returns something that is not a Standard Webhooks secret, or a * secret another open server subscription signs with. */ @@ -190,15 +203,23 @@ export class EventsClientExtension implements ClientExtension { descriptor = connection.descriptor(options.name); } if (descriptor === undefined) throw new EventsError('notFound', 'Event type not found', { kind: 'event' }); - const mode = selectDeliveryMode(options.name, descriptor.delivery, options.delivery, this.#options.webhook !== undefined); - // Unless `delivery` forced push, a first push stream that cannot work hands the subscription to poll, once. - const fallback = options.delivery === undefined && mode === 'push' && descriptor.delivery.includes('poll'); + const mode = this.#select(options, descriptor); try { - return await this.#start(mode, options, connection, fallback); + return await this.#subscribeIn(mode, descriptor, options, connection); } catch (error) { - if (!(error instanceof PushUnavailableError)) throw error; - connection.report(error); - return this.#start('poll', options, connection, false); + if (!isModeRefusal(error)) throw error; + // The listing the mode came from may be stale: list again and select again, once. + let fresh: EventDescriptor | undefined; + try { + await connection.list(); + fresh = connection.descriptor(options.name); + } catch { + throw error; + } + if (fresh === undefined) throw error; + const again = this.#select(options, fresh); + if (again === mode) throw error; + return this.#subscribeIn(again, fresh, options, connection); } } @@ -220,6 +241,27 @@ export class EventsClientExtension implements ClientExtension { return request => receiver.handle(request); } + #select(options: SubscribeOptions, descriptor: EventDescriptor): DeliveryMode { + return selectDeliveryMode(options.name, descriptor.delivery, options.delivery, this.#options.webhook !== undefined); + } + + // Runs `mode`; unless `delivery` forced push, a first push stream that cannot work hands the subscription to poll, once. + async #subscribeIn( + mode: DeliveryMode, + descriptor: EventDescriptor, + options: SubscribeOptions, + connection: EventsConnection + ): Promise> { + const fallback = options.delivery === undefined && mode === 'push' && descriptor.delivery.includes('poll'); + try { + return await this.#start(mode, options, connection, fallback); + } catch (error) { + if (!(error instanceof PushUnavailableError)) throw error; + connection.report(error); + return this.#start('poll', options, connection, false); + } + } + // Runs a subscription in `mode`, resolving once its first exchange succeeds. async #start( mode: DeliveryMode, diff --git a/packages/client/src/ext/events/push.ts b/packages/client/src/ext/events/push.ts index 7478fb1d0b..ea59148d7b 100644 --- a/packages/client/src/ext/events/push.ts +++ b/packages/client/src/ext/events/push.ts @@ -18,7 +18,7 @@ import type * as z from 'zod/v4'; import type { StreamEnd, StreamHandle } from '../../client/client'; import { clientInternals } from '../../client/client'; -import { connectionClosed, DriverLoop, isHeaderMismatch, jitteredDelay, MAX_TIMER_DELAY_MS } from './recovery'; +import { connectionClosed, DriverLoop, endsSubscription, isHeaderMismatch, jitteredDelay, MAX_TIMER_DELAY_MS } from './recovery'; import { asEventsError } from './request'; import type { Driver, DriverContext } from './subscription'; @@ -107,9 +107,9 @@ export class PushDriver implements Driver { return; } const { connection, subscription } = this.#context; - if (this.#fallback && this.#loop.first && !(error instanceof EventsError) && connectionClosed(connection, error) === undefined) { - throw new PushUnavailableError(subscription.name, error); - } + const unavailable = + !(error instanceof EventsError) && !endsSubscription(error) && connectionClosed(connection, error) === undefined; + if (this.#fallback && this.#loop.first && unavailable) throw new PushUnavailableError(subscription.name, error); await this.#loop.recover(error); } diff --git a/packages/client/src/ext/events/recovery.ts b/packages/client/src/ext/events/recovery.ts index 92a1805edc..2482b93c2f 100644 --- a/packages/client/src/ext/events/recovery.ts +++ b/packages/client/src/ext/events/recovery.ts @@ -1,8 +1,9 @@ import type { DeliveryMode } from '@modelcontextprotocol/core/ext/events'; -import { HEADER_MISMATCH_ERROR_CODE, ProtocolError } from '@modelcontextprotocol/core-internal'; +import { HEADER_MISMATCH_ERROR_CODE, ProtocolError, ProtocolErrorCode } from '@modelcontextprotocol/core-internal'; import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; -import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal/public'; +import { SdkError, SdkErrorCode, SdkHttpError } from '@modelcontextprotocol/core-internal/public'; +import { isAuthSeamEscape } from '../../client/authSeam'; import { NoCompatibleDeliveryModeError } from './errors'; import type { EventsConnection } from './request'; import type { DriverContext, SubscribeOptions } from './subscription'; @@ -11,9 +12,20 @@ import type { DriverContext, SubscribeOptions } from './subscription'; export const MAX_TIMER_DELAY_MS = 2_147_483_647; const RETRY_BASE_MS = 1000; const RETRY_MAX_MS = 30_000; +// Retried failures are reported at once, then counted and reported together at most this often per subscription. +const RETRY_REPORT_INTERVAL_MS = 60_000; +// JSON-RPC codes that end a subscription: the server no longer serves the method, or rejects its params. +const FINAL_CODES: ReadonlySet = new Set([ProtocolErrorCode.MethodNotFound, ProtocolErrorCode.InvalidParams]); + +// An error that ends a subscription whenever it comes: an auth failure (a retry would run auth() again), a -32601 or a -32602. +export function endsSubscription(error: unknown): boolean { + return isAuthSeamEscape(error) || (error instanceof ProtocolError && FINAL_CODES.has(error.code)); +} -// An error of the first exchange that subscribe() rejects with (a -32020 only once its re-list is spent); any other (transport, non-Events JSON-RPC, a verification limit) is retried in the background. +// An error of the first exchange that subscribe() rejects with (a -32020 only once its re-list is spent); any other (transport, an HTTP 5xx or 429, another non-Events JSON-RPC error, a verification limit) is retried in the background. export function refusesSubscription(error: unknown): boolean { + if (endsSubscription(error)) return true; + if (error instanceof SdkHttpError) return !(error.status >= 500 || error.status === 429); return (error instanceof EventsError && !isVerificationLimit(error)) || error instanceof SdkError || isHeaderMismatch(error); } @@ -60,13 +72,27 @@ export function isSchemaChange(error: unknown): boolean { ); } -// Every mode's recovery once subscribed (spec §6.3): `relist` and go on while still offered, `mismatch` (re-list and retry once, then end), `fail` (end with the error), or `retry` later (anything but an Events kind, and a verification limit). +// An `unsupported` error saying the server does not offer the delivery mode used. +export function isModeRefusal(error: unknown): boolean { + return ( + error instanceof EventsError && + error.kind === 'unsupported' && + (error.data as { feature?: unknown } | undefined)?.feature === 'deliveryMode' + ); +} + +// Every mode's recovery once subscribed (spec §6.3): `relist` and go on while still offered, `mismatch` (re-list and retry once, then end), `fail` (end with the error), or `retry` later (anything but an Events kind or an endsSubscription() error, and a verification limit). export function recoveryFor(error: unknown): 'relist' | 'mismatch' | 'fail' | 'retry' { + if (endsSubscription(error)) return 'fail'; if (isHeaderMismatch(error)) return 'mismatch'; if (!(error instanceof EventsError) || isVerificationLimit(error)) return 'retry'; return error.kind === 'notFound' || isSchemaChange(error) ? 'relist' : 'fail'; } +function messageOf(error: unknown): string { + return error instanceof Error ? error.message : String(error); +} + // Reports a possible gap at `cursor` through onGap; a throwing onGap goes to the client's onerror, and delivery goes on. export function reportGap(subscription: SubscribeOptions, connection: EventsConnection, cursor: string | null): void { try { @@ -88,7 +114,7 @@ export async function requireOffered(connection: EventsConnection, name: string, if (!descriptor.delivery.includes(mode)) throw new NoCompatibleDeliveryModeError(name, descriptor.delivery, [mode]); } -// Re-lists, then whether `name` is still listed with `mode`; `undefined` when the list fails. +// Re-lists, then whether `name` is still listed with `mode`; `undefined` when the list fails, unless with an endsSubscription() error, which it throws. export async function stillOffered( connection: EventsConnection, name: string, @@ -97,7 +123,8 @@ export async function stillOffered( ): Promise { try { await connection.list(undefined, { signal }); - } catch { + } catch (error) { + if (endsSubscription(error)) throw error; return undefined; } return connection.descriptor(name)?.delivery.includes(mode) === true; @@ -136,6 +163,11 @@ export class DriverLoop { #hooks: LoopHooks = {}; #wake: (() => void) | undefined; #running: Promise = Promise.resolve(); + // Retried failures since the last report and the latest of them, when that report went out, and the timer of the next. + #retried = 0; + #lastRetried: unknown; + #reportedAt: number | undefined; + #report: ReturnType | undefined; constructor(context: DriverContext, mode: DeliveryMode) { this.#context = context; @@ -190,6 +222,7 @@ export class DriverLoop { this.#stopped = true; this.#abort.abort(); this.#interrupt(); + clearTimeout(this.#report); await cleanup?.(); await this.#running; } @@ -248,6 +281,7 @@ export class DriverLoop { // A transient re-list failure is retried in the background, from now, as a transient first exchange is. this.#restartFromNow(); this.subscribed(); + this.#retrying(listError); return 'retry'; } this.#restartFromNow(); @@ -255,10 +289,14 @@ export class DriverLoop { } if (refusesSubscription(error)) throw error; this.subscribed(); + this.#retrying(error); return 'retry'; } const recovery = recoveryFor(error); - if (recovery === 'retry') return 'retry'; + if (recovery === 'retry') { + this.#retrying(error); + return 'retry'; + } // A -32020 here is the second: the mode has already re-listed once and retried with fresh headers. if (recovery !== 'relist') throw error; const offered = await stillOffered(connection, subscription.name, this.#mode, this.#abort.signal); @@ -278,12 +316,47 @@ export class DriverLoop { this.#schemaChanged = true; } + // Reports a failure the loop retries to onerror at once, unless a report went out in the last RETRY_REPORT_INTERVAL_MS; then it counts towards the next. + #retrying(error: unknown): void { + if (this.ended) return; + const now = Date.now(); + if (this.#report === undefined && (this.#reportedAt === undefined || now - this.#reportedAt >= RETRY_REPORT_INTERVAL_MS)) { + this.#reportedAt = now; + this.#context.connection.report(new Error(`${this.#subject()} failed and is retried: ${messageOf(error)}`, { cause: error })); + return; + } + this.#retried += 1; + this.#lastRetried = error; + this.#report ??= setTimeout(() => this.#reportRetried(), this.#reportedAt! + RETRY_REPORT_INTERVAL_MS - now); + } + + // Reports how many failures were retried since the last report, and the latest. + #reportRetried(): void { + const retried = this.#retried; + const latest = this.#lastRetried; + this.#report = undefined; + this.#reportedAt = Date.now(); + this.#retried = 0; + this.#lastRetried = undefined; + const failures = retried === 1 ? 'failure' : 'failures'; + this.#context.connection.report( + new Error(`${this.#subject()}: ${retried} more retried ${failures} since the last report, the latest: ${messageOf(latest)}`, { + cause: latest + }) + ); + } + + #subject(): string { + return `${this.#mode} subscription to '${this.#context.subscription.name}'`; + } + #interrupt(): void { this.#wake?.(); this.#hooks.interrupt?.(); } #fail(error: unknown): void { + clearTimeout(this.#report); this.#settle.reject(error); this.#context.queue.fail(error); } diff --git a/packages/client/src/ext/events/subscription.ts b/packages/client/src/ext/events/subscription.ts index d0978f1757..bf3a49b6b7 100644 --- a/packages/client/src/ext/events/subscription.ts +++ b/packages/client/src/ext/events/subscription.ts @@ -48,11 +48,17 @@ export interface SubscribeOptions { * - A `ProtocolError` `-32020` (the `Mcp-Param` headers do not match the * arguments): the event types are listed again and the request is retried * once with fresh headers; a second `-32020` ends the loop with it. - * - Anything else (a network or transport failure, another JSON-RPC error, a - * push stream that ends, goes silent or sends no valid `active`): retried - * after a backoff. The server's webhook verification limit - * (`resourceExhausted` with `data.limit: 'verification'`) is retried after - * its `data.retryAfterMs`, or after a backoff without one. + * - An auth failure of the transport (such as the `UnauthorizedError` of a + * `401` its `authProvider` could not resolve), or a `ProtocolError` + * `-32601` (the server no longer serves the method): the loop ends with it. + * - Anything else (a network or transport failure, an HTTP error status, + * another JSON-RPC error, a push stream that ends, goes silent or sends no + * valid `active`): retried after a backoff. The server's webhook + * verification limit (`resourceExhausted` with `data.limit: + * 'verification'`) is retried after its `data.retryAfterMs`, or after a + * backoff without one. Each of these failures but a push stream that ends + * or goes silent is reported to the client's `onerror`: the first at once, + * then at most one report a minute with how many were retried since. * * Closing the client, or connecting it again without resuming its session, * ends its subscriptions at once: the loop rejects with an `SdkError` diff --git a/packages/client/test/ext/events/extension.test.ts b/packages/client/test/ext/events/extension.test.ts index 68e4dadf80..fddb52d047 100644 --- a/packages/client/test/ext/events/extension.test.ts +++ b/packages/client/test/ext/events/extension.test.ts @@ -153,6 +153,42 @@ describe('EventsClientExtension.subscribe', () => { expect(() => selectDeliveryMode('tick', ['webhook', 'poll'], 'webhook', false)).toThrow(expect.objectContaining({ usable: [] })); }); + it('lists again once when the server refuses the delivery mode of a stale listing, and subscribes in the mode selected again', async () => { + const stale = descriptor('tick', { delivery: ['push', 'poll'] }); + const refusePush: Handler = () => { + throw new RpcError(-32_026, 'Unsupported', { feature: 'deliveryMode', value: 'push' }); + }; + const relisting = (fresh: ReturnType) => { + const listings = [[stale], [fresh]]; + return () => ({ events: listings.shift() ?? [fresh] }); + }; + + const pollOnly = descriptor('tick', { delivery: ['poll'] }); + const moved = await connectEvents({ 'events/list': relisting(pollOnly), 'events/stream': refusePush, 'events/poll': quietPoll }); + await moved.events.list(); + const sub = await track(moved.events.subscribe({ name: 'tick' })); + expect(sub.deliveryMode).toBe('poll'); + expect(callsTo(moved.calls, 'events/list')).toHaveLength(2); + expect(callsTo(moved.calls, 'events/stream')).toHaveLength(1); + + // A forced mode is not changed to another one. + const forced = await connectEvents({ 'events/list': relisting(pollOnly), 'events/stream': refusePush, 'events/poll': quietPoll }); + await forced.events.list(); + const error = await forced.events.subscribe({ name: 'tick', delivery: 'push' }).catch((error_: unknown) => error_); + expect(error).toBeInstanceOf(NoCompatibleDeliveryModeError); + expect(error).toMatchObject({ offered: ['poll'], usable: ['push'] }); + expect(callsTo(forced.calls, 'events/poll')).toHaveLength(0); + + // A fresh listing that still selects the refused mode rejects with the refusal. + const same = await connectEvents({ 'events/list': relisting(stale), 'events/stream': refusePush, 'events/poll': quietPoll }); + await same.events.list(); + const refused = await same.events.subscribe({ name: 'tick' }).catch((error_: unknown) => error_); + expect(refused).toBeInstanceOf(EventsError); + expect(refused).toMatchObject({ kind: 'unsupported', data: { feature: 'deliveryMode', value: 'push' } }); + expect(callsTo(same.calls, 'events/list')).toHaveLength(2); + expect(callsTo(same.calls, 'events/stream')).toHaveLength(1); + }); + it('refetches events/list for an uncached name and refuses one the server does not list', async () => { const { events, calls } = await connectEvents({ 'events/list': listing(descriptor('tick')), 'events/poll': quietPoll }); await track(events.subscribe({ name: 'tick' })); diff --git a/packages/client/test/ext/events/poll.test.ts b/packages/client/test/ext/events/poll.test.ts index d36194cb79..dda5ab6cb9 100644 --- a/packages/client/test/ext/events/poll.test.ts +++ b/packages/client/test/ext/events/poll.test.ts @@ -1,11 +1,12 @@ -import { ProtocolError, SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal'; +import { ProtocolError, SdkError, SdkErrorCode, SdkHttpError } from '@modelcontextprotocol/core-internal'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import { UnauthorizedError } from '../../../src/client/auth'; import type { Client } from '../../../src/client/client'; import type { EventSubscription, SubscribeOptions } from '../../../src/ext/events/index'; import { EventsError, NoCompatibleDeliveryModeError } from '../../../src/ext/events/index'; import type { Call, Handler, Notification } from './scripted'; -import { callsTo, connectEvents, descriptor, listing, occurrence, RpcError, script } from './scripted'; +import { authFailure, callsTo, connectEvents, descriptor, failSends, listing, occurrence, RpcError, script } from './scripted'; const subscriptions: EventSubscription[] = []; @@ -331,7 +332,8 @@ describe('poll delivery', () => { expect(vi.getTimerCount()).toBe(0); await vi.advanceTimersByTimeAsync(120_000); expect(polls()).toHaveLength(1); - expect(callsTo(calls, 'events/list')).toHaveLength(1); + // A refused delivery mode lists the event types again, which still select it. + expect(callsTo(calls, 'events/list')).toHaveLength(refusal.data?.['feature'] === 'deliveryMode' ? 2 : 1); } }); @@ -357,6 +359,109 @@ describe('poll delivery', () => { expect(await nextEventId(sub[Symbol.asyncIterator]())).toBe('e1'); }); + it('reports a retried failure to onerror at once, then those of the next minute together, and keeps polling', async () => { + const { client, polls, subscribe } = await pollWith(() => { + throw new RpcError(-32_603, 'Internal error'); + }); + const errors: Error[] = []; + client.onerror = error => void errors.push(error); + await subscribe(); + + expect(errors).toEqual([ + expect.objectContaining({ + message: "poll subscription to 'tick' failed and is retried: Internal error", + cause: expect.objectContaining({ code: -32_603 }) + }) + ]); + // Retries at 1, 3, 7, 15 and 31 s fall in the minute after that report. + await vi.advanceTimersByTimeAsync(59_999); + expect(polls()).toHaveLength(6); + expect(errors).toHaveLength(1); + await vi.advanceTimersByTimeAsync(1); + expect(errors).toHaveLength(2); + expect(errors[1]).toMatchObject({ + message: "poll subscription to 'tick': 5 more retried failures since the last report, the latest: Internal error", + cause: expect.objectContaining({ code: -32_603 }) + }); + await vi.advanceTimersByTimeAsync(120_000); + expect(polls()).toHaveLength(8); + expect(errors).toHaveLength(4); + }); + + it('ends the loop on -32601, and rejects subscribe() when the first poll gets it', async () => { + const { polls, subscribe } = await pollWith( + script({ events: [], cursor: 'c1', nextPollMs: 0 }, new RpcError(-32_601, 'Method not found')) + ); + const sub = await subscribe(); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + await vi.advanceTimersByTimeAsync(1000); + + const error = await pending; + expect(error).toBeInstanceOf(ProtocolError); + expect(error).toMatchObject({ code: -32_601 }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(120_000); + expect(polls()).toHaveLength(2); + + const first = await pollWith(script(new RpcError(-32_601, 'Method not found'))); + const refused = await first.subscribe().catch((error_: unknown) => error_); + expect(refused).toBeInstanceOf(ProtocolError); + expect(refused).toMatchObject({ code: -32_601 }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(120_000); + expect(first.polls()).toHaveLength(1); + }); + + it('rejects subscribe() on an auth failure of the first poll, and ends the loop on one once subscribed, without retrying', async () => { + const first = await pollWith(script({ events: [], cursor: 'c1', nextPollMs: 60_000 })); + const refusedPolls = failSends(first.client, 'events/poll', authFailure); + const error = await first.subscribe().catch((error_: unknown) => error_); + expect(error).toBeInstanceOf(UnauthorizedError); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(120_000); + expect(refusedPolls()).toBe(1); + + const later = await pollWith(script({ events: [], cursor: 'c1', nextPollMs: 0 })); + const sub = await later.subscribe(); + const laterPolls = failSends(later.client, 'events/poll', authFailure); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + await vi.advanceTimersByTimeAsync(1000); + expect(await pending).toBeInstanceOf(UnauthorizedError); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(120_000); + expect(laterPolls()).toBe(1); + expect(later.polls()).toHaveLength(1); + }); + + it('resolves subscribe() after an HTTP 503 or 429 on the first poll and delivers after the retry; another status rejects', async () => { + const httpError = (status: number) => + new SdkHttpError(SdkErrorCode.ClientHttpNotImplemented, `Error POSTing to endpoint: ${status}`, { status }); + for (const status of [503, 429]) { + const { client, polls, subscribe } = await pollWith(script({ events: [occurrence('e1')], cursor: 'c1', nextPollMs: 60_000 })); + failSends(client, 'events/poll', attempt => (attempt === 1 ? httpError(status) : undefined)); + const sub = await subscribe(); + expect(polls()).toHaveLength(0); + + await vi.advanceTimersByTimeAsync(1000); + expect(polls()).toHaveLength(1); + expect(await nextEventId(sub[Symbol.asyncIterator]())).toBe('e1'); + await sub.cancel(); + } + + const { client, subscribe } = await pollWith(script({ events: [], cursor: 'c1', nextPollMs: 60_000 })); + const attempts = failSends(client, 'events/poll', () => httpError(404)); + const error = await subscribe().catch((error_: unknown) => error_); + expect(error).toBeInstanceOf(SdkHttpError); + expect(error).toMatchObject({ status: 404 }); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(120_000); + expect(attempts()).toBe(1); + }); + it('ends the loop with ConnectionClosed when the client closes during a poll', async () => { const { client, polls, subscribe } = await pollWith(script({ events: [], cursor: 'c1', nextPollMs: 0 })); const sub = await subscribe(); diff --git a/packages/client/test/ext/events/push.test.ts b/packages/client/test/ext/events/push.test.ts index 76c868ac18..b3cc9a8471 100644 --- a/packages/client/test/ext/events/push.test.ts +++ b/packages/client/test/ext/events/push.test.ts @@ -3,10 +3,11 @@ import { ProtocolError, SdkError, SdkErrorCode, SUBSCRIPTION_ID_META_KEY } from import type { MockInstance } from 'vitest'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import { UnauthorizedError } from '../../../src/client/auth'; import type { EventSubscription, SubscribeOptions } from '../../../src/ext/events/index'; import { EventsError, NoCompatibleDeliveryModeError } from '../../../src/ext/events/index'; import type { Call, Handler } from './scripted'; -import { callsTo, connectEvents, descriptor, listing, occurrence, RpcError, script } from './scripted'; +import { authFailure, callsTo, connectEvents, descriptor, failSends, listing, occurrence, RpcError, script } from './scripted'; const subscriptions: EventSubscription[] = []; @@ -298,6 +299,23 @@ describe('push delivery', () => { expect(await nextEventId(sub[Symbol.asyncIterator]())).toBe('e1'); }); + it('ends the loop on an auth failure of a reopen, without reopening again', async () => { + const { client, last, streams, subscribe } = await pushWith(); + const sub = await subscribe({}, s => s.active({ cursor: 'c1' })); + const reopens = failSends(client, 'events/stream', authFailure); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + + await last().end(); + await vi.advanceTimersByTimeAsync(500); + expect(await pending).toBeInstanceOf(UnauthorizedError); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(120_000); + expect(reopens()).toBe(1); + expect(streams()).toHaveLength(1); + }); + it('fails the iterator on terminated forbidden', async () => { const { last, streams, subscribe } = await pushWith(); const sub = await subscribe(); @@ -463,7 +481,8 @@ describe('push delivery', () => { expect(vi.getTimerCount()).toBe(0); await vi.advanceTimersByTimeAsync(120_000); expect(streams()).toHaveLength(1); - expect(lists()).toHaveLength(1); + // A refused delivery mode lists the event types again, which still select it. + expect(lists()).toHaveLength(refusal.data?.feature === 'deliveryMode' ? 2 : 1); } }); @@ -659,6 +678,22 @@ describe('push delivery', () => { expect(errors).toEqual([]); }); + it.each([ + ['an auth failure', authFailure, UnauthorizedError], + ['-32601', () => new ProtocolError(-32_601, 'Method not found'), ProtocolError] + ])('rejects without falling back when the first stream fails with %s', async (_case, failure, type) => { + const { client, events, errors, polls } = await pushOrPoll(() => new Promise(() => {})); + const attempts = failSends(client, 'events/stream', failure); + const error = await events.subscribe({ name: 'tick' }).catch((error_: unknown) => error_); + + expect(error).toBeInstanceOf(type); + expect(polls()).toHaveLength(0); + expect(errors).toEqual([]); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(120_000); + expect(attempts()).toBe(1); + }); + it('rejects as before when the first stream is refused with an EventsError', async () => { const { events, errors, polls } = await pushOrPoll(script(new RpcError(-32_024, 'Forbidden'))); const error = await events.subscribe({ name: 'tick' }).catch((error_: unknown) => error_); diff --git a/packages/client/test/ext/events/recovery.test.ts b/packages/client/test/ext/events/recovery.test.ts index 4b4f885dbb..221bcd780f 100644 --- a/packages/client/test/ext/events/recovery.test.ts +++ b/packages/client/test/ext/events/recovery.test.ts @@ -1,9 +1,13 @@ -import { ProtocolError, SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal'; +import { ProtocolError, SdkError, SdkErrorCode, SdkHttpError } from '@modelcontextprotocol/core-internal'; import { describe, expect, it, vi } from 'vitest'; import { EventsError } from '../../../src/ext/events/index'; import { recoveryFor, refusesSubscription, reportGap } from '../../../src/ext/events/recovery'; import type { EventsConnection } from '../../../src/ext/events/request'; +import { authFailure } from './scripted'; + +const httpError = (status: number) => + new SdkHttpError(SdkErrorCode.ClientHttpNotImplemented, `Error POSTing to endpoint: ${status}`, { status }); describe('the recovery rules every delivery mode shares', () => { it.each([ @@ -32,8 +36,13 @@ describe('the recovery rules every delivery mode shares', () => { ], ['callbackEndpointError', 'fail', true, new EventsError('callbackEndpointError', 'Unreachable', { reason: 'timeout' })], ['-32020', 'mismatch', true, new ProtocolError(-32_020, 'Mcp-Param-Region header mismatch')], + ['-32601', 'fail', true, new ProtocolError(-32_601, 'Method not found')], ['another JSON-RPC error', 'retry', false, new ProtocolError(-32_603, 'Internal error')], + ['an auth failure', 'fail', true, authFailure()], ['an SDK error', 'retry', true, new SdkError(SdkErrorCode.RequestTimeout, 'Request timed out')], + ['an HTTP 503', 'retry', false, httpError(503)], + ['an HTTP 429', 'retry', false, httpError(429)], + ['an HTTP 404', 'retry', true, httpError(404)], ['a transport error', 'retry', false, new Error('fetch failed')] ] as const)('%s → %s once subscribed; refuses a first exchange: %s', (_name, recovery, refuses, error) => { expect(recoveryFor(error)).toBe(recovery); diff --git a/packages/client/test/ext/events/scripted.ts b/packages/client/test/ext/events/scripted.ts index 7ea017871b..828b94c1f4 100644 --- a/packages/client/test/ext/events/scripted.ts +++ b/packages/client/test/ext/events/scripted.ts @@ -4,6 +4,8 @@ import type { JSONRPCMessage, JSONRPCRequest, RequestId, ServerCapabilities, Tra import { InMemoryTransport } from '@modelcontextprotocol/core-internal'; import { generateWebhookId, parseWebhookSecret, signWebhook } from '@modelcontextprotocol/core-internal/ext/events'; +import { UnauthorizedError } from '../../../src/client/auth'; +import { markAuthSeamEscape } from '../../../src/client/authSeam'; import type { ClientOptions } from '../../../src/client/client'; import { Client } from '../../../src/client/client'; import type { EventsClientOptions } from '../../../src/ext/events/index'; @@ -191,6 +193,25 @@ export function script(...answers: Array | RpcError>): H export const callsTo = (calls: Call[], method: string): Call[] => calls.filter(call => call.method === method); +/** + * Makes the client's transport reject its `attempt`th request to `method` (from 1) with `failure(attempt)`, as a + * transport whose send fails does, or send it on when that is `undefined`; returns how many requests it saw. + */ +export function failSends(client: Client, method: string, failure: (attempt: number) => unknown): () => number { + const transport = client.transport!; + const send = transport.send.bind(transport); + let attempts = 0; + transport.send = (message, options) => { + if (!('method' in message && 'id' in message && message.method === method)) return send(message, options); + const error = failure(++attempts); + return error === undefined ? send(message, options) : Promise.reject(error); + }; + return () => attempts; +} + +/** An `UnauthorizedError` as the HTTP transports throw it on a 401: stamped as escaping their auth seam. */ +export const authFailure = (): Error => markAuthSeamEscape(new UnauthorizedError()); + export const WEBHOOK_URL = 'https://hooks.example.com/mcp/client123'; export interface WebhookPostOptions { diff --git a/packages/client/test/ext/events/webhook.test.ts b/packages/client/test/ext/events/webhook.test.ts index 584885581f..f2a67f59c0 100644 --- a/packages/client/test/ext/events/webhook.test.ts +++ b/packages/client/test/ext/events/webhook.test.ts @@ -2,10 +2,22 @@ import { ProtocolError, SdkError, SdkErrorCode } from '@modelcontextprotocol/cor import { generateWebhookSecret, parseWebhookSecret } from '@modelcontextprotocol/core-internal/ext/events'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import { UnauthorizedError } from '../../../src/client/auth'; import type { EventSubscription, SubscribeOptions } from '../../../src/ext/events/index'; import { EventsError, NoCompatibleDeliveryModeError } from '../../../src/ext/events/index'; import type { Call, Handler } from './scripted'; -import { callsTo, connectEvents, descriptor, listing, occurrence, RpcError, WEBHOOK_URL, webhookPost } from './scripted'; +import { + authFailure, + callsTo, + connectEvents, + descriptor, + failSends, + listing, + occurrence, + RpcError, + WEBHOOK_URL, + webhookPost +} from './scripted'; const subscriptions: EventSubscription[] = []; @@ -352,6 +364,23 @@ describe('webhook delivery', () => { } }); + it('fails the iterator on an auth failure of a refresh, without refreshing again', async () => { + const { client, post, subscribes, subscribe } = await webhookWith(granting({}, {})); + const sub = await subscribe(); + const refreshes = failSends(client, 'events/subscribe', authFailure); + const pending = sub[Symbol.asyncIterator]() + .next() + .catch((error_: unknown) => error_); + + await vi.advanceTimersByTimeAsync(45_000); + expect(await pending).toBeInstanceOf(UnauthorizedError); + expect(vi.getTimerCount()).toBe(0); + await vi.advanceTimersByTimeAsync(120_000); + expect(refreshes()).toBe(1); + expect(subscribes()).toHaveLength(1); + expect(await post(occurrence('e1'))).toBe(503); + }); + it('retries a refresh that fails transiently after a jittered delay, with the last cursor', async () => { const internal = new RpcError(-32_603, 'Internal error'); const { subscribes, subscribe } = await webhookWith(granting({ cursor: 'c1' }, internal, internal, { cursor: 'c2' }, internal, {})); @@ -639,7 +668,8 @@ describe('webhook delivery', () => { expect(challenge.status).toBe(401); await vi.advanceTimersByTimeAsync(120_000); expect(subscribes()).toHaveLength(1); - expect(lists()).toHaveLength(1); + // A refused delivery mode lists the event types again, which still select it. + expect(lists()).toHaveLength(refusal.data?.['feature'] === 'deliveryMode' ? 2 : 1); } }); diff --git a/packages/server/src/ext/events/extension.ts b/packages/server/src/ext/events/extension.ts index 405c9a0bf7..deee2851b1 100644 --- a/packages/server/src/ext/events/extension.ts +++ b/packages/server/src/ext/events/extension.ts @@ -19,6 +19,7 @@ import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; import type { ServerExtension, ServerExtensionContext } from '../../server/extension'; import { markModernOnlyExtension } from '../../server/modernOnlyExtensions'; import { registerParamHeaderSource } from '../../server/paramHeaderSources'; +import { perRequestBacklogOf } from '../../server/perRequestTransport'; import type { Server } from '../../server/server'; import { markStreamingMethod } from '../../server/streamingMethods'; import type { BufferedEvent } from './emitBuffer'; @@ -260,7 +261,7 @@ export class EventsExtension implements ServerExtension { this.#modernOnly(server, () => this.#poll.handlePoll(params, requestCtx)) ); ctx.setRequestHandler(EVENTS_STREAM_METHOD, { params: StreamEventsRequestParamsSchema }, (params, requestCtx) => - this.#modernOnly(server, () => this.#push.open(params, requestCtx)) + this.#modernOnly(server, () => this.#push.open(params, requestCtx, perRequestBacklogOf(server.transport))) ); ctx.setRequestHandler(EVENTS_SUBSCRIBE_METHOD, { params: SubscribeEventsRequestParamsSchema }, (params, requestCtx) => this.#modernOnly(server, () => diff --git a/packages/server/src/ext/events/node.ts b/packages/server/src/ext/events/node.ts index 39bab1795e..fedaa483d8 100644 --- a/packages/server/src/ext/events/node.ts +++ b/packages/server/src/ext/events/node.ts @@ -10,6 +10,7 @@ import http from 'node:http'; import https from 'node:https'; import type { LookupFunction } from 'node:net'; import net from 'node:net'; +import os from 'node:os'; import { isSpecialPurposeAddress } from './specialAddresses'; import type { WebhookSender, WebhookSendOutcome, WebhookSendRequest } from './types'; @@ -22,6 +23,8 @@ const MAX_RESPONSE_BYTES = 65_536; const REFUSED: WebhookSendOutcome = { error: 'connection_refused' }; // OpenSSL certificate and verification codes, Node's TLS and OpenSSL error codes, and EPROTO, which Node reports for a failed TLS handshake. const TLS_FAILURE_CODE = /CERT|UNABLE_TO_VERIFY|INVALID_CA|SELF_SIGNED|DEPTH_ZERO|^ERR_SSL_|^ERR_TLS_|^EPROTO$/; +// IPv6 fe80::/10 and IPv4 169.254.0.0/16, which every interface can have without a route off its link. +const LINK_LOCAL = /^fe[89ab][\da-f]:|^169\.254\./i; /** * The default {@linkcode WebhookSender} for Node.js, hardened against @@ -30,10 +33,13 @@ const TLS_FAILURE_CODE = /CERT|UNABLE_TO_VERIFY|INVALID_CA|SELF_SIGNED|DEPTH_ZER * (with a DNS query, not `getaddrinfo`, so `/etc/hosts` does not apply), * refuses with `connection_refused` when any resolved address is in an IANA * special-purpose range (loopback, private, link-local and the like), and - * connects only to the addresses it checked, which Node tries in turn, with - * the URL's host name in the `Host` header and TLS SNI. It follows no - * redirects (a 3xx answer is returned as it is), gives up after 5 seconds - * with `{ error: 'timeout' }`, and reads at most 64 KiB of the response body. + * connects only to the addresses it checked, which Node tries in turn (only + * those of a family the host has an interface address of that is neither + * loopback nor link-local, unless that leaves none or the host's interfaces + * cannot be read), with the URL's host name + * in the `Host` header and TLS SNI. It follows no redirects (a 3xx answer is + * returned as it is), gives up after 5 seconds with `{ error: 'timeout' }`, + * and reads at most 64 KiB of the response body. * * Experimental: Events (SEP-3415) is new; this API may change in a minor release. * @@ -133,11 +139,12 @@ function hostnameOf(url: URL): string { return url.hostname.startsWith('[') ? url.hostname.slice(1, -1) : url.hostname; } -// A lookup that answers with checked addresses only, so the connection goes nowhere else: those of the family asked for, all of them when asked for all (Node then tries each), else the first. +// A lookup that answers with checked addresses only, so the connection goes nowhere else: those of the family asked for (with ADDRCONFIG, of a family the host has a non-loopback, non-link-local address of), all of them when asked for all (Node then tries each), else the first. function pinnedTo(addresses: readonly LookupAddress[]): LookupFunction { return (hostname, options, callback) => { const family = options.family === 'IPv4' ? 4 : options.family === 'IPv6' ? 6 : options.family; - const answers = family === 4 || family === 6 ? addresses.filter(address => address.family === family) : addresses; + const asked = family === 4 || family === 6 ? addresses.filter(address => address.family === family) : addresses; + const answers = ((options.hints ?? 0) & dns.ADDRCONFIG) === 0 ? asked : configured(asked); const [first] = answers; if (first === undefined) { callback(Object.assign(new Error(`getaddrinfo ENOTFOUND ${hostname}`), { code: 'ENOTFOUND', hostname }), []); @@ -149,6 +156,24 @@ function pinnedTo(addresses: readonly LookupAddress[]): LookupFunction { }; } +// As ADDRCONFIG: the addresses of a family the host has an interface address of, not internal or link-local; all of them when that leaves none or the interfaces cannot be read. +function configured(addresses: readonly LookupAddress[]): readonly LookupAddress[] { + let interfaces: ReturnType; + try { + interfaces = os.networkInterfaces(); + } catch { + return addresses; + } + const families = new Set(); + for (const entries of Object.values(interfaces)) { + for (const entry of entries ?? []) { + if (!entry.internal && !LINK_LOCAL.test(entry.address)) families.add(entry.family === 'IPv6' ? 6 : 4); + } + } + const kept = addresses.filter(address => families.has(address.family)); + return kept.length === 0 ? addresses : kept; +} + // Certificate, verification and handshake failures are tls_error; every other failure (refused, reset, unreachable, unresolved) is connection_refused. function failureOf(error: unknown): WebhookSendOutcome { const code = (error as { code?: unknown } | null | undefined)?.code; diff --git a/packages/server/src/ext/events/push.ts b/packages/server/src/ext/events/push.ts index fc5983f791..1c5887a5f7 100644 --- a/packages/server/src/ext/events/push.ts +++ b/packages/server/src/ext/events/push.ts @@ -26,6 +26,8 @@ import type { SubscriptionValidator } from './validation'; // The shortest heartbeat granted, whatever the client suggests (D33). const HEARTBEAT_FLOOR_MS = 5000; +// A stream whose client has left more than this unread ends before its next write. +const MAX_STREAM_BACKLOG_BYTES = 1_048_576; // A check that throws one of these ends its subscription; any other error leaves the loop running. export const TERMINAL_KINDS: ReadonlySet = new Set(['forbidden', 'notFound', 'unsupported']); @@ -46,6 +48,8 @@ interface PushStream { readonly requestId: RequestId; readonly grant: number; readonly notify: ServerContext['mcpReq']['notify']; + // The bytes written that the client has not read yet, where the transport tells. + readonly backlog?: () => number; // Aborts when the stream ends; the `signal` of every callback's ctx. readonly ended: AbortController; readonly ctx: CheckContext; @@ -89,7 +93,7 @@ export function errorObject(error: unknown): EventsErrorObject { return { code: ProtocolErrorCode.InternalError, message: error instanceof Error ? error.message : String(error) }; } -// A batch's cursors stay at `from` until its last event, so none runs ahead of an unsent event; a truncated batch carries the fresh cursor throughout. +// A batch's cursors, its start or gap cursor too, stay at `from` until its last event, truncated or not, so none runs ahead of an unsent event. export async function checkedBatch( entry: RegisteredEvent, from: string | null, @@ -99,7 +103,7 @@ export async function checkedBatch( ): Promise { const { events, truncated } = await checkedEvents(entry, result, maxAgeMs, report); const last = events.length - 1; - const cursorAt = (index: number) => (truncated || index === last ? result.cursor : from); + const cursorAt = (index: number) => (index === last ? result.cursor : from); return { cursor: cursorAt(-1), truncated, @@ -173,10 +177,11 @@ export class StreamSet implements SubscriptionSource { return count; } - async open(params: StreamEventsRequestParams, ctx: ServerContext): Promise { + // `backlog` reads the bytes of the response stream the client has not read, on a transport that can tell. + async open(params: StreamEventsRequestParams, ctx: ServerContext, backlog?: () => number): Promise { const { entry, principal, args } = await this.#deps.validator.validate('push', params, ctx); this.#deps.validator.assertCapacity(principal); - const stream = this.#create(entry, principal, args, params, ctx); + const stream = this.#create(entry, principal, args, params, ctx, backlog); const result = { _meta: { [SUBSCRIPTION_ID_META_KEY]: ctx.mcpReq.id } }; try { await entry.definition.onSubscribe?.(stream.ctx, args); @@ -245,7 +250,8 @@ export class StreamSet implements SubscriptionSource { principal: string | null, args: Record, params: StreamEventsRequestParams, - ctx: ServerContext + ctx: ServerContext, + backlog: (() => number) | undefined ): PushStream { let finish!: () => void; const done = new Promise(resolve => (finish = resolve)); @@ -257,6 +263,7 @@ export class StreamSet implements SubscriptionSource { requestId: ctx.mcpReq.id, grant: Math.min(Math.max(params.heartbeatMs ?? max, HEARTBEAT_FLOOR_MS), max), notify: ctx.mcpReq.notify, + ...(backlog !== undefined && { backlog }), ended, ctx: makeContext({ name: entry.name, @@ -321,6 +328,11 @@ export class StreamSet implements SubscriptionSource { // Params that resolve to `undefined` (a dropped event) send nothing; an event's own `_meta` keys stay beside the stream's id. #write(stream: PushStream, method: string, params: Record | Promise | undefined>): void { + // A client that stopped reading is treated as gone, as after a failed write; it reconnects from its cursor. + if ((stream.backlog?.() ?? 0) > MAX_STREAM_BACKLOG_BYTES) { + void this.#end(stream); + return; + } // A failed write means the client is gone. stream.queue = stream.queue .then(async () => { diff --git a/packages/server/src/ext/events/webhookEngine.ts b/packages/server/src/ext/events/webhookEngine.ts index c3318199ff..edf382ec32 100644 --- a/packages/server/src/ext/events/webhookEngine.ts +++ b/packages/server/src/ext/events/webhookEngine.ts @@ -34,6 +34,10 @@ const VERIFICATION_WINDOW_MS = 60_000; const QUEUE_FULL_RETRY_MS = 5000; // The most failed pairs and destination hosts the verification limits remember. const MAX_REMEMBERED = 10_000; +// setTimeout fires at once for longer delays; a longer grant re-arms when the timer fires early. +const MAX_TIMER_DELAY_MS = 2 ** 31 - 1; +// After a failed store read, the record of an unwatched subscription is read again this much later. +const SWEEP_RETRY_MS = 60_000; const encoder = new TextEncoder(); @@ -43,6 +47,8 @@ export interface WebhookEngineOptions { // Read at every send, so origins added later count. readonly trustedOrigins: ReadonlySet; onerror(error: Error): void; + // Whether this process watches the subscription (an expiry timer of its own); default none. + readonly watches?: (id: string) => boolean; readonly now?: () => number; } @@ -102,6 +108,11 @@ interface Tracked { // The attempts of the last SUSPENSION_WINDOW_MS, oldest first, and how many of them failed. recent: Array<{ readonly at: number; readonly failed: boolean }>; recentFailures: number; + // For a subscription this process does not watch: the `createdAt` of the record it delivers to, and the next read of that record. + createdAt?: number; + sweep?: ReturnType; + // An event was abandoned since the subscriber was last told of a gap. + gap: boolean; } // One `principal\0url` handshake in flight: the subscribes waiting for it, and the abort that pulls it from the host's queue once all of them were cancelled. @@ -204,6 +215,7 @@ export class WebhookEngine { readonly #store: WebhookSubscriptionStore; readonly #trustedOrigins: ReadonlySet; readonly #onerror: (error: Error) => void; + readonly #watches: (id: string) => boolean; readonly #now: () => number; readonly #tracked = new Map(); readonly #controls = new Set(); @@ -224,6 +236,7 @@ export class WebhookEngine { this.#store = options.store; this.#trustedOrigins = options.trustedOrigins; this.#onerror = options.onerror; + this.#watches = options.watches ?? (() => false); this.#now = options.now ?? (() => Date.now()); } @@ -253,7 +266,20 @@ export class WebhookEngine { // Queues one event POST and returns; calls for one subscription come in position order, and `seed` starts the watermark of an untracked id. deliver(record: WebhookSubscriptionRecord, occurrence: EventOccurrence, position: string | null, seed: string | null): void { - const tracked = this.#tracked.get(record.id) ?? this.#start(record.id, seed); + const watched = this.#watches(record.id); + let tracked = this.#tracked.get(record.id); + // A record created again since starts again, as track() does on a create. + if (!watched && tracked?.createdAt !== undefined && tracked.createdAt !== record.createdAt) { + this.#drop(record.id); + tracked = undefined; + } + if (tracked === undefined) { + tracked = this.#start(record.id, seed); + if (!watched) { + tracked.createdAt = record.createdAt; + this.#sweepAt(tracked, record); + } + } const message: Message = { webhookId: generateWebhookId(), occurrence, position, attempts: 0, place: 'waiting' }; tracked.pending.push(message); this.#queue(tracked, message, record); @@ -284,6 +310,15 @@ export class WebhookEngine { return this.#tracked.get(id)?.watermark; } + // Whether an event was abandoned since the subscriber was last told, which a refresh answers as `truncated: true`; it clears the mark. + takeGap(id: string): boolean { + const tracked = this.#tracked.get(id); + if (tracked?.gap !== true) return false; + tracked.gap = false; + // A type without replay has no position to have skipped past (SEP-3415: `truncated` stays false). + return tracked.watermark !== null; + } + // Moves the watermark to `position` when no message is pending, so a quiet upstream still advances it; it never passes an unsettled message. advance(id: string, position: string | null): void { const tracked = this.#tracked.get(id); @@ -465,7 +500,8 @@ export class WebhookEngine { lastDeliveryAt: null, lastError: null, recent: [], - recentFailures: 0 + recentFailures: 0, + gap: false }; this.#tracked.set(id, tracked); return tracked; @@ -478,6 +514,30 @@ export class WebhookEngine { tracked.ended.abort(); for (const message of tracked.pending) clearTimeout(message.retry); clearTimeout(tracked.report); + clearTimeout(tracked.sweep); + } + + // Reads the record of a subscription this process does not watch again at its expiry, so its state goes once the subscription ends elsewhere. + #sweepAt(tracked: Tracked, record: WebhookSubscriptionRecord): void { + const delay = Math.min(Math.max(record.expiresAt - this.#now(), 0), MAX_TIMER_DELAY_MS); + tracked.sweep = unref(setTimeout(() => void this.#sweep(tracked), delay)); + } + + // A record gone, expired or created again drops the state, unless it started again since; a later expiry re-arms; a watch begun since takes over. + async #sweep(tracked: Tracked): Promise { + tracked.sweep = undefined; + let record: WebhookSubscriptionRecord | undefined; + try { + record = await this.#store.get(tracked.id); + } catch (error) { + if (!this.#isCurrent(tracked)) return; + this.#onerror(toError(error)); + tracked.sweep = unref(setTimeout(() => void this.#sweep(tracked), SWEEP_RETRY_MS)); + return; + } + if (!this.#isCurrent(tracked) || this.#watches(tracked.id)) return; + if (record === undefined || record.expiresAt <= this.#now() || record.createdAt !== tracked.createdAt) this.forget(tracked.id); + else this.#sweepAt(tracked, record); } #isCurrent(tracked: Tracked): boolean { @@ -532,6 +592,7 @@ export class WebhookEngine { // Settles a message the engine gives up on, and reports it at once unless a report went out in the last ABANDON_REPORT_INTERVAL_MS; then it counts towards the next. #abandon(tracked: Tracked, message: Message, reason: string): void { this.#settle(tracked, message); + tracked.gap = true; const { eventId } = message.occurrence; const now = this.#now(); if (tracked.report === undefined && (tracked.reportedAt === undefined || now - tracked.reportedAt >= ABANDON_REPORT_INTERVAL_MS)) { @@ -593,14 +654,29 @@ export class WebhookEngine { ) ); this.#settle(tracked, message); + tracked.gap = true; return; } const outcome = await this.#post(record.url, record.id, this.#secretsOf(record), message.webhookId, body, tracked.ended.signal); if (!this.#isCurrent(tracked)) return; const retry = this.#observe(tracked, outcome); if (!tracked.active) tracked.suspendedExpiresAt ??= record.expiresAt; - if (retry) this.#retry(tracked, message); - else this.#settle(tracked, message); + if (retry) { + this.#retry(tracked, message); + return; + } + this.#settle(tracked, message); + const status = 'status' in outcome ? outcome.status : undefined; + // A 413 loses the event to the subscriber; a 410 is the receiver's own choice. + if (status === 413) tracked.gap = true; + else if (status !== undefined && isSuccess(status) && tracked.gap) this.#signalGap(tracked, record); + } + + // Tells the subscriber, after a delivery it acknowledged, that events were abandoned before the watermark. + #signalGap(tracked: Tracked, record: WebhookSubscriptionRecord): void { + tracked.gap = false; + // A type without replay has no position to have skipped past (SEP-3415: no gap for `cursor: null`). + if (tracked.watermark !== null) void this.sendControl(record, { type: 'gap', cursor: tracked.watermark }); } // Waits out the retry delay out of its slot, then queues the next attempt; after the last it abandons the message. diff --git a/packages/server/src/ext/events/webhookSubscriptions.ts b/packages/server/src/ext/events/webhookSubscriptions.ts index b6e332fb1d..a020319792 100644 --- a/packages/server/src/ext/events/webhookSubscriptions.ts +++ b/packages/server/src/ext/events/webhookSubscriptions.ts @@ -145,7 +145,8 @@ export class WebhookSubscriptions implements SubscriptionSource { sender: deps.sender, store: deps.store, trustedOrigins: deps.trustedOrigins, - onerror: error => deps.report(error) + onerror: error => deps.report(error), + watches: id => this.#watched.has(id) }); } @@ -392,7 +393,8 @@ export class WebhookSubscriptions implements SubscriptionSource { id, refreshBefore: new Date(refreshed.expiresAt).toISOString(), cursor: this.#engine.watermark(id) ?? null, - truncated: false, + // Events this process abandoned since the subscriber was last told. + truncated: this.#engine.takeGap(id), ...(deliveryStatus === undefined ? {} : { deliveryStatus }) }; } @@ -582,10 +584,12 @@ export class WebhookSubscriptions implements SubscriptionSource { const result = await entry.definition.check!(watched.ctx, record.arguments, from); const batch = await checkedBatch(entry, from, result, undefined, this.#deps.report); if (this.#watched.get(id) !== watched) return; - if (batch.truncated) void this.#engine.sendControl(record, { type: 'gap', cursor: batch.cursor }); this.#send(record, batch, from); // A quiet batch moves the watermark to the upstream cursor once nothing awaits an answer, so the refresh cursor advances. if (batch.events.length === 0) this.#engine.advance(id, batch.position); + // The gap goes at the watermark, as for abandoned events, or at the batch cursor when there is no watermark. + const gapCursor = this.#engine.watermark(id) ?? batch.cursor; + if (batch.truncated) void this.#engine.sendControl(record, { type: 'gap', cursor: gapCursor }); watched.position = batch.position; } } catch (error) { diff --git a/packages/server/src/server/perRequestTransport.ts b/packages/server/src/server/perRequestTransport.ts index bd1a04f9da..bd7e598fa0 100644 --- a/packages/server/src/server/perRequestTransport.ts +++ b/packages/server/src/server/perRequestTransport.ts @@ -116,6 +116,7 @@ interface SseSink { } let readClassification: (transport: PerRequestHTTPServerTransport) => MessageClassification; +let readBacklog: (transport: PerRequestHTTPServerTransport) => number; /** * The per-request micro-transport: a real, connected `Transport` whose whole @@ -128,6 +129,11 @@ let readClassification: (transport: PerRequestHTTPServerTransport) => MessageCla export class PerRequestHTTPServerTransport implements Transport { static { readClassification = transport => transport._classification; + readBacklog = transport => { + const sse = transport._sse; + const desiredSize = sse === undefined || sse.closed ? null : sse.controller.desiredSize; + return desiredSize === null ? 0 : -desiredSize; + }; } onclose?: () => void; @@ -393,17 +399,21 @@ export class PerRequestHTTPServerTransport implements Transport { private upgradeToSse(): void { let controller!: ReadableStreamDefaultController; - const readable = new ReadableStream({ - start: streamController => { - controller = streamController; + const readable = new ReadableStream( + { + start: streamController => { + controller = streamController; + }, + cancel: () => { + // The client went away mid-stream: tear the exchange down, + // which aborts the in-flight handler through the connected + // server's close chain. + void this.close(); + } }, - cancel: () => { - // The client went away mid-stream: tear the exchange down, - // which aborts the in-flight handler through the connected - // server's close chain. - void this.close(); - } - }); + // Sized in bytes from a high-water mark of 0, so `desiredSize` is minus the bytes the client has not read. + new ByteLengthQueuingStrategy({ highWaterMark: 0 }) + ); this._sse = { controller, encoder: new TextEncoder(), closed: false }; this._sse.keepAliveTimer = armSseKeepAlive(this._keepAliveMs, () => this.writeCommentFrame('keepalive')); @@ -457,3 +467,8 @@ export class PerRequestHTTPServerTransport implements Transport { export function perRequestClassificationOf(transport: Transport): MessageClassification | undefined { return transport instanceof PerRequestHTTPServerTransport ? readClassification(transport) : undefined; } + +/** Package-internal: reads how many bytes of a per-request transport's response stream the client has not read (0 while it is not streaming); `undefined` for any other transport. Not public API. */ +export function perRequestBacklogOf(transport: Transport | undefined): (() => number) | undefined { + return transport instanceof PerRequestHTTPServerTransport ? () => readBacklog(transport) : undefined; +} diff --git a/packages/server/test/ext/events/node.test.ts b/packages/server/test/ext/events/node.test.ts index 2805d73fa4..ce8435c9a3 100644 --- a/packages/server/test/ext/events/node.test.ts +++ b/packages/server/test/ext/events/node.test.ts @@ -292,6 +292,60 @@ describe('nodeWebhookSender', () => { expect(await connection.lookup({})).toEqual({ address: '1.1.1.1', family: 4 }); }); + describe('with ADDRCONFIG', () => { + const entry = (family: 'IPv4' | 'IPv6', address: string, internal = false) => + ({ address, family, internal, netmask: '', mac: '', cidr: null }) as os.NetworkInterfaceInfo; + const loopback = { lo0: [entry('IPv4', '127.0.0.1', true), entry('IPv6', '::1', true)] }; + const A = { address: '1.1.1.1', family: 4 }; + const AAAA = { address: '2606:4700:4700::1111', family: 6 }; + + // The pinned lookup of a send to a host with one checked address of each family. + async function dualStackLookup() { + stubResolver(['1.1.1.1', '2606:4700:4700::1111']); + const connection = captureConnection(); + await nodeWebhookSender()(sendRequest('https://dual.example.test/x', false)); + return (options: dns.LookupOptions = {}) => connection.lookup({ all: true, hints: dns.ADDRCONFIG, ...options }); + } + + it('answers only the families the host has an address of that is neither internal nor link-local, or all when none is', async () => { + const interfaces = vi.spyOn(os, 'networkInterfaces'); + const lookup = await dualStackLookup(); + + interfaces.mockReturnValue({ ...loopback, en0: [entry('IPv4', '192.168.1.2')] }); + expect(await lookup()).toEqual([A]); + expect(await lookup({ hints: 0 })).toEqual([A, AAAA]); + // Linux gives every interface an fe80:: address, routed or not. + interfaces.mockReturnValue({ ...loopback, eth0: [entry('IPv4', '192.168.1.2'), entry('IPv6', 'fe80::1')] }); + expect(await lookup()).toEqual([A]); + interfaces.mockReturnValue({ ...loopback, eth0: [entry('IPv4', '192.168.1.2'), entry('IPv6', '2001:db8::2')] }); + expect(await lookup()).toEqual([A, AAAA]); + interfaces.mockReturnValue(loopback); + expect(await lookup()).toEqual([A, AAAA]); + interfaces.mockReturnValue({ ...loopback, eth0: [entry('IPv6', '2001:db8::2')] }); + expect(await lookup({ family: 4 })).toEqual([A]); + }); + + it('does not count an IPv4 link-local address', async () => { + const interfaces = vi.spyOn(os, 'networkInterfaces'); + const lookup = await dualStackLookup(); + + interfaces.mockReturnValue({ ...loopback, eth0: [entry('IPv4', '169.254.10.20'), entry('IPv6', '2001:db8::2')] }); + expect(await lookup()).toEqual([AAAA]); + interfaces.mockReturnValue({ ...loopback, eth0: [entry('IPv4', '169.254.10.20'), entry('IPv6', 'fe80::1')] }); + expect(await lookup()).toEqual([A, AAAA]); + }); + + it('answers every checked address when the interfaces cannot be read', async () => { + vi.spyOn(os, 'networkInterfaces').mockImplementation(() => { + throw Object.assign(new Error('uv_interface_addresses returned Unknown system error 1'), { code: 'ERR_SYSTEM_ERROR' }); + }); + const lookup = await dualStackLookup(); + + expect(await lookup()).toEqual([A, AAAA]); + expect(await lookup({ all: false, family: 6 })).toEqual(AAAA); + }); + }); + it('fails the lookup for a family with no checked address', async () => { stubResolver(['1.1.1.1']); const connection = captureConnection(); @@ -302,6 +356,13 @@ describe('nodeWebhookSender', () => { }); it.skipIf(!hasIpv6Loopback)('connects to the AAAA address when the A address does not answer', async () => { + // A dual-stack host, so ADDRCONFIG keeps both families. + vi.spyOn(os, 'networkInterfaces').mockReturnValue({ + en0: [ + { address: '192.168.1.2', family: 'IPv4', internal: false, netmask: '', mac: '', cidr: null }, + { address: '2001:db8::2', family: 'IPv6', internal: false, netmask: '', mac: '', cidr: null, scopeid: 0 } + ] + }); const receiver = await countingServer('::1'); await treatAsPublic('192.0.2.1', '::1'); stubResolver(['192.0.2.1', '::1']); diff --git a/packages/server/test/ext/events/push.test.ts b/packages/server/test/ext/events/push.test.ts index 6a695723a2..8ff037adc7 100644 --- a/packages/server/test/ext/events/push.test.ts +++ b/packages/server/test/ext/events/push.test.ts @@ -194,7 +194,7 @@ describe('events/stream: a check type', () => { ]); }); - it('replays from a cursor first, then reports a gap mid-stream with a fresh active', async () => { + it('replays from a cursor first, then reports a gap mid-stream with another active', async () => { vi.useFakeTimers({ shouldAdvanceTime: true }); const check = vi .fn() @@ -223,13 +223,43 @@ describe('events/stream: a check type', () => { expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'b', data: { n: 2 }, cursor: 'h3' } }); const gap = next(stream); await vi.advanceTimersByTimeAsync(5000); - // A truncated batch carries the fresh cursor on its active and on every event, so the cursor never moves back. - expect(await gap).toEqual(notification(ACTIVE, stream.id, { cursor: 'h9', truncated: true, heartbeatMs: 30_000 })); - expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'c', cursor: 'h9' } }); + // A truncated batch's cursors stay at its start too, on its active and its events until the last. + expect(await gap).toEqual(notification(ACTIVE, stream.id, { cursor: 'h3', truncated: true, heartbeatMs: 30_000 })); + expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'c', cursor: 'h3' } }); expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'd', cursor: 'h9' } }); expect(check.mock.calls.map(call => call[2])).toEqual(['h1', 'h3']); }); + it('resumes a truncated batch dropped after its first event from that event, and delivers the rest', async () => { + const batch = { + events: [ + { eventId: 'a', data: { n: 1 } }, + { eventId: 'b', data: { n: 2 } }, + { eventId: 'c', data: { n: 3 } } + ], + cursor: 'h9', + truncated: true + }; + const check = vi.fn((_ctx, _args, cursor) => (cursor === 'h1' ? batch : { events: [], cursor: 'h9' })); + const events = new EventsExtension(); + events.registerEvent('tick', { payloadSchema: P, check }); + const served = serve(events); + const first = await open(served, { name: 'tick', cursor: 'h1' }); + expect(await next(first)).toMatchObject({ method: ACTIVE, params: { cursor: 'h1', truncated: true } }); + const dropped = paramsOf(await next(first)); + expect(dropped).toMatchObject({ eventId: 'a', cursor: 'h1' }); + first.abort(); + + const resumed = await open(served, { name: 'tick', cursor: dropped['cursor'] }); + expect(await next(resumed)).toMatchObject({ method: ACTIVE, params: { cursor: 'h1', truncated: true } }); + const frames = [paramsOf(await next(resumed)), paramsOf(await next(resumed)), paramsOf(await next(resumed))]; + expect(frames.map(params => [params['eventId'], params['cursor']])).toEqual([ + ['a', 'h1'], + ['b', 'h1'], + ['c', 'h9'] + ]); + }); + it('confirms a cursor: null result with truncated: false, and sends no fresh active for its gaps (SEP-3415 §Cursor Lifecycle)', async () => { vi.useFakeTimers({ shouldAdvanceTime: true }); const check = vi.fn(() => ({ events: [], cursor: null, truncated: true })); @@ -257,8 +287,8 @@ describe('events/stream: a check type', () => { const events = new EventsExtension(); events.registerEvent('tick', { payloadSchema: P, check }); const stream = await open(serve(events), { name: 'tick', cursor: 'h1', maxAgeMs: 300_000 }); - expect(await next(stream)).toMatchObject({ method: ACTIVE, params: { cursor: 'h2', truncated: true } }); - expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'new', cursor: 'h2' } }); + expect(await next(stream)).toMatchObject({ method: ACTIVE, params: { cursor: 'h1', truncated: true } }); + expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'new', cursor: 'h1' } }); expect(await next(stream)).toMatchObject({ method: EVENT, params: { eventId: 'newer', cursor: 'h2' } }); expect(check.mock.calls[0]![0]).toMatchObject({ mode: 'push', maxAgeMs: 300_000 }); }); @@ -620,6 +650,33 @@ describe('events/stream: termination', () => { }); }); +describe('events/stream: a client that stops reading', () => { + it('ends a stream whose client leaves more than 1 MiB unread, and keeps one whose client reads', async () => { + const events = new EventsExtension(); + const handle = events.registerEvent('big', { emitOnly: true, payloadSchema: z.object({ s: z.string() }) }); + const served = serve(events); + const stalled = await open(served, { name: 'big', cursor: null }); + const reading = await open(served, { name: 'big', cursor: null }); + expect(await next(stalled)).toMatchObject({ method: ACTIVE }); + expect(await next(reading)).toMatchObject({ method: ACTIVE }); + + // 20 events of 100 kB: the stalled client reads none of them. + const read: unknown[] = []; + for (let n = 0; n < 20; n++) { + await handle.emit({ eventId: `e${n}`, data: { s: 'x'.repeat(100_000) } }); + read.push(paramsOf(await next(reading))['eventId']); + } + expect(read).toHaveLength(20); + expect(testHook(events).state().pushStreams).toBe(1); + + const left = await rest(stalled); + expect(left.at(-1)).toEqual(finalResult(stalled.id)); + const unread = left.filter(frame => 'method' in frame && frame.method === EVENT); + expect(unread.length).toBeGreaterThan(9); + expect(unread.length).toBeLessThan(15); + }); +}); + describe('events/stream: response modes', () => { it("streams under responseMode: 'json' (Decision 11)", async () => { const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}); diff --git a/packages/server/test/ext/events/webhookEngine.test.ts b/packages/server/test/ext/events/webhookEngine.test.ts index 4348a67b15..3533c867f7 100644 --- a/packages/server/test/ext/events/webhookEngine.test.ts +++ b/packages/server/test/ext/events/webhookEngine.test.ts @@ -115,12 +115,13 @@ function bodyOf(request: WebhookSendRequest): Record { return JSON.parse(request.body) as Record; } -// A responder that holds each event POST until the test answers it, counting the POSTs in flight at most; `fail` answers a POST with 503 at once. +// A responder that holds each event POST until the test answers it, counting the POSTs in flight at most; `fail` answers a POST with 503 at once, and a control body gets 200 at once. function held(fail: (request: WebhookSendRequest) => boolean = () => false) { const answers: Array<() => void> = []; let inFlight = 0; let most = 0; const respond: Respond = request => { + if ('type' in bodyOf(request)) return { status: 200, body: '' }; inFlight += 1; most = Math.max(most, inFlight); if (fail(request)) { @@ -459,6 +460,86 @@ describe('event delivery', () => { expect(vi.getTimerCount()).toBe(0); }); + it('tells the subscriber of an abandoned event with one gap envelope at the watermark, after the next acknowledged delivery', async () => { + let healthy = false; + const { engine, record, requests, until } = setup(() => (healthy ? { status: 200, body: '' } : { status: 503, body: '' })); + const gaps = () => requests.map(request => bodyOf(request)).filter(body => body.type === 'gap'); + engine.track(ID, 'p0'); + engine.deliver(record, occurrence('evt_1'), 'p1', null); + await until(1); + for (const [index, delay] of DELAYS.entries()) { + await settle(); + await vi.advanceTimersByTimeAsync(delay); + await until(index + 2); + } + await settle(); + expect(engine.watermark(ID)).toBe('p1'); + expect(gaps()).toEqual([]); + + healthy = true; + engine.deliver(record, occurrence('evt_2'), 'p2', null); + await until(7); + await settle(); + expect(gaps()).toEqual([{ type: 'gap', cursor: 'p2' }]); + expect(requests[6]!.headers['webhook-id']).toMatch(/^msg_gap_[\w-]+$/); + engine.deliver(record, occurrence('evt_3'), 'p3', null); + await until(8); + await settle(); + expect(gaps()).toHaveLength(1); + }); + + it.each([ + ['a 413', 413, true], + ['a 410', 410, false] + ])('marks a gap for an event lost to %s answer, and for a body it does not send', async (_case, status, gap) => { + const answers: WebhookSendOutcome[] = [{ status, body: '' }]; + const { engine, record, requests, until } = setup(() => answers.shift() ?? { status: 200, body: '' }); + const gaps = () => requests.map(request => bodyOf(request)).filter(body => body.type === 'gap'); + engine.track(ID, 'p0'); + engine.deliver(record, occurrence('evt_1'), 'p1', null); + await until(1); + await settle(); + engine.deliver(record, occurrence('evt_2'), 'p2', null); + await until(gap ? 3 : 2); + await settle(); + expect(gaps()).toEqual(gap ? [{ type: 'gap', cursor: 'p2' }] : []); + + engine.deliver(record, occurrence('evt_3', { blob: 'x'.repeat(262_144) }), 'p3', null); + await settle(); + engine.deliver(record, occurrence('evt_4'), 'p4', null); + await until(gap ? 5 : 4); + await settle(); + expect(gaps().at(-1)).toEqual({ type: 'gap', cursor: 'p4' }); + }); + + it('answers a refresh with the mark instead, so no envelope follows; a type without replay gets neither', async () => { + const answers: WebhookSendOutcome[] = [{ status: 413, body: '' }]; + const { engine, record, requests, until } = setup(() => answers.shift() ?? { status: 200, body: '' }); + engine.track(ID, 'p0'); + engine.deliver(record, occurrence('evt_1'), 'p1', null); + await until(1); + await settle(); + expect(engine.takeGap(ID)).toBe(true); + expect(engine.takeGap(ID)).toBe(false); + engine.deliver(record, occurrence('evt_2'), 'p2', null); + await until(2); + await settle(); + expect(requests.filter(request => bodyOf(request).type === 'gap')).toEqual([]); + + engine.track(ID, null); + answers.push({ status: 413, body: '' }); + engine.deliver(record, occurrence('evt_3'), null, null); + engine.deliver(record, occurrence('evt_4'), null, null); + await until(4); + await settle(); + expect(requests.filter(request => bodyOf(request).type === 'gap')).toEqual([]); + answers.push({ status: 413, body: '' }); + engine.deliver(record, occurrence('evt_5'), null, null); + await until(5); + await settle(); + expect(engine.takeGap(ID)).toBe(false); + }); + it.each([410, 413])('treats %i as final for the message', async status => { const { engine, store, record, requests, until } = setup(() => ({ status, body: '' })); const put = vi.spyOn(store, 'put'); @@ -635,13 +716,18 @@ describe('event delivery', () => { ]); await until(10); + // The first answer also sends the subscriber a gap for the abandoned events. for (let n = 0; n < 10; n++) { hold.answers[n]!(); - await until(11 + n); + await until(12 + n); } await settle(); // The oldest message kept starts next, and the abandoned ones no longer hold the watermark back. - expect(requests.slice(10).map(request => bodyOf(request).eventId)).toEqual(Array.from({ length: 10 }, (_, n) => `evt_${17 + n}`)); + const sent = requests.slice(10).map(request => bodyOf(request)); + expect(sent.filter(body => 'eventId' in body).map(body => body.eventId)).toEqual( + Array.from({ length: 10 }, (_, n) => `evt_${17 + n}`) + ); + expect(sent.filter(body => body.type === 'gap')).toHaveLength(1); expect(engine.watermark(ID)).toBe('p16'); expect(hold.most()).toBe(10); }); @@ -867,9 +953,11 @@ describe('delivery status', () => { healthy = true; engine.resume(ID); - await until(100 + 10_000); + // And one gap envelope after the first acknowledged delivery. + await until(100 + 10_000 + 1); await settle(); - expect(requests).toHaveLength(100 + 10_000); + expect(requests).toHaveLength(100 + 10_000 + 1); + expect(requests.filter(request => bodyOf(request).type === 'gap')).toHaveLength(1); expect(requests.some(request => bodyOf(request).eventId === 'evt_21')).toBe(false); expect(engine.watermark(ID)).toBe('p10021'); await vi.advanceTimersByTimeAsync(60_000); @@ -1110,6 +1198,32 @@ describe('forget and clear', () => { expect(requests).toHaveLength(12); }); + it('reads the record of an unwatched subscription again at its expiry, drops its state once it is gone, and clears that timer on every drop', async () => { + const { engine, store, record, until } = setup(); + engine.deliver(record, occurrence('evt_1'), 'p1', 'p0'); + await until(1); + await settle(); + expect(vi.getTimerCount()).toBe(1); + + await store.put({ ...record, expiresAt: record.expiresAt + 3_600_000 }); + await vi.advanceTimersByTimeAsync(3_600_000); + expect(engine.size).toBe(1); + expect(vi.getTimerCount()).toBe(1); + store.records.delete(ID); + await vi.advanceTimersByTimeAsync(3_600_000); + expect(engine.size).toBe(0); + expect(vi.getTimerCount()).toBe(0); + + for (const drop of ['forget', 'clear'] as const) { + engine.deliver(recordFor(), occurrence('evt_2'), 'p2', 'p1'); + await settle(); + expect(vi.getTimerCount()).toBe(1); + if (drop === 'forget') engine.forget(ID); + else engine.clear(); + expect(vi.getTimerCount()).toBe(0); + } + }); + it('track() starts the watermark again for a subscription it already tracks', async () => { const { engine, record, until } = setup(); engine.deliver(record, occurrence('evt_1'), 'p1', 'p0'); diff --git a/packages/server/test/ext/events/webhookSubscriptions.test.ts b/packages/server/test/ext/events/webhookSubscriptions.test.ts index 7ff76d5ab2..58f3e48160 100644 --- a/packages/server/test/ext/events/webhookSubscriptions.test.ts +++ b/packages/server/test/ext/events/webhookSubscriptions.test.ts @@ -775,6 +775,38 @@ describe('events/subscribe: refreshing', () => { expect(elsewhere).not.toHaveProperty('deliveryStatus'); }); + it('answers the refresh after an abandoned event with truncated: true, once, and then sends no gap envelope for it', async () => { + let healthy = false; + const { events, post } = replica({ respond: echo(() => (healthy ? { status: 200, body: '' } : { status: 503, body: '' })) }); + const handle = events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const alice = client(events); + subscribed(await alice.subscribe()); + await handle.emit({ eventId: 'lost', data: { n: 1 } }); + await post.until(2); + for (const [index, delay] of [5000, 30_000, 120_000, 300_000].entries()) { + await settle(); + await vi.advanceTimersByTimeAsync(delay); + await post.until(index + 3); + } + await settle(); + + const refreshed = subscribed(await alice.subscribe()); + expect(refreshed).toMatchObject({ truncated: true, cursor: expect.any(String) }); + healthy = true; + await handle.emit({ eventId: 'kept', data: { n: 2 } }); + await post.until(7); + await settle(); + expect(post.deliveries().map(request => bodyOf(request).eventId ?? bodyOf(request).type)).toEqual([ + 'lost', + 'lost', + 'lost', + 'lost', + 'lost', + 'kept' + ]); + expect(subscribed(await alice.subscribe())).toMatchObject({ truncated: false }); + }); + it('reports a suspension on the refresh that ends it', async () => { const { events, post } = replica({ respond: echo(() => ({ status: 503, body: '' })) }); const handle = events.registerEvent('e', { emitOnly: true, payloadSchema: P }); @@ -933,6 +965,84 @@ describe('several replicas sharing one store', () => { expect(onA).not.toHaveBeenCalled(); }); + it('drops what a replica that only delivers holds for a subscription at its expiry once it ended elsewhere', async () => { + const store = new InMemoryWebhookSubscriptionStore(); + const a = replica({ webhookStore: store }); + const b = replica({ webhookStore: store }); + a.events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const handle = b.events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const alice = client(a.events); + const ids: string[] = []; + for (const k of [1, 2, 3, 4]) ids.push(subscribed(await alice.subscribe({ arguments: { k }, ttlMs: 60_000 })).id); + await handle.emit({ data: { n: 1 } }); + await b.post.until(4); + await settle(); + expect(b.hook.state()).toMatchObject({ webhookSubscriptions: 4, webhookExpiryTimers: 0 }); + + // k: 1 unsubscribed on A, k: 2 dropped by the store, k: 3 created again, k: 4 refreshed. + resultOf(await alice.unsubscribe({ arguments: { k: 1 } })); + await store.delete(ids[1]!); + await vi.advanceTimersByTimeAsync(1000); + resultOf(await alice.unsubscribe({ arguments: { k: 3 } })); + subscribed(await alice.subscribe({ arguments: { k: 3 }, ttlMs: 60_000 })); + await vi.advanceTimersByTimeAsync(29_000); + subscribed(await alice.subscribe({ arguments: { k: 4 }, ttlMs: 60_000 })); + expect(b.hook.state().webhookSubscriptions).toBe(4); + + await vi.advanceTimersByTimeAsync(30_000); + expect(b.hook.state().webhookSubscriptions).toBe(1); + await vi.advanceTimersByTimeAsync(30_000); + expect(b.hook.state().webhookSubscriptions).toBe(0); + expect(b.post.deliveries()).toHaveLength(4); + }); + + it('starts what a replica that only delivers holds again for a subscription created again elsewhere, and keeps it past the old expiry', async () => { + const held: Array<() => void> = []; + let holding = false; + const store = new InMemoryWebhookSubscriptionStore(); + const a = replica({ webhookStore: store }); + const b = replica({ + webhookStore: store, + respond: () => + holding ? new Promise(resolve => held.push(() => resolve({ status: 200, body: '' }))) : { status: 200, body: '' } + }); + a.events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const handle = b.events.registerEvent('e', { emitOnly: true, payloadSchema: P }); + const alice = client(a.events); + subscribed(await alice.subscribe({ ttlMs: 60_000 })); + await handle.emit({ eventId: 'evt_1', data: { n: 1 } }); + await b.post.until(1); + await settle(); + + // Created again on A, with a longer grant; B delivers to the new record and the receiver holds the POST. + await vi.advanceTimersByTimeAsync(1000); + resultOf(await alice.unsubscribe()); + subscribed(await alice.subscribe({ ttlMs: 120_000 })); + holding = true; + await handle.emit({ eventId: 'evt_2', data: { n: 2 } }); + await b.post.until(2); + await settle(); + + // Past the old record's expiry, B still holds the delivery in flight, so the watermark stays behind it. + await vi.advanceTimersByTimeAsync(59_500); + expect(b.hook.state().webhookSubscriptions).toBe(1); + expect(b.post.requests[1]!.signal.aborted).toBe(false); + await handle.emit({ eventId: 'evt_3', data: { n: 3 } }); + await b.post.until(3); + await settle(); + const [first, , third] = b.post.requests.map(request => bodyOf(request)); + expect(third).toMatchObject({ eventId: 'evt_3', cursor: first!.cursor }); + for (const answer of held.splice(0)) answer(); + await settle(); + expect(b.hook.state().webhookSubscriptions).toBe(1); + + // At the new record's expiry it goes. + await vi.advanceTimersByTimeAsync(60_499); + expect(b.hook.state().webhookSubscriptions).toBe(1); + await vi.advanceTimersByTimeAsync(1); + expect(b.hook.state().webhookSubscriptions).toBe(0); + }); + it('expires a record lazily where no timer watches it, running onUnsubscribe once (F3b)', async () => { const store = new InMemoryWebhookSubscriptionStore(); const a = replica({ webhookStore: store }); @@ -1182,6 +1292,60 @@ describe('check-kind webhook subscriptions', () => { expect(gapped).toMatchObject({ cursor: 'c5', truncated: true }); }); + it('sends the gap envelope of a truncated check at the watermark, behind an event still unacknowledged', async () => { + const respond: Respond = request => { + if (isVerification(request)) return echo()(request); + return bodyOf(request).eventId === 'a' ? new Promise(() => {}) : { status: 200, body: '' }; + }; + const check = vi + .fn() + .mockReturnValueOnce({ events: [], cursor: 'c0' }) + .mockReturnValueOnce({ events: [{ eventId: 'a', data: { n: 1 } }], cursor: 'c1' }) + .mockReturnValueOnce({ events: [{ eventId: 'b', data: { n: 2 } }], cursor: 'c9', truncated: true }) + .mockReturnValue({ events: [], cursor: 'c9' }); + const { events, post } = replica({ respond }); + events.registerEvent('t', { payloadSchema: P, check }); + subscribed(await client(events).subscribe({ name: 't' })); + await vi.advanceTimersByTimeAsync(10_000); + await post.until(4); + await settle(); + + expect(post.deliveries().map(request => bodyOf(request))).toContainEqual({ type: 'gap', cursor: 'c0' }); + }); + + it('keeps the watermark behind the unsettled events of a truncated batch', async () => { + let healthy = false; + const respond: Respond = request => { + if (isVerification(request)) return echo()(request); + return healthy || bodyOf(request).eventId === 'a' ? { status: 200, body: '' } : { status: 503, body: '' }; + }; + const check = vi.fn((_ctx, _args, cursor) => { + if (cursor !== 'old') return { events: [], cursor: 'c9' }; + const page = ['a', 'b', 'c'].map((eventId, n) => ({ eventId, data: { n } })); + return { events: page, cursor: 'c9', truncated: true }; + }); + const { events, post } = replica({ checkIntervalMs: 100_000, respond }); + events.registerEvent('t', { payloadSchema: P, check }); + const alice = client(events); + expect(subscribed(await alice.subscribe({ name: 't', cursor: 'old' }))).toMatchObject({ cursor: 'old', truncated: true }); + await post.until(4); + await settle(); + const bodies = post.deliveries().map(request => bodyOf(request)); + expect(bodies.map(body => [body.eventId, body.cursor]).sort()).toEqual([ + ['a', 'old'], + ['b', 'old'], + ['c', 'old'] + ]); + + // `a` is acknowledged; `b` and `c` wait for their retry, so the watermark stays before them. + expect(subscribed(await alice.subscribe({ name: 't' })).cursor).toBe('old'); + healthy = true; + await vi.advanceTimersByTimeAsync(5000); + await post.until(6); + await settle(); + expect(subscribed(await alice.subscribe({ name: 't' })).cursor).toBe('c9'); + }); + it('answers truncated: false and sends no gap envelope for a cursor: null result (SEP-3415 §Cursor Lifecycle)', async () => { const check = vi.fn(() => ({ events: [], cursor: null, truncated: true })); const { events, post } = replica(); diff --git a/test/e2e/scenarios/events.test.ts b/test/e2e/scenarios/events.test.ts index 260c285a22..7cd30974a4 100644 --- a/test/e2e/scenarios/events.test.ts +++ b/test/e2e/scenarios/events.test.ts @@ -1224,8 +1224,7 @@ verifies('typescript:events:store:restart', async ({ transport }: TestArgs) => { await subscription.cancel(); } { - // A check type: the rebuilt server runs its check loop from the client's next refresh. Fake timers bring that refresh - // at ¾ of the 60 s grant, while the grant runs in real time, so a slow run cannot turn the refresh into a create. + // A check type: the rebuilt server runs its check loop from the client's next refresh. const realSetTimeout = globalThis.setTimeout; vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); try {