@prairielearn/named-locks 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# @prairielearn/named-locks
+
+## 1.2.0
+
+### Minor Changes
+
+- 400a0b901: Allow locks to be automatically renewed
+
+## 1.1.0
+
+### Minor Changes
+
+- 5ae096ba7: Export underlying Postgres client pool as `pool`
+
+### Patch Changes
+
+- Updated dependencies [5ae096ba7]
+  - @prairielearn/postgres@1.3.0

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,17 +1,37 @@
 /// <reference types="node" />
-import { PoolClient } from '@prairielearn/postgres';
+/// <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;
 }
+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.
  */

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 = void 0;
+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");
 /*
@@ -48,20 +48,22 @@ const postgres_1 = require("@prairielearn/postgres");
  * lock already held. Since there are a finite pool of locks available, this
  * can lead to deadlocks.
  */
-const pool = new postgres_1.PostgresPool();
+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) {
-    await pool.initAsync(pgConfig, idleErrorHandler);
-    await pool.queryAsync('CREATE TABLE IF NOT EXISTS named_locks (id bigserial PRIMARY KEY, name text NOT NULL UNIQUE);', {});
+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);', {});
 }
 exports.init = init;
 /**
  * Shuts down the database connection pool that was used to acquire locks.
  */
 async function close() {
-    await pool.closeAsync();
+    await exports.pool.closeAsync();
 }
 exports.close = close;
 /**
@@ -73,7 +75,7 @@ exports.close = close;
  * @param name The name of the lock to acquire.
  */
 async function tryLockAsync(name) {
-    return getLock(name, { wait: false });
+    return getLock(name, { timeout: 0 });
 }
 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,7 +101,8 @@ exports.waitLock = util_1.default.callbackify(waitLockAsync);
 async function releaseLockAsync(lock) {
     if (lock == null)
         throw new Error('lock is null');
-    await pool.endTransactionAsync(lock.client, null);
+    clearInterval(lock.intervalId ?? undefined);
+    await exports.pool.endTransactionAsync(lock.client, null);
 }
 exports.releaseLockAsync = releaseLockAsync;
 exports.releaseLock = util_1.default.callbackify(releaseLockAsync);
@@ -130,15 +129,15 @@ exports.doWithLock = doWithLock;
  * @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();
+    await exports.pool.queryAsync('INSERT INTO named_locks (name) VALUES ($name) ON CONFLICT (name) DO NOTHING;', { name });
+    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`.
-            await pool.queryWithClientAsync(client, `SET LOCAL lock_timeout = ${client.escapeLiteral(options.timeout.toString())}`, {});
+            await exports.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
@@ -146,27 +145,34 @@ 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 pool.queryWithClientAsync(client, lock_sql, { name });
+        const result = await exports.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);
+        await exports.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);
+        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.0.0",
+  "version": "1.2.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",
+    "@types/node": "^18.15.11",
     "typescript": "^4.9.4"
   },
   "dependencies": {
-    "@prairielearn/postgres": "^1.2.0"
+    "@prairielearn/postgres": "^1.3.0"
   }
 }

package/src/index.ts

@@ -2,24 +2,34 @@ 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;
-    };
-
 /*
  * The functions here all identify locks by "name", which is a plain
  * string. The locks use the named_locks DB table. Each lock name
@@ -63,15 +73,18 @@ type InternalLockOptions =
  * can lead to deadlocks.
  */
 
-const pool = new PostgresPool();
+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);',
@@ -95,7 +108,7 @@ 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 });
+  return getLock(name, { timeout: 0 });
 }
 
 export const tryLock = util.callbackify(tryLockAsync);
@@ -107,12 +120,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 +134,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);
 }
 
@@ -156,7 +165,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 +175,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 +192,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 +211,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 };
 }