Skip to content

feat: Events extension (SEP-3415) - #3209

Draft
KKonstantinov wants to merge 38 commits into
mainfrom
feature/ext-events-sep-3415
Draft

KKonstantinov wants to merge 38 commits into
mainfrom
feature/ext-events-sep-3415

Conversation

@KKonstantinov

Copy link
Copy Markdown
Contributor

Adds the Events extension (SEP-3415) to the server, the client and the core wire schemas. A server declares event types and delivers their events by poll (events/poll), push (events/stream) or webhook (events/subscribe); a client lists them and subscribes with one call, and the SDK picks the delivery mode. Everything is experimental and reachable only through new ext/events subpaths; package root exports are unchanged. Events installs through the extensions option from #2820: new McpServer(info, { extensions: [events] }) and new Client(info, { extensions: [eventsClient] }).

Motivation and Context

SEP-3415 was accepted on 2026-11-11 and still lists an official-SDK reference implementation as outstanding; this is the TypeScript one. modelcontextprotocol/python-sdk#3822 covers poll and webhook with in-memory state; this PR covers all three delivery modes, does the delivery work for the author as SEP Appendix A describes, and makes webhook state pluggable.

Built against:

How Has This Been Tested?

  • Unit: 310 server tests and 114 client tests for Events, plus core-internal tests for EventsError, canonical JSON and webhook signing, and core tests for the wire schemas.
  • Integration (50): end to end over stdio and Streamable HTTP, and a wire-behaviour suite that asserts the raw JSON-RPC and headers of every events/* exchange: Mcp-Name, Mcp-Param and the 400 / -32020 mismatch, the {} capability, and that the client never opens subscriptions/listen.
  • e2e: 43 requirements in test/e2e/requirements.ts, run on 2026-07-28. Ids shared with other SDKs use the SEP's wording; SDK-specific behaviour has typescript: ids.
  • Example: examples/events is a self-verifying server and client pair with an emit-only and a check event type: poll and push on the stdio and HTTP legs, webhook on the HTTP leg. pnpm run:examples passes every leg.
  • Conformance, run locally against a build of conformance#541, since no released referee has these scenarios yet. The two scripts read the checkout from EVENTS_CONFORMANCE_DIR; once the scenarios are released they move into conformance.yml with a pin bump.
    • Server: 128 of 128 checks pass across events-discovery (14), events-poll (33), events-push (28), events-webhook (28) and events-webhook-delivery (25), with 13 warnings, all "unverified, not violated". Baselined: the two events-webhook:sep-3415-ttl-no-expiry-* checks, because the server grants only finite TTLs (below); events-discovery:sep-3415-list-pagination, because events/list is served as one page; and ten checks the suite reports as not testable for any server (it cannot mint a stale cursor, rotate a secret mid-delivery, or set up a second principal, a restart or a key-discovery origin).
    • Client: events-client-no-extension passes. The poll, push and webhook client scenarios cannot grade yet: the conformance#541 mock server omits payloadSchema from its event descriptors (SEP l.15) and heartbeatMs from active (SEP l.382), so the client, which stays strict, refuses the listing and never polls, streams or subscribes. Those 14 checks are baselined with that reason until the mock sends both fields (I'll raise it on requireBearerAuth 403 breaks claude desktop #541); the e2e requirements and the integration suite cover the same behaviour. Two more are baselined for list_changed (below).
  • Whole repo: build, typecheck, lint and the docs check pass, and every package suite passes. Locally the e2e run also shows the protocol:timeout:max-total [sse] timeout flake, which fails the same way on main without this branch.

Breaking Changes

None. The Events API is new, experimental, and reachable only through the new subpaths.

One edge worth knowing: on 2026-07-28, createMcpHandler now requires Mcp-Name on events/poll, events/stream, events/subscribe and events/unsubscribe (400 / -32020 when it is missing or does not match params.name), whether or not the server serves Events. A server without Events answers those methods with method-not-found anyway, so only the error a header-less client sees changes.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

Additional context

Protocol version. Events is served and used on 2026-07-28 sessions only. A server whose session negotiated an earlier revision leaves Events out of its initialize result and answers events/* with -32601. The check reads the session's revision, so a single request cannot opt in by claiming 2026-07-28 in its own envelope.

Installing. Both sides install through #2820's setup(ctx); there is no attach. One EventsExtension serves every server constructed with it, which is what createMcpHandler's per-request factory needs. Skills keeps its attach because it was released before #2820.

Two kinds of event type. registerEvent takes either a check(ctx, args, cursor) function, which the SDK calls to pull from upstream, or emitOnly: true, for types the author pushes with handle.emit(). The definition is a discriminated union, after SEP Appendix A's emit_only=True; python-sdk#3822 infers the kind instead. Either kind is delivered by poll, push or webhook.

Webhook delivery needs a principal. It turns on only when webhookTtlMs, webhookSender and getPrincipal are all set. getPrincipal has no default, unlike python-sdk#3822, whose access_token_principal combines client id, issuer and subject: the TypeScript AuthInfo has no subject field, and clientId names the app, not the user. A default can be added later without breaking anyone, since configuration that throws today would then be accepted.

Webhook storage. WebhookSubscriptionStore is public, with InMemoryWebhookSubscriptionStore as the default (the webhookStore option). SEP Appendix B says "A horizontally scaled server, with several replicas behind a load balancer, needs shared state", and Appendix A assumes SDK storage ("SDKs SHOULD refuse a no-expiry cap unless the author has wired up durable storage"); python-sdk#3822 keeps memory only. The store holds webhook secrets. The SDK deletes an expired record when it next reads it, so the docs tell shared-store users to expire records themselves (a Redis TTL, for example).

Finite TTLs only. The server never grants refreshBefore: null; every grant is capped by webhookTtlMs. No-expiry also needs collection after sustained delivery failure and a store the author declares durable, so it is a follow-up on top of the store. That is why the two ttl-no-expiry conformance checks are baselined.

Callback URLs. nodeWebhookSender() requires https, resolves the host at every send, refuses IANA special-purpose addresses, follows no redirects and gives up after 5 seconds. trustedOrigins (Python's name for the same option) exempts exact origins from the https MUST and the private-address rule, for local development only.

Endpoint verification is rate-limited (SEP l.632). A failed verification is remembered for 60 seconds per principal and URL, and each callback host gets at most one verification in flight and ten per minute. Past that, events/subscribe answers ResourceExhausted with { limit: 'verification', retryAfterMs }. The limits are internal constants, not options.

Several replicas. With replicas sharing a WebhookSubscriptionStore, emit() reaches push streams and the poll buffer only on the process that emits; a webhook subscription's check loop may run on more than one replica (the SDK prefers a duplicate delivery to a missed one, and receivers dedupe by eventId); and onUnsubscribe for a lapsed subscription may fire on more than one replica. The docs say so.

Push under every response mode. events/stream streams even when createMcpHandler uses responseMode: 'json'. It sends no SSE comment keepalive: the Events heartbeat (heartbeatMs, 30 seconds by default) is the liveness signal (SEP l.381).

Mcp-Param on events/*. Clients mirror annotated subscription arguments into Mcp-Param-* headers (SEP e1794032), and the server validates them with the same code that serves tools/call.

Not in this PR: notifications/events/list_changed. The SEP makes it optional on both sides: the server's listChanged defaults to false, and a client receives the notification only if it opts in on subscriptions/listen. The server advertises {} and the client never opts in. Supporting it would mean adding eventsListChanged to the core SubscriptionFilter and a member to the public ServerEvent union. SEP-3371 rules out extensions adding filter fields to core streams, and the replacement shape is still open on #3415 (r4359154508). Conformance: the server suite passes. In the client suite, events-client-poll:sep-3415-client-listen-opt-in and events-client-poll:sep-3415-client-relist-on-list-changed are listed as expected failures, pending conformance#541 grading them only for clients that opt in. It will follow in a separate PR once the SEPs settle how the notification is delivered.

Open points.

  • Poll for event types that cannot replay. For a type whose check returns cursor: null, the SEP's "null means start from now", read literally, gives poll clients nothing. Here the first check call of a subscription only records where to start, and every later check(null) call delivers what happened since; push and webhook behave the same. In poll, that subscription is the poll lease, which the SEP keys on principal, event name and arguments. Clients sharing a lease (every caller on a server without authentication, or one user's two devices) split those events between them, and a lease that lapses between polls delivers nothing. Worth settling in the SEP.
  • Verification limit after a restart. When a server with the in-memory store restarts, a client's refresh becomes a new subscribe that must verify again. If the callback host's verification budget is spent at that moment, the client currently ends the subscription instead of retrying after retryAfterMs.

…ication rate limits, schema and address edges
Brings in #2820 (server and client extensions), #2370 (injectable logger), #2449 and #3153. Conflict in createMcpHandler.ts: the responseMode 'json' warning goes through logger.warn and names events/stream.
EventsExtension and EventsClientExtension implement #2820's ServerExtension and ClientExtension: setup(ctx) registers the events/* handlers through ctx.setRequestHandler and keeps the era gate, the events/stream streaming mark and the Mcp-Param header source. attach() is gone, with its connect check, one-per-server set and idempotence, which the extensions mechanism covers (duplicate id) or makes impossible (setup runs at construction). Call sites, docs, guide snippets, the changeset and typescript:events:attach:rules (now typescript:events:extensions:rules) follow.
@changeset-bot

changeset-bot Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 5ebb589

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages
Name Type
@modelcontextprotocol/core Minor
@modelcontextprotocol/core-internal Minor
@modelcontextprotocol/client Minor
@modelcontextprotocol/server Minor
@modelcontextprotocol/server-legacy Minor
@modelcontextprotocol/codemod Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@KKonstantinov KKonstantinov changed the title feat: MCP Events & Triggers feat: Events extension (SEP-3415) Nov 19, 2026
@KKonstantinov

Copy link
Copy Markdown
Contributor Author

@claude review

@pkg-pr-new

pkg-pr-new Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@3209

@modelcontextprotocol/codemod

npm i https://pkg.pr.new/@modelcontextprotocol/codemod@3209

@modelcontextprotocol/core

npm i https://pkg.pr.new/@modelcontextprotocol/core@3209

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@3209

@modelcontextprotocol/server-legacy

npm i https://pkg.pr.new/@modelcontextprotocol/server-legacy@3209

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@3209

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@3209

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@3209

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@3209

commit: 5ebb589

Comment thread packages/server/src/ext/events/node.ts Resolved
Comment thread packages/client/src/ext/events/push.ts Resolved
Comment thread packages/server/src/ext/events/poll.ts Resolved
Comment thread packages/server/src/ext/events/push.ts Resolved
Comment thread packages/server/src/ext/events/poll.ts Resolved
Comment thread packages/server/src/ext/events/poll.ts Resolved
- Push merges the event's _meta with the stream's subscription id instead of replacing it.
- Every interval the server sends is a wire-valid integer: nextPollMs from check is rounded up, clamped at 0 and capped at half of pollSubscriptionTtlMs; heartbeatMs, defaultNextPollMs and webhookTtlMs must be positive integers, and an explicit defaultNextPollMs above half the lease TTL throws.
- The client ends a push stream whose active fails its schema, and bounds the wait for the first active by the request timeout.
- A verification for a host with one in flight waits its turn (at most 10 waiting; a cancelled waiter leaves at once); the client retries resourceExhausted with limit 'verification' after retryAfterMs.
- With getPrincipal set, each principal (and the callers without one, together) holds at most a quarter of maxSubscriptions, refused as limit 'principalSubscriptions'.
- nodeWebhookSender resolves through a c-ares Resolver, cancelled at the deadline, instead of dns.lookup on the libuv thread pool.
- A new webhook subscription to an emit-only type replays the buffer from its cursor, and each body carries the event's own cursor once nothing before it is unsettled.
- Docs: poll limits for types without replay, the store keeps records a minute past expiresAt so onUnsubscribe runs, DNS resolution.
@KKonstantinov

Copy link
Copy Markdown
Contributor Author

@claude review

Comment thread packages/server/src/ext/events/node.ts Resolved
Comment on lines +503 to +506
#retry(tracked: Tracked, message: Message): void {
const delay = RETRY_DELAYS_MS[message.attempts - 1];
if (delay === undefined) {
this.#settle(tracked, message);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Webhook subscribers lose events without any signal when their endpoint fails for all five attempts of a message, about 7.5 minutes. #retry settles the abandoned message (webhookEngine.ts:506) and #settle moves the watermark past it. Later event cursors and the next refresh (truncated: false) carry the client past the loss. Fix: record that a message was abandoned and report it, by a gap body once a delivery succeeds or truncated: true on the next refresh, which covers the 4 sites listed. Same pattern at 4 sites (webhookEngine.ts:494, webhookEngine.ts:500, webhookEngine.ts:506, webhookEngine.ts:516).

Why this was flagged

A receiver answers non-2xx or times out for longer than RETRY_DELAYS_MS allows (attempts at 0, 5, 35, 155 and 455 s, webhookEngine.ts:14), then recovers. #retry finds no delay left and calls #settle (:505-506), which sets tracked.watermark = head.position (:525). The same happens for 410/413 (:543, :500), a body over 262_144 bytes (:488-494) and the parked overflow (:515-516). The next delivered event carries its own position as cursor (:486), and #refresh answers the watermark with a literal truncated: false (webhookSubscriptions.ts:392-393). The client stores both as its cursor (client webhook.ts:179, :297) and calls onGap only for truncated or a gap body. The only gap body sent is for a truncated check batch (webhookSubscriptions.ts:570). lastError and failedSince are cleared by the next 2xx (:536-538), so a later refresh shows nothing. Events is new, so the base has no such path.

Verification: At packages/server/src/ext/events/webhookEngine.ts:504-507, #retry finds delay === undefined after the fifth attempt and calls this.#settle(tracked, message). :520-527 #settle sets message.done = true and runs tracked.watermark = head.position, so an abandoned message is indistinguishable from an acknowledged one. The base branch has no webhook delivery, so this is new behaviour.

Finding ID: f-0ef704cb

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#retry now goes through #abandon (webhookEngine.ts:610, :533), but that only reports to the server's onerror; the subscriber still gets no signal. #abandon calls #settle, so the watermark still moves past the abandoned message (:630), the next delivered event still carries a cursor beyond it (:587), and #refresh still answers with a literal truncated: false (webhookSubscriptions.ts:395). tracked.abandoned is used only for throttling the operator report and is reset by #reportAbandoned. To close this, keep a per-subscription "lost since last signalled" flag set in #abandon (and the oversize-body path at :595), and surface it to the client by sendControl(record, { type: 'gap', cursor }) once a delivery succeeds or by returning truncated: true from the next refresh, clearing it only then.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The latest push brings this issue back at packages/server/src/ext/events/webhookSubscriptions.ts:397:

🔴 Webhook subscribers can still lose abandoned events with no gap report when the refresh response that carries truncated: true does not reach them. #refresh calls takeGap while building its result (webhookSubscriptions.ts:397), and takeGap clears the mark at once (webhookEngine.ts:317). The client's retried refresh then gets truncated: false and a cursor past the lost events. Fix: clear the mark only once the subscriber is known to have it, for example when a later refresh arrives carrying the cursor that answer returned; apply the same rule to #signalGap (webhookEngine.ts:677).

Why this was flagged

When a receiver was unreachable long enough for the engine to abandon events (#abandon sets tracked.gap = true, webhookEngine.ts:595), and the client's next events/subscribe refresh is processed by the server but its response is lost (the connection drops, a proxy times out, or the client's request timeout fires first). #refresh evaluates truncated: this.#engine.takeGap(id) (webhookSubscriptions.ts:397); takeGap sets tracked.gap = false before the result is sent (webhookEngine.ts:316-319). The SDK client retries the refresh; the second answer has truncated: false and cursor equal to the watermark, which #settle already moved past the abandoned events. The client stores that cursor and never calls onGap. #signalGap has the same shape: it clears the mark at webhookEngine.ts:677 before the gap control POST is acknowledged, and a control body that fails all its attempts is dropped.

Verification: takeGap sets tracked.gap = false before returning (packages/server/src/ext/events/webhookEngine.ts:314-320). Nothing in #refresh or subscribe() (webhookSubscriptions.ts:176-202) restores it if the response is not delivered. No other path re-signals the gap. Events is new in this PR, so the base has no such path.

Comment on lines +385 to +393
const from = params.cursor ?? null;
if (this.#engine.watermark(id) === undefined) this.#engine.track(id, from);
this.#engine.resume(id);
this.#keep(refreshed, entry, from);
return {
id,
refreshBefore: new Date(refreshed.expiresAt).toISOString(),
cursor: this.#engine.watermark(id) ?? null,
truncated: false,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 An app that restarts and resumes a webhook subscription from its saved cursor silently loses the events its old process had received but not finished. #refresh drops params.cursor whenever this process already tracks a watermark (webhookSubscriptions.ts:386). It answers the watermark with truncated: false. Fix: a subscribe whose cursor is not the watermark must get a replay from that cursor, as #create gives, or truncated: true, while the SDK client's periodic refresh, which sends its lagging cursor (client webhook.ts:273), does not trigger one each time. Poll and push replay from the saved cursor.

Why this was flagged

A client app in webhook mode persists subscription.cursor per event and is killed while handling one, with later events already POSTed and answered 200 by its receiver (packages/client/src/ext/events/receiver.ts:125-127). The new process calls subscribe({ name, arguments, cursor: saved }) within the grant. The server derives the same id (webhookSubscriptions.ts:182), finds the unexpired record and runs #refresh. Line 386 uses from only when this.#engine.watermark(id) === undefined, so the saved cursor is unused; lines 392-393 answer cursor: this.#engine.watermark(id) and truncated: false. The watermark already passed the acked events (webhookEngine.ts:520-527). The client's #accept stores that cursor and calls no onGap (client webhook.ts:296-297), so the unfinished events never reach the new loop. Events is new, so the base has no such path. No safeguard applies: the client dedupes but cannot ask for a replay.

Verification: Triggers when a webhook-mode client process dies without unsubscribing and a new process re-subscribes with its saved cursor inside the grant. #refresh uses the client's cursor only when no watermark is tracked (packages/server/src/ext/events/webhookSubscriptions.ts:386). So onGap never fires. Events is new in this PR, so the base has no such path.

Finding ID: f-1f771c1e

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The restart case is still silent. #refresh now answers truncated: this.#engine.takeGap(id) (webhookSubscriptions.ts:397), but the engine sets that flag only in #abandon (webhookEngine.ts:595). Events the old process's receiver answered 200 are settled normally, so the flag stays false. Line 389 still uses params.cursor only when no watermark is tracked, so the new process gets the watermark with truncated: false and onGap never fires. The sentence added to docs/clients/events.md describes the loss but does not signal it. To fix it, #refresh needs to compare params.cursor with the watermark and, when they differ, either replay from that cursor as #create does or answer truncated: true, without doing so on every periodic SDK refresh that sends a lagging cursor.

Comment thread packages/server/src/ext/events/poll.ts Resolved
Comment thread packages/server/src/ext/events/node.ts Resolved
… limits, stable eventId

- nodeWebhookSender fails a send whose deadline or cancel fires while one DNS family is still pending, and pins the connection to every checked address (by family when asked) instead of the first, so IPv6-only servers reach dual-stack receivers.
- The webhook engine runs at most 10 event POSTs per subscription at a time, for replay, resume and live bursts.
- check results must give every event an eventId; one without is dropped and reported. emit() still generates ids.
- The client falls back from push to poll when the first push exchange fails for a reason other than an EventsError and the app did not choose a mode.
- A refresh on any replica ends a suspension: the engine reactivates when the stored record's expiresAt moves past the one it saw at suspension.
- A failing store listing during an emit's fan-out is retried up to 3 times without delivering twice.
- Docs and the typescript:events:store:restart requirement describe restart behaviour as it is (check types resume at the next refresh, from the client's cursor), and the client docs say the receiver acknowledges once an event is queued.
- A message holds one of a subscription's ten slots only while a POST attempt is in flight; a retry queues for a slot when it is due, so a failing receiver suspends within about 100 attempts again.
- Messages waiting for a slot and parked messages share one cap of 10 000 per subscription; past it the oldest is abandoned.
- Events abandoned past the cap or after their fifth failed attempt are reported to onerror at once for the first, then at most once a minute per subscription with how many.
- Tests: the IPv6 fall-through resolves A to an unanswered TEST-NET address, the restart e2e runs on fake time with a bounded wait, and an invalid first active falls back to poll.
@KKonstantinov

Copy link
Copy Markdown
Contributor Author

@claude review

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Findings marked 🟡 are optional suggestions and need no follow-up push.

Still open from earlier reviews (4):

If you have decided not to act on one of these findings, resolve its thread (a reply alone leaves it open) and the next review stops counting it. To review this commit again now, use Re-run on its "Claude Code Review" check.

Comment thread packages/server/src/ext/events/push.ts Resolved
Comment thread packages/server/src/ext/events/node.ts Resolved
Comment thread packages/server/src/ext/events/push.ts Resolved
Comment thread test/e2e/scenarios/events.test.ts Resolved
Comment on lines +220 to +244
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);
}
});

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 nit (optional): CLAUDE.md's Minimalism principle prefers changes that add no API unless justified: the EventsExtension constructor installs a test hook on every shipped instance under Symbol.for('mcp.events.testHook') (restart, state, addTrustedOrigin, addSource, addFanOut), used only by unit tests and the conformance fixture. Fix: keep test-only controls out of shipped code: give tests what they need through constructor injection or a test-only build, and have the conformance fixture set trusted origins and restarts through public options.

Why this was flagged

Nothing fails at runtime. The principle guards the SDK's surface. Here packages/server/src/ext/events/extension.ts:220-244 gives every shipped EventsExtension a non-enumerable property, reachable through the global symbol registry by any code that holds the instance. Through it a caller can add a trustedOrigins entry after construction (which exempts that origin from the https and private-address rules), register extra fan-outs and sources, and drop all in-memory state. Code that exists only to serve it: #restarts and #generation in extension.ts, clear() on PollSource, EmitBuffer, LeaseTable, WebhookSubscriptions and WebhookEngine, StreamSet.closeAll() ('for a simulated restart'), and the 'Read at every send, so origins added later count' contract at webhookEngine.ts:43. It is deliberate: testHook.ts:20 calls it 'never part of the public API or its declarations' and registration.test.ts:320 pins it as non-enumerable. Its only users are test/conformance/src/events.ts:66 and four unit-test files.

Verification: Instruction: root CLAUDE.md at base 5ee54ee, principle 1, verbatim: "Minimalism — The SDK should do less, not more: prefer changes that add no API or option unless justified." REVIEW.md says to review by these principles, so it binds packages/server/src/ext/events/extension.ts.

Code: packages/server/src/ext/events/extension.ts:220-244, in a file this diff adds. The EventsExtension constructor calls installTestHook(this, {...}) unconditionally.

Finding ID: f-a1b4cbc2

…og and replica state

Client:
- An auth-seam error (UnauthorizedError from an authProvider, or a throwing token()) refuses the first exchange and ends a live subscription, instead of being retried with a fresh authorization redirect each time.
- Retried failures are reported to onerror, the first at once and then at most once a minute with how many; -32601 and -32602 end the subscription.
- A first exchange refused with unsupported deliveryMode re-lists once and selects again; an HTTP 5xx or 429 on the first exchange is retried like any transient failure.

Server:
- In every check batch, truncated or not, events before the last carry the cursor the batch was read from, and so does a truncated batch's own cursor, so no saved cursor passes an unsent event.
- The pinned lookup honours ADDRCONFIG: only families the host has a non-loopback, non-link-local interface address of, unless that leaves none.
- Events abandoned past the held cap, after the last retry, over the body size or answered 413 are signalled to the subscriber as a gap: a gap envelope at the watermark after the next acknowledged delivery, or truncated: true on the next refresh.
- A replica that only delivers for a subscription re-reads its record at expiresAt and drops the state once the record is gone, expired or re-created; a re-created record restarts the state instead.
- A push stream whose unread backlog passes 1 MiB is ended; the per-request transport exposes its queued byte count internally.

The restart e2e block uses fake setTimeout with a real clock so the client's refresh lands at three quarters of the 60 s grant before the grant can lapse, and a slow run cannot turn the refresh into a create.
@KKonstantinov

Copy link
Copy Markdown
Contributor Author

@claude review

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Findings marked 🟡 are optional suggestions and need no follow-up push.

Still open from earlier reviews (3):

  • Unresolved: 1 minor or pre-existing, 2 blocking on lines changed since (possibly already fixed).

If you have decided not to act on one of these findings, resolve its thread (a reply alone leaves it open) and the next review stops counting it. To review this commit again now, use Re-run on its "Claude Code Review" check.


// 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));

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 A single transient failure while fetching a token ends every Events subscription for good, where the same failure on the request itself is retried. endsSubscription (recovery.ts:22) treats any auth-seam stamp as final. The transport stamps every throw from authProvider.token() and onUnauthorized, whatever its cause (streamableHttp.ts:504-508, :1089-1092). Fix: end the subscription only for outcomes that need the user (an UnauthorizedError or a redirect); keep retrying with backoff when the stamped error is a network or 5xx failure from the token source.

Why this was flagged

A client uses an authProvider whose token() or onUnauthorized performs I/O, and that call fails once with a network error or an identity-provider 5xx while a subscription is live. streamableHttp.ts:504-508 catches the token() throw and calls markAuthSeamEscape(error). streamableHttp.ts:1089-1092 does the same for any throw from onUnauthorized. endsSubscription returns true for the stamp (recovery.ts:22), so recoveryFor answers 'fail' (recovery.ts:86) and DriverLoop.recover throws (recovery.ts:301). Every poll, push and webhook loop of that client ends on its next request. A plain fetch failed on the same events/poll is retried (recovery.ts:88). The stamp was adopted to stop the repeated redirect of the posted recovery.ts:89 finding, but it does not tell a redirect from a transient failure.

Verification: Triggers when an HTTP client with an authProvider holds an Events subscription and the token fetch or onUnauthorized fails once for a transient reason. packages/client/src/ext/events/recovery.ts:22: endsSubscription returns true for any isAuthSeamEscape(error). The tests added (poll.test.ts:417-438) only pin a stamped UnauthorizedError, not a transient throw.

Finding ID: f-d6899913

ended,
ctx: makeContext({
name: entry.name,
subscriptionId: globalThis.crypto.randomUUID(),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Push subscribers silently lose targeted events across a stream reconnect, while poll and webhook subscribers keep them. Each events/stream gets a new random subscriptionId (push.ts:270). selectEvent drops a buffered event whose target is another id (poll.ts:88), and the replay cursor still moves past it with no truncated. Fix: give a push subscription an id that survives a reconnect (as poll leases and webhook ids do), or report truncated when replay skips an event targeted at the stream's previous id.

Why this was flagged

An author calls handle.emit(event, { subscriptionId }) with the id its onSubscribe received, as types.ts:20 and docs/servers/events.md:76 describe, and the subscriber is on events/stream. The stream drops (proxy idle cut, dead-stream timer, network) and the SDK client reopens from its cursor (client push.ts:90-98, :124). StreamSet.#create assigns subscriptionId: globalThis.crypto.randomUUID() per request (push.ts:270), so the reopened stream has a new id. replayBuffer calls selectEvent for each buffered event (push.ts:148-156); poll.ts:88 returns undefined because target !== ctx.subscriptionId, yet position advances and truncated stays false. A targeted event written but lost in flight, or emitted to the old id during the reconnect delay, is never delivered and no onGap runs. Webhook ids are derived from principal, url, name and arguments (webhookSubscriptions.ts:185) and stay stable, so only push loses them. Events is new, so the base has no such path.

Verification: packages/server/src/ext/events/push.ts:270 sets subscriptionId: globalThis.crypto.randomUUID() for every events/stream request, so a reopened stream always has a new id. poll.ts:88 does not select the buffered event targeted at the old id. The cursor moves past the unselected event with no gap reported. Events is new in this diff, so the base has no such path.

Finding ID: f-0fdc71e9

while (!loop.ended) {
const { error } = await this.#open();
if (loop.ended) return;
if (error === undefined) loop.subscribed();

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Apps behind a proxy that buffers events/stream and closes it in under 60 s get a push subscription that never yields: no error, no fallback to poll. PushDriver.#run calls loop.subscribed() at push.ts:95 whenever a stream ends without an error, even before any active. That resolves subscribe() and clears loop.first, so the fallback at push.ts:112 can never run. Fix: give every stream that ends before a valid active an error ending, so the first one falls back to poll (or is retried and reported), while an end after active still reopens quietly.

Why this was flagged

Condition: a Streamable HTTP intermediary passes the 200 headers of events/stream, holds the body, and closes the response before the client's 60 s wait (DEFAULT_REQUEST_TIMEOUT_MSEC, push.ts:154). The transport calls onRequestStreamEnd (packages/client/src/client/streamableHttp.ts:862, :898), which _openStream maps to end({ cause: 'remote' }) with no error (packages/client/src/client/client.ts:2289). endingOf (push.ts:42-44) returns {}, so #run (push.ts:95) runs loop.subscribed() and EventsClientExtension.subscribe() resolves with deliveryMode: 'push'. From then on this.#fallback && this.#loop.first (push.ts:112) is false, and #attempt resets only in #active, so the driver reopens up to 30 s apart forever and the loop yields nothing. Events is new, so the base has no such call. No test ends a first stream before active (push.test.ts ends streams only after active).

Verification: packages/client/src/ext/events/push.ts:93-96: an errorless end never reaches #recover. packages/client/src/ext/events/recovery.ts:231-234: subscribed() sets #first = false and resolves start(), so subscribe() resolves as a push subscription. No guard covers the path.

Finding ID: f-19d66d1f

Comment on lines +331 to +335
// 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;
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Healthy push subscribers get disconnected when a server emits more than 1 MiB of events to their stream without yielding to I/O. #write (push.ts:332) ends the stream on one instantaneous reading of the unread byte count. The HTTP response cannot flush inside a loop of await handle.emit(), so that count only grows there. onUnsubscribe runs and the client has to reconnect and replay from the emit buffer. Fix: end a stream only when its backlog stays over MAX_STREAM_BACKLOG_BYTES over time, for example still over the limit on a later timer tick, so a burst to a client that is reading is not treated as a stalled client.

Why this was flagged

An author runs for (const item of items) await handle.emit(item) on an emit-only type, with enough items that the frames for one events/stream subscriber pass 1_048_576 bytes; nothing was run to reproduce this. Each emit reaches StreamSet.fanOut (push.ts:219) and #write, and the queued stream.notify ends in controller.enqueue (perRequestTransport.ts:459) with only microtasks in between. The reader stops pulling once res.write(chunk) === false until 'drain' (packages/middleware/node/src/toNodeHandler.ts:207-214), which needs an I/O turn, so -desiredSize (perRequestTransport.ts:132-136) passes MAX_STREAM_BACKLOG_BYTES and push.ts:332-334 calls #end(stream) for a client that reads normally. Before this push the stream stayed open; the base branch has no Events. No safeguard applies: docs/servers/events.md:96 describes the rule as a client that 'leaves more than 1 MiB unread'.

Verification: packages/server/src/ext/events/push.ts:332-335: #write reads stream.backlog() once and, above MAX_STREAM_BACKLOG_BYTES (push.ts:30, 1_048_576), calls void this.#end(stream) and returns. There is no time or stall component. The only test (push.test.ts:654-677) has the healthy stream read between emits, so it does not cover a burst.

Finding ID: f-57be5682

): Promise<Batch> {
const { events, truncated } = await checkedEvents(entry, result, maxAgeMs, report);
const last = events.length - 1;
const cursorAt = (index: number) => (index === last ? result.cursor : from);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Apps that subscribe with maxAgeMs to a check event type can now receive events older than that limit after a push stream reconnects mid-batch. checkedBatch (push.ts:106) keeps from on active and on every event but the last, also when maxAgeMs cut the batch. The client drops maxAgeMs at the first active (client recovery.ts:239), so the reopen sends from with no limit. Fix: keep sending maxAgeMs until the client's cursor has moved off the one it subscribed with, in push and webhook alike, for example by clearing it in setCursor on a changed cursor instead of in succeeded. [also at: packages/client/src/ext/events/recovery.ts:239 - Apps using maxAgeMs can still receive the old events it should skip, after a push stream drops partway through its first replay batch.]

Why this was flagged

A client calls events.subscribe({ name, cursor: 'h1', maxAgeMs: 300_000 }) and push is selected for a check type whose check returns one event older than 5 minutes and two newer ones with cursor: 'h2'. checkedEvents drops the old one and sets truncated (packages/server/src/ext/events/poll.ts:69-71), and checkedBatch sends active { cursor: 'h1', truncated: true } and the first event with cursor: 'h1' (packages/server/src/ext/events/push.ts:106-110). The client's #active calls loop.succeeded, which sets #maxAgeMs = undefined (packages/client/src/ext/events/recovery.ts:239). If the stream ends before the last event, #open sends cursor: 'h1' and no maxAgeMs (packages/client/src/ext/events/push.ts:121-126), so startCheck runs unfiltered and the over-age event reaches the app. The base branch has no Events. #seen does not help: the old event was never delivered.

Verification: packages/server/src/ext/events/push.ts:106: lines 108-110 put from on active and on every event but the last, regardless of truncated. packages/client/src/ext/events/recovery.ts:239: this.#maxAgeMs = undefined; on that first success. packages/client/src/ext/events/subscription.ts:155: the queue de-duplicates by eventId only.

Finding ID: f-0e3a1bc9

id,
principal,
name: entry.name,
arguments: args,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Webhook subscriptions break under a shared store when an event type's inputSchema transforms arguments into a Date, Set, Map or bigint. #create writes the schema output to record.arguments (webhookSubscriptions.ts:297). The guide's store saves records as JSON, so check, match and onUnsubscribe later get strings or {} where their types promise the output. Fix: hand those callbacks the schema output whatever the store does, e.g. store the raw client arguments and run entry.parseArguments when a record is read, which covers the 3 sites listed. Same pattern at 3 sites (webhookSubscriptions.ts:519, :542, :584).

Why this was flagged

An author registers inputSchema: z.object({ tags: z.array(z.string()).transform(t => new Set(t)) }) with match: (ctx, event, { tags }) => tags.has(event.data.tag), turns webhook delivery on and passes the webhookStore from docs/servers/events.md:145-171, which does JSON.stringify(record) and JSON.parse(json) as WebhookSubscriptionRecord. #create stores arguments: args, the parsed output (webhookSubscriptions.ts:297). #deliverEmitted passes record.arguments from listByName to selectEvent (:542). After the round trip the Set is {}. match throws, and selectEvent reports it and skips the event (poll.ts:101-104), so nothing reaches the webhook. Poll, push and the default InMemoryWebhookSubscriptionStore keep the output in memory and work, so this shows only with a shared store. Events is new, so the base has no such path. No safeguard applies: WebhookSubscriptionRecord.arguments is Record<string, unknown> (types.ts:251) and no doc says it must survive serialisation.

Verification: Triggers when an event type's inputSchema outputs a non-JSON value and the webhookStore serialises records, as the guide's store does. webhookSubscriptions.ts:297 writes the schema output to the record, and :542 passes record.arguments to selectEvent, so every emitted event is dropped. No guard exists: there is no re-parse on read. Events is new in this PR, so the base has no such path.

Finding ID: f-3f505fb9

failures = 0;
this.#deliver(result);
loop.subscribed();
if (result.hasMore !== true) await loop.sleep(Math.max(result.nextPollMs ?? this.#floorMs, this.#floorMs));

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Poll subscribers can send back-to-back events/poll requests without end and receive no events. PollDriver.#run (poll.ts:48) polls again at once on every hasMore: true, with no floor and no limit on repeats. The SDK server answers a cursor from another replica with no events, truncated: true and hasMore: true (emitBuffer.ts:89), so two replicas that both hold emitted events bounce the client between them. Fix: re-poll at once only when the page made progress, and otherwise wait the floor, for example when hasMore comes with no events or with truncated, while a full page with hasMore still re-polls at once.

Why this was flagged

Condition: two or more replicas of an SDK server behind a per-request load balancer, each of which called emit() for the same emit-only type within the buffer's 10 minutes; docs/servers/events.md:190-192 describes this deployment. Each EmitBuffer has its own random epoch (emitBuffer.ts:30-32, :134-137). A poll that carries replica A's cursor to replica B fails #parse (emitBuffer.ts:143-148), so read returns { events: [], cursor: <B's oldest>, truncated: true, hasMore: position < ring.last } (emitBuffer.ts:87-90), and handlePoll forwards it (server poll.ts:166-176). The client stores that cursor, calls onGap, and skips loop.sleep because hasMore is true (client poll.ts:44-48). The next poll lands on A with B's cursor and gets the same answer. Under round-robin routing no poll ever carries a valid cursor, so the loop runs at network speed and yields nothing. pollIntervalFloorMs does not apply to hasMore. Events is new, so the base has no such loop.

Verification: Triggers when a poll subscriber's consecutive events/poll requests land on different replicas of an SDK server and each replica holds buffered emit-only events for that type. On hasMore: true the loop at packages/client/src/ext/events/poll.ts:48 re-polls at once, with no progress check, no repeat cap and no backoff. The defect is new in this PR; the base has no Events code.

Finding ID: f-fe8280d1

Comment on lines +218 to +223
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)
);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 On servers with a shared webhookStore, emitting faster than the store can list subscriptions grows memory and webhook delay without limit. fanOut (webhookSubscriptions.ts:221) chains one listByName pass per event onto the #byName queue, and emit() does not wait for it. Fix: bound that queue for every event type, for example one listing pass for all queued events, abandoning the oldest past a cap with a gap and an onerror report. New webhook subscribes to the type wait behind the same queue (webhookSubscriptions.ts:358).

Why this was flagged

Condition: webhookTtlMs, webhookSender and a remote webhookStore are set, and an emit-only type is emitted faster than one store listing per event; this population cannot be enumerated from the checkout. EventsExtension.#emit awaits webhooks.fanOut, which returns void (extension.ts:395-403), so handle.emit() resolves at once. fanOut calls enqueue(this.#byName, name, ...) (webhookSubscriptions.ts:221) and each task awaits store.listByName(name) (:534, :558), also for a type with delivery: { webhook: false } or no webhook subscriber. The guide's store reads every record per listing (docs/servers/events.md:163-169). Tasks, each holding its event, pile up with no cap: emitBuffer.maxEvents and MAX_HELD_MESSAGES (webhookEngine.ts:19) do not cover them, and nothing reaches onerror. #startEmitOnly queues on the same key (:358), so a create answers only after the backlog, past the SDK client's 60 s request timeout. Events is new, so the base has no such path. This is not the failed-store-read drop: the fix is a bound, not a retry. Nothing was run.

Verification: Triggers when a server with a remote webhookStore emits one event type faster, sustained, than one store listing per event completes. fanOut (packages/server/src/ext/events/webhookSubscriptions.ts:218-224) returns void and chains one task per event; enqueue (:94-105) has no length cap, coalescing or drop. No guard found. Events is new in this PR, so the base has no such path.

Finding ID: f-38f4f433

/** 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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 nit (optional): Apps are told onGap receives the fresh cursor, but after a truncated check batch that still has events it gets the cursor they already sent. checkedBatch puts from on that active frame and on the webhook subscribe result (server push.ts:108), and the client hands it to onGap (recovery.ts:243). Fix: make the words true for every truncated path, for example describe it as the cursor delivery continues from, in subscription.ts:24 and docs/clients/events.md:67. [also at: packages/client/src/ext/events/subscription.ts:25 - nit: onGap is documented as receiving the fresh cursor, but in push and webhook mode it can now get the stale cursor the client already sent.; docs/clients/events.md:67 - nit: The client guide and the onGap JSDoc say onGap receives the fresh cursor, but for a check type on push or webhook it now receives the cursor the client already had.]

Why this was flagged

Nothing fails at runtime. A check returns truncated: true with events, or maxAgeMs skips older ones, on a push stream or a webhook subscribe. checkedBatch (packages/server/src/ext/events/push.ts:106-108) sets cursor: cursorAt(-1), which is from when the batch has events. The client's #active passes it to loop.succeeded (packages/client/src/ext/events/push.ts:215) and #accept does the same (webhook.ts:296); succeeded calls reportGap(..., cursor) (recovery.ts:243), so onGap gets the cursor the app subscribed with, not a new one. subscription.ts:24 says 'Called with the fresh cursor' and docs/clients/events.md:67 says 'onGap receives the fresh cursor'. Poll still passes result.cursor, and before commit 5ebb589 a truncated push batch did too. packages/server/test/ext/events/push.test.ts:227 and :248 pin the active cursor at the batch start, so this is deliberate in code and only the words are stale.

Verification: A check type returns truncated: true together with events on a push stream or a webhook subscribe. packages/server/src/ext/events/push.ts:105-108 sets cursor: cursorAt(-1): with one or more events, -1 !== last, so the batch cursor is from, not result.cursor. recovery.ts:243 passes it to onGap, while subscription.ts:24 says "Called with the fresh cursor".

Finding ID: f-ce6393a7

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant