@standardserver/peer 0.0.0 → 0.0.2

package/dist/index.d.mts

@@ -202,22 +202,60 @@ declare class ClientPeer {
     close(options?: AsyncIdQueueCloseOptions): Promise<void>;
 }
 
+interface EncodePeerMessageOptions {
+    /**
+     * Optional string prepended to the encoded message.
+     * Used to distinguish messages when multiple protocols share the same peer.
+     */
+    prefix?: string;
+}
+/**
+ * Encodes a {@link PeerMessage} into a wire-safe representation.
+ *
+ * Encoding rules:
+ * - If no binary payload is present, the message is encoded as a JSON string.
+ * - If binary data exists, the output layout is:
+ *
+ *   [ UTF-8 (prefix + JSON) | delimiter byte | raw binary bytes ]
+ *
+ * The optional prefix is prepended to the JSON portion before encoding.
+ */
+declare function encodePeerMessage(message: PeerMessage, options?: EncodePeerMessageOptions): Promise<string | Uint8Array<ArrayBuffer>>;
+interface DecodePeerMessageOptions {
+    /**
+     * Optional prefix expected at the start of the encoded message.
+     * If present and the message does not start with this prefix,
+     * the decoder returns `matched: false`.
+     */
+    prefix?: string;
+}
 /**
- * Encodes a PeerMessage into a wire-safe representation.
+ * Result of a decode attempt.
  *
- * - If no binary data is present, the message is encoded as a JSON string.
- * - If binary data exists, the output is:
- *   [ UTF-8 JSON bytes | separator byte | raw binary bytes ]
+ * - `matched: false` indicates the input does not belong to this decoder
+ *   (typically due to a prefix mismatch).
+ * - `matched: true` indicates successful decoding of a {@link PeerMessage}.
  */
-declare function encodePeerMessage(message: PeerMessage): Promise<string | Uint8Array<ArrayBuffer>>;
+type DecodePeerMessageResult = {
+    matched: false;
+    message?: undefined;
+} | {
+    matched: true;
+    message: PeerMessage;
+};
 /**
- * Decodes a wire-encoded PeerMessage.
+ * Decodes a wire-encoded {@link PeerMessage}.
+ *
+ * Decoding rules:
+ * - String input is treated as a JSON-only message.
+ * - Binary input may contain:
+ *   - JSON only, or
+ *   - JSON followed by binary data separated by the delimiter byte.
  *
- * - String input is treated as pure JSON.
- * - Binary input may contain only JSON bytes, or JSON followed by binary data
- *   separated by the separator byte.
+ * If a prefix is provided, it must be present at the start of the payload
+ * or the decode attempt will return `matched: false`.
  */
-declare function decodePeerMessage(data: string | Uint8Array<ArrayBuffer>): PeerMessage;
+declare function decodePeerMessage(encoded: string | Uint8Array<ArrayBuffer>, options?: DecodePeerMessageOptions): DecodePeerMessageResult;
 
 /**
  * Creates an AsyncIterator from a queue of peer event-stream messages.
@@ -277,4 +315,4 @@ declare class ServerPeer {
 }
 
 export { ClientPeer, EventStreamTransmitter, HibernationEventIterator, ServerPeer, decodePeerMessage, encodePeerMessage, toEventIterator };
-export type { ClientPeerCloseOptions, HibernationEventIteratorCallback, PeerAbortMessage, PeerEventStreamMessage, PeerMessage, PeerOctetStreamMessage, PeerRequestMessage, PeerResponseMessage, PeerStreamCancelMessage, ServerPeerCloseOptions };
+export type { ClientPeerCloseOptions, DecodePeerMessageOptions, DecodePeerMessageResult, EncodePeerMessageOptions, HibernationEventIteratorCallback, PeerAbortMessage, PeerEventStreamMessage, PeerMessage, PeerOctetStreamMessage, PeerRequestMessage, PeerResponseMessage, PeerStreamCancelMessage, ServerPeerCloseOptions };

package/dist/index.d.ts

@@ -202,22 +202,60 @@ declare class ClientPeer {
     close(options?: AsyncIdQueueCloseOptions): Promise<void>;
 }
 
+interface EncodePeerMessageOptions {
+    /**
+     * Optional string prepended to the encoded message.
+     * Used to distinguish messages when multiple protocols share the same peer.
+     */
+    prefix?: string;
+}
+/**
+ * Encodes a {@link PeerMessage} into a wire-safe representation.
+ *
+ * Encoding rules:
+ * - If no binary payload is present, the message is encoded as a JSON string.
+ * - If binary data exists, the output layout is:
+ *
+ *   [ UTF-8 (prefix + JSON) | delimiter byte | raw binary bytes ]
+ *
+ * The optional prefix is prepended to the JSON portion before encoding.
+ */
+declare function encodePeerMessage(message: PeerMessage, options?: EncodePeerMessageOptions): Promise<string | Uint8Array<ArrayBuffer>>;
+interface DecodePeerMessageOptions {
+    /**
+     * Optional prefix expected at the start of the encoded message.
+     * If present and the message does not start with this prefix,
+     * the decoder returns `matched: false`.
+     */
+    prefix?: string;
+}
 /**
- * Encodes a PeerMessage into a wire-safe representation.
+ * Result of a decode attempt.
  *
- * - If no binary data is present, the message is encoded as a JSON string.
- * - If binary data exists, the output is:
- *   [ UTF-8 JSON bytes | separator byte | raw binary bytes ]
+ * - `matched: false` indicates the input does not belong to this decoder
+ *   (typically due to a prefix mismatch).
+ * - `matched: true` indicates successful decoding of a {@link PeerMessage}.
  */
-declare function encodePeerMessage(message: PeerMessage): Promise<string | Uint8Array<ArrayBuffer>>;
+type DecodePeerMessageResult = {
+    matched: false;
+    message?: undefined;
+} | {
+    matched: true;
+    message: PeerMessage;
+};
 /**
- * Decodes a wire-encoded PeerMessage.
+ * Decodes a wire-encoded {@link PeerMessage}.
+ *
+ * Decoding rules:
+ * - String input is treated as a JSON-only message.
+ * - Binary input may contain:
+ *   - JSON only, or
+ *   - JSON followed by binary data separated by the delimiter byte.
  *
- * - String input is treated as pure JSON.
- * - Binary input may contain only JSON bytes, or JSON followed by binary data
- *   separated by the separator byte.
+ * If a prefix is provided, it must be present at the start of the payload
+ * or the decode attempt will return `matched: false`.
  */
-declare function decodePeerMessage(data: string | Uint8Array<ArrayBuffer>): PeerMessage;
+declare function decodePeerMessage(encoded: string | Uint8Array<ArrayBuffer>, options?: DecodePeerMessageOptions): DecodePeerMessageResult;
 
 /**
  * Creates an AsyncIterator from a queue of peer event-stream messages.
@@ -277,4 +315,4 @@ declare class ServerPeer {
 }
 
 export { ClientPeer, EventStreamTransmitter, HibernationEventIterator, ServerPeer, decodePeerMessage, encodePeerMessage, toEventIterator };
-export type { ClientPeerCloseOptions, HibernationEventIteratorCallback, PeerAbortMessage, PeerEventStreamMessage, PeerMessage, PeerOctetStreamMessage, PeerRequestMessage, PeerResponseMessage, PeerStreamCancelMessage, ServerPeerCloseOptions };
+export type { ClientPeerCloseOptions, DecodePeerMessageOptions, DecodePeerMessageResult, EncodePeerMessageOptions, HibernationEventIteratorCallback, PeerAbortMessage, PeerEventStreamMessage, PeerMessage, PeerOctetStreamMessage, PeerRequestMessage, PeerResponseMessage, PeerStreamCancelMessage, ServerPeerCloseOptions };

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { flattenStandardHeader, getFilenameFromContentDisposition, generateContentDisposition } from '@standardserver/core';
-import { AsyncIteratorClass, isTypescriptObject, SequentialIdGenerator, AsyncIdQueue, isAsyncIteratorObject, AbortError, stringifyJSON } from '@standardserver/shared';
+import { AsyncIteratorClass, isTypescriptObject, isAsyncIteratorObject, SequentialIdGenerator, AsyncIdQueue, AbortError, stringifyJSON } from '@standardserver/shared';
+import { generateContentDisposition, flattenStandardHeader, getFilenameFromContentDisposition } from '@standardserver/core';
 import { withEventIteratorEventMeta, EventIteratorErrorEvent, resolveEventIteratorEvent } from '@standardserver/core/event-stream';
 
 function toEventIterator(pull, cleanup) {
@@ -181,6 +181,37 @@ async function toStandardBody(message, eventStreamMessageQueue, octetStreamMessa
     await cleanup(true);
   }
 }
+async function encodeAtomicStandardBody(body, headers) {
+  headers = { ...headers };
+  let binary;
+  let jsonBody = body;
+  headers["standard-server"] = void 0;
+  if (body instanceof ReadableStream) {
+    jsonBody = void 0;
+    headers["standard-server"] = "octet-stream";
+  } else if (isAsyncIteratorObject(body)) {
+    jsonBody = void 0;
+    headers["standard-server"] = "event-stream";
+  } else if (body instanceof FormData) {
+    const res = new Response(body);
+    binary = await res.blob();
+    jsonBody = void 0;
+    headers["standard-server"] = "form-data";
+    headers["content-type"] ??= res.headers.get("content-type");
+  } else if (body instanceof Blob) {
+    binary = body;
+    jsonBody = void 0;
+    headers["standard-server"] = "file";
+    headers["content-disposition"] ??= generateContentDisposition(
+      body instanceof File ? body.name : "blob"
+    );
+    headers["content-type"] ??= body.type;
+  } else if (body instanceof URLSearchParams) {
+    jsonBody = body.toString();
+    headers["standard-server"] = "url-search-params";
+  }
+  return [jsonBody, headers, binary];
+}
 
 class ClientPeer {
   constructor(send) {
@@ -245,39 +276,20 @@ class ClientPeer {
     ];
     this.cleanupFns.set(id, cleanupFns);
     try {
+      const [jsonBody, headers, binary] = await encodeAtomicStandardBody(request.body, request.headers);
+      signal?.throwIfAborted();
       const requestMessage = {
         id,
         kind: "request",
         json: {
-          ...{ ...request, signal: void 0 },
-          // clone and remove signal from request
-          headers: { ...request.headers }
-          // clone headers
-        }
+          ...request,
+          headers,
+          body: jsonBody,
+          ...{ signal: void 0 }
+          // remove signal from request
+        },
+        binary
       };
-      if (request.body instanceof ReadableStream) {
-        requestMessage.json.body = void 0;
-        requestMessage.json.headers["standard-server"] = "octet-stream";
-      } else if (isAsyncIteratorObject(request.body)) {
-        requestMessage.json.body = void 0;
-        requestMessage.json.headers["standard-server"] = "event-stream";
-      } else if (request.body instanceof FormData) {
-        const res = new Response(request.body);
-        requestMessage.binary = await res.blob();
-        requestMessage.json.body = void 0;
-        requestMessage.json.headers["standard-server"] = "form-data";
-        requestMessage.json.headers["content-type"] = res.headers.get("content-type") ?? void 0;
-      } else if (request.body instanceof Blob) {
-        requestMessage.binary = request.body;
-        requestMessage.json.body = void 0;
-        requestMessage.json.headers["standard-server"] = "file";
-        requestMessage.json.headers["content-disposition"] = generateContentDisposition(request.body instanceof File ? request.body.name : "blob");
-        requestMessage.json.headers["content-type"] = request.body.type;
-      } else if (request.body instanceof URLSearchParams) {
-        requestMessage.json.body = request.body.toString();
-        requestMessage.json.headers["standard-server"] = "url-search-params";
-      }
-      signal?.throwIfAborted();
       await this.send(requestMessage);
       signal?.throwIfAborted();
       if (isAsyncIteratorObject(request.body)) {
@@ -391,36 +403,57 @@ class ClientPeer {
   }
 }
 
-const JSON_BINARY_SEPARATOR_BYTE = 255;
+const JSON_BINARY_DELIMITER = 255;
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
-async function encodePeerMessage(message) {
+async function encodePeerMessage(message, options = {}) {
+  const jsonPart = stringifyJSON({ ...message, binary: void 0 });
   if (message.binary === void 0) {
-    return stringifyJSON(message);
+    return options.prefix ? options.prefix + jsonPart : jsonPart;
   }
-  const jsonBytes = textEncoder.encode(stringifyJSON(message));
+  const textBytes = textEncoder.encode(
+    options.prefix ? options.prefix + jsonPart : jsonPart
+  );
   const binaryBytes = message.binary instanceof Blob ? new Uint8Array(await message.binary.arrayBuffer()) : message.binary;
   const output = new Uint8Array(
-    jsonBytes.length + 1 + binaryBytes.length
+    textBytes.length + 1 + binaryBytes.length
   );
-  output.set(jsonBytes, 0);
-  output[jsonBytes.length] = JSON_BINARY_SEPARATOR_BYTE;
-  output.set(binaryBytes, jsonBytes.length + 1);
+  output.set(textBytes, 0);
+  output[textBytes.length] = JSON_BINARY_DELIMITER;
+  output.set(binaryBytes, textBytes.length + 1);
   return output;
 }
-function decodePeerMessage(data) {
-  if (typeof data === "string") {
-    return JSON.parse(data);
+function decodePeerMessage(encoded, options = {}) {
+  if (typeof encoded === "string") {
+    if (options.prefix) {
+      if (!encoded.startsWith(options.prefix)) {
+        return { matched: false };
+      }
+      encoded = encoded.slice(options.prefix.length);
+    }
+    return { matched: true, message: JSON.parse(encoded) };
+  }
+  if (options.prefix) {
+    const prefixBytes = textEncoder.encode(options.prefix);
+    for (let i = 0; i < prefixBytes.length; i++) {
+      if (encoded[i] !== prefixBytes[i]) {
+        return { matched: false };
+      }
+    }
+    encoded = encoded.subarray(prefixBytes.length);
   }
-  const separatorIndex = data.indexOf(JSON_BINARY_SEPARATOR_BYTE);
+  const separatorIndex = encoded.indexOf(JSON_BINARY_DELIMITER);
   if (separatorIndex === -1) {
-    return JSON.parse(textDecoder.decode(data));
+    return { matched: true, message: JSON.parse(textDecoder.decode(encoded)) };
   }
-  const jsonBytes = data.subarray(0, separatorIndex);
-  const binaryBytes = data.subarray(separatorIndex + 1);
+  const jsonBytes = encoded.subarray(0, separatorIndex);
+  const binaryBytes = encoded.subarray(separatorIndex + 1);
   return {
-    ...JSON.parse(textDecoder.decode(jsonBytes)),
-    binary: binaryBytes
+    matched: true,
+    message: {
+      ...JSON.parse(textDecoder.decode(jsonBytes)),
+      binary: binaryBytes
+    }
   };
 }
 
@@ -509,41 +542,22 @@ class ServerPeer {
       if (signal.aborted) {
         return;
       }
+      const [jsonBody, headers, binary] = await encodeAtomicStandardBody(response.body, response.headers);
+      if (signal.aborted) {
+        return;
+      }
       const responseMessage = {
         id: message.id,
         kind: "response",
         json: {
-          ...{ ...response, signal: void 0 },
-          // clone and remove signal from request
-          headers: { ...response.headers }
-          // clone headers
-        }
+          ...response,
+          headers,
+          body: jsonBody,
+          ...{ signal: void 0 }
+          // remove signal from request
+        },
+        binary
       };
-      if (response.body instanceof ReadableStream) {
-        responseMessage.json.body = void 0;
-        responseMessage.json.headers["standard-server"] = "octet-stream";
-      } else if (isAsyncIteratorObject(response.body)) {
-        responseMessage.json.body = void 0;
-        responseMessage.json.headers["standard-server"] = "event-stream";
-      } else if (response.body instanceof FormData) {
-        const res = new Response(response.body);
-        responseMessage.binary = await res.blob();
-        responseMessage.json.body = void 0;
-        responseMessage.json.headers["standard-server"] = "form-data";
-        responseMessage.json.headers["content-type"] = res.headers.get("content-type") ?? void 0;
-      } else if (response.body instanceof Blob) {
-        responseMessage.binary = response.body;
-        responseMessage.json.body = void 0;
-        responseMessage.json.headers["standard-server"] = "file";
-        responseMessage.json.headers["content-disposition"] = generateContentDisposition(response.body instanceof File ? response.body.name : "blob");
-        responseMessage.json.headers["content-type"] = response.body.type;
-      } else if (response.body instanceof URLSearchParams) {
-        responseMessage.json.body = response.body.toString();
-        responseMessage.json.headers["standard-server"] = "url-search-params";
-      }
-      if (signal.aborted) {
-        return;
-      }
       await this.send(responseMessage);
       if (signal.aborted) {
         return;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@standardserver/peer",
   "type": "module",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "license": "MIT",
   "homepage": "https://standardserver.dev",
   "repository": {
@@ -20,8 +20,8 @@
     "dist"
   ],
   "dependencies": {
-    "@standardserver/core": "0.0.0",
-    "@standardserver/shared": "0.0.0"
+    "@standardserver/core": "0.0.2",
+    "@standardserver/shared": "0.0.2"
   },
   "scripts": {
     "build": "unbuild",