@c9up/comet 0.1.1 → 0.1.3

package/README.md

@@ -41,3 +41,11 @@ const results = await rpc.batch([{ method: "a" }, { method: "b" }]); // settled
 The `@c9up/comet/protocol` surface exposes the spec primitives a server binding
 needs: `parseRequest`, `isNotification`, `buildRequest`/`buildSuccess`/`buildError`,
 `RpcError`/`toRpcError`/`isRpcShapedError`, and the reserved `RpcErrorCode`.
+
+`parseRequest` enforces the envelope MUSTs — the version, the method, an `id`
+that is a String/Number/Null, and a `params` that is a Structured value (§4.2:
+an Array or an Object, never a scalar). A handler raises a domain error by
+throwing `RpcError`; `isRpcShapedError` also accepts a plain object whose `code`
+is a **negative integer**, the space the spec gives errors, so the numeric
+`code` an aborted `fetch` or a gRPC status happens to carry is not mistaken for
+one.

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAGN,QAAQ,EAGR,MAAM,eAAe,CAAC;AAEvB;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,CAC1B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,OAAO,EACb,OAAO,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,KAC7B,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAChC,wDAAwD;IACxD,SAAS,EAAE,YAAY,CAAC;IACxB,qCAAqC;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,mDAAmD;AACnD,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IAC1C;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC;IAC7B,uFAAuF;IACvF,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,wFAAwF;AACxF,MAAM,WAAW,OAAO,CAAC,CAAC,GAAG,OAAO;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC;CAC7B;AAED,+EAA+E;AAC/E,MAAM,MAAM,SAAS,CAAC,CAAC,GAAG,OAAO,IAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,CAAC;AAElC,MAAM,WAAW,SAAS;IACzB;;;;;OAKG;IACH,IAAI,CAAC,CAAC,GAAG,OAAO,EACf,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAAC;IACd;;;OAGG;IACH,KAAK,CACJ,KAAK,EAAE,OAAO,EAAE,EAChB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAChC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;CACxB;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAgFpE"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAGN,QAAQ,EAGR,MAAM,eAAe,CAAC;AAEvB;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,CAC1B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,OAAO,EACb,OAAO,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,KAC7B,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAChC,wDAAwD;IACxD,SAAS,EAAE,YAAY,CAAC;IACxB,qCAAqC;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,mDAAmD;AACnD,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IAC1C;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC;IAC7B,uFAAuF;IACvF,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,wFAAwF;AACxF,MAAM,WAAW,OAAO,CAAC,CAAC,GAAG,OAAO;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC;CAC7B;AAED,+EAA+E;AAC/E,MAAM,MAAM,SAAS,CAAC,CAAC,GAAG,OAAO,IAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,CAAC;AAElC,MAAM,WAAW,SAAS;IACzB;;;;;OAKG;IACH,IAAI,CAAC,CAAC,GAAG,OAAO,EACf,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAAC;IACd;;;OAGG;IACH,KAAK,CACJ,KAAK,EAAE,OAAO,EAAE,EAChB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAChC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;CACxB;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CA2JpE"}

package/dist/client.js

@@ -15,9 +15,21 @@ export function createRpcClient(options) {
     const { transport } = options;
     const url = options.url ?? "/rpc";
     let nextId = 0;
+    /**
+     * The next request id — one counter for single calls and batches alike.
+     *
+     * A batch used to number its entries from zero, so every batch sent the ids
+     * `0, 1, 2` again and a call sent `1` at the same time. Over HTTP the
+     * transport pairs each response with its own request and nothing shows; over
+     * a transport that multiplexes — one WebSocket carrying several requests,
+     * which is the reason the transport is injected at all — the correlation is
+     * the id, and two live requests carrying the same one is a response
+     * delivered to the wrong caller.
+     */
+    const allocateId = () => ++nextId;
     return {
         async call(method, params, callOptions) {
-            const id = ++nextId;
+            const id = allocateId();
             const res = await transport(url, buildRequest(method, params, id), {
                 signal: callOptions?.signal,
             });
@@ -28,11 +40,20 @@ export function createRpcClient(options) {
             if (!isObject(res) || res.jsonrpc !== "2.0" || res.id !== id) {
                 throw new RpcError(RpcErrorCode.InternalError, `Malformed or mismatched JSON-RPC response for "${method}" (bad jsonrpc/id envelope)`);
             }
+            // §5: `result` and `error` are mutually exclusive — "Either the
+            // result member or error member MUST be included, but both members
+            // MUST NOT be included." A response carrying both is malformed, and
+            // reading the error out of it is guessing at which half the sender
+            // meant. Refused, the way a bad jsonrpc/id envelope already is.
+            const hasResult = "result" in res;
+            if (hasResult && res.error !== undefined) {
+                throw new RpcError(RpcErrorCode.InternalError, `Malformed JSON-RPC response for "${method}" (carries both result and error)`);
+            }
             if (res.error !== undefined)
                 throw toRpcError(res.error);
             // A conformant success response carries `result` (any JSON value,
             // including null) and no error — neither key present is malformed.
-            if (!("result" in res)) {
+            if (!hasResult) {
                 throw new RpcError(RpcErrorCode.InternalError, `JSON-RPC response for "${method}" has neither result nor error`);
             }
             // Result boundary — the same unchecked `T` assertion HTTP clients use,
@@ -44,32 +65,75 @@ export function createRpcClient(options) {
         async batch(calls, batchOptions) {
             if (calls.length === 0)
                 return [];
-            const requests = calls.map((c, index) => 
-            // index = request position; responses are matched back by id
-            buildRequest(c.method, c.params, index));
-            const res = await transport(url, requests, {
-                signal: batchOptions?.signal,
-            });
+            // Each call keeps the id it was sent under; responses are matched
+            // back by it, in whatever order the server returns them.
+            const pending = calls.map((call) => ({ call, id: allocateId() }));
+            const res = await transport(url, pending.map((entry) => buildRequest(entry.call.method, entry.call.params, entry.id)), { signal: batchOptions?.signal });
             if (!Array.isArray(res)) {
                 throw new RpcError(RpcErrorCode.InternalError, "Malformed JSON-RPC batch response");
             }
+            // Envelope conformance, per item, exactly as `call` applies it — this
+            // checked none of it, so `{ jsonrpc: "1.0", id: 0 }` came back as
+            // `{ ok: true, value: undefined }` where the single-call path would
+            // have refused it.
             const byId = new Map();
-            for (const item of res)
-                if (isObject(item))
-                    byId.set(item.id, item);
-            return calls.map((c, index) => {
-                const envelope = byId.get(index);
-                if (!envelope) {
-                    return {
-                        ok: false,
-                        error: new RpcError(RpcErrorCode.InternalError, `No response for "${c.method}"`),
-                    };
+            const duplicated = new Set();
+            for (const item of res) {
+                if (!isObject(item))
+                    continue;
+                // A repeated id is a malformed batch, and silently keeping the last
+                // one lets a response answer a call it was not for.
+                if (byId.has(item.id))
+                    duplicated.add(item.id);
+                byId.set(item.id, item);
+            }
+            return pending.map(({ call: c, id }) => {
+                const fail = (message) => ({
+                    ok: false,
+                    error: new RpcError(RpcErrorCode.InternalError, message),
+                });
+                const envelope = byId.get(id);
+                if (!envelope)
+                    return fail(`No response for "${c.method}"`);
+                if (duplicated.has(id)) {
+                    return fail(`More than one response carried id ${id}`);
+                }
+                if (envelope.jsonrpc !== "2.0") {
+                    return fail(`Malformed JSON-RPC response for "${c.method}" (bad jsonrpc version)`);
+                }
+                const hasResult = "result" in envelope;
+                // §5: mutually exclusive. See the single-call path.
+                if (hasResult && envelope.error !== undefined) {
+                    return fail(`Malformed JSON-RPC response for "${c.method}" (carries both result and error)`);
                 }
                 if (envelope.error !== undefined) {
                     return { ok: false, error: toRpcError(envelope.error) };
                 }
-                const value = c.parse ? c.parse(envelope.result) : envelope.result;
-                return { ok: true, value };
+                // A conformant success carries `result` — any JSON value, null
+                // included — so its absence is malformed, not an undefined value.
+                if (!hasResult) {
+                    return fail(`JSON-RPC response for "${c.method}" has neither result nor error`);
+                }
+                if (!c.parse)
+                    return { ok: true, value: envelope.result };
+                try {
+                    return { ok: true, value: c.parse(envelope.result) };
+                }
+                catch (error) {
+                    // A batch settles per call, and a result that fails ITS OWN
+                    // validation is that entry's failure. Letting the throw out
+                    // rejected the whole promise and took every other entry with
+                    // it — the ones that had already succeeded included.
+                    const reason = error instanceof Error ? error.message : String(error);
+                    return {
+                        ok: false,
+                        error: new RpcError(RpcErrorCode.InternalError, `Result for "${c.method}" failed validation: ${reason}`, 
+                        // Built here rather than received, so `data` carries what
+                        // the validator threw — a caller checking WHY it failed
+                        // has nowhere else to read it.
+                        error),
+                    };
+                }
             });
         },
     };

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/protocol.d.ts

@@ -54,7 +54,15 @@ export declare class RpcError extends Error {
 }
 /** Type guard for {@link RpcError}. */
 export declare function isRpcError(value: unknown): value is RpcError;
-/** Narrow an unknown to a plain object (non-null). */
+/**
+ * Narrow an unknown to a JSON-RPC Object — non-null, and not an Array.
+ *
+ * Every envelope the spec defines is an Object; the one Array it has is the
+ * batch, which a binding frames before anything here sees it. Answering "yes"
+ * to an Array let a batch walk into the single-request path, where it was
+ * turned away for a missing `jsonrpc` rather than for being the wrong kind of
+ * thing.
+ */
 export declare function isObject(value: unknown): value is Record<string, unknown>;
 /**
  * Turn a JSON-RPC `error` member (untrusted wire value) into an {@link RpcError}.
@@ -62,16 +70,34 @@ export declare function isObject(value: unknown): value is Record<string, unknow
  */
 export declare function toRpcError(error: unknown): RpcError;
 /**
- * A domain error shaped like a JSON-RPC error — it carries a numeric `code`. A
- * server binding can map such a throw to a JSON-RPC error response instead of
- * collapsing every throw to InternalError.
+ * Whether a thrown value is a JSON-RPC error a binding may answer the caller
+ * with, rather than an internal failure it has to keep to itself.
+ *
+ * {@link RpcError} always is: throwing one is a statement. A foreign object is
+ * only read as one when its `code` is a NEGATIVE integer — the space the spec
+ * gives errors (§5.1 reserves -32768..-32000 and the framework issues -32003,
+ * -32004 and the like), and the space a handler writing a domain code picks
+ * from.
+ *
+ * Accepting any number was accepting the numbers other things happen to carry.
+ * A `DOMException` has a legacy numeric `code` — 20 for `AbortError`, 23 for
+ * `TimeoutError` — so a handler whose outbound `fetch` timed out answered the
+ * caller with `{ code: 20, message: "This operation was aborted" }`, walking
+ * straight past the guard a binding puts there to keep internal messages off
+ * the wire in production. gRPC status codes (0..16) arrive the same way.
  */
 export declare function isRpcShapedError(err: unknown): err is {
     code: number;
     message?: unknown;
     data?: unknown;
 };
-/** Build an outgoing request envelope. */
+/**
+ * Build an outgoing request envelope. An absent `params` is left out, the way
+ * {@link buildError} leaves out an absent `data`: a transport that does not go
+ * through `JSON.stringify` — a worker, an in-process bus — otherwise carries a
+ * `params` member holding `undefined`, which is not a Structured value and is
+ * refused by the parser at the other end.
+ */
 export declare function buildRequest(method: string, params: unknown, id: JsonRpcId): JsonRpcRequest;
 /** Build a success response envelope. */
 export declare function buildSuccess(result: unknown, id: JsonRpcId): JsonRpcSuccessResponse;
@@ -89,7 +115,8 @@ export type ParsedRpcRequest = {
 };
 /**
  * Validate an incoming JSON-RPC envelope and extract `method`/`params`/`id`.
- * Returns an `InvalidRequest` error response when the version/method are wrong.
+ * Returns an `InvalidRequest` error response when the version, the method, the
+ * id or the shape of `params` is wrong.
  */
 export declare function parseRequest(request: unknown): ParsedRpcRequest;
 /**

package/dist/protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,+DAA+D;AAC/D,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAE/C,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,EAAE,EAAE,SAAS,CAAC;CACd;AAED,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED,mDAAmD;AACnD,MAAM,WAAW,sBAAsB;IACtC,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,EAAE,EAAE,SAAS,CAAC;CACd;AAED,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,kBAAkB,CAAC;IAC1B,EAAE,EAAE,SAAS,CAAC;CACd;AAED,MAAM,MAAM,eAAe,GAAG,sBAAsB,GAAG,oBAAoB,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;CAMf,CAAC;AAEX,uFAAuF;AACvF,qBAAa,QAAS,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;gBACZ,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAMzD;AAED,uCAAuC;AACvC,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED,sDAAsD;AACtD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAanD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC/B,GAAG,EAAE,OAAO,GACV,GAAG,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,CAE5D;AAED,0CAA0C;AAC1C,wBAAgB,YAAY,CAC3B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,EACf,EAAE,EAAE,SAAS,GACX,cAAc,CAEhB;AAED,yCAAyC;AACzC,wBAAgB,YAAY,CAC3B,MAAM,EAAE,OAAO,EACf,EAAE,EAAE,SAAS,GACX,sBAAsB,CAExB;AAED,yEAAyE;AACzE,wBAAgB,UAAU,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,SAAS,EACb,IAAI,CAAC,EAAE,OAAO,GACZ,oBAAoB,CAMtB;AAED,sCAAsC;AACtC,MAAM,MAAM,gBAAgB,GACzB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,SAAS,CAAA;CAAE,GAC5D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAEjD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,CAyC/D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CASxD"}
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,+DAA+D;AAC/D,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAE/C,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,EAAE,EAAE,SAAS,CAAC;CACd;AAED,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED,mDAAmD;AACnD,MAAM,WAAW,sBAAsB;IACtC,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,EAAE,EAAE,SAAS,CAAC;CACd;AAED,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,kBAAkB,CAAC;IAC1B,EAAE,EAAE,SAAS,CAAC;CACd;AAED,MAAM,MAAM,eAAe,GAAG,sBAAsB,GAAG,oBAAoB,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;CAMf,CAAC;AAEX,uFAAuF;AACvF,qBAAa,QAAS,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;gBACZ,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAMzD;AAED,uCAAuC;AACvC,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAaD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAanD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC/B,GAAG,EAAE,OAAO,GACV,GAAG,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,CAG5D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC3B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,EACf,EAAE,EAAE,SAAS,GACX,cAAc,CAIhB;AAED,yCAAyC;AACzC,wBAAgB,YAAY,CAC3B,MAAM,EAAE,OAAO,EACf,EAAE,EAAE,SAAS,GACX,sBAAsB,CAExB;AAED,yEAAyE;AACzE,wBAAgB,UAAU,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,SAAS,EACb,IAAI,CAAC,EAAE,OAAO,GACZ,oBAAoB,CAMtB;AAED,sCAAsC;AACtC,MAAM,MAAM,gBAAgB,GACzB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,SAAS,CAAA;CAAE,GAC5D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAEjD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,CAgD/D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CASxD"}

package/dist/protocol.js

@@ -33,9 +33,27 @@ export class RpcError extends Error {
 export function isRpcError(value) {
     return value instanceof RpcError;
 }
-/** Narrow an unknown to a plain object (non-null). */
+/**
+ * Narrow an unknown to a JSON-RPC Object — non-null, and not an Array.
+ *
+ * Every envelope the spec defines is an Object; the one Array it has is the
+ * batch, which a binding frames before anything here sees it. Answering "yes"
+ * to an Array let a batch walk into the single-request path, where it was
+ * turned away for a missing `jsonrpc` rather than for being the wrong kind of
+ * thing.
+ */
 export function isObject(value) {
-    return typeof value === "object" && value !== null;
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * A JSON-RPC error code. Spec §5.1 on `code`: "A Number that indicates the
+ * error type that occurred. This MUST be an integer." A fractional code — or a
+ * `NaN`, which is what an arithmetic slip in a handler produces — is not one,
+ * and `NaN` does not survive `JSON.stringify`: it goes out as `null` and
+ * reaches the caller as an error whose code is missing.
+ */
+function isErrorCode(value) {
+    return typeof value === "number" && Number.isInteger(value);
 }
 /**
  * Turn a JSON-RPC `error` member (untrusted wire value) into an {@link RpcError}.
@@ -43,23 +61,45 @@ export function isObject(value) {
  */
 export function toRpcError(error) {
     if (isObject(error) &&
-        typeof error.code === "number" &&
+        isErrorCode(error.code) &&
         typeof error.message === "string") {
         return new RpcError(error.code, error.message, error.data);
     }
     return new RpcError(RpcErrorCode.InternalError, "Malformed JSON-RPC error envelope", error);
 }
 /**
- * A domain error shaped like a JSON-RPC error — it carries a numeric `code`. A
- * server binding can map such a throw to a JSON-RPC error response instead of
- * collapsing every throw to InternalError.
+ * Whether a thrown value is a JSON-RPC error a binding may answer the caller
+ * with, rather than an internal failure it has to keep to itself.
+ *
+ * {@link RpcError} always is: throwing one is a statement. A foreign object is
+ * only read as one when its `code` is a NEGATIVE integer — the space the spec
+ * gives errors (§5.1 reserves -32768..-32000 and the framework issues -32003,
+ * -32004 and the like), and the space a handler writing a domain code picks
+ * from.
+ *
+ * Accepting any number was accepting the numbers other things happen to carry.
+ * A `DOMException` has a legacy numeric `code` — 20 for `AbortError`, 23 for
+ * `TimeoutError` — so a handler whose outbound `fetch` timed out answered the
+ * caller with `{ code: 20, message: "This operation was aborted" }`, walking
+ * straight past the guard a binding puts there to keep internal messages off
+ * the wire in production. gRPC status codes (0..16) arrive the same way.
  */
 export function isRpcShapedError(err) {
-    return isObject(err) && typeof err.code === "number";
+    if (err instanceof RpcError)
+        return true;
+    return isObject(err) && isErrorCode(err.code) && err.code < 0;
 }
-/** Build an outgoing request envelope. */
+/**
+ * Build an outgoing request envelope. An absent `params` is left out, the way
+ * {@link buildError} leaves out an absent `data`: a transport that does not go
+ * through `JSON.stringify` — a worker, an in-process bus — otherwise carries a
+ * `params` member holding `undefined`, which is not a Structured value and is
+ * refused by the parser at the other end.
+ */
 export function buildRequest(method, params, id) {
-    return { jsonrpc: "2.0", method, params, id };
+    return params === undefined
+        ? { jsonrpc: "2.0", method, id }
+        : { jsonrpc: "2.0", method, params, id };
 }
 /** Build a success response envelope. */
 export function buildSuccess(result, id) {
@@ -75,7 +115,8 @@ export function buildError(code, message, id, data) {
 }
 /**
  * Validate an incoming JSON-RPC envelope and extract `method`/`params`/`id`.
- * Returns an `InvalidRequest` error response when the version/method are wrong.
+ * Returns an `InvalidRequest` error response when the version, the method, the
+ * id or the shape of `params` is wrong.
  */
 export function parseRequest(request) {
     if (!isObject(request)) {
@@ -103,7 +144,13 @@ export function parseRequest(request) {
     const id = rawId === null || typeof rawId === "string" || typeof rawId === "number"
         ? rawId
         : null;
-    if (jsonrpc !== "2.0" || !method || !idValid) {
+    // §4.2: "If present, parameters for the rpc call MUST be provided as a
+    // Structured value. Either by-position through an Array or by-name through
+    // an Object." A string, a number or a `null` is none of those, and passing
+    // one on hands the method a `params` no handler was written to read — the
+    // envelope check saying yes to something the method can only say no to.
+    const paramsValid = params === undefined || isObject(params) || Array.isArray(params);
+    if (jsonrpc !== "2.0" || !method || !idValid || !paramsValid) {
         return {
             ok: false,
             response: buildError(RpcErrorCode.InvalidRequest, "Invalid Request", id),

package/dist/protocol.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/comet",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Comet — agnostic JSON-RPC 2.0 protocol + isomorphic, transport-injectable client for the Ream framework",
   "license": "MIT",
   "type": "module",
@@ -23,6 +23,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
     "@types/node": "^22.19.15",
+    "@vitest/coverage-v8": "^4.1.2",
     "typescript": "^6.0.2",
     "vitest": "^4.1.2"
   },
@@ -45,7 +46,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
-    "lint": "biome check src/",
+    "lint": "biome check src/ tests/",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit"
   }

package/src/client.ts

@@ -84,6 +84,18 @@ export function createRpcClient(options: RpcClientOptions): RpcClient {
 	const { transport } = options;
 	const url = options.url ?? "/rpc";
 	let nextId = 0;
+	/**
+	 * The next request id — one counter for single calls and batches alike.
+	 *
+	 * A batch used to number its entries from zero, so every batch sent the ids
+	 * `0, 1, 2` again and a call sent `1` at the same time. Over HTTP the
+	 * transport pairs each response with its own request and nothing shows; over
+	 * a transport that multiplexes — one WebSocket carrying several requests,
+	 * which is the reason the transport is injected at all — the correlation is
+	 * the id, and two live requests carrying the same one is a response
+	 * delivered to the wrong caller.
+	 */
+	const allocateId = (): number => ++nextId;
 
 	return {
 		async call<T>(
@@ -91,7 +103,7 @@ export function createRpcClient(options: RpcClientOptions): RpcClient {
 			params?: unknown,
 			callOptions?: RpcCallOptions<T>,
 		): Promise<T> {
-			const id = ++nextId;
+			const id = allocateId();
 			const res = await transport(url, buildRequest(method, params, id), {
 				signal: callOptions?.signal,
 			});
@@ -105,10 +117,22 @@ export function createRpcClient(options: RpcClientOptions): RpcClient {
 					`Malformed or mismatched JSON-RPC response for "${method}" (bad jsonrpc/id envelope)`,
 				);
 			}
+			// §5: `result` and `error` are mutually exclusive — "Either the
+			// result member or error member MUST be included, but both members
+			// MUST NOT be included." A response carrying both is malformed, and
+			// reading the error out of it is guessing at which half the sender
+			// meant. Refused, the way a bad jsonrpc/id envelope already is.
+			const hasResult = "result" in res;
+			if (hasResult && res.error !== undefined) {
+				throw new RpcError(
+					RpcErrorCode.InternalError,
+					`Malformed JSON-RPC response for "${method}" (carries both result and error)`,
+				);
+			}
 			if (res.error !== undefined) throw toRpcError(res.error);
 			// A conformant success response carries `result` (any JSON value,
 			// including null) and no error — neither key present is malformed.
-			if (!("result" in res)) {
+			if (!hasResult) {
 				throw new RpcError(
 					RpcErrorCode.InternalError,
 					`JSON-RPC response for "${method}" has neither result nor error`,
@@ -126,37 +150,88 @@ export function createRpcClient(options: RpcClientOptions): RpcClient {
 			batchOptions?: { signal?: AbortSignal },
 		): Promise<RpcResult[]> {
 			if (calls.length === 0) return [];
-			const requests = calls.map((c, index) =>
-				// index = request position; responses are matched back by id
-				buildRequest(c.method, c.params, index),
+			// Each call keeps the id it was sent under; responses are matched
+			// back by it, in whatever order the server returns them.
+			const pending = calls.map((call) => ({ call, id: allocateId() }));
+			const res = await transport(
+				url,
+				pending.map((entry) =>
+					buildRequest(entry.call.method, entry.call.params, entry.id),
+				),
+				{ signal: batchOptions?.signal },
 			);
-			const res = await transport(url, requests, {
-				signal: batchOptions?.signal,
-			});
 			if (!Array.isArray(res)) {
 				throw new RpcError(
 					RpcErrorCode.InternalError,
 					"Malformed JSON-RPC batch response",
 				);
 			}
+			// Envelope conformance, per item, exactly as `call` applies it — this
+			// checked none of it, so `{ jsonrpc: "1.0", id: 0 }` came back as
+			// `{ ok: true, value: undefined }` where the single-call path would
+			// have refused it.
 			const byId = new Map<unknown, Record<string, unknown>>();
-			for (const item of res) if (isObject(item)) byId.set(item.id, item);
-			return calls.map((c, index) => {
-				const envelope = byId.get(index);
-				if (!envelope) {
+			const duplicated = new Set<unknown>();
+			for (const item of res) {
+				if (!isObject(item)) continue;
+				// A repeated id is a malformed batch, and silently keeping the last
+				// one lets a response answer a call it was not for.
+				if (byId.has(item.id)) duplicated.add(item.id);
+				byId.set(item.id, item);
+			}
+			return pending.map(({ call: c, id }) => {
+				const fail = (message: string): RpcResult => ({
+					ok: false,
+					error: new RpcError(RpcErrorCode.InternalError, message),
+				});
+				const envelope = byId.get(id);
+				if (!envelope) return fail(`No response for "${c.method}"`);
+				if (duplicated.has(id)) {
+					return fail(`More than one response carried id ${id}`);
+				}
+				if (envelope.jsonrpc !== "2.0") {
+					return fail(
+						`Malformed JSON-RPC response for "${c.method}" (bad jsonrpc version)`,
+					);
+				}
+				const hasResult = "result" in envelope;
+				// §5: mutually exclusive. See the single-call path.
+				if (hasResult && envelope.error !== undefined) {
+					return fail(
+						`Malformed JSON-RPC response for "${c.method}" (carries both result and error)`,
+					);
+				}
+				if (envelope.error !== undefined) {
+					return { ok: false, error: toRpcError(envelope.error) };
+				}
+				// A conformant success carries `result` — any JSON value, null
+				// included — so its absence is malformed, not an undefined value.
+				if (!hasResult) {
+					return fail(
+						`JSON-RPC response for "${c.method}" has neither result nor error`,
+					);
+				}
+				if (!c.parse) return { ok: true, value: envelope.result };
+				try {
+					return { ok: true, value: c.parse(envelope.result) };
+				} catch (error) {
+					// A batch settles per call, and a result that fails ITS OWN
+					// validation is that entry's failure. Letting the throw out
+					// rejected the whole promise and took every other entry with
+					// it — the ones that had already succeeded included.
+					const reason = error instanceof Error ? error.message : String(error);
 					return {
 						ok: false,
 						error: new RpcError(
 							RpcErrorCode.InternalError,
-							`No response for "${c.method}"`,
+							`Result for "${c.method}" failed validation: ${reason}`,
+							// Built here rather than received, so `data` carries what
+							// the validator threw — a caller checking WHY it failed
+							// has nowhere else to read it.
+							error,
 						),
 					};
 				}
-				if (envelope.error !== undefined) {
-					return { ok: false, error: toRpcError(envelope.error) };
-				}
-				const value = c.parse ? c.parse(envelope.result) : envelope.result;
-				return { ok: true, value };
 			});
 		},
 	};

package/src/protocol.ts

@@ -71,9 +71,28 @@ export function isRpcError(value: unknown): value is RpcError {
 	return value instanceof RpcError;
 }
 
-/** Narrow an unknown to a plain object (non-null). */
+/**
+ * Narrow an unknown to a JSON-RPC Object — non-null, and not an Array.
+ *
+ * Every envelope the spec defines is an Object; the one Array it has is the
+ * batch, which a binding frames before anything here sees it. Answering "yes"
+ * to an Array let a batch walk into the single-request path, where it was
+ * turned away for a missing `jsonrpc` rather than for being the wrong kind of
+ * thing.
+ */
 export function isObject(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * A JSON-RPC error code. Spec §5.1 on `code`: "A Number that indicates the
+ * error type that occurred. This MUST be an integer." A fractional code — or a
+ * `NaN`, which is what an arithmetic slip in a handler produces — is not one,
+ * and `NaN` does not survive `JSON.stringify`: it goes out as `null` and
+ * reaches the caller as an error whose code is missing.
+ */
+function isErrorCode(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value);
 }
 
 /**
@@ -83,7 +102,7 @@ export function isObject(value: unknown): value is Record<string, unknown> {
 export function toRpcError(error: unknown): RpcError {
 	if (
 		isObject(error) &&
-		typeof error.code === "number" &&
+		isErrorCode(error.code) &&
 		typeof error.message === "string"
 	) {
 		return new RpcError(error.code, error.message, error.data);
@@ -96,23 +115,44 @@ export function toRpcError(error: unknown): RpcError {
 }
 
 /**
- * A domain error shaped like a JSON-RPC error — it carries a numeric `code`. A
- * server binding can map such a throw to a JSON-RPC error response instead of
- * collapsing every throw to InternalError.
+ * Whether a thrown value is a JSON-RPC error a binding may answer the caller
+ * with, rather than an internal failure it has to keep to itself.
+ *
+ * {@link RpcError} always is: throwing one is a statement. A foreign object is
+ * only read as one when its `code` is a NEGATIVE integer — the space the spec
+ * gives errors (§5.1 reserves -32768..-32000 and the framework issues -32003,
+ * -32004 and the like), and the space a handler writing a domain code picks
+ * from.
+ *
+ * Accepting any number was accepting the numbers other things happen to carry.
+ * A `DOMException` has a legacy numeric `code` — 20 for `AbortError`, 23 for
+ * `TimeoutError` — so a handler whose outbound `fetch` timed out answered the
+ * caller with `{ code: 20, message: "This operation was aborted" }`, walking
+ * straight past the guard a binding puts there to keep internal messages off
+ * the wire in production. gRPC status codes (0..16) arrive the same way.
  */
 export function isRpcShapedError(
 	err: unknown,
 ): err is { code: number; message?: unknown; data?: unknown } {
-	return isObject(err) && typeof err.code === "number";
+	if (err instanceof RpcError) return true;
+	return isObject(err) && isErrorCode(err.code) && err.code < 0;
 }
 
-/** Build an outgoing request envelope. */
+/**
+ * Build an outgoing request envelope. An absent `params` is left out, the way
+ * {@link buildError} leaves out an absent `data`: a transport that does not go
+ * through `JSON.stringify` — a worker, an in-process bus — otherwise carries a
+ * `params` member holding `undefined`, which is not a Structured value and is
+ * refused by the parser at the other end.
+ */
 export function buildRequest(
 	method: string,
 	params: unknown,
 	id: JsonRpcId,
 ): JsonRpcRequest {
-	return { jsonrpc: "2.0", method, params, id };
+	return params === undefined
+		? { jsonrpc: "2.0", method, id }
+		: { jsonrpc: "2.0", method, params, id };
 }
 
 /** Build a success response envelope. */
@@ -144,7 +184,8 @@ export type ParsedRpcRequest =
 
 /**
  * Validate an incoming JSON-RPC envelope and extract `method`/`params`/`id`.
- * Returns an `InvalidRequest` error response when the version/method are wrong.
+ * Returns an `InvalidRequest` error response when the version, the method, the
+ * id or the shape of `params` is wrong.
  */
 export function parseRequest(request: unknown): ParsedRpcRequest {
 	if (!isObject(request)) {
@@ -180,7 +221,14 @@ export function parseRequest(request: unknown): ParsedRpcRequest {
 		rawId === null || typeof rawId === "string" || typeof rawId === "number"
 			? rawId
 			: null;
-	if (jsonrpc !== "2.0" || !method || !idValid) {
+	// §4.2: "If present, parameters for the rpc call MUST be provided as a
+	// Structured value. Either by-position through an Array or by-name through
+	// an Object." A string, a number or a `null` is none of those, and passing
+	// one on hands the method a `params` no handler was written to read — the
+	// envelope check saying yes to something the method can only say no to.
+	const paramsValid =
+		params === undefined || isObject(params) || Array.isArray(params);
+	if (jsonrpc !== "2.0" || !method || !idValid || !paramsValid) {
 		return {
 			ok: false,
 			response: buildError(RpcErrorCode.InvalidRequest, "Invalid Request", id),