@friggframework/core 2.0.0-next.12 → 2.0.0-next.121

package/core/Worker.js

@@ -1,10 +1,13 @@
-const AWS = require('aws-sdk');
+const { SQSClient, GetQueueUrlCommand, SendMessageCommand } = require('@aws-sdk/client-sqs');
 const _ = require('lodash');
 const { RequiredPropertyError } = require('../errors');
 const { get } = require('../assertions');
+const { readQueueDelivery } = require('../queues/queue-delivery');
+const { runMessageScope } = require('./invocation-scope');
+const { getLogger } = require('../logs');
 
-AWS.config.update({ region: process.env.AWS_REGION });
-const sqs = new AWS.SQS({ apiVersion: '2012-11-05' });
+const sqs = new SQSClient({ region: process.env.AWS_REGION });
+const log = getLogger('frigg.worker');
 
 class Worker {
     async getQueueURL(params) {
@@ -12,25 +15,59 @@ class Worker {
         // let params = {
         //     QueueName:  process.env.QueueName
         // };
-        return new Promise((resolve, reject) => {
-            sqs.getQueueUrl(params, (err, data) => {
-                if (err) {
-                    reject(err);
-                } else {
-                    resolve(data.QueueUrl);
-                }
-            });
-        });
+        const command = new GetQueueUrlCommand(params);
+        const data = await sqs.send(command);
+        return data.QueueUrl;
     }
 
     async run(params, context = {}) {
         const records = get(params, 'Records');
+        const batchItemFailures = [];
+
+        console.log(
+            `[Worker] run: processing ${records.length} record(s)`
+        );
 
         for (const record of records) {
-            const runParams = JSON.parse(record.body);
-            this._validateParams(runParams);
-            await this._run(runParams, context);
+            await runMessageScope(record, async () => {
+                // messageId, receiveCount and the event come from the scope.
+                log.debug('Record started', { eventName: 'frigg.worker.record_started' });
+
+                try {
+                    const runParams = JSON.parse(record.body);
+                    this._validateParams(runParams);
+                    await this._run(runParams, context, readQueueDelivery(record));
+                    log.debug('Record succeeded', { eventName: 'frigg.worker.record_succeeded' });
+                } catch (error) {
+                    if (error.isHaltError) {
+                        // HaltError means "discard this message, don't retry".
+                        // Treat as success so SQS deletes it from the queue.
+                        // Logged explicitly — silent discards made prod debugging
+                        // extremely hard; keep this visible.
+                        log.error('Record halted (discarded, no retry)', {
+                            eventName: 'frigg.worker.record_halted',
+                            statusCode: error.statusCode,
+                            error,
+                        });
+                        return;
+                    }
+                    // The message goes back to SQS, so WARN (ADR-048 §4).
+                    log.warn('Record failed, returned for retry', {
+                        eventName: 'frigg.worker.record_failed',
+                        error,
+                    });
+                    batchItemFailures.push({ itemIdentifier: record.messageId });
+                }
+            });
         }
+
+        if (batchItemFailures.length > 0) {
+            console.warn(
+                `[Worker] run: returning ${batchItemFailures.length} batchItemFailure(s) of ${records.length}`
+            );
+        }
+
+        return { batchItemFailures };
     }
 
     async _run(params, context = {}) {
@@ -54,15 +91,9 @@ class Worker {
     }
 
     async sendAsyncSQSMessage(params) {
-        return new Promise((resolve, reject) => {
-            sqs.sendMessage(params, (err, data) => {
-                if (err) {
-                    reject(err);
-                } else {
-                    resolve(data.MessageId);
-                }
-            });
-        });
+        const command = new SendMessageCommand(params);
+        const data = await sqs.send(command);
+        return data.MessageId;
     }
 
     // Throw an exception if the params do not validate

package/core/create-handler.js

@@ -2,9 +2,25 @@
 // REMOVING FOR NOW UNTIL WE ADD WEBPACK BACK IN
 // require('source-map-support').install();
 
-const { connectToDatabase } = require('../database/mongo');
-const { initDebugLog, flushDebugLog } = require('../logs');
+const { getLogger, toSanitizedSurrogate } = require('../logs');
+const {
+    summarizeLambdaEvent,
+    toScopeInvocation,
+    toRequestDetails,
+} = require('../logs/summarize-event');
+const {
+    runInvocationScope,
+    DEFAULT_FLUSH_TIMEOUT_MS,
+} = require('./invocation-scope');
 const { secretsToEnv } = require('./secrets-to-env');
+const { parametersToEnv } = require('./parameters-to-env');
+const {
+    getTelemetry,
+    getUsageRollupSubscriber,
+    getPluginTelemetrySubscribers,
+} = require('../telemetry/telemetry-runtime');
+
+const log = getLogger('frigg.handler');
 
 const createHandler = (optionByName = {}) => {
     const {
@@ -12,6 +28,9 @@ const createHandler = (optionByName = {}) => {
         isUserFacingResponse = true,
         method,
         shouldUseDatabase = true,
+        telemetry,
+        flushTimeoutMs = DEFAULT_FLUSH_TIMEOUT_MS,
+        usageRollup,
     } = optionByName;
 
     if (!method) {
@@ -19,50 +38,114 @@ const createHandler = (optionByName = {}) => {
     }
 
     return async (event, context) => {
-        try {
-            initDebugLog(eventName, event);
+        const eventSummary = summarizeLambdaEvent(event);
+        const activeTelemetry = telemetry || getTelemetry();
+        const activeUsageRollup =
+            usageRollup !== undefined
+                ? usageRollup
+                : getUsageRollupSubscriber();
 
-            const requestMethod = event.httpMethod;
-            const requestPath = event.path;
-            if (requestMethod && requestPath) {
-                console.info(`${requestMethod} ${requestPath}`);
-            }
+        // Wire adopter-declared telemetry subscribers once per cold start.
+        // Memoized in the singleton, so this is a cheap
+        // no-op after the first invocation.
+        getPluginTelemetrySubscribers();
 
-            // If enabled (i.e. if SECRET_ARN is set in process.env) Fetch secrets from AWS Secrets Manager, and set them as environment variables.
-            await secretsToEnv();
+        const scopeFields = {
+            requestId: context?.awsRequestId,
+            handlerName: eventName,
+            method: eventSummary.method,
+            route: eventSummary.route,
+            routeKey: eventSummary.routeKey,
+            invocation: toScopeInvocation(eventSummary),
+        };
+        // Path, query keys and header names go only on the entry and failure
+        // records; the logger adds them to the scope's invocation.
+        const requestDetails = toRequestDetails(eventSummary);
 
-            // Helps mongoose reuse the connection.  Lowers response times.
-            context.callbackWaitsForEmptyEventLoop = false;
+        return runInvocationScope(
+            scopeFields,
+            async () => {
+                try {
+                    log.info('Handler invoked', {
+                        eventName: 'frigg.handler.invoked',
+                        invocation: requestDetails,
+                    });
 
-            if (shouldUseDatabase) {
-                await connectToDatabase();
-            }
+                    // If enabled (i.e. if SECRET_ARN is set in process.env) Fetch secrets from AWS Secrets Manager, and set them as environment variables.
+                    await secretsToEnv();
 
-            // Run the Lambda
-            return await method(event, context);
-        } catch (error) {
-            flushDebugLog(error);
-
-            // Don't leak implementation details to end users.
-            if (isUserFacingResponse) {
-                return {
-                    statusCode: 500,
-                    body: JSON.stringify({
-                        error: 'An Internal Error Occurred',
-                    }),
-                };
-            }
+                    // If enabled (i.e. if SSM_PARAMETER_PREFIX and FRIGG_SSM_OFFLOADED_KEYS are set) fetch offloaded params from SSM Parameter Store into process.env.
+                    await parametersToEnv();
 
-            // Handle server-to-server responses.
+                    // Lazy-required so DB-free handlers never load the Prisma client.
+                    if (shouldUseDatabase) {
+                        const { connectPrisma } = require('../database/prisma');
+                        await connectPrisma();
+                    }
 
-            // Halt errors are logged but suceed and won't be retried.
-            if (error.isHaltError === true) {
-                return;
-            }
+                    // Helps reuse the database connection.  Lowers response times.
+                    context.callbackWaitsForEmptyEventLoop = false;
 
-            // Here we can just rethrow and let AWS build the response.
-            throw error;
-        }
+                    // Run the Lambda
+                    return await method(event, context);
+                } catch (error) {
+                    // Allow client-safe errors to pass through with their actual message
+                    if (isUserFacingResponse && error.isClientSafe === true) {
+                        const statusCode = error.statusCode || 400;
+                        log.warn('Request rejected', {
+                            eventName: 'frigg.handler.rejected',
+                            statusCode,
+                            error,
+                        });
+                        return {
+                            statusCode,
+                            body: JSON.stringify({
+                                error: error.message,
+                            }),
+                        };
+                    }
+
+                    // Server-to-server: halt errors succeed and won't be
+                    // retried, so the halt itself is the failure record.
+                    if (!isUserFacingResponse && error.isHaltError === true) {
+                        log.error('Handler halted', {
+                            eventName: 'frigg.handler.halted',
+                            invocation: requestDetails,
+                            error,
+                        });
+                        return;
+                    }
+
+                    log.error('Handler failed', {
+                        eventName: 'frigg.handler.failed',
+                        invocation: requestDetails,
+                        error,
+                    });
+
+                    // Don't leak implementation details to end users.
+                    if (isUserFacingResponse) {
+                        return {
+                            statusCode: 500,
+                            body: JSON.stringify({
+                                error: 'An Internal Error Occurred',
+                            }),
+                        };
+                    }
+
+                    // The Lambda runtime writes a rethrown error itself, so
+                    // rethrow a sanitized copy (ADR-048 §6 item 11).
+                    throw toSanitizedSurrogate(error);
+                }
+            },
+            {
+                telemetry: activeTelemetry,
+                usageRollup: activeUsageRollup,
+                eventSummary,
+                shouldUseDatabase,
+                flushTimeoutMs,
+                context,
+            }
+        );
     };
 };
 

package/core/index.js

@@ -2,5 +2,12 @@ const { Delegate } = require('./Delegate');
 const { Worker } = require('./Worker');
 const { loadInstalledModules } = require('./load-installed-modules');
 const { createHandler } = require('./create-handler');
+const { runInvocationScope } = require('./invocation-scope');
 
-module.exports = { Delegate, Worker, loadInstalledModules, createHandler };
+module.exports = {
+    Delegate,
+    Worker,
+    loadInstalledModules,
+    createHandler,
+    runInvocationScope,
+};

package/core/invocation-scope.js

@@ -0,0 +1,225 @@
+const { runInContext, LOGGER_SCOPE_KEY } = require('../logs/context');
+const { summarizeMessageBody } = require('../logs/summarize-event');
+const { flushSinks, hasFlushableSinks } = require('../logs/logger-runtime');
+
+// Bounds the tail latency telemetry adds to every warm invocation. Kept low so
+// an unreachable OTLP endpoint (e.g. a VPC Lambda with no NAT/egress) costs at
+// most this, not multiple seconds. Override with OTEL_FLUSH_TIMEOUT_MS.
+const DEFAULT_FLUSH_TIMEOUT_MS =
+    Number(process.env.OTEL_FLUSH_TIMEOUT_MS) || 500;
+
+// Time kept back from the Lambda deadline, so a slow flush never becomes a
+// Lambda timeout.
+const FLUSH_MARGIN_MS = 50;
+
+// setTimeout fires at once for a delay above this.
+const MAX_TIMER_MS = 2 ** 31 - 1;
+
+/**
+ * Fold the invocation's buffered usage counters into the durable store, then
+ * clear the buffer. On an SQS redelivery (ApproximateReceiveCount > 1) we
+ * DISCARD rather than flush — the prior delivery already counted, and the usage
+ * accuracy contract is "approximate, skip obvious redeliveries". Fully guarded.
+ */
+async function flushUsageRollup(subscriber, eventSummary, shouldUseDatabase) {
+    if (!subscriber) return;
+    try {
+        // Persisting usage requires a DB connection. DB-free handlers (e.g. the
+        // webhook-receipt route) never called connectPrisma, so drop the buffer
+        // instead of issuing a connectionless Prisma write.
+        if (!shouldUseDatabase) {
+            subscriber.discard();
+            return;
+        }
+        // Discard only when EVERY record in the batch is a redelivery. The buffer
+        // is invocation-scoped (not per-message), so discarding on *any*
+        // redelivery would drop the fresh records' counts too (silent
+        // under-count). For a mixed batch we flush: preserving fresh counts and
+        // at worst re-counting the one redelivered record is strictly better than
+        // losing fresh data for an approximate store. (Integration queue workers
+        // are batchSize:1 today, so a batch is all-or-nothing; this keeps it
+        // correct if batchSize is ever raised.)
+        const records = Array.isArray(eventSummary?.records)
+            ? eventSummary.records
+            : [];
+        const allRedelivered =
+            records.length > 0 &&
+            records.every((r) => Number(r.receiveCount) > 1);
+        if (allRedelivered) {
+            subscriber.discard();
+        } else {
+            await subscriber.flush();
+        }
+    } catch (_) {
+        // Usage rollup must never break the handler.
+    }
+}
+
+function isTelemetryEnabled(telemetry) {
+    try {
+        return Boolean(
+            telemetry &&
+                typeof telemetry.isEnabled === 'function' &&
+                telemetry.isEnabled()
+        );
+    } catch (_) {
+        return false;
+    }
+}
+
+/**
+ * Flush telemetry before the Lambda container freezes. Because
+ * `callbackWaitsForEmptyEventLoop=false` stops the event loop the moment the
+ * handler returns, OTel's timer-driven batch processors would never fire — so
+ * spans/metrics must be flushed here. No timer of its own: the caller bounds it
+ * with `withDeadline`. Fully guarded, so a flush failure never breaks the
+ * handler.
+ */
+async function flushTelemetry(telemetry, { signal } = {}) {
+    if (!isTelemetryEnabled(telemetry) || signal?.aborted) return;
+    try {
+        await telemetry.forceFlush();
+    } catch (_) {
+        // Telemetry flush must never break the handler.
+    }
+}
+
+/**
+ * Run `fn(signal)` for at most `ms`. Owns the only timer and clears it when the
+ * work settles. Aborts the signal at the deadline. Never rejects, and a late
+ * rejection of the work is swallowed.
+ */
+function withDeadline(ms, fn) {
+    const controller = new AbortController();
+    return new Promise((resolve) => {
+        let timer;
+        const finish = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        timer = setTimeout(() => {
+            controller.abort();
+            finish();
+        }, Math.min(ms, MAX_TIMER_MS));
+        let work;
+        try {
+            work = Promise.resolve(fn(controller.signal));
+        } catch (_) {
+            work = Promise.resolve();
+        }
+        work.then(finish, finish);
+    });
+}
+
+function remainingTimeMs(context) {
+    try {
+        const remaining = context?.getRemainingTimeInMillis?.();
+        return typeof remaining === 'number' ? remaining : Infinity;
+    } catch (_) {
+        return Infinity;
+    }
+}
+
+async function flushInvocation({
+    telemetry,
+    usageRollup,
+    eventSummary,
+    shouldUseDatabase,
+    flushTimeoutMs,
+    context,
+}) {
+    // ADR-048 §11: the deadline is fixed at flush start. The usage rollup
+    // emits no telemetry, so it runs in parallel with no bound of its own.
+    const deadline = Math.min(
+        flushTimeoutMs,
+        remainingTimeMs(context) - FLUSH_MARGIN_MS
+    );
+    await Promise.all([
+        flushUsageRollup(usageRollup, eventSummary, shouldUseDatabase),
+        flushBounded(telemetry, deadline),
+    ]);
+}
+
+function flushBounded(telemetry, deadline) {
+    const flushes = [];
+    if (isTelemetryEnabled(telemetry)) {
+        flushes.push((signal) => flushTelemetry(telemetry, { signal }));
+    }
+    if (hasFlushableSinks()) {
+        flushes.push((signal) => flushSinks({ signal }));
+    }
+    if (!flushes.length || !(deadline > 0)) return undefined;
+    return withDeadline(deadline, (signal) =>
+        Promise.allSettled(flushes.map((flush) => flush(signal)))
+    );
+}
+
+/**
+ * Open the logger scope for one invocation, run `fn` inside it, then flush.
+ * `fields` (requestId, handlerName, method, route, routeKey, invocation, ...)
+ * go into the scope's logger sub-object and never reach the telemetry bus.
+ */
+async function runInvocationScope(fields, fn, opts = {}) {
+    const {
+        telemetry,
+        usageRollup,
+        eventSummary,
+        shouldUseDatabase = true,
+        flushTimeoutMs = DEFAULT_FLUSH_TIMEOUT_MS,
+        context,
+    } = opts;
+    return runInContext({ [LOGGER_SCOPE_KEY]: { ...(fields || {}) } }, async () => {
+        try {
+            return await fn();
+        } finally {
+            // Every step is guarded, so a flush never changes the result.
+            await flushInvocation({
+                telemetry,
+                usageRollup,
+                eventSummary,
+                shouldUseDatabase,
+                flushTimeoutMs,
+                context,
+            });
+        }
+    });
+}
+
+function toCount(value) {
+    const count = Number(value);
+    return value !== undefined && value !== null && Number.isFinite(count)
+        ? count
+        : undefined;
+}
+
+/**
+ * Open the logger scope for one SQS message: messageId, receiveCount and the
+ * Frigg ids the body carries. No flush; the invocation scope owns that.
+ */
+function runMessageScope(record, fn) {
+    const { event, processId, integrationId } = summarizeMessageBody(
+        record?.body
+    );
+    return runInContext(
+        {
+            [LOGGER_SCOPE_KEY]: {
+                messageId: record?.messageId,
+                receiveCount: toCount(record?.attributes?.ApproximateReceiveCount),
+                integrationEvent: event,
+                processId,
+                integrationId,
+            },
+        },
+        fn
+    );
+}
+
+module.exports = {
+    runInvocationScope,
+    runMessageScope,
+    withDeadline,
+    flushTelemetry,
+    flushUsageRollup,
+    FLUSH_MARGIN_MS,
+    DEFAULT_FLUSH_TIMEOUT_MS,
+};