sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ SQS/ QueueEventSource.ts

import * as Binding from "alchemy/Binding";
import type * as lambda from "aws-lambda";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import type { Queue } from "./Queue.ts";

export type SQSRecord = lambda.SQSRecord;

export type SQSEvent = lambda.SQSEvent;

export interface MessagesProps extends QueueEventSourceProps {
  /**
   * How long each `ReceiveMessage` long-polls for messages when using the
   * process (run) path (e.g. `"20 seconds"`). Rounded to whole seconds on
   * the wire.
   * @default 20 seconds
   */
  waitTime?: Duration.Input;
  /**
   * Maximum number of messages to receive per poll when using the process (run) path.
   * @default 10
   */
  maxNumberOfMessages?: number;
}

/**
 * Lambda's partial-batch response for SQS. Every message listed in
 * `batchItemFailures` (by `itemIdentifier` = `messageId`) is retried; every
 * other message in the batch is deleted.
 */
export type SQSBatchResponse = lambda.SQSBatchResponse;

/**
 * Handler for one delivered batch of SQS messages: receives the
 * {@link SQSEvent} and returns Lambda's {@link SQSBatchResponse} (or `void`
 * when every message succeeded). A failure or defect retries the whole batch.
 */
export type QueueMessagesHandler<E = never, Req = never> = (
  event: SQSEvent,
) => Effect.Effect<SQSBatchResponse | void, E, Req>;

/**
 * Subscribe an Effect handler to batches of messages delivered from an SQS
 * {@link Queue}.
 *
 * The handler receives the {@link SQSEvent} and returns Lambda's
 * {@link SQSBatchResponse}: list the `messageId` of each message that failed
 * in `batchItemFailures` and only those are retried. Return `void` when every
 * message succeeded. If the handler fails, the whole batch is retried.
 *
 * Each batch runs inside a `process <queue>` span (`SpanKind.CONSUMER`) linked
 * to the `traceparent` message attribute of each message that carries one.
 *
 * @param queue The SQS queue to consume messages from.
 * @param props Optional event-source configuration.
 * @param process The batch handler (last argument).
 *
 * @example Report only the failed messages
 * ```typescript
 * yield* SQS.consumeQueueMessages(
 *   queue,
 *   Effect.fn(function* (event) {
 *     const failed = yield* Effect.filter(
 *       event.Records,
 *       (record) =>
 *         Effect.try(() => JSON.parse(record.body)).pipe(
 *           Effect.flatMap((order) => putItem({ Item: { id: { S: order.id } } })),
 *           Effect.as(false),
 *           Effect.catchCause(() => Effect.succeed(true)),
 *         ),
 *       { concurrency: "unbounded" },
 *     );
 *     return {
 *       batchItemFailures: failed.map((record) => ({ itemIdentifier: record.messageId })),
 *     };
 *   }),
 * );
 * ```
 *
 * @example Process the whole batch at once
 * ```typescript
 * const sink = yield* SQS.QueueSink(results);
 *
 * yield* SQS.consumeQueueMessages(
 *   queue,
 *   { batchSize: 10 },
 *   Effect.fn(function* (event) {
 *     // a failure retries the whole batch
 *     yield* Stream.fromIterable(event.Records).pipe(
 *       Stream.map((record) => ({ MessageBody: record.body })),
 *       Stream.run(sink),
 *     );
 *   }),
 * );
 * ```
 */
export function consumeQueueMessages<Q extends Queue, E = never, Req = never, ResourceReq = never>(
  queue: Q | Effect.Effect<Q, never, ResourceReq>,
  process: QueueMessagesHandler<E, Req>,
): Effect.Effect<void, never, QueueEventSource | ResourceReq>;
export function consumeQueueMessages<Q extends Queue, E = never, Req = never, ResourceReq = never>(
  queue: Q | Effect.Effect<Q, never, ResourceReq>,
  props: MessagesProps,
  process: QueueMessagesHandler<E, Req>,
): Effect.Effect<void, never, QueueEventSource | ResourceReq>;
export function consumeQueueMessages<Q extends Queue, E = never, Req = never, ResourceReq = never>(
  queue: Q | Effect.Effect<Q, never, ResourceReq>,
  propsOrProcess: MessagesProps | QueueMessagesHandler<E, Req>,
  maybeProcess?: QueueMessagesHandler<E, Req>,
): Effect.Effect<void, never, QueueEventSource | ResourceReq> {
  const [props, process] =
    typeof propsOrProcess === "function"
      ? [{} as MessagesProps, propsOrProcess]
      : [propsOrProcess, maybeProcess!];
  // Accept the queue or the Effect that declares it, like bindings do.
  const resolved = Effect.isEffect(queue) ? queue : Effect.succeed(queue);
  return resolved.pipe(
    Effect.flatMap((value) => QueueEventSource.use((source) => source(value, props, process))),
  );
}

/**
 * Event source connecting an SQS {@link Queue} to the hosting compute
 * (Lambda function or ServerHost process).
 *
 * The contract is a `Binding.Service`; the host-specific implementation
 * layers are `Lambda.QueueEventSource` (event-source mapping + runtime
 * dispatch) and `AWS.Server.SQSQueueEventSource` (long-poll receive loop).
 * Consume it through the {@link consumeQueueMessages} helper.
 * ### Consuming a Queue
 * **Example:** Consume Messages in a Lambda Function
 * ```typescript
 * export default WorkerFunction.make(
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const queue = yield* SQS.Queue("Jobs");
 *
 *     // registers the event-source mapping and the runtime dispatcher
 *     yield* SQS.consumeQueueMessages(
 *       queue,
 *       { batchSize: 10 },
 *       Effect.fn(function* (event) {
 *         for (const record of event.Records) {
 *           yield* Effect.log(record.body);
 *         }
 *       }),
 *     );
 *   }).pipe(Effect.provide(Lambda.QueueEventSource)),
 * );
 * ```
 *
 * @binding
 */
export interface QueueEventSource extends Binding.Service<
  QueueEventSource,
  "AWS.SQS.QueueEventSource",
  QueueEventSourceService
> {}

export const QueueEventSource = Binding.Service<QueueEventSource>("AWS.SQS.QueueEventSource");

export interface QueueEventSourceProps {
  /**
   * The maximum number of records in each batch that Lambda pulls from the queue.
   * @default 10
   */
  batchSize?: number;
  /**
   * The maximum amount of time that Lambda spends gathering records before
   * invoking the function (e.g. `"5 seconds"`). Rounded to whole seconds on
   * the wire.
   * @default 0
   */
  maximumBatchingWindow?: Duration.Input;
}

export type QueueEventSourceService = <E = never, Req = never>(
  queue: Queue,
  props: MessagesProps,
  process: QueueMessagesHandler<E, Req>,
) => Effect.Effect<void, never, never>;