@floegence/flowersec-core 0.1.2 → 0.2.0

package/dist/client-connect/connectCore.js

@@ -5,7 +5,7 @@ import { RpcClient } from "../rpc/client.js";
 import { writeStreamHello } from "../streamhello/streamHello.js";
 import { normalizeObserver, nowSeconds } from "../observability/observer.js";
 import { base64urlDecode } from "../utils/base64url.js";
-import { FlowersecError, throwIfAborted } from "../utils/errors.js";
+import { AbortError, FlowersecError, throwIfAborted } from "../utils/errors.js";
 import { WebSocketBinaryTransport, WsCloseError } from "../ws-client/binaryTransport.js";
 import { OriginMismatchError, WsFactoryRequiredError, classifyConnectError, classifyHandshakeError, createWebSocket, waitOpen, withAbortAndTimeout, } from "./common.js";
 import { isTunnelAttachCloseReason } from "./tunnelAttachCloseReason.js";
@@ -177,14 +177,7 @@ export async function connectCore(args) {
             secure.close();
             throw new FlowersecError({ path: args.path, stage: "yamux", code: "open_stream_failed", message: "open rpc stream failed", cause: e });
         }
-        const reader = new ByteReader(async () => {
-            try {
-                return await rpcStream.read();
-            }
-            catch {
-                return null;
-            }
-        });
+        const reader = new ByteReader(() => rpcStream.read());
         const readExactly = (n) => reader.readExactly(n);
         const write = (b) => rpcStream.write(b);
         try {
@@ -252,9 +245,28 @@ export async function connectCore(args) {
             mux,
             rpc,
             ping,
-            openStream: async (kind) => {
+            openStream: async (kind, opts = {}) => {
                 if (kind == null || kind === "")
                     throw new FlowersecError({ path: args.path, stage: "validate", code: "missing_stream_kind", message: "missing stream kind" });
+                if (opts.signal?.aborted) {
+                    throw new FlowersecError({
+                        path: args.path,
+                        stage: "yamux",
+                        code: "canceled",
+                        message: "open stream aborted",
+                        cause: opts.signal.reason,
+                    });
+                }
+                const abortReason = (signal) => {
+                    const r = signal.reason;
+                    if (r instanceof Error)
+                        return r;
+                    if (typeof r === "string" && r !== "")
+                        return new AbortError(r);
+                    return new AbortError("aborted");
+                };
+                const signal = opts.signal;
+                let abortListener;
                 let s;
                 try {
                     s = await mux.openStream();
@@ -262,10 +274,59 @@ export async function connectCore(args) {
                 catch (e) {
                     throw new FlowersecError({ path: args.path, stage: "yamux", code: "open_stream_failed", message: "open stream failed", cause: e });
                 }
+                if (signal != null) {
+                    abortListener = () => {
+                        try {
+                            s.reset(abortReason(signal));
+                        }
+                        catch {
+                            // ignore
+                        }
+                    };
+                    signal.addEventListener("abort", abortListener, { once: true });
+                    if (signal.aborted)
+                        abortListener();
+                }
+                if (signal?.aborted) {
+                    if (abortListener != null)
+                        signal.removeEventListener("abort", abortListener);
+                    try {
+                        await s.close();
+                    }
+                    catch {
+                        // ignore
+                    }
+                    throw new FlowersecError({
+                        path: args.path,
+                        stage: "yamux",
+                        code: "canceled",
+                        message: "open stream aborted",
+                        cause: signal.reason,
+                    });
+                }
                 try {
                     await writeStreamHello((b) => s.write(b), kind);
                 }
                 catch (err) {
+                    if (signal?.aborted) {
+                        if (abortListener != null)
+                            signal.removeEventListener("abort", abortListener);
+                        try {
+                            await s.close();
+                        }
+                        catch {
+                            // ignore
+                        }
+                        throw new FlowersecError({
+                            path: args.path,
+                            stage: "yamux",
+                            code: "canceled",
+                            message: "open stream aborted",
+                            cause: signal.reason,
+                        });
+                    }
+                    if (signal != null && abortListener != null)
+                        signal.removeEventListener("abort", abortListener);
                     try {
                         await s.close();
                     }

package/dist/client.d.ts

@@ -7,7 +7,9 @@ export type Client = Readonly<{
     path: ClientPath;
     endpointInstanceId?: string;
     rpc: RpcClient;
-    openStream: (kind: string) => Promise<YamuxStream>;
+    openStream: (kind: string, opts?: Readonly<{
+        signal?: AbortSignal;
+    }>) => Promise<YamuxStream>;
     ping: () => Promise<void>;
     close: () => void;
 }>;

package/dist/framing/index.d.ts

@@ -0,0 +1 @@
+export * from "./jsonframe.js";

package/dist/framing/index.js

@@ -0,0 +1 @@
+export * from "./jsonframe.js";

package/dist/framing/jsonframe.d.ts

@@ -0,0 +1,14 @@
+export declare const DEFAULT_MAX_JSON_FRAME_BYTES: number;
+export declare class JsonFramingError extends Error {
+}
+type WriteFn = (b: Uint8Array) => Promise<void>;
+type WriteLike = Readonly<{
+    write: (b: Uint8Array) => Promise<void>;
+}>;
+type ReadExactlyFn = (n: number) => Promise<Uint8Array>;
+type ReadExactlyLike = Readonly<{
+    readExactly: (n: number) => Promise<Uint8Array>;
+}>;
+export declare function writeJsonFrame(write: WriteFn | WriteLike, v: unknown): Promise<void>;
+export declare function readJsonFrame(readExactly: ReadExactlyFn | ReadExactlyLike, maxBytes: number): Promise<unknown>;
+export {};

package/dist/{rpc/framing.js → framing/jsonframe.js}

@@ -1,8 +1,15 @@
 import { readU32be, u32be } from "../utils/bin.js";
+export const DEFAULT_MAX_JSON_FRAME_BYTES = 1 << 20;
 const te = new TextEncoder();
 const td = new TextDecoder();
-// RpcFramingError marks malformed or oversized frames.
-export class RpcFramingError extends Error {
+// JsonFramingError marks malformed or oversized frames.
+export class JsonFramingError extends Error {
+}
+function normalizeWrite(write) {
+    return typeof write === "function" ? write : (b) => write.write(b);
+}
+function normalizeReadExactly(readExactly) {
+    return typeof readExactly === "function" ? readExactly : (n) => readExactly.readExactly(n);
 }
 // writeJsonFrame encodes a JSON payload with a 4-byte length prefix.
 export async function writeJsonFrame(write, v) {
@@ -11,14 +18,15 @@ export async function writeJsonFrame(write, v) {
     const out = new Uint8Array(4 + json.length);
     out.set(hdr, 0);
     out.set(json, 4);
-    await write(out);
+    await normalizeWrite(write)(out);
 }
 // readJsonFrame reads and parses a length-prefixed JSON payload.
 export async function readJsonFrame(readExactly, maxBytes) {
-    const hdr = await readExactly(4);
+    const read = normalizeReadExactly(readExactly);
+    const hdr = await read(4);
     const n = readU32be(hdr, 0);
     if (maxBytes > 0 && n > maxBytes)
-        throw new RpcFramingError("frame too large");
-    const payload = await readExactly(n);
+        throw new JsonFramingError("frame too large");
+    const payload = await read(n);
     return JSON.parse(td.decode(payload));
 }

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export * from "./utils/base64url.js";
 export * from "./utils/bin.js";
 export * from "./utils/errors.js";
+export * from "./framing/index.js";
+export * from "./streamio/index.js";
 export * from "./e2ee/constants.js";
 export * from "./e2ee/framing.js";
 export * from "./e2ee/transcript.js";

package/dist/index.js

@@ -1,6 +1,8 @@
 export * from "./utils/base64url.js";
 export * from "./utils/bin.js";
 export * from "./utils/errors.js";
+export * from "./framing/index.js";
+export * from "./streamio/index.js";
 export * from "./e2ee/constants.js";
 export * from "./e2ee/framing.js";
 export * from "./e2ee/transcript.js";

package/dist/rpc/client.js

@@ -1,5 +1,5 @@
 import { normalizeObserver, nowSeconds } from "../observability/observer.js";
-import { readJsonFrame, writeJsonFrame } from "./framing.js";
+import { DEFAULT_MAX_JSON_FRAME_BYTES, readJsonFrame, writeJsonFrame } from "../framing/jsonframe.js";
 import { assertRpcEnvelope } from "./validate.js";
 // Guard against precision loss when encoding request IDs as numbers.
 const MAX_SAFE_REQUEST_ID = BigInt(Number.MAX_SAFE_INTEGER);
@@ -108,7 +108,7 @@ export class RpcClient {
     async readLoop() {
         try {
             while (!this.closed) {
-                const v = assertRpcEnvelope(await readJsonFrame(this.readExactly, 1 << 20));
+                const v = assertRpcEnvelope(await readJsonFrame(this.readExactly, DEFAULT_MAX_JSON_FRAME_BYTES));
                 if (v.response_to === 0) {
                     // Notification: response_to=0 and request_id=0.
                     if (v.request_id === 0) {

package/dist/rpc/index.d.ts

@@ -1,4 +1,3 @@
-export * from "./framing.js";
 export * from "./caller.js";
 export * from "./client.js";
 export * from "./server.js";

package/dist/rpc/index.js

@@ -1,4 +1,3 @@
-export * from "./framing.js";
 export * from "./caller.js";
 export * from "./client.js";
 export * from "./server.js";

package/dist/rpc/server.js

@@ -1,4 +1,4 @@
-import { readJsonFrame, writeJsonFrame } from "./framing.js";
+import { DEFAULT_MAX_JSON_FRAME_BYTES, readJsonFrame, writeJsonFrame } from "../framing/jsonframe.js";
 import { assertRpcEnvelope } from "./validate.js";
 // RpcServer dispatches request envelopes to registered handlers.
 export class RpcServer {
@@ -21,7 +21,7 @@ export class RpcServer {
         while (!this.closed) {
             if (signal?.aborted)
                 throw signal.reason ?? new Error("aborted");
-            const v = assertRpcEnvelope(await readJsonFrame(this.readExactly, 1 << 20));
+            const v = assertRpcEnvelope(await readJsonFrame(this.readExactly, DEFAULT_MAX_JSON_FRAME_BYTES));
             if (v.response_to !== 0)
                 continue;
             if (v.request_id === 0) {

package/dist/streamhello/streamHello.js

@@ -1,4 +1,4 @@
-import { readJsonFrame, writeJsonFrame } from "../rpc/framing.js";
+import { readJsonFrame, writeJsonFrame } from "../framing/jsonframe.js";
 // writeStreamHello sends the initial stream greeting.
 export async function writeStreamHello(write, kind) {
     const h = { kind, v: 1 };

package/dist/streamio/index.d.ts

@@ -0,0 +1,15 @@
+import { ByteReader } from "../yamux/byteReader.js";
+import type { YamuxStream } from "../yamux/stream.js";
+export declare function readMaybe(stream: YamuxStream): Promise<Uint8Array | null>;
+export declare function createByteReader(stream: YamuxStream, opts?: Readonly<{
+    signal?: AbortSignal;
+}>): ByteReader;
+export declare function readExactly(reader: ByteReader, n: number, opts?: Readonly<{
+    signal?: AbortSignal;
+}>): Promise<Uint8Array>;
+export type ReadNBytesOptions = Readonly<{
+    chunkSize?: number;
+    signal?: AbortSignal;
+    onProgress?: (read: number) => void;
+}>;
+export declare function readNBytes(reader: ByteReader, n: number, opts?: ReadNBytesOptions): Promise<Uint8Array>;

package/dist/streamio/index.js

@@ -0,0 +1,58 @@
+import { AbortError, throwIfAborted } from "../utils/errors.js";
+import { ByteReader } from "../yamux/byteReader.js";
+function abortReasonToError(signal) {
+    const r = signal.reason;
+    if (r instanceof Error)
+        return r;
+    if (typeof r === "string" && r !== "")
+        return new AbortError(r);
+    return new AbortError("aborted");
+}
+function bindAbortToStream(stream, signal) {
+    const onAbort = () => {
+        try {
+            stream.reset(abortReasonToError(signal));
+        }
+        catch {
+            // Best-effort cancel.
+        }
+    };
+    if (signal.aborted) {
+        onAbort();
+        return;
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+}
+// readMaybe reads the next chunk or null on EOF.
+export async function readMaybe(stream) {
+    return await stream.read();
+}
+// createByteReader adapts a YamuxStream to a ByteReader (EOF is handled by YamuxStream.read()).
+export function createByteReader(stream, opts = {}) {
+    if (opts.signal != null)
+        bindAbortToStream(stream, opts.signal);
+    return new ByteReader(() => stream.read());
+}
+// readExactly reads n bytes (or throws on EOF/error). If signal aborts, the caller is expected to reset/close the stream.
+export async function readExactly(reader, n, opts = {}) {
+    throwIfAborted(opts.signal, "read aborted");
+    return await reader.readExactly(n);
+}
+// readNBytes reads exactly n bytes and returns them as a single contiguous buffer.
+export async function readNBytes(reader, n, opts = {}) {
+    const total = Math.max(0, Math.floor(n));
+    const out = new Uint8Array(total);
+    if (total === 0)
+        return out;
+    const chunkSize = Math.max(1, Math.floor(opts.chunkSize ?? 64 * 1024));
+    let off = 0;
+    while (off < total) {
+        throwIfAborted(opts.signal, "read aborted");
+        const take = Math.min(chunkSize, total - off);
+        const chunk = await reader.readExactly(take);
+        out.set(chunk, off);
+        off += chunk.length;
+        opts.onProgress?.(off);
+    }
+    return out;
+}

package/dist/yamux/byteReader.js

@@ -1,3 +1,4 @@
+import { StreamEOFError } from "./errors.js";
 // ByteReader buffers incoming chunks and supports exact reads.
 export class ByteReader {
     readChunk;
@@ -15,7 +16,7 @@ export class ByteReader {
         while (this.buffered < n) {
             const chunk = await this.readChunk();
             if (chunk == null)
-                throw new Error("eof");
+                throw new StreamEOFError();
             if (chunk.length === 0)
                 continue;
             this.chunks.push(chunk);

package/dist/yamux/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class StreamEOFError extends Error {
+    constructor(message?: string);
+}
+export declare function isStreamEOFError(e: unknown): e is StreamEOFError;

package/dist/yamux/errors.js

@@ -0,0 +1,10 @@
+// StreamEOFError marks end-of-stream for yamux reads.
+export class StreamEOFError extends Error {
+    constructor(message = "eof") {
+        super(message);
+        this.name = "StreamEOFError";
+    }
+}
+export function isStreamEOFError(e) {
+    return e instanceof StreamEOFError;
+}

package/dist/yamux/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./constants.js";
 export * from "./byteReader.js";
+export * from "./errors.js";
 export * from "./header.js";
 export * from "./session.js";
 export * from "./stream.js";

package/dist/yamux/index.js

@@ -1,5 +1,6 @@
 export * from "./constants.js";
 export * from "./byteReader.js";
+export * from "./errors.js";
 export * from "./header.js";
 export * from "./session.js";
 export * from "./stream.js";

package/dist/yamux/stream.d.ts

@@ -15,7 +15,7 @@ export declare class YamuxStream {
     open(): Promise<void>;
     onData(data: Uint8Array, flags: number): void;
     onWindowUpdate(delta: number, flags: number): void;
-    read(): Promise<Uint8Array>;
+    read(): Promise<Uint8Array | null>;
     write(data: Uint8Array): Promise<void>;
     close(): Promise<void>;
     reset(err: Error): void;

package/dist/yamux/stream.js

@@ -54,7 +54,7 @@ export class YamuxStream {
         this.sendWindow += delta >>> 0;
         this.session.notifySendWindow(this.id);
     }
-    // read resolves with the next data chunk or throws on EOF/reset.
+    // read resolves with the next data chunk, null on EOF, or throws on reset/errors.
     async read() {
         while (true) {
             if (this.error != null)
@@ -66,7 +66,7 @@ export class YamuxStream {
                 return b;
             }
             if (this.state === "closed" || this.state === "remoteClose")
-                throw new Error("eof");
+                return null;
             await new Promise((resolve) => this.readWaiters.push(resolve));
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floegence/flowersec-core",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Flowersec core TypeScript library (browser-friendly E2EE + multiplexing over WebSocket).",
   "license": "MIT",
   "repository": {
@@ -36,6 +36,14 @@
       "types": "./dist/browser/index.d.ts",
       "default": "./dist/browser/index.js"
     },
+    "./framing": {
+      "types": "./dist/framing/index.d.ts",
+      "default": "./dist/framing/index.js"
+    },
+    "./streamio": {
+      "types": "./dist/streamio/index.d.ts",
+      "default": "./dist/streamio/index.js"
+    },
     "./rpc": {
       "types": "./dist/rpc/index.d.ts",
       "default": "./dist/rpc/index.js"

package/dist/rpc/framing.d.ts

@@ -1,4 +0,0 @@
-export declare class RpcFramingError extends Error {
-}
-export declare function writeJsonFrame(write: (b: Uint8Array) => Promise<void>, v: unknown): Promise<void>;
-export declare function readJsonFrame(readExactly: (n: number) => Promise<Uint8Array>, maxBytes: number): Promise<unknown>;