vouchington-tooling 0.61.1 → 0.63.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/README.md +80 -0
  2. package/dist/postgres-test-faults/fault-support.d.mts +11 -0
  3. package/dist/postgres-test-faults/fault-support.mjs +61 -0
  4. package/dist/postgres-test-faults/fault-types.d.mts +43 -0
  5. package/dist/postgres-test-faults/fault-types.mjs +1 -0
  6. package/dist/postgres-test-faults/index.d.mts +5 -0
  7. package/dist/postgres-test-faults/index.mjs +4 -0
  8. package/dist/postgres-test-faults/lock-observers.d.mts +20 -0
  9. package/dist/postgres-test-faults/lock-observers.mjs +14 -0
  10. package/dist/postgres-test-faults/lock-wait.d.mts +13 -0
  11. package/dist/postgres-test-faults/lock-wait.mjs +62 -0
  12. package/dist/postgres-test-faults/lock-waiter.d.mts +19 -0
  13. package/dist/postgres-test-faults/lock-waiter.mjs +95 -0
  14. package/dist/postgres-test-faults/observation-queue.d.mts +2 -0
  15. package/dist/postgres-test-faults/observation-queue.mjs +22 -0
  16. package/dist/postgres-test-faults/polling.d.mts +6 -0
  17. package/dist/postgres-test-faults/polling.mjs +33 -0
  18. package/dist/postgres-test-faults/pool-query-failure.d.mts +8 -0
  19. package/dist/postgres-test-faults/pool-query-failure.mjs +136 -0
  20. package/dist/postgres-test-faults/query-failure.d.mts +8 -0
  21. package/dist/postgres-test-faults/query-failure.mjs +108 -0
  22. package/dist/postgres-test-faults/test-cluster.test-helpers.d.mts +13 -0
  23. package/dist/postgres-test-faults/test-cluster.test-helpers.mjs +84 -0
  24. package/dist/provider-replay/abort-listeners.d.mts +4 -0
  25. package/dist/provider-replay/abort-listeners.mjs +19 -0
  26. package/dist/provider-replay/aws-replay-abort-signal.d.mts +5 -0
  27. package/dist/provider-replay/aws-replay-abort-signal.mjs +63 -0
  28. package/dist/provider-replay/aws-replay-request-handler.d.mts +38 -0
  29. package/dist/provider-replay/aws-replay-request-handler.mjs +66 -0
  30. package/dist/provider-replay/force-client-option.d.mts +6 -0
  31. package/dist/provider-replay/force-client-option.mjs +13 -0
  32. package/dist/provider-replay/index.d.mts +6 -0
  33. package/dist/provider-replay/index.mjs +6 -0
  34. package/dist/provider-replay/provider-replay.d.mts +32 -0
  35. package/dist/provider-replay/provider-replay.mjs +54 -0
  36. package/dist/provider-replay/recorded-response.d.mts +17 -0
  37. package/dist/provider-replay/recorded-response.mjs +42 -0
  38. package/dist/provider-replay/replay-response.d.mts +8 -0
  39. package/dist/provider-replay/replay-response.mjs +38 -0
  40. package/dist/runner-port-policy/index.d.mts +9 -0
  41. package/dist/runner-port-policy/index.mjs +32 -0
  42. package/dist/vitest-diagnostics/index.d.mts +8 -0
  43. package/dist/vitest-diagnostics/index.mjs +4 -0
  44. package/dist/vitest-diagnostics/vitest-ci-reporters.d.mts +40 -0
  45. package/dist/vitest-diagnostics/vitest-ci-reporters.mjs +70 -0
  46. package/dist/vitest-diagnostics/vitest-file-progress-reporter.d.mts +24 -0
  47. package/dist/vitest-diagnostics/vitest-file-progress-reporter.mjs +49 -0
  48. package/dist/vitest-diagnostics/vitest-github-actions-reporter.d.mts +13 -0
  49. package/dist/vitest-diagnostics/vitest-github-actions-reporter.mjs +35 -0
  50. package/dist/vitest-diagnostics/vitest-storybook-progress-reporter.d.mts +24 -0
  51. package/dist/vitest-diagnostics/vitest-storybook-progress-reporter.mjs +53 -0
  52. package/package.json +17 -1
  53. package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
package/README.md CHANGED
@@ -355,6 +355,7 @@ gone.
355
355
  ```ts
356
356
  import {
357
357
  isRunnerReservedPort,
358
+ listenOnLoopbackEphemeralPort,
358
359
  listenOnRunnerUnreservedEphemeralPort,
359
360
  runnerPortPolicy,
360
361
  } from 'vouchington-tooling/runner-port-policy'
@@ -384,6 +385,15 @@ import {
384
385
  import { createArtifactClassifier, runCleanup } from 'vouchington-tooling/gha-artifacts-cleanup'
385
386
  import { ensureLabels, labelsFromPaths } from 'vouchington-tooling/agent-issue-labels'
386
387
  import { validateOptionalHttpOrigin } from 'vouchington-tooling/http-origin'
388
+ // Replay recorded raw `.http` responses through an SDK `fetch` or AWS SDK v3 `requestHandler`:
389
+ // const replay = createProviderReplay({ chunkBytes: 3 })
390
+ // replay.respondWith(loadRecordedResponse('ok.http', { fixtureRoot: new URL('./fixtures/', import.meta.url) }))
391
+ // new Sdk({ fetch: replay.fetch }) or new AwsClient({ requestHandler: createAwsReplayRequestHandler(replay) })
392
+ import {
393
+ createAwsReplayRequestHandler,
394
+ createProviderReplay,
395
+ loadRecordedResponse,
396
+ } from 'vouchington-tooling/provider-replay'
387
397
  import { boundPendingLine, splitCompleteLines } from 'vouchington-tooling/process-line-buffer'
388
398
  import {
389
399
  isProcessGroupAlive,
@@ -667,6 +677,20 @@ feeds a handshake settlement's counts to a detector. `formatForkLeakDiagnostics`
667
677
  fourth argument, `{ poolMetricsLabel }`, to replace the default `pool metrics:` label (for example
668
678
  `'PostgreSQL pool metrics:'`).
669
679
 
680
+ `ciReporters(options?)` builds the Vitest `reporters` list from env vars, and `ciOutputFile(options?)`
681
+ builds `outputFile`. Unset or empty `VITEST_CI_REPORTERS` returns `undefined` (or `default` plus file
682
+ progress when `VITEST_DIAGNOSTICS=1`); `run` returns `minimal`, the optional Storybook progress
683
+ reporter (`VITEST_STORYBOOK_BROWSER=1`), `github-actions`, `junit`, `extraReporters`,
684
+ `hanging-process`, and file progress (stdout with `VITEST_DIAGNOSTICS=1`, appended to
685
+ `VITEST_FILE_PROGRESS_FILE` when set). Options: `env`, `envNames` (rename any variable; see
686
+ `DEFAULT_CI_REPORTER_ENV_NAMES`), `fileProgressPrefix`, `storybookProgressPrefix`, `extraReporters`
687
+ (for example a no-skips or teardown-overrun reporter), and `cwd`. The progress reporters print
688
+ `<prefix> event=start|finish module="..."` and `<prefix> seq=N event=module-*` lines; the defaults
689
+ are `[vitest-file]` and `[vitest-browser-progress]`, exported as `DEFAULT_FILE_PROGRESS_PREFIX` and
690
+ `DEFAULT_STORYBOOK_PROGRESS_PREFIX`. Pass the same prefix to `formatFileProgress`,
691
+ `formatStorybookProgressMarker`, and `latestStorybookProgressSequence(text, prefix)` when parsing.
692
+ These stay in the Node entry, never the browser entry.
693
+
670
694
  `vouchington-tooling/vitest-diagnostics/browser` is the browser-safe entry for Storybook and Vitest
671
695
  browser projects, for example a root fake-timer setup file shared with a Node project. It exports
672
696
  only `checkAndRestoreFakeTimers`, `formatFakeTimerLeakDiagnostics`, and the `FakeTimerController`
@@ -740,6 +764,12 @@ the dedicated process group to exit after the direct child closes so descendants
740
764
  `isProcessGroupAlive` and `waitForProcessGroupExit` are also available when callers need the same
741
765
  process-group probe and bounded-drain semantics outside a browser session.
742
766
 
767
+ `listenOnLoopbackEphemeralPort(server, options?)` from `runner-port-policy` binds an ephemeral port
768
+ outside the reserved runner range on IPv6 loopback (`::1`) and falls back to `127.0.0.1` only when the
769
+ host reports `EAFNOSUPPORT` (for example a kernel booted with `ipv6.disable=1`). Any other bind error is
770
+ rethrown. It resolves `{ host, port }` and accepts the same `EphemeralListenerOptions` (`isAllowedPort`,
771
+ `listen`, `maxBindAttempts`, `policy`) as `listenOnRunnerUnreservedEphemeralPort`, whose bind-retry loop it reuses.
772
+
743
773
  ### Generated arbiter input
744
774
 
745
775
  The `pg-schema-snapshot` export also provides `projectGeneratedArbiterInput(conflict)` for
@@ -1054,3 +1084,53 @@ from `TMUX_TARGET_BIN`, the worktree from `TMUX_TARGET_ROOT` (default: current d
1054
1084
  touching it. `tmux post-tool` reads an agent post-tool hook payload on stdin and prints a rename
1055
1085
  reminder at plan, PR, push and reset checkpoints; reminders name `TMUX_NAME_COMMAND` (default
1056
1086
  `vouchington tmux name`).
1087
+
1088
+ ## PostgreSQL test faults and lock waits
1089
+
1090
+ `vouchington-tooling/postgres-test-faults` injects real PostgreSQL failures and observes real lock
1091
+ waits for any `pg.Pool` application. It needs the optional peer `pg` (>=8) and `@types/pg`; no
1092
+ product code is imported, so pools and request ownership are passed in.
1093
+
1094
+ ```ts
1095
+ import {
1096
+ createPostgresLockObservers,
1097
+ withPostgresPoolQueryFailureForTest,
1098
+ withPostgresQueryFailureForTest,
1099
+ } from 'vouchington-tooling/postgres-test-faults'
1100
+
1101
+ const { result, error } = await withPostgresQueryFailureForTest(
1102
+ '/* orders:insert */', // exact leading block comment that marks the statement to fail
1103
+ () => placeOrder().catch((err: unknown) => err), // absorb the injected error
1104
+ { pools: [readPool, writePool], command: 'INSERT' },
1105
+ )
1106
+ // error.code === '25P02': PostgreSQL rejected the marked statement on an aborted transaction.
1107
+ ```
1108
+
1109
+ - `withPostgresQueryFailureForTest(marker, operation, options)` fails one marked statement on a
1110
+ client leased from `options.pools` with the promise form of `pool.connect()` (the callback
1111
+ overload is not instrumented), inside a transaction the operation began with `BEGIN`. A
1112
+ division by zero aborts that transaction, so PostgreSQL itself answers `25P02`.
1113
+ - `withPostgresPoolQueryFailureForTest(marker, operation, options)` does the same for a marked
1114
+ `pool.query({ text })` call: it leases a real client, aborts its transaction, and hands the client
1115
+ to the unchanged `pg.Pool#query` core.
1116
+ - Both resolve to `{ result, error }` only when the operation absorbs the injected `25P02` (catch
1117
+ or translate it, and return the outcome as `result`). If the operation lets the error
1118
+ propagate, the helper rejects with that error; it also rejects when the marked SQL never ran.
1119
+ Observers give up after `timeoutMs` even when a query never settles; `signal` is checked between
1120
+ steps, not inside a pending query. `options` is
1121
+ `{ pools, command?, requestId?, isOwnedRequest?, endTimeoutMs? }`. A statement is owned by the
1122
+ operation's async context, or by `requestId` when `isOwnedRequest(requestId)` returns true
1123
+ (use it for work that runs outside that context, such as a request handler). Scopes are
1124
+ serialized and cannot be nested.
1125
+ - `createPostgresLockObservers({ write, advisoryLockPool?, timeoutMs?, intervalMs? })` binds the
1126
+ observers to your executors (any `({ text, values }) => Promise<{ rows }>`, for example
1127
+ `query => pool.query(query)`), with defaults of 5000 ms and 10 ms. It returns
1128
+ `getTestPostgresBackendProcessId(executor)`, `getTestPostgresAdvisoryLockHolderProcessId({ key,
1129
+ mode?, namespace? })`, `waitForTestPostgresLockWaiter(holderPid, marker, observer?, onDiagnostic?,
1130
+ signal?, waiterPid?)` and `waitForTestPostgresBlockedLockChain(holderPid, directMarker,
1131
+ blockedMarkers, observer?)`. The waiters poll `pg_stat_activity` and `pg_blocking_pids`; the
1132
+ observer is `'write'`, `'advisoryLock'` or a reserved executor.
1133
+
1134
+ The package's own tests start a throwaway cluster with `initdb`/`pg_ctl` found through
1135
+ `POSTGRES_BIN_DIR`, `PATH` or a standard install location. They skip where no server can run and
1136
+ fail under `CI`.
@@ -0,0 +1,11 @@
1
+ import type { PostgresFaultOptions } from './fault-types.mts';
2
+ export declare function assertFaultOptions(queryMarker: string, options: PostgresFaultOptions): void;
3
+ export declare function queryText(input: unknown): string;
4
+ /** True when `text` starts with the marker and, if given, the command that follows it. */
5
+ export declare function targetsStatement(text: string, queryMarker: string, command?: string): boolean;
6
+ /** The faulted call must be the adapter's plain `{ text }` config, never a callback or submittable. */
7
+ export declare function isPlainTextConfig(args: unknown[]): boolean;
8
+ export declare function ownsRequest(options: PostgresFaultOptions): boolean;
9
+ export declare function installProperty(object: object, key: string, value: unknown): void;
10
+ export declare function restoreProperty(object: object, key: string, descriptor: PropertyDescriptor | undefined): void;
11
+ export declare function hasErrorCode(err: unknown, code: string): err is Error;
@@ -0,0 +1,61 @@
1
+ // A marker is exactly one leading SQL block comment that holds a name.
2
+ const MARKER_PATTERN = /^\/\* [^*]+ \*\/$/;
3
+ export function assertFaultOptions(queryMarker, options) {
4
+ if (!MARKER_PATTERN.test(queryMarker))
5
+ throw new Error('PostgreSQL fault injection requires an exact leading query annotation');
6
+ if (options.pools.length === 0)
7
+ throw new Error('PostgreSQL fault injection requires at least one pool');
8
+ if (options.endTimeoutMs !== undefined &&
9
+ !(Number.isInteger(options.endTimeoutMs) && options.endTimeoutMs >= 0))
10
+ throw new Error('endTimeoutMs must be a non-negative integer');
11
+ if (options.requestId === undefined)
12
+ return;
13
+ if (options.requestId === '' || options.isOwnedRequest === undefined)
14
+ throw new Error('Request-scoped PostgreSQL faults require a request id and isOwnedRequest');
15
+ }
16
+ export function queryText(input) {
17
+ return typeof input === 'string'
18
+ ? input
19
+ : typeof input === 'object' && input !== null && 'text' in input
20
+ ? String(input.text)
21
+ : '';
22
+ }
23
+ /** True when `text` starts with the marker and, if given, the command that follows it. */
24
+ export function targetsStatement(text, queryMarker, command) {
25
+ const target = text.trimStart();
26
+ if (!target.startsWith(queryMarker))
27
+ return false;
28
+ return !command || target.slice(queryMarker.length).trimStart().toUpperCase().startsWith(command);
29
+ }
30
+ /** The faulted call must be the adapter's plain `{ text }` config, never a callback or submittable. */
31
+ export function isPlainTextConfig(args) {
32
+ const input = args[0];
33
+ return (args.length === 1 &&
34
+ typeof input === 'object' &&
35
+ input !== null &&
36
+ 'text' in input &&
37
+ typeof input.text === 'string' &&
38
+ !('callback' in input) &&
39
+ !('submit' in input) &&
40
+ Object.getPrototypeOf(input) === Object.prototype);
41
+ }
42
+ export function ownsRequest(options) {
43
+ return options.requestId !== undefined && options.isOwnedRequest?.(options.requestId) === true;
44
+ }
45
+ export function installProperty(object, key, value) {
46
+ Object.defineProperty(object, key, {
47
+ configurable: true,
48
+ enumerable: true,
49
+ writable: true,
50
+ value,
51
+ });
52
+ }
53
+ export function restoreProperty(object, key, descriptor) {
54
+ if (descriptor)
55
+ Object.defineProperty(object, key, descriptor);
56
+ else
57
+ Reflect.deleteProperty(object, key);
58
+ }
59
+ export function hasErrorCode(err, code) {
60
+ return err instanceof Error && 'code' in err && err.code === code;
61
+ }
@@ -0,0 +1,43 @@
1
+ import type pg from 'pg';
2
+ /** Minimal structural query executor: a `pg.Pool#query`, a pool client, or a wrapper around one. */
3
+ export type QueryExecutor = <Row extends object = Record<string, unknown>>(query: {
4
+ text: string;
5
+ values?: unknown[];
6
+ }) => Promise<{
7
+ rows: Row[];
8
+ }>;
9
+ /** Statement kinds a fault can target after the leading marker annotation. */
10
+ export type FaultCommand = 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE';
11
+ export type PostgresFaultOptions = {
12
+ /** Pools whose connections are instrumented while the operation runs. */
13
+ pools: readonly pg.Pool[];
14
+ /** Only fail a statement whose SQL, after the marker, starts with this command. */
15
+ command?: FaultCommand;
16
+ /** Own faults raised outside the async context of the operation, for example in a request handler. */
17
+ requestId?: string;
18
+ /** Decides whether the current execution context belongs to `requestId`. Required with `requestId`. */
19
+ isOwnedRequest?: (requestId: string) => boolean;
20
+ /** Milliseconds to wait for a failed pool client to finish closing. Defaults to 5000. */
21
+ endTimeoutMs?: number;
22
+ };
23
+ export type PostgresFaultResult<Result> = {
24
+ result: Result;
25
+ error: Error;
26
+ };
27
+ export type PollOptions = {
28
+ /** Milliseconds before an observer gives up. Defaults to 5000. */
29
+ timeoutMs?: number;
30
+ /** Milliseconds between observations. Defaults to 10. */
31
+ intervalMs?: number;
32
+ };
33
+ export type ObserverPool = 'write' | 'advisoryLock' | QueryExecutor;
34
+ export type LockObserverConfig = PollOptions & {
35
+ /** Executor for the default `'write'` observer and for advisory-lock holder lookups. */
36
+ write: QueryExecutor;
37
+ /** Executor for the `'advisoryLock'` observer, usually a pool reserved for observation. */
38
+ advisoryLockPool?: QueryExecutor;
39
+ };
40
+ export type LockWaiterDiagnostic = {
41
+ phase: 'snapshot-clear-start' | 'snapshot-cleared' | 'waiter-query-start' | 'waiter-query';
42
+ waiting: boolean;
43
+ };
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,5 @@
1
+ export { withPostgresPoolQueryFailureForTest } from './pool-query-failure.mts';
2
+ export { withPostgresQueryFailureForTest } from './query-failure.mts';
3
+ export { createPostgresLockObservers, type PostgresLockObservers } from './lock-observers.mts';
4
+ export { getTestPostgresBackendProcessId } from './lock-wait.mts';
5
+ export type { FaultCommand, LockObserverConfig, LockWaiterDiagnostic, ObserverPool, PollOptions, PostgresFaultOptions, PostgresFaultResult, QueryExecutor, } from './fault-types.mts';
@@ -0,0 +1,4 @@
1
+ export { withPostgresPoolQueryFailureForTest } from "./pool-query-failure.mjs";
2
+ export { withPostgresQueryFailureForTest } from "./query-failure.mjs";
3
+ export { createPostgresLockObservers } from "./lock-observers.mjs";
4
+ export { getTestPostgresBackendProcessId } from "./lock-wait.mjs";
@@ -0,0 +1,20 @@
1
+ import type { LockObserverConfig, QueryExecutor } from './fault-types.mts';
2
+ import { waitForBlockedLockChain, waitForLockWaiter } from './lock-waiter.mts';
3
+ type ConfiguredWaiter = (...args: Parameters<typeof waitForLockWaiter> extends [unknown, ...infer Rest] ? Rest : never) => Promise<void>;
4
+ type ConfiguredChain = (...args: Parameters<typeof waitForBlockedLockChain> extends [unknown, ...infer Rest] ? Rest : never) => Promise<void>;
5
+ export type PostgresLockObservers = {
6
+ getTestPostgresBackendProcessId: (query: QueryExecutor) => Promise<number>;
7
+ getTestPostgresAdvisoryLockHolderProcessId: (input: {
8
+ key: string;
9
+ mode?: 'exclusive' | 'shared';
10
+ namespace?: number;
11
+ }) => Promise<number>;
12
+ waitForTestPostgresLockWaiter: ConfiguredWaiter;
13
+ waitForTestPostgresBlockedLockChain: ConfiguredChain;
14
+ };
15
+ /**
16
+ * Binds the lock-wait observers to the executors and timings of one application. Call once in a
17
+ * test setup module and re-export the functions.
18
+ */
19
+ export declare function createPostgresLockObservers(config: LockObserverConfig): PostgresLockObservers;
20
+ export {};
@@ -0,0 +1,14 @@
1
+ import { getAdvisoryLockHolderProcessId, getTestPostgresBackendProcessId } from "./lock-wait.mjs";
2
+ import { waitForBlockedLockChain, waitForLockWaiter } from "./lock-waiter.mjs";
3
+ /**
4
+ * Binds the lock-wait observers to the executors and timings of one application. Call once in a
5
+ * test setup module and re-export the functions.
6
+ */
7
+ export function createPostgresLockObservers(config) {
8
+ return {
9
+ getTestPostgresBackendProcessId,
10
+ getTestPostgresAdvisoryLockHolderProcessId: (input) => getAdvisoryLockHolderProcessId(config, input),
11
+ waitForTestPostgresLockWaiter: (...args) => waitForLockWaiter(config, ...args),
12
+ waitForTestPostgresBlockedLockChain: (...args) => waitForBlockedLockChain(config, ...args),
13
+ };
14
+ }
@@ -0,0 +1,13 @@
1
+ import type { LockObserverConfig, ObserverPool, QueryExecutor } from './fault-types.mts';
2
+ /** Returns the PostgreSQL backend PID serving `query`'s current connection. */
3
+ export declare function getTestPostgresBackendProcessId(query: QueryExecutor): Promise<number>;
4
+ /** Runs `text` on the executor chosen by `observerPool`. */
5
+ export declare function runObservation<Row extends object>(config: LockObserverConfig, observerPool: ObserverPool, text: string, values: unknown[]): Promise<{
6
+ rows: Row[];
7
+ }>;
8
+ /** Returns the backend PID holding an exact session advisory lock owned by this test. */
9
+ export declare function getAdvisoryLockHolderProcessId(config: LockObserverConfig, input: {
10
+ key: string;
11
+ mode?: 'exclusive' | 'shared';
12
+ namespace?: number;
13
+ }): Promise<number>;
@@ -0,0 +1,62 @@
1
+ /** Returns the PostgreSQL backend PID serving `query`'s current connection. */
2
+ export async function getTestPostgresBackendProcessId(query) {
3
+ const { rows } = await query({
4
+ text: `
5
+ /* getTestPostgresBackendProcessId */
6
+ SELECT pg_backend_pid()::integer AS process_id
7
+ `,
8
+ });
9
+ const processId = rows[0]?.process_id;
10
+ if (processId === undefined)
11
+ throw new Error('PostgreSQL did not return a backend process ID');
12
+ return processId;
13
+ }
14
+ /** Runs `text` on the executor chosen by `observerPool`. */
15
+ export function runObservation(config, observerPool, text, values) {
16
+ if (typeof observerPool === 'function')
17
+ return observerPool({ text, values });
18
+ if (observerPool === 'write')
19
+ return config.write({ text, values });
20
+ if (!config.advisoryLockPool)
21
+ throw new Error("The 'advisoryLock' observer requires an advisoryLockPool executor");
22
+ return config.advisoryLockPool({ text, values });
23
+ }
24
+ /** Returns the backend PID holding an exact session advisory lock owned by this test. */
25
+ export async function getAdvisoryLockHolderProcessId(config, input) {
26
+ const lockMode = input.mode === 'shared' ? 'ShareLock' : 'ExclusiveLock';
27
+ const result = input.namespace === undefined
28
+ ? await config.write({
29
+ text: `
30
+ /* getTestPostgresAdvisoryLockHolderProcessId:oneInt */
31
+ SELECT pid::integer AS process_id
32
+ FROM pg_locks
33
+ WHERE locktype = 'advisory'
34
+ AND database = (SELECT oid FROM pg_database WHERE datname = current_database())
35
+ AND mode = $1
36
+ AND granted
37
+ AND objsubid = 1
38
+ AND classid::bigint = ((hashtextextended($2::text, 0) >> 32) & 4294967295)
39
+ AND objid::bigint = (hashtextextended($2::text, 0) & 4294967295)
40
+ `,
41
+ values: [lockMode, input.key],
42
+ })
43
+ : await config.write({
44
+ text: `
45
+ /* getTestPostgresAdvisoryLockHolderProcessId:twoInt */
46
+ SELECT pid::integer AS process_id
47
+ FROM pg_locks
48
+ WHERE locktype = 'advisory'
49
+ AND database = (SELECT oid FROM pg_database WHERE datname = current_database())
50
+ AND mode = $1
51
+ AND granted
52
+ AND objsubid = 2
53
+ AND classid = $2::integer::oid
54
+ AND objid = hashtext($3::text)::oid
55
+ `,
56
+ values: [lockMode, input.namespace, input.key],
57
+ });
58
+ const processId = result.rows[0]?.process_id;
59
+ if (processId === undefined)
60
+ throw new Error('PostgreSQL did not report the test advisory-lock holder');
61
+ return processId;
62
+ }
@@ -0,0 +1,19 @@
1
+ import type { LockObserverConfig, LockWaiterDiagnostic, ObserverPool } from './fault-types.mts';
2
+ /**
3
+ * Waits until a query bearing `queryMarker` is blocked by this test's lock-holding backend.
4
+ * Use a dedicated advisory executor when the held lock and blocked operations can occupy every
5
+ * write connection; the observer must run before the holder is released. Passing a previously
6
+ * acquired transaction executor reserves the observer connection before the holder or blocked
7
+ * operation starts, and its transaction-local activity snapshot is discarded before each
8
+ * observation. Supply `waiterProcessId` to distinguish this operation from other matching waiters.
9
+ */
10
+ export declare function waitForLockWaiter(config: LockObserverConfig, holderProcessId: number, queryMarker: string, observerPool?: ObserverPool, onDiagnostic?: (diagnostic: LockWaiterDiagnostic) => void, signal?: AbortSignal, waiterProcessId?: number): Promise<void>;
11
+ /**
12
+ * Waits until one backend is blocked by `holderProcessId` on `directQueryMarker` and a second
13
+ * backend is blocked by that first backend on one of `blockedByDirectQueryMarkers`.
14
+ *
15
+ * Use this when the second operation cannot reach the holder's lock because the first operation
16
+ * already holds a conflicting row lock. `pg_blocking_pids` reports only the direct blocker, so
17
+ * the second wait is the transitive link.
18
+ */
19
+ export declare function waitForBlockedLockChain(config: LockObserverConfig, holderProcessId: number, directQueryMarker: string, blockedByDirectQueryMarkers: readonly string[], observerPool?: ObserverPool): Promise<void>;
@@ -0,0 +1,95 @@
1
+ import { runObservation } from "./lock-wait.mjs";
2
+ import { pollUntilNotNull } from "./polling.mjs";
3
+ /** A LIKE pattern matching `text` literally anywhere, so `%`, `_` and `\` in markers are not wildcards. */
4
+ function likeContains(text) {
5
+ return `%${text.replace(/[\\%_]/g, '\\$&')}%`;
6
+ }
7
+ const CLEAR_SNAPSHOT = 'SELECT pg_stat_clear_snapshot()';
8
+ const WAITER_SQL = `
9
+ /* waitForTestPostgresLockWaiter */
10
+ SELECT EXISTS (
11
+ SELECT 1
12
+ FROM pg_stat_activity activity
13
+ WHERE activity.pid <> pg_backend_pid()
14
+ AND ($1::integer IS NULL OR activity.pid = $1::integer)
15
+ AND activity.state = 'active'
16
+ AND activity.wait_event_type = 'Lock'
17
+ AND activity.query LIKE $2::text
18
+ AND $3::integer = ANY(pg_blocking_pids(activity.pid))
19
+ ) AS waiting
20
+ `;
21
+ const CHAIN_SQL = `
22
+ /* waitForTestPostgresBlockedLockChain */
23
+ SELECT EXISTS (
24
+ SELECT 1
25
+ FROM pg_stat_activity direct_waiter
26
+ JOIN pg_stat_activity indirect_waiter
27
+ ON direct_waiter.pid = ANY(pg_blocking_pids(indirect_waiter.pid))
28
+ WHERE direct_waiter.pid <> pg_backend_pid()
29
+ AND indirect_waiter.pid <> pg_backend_pid()
30
+ AND direct_waiter.state = 'active'
31
+ AND indirect_waiter.state = 'active'
32
+ AND direct_waiter.wait_event_type = 'Lock'
33
+ AND indirect_waiter.wait_event_type = 'Lock'
34
+ AND direct_waiter.query LIKE $1::text
35
+ AND $2::integer = ANY(pg_blocking_pids(direct_waiter.pid))
36
+ AND indirect_waiter.query LIKE ANY($3::text[])
37
+ ) AS waiting
38
+ `;
39
+ /**
40
+ * Waits until a query bearing `queryMarker` is blocked by this test's lock-holding backend.
41
+ * Use a dedicated advisory executor when the held lock and blocked operations can occupy every
42
+ * write connection; the observer must run before the holder is released. Passing a previously
43
+ * acquired transaction executor reserves the observer connection before the holder or blocked
44
+ * operation starts, and its transaction-local activity snapshot is discarded before each
45
+ * observation. Supply `waiterProcessId` to distinguish this operation from other matching waiters.
46
+ */
47
+ export async function waitForLockWaiter(config, holderProcessId, queryMarker, observerPool = 'write', onDiagnostic, signal, waiterProcessId) {
48
+ await pollUntilNotNull(async () => {
49
+ signal?.throwIfAborted();
50
+ if (typeof observerPool === 'function') {
51
+ onDiagnostic?.({ phase: 'snapshot-clear-start', waiting: false });
52
+ signal?.throwIfAborted();
53
+ await observerPool({
54
+ text: `/* waitForTestPostgresLockWaiter.refresh */ ${CLEAR_SNAPSHOT}`,
55
+ });
56
+ signal?.throwIfAborted();
57
+ onDiagnostic?.({ phase: 'snapshot-cleared', waiting: false });
58
+ }
59
+ onDiagnostic?.({ phase: 'waiter-query-start', waiting: false });
60
+ signal?.throwIfAborted();
61
+ const { rows } = await runObservation(config, observerPool, WAITER_SQL, [waiterProcessId ?? null, likeContains(queryMarker), holderProcessId]);
62
+ signal?.throwIfAborted();
63
+ onDiagnostic?.({ phase: 'waiter-query', waiting: rows[0]?.waiting ?? false });
64
+ return rows[0]?.waiting ? true : null;
65
+ }, config.timeoutMs ?? 5_000, config.intervalMs ?? 10).catch((err) => {
66
+ const cause = signal?.aborted && err !== signal.reason
67
+ ? new SuppressedError(err, signal.reason, 'Lock observation failed during cancellation')
68
+ : err;
69
+ throw new Error(`Operation did not wait for the test lock: ${queryMarker}`, { cause });
70
+ });
71
+ }
72
+ /**
73
+ * Waits until one backend is blocked by `holderProcessId` on `directQueryMarker` and a second
74
+ * backend is blocked by that first backend on one of `blockedByDirectQueryMarkers`.
75
+ *
76
+ * Use this when the second operation cannot reach the holder's lock because the first operation
77
+ * already holds a conflicting row lock. `pg_blocking_pids` reports only the direct blocker, so
78
+ * the second wait is the transitive link.
79
+ */
80
+ export async function waitForBlockedLockChain(config, holderProcessId, directQueryMarker, blockedByDirectQueryMarkers, observerPool = 'advisoryLock') {
81
+ await pollUntilNotNull(async () => {
82
+ if (typeof observerPool === 'function')
83
+ await observerPool({
84
+ text: `/* waitForTestPostgresBlockedLockChain.refresh */ ${CLEAR_SNAPSHOT}`,
85
+ });
86
+ const { rows } = await runObservation(config, observerPool, CHAIN_SQL, [
87
+ likeContains(directQueryMarker),
88
+ holderProcessId,
89
+ blockedByDirectQueryMarkers.map(likeContains),
90
+ ]);
91
+ return rows[0]?.waiting ? true : null;
92
+ }, config.timeoutMs ?? 5_000, config.intervalMs ?? 10).catch((err) => {
93
+ throw new Error(`Operations did not form a lock chain behind the test holder: ${directQueryMarker}`, { cause: err });
94
+ });
95
+ }
@@ -0,0 +1,2 @@
1
+ /** Serializes pool instrumentation so two fault scopes never wrap the same pool at once. */
2
+ export declare function runPoolObservationExclusively<Result>(operation: () => Promise<Result>): Promise<Result>;
@@ -0,0 +1,22 @@
1
+ import { AsyncLocalStorage } from 'node:async_hooks';
2
+ const observationScope = new AsyncLocalStorage();
3
+ const poolObservationQueue = { tail: Promise.resolve() };
4
+ /** Serializes pool instrumentation so two fault scopes never wrap the same pool at once. */
5
+ export async function runPoolObservationExclusively(operation) {
6
+ if (observationScope.getStore()?.active)
7
+ throw new Error('PostgreSQL pool instrumentation cannot be nested');
8
+ const previousObservation = poolObservationQueue.tail;
9
+ let releaseObservation;
10
+ poolObservationQueue.tail = new Promise((resolve) => {
11
+ releaseObservation = resolve;
12
+ });
13
+ await previousObservation;
14
+ const context = { active: true };
15
+ try {
16
+ return await observationScope.run(context, operation);
17
+ }
18
+ finally {
19
+ context.active = false;
20
+ releaseObservation();
21
+ }
22
+ }
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Polls `fn` until it returns a non-null value, then returns it. Throws once `maxMs` elapses, even
3
+ * when a reading never settles, so a value that never appears fails at the wait instead of letting
4
+ * a later assertion pass vacuously.
5
+ */
6
+ export declare function pollUntilNotNull<T>(fn: () => Promise<T | null | undefined>, maxMs?: number, intervalMs?: number, description?: string): Promise<T>;
@@ -0,0 +1,33 @@
1
+ /** How long the final reading after the deadline may take before the wait gives up. */
2
+ const FINAL_READING_GRACE_MS = 250;
3
+ async function within(reading, ms, timeoutError) {
4
+ let timer;
5
+ const timeout = new Promise((_, reject) => {
6
+ timer = setTimeout(() => reject(timeoutError), ms);
7
+ });
8
+ try {
9
+ return await Promise.race([reading, timeout]);
10
+ }
11
+ finally {
12
+ clearTimeout(timer);
13
+ }
14
+ }
15
+ /**
16
+ * Polls `fn` until it returns a non-null value, then returns it. Throws once `maxMs` elapses, even
17
+ * when a reading never settles, so a value that never appears fails at the wait instead of letting
18
+ * a later assertion pass vacuously.
19
+ */
20
+ export async function pollUntilNotNull(fn, maxMs = 2000, intervalMs = 25, description = 'a non-null value') {
21
+ const timeoutError = new Error(`Timed out waiting for ${description} (after ${maxMs}ms)`);
22
+ const deadline = Date.now() + maxMs;
23
+ while (Date.now() < deadline) {
24
+ const result = await within(fn(), Math.max(deadline - Date.now(), 1), timeoutError);
25
+ if (result != null)
26
+ return result;
27
+ await new Promise((resolve) => setTimeout(resolve, intervalMs));
28
+ }
29
+ const last = await within(fn(), FINAL_READING_GRACE_MS, timeoutError);
30
+ if (last != null)
31
+ return last;
32
+ throw timeoutError;
33
+ }
@@ -0,0 +1,8 @@
1
+ import type { PostgresFaultOptions, PostgresFaultResult } from './fault-types.mts';
2
+ /**
3
+ * Lets the unchanged `pg.Pool#query` core execute its original SQL on an actual aborted client.
4
+ * The statement whose text starts with `queryMarker` (for example a leading block comment naming
5
+ * the statement) is run after a real division by zero aborts the leased transaction, so
6
+ * PostgreSQL answers it with `25P02`.
7
+ */
8
+ export declare function withPostgresPoolQueryFailureForTest<Result>(queryMarker: string, operation: () => Promise<Result>, options: PostgresFaultOptions): Promise<PostgresFaultResult<Result>>;