@satorio/machinery 0.2.1

package/dist/postgres/layer.js

@@ -0,0 +1,72 @@
+import { BunFileSystem } from '@effect/platform-bun';
+import { SqlClient } from '@effect/sql';
+import { PgClient } from '@effect/sql-pg';
+import { DocumentNumberCounter, IntegrationEventOutbox, ProcessedEventRegistry, ReadinessProbe, TransactionBoundary, } from '@satorio/machinery/ports';
+import { Effect, Layer } from 'effect';
+import { poolOptionsFor, scopedPostgresTransport, sslOptionsFor, } from './client.js';
+import { makePgDocumentNumberCounter } from './document-number-counter.js';
+import { makePgIntegrationEventOutbox } from './integration-event-outbox.js';
+import { MIGRATION_APPLICATION_NAME_SUFFIX, migrationPoolOptionsFor, } from './migrations/runner.js';
+import { makePgProcessedEventRegistry } from './processed-event-registry.js';
+import { readinessProbeAsking } from './readiness-probe.js';
+import { postgresConnectionSettings } from './settings.js';
+import { makePgTransactionBoundary } from './transaction-boundary.js';
+const acquireDatabasePool = scopedPostgresTransport(poolOptionsFor, 'Could not open a connection pool to the database');
+const acquireMigrationPool = scopedPostgresTransport(migrationPoolOptionsFor, 'Could not open a connection pool for the migration runner');
+/**
+ * The `@effect/sql-pg` client every other layer here builds on, opened
+ * from the environment `settings.ts` names.
+ */
+export const PostgresClientLive = Layer.unwrapEffect(Effect.gen(function* () {
+    const settings = yield* postgresConnectionSettings;
+    const ssl = yield* sslOptionsFor(settings);
+    return PgClient.layerFromPool({
+        acquire: acquireDatabasePool(settings, ssl),
+        applicationName: settings.applicationName,
+    });
+}));
+/**
+ * The client the migration runner uses: one connection, under its own name.
+ *
+ * The same client for the migration runner: one connection, and its own name
+ * in `pg_stat_activity`, so a long migration is easy to spot next to the
+ * service's own pool.
+ */
+export const MigrationPgClientLive = Layer.unwrapEffect(Effect.gen(function* () {
+    const settings = yield* postgresConnectionSettings;
+    const ssl = yield* sslOptionsFor(settings);
+    return PgClient.layerFromPool({
+        acquire: acquireMigrationPool(settings, ssl),
+        applicationName: `${settings.applicationName}${MIGRATION_APPLICATION_NAME_SUFFIX}`,
+    });
+}));
+/**
+ * The transaction boundary on a real Postgres transaction.
+ */
+export const PgTransactionBoundaryLive = Layer.effect(TransactionBoundary, makePgTransactionBoundary);
+/**
+ * The exactly-once claim on a real `processed_event` table.
+ */
+export const PgProcessedEventRegistryLive = Layer.effect(ProcessedEventRegistry, makePgProcessedEventRegistry);
+/**
+ * The document number counter on a real `document_number_counter` table.
+ */
+export const PgDocumentNumberCounterLive = Layer.effect(DocumentNumberCounter, makePgDocumentNumberCounter);
+/**
+ * The outbox on a real `integration_event_outbox` table.
+ */
+export const PgIntegrationEventOutboxLive = Layer.effect(IntegrationEventOutbox, makePgIntegrationEventOutbox);
+/**
+ * The readiness probe on one `SELECT 1` against the service's own pool.
+ */
+export const PgReadinessProbeLive = Layer.effect(ReadinessProbe, Effect.map(SqlClient.SqlClient, (sql) => readinessProbeAsking(sql `SELECT 1`)));
+/**
+ * Every port this mechanism implements, on one client, for a service
+ * that supplies its own `FileSystem`.
+ */
+export const PostgresPortsLive = Layer.mergeAll(PgProcessedEventRegistryLive, PgIntegrationEventOutboxLive, PgDocumentNumberCounterLive, PgTransactionBoundaryLive, PgReadinessProbeLive).pipe(Layer.provideMerge(PostgresClientLive));
+/**
+ * The same bundle on Bun's own file system, which is the whole Postgres
+ * side of the machinery in one layer.
+ */
+export const PostgresPortsOnBunLive = PostgresPortsLive.pipe(Layer.provide(BunFileSystem.layer));

package/dist/postgres/migrations/advisory-lock.d.ts

@@ -0,0 +1,47 @@
+import { SqlClient, type SqlError } from '@effect/sql';
+import { Effect, Schedule } from 'effect';
+import { MigrationLockBusyError } from '../failures.js';
+/**
+ * The lowest int4 Postgres accepts, which is the floor of both halves of
+ * an advisory-lock key.
+ *
+ * @internal
+ */
+export declare const POSTGRES_INTEGER_MIN = -2147483648;
+/**
+ * The highest int4 Postgres accepts, which is the ceiling of both halves
+ * of an advisory-lock key.
+ *
+ * @internal
+ */
+export declare const POSTGRES_INTEGER_MAX = 2147483647;
+/**
+ * A lock somebody else may already hold: its name, the attempt to take
+ * it, and the release that follows.
+ *
+ * @internal
+ */
+export interface AdvisoryLock<E, R> {
+    readonly name: string;
+    readonly tryAcquire: Effect.Effect<boolean, E, R>;
+    readonly release: Effect.Effect<void, E, R>;
+}
+/**
+ * Turns a lock name into the pair of int4 keys Postgres advisory locks
+ * need. Two different hashes of the same name form the two halves, so a
+ * collision needs both halves to match.
+ *
+ * @internal
+ */
+export declare const advisoryLockKeyFor: (name: string) => readonly [number, number];
+/**
+ * Runs an effect while holding the lock, waiting on the given schedule
+ * while somebody else holds it, and letting go however the effect ends.
+ */
+export declare const holdingAdvisoryLock: <ELock, RLock, ScheduleOut, RSchedule>(lock: AdvisoryLock<ELock, RLock>, retryWhileBusy: Schedule.Schedule<ScheduleOut, unknown, RSchedule>) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | ELock | MigrationLockBusyError, R | RLock | RSchedule>;
+/**
+ * A named advisory lock on the connection's own database. The name is
+ * hashed into the pair of int4 keys Postgres wants, so two names collide
+ * only when both halves do.
+ */
+export declare const postgresAdvisoryLock: (name: string) => AdvisoryLock<SqlError.SqlError, SqlClient.SqlClient>;

package/dist/postgres/migrations/advisory-lock.js

@@ -0,0 +1,59 @@
+import { SqlClient } from '@effect/sql';
+import { Effect, Schedule } from 'effect';
+import { MigrationLockBusyError } from '../failures.js';
+/**
+ * The lowest int4 Postgres accepts, which is the floor of both halves of
+ * an advisory-lock key.
+ *
+ * @internal
+ */
+export const POSTGRES_INTEGER_MIN = -2_147_483_648;
+/**
+ * The highest int4 Postgres accepts, which is the ceiling of both halves
+ * of an advisory-lock key.
+ *
+ * @internal
+ */
+export const POSTGRES_INTEGER_MAX = 2_147_483_647;
+const FNV_OFFSET_BASIS = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+const LOWER_HALF_SALT = 'postgres-advisory-lock';
+const fnv1a32 = (text) => {
+    let hash = FNV_OFFSET_BASIS;
+    for (let index = 0; index < text.length; index += 1) {
+        hash = Math.imul(hash ^ text.charCodeAt(index), FNV_PRIME);
+    }
+    return hash | 0;
+};
+/**
+ * Turns a lock name into the pair of int4 keys Postgres advisory locks
+ * need. Two different hashes of the same name form the two halves, so a
+ * collision needs both halves to match.
+ *
+ * @internal
+ */
+export const advisoryLockKeyFor = (name) => [
+    fnv1a32(name),
+    fnv1a32(`${LOWER_HALF_SALT}:${name}`),
+];
+const errorIsLockBusy = (error) => error instanceof MigrationLockBusyError;
+/**
+ * Runs an effect while holding the lock, waiting on the given schedule
+ * while somebody else holds it, and letting go however the effect ends.
+ */
+export const holdingAdvisoryLock = (lock, retryWhileBusy) => (effect) => Effect.acquireUseRelease(Effect.retry(Effect.flatMap(lock.tryAcquire, (acquired) => acquired
+    ? Effect.void
+    : Effect.fail(new MigrationLockBusyError({ lockName: lock.name }))), Schedule.whileInput(retryWhileBusy, errorIsLockBusy)), () => effect, () => Effect.orDie(lock.release));
+/**
+ * A named advisory lock on the connection's own database. The name is
+ * hashed into the pair of int4 keys Postgres wants, so two names collide
+ * only when both halves do.
+ */
+export const postgresAdvisoryLock = (name) => {
+    const [upperHalf, lowerHalf] = advisoryLockKeyFor(name);
+    return {
+        name,
+        tryAcquire: Effect.flatMap(SqlClient.SqlClient, (sql) => sql `SELECT pg_try_advisory_lock(${upperHalf}, ${lowerHalf}) AS acquired`.pipe(Effect.map((rows) => rows[0]?.acquired === true))),
+        release: Effect.flatMap(SqlClient.SqlClient, (sql) => Effect.asVoid(sql `SELECT pg_advisory_unlock(${upperHalf}, ${lowerHalf})`)),
+    };
+};

package/dist/postgres/migrations/runner.d.ts

@@ -0,0 +1,56 @@
+import type { ConnectionOptions } from 'node:tls';
+import { Migrator, SqlClient } from '@effect/sql';
+import type { SqlError } from '@effect/sql/SqlError';
+import { Effect, Schedule } from 'effect';
+import type { PoolConfig } from 'pg';
+import { type PostgresConnectionSettings } from '../settings.js';
+/**
+ * Directory holding the machinery's shared migrations: the processed-event
+ * registry and the outbox. The machinery reserves numbers 1-99; a service's
+ * own migrations start at 100.
+ */
+export declare const MACHINERY_MIGRATIONS_DIRECTORY: string;
+/**
+ * What the migration runner adds to the application name, so a long
+ * migration is easy to tell from the service's own pool in
+ * `pg_stat_activity`.
+ *
+ * @internal
+ */
+export declare const MIGRATION_APPLICATION_NAME_SUFFIX = "-migrate";
+/**
+ * The name every migration lock is built from, so one reader finds them all.
+ */
+export declare const MIGRATION_LOCK_NAME = "migrations";
+/**
+ * The lock one schema's migrations take, so two services migrating two
+ * schemas never wait on each other.
+ */
+export declare const migrationLockNameFor: (schema: string) => string;
+/**
+ * Retry schedule for the migration advisory lock. A second process does
+ * not fail or run in parallel: it waits up to five minutes for the first
+ * process to finish.
+ *
+ * @internal
+ */
+export declare const MIGRATION_LOCK_RETRY: Schedule.Schedule<[number, number], unknown, never>;
+/**
+ * Builds pool options for the migration runner: one process, one
+ * connection. Migrations run one after another, so a pool of two would
+ * only confuse the picture in `pg_stat_activity`.
+ *
+ * @internal
+ */
+export declare const migrationPoolOptionsFor: (settings: PostgresConnectionSettings, ssl: boolean | ConnectionOptions) => PoolConfig;
+/**
+ * Applies pending migrations from the given directories, the machinery's
+ * own directory first, then the caller's. Creates the schema before
+ * running any migration, since the first migration already writes to it.
+ */
+export declare const applyMigrations: (directories?: readonly string[]) => Effect.Effect<readonly (readonly [id: number, name: string])[], import("effect/ConfigError").ConfigError | SqlError | import("..").MigrationLockBusyError | Migrator.MigrationError, import("@effect/platform/FileSystem").FileSystem | SqlClient.SqlClient>;
+/**
+ * Says in one line what the run applied, or that the database was
+ * already current.
+ */
+export declare const reportApplied: (applied: ReadonlyArray<readonly [number, string]>) => Effect.Effect<void>;

package/dist/postgres/migrations/runner.js

@@ -0,0 +1,69 @@
+import { Migrator, SqlClient } from '@effect/sql';
+import { Duration, Effect, Schedule } from 'effect';
+import { poolOptionsFor } from '../client.js';
+import { postgresConnectionSettings, } from '../settings.js';
+import { holdingAdvisoryLock, postgresAdvisoryLock } from './advisory-lock.js';
+import { sqlMigrationsIn } from './sql-file-loader.js';
+/**
+ * Directory holding the machinery's shared migrations: the processed-event
+ * registry and the outbox. The machinery reserves numbers 1-99; a service's
+ * own migrations start at 100.
+ */
+export const MACHINERY_MIGRATIONS_DIRECTORY = `${import.meta.dirname}/../sql`;
+/**
+ * What the migration runner adds to the application name, so a long
+ * migration is easy to tell from the service's own pool in
+ * `pg_stat_activity`.
+ *
+ * @internal
+ */
+export const MIGRATION_APPLICATION_NAME_SUFFIX = '-migrate';
+/**
+ * The name every migration lock is built from, so one reader finds them all.
+ */
+export const MIGRATION_LOCK_NAME = 'migrations';
+/**
+ * The lock one schema's migrations take, so two services migrating two
+ * schemas never wait on each other.
+ */
+export const migrationLockNameFor = (schema) => `${MIGRATION_LOCK_NAME}:${schema}`;
+/**
+ * Retry schedule for the migration advisory lock. A second process does
+ * not fail or run in parallel: it waits up to five minutes for the first
+ * process to finish.
+ *
+ * @internal
+ */
+export const MIGRATION_LOCK_RETRY = Schedule.spaced(Duration.seconds(2)).pipe(Schedule.intersect(Schedule.recurs(150)));
+/**
+ * Builds pool options for the migration runner: one process, one
+ * connection. Migrations run one after another, so a pool of two would
+ * only confuse the picture in `pg_stat_activity`.
+ *
+ * @internal
+ */
+export const migrationPoolOptionsFor = (settings, ssl) => ({
+    ...poolOptionsFor(settings, ssl),
+    application_name: `${settings.applicationName}${MIGRATION_APPLICATION_NAME_SUFFIX}`,
+    max: 1,
+    min: 1,
+});
+const ensureSchemaExists = (schema) => Effect.flatMap(SqlClient.SqlClient, (sql) => Effect.asVoid(sql `CREATE SCHEMA IF NOT EXISTS ${sql(schema)}`));
+/**
+ * Applies pending migrations from the given directories, the machinery's
+ * own directory first, then the caller's. Creates the schema before
+ * running any migration, since the first migration already writes to it.
+ */
+export const applyMigrations = (directories = [MACHINERY_MIGRATIONS_DIRECTORY]) => Effect.flatMap(postgresConnectionSettings, (settings) => Effect.gen(function* () {
+    yield* ensureSchemaExists(settings.schema);
+    return yield* Migrator.make({})({
+        loader: sqlMigrationsIn(directories),
+    });
+}).pipe(holdingAdvisoryLock(postgresAdvisoryLock(migrationLockNameFor(settings.schema)), MIGRATION_LOCK_RETRY)));
+/**
+ * Says in one line what the run applied, or that the database was
+ * already current.
+ */
+export const reportApplied = (applied) => applied.length === 0
+    ? Effect.logInfo('Migrations: nothing new, the database is already current')
+    : Effect.logInfo(`Migrations applied: ${applied.map(([id, name]) => `${id}_${name}`).join(', ')}`);

package/dist/postgres/migrations/sql-file-loader.d.ts

@@ -0,0 +1,59 @@
+import { FileSystem } from '@effect/platform';
+import { Migrator, SqlClient, type SqlError } from '@effect/sql';
+import { Effect } from 'effect';
+/**
+ * What a migration file is called: a number, an underscore, a name, and
+ * `.sql`.
+ *
+ * @internal
+ */
+export declare const SQL_MIGRATION_FILE_NAME: RegExp;
+/**
+ * One migration's body, ready to run against the client.
+ *
+ * @internal
+ */
+export type SqlMigrationExecution = Effect.Effect<ReadonlyArray<object>, SqlError.SqlError, SqlClient.SqlClient>;
+/**
+ * One migration in the shape `@effect/sql`'s migrator loads.
+ *
+ * @internal
+ */
+export type ResolvedSqlMigration = readonly [
+    id: number,
+    name: string,
+    load: Effect.Effect<SqlMigrationExecution>
+];
+/**
+ * One migration found on disk, with the body already read.
+ *
+ * @internal
+ */
+export interface DiscoveredSqlMigration {
+    readonly id: number;
+    readonly name: string;
+    readonly fileName: string;
+    readonly body: string;
+}
+/**
+ * Discovers migrations across one or more directories: the machinery's own
+ * shared tables and a service's own. The migration number must be unique
+ * across all directories, or the apply order would differ between
+ * environments — the machinery holds numbers 1-99, a service starts at 100.
+ *
+ * @internal
+ */
+export declare const discoverSqlMigrationsIn: (directories: readonly string[]) => Effect.Effect<ReadonlyArray<DiscoveredSqlMigration>, Migrator.MigrationError, FileSystem.FileSystem>;
+/**
+ * Runs one migration body as a single statement batch.
+ *
+ * @internal
+ */
+export declare const executeSqlBody: (body: string) => SqlMigrationExecution;
+/**
+ * The loader `@effect/sql`'s migrator takes: every migration of every
+ * directory, oldest number first.
+ *
+ * @internal
+ */
+export declare const sqlMigrationsIn: (directories: readonly string[]) => Effect.Effect<ReadonlyArray<ResolvedSqlMigration>, Migrator.MigrationError, FileSystem.FileSystem>;

package/dist/postgres/migrations/sql-file-loader.js

@@ -0,0 +1,99 @@
+import { FileSystem } from '@effect/platform';
+import { Migrator, SqlClient } from '@effect/sql';
+import { Effect } from 'effect';
+/**
+ * What a migration file is called: a number, an underscore, a name, and
+ * `.sql`.
+ *
+ * @internal
+ */
+export const SQL_MIGRATION_FILE_NAME = /^(\d+)_([^.]+)\.sql$/;
+const directoryIsUnreadable = (directory, cause) => new Migrator.MigrationError({
+    cause,
+    reason: 'failed',
+    message: `Migration directory ${directory} is unreadable`,
+});
+const fileIsUnreadable = (path, cause) => new Migrator.MigrationError({
+    cause,
+    reason: 'failed',
+    message: `Migration file ${path} is unreadable`,
+});
+const fileNameBreaksTheNamingRule = (fileName) => new Migrator.MigrationError({
+    reason: 'failed',
+    message: `File ${fileName} sits in the migrations directory but isn't a ` +
+        `migration: the name must look like <number>_<name>.sql`,
+});
+const migrationNumberIsNotUnique = (clashes) => new Migrator.MigrationError({
+    reason: 'duplicates',
+    message: `Migration number isn't unique, no migration was applied: ` +
+        clashes
+            .map(([id, fileNames]) => `${id} - ${fileNames.join(', ')}`)
+            .join('; '),
+});
+const nameFileOrRefuse = (directory, fileName) => {
+    const parts = SQL_MIGRATION_FILE_NAME.exec(fileName);
+    const number = parts?.[1];
+    const name = parts?.[2];
+    return number === undefined || name === undefined
+        ? Effect.fail(fileNameBreaksTheNamingRule(`${directory}/${fileName}`))
+        : Effect.succeed({
+            id: Number(number),
+            name,
+            fileName: `${directory}/${fileName}`,
+        });
+};
+const refuseRepeatedMigrationNumbers = (migrations) => {
+    const fileNamesByNumber = new Map();
+    for (const migration of migrations) {
+        fileNamesByNumber.set(migration.id, [
+            ...(fileNamesByNumber.get(migration.id) ?? []),
+            migration.fileName,
+        ]);
+    }
+    const clashes = [...fileNamesByNumber.entries()]
+        .filter(([, fileNames]) => fileNames.length > 1)
+        .map(([id, fileNames]) => [id, [...fileNames].sort()]);
+    return clashes.length === 0
+        ? Effect.void
+        : Effect.fail(migrationNumberIsNotUnique(clashes));
+};
+const byAscendingMigrationNumber = (left, right) => left.id - right.id;
+const namedFilesIn = (directory) => Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const entries = yield* fileSystem
+        .readDirectory(directory)
+        .pipe(Effect.mapError((cause) => directoryIsUnreadable(directory, cause)));
+    return yield* Effect.forEach(entries, (fileName) => nameFileOrRefuse(directory, fileName));
+});
+/**
+ * Discovers migrations across one or more directories: the machinery's own
+ * shared tables and a service's own. The migration number must be unique
+ * across all directories, or the apply order would differ between
+ * environments — the machinery holds numbers 1-99, a service starts at 100.
+ *
+ * @internal
+ */
+export const discoverSqlMigrationsIn = (directories) => Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const perDirectory = yield* Effect.forEach(directories, namedFilesIn);
+    const named = perDirectory.flat();
+    yield* refuseRepeatedMigrationNumbers(named);
+    return yield* Effect.forEach([...named].sort(byAscendingMigrationNumber), (migration) => fileSystem.readFileString(migration.fileName).pipe(Effect.mapError((cause) => fileIsUnreadable(migration.fileName, cause)), Effect.map((body) => ({ ...migration, body }))));
+});
+/**
+ * Runs one migration body as a single statement batch.
+ *
+ * @internal
+ */
+export const executeSqlBody = (body) => Effect.flatMap(SqlClient.SqlClient, (sql) => sql.unsafe(body));
+/**
+ * The loader `@effect/sql`'s migrator takes: every migration of every
+ * directory, oldest number first.
+ *
+ * @internal
+ */
+export const sqlMigrationsIn = (directories) => Effect.map(discoverSqlMigrationsIn(directories), (migrations) => migrations.map((migration) => [
+    migration.id,
+    migration.name,
+    Effect.succeed(executeSqlBody(migration.body)),
+]));

package/dist/postgres/processed-event-registry.d.ts

@@ -0,0 +1,13 @@
+import { PgClient } from '@effect/sql-pg';
+import { type ClaimProcessedEventInput, ProcessedEventRegistryUnavailableError } from '@satorio/machinery/ports';
+import { Effect } from 'effect';
+/**
+ * Builds the registry on the service's own pool: one statement that both
+ * takes the claim and reads who won it, retried only over the race
+ * window.
+ *
+ * @internal
+ */
+export declare const makePgProcessedEventRegistry: Effect.Effect<{
+    claim: (input: ClaimProcessedEventInput) => Effect.Effect<import("@satorio/machinery/ports").ProcessedEventClaim, ProcessedEventRegistryUnavailableError>;
+}, never, PgClient.PgClient>;

package/dist/postgres/processed-event-registry.js

@@ -0,0 +1,44 @@
+import { PgClient } from '@effect/sql-pg';
+import { alreadyProcessed, claimAccepted, ProcessedEventRegistryUnavailableError, portUnavailable, } from '@satorio/machinery/ports';
+import { DateTime, Effect, Schedule } from 'effect';
+import { ClaimRaceWindowMissedError } from './failures.js';
+const CLAIM_RACE_WINDOW_RETRY_LIMIT = 5;
+const RETRY_ONLY_ON_RACE_WINDOW_MISS = Schedule.recurs(CLAIM_RACE_WINDOW_RETRY_LIMIT).pipe(Schedule.whileInput((failure) => failure._tag === 'ClaimRaceWindowMissedError'));
+/**
+ * Builds the registry on the service's own pool: one statement that both
+ * takes the claim and reads who won it, retried only over the race
+ * window.
+ *
+ * @internal
+ */
+export const makePgProcessedEventRegistry = Effect.gen(function* () {
+    const sql = yield* PgClient.PgClient;
+    const unavailable = portUnavailable(ProcessedEventRegistryUnavailableError);
+    const oneClaimAttempt = (input) => Effect.gen(function* () {
+        const outcome = yield* sql `
+        WITH accepted AS (
+          INSERT INTO processed_event (event_id, processed_at)
+          VALUES (${input.eventId}::text, ${DateTime.toDate(input.processedAt)}::timestamptz)
+          ON CONFLICT (event_id) DO NOTHING
+          RETURNING processed_at AS "processedAt", true AS "claimed"
+        )
+        SELECT "processedAt", "claimed" FROM accepted
+        UNION ALL
+        SELECT processed_at AS "processedAt", false AS "claimed"
+        FROM processed_event
+        WHERE event_id = ${input.eventId}::text
+          AND NOT EXISTS (SELECT 1 FROM accepted)
+      `;
+        const row = outcome[0];
+        return row === undefined
+            ? yield* new ClaimRaceWindowMissedError({ eventId: input.eventId })
+            : row;
+    });
+    const claim = (input) => oneClaimAttempt(input).pipe(Effect.retry(RETRY_ONLY_ON_RACE_WINDOW_MISS), Effect.map((row) => row.claimed
+        ? claimAccepted
+        : alreadyProcessed(DateTime.unsafeMake(row.processedAt))), Effect.catchTags({
+        SqlError: unavailable('claim'),
+        ClaimRaceWindowMissedError: (failure) => unavailable('claim')(`Race window did not close within ${CLAIM_RACE_WINDOW_RETRY_LIMIT} attempts for eventId ${failure.eventId}`),
+    }));
+    return { claim };
+});

package/dist/postgres/readiness-probe.d.ts

@@ -0,0 +1,27 @@
+import type { SqlError } from '@effect/sql/SqlError';
+import { DatabaseDidNotAnswerError } from '@satorio/machinery/ports';
+import { Effect } from 'effect';
+/**
+ * Reason reported when the readiness query answers with a failure. A
+ * probe reads `reason` to tell a silent database from a slow one.
+ */
+export declare const READINESS_REASON_WHEN_THE_DATABASE_STAYS_SILENT = "database did not answer the readiness query";
+/**
+ * Reason reported when the readiness query times out. A database you can't
+ * reach doesn't always fail fast: the client may keep trying to connect
+ * while the caller waits. Without a deadline the probe would hang instead
+ * of reporting "down", and `/readyz` would hang with it.
+ */
+export declare const READINESS_REASON_WHEN_THE_QUERY_TIMES_OUT = "readiness query did not answer within the deadline";
+/**
+ * How long the probe waits for its query before it reports "down".
+ */
+export declare const READINESS_QUERY_DEADLINE_MILLIS = 2000;
+/**
+ * Builds a probe around one query the database must answer, with a
+ * deadline over it so an unreachable database reports "down" instead of
+ * hanging.
+ */
+export declare const readinessProbeAsking: (aQueryTheDatabaseMustAnswer: Effect.Effect<unknown, SqlError>) => {
+    verifyDatabaseAnswers: Effect.Effect<void, DatabaseDidNotAnswerError, never>;
+};

package/dist/postgres/readiness-probe.js

@@ -0,0 +1,33 @@
+import { DatabaseDidNotAnswerError } from '@satorio/machinery/ports';
+import { Duration, Effect } from 'effect';
+/**
+ * Reason reported when the readiness query answers with a failure. A
+ * probe reads `reason` to tell a silent database from a slow one.
+ */
+export const READINESS_REASON_WHEN_THE_DATABASE_STAYS_SILENT = 'database did not answer the readiness query';
+/**
+ * Reason reported when the readiness query times out. A database you can't
+ * reach doesn't always fail fast: the client may keep trying to connect
+ * while the caller waits. Without a deadline the probe would hang instead
+ * of reporting "down", and `/readyz` would hang with it.
+ */
+export const READINESS_REASON_WHEN_THE_QUERY_TIMES_OUT = 'readiness query did not answer within the deadline';
+/**
+ * How long the probe waits for its query before it reports "down".
+ */
+export const READINESS_QUERY_DEADLINE_MILLIS = 2_000;
+/**
+ * Builds a probe around one query the database must answer, with a
+ * deadline over it so an unreachable database reports "down" instead of
+ * hanging.
+ */
+export const readinessProbeAsking = (aQueryTheDatabaseMustAnswer) => ({
+    verifyDatabaseAnswers: aQueryTheDatabaseMustAnswer.pipe(Effect.asVoid, Effect.catchTag('SqlError', (silence) => Effect.logError('readiness query failed', silence).pipe(Effect.andThen(new DatabaseDidNotAnswerError({
+        reason: READINESS_REASON_WHEN_THE_DATABASE_STAYS_SILENT,
+    })))), Effect.timeoutFail({
+        duration: Duration.millis(READINESS_QUERY_DEADLINE_MILLIS),
+        onTimeout: () => new DatabaseDidNotAnswerError({
+            reason: READINESS_REASON_WHEN_THE_QUERY_TIMES_OUT,
+        }),
+    })),
+});