@askdkc/kiokuko 0.1.0

package/dist/server/http.js

@@ -0,0 +1,349 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createServer as nodeCreateServer } from 'node:http';
+import path from 'node:path';
+import { getGlobalDatabasePath, getRuntimeDescriptorPath } from '../config/paths.js';
+import { openConnection } from '../db/connection.js';
+import { migrateDatabase as defaultMigrateDatabase } from '../db/migrate.js';
+import { KiokukoError } from '../errors.js';
+import { createApp } from './app.js';
+import { acquireInstanceLock as defaultAcquireInstanceLock, isPidAlive as defaultIsPidAlive, } from './instance-lock.js';
+import { createRuntimeDescriptor as defaultCreateRuntimeDescriptor, readRuntimeDescriptor as defaultReadRuntimeDescriptor, removeRuntimeDescriptor as defaultRemoveRuntimeDescriptor, toPublicRuntimeDescriptor, writeRuntimeDescriptor as defaultWriteRuntimeDescriptor, } from './runtime-descriptor.js';
+import { WriteQueue } from './write-queue.js';
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_PORT = 0;
+const DEFAULT_QUEUE_CAPACITY = 64;
+function invalid(message, details = {}) {
+    throw new KiokukoError('VALIDATION_ERROR', message, details);
+}
+function validateHost(host) {
+    if (host !== '127.0.0.1' && host !== '::1' && host !== 'localhost') {
+        invalid('The HTTP server only accepts loopback hosts');
+    }
+    return host;
+}
+function validatePort(port) {
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        invalid('port must be an integer between 0 and 65535');
+    }
+    return port;
+}
+function validateCapabilityToken(token) {
+    if (!/^[a-f0-9]{64}$/.test(token))
+        invalid('capabilityToken must be a 256-bit lowercase hexadecimal value');
+    return token;
+}
+function validateApplicationComposition(options) {
+    if (options.applicationFactory !== undefined && (options.app !== undefined || options.v1 !== undefined)) {
+        invalid('applicationFactory cannot be combined with app or v1');
+    }
+}
+function descriptorPathFor(options) {
+    if (options.descriptorPath !== undefined)
+        return options.descriptorPath;
+    if (options.runtimeDirectory !== undefined) {
+        const join = options.platform === 'win32' ? path.win32.join : path.posix.join;
+        return join(options.runtimeDirectory, 'server.json');
+    }
+    return getRuntimeDescriptorPath(options);
+}
+function databasePathFor(options) {
+    return options.databasePath ?? getGlobalDatabasePath(options);
+}
+function lockOptionsFor(options, instanceId, pid, isPidAlive) {
+    const lockOptions = {
+        instanceId,
+        isPidAlive,
+        pid,
+    };
+    if (options.runtimeDirectory !== undefined)
+        lockOptions.runtimeDirectory = options.runtimeDirectory;
+    if (options.platform !== undefined)
+        lockOptions.platform = options.platform;
+    if (options.env !== undefined)
+        lockOptions.env = options.env;
+    return lockOptions;
+}
+function publicUrl(host, port) {
+    const renderedHost = host === '::1' ? '[::1]' : host;
+    return `http://${renderedHost}:${port}`;
+}
+function listeningPort(server) {
+    const address = server.address();
+    if (address === null || typeof address === 'string' || !Number.isInteger(address.port)) {
+        throw new KiokukoError('DATABASE_ERROR', 'HTTP server did not expose a listening address');
+    }
+    return address.port;
+}
+function safeRuntimeError(error, fallback) {
+    if (error instanceof KiokukoError) {
+        const messages = {
+            CONFLICT: 'Request conflicts with current runtime state',
+            VALIDATION_ERROR: 'Runtime configuration is invalid',
+            SECURITY_REJECTION: 'Runtime file was rejected',
+        };
+        return new KiokukoError(error.code, messages[error.code] ?? fallback);
+    }
+    return new KiokukoError('DATABASE_ERROR', fallback);
+}
+function safeStartupError(error) {
+    return safeRuntimeError(error, 'Unable to start the HTTP server');
+}
+function safeCloseError(error) {
+    return safeRuntimeError(error, 'Unable to close the HTTP server');
+}
+async function closeServer(server) {
+    await new Promise((resolve, reject) => {
+        try {
+            server.close((error) => {
+                if (error && (!('code' in error) || error.code !== 'ERR_SERVER_NOT_RUNNING')) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ERR_SERVER_NOT_RUNNING') {
+                resolve();
+                return;
+            }
+            reject(error);
+        }
+    });
+}
+async function listen(server, port, host) {
+    await new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.off('listening', onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            resolve();
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        try {
+            server.listen(port, host);
+        }
+        catch (error) {
+            server.off('error', onError);
+            server.off('listening', onListening);
+            reject(error);
+        }
+    });
+}
+async function removeOwnedDescriptor(removeDescriptor, descriptorPath, instanceId) {
+    await removeDescriptor(descriptorPath, instanceId);
+}
+async function assertDescriptorAvailable(readDescriptor, isPidAlive, descriptorPath) {
+    const existingDescriptor = await readDescriptor(descriptorPath);
+    if (existingDescriptor && await isPidAlive(existingDescriptor.pid)) {
+        throw new KiokukoError('CONFLICT', 'Another live Kiokuko instance owns the runtime descriptor');
+    }
+}
+export async function startHttpServer(options = {}) {
+    const host = validateHost(options.host ?? DEFAULT_HOST);
+    const port = validatePort(options.port ?? DEFAULT_PORT);
+    validateApplicationComposition(options);
+    const queueCapacity = options.queueCapacity ?? DEFAULT_QUEUE_CAPACITY;
+    const queue = new WriteQueue(queueCapacity);
+    const databasePath = databasePathFor(options);
+    const descriptorPath = descriptorPathFor(options);
+    const instanceId = options.instanceId ?? randomUUID();
+    const pid = options.pid ?? process.pid;
+    const capabilityToken = validateCapabilityToken(options.capabilityToken ?? randomBytes(32).toString('hex'));
+    const isPidAlive = options.dependencies?.isPidAlive ?? options.isPidAlive ?? defaultIsPidAlive;
+    const readDescriptor = options.dependencies?.readRuntimeDescriptor ?? options.readRuntimeDescriptor ?? defaultReadRuntimeDescriptor;
+    const writeDescriptor = options.dependencies?.writeRuntimeDescriptor ?? options.writeRuntimeDescriptor ?? defaultWriteRuntimeDescriptor;
+    const removeDescriptor = options.dependencies?.removeRuntimeDescriptor ?? options.removeRuntimeDescriptor ?? defaultRemoveRuntimeDescriptor;
+    const createDescriptor = options.dependencies?.createRuntimeDescriptor ?? options.createRuntimeDescriptor ?? defaultCreateRuntimeDescriptor;
+    const acquireLock = options.dependencies?.acquireInstanceLock ?? options.acquireInstanceLock ?? defaultAcquireInstanceLock;
+    const openDatabase = options.dependencies?.openDatabase ?? options.openDatabase ?? openConnection;
+    const migrate = options.dependencies?.migrateDatabase ?? options.migrateDatabase ?? defaultMigrateDatabase;
+    const createHttpServer = options.dependencies?.createServer ?? options.createServer ?? nodeCreateServer;
+    try {
+        await assertDescriptorAvailable(readDescriptor, isPidAlive, descriptorPath);
+    }
+    catch (error) {
+        throw safeStartupError(error);
+    }
+    let database;
+    let lock;
+    let server;
+    let descriptorAttempted = false;
+    let databaseClosed = false;
+    let lockReleased = false;
+    let descriptorRemoved = false;
+    const rollback = async (originalError) => {
+        if (server !== undefined)
+            await closeServer(server).catch(() => undefined);
+        await queue.close().catch(() => undefined);
+        if (database !== undefined && !databaseClosed) {
+            try {
+                database.close();
+            }
+            catch {
+                // Preserve the startup error.
+            }
+            databaseClosed = true;
+        }
+        if (descriptorAttempted && !descriptorRemoved) {
+            await removeOwnedDescriptor(removeDescriptor, descriptorPath, instanceId).catch(() => undefined);
+            descriptorRemoved = true;
+        }
+        if (lock !== undefined && !lockReleased) {
+            await lock.release().catch(() => undefined);
+            lockReleased = true;
+        }
+        throw safeStartupError(originalError);
+    };
+    try {
+        lock = await acquireLock(databasePath, lockOptionsFor(options, instanceId, pid, isPidAlive));
+        database = await openDatabase(databasePath);
+        await migrate(database, options.migrationsDirectory);
+        let closing = false;
+        let ready = false;
+        const requestAdmission = new AsyncLocalStorage();
+        let activeRequests = 0;
+        const requestDrainWaiters = [];
+        const waitForAcceptedRequests = () => {
+            if (activeRequests === 0)
+                return Promise.resolve();
+            return new Promise((resolve) => {
+                requestDrainWaiters.push(resolve);
+            });
+        };
+        const enqueueWrite = (operation) => {
+            if (closing && requestAdmission.getStore()?.active !== true) {
+                return Promise.reject(new KiokukoError('SERVICE_UNAVAILABLE', 'Write queue is closed'));
+            }
+            return queue.enqueue(operation);
+        };
+        const createAuthenticatedApp = (v1) => createApp({
+            expectedToken: capabilityToken,
+            readiness: () => ready && !closing,
+            ...(v1 === undefined ? {} : { v1 }),
+        });
+        const application = options.applicationFactory === undefined
+            ? options.app ?? createAuthenticatedApp(options.v1)
+            : options.applicationFactory({
+                database,
+                enqueueWrite,
+                createAuthenticatedApp,
+            });
+        const requestListener = (request, response) => {
+            const admission = { active: true };
+            activeRequests += 1;
+            const settle = () => {
+                if (!admission.active)
+                    return;
+                admission.active = false;
+                activeRequests -= 1;
+                if (activeRequests !== 0)
+                    return;
+                const waiters = requestDrainWaiters.splice(0);
+                for (const resolve of waiters)
+                    resolve();
+            };
+            response.once('finish', settle);
+            response.once('close', settle);
+            try {
+                requestAdmission.run(admission, () => application(request, response));
+            }
+            catch (error) {
+                settle();
+                throw error;
+            }
+        };
+        server = createHttpServer(requestListener);
+        await listen(server, port, host);
+        const actualPort = listeningPort(server);
+        const url = publicUrl(host, actualPort);
+        const descriptor = createDescriptor({
+            baseUrl: url,
+            capabilityToken,
+            databasePath,
+            instanceId,
+            pid,
+            ...(options.startedAt === undefined ? {} : { startedAt: options.startedAt }),
+        });
+        await assertDescriptorAvailable(readDescriptor, isPidAlive, descriptorPath);
+        descriptorAttempted = true;
+        await writeDescriptor(descriptorPath, descriptor);
+        ready = true;
+        const publicDescriptor = toPublicRuntimeDescriptor(descriptor);
+        let closePromise;
+        const handle = {
+            server,
+            url,
+            descriptor: publicDescriptor,
+            runtimeDescriptor: publicDescriptor,
+            get queueState() {
+                return queue.state;
+            },
+            enqueueWrite(operation) {
+                return enqueueWrite(operation);
+            },
+            close() {
+                if (closePromise !== undefined)
+                    return closePromise;
+                closing = true;
+                ready = false;
+                closePromise = (async () => {
+                    let firstError;
+                    const serverClose = closeServer(server).catch((error) => {
+                        firstError ??= error;
+                    });
+                    const requestClose = waitForAcceptedRequests().catch((error) => {
+                        firstError ??= error;
+                    });
+                    const queueClose = activeRequests === 0
+                        ? queue.close().catch((error) => {
+                            firstError ??= error;
+                        })
+                        : undefined;
+                    await Promise.all([serverClose, requestClose]);
+                    if (queueClose === undefined) {
+                        await queue.close().catch((error) => {
+                            firstError ??= error;
+                        });
+                    }
+                    else {
+                        await queueClose;
+                    }
+                    if (database !== undefined && !databaseClosed) {
+                        try {
+                            database.close();
+                        }
+                        catch (error) {
+                            firstError ??= error;
+                        }
+                        databaseClosed = true;
+                    }
+                    if (!descriptorRemoved) {
+                        await removeOwnedDescriptor(removeDescriptor, descriptorPath, instanceId).catch((error) => {
+                            firstError ??= error;
+                        });
+                        descriptorRemoved = true;
+                    }
+                    if (lock !== undefined && !lockReleased) {
+                        await lock.release().catch((error) => {
+                            firstError ??= error;
+                        });
+                        lockReleased = true;
+                    }
+                    if (firstError !== undefined)
+                        throw safeCloseError(firstError);
+                })();
+                return closePromise;
+            },
+        };
+        return handle;
+    }
+    catch (error) {
+        return rollback(error);
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/server/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/server/http.ts"],"names":[],"mappings":"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"}

package/dist/server/idempotency.d.ts

@@ -0,0 +1,12 @@
+import type { SqliteDatabase } from '../db/adapter.js';
+import { type JsonValue } from '../serialization/validate.js';
+export interface IdempotencyInput {
+    readonly scope: unknown;
+    readonly key: unknown;
+    readonly request: unknown;
+    readonly createdAt?: unknown;
+}
+export type IdempotencyOperation<T extends JsonValue = JsonValue> = () => T;
+export declare function executeIdempotent<T extends JsonValue>(database: SqliteDatabase, input: unknown, operation: IdempotencyOperation<T>): T;
+export declare function executeIdempotentInTransaction<T extends JsonValue>(database: SqliteDatabase, input: unknown, operation: IdempotencyOperation<T>): T;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/server/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../src/server/idempotency.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGvD,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE7E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,IAAI,MAAM,CAAC,CAAC;AAwO5E,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,SAAS,EACnD,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,oBAAoB,CAAC,CAAC,CAAC,GACjC,CAAC,CAIH;AAED,wBAAgB,8BAA8B,CAAC,CAAC,SAAS,SAAS,EAChE,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,oBAAoB,CAAC,CAAC,CAAC,GACjC,CAAC,CAIH"}

package/dist/server/idempotency.js

@@ -0,0 +1,210 @@
+import { createHash } from 'node:crypto';
+import { withImmediateTransaction } from '../db/transaction.js';
+import { KiokukoError } from '../errors.js';
+import { canonicalJson } from '../serialization/validate.js';
+const MAX_SCOPE_OR_KEY_LENGTH = 256;
+const INPUT_FIELDS = new Set(['scope', 'key', 'request', 'createdAt']);
+const CONTROL_CHARACTERS = /\p{Cc}/u;
+const CANONICAL_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;
+const VALIDATION_MESSAGE = 'Invalid idempotency input';
+const RESPONSE_VALIDATION_MESSAGE = 'Invalid idempotency response';
+const INTEGRITY_MESSAGE = 'Stored idempotency record is invalid';
+const CONFLICT_MESSAGE = 'Idempotency key was reused with a different request';
+function invalidInput() {
+    throw new KiokukoError('VALIDATION_ERROR', VALIDATION_MESSAGE);
+}
+function invalidResponse() {
+    throw new KiokukoError('VALIDATION_ERROR', RESPONSE_VALIDATION_MESSAGE);
+}
+function sha256(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    try {
+        const prototype = Object.getPrototypeOf(value);
+        return prototype === Object.prototype || prototype === null;
+    }
+    catch {
+        return false;
+    }
+}
+function isCanonicalArrayIndex(value) {
+    if (value === '0')
+        return true;
+    if (!/^[1-9]\d*$/u.test(value))
+        return false;
+    const index = Number(value);
+    return Number.isSafeInteger(index) && index < 4_294_967_295 && String(index) === value;
+}
+function validateJsonValue(value, ancestors, failure) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'string')
+        return;
+    if (typeof value === 'number') {
+        if (Number.isFinite(value))
+            return;
+        failure();
+    }
+    if (typeof value !== 'object')
+        failure();
+    if (ancestors.has(value))
+        failure();
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            for (const key of Reflect.ownKeys(value)) {
+                if (typeof key !== 'string' || (key !== 'length' && !isCanonicalArrayIndex(key)))
+                    failure();
+            }
+            for (const item of value)
+                validateJsonValue(item, ancestors, failure);
+        }
+        else {
+            if (!isPlainObject(value))
+                failure();
+            for (const key of Reflect.ownKeys(value)) {
+                if (typeof key !== 'string')
+                    failure();
+            }
+            for (const child of Object.values(value))
+                validateJsonValue(child, ancestors, failure);
+        }
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function boundedString(value) {
+    if (typeof value !== 'string'
+        || value.trim().length === 0
+        || value.length > MAX_SCOPE_OR_KEY_LENGTH
+        || CONTROL_CHARACTERS.test(value)) {
+        invalidInput();
+    }
+    return value;
+}
+function isCanonicalTimestamp(value) {
+    if (typeof value !== 'string' || !CANONICAL_TIMESTAMP.test(value))
+        return false;
+    const parsed = new Date(value);
+    return !Number.isNaN(parsed.getTime()) && parsed.toISOString() === value;
+}
+function canonicalTimestamp(value) {
+    if (!isCanonicalTimestamp(value))
+        invalidInput();
+    return value;
+}
+function validateInput(input) {
+    if (!isPlainObject(input))
+        invalidInput();
+    try {
+        for (const field of Reflect.ownKeys(input)) {
+            if (typeof field !== 'string' || !INPUT_FIELDS.has(field))
+                invalidInput();
+        }
+    }
+    catch {
+        invalidInput();
+    }
+    const scope = boundedString(input.scope);
+    const key = boundedString(input.key);
+    let requestJson;
+    try {
+        validateJsonValue(input.request, new WeakSet(), invalidInput);
+        requestJson = canonicalJson(input.request);
+    }
+    catch {
+        invalidInput();
+    }
+    const createdAt = input.createdAt === undefined
+        ? new Date().toISOString()
+        : canonicalTimestamp(input.createdAt);
+    return {
+        scope,
+        keyHash: sha256(key),
+        requestHash: sha256(requestJson),
+        createdAt,
+    };
+}
+function invalidStoredRecord() {
+    throw new KiokukoError('INTEGRITY_ERROR', INTEGRITY_MESSAGE);
+}
+function isSha256(value) {
+    return typeof value === 'string' && /^[0-9a-f]{64}$/u.test(value);
+}
+function storedResponse(row, expectedScope) {
+    if (row.scope !== expectedScope
+        || !isSha256(row.key_hash)
+        || !isSha256(row.request_hash)
+        || typeof row.response_json !== 'string'
+        || !isCanonicalTimestamp(row.created_at)) {
+        invalidStoredRecord();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(row.response_json);
+        if (canonicalJson(parsed) !== row.response_json)
+            invalidStoredRecord();
+    }
+    catch {
+        invalidStoredRecord();
+    }
+    return parsed;
+}
+function findStoredRecord(database, validated) {
+    const select = `
+    SELECT scope, key_hash, request_hash, response_json, created_at
+    FROM gateway_idempotency
+  `;
+    const direct = database.prepare(`${select} WHERE scope = ? AND key_hash = ?`).get(validated.scope, validated.keyHash);
+    if (direct) {
+        const response = storedResponse(direct, validated.scope);
+        return { requestHash: direct.request_hash, response };
+    }
+    for (const row of database.prepare(`${select} WHERE scope = ?`).all(validated.scope)) {
+        const response = storedResponse(row, validated.scope);
+        if (row.key_hash === validated.keyHash) {
+            return { requestHash: row.request_hash, response };
+        }
+    }
+    return undefined;
+}
+function validateOperation(operation) {
+    if (typeof operation !== 'function')
+        invalidInput();
+}
+function executeValidated(database, validated, operation) {
+    const existing = findStoredRecord(database, validated);
+    if (existing) {
+        if (existing.requestHash !== validated.requestHash) {
+            throw new KiokukoError('CONFLICT', CONFLICT_MESSAGE, { reason: 'request_mismatch' });
+        }
+        return existing.response;
+    }
+    const responseValue = operation();
+    let responseJson;
+    try {
+        validateJsonValue(responseValue, new WeakSet(), invalidResponse);
+        responseJson = canonicalJson(responseValue);
+    }
+    catch {
+        throw new KiokukoError('VALIDATION_ERROR', RESPONSE_VALIDATION_MESSAGE);
+    }
+    database.prepare(`
+    INSERT INTO gateway_idempotency (scope, key_hash, request_hash, response_json, created_at)
+    VALUES (?, ?, ?, ?, ?)
+  `).run(validated.scope, validated.keyHash, validated.requestHash, responseJson, validated.createdAt);
+    return JSON.parse(responseJson);
+}
+export function executeIdempotent(database, input, operation) {
+    validateOperation(operation);
+    const validated = validateInput(input);
+    return withImmediateTransaction(database, () => executeValidated(database, validated, operation));
+}
+export function executeIdempotentInTransaction(database, input, operation) {
+    validateOperation(operation);
+    const validated = validateInput(input);
+    return executeValidated(database, validated, operation);
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/server/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../../src/server/idempotency.ts"],"names":[],"mappings":"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"}

package/dist/server/instance-lock.d.ts

@@ -0,0 +1,17 @@
+import { type PathEnvironment } from '../config/paths.js';
+export type PidLiveness = (pid: number) => boolean | Promise<boolean>;
+export interface InstanceLockOptions extends PathEnvironment {
+    runtimeDirectory?: string;
+    pid?: number;
+    instanceId?: string;
+    isPidAlive?: PidLiveness;
+}
+export interface InstanceLock {
+    path: string;
+    instanceId: string;
+    release(): Promise<boolean>;
+}
+export declare function isPidAlive(pid: number): Promise<boolean>;
+export declare function acquireInstanceLock(databasePath: string, options?: InstanceLockOptions): Promise<InstanceLock>;
+export declare function releaseInstanceLock(lockFilePath: string, expectedInstanceId: string): Promise<boolean>;
+//# sourceMappingURL=instance-lock.d.ts.map

package/dist/server/instance-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-lock.d.ts","sourceRoot":"","sources":["../../src/server/instance-lock.ts"],"names":[],"mappings":"AAGA,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG/E,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtE,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,WAAW,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7B;AAgDD,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAW9D;AAED,wBAAsB,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,CAAC,CA6BxH;AAED,wBAAsB,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAgB5G"}