@faceteer/cdk/handlers/queue-handler.d.ts

CDK 2.0 constructs and helpers that make composing a Lambda powered service easier.

import { SQSClient } from '@aws-sdk/client-sqs';
import type { SQSHandler, SQSRecord } from 'aws-lambda';
import { AsyncHandler, HandlerDefinition, HandlerTypes } from './handler';
import type { InvalidMessage, Message, ValidatedMessage } from './message';
export interface QueueHandlerDefinition extends HandlerDefinition {
    /**
     * A name for the queue.
     */
    queueName: string;
    /**
     * The largest number of records that AWS Lambda will retrieve from your event source at the time of invoking your function.
     *
     * Valid Range: Minimum value of 1. Maximum value of 10.
     * If `maxBatchingWindow` is configured, this value can go up to 10,000.
     *
     * @default 10
     */
    batchSize?: number;
    /**
     * The maximum amount of time to gather records before invoking the function.
     *
     * Valid Range: Minimum value of 0 minutes. Maximum value of 5 minutes.
     *
     * @default - no batching window. The lambda function will be invoked immediately with the records that are available.
     */
    maxBatchingWindow?: number;
    /**
     * How many times to attempt processing a message
     *
     * @default 10
     */
    maximumAttempts?: number;
    /**
     * The max number of concurrent invocations for the SQSHandler
     */
    maxConcurrency?: number;
}
export type QueueHandlerEvent<T> = {
    /**
     * The raw SQS records
     */
    Records: SQSRecord[];
    /**
     * Messages that have been validated
     */
    ValidMessages: ValidatedMessage<T>[];
    /**
     * Messages that failed to validate
     */
    InvalidMessages: InvalidMessage[];
};
export type DlqHandlerEvent = {
    /**
     * The raw SQS records
     */
    Records: SQSRecord[];
};
export type QueueHandlerResponse<T> = {
    retry: ValidatedMessage<T>[];
} | void;
export interface QueueHandlerOptions<T> extends QueueHandlerDefinition {
    validator?: (messageBody: any) => T;
    sqs: SQSClient;
}
export interface QueueResults<T> {
    Failed: {
        message: Message<T>;
        error: unknown;
    }[];
    Sent: Message<T>[];
}
export type QueueHandlerWithDefinition<T> = SQSHandler & {
    type: HandlerTypes.Queue;
    definition: QueueHandlerDefinition;
    sendMessages: (messages: Message<T>[]) => Promise<QueueResults<T>>;
};
export interface SendMessagesOptions<T> {
    /**
     * How many parallel requests to
     * make to SQS at a time
     */
    concurrentRequestLimit?: number;
    /**
     * A unique key used to deduplicate events before
     * sending them in a batch. Otherwise a hash of the
     * event is used
     */
    uniqueKey?: keyof T;
    /**
     * Randomly delay the message by up to N seconds.
     *
     * Max 900
     */
    randomDelay?: number;
}
/**
 * A function that sends messages to a queue
 */
export type QueueSender<T> = (messages: Message<T>[], options?: SendMessagesOptions<T>) => Promise<QueueResults<T>>;
/**
 * Class to help connecting to and interfacing with
 * sqs driven lambda functions
 */
export declare class QueueManager {
    /**
     * The maximum size for an SQS message
     */
    static readonly MAX_MESSAGE_SIZE_IN_BYTES = 262144;
    /**
     * You can only delay a message in SQS for up
     * to 900 seconds (15 minutes)
     */
    static readonly MAX_DELAY_IN_SECONDS = 900;
    /**
     * ## Get the URI for a Queue and DLQ
     *
     * This is assuming that environment variables are set for the
     * queue names. The environment variables should be the queue name
     * converted to constant case.
     *
     * If SQS_ENDPOINT environment variable is set, it will be used
     * for local development (e.g., ElasticMQ at http://localhost:9324).
     * Otherwise, it constructs standard AWS SQS URLs.
     *
     * @param queueName The name of the queue
     */
    static getUris(queueName: string): {
        uri: string;
        dlq: string;
    };
    /**
     * ## Get the delay in seconds for an SQS message
     *
     * This function will return a exponential back off delay with a maximum
     * of 900 seconds based on how many times the message
     * has been attempted to be processed.
     *
     * If the `randomDelay` option is set it will also generate
     * a random delay between 0 and the value of `randomDelay`
     *
     * The higher value of the random delay or the exponential
     * back off will be chosen
     * @param attempts How many times the message has tried to be processed
     * @param randomDelay How long to randomly delay the message for in seconds
     */
    static getDelay(attempts: number, randomDelay?: number): number;
    /**
     * Generate a bound function that can send events to an SQS queue
     * @param sqs
     * @param queueName
     * @returns
     */
    static generateQueueSender<T>(sqs: SQSClient, queueName: string): QueueSender<T>;
    /**
     * ## Send messages to an SQS queue
     *
     * This function handles things like properly batching messages
     * into groups of 10, and making sure that the overall size
     * of the batch isn't greater than the maximum allowed size
     * @param sqs A configured instance of an Amazon SQS client
     * @param queueName The name of the queue that the events should be sent to
     * @param messages An array of messages that should be sent
     * @param options Options for configuring sending batches to SQS
     */
    static send<T>(sqs: SQSClient, queueName: string, messages: Message<T>[], { concurrentRequestLimit, uniqueKey, randomDelay, }?: SendMessagesOptions<T>): Promise<QueueResults<T>>;
}
export declare function QueueHandler<T = unknown>(options: QueueHandlerOptions<T>, handler: AsyncHandler<QueueHandlerEvent<T>, QueueHandlerResponse<T>>): QueueHandlerWithDefinition<T>;