@shivaedev/effect-pg-boss 0.13.0 → 0.15.0

package/src/server/internal/listJobs.ts

@@ -0,0 +1,98 @@
+import { Effect, Option, Schema } from "effect";
+import type { PgBossClient } from "#client.ts";
+import type { JobPayloadSchema, QueueDefinition } from "#definition.ts";
+import { type PgBossError, type PgBossPayloadError, toPgBossError } from "#error.ts";
+import { type DeadLetteredJob, deadLetterQueueName, type JobPage, type JobPageOptions } from "#health.ts";
+import { decodeStoredData, quotedSchema } from "#internal/storedRows.ts";
+import type { PgBossService } from "#service.ts";
+
+const Cursor = Schema.StringFromBase64Url.pipe(Schema.decodeTo(Schema.fromJsonString(Schema.Tuple([Schema.String, Schema.String]))));
+
+const Row = Schema.Struct({
+	completedOn: Schema.OptionFromNullOr(Schema.DateTimeUtcFromDate),
+	createdOn: Schema.DateTimeUtcFromDate,
+	cursorAt: Schema.String,
+	data: Schema.Unknown,
+	id: Schema.String,
+	output: Schema.Unknown,
+	queue: Schema.String,
+	retryCount: Schema.Number,
+	retryLimit: Schema.Number,
+	sourceId: Schema.OptionFromNullOr(Schema.String),
+	sourceOutput: Schema.Unknown,
+	startedOn: Schema.OptionFromNullOr(Schema.DateTimeUtcFromDate),
+	state: Schema.Literals(["created", "retry", "active", "completed", "cancelled", "failed"]),
+});
+
+const Rows = Schema.Array(Row);
+
+type Listing = "deadLetteredJobs" | "failedJobs";
+
+export function failedJobsFor(client: PgBossClient, schema: string): PgBossService["failedJobs"] {
+	return (queue, options) =>
+		listJobs(client, schema, "failedJobs", queue, options).pipe(
+			Effect.map(({ jobs, next }) => ({ jobs: jobs.map(({ sourceId: _id, sourceOutput: _output, ...job }) => job), next })),
+		);
+}
+
+export function deadLetteredJobsFor(client: PgBossClient, schema: string): PgBossService["deadLetteredJobs"] {
+	return (queue, options) => listJobs(client, schema, "deadLetteredJobs", queue, options);
+}
+
+function listJobs<const TName extends string, const TPayload extends JobPayloadSchema>(
+	client: PgBossClient,
+	schema: string,
+	listing: Listing,
+	queue: QueueDefinition<TName, TPayload>,
+	options: JobPageOptions,
+): Effect.Effect<JobPage<DeadLetteredJob<TPayload["Type"]>>, PgBossError | PgBossPayloadError, TPayload["DecodingServices"]> {
+	return Effect.tryPromise({
+		catch: (error) => toPgBossError(listing, error, queue.name),
+		try: async () => {
+			if (client.getDb === undefined) {
+				throw new TypeError("This pg-boss client does not support getDb");
+			}
+			if (!Number.isSafeInteger(options.limit) || options.limit < 1) {
+				throw new RangeError("The page limit must be a positive integer");
+			}
+			const after = options.cursor === undefined ? undefined : await Schema.decodeUnknownPromise(Cursor)(options.cursor);
+			const quoted = quotedSchema(schema);
+			const { rows } = await client.getDb().executeSql(
+				`SELECT
+						id,
+						name AS queue,
+						state,
+						retry_count AS "retryCount",
+						retry_limit AS "retryLimit",
+						created_on AS "createdOn",
+						started_on AS "startedOn",
+						completed_on AS "completedOn",
+						output,
+						data,
+						source_id AS "sourceId",
+						source_output AS "sourceOutput",
+						to_json(created_on) #>> '{}' AS "cursorAt"
+					FROM ${quoted}.job
+					WHERE name = $1
+						${listing === "failedJobs" ? "AND state = 'failed'" : ""}
+						AND ($2::timestamptz IS NULL OR (created_on, id) < ($2::timestamptz, $3::uuid))
+					ORDER BY created_on DESC, id DESC
+					LIMIT $4`,
+				[listing === "failedJobs" ? queue.name : deadLetterQueueName(queue.name), after?.[0] ?? null, after?.[1] ?? null, options.limit + 1],
+			);
+			return Schema.decodeUnknownPromise(Rows)(rows);
+		},
+	}).pipe(
+		Effect.flatMap((rows) => {
+			const page = rows.slice(0, options.limit);
+			const last = page.at(-1);
+			const next =
+				rows.length > options.limit && last !== undefined ? Option.some(Schema.encodeSync(Cursor)([last.cursorAt, last.id])) : Option.none();
+			return Effect.forEach(page, ({ cursorAt: _, data, ...row }) =>
+				decodeStoredData(queue, data).pipe(
+					Effect.map((decoded) => ({ ...row, attempt: Option.isSome(row.startedOn) ? row.retryCount + 1 : 0, data: decoded })),
+				),
+			).pipe(Effect.map((jobs) => ({ jobs, next })));
+		}),
+	);
+}

package/src/server/internal/observeTestingSettlements.ts

@@ -1,6 +1,6 @@
 import type { PgBoss } from "pg-boss";
 
-export function observeTestingSettlements(client: PgBoss, changed: () => void) {
+export function observeTestingSettlements(client: PgBoss, settled: (name: string) => void) {
 	const observers = new Map<string, () => void>();
 	return {
 		close() {
@@ -23,7 +23,7 @@ export function observeTestingSettlements(client: PgBoss, changed: () => void) {
 					}
 					// This controller owns the spy; clear history and the losing wait before rearming both outcomes.
 					spy.clear();
-					changed();
+					settled(name);
 				}
 			}
 			observers.set(name, () => {

package/src/server/internal/service.ts

@@ -4,11 +4,13 @@ import { type PgBossError, PgBossPayloadError, toPgBossError } from "#error.ts";
 import { countsFor } from "#internal/countsFor.ts";
 import { healthFor } from "#internal/health.ts";
 import { getJobFor, retryFor } from "#internal/jobControl.ts";
+import { deadLetteredJobsFor, failedJobsFor } from "#internal/listJobs.ts";
 import { capturePayload } from "#internal/tracing.ts";
 import type { PgBossService } from "#service.ts";
 
 export const makeService = (client: PgBossClient, names: readonly string[], schema = "pgboss"): PgBossService => ({
 	counts: (queue) => countsFor(client, schema, queue.name),
+	deadLetteredJobs: deadLetteredJobsFor(client, schema),
 	enqueue: (queue, payload, options) =>
 		Schema.encodeUnknownEffect(queue.schema)(payload).pipe(
 			Effect.mapError(
@@ -40,6 +42,7 @@ export const makeService = (client: PgBossClient, names: readonly string[], sche
 				);
 			}),
 		),
+	failedJobs: failedJobsFor(client, schema),
 	getJob: getJobFor(client),
 	health: healthFor(client, names),
 	retry: retryFor(client),

package/src/server/internal/settleDeferral.ts

@@ -1,7 +1,8 @@
 import { Schema } from "effect";
 import type { Job } from "pg-boss";
 import type { PgBossClient } from "#client.ts";
-import { STATELY_DEFERRAL_POLICY } from "./deferral.ts";
+import { STATELY_DEFERRAL_POLICY } from "#internal/deferral.ts";
+import { quotedSchema } from "#internal/storedRows.ts";
 
 const Settlement = Schema.Struct({ claimed: Schema.Boolean, deferred: Schema.Boolean });
 
@@ -9,7 +10,7 @@ export async function settleDeferral(client: PgBossClient, schema: string, job:
 	if (client.getDb === undefined) {
 		throw new TypeError("This pg-boss client does not support getDb for RetryAt");
 	}
-	const quoted = `"${schema.replaceAll('"', '""')}"`;
+	const quoted = quotedSchema(schema);
 	// Native failure settlement deletes and reinserts jobs, so a cascading job foreign key would erase the counter.
 	const { rows } = await client.getDb().executeSql(
 		`WITH claimed AS MATERIALIZED (

package/src/server/internal/storedRows.ts

@@ -0,0 +1,17 @@
+import { Effect, Redacted, Schema } from "effect";
+import type { JobPayloadSchema, QueueDefinition } from "#definition.ts";
+import { PgBossPayloadError } from "#error.ts";
+import { payloadOf } from "#internal/tracing.ts";
+
+export function quotedSchema(schema: string): string {
+	return `"${schema.replaceAll('"', '""')}"`;
+}
+
+export function decodeStoredData<const TName extends string, const TPayload extends JobPayloadSchema>(
+	queue: Pick<QueueDefinition<TName, TPayload>, "name" | "schema">,
+	data: unknown,
+): Effect.Effect<TPayload["Type"], PgBossPayloadError, TPayload["DecodingServices"]> {
+	return Schema.decodeUnknownEffect(queue.schema)(payloadOf(data)).pipe(
+		Effect.mapError((error) => new PgBossPayloadError({ direction: "decode", original: Redacted.make(error), queue: queue.name })),
+	);
+}

package/src/server/internal/testingClient.ts

@@ -4,16 +4,25 @@ import { deferralObservers } from "#internal/deferral.ts";
 import { expireAttempt } from "#internal/expireAttempt.ts";
 import { observeTestingSettlements } from "#internal/observeTestingSettlements.ts";
 import { testingExpirations } from "#internal/testingExpirations.ts";
+import type { TestingBatch, TestingWork } from "#internal/testingIdle.ts";
 
 export interface TestingControls {
 	readonly changed: () => void;
 	readonly expirations: Map<string, number>;
 	readonly failures: Set<string>;
 	readonly retryPolicy: Pick<SendOptions, "retryBackoff" | "retryDelay">;
+	readonly work: TestingWork;
 }
 
 export function testingClient(client: PgBoss, schema: string, controls: TestingControls): PgBossClient {
-	const settlements = observeTestingSettlements(client, controls.changed);
+	const settlements = observeTestingSettlements(client, (name) => {
+		for (const batch of controls.work.batches) {
+			if (batch.name === name) {
+				batch.settled = true;
+			}
+		}
+		controls.changed();
+	});
 	const expirations = testingExpirations(client);
 	function update(request: UpdateRequest): Promise<UpdateResponse>;
 	function update(name: string, data: object | null | undefined, options?: UpdateOptions): Promise<UpdateResponse>;
@@ -82,7 +91,10 @@ export function testingClient(client: PgBoss, schema: string, controls: TestingC
 			}),
 		work: (name, options, handler) => {
 			settlements.watch(name);
+			controls.work.queues.add(name);
 			return client.work(name, options, async (jobs: Job<unknown>[]) => {
+				const batch: TestingBatch = { name, settled: false };
+				controls.work.batches.add(batch);
 				controls.changed();
 				try {
 					const ready: Job<unknown>[] = [];
@@ -98,6 +110,7 @@ export function testingClient(client: PgBoss, schema: string, controls: TestingC
 						await handler(ready);
 					}
 				} finally {
+					controls.work.batches.delete(batch);
 					controls.changed();
 				}
 			});

package/src/server/internal/testingDeferrals.ts

@@ -2,6 +2,7 @@ import { DateTime } from "effect";
 import type { PgBoss } from "pg-boss";
 import type { QueueDefinition } from "#definition.ts";
 import { deferralOf } from "#internal/deferral.ts";
+import { quotedSchema } from "#internal/storedRows.ts";
 import { testingOperation } from "#internal/testingReadout.ts";
 
 export function testingDeferrals(client: () => PgBoss, schema: () => string, changed: () => void) {
@@ -22,11 +23,11 @@ export function testingDeferrals(client: () => PgBoss, schema: () => string, cha
 			testingOperation(
 				"runDeferredNow",
 				async () => {
-					const quotedSchema = `"${schema().replaceAll('"', '""')}"`;
+					const quoted = quotedSchema(schema());
 					await client()
 						.getDb()
 						.executeSql(
-							`UPDATE ${quotedSchema}.job SET start_after = ${quotedSchema}.job_now()
+							`UPDATE ${quoted}.job SET start_after = ${quoted}.job_now()
 				WHERE name = $1 AND state = 'retry' AND output ? 'jobDeferral' AND started_on IS NULL`,
 							[queue.name],
 						);

package/src/server/internal/testingIdle.ts

@@ -0,0 +1,52 @@
+import { Effect, Schema } from "effect";
+import type { PgBoss } from "pg-boss";
+import type { PgBossTestingError } from "#error.ts";
+import { quotedSchema } from "#internal/storedRows.ts";
+import { testingOperation } from "#internal/testingReadout.ts";
+
+export interface TestingBatch {
+	readonly name: string;
+	settled: boolean;
+}
+
+export interface TestingWork {
+	readonly batches: Set<TestingBatch>;
+	readonly queues: Set<string>;
+}
+
+const Busy = Schema.Struct({ busy: Schema.Boolean });
+
+export function testingIdle(
+	client: () => PgBoss,
+	schema: () => string,
+	work: TestingWork,
+	signal: { readonly revision: Effect.Effect<number>; readonly waitForChange: (after: number) => Effect.Effect<number> },
+): Effect.Effect<void, PgBossTestingError> {
+	const busy = testingOperation("waitForIdle", async () => {
+		const quoted = quotedSchema(schema());
+		const { rows } = await client()
+			.getDb()
+			.executeSql(
+				`/* effect-pg-boss testing idle */ SELECT EXISTS (
+					SELECT 1 FROM ${quoted}.job
+					WHERE name = ANY($1::text[]) AND (
+						(state < 'active' AND NOT blocked AND start_after <= ${quoted}.job_now())
+						OR state = 'active'
+					)
+				) AS busy`,
+				[[...work.queues]],
+			);
+		return (await Schema.decodeUnknownPromise(Busy)(rows[0])).busy;
+	});
+	return Effect.gen(function* () {
+		while (true) {
+			const revision = yield* signal.revision;
+			// A batch with no settlement since its fetch still holds active jobs, so it is busy without a read.
+			const unsettled = [...work.batches].some((batch) => !batch.settled);
+			if (work.queues.size === 0 || !(unsettled || (yield* busy))) {
+				return;
+			}
+			yield* signal.waitForChange(revision);
+		}
+	});
+}

package/src/server/internal/testingReadout.ts

@@ -1,8 +1,8 @@
-import { Effect, Redacted, Schema } from "effect";
+import { Effect, Redacted } from "effect";
 import type { FindJobsOptions, PgBoss } from "pg-boss";
 import type { JobPayloadSchema, QueueDefinition } from "#definition.ts";
-import { PgBossPayloadError, PgBossTestingError } from "#error.ts";
-import { payloadOf } from "#internal/tracing.ts";
+import { PgBossTestingError } from "#error.ts";
+import { decodeStoredData } from "#internal/storedRows.ts";
 
 export function testingOperation<A>(operation: string, run: () => Promise<A>, queue?: string) {
 	return Effect.tryPromise({
@@ -14,13 +14,6 @@ export function testingOperation<A>(operation: string, run: () => Promise<A>, qu
 export function testingReadout(client: () => PgBoss) {
 	return <TName extends string, TPayload extends JobPayloadSchema>(queue: QueueDefinition<TName, TPayload>, options?: FindJobsOptions) =>
 		testingOperation("jobs", () => client().findJobs<unknown>(queue.name, options), queue.name).pipe(
-			Effect.flatMap((jobs) =>
-				Effect.forEach(jobs, (job) =>
-					Schema.decodeUnknownEffect(queue.schema)(payloadOf(job.data)).pipe(
-						Effect.mapError((original) => new PgBossPayloadError({ direction: "decode", original: Redacted.make(original), queue: queue.name })),
-						Effect.map((data) => ({ ...job, data })),
-					),
-				),
-			),
+			Effect.flatMap((jobs) => Effect.forEach(jobs, (job) => decodeStoredData(queue, job.data).pipe(Effect.map((data) => ({ ...job, data }))))),
 		);
 }

package/src/server/internal/testingSignal.ts

@@ -6,10 +6,12 @@ export function testingSignal() {
 	return {
 		changed() {
 			revision += 1;
-			for (const listener of listeners) {
+			// A resumed waiter can wait again synchronously; it must wait for the next change, not this one.
+			const waiting = [...listeners];
+			listeners.clear();
+			for (const listener of waiting) {
 				listener(revision);
 			}
-			listeners.clear();
 		},
 		revision: Effect.sync(() => revision),
 		waitForChange: (after: number): Effect.Effect<number> =>

package/src/server/internal/testingSnapshot.ts

@@ -0,0 +1,53 @@
+import { Effect, Schema } from "effect";
+import type { PgBoss } from "pg-boss";
+import type { PgBossPayloadError, PgBossTestingError } from "#error.ts";
+import { decodeStoredData, quotedSchema } from "#internal/storedRows.ts";
+import { testingOperation } from "#internal/testingReadout.ts";
+import type { SnapshotQueue, UnfinishedJob } from "#testing.ts";
+
+const Rows = Schema.Array(
+	Schema.Struct({
+		data: Schema.Unknown,
+		id: Schema.String,
+		queue: Schema.String,
+		startAfter: Schema.DateTimeUtcFromDate,
+		state: Schema.Literals(["created", "retry", "active", "failed"]),
+	}),
+);
+
+export function testingSnapshot(client: () => PgBoss, schema: () => string) {
+	return <const TQueues extends readonly SnapshotQueue[]>(
+		queues: TQueues,
+	): Effect.Effect<
+		readonly UnfinishedJob<TQueues[number]>[],
+		PgBossPayloadError | PgBossTestingError,
+		TQueues[number]["schema"]["DecodingServices"]
+	> => {
+		const byName = new Map<string, TQueues[number]>(queues.map((queue) => [queue.name, queue]));
+		return testingOperation("snapshot", async () => {
+			const quoted = quotedSchema(schema());
+			const { rows } = await client()
+				.getDb()
+				.executeSql(
+					`SELECT id, name AS queue, state, data, start_after AS "startAfter"
+					FROM ${quoted}.job
+					WHERE name = ANY($1::text[]) AND state IN ('created', 'retry', 'active', 'failed')
+					ORDER BY created_on, id`,
+					[[...byName.keys()]],
+				);
+			return Schema.decodeUnknownPromise(Rows)(rows);
+		}).pipe(
+			Effect.flatMap((rows) =>
+				Effect.forEach(rows, ({ data, queue: name, ...row }) => {
+					const queue = byName.get(name);
+					if (queue === undefined) {
+						return Effect.die(new Error(`The snapshot returned a job of an unrequested queue ${name}`));
+					}
+					return decodeStoredData<TQueues[number]["name"], TQueues[number]["schema"]>(queue, data).pipe(
+						Effect.map((decoded): UnfinishedJob<TQueues[number]> => ({ ...row, data: decoded, queue: queue.name })),
+					);
+				}),
+			),
+		);
+	};
+}

package/src/server/service.ts

@@ -3,7 +3,7 @@ import type { ConstructorOptions, JobWithMetadata, SendOptions, StopOptions } fr
 import type { PgBossClientFactory } from "#client.ts";
 import type { JobPayloadSchema, JobRegistration, QueueDefinition, RegistrationRequirements } from "#definition.ts";
 import type { PgBossError, PgBossPayloadError, PgBossQueueOptionsError } from "#error.ts";
-import type { JobsHealth, QueueCounts } from "#health.ts";
+import type { DeadLetteredJob, JobPage, JobPageOptions, JobsHealth, ListedJob, QueueCounts } from "#health.ts";
 import { logClientError, subscribeClientErrors } from "#internal/clientErrors.ts";
 import { acquireClient, releaseClient } from "#internal/lifecycle.ts";
 import { registerJobs, registrationName } from "#internal/register.ts";
@@ -11,11 +11,19 @@ import { makeService } from "#internal/service.ts";
 
 export interface PgBossService {
 	readonly counts: (queue: Pick<QueueDefinition, "name">) => Effect.Effect<QueueCounts, PgBossError>;
+	readonly deadLetteredJobs: <const TName extends string, const TPayload extends JobPayloadSchema>(
+		queue: QueueDefinition<TName, TPayload>,
+		options: JobPageOptions,
+	) => Effect.Effect<JobPage<DeadLetteredJob<TPayload["Type"]>>, PgBossError | PgBossPayloadError, TPayload["DecodingServices"]>;
 	readonly enqueue: <const TName extends string, const TPayload extends JobPayloadSchema, const TQueue extends QueueDefinition<TName, TPayload>>(
 		queue: QueueDefinition<TName, TPayload> & TQueue,
 		payload: NoInfer<Schema.Schema.Type<TPayload>>,
 		options?: NoInfer<TQueue["key"] extends undefined ? SendOptions : Omit<SendOptions, "singletonKey"> & { readonly singletonKey?: never }>,
 	) => Effect.Effect<Option.Option<string>, PgBossError | PgBossPayloadError, TPayload["EncodingServices"]>;
+	readonly failedJobs: <const TName extends string, const TPayload extends JobPayloadSchema>(
+		queue: QueueDefinition<TName, TPayload>,
+		options: JobPageOptions,
+	) => Effect.Effect<JobPage<ListedJob<TPayload["Type"]>>, PgBossError | PgBossPayloadError, TPayload["DecodingServices"]>;
 	readonly getJob: <const TName extends string, const TPayload extends JobPayloadSchema>(
 		queue: QueueDefinition<TName, TPayload>,
 		id: string,

package/src/server/testing.ts

@@ -1,12 +1,24 @@
-import { Effect, Redacted } from "effect";
+import { type DateTime, Effect, Redacted } from "effect";
 import { PgBoss } from "pg-boss";
 import type { PgBossClientFactory } from "#client.ts";
-import type { QueueDefinition } from "#definition.ts";
+import type { JobPayloadSchema, QueueDefinition } from "#definition.ts";
 import { PgBossTestingError } from "#error.ts";
 import { testingClient } from "#internal/testingClient.ts";
 import { testingDeferrals } from "#internal/testingDeferrals.ts";
+import { type TestingWork, testingIdle } from "#internal/testingIdle.ts";
 import { testingOperation, testingReadout } from "#internal/testingReadout.ts";
 import { testingSignal } from "#internal/testingSignal.ts";
+import { testingSnapshot } from "#internal/testingSnapshot.ts";
+
+export type SnapshotQueue = Pick<QueueDefinition<string, JobPayloadSchema>, "name" | "schema">;
+
+export interface UnfinishedJob<TQueue extends SnapshotQueue> {
+	readonly data: TQueue["schema"]["Type"];
+	readonly id: string;
+	readonly queue: TQueue["name"];
+	readonly startAfter: DateTime.Utc;
+	readonly state: "active" | "created" | "failed" | "retry";
+}
 
 export const testRetryPolicy = Object.freeze({ retryBackoff: false, retryDelay: 0 });
 
@@ -18,11 +30,13 @@ export function makePgBossTesting(options: PgBossTestingOptions = {}) {
 	let current: PgBoss | undefined;
 	let schema = "pgboss";
 	const signal = testingSignal();
+	const work: TestingWork = { batches: new Set(), queues: new Set() };
 	const controls = {
 		changed: signal.changed,
 		expirations: new Map<string, number>(),
 		failures: new Set<string>(),
 		retryPolicy: options.retryPolicy ?? {},
+		work,
 	};
 	function client(): PgBoss {
 		if (current === undefined) {
@@ -82,7 +96,9 @@ export function makePgBossTesting(options: PgBossTestingOptions = {}) {
 		jobs: testingReadout(client),
 		revision: signal.revision,
 		schemaVersion: testingOperation("schemaVersion", () => client().schemaVersion()),
+		snapshot: testingSnapshot(client, () => schema),
 		waitForChange: signal.waitForChange,
+		waitForIdle: testingIdle(client, () => schema, work, signal),
 	};
 }