From f225a0abedce8b7c974e29b2aa3833dee3a310ad Mon Sep 17 00:00:00 2001 From: am <6e30cd56c30e030cd31bb0939b94a7c257c9a09d5ba2d92cf2735da45629f248@buzz.block.builderlab.xyz> Date: Wed, 23 Sep 2026 14:50:48 -0700 Subject: [PATCH] docs: tighten websocket thread-window failure rules Co-authored-by: Kalvin Chau Signed-off-by: Kalvin Chau --- docs/nips/NIP-CW.md | 25 +++++++++---------------- 1 file changed, 9 insertions(+), 16 deletions(-) diff --git a/docs/nips/NIP-CW.md b/docs/nips/NIP-CW.md index 68af11ece9..77325ae498 100644 --- a/docs/nips/NIP-CW.md +++ b/docs/nips/NIP-CW.md @@ -250,13 +250,9 @@ the head page. Unknown fields, malformed values, and mixing thread windows with another query mode MUST be rejected. A query MAY contain at most four window filters. -On WebSocket REQ, invalid thread-window extensions that reach the window -validator terminate the named subscription with `CLOSED invalid:`. Malformed -standard NIP-01 filter fields (for example `until: -1`, `kinds: [70000]`, or -`limit: "x"`) can fail typed filter deserialization earlier and receive a -connection-level `NOTICE` instead; clients MUST NOT wait indefinitely for EOSE -or CLOSED after a parse failure. A missing or invalid bounds overlay still -makes a page unusable. +On WebSocket `REQ`, invalid window fields return `CLOSED invalid:` after filter +parsing. Malformed NIP-01 fields may instead fail parsing with `NOTICE`; neither +response is a usable page. ### Relay Processing @@ -308,15 +304,12 @@ allowance even at `limit: 1`; blind retries of the same query will not help. For timeouts or changed access, retry with bounded backoff and fresh access. These errors MUST NOT trigger legacy compatibility fallback. -A WebSocket thread-window page is complete only after its request-bound bounds -and EOSE arrive. If any EVENT or the terminal EOSE cannot be enqueued, the relay -cancels that connection rather than silently leaving a finite request pending; -a Close frame is best-effort and may not reach a stalled reader. Clients MUST -abandon the entire incomplete batch, retain their previous cursor, and retry -with a fresh request ID and bounded backoff after disconnect or timeout. A client -MUST also impose its own deadline and surface persistent failure rather than -wait forever or fall back to legacy pagination. This relay capability does not -itself enable thread-window pagination in desktop or mobile clients. +On WebSocket `REQ`, a page is complete only with valid request-bound bounds +and `EOSE`. If an `EVENT` or `EOSE` cannot be queued, the relay cancels the +connection; the Close frame is best-effort. On disconnect or timeout, clients +MUST discard the incomplete batch, retain the prior cursor, and retry with a +fresh request ID and bounded backoff. Clients MUST bound the wait and surface +persistent failure, not fall back to legacy pagination. ### Thread Bounds: `kind:39007`