feat(pull): name the push server's refusal codes, and record them in the lab

[IgorShevchik]

What

An audit of the push-server sources on an on-prem stand answered the open questions from #559. This lands the parts that are code, and — after a five-reviewer pass — states carefully what the audit does and does not establish.

1. The refusal codes

A publish the push server refuses is not answered and does not error. It closes the WebSocket with a code and a reason string. CloseReasons knew one of them, 4010.

Eleven added, separated by meaning rather than by numeric range:

Code	Name	Kind
4013	WRONG_REQUEST_DATA	frame — decode threw, or requests empty
4014	REQUEST_COMMAND_NOT_ALLOWED	frame
4015	WRONG_REQUEST_COMMAND	frame
4016	TOO_MANY_MESSAGES	frame — > 100
4017	NO_CHANNELS_FOUND	frame — receivers empty
4018	TOO_MANY_CHANNELS	frame — > 100
4019	INVALID_CHANNEL_ID	frame — trusted connections only
4020	PRIVATE_CHANNEL_NOT_ALLOWED	frame — isPrivate was true
4021	INVALID_CHANNEL_SIGNATURE	frame — HMAC did not verify
4012	NO_PUBLIC_CHANNEL_ID	connection
4029	TOO_MANY_CONNECTIONS	connection

4010, 4012 and 4029 share the range but are connection-level, so a caller testing "is it 401x, my publish failed" would misclassify all three. Hence isFrameRefusalCloseCode(). The docblock also marks direction: everything below 4010 is a code the client passes to disconnect(), and none of the new ones may be used that way.

2. The lab records closures — and says what they are worth

A close listener beside the frame tap. The export gains socketClosures (each entry with frameRefusal) and encodeWindow — check 9's start and end, because checks[].ms is a duration, so the report previously invited a correlation it gave the reader no way to make. Closures reset per run and are capped like the other collectors.

The absence of a close code proves nothing, and every surrounding text now says so. Only a structurally unparseable frame trips 4013; a scalar written at the wrong field number parses cleanly, is broadcast with an empty body, and yields no close code and no echo — exactly what a warn looks like. A closure inside the window is correlation, not cause, on a connection shared with subscriptions and heartbeats; and the tap runs off a 2-second poll, so a socket opened and closed between ticks is never seen.

3. The schema: examined, not closed

The audit reports field numbers matching ours on the send side, verified here against protobuf/model.js (Receiver.encode, tags 10/16/26) and protobuf-lite/messages.ts (writeReceiver):

message Receiver { bytes id = 1; bool isPrivate = 2; bytes signature = 3; }

An earlier revision of this PR called that "R1 closed". It should not have. The doc now carries the provenance with the claim:

• the report is not in this repository and cannot be checked from it;
• it names the stand as push-server 2.0.0, while this document uses "push-server version" to mean the protocol number and pins protobuf to exactly 4. Which axis that is cannot be determined from here;
• the stand had publishing disabled, so the publish path it describes was not exercised there;
• only Receiver is quoted. The three nesting field numbers the encoder hardcodes come from request.proto, unreproduced, and nothing was said about OutgoingMessage, Sender, ResponseBatch or the oneof — which is where the doc's own worked example (fixed32 vs sfixed32) lives.

4. The exit criterion, split by what a deletion moves

• R1 — is the schema right? Equally wrong in both implementations, so deleting one moves it not at all. That, not the audit, is why it does not gate the deletion.
• R2 — does the lite codec agree with model.js? Open. Closable by fuzzing, no portal.
• R3 — does it behave like the library where the schema is silent? New, and invisible to both a .proto audit and a byte-for-byte differential on well-formed input. readSender is the worked example: returning {} instead of proto3 defaults threw inside decodeId and took the whole batch with it.

Also recorded: the echo question is settleable without trusting any server-side claim — a second tab subscribed to SubscriptionType.Client receiving the first tab's publish distinguishes "server excludes the sender" from "the frame was refused".

5. Corrections the audit prompted, verified against this code

isPublishingEnabled() is serverVersion > 3 && publish_enabled — nothing gates publishing on being an application. So skills/b24jssdk-helpers/SKILL.md's "The Pull client only RECEIVES / there is no client-side send in an application" and the migration note's "the only one that works there" were false, not merely imprecise. Both corrected; the guidance (publish from the back end) stands, only the stated reason changed. sendMessageToChannels() never makes the lookup at all, which the skill now says.

pull.proto records that the server reads only requests[0] of a batch, where the schema says repeated.

96.error-codes.md's JSSDK_PULL_SEND_REFUSED row now points at the close codes — deliberately not adding them to that table, since they never reach a caller as an error.

Review

Five reviewers. Findings acted on: the "R1 closed" overreach and its provenance (reviewer 4), the enum's mixed directions and the false "401x = publish refused" generalisation (2, 4), socketClosures not resetting and uncapped (1, 5), no way to correlate with check 9 (1), the server-authored reason entering the export unbounded and unflagged (5), the self-contradiction left at pull-protobuf.md:265 and the stale pointers at :104/:218/:273 (3), the six repo locations still asserting an application cannot publish (3), and the README's report-shape list (3). One finding declined with reason: the eleven codes do not belong in 96.error-codes.md's table.

Reviewer 3 also caught that the previous commit body began a line with Source:, which release-please would have minted into a spurious changelog entry. Commit reworded and force-pushed.

Verification

typecheck (jssdk + nuxt playground), eslint, pnpm lint:md, docs-lint --strict, and the Pull suites (12 files, 91 tests) pass locally.

Follow-up

#559 carries the remaining work: fuzz differentials for R2 and R3, after which protobuf/ can go.

🤖 Generated with Claude Code

https://claude.ai/code/session_01F22e2ft66y7nuBJjzdThBr