@secure-exec/core 0.2.1 → 0.3.0-rc.2

package/dist/event-buffer.js

@@ -0,0 +1,313 @@
+import { fromGeneratedExtEnvelope, } from "./ext.js";
+import { ownershipMatchesSelector, ownershipSelectorKey, } from "./ownership.js";
+import { fromGeneratedStreamChannel, fromGeneratedVmLifecycleState, } from "./protocol-maps.js";
+export const ANY_BUFFERED_EVENT_KEY = "*";
+export class SidecarEventBufferOverflow extends Error {
+    capacity;
+    bufferedEvents;
+    eventType;
+    constructor(options) {
+        super(`sidecar event buffer overflow after ${options.bufferedEvents} queued events (capacity ${options.capacity}) while buffering ${options.eventType}`);
+        this.name = "SidecarEventBufferOverflow";
+        this.capacity = options.capacity;
+        this.bufferedEvents = options.bufferedEvents;
+        this.eventType = options.eventType;
+    }
+}
+export class SidecarEventBuffer {
+    capacity;
+    bufferedEvents = new Map();
+    bufferedEventQueues = new Map();
+    nextBufferedEventId = 1;
+    constructor(capacity) {
+        this.capacity = capacity;
+    }
+    get size() {
+        return this.bufferedEvents.size;
+    }
+    buffer(event) {
+        if (this.bufferedEvents.size >= this.capacity) {
+            return new SidecarEventBufferOverflow({
+                capacity: this.capacity,
+                bufferedEvents: this.bufferedEvents.size,
+                eventType: event.payload.type,
+            });
+        }
+        const eventId = this.nextBufferedEventId++;
+        const keys = sidecarEventBufferKeys(event);
+        this.bufferedEvents.set(eventId, {
+            event,
+            keys,
+        });
+        for (const key of keys) {
+            const queue = this.bufferedEventQueues.get(key);
+            if (queue) {
+                queue.add(eventId);
+                continue;
+            }
+            this.bufferedEventQueues.set(key, new Set([eventId]));
+        }
+        return null;
+    }
+    take(matcher) {
+        if (matcher.bufferKey !== null) {
+            return this.takeFromKey(matcher.bufferKey);
+        }
+        const queue = this.bufferedEventQueues.get(ANY_BUFFERED_EVENT_KEY);
+        if (!queue) {
+            return null;
+        }
+        for (const eventId of queue) {
+            const record = this.bufferedEvents.get(eventId);
+            if (!record) {
+                continue;
+            }
+            if (!matcher.matches(record.event)) {
+                continue;
+            }
+            return this.remove(eventId);
+        }
+        return null;
+    }
+    takeFromKey(key) {
+        const queue = this.bufferedEventQueues.get(key);
+        if (!queue) {
+            return null;
+        }
+        for (const eventId of queue) {
+            const record = this.bufferedEvents.get(eventId);
+            if (!record) {
+                queue.delete(eventId);
+                continue;
+            }
+            return this.remove(eventId);
+        }
+        return null;
+    }
+    remove(eventId) {
+        const record = this.bufferedEvents.get(eventId);
+        if (!record) {
+            return null;
+        }
+        this.bufferedEvents.delete(eventId);
+        for (const key of record.keys) {
+            const queue = this.bufferedEventQueues.get(key);
+            if (!queue) {
+                continue;
+            }
+            queue.delete(eventId);
+            if (queue.size === 0) {
+                this.bufferedEventQueues.delete(key);
+            }
+        }
+        return record.event;
+    }
+}
+function buildBufferKey(type, options) {
+    const parts = [`type:${type}`];
+    if (options?.ownership) {
+        parts.push(`ownership:${ownershipSelectorKey(options.ownership)}`);
+    }
+    if (options?.state) {
+        parts.push(`state:${options.state}`);
+    }
+    if (options?.processId) {
+        parts.push(`process:${options.processId}`);
+    }
+    if (options?.channel) {
+        parts.push(`channel:${options.channel}`);
+    }
+    if (options?.name) {
+        parts.push(`name:${options.name}`);
+    }
+    return parts.join("|");
+}
+export function sidecarSelectorMatchesEvent(selector, event) {
+    if ("any" in selector) {
+        return true;
+    }
+    if (event.payload.type !== selector.type) {
+        return false;
+    }
+    if (!ownershipMatchesSelector(selector.ownership, event.ownership)) {
+        return false;
+    }
+    switch (selector.type) {
+        case "vm_lifecycle": {
+            const payload = event.payload;
+            return selector.state === undefined || payload.state === selector.state;
+        }
+        case "process_output": {
+            const payload = event.payload;
+            return ((selector.processId === undefined ||
+                payload.process_id === selector.processId) &&
+                (selector.channel === undefined || payload.channel === selector.channel));
+        }
+        case "process_exited": {
+            const payload = event.payload;
+            return (selector.processId === undefined ||
+                payload.process_id === selector.processId);
+        }
+        case "structured": {
+            const payload = event.payload;
+            if (selector.name !== undefined && payload.name !== selector.name) {
+                return false;
+            }
+            if (!selector.detail) {
+                return true;
+            }
+            for (const [key, value] of Object.entries(selector.detail)) {
+                if (payload.detail[key] !== value) {
+                    return false;
+                }
+            }
+            return true;
+        }
+    }
+}
+export function sidecarSelectorBufferKey(selector) {
+    if ("any" in selector) {
+        return ANY_BUFFERED_EVENT_KEY;
+    }
+    switch (selector.type) {
+        case "vm_lifecycle":
+            return buildBufferKey(selector.type, {
+                ownership: selector.ownership,
+                state: selector.state,
+            });
+        case "process_output":
+            return buildBufferKey(selector.type, {
+                ownership: selector.ownership,
+                processId: selector.processId,
+                channel: selector.channel,
+            });
+        case "process_exited":
+            return buildBufferKey(selector.type, {
+                ownership: selector.ownership,
+                processId: selector.processId,
+            });
+        case "structured":
+            if (selector.detail) {
+                return null;
+            }
+            return buildBufferKey(selector.type, {
+                ownership: selector.ownership,
+                name: selector.name,
+            });
+    }
+}
+export function normalizeSidecarEventMatcher(selector) {
+    if (typeof selector === "function") {
+        return {
+            matches: selector,
+            bufferKey: null,
+        };
+    }
+    return {
+        matches: (event) => sidecarSelectorMatchesEvent(selector, event),
+        bufferKey: sidecarSelectorBufferKey(selector),
+    };
+}
+export function fromGeneratedEventPayload(payload) {
+    switch (payload.tag) {
+        case "VmLifecycleEvent":
+            return {
+                type: "vm_lifecycle",
+                state: fromGeneratedVmLifecycleState(payload.val.state),
+            };
+        case "ProcessOutputEvent":
+            return {
+                type: "process_output",
+                process_id: payload.val.processId,
+                channel: fromGeneratedStreamChannel(payload.val.channel),
+                chunk: Buffer.from(payload.val.chunk),
+            };
+        case "ProcessExitedEvent":
+            return {
+                type: "process_exited",
+                process_id: payload.val.processId,
+                exit_code: payload.val.exitCode,
+            };
+        case "StructuredEvent":
+            return {
+                type: "structured",
+                name: payload.val.name,
+                detail: Object.fromEntries(payload.val.detail),
+            };
+        case "ExtEnvelope":
+            return {
+                type: "ext",
+                envelope: fromGeneratedExtEnvelope(payload.val),
+            };
+    }
+}
+export function sidecarEventWaitAbortError(reason) {
+    return reason instanceof Error
+        ? reason
+        : new Error(reason ? String(reason) : "sidecar event wait aborted");
+}
+export function sidecarEventBufferKeys(event) {
+    const owner = event.ownership;
+    const keys = new Set([
+        ANY_BUFFERED_EVENT_KEY,
+        buildBufferKey(event.payload.type),
+        buildBufferKey(event.payload.type, { ownership: owner }),
+    ]);
+    switch (event.payload.type) {
+        case "vm_lifecycle":
+            keys.add(buildBufferKey(event.payload.type, {
+                state: event.payload.state,
+            }));
+            keys.add(buildBufferKey(event.payload.type, {
+                ownership: owner,
+                state: event.payload.state,
+            }));
+            break;
+        case "process_output":
+            keys.add(buildBufferKey(event.payload.type, {
+                processId: event.payload.process_id,
+            }));
+            keys.add(buildBufferKey(event.payload.type, {
+                channel: event.payload.channel,
+            }));
+            keys.add(buildBufferKey(event.payload.type, {
+                processId: event.payload.process_id,
+                channel: event.payload.channel,
+            }));
+            keys.add(buildBufferKey(event.payload.type, {
+                ownership: owner,
+                processId: event.payload.process_id,
+            }));
+            keys.add(buildBufferKey(event.payload.type, {
+                ownership: owner,
+                channel: event.payload.channel,
+            }));
+            keys.add(buildBufferKey(event.payload.type, {
+                ownership: owner,
+                processId: event.payload.process_id,
+                channel: event.payload.channel,
+            }));
+            break;
+        case "process_exited":
+            keys.add(buildBufferKey(event.payload.type, {
+                processId: event.payload.process_id,
+            }));
+            keys.add(buildBufferKey(event.payload.type, {
+                ownership: owner,
+                processId: event.payload.process_id,
+            }));
+            break;
+        case "structured":
+            keys.add(buildBufferKey(event.payload.type, {
+                name: event.payload.name,
+            }));
+            keys.add(buildBufferKey(event.payload.type, {
+                ownership: owner,
+                name: event.payload.name,
+            }));
+            break;
+        case "ext":
+            break;
+    }
+    return [...keys];
+}

package/dist/ext.d.ts

@@ -0,0 +1,7 @@
+import type * as sidecarProtocol from "./generated-protocol.js";
+export interface LiveExtEnvelope {
+    namespace: string;
+    payload: Uint8Array;
+}
+export declare function toGeneratedExtEnvelope(envelope: LiveExtEnvelope): sidecarProtocol.ExtEnvelope;
+export declare function fromGeneratedExtEnvelope(envelope: sidecarProtocol.ExtEnvelope): LiveExtEnvelope;

package/dist/ext.js

@@ -0,0 +1,13 @@
+import { toExactArrayBuffer } from "./bytes.js";
+export function toGeneratedExtEnvelope(envelope) {
+    return {
+        namespace: envelope.namespace,
+        payload: toExactArrayBuffer(envelope.payload),
+    };
+}
+export function fromGeneratedExtEnvelope(envelope) {
+    return {
+        namespace: envelope.namespace,
+        payload: Buffer.from(envelope.payload),
+    };
+}

package/dist/filesystem.d.ts

@@ -0,0 +1,41 @@
+import * as protocol from "./generated-protocol.js";
+import { type LiveRootFilesystemEntryEncoding } from "./protocol-maps.js";
+export type { LiveRootFilesystemEntryEncoding } from "./protocol-maps.js";
+export type GuestFilesystemContentEncoding = "utf8" | "base64";
+export interface GuestFilesystemContentResult {
+    path: string;
+    content?: string;
+    encoding?: GuestFilesystemContentEncoding;
+}
+export type LiveRootFilesystemEntry = {
+    path: string;
+    kind: "file" | "directory" | "symlink";
+    mode?: number;
+    uid?: number;
+    gid?: number;
+    content?: string;
+    encoding?: LiveRootFilesystemEntryEncoding;
+    target?: string;
+    executable?: boolean;
+};
+export type LiveRootFilesystemLowerDescriptor = {
+    kind: "snapshot";
+    entries: LiveRootFilesystemEntry[];
+} | {
+    kind: "bundled_base_filesystem";
+};
+export type LiveRootFilesystemDescriptor = {
+    mode?: "ephemeral" | "read_only";
+    disable_default_base_layer?: boolean;
+    lowers?: LiveRootFilesystemLowerDescriptor[];
+    bootstrap_entries?: LiveRootFilesystemEntry[];
+};
+export declare function encodeGuestFilesystemContent(content: string | Uint8Array): {
+    content: string;
+    encoding?: GuestFilesystemContentEncoding;
+};
+export declare function decodeGuestFilesystemContent(response: GuestFilesystemContentResult): Uint8Array;
+export declare function toGeneratedRootFilesystemDescriptor(descriptor: LiveRootFilesystemDescriptor): protocol.RootFilesystemDescriptor;
+export declare function toGeneratedRootFilesystemLower(lower: LiveRootFilesystemLowerDescriptor): protocol.RootFilesystemLowerDescriptor;
+export declare function toGeneratedRootFilesystemEntry(entry: LiveRootFilesystemEntry): protocol.RootFilesystemEntry;
+export declare function fromGeneratedRootFilesystemEntry(entry: protocol.RootFilesystemEntry): LiveRootFilesystemEntry;

package/dist/filesystem.js

@@ -0,0 +1,70 @@
+import { fromGeneratedRootFilesystemEntryEncoding, fromGeneratedRootFilesystemEntryKind, toGeneratedRootFilesystemEntryEncoding, toGeneratedRootFilesystemEntryKind, toGeneratedRootFilesystemMode, } from "./protocol-maps.js";
+export function encodeGuestFilesystemContent(content) {
+    if (typeof content === "string") {
+        return { content };
+    }
+    return {
+        content: Buffer.from(content).toString("base64"),
+        encoding: "base64",
+    };
+}
+export function decodeGuestFilesystemContent(response) {
+    if (response.content === undefined) {
+        throw new Error(`sidecar returned no file content for ${response.path}`);
+    }
+    if (response.encoding === "base64") {
+        return Buffer.from(response.content, "base64");
+    }
+    return Buffer.from(response.content, "utf8");
+}
+export function toGeneratedRootFilesystemDescriptor(descriptor) {
+    return {
+        mode: toGeneratedRootFilesystemMode(descriptor.mode ?? "ephemeral"),
+        disableDefaultBaseLayer: descriptor.disable_default_base_layer ?? false,
+        lowers: (descriptor.lowers ?? []).map(toGeneratedRootFilesystemLower),
+        bootstrapEntries: (descriptor.bootstrap_entries ?? []).map(toGeneratedRootFilesystemEntry),
+    };
+}
+export function toGeneratedRootFilesystemLower(lower) {
+    switch (lower.kind) {
+        case "snapshot":
+            return {
+                tag: "SnapshotRootFilesystemLower",
+                val: {
+                    entries: (lower.entries ?? []).map(toGeneratedRootFilesystemEntry),
+                },
+            };
+        case "bundled_base_filesystem":
+            return { tag: "BundledBaseFilesystemLower", val: null };
+    }
+}
+export function toGeneratedRootFilesystemEntry(entry) {
+    return {
+        path: entry.path,
+        kind: toGeneratedRootFilesystemEntryKind(entry.kind),
+        mode: entry.mode ?? null,
+        uid: entry.uid ?? null,
+        gid: entry.gid ?? null,
+        content: entry.content ?? null,
+        encoding: entry.encoding === undefined
+            ? null
+            : toGeneratedRootFilesystemEntryEncoding(entry.encoding),
+        target: entry.target ?? null,
+        executable: entry.executable ?? false,
+    };
+}
+export function fromGeneratedRootFilesystemEntry(entry) {
+    return {
+        path: entry.path,
+        kind: fromGeneratedRootFilesystemEntryKind(entry.kind),
+        ...(entry.mode !== null ? { mode: entry.mode } : {}),
+        ...(entry.uid !== null ? { uid: entry.uid } : {}),
+        ...(entry.gid !== null ? { gid: entry.gid } : {}),
+        ...(entry.content !== null ? { content: entry.content } : {}),
+        ...(entry.encoding !== null
+            ? { encoding: fromGeneratedRootFilesystemEntryEncoding(entry.encoding) }
+            : {}),
+        ...(entry.target !== null ? { target: entry.target } : {}),
+        executable: entry.executable,
+    };
+}

package/dist/frame-payload-codec.d.ts

@@ -0,0 +1,8 @@
+export type TransportPayloadCodec = "bare" | "json";
+export declare function encodeJsonFramePayload(frame: unknown): Buffer;
+export declare function decodeJsonFramePayload<TFrame extends {
+    payload?: {
+        type?: string;
+        chunk?: unknown;
+    };
+}>(payload: Uint8Array): TFrame;

package/dist/frame-payload-codec.js

@@ -0,0 +1,14 @@
+export function encodeJsonFramePayload(frame) {
+    // BARE `data` fields are Uint8Array; JSON.stringify renders those as objects, so encode them
+    // as number arrays to match serde_json's Vec<u8> representation on the Rust side.
+    return Buffer.from(JSON.stringify(frame, (_key, value) => value instanceof Uint8Array ? Array.from(value) : value), "utf8");
+}
+export function decodeJsonFramePayload(payload) {
+    const frame = JSON.parse(Buffer.from(payload).toString("utf8"));
+    const decodedPayload = frame.payload;
+    if (decodedPayload?.type === "process_output" &&
+        Array.isArray(decodedPayload.chunk)) {
+        decodedPayload.chunk = Uint8Array.from(decodedPayload.chunk);
+    }
+    return frame;
+}

package/dist/frame-rpc.d.ts

@@ -0,0 +1,38 @@
+import type { Readable, Writable } from "node:stream";
+export type ClassifiedFrame<TResponseFrame, TEventFrame, TSidecarRequestFrame> = {
+    kind: "response";
+    requestId: number;
+    frame: TResponseFrame;
+} | {
+    kind: "event";
+    frame: TEventFrame;
+} | {
+    kind: "sidecarRequest";
+    frame: TSidecarRequestFrame;
+};
+export interface FrameRpcTransportOptions<TReadFrame, TWriteFrame, TResponseFrame, TEventFrame, TSidecarRequestFrame> {
+    stdin: Writable;
+    stdout: Readable;
+    encodeFrame: (frame: TWriteFrame) => Uint8Array;
+    decodeFrame: (payload: Uint8Array) => TReadFrame;
+    classifyFrame: (frame: TReadFrame) => ClassifiedFrame<TResponseFrame, TEventFrame, TSidecarRequestFrame>;
+}
+export declare class FrameRpcTransport<TReadFrame, TWriteFrame, TResponseFrame, TEventFrame, TSidecarRequestFrame> {
+    private readonly frameTransport;
+    private readonly pendingResponses;
+    private readonly eventListeners;
+    private readonly sidecarRequestListeners;
+    constructor(options: FrameRpcTransportOptions<TReadFrame, TWriteFrame, TResponseFrame, TEventFrame, TSidecarRequestFrame>);
+    onEvent(handler: (event: TEventFrame) => void): () => void;
+    onSidecarRequest(handler: (request: TSidecarRequestFrame) => void): () => void;
+    onError(handler: (error: Error) => void): () => void;
+    onEnd(handler: () => void): () => void;
+    sendFrame(requestId: number, frame: TWriteFrame, options: {
+        timeoutMs: number;
+        timeoutMessage: () => string;
+    }): Promise<TResponseFrame>;
+    writeFrame(frame: TWriteFrame): Promise<void>;
+    rejectAll(error: Error): void;
+    dispose(): void;
+    private dispatchFrame;
+}

package/dist/frame-rpc.js

@@ -0,0 +1,73 @@
+import { PendingResponseRegistry } from "./correlation.js";
+import { StdioFrameTransport } from "./frame-stream.js";
+export class FrameRpcTransport {
+    frameTransport;
+    pendingResponses = new PendingResponseRegistry();
+    eventListeners = new Set();
+    sidecarRequestListeners = new Set();
+    constructor(options) {
+        this.frameTransport = new StdioFrameTransport({
+            stdin: options.stdin,
+            stdout: options.stdout,
+            encodeFrame: options.encodeFrame,
+            decodeFrame: options.decodeFrame,
+        });
+        this.frameTransport.onFrame((frame) => {
+            this.dispatchFrame(options.classifyFrame(frame));
+        });
+    }
+    onEvent(handler) {
+        this.eventListeners.add(handler);
+        return () => {
+            this.eventListeners.delete(handler);
+        };
+    }
+    onSidecarRequest(handler) {
+        this.sidecarRequestListeners.add(handler);
+        return () => {
+            this.sidecarRequestListeners.delete(handler);
+        };
+    }
+    onError(handler) {
+        return this.frameTransport.onError(handler);
+    }
+    onEnd(handler) {
+        return this.frameTransport.onEnd(handler);
+    }
+    async sendFrame(requestId, frame, options) {
+        const response = this.pendingResponses.waitForResponse(requestId, options);
+        void this.writeFrame(frame).catch((error) => {
+            this.pendingResponses.reject(requestId, error instanceof Error ? error : new Error(String(error)));
+        });
+        return await response;
+    }
+    async writeFrame(frame) {
+        await this.frameTransport.writeFrame(frame);
+    }
+    rejectAll(error) {
+        this.pendingResponses.rejectAll(error);
+    }
+    dispose() {
+        this.frameTransport.dispose();
+        this.pendingResponses.rejectAll(new Error("frame rpc transport disposed"));
+        this.eventListeners.clear();
+        this.sidecarRequestListeners.clear();
+    }
+    dispatchFrame(classified) {
+        switch (classified.kind) {
+            case "response":
+                this.pendingResponses.resolve(classified.requestId, classified.frame);
+                return;
+            case "event":
+                for (const listener of this.eventListeners) {
+                    listener(classified.frame);
+                }
+                return;
+            case "sidecarRequest":
+                for (const listener of this.sidecarRequestListeners) {
+                    listener(classified.frame);
+                }
+                return;
+        }
+    }
+}

package/dist/frame-stream.d.ts

@@ -0,0 +1,27 @@
+import type { Readable, Writable } from "node:stream";
+export interface StdioFrameTransportOptions<TReadFrame, TWriteFrame> {
+    stdin: Writable;
+    stdout: Readable;
+    encodeFrame: (frame: TWriteFrame) => Uint8Array;
+    decodeFrame: (payload: Uint8Array) => TReadFrame;
+}
+export declare class StdioFrameTransport<TReadFrame, TWriteFrame = TReadFrame> {
+    private readonly stdin;
+    private readonly stdout;
+    private readonly encodeFrame;
+    private readonly decodeFrame;
+    private readonly frameListeners;
+    private readonly errorListeners;
+    private readonly endListeners;
+    private stdoutBuffer;
+    constructor(options: StdioFrameTransportOptions<TReadFrame, TWriteFrame>);
+    onFrame(handler: (frame: TReadFrame) => void): () => void;
+    onError(handler: (error: Error) => void): () => void;
+    onEnd(handler: () => void): () => void;
+    writeFrame(frame: TWriteFrame): Promise<void>;
+    dispose(): void;
+    private readonly handleData;
+    private readonly handleEnd;
+    private readonly handleError;
+    private drainFrames;
+}