ts-prorm-orm 1.1.0

package/dist/nosql/etcd/index.js

@@ -0,0 +1,502 @@
+"use strict";
+/**
+ * etcd store implementation.
+ *
+ * etcd is a distributed, strongly-consistent key-value store used for
+ * service discovery, distributed configuration and coordination primitives
+ * (leader election, distributed locking). It has no query language, no
+ * schema, and no `JOIN`/transaction-log concept in the SQL sense, so it does
+ * not fit the SQL-shaped `Dialect` interface used by the SQL dialects in
+ * this repo. Instead it implements the minimal `NoSqlStore` marker
+ * interface (`src/nosql/store.ts`) and exposes etcd's real primitives -
+ * key/value get/put/delete (including prefix range operations), watch
+ * (etcd's signature "subscribe to key/prefix changes" feature), leases
+ * (TTL-based key expiry with keep-alive), distributed locking, and
+ * compare-and-swap transactions - as a typed, promise-based API instead of
+ * forcing everything into a `query(sql)` shape.
+ *
+ * Uses the official `etcd3` driver.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EtcdStore = void 0;
+const etcd3_1 = require("etcd3");
+const errors_1 = require("../../errors");
+function wrapConnectionError(err, hosts) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const host = Array.isArray(hosts) ? hosts.join(',') : hosts;
+    const message = /unavailable|econnrefused/i.test(parent.message)
+        ? 'Connection refused'
+        : `Unable to connect to etcd: ${parent.message}`;
+    return new errors_1.ConnectionError(message, { parent, database: 'etcd', host });
+}
+function wrapDatabaseError(err, message) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    // Keep the `action` context (e.g. "etcd PUT failed") but don't discard the
+    // real underlying etcd error text, the same way the Redis store does.
+    const combined = message ? `${message}: ${parent.message}` : parent.message;
+    return errors_1.DatabaseError.from(parent, { message: combined });
+}
+function kvToRecord(kvs) {
+    return { ...kvs };
+}
+/**
+ * `EtcdStore` wraps an `etcd3` client and exposes etcd's real primitives:
+ * key/value get/put/delete (single-key and prefix-range), watch, leases,
+ * distributed locking, and compare-and-swap transactions.
+ */
+class EtcdStore {
+    constructor(options) {
+        this.name = 'etcd';
+        this.library = 'etcd3';
+        this.client = null;
+        this.connected = false;
+        /** Leases granted through `grantLease()`, keyed by lease ID, so later calls can look them back up. */
+        this.leases = new Map();
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    toClientOptions() {
+        // Spread (rather than pick known fields one-by-one) so any additional
+        // etcd3 `IOptions` fields a caller passes through (e.g. `grpcOptions`,
+        // `faultHandling`) reach the underlying client too.
+        return { ...this.options };
+    }
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        try {
+            const client = new etcd3_1.Etcd3(this.toClientOptions());
+            // etcd3's constructor doesn't itself dial out; issue a cheap call to
+            // surface connectivity problems (bad hosts, refused connections,
+            // auth failures) immediately, the same way RedisStore eagerly
+            // connects instead of waiting for the first real command.
+            await client.get('__prorm_connect_probe__').string();
+            this.client = client;
+            this.connected = true;
+        }
+        catch (err) {
+            this.client?.close();
+            this.client = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.hosts);
+        }
+    }
+    async disconnect() {
+        for (const lease of this.leases.values()) {
+            lease.release();
+        }
+        this.leases.clear();
+        if (this.client) {
+            this.client.close();
+            this.client = null;
+        }
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `etcd3` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to etcd', { database: 'etcd' });
+        }
+        return this.client;
+    }
+    async exec(fn, action) {
+        const client = this.requireClient();
+        try {
+            return await fn(client);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `etcd ${action} failed`);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // JSON helpers (opt-in convenience on top of the raw string API)
+    // ---------------------------------------------------------------------
+    async putJSON(key, value, options = {}) {
+        return this.put(key, JSON.stringify(value), options);
+    }
+    async getJSON(key) {
+        const raw = await this.get(key);
+        if (raw === null) {
+            return null;
+        }
+        try {
+            return JSON.parse(raw);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `etcd GETJSON failed (invalid JSON for key "${key}")`);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Single-key operations
+    // ---------------------------------------------------------------------
+    async get(key) {
+        return this.exec((c) => c.get(key).string(), 'GET');
+    }
+    async getBuffer(key) {
+        return this.exec((c) => c.get(key).buffer(), 'GET');
+    }
+    async put(key, value, options = {}) {
+        await this.exec(async (c) => {
+            const builder = c.put(key).value(value);
+            if (options.lease !== undefined) {
+                builder.lease(options.lease);
+            }
+            await builder.exec();
+        }, 'PUT');
+    }
+    /** Deletes a single key. Returns the number of keys actually deleted (`0` or `1`). */
+    async delete(key) {
+        return this.exec(async (c) => {
+            const res = await c.delete().key(key).exec();
+            return Number(res.deleted);
+        }, 'DELETE');
+    }
+    async exists(key) {
+        return this.exec((c) => c.get(key).exists(), 'EXISTS');
+    }
+    // ---------------------------------------------------------------------
+    // Prefix / range operations
+    // ---------------------------------------------------------------------
+    /** All key/value pairs whose key starts with `prefix`. */
+    async getPrefix(prefix) {
+        return this.exec(async (c) => kvToRecord(await c.getAll().prefix(prefix).strings()), 'GETPREFIX');
+    }
+    /** All keys (without values) starting with `prefix`. */
+    async getKeysWithPrefix(prefix) {
+        return this.exec((c) => c.getAll().prefix(prefix).keys(), 'GETPREFIX KEYS');
+    }
+    /** Number of keys starting with `prefix`, without transferring their values. */
+    async countPrefix(prefix) {
+        return this.exec((c) => c.getAll().prefix(prefix).count(), 'COUNTPREFIX');
+    }
+    /** Deletes every key starting with `prefix`. Returns the number of keys deleted. */
+    async deletePrefix(prefix) {
+        return this.exec(async (c) => {
+            const res = await c.delete().prefix(prefix).exec();
+            return Number(res.deleted);
+        }, 'DELETEPREFIX');
+    }
+    // ---------------------------------------------------------------------
+    // Watch (etcd's signature feature: subscribe to key/prefix changes)
+    // ---------------------------------------------------------------------
+    attachWatchHandler(watcher, handler) {
+        watcher.on('put', (kv, previous) => {
+            handler({
+                type: 'put',
+                key: kv.key.toString(),
+                value: kv.value.toString(),
+                previousValue: previous ? previous.value.toString() : null,
+            });
+        });
+        watcher.on('delete', (kv, previous) => {
+            handler({
+                type: 'delete',
+                key: kv.key.toString(),
+                value: null,
+                previousValue: previous ? previous.value.toString() : null,
+            });
+        });
+    }
+    /**
+     * Watch a single key for changes, invoking `handler` for every `put`/
+     * `delete` on that key. Returns a handle whose `cancel()` stops the
+     * underlying watch stream.
+     */
+    async watch(key, handler) {
+        return this.exec(async (c) => {
+            const watcher = await c.watch().key(key).withPreviousKV().create();
+            this.attachWatchHandler(watcher, handler);
+            return { watcher, cancel: () => watcher.cancel() };
+        }, 'WATCH');
+    }
+    /**
+     * Watch every key starting with `prefix` for changes, invoking `handler`
+     * for every `put`/`delete` on any matching key. Returns a handle whose
+     * `cancel()` stops the underlying watch stream.
+     */
+    async watchPrefix(prefix, handler) {
+        return this.exec(async (c) => {
+            const watcher = await c.watch().prefix(prefix).withPreviousKV().create();
+            this.attachWatchHandler(watcher, handler);
+            return { watcher, cancel: () => watcher.cancel() };
+        }, 'WATCH');
+    }
+    // ---------------------------------------------------------------------
+    // Leases (TTL-based key expiry + keep-alive)
+    // ---------------------------------------------------------------------
+    /**
+     * Grants a new lease with the given TTL (in seconds). By default the
+     * lease is kept alive automatically in the background (`autoKeepAlive`);
+     * pass `{ autoKeepAlive: false }` to manage keep-alives manually via
+     * `keepAliveOnce()`. Returns the lease ID, which can be passed to
+     * `put(key, value, { lease })` to associate keys with the lease so they
+     * expire automatically when it does.
+     */
+    async grantLease(ttlSeconds, options = {}) {
+        return this.exec(async (c) => {
+            const leaseOptions = { autoKeepAlive: options.autoKeepAlive ?? true };
+            const lease = c.lease(ttlSeconds, leaseOptions);
+            const id = await lease.grant();
+            this.leases.set(id, lease);
+            return id;
+        }, 'LEASE GRANT');
+    }
+    /** Puts `key`/`value` under a previously granted lease, so it expires when the lease does. */
+    async putWithLease(key, value, leaseId) {
+        const lease = this.requireLease(leaseId);
+        try {
+            await lease.put(key).value(value).exec();
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'etcd PUT (with lease) failed');
+        }
+    }
+    /** Fires a single, immediate keep-alive for a lease, resetting its TTL countdown. */
+    async keepAliveOnce(leaseId) {
+        const lease = this.requireLease(leaseId);
+        try {
+            await lease.keepaliveOnce();
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'etcd LEASE KEEPALIVE failed');
+        }
+    }
+    /** Revokes a lease immediately, evicting every key still attached to it. */
+    async revokeLease(leaseId) {
+        const lease = this.requireLease(leaseId);
+        try {
+            await lease.revoke();
+        }
+        finally {
+            this.leases.delete(leaseId);
+        }
+    }
+    /**
+     * Stops sending keep-alives for a lease, letting it expire naturally when
+     * its TTL elapses, instead of revoking it immediately. Use `revokeLease()`
+     * to evict its keys right away.
+     */
+    releaseLease(leaseId) {
+        const lease = this.leases.get(leaseId);
+        lease?.release();
+        this.leases.delete(leaseId);
+    }
+    /**
+     * Registers a handler that fires when etcd indicates a lease has been
+     * lost (TTL expired without a successful keep-alive, or it was revoked
+     * server-side). Not fired when `revokeLease()`/`releaseLease()` is called
+     * locally and succeeds normally.
+     */
+    onLeaseLost(leaseId, handler) {
+        const lease = this.requireLease(leaseId);
+        lease.on('lost', handler);
+    }
+    requireLease(leaseId) {
+        const lease = this.leases.get(leaseId);
+        if (!lease) {
+            throw new errors_1.DatabaseError(`Unknown etcd lease "${leaseId}" (not granted through this store instance)`);
+        }
+        return lease;
+    }
+    // ---------------------------------------------------------------------
+    // Distributed locking
+    // ---------------------------------------------------------------------
+    /**
+     * Acquires a distributed lock on `key`, blocking (queueing behind the
+     * current holder, in acquisition order) until it's free rather than
+     * rejecting immediately. Under the hood this is a lease on the key
+     * that's revoked on `release()`, or timed out by etcd if the holder
+     * dies - `ttlSeconds` controls that lease's TTL (etcd3 defaults to 30s).
+     *
+     * Note: `etcd3`'s own `Lock#acquire()` is a single compare-and-swap
+     * attempt - it *rejects immediately* with `EtcdLockFailedError` if the
+     * key already exists, rather than waiting, despite this store's docs
+     * (and the in-repo test mock) describing blocking/queueing semantics.
+     * To actually deliver that documented contract against a real etcd
+     * server, `acquireLockOrThrow()` below retries: on
+     * `EtcdLockFailedError` it watches the key until it's deleted (i.e. the
+     * current holder released or its lease expired), then retries the CAS.
+     * Multiple waiters can wake and race the retry simultaneously; that's
+     * fine because the retry is itself a CAS - at most one of them wins
+     * each round, and the rest go back to waiting.
+     */
+    async acquireLock(key, ttlSeconds) {
+        return this.exec(async (c) => {
+            const lock = await this.acquireLockOrThrow(c, key, ttlSeconds);
+            return this.toLockHandle(lock);
+        }, 'LOCK');
+    }
+    /**
+     * Wraps an acquired `etcd3` `Lock` in an `EtcdLockHandle`. `etcd3`'s own
+     * `Lock#leaseId()` keeps returning the (now-revoked) lease ID even after
+     * `release()` - verified against a real etcd server - which contradicts
+     * this handle's documented `null`-after-release contract, so track
+     * "released" locally instead of trusting the underlying lock for that.
+     */
+    toLockHandle(lock) {
+        let released = false;
+        return {
+            leaseId: async () => (released ? null : lock.leaseId()),
+            release: async () => {
+                await lock.release();
+                released = true;
+            },
+        };
+    }
+    /**
+     * Acquires a distributed lock on `key`, runs `fn`, and releases the lock
+     * once `fn`'s result settles (whether it resolves or rejects). This is
+     * the recommended way to use locks - it can't leak a held lock the way
+     * manual `acquireLock()`/`release()` pairing can if `fn` throws.
+     */
+    async withLock(key, fn, ttlSeconds) {
+        const client = this.requireClient();
+        let lock;
+        try {
+            lock = await this.acquireLockOrThrow(client, key, ttlSeconds);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'etcd LOCK failed');
+        }
+        try {
+            const value = await fn();
+            await lock.release();
+            return value;
+        }
+        catch (err) {
+            await lock.release().catch(() => undefined);
+            throw err;
+        }
+    }
+    /**
+     * Repeatedly attempts `client.lock(key).acquire()`, waiting for the key
+     * to be deleted (via a watch) and retrying whenever it fails with
+     * `EtcdLockFailedError`, so the returned promise doesn't settle until
+     * the lock is actually acquired (see `acquireLock()` above for why this
+     * is necessary against a real etcd server).
+     */
+    async acquireLockOrThrow(client, key, ttlSeconds) {
+        for (;;) {
+            const lock = client.lock(key);
+            if (ttlSeconds !== undefined) {
+                lock.ttl(ttlSeconds);
+            }
+            try {
+                await lock.acquire();
+                return lock;
+            }
+            catch (err) {
+                if (!(err instanceof etcd3_1.EtcdLockFailedError)) {
+                    throw err;
+                }
+                await this.waitForKeyDeletion(client, key);
+            }
+        }
+    }
+    /** Resolves once `key` no longer exists (already gone, or deleted while we watch it). */
+    async waitForKeyDeletion(client, key) {
+        const stillThere = await client.get(key).exists();
+        if (!stillThere) {
+            return;
+        }
+        const watcher = await client.watch().key(key).create();
+        try {
+            await new Promise((resolve) => {
+                let settled = false;
+                const finish = () => {
+                    if (settled) {
+                        return;
+                    }
+                    settled = true;
+                    resolve();
+                };
+                watcher.on('delete', finish);
+                // The key may have been deleted between the exists() check above
+                // and the watcher attaching; re-check to avoid waiting forever.
+                client
+                    .get(key)
+                    .exists()
+                    .then((exists) => {
+                    if (!exists) {
+                        finish();
+                    }
+                })
+                    .catch(() => finish());
+            });
+        }
+        finally {
+            await watcher.cancel().catch(() => undefined);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Transactions (compare-and-swap via etcd3's if()/then()/else())
+    // ---------------------------------------------------------------------
+    /**
+     * Starts a raw etcd transaction: `if (key.<column> <cmp> value) { ... }`.
+     * Returns etcd3's `ComparatorBuilder` directly so callers get its full
+     * `.and()/.then()/.else()/.commit()` chain; combine with `putOp()`/
+     * `deleteOp()`/`getOp()` below to build the `then`/`else` clauses.
+     *
+     * ```typescript
+     * const result = await store
+     *   .ifCompare('config-version', 'Value', '==', '1')
+     *   .then(store.putOp('config-version', '2'))
+     *   .else(store.getOp('config-version'))
+     *   .commit();
+     * ```
+     */
+    ifCompare(key, column, cmp, value) {
+        return this.requireClient().if(key, column, cmp, value);
+    }
+    /** A `put` operation builder, for use as a `.then()`/`.else()` clause in `ifCompare()`. */
+    putOp(key, value) {
+        return this.requireClient().put(key).value(value);
+    }
+    /** A `delete` operation builder, for use as a `.then()`/`.else()` clause in `ifCompare()`. */
+    deleteOp(key) {
+        return this.requireClient().delete().key(key);
+    }
+    /** A `get` operation builder, for use as a `.then()`/`.else()` clause in `ifCompare()`. */
+    getOp(key) {
+        return this.requireClient().get(key);
+    }
+    /**
+     * Convenience compare-and-swap: atomically sets `key` to `newValue` only
+     * if its current value equals `expectedValue` (or, if `expectedValue` is
+     * `null`, only if the key does not currently exist). Returns whether the
+     * swap happened.
+     */
+    async compareAndSwap(key, expectedValue, newValue) {
+        return this.exec(async (c) => {
+            const comparator = expectedValue === null
+                ? c.if(key, 'Create', '==', 0)
+                : c.if(key, 'Value', '==', expectedValue);
+            const result = await comparator.then(c.put(key).value(newValue)).commit();
+            return result.succeeded;
+        }, 'TXN');
+    }
+    /**
+     * Atomically deletes `key` only if its current value equals
+     * `expectedValue`. Returns whether the delete happened.
+     */
+    async compareAndDelete(key, expectedValue) {
+        return this.exec(async (c) => {
+            const result = await c
+                .if(key, 'Value', '==', expectedValue)
+                .then(c.delete().key(key))
+                .commit();
+            return result.succeeded;
+        }, 'TXN');
+    }
+}
+exports.EtcdStore = EtcdStore;
+exports.default = EtcdStore;