@qvac/sdk 0.18.2 → 0.19.1

package/dist/src/client/rpc/rpc-client.d.ts

@@ -0,0 +1,19 @@
+import type RPC from 'bare-rpc';
+import { type Request, type Response, type RPCOptions } from '@qvac/inference/surface';
+export declare function send<T extends Request>(request: T, options?: RPCOptions, rpc?: RPC): Promise<Response>;
+export declare function stream<T extends Request>(request: T, options?: RPCOptions, rpc?: RPC): AsyncGenerator<Response>;
+export interface DuplexWritable {
+    write(chunk: Uint8Array): void;
+    end(): void;
+    destroy(): void;
+}
+export interface DuplexReadable extends AsyncIterable<Buffer | string> {
+    destroy(): void;
+}
+export interface DuplexSession {
+    requestStream: DuplexWritable;
+    responseStream: DuplexReadable;
+}
+export declare function duplex<T extends Request>(request: T, options?: RPCOptions): Promise<DuplexSession>;
+export declare function close(): Promise<void>;
+//# sourceMappingURL=rpc-client.d.ts.map

package/dist/src/client/rpc/rpc-client.js

@@ -0,0 +1,550 @@
+import { requestSchema, responseSchema, PROFILING_TRAILER_KEY, nowMs, shouldProfile, shouldIncludeServerBreakdown, shouldIncludeResourceGauges, generateId as createProfileId, createProfilingMeta, createProfilingDisabledMeta, injectProfilingMetaIntoObject, extractProfilingMeta, stripProfilingMeta, recordFailure } from '@qvac/inference/surface';
+import { reconstructError } from './rpc-error.js';
+import { withTimeout, withTimeoutStream, OperationTimeoutError } from '../../utils/withTimeout.js';
+import { getClientLogger, summarizeRequest } from '../../logging/index.js';
+import { getRPC, close as closeRPC, createDuplexSession, getWorkerLifeSignal, notifyChannelClosed } from '#rpc';
+import { WorkerCrashedError, RequestValidationFailedError } from '../../utils/errors-client.js';
+import { formatZodError } from '../../utils/zod-error.js';
+import { z } from 'zod';
+import { createClientTimings, createClientStreamTimings, recordClientEvents, recordClientStreamEvents, cacheConnectionTime, flushConnectionTime, resetConnectionTracking } from './profiling/index.js';
+const logger = getClientLogger();
+let rpcInstance = null;
+let commandCounter = 0;
+let firstConnectionPending = true;
+function getNextCommandId() {
+    commandCounter = (commandCounter + 1) % Number.MAX_SAFE_INTEGER;
+    return commandCounter;
+}
+function memberDiscriminator(option) {
+    const direct = option.shape?.type?.value;
+    if (typeof direct === 'string')
+        return direct;
+    const nested = option.options?.[0]?.shape?.type?.value;
+    return typeof nested === 'string' ? nested : undefined;
+}
+function pinpointRequestError(request, fallback) {
+    const type = request?.type;
+    if (typeof type !== 'string')
+        return fallback;
+    for (const option of requestSchema.options) {
+        if (memberDiscriminator(option) !== type)
+            continue;
+        const result = option.safeParse(request);
+        return result.success ? fallback : result.error;
+    }
+    return fallback;
+}
+function parseRequest(request) {
+    try {
+        return requestSchema.parse(request);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            throw new RequestValidationFailedError(formatZodError(pinpointRequestError(request, error)));
+        }
+        throw error;
+    }
+}
+// Race in-flight reply/stream pulls against the worker-life signal —
+// bare-rpc's `_onerror`/`_onclose` reject a pending reply or destroy a
+// stream with its own generic `RPCError` (e.g. `CHANNEL_CLOSED`) as soon
+// as the channel dies, which can beat the SDK's own crash detection
+// (driven by the child process's `'exit'` event). Since `req.reply()` and
+// response streams never reject with an application-level error — those
+// always arrive as a resolved payload handled by `checkAndThrowError` —
+// any rejection reaching these helpers other than our own `withTimeout`
+// is transport failure. Under our IPC transport a channel close always
+// means the worker is gone, so remapping it to the life signal's reason
+// (or a generic crash if the signal hasn't fired yet) is safe.
+//
+// When we win that race, the life signal hasn't aborted yet, so nothing
+// has invalidated the cached RPC connection — the next call would reuse
+// the same dead channel and fail again. `notifyChannelClosed()` tears it
+// down eagerly instead of waiting on the slow exit event; it's a no-op
+// once the signal is already aborted, so this is safe to call every time.
+function lifeSignalAbortError(signal) {
+    if (!signal.aborted)
+        notifyChannelClosed();
+    if (signal.reason instanceof Error)
+        return signal.reason;
+    return new WorkerCrashedError(null, null);
+}
+async function awaitWithLifeSignal(p) {
+    // Null on Bare-direct / Expo and pre-spawn.
+    const lifeSignal = getWorkerLifeSignal();
+    if (!lifeSignal)
+        return p;
+    if (lifeSignal.aborted) {
+        // `p` (e.g. `req.reply()`) may already be a rejected promise — bare-rpc
+        // 1.3.8 rejects synchronously once its channel is closed. We're
+        // discarding it in favour of the life signal's classification, so give
+        // it a handler or its rejection surfaces as an unhandled rejection.
+        p.catch(() => { });
+        throw lifeSignalAbortError(lifeSignal);
+    }
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const onAbort = () => {
+            if (settled)
+                return;
+            settled = true;
+            lifeSignal.removeEventListener('abort', onAbort);
+            reject(lifeSignalAbortError(lifeSignal));
+        };
+        lifeSignal.addEventListener('abort', onAbort, { once: true });
+        p.then((value) => {
+            if (settled)
+                return;
+            settled = true;
+            lifeSignal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (err) => {
+            if (settled)
+                return;
+            settled = true;
+            lifeSignal.removeEventListener('abort', onAbort);
+            reject(err instanceof OperationTimeoutError ? err : lifeSignalAbortError(lifeSignal));
+        });
+    });
+}
+async function* iterateWithLifeSignal(source) {
+    // Null on Bare-direct / Expo and pre-spawn.
+    const lifeSignal = getWorkerLifeSignal();
+    if (!lifeSignal) {
+        yield* source;
+        return;
+    }
+    if (lifeSignal.aborted)
+        throw lifeSignalAbortError(lifeSignal);
+    try {
+        while (true) {
+            const nextP = source.next();
+            const result = await new Promise((resolve, reject) => {
+                let settled = false;
+                const onAbort = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    lifeSignal.removeEventListener('abort', onAbort);
+                    reject(lifeSignalAbortError(lifeSignal));
+                };
+                lifeSignal.addEventListener('abort', onAbort, { once: true });
+                nextP.then((value) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    lifeSignal.removeEventListener('abort', onAbort);
+                    resolve(value);
+                }, (err) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    lifeSignal.removeEventListener('abort', onAbort);
+                    reject(err instanceof OperationTimeoutError ? err : lifeSignalAbortError(lifeSignal));
+                });
+            });
+            if (result.done)
+                return;
+            yield result.value;
+        }
+    }
+    finally {
+        // Fire-and-forget cleanup. If the source is suspended on a never-
+        // settling read (worker dead), `.return()` propagates an abrupt
+        // completion through the for-await chain so inner streams get
+        // destroyed. The `.catch` swallows the case where the underlying
+        // stream cannot honour `.return()` cleanly.
+        void source.return?.(undefined).catch(() => { });
+    }
+}
+function checkAndThrowError(response) {
+    if (response.type === 'error') {
+        // Use the typed-error reconstructor map in `rpc-error.ts` so the
+        // original class (e.g. `RequestRejectedByPolicyError`) survives
+        // the RPC boundary intact and `err instanceof <Class>` works in
+        // consumer `catch` blocks. Unknown error names fall back to a
+        // plain `RPCError` wrapper inside `reconstructError`.
+        throw reconstructError(response);
+    }
+}
+function invalidateRPCInstance() {
+    rpcInstance = null;
+    firstConnectionPending = true;
+    resetConnectionTracking();
+}
+async function getRPCInstance() {
+    if (rpcInstance)
+        return { rpc: await rpcInstance };
+    const connectionStart = firstConnectionPending ? nowMs() : null;
+    rpcInstance = getRPC();
+    const rpc = await rpcInstance;
+    // Drop the cache on worker death so the next call respawns and
+    // records connectionMs again as a "first" connection.
+    const lifeSignal = getWorkerLifeSignal();
+    if (lifeSignal?.aborted) {
+        invalidateRPCInstance();
+    }
+    else if (lifeSignal) {
+        lifeSignal.addEventListener('abort', invalidateRPCInstance, {
+            once: true
+        });
+    }
+    if (connectionStart !== null && firstConnectionPending) {
+        firstConnectionPending = false;
+        return { rpc, connectionMs: nowMs() - connectionStart };
+    }
+    return { rpc };
+}
+async function prepareRPCContext(requestType, perCallProfiling, rpc) {
+    const rpcResult = rpc ? { rpc } : await getRPCInstance();
+    const profilingEnabled = shouldProfile(requestType, perCallProfiling);
+    const signalDisable = perCallProfiling?.enabled === false;
+    if (rpcResult.connectionMs !== undefined) {
+        cacheConnectionTime(rpcResult.connectionMs);
+    }
+    if (profilingEnabled) {
+        flushConnectionTime();
+    }
+    return { rpc: rpcResult.rpc, profilingEnabled, signalDisable };
+}
+export async function send(request, options, rpc) {
+    const ctx = await prepareRPCContext(request.type, options?.profiling, rpc);
+    if (!ctx.profilingEnabled) {
+        return sendBase(request, ctx.rpc, options, ctx.signalDisable);
+    }
+    return sendProfiled(request, ctx.rpc, options);
+}
+async function sendBase(request, rpc, options, signalDisable = false) {
+    const parsedRequest = parseRequest(request);
+    const req = rpc.request(getNextCommandId());
+    logger.debug('RPC Client sending:', summarizeRequest(request));
+    const payloadObj = signalDisable
+        ? injectProfilingMetaIntoObject(parsedRequest, createProfilingDisabledMeta())
+        : parsedRequest;
+    const payload = JSON.stringify(payloadObj);
+    req.send(payload, 'utf-8');
+    const response = await awaitWithLifeSignal(withTimeout(req.reply('utf-8'), options?.timeout));
+    const resPayload = responseSchema.parse(JSON.parse(response?.toString() || '{}'));
+    logger.debug('ResPayload', { type: resPayload.type });
+    checkAndThrowError(resPayload);
+    return resPayload;
+}
+async function sendProfiled(request, rpc, options) {
+    const requestType = request.type;
+    const profileId = createProfileId();
+    const includeServer = shouldIncludeServerBreakdown(options?.profiling);
+    const includeResources = shouldIncludeResourceGauges(options?.profiling);
+    const timings = createClientTimings(profileId, requestType);
+    try {
+        const zodStart = nowMs();
+        const parsedRequest = parseRequest(request);
+        timings.requestZodValidationMs = nowMs() - zodStart;
+        const req = rpc.request(getNextCommandId());
+        logger.debug('RPC Client sending:', summarizeRequest(request));
+        const profilingMeta = createProfilingMeta(profileId, includeServer, includeResources);
+        const requestWithMeta = injectProfilingMetaIntoObject(parsedRequest, profilingMeta);
+        const stringifyStart = nowMs();
+        const payload = JSON.stringify(requestWithMeta);
+        timings.requestStringifyMs = nowMs() - stringifyStart;
+        timings.sendStart = nowMs();
+        req.send(payload, 'utf-8');
+        const response = await awaitWithLifeSignal(withTimeout(req.reply('utf-8'), options?.timeout));
+        timings.firstResponseAt = nowMs();
+        const parseStart = nowMs();
+        const rawParsed = JSON.parse(response?.toString() || '{}');
+        timings.responseJsonParseMs = nowMs() - parseStart;
+        const responseMeta = extractProfilingMeta(rawParsed);
+        const cleanPayload = stripProfilingMeta(rawParsed);
+        const zodValidateStart = nowMs();
+        const resPayload = responseSchema.parse(cleanPayload);
+        timings.responseZodValidationMs = nowMs() - zodValidateStart;
+        timings.requestEnd = nowMs();
+        logger.debug('ResPayload', { type: resPayload.type });
+        recordClientEvents(timings, responseMeta);
+        checkAndThrowError(resPayload);
+        return resPayload;
+    }
+    catch (error) {
+        if (timings.requestEnd === undefined) {
+            const base = {
+                ts: nowMs(),
+                op: timings.requestType,
+                kind: 'rpc',
+                profileId: timings.profileId
+            };
+            recordFailure(base, timings.requestStart, error);
+        }
+        throw error;
+    }
+}
+export async function* stream(request, options = {}, rpc) {
+    const ctx = await prepareRPCContext(request.type, options?.profiling, rpc);
+    if (!ctx.profilingEnabled) {
+        yield* streamBase(request, ctx.rpc, options, ctx.signalDisable);
+        return;
+    }
+    yield* streamProfiled(request, ctx.rpc, options);
+}
+async function* streamBase(request, rpc, options = {}, signalDisable = false) {
+    const parsedRequest = parseRequest(request);
+    const req = rpc.request(getNextCommandId());
+    logger.debug('RPC Client streaming:', summarizeRequest(request));
+    const payloadObj = signalDisable
+        ? injectProfilingMetaIntoObject(parsedRequest, createProfilingDisabledMeta())
+        : parsedRequest;
+    req.send(JSON.stringify(payloadObj), 'utf-8');
+    const responseStream = req.createResponseStream({ encoding: 'utf-8' });
+    let buffer = '';
+    async function* processStream() {
+        for await (const chunk of responseStream) {
+            yield chunk;
+        }
+    }
+    const streamWithTimeout = withTimeoutStream(processStream(), options?.timeout);
+    for await (const chunk of iterateWithLifeSignal(streamWithTimeout)) {
+        buffer += chunk.toString();
+        // Process complete lines (newline-delimited JSON)
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || ''; // Keep incomplete line in buffer
+        for (const line of lines) {
+            if (line.trim()) {
+                const response = responseSchema.parse(JSON.parse(line));
+                checkAndThrowError(response);
+                yield response;
+            }
+        }
+    }
+}
+async function* streamProfiled(request, rpc, options = {}) {
+    const requestType = request.type;
+    const profileId = createProfileId();
+    const includeServer = shouldIncludeServerBreakdown(options?.profiling);
+    const includeResources = shouldIncludeResourceGauges(options?.profiling);
+    const timings = createClientStreamTimings(profileId, requestType);
+    let profilingMeta = undefined;
+    try {
+        const zodStart = nowMs();
+        const parsedRequest = parseRequest(request);
+        timings.requestZodValidationMs = nowMs() - zodStart;
+        const req = rpc.request(getNextCommandId());
+        logger.debug('RPC Client streaming:', summarizeRequest(request));
+        const requestMeta = createProfilingMeta(profileId, includeServer, includeResources);
+        const requestWithMeta = injectProfilingMetaIntoObject(parsedRequest, requestMeta);
+        const stringifyStart = nowMs();
+        const payload = JSON.stringify(requestWithMeta);
+        timings.requestStringifyMs = nowMs() - stringifyStart;
+        timings.sendStart = nowMs();
+        req.send(payload, 'utf-8');
+        const responseStream = req.createResponseStream({ encoding: 'utf-8' });
+        let buffer = '';
+        async function* processStream() {
+            for await (const chunk of responseStream) {
+                yield chunk;
+            }
+        }
+        const streamWithTimeout = withTimeoutStream(processStream(), options?.timeout);
+        for await (const chunk of iterateWithLifeSignal(streamWithTimeout)) {
+            const chunkTime = nowMs();
+            if (timings.firstChunkAt === undefined) {
+                timings.firstChunkAt = chunkTime;
+            }
+            timings.lastChunkAt = chunkTime;
+            buffer += chunk.toString();
+            const lines = buffer.split('\n');
+            buffer = lines.pop() || '';
+            for (const line of lines) {
+                if (line.trim()) {
+                    const rawParsed = JSON.parse(line);
+                    const chunkMeta = extractProfilingMeta(rawParsed);
+                    if (chunkMeta) {
+                        profilingMeta = chunkMeta;
+                    }
+                    if (rawParsed[PROFILING_TRAILER_KEY] === true)
+                        continue;
+                    const cleanPayload = stripProfilingMeta(rawParsed);
+                    const response = responseSchema.parse(cleanPayload);
+                    timings.chunkCount++;
+                    checkAndThrowError(response);
+                    yield response;
+                }
+            }
+        }
+    }
+    catch (error) {
+        if (timings.requestEnd === undefined) {
+            const base = {
+                ts: nowMs(),
+                op: timings.requestType,
+                kind: 'rpc',
+                profileId: timings.profileId
+            };
+            recordFailure(base, timings.requestStart, error);
+        }
+        throw error;
+    }
+    finally {
+        if (timings.chunkCount > 0) {
+            timings.requestEnd = nowMs();
+            recordClientStreamEvents(timings, profilingMeta);
+        }
+    }
+}
+// bare-rpc's own teardown can destroy the duplex streams with the raw
+// transport error before the worker-life-signal's onAbort handler (in
+// `createDuplexSession`) gets to destroy them with the classified one —
+// same race as the plain reply/stream paths above, so route consumption
+// through the same remap.
+function toAsyncGenerator(iterable) {
+    return (async function* () {
+        yield* iterable;
+    })();
+}
+function withLifeSignalDuplex(raw) {
+    const generator = iterateWithLifeSignal(toAsyncGenerator(raw));
+    return {
+        [Symbol.asyncIterator]() {
+            return generator[Symbol.asyncIterator]();
+        },
+        destroy() {
+            raw.destroy();
+        }
+    };
+}
+export async function duplex(request, options) {
+    const ctx = await prepareRPCContext(request.type, options?.profiling);
+    if (!ctx.profilingEnabled) {
+        return duplexBase(request, ctx.signalDisable, options?.timeout);
+    }
+    return duplexProfiled(request, options);
+}
+async function duplexBase(request, signalDisable, timeout) {
+    const parsedRequest = parseRequest(request);
+    logger.debug('RPC Client duplex:', summarizeRequest(request));
+    const payloadObj = signalDisable
+        ? injectProfilingMetaIntoObject(parsedRequest, createProfilingDisabledMeta())
+        : parsedRequest;
+    const payload = JSON.stringify(payloadObj);
+    const sessionPromise = createDuplexSession(payload, getNextCommandId());
+    const session = await withTimeout(sessionPromise, timeout);
+    return {
+        requestStream: session.requestStream,
+        responseStream: withLifeSignalDuplex(session.responseStream)
+    };
+}
+async function duplexProfiled(request, options = {}) {
+    const requestType = request.type;
+    const profileId = createProfileId();
+    const includeServer = shouldIncludeServerBreakdown(options?.profiling);
+    const includeResources = shouldIncludeResourceGauges(options?.profiling);
+    const timings = createClientStreamTimings(profileId, requestType);
+    let session;
+    try {
+        const zodStart = nowMs();
+        const parsedRequest = parseRequest(request);
+        timings.requestZodValidationMs = nowMs() - zodStart;
+        logger.debug('RPC Client duplex:', summarizeRequest(request));
+        const requestMeta = createProfilingMeta(profileId, includeServer, includeResources);
+        const requestWithMeta = injectProfilingMetaIntoObject(parsedRequest, requestMeta);
+        const stringifyStart = nowMs();
+        const payload = JSON.stringify(requestWithMeta);
+        timings.requestStringifyMs = nowMs() - stringifyStart;
+        timings.sendStart = nowMs();
+        const sessionPromise = createDuplexSession(payload, getNextCommandId());
+        session = await withTimeout(sessionPromise, options?.timeout);
+    }
+    catch (error) {
+        const base = {
+            ts: nowMs(),
+            op: timings.requestType,
+            kind: 'rpc',
+            profileId: timings.profileId
+        };
+        recordFailure(base, timings.requestStart, error);
+        throw error;
+    }
+    let profilingMeta = undefined;
+    const rawReadable = withLifeSignalDuplex(session.responseStream);
+    async function* profiledResponseStream() {
+        let lineBuffer = '';
+        try {
+            for await (const chunk of rawReadable) {
+                const chunkTime = nowMs();
+                if (timings.firstChunkAt === undefined) {
+                    timings.firstChunkAt = chunkTime;
+                }
+                timings.lastChunkAt = chunkTime;
+                lineBuffer += chunk.toString();
+                const lines = lineBuffer.split('\n');
+                lineBuffer = lines.pop() || '';
+                const outputParts = [];
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(line);
+                    }
+                    catch {
+                        outputParts.push(line);
+                        continue;
+                    }
+                    const chunkMeta = extractProfilingMeta(parsed);
+                    if (chunkMeta) {
+                        profilingMeta = chunkMeta;
+                    }
+                    if (parsed[PROFILING_TRAILER_KEY] === true) {
+                        continue;
+                    }
+                    // Yield original line — consumer's Zod .parse() strips profiling keys
+                    outputParts.push(line);
+                }
+                if (outputParts.length > 0) {
+                    timings.chunkCount += outputParts.length;
+                    // Yield strings (not Buffer) — RN/Hermes has no global `Buffer`; consumers call `.toString()` either way.
+                    yield outputParts.join('\n') + '\n';
+                }
+            }
+            if (lineBuffer.trim()) {
+                timings.chunkCount++;
+                yield lineBuffer + '\n';
+            }
+        }
+        catch (error) {
+            if (timings.requestEnd === undefined) {
+                const base = {
+                    ts: nowMs(),
+                    op: timings.requestType,
+                    kind: 'rpc',
+                    profileId: timings.profileId
+                };
+                recordFailure(base, timings.requestStart, error);
+            }
+            throw error;
+        }
+        finally {
+            if (timings.chunkCount > 0) {
+                timings.requestEnd = nowMs();
+                recordClientStreamEvents(timings, profilingMeta);
+            }
+        }
+    }
+    const generator = profiledResponseStream();
+    const wrappedResponseStream = {
+        [Symbol.asyncIterator]() {
+            return generator[Symbol.asyncIterator]();
+        },
+        destroy() {
+            rawReadable.destroy();
+        }
+    };
+    return {
+        requestStream: session.requestStream,
+        responseStream: wrappedResponseStream
+    };
+}
+export async function close() {
+    if (!rpcInstance)
+        return;
+    invalidateRPCInstance();
+    await closeRPC();
+}

package/dist/src/client/rpc/rpc-error.d.ts

@@ -0,0 +1,28 @@
+import type { ErrorResponse } from '@qvac/inference/surface';
+export declare class RPCError extends Error {
+    readonly timestamp?: string;
+    readonly remoteStack?: string;
+    readonly code?: number;
+    readonly cause?: unknown;
+    readonly isQvacError: boolean;
+    constructor(errorResponse: ErrorResponse);
+    toJSON(): {
+        name: string;
+        code: number | undefined;
+        message: string;
+        stack: string | undefined;
+        cause: unknown;
+        timestamp: string | undefined;
+        isQvacError: boolean;
+    };
+}
+/**
+ * Rebuild the original server-thrown typed error from its serialised
+ * envelope so consumer code can do
+ * `if (err instanceof RequestRejectedByPolicyError) { ... }` across
+ * the RPC boundary. Unknown error names fall through to the legacy
+ * `RPCError` wrapper, which preserves `name`/`code`/`message` for
+ * code-based predicates.
+ */
+export declare function reconstructError(response: ErrorResponse): Error;
+//# sourceMappingURL=rpc-error.d.ts.map