@empire-builder-kit/runtime 1.0.0-beta.9 → 1.0.0-rc.1

package/src/async-work/schedule.js

@@ -0,0 +1,279 @@
+import { __awaiter, __rest } from "tslib";
+import { asyncWorkDigest, asyncWorkIdentity, compareAsyncStrings, failAsyncWork, requireAsyncCursor, requireAsyncIdentifier, requireAsyncInteger, requireAsyncNumber, requireCanonicalAsyncTimestamp, } from './contract.js';
+export const ASYNC_SCHEDULE_VERSION = 1;
+export const ASYNC_BACKFILL_REPORT_VERSION = 1;
+export const ASYNC_BACKFILL_CHECKPOINT_VERSION = 1;
+export function createScheduleDefinition(input) {
+    var _a, _b;
+    if (!['backfill-every-interval', 'catch-up-once', 'skip'].includes(input.missedRunBehavior)) {
+        failAsyncWork('async-input-invalid', '/missedRunBehavior', 'must explicitly be skip, catch-up-once, or backfill-every-interval');
+    }
+    let cadence;
+    if (((_a = input.cadence) === null || _a === void 0 ? void 0 : _a.kind) === 'one-time') {
+        cadence = {
+            at: requireCanonicalAsyncTimestamp(input.cadence.at, '/cadence/at'),
+            kind: 'one-time',
+        };
+    }
+    else if (((_b = input.cadence) === null || _b === void 0 ? void 0 : _b.kind) === 'interval') {
+        cadence = {
+            intervalSeconds: requireAsyncInteger(input.cadence.intervalSeconds, '/cadence/intervalSeconds', 60, 31536000),
+            kind: 'interval',
+        };
+    }
+    else {
+        failAsyncWork('async-input-invalid', '/cadence', 'must be an interval or one-time cadence');
+    }
+    const maximumCatchUpRuns = requireAsyncInteger(input.maximumCatchUpRuns, '/maximumCatchUpRuns', 0, 10000);
+    if (input.missedRunBehavior !== 'skip' && maximumCatchUpRuns === 0) {
+        failAsyncWork('async-input-invalid', '/maximumCatchUpRuns', 'must be positive when missed runs are caught up');
+    }
+    if (typeof input.enabled !== 'boolean') {
+        failAsyncWork('async-input-invalid', '/enabled', 'must explicitly declare schedule state');
+    }
+    return {
+        cadence,
+        dlq: requireAsyncIdentifier(input.dlq, '/dlq'),
+        enabled: input.enabled,
+        maximumCatchUpRuns,
+        missedRunBehavior: input.missedRunBehavior,
+        owner: requireAsyncIdentifier(input.owner, '/owner'),
+        retryAttempts: requireAsyncInteger(input.retryAttempts, '/retryAttempts', 0, 185),
+        scheduleId: requireAsyncIdentifier(input.scheduleId, '/scheduleId'),
+        targetCommand: requireAsyncIdentifier(input.targetCommand, '/targetCommand'),
+        targetVersion: requireAsyncInteger(input.targetVersion, '/targetVersion', 1, Number.MAX_SAFE_INTEGER),
+        timeZone: requireAsyncIdentifier(input.timeZone, '/timeZone'),
+        version: ASYNC_SCHEDULE_VERSION,
+    };
+}
+/**
+ * Computes bounded catch-up intent. The generated AWS adapter owns the
+ * Scheduler expression; handlers receive stable scheduled timestamps and
+ * remain idempotent if Scheduler invokes them more than once.
+ */
+export function planMissedScheduleRuns(input) {
+    const schedule = createScheduleDefinition(input.schedule);
+    const now = requireCanonicalAsyncTimestamp(input.now, '/now');
+    if (!schedule.enabled) {
+        return {
+            outcome: 'disabled',
+            runAt: [],
+            scheduleId: schedule.scheduleId,
+            skippedCount: 0,
+        };
+    }
+    const previous = input.lastCompletedAt
+        ? requireCanonicalAsyncTimestamp(input.lastCompletedAt, '/lastCompletedAt')
+        : undefined;
+    const candidates = [];
+    let latestMissedAt;
+    let missedCount = 0;
+    if (schedule.cadence.kind === 'one-time') {
+        if (Date.parse(schedule.cadence.at) <= Date.parse(now) &&
+            (!previous || Date.parse(previous) < Date.parse(schedule.cadence.at))) {
+            candidates.push(schedule.cadence.at);
+            latestMissedAt = schedule.cadence.at;
+            missedCount = 1;
+        }
+    }
+    else if (previous) {
+        const previousMs = Date.parse(previous);
+        const current = Date.parse(now);
+        const intervalMs = schedule.cadence.intervalSeconds * 1000;
+        missedCount = Math.max(0, Math.floor((current - previousMs - 1) / intervalMs));
+        if (missedCount > 0) {
+            latestMissedAt = new Date(previousMs + missedCount * intervalMs).toISOString();
+            if (schedule.missedRunBehavior === 'catch-up-once') {
+                candidates.push(latestMissedAt);
+            }
+            else if (schedule.missedRunBehavior === 'backfill-every-interval') {
+                const selectedCount = Math.min(missedCount, schedule.maximumCatchUpRuns);
+                for (let offset = 1; offset <= selectedCount; offset += 1) {
+                    candidates.push(new Date(previousMs + offset * intervalMs).toISOString());
+                }
+            }
+        }
+    }
+    if (!latestMissedAt) {
+        return {
+            outcome: 'none',
+            runAt: [],
+            scheduleId: schedule.scheduleId,
+            skippedCount: 0,
+        };
+    }
+    if (schedule.missedRunBehavior === 'skip') {
+        return {
+            latestMissedAt,
+            outcome: 'skipped',
+            runAt: [],
+            scheduleId: schedule.scheduleId,
+            skippedCount: missedCount,
+        };
+    }
+    return {
+        latestMissedAt,
+        outcome: 'caught-up',
+        runAt: candidates,
+        scheduleId: schedule.scheduleId,
+        skippedCount: missedCount - candidates.length,
+    };
+}
+function normalizeBackfillScope(scope) {
+    const from = requireCanonicalAsyncTimestamp(scope.from, '/scope/from');
+    const to = requireCanonicalAsyncTimestamp(scope.to, '/scope/to');
+    if (Date.parse(from) >= Date.parse(to)) {
+        failAsyncWork('async-input-invalid', '/scope', 'from must precede to');
+    }
+    if (!Array.isArray(scope.partitions) ||
+        scope.partitions.length === 0 ||
+        scope.partitions.length > 1000) {
+        failAsyncWork('async-input-invalid', '/scope/partitions', 'must explicitly select from one through 1000 partitions');
+    }
+    const partitions = scope.partitions
+        .map((partition, index) => requireAsyncIdentifier(partition, `/scope/partitions/${index}`))
+        .sort(compareAsyncStrings);
+    if (new Set(partitions).size !== partitions.length) {
+        failAsyncWork('async-input-invalid', '/scope/partitions', 'must not contain duplicates');
+    }
+    return { from, partitions, to };
+}
+export function createBackfillReport(input) {
+    if (!['ordinary', 'protected'].includes(input.approvalClass)) {
+        failAsyncWork('async-input-invalid', '/approvalClass', 'must be ordinary or protected');
+    }
+    const preparedAt = requireCanonicalAsyncTimestamp(input.preparedAt, '/preparedAt');
+    const expiresAt = requireCanonicalAsyncTimestamp(input.expiresAt, '/expiresAt');
+    if (Date.parse(expiresAt) <= Date.parse(preparedAt)) {
+        failAsyncWork('async-input-invalid', '/expiresAt', 'must be later than preparedAt');
+    }
+    const material = {
+        approvalClass: input.approvalClass,
+        concurrency: requireAsyncInteger(input.concurrency, '/concurrency', 1, 1000),
+        estimatedCostUsd: requireAsyncNumber(input.estimatedCostUsd, '/estimatedCostUsd', 0, 10000000),
+        expiresAt,
+        job: requireAsyncIdentifier(input.job, '/job'),
+        maximumItems: requireAsyncInteger(input.maximumItems, '/maximumItems', 1, 10000000),
+        preparedAt,
+        scope: normalizeBackfillScope(input.scope),
+        version: ASYNC_BACKFILL_REPORT_VERSION,
+    };
+    const reportDigest = asyncWorkDigest(material);
+    return Object.assign(Object.assign({}, material), { reportDigest, reportId: asyncWorkDigest({
+            operation: 'bounded-backfill-v1',
+            reportDigest,
+        }) });
+}
+export function runBackfillPage(input) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const now = requireCanonicalAsyncTimestamp(input.now, '/now');
+        const report = input.report;
+        const { reportDigest: ignoredDigest, reportId: ignoredId } = report, material = __rest(report, ["reportDigest", "reportId"]);
+        void ignoredDigest;
+        void ignoredId;
+        const expectedDigest = asyncWorkDigest(material);
+        if (report.version !== ASYNC_BACKFILL_REPORT_VERSION ||
+            report.reportDigest !== expectedDigest ||
+            report.reportId !==
+                asyncWorkDigest({
+                    operation: 'bounded-backfill-v1',
+                    reportDigest: expectedDigest,
+                })) {
+            failAsyncWork('async-report-invalid', '/report', 'digest does not bind the exact backfill scope');
+        }
+        if (Date.parse(now) >= Date.parse(report.expiresAt)) {
+            failAsyncWork('async-report-expired', '/report/expiresAt', 'report expired');
+        }
+        if (report.approvalClass === 'protected' &&
+            (input.approvalId === undefined ||
+                !requireAsyncIdentifier(input.approvalId, '/approvalId'))) {
+            failAsyncWork('async-approval-required', '/approvalId', 'protected backfill requires an attributable approval');
+        }
+        const prior = (_a = input.checkpoint) !== null && _a !== void 0 ? _a : {
+            complete: false,
+            processed: 0,
+            reportDigest: report.reportDigest,
+            version: ASYNC_BACKFILL_CHECKPOINT_VERSION,
+        };
+        if (prior.version !== ASYNC_BACKFILL_CHECKPOINT_VERSION ||
+            prior.reportDigest !== report.reportDigest ||
+            typeof prior.complete !== 'boolean') {
+            failAsyncWork('async-report-invalid', '/checkpoint', 'must belong to this exact backfill report');
+        }
+        const priorProcessed = requireAsyncInteger(prior.processed, '/checkpoint/processed', 0, report.maximumItems);
+        const priorCursor = prior.cursor === undefined
+            ? undefined
+            : requireAsyncCursor(prior.cursor, '/checkpoint/cursor');
+        if (input.cancelled || prior.complete) {
+            return {
+                alreadyApplied: 0,
+                checkpoint: prior,
+                failed: 0,
+                outcome: input.cancelled ? 'cancelled' : 'complete',
+                processed: 0,
+                succeeded: 0,
+            };
+        }
+        const remaining = report.maximumItems - priorProcessed;
+        if (remaining === 0) {
+            return {
+                alreadyApplied: 0,
+                checkpoint: Object.assign(Object.assign({}, prior), { complete: true }),
+                failed: 0,
+                outcome: 'complete',
+                processed: 0,
+                succeeded: 0,
+            };
+        }
+        const limit = Math.min(requireAsyncInteger(input.limit, '/limit', 1, 10000), remaining);
+        const page = yield input.adapter.scan(Object.assign(Object.assign({}, (priorCursor ? { cursor: priorCursor } : {})), { limit, scope: report.scope }));
+        if (!Array.isArray(page.items) || page.items.length > limit) {
+            failAsyncWork('async-adapter-outcome-invalid', '/adapter/scan/items', 'must be an array no larger than the requested page');
+        }
+        const nextCursor = page.nextCursor === undefined
+            ? undefined
+            : requireAsyncCursor(page.nextCursor, '/adapter/scan/nextCursor');
+        const seen = new Set();
+        let succeeded = 0;
+        let alreadyApplied = 0;
+        let failed = 0;
+        for (const [index, item] of page.items.entries()) {
+            const itemId = requireAsyncIdentifier(item === null || item === void 0 ? void 0 : item.itemId, `/adapter/scan/items/${index}/itemId`);
+            if (seen.has(itemId)) {
+                failAsyncWork('async-adapter-outcome-invalid', `/adapter/scan/items/${index}/itemId`, 'must be unique within the page');
+            }
+            seen.add(itemId);
+            const outcome = yield input.adapter.process({
+                idempotencyKey: asyncWorkIdentity('backfill-item-v1', [
+                    report.reportId,
+                    itemId,
+                ]),
+                item,
+                reportId: report.reportId,
+            });
+            if (outcome === 'succeeded')
+                succeeded += 1;
+            else if (outcome === 'already-applied')
+                alreadyApplied += 1;
+            else if (outcome === 'failed')
+                failed += 1;
+            else {
+                failAsyncWork('async-adapter-outcome-invalid', '/adapter/process', 'must be succeeded, already-applied, or failed');
+            }
+        }
+        const processed = page.items.length;
+        const totalProcessed = priorProcessed + processed;
+        const complete = nextCursor === undefined || totalProcessed >= report.maximumItems;
+        const checkpoint = Object.assign(Object.assign({ complete }, (nextCursor && !complete ? { cursor: nextCursor } : {})), { processed: totalProcessed, reportDigest: report.reportDigest, version: ASYNC_BACKFILL_CHECKPOINT_VERSION });
+        return {
+            alreadyApplied,
+            checkpoint: failed > 0 ? prior : checkpoint,
+            failed,
+            outcome: failed > 0 ? 'retry-required' : complete ? 'complete' : 'more',
+            processed,
+            succeeded,
+        };
+    });
+}
+//# sourceMappingURL=schedule.js.map

package/src/async-work/schedule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.js","sourceRoot":"","sources":["../../../../../packages/runtime/src/async-work/schedule.ts"],"names":[],"mappings":"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"}

package/src/async-work/sqs.d.ts

@@ -0,0 +1,133 @@
+export interface RetryPolicyV1 {
+    attemptTimeoutMs: number;
+    baseDelayMs: number;
+    maximumAttempts: number;
+    maximumDelayMs: number;
+    totalTimeoutMs: number;
+}
+export type RetryAttemptResult<TResult> = {
+    outcome: 'succeeded';
+    value: TResult;
+} | {
+    errorCode: string;
+    outcome: 'retryable' | 'terminal';
+};
+export type RetryExecutionResult<TResult> = {
+    attempts: number;
+    outcome: 'succeeded';
+    value: TResult;
+} | {
+    attempts: number;
+    errorCode: string;
+    outcome: 'retry-exhausted' | 'terminal';
+};
+export interface ExecuteWithRetryInput<TResult> {
+    attempt: (input: {
+        attempt: number;
+        signal: AbortSignal;
+    }) => Promise<RetryAttemptResult<TResult>>;
+    now?: () => number;
+    policy: RetryPolicyV1;
+    random?: () => number;
+    sleep?: (milliseconds: number) => Promise<void>;
+}
+/**
+ * Applies a single bounded retry budget with full jitter. SDK retries should
+ * be disabled or included in this declared total attempt budget.
+ */
+export declare function executeWithRetry<TResult>(input: ExecuteWithRetryInput<TResult>): Promise<RetryExecutionResult<TResult>>;
+export interface SqsBatchRecord {
+    body: string;
+    messageId: string;
+}
+export type SqsRecordOutcome = {
+    outcome: 'succeeded';
+} | {
+    errorCode: string;
+    outcome: 'retry' | 'terminal';
+};
+export interface SqsPartialBatchResponse {
+    batchItemFailures: Array<{
+        itemIdentifier: string;
+    }>;
+}
+export interface SqsBatchResultV1 {
+    failed: number;
+    failureMetadata: Array<{
+        errorCode: string;
+        messageId: string;
+        outcome: 'retry' | 'terminal';
+    }>;
+    response: SqsPartialBatchResponse;
+    succeeded: number;
+    total: number;
+}
+/**
+ * Produces AWS Lambda's partial-batch response without ever returning message
+ * bodies. Terminal records remain failed so SQS moves them through the
+ * declared receive count to the DLQ instead of silently dropping them.
+ */
+export declare function processSqsBatch(input: {
+    handler: (record: SqsBatchRecord) => Promise<SqsRecordOutcome>;
+    records: readonly SqsBatchRecord[];
+}): Promise<SqsBatchResultV1>;
+export interface DlqMessageMetadataV1 {
+    messageId: string;
+    receivedAt: string;
+    receiveCount: number;
+    workType: string;
+}
+export interface DlqRedriveScopeV1 {
+    maximumMessages: number;
+    receivedAfter?: string;
+    receivedBefore?: string;
+    workTypes: readonly string[];
+}
+export interface DlqRedriveReportV1 {
+    approvalClass: 'ordinary' | 'protected';
+    expiresAt: string;
+    messageIds: readonly string[];
+    preparedAt: string;
+    queue: string;
+    ratePerSecond: number;
+    reportDigest: string;
+    reportId: string;
+    scope: {
+        maximumMessages: number;
+        receivedAfter?: string;
+        receivedBefore?: string;
+        workTypes: readonly string[];
+    };
+    selectedCount: number;
+    version: 1;
+}
+export declare function createDlqRedriveReport(input: {
+    approvalClass: 'ordinary' | 'protected';
+    expiresAt: string;
+    messages: readonly DlqMessageMetadataV1[];
+    preparedAt: string;
+    queue: string;
+    ratePerSecond: number;
+    scope: DlqRedriveScopeV1;
+}): DlqRedriveReportV1;
+export interface DlqRedriveAdapter {
+    redrive(input: {
+        messageIds: readonly string[];
+        operationId: string;
+        ratePerSecond: number;
+    }): Promise<{
+        acceptedMessageIds: readonly string[];
+    }>;
+}
+export declare function applyDlqRedrive(input: {
+    adapter: DlqRedriveAdapter;
+    approvalId?: string;
+    availableMessageIds: readonly string[];
+    now: string;
+    report: DlqRedriveReportV1;
+}): Promise<{
+    acceptedCount: number;
+    operationId: string;
+    outcome: 'applied' | 'converged';
+    remainingCount: number;
+}>;