@satorio/machinery 0.2.1

package/dist/queue/layer.js

@@ -0,0 +1,58 @@
+import { refusalText } from '@satorio/machinery/core';
+import { QueueMessageProducer, QueueMessageSource, } from '@satorio/machinery/ports';
+import { Effect, Layer, Option } from 'effect';
+import { makeSqsQueueMessageProducer, openSqsSendTransport, queueMessageProducerUnavailableWithoutConfiguration, scopedSqsSendTransport, } from './queue-message-producer.js';
+import { makeSqsQueueMessageSource, openSqsTransport, queueMessageSourceUnavailableWithoutConfiguration, scopedSqsTransport, } from './queue-message-source.js';
+import { configuredQueueUrl, queueConsumerSettings, queueProducerSettings, queueUrlRefusal, } from './settings.js';
+/**
+ * A message source built from environment variables with the given
+ * prefix. With no queue URL set it mounts the loud stand and logs the
+ * one refusal every later receive repeats, so startup carries on and
+ * nothing goes missing in silence. The transport is a parameter, so a
+ * test substitutes its own without touching the wiring.
+ *
+ * @internal
+ */
+export const queueMessageSourceFromEnvironmentLive = (variablePrefix, openTransport) => Layer.unwrapEffect(Effect.gen(function* () {
+    const configured = yield* configuredQueueUrl(variablePrefix);
+    if (Option.isNone(configured)) {
+        const refusal = queueUrlRefusal(variablePrefix);
+        yield* Effect.logError(refusalText(refusal));
+        return Layer.succeed(QueueMessageSource, queueMessageSourceUnavailableWithoutConfiguration(refusal));
+    }
+    return Layer.scoped(QueueMessageSource, Effect.gen(function* () {
+        const settings = yield* queueConsumerSettings(variablePrefix);
+        const transport = yield* scopedSqsTransport(() => openTransport(settings));
+        return makeSqsQueueMessageSource(transport, settings);
+    }));
+}));
+/**
+ * The message source on the real AWS SDK transport, reading the
+ * variables this prefix names.
+ */
+export const sqsQueueMessageSourceLive = (variablePrefix) => queueMessageSourceFromEnvironmentLive(variablePrefix, openSqsTransport);
+/**
+ * A message producer built from environment variables with the given
+ * prefix, mounting the loud stand when no queue URL is set. The
+ * transport is a parameter for the same reason the source's is.
+ *
+ * @internal
+ */
+export const queueMessageProducerFromEnvironmentLive = (variablePrefix, openTransport) => Layer.unwrapEffect(Effect.gen(function* () {
+    const configured = yield* configuredQueueUrl(variablePrefix);
+    if (Option.isNone(configured)) {
+        const refusal = queueUrlRefusal(variablePrefix);
+        yield* Effect.logError(refusalText(refusal));
+        return Layer.succeed(QueueMessageProducer, queueMessageProducerUnavailableWithoutConfiguration(refusal));
+    }
+    return Layer.scoped(QueueMessageProducer, Effect.gen(function* () {
+        const settings = yield* queueProducerSettings(variablePrefix);
+        const transport = yield* scopedSqsSendTransport(() => openTransport(settings));
+        return makeSqsQueueMessageProducer(transport, settings);
+    }));
+}));
+/**
+ * The message producer on the real AWS SDK transport, reading the
+ * variables this prefix names.
+ */
+export const sqsQueueMessageProducerLive = (variablePrefix) => queueMessageProducerFromEnvironmentLive(variablePrefix, openSqsSendTransport);

package/dist/queue/message-codec.d.ts

@@ -0,0 +1,43 @@
+import { type VersionedEventDefinition } from '@satorio/machinery/workflow';
+import { Effect, Schema } from 'effect';
+import { StoredEventEnvelope } from './envelope.js';
+import { QueueMessageNotDecodableError } from './failures.js';
+/**
+ * The envelope as it travels: the JSON text on the wire, read and written
+ * through one schema.
+ */
+export declare const QueueMessageBody: Schema.transform<Schema.SchemaClass<unknown, string, never>, Schema.Struct<{
+    eventId: typeof Schema.NonEmptyTrimmedString;
+    eventType: typeof Schema.NonEmptyTrimmedString;
+    schemaVersion: Schema.brand<Schema.filter<typeof Schema.Int>, "SchemaVersion">;
+    occurredAt: typeof Schema.DateTimeUtc;
+    payload: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+}>>;
+/**
+ * Reads a message body into an envelope, or refuses at the envelope stage and
+ * says what it could not read.
+ */
+export declare const decodeQueueMessageBody: (body: string) => Effect.Effect<StoredEventEnvelope, QueueMessageNotDecodableError>;
+/**
+ * What turns a stored payload of some version into the event a handler works
+ * with.
+ */
+export type PayloadDecoder<A> = (storedVersion: number, payload: unknown) => Effect.Effect<A, QueueMessageNotDecodableError>;
+/**
+ * Builds the payload decoder for one event definition, climbing a stored
+ * payload up to the version this code knows.
+ */
+export declare const payloadDecoderFor: <S extends Schema.Schema.AnyNoContext>(definition: VersionedEventDefinition<S>) => PayloadDecoder<Schema.Schema.Type<S>>;
+/**
+ * Builds the same envelope contract, but for sending: the producer sets
+ * exactly the fields the consumer expects to read.
+ */
+export declare const queueMessageBodyOf: (envelope: {
+    readonly eventId: string;
+    readonly eventType: string;
+    readonly schemaVersion: number;
+    readonly occurredAtIso: string;
+    readonly payload: {
+        readonly [key: string]: unknown;
+    };
+}) => string;

package/dist/queue/message-codec.js

@@ -0,0 +1,33 @@
+import { decodeStoredPayload, } from '@satorio/machinery/workflow';
+import { Effect, Schema } from 'effect';
+import { StoredEventEnvelope } from './envelope.js';
+import { QueueMessageNotDecodableError } from './failures.js';
+/**
+ * The envelope as it travels: the JSON text on the wire, read and written
+ * through one schema.
+ */
+export const QueueMessageBody = Schema.parseJson(StoredEventEnvelope).annotations({
+    identifier: 'QueueMessageBody',
+});
+const decodeBody = Schema.decode(QueueMessageBody);
+/**
+ * Reads a message body into an envelope, or refuses at the envelope stage and
+ * says what it could not read.
+ */
+export const decodeQueueMessageBody = (body) => decodeBody(body).pipe(Effect.mapError((cause) => new QueueMessageNotDecodableError({ stage: 'envelope', cause })));
+/**
+ * Builds the payload decoder for one event definition, climbing a stored
+ * payload up to the version this code knows.
+ */
+export const payloadDecoderFor = (definition) => (storedVersion, payload) => decodeStoredPayload(definition, storedVersion, payload).pipe(Effect.mapError((cause) => new QueueMessageNotDecodableError({ stage: 'payload', cause })));
+/**
+ * Builds the same envelope contract, but for sending: the producer sets
+ * exactly the fields the consumer expects to read.
+ */
+export const queueMessageBodyOf = (envelope) => JSON.stringify({
+    eventId: envelope.eventId,
+    eventType: envelope.eventType,
+    schemaVersion: envelope.schemaVersion,
+    occurredAt: envelope.occurredAtIso,
+    payload: envelope.payload,
+});

package/dist/queue/queue-message-producer.d.ts

@@ -0,0 +1,61 @@
+import { type Refusal } from '@satorio/machinery/core';
+import { type QueueMessageProducerShape } from '@satorio/machinery/ports';
+import { Effect, type Scope } from 'effect';
+import { type QueueProducerSettings } from './settings.js';
+/**
+ * What one send call asks for.
+ *
+ * @internal
+ */
+export interface SqsSendRequest {
+    readonly QueueUrl: string;
+    readonly MessageBody: string;
+}
+/**
+ * The narrowest slice of the SDK the producer uses: put one body on the
+ * queue.
+ *
+ * @internal
+ */
+export interface SqsSendTransport {
+    readonly sendMessage: (request: SqsSendRequest, signal?: AbortSignal) => Promise<unknown>;
+}
+/**
+ * The transport plus the one call that closes the client behind it.
+ *
+ * @internal
+ */
+export interface ClosableSqsSendTransport extends SqsSendTransport {
+    readonly close: () => void;
+}
+/**
+ * The producer over one SQS transport: every send goes to the queue this
+ * prefix named.
+ *
+ * @internal
+ */
+export declare const makeSqsQueueMessageProducer: (transport: SqsSendTransport, settings: QueueProducerSettings) => QueueMessageProducerShape;
+/**
+ * Holds one sending transport open for the length of a scope and closes
+ * it when the scope ends.
+ *
+ * @internal
+ */
+export declare const scopedSqsSendTransport: (openTransport: () => ClosableSqsSendTransport) => Effect.Effect<SqsSendTransport, never, Scope.Scope>;
+/**
+ * Opens the real SQS client. This is the only place the sending half of
+ * the SDK is constructed.
+ *
+ * @internal
+ */
+export declare const openSqsSendTransport: (settings: QueueProducerSettings) => ClosableSqsSendTransport;
+/**
+ * Without a configured queue, the producer does not fail service
+ * startup: it mounts a stand that fails `send` loudly with the same
+ * three-part refusal the mount desk logged. The rest of the service
+ * keeps running, and the procedure that wanted to send says honestly
+ * that the queue is not configured instead of losing what it sent.
+ *
+ * @internal
+ */
+export declare const queueMessageProducerUnavailableWithoutConfiguration: (refusal: Refusal) => QueueMessageProducerShape;

package/dist/queue/queue-message-producer.js

@@ -0,0 +1,52 @@
+import { SendMessageCommand, SQSClient } from '@aws-sdk/client-sqs';
+import { refusalText } from '@satorio/machinery/core';
+import { QueueMessageProducerUnavailableError, } from '@satorio/machinery/ports';
+import { Effect } from 'effect';
+import { sqsClientConfigurationOf, } from './settings.js';
+/**
+ * The producer over one SQS transport: every send goes to the queue this
+ * prefix named.
+ *
+ * @internal
+ */
+export const makeSqsQueueMessageProducer = (transport, settings) => ({
+    send: (body) => Effect.tryPromise({
+        try: (signal) => transport.sendMessage({ QueueUrl: settings.queueUrl, MessageBody: body }, signal),
+        catch: (cause) => new QueueMessageProducerUnavailableError({ operation: 'send', cause }),
+    }).pipe(Effect.asVoid),
+});
+/**
+ * Holds one sending transport open for the length of a scope and closes
+ * it when the scope ends.
+ *
+ * @internal
+ */
+export const scopedSqsSendTransport = (openTransport) => Effect.acquireRelease(Effect.sync(openTransport), (transport) => Effect.sync(() => transport.close()));
+/**
+ * Opens the real SQS client. This is the only place the sending half of
+ * the SDK is constructed.
+ *
+ * @internal
+ */
+export const openSqsSendTransport = (settings) => {
+    const client = new SQSClient(sqsClientConfigurationOf(settings));
+    return {
+        sendMessage: (request, signal) => client.send(new SendMessageCommand(request), signal === undefined ? {} : { abortSignal: signal }),
+        close: () => client.destroy(),
+    };
+};
+/**
+ * Without a configured queue, the producer does not fail service
+ * startup: it mounts a stand that fails `send` loudly with the same
+ * three-part refusal the mount desk logged. The rest of the service
+ * keeps running, and the procedure that wanted to send says honestly
+ * that the queue is not configured instead of losing what it sent.
+ *
+ * @internal
+ */
+export const queueMessageProducerUnavailableWithoutConfiguration = (refusal) => ({
+    send: () => Effect.fail(new QueueMessageProducerUnavailableError({
+        operation: 'send',
+        cause: refusalText(refusal),
+    })),
+});

package/dist/queue/queue-message-source.d.ts

@@ -0,0 +1,93 @@
+import { type Refusal } from '@satorio/machinery/core';
+import { type QueueMessageSourceShape } from '@satorio/machinery/ports';
+import { Effect, type Scope } from 'effect';
+import { type QueueConsumerSettings } from './settings.js';
+/**
+ * One message as SQS hands it over, before anything checks that the
+ * fields a consumer needs are there.
+ *
+ * @internal
+ */
+export interface SqsReceivedMessage {
+    readonly MessageId?: string | undefined;
+    readonly ReceiptHandle?: string | undefined;
+    readonly Body?: string | undefined;
+}
+/**
+ * What one receive call answers with.
+ *
+ * @internal
+ */
+export interface SqsReceiveResult {
+    readonly Messages?: readonly SqsReceivedMessage[] | undefined;
+}
+/**
+ * What one receive call asks for.
+ *
+ * @internal
+ */
+export interface SqsReceiveRequest {
+    readonly QueueUrl: string;
+    readonly MaxNumberOfMessages: number;
+    readonly WaitTimeSeconds: number;
+    readonly VisibilityTimeout: number;
+}
+/**
+ * What one acknowledgement asks for.
+ *
+ * @internal
+ */
+export interface SqsDeleteRequest {
+    readonly QueueUrl: string;
+    readonly ReceiptHandle: string;
+}
+/**
+ * The transport is the narrowest slice of the SDK the source uses:
+ * receive a batch and delete what was taken. A test can supply its own
+ * object of this shape, needing neither the network nor a mock of the
+ * whole client.
+ *
+ * @internal
+ */
+export interface SqsMessageTransport {
+    readonly receiveMessages: (request: SqsReceiveRequest, signal?: AbortSignal) => Promise<SqsReceiveResult>;
+    readonly deleteMessage: (request: SqsDeleteRequest, signal?: AbortSignal) => Promise<unknown>;
+}
+/**
+ * The transport plus the one call that closes the client behind it.
+ *
+ * @internal
+ */
+export interface ClosableSqsTransport extends SqsMessageTransport {
+    readonly close: () => void;
+}
+/**
+ * The message source over one SQS transport: receive a batch with the
+ * poll settings this prefix named, and acknowledge by deleting.
+ *
+ * @internal
+ */
+export declare const makeSqsQueueMessageSource: (transport: SqsMessageTransport, settings: QueueConsumerSettings) => QueueMessageSourceShape;
+/**
+ * Holds one transport open for the length of a scope and closes it when
+ * the scope ends.
+ *
+ * @internal
+ */
+export declare const scopedSqsTransport: (openTransport: () => ClosableSqsTransport) => Effect.Effect<SqsMessageTransport, never, Scope.Scope>;
+/**
+ * Opens the real SQS client. This is the only place the receiving half
+ * of the SDK is constructed.
+ *
+ * @internal
+ */
+export declare const openSqsTransport: (settings: QueueConsumerSettings) => ClosableSqsTransport;
+/**
+ * Without a configured queue, the source does not fail service startup:
+ * it mounts a stand that fails `receive` and `acknowledge` loudly with
+ * the same three-part refusal the mount desk logged. A consumer polling
+ * an unconfigured queue says so on every beat instead of sitting quiet.
+ *
+ * @internal
+ */
+export declare const queueMessageSourceUnavailableWithoutConfiguration: (refusal: Refusal) => QueueMessageSourceShape;

package/dist/queue/queue-message-source.js

@@ -0,0 +1,86 @@
+import { DeleteMessageCommand, ReceiveMessageCommand, SQSClient, } from '@aws-sdk/client-sqs';
+import { refusalText } from '@satorio/machinery/core';
+import { QueueMessageSourceUnavailableError, } from '@satorio/machinery/ports';
+import { Effect } from 'effect';
+import { sqsClientConfigurationOf, } from './settings.js';
+const MISSING_FIELD_NAMES = ['MessageId', 'ReceiptHandle', 'Body'];
+const missingFieldNamesOf = (message) => MISSING_FIELD_NAMES.filter((name) => message[name] === undefined);
+const rawMessageOf = (message) => {
+    const { MessageId, ReceiptHandle, Body } = message;
+    if (MessageId === undefined ||
+        ReceiptHandle === undefined ||
+        Body === undefined) {
+        return Effect.fail(new QueueMessageSourceUnavailableError({
+            operation: 'receive',
+            cause: `SQS returned a message missing required fields: ${missingFieldNamesOf(message).join(', ')}`,
+        }));
+    }
+    return Effect.succeed({
+        messageId: MessageId,
+        receiptHandle: ReceiptHandle,
+        body: Body,
+    });
+};
+/**
+ * The message source over one SQS transport: receive a batch with the
+ * poll settings this prefix named, and acknowledge by deleting.
+ *
+ * @internal
+ */
+export const makeSqsQueueMessageSource = (transport, settings) => ({
+    receive: Effect.tryPromise({
+        try: (signal) => transport.receiveMessages({
+            QueueUrl: settings.queueUrl,
+            MaxNumberOfMessages: settings.maxMessagesPerReceive,
+            WaitTimeSeconds: settings.waitTimeSeconds,
+            VisibilityTimeout: settings.visibilityTimeoutSeconds,
+        }, signal),
+        catch: (cause) => new QueueMessageSourceUnavailableError({ operation: 'receive', cause }),
+    }).pipe(Effect.flatMap((result) => Effect.forEach(result.Messages ?? [], rawMessageOf))),
+    acknowledge: (receiptHandle) => Effect.tryPromise({
+        try: (signal) => transport.deleteMessage({ QueueUrl: settings.queueUrl, ReceiptHandle: receiptHandle }, signal),
+        catch: (cause) => new QueueMessageSourceUnavailableError({
+            operation: 'acknowledge',
+            cause,
+        }),
+    }).pipe(Effect.asVoid),
+});
+/**
+ * Holds one transport open for the length of a scope and closes it when
+ * the scope ends.
+ *
+ * @internal
+ */
+export const scopedSqsTransport = (openTransport) => Effect.acquireRelease(Effect.sync(openTransport), (transport) => Effect.sync(() => transport.close()));
+/**
+ * Opens the real SQS client. This is the only place the receiving half
+ * of the SDK is constructed.
+ *
+ * @internal
+ */
+export const openSqsTransport = (settings) => {
+    const client = new SQSClient(sqsClientConfigurationOf(settings));
+    return {
+        receiveMessages: (request, signal) => client.send(new ReceiveMessageCommand(request), signal === undefined ? {} : { abortSignal: signal }),
+        deleteMessage: (request, signal) => client.send(new DeleteMessageCommand(request), signal === undefined ? {} : { abortSignal: signal }),
+        close: () => client.destroy(),
+    };
+};
+/**
+ * Without a configured queue, the source does not fail service startup:
+ * it mounts a stand that fails `receive` and `acknowledge` loudly with
+ * the same three-part refusal the mount desk logged. A consumer polling
+ * an unconfigured queue says so on every beat instead of sitting quiet.
+ *
+ * @internal
+ */
+export const queueMessageSourceUnavailableWithoutConfiguration = (refusal) => ({
+    receive: Effect.fail(new QueueMessageSourceUnavailableError({
+        operation: 'receive',
+        cause: refusalText(refusal),
+    })),
+    acknowledge: () => Effect.fail(new QueueMessageSourceUnavailableError({
+        operation: 'acknowledge',
+        cause: refusalText(refusal),
+    })),
+});

package/dist/queue/readiness.d.ts

@@ -0,0 +1,78 @@
+import { type GetQueueAttributesCommandInput } from '@aws-sdk/client-sqs';
+import { QueueMessageSourceUnavailableError } from '@satorio/machinery/ports';
+import { type ConfigError, Effect, Option, type Scope } from 'effect';
+import { type QueueConsumerSettings } from './settings.js';
+/**
+ * How long to wait for an SQS reply before treating the queue as
+ * unavailable. Without a deadline, a hung network keeps the readiness
+ * probe open indefinitely — the same class of gap as the Postgres probe.
+ *
+ * @internal
+ */
+export declare const QUEUE_READINESS_DEADLINE_MILLIS = 2000;
+/**
+ * What the probe asks SQS: one attribute of one queue.
+ * `GetQueueAttributes` reads nothing off the queue, unlike receive,
+ * which polls and hides messages while it does.
+ *
+ * @internal
+ */
+export declare const probeRequestOf: (queueUrl: string) => GetQueueAttributesCommandInput;
+/**
+ * The one call the probe makes: read an attribute of the queue. It takes
+ * no message off the queue, unlike receive.
+ *
+ * @internal
+ */
+export interface SqsProbeTransport {
+    readonly describeQueue: (queueUrl: string, signal?: AbortSignal) => Promise<unknown>;
+}
+/**
+ * The probe transport plus the one call that closes the client behind
+ * it.
+ *
+ * @internal
+ */
+export interface ClosableSqsProbeTransport extends SqsProbeTransport {
+    readonly close: () => void;
+}
+/**
+ * Opens the client the probe asks with. `GetQueueAttributes` is the
+ * cheapest call SQS offers: it reads one attribute and takes nothing off
+ * the queue.
+ *
+ * @internal
+ */
+export declare const openSqsProbeTransport: (settings: QueueConsumerSettings) => ClosableSqsProbeTransport;
+/**
+ * Holds the probe's client open for the length of a scope and closes it
+ * when the scope ends — including the scope an interruption ends, which
+ * a `finally` block around a promise does not reach.
+ *
+ * @internal
+ */
+export declare const scopedSqsProbeTransport: (openTransport: () => ClosableSqsProbeTransport) => Effect.Effect<SqsProbeTransport, never, Scope.Scope>;
+/**
+ * Pings queue readiness. The client lives for exactly one call — the
+ * probe runs rarely, so a long-lived client is not worth it. The SDK
+ * call carries Effect's own `abortSignal`, so an interruption cancels
+ * the promise through that same signal: the deadline stops the network
+ * call itself, not just the wait for it. The transport is a parameter,
+ * so a test answers without a network.
+ *
+ * @internal
+ */
+export declare const pingQueueMessageSourceWith: (settings: QueueConsumerSettings, openTransport: (settings: QueueConsumerSettings) => ClosableSqsProbeTransport) => Effect.Effect<void, QueueMessageSourceUnavailableError>;
+/**
+ * Pings queue readiness against the real SQS client.
+ *
+ * @internal
+ */
+export declare const pingQueueMessageSource: (settings: QueueConsumerSettings) => Effect.Effect<void, QueueMessageSourceUnavailableError>;
+/**
+ * The readiness check for a queue, absent when no queue is mounted at all.
+ *
+ * A queue without a URL is never mounted at all, so its readiness probe is
+ * `None`: readyz does not ask about something the application does not have.
+ */
+export declare const queueReadinessCheck: (variablePrefix: string) => Effect.Effect<Option.Option<Effect.Effect<void, QueueMessageSourceUnavailableError>>, ConfigError.ConfigError>;

package/dist/queue/readiness.js

@@ -0,0 +1,86 @@
+import { GetQueueAttributesCommand, SQSClient, } from '@aws-sdk/client-sqs';
+import { QueueMessageSourceUnavailableError } from '@satorio/machinery/ports';
+import { Duration, Effect, Option } from 'effect';
+import { configuredQueueUrl, queueConsumerSettings, sqsClientConfigurationOf, } from './settings.js';
+/**
+ * How long to wait for an SQS reply before treating the queue as
+ * unavailable. Without a deadline, a hung network keeps the readiness
+ * probe open indefinitely — the same class of gap as the Postgres probe.
+ *
+ * @internal
+ */
+export const QUEUE_READINESS_DEADLINE_MILLIS = 2_000;
+const QUEUE_ARN_ATTRIBUTE = 'QueueArn';
+/**
+ * What the probe asks SQS: one attribute of one queue.
+ * `GetQueueAttributes` reads nothing off the queue, unlike receive,
+ * which polls and hides messages while it does.
+ *
+ * @internal
+ */
+export const probeRequestOf = (queueUrl) => ({
+    QueueUrl: queueUrl,
+    AttributeNames: [QUEUE_ARN_ATTRIBUTE],
+});
+/**
+ * Opens the client the probe asks with. `GetQueueAttributes` is the
+ * cheapest call SQS offers: it reads one attribute and takes nothing off
+ * the queue.
+ *
+ * @internal
+ */
+export const openSqsProbeTransport = (settings) => {
+    const client = new SQSClient(sqsClientConfigurationOf(settings));
+    return {
+        describeQueue: (queueUrl, signal) => client.send(new GetQueueAttributesCommand(probeRequestOf(queueUrl)), signal === undefined ? {} : { abortSignal: signal }),
+        close: () => client.destroy(),
+    };
+};
+/**
+ * Holds the probe's client open for the length of a scope and closes it
+ * when the scope ends — including the scope an interruption ends, which
+ * a `finally` block around a promise does not reach.
+ *
+ * @internal
+ */
+export const scopedSqsProbeTransport = (openTransport) => Effect.acquireRelease(Effect.sync(openTransport), (transport) => Effect.sync(() => transport.close()));
+const askWith = (transport, settings) => Effect.tryPromise({
+    try: (signal) => transport.describeQueue(settings.queueUrl, signal),
+    catch: (cause) => new QueueMessageSourceUnavailableError({ operation: 'ping', cause }),
+}).pipe(Effect.asVoid);
+/**
+ * Pings queue readiness. The client lives for exactly one call — the
+ * probe runs rarely, so a long-lived client is not worth it. The SDK
+ * call carries Effect's own `abortSignal`, so an interruption cancels
+ * the promise through that same signal: the deadline stops the network
+ * call itself, not just the wait for it. The transport is a parameter,
+ * so a test answers without a network.
+ *
+ * @internal
+ */
+export const pingQueueMessageSourceWith = (settings, openTransport) => Effect.scoped(Effect.flatMap(scopedSqsProbeTransport(() => openTransport(settings)), (transport) => askWith(transport, settings))).pipe(Effect.timeoutFail({
+    duration: Duration.millis(QUEUE_READINESS_DEADLINE_MILLIS),
+    onTimeout: () => new QueueMessageSourceUnavailableError({
+        operation: 'ping',
+        cause: 'timed out waiting for a response',
+    }),
+}));
+/**
+ * Pings queue readiness against the real SQS client.
+ *
+ * @internal
+ */
+export const pingQueueMessageSource = (settings) => pingQueueMessageSourceWith(settings, openSqsProbeTransport);
+/**
+ * The readiness check for a queue, absent when no queue is mounted at all.
+ *
+ * A queue without a URL is never mounted at all, so its readiness probe is
+ * `None`: readyz does not ask about something the application does not have.
+ */
+export const queueReadinessCheck = (variablePrefix) => Effect.gen(function* () {
+    const configured = yield* configuredQueueUrl(variablePrefix);
+    if (Option.isNone(configured))
+        return Option.none();
+    const settings = yield* queueConsumerSettings(variablePrefix);
+    return Option.some(pingQueueMessageSource(settings));
+});