feat(nip-01): send the rate-limited backoff hint on CLOSED (the half of nostr-protocol/nips#2498 the relay does not send)

Start with src/utils/messages.ts and src/@types/messages.ts for the existing OK and CLOSED patterns, then compare the read gates in src/adapters/web-socket-adapter.ts and src/handlers/subscribe-message-handler.ts. Decide which gate should emit the hint, since the issue describes two options and neither currently sends CLOSED for rate limiting. Add the constructor and wire-frame tests described in the issue, including the relay probe check; done means a rate-limited CLOSED carries the optional milliseconds parameter and existing behavior remains covered.

feat(nip-01): send the rate-limited backoff hint on CLOSED

nostr-protocol/nips#2498 ("Add an extra parameter to the CLOSED and OK messages") appends an optional trailing parameter to both messages:

• ["OK", <event_id>, <true|false>, <message>, <?params>]
• ["CLOSED", <subscription_id>, <message>, <?params>]

rate-limited is the one pair the PR standardizes: a zero-free decimal string of a positive integer in milliseconds, read as "back off this long before sending the relay the same message type that tripped the limit". It MAY be approximate, and its absence MUST NOT be read as an instruction to retry immediately. The text's own example for this side: ["CLOSED", "sub1...", "rate-limited: slow down there chief", "2500"].

Half of it shipped; this is the other half

PR #807 implemented the OK side and shipped it in 3.3.0 — createCommandResult (src/utils/messages.ts:32) now takes params?: string, and the hint is Math.max(1, Math.ceil(period)) ms of the first rate-limit window that tripped. It closed #805 with its own body stating the boundary: "CLOSED is untouched, since nostream never sends rate-limited on it."

That statement is still true on main (4cf419f), and so is the plumbing gap:

• createClosedMessage (src/utils/messages.ts:43) builds a fixed [CLOSED, queryId, reason].
• ClosedMessage (src/@types/messages.ts:89-93) declares 0, 1, 2 and no optional 3.

Can nostream support it? The message is a one-parameter change; the message source is the gap

Adding the parameter is the same shape #807 already did for OK — one optional argument on a shared helper and its type. What does not exist is any site that would emit it, because nothing that gates a read answers with a CLOSED today. Verified on main 4cf419f:

So the parameter has nowhere to attach, and the NIP's wording makes this a design call rather than plumbing: the value means "back off the same message type that tripped it", while nostream's read-side throttle is message-type-agnostic and sits above the handler (the event.rateLimits limiter from #807 is write-only — REQ/COUNT never touch it).

Two honest options:

1. Speak CLOSED from the existing read-side throttle when the message is a REQ — src/adapters/web-socket-adapter.ts:203-204 has the subscription id in hand as message[1] before dispatch. Cheapest, but it changes a frame every client already sees, and the limiter would need a per-message-type prefix.
2. Add a REQ-scoped limiter in the subscribe handler, beside the existing auth CLOSED at src/handlers/subscribe-message-handler.ts:68, so the value means what the NIP says it means: this subscription class, this window.

Either way, the emission site is roughly five lines next to a precedent that already exists, plus the helper/type change.

Related, and worth separating

The argument for the parameter in the PR thread (jb55, from the strfry side) is that the hint only helps if the cut-off is visible: a relay that stops delivering a REQ's stored events early should end with CLOSED "rate-limited: ..." and MUST NOT send EOSE, because a client that received some EVENTs and then EOSE cannot tell a short result from a complete one. Nostream's stream ends at EOSE (src/handlers/subscribe-message-handler.ts:208,237). That is a different behaviour from the parameter and deserves its own issue if it is wanted — it is flagged here only because it is the case that makes the CLOSED parameter worth having.

Testing

• Constructor: 3-element output when no hint, 4-element when present (the OK tests from #807 are the model).
• Whichever site is chosen: a case asserting the wire frame, including that a client reading only [0..2] is unaffected.
• src/utils/relay-probe/ws-protocol-probe.ts:253 reads response[2] of a CLOSED — trailing elements must not confuse it.

Effort

Small and self-contained: one optional parameter through createClosedMessage/ClosedMessage, and one emission at a read gate. The work is deciding which gate, since none of them speaks CLOSED today.