@floegence/flowersec-core 0.14.0 → 0.15.0

package/dist/client-connect/connectCore.js

@@ -14,6 +14,19 @@ export async function connectCore(args) {
     const observer = normalizeObserver(args.opts.observer);
     const signal = args.opts.signal;
     const connectStart = nowSeconds();
+    let attachState = args.path === "tunnel" ? "not_started" : "accepted";
+    const reportAttachSuccess = () => {
+        if (args.path !== "tunnel" || attachState !== "sent")
+            return;
+        observer.onAttach("ok", undefined);
+        attachState = "accepted";
+    };
+    const reportAttachFailure = (reason) => {
+        if (args.path !== "tunnel" || attachState !== "sent")
+            return;
+        observer.onAttach("fail", reason);
+        attachState = "failed";
+    };
     const origin = typeof args.opts.origin === "string" ? args.opts.origin.trim() : "";
     if (origin === "") {
         throw new FlowersecError({ path: args.path, stage: "validate", code: "missing_origin", message: "missing origin" });
@@ -131,9 +144,11 @@ export async function connectCore(args) {
         if (args.path === "tunnel") {
             try {
                 ws.send(args.attach.attachJson);
+                attachState = "sent";
             }
             catch (err) {
                 observer.onAttach("fail", "send_failed");
+                attachState = "failed";
                 try {
                     transport.close();
                 }
@@ -161,9 +176,7 @@ export async function connectCore(args) {
                 ...(signal !== undefined ? { signal } : {}),
                 onCancel: () => transport.close(),
             });
-            if (args.path === "tunnel") {
-                observer.onAttach("ok", undefined);
-            }
+            reportAttachSuccess();
             observer.onHandshake(args.path, "ok", undefined, nowSeconds() - handshakeStart);
         }
         catch (err) {
@@ -173,12 +186,12 @@ export async function connectCore(args) {
             if (args.path === "tunnel" && err instanceof WsCloseError) {
                 const reason = err.reason;
                 if (isTunnelAttachCloseReason(reason)) {
-                    observer.onAttach("fail", reason);
+                    reportAttachFailure(reason);
                     throw new FlowersecError({ path: args.path, stage: "attach", code: reason, message: "tunnel rejected attach", cause: err });
                 }
             }
             if (args.path === "tunnel") {
-                observer.onAttach("ok", undefined);
+                reportAttachFailure(handshakeCode === "timeout" ? "timeout" : handshakeCode === "canceled" ? "canceled" : "attach_failed");
             }
             observer.onHandshake(args.path, "fail", handshakeCode, handshakeElapsedSeconds);
             throw new FlowersecError({

package/dist/proxy/bootstrap.d.ts

@@ -7,6 +7,7 @@ import type { ProxyRuntime } from "./runtime.js";
 export type ConnectTunnelProxyBrowserOptions = Readonly<{
     connect?: TunnelConnectBrowserOptions;
     profile?: ProxyProfileName | Partial<ProxyProfile>;
+    runtimeGlobalKey?: string;
     runtime?: RegisterProxyIntegrationOptions["runtime"];
     serviceWorker: ProxyIntegrationServiceWorkerOptions;
     plugins?: readonly ProxyIntegrationPlugin[];

package/dist/proxy/bootstrap.js

@@ -6,6 +6,7 @@ export async function connectTunnelProxyBrowser(grant, opts) {
         client,
         serviceWorker: opts.serviceWorker,
         ...(opts.profile === undefined ? {} : { profile: opts.profile }),
+        ...(opts.runtimeGlobalKey === undefined ? {} : { runtimeGlobalKey: opts.runtimeGlobalKey }),
         ...(opts.runtime === undefined ? {} : { runtime: opts.runtime }),
         ...(opts.plugins === undefined ? {} : { plugins: opts.plugins }),
     };

package/dist/proxy/integration.d.ts

@@ -27,6 +27,7 @@ export type ProxyIntegrationServiceWorkerOptions = Readonly<{
 export type RegisterProxyIntegrationOptions = Readonly<{
     client: Client;
     profile?: ProxyProfileName | Partial<ProxyProfile>;
+    runtimeGlobalKey?: string;
     runtime?: Readonly<{
         maxJsonFrameBytes?: number;
         maxChunkBytes?: number;

package/dist/proxy/integration.js

@@ -172,6 +172,18 @@ function buildRuntimeOptions(profile, runtime) {
         timeoutMs: runtime?.timeoutMs ?? profile.timeoutMs,
     };
 }
+function bindRuntimeGlobal(runtime, key) {
+    const runtimeGlobalKey = String(key ?? "").trim();
+    if (runtimeGlobalKey === "")
+        return null;
+    const target = globalThis;
+    target[runtimeGlobalKey] = runtime;
+    return () => {
+        if (target[runtimeGlobalKey] === runtime) {
+            delete target[runtimeGlobalKey];
+        }
+    };
+}
 export function createProxyIntegrationServiceWorkerScript(opts = {}) {
     const plugins = opts.plugins ?? [];
     let scriptOpts = opts.baseOptions ?? {};
@@ -212,6 +224,7 @@ export async function registerProxyIntegration(input) {
     const profile = resolveProxyProfile(opts.profile);
     const runtimeOpts = buildRuntimeOptions(profile, opts.runtime);
     const runtime = createProxyRuntime({ ...runtimeOpts, client: opts.client });
+    const releaseRuntimeGlobal = bindRuntimeGlobal(runtime, opts.runtimeGlobalKey);
     const swCfg = opts.serviceWorker;
     const repairQueryKey = String(swCfg.repair?.queryKey ?? "_flowersec_sw_repair").trim() || "_flowersec_sw_repair";
     const maxRepairAttempts = Math.max(0, Math.floor(swCfg.repair?.maxAttempts ?? 2));
@@ -280,13 +293,34 @@ export async function registerProxyIntegration(input) {
     return {
         runtime,
         dispose: async () => {
+            let firstError = null;
             if (monitorHandler && sw) {
                 sw.removeEventListener("controllerchange", monitorHandler);
             }
-            runtime.dispose();
+            try {
+                runtime.dispose();
+            }
+            catch (error) {
+                firstError = error;
+            }
             for (const plugin of plugins) {
-                await plugin.onDisposed?.();
+                try {
+                    await plugin.onDisposed?.();
+                }
+                catch (error) {
+                    if (firstError == null)
+                        firstError = error;
+                }
+            }
+            try {
+                releaseRuntimeGlobal?.();
+            }
+            catch (error) {
+                if (firstError == null)
+                    firstError = error;
             }
+            if (firstError != null)
+                throw firstError;
         },
     };
 }

package/dist/rpc/index.d.ts

@@ -2,4 +2,5 @@ export * from "./caller.js";
 export * from "./client.js";
 export * from "./server.js";
 export * from "./callError.js";
+export * from "./rpcProxy.js";
 export * from "./typed.js";

package/dist/rpc/index.js

@@ -2,4 +2,5 @@ export * from "./caller.js";
 export * from "./client.js";
 export * from "./server.js";
 export * from "./callError.js";
+export * from "./rpcProxy.js";
 export * from "./typed.js";

package/dist/rpc/rpcProxy.d.ts

@@ -0,0 +1,16 @@
+import type { RpcClient } from "./client.js";
+export declare class RpcProxyDetachedError extends Error {
+    constructor();
+}
+export declare class RpcProxy {
+    private client;
+    private readonly notifyHandlers;
+    attach(client: RpcClient): void;
+    detach(): void;
+    onNotify(typeId: number, handler: (payload: unknown) => void): () => void;
+    call(typeId: number, payload: unknown, signal?: AbortSignal): Promise<{
+        payload: unknown;
+        error?: import("../gen/flowersec/rpc/v1.gen.js").RpcError;
+    }>;
+    notify(typeId: number, payload: unknown): Promise<void>;
+}

package/dist/rpc/rpcProxy.js

@@ -0,0 +1,58 @@
+export class RpcProxyDetachedError extends Error {
+    constructor() {
+        super("rpc proxy is not attached");
+        this.name = "RpcProxyDetachedError";
+    }
+}
+// RpcProxy keeps notify subscriptions stable across client reattachment.
+export class RpcProxy {
+    client = null;
+    notifyHandlers = new Map();
+    attach(client) {
+        this.detach();
+        this.client = client;
+        for (const [typeId, handlers] of this.notifyHandlers) {
+            for (const [handler, state] of handlers) {
+                state.unsub = client.onNotify(typeId, handler);
+            }
+        }
+    }
+    detach() {
+        for (const [, handlers] of this.notifyHandlers) {
+            for (const [, state] of handlers) {
+                state.unsub?.();
+                delete state.unsub;
+            }
+        }
+        this.client = null;
+    }
+    onNotify(typeId, handler) {
+        const tid = typeId >>> 0;
+        const handlers = this.notifyHandlers.get(tid) ?? new Map();
+        if (!this.notifyHandlers.has(tid))
+            this.notifyHandlers.set(tid, handlers);
+        if (!handlers.has(handler)) {
+            const state = {};
+            if (this.client != null)
+                state.unsub = this.client.onNotify(tid, handler);
+            handlers.set(handler, state);
+        }
+        return () => {
+            const state = handlers.get(handler);
+            state?.unsub?.();
+            handlers.delete(handler);
+            if (handlers.size === 0)
+                this.notifyHandlers.delete(tid);
+        };
+    }
+    async call(typeId, payload, signal) {
+        if (this.client == null)
+            throw new RpcProxyDetachedError();
+        return await this.client.call(typeId, payload, signal);
+    }
+    async notify(typeId, payload) {
+        if (this.client == null)
+            throw new RpcProxyDetachedError();
+        await this.client.notify(typeId, payload);
+    }
+}

package/dist/rpc-proxy/rpcProxy.d.ts

@@ -1,13 +1 @@
-import type { RpcClient } from "../rpc/client.js";
-export declare class RpcProxy {
-    private client;
-    private readonly notifyHandlers;
-    attach(client: RpcClient): void;
-    detach(): void;
-    onNotify(typeId: number, handler: (payload: unknown) => void): () => void;
-    call(typeId: number, payload: unknown, signal?: AbortSignal): Promise<{
-        payload: unknown;
-        error?: import("../gen/flowersec/rpc/v1.gen.js").RpcError;
-    }>;
-    notify(typeId: number, payload: unknown): Promise<void>;
-}
+export { RpcProxy, RpcProxyDetachedError } from "../rpc/rpcProxy.js";

package/dist/rpc-proxy/rpcProxy.js

@@ -1,59 +1 @@
-// RpcProxy allows handlers to survive client reattachment.
-export class RpcProxy {
-    // Active client connection (null when detached).
-    client = null;
-    // Persisted notification handlers across reattachments.
-    notifyHandlers = new Map();
-    // attach wires existing notification handlers to a new client.
-    attach(client) {
-        this.detach();
-        this.client = client;
-        for (const [typeId, handlers] of this.notifyHandlers) {
-            for (const [h, state] of handlers) {
-                state.unsub = client.onNotify(typeId, h);
-            }
-        }
-    }
-    // detach unwires handlers from the current client.
-    detach() {
-        for (const [, handlers] of this.notifyHandlers) {
-            for (const [, state] of handlers) {
-                state.unsub?.();
-                delete state.unsub;
-            }
-        }
-        this.client = null;
-    }
-    // onNotify registers handlers that will be rebound on reattach.
-    onNotify(typeId, handler) {
-        const tid = typeId >>> 0;
-        const handlers = this.notifyHandlers.get(tid) ?? new Map();
-        if (!this.notifyHandlers.has(tid))
-            this.notifyHandlers.set(tid, handlers);
-        if (!handlers.has(handler)) {
-            const state = {};
-            if (this.client != null)
-                state.unsub = this.client.onNotify(tid, handler);
-            handlers.set(handler, state);
-        }
-        return () => {
-            const state = handlers.get(handler);
-            state?.unsub?.();
-            handlers.delete(handler);
-            if (handlers.size === 0)
-                this.notifyHandlers.delete(tid);
-        };
-    }
-    // call forwards the RPC call to the attached client.
-    async call(typeId, payload, signal) {
-        if (this.client == null)
-            throw new Error("rpc proxy is not attached");
-        return await this.client.call(typeId, payload, signal);
-    }
-    // notify forwards a one-way notification to the attached client.
-    async notify(typeId, payload) {
-        if (this.client == null)
-            throw new Error("rpc proxy is not attached");
-        await this.client.notify(typeId, payload);
-    }
-}
+export { RpcProxy, RpcProxyDetachedError } from "../rpc/rpcProxy.js";

package/dist/streamio/index.d.ts

@@ -1,3 +1,4 @@
+import type { Client } from "../client.js";
 import { ByteReader } from "../yamux/byteReader.js";
 import type { YamuxStream } from "../yamux/stream.js";
 export declare function readMaybe(stream: YamuxStream): Promise<Uint8Array | null>;
@@ -13,3 +14,19 @@ export type ReadNBytesOptions = Readonly<{
     onProgress?: (read: number) => void;
 }>;
 export declare function readNBytes(reader: ByteReader, n: number, opts?: ReadNBytesOptions): Promise<Uint8Array>;
+export type JsonFrameChannel = Readonly<{
+    stream: YamuxStream;
+    reader: ByteReader;
+    writeFrame: (value: unknown) => Promise<void>;
+    readFrame: <T = unknown>(opts?: Readonly<{
+        maxBytes?: number;
+        assert?: (value: unknown) => T;
+    }>) => Promise<T>;
+    close: () => Promise<void>;
+}>;
+export type JsonFrameChannelOptions = Readonly<{
+    signal?: AbortSignal;
+    maxJsonFrameBytes?: number;
+}>;
+export declare function createJsonFrameChannel(stream: YamuxStream, opts?: JsonFrameChannelOptions): JsonFrameChannel;
+export declare function openJsonFrameChannel(client: Pick<Client, "openStream">, kind: string, opts?: JsonFrameChannelOptions): Promise<JsonFrameChannel>;

package/dist/streamio/index.js

@@ -1,3 +1,4 @@
+import { DEFAULT_MAX_JSON_FRAME_BYTES, readJsonFrame, writeJsonFrame } from "../framing/jsonframe.js";
 import { AbortError, throwIfAborted } from "../utils/errors.js";
 import { ByteReader } from "../yamux/byteReader.js";
 function abortReasonToError(signal) {
@@ -56,3 +57,34 @@ export async function readNBytes(reader, n, opts = {}) {
     }
     return out;
 }
+function normalizeMaxJsonFrameBytes(maxBytes) {
+    const value = maxBytes ?? DEFAULT_MAX_JSON_FRAME_BYTES;
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error("maxJsonFrameBytes must be a non-negative finite number");
+    }
+    return Math.floor(value);
+}
+export function createJsonFrameChannel(stream, opts = {}) {
+    const reader = createByteReader(stream, opts.signal == null ? {} : { signal: opts.signal });
+    const defaultMaxBytes = normalizeMaxJsonFrameBytes(opts.maxJsonFrameBytes);
+    return {
+        stream,
+        reader,
+        writeFrame: async (value) => {
+            await writeJsonFrame(stream, value);
+        },
+        readFrame: async (readOpts = {}) => {
+            const raw = await readJsonFrame(reader, normalizeMaxJsonFrameBytes(readOpts.maxBytes ?? defaultMaxBytes));
+            if (readOpts.assert != null)
+                return readOpts.assert(raw);
+            return raw;
+        },
+        close: async () => {
+            await stream.close();
+        },
+    };
+}
+export async function openJsonFrameChannel(client, kind, opts = {}) {
+    const stream = await client.openStream(kind, opts.signal == null ? {} : { signal: opts.signal });
+    return createJsonFrameChannel(stream, opts);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floegence/flowersec-core",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Flowersec core TypeScript library (browser-friendly E2EE + multiplexing over WebSocket).",
   "license": "MIT",
   "repository": {
@@ -108,7 +108,10 @@
     "build": "tsc -p tsconfig.build.json",
     "bench": "vitest bench --run",
     "test": "vitest run",
-    "lint": "eslint ."
+    "lint": "eslint .",
+    "verify:package": "node ./scripts/verify-package-exports.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build && npm run verify:package"
   },
   "dependencies": {
     "@noble/ciphers": "^0.6.0",