@prairielearn/named-locks 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @prairielearn/named-locks
 
+## 1.3.0
+
+### Minor Changes
+
+- 4cc962358: Add `tryWithLock` function
+
+## 1.2.0
+
+### Minor Changes
+
+- 400a0b901: Allow locks to be automatically renewed
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -0,0 +1,79 @@
+# `@prairielearn/named-locks`
+
+Uses Postgres row-level locks to grant exclusive access to resources.
+
+## Usage
+
+You must first call `init` with Postgres connection details and an idle error handler:
+
+```ts
+import { init } from '@prairielearn/named-locks';
+
+await init(
+  {
+    user: 'postgres',
+    // ... other Postgres config
+  },
+  (err) => {
+    throw err;
+  }
+);
+```
+
+You can then obtain a lock and do work while it is held. The lock will be automatically released once the provided function either resolves or rejects.
+
+```ts
+import { doWithLock } from '@prairielearn/named-locks';
+
+await doWithLock('name', {}, async () => {
+  console.log('Doing some work');
+});
+```
+
+Optionally, you may configure the lock to automatically "renew" itself by periodically making no-op queries in the background. This is useful for operations that may take longer than the configured Postgres idle session timeout.
+
+```ts
+import { doWithLock } from '@prairielearn/named-locks';
+
+await doWithLock(
+  'name',
+  {
+    autoRenew: true,
+  },
+  async () => {
+    console.log('Doing some work');
+  }
+);
+```
+
+### Advanced usage
+
+Normally, it's preferable to use `doWithLock`, as it will automatically release the lock in case of failure. However, for advanced usage, you can manually acquire and release a lock.
+
+```ts
+import { waitLockAsync, releaseLockAsync } from '@prairielearn/named-locks';
+
+const lock = await waitLockAsync('name', {});
+try {
+  console.log('Doing some work');
+} finally {
+  await releaseLockAsync(lock);
+}
+```
+
+If you only want to acquire a lock if it's immediately available, you can use `tryLockAsync` instead:
+
+```ts
+import { tryLockAsync, releaseLockAsync } from '@prairielearn/named-locks';
+
+const lock = await waitLockAsync('name', {});
+if (lock) {
+  try {
+    console.log('Doing some work');
+  } finally {
+    await releaseLockAsync(lock);
+  }
+} else {
+  console.log('Lock not acquired');
+}
+```

package/dist/index.d.ts

@@ -1,18 +1,38 @@
 /// <reference types="node" />
+/// <reference types="node" />
 import { PostgresPool, PoolClient } from '@prairielearn/postgres';
 import { PoolConfig } from 'pg';
+interface NamedLocksConfig {
+    /**
+     * How often to renew the lock in milliseconds. Defaults to 60 seconds.
+     * Auto-renewal must be explicitly enabled on each lock where it is desired.
+     *
+     */
+    renewIntervalMs?: number;
+}
 interface Lock {
     client: PoolClient;
+    intervalId: NodeJS.Timeout | null;
 }
 interface LockOptions {
     /** How many milliseconds to wait (anything other than a positive number means forever) */
     timeout?: number;
+    /**
+     * Whether or not this lock should automatically renew itself periodically.
+     * By default, locks will not renew themselves.
+     *
+     * This is mostly useful for locks that may be help for longer than the idle
+     * session timeout that's configured for the Postgres database. The lock is
+     * "renewed" by making a no-op query.
+     */
+    autoRenew?: boolean;
 }
+type TryLockOptions = Omit<LockOptions, 'timeout'>;
 export declare const pool: PostgresPool;
 /**
  * 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>;
+export declare function init(pgConfig: PoolConfig, idleErrorHandler: (error: Error, client: PoolClient) => void, namedLocksConfig?: NamedLocksConfig): Promise<void>;
 /**
  * Shuts down the database connection pool that was used to acquire locks.
  */
@@ -25,7 +45,7 @@ export declare function close(): Promise<void>;
  *
  * @param name The name of the lock to acquire.
  */
-export declare function tryLockAsync(name: string): Promise<Lock | null>;
+export declare function tryLockAsync(name: string, options?: TryLockOptions): 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.
@@ -47,4 +67,10 @@ export declare const releaseLock: (arg1: Lock, callback: (err: NodeJS.ErrnoExcep
  * and releases the lock once the function has executed.
  */
 export declare function doWithLock<T>(name: string, options: LockOptions, func: () => Promise<T>): Promise<T>;
+/**
+ * Tries to acquire the given lock, executes the provided function with the lock held,
+ * and releases the lock once the function has executed. If the lock cannot be acquired,
+ * the function is not executed and null is returned.
+ */
+export declare function tryWithLock<T>(name: string, options: TryLockOptions, func: () => Promise<T>): Promise<T | null>;
 export {};

package/dist/index.js

@@ -3,7 +3,7 @@ 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 = exports.pool = void 0;
+exports.tryWithLock = exports.doWithLock = exports.releaseLock = exports.releaseLockAsync = exports.waitLock = exports.waitLockAsync = exports.tryLock = exports.tryLockAsync = exports.close = exports.init = exports.pool = void 0;
 const util_1 = __importDefault(require("util"));
 const postgres_1 = require("@prairielearn/postgres");
 /*
@@ -49,10 +49,12 @@ const postgres_1 = require("@prairielearn/postgres");
  * can lead to deadlocks.
  */
 exports.pool = new postgres_1.PostgresPool();
+let renewIntervalMs = 60000;
 /**
  * Initializes a new {@link PostgresPool} that will be used to acquire named locks.
  */
-async function init(pgConfig, idleErrorHandler) {
+async function init(pgConfig, idleErrorHandler, namedLocksConfig = {}) {
+    renewIntervalMs = namedLocksConfig.renewIntervalMs ?? renewIntervalMs;
     await exports.pool.initAsync(pgConfig, idleErrorHandler);
     await exports.pool.queryAsync('CREATE TABLE IF NOT EXISTS named_locks (id bigserial PRIMARY KEY, name text NOT NULL UNIQUE);', {});
 }
@@ -72,8 +74,8 @@ exports.close = close;
  *
  * @param name The name of the lock to acquire.
  */
-async function tryLockAsync(name) {
-    return getLock(name, { wait: false });
+async function tryLockAsync(name, options = {}) {
+    return getLock(name, { timeout: 0, ...options });
 }
 exports.tryLockAsync = tryLockAsync;
 exports.tryLock = util_1.default.callbackify(tryLockAsync);
@@ -84,11 +86,7 @@ exports.tryLock = util_1.default.callbackify(tryLockAsync);
  * @param options
  */
 async function waitLockAsync(name, options) {
-    const internalOptions = {
-        wait: true,
-        timeout: options.timeout || 0,
-    };
-    const lock = await getLock(name, internalOptions);
+    const lock = await getLock(name, options);
     if (lock == null)
         throw new Error(`failed to acquire lock: ${name}`);
     return lock;
@@ -103,6 +101,7 @@ exports.waitLock = util_1.default.callbackify(waitLockAsync);
 async function releaseLockAsync(lock) {
     if (lock == null)
         throw new Error('lock is null');
+    clearInterval(lock.intervalId ?? undefined);
     await exports.pool.endTransactionAsync(lock.client, null);
 }
 exports.releaseLockAsync = releaseLockAsync;
@@ -121,6 +120,23 @@ async function doWithLock(name, options, func) {
     }
 }
 exports.doWithLock = doWithLock;
+/**
+ * Tries to acquire the given lock, executes the provided function with the lock held,
+ * and releases the lock once the function has executed. If the lock cannot be acquired,
+ * the function is not executed and null is returned.
+ */
+async function tryWithLock(name, options, func) {
+    const lock = await tryLockAsync(name, options);
+    if (lock == null)
+        return null;
+    try {
+        return await func();
+    }
+    finally {
+        await releaseLockAsync(lock);
+    }
+}
+exports.tryWithLock = tryWithLock;
 /**
  * Internal helper function to get a lock with optional
  * waiting. Do not call directly, but use tryLock() or waitLock()
@@ -134,7 +150,7 @@ async function getLock(name, options) {
     const client = await exports.pool.beginTransactionAsync();
     let acquiredLock = false;
     try {
-        if (options.wait && options.timeout > 0) {
+        if (options.timeout) {
             // 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`.
@@ -146,7 +162,7 @@ async function getLock(name, options) {
         // safe if it shows up in plaintext in logs, telemetry, error messages,
         // etc.
         const lockNameLiteral = client.escapeLiteral(name);
-        const lock_sql = options.wait
+        const lock_sql = options.timeout
             ? `SELECT * FROM named_locks WHERE name = ${lockNameLiteral} FOR UPDATE;`
             : `SELECT * FROM named_locks WHERE name = ${lockNameLiteral} FOR UPDATE SKIP LOCKED;`;
         const result = await exports.pool.queryWithClientAsync(client, lock_sql, { name });
@@ -164,9 +180,16 @@ async function getLock(name, options) {
         await exports.pool.endTransactionAsync(client, null);
         return null;
     }
+    let intervalId = null;
+    if (options.autoRenew) {
+        // Periodically "renew" the lock by making a query.
+        intervalId = setInterval(() => {
+            client.query('SELECT 1;').catch(() => { });
+        }, renewIntervalMs);
+    }
     // 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 };
+    return { client, intervalId };
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -1,17 +1,22 @@
 {
   "name": "@prairielearn/named-locks",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "main": "./dist/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PrairieLearn/PrairieLearn.git",
+    "directory": "packages/named-locks"
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch --preserveWatchOutput"
   },
   "devDependencies": {
-    "@prairielearn/tsconfig": "*",
-    "@types/node": "^18.14.2",
+    "@prairielearn/tsconfig": "^0.0.0",
+    "@types/node": "^18.15.11",
     "typescript": "^4.9.4"
   },
   "dependencies": {
-    "@prairielearn/postgres": "^1.3.0"
+    "@prairielearn/postgres": "^1.6.0"
   }
 }

package/src/index.ts

@@ -2,23 +2,35 @@ import util from 'util';
 import { PostgresPool, PoolClient } from '@prairielearn/postgres';
 import { PoolConfig } from 'pg';
 
+interface NamedLocksConfig {
+  /**
+   * How often to renew the lock in milliseconds. Defaults to 60 seconds.
+   * Auto-renewal must be explicitly enabled on each lock where it is desired.
+   *
+   */
+  renewIntervalMs?: number;
+}
+
 interface Lock {
   client: PoolClient;
+  intervalId: NodeJS.Timeout | null;
 }
 
 interface LockOptions {
   /** How many milliseconds to wait (anything other than a positive number means forever) */
   timeout?: number;
+  /**
+   * Whether or not this lock should automatically renew itself periodically.
+   * By default, locks will not renew themselves.
+   *
+   * This is mostly useful for locks that may be help for longer than the idle
+   * session timeout that's configured for the Postgres database. The lock is
+   * "renewed" by making a no-op query.
+   */
+  autoRenew?: boolean;
 }
 
-type InternalLockOptions =
-  | {
-      wait: false;
-    }
-  | {
-      wait: true;
-      timeout: number;
-    };
+type TryLockOptions = Omit<LockOptions, 'timeout'>;
 
 /*
  * The functions here all identify locks by "name", which is a plain
@@ -64,14 +76,17 @@ type InternalLockOptions =
  */
 
 export const pool = new PostgresPool();
+let renewIntervalMs = 60_000;
 
 /**
  * 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
+  idleErrorHandler: (error: Error, client: PoolClient) => void,
+  namedLocksConfig: NamedLocksConfig = {}
 ) {
+  renewIntervalMs = namedLocksConfig.renewIntervalMs ?? renewIntervalMs;
   await pool.initAsync(pgConfig, idleErrorHandler);
   await pool.queryAsync(
     'CREATE TABLE IF NOT EXISTS named_locks (id bigserial PRIMARY KEY, name text NOT NULL UNIQUE);',
@@ -94,8 +109,11 @@ export async function close() {
  *
  * @param name The name of the lock to acquire.
  */
-export async function tryLockAsync(name: string): Promise<Lock | null> {
-  return getLock(name, { wait: false });
+export async function tryLockAsync(
+  name: string,
+  options: TryLockOptions = {}
+): Promise<Lock | null> {
+  return getLock(name, { timeout: 0, ...options });
 }
 
 export const tryLock = util.callbackify(tryLockAsync);
@@ -107,12 +125,7 @@ export const tryLock = util.callbackify(tryLockAsync);
  * @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);
+  const lock = await getLock(name, options);
   if (lock == null) throw new Error(`failed to acquire lock: ${name}`);
   return lock;
 }
@@ -126,6 +139,7 @@ export const waitLock = util.callbackify(waitLockAsync);
  */
 export async function releaseLockAsync(lock: Lock) {
   if (lock == null) throw new Error('lock is null');
+  clearInterval(lock.intervalId ?? undefined);
   await pool.endTransactionAsync(lock.client, null);
 }
 
@@ -148,6 +162,25 @@ export async function doWithLock<T>(
   }
 }
 
+/**
+ * Tries to acquire the given lock, executes the provided function with the lock held,
+ * and releases the lock once the function has executed. If the lock cannot be acquired,
+ * the function is not executed and null is returned.
+ */
+export async function tryWithLock<T>(
+  name: string,
+  options: TryLockOptions,
+  func: () => Promise<T>
+): Promise<T | null> {
+  const lock = await tryLockAsync(name, options);
+  if (lock == null) return null;
+  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()
@@ -156,7 +189,7 @@ export async function doWithLock<T>(
  * @param name The name of the lock to acquire.
  * @param options Optional parameters.
  */
-async function getLock(name: string, options: InternalLockOptions) {
+async function getLock(name: string, options: LockOptions) {
   await pool.queryAsync(
     'INSERT INTO named_locks (name) VALUES ($name) ON CONFLICT (name) DO NOTHING;',
     { name }
@@ -166,7 +199,7 @@ async function getLock(name: string, options: InternalLockOptions) {
 
   let acquiredLock = false;
   try {
-    if (options.wait && options.timeout > 0) {
+    if (options.timeout) {
       // 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`.
@@ -183,7 +216,7 @@ async function getLock(name: string, options: InternalLockOptions) {
     // safe if it shows up in plaintext in logs, telemetry, error messages,
     // etc.
     const lockNameLiteral = client.escapeLiteral(name);
-    const lock_sql = options.wait
+    const lock_sql = options.timeout
       ? `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 });
@@ -202,8 +235,16 @@ async function getLock(name: string, options: InternalLockOptions) {
     return null;
   }
 
+  let intervalId = null;
+  if (options.autoRenew) {
+    // Periodically "renew" the lock by making a query.
+    intervalId = setInterval(() => {
+      client.query('SELECT 1;').catch(() => {});
+    }, renewIntervalMs);
+  }
+
   // 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 };
+  return { client, intervalId };
 }