@prairielearn/named-locks 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+/// <reference types="node" />
+import { PoolClient } from '@prairielearn/postgres';
+import { PoolConfig } from 'pg';
+interface Lock {
+    client: PoolClient;
+}
+interface LockOptions {
+    /** How many milliseconds to wait (anything other than a positive number means forever) */
+    timeout?: number;
+}
+/**
+ * Initializes a new {@link PostgresPool} that will be used to acquire named locks.
+ */
+export declare function init(pgConfig: PoolConfig, idleErrorHandler: (error: Error, client: PoolClient) => void): Promise<void>;
+/**
+ * Shuts down the database connection pool that was used to acquire locks.
+ */
+export declare function close(): Promise<void>;
+/**
+ * Try to acquire a lock and either succeed if it's available or
+ * return immediately if not. If a lock is acquired then it must
+ * must later be released by releaseLock(). If a lock is not acquired
+ * (it is null) then releaseLock() should not be called.
+ *
+ * @param name The name of the lock to acquire.
+ */
+export declare function tryLockAsync(name: string): Promise<Lock | null>;
+export declare const tryLock: (arg1: string, callback: (err: NodeJS.ErrnoException, result: Lock | null) => void) => void;
+/**
+ * Wait until a lock can be successfully acquired.
+ *
+ * @param name The name of the lock to acquire.
+ * @param options
+ */
+export declare function waitLockAsync(name: string, options: LockOptions): Promise<Lock>;
+export declare const waitLock: (arg1: string, arg2: LockOptions, callback: (err: NodeJS.ErrnoException | null, result: Lock) => void) => void;
+/**
+ * Release a lock.
+ *
+ * @param lock A previously-acquired lock.
+ */
+export declare function releaseLockAsync(lock: Lock): Promise<void>;
+export declare const releaseLock: (arg1: Lock, callback: (err: NodeJS.ErrnoException) => void) => void;
+/**
+ * Acquires the given lock, executes the provided function with the lock held,
+ * and releases the lock once the function has executed.
+ */
+export declare function doWithLock<T>(name: string, options: LockOptions, func: () => Promise<T>): Promise<T>;
+export {};

package/dist/index.js

@@ -0,0 +1,172 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.doWithLock = exports.releaseLock = exports.releaseLockAsync = exports.waitLock = exports.waitLockAsync = exports.tryLock = exports.tryLockAsync = exports.close = exports.init = void 0;
+const util_1 = __importDefault(require("util"));
+const postgres_1 = require("@prairielearn/postgres");
+/*
+ * The functions here all identify locks by "name", which is a plain
+ * string. The locks use the named_locks DB table. Each lock name
+ * corresponds to a unique table row. To take a lock, we:
+ *     1. make sure a row exists for the lock name
+ *     2. start a transaction
+ *     3. acquire a "FOR UPDATE" row lock on the DB row for the named
+ *        lock (this blocks all other locks on the same row). See
+ *        https://www.postgresql.org/docs/current/explicit-locking.html#LOCKING-ROWS
+ *     4. return to the caller with the transaction held open
+ *
+ * The caller then does some work and finally calls releaseLock(),
+ * which ends the transaction, thereby releasing the row lock.
+ *
+ * The flow above will wait indefinitely for the lock to become
+ * available. To implement optional timeouts, we set the DB variable
+ * `lock_timeout`:
+ * https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-LOCK-TIMEOUT
+ * If we timeout then we will return an error to the caller.
+ *
+ * To implement a no-waiting tryLock() we use the PostgreSQL "SKIP
+ * LOCKED" feature:
+ * https://www.postgresql.org/docs/current/sql-select.html#SQL-FOR-UPDATE-SHARE
+ * If we fail to acquire the lock then we immediately release the
+ * transaction and return to the caller with `lock = null`. In this
+ * case the caller should not call releaseLock().
+ *
+ * The lock object returned by functions in this module are of the
+ * form `{client, done}`, where `client` and `done` are sqldb
+ * transaction objects. These are simply the objects we need to end
+ * the transaction, which will release the lock.
+ *
+ * Importantly, we use a separate pool of database connections for acquiring
+ * and holding locks. This ensures that we don't end up with a deadlock.
+ * For instance, if we have a pool of 10 clients and there are 10 locks held at
+ * once, if any code inside of a lock tries to acquire another database client,
+ * we'd deadlock if we weren't separating the two pools of connections.
+ *
+ * You should NEVER try to acquire a lock in code that is executing with another
+ * lock already held. Since there are a finite pool of locks available, this
+ * can lead to deadlocks.
+ */
+const pool = new postgres_1.PostgresPool();
+/**
+ * Initializes a new {@link PostgresPool} that will be used to acquire named locks.
+ */
+async function init(pgConfig, idleErrorHandler) {
+    await pool.initAsync(pgConfig, idleErrorHandler);
+    await pool.queryAsync('CREATE TABLE IF NOT EXISTS named_locks (id bigserial PRIMARY KEY, name text NOT NULL UNIQUE);', {});
+}
+exports.init = init;
+/**
+ * Shuts down the database connection pool that was used to acquire locks.
+ */
+async function close() {
+    await pool.closeAsync();
+}
+exports.close = close;
+/**
+ * Try to acquire a lock and either succeed if it's available or
+ * return immediately if not. If a lock is acquired then it must
+ * must later be released by releaseLock(). If a lock is not acquired
+ * (it is null) then releaseLock() should not be called.
+ *
+ * @param name The name of the lock to acquire.
+ */
+async function tryLockAsync(name) {
+    return getLock(name, { wait: false });
+}
+exports.tryLockAsync = tryLockAsync;
+exports.tryLock = util_1.default.callbackify(tryLockAsync);
+/**
+ * Wait until a lock can be successfully acquired.
+ *
+ * @param name The name of the lock to acquire.
+ * @param options
+ */
+async function waitLockAsync(name, options) {
+    const internalOptions = {
+        wait: true,
+        timeout: options.timeout || 0,
+    };
+    const lock = await getLock(name, internalOptions);
+    if (lock == null)
+        throw new Error(`failed to acquire lock: ${name}`);
+    return lock;
+}
+exports.waitLockAsync = waitLockAsync;
+exports.waitLock = util_1.default.callbackify(waitLockAsync);
+/**
+ * Release a lock.
+ *
+ * @param lock A previously-acquired lock.
+ */
+async function releaseLockAsync(lock) {
+    if (lock == null)
+        throw new Error('lock is null');
+    await pool.endTransactionAsync(lock.client, null);
+}
+exports.releaseLockAsync = releaseLockAsync;
+exports.releaseLock = util_1.default.callbackify(releaseLockAsync);
+/**
+ * Acquires the given lock, executes the provided function with the lock held,
+ * and releases the lock once the function has executed.
+ */
+async function doWithLock(name, options, func) {
+    const lock = await waitLockAsync(name, options);
+    try {
+        return await func();
+    }
+    finally {
+        await releaseLockAsync(lock);
+    }
+}
+exports.doWithLock = doWithLock;
+/**
+ * Internal helper function to get a lock with optional
+ * waiting. Do not call directly, but use tryLock() or waitLock()
+ * instead.
+ *
+ * @param name The name of the lock to acquire.
+ * @param options Optional parameters.
+ */
+async function getLock(name, options) {
+    await pool.queryAsync('INSERT INTO named_locks (name) VALUES ($name) ON CONFLICT (name) DO NOTHING;', { name });
+    const client = await pool.beginTransactionAsync();
+    let acquiredLock = false;
+    try {
+        if (options.wait && options.timeout > 0) {
+            // SQL doesn't like us trying to use a parameterized query with
+            // `SET LOCAL ...`. So, in this very specific case, we do the
+            // parameterization ourselves using `escapeLiteral`.
+            await pool.queryWithClientAsync(client, `SET LOCAL lock_timeout = ${client.escapeLiteral(options.timeout.toString())}`, {});
+        }
+        // A stuck lock is a critical issue. To make them easier to debug, we'll
+        // include the literal lock name in the query instead of using a
+        // parameterized query. The lock name should never include PII, so it's
+        // safe if it shows up in plaintext in logs, telemetry, error messages,
+        // etc.
+        const lockNameLiteral = client.escapeLiteral(name);
+        const lock_sql = options.wait
+            ? `SELECT * FROM named_locks WHERE name = ${lockNameLiteral} FOR UPDATE;`
+            : `SELECT * FROM named_locks WHERE name = ${lockNameLiteral} FOR UPDATE SKIP LOCKED;`;
+        const result = await pool.queryWithClientAsync(client, lock_sql, { name });
+        acquiredLock = result.rowCount === 1;
+    }
+    catch (err) {
+        // Something went wrong, so we end the transaction and re-throw the
+        // error.
+        await pool.endTransactionAsync(client, err);
+        throw err;
+    }
+    if (!acquiredLock) {
+        // We didn't acquire the lock so our parent caller will never
+        // release it, so we have to end the transaction now.
+        await pool.endTransactionAsync(client, null);
+        return null;
+    }
+    // We successfully acquired the lock, so we return with the transaction
+    // help open. The caller will be responsible for releasing the lock and
+    // ending the transaction.
+    return { client };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@prairielearn/named-locks",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch --preserveWatchOutput"
+  },
+  "devDependencies": {
+    "@prairielearn/tsconfig": "*",
+    "@types/node": "^18.14.2",
+    "typescript": "^4.9.4"
+  },
+  "dependencies": {
+    "@prairielearn/postgres": "^1.2.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,209 @@
+import util from 'util';
+import { PostgresPool, PoolClient } from '@prairielearn/postgres';
+import { PoolConfig } from 'pg';
+
+interface Lock {
+  client: PoolClient;
+}
+
+interface LockOptions {
+  /** How many milliseconds to wait (anything other than a positive number means forever) */
+  timeout?: number;
+}
+
+type InternalLockOptions =
+  | {
+      wait: false;
+    }
+  | {
+      wait: true;
+      timeout: number;
+    };
+
+/*
+ * The functions here all identify locks by "name", which is a plain
+ * string. The locks use the named_locks DB table. Each lock name
+ * corresponds to a unique table row. To take a lock, we:
+ *     1. make sure a row exists for the lock name
+ *     2. start a transaction
+ *     3. acquire a "FOR UPDATE" row lock on the DB row for the named
+ *        lock (this blocks all other locks on the same row). See
+ *        https://www.postgresql.org/docs/current/explicit-locking.html#LOCKING-ROWS
+ *     4. return to the caller with the transaction held open
+ *
+ * The caller then does some work and finally calls releaseLock(),
+ * which ends the transaction, thereby releasing the row lock.
+ *
+ * The flow above will wait indefinitely for the lock to become
+ * available. To implement optional timeouts, we set the DB variable
+ * `lock_timeout`:
+ * https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-LOCK-TIMEOUT
+ * If we timeout then we will return an error to the caller.
+ *
+ * To implement a no-waiting tryLock() we use the PostgreSQL "SKIP
+ * LOCKED" feature:
+ * https://www.postgresql.org/docs/current/sql-select.html#SQL-FOR-UPDATE-SHARE
+ * If we fail to acquire the lock then we immediately release the
+ * transaction and return to the caller with `lock = null`. In this
+ * case the caller should not call releaseLock().
+ *
+ * The lock object returned by functions in this module are of the
+ * form `{client, done}`, where `client` and `done` are sqldb
+ * transaction objects. These are simply the objects we need to end
+ * the transaction, which will release the lock.
+ *
+ * Importantly, we use a separate pool of database connections for acquiring
+ * and holding locks. This ensures that we don't end up with a deadlock.
+ * For instance, if we have a pool of 10 clients and there are 10 locks held at
+ * once, if any code inside of a lock tries to acquire another database client,
+ * we'd deadlock if we weren't separating the two pools of connections.
+ *
+ * You should NEVER try to acquire a lock in code that is executing with another
+ * lock already held. Since there are a finite pool of locks available, this
+ * can lead to deadlocks.
+ */
+
+const pool = new PostgresPool();
+
+/**
+ * Initializes a new {@link PostgresPool} that will be used to acquire named locks.
+ */
+export async function init(
+  pgConfig: PoolConfig,
+  idleErrorHandler: (error: Error, client: PoolClient) => void
+) {
+  await pool.initAsync(pgConfig, idleErrorHandler);
+  await pool.queryAsync(
+    'CREATE TABLE IF NOT EXISTS named_locks (id bigserial PRIMARY KEY, name text NOT NULL UNIQUE);',
+    {}
+  );
+}
+
+/**
+ * Shuts down the database connection pool that was used to acquire locks.
+ */
+export async function close() {
+  await pool.closeAsync();
+}
+
+/**
+ * Try to acquire a lock and either succeed if it's available or
+ * return immediately if not. If a lock is acquired then it must
+ * must later be released by releaseLock(). If a lock is not acquired
+ * (it is null) then releaseLock() should not be called.
+ *
+ * @param name The name of the lock to acquire.
+ */
+export async function tryLockAsync(name: string): Promise<Lock | null> {
+  return getLock(name, { wait: false });
+}
+
+export const tryLock = util.callbackify(tryLockAsync);
+
+/**
+ * Wait until a lock can be successfully acquired.
+ *
+ * @param name The name of the lock to acquire.
+ * @param options
+ */
+export async function waitLockAsync(name: string, options: LockOptions): Promise<Lock> {
+  const internalOptions = {
+    wait: true,
+    timeout: options.timeout || 0,
+  };
+
+  const lock = await getLock(name, internalOptions);
+  if (lock == null) throw new Error(`failed to acquire lock: ${name}`);
+  return lock;
+}
+
+export const waitLock = util.callbackify(waitLockAsync);
+
+/**
+ * Release a lock.
+ *
+ * @param lock A previously-acquired lock.
+ */
+export async function releaseLockAsync(lock: Lock) {
+  if (lock == null) throw new Error('lock is null');
+  await pool.endTransactionAsync(lock.client, null);
+}
+
+export const releaseLock = util.callbackify(releaseLockAsync);
+
+/**
+ * Acquires the given lock, executes the provided function with the lock held,
+ * and releases the lock once the function has executed.
+ */
+export async function doWithLock<T>(
+  name: string,
+  options: LockOptions,
+  func: () => Promise<T>
+): Promise<T> {
+  const lock = await waitLockAsync(name, options);
+  try {
+    return await func();
+  } finally {
+    await releaseLockAsync(lock);
+  }
+}
+
+/**
+ * Internal helper function to get a lock with optional
+ * waiting. Do not call directly, but use tryLock() or waitLock()
+ * instead.
+ *
+ * @param name The name of the lock to acquire.
+ * @param options Optional parameters.
+ */
+async function getLock(name: string, options: InternalLockOptions) {
+  await pool.queryAsync(
+    'INSERT INTO named_locks (name) VALUES ($name) ON CONFLICT (name) DO NOTHING;',
+    { name }
+  );
+
+  const client = await pool.beginTransactionAsync();
+
+  let acquiredLock = false;
+  try {
+    if (options.wait && options.timeout > 0) {
+      // SQL doesn't like us trying to use a parameterized query with
+      // `SET LOCAL ...`. So, in this very specific case, we do the
+      // parameterization ourselves using `escapeLiteral`.
+      await pool.queryWithClientAsync(
+        client,
+        `SET LOCAL lock_timeout = ${client.escapeLiteral(options.timeout.toString())}`,
+        {}
+      );
+    }
+
+    // A stuck lock is a critical issue. To make them easier to debug, we'll
+    // include the literal lock name in the query instead of using a
+    // parameterized query. The lock name should never include PII, so it's
+    // safe if it shows up in plaintext in logs, telemetry, error messages,
+    // etc.
+    const lockNameLiteral = client.escapeLiteral(name);
+    const lock_sql = options.wait
+      ? `SELECT * FROM named_locks WHERE name = ${lockNameLiteral} FOR UPDATE;`
+      : `SELECT * FROM named_locks WHERE name = ${lockNameLiteral} FOR UPDATE SKIP LOCKED;`;
+    const result = await pool.queryWithClientAsync(client, lock_sql, { name });
+    acquiredLock = result.rowCount === 1;
+  } catch (err) {
+    // Something went wrong, so we end the transaction and re-throw the
+    // error.
+    await pool.endTransactionAsync(client, err as Error);
+    throw err;
+  }
+
+  if (!acquiredLock) {
+    // We didn't acquire the lock so our parent caller will never
+    // release it, so we have to end the transaction now.
+    await pool.endTransactionAsync(client, null);
+    return null;
+  }
+
+  // We successfully acquired the lock, so we return with the transaction
+  // help open. The caller will be responsible for releasing the lock and
+  // ending the transaction.
+  return { client };
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@prairielearn/tsconfig",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node"],
+  }
+}