@adecore/database 0.0.1 → 0.16.0-beta.0

package/dist/host/host.js

@@ -0,0 +1,343 @@
+import { PROTOCOL_VERSION } from '../protocol/index.js';
+import { parseRequest } from './validate.js';
+const DEFAULT_READY_TIMEOUT_MS = 10000;
+/* How long a release or a dispose waits for a helper to answer its `close` requests. */
+const CLOSE_GRACE_MS = 2000;
+/* A failure with the code the caller gets. */
+class Failure extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const failure = (id, code, message) => ({ id, ok: false, error: { code, message } });
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+const isDict = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/* Settles when every promise has, or after the grace period; a helper that hangs must not hold up an app that quits. */
+const settleWithin = async (promises) => {
+    let timer;
+    const grace = new Promise((resolve) => {
+        timer = setTimeout(resolve, CLOSE_GRACE_MS);
+    });
+    try {
+        await Promise.race([Promise.allSettled(promises), grace]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+/* Reads what the helper wrote for a request; anything that is not a response of the protocol becomes an `internal` error. */
+const normalize = (id, message) => {
+    if (message.ok === true) {
+        return { id, ok: true, result: message.result ?? null };
+    }
+    const error = message.error;
+    if (message.ok === false && isDict(error) && typeof error.code === 'string' && typeof error.message === 'string') {
+        return { id, ok: false, error: error };
+    }
+    return failure(id, 'internal', 'The helper sent a response that is not part of the protocol.');
+};
+export const createDatabaseHost = (options) => {
+    const readyTimeoutMs = options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+    // Session id to the owner that opened it.
+    const sessions = new Map();
+    const inflight = new Map();
+    let running = null;
+    let counter = 0;
+    let disposed = false;
+    let disposal = null;
+    const retire = (run, message) => {
+        if (run.state === 'dead') {
+            return;
+        }
+        const wasStarting = run.state === 'starting';
+        run.state = 'dead';
+        clearTimeout(run.timer);
+        if (running === run) {
+            running = null;
+        }
+        sessions.clear();
+        if (wasStarting) {
+            run.rejectReady(new Failure('helper-unavailable', message));
+        }
+        const pending = [...run.pending.entries()];
+        run.pending.clear();
+        for (const [id, resolve] of pending) {
+            resolve(failure(id, 'helper-exited', message));
+        }
+    };
+    const abort = (run, message) => {
+        run.process.kill();
+        retire(run, message);
+    };
+    const onHandshake = (run, line) => {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            abort(run, 'The helper did not start with a ready line.');
+            return;
+        }
+        if (!isDict(message) || message.event !== 'ready') {
+            abort(run, 'The helper did not start with a ready line.');
+            return;
+        }
+        if (message.protocol !== PROTOCOL_VERSION) {
+            abort(run, `The helper speaks protocol ${String(message.protocol)}, this host speaks ${PROTOCOL_VERSION}.`);
+            return;
+        }
+        run.state = 'ready';
+        clearTimeout(run.timer);
+        run.resolveReady();
+    };
+    const onResponse = (run, line) => {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!isDict(message) || typeof message.id !== 'string') {
+            return;
+        }
+        const resolve = run.pending.get(message.id);
+        if (resolve === undefined) {
+            return;
+        }
+        run.pending.delete(message.id);
+        resolve(normalize(message.id, message));
+    };
+    const startRun = () => {
+        let child;
+        try {
+            child = options.start();
+        }
+        catch (error) {
+            throw new Failure('helper-unavailable', `The helper could not be started: ${messageOf(error)}`);
+        }
+        let resolveReady = () => { };
+        let rejectReady = (_error) => { };
+        const ready = new Promise((resolve, reject) => {
+            resolveReady = resolve;
+            rejectReady = reject;
+        });
+        // A request awaits this; a run nobody waits for must not raise an unhandled rejection.
+        ready.catch(() => { });
+        const run = { process: child, ready, pending: new Map(), resolveReady, rejectReady, timer: undefined, state: 'starting' };
+        run.timer = setTimeout(() => abort(run, 'The helper did not become ready in time.'), readyTimeoutMs);
+        child.onLine((line) => {
+            if (run.state === 'starting') {
+                onHandshake(run, line);
+            }
+            else if (run.state === 'ready') {
+                onResponse(run, line);
+            }
+        });
+        child.onExit((code) => retire(run, code === null ? 'The helper exited.' : `The helper exited with code ${code}.`));
+        return run;
+    };
+    const ensureRunning = async () => {
+        if (running === null || running.state === 'dead') {
+            running = startRun();
+        }
+        const run = running;
+        await run.ready;
+        if (run.state === 'dead') {
+            throw new Failure('helper-exited', 'The helper exited.');
+        }
+        return run;
+    };
+    /* Sends a message under a helper id of the host's own; the promise never rejects. */
+    const dispatch = (run, method, params) => {
+        const id = `h${++counter}`;
+        const response = new Promise((resolve) => {
+            run.pending.set(id, resolve);
+            try {
+                run.process.write(JSON.stringify({ id, method, params }));
+            }
+            catch (error) {
+                run.pending.delete(id);
+                resolve(failure(id, 'helper-unavailable', `The helper could not be written to: ${messageOf(error)}`));
+            }
+        });
+        return { id, response };
+    };
+    const liveRun = () => (running !== null && running.state === 'ready' ? running : null);
+    const sessionOf = (request) => {
+        const session = request.params.session;
+        return typeof session === 'string' ? session : null;
+    };
+    const assertSession = (request, owner) => {
+        const session = sessionOf(request);
+        if (session !== null && sessions.get(session) !== owner) {
+            throw new Failure('unknown-session', `There is no open session "${session}".`);
+        }
+    };
+    const assertActive = (entry) => {
+        if (disposed) {
+            throw new Failure('helper-unavailable', 'The database host has been disposed.');
+        }
+        if (entry.cancelled) {
+            throw new Failure('cancelled', 'The request was cancelled.');
+        }
+    };
+    /* An app's check that throws or rejects counts as a no. */
+    const permitted = async (check) => {
+        try {
+            return await check();
+        }
+        catch {
+            return false;
+        }
+    };
+    const authorize = async (request, owner) => {
+        switch (request.method) {
+            case 'open':
+            case 'test': {
+                if (options.authorize !== undefined && !(await permitted(() => options.authorize(request.params.connection, owner)))) {
+                    throw new Failure('forbidden', 'This connection is not allowed.');
+                }
+                break;
+            }
+            case 'export':
+            case 'import':
+            case 'sample': {
+                const access = request.method === 'export' ? 'write' : 'read';
+                if (options.authorizeFile === undefined || !(await permitted(() => options.authorizeFile(request.params.path, access, owner)))) {
+                    throw new Failure('forbidden', 'This file is not allowed.');
+                }
+                break;
+            }
+            case 'discover': {
+                if (options.authorizeDiscovery === undefined || !(await permitted(() => options.authorizeDiscovery(request.params.kind, owner)))) {
+                    throw new Failure('forbidden', 'Discovery is not allowed.');
+                }
+                break;
+            }
+        }
+    };
+    const cancelOwned = async (request, owner) => {
+        const entries = inflight.get(owner);
+        const target = request.id === request.params.request ? undefined : entries?.get(request.params.request);
+        const answer = (cancelled) => ({ id: request.id, ok: true, result: { cancelled } });
+        if (target === undefined) {
+            return answer(false);
+        }
+        if (target.helperId === null) {
+            target.cancelled = true;
+            return answer(true);
+        }
+        const run = liveRun();
+        if (run === null) {
+            return answer(false);
+        }
+        const sent = await dispatch(run, 'cancel', { request: target.helperId }).response;
+        return { ...sent, id: request.id };
+    };
+    /* Remembers what a response changed about the sessions, then hands it back under the caller's id. */
+    const settle = (request, owner, entry, run, response) => {
+        if (request.method === 'close') {
+            sessions.delete(request.params.session);
+        }
+        if (request.method !== 'open' || !response.ok) {
+            return { ...response, id: request.id };
+        }
+        const session = response.result?.session;
+        if (typeof session !== 'string') {
+            return failure(request.id, 'internal', 'The helper opened a session without an id.');
+        }
+        if (run.state === 'dead') {
+            return failure(request.id, 'helper-exited', 'The helper exited.');
+        }
+        if (entry.released) {
+            void dispatch(run, 'close', { session }).response;
+            return failure(request.id, 'cancelled', 'The request was cancelled.');
+        }
+        sessions.set(session, owner);
+        return { ...response, id: request.id };
+    };
+    const route = async (request, owner, entry) => {
+        assertSession(request, owner);
+        if (request.method === 'cancel') {
+            return cancelOwned(request, owner);
+        }
+        await authorize(request, owner);
+        assertActive(entry);
+        const run = await ensureRunning();
+        assertActive(entry);
+        assertSession(request, owner);
+        const sent = dispatch(run, request.method, request.params);
+        entry.helperId = sent.id;
+        return settle(request, owner, entry, run, await sent.response);
+    };
+    const handle = async (input, owner) => {
+        const parsed = parseRequest(input);
+        if (!parsed.ok) {
+            return { id: parsed.id, ok: false, error: parsed.error };
+        }
+        const request = parsed.request;
+        if (disposed) {
+            return failure(request.id, 'helper-unavailable', 'The database host has been disposed.');
+        }
+        let entries = inflight.get(owner);
+        if (entries === undefined) {
+            entries = new Map();
+            inflight.set(owner, entries);
+        }
+        if (entries.has(request.id)) {
+            return failure(request.id, 'invalid-request', `A request with id "${request.id}" is already running.`);
+        }
+        const entry = { helperId: null, cancelled: false, released: false };
+        entries.set(request.id, entry);
+        try {
+            return await route(request, owner, entry);
+        }
+        catch (error) {
+            if (error instanceof Failure) {
+                return failure(request.id, error.code, error.message);
+            }
+            return failure(request.id, 'internal', messageOf(error));
+        }
+        finally {
+            entries.delete(request.id);
+            if (entries.size === 0 && inflight.get(owner) === entries) {
+                inflight.delete(owner);
+            }
+        }
+    };
+    const release = async (owner) => {
+        const run = liveRun();
+        const closing = [];
+        for (const entry of inflight.get(owner)?.values() ?? []) {
+            entry.cancelled = true;
+            entry.released = true;
+            if (entry.helperId !== null && run !== null) {
+                closing.push(dispatch(run, 'cancel', { request: entry.helperId }).response);
+            }
+        }
+        for (const [session, sessionOwner] of [...sessions]) {
+            if (sessionOwner !== owner) {
+                continue;
+            }
+            sessions.delete(session);
+            if (run !== null) {
+                closing.push(dispatch(run, 'close', { session }).response);
+            }
+        }
+        await settleWithin(closing);
+    };
+    const dispose = () => {
+        disposal ??= (async () => {
+            disposed = true;
+            await Promise.all([...new Set([...inflight.keys(), ...sessions.values()])].map(release));
+            if (running !== null) {
+                abort(running, 'The database host has been disposed.');
+            }
+        })();
+        return disposal;
+    };
+    return { handle, release, dispose };
+};

package/dist/host/index.d.ts

@@ -0,0 +1,5 @@
+export { helperPath, type HelperPathOptions } from './helper-path.ts';
+export { createDatabaseHost } from './host.ts';
+export { spawnHelper, type SpawnHelperOptions } from './spawn.ts';
+export type { DatabaseHost, DatabaseHostOptions, HelperProcess } from './types.ts';
+export { parseRequest, type ParsedRequest } from './validate.ts';

package/dist/host/index.js

@@ -0,0 +1,4 @@
+export { helperPath } from './helper-path.js';
+export { createDatabaseHost } from './host.js';
+export { spawnHelper } from './spawn.js';
+export { parseRequest } from './validate.js';

package/dist/host/spawn.d.ts

@@ -0,0 +1,7 @@
+import type { HelperProcess } from './types.ts';
+export interface SpawnHelperOptions {
+    readonly args?: readonly string[];
+    readonly env?: Readonly<Record<string, string>>;
+    readonly onLog?: (line: string) => void;
+}
+export declare const spawnHelper: (path: string, options?: SpawnHelperOptions) => HelperProcess;

package/dist/host/spawn.js

@@ -0,0 +1,98 @@
+import { spawn } from 'node:child_process';
+/*
+ * Cuts a stream into lines. A line can be megabytes, so pieces wait in a list and only the new chunk is
+ * searched for a break; joining a growing string on every chunk would make a large line quadratic.
+ */
+const createLineSplitter = (onLine) => {
+    let pieces = [];
+    const emit = (line) => {
+        const clean = line.endsWith('\r') ? line.slice(0, -1) : line;
+        if (clean.length > 0) {
+            onLine(clean);
+        }
+    };
+    return {
+        push(chunk) {
+            let start = 0;
+            let end = chunk.indexOf('\n');
+            while (end !== -1) {
+                pieces.push(chunk.slice(start, end));
+                const line = pieces.join('');
+                pieces = [];
+                emit(line);
+                start = end + 1;
+                end = chunk.indexOf('\n', start);
+            }
+            if (start < chunk.length) {
+                pieces.push(chunk.slice(start));
+            }
+        },
+        flush() {
+            const line = pieces.join('');
+            pieces = [];
+            emit(line);
+        }
+    };
+};
+/* Runs the helper binary at `path`, speaking one JSON message per line over stdin and stdout. */
+export const spawnHelper = (path, options = {}) => {
+    const lineListeners = [];
+    const exitListeners = [];
+    let finished = false;
+    let exitCode = null;
+    let killed = false;
+    const child = spawn(path, [...(options.args ?? [])], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: options.env ? { ...process.env, ...options.env } : process.env,
+        windowsHide: true
+    });
+    const lines = createLineSplitter((line) => lineListeners.forEach((listener) => listener(line)));
+    const logs = createLineSplitter((line) => options.onLog?.(line));
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => lines.push(chunk));
+    child.stderr.on('data', (chunk) => logs.push(chunk));
+    child.stdin.on('error', () => { });
+    const finish = (code) => {
+        if (finished) {
+            return;
+        }
+        finished = true;
+        exitCode = code;
+        lines.flush();
+        logs.flush();
+        exitListeners.forEach((listener) => listener(code));
+    };
+    child.on('error', (error) => {
+        options.onLog?.(error.message);
+        // Without a pid the process never started, and no `close` follows.
+        if (child.pid === undefined) {
+            finish(null);
+        }
+    });
+    child.on('close', (code) => finish(code));
+    return {
+        write(line) {
+            if (!finished && child.stdin.writable) {
+                child.stdin.write(`${line}\n`);
+            }
+        },
+        onLine(listener) {
+            lineListeners.push(listener);
+        },
+        onExit(listener) {
+            if (finished) {
+                queueMicrotask(() => listener(exitCode));
+                return;
+            }
+            exitListeners.push(listener);
+        },
+        kill() {
+            if (killed || finished) {
+                return;
+            }
+            killed = true;
+            child.kill();
+        }
+    };
+};

package/dist/host/types.d.ts

@@ -0,0 +1,19 @@
+import type { ConnectionConfig, DatabaseResponse } from '../protocol/index.ts';
+export interface HelperProcess {
+    write(line: string): void;
+    onLine(listener: (line: string) => void): void;
+    onExit(listener: (code: number | null) => void): void;
+    kill(): void;
+}
+export interface DatabaseHostOptions {
+    start(): HelperProcess;
+    authorize?(connection: ConnectionConfig, owner: string): boolean | Promise<boolean>;
+    authorizeFile?(path: string, access: 'read' | 'write', owner: string): boolean | Promise<boolean>;
+    authorizeDiscovery?(kind: 'docker', owner: string): boolean | Promise<boolean>;
+    readyTimeoutMs?: number;
+}
+export interface DatabaseHost {
+    handle(request: unknown, owner: string): Promise<DatabaseResponse>;
+    release(owner: string): Promise<void>;
+    dispose(): Promise<void>;
+}

package/dist/host/types.js

@@ -0,0 +1 @@
+export {};

package/dist/host/validate.d.ts

@@ -0,0 +1,10 @@
+import type { DatabaseError, DatabaseRequest } from '../protocol/index.ts';
+export type ParsedRequest = {
+    readonly ok: true;
+    readonly request: DatabaseRequest;
+} | {
+    readonly ok: false;
+    readonly id: string;
+    readonly error: DatabaseError;
+};
+export declare const parseRequest: (input: unknown) => ParsedRequest;