Add stateless subscriptions example with listen-based e2e (#13)

Supersedes #9 (approved there; GitHub closed it when #8's base branch
was deleted, and a rebased head cannot be reopened). Identical content
rebased onto main after #8's squash-merge — the review threads and
approval live on #9.

---

Stacked on #8 (go-sdk v1.7.0 bump) — the follow-up it deferred.

Adds `examples/subscriptions/cmd/subscriptions-stateless`: the tasks
subscription wiring served with `StreamableHTTPOptions{Stateless: true,
PropagateRequestCancellation: true}` — the deployment shape for
horizontally scaled servers behind a plain round-robin load balancer,
and the only mode in which the Go SDK speaks protocol revision
2026-07-28.

## What the e2e suite pins

- **2026-07-28 negotiated over plain HTTP** via `server/discover` (the
connect helper fails if a session ever falls back below it), with normal
tool round-trips.
- **Listen-based subscription delivery**: `resources/subscribe` doesn't
exist on this path — `ClientSession.Subscribe` opens a per-URI
`subscriptions/listen` stream, the server's `SubscribeHandler` still
fires per URI (same ACL gate as the legacy path), and `ResourceUpdated`
pushes flow back over the stream. Two concurrent clients on the same URI
prove per-connection fan-out.
- **Teardown**: `Unsubscribe` ends the listen stream,
`UnsubscribeHandler` fires, and further mutations deliver nothing.
- **`PropagateRequestCancellation`**: aborting the HTTP request mid-call
cancels the in-flight handler context (proven with an instrumented
blocking tool).
- **Legacy coexistence**: the same stateless endpoint still answers a
classic `initialize` from pre-2026 clients (echoing their requested
version), and GET is rejected with 405/`Allow: POST` per the stateless
contract.

Subscription registration is asynchronous under `subscriptions/listen`
(the client dispatches without awaiting), so delivery tests mutate in a
poll loop until the notification arrives rather than mutating once — the
suite passed three consecutive `-race -count=3` runs with no flakes.

Docs: new "Serving stateless" section in
`examples/subscriptions/README.md` (why no session affinity is needed:
subscription state lives on the connection; a dropped stream is
re-issued by the client to whichever replica answers next; feed every
replica from a shared event source), plus main README examples-table and
cmd-list entries.

## Verification

- `go test -race -count=1 ./...` green (new suite: 6 tests, also run at
`-count=3` for flake detection)
- `golangci-lint run` 0 issues; `go mod tidy` no-op (no new
dependencies)

---------

Co-authored-by: Jiacheng Xu <xjcmaxwellcjx@gmail.com>

Author: yhxlele

.golangci.yml

@@ -52,6 +52,10 @@ linters:
         - fieldalignment  # prioritise readability over struct-field packing
     misspell:
       locale: US
+      ignore-rules:
+        # MCP's own protocol vocabulary: the wire method is
+        # notifications/cancelled and the SDK exports CancelledParams.
+        - cancelled
     nakedret:
       max-func-lines: 30
     revive:

README.md

@@ -383,7 +383,7 @@ There are two common shapes:
 
 2. **Wrap an external source.** Real handlers that start/stop upstream delivery per subscription (open a gRPC stream, run a PG `LISTEN`, subscribe to a Redis/Kafka topic, register a webhook). Best when events come from outside the process. Still call `ResourceUpdated` on each incoming event.
 
-[`examples/subscriptions`](examples/subscriptions) ships both as runnable demos: `cmd/subscriptions-simple` for the push-from-write-path pattern (about 30 lines of wiring) and `cmd/subscriptions` for the external-source pattern, with per-principal subscribe authorization and a watcher wrapped in `protomcp.RetryLoop`.
+[`examples/subscriptions`](examples/subscriptions) ships all of this as runnable demos: `cmd/subscriptions-simple` for the push-from-write-path pattern (about 30 lines of wiring), `cmd/subscriptions` for the external-source pattern with per-principal subscribe authorization and a watcher wrapped in `protomcp.RetryLoop`, and `cmd/subscriptions-stateless` for the stateless serving shape where ≥ 2026-07-28 clients subscribe via `subscriptions/listen` with no session affinity anywhere.
 
 ### `protomcp.v1.prompt`, method option
 
@@ -464,7 +464,7 @@ Each example is standalone, runnable, and has its own README.
 |---|---|
 | [`examples/greeter`](examples/greeter) | Tool primitive surface, unary + server-streaming RPCs, progress notifications with monotonic counter, **progress-token gRPC-metadata propagation**, `ToolErrorHandler`, `ToolResultProcessor` redaction, `ToolMiddleware` request mutation, SDK options pass-through, **`field_schema.exclude` schema masking round-trip** |
 | [`examples/tasks`](examples/tasks) | **Every declarative MCP primitive end-to-end.** Tools with `read_only` / `idempotent` / `destructive` hints + `OUTPUT_ONLY` stripping, **two `resource_template` annotations (`tasks://{id}`, `tags://{id}`)**, **a single `resource_list` that enumerates both types via `{type}://{id}` with `OffsetPagination`**, **prompts (`tasks_review`)**, **elicitation (confirm `DeleteTask`)**, plus `@example` markers and `enumDescriptions` on `TaskStatus` |
-| [`examples/subscriptions`](examples/subscriptions) | **User-wired resource subscriptions** on top of the Tasks resource template. Per-principal subscribe authorization in `SubscribeHandler`/`UnsubscribeHandler`, plus a watcher wrapped in `protomcp.RetryLoop` pushing `ResourceUpdated`. Race-tested. |
+| [`examples/subscriptions`](examples/subscriptions) | **User-wired resource subscriptions** on top of the Tasks resource template. Per-principal subscribe authorization in `SubscribeHandler`/`UnsubscribeHandler`, plus a watcher wrapped in `protomcp.RetryLoop` pushing `ResourceUpdated`. Also the **stateless serving shape** (`Stateless` + `PropagateRequestCancellation`): protocol ≥ 2026-07-28 with `subscriptions/listen`-delivered subscriptions and no session affinity. Race-tested. |
 | [`examples/auth`](examples/auth) | Two-layer auth: SDK-native bearer middleware **or** custom HTTP middleware, both writing gRPC metadata for the upstream |
 
 Cmd directories inside each example hold the runnable binaries:
@@ -477,6 +477,7 @@ Cmd directories inside each example hold the runnable binaries:
 - [`examples/greeter/cmd/sdkopts`](examples/greeter/cmd/sdkopts), pass `mcp.ServerOptions` / `mcp.StreamableHTTPOptions`
 - [`examples/tasks/cmd/tasks`](examples/tasks/cmd/tasks), CRUD
 - [`examples/subscriptions/cmd/subscriptions`](examples/subscriptions/cmd/subscriptions), authorization-gated subscribe wiring
+- [`examples/subscriptions/cmd/subscriptions-stateless`](examples/subscriptions/cmd/subscriptions-stateless), stateless serving + `subscriptions/listen` delivery (protocol ≥ 2026-07-28)
 - [`examples/auth/cmd/auth`](examples/auth/cmd/auth), custom HTTP middleware → ctx → metadata
 - [`examples/auth/cmd/sdkauth`](examples/auth/cmd/sdkauth), MCP Go SDK's `auth.RequireBearerToken` → `TokenInfoFromContext` → metadata
 

examples/subscriptions/README.md

@@ -195,6 +195,100 @@ resources push from internal code and others need an external watch.
 Return `nil` for push-path URIs (no-op) and open the external watch
 only for URIs that need it.
 
+## Serving stateless (protocol ≥ 2026-07-28, no session affinity)
+
+`cmd/subscriptions-stateless` runs the same subscription wiring with
+
+```go
+protomcp.WithHTTPOptions(&mcp.StreamableHTTPOptions{
+    Stateless:                    true,
+    PropagateRequestCancellation: true,
+})
+```
+
+Stateless mode is the shape for horizontally scaled servers behind a
+plain round-robin load balancer — and it is the only mode in which the
+Go SDK speaks protocol revision 2026-07-28, where `resources/subscribe`
+is replaced by `subscriptions/listen`: one long-lived POST whose
+response stream carries the notifications. Subscription state lives on
+that connection, not in a server-side session map, so no affinity
+mechanism is needed: any replica can serve any request, and the replica
+holding a listen stream delivers to it. Your `SubscribeHandler` /
+`UnsubscribeHandler` fire per URI exactly as in the other patterns —
+`subscriptions/listen` routes through the same gate — and the push
+side (`ResourceUpdated`) is unchanged; in a multi-replica deployment,
+feed every replica from a shared event source so whichever one holds a
+given stream can deliver. One asymmetry to guard: a legacy
+`resources/subscribe` also reaches the gate on a stateless server, but
+its per-POST session dies with the response — the subscription could
+never deliver, and go-sdk tears the session down without firing
+`UnsubscribeHandler`, so any gate-side bookkeeping (the demo's
+heartbeat refcount included) leaks +1 with no matching -1. The demo
+rejects those legacy lifecycle RPCs outright
+(`requireListenScopedSubscription`): only `subscriptions/listen`
+subscriptions, whose params carry the SEP-2575 `_meta` protocol version,
+are accepted.
+
+**A dropped listen stream is not replaced, and the loss is silent.** On
+go-sdk v1.7.0, streams on this protocol carry no SSE event IDs, and the
+client abandons a POST stream whose connection dies without one instead
+of retrying it; because `subscriptions/listen` is dispatched
+fire-and-forget, the synthesized `request terminated without response`
+error is discarded, so no error surfaces to the application. A later
+`ClientSession.Subscribe` for the same URI is a no-op while the client
+still believes it is subscribed (and a `Subscribe` whose initial listen
+call fails leaves the same stale entry behind), so a dead subscription
+cannot be repaired in place by subscribing again.
+
+Detection has to ride each watched URI's own stream:
+`ClientSession.Subscribe` opens a separate `subscriptions/listen` POST
+per URI, so a dedicated heartbeat resource attests only its own stream
+and can keep beating while the stream for the URI you actually watch
+is already dead. To notice a dead stream, have the server emit a
+periodic update for every watched URI and treat a missed heartbeat as
+that stream's death — at the cost of one update (and, since a
+heartbeat is indistinguishable from a real change, one re-read) per
+URI per interval. The stateless demo implements this: `watchHeartbeat`
+refcounts watched URIs from the subscribe/unsubscribe gate and touches
+each one on the `-heartbeat` interval (default 30s, `0` disables). Periodic re-reads of the watched resource remain a
+reconciliation fallback, not a liveness check: each read is its own
+stateless POST and succeeds whether or not the listen stream is alive,
+so polling bounds how stale a client can silently become, but an
+unchanged resource reveals nothing and a dead stream goes undetected.
+
+Recovery is session-scoped on go-sdk v1.7.0. The natural per-URI cycle
+— `Unsubscribe` to clear the client-side entry, then a fresh
+`Subscribe` — does not survive contact with the implementation:
+canceling the listen call makes the client send a
+`notifications/cancelled` POST without the
+`_meta["io.modelcontextprotocol/protocolVersion"]` the 2026-07-28
+protocol requires on every message (`cancelCall` skips the
+`injectRequestMeta` step every other client send performs), the server
+rejects it (`-32602` over HTTP 400), and the client treats the failed
+send as fatal and permanently fails the connection. From that point
+every awaited call returns `connection closed` and every
+fire-and-forget send — a re-`Subscribe` included — vanishes silently;
+canceling any in-flight request poisons the session through the same
+path. Until that is fixed upstream, recover by replacing the session:
+close the poisoned `ClientSession`, `Connect` a fresh one (any replica
+answers), re-`Subscribe` every watched URI, and re-read each one to
+reconcile updates missed while dark. The e2e suite pins both halves —
+the poisoning and the reconnect recovery.
+
+`PropagateRequestCancellation` ties each in-flight handler context to
+its HTTP request, so a client that goes away mid-call cancels the
+handler instead of leaving it running for nobody. (The SDK forces this
+on for `subscriptions/listen` requests regardless — a listen handler
+blocks until its request ends.)
+
+The e2e suite in `cmd/subscriptions-stateless/main_test.go` pins the
+whole contract: 2026-07-28 negotiated over plain HTTP, listen-based
+delivery to concurrent clients, unsubscribe teardown, heartbeats
+arriving with no mutation at all, the Unsubscribe poisoning and its
+reconnect recovery, handler cancellation on request abort, and the
+same endpoint still answering a classic `initialize` from pre-2026
+clients.
+
 ## Running the demos
 
 ```shell
@@ -203,6 +297,11 @@ go run ./examples/subscriptions/cmd/subscriptions-simple -addr :8080
 
 # Pattern B: watch stream + authz (requires a bearer token)
 go run ./examples/subscriptions/cmd/subscriptions -addr :8080
+
+# Stateless: same push wiring, Stateless + PropagateRequestCancellation,
+# subscriptions arrive via subscriptions/listen (protocol >= 2026-07-28);
+# -heartbeat touches every watched URI on an interval for stream liveness
+go run ./examples/subscriptions/cmd/subscriptions-stateless -addr :8080 -heartbeat 30s
 ```
 
 Point any MCP client at `http://localhost:8080`. For Pattern B,