@floegence/flowersec-core 0.26.0 → 2.0.0

package/dist/public/contract.d.ts

@@ -0,0 +1,83 @@
+import type { StreamMetadata } from "./streamMetadata.js";
+export type CarrierKind = "websocket" | "raw_quic" | "webtransport";
+export type PathKind = "direct" | "tunnel";
+export type JsonPrimitive = null | boolean | number | string;
+export type JsonValue = JsonPrimitive | JsonObject | readonly JsonValue[];
+export type JsonObject = Readonly<{
+    [key: string]: JsonValue;
+}>;
+export type OperationOptions = Readonly<{
+    signal?: AbortSignal;
+}>;
+export type UnreliableMessageSendOptions = OperationOptions & Readonly<{
+    expiresAtUnixMs: number;
+}>;
+export type UnreliableMessageSendResult = "accepted" | "dropped_budget" | "dropped_expired" | "dropped_carrier";
+export interface UnreliableMessageChannel {
+    readonly maxMessageSize: 976;
+    send(message: Uint8Array, options: UnreliableMessageSendOptions): Promise<UnreliableMessageSendResult>;
+    receive(options?: OperationOptions): Promise<Uint8Array>;
+}
+export declare class UnreliableMessageError extends Error {
+    readonly code: "invalid_message" | "closed" | "operation_failed";
+    constructor(code: "invalid_message" | "closed" | "operation_failed");
+}
+export type StreamOpenOptions = OperationOptions & Readonly<{
+    metadata?: StreamMetadata;
+}>;
+export type SessionErrorCode = "canceled" | "timeout" | "closed" | "going_away" | "resource_exhausted" | "stream_rejected" | "stream_reset" | "rekey_failed" | "liveness_failed" | "unreliable_unavailable" | "unreliable_too_large" | "unreliable_dropped" | "operation_failed";
+/** A closed, carrier-neutral session failure with no internal cause or peer detail. */
+export declare class SessionError extends Error {
+    readonly code: SessionErrorCode;
+    constructor(code: SessionErrorCode);
+}
+export type RpcResult<Response = unknown> = Readonly<{
+    ok: true;
+    payload: Response;
+}> | Readonly<{
+    ok: false;
+    error: Readonly<{
+        code: number;
+        message?: string;
+    }>;
+}>;
+export interface RpcPeer {
+    call<Request = unknown, Response = unknown>(typeId: number, payload: Request, decodeResponse: (payload: JsonValue) => Response, signal?: AbortSignal): Promise<RpcResult<Response>>;
+    notify<Payload = unknown>(typeId: number, payload: Payload): Promise<void>;
+    onNotify<Payload = unknown>(typeId: number, handler: (payload: Payload) => void): () => void;
+}
+export interface ByteStream {
+    readonly kind: string;
+    readonly terminalError: SessionError | undefined;
+    read(options?: OperationOptions): Promise<Uint8Array | null>;
+    write(data: Uint8Array, options?: OperationOptions): Promise<number>;
+    closeWrite(): Promise<void>;
+    reset(): Promise<void>;
+    close(): Promise<void>;
+}
+export interface IncomingStream {
+    readonly kind: string;
+    readonly metadata: StreamMetadata;
+    readonly stream: ByteStream;
+}
+export type SessionTermination = Readonly<{
+    error: SessionError;
+}>;
+export interface Session {
+    readonly rpc: RpcPeer;
+    readonly unreliableMessages?: UnreliableMessageChannel;
+    openStream(kind: string, options?: StreamOpenOptions): Promise<ByteStream>;
+    acceptStream(options?: OperationOptions): Promise<IncomingStream>;
+    rekey(options?: OperationOptions): Promise<void>;
+    probeLiveness(options?: OperationOptions): Promise<number>;
+    waitTermination(): Promise<SessionTermination>;
+    close(): Promise<void>;
+}
+export type RetryDisposition = Readonly<{
+    kind: "terminal";
+}> | Readonly<{
+    kind: "retryable";
+}> | Readonly<{
+    kind: "retry_after";
+    notBeforeUnixMilliseconds: number;
+}>;

package/dist/public/contract.js

@@ -0,0 +1,17 @@
+export class UnreliableMessageError extends Error {
+    code;
+    constructor(code) {
+        super(`Flowersec unreliable message failed (code=${code})`);
+        this.code = code;
+        this.name = "UnreliableMessageError";
+    }
+}
+/** A closed, carrier-neutral session failure with no internal cause or peer detail. */
+export class SessionError extends Error {
+    code;
+    constructor(code) {
+        super(`Flowersec session failed (code=${code})`);
+        this.code = code;
+        this.name = "SessionError";
+    }
+}

package/dist/public/streamMetadata.d.ts

@@ -0,0 +1,10 @@
+import type { JsonObject } from "./contract.js";
+export declare class StreamMetadataError extends Error {
+    constructor();
+}
+export declare class StreamMetadata {
+    readonly values: JsonObject;
+    private readonly streamMetadataBrand;
+    private constructor();
+}
+export declare function createStreamMetadata(values: JsonObject): StreamMetadata;

package/dist/public/streamMetadata.js

@@ -0,0 +1,40 @@
+import { canonicalStreamMetadataJSONV2Internal } from "../v2/protocol.js";
+export class StreamMetadataError extends Error {
+    constructor() {
+        super("invalid Flowersec stream metadata");
+        this.name = "StreamMetadataError";
+    }
+}
+export class StreamMetadata {
+    values;
+    constructor(values) {
+        this.values = values;
+        Object.freeze(this);
+    }
+    /** @internal */
+    static fromCanonicalValues(values) {
+        return new StreamMetadata(values);
+    }
+}
+export function createStreamMetadata(values) {
+    try {
+        const canonical = canonicalStreamMetadataJSONV2Internal(values);
+        return StreamMetadata.fromCanonicalValues(deepFreeze(JSON.parse(canonical)));
+    }
+    catch {
+        throw new StreamMetadataError();
+    }
+}
+/** @internal */
+export function streamMetadataValues(metadata) {
+    if (!(metadata instanceof StreamMetadata))
+        throw new StreamMetadataError();
+    return metadata.values;
+}
+function deepFreeze(value) {
+    if (typeof value !== "object" || value === null || Object.isFrozen(value))
+        return value;
+    for (const child of Object.values(value))
+        deepFreeze(child);
+    return Object.freeze(value);
+}

package/dist/rpc/caller.d.ts

@@ -1,4 +1,4 @@
-import type { RpcError } from "../gen/flowersec/rpc/v1.gen.js";
+import type { RpcError } from "./wire.js";
 export type RpcCaller = {
     call(typeId: number, payload: unknown, signal?: AbortSignal): Promise<{
         payload: unknown;

package/dist/rpc/client.d.ts

@@ -1,5 +1,4 @@
-import type { RpcError } from "../gen/flowersec/rpc/v1.gen.js";
-import { type ClientObserverLike } from "../observability/observer.js";
+import type { RpcError } from "./wire.js";
 export declare class RpcClient {
     private readonly readExactly;
     private readonly write;
@@ -7,10 +6,8 @@ export declare class RpcClient {
     private readonly pending;
     private readonly notifyHandlers;
     private closed;
-    private readonly observer;
     private readonly onTerminal;
     constructor(readExactly: (n: number) => Promise<Uint8Array>, write: (b: Uint8Array) => Promise<void>, opts?: Readonly<{
-        observer?: ClientObserverLike;
         onTerminal?: (error: Error) => void;
     }>);
     call(typeId: number, payload: unknown, signal?: AbortSignal): Promise<{

package/dist/rpc/client.js

@@ -1,4 +1,3 @@
-import { normalizeObserver, nowSeconds } from "../observability/observer.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.
@@ -15,13 +14,10 @@ export class RpcClient {
     notifyHandlers = new Map();
     // Closed state to stop the read loop and reject calls.
     closed = false;
-    // Observer for RPC events.
-    observer;
     onTerminal;
     constructor(readExactly, write, opts = {}) {
         this.readExactly = readExactly;
         this.write = write;
-        this.observer = normalizeObserver(opts.observer);
         this.onTerminal = opts.onTerminal;
         void this.readLoop();
     }
@@ -31,10 +27,6 @@ export class RpcClient {
             throw new Error("rpc client closed");
         if (this.nextId > MAX_SAFE_REQUEST_ID)
             throw new Error("request id overflow");
-        const start = nowSeconds();
-        const record = (result) => {
-            this.observer.onRpcCall(result, nowSeconds() - start);
-        };
         const requestId = this.nextId;
         this.nextId += 1n;
         const env = {
@@ -51,12 +43,10 @@ export class RpcClient {
         }
         catch (e) {
             this.pending.delete(requestId);
-            record("transport_error");
             throw e;
         }
         if (signal?.aborted) {
             this.pending.delete(requestId);
-            record("canceled");
             throw signal.reason ?? new Error("aborted");
         }
         let resp;
@@ -65,11 +55,8 @@ export class RpcClient {
         }
         catch (e) {
             this.pending.delete(requestId);
-            record(signal?.aborted ? "canceled" : "transport_error");
             throw e;
         }
-        const result = rpcResultFromError(resp.error);
-        record(result);
         if (resp.error == null)
             return { payload: resp.payload };
         return { payload: resp.payload, error: resp.error };
@@ -114,7 +101,6 @@ export class RpcClient {
                 if (v.response_to === 0) {
                     // Notification: response_to=0 and request_id=0.
                     if (v.request_id === 0) {
-                        this.observer.onRpcNotify();
                         const set = this.notifyHandlers.get(v.type_id >>> 0);
                         if (set != null) {
                             for (const h of set) {
@@ -172,10 +158,3 @@ async function raceAbort(p, signal) {
         });
     });
 }
-function rpcResultFromError(err) {
-    if (err == null)
-        return "ok";
-    if (err.code === 404)
-        return "handler_not_found";
-    return "rpc_error";
-}

package/dist/rpc/rpcProxy.d.ts

@@ -10,7 +10,7 @@ export declare class RpcProxy {
     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;
+        error?: import("./wire.js").RpcError;
     }>;
     notify(typeId: number, payload: unknown): Promise<void>;
 }

package/dist/rpc/server.d.ts

@@ -1,4 +1,4 @@
-import type { RpcError } from "../gen/flowersec/rpc/v1.gen.js";
+import type { RpcError } from "./wire.js";
 export type RpcHandler = (payload: unknown) => Promise<{
     payload: unknown;
     error?: RpcError;

package/dist/rpc/validate.d.ts

@@ -1,2 +1,2 @@
-import type { RpcEnvelope } from "../gen/flowersec/rpc/v1.gen.js";
+import type { RpcEnvelope } from "./wire.js";
 export declare function assertRpcEnvelope(v: unknown): RpcEnvelope;

package/dist/rpc/wire.d.ts

@@ -0,0 +1,15 @@
+export interface RpcEnvelope {
+    type_id: number;
+    request_id: number;
+    response_to: number;
+    payload: unknown;
+    error?: RpcError;
+}
+export interface RpcError {
+    code: number;
+    message?: string;
+}
+export interface StreamHello {
+    kind: string;
+    v: number;
+}

package/dist/runtime/errors.d.ts

@@ -0,0 +1,6 @@
+export type RuntimeErrorCode = "runtime_unsupported" | "runtime_start_failed" | "runtime_crashed";
+export declare class RuntimeError extends Error {
+    readonly code: RuntimeErrorCode;
+    readonly cause?: unknown | undefined;
+    constructor(code: RuntimeErrorCode, message: string, cause?: unknown | undefined);
+}

package/dist/runtime/errors.js

@@ -0,0 +1,10 @@
+export class RuntimeError extends Error {
+    code;
+    cause;
+    constructor(code, message, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = "RuntimeError";
+    }
+}

package/dist/transport/webSocketAdapter.d.ts

@@ -0,0 +1,24 @@
+import { type CarrierSessionV2 } from "../v2/carrier.js";
+import type { OperationOptionsV2, PathKind } from "../v2/contract.js";
+export type WebSocketBinaryTransportV2 = Readonly<{
+    readBinary(options?: Readonly<{
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }>): Promise<Uint8Array>;
+    writeBinary(data: Uint8Array, options?: OperationOptionsV2): Promise<void>;
+    close(): void;
+}>;
+export type WebSocketResourcePolicyV2 = Readonly<{
+    maxConcurrentStreams?: number;
+    maxFrameBytes?: number;
+    preferredWriteBytes?: number;
+    maxStreamWriteQueueBytes?: number;
+    maxStreamReceiveBytes?: number;
+    maxSessionReceiveBytes?: number;
+}>;
+export declare function createWebSocketCarrierSessionV2(transport: WebSocketBinaryTransportV2, options: Readonly<{
+    path: PathKind;
+    client: boolean;
+    inboundBidirectionalStreamCapacity: number;
+    resourcePolicy?: WebSocketResourcePolicyV2;
+}>): CarrierSessionV2;

package/dist/transport/webSocketAdapter.js

@@ -0,0 +1,234 @@
+import { YamuxSession } from "../yamux/session.js";
+import { CarrierError } from "../v2/carrier.js";
+export function createWebSocketCarrierSessionV2(transport, options) {
+    return new WebSocketYamuxCarrierSession(transport, options);
+}
+class WebSocketYamuxCarrierSession {
+    kind = "websocket";
+    path;
+    inboundBidirectionalStreamCapacity;
+    unreliableDatagrams = undefined;
+    incoming = new IncomingStreamQueue();
+    yamux;
+    termination = deferred();
+    terminalError;
+    closed = false;
+    constructor(transport, options) {
+        requireCapacity(options.inboundBidirectionalStreamCapacity);
+        this.path = options.path;
+        this.inboundBidirectionalStreamCapacity = options.inboundBidirectionalStreamCapacity;
+        const duplex = {
+            read: async () => await transport.readBinary(),
+            write: async (chunk) => await transport.writeBinary(chunk),
+            close: () => transport.close(),
+        };
+        const policy = options.resourcePolicy ?? {};
+        this.yamux = new YamuxSession(duplex, {
+            client: options.client,
+            limits: {
+                maxActiveStreams: Math.max(policy.maxConcurrentStreams ?? this.inboundBidirectionalStreamCapacity, this.inboundBidirectionalStreamCapacity),
+                maxInboundStreams: this.inboundBidirectionalStreamCapacity,
+                ...(policy.maxFrameBytes === undefined ? {} : { maxFrameBytes: policy.maxFrameBytes }),
+                ...(policy.preferredWriteBytes === undefined ? {} : { preferredOutboundFrameBytes: policy.preferredWriteBytes }),
+                ...(policy.maxStreamWriteQueueBytes === undefined ? {} : { maxStreamWriteQueueBytes: policy.maxStreamWriteQueueBytes }),
+                ...(policy.maxStreamReceiveBytes === undefined ? {} : { maxStreamReceiveBytes: policy.maxStreamReceiveBytes }),
+                ...(policy.maxSessionReceiveBytes === undefined ? {} : { maxSessionReceiveBytes: policy.maxSessionReceiveBytes }),
+            },
+            onIncomingStream: (stream) => this.incoming.push(new YamuxCarrierStreamAdapter(stream)),
+            onTerminal: (error) => {
+                const failure = error instanceof CarrierError
+                    ? error
+                    : new CarrierError("closed", "WebSocket carrier terminated", error);
+                this.closed = true;
+                this.terminalError = failure;
+                this.incoming.fail(failure);
+                this.termination.resolve();
+            },
+        });
+    }
+    async openStream(options = {}) {
+        this.assertOpen();
+        try {
+            return new YamuxCarrierStreamAdapter(await this.yamux.openStream(options));
+        }
+        catch (error) {
+            throw error instanceof CarrierError ? error : new CarrierError("closed", "WebSocket stream open failed", error);
+        }
+    }
+    async acceptStream(options = {}) {
+        this.assertOpen();
+        return await this.incoming.shift(options.signal);
+    }
+    async close() {
+        this.closeLocally();
+    }
+    abort() {
+        this.closeLocally();
+    }
+    async waitTermination() {
+        await this.termination.promise;
+        if (this.terminalError !== undefined)
+            throw this.terminalError;
+    }
+    assertOpen() {
+        if (this.terminalError !== undefined)
+            throw this.terminalError;
+        if (this.closed)
+            throw new CarrierError("closed", "WebSocket carrier is closed");
+    }
+    closeLocally() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const failure = new CarrierError("closed", "WebSocket carrier is closed");
+        this.incoming.fail(failure);
+        this.yamux.close();
+        this.termination.resolve();
+    }
+}
+class YamuxCarrierStreamAdapter {
+    stream;
+    constructor(stream) {
+        this.stream = stream;
+    }
+    async read(options = {}) {
+        try {
+            return await abortable(this.stream.read(), options.signal, () => this.stream.abort());
+        }
+        catch (error) {
+            throw error instanceof CarrierError ? error : new CarrierError("reset", "WebSocket stream read failed", error);
+        }
+    }
+    async write(data, options = {}) {
+        throwIfAborted(options.signal);
+        try {
+            await abortable(this.stream.write(data), options.signal, () => this.stream.abort());
+        }
+        catch (error) {
+            throw error instanceof CarrierError ? error : new CarrierError("reset", "WebSocket stream write failed", error);
+        }
+        return data.length;
+    }
+    async closeWrite() {
+        await this.stream.close();
+    }
+    async reset() {
+        await this.stream.reset();
+    }
+    async stopSending() {
+        throw new CarrierError("stop_sending_unavailable", "WebSocket/Yamux cannot stop only the receive side of a bidirectional stream");
+    }
+    abort(error) {
+        this.stream.abort(error);
+    }
+}
+class IncomingStreamQueue {
+    values = [];
+    waiters = new Set();
+    terminalError;
+    push(value) {
+        if (this.terminalError !== undefined) {
+            value.abort(this.terminalError);
+            return;
+        }
+        const waiter = this.waiters.values().next().value;
+        if (waiter === undefined)
+            this.values.push(value);
+        else {
+            this.waiters.delete(waiter);
+            waiter.deliver(value);
+        }
+    }
+    shift(signal) {
+        throwIfAborted(signal);
+        if (this.terminalError !== undefined)
+            return Promise.reject(this.terminalError);
+        const value = this.values.shift();
+        if (value !== undefined)
+            return Promise.resolve(value);
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const cleanup = () => {
+                this.waiters.delete(waiter);
+                signal?.removeEventListener("abort", abort);
+            };
+            const waiter = {
+                deliver: (stream) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    resolve(stream);
+                },
+                fail: (error) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    reject(error);
+                },
+            };
+            const abort = () => waiter.fail(new CarrierError("aborted", "carrier operation aborted"));
+            this.waiters.add(waiter);
+            signal?.addEventListener("abort", abort, { once: true });
+            if (signal?.aborted === true)
+                abort();
+        });
+    }
+    fail(error) {
+        if (this.terminalError !== undefined)
+            return;
+        this.terminalError = error;
+        for (const stream of this.values)
+            stream.abort(error);
+        this.values.length = 0;
+        for (const waiter of this.waiters)
+            waiter.fail(error);
+        this.waiters.clear();
+    }
+}
+function deferred() {
+    let resolve;
+    const promise = new Promise((resolvePromise) => { resolve = resolvePromise; });
+    return { promise, resolve };
+}
+function requireCapacity(value) {
+    if (!Number.isInteger(value) || value < 3 || value > 130) {
+        throw new RangeError("inboundBidirectionalStreamCapacity must be an integer from 3 to 130");
+    }
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted === true)
+        throw new CarrierError("aborted", "carrier operation aborted");
+}
+async function abortable(promise, signal, onAbort) {
+    if (signal === undefined)
+        return await promise;
+    throwIfAborted(signal);
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => signal.removeEventListener("abort", abort);
+        const abort = () => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            onAbort();
+            reject(new CarrierError("aborted", "carrier operation aborted"));
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        void promise.then((value) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(value);
+        }, (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        });
+    });
+}

package/dist/transport/webTransportAdapter.d.ts

@@ -0,0 +1,27 @@
+import { type NativeCarrierSessionV2 } from "../v2/carrier.js";
+import type { PathKind } from "../v2/contract.js";
+export type WebTransportBidirectionalLikeV2 = Readonly<{
+    readable: ReadableStream<Uint8Array>;
+    writable: WritableStream<Uint8Array>;
+}>;
+export type WebTransportDatagramsLikeV2 = Readonly<{
+    readable: ReadableStream<Uint8Array>;
+    writable: WritableStream<Uint8Array>;
+    maxDatagramSize?: number;
+}>;
+export type WebTransportSessionLikeV2 = Readonly<{
+    closed: Promise<unknown>;
+    incomingBidirectionalStreams: ReadableStream<WebTransportBidirectionalLikeV2>;
+    datagrams: WebTransportDatagramsLikeV2;
+    createBidirectionalStream(): Promise<WebTransportBidirectionalLikeV2>;
+    close(info?: Readonly<{
+        closeCode: number;
+        reason: string;
+    }>): void;
+}>;
+export declare function adaptWebTransportCarrierSessionV2(native: WebTransportSessionLikeV2, options: Readonly<{
+    path: PathKind;
+    inboundBidirectionalStreamCapacity: number;
+    datagramMaxSize?: number;
+}>): NativeCarrierSessionV2;
+export declare function hasWebTransportConstructorSurfaceV2(value: unknown): boolean;