diff --git a/.changeset/events-extension.md b/.changeset/events-extension.md new file mode 100644 index 0000000000..7cb1a5e726 --- /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 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`, 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 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/.vitepress/nav.ts b/docs/.vitepress/nav.ts index cc85be9685..318052de09 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..0d261122bf --- /dev/null +++ b/docs/clients/events.md @@ -0,0 +1,122 @@ +--- +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 events = new EventsClientExtension(); +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' } }); +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' } +``` + +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. 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). +::: + +## 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. + +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. + +```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`), 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`. + +## Recap + +- `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. +- `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..e821842446 --- /dev/null +++ b/docs/servers/events.md @@ -0,0 +1,225 @@ +--- +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`. 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. + +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). +::: + +## 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. 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. + +## Serve the event types from every server + +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#extensions" +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. 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. + +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 + +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. 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. +::: + +## 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) { + // 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); + 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; + } + } + }; +} + +// `kv` is your SharedKeyValue client for that database, connected at startup. +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, 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. +- 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 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/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/docs/troubleshooting.md b/docs/troubleshooting.md index f17adf26e6..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. +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/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/client-quickstart/tsconfig.json b/examples/client-quickstart/tsconfig.json index e227905f23..44c6809493 100644 --- a/examples/client-quickstart/tsconfig.json +++ b/examples/client-quickstart/tsconfig.json @@ -19,11 +19,17 @@ "@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" ], "@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/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..6a0222853d --- /dev/null +++ b/examples/events/client.ts @@ -0,0 +1,90 @@ +/** + * 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'; + +// 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 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; +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..a21234ebc1 --- /dev/null +++ b/examples/events/server.ts @@ -0,0 +1,107 @@ +/** + * 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' }, { extensions: [events] }); + mcp.registerTool('increment', { description: 'Add one to the counter', inputSchema: z.object({}) }, () => { + count += 1; + return { content: [{ type: 'text', text: String(count) }] }; + }); + 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..346d62bfba --- /dev/null +++ b/examples/guides/clients/events.examples.ts @@ -0,0 +1,180 @@ +/** + * 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(() => 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(); + +// 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 events = new EventsClientExtension(); +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' } }); +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: 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' }); +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..a95506f0a1 --- /dev/null +++ b/examples/guides/servers/events.examples.ts @@ -0,0 +1,305 @@ +/** + * 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 extensions +import { createMcpHandler, McpServer } from '@modelcontextprotocol/server'; + +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. +// --------------------------------------------------------------------------- +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 subscriber = new EventsClientExtension(options); + 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)) }) + ); + 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(() => 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'"); +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) { + // 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); + 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; + } + } + }; +} + +// `kv` is your SharedKeyValue client for that database, connected at startup. +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(() => 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(); +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]) 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/examples/server-quickstart/tsconfig.json b/examples/server-quickstart/tsconfig.json index ad7cceae55..73a0c577b3 100644 --- a/examples/server-quickstart/tsconfig.json +++ b/examples/server-quickstart/tsconfig.json @@ -19,11 +19,17 @@ "@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" ], "@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 75cedeee6c..5b671ede94 100644 --- a/examples/shared/tsconfig.json +++ b/examples/shared/tsconfig.json @@ -19,12 +19,18 @@ "@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" ], "@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 28288e5c6d..16d71de6a9 100644 --- a/examples/tsconfig.json +++ b/examples/tsconfig.json @@ -16,8 +16,11 @@ "@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"], + "@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"], @@ -28,12 +31,16 @@ ], "@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" ], "@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/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/client/client.ts b/packages/client/src/client/client.ts index 0c45041337..19bf11d1e5 100644 --- a/packages/client/src/client/client.ts +++ b/packages/client/src/client/client.ts @@ -463,8 +463,25 @@ 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; + // 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; logger(client: Client): SdkLogger; walkPages( @@ -613,12 +630,22 @@ 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; + // 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; /** Backing store for {@linkcode getDiscoverResult}. Per-connection. */ private _discoverResult?: DiscoverResult; 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.logger = client => client._logger; clientInternals.walkPages = (client, method, fetchPage, items) => client._walkPages(method, fetchPage, items); @@ -653,6 +680,8 @@ 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. @@ -2219,6 +2248,87 @@ 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' }); + } + }; + } + + // Runs the `clientInternals.onClose` listeners from a snapshot; a throwing one goes to `onerror` and the rest still run. + private _runCloseListeners(): void { + const listeners = [...this._closeListeners]; + for (const listener of listeners) { + 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. + 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))); + } + } + } + /** * The subscription auto-opened by `ClientOptions.listChanged` on a modern * connection — the listen filter is the intersection of the configured @@ -2244,6 +2354,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 @@ -2318,6 +2435,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)) { @@ -2358,14 +2485,20 @@ 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(); + this._runCloseListeners(); + } finally { + // Base teardown runs even if a callback above throws, so pending requests and timers are always settled. + super._onclose(); } - super._onclose(); } /** 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..789b9899d9 --- /dev/null +++ b/packages/client/src/ext/events/extension.ts @@ -0,0 +1,304 @@ +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'; + +import type { ClientExtension, ClientExtensionContext } from '../../client/extension'; +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'; +import { WebhookSubscriptions } from './webhook'; + +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, where + * {@linkcode EventsClientExtension.createWebhookHandler} is mounted. Each + * server subscription signs with its own `whsec_` secret, random unless + * `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), unless it would reach + * the end of the grant: the refresh then comes at ¾ of it. 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. Pass it in one client's + * `extensions` option. + * + * @example + * ```ts + * const events = new EventsClientExtension(); + * 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) { + * console.log(event.data); + * } + * ``` + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export class EventsClientExtension implements ClientExtension { + /** The extension identifier the client declares. */ + 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. */ + 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; + this.#webhooks = options.webhook === undefined ? undefined : new WebhookSubscriptions(options.webhook, this.#receiver, floorMs); + } + + /** + * 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} when another client already holds this instance, which fails the new client's constructor. + */ + 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. */ + 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; 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, 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. + * + * 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 + * (`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`, 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, `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. + */ + 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 = this.#select(options, descriptor); + try { + return await this.#subscribeIn(mode, descriptor, options, connection); + } catch (error) { + 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); + } + } + + /** + * 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 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 + * id it does not route (yet), which the server retries. + */ + createWebhookHandler(): (request: Request) => Promise { + const receiver = this.#receiver; + 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, + 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, fallback); + // Webhook is selected only with the `webhook` option set. + return this.#webhooks!.driver(context); + } + + #require(method: string): EventsConnection { + const connection = this.#connection; + 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, + `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..ffac652f19 --- /dev/null +++ b/packages/client/src/ext/events/poll.ts @@ -0,0 +1,73 @@ +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'; + +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; + #nextPollMs: number | undefined; + + constructor(context: DriverContext, floorMs: number) { + this.#context = context; + this.#loop = new DriverLoop(context, 'poll'); + this.#floorMs = floorMs; + } + + start(): Promise { + return this.#loop.start(() => this.#run()); + } + + stop(): Promise { + return this.#loop.stop(); + } + + // Polls until stopped; throws, ending the subscription, when a failure calls for it. + async #run(): Promise { + const loop = this.#loop; + let failures = 0; + while (!loop.ended) { + let result: PollEventsResult; + try { + result = await this.#poll(); + } catch (error) { + 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); + 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: 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 cursor = result.cursor ?? null; + this.#nextPollMs = result.nextPollMs; + 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. + #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)); + } +} diff --git a/packages/client/src/ext/events/push.ts b/packages/client/src/ext/events/push.ts new file mode 100644 index 0000000000..ea59148d7b --- /dev/null +++ b/packages/client/src/ext/events/push.ts @@ -0,0 +1,240 @@ +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 { 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 { connectionClosed, DriverLoop, endsSubscription, isHeaderMismatch, jitteredDelay, MAX_TIMER_DELAY_MS } from './recovery'; +import { asEventsError } from './request'; +import type { Driver, DriverContext } 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; + +// 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; +} + +// 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) } : {}; +} + +// 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; + 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`. + #mismatched = 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; + // 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, fallback = false) { + this.#context = context; + this.#loop = new DriverLoop(context, 'push'); + this.#fallback = fallback; + } + + start(): Promise { + return this.#loop.start(() => this.#run(), { interrupt: () => 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 { + const loop = this.#loop; + while (!loop.ended) { + const { error } = await this.#open(); + if (loop.ended) return; + if (error === undefined) loop.subscribed(); + else await this.#recover(error); + 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 { + // 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 this.#context.connection.list(undefined, { signal: this.#loop.signal }).catch(() => {}); + return; + } + const { connection, subscription } = this.#context; + 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); + } + + // 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: loop.cursor, + ...(loop.maxAgeMs !== undefined && { maxAgeMs: loop.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; + // 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, + { 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.#fault(end, new SdkError(SdkErrorCode.InvalidResult, `Invalid ${EVENTS_ACTIVE_NOTIFICATION} params`)); + return; + } + 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.#loop.setCursor(params.cursor ?? null); + break; + } + case EVENTS_HEARTBEAT_NOTIFICATION: { + const params = this.#parse(EventsHeartbeatNotificationParamsSchema, notification); + if (params !== undefined) this.#loop.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 cursor = params.cursor ?? null; + this.#grantMs = params.heartbeatMs; + this.#attempt = 0; + this.#mismatched = false; + 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. + #alive(end: (ending: Ending) => void): void { + if (this.#grantMs === undefined || this.#end !== end) return; + clearTimeout(this.#dead); + 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. + #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; + } +} diff --git a/packages/client/src/ext/events/receiver.ts b/packages/client/src/ext/events/receiver.ts new file mode 100644 index 0000000000..3bf3f1b6fe --- /dev/null +++ b/packages/client/src/ext/events/receiver.ts @@ -0,0 +1,167 @@ +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); + } + + // 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 }); + } + + // 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 { + 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..2482b93c2f --- /dev/null +++ b/packages/client/src/ext/events/recovery.ts @@ -0,0 +1,363 @@ +import type { DeliveryMode } from '@modelcontextprotocol/core/ext/events'; +import { HEADER_MISMATCH_ERROR_CODE, ProtocolError, ProtocolErrorCode } from '@modelcontextprotocol/core-internal'; +import { EventsError } from '@modelcontextprotocol/core-internal/ext/events'; +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'; + +// 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; +// 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, 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); +} + +// 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). +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' + ); +} + +// 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 { + 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, unless with an endsSubscription() error, which it throws. +export async function stillOffered( + connection: EventsConnection, + name: string, + mode: DeliveryMode, + signal: AbortSignal +): Promise { + try { + await connection.list(undefined, { signal }); + } catch (error) { + if (endsSubscription(error)) throw error; + 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(); + // 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; + 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; + } + + // 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; + } + + // 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(); + clearTimeout(this.#report); + 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) { + 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(); + this.#retrying(listError); + return 'retry'; + } + this.#restartFromNow(); + return 'restarted'; + } + if (refusesSubscription(error)) throw error; + this.subscribed(); + this.#retrying(error); + return 'retry'; + } + const recovery = recoveryFor(error); + 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); + 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; + } + + // 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/request.ts b/packages/client/src/ext/events/request.ts new file mode 100644 index 0000000000..814af26d52 --- /dev/null +++ b/packages/client/src/ext/events/request.ts @@ -0,0 +1,127 @@ +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, 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 './recovery'; + +// 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. +export 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(); + readonly #closeListeners = new Set<() => void>(); + + constructor(client: Client) { + this.client = client; + clientInternals.onClose(client, () => { + // 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) { + this.report(error); + } + } + }); + } + + // 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; + } + + // 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) { + if (mirror === undefined || !isHeaderMismatch(error)) 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..bf3a49b6b7 --- /dev/null +++ b/packages/client/src/ext/events/subscription.ts @@ -0,0 +1,245 @@ +import type { DeliveryMode, DeliveryStatus, EventOccurrence } from '@modelcontextprotocol/core/ext/events'; + +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) 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; + /** Replays no event older than this many milliseconds, however old `cursor` is. */ + maxAgeMs?: number; + /** + * 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, 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 (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 + * 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` + * 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. + * - 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` + * (`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. + * + * 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 in an `events/subscribe` result. */ + readonly deliveryStatus?: DeliveryStatus; + /** + * Stops delivery and ends the loop. Cancelling the last of identical + * webhook subscriptions also removes the subscription on the server + * (`events/unsubscribe`). + */ + 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 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: DeliveryQueue; + readonly connection: EventsConnection; +} + +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 }; + +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/src/ext/events/webhook.ts b/packages/client/src/ext/events/webhook.ts new file mode 100644 index 0000000000..7e250ad4d9 --- /dev/null +++ b/packages/client/src/ext/events/webhook.ts @@ -0,0 +1,312 @@ +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, retryAfterOf } 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; + +export 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(); + // 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; + 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 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; + } + 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; + // 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, + 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 = { + 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.#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. + 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; + const stopping = this.#driver.stop(); + // Settles however the unsubscribe ends (answered, refused, failed, or the client closed). + this.#close(stopping.catch(() => {})); + await stopping; + } + }; + } +} + +// 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 { + // 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: () => { + 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(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. + 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. + await loop.sleep(expiresAt === undefined ? MAX_TIMER_DELAY_MS : this.#refreshDelay(expiresAt - Date.now())); + } + if (this.#terminated !== undefined) { + this.#live = false; + return this.#terminated; + } + } + 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; + 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.#sink); + this.#id = undefined; + } +} 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/client/openStream.test.ts b/packages/client/test/client/openStream.test.ts new file mode 100644 index 0000000000..00b8b428e3 --- /dev/null +++ b/packages/client/test/client/openStream.test.ts @@ -0,0 +1,382 @@ +/** + * `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; 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 { + 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('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'); + 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([]); + }); +}); + +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('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[] = []; + 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/extension.test.ts b/packages/client/test/ext/events/extension.test.ts new file mode 100644 index 0000000000..fddb52d047 --- /dev/null +++ b/packages/client/test/ext/events/extension.test.ts @@ -0,0 +1,203 @@ +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 } 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('serves one client, and refuses calls before a client is constructed with it', async () => { + const events = new EventsClientExtension(); + 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', () => { + 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('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' })); + 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..dda5ab6cb9 --- /dev/null +++ b/packages/client/test/ext/events/poll.test.ts @@ -0,0 +1,638 @@ +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 { authFailure, callsTo, connectEvents, descriptor, failSends, 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<{ + client: Client; + calls: Call[]; + notifications: Notification[]; + reconnect: () => Promise; + polls: () => Call[]; + subscribe: (options?: Partial) => Promise; +}> { + 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 }); + 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 onGap = vi.fn(); + 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({ 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); + 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('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( + 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('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( + 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: '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) { + 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); + // 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); + } + }); + + 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('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(); + 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('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_); + 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('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[]) => { + 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(); + 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/push.test.ts b/packages/client/test/ext/events/push.test.ts new file mode 100644 index 0000000000..b3cc9a8471 --- /dev/null +++ b/packages/client/test/ext/events/push.test.ts @@ -0,0 +1,786 @@ +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 { 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 { authFailure, callsTo, connectEvents, descriptor, failSends, listing, occurrence, RpcError, script } 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('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' })); + 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('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(); + 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); + // A refused delivery mode lists the event types again, which still select it. + expect(lists()).toHaveLength(refusal.data?.feature === 'deliveryMode' ? 2 : 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('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); + }); + + 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('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_); + 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.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_); + + 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[] = []; + 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 })); + 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/receiver.test.ts b/packages/client/test/ext/events/receiver.test.ts new file mode 100644 index 0000000000..7a9b74225d --- /dev/null +++ b/packages/client/test/ext/events/receiver.test.ts @@ -0,0 +1,194 @@ +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', 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' })); + 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/recovery.test.ts b/packages/client/test/ext/events/recovery.test.ts new file mode 100644 index 0000000000..221bcd780f --- /dev/null +++ b/packages/client/test/ext/events/recovery.test.ts @@ -0,0 +1,72 @@ +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([ + ['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' })], + [ + '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')], + ['-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); + 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); + }); +}); diff --git a/packages/client/test/ext/events/scripted.ts b/packages/client/test/ext/events/scripted.ts new file mode 100644 index 0000000000..828b94c1f4 --- /dev/null +++ b/packages/client/test/ext/events/scripted.ts @@ -0,0 +1,239 @@ +import type { EventDescriptor, EventOccurrence } 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 { 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'; +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; +} + +/** 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 { + const { capabilities = EVENTS_CAPABILITIES, revision = MODERN } = options; + const calls: Call[] = []; + const notifications: Notification[] = []; + const headersById = new Map>(); + 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); + }; + 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 }) + } + }) + ) + // An answer that comes after the client closed has no one to go to. + .catch(() => {}); + }; + await server.start(); + return transport; + }; + const client = new Client( + { name: 'events-test-client', version: '1.0.0' }, + revision === MODERN ? { versionNegotiation: { mode: { pin: MODERN } }, ...options.clientOptions } : options.clientOptions + ); + await client.connect(await link()); + return { + client, + calls, + notifications, + send: message => serverTx!.send(message), + reconnect: async () => client.connect(await link()) + }; +} + +/** 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, clientOptions: { ...options.clientOptions, extensions: [events] } }); + 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); + +/** + * 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 { + 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..f2a67f59c0 --- /dev/null +++ b/packages/client/test/ext/events/webhook.test.ts @@ -0,0 +1,812 @@ +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 { 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 { + authFailure, + callsTo, + connectEvents, + descriptor, + failSends, + 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; 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 }) }, + ...(pollIntervalFloorMs !== undefined && { pollIntervalFloorMs }) + } + } + ); + 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; + } + }; +} + +/** 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' })); + 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('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(); + + 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('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, {})); + 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('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(); + 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('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({}, {})); + 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); + // A refused delivery mode lists the event types again, which still select it. + expect(lists()).toHaveLength(refusal.data?.['feature'] === 'deliveryMode' ? 2 : 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("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( + 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([]); + }); +}); diff --git a/packages/client/tsconfig.json b/packages/client/tsconfig.json index 4fb474f8fb..84fc56fc35 100644 --- a/packages/client/tsconfig.json +++ b/packages/client/tsconfig.json @@ -8,12 +8,16 @@ "@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" ], "@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/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/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/packageTopologyPins.test.ts b/packages/core-internal/test/packageTopologyPins.test.ts index 5bc882e8e3..35196ee426 100644 --- a/packages/core-internal/test/packageTopologyPins.test.ts +++ b/packages/core-internal/test/packageTopologyPins.test.ts @@ -38,14 +38,27 @@ const PUBLIC_PACKAGES: Record { + 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/core-internal/tsconfig.json b/packages/core-internal/tsconfig.json index d46f187ffb..98058290e8 100644 --- a/packages/core-internal/tsconfig.json +++ b/packages/core-internal/tsconfig.json @@ -8,7 +8,8 @@ "@modelcontextprotocol/eslint-config": ["./node_modules/@modelcontextprotocol/eslint-config/tsconfig.json"], "@modelcontextprotocol/vitest-config": ["./node_modules/@modelcontextprotocol/vitest-config/tsconfig.json"], "@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/skills": ["./node_modules/@modelcontextprotocol/core/src/ext/skills/index.ts"], + "@modelcontextprotocol/core/ext/events": ["./node_modules/@modelcontextprotocol/core/src/ext/events/index.ts"] } } } diff --git a/packages/core/package.json b/packages/core/package.json index fbcf2818d9..a0861ab104 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -50,6 +50,16 @@ "types": "./dist/ext/skills/index.d.cts", "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" + } } }, "typesVersions": { @@ -59,6 +69,9 @@ ], "ext/skills": [ "dist/ext/skills/index.d.mts" + ], + "ext/events": [ + "dist/ext/events/index.d.mts" ] } }, diff --git a/packages/core/src/ext/events/capability.ts b/packages/core/src/ext/events/capability.ts new file mode 100644 index 0000000000..1b4861d39c --- /dev/null +++ b/packages/core/src/ext/events/capability.ts @@ -0,0 +1,22 @@ +import type { CapabilitiesWithExtensions } from '../skills/capability'; +import { EVENTS_EXTENSION_ID } from './constants'; +import { EventsCapabilitySchema } from './schemas'; +import type { EventsCapability } from './types'; + +/** + * Reads the Events extension capability out of a peer's advertised + * capabilities, returning `undefined` when the peer does not advertise the + * extension or advertises a malformed value. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export function eventsCapabilityOf(capabilities: CapabilitiesWithExtensions | undefined): EventsCapability | undefined { + const declared = capabilities?.extensions?.[EVENTS_EXTENSION_ID]; + if (declared === undefined) { + return undefined; + } + const parsed = EventsCapabilitySchema.safeParse(declared); + return parsed.success ? parsed.data : undefined; +} diff --git a/packages/core/src/ext/events/constants.ts b/packages/core/src/ext/events/constants.ts new file mode 100644 index 0000000000..7c5cf6b4e6 --- /dev/null +++ b/packages/core/src/ext/events/constants.ts @@ -0,0 +1,138 @@ +/** + * Wire constants for the MCP Events extension (SEP-3415). + * + * Runtime-neutral: this module imports nothing. + */ + +/** + * The identifier a server advertises in `ServerCapabilities.extensions`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EVENTS_EXTENSION_ID = 'io.modelcontextprotocol/events'; + +/** + * Lists the event types a server offers. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EVENTS_LIST_METHOD = 'events/list'; + +/** + * Fetches the events of one subscription since a cursor (poll delivery). + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EVENTS_POLL_METHOD = 'events/poll'; + +/** + * Opens a long-lived stream for one subscription (push delivery). + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EVENTS_STREAM_METHOD = 'events/stream'; + +/** + * Creates or refreshes a webhook subscription (webhook delivery). + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EVENTS_SUBSCRIBE_METHOD = 'events/subscribe'; + +/** + * Removes a webhook subscription. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EVENTS_UNSUBSCRIBE_METHOD = 'events/unsubscribe'; + +/** + * Confirms a push stream, carrying the granted heartbeat interval; sent again mid-stream after a gap. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EVENTS_ACTIVE_NOTIFICATION = 'notifications/events/active'; + +/** + * Delivers one event occurrence on a push stream. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EVENTS_EVENT_NOTIFICATION = 'notifications/events/event'; + +/** + * Keeps a push stream alive and advances its cursor while no events match. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EVENTS_HEARTBEAT_NOTIFICATION = 'notifications/events/heartbeat'; + +/** + * Reports a recoverable failure on a push stream, which stays open. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EVENTS_ERROR_NOTIFICATION = 'notifications/events/error'; + +/** + * Ends a push subscription from the server side. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EVENTS_TERMINATED_NOTIFICATION = 'notifications/events/terminated'; + +/** + * The header carrying the subscription `id` on every webhook POST. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const WEBHOOK_SUBSCRIPTION_ID_HEADER = 'X-MCP-Subscription-Id'; + +/** + * The delivery modes an event type can advertise. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const DELIVERY_MODES = ['poll', 'push', 'webhook'] as const; + +/** + * The categories a server reports as `deliveryStatus.lastError`, and as `data.reason` of a callback endpoint error. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const DELIVERY_ERROR_CATEGORIES = [ + 'connection_refused', + 'timeout', + 'tls_error', + 'http_4xx', + 'http_5xx', + 'challenge_failed' +] as const; diff --git a/packages/core/src/ext/events/index.ts b/packages/core/src/ext/events/index.ts new file mode 100644 index 0000000000..685a4767ff --- /dev/null +++ b/packages/core/src/ext/events/index.ts @@ -0,0 +1,82 @@ +// @modelcontextprotocol/core/ext/events +// +// Shared surface of the MCP Events extension (SEP-3415): wire constants, Zod +// schemas, the types inferred from them, and the capability reader. + +export { eventsCapabilityOf } from './capability'; +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 './constants'; +export { + DeliveryErrorCategorySchema, + DeliveryModeSchema, + DeliveryStatusSchema, + EventDescriptorSchema, + EventNotificationParamsSchema, + EventOccurrenceSchema, + EventsActiveNotificationParamsSchema, + EventsCapabilitySchema, + EventsErrorNotificationParamsSchema, + EventsErrorObjectSchema, + EventsHeartbeatNotificationParamsSchema, + EventsTerminatedNotificationParamsSchema, + ListEventsRequestParamsSchema, + ListEventsResultSchema, + PollEventsRequestParamsSchema, + PollEventsResultSchema, + StreamEventsRequestParamsSchema, + StreamEventsResultSchema, + SubscribeEventsRequestParamsSchema, + SubscribeEventsResultSchema, + UnsubscribeEventsRequestParamsSchema, + UnsubscribeEventsResultSchema, + WebhookControlBodySchema, + WebhookDeliverySchema, + WebhookGapBodySchema, + WebhookTargetSchema, + WebhookTerminatedBodySchema, + WebhookVerificationBodySchema +} from './schemas'; +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 './types'; diff --git a/packages/core/src/ext/events/schemas.ts b/packages/core/src/ext/events/schemas.ts new file mode 100644 index 0000000000..eb7b958353 --- /dev/null +++ b/packages/core/src/ext/events/schemas.ts @@ -0,0 +1,391 @@ +import * as z from 'zod/v4'; + +import { BaseRequestParamsSchema, PaginatedRequestParamsSchema, PaginatedResultSchema, ResultSchema } from '../../schemas'; +import { DELIVERY_ERROR_CATEGORIES, DELIVERY_MODES } from './constants'; + +// Every object schema here is loose, so unknown keys survive; an absent `cursor` means the same as `null` (SEP-3415). + +const cursor = z.string().nullable().optional(); +const meta = z.record(z.string(), z.unknown()).optional(); +const jsonObject = z.record(z.string(), z.unknown()); + +/** + * One of `poll`, `push`, `webhook`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const DeliveryModeSchema = z.enum(DELIVERY_MODES); + +/** + * One of the six webhook delivery failure categories. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const DeliveryErrorCategorySchema = z.enum(DELIVERY_ERROR_CATEGORIES); + +/** + * An event type as `events/list` describes it. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EventDescriptorSchema = z.looseObject({ + name: z.string(), + description: z.string().optional(), + /** The delivery modes the event type supports; never empty. */ + delivery: z.array(DeliveryModeSchema).min(1), + /** JSON Schema for the subscription `arguments`. */ + inputSchema: jsonObject, + /** JSON Schema for `data` in delivered events. */ + payloadSchema: jsonObject, + _meta: meta +}); + +/** + * One delivered event: a poll result entry, the params of `notifications/events/event`, or a webhook event body. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EventOccurrenceSchema = z.looseObject({ + /** Stable identifier of the upstream event, for deduplication within a subscription. */ + eventId: z.string(), + name: z.string(), + /** ISO 8601 time the event occurred. */ + timestamp: z.string(), + /** Payload conforming to the event type's `payloadSchema`. */ + data: jsonObject, + /** Subscription position after this event (push and webhook); `null` without replay. */ + cursor, + _meta: meta +}); + +/** + * The error object of `notifications/events/error`, `notifications/events/terminated` and the webhook `terminated` body. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EventsErrorObjectSchema = z.looseObject({ + code: z.number().int(), + message: z.string(), + data: jsonObject.optional() +}); + +/** + * Params of `events/list`: the pagination params every list request takes. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +// eslint-disable-next-line unicorn/prefer-export-from -- a bare re-export cannot carry the experimental JSDoc +export const ListEventsRequestParamsSchema = PaginatedRequestParamsSchema; + +/** + * Result of `events/list`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const ListEventsResultSchema = z.looseObject({ + ...PaginatedResultSchema.shape, + events: z.array(EventDescriptorSchema) +}); + +const subscriptionRequestFields = { + ...BaseRequestParamsSchema.shape, + /** The event type name. */ + name: z.string(), + /** Subscription arguments, valid against the event type's `inputSchema`. */ + arguments: jsonObject.optional(), + /** Where to start: `null` (or absent) means now. */ + cursor, + /** Do not replay events older than this many milliseconds. */ + maxAgeMs: z.number().int().nonnegative().optional() +}; + +/** + * Params of `events/poll`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const PollEventsRequestParamsSchema = z.looseObject({ + ...subscriptionRequestFields, + /** Cap on the number of events returned. */ + maxEvents: z.number().int().min(1).optional() +}); + +/** + * Result of `events/poll`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const PollEventsResultSchema = z.looseObject({ + ...ResultSchema.shape, + events: z.array(EventOccurrenceSchema), + /** The position to poll from next; `null` without replay. */ + cursor, + /** Whether events were skipped between the supplied cursor and this batch. */ + truncated: z.boolean().optional(), + /** Whether more events are ready now; poll again at once, ignoring `nextPollMs`. */ + hasMore: z.boolean().optional(), + /** The recommended wait before the next poll. */ + nextPollMs: z.number().int().nonnegative().optional() +}); + +/** + * Params of `events/stream`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const StreamEventsRequestParamsSchema = z.looseObject({ + ...subscriptionRequestFields, + /** Suggested heartbeat interval; the server's grant in `notifications/events/active` is authoritative. */ + heartbeatMs: z.number().int().min(1).optional() +}); + +/** + * Result of `events/stream`: the empty final frame when the server closes the stream. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const StreamEventsResultSchema = z.looseObject(ResultSchema.shape); + +/** + * The `delivery` object of `events/subscribe`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const WebhookDeliverySchema = z.looseObject({ + mode: z.literal('webhook'), + /** The `https` callback URL the server POSTs to. */ + url: z.string(), + /** The Standard Webhooks signing secret: `whsec_` followed by base64 of 24 to 64 random bytes. */ + secret: z.string() +}); + +/** + * The `delivery` object of `events/unsubscribe`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const WebhookTargetSchema = z.looseObject({ + /** The callback URL of the subscription to remove. */ + url: z.string() +}); + +/** + * Params of `events/subscribe`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const SubscribeEventsRequestParamsSchema = z.looseObject({ + ...subscriptionRequestFields, + delivery: WebhookDeliverySchema, + /** Suggested lifetime: absent asks for the server default, `null` for no expiry. */ + ttlMs: z.number().int().nonnegative().nullable().optional() +}); + +/** + * 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 const DeliveryStatusSchema = z.looseObject({ + /** Whether the server is delivering; `false` means retries were suspended until this refresh. */ + active: z.boolean(), + lastDeliveryAt: z.string().nullable().optional(), + lastError: DeliveryErrorCategorySchema.nullable().optional(), + failedSince: z.string().optional(), + /** Whether the server is rate-limiting deliveries (delayed, not failing). */ + throttled: z.boolean().optional(), + retryAfterMs: z.number().int().nonnegative().optional() +}); + +/** + * Result of `events/subscribe`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const SubscribeEventsResultSchema = z.looseObject({ + ...ResultSchema.shape, + /** Server-derived subscription id, sent as `X-MCP-Subscription-Id` on every delivery. */ + id: z.string(), + /** ISO 8601 time to refresh before; `null` grants no expiry. */ + refreshBefore: z.string().nullable(), + /** Safe-to-persist watermark; `null` without replay. */ + cursor, + truncated: z.boolean().optional(), + deliveryStatus: DeliveryStatusSchema.optional() +}); + +/** + * Params of `events/unsubscribe`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const UnsubscribeEventsRequestParamsSchema = z.looseObject({ + ...BaseRequestParamsSchema.shape, + name: z.string(), + arguments: jsonObject.optional(), + delivery: WebhookTargetSchema +}); + +/** + * Result of `events/unsubscribe`: an empty result. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const UnsubscribeEventsResultSchema = z.looseObject(ResultSchema.shape); + +/** + * Params of `notifications/events/active`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EventsActiveNotificationParamsSchema = z.looseObject({ + cursor, + truncated: z.boolean().optional(), + /** The granted heartbeat interval. */ + heartbeatMs: z.number().int().min(1), + _meta: meta +}); + +/** + * Params of `notifications/events/event`: one event occurrence. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EventNotificationParamsSchema = EventOccurrenceSchema; + +/** + * Params of `notifications/events/heartbeat`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EventsHeartbeatNotificationParamsSchema = z.looseObject({ + /** The position the server has checked up to. */ + cursor, + _meta: meta +}); + +const errorNotificationFields = { + error: EventsErrorObjectSchema, + _meta: meta +}; + +/** + * Params of `notifications/events/error`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EventsErrorNotificationParamsSchema = z.looseObject(errorNotificationFields); + +/** + * Params of `notifications/events/terminated`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EventsTerminatedNotificationParamsSchema = z.looseObject(errorNotificationFields); + +/** + * Webhook control body: a gap between refreshes, with the fresh cursor to persist. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const WebhookGapBodySchema = z.looseObject({ + type: z.literal('gap'), + cursor +}); + +/** + * Webhook control body: the subscription has ended. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const WebhookTerminatedBodySchema = z.looseObject({ + type: z.literal('terminated'), + error: EventsErrorObjectSchema +}); + +/** + * Webhook control body: the endpoint verification challenge, echoed back in a `2xx` body. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const WebhookVerificationBodySchema = z.looseObject({ + type: z.literal('verification'), + challenge: z.string() +}); + +/** + * Any webhook control body; a webhook body without a top-level `type` is an event occurrence. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const WebhookControlBodySchema = z.discriminatedUnion('type', [ + WebhookGapBodySchema, + WebhookTerminatedBodySchema, + WebhookVerificationBodySchema +]); + +/** + * The value at `capabilities.extensions["io.modelcontextprotocol/events"]`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export const EventsCapabilitySchema = z.looseObject({ + /** Whether the server sends `notifications/events/list_changed`. */ + listChanged: z.boolean().optional() +}); diff --git a/packages/core/src/ext/events/types.ts b/packages/core/src/ext/events/types.ts new file mode 100644 index 0000000000..0c84c7673e --- /dev/null +++ b/packages/core/src/ext/events/types.ts @@ -0,0 +1,284 @@ +import type * as z from 'zod/v4'; + +import type { + DeliveryErrorCategorySchema, + DeliveryModeSchema, + DeliveryStatusSchema, + EventDescriptorSchema, + EventNotificationParamsSchema, + EventOccurrenceSchema, + EventsActiveNotificationParamsSchema, + EventsCapabilitySchema, + EventsErrorNotificationParamsSchema, + EventsErrorObjectSchema, + EventsHeartbeatNotificationParamsSchema, + EventsTerminatedNotificationParamsSchema, + ListEventsRequestParamsSchema, + ListEventsResultSchema, + PollEventsRequestParamsSchema, + PollEventsResultSchema, + StreamEventsRequestParamsSchema, + StreamEventsResultSchema, + SubscribeEventsRequestParamsSchema, + SubscribeEventsResultSchema, + UnsubscribeEventsRequestParamsSchema, + UnsubscribeEventsResultSchema, + WebhookControlBodySchema, + WebhookDeliverySchema, + WebhookGapBodySchema, + WebhookTargetSchema, + WebhookTerminatedBodySchema, + WebhookVerificationBodySchema +} from './schemas'; + +/** + * `poll`, `push` or `webhook`. + * + * Experimental: Events (SEP-3415) is new; this API may change in a minor release. + * + * @experimental + */ +export type DeliveryMode = z.infer; + +/** + * 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..d4e49880d6 100644 --- a/packages/middleware/express/tsconfig.json +++ b/packages/middleware/express/tsconfig.json @@ -16,11 +16,17 @@ "@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" ], "@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/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..d4e49880d6 100644 --- a/packages/middleware/hono/tsconfig.json +++ b/packages/middleware/hono/tsconfig.json @@ -16,11 +16,17 @@ "@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" ], "@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 6c35df5027..9a4001de59 100644 --- a/packages/middleware/node/tsconfig.json +++ b/packages/middleware/node/tsconfig.json @@ -14,12 +14,18 @@ "@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" ], "@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-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/package.json b/packages/server/package.json index 8682d531b5..d0c75631d5 100644 --- a/packages/server/package.json +++ b/packages/server/package.json @@ -60,6 +60,26 @@ "default": "./dist/ext/skills/node.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" + } + }, + "./ext/events/node": { + "import": { + "types": "./dist/ext/events/node.d.mts", + "default": "./dist/ext/events/node.mjs" + }, + "require": { + "types": "./dist/ext/events/node.d.cts", + "default": "./dist/ext/events/node.cjs" + } + }, "./validators/ajv": { "import": { "types": "./dist/validators/ajv.d.mts", @@ -133,6 +153,12 @@ "ext/skills/node": [ "dist/ext/skills/node.d.mts" ], + "ext/events": [ + "dist/ext/events/index.d.mts" + ], + "ext/events/node": [ + "dist/ext/events/node.d.mts" + ], "validators/ajv": [ "dist/validators/ajv.d.mts" ], diff --git a/packages/server/src/ext/events/context.ts b/packages/server/src/ext/events/context.ts new file mode 100644 index 0000000000..bb792efe66 --- /dev/null +++ b/packages/server/src/ext/events/context.ts @@ -0,0 +1,27 @@ +import type { DeliveryMode } from '@modelcontextprotocol/core/ext/events'; + +import type { CheckContext } from './types'; + +export interface ContextFields { + name: string; + subscriptionId: string; + principal: string | null; + mode: DeliveryMode; + signal: AbortSignal; + maxEvents?: number; + maxAgeMs?: number; +} + +// The frozen `ctx` handed to event callbacks; the hints are present only when given. +export function makeContext(fields: ContextFields): CheckContext { + const { name, subscriptionId, principal, mode, signal, maxEvents, maxAgeMs } = fields; + return Object.freeze({ + name, + subscriptionId, + principal, + mode, + signal, + ...(maxEvents === undefined ? {} : { maxEvents }), + ...(maxAgeMs === undefined ? {} : { maxAgeMs }) + }); +} diff --git a/packages/server/src/ext/events/emitBuffer.ts b/packages/server/src/ext/events/emitBuffer.ts new file mode 100644 index 0000000000..f3d759acc8 --- /dev/null +++ b/packages/server/src/ext/events/emitBuffer.ts @@ -0,0 +1,149 @@ +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(); + // 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; + 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 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(); + this.#epoch = undefined; + } + + #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; + } + + #currentEpoch(): string { + this.#epoch ??= newEpoch(); + return this.#epoch; + } + + #format(sequence: number): string { + return `e${this.#currentEpoch()}.${sequence}`; + } + + #parse(cursor: string): number | undefined { + const match = CURSOR.exec(cursor); + 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 new file mode 100644 index 0000000000..8f5fb96dec --- /dev/null +++ b/packages/server/src/ext/events/eraGate.ts @@ -0,0 +1,10 @@ +import { isModernProtocolVersion, ProtocolError, ProtocolErrorCode } from '@modelcontextprotocol/core-internal'; + +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 new file mode 100644 index 0000000000..deee2851b1 --- /dev/null +++ b/packages/server/src/ext/events/extension.ts @@ -0,0 +1,422 @@ +import type { EventDescriptor, ListEventsResult } from '@modelcontextprotocol/core/ext/events'; +import { + EVENTS_EXTENSION_ID, + EVENTS_LIST_METHOD, + EVENTS_POLL_METHOD, + EVENTS_STREAM_METHOD, + EVENTS_SUBSCRIBE_METHOD, + EVENTS_UNSUBSCRIBE_METHOD, + ListEventsRequestParamsSchema, + PollEventsRequestParamsSchema, + StreamEventsRequestParamsSchema, + SubscribeEventsRequestParamsSchema, + UnsubscribeEventsRequestParamsSchema +} from '@modelcontextprotocol/core/ext/events'; +import type { ServerContext, StandardSchemaWithJSON } from '@modelcontextprotocol/core-internal'; +import { scanXMcpHeaderDeclarations } from '@modelcontextprotocol/core-internal'; +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'; +import { EmitBuffer } from './emitBuffer'; +import { assertModernServer } from './eraGate'; +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 { WebhookSubscriptions } from './webhookSubscriptions'; + +// 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` 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; + +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 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; +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; + +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 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 { + 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)})`); + } +} + +// 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'); + } + 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}, 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 implements ServerExtension { + readonly id = EVENTS_EXTENSION_ID; + readonly #registry = new EventRegistry(); + readonly #sources: SubscriptionSource[] = []; + readonly #trustedOrigins: Set; + readonly #webhookEnabled: boolean; + readonly #onerror: (error: Error) => void; + readonly #buffer: EmitBuffer; + readonly #validator: SubscriptionValidator; + readonly #poll: PollSource; + readonly #push: StreamSet; + // 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. + 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 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; + 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 ?? DEFAULT_MAX_SUBSCRIPTIONS, + 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, + defaultNextPollMs: options.defaultNextPollMs ?? DEFAULT_NEXT_POLL_MS, + report: error => this.#report(error) + }); + 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) + }); + const { webhookTtlMs, webhookSender } = options; + const webhooks = + webhookTtlMs === undefined || webhookSender === undefined + ? undefined + : new WebhookSubscriptions({ + validator: this.#validator, + registry: this.#registry, + buffer: this.#buffer, + sender: webhookSender, + store: options.webhookStore ?? new InMemoryWebhookSubscriptionStore(), + trustedOrigins: this.#trustedOrigins, + 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(), + () => this.#push.closeAll(), + () => this.#webhooks?.clear() + ); + installTestHook(this, { + generation: () => this.#generation, + restart: () => { + this.#generation += 1; + for (const clear of this.#restarts) clear(); + }, + state: () => ({ + trustedOrigins: [...this.#trustedOrigins], + emitBuffer: this.#buffer.sizes(), + pollLeases: this.#poll.size, + pushStreams: this.#push.size, + webhookSubscriptions: this.#webhooks?.delivering ?? 0, + webhookExpiryTimers: this.#webhooks?.watching ?? 0 + }), + addTrustedOrigin: origin => { + assertOrigin(origin); + this.#trustedOrigins.add(origin); + }, + addSource: source => { + this.#sources.push(source); + }, + addFanOut: fanOut => { + this.#fanOuts.push(fanOut); + } + }); + } + + /** + * 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`. + */ + setup(ctx: ServerExtensionContext): void { + const server = ctx.mcp.server; + ctx.setRequestHandler(EVENTS_LIST_METHOD, { params: ListEventsRequestParamsSchema }, () => + this.#modernOnly(server, () => this.#list()) + ); + ctx.setRequestHandler(EVENTS_POLL_METHOD, { params: PollEventsRequestParamsSchema }, (params, requestCtx) => + 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, perRequestBacklogOf(server.transport))) + ); + ctx.setRequestHandler(EVENTS_SUBSCRIBE_METHOD, { params: SubscribeEventsRequestParamsSchema }, (params, requestCtx) => + this.#modernOnly(server, () => + this.#webhooks === undefined ? this.#refuseWebhook(params, requestCtx) : this.#webhooks.subscribe(params, requestCtx) + ) + ); + ctx.setRequestHandler(EVENTS_UNSUBSCRIBE_METHOD, { params: UnsubscribeEventsRequestParamsSchema }, (params, requestCtx) => + this.#modernOnly(server, () => + this.#webhooks === undefined ? this.#refuseWebhook(params, requestCtx) : this.#webhooks.unsubscribe(params, requestCtx) + ) + ); + markModernOnlyExtension(server, EVENTS_EXTENSION_ID); + markStreamingMethod(server, EVENTS_STREAM_METHOD); + registerParamHeaderSource(ctx.mcp, NAMED_EVENT_METHODS, name => this.#registry.get(name)?.inputJson); + } + + /** + * 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; 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'`). + */ + 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) { + // 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, + new EventsError('unsupported', `Event type ${feature} changed`, { feature, reason: 'schema_changed' }) + ); + } + 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 => { + 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) + }; + if (definition.emitOnly !== true) return handle; + const emitOnly: EmitOnlyEventHandle = { + ...handle, + emit: async (input, options) => { + assertCurrent(); + await this.#emit(current, input, options?.subscriptionId); + } + }; + return emitOnly; + } + + // 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(): ListEventsResult { + 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}` + ) + ); + } + + // 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_)); + } + + #report(error: unknown): void { + try { + 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/index.ts b/packages/server/src/ext/events/index.ts new file mode 100644 index 0000000000..4b72c5ff0d --- /dev/null +++ b/packages/server/src/ext/events/index.ts @@ -0,0 +1,71 @@ +// @modelcontextprotocol/server/ext/events +// +// Server side of the MCP Events extension (SEP-3415). + +export { EventsExtension } from './extension'; +export { InMemoryWebhookSubscriptionStore } from './store'; +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/leases.ts b/packages/server/src/ext/events/leases.ts new file mode 100644 index 0000000000..f64fcd5889 --- /dev/null +++ b/packages/server/src/ext/events/leases.ts @@ -0,0 +1,101 @@ +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; + } + + // 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) { + 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/node.ts b/packages/server/src/ext/events/node.ts new file mode 100644 index 0000000000..fedaa483d8 --- /dev/null +++ b/packages/server/src/ext/events/node.ts @@ -0,0 +1,181 @@ +// @modelcontextprotocol/server/ext/events/node +// +// Node.js webhook sender for the MCP Events extension (SEP-3415). The only +// module of the events extension that imports Node built-ins. + +import type { LookupAddress } from 'node:dns'; +import dns from 'node:dns'; +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 os from 'node:os'; + +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. +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 + * server-side request forgery. Unless the URL's origin is in `trustedOrigins`, + * 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 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. + * + * @experimental + */ +export function nodeWebhookSender(): WebhookSender { + return send; +} + +async function send(request: WebhookSendRequest): Promise { + 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 resolve(hostnameOf(url), deadline.signal); + // 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) { + 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 (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; + 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); + }); +} + +// 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; 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; +} + +// 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 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 }), []); + } else if (options.all) { + callback(null, [...answers]); + } else { + callback(null, first.address, first.family); + } + }; +} + +// 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; + return typeof code === 'string' && TLS_FAILURE_CODE.test(code) ? { error: 'tls_error' } : REFUSED; +} diff --git a/packages/server/src/ext/events/poll.ts b/packages/server/src/ext/events/poll.ts new file mode 100644 index 0000000000..6113e25a9c --- /dev/null +++ b/packages/server/src/ext/events/poll.ts @@ -0,0 +1,270 @@ +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, EventResult } 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 }) + }; +} + +// 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, + maxAgeMs: number | undefined, + report: (error: unknown) => void +): Promise<{ events: EventOccurrence[]; truncated: boolean }> { + 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) { + // 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) { + truncated = true; + continue; + } + events.push(occurrence); + } + // 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. +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; + } +} + +// 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; + 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); + }); + } + + get size(): number { + 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) => { + key = leaseKey(principal, params.name, rawArgs); + this.#throwTerminated(key); + }); + const { lease, created } = 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 => selectEvent(entry, selectCtx, args, buffered, this.#deps.report) + }); + 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.#nextPollMs(undefined) }; + } + + const result = await check(makeContext({ ...fields, maxEvents, maxAgeMs: params.maxAgeMs }), args, cursor); + 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 }; + } + const { events, truncated } = await checkedEvents(entry, result, params.maxAgeMs, this.#deps.report); + 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(); + } + + // 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; + if (terminated === undefined) return; + this.#leases.delete(key); + throw terminated; + } + + // 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; + 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, + principal, + args, + entry, + ended: new AbortController() + })); + if (!created) return { lease, created }; + 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, created }; + } + + 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/push.ts b/packages/server/src/ext/events/push.ts new file mode 100644 index 0000000000..1c5887a5f7 --- /dev/null +++ b/packages/server/src/ext/events/push.ts @@ -0,0 +1,387 @@ +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, checkedSelection, selectEvent } from './poll'; +import type { RegisteredEvent } from './registry'; +import type { CheckContext, EventContext, EventResult } from './types'; +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']); + +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 { + // The registration it serves; an update() replaces it with the updated one. + entry: RegisteredEvent; + readonly args: Record; + 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; + // 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 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[]; + 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}` and the webhook `terminated` body: an `EventsError` as it is, anything else as -32603. +export 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) }; +} + +// 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, + result: EventResult, + 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) => (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); +} + +// 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; + readonly #streams = new Set(); + + constructor(deps: PushDeps) { + this.#deps = deps; + } + + get size(): number { + 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; + } + + // `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, backlog); + 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 startCheck(entry, stream.ctx, args, params.cursor ?? null, params.maxAgeMs, this.#deps.report); + } + } 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; + 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; + } + + // 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.#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[] = []; + 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, + backlog: (() => number) | undefined + ): 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, + ...(backlog !== undefined && { backlog }), + 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; + } + + #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.#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)); + } + + 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 checkedBatch(stream.entry, from, result, undefined, this.#deps.report); + 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); + } + + // 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 () => { + const resolved = await params; + 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; + 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/registry.ts b/packages/server/src/ext/events/registry.ts new file mode 100644 index 0000000000..d3532129d3 --- /dev/null +++ b/packages/server/src/ext/events/registry.ts @@ -0,0 +1,114 @@ +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]; + +// 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'; + 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 updatable fields of `changes` replaced. + update(entry: RegisteredEvent, changes: EventChanges): RegisteredEvent { + 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; + } + + 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/specialAddresses.ts b/packages/server/src/ext/events/specialAddresses.ts new file mode 100644 index 0000000000..c674650cb4 --- /dev/null +++ b/packages/server/src/ext/events/specialAddresses.ts @@ -0,0 +1,105 @@ +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:1::/48', + '100::/64', + '100:0:0:1::/64', + '2001::/23', + '2001:db8::/32', + '2002::/16', + '3fff::/20', + '5f00::/16', + 'fc00::/7', + 'fe80::/10', + 'ff00::/8' +].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 { + const ipv4 = parseIpv4(ip); + if (ipv4 !== undefined) return within(ipv4, IPV4_SPECIAL); + const ipv6 = parseIpv6(ip); + if (ipv6 === undefined) return true; + if (within(ipv6, EMBEDS_IPV4)) return within(ipv6 & 0xff_ff_ff_ffn, IPV4_SPECIAL); + return within(ipv6, IPV6_SPECIAL); +} 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 new file mode 100644 index 0000000000..89887cf288 --- /dev/null +++ b/packages/server/src/ext/events/testHook.ts @@ -0,0 +1,34 @@ +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; + // Open push streams, counting those still starting. + 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. +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; + addFanOut(fanOut: EmitFanOut): 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..2fb10ac26a --- /dev/null +++ b/packages/server/src/ext/events/types.ts @@ -0,0 +1,320 @@ +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'; + +export type InferInput = StandardSchemaWithJSON.InferInput; +export 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 + * `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

> { + /** 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; + /** 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

> { + /** + * 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; + /** + * 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; + /** More events are waiting beyond `ctx.maxEvents`. */ + hasMore?: boolean; +} + +export 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`, 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`. Poll serves such a type one subscription per lease (principal, event name and + * arguments), so clients that share a lease, as every caller does on a server without `getPrincipal`, + * split its events between them, and a client's first poll on an existing lease can return events from + * before it subscribed. A poll client that waits longer than `pollSubscriptionTtlMs` between polls starts + * a new lease each time and gets nothing. Clients that need every event use push or webhook. + */ + 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, and push and webhook subscriptions that pass a cursor + * replay it first; 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; + /** Aborts when the SDK stops delivering to the subscription. */ + 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. + * 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. + * + * @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`, so a + * store that drops records itself should keep each one a while past + * `expiresAt`. 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, and the counts + * (`maxSubscriptions`, `emitBuffer.maxEvents`) and the durations clients + * receive (`webhookTtlMs`, `heartbeatMs`, `defaultNextPollMs`) whole numbers. + * + * 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 and replayed from. */ + emitBuffer?: { maxAgeMs?: number; maxEvents?: number }; + /** 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, 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` + * (`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; + /** 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 new file mode 100644 index 0000000000..1729fa51dd --- /dev/null +++ b/packages/server/src/ext/events/validation.ts @@ -0,0 +1,82 @@ +import type { DeliveryMode } from '@modelcontextprotocol/core/ext/events'; +import type { ServerContext } from '@modelcontextprotocol/core-internal'; +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; + readonly getPrincipal: EventsOptions['getPrincipal']; + 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 { + return new EventsError('unsupported', message, { feature: 'deliveryMode', value: mode }); +} + +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; + } + + // 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, + ctx: ServerContext, + beforeParse?: (principal: string | null, rawArgs: Record) => void + ): Promise { + 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 notOffered(`Event type ${params.name} does not offer ${mode} delivery`, mode); + } + const rawArgs = params.arguments ?? {}; + beforeParse?.(principal, rawArgs); + const args = await entry.parseArguments(rawArgs); + return { entry, principal, args }; + } + + // 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 new file mode 100644 index 0000000000..edf382ec32 --- /dev/null +++ b/packages/server/src/ext/events/webhookEngine.ts @@ -0,0 +1,814 @@ +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]; +// 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 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; +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; at most 10 more wait their turn. +const VERIFICATIONS_PER_WINDOW = 10; +const VERIFICATION_WINDOW_MS = 60_000; +// 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; +// 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(); + +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; + // Whether this process watches the subscription (an expiry timer of its own); default none. + readonly watches?: (id: string) => boolean; + 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; + readonly occurrence: EventOccurrence; + // The subscription's position after this event. + readonly position: string | null; + attempts: number; + place: Place; + 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; + // 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[]; + // 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. + parked: Message[]; + 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. + 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; + // 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. +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[]; +} + +// 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?.(); + return timer; +} + +function byteLength(text: string): number { + return encoder.encode(text).byteLength; +} + +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); + 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 }); +} + +// 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', + 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; + 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(); + // 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; + + constructor(options: WebhookEngineOptions) { + this.#sender = options.sender; + this.#store = options.store; + this.#trustedOrigins = options.trustedOrigins; + this.#onerror = options.onerror; + this.#watches = options.watches ?? (() => false); + this.#now = options.now ?? (() => Date.now()); + } + + // Subscriptions this process holds delivery state for. + get size(): number { + return this.#tracked.size; + } + + // 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, signal); + let covered = this.#verified.get(key); + if (covered === undefined) { + covered = 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; 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 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); + } + + // 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) { + 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 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 { + 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); + 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; + 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, 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 = new Set(tracked.parked); + tracked.parked = []; + // 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); + } + + // 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); + 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); + for (const control of this.#controls) this.#stopControl(control); + this.#verified.clear(); + 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; `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, 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 && this.#now() < failed.until) throw verificationError(failed.reason); + this.#failed.delete(key); + const host = await this.#claimHost(url, abandoned); + 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 { + this.#releaseHost(host); + } + } + + // 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(); + let host = this.#hosts.get(name); + if (host === undefined) { + 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 (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, + ended: new AbortController(), + watermark, + pending: [], + running: 0, + waiting: [], + parked: [], + active: true, + abandoned: 0, + lastDeliveryAt: null, + lastError: null, + recent: [], + recentFailures: 0, + gap: false + }; + 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); + 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 { + return this.#tracked.get(tracked.id) === tracked; + } + + // 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.place = 'running'; + tracked.running += 1; + this.#attempt(tracked, message, record); + } + + // 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(); + if (next === undefined) return; + this.#begin(tracked, next); + } + } + + // 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); + 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)) { + 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) => { + if (!this.#isCurrent(tracked)) return; + this.#onerror(toError(error)); + this.#retry(tracked, message); + }); + } + + async #try(tracked: Tracked, message: Message, supplied: WebhookSubscriptionRecord | undefined): Promise { + 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; + } + // 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; + this.#park(tracked, message); + return; + } + // 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( + `webhook subscription ${tracked.id}: abandoned event ${message.occurrence.eventId}, whose body is over ${MAX_BODY_BYTES} bytes` + ) + ); + 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); + 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. + #retry(tracked: Tracked, message: Message): void { + const delay = RETRY_DELAYS_MS[message.attempts - 1]; + if (delay === undefined) { + this.#abandon(tracked, message, `after ${message.attempts} failed attempts`); + return; + } + this.#release(tracked, message, 'retrying'); + message.retry = unref(setTimeout(() => this.#queue(tracked, message), delay)); + } + + // 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.#cap(tracked); + } + + // 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 { + this.#release(tracked, message, 'done'); + let head = tracked.pending[0]; + while (head?.place === 'done') { + 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 (FINAL_STATUSES.has(outcome.status)) 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; + } + } + + // 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. + #secretsOf(record: WebhookSubscriptionRecord): string[] { + const previous = record.previousSecret; + return previous !== undefined && this.#now() < previous.expiresAt ? [record.secret, previous.secret] : [record.secret]; + } + + async #post( + url: string, + subscriptionId: string, + 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': 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/src/ext/events/webhookSubscriptions.ts b/packages/server/src/ext/events/webhookSubscriptions.ts new file mode 100644 index 0000000000..a020319792 --- /dev/null +++ b/packages/server/src/ext/events/webhookSubscriptions.ts @@ -0,0 +1,605 @@ +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 { checkedSelection, selectEvent } from './poll'; +import type { Batch } 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'; +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; +// 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; + +// 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; + 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; 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; + 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; + 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; +} + +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, 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)}`; +} + +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(); + // 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(); + + constructor(deps: WebhookDeps) { + this.#deps = deps; + this.#engine = new WebhookEngine({ + sender: deps.sender, + store: deps.store, + trustedOrigins: deps.trustedOrigins, + onerror: error => deps.report(error), + watches: id => this.#watched.has(id) + }); + } + + // What `maxSubscriptions` counts here: the subscriptions this process watches, and the creates still starting. + get size(): number { + 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; + } + + // 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, params.arguments ?? {}); + const ttl = grantMs(params.ttlMs, this.#deps.webhookTtlMs); + 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 () => { + 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 } = 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(); + 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) + ); + } + + // 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(); + 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.#starting.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(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, subscribing.signal); + 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 this.#startEmitOnly(record, watched, from, params.maxAgeMs, 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); + } + } + + 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; + } + + // 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. + 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, + // Events this process abandoned since the subscriber was last told. + truncated: this.#engine.takeGap(id), + ...(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 }); + } + + // 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 { + 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))); + } + } + } + + // 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; + 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) { + 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/src/server/createMcpHandler.ts b/packages/server/src/server/createMcpHandler.ts index ee9ce4ae00..901b5d7059 100644 --- a/packages/server/src/server/createMcpHandler.ts +++ b/packages/server/src/server/createMcpHandler.ts @@ -65,6 +65,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'; @@ -74,6 +75,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 @@ -182,8 +184,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; /** @@ -204,7 +207,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; @@ -721,7 +726,7 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa }); if (responseMode === 'json') { logger.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.' ); } @@ -822,8 +827,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` / @@ -831,13 +838,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) { @@ -897,13 +910,18 @@ 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 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 }), - ...(responseMode !== undefined && { responseMode }), - ...(options.keepAliveMs !== undefined && { keepAliveMs: options.keepAliveMs }) + ...(exchangeMode !== undefined && { responseMode: exchangeMode }), + ...(keepAliveMs !== undefined && { keepAliveMs }) }); if (route.messageKind === 'notification') { // Notification exchanges have no terminal response to ride the 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/paramHeaderSources.ts b/packages/server/src/server/paramHeaderSources.ts new file mode 100644 index 0000000000..614543968b --- /dev/null +++ b/packages/server/src/server/paramHeaderSources.ts @@ -0,0 +1,18 @@ +import type { McpServer } from './mcp'; + +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>(); + +// 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/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/src/server/server.ts b/packages/server/src/server/server.ts index dc00724587..d2b99cc8c1 100644 --- a/packages/server/src/server/server.ts +++ b/packages/server/src/server/server.ts @@ -70,6 +70,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'; @@ -960,7 +961,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/src/server/streamingMethods.ts b/packages/server/src/server/streamingMethods.ts new file mode 100644 index 0000000000..56959cc870 --- /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, and without SSE comment keepalives. +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/emitBuffer.test.ts b/packages/server/test/ext/events/emitBuffer.test.ts new file mode 100644 index 0000000000..07cf4d39f6 --- /dev/null +++ b/packages/server/test/ext/events/emitBuffer.test.ts @@ -0,0 +1,200 @@ +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('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' } }); + 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/harness.ts b/packages/server/test/ext/events/harness.ts new file mode 100644 index 0000000000..3c5aef774c --- /dev/null +++ b/packages/server/test/ext/events/harness.ts @@ -0,0 +1,139 @@ +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`, in the `extensions` of the fresh `McpServer` built for each request; `setup` adds more to each. */ +export function serve( + events: EventsExtension, + options: { authInfo?: AuthInfo; responseMode?: 'auto' | 'json'; keepAliveMs?: number; setup?: (mcp: McpServer) => void } = {} +): Served { + const handler = createMcpHandler( + () => { + const mcp = new McpServer({ name: 'events-test', version: '1.0.0' }, { extensions: [events] }); + options.setup?.(mcp); + return mcp; + }, + { + ...(options.responseMode !== undefined && { responseMode: options.responseMode }), + ...(options.keepAliveMs !== undefined && { keepAliveMs: options.keepAliveMs }) + } + ); + + 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/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); + }); +}); 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..ce8435c9a3 --- /dev/null +++ b/packages/server/test/ext/events/node.test.ts @@ -0,0 +1,492 @@ +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 os from 'node:os'; +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.useRealTimers(); + 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, host = '127.0.0.1'): Promise { + servers.push(server); + 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(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 }; +} + +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) }; +} + +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) => { + pinned = options.lookup as net.LookupFunction; + return failingRequest('ECONNREFUSED'); + }) as unknown as typeof https.request); + 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 `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 => !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. +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 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(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 { resolve4 } = stubResolver(); + + expect(await nodeWebhookSender()(sendRequest('http://example.com/hooks', false))).toEqual(REFUSED); + expect(resolve4).not.toHaveBeenCalled(); + }); + + it('refuses when any resolved address, of either family, is special, without connecting', async () => { + const receiver = await countingServer(); + await treatAsPublic('127.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 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('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 }); + }); + + 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(); + + 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 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']); + + // 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); + }); + + 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 { 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(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'); + stubResolver(['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/poll.test.ts b/packages/server/test/ext/events/poll.test.ts new file mode 100644 index 0000000000..27341e4e77 --- /dev/null +++ b/packages/server/test/ext/events/poll.test.ts @@ -0,0 +1,771 @@ +import { PollEventsResultSchema } from '@modelcontextprotocol/core/ext/events'; +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: [{ 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({ + 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 and timestamp on check events', async () => { + const events = new EventsExtension({ defaultNextPollMs: 1000 }); + events.registerEvent('t', { + payloadSchema: P, + check: () => ({ + events: [ + { eventId: 'upstream-1', 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).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({ + 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.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 }) }); + 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('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: [{ 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' }); + }); + + 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(); + 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 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 }); + 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('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 }); + 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('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 }); + 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('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 }); + 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('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))); + 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, + pushStreams: 0, + webhookSubscriptions: 0, + webhookExpiryTimers: 0 + }); + + hook.restart(); + 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); + expect(onSubscribe).toHaveBeenCalledTimes(2); + }); +}); 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..8ff037adc7 --- /dev/null +++ b/packages/server/test/ext/events/push.test.ts @@ -0,0 +1,752 @@ +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; 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 } }); + 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 another 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 } }, + { eventId: 'd', data: { n: 4 } } + ], + 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); + // 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 })); + 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(() => ({ + events: [ + { eventId: 'old', timestamp: old, data: { n: 1 } }, + { 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: 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 }); + }); + + 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 + .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('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(); + 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('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 }); + 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("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(); + 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, + webhookSubscriptions: 0, + webhookExpiryTimers: 0 + }); + hook.restart(); + expect(onUnsubscribe).toHaveBeenCalledOnce(); + expect(await rest(stream)).toEqual([finalResult(stream.id)]); + expect(hook.state().pushStreams).toBe(0); + }); +}); + +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(() => {}); + 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' }] } }); + }); + + 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); + } +} 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..a8adeb3ae5 --- /dev/null +++ b/packages/server/test/ext/events/registration.test.ts @@ -0,0 +1,333 @@ +import type { DiscoverResult, InitializeResult } 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': {} } }, extensions: [new EventsExtension()] } + ); + expect(legacyAdvertisedCapabilities(mcp.server, mcp.server.getCapabilities()).extensions).toEqual({ 'example.com/other': {} }); + const alone = new McpServer({ name: 't', version: '1' }, { extensions: [new EventsExtension()] }); + 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.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 })).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, and without getPrincipal no share limits them', 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('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']) { + 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('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 () => {}); + 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('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 () => {}); + 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('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' + ); + }); + + 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' }] }); + } + }); +}); + +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/ext/events/specialAddresses.test.ts b/packages/server/test/ext/events/specialAddresses.test.ts new file mode 100644 index 0000000000..4f439dd4f7 --- /dev/null +++ b/packages/server/test/ext/events/specialAddresses.test.ts @@ -0,0 +1,90 @@ +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 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'], + ['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'], + ['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'], + ['::/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); + }); + + 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', + '::808:808', + '64:ff9b::808:808', + '64:ff9b:2::1', + '100:0:0: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/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 new file mode 100644 index 0000000000..3533c867f7 --- /dev/null +++ b/packages/server/test/ext/events/webhookEngine.test.ts @@ -0,0 +1,1237 @@ +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; +} + +// 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)) { + inFlight -= 1; + return { status: 503, body: '' }; + } + return new Promise(resolve => + 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])); +} + +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, 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: 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 waits its turn; another host does not wait. + const samePair = engine.verify('u', HOOK_URL, SECRET, 'sub_2'); + 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']); + + 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(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 () => { + 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' } }); + }); + + 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); + // Nothing before it is unsettled, so it carries its own position. + expect(bodyOf(request)).toEqual({ ...occurrence('evt_1'), cursor: 'p1' }); + } + }); + + 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, 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); + 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); + 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('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'); + 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, 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: '' } + ); + 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'); + // 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); + await until(4); + 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('p4'); + }); + + 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('p2'); + 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(); + 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(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 }); + }); + + 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('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 <= 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(); + 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(12 + n); + } + await settle(); + expect(eventIds().slice(11)).toEqual(['evt_12', 'evt_13', 'evt_14', 'evt_15', 'evt_1']); + expect(engine.watermark(ID)).toBe('p0'); + + 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); + // 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(12 + n); + } + await settle(); + // The oldest message kept starts next, and the abandoned ones no longer hold the watermark back. + 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); + }); + + 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 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: '' } + ); + 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('holds at most 10 000 messages while suspended, abandoning the oldest and reporting it', async () => { + let healthy = false; + 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. + 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); + // And one gap envelope after the first acknowledged delivery. + await until(100 + 10_000 + 1); + await settle(); + 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); + 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'); + 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('resumes many parked messages at most 10 in flight, in position order', async () => { + let healthy = false; + const hold = held(() => !healthy); + const { engine, record, requests, until } = setup(hold.respond); + 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 }); + for (let n = 101; n <= 130; n++) engine.deliver(record, occurrence(`evt_${n}`), `p${n}`, null); + await settle(); + 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_${101 + n}`).sort()); + expect(resumed.slice(10)).toEqual(Array.from({ length: 20 }, (_, n) => `evt_${111 + n}`)); + expect(hold.most()).toBe(10); + }); + + 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('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'); + }); +}); + +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('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('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'); + 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); + }); +}); 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..58f3e48160 --- /dev/null +++ b/packages/server/test/ext/events/webhookSubscriptions.test.ts @@ -0,0 +1,1610 @@ +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 }) + }; +} + +// 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; +} + +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' }); +} + +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: Gated; reached(): void; released: Promise } | undefined; + + hold(method: Gated): { 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); + } + + 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; + held.reached(); + await held.released; + } +} + +// 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(); +}); + +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 } })); + 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(); + 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('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], + [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('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("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: 8 }); + 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 }); + // 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 }); + } + ); + + 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, 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({ 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 } })); + + // 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('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 }); + 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']); + }); +}); + +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('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 }); + 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('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()); + // 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: 102 } }); + 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: '' })) }); + 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('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 }); + 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 }] + ]); + }); + + 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 }); + 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', () => { + 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: 'c1' }); + 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('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('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' }; + 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: 'c1' }); + + 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('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(); + 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 => + 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]]); + }); +}); diff --git a/packages/server/test/server/barrelClean.test.ts b/packages/server/test/server/barrelClean.test.ts index 72fc4221bf..a59db62c96 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'); @@ -143,12 +146,34 @@ describe('@modelcontextprotocol/server root and ext/skills are runtime-neutral', 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/ ); }); + 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/tsconfig.json b/packages/server/tsconfig.json index 54f3389a5f..8292e2e3b8 100644 --- a/packages/server/tsconfig.json +++ b/packages/server/tsconfig.json @@ -8,12 +8,16 @@ "@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" ], "@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/server/tsdown.config.ts b/packages/server/tsdown.config.ts index 06137a4560..992660abf7 100644 --- a/packages/server/tsdown.config.ts +++ b/packages/server/tsdown.config.ts @@ -11,7 +11,9 @@ 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', + 'src/ext/events/node.ts' ], format: ['esm', 'cjs'], fixedExtension: true, @@ -29,9 +31,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 +45,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/pnpm-lock.yaml b/pnpm-lock.yaml index 6d677340d8..df805b27fa 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': 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..b52630bc9e --- /dev/null +++ b/test/conformance/src/events.ts @@ -0,0 +1,374 @@ +/** + * 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); + 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 }; + }, + 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 } +}); + +// 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( + () => 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 = { + 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'); + } + ); + + mcp.registerTool( + 'events_conformance_yield_gap', + { + 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 !== COUNTER && name !== PULSE) return refuse(`only ${COUNTER} and ${PULSE} read an upstream`); + gapNext.add(name); + return text('ok'); + } + ); +} diff --git a/test/conformance/src/everythingClient.ts b/test/conformance/src/everythingClient.ts index 2c9849cf0a..4203652596 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,40 @@ 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' }, extensions: [events] } + ); + 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 e546b37074..3959186550 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 @@ -165,13 +166,18 @@ 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: the events_conformance_* control tools. + registerEventsControls(mcpServer); + // Helper to send log messages using the underlying server function sendLog( level: 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency', diff --git a/test/conformance/tsconfig.json b/test/conformance/tsconfig.json index 01cfe3ef37..f3367ea8e9 100644 --- a/test/conformance/tsconfig.json +++ b/test/conformance/tsconfig.json @@ -12,18 +12,27 @@ "@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" ], "@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"], "@modelcontextprotocol/server/_shims": ["./node_modules/@modelcontextprotocol/server/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/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/requirements.ts b/test/e2e/requirements.ts index 5270df49b4..5125c8a143 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 = { // Extensions (SEP-3371 SDK extension points) 'extensions:registration:duplicate-id': { @@ -3665,6 +3676,231 @@ 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 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, + 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; 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, + 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:extensions:rules': { + ...EVENTS_CELLS, + source: 'sdk', + 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, + 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 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, + 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..7cd30974a4 --- /dev/null +++ b/test/e2e/scenarios/events.test.ts @@ -0,0 +1,1328 @@ +/** + * Self-contained test bodies for the Events extension (SEP-3415). + * + * 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 + * 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 { 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 () => new McpServer({ name: 's', version: '0' }, { extensions: [events] }); +} + +/** 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 in its extensions, ready for wire(). */ +function eventsClient(options: EventsClientOptions = FAST): { client: Client; clientEvents: EventsClientExtension } { + const clientEvents = new EventsClientExtension(options); + const client = new Client({ name: 'c', version: '0' }, { extensions: [clientEvents] }); + 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); + + const settings = client.getServerCapabilities()?.extensions?.[EVENTS_EXTENSION_ID]; + expect(settings).toBeTypeOf('object'); + expect(settings).not.toBeNull(); + expect(Array.isArray(settings)).toBe(false); + // 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) => { + 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) => { + 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: [{ eventId: 'old', 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: [ + { eventId: 'stale', timestamp: new Date(Date.now() - 600_000).toISOString(), data: { text: 'stale' } }, + { eventId: 'fresh', 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' }, _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([ + expect.objectContaining({ + params: { + eventId: 'evt-1', + name: NOTE, + timestamp: expect.any(String), + data: { text: 'pushed' }, + cursor: expect.any(String), + _meta: { 'vendor/k': 1, [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); + // This server does not grant no-expiry, so ttlMs: null gets a finite refreshBefore. + const unlimited = await grantOf(null); + 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); + // 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); + } + } +}); + +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: [{ eventId: 'backlog', 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: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' + ); + + // 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(); + } + } + + // 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) => { + 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(); + } + { + // 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 { + const posts: Post[] = []; + const { client, clientEvents } = eventsClient({ ...FAST, webhook: { url: HOOK_URL } }); + const options = webhookOptions(senderTo(clientEvents.createWebhookHandler(), posts), { + webhookStore: new InMemoryWebhookSubscriptionStore(), + checkIntervalMs: 1000 + }); + // 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(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(); + } + } +}); + +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([]); +}); diff --git a/test/e2e/tsconfig.json b/test/e2e/tsconfig.json index 13094c9b35..17948aede4 100644 --- a/test/e2e/tsconfig.json +++ b/test/e2e/tsconfig.json @@ -12,12 +12,18 @@ "@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" ], "@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" ], @@ -27,12 +33,15 @@ "@modelcontextprotocol/client/validators/ajv": ["./node_modules/@modelcontextprotocol/client/src/validators/ajv.ts"], "@modelcontextprotocol/client/validators/cf-worker": ["./node_modules/@modelcontextprotocol/client/src/validators/cfWorker.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": ["./node_modules/@modelcontextprotocol/server/src/index.ts"], "@modelcontextprotocol/server/stdio": ["./node_modules/@modelcontextprotocol/server/src/stdio.ts"], "@modelcontextprotocol/server/_shims": ["./node_modules/@modelcontextprotocol/server/src/shimsNode.ts"], "@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/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/helpers/tsconfig.json b/test/helpers/tsconfig.json index e6108eaf1f..2f9324ab9c 100644 --- a/test/helpers/tsconfig.json +++ b/test/helpers/tsconfig.json @@ -12,12 +12,18 @@ "@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" ], "@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/test/__fixtures__/eventsStdioServer.ts b/test/integration/test/__fixtures__/eventsStdioServer.ts new file mode 100644 index 0000000000..008ddb0ec9 --- /dev/null +++ b/test/integration/test/__fixtures__/eventsStdioServer.ts @@ -0,0 +1,134 @@ +/** + * 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[]; + // 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. +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 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: [] }; + }); + 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 mcp; + }; + 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 { server } = eventsFixture(); + const handle = serveStdio(() => server('events-stdio-fixture')); + + 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..72bdb48792 --- /dev/null +++ b/test/integration/test/events/eventsEndToEnd.test.ts @@ -0,0 +1,778 @@ +/** + * 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 } 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, events: EventsClientExtension): Client { + return new Client( + { name: 'events-host', version: '1.0.0' }, + revision === MODERN ? { versionNegotiation: { mode: { pin: MODERN } }, extensions: [events] } : { extensions: [events] } + ); +} + +// 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(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. +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 events = options.events ?? new EventsClientExtension(CLIENT_OPTIONS); + 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 => { + 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 events = new EventsClientExtension(CLIENT_OPTIONS); + const client = clientFor(revision, events); + 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 { server } = eventsFixture(); + const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); + const handle = serveStdio(() => server('events-in-memory'), { transport: serverTransport }); + const events = new EventsClientExtension(CLIENT_OPTIONS); + const client = clientFor(revision, events); + 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()); + 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(), { 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); + 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); + 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 () => { + // 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. + const options = { + webhookTtlMs: 2000, + webhookSender: inProcessSender(events.createWebhookHandler(), posts), + webhookStore: store, + getPrincipal + }; + const first = eventsFixture(options); + const second = eventsFixture(options); + const firstHandler = handlerFor(first); + const secondHandler = handlerFor(second); + 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)); + 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); + 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..0a3e1a894c --- /dev/null +++ b/test/integration/test/events/eventsWire.test.ts @@ -0,0 +1,291 @@ +/** + * 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(() => new McpServer({ name: 'events-wire', version: '1.0.0' }, { extensions: [events] })); + 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 events = new EventsClientExtension({ webhook: { url: HOOK_URL } }); + 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); + 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); }); diff --git a/test/integration/tsconfig.json b/test/integration/tsconfig.json index a15fa93ad5..45b3111303 100644 --- a/test/integration/tsconfig.json +++ b/test/integration/tsconfig.json @@ -12,12 +12,18 @@ "@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" ], "@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" ], @@ -35,8 +41,11 @@ "@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/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"], + "@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"],