@friggframework/core 2.0.0--canary.704.79d9a63.0 → 2.0.0--canary.686.e94de4d.0

package/providers/runtime-detection.js

@@ -0,0 +1,124 @@
+/**
+ * Deployed-runtime detection, provider-aware.
+ *
+ * "Deployed" decides whether a missing secret may be tolerated: a deployed
+ * function must fail closed whatever STAGE says, while a laptop, a test run or
+ * a local emulator may run in development mode. Reading only AWS Lambda's
+ * variables (AWS_LAMBDA_FUNCTION_NAME, LAMBDA_TASK_ROOT, AWS_EXECUTION_ENV)
+ * makes every other host look local: a Netlify Function with STAGE=dev would
+ * be treated like `frigg start`.
+ *
+ * So the active provider is asked as well. The provider is the app
+ * definition's `provider` or FRIGG_PROVIDER (which provider-netlify's
+ * generated function entry points set to 'netlify'), resolved to its
+ * @friggframework/provider-<name> package, and its `detect(env)` says whether
+ * the process runs on that platform.
+ *
+ * A local run is never deployed: serverless-offline / `serverless invoke
+ * local` (IS_OFFLINE, IS_LOCAL), `netlify dev` (NETLIFY_DEV=true) and Jest
+ * (JEST_WORKER_ID).
+ */
+const { resolveProvider } = require('./resolve-provider');
+
+function isSet(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+
+function isTrue(value) {
+    if (typeof value !== 'string') return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized === 'true' || normalized === '1';
+}
+
+/**
+ * @param {Object} [env=process.env]
+ * @returns {boolean} true under a local emulator or test runner
+ */
+function isLocalRun(env = process.env) {
+    return (
+        isTrue(env.IS_OFFLINE) ||
+        isTrue(env.IS_LOCAL) ||
+        isTrue(env.NETLIFY_DEV) ||
+        isSet(env.JEST_WORKER_ID)
+    );
+}
+
+/**
+ * The AWS Lambda runtime sets AWS_LAMBDA_FUNCTION_NAME, LAMBDA_TASK_ROOT and
+ * AWS_EXECUTION_ENV (AWS_Lambda_<runtime>).
+ *
+ * @param {Object} [env=process.env]
+ * @returns {boolean}
+ */
+function isAwsLambdaRuntime(env = process.env) {
+    return (
+        isSet(env.AWS_LAMBDA_FUNCTION_NAME) ||
+        isSet(env.LAMBDA_TASK_ROOT) ||
+        String(env.AWS_EXECUTION_ENV ?? '').startsWith('AWS_Lambda_')
+    );
+}
+
+/**
+ * The provider plugin of the running app, or null for AWS (covered by
+ * isAwsLambdaRuntime) or when no provider is named or its package is absent.
+ *
+ * @param {Object} [env=process.env]
+ * @param {Object} [options]
+ * @param {Object} [options.appDefinition]
+ * @param {Function} [options.resolve=resolveProvider]
+ * @returns {Object|null}
+ */
+function resolveActiveProvider(env = process.env, { appDefinition, resolve = resolveProvider } = {}) {
+    const name = appDefinition?.provider || env.FRIGG_PROVIDER;
+    if (!isSet(name) || name === 'aws') return null;
+    try {
+        return resolve(null, { provider: name });
+    } catch (_) {
+        return null;
+    }
+}
+
+/**
+ * True when the process runs as a deployed function on AWS Lambda or on the
+ * active provider's platform, and not under a local emulator or test runner.
+ *
+ * @param {Object} [env=process.env]
+ * @param {Object} [options]
+ * @param {Object} [options.provider] - provider plugin to ask (default: the active one)
+ * @param {Object} [options.appDefinition] - reads `provider`
+ * @returns {boolean}
+ */
+function isDeployedRuntime(env = process.env, { provider, appDefinition } = {}) {
+    if (isLocalRun(env)) return false;
+    if (isAwsLambdaRuntime(env)) return true;
+    if (provider === undefined) {
+        // A named non-AWS provider whose package cannot be loaded (or has no
+        // detect()) cannot say where we run. Fail closed: provider-netlify's
+        // generated entry points set FRIGG_PROVIDER, so treating that as local
+        // would let a deployed function accept unsigned queue messages.
+        const name = appDefinition?.provider || env.FRIGG_PROVIDER;
+        if (isSet(name) && name !== 'aws') {
+            const active = resolveActiveProvider(env, { appDefinition });
+            if (!active || typeof active.detect !== 'function') return true;
+            return askProvider(active, env, true);
+        }
+        return false;
+    }
+    if (!provider || typeof provider.detect !== 'function') return false;
+    return askProvider(provider, env, false);
+}
+
+function askProvider(active, env, onError) {
+    try {
+        return active.detect(env) === true;
+    } catch (_) {
+        return onError;
+    }
+}
+
+module.exports = {
+    isDeployedRuntime,
+    isAwsLambdaRuntime,
+    isLocalRun,
+    resolveActiveProvider,
+};

package/queues/index.js

@@ -1,4 +1,29 @@
 const { QueuerUtil } = require('./queuer-util');
+const { QueueProvider } = require('./queue-provider');
+const { QueueClientInterface } = require('./queue-client-interface');
+const {
+    createQueueProvider,
+    determineProvider,
+    QUEUE_PROVIDERS,
+} = require('./queue-provider-factory');
+const {
+    NetlifyBackgroundProvider,
+    QStashQueueProvider,
+} = require('./providers');
+
 module.exports = {
     QueuerUtil,
+    QueueProvider,
+    QueueClientInterface,
+    createQueueProvider,
+    determineProvider,
+    QUEUE_PROVIDERS,
+    NetlifyBackgroundProvider,
+    QStashQueueProvider,
+    get SqsQueueProvider() {
+        return require('./providers/sqs-queue-provider').SqsQueueProvider;
+    },
+    get SqsQueueClient() {
+        return require('./sqs-queue-client').SqsQueueClient;
+    },
 };

package/queues/providers/index.js

@@ -0,0 +1,11 @@
+const { NetlifyBackgroundProvider } = require('./netlify-background-provider');
+const { QStashQueueProvider } = require('./qstash-queue-provider');
+
+module.exports = {
+    NetlifyBackgroundProvider,
+    QStashQueueProvider,
+    // Lazy: requiring the barrel must not construct anything AWS-specific.
+    get SqsQueueProvider() {
+        return require('./sqs-queue-provider').SqsQueueProvider;
+    },
+};

package/queues/providers/netlify-background-provider.js

@@ -0,0 +1,150 @@
+/**
+ * Netlify Background Functions Queue Provider (Adapter)
+ *
+ * Uses Netlify Background Functions for async job processing.
+ * Background functions have a 15-minute execution limit and are triggered via HTTP POST.
+ * They return 202 immediately while processing continues.
+ *
+ * Queue ID format: The function name or URL path for the background function.
+ * Convention: function files named with '-background' suffix (e.g., 'worker-background.js')
+ *
+ * Authentication: a background function is a public URL and Netlify does
+ * not authenticate its caller, so every message is signed with
+ * FRIGG_QUEUE_SIGNING_SECRET (HMAC-SHA256 over timestamp + raw body, see
+ * ../queue-message-auth.js) and verifyEvent() checks that signature before
+ * the worker parses or dispatches anything. Without the secret, send() and
+ * verifyEvent() refuse, except outside production with
+ * FRIGG_QUEUE_ALLOW_UNSIGNED=true.
+ *
+ * Limitations:
+ * - No built-in retry (must implement manually)
+ * - No dead-letter queue
+ * - No FIFO ordering guarantees
+ * - 15-minute max execution time
+ */
+const { QueueProvider } = require('../queue-provider');
+const {
+    SIGNING_SECRET_ENV,
+    ALLOW_UNSIGNED_ENV,
+    SIGNATURE_HEADER,
+    TIMESTAMP_HEADER,
+    allowsUnsignedMessages,
+    readSigningSecret,
+    signQueueMessage,
+    verifyQueueMessage,
+    readHeader,
+    readRawBody,
+} = require('../queue-message-auth');
+
+class NetlifyBackgroundProvider extends QueueProvider {
+    /**
+     * @param {Object} [options]
+     * @param {string} [options.baseUrl] - site URL (default process.env.URL)
+     * @param {string} [options.signingSecret] - default FRIGG_QUEUE_SIGNING_SECRET, read per call
+     * @param {Object} [options.env] - environment to read (default process.env)
+     * @param {() => number} [options.now] - clock in milliseconds (tests)
+     */
+    constructor(options = {}) {
+        super();
+        // Base URL for triggering background functions (e.g., https://mysite.netlify.app)
+        this.baseUrl = options.baseUrl || process.env.URL || '';
+        this.signingSecret = options.signingSecret;
+        this.env = options.env || process.env;
+        this.now = options.now || Date.now;
+        // verifyEvent() proves an HTTP delivery came from Frigg.
+        this.verifiesHttpDelivery = true;
+    }
+
+    // Read on every call, not in the constructor: secrets may be loaded into
+    // the environment after the provider is built (loadSecrets).
+    _secret() {
+        return this.signingSecret || readSigningSecret(this.env);
+    }
+
+    /**
+     * Send a message by invoking a Netlify Background Function via HTTP POST.
+     *
+     * @param {Object} message - Message payload
+     * @param {string} queueId - Background function path (e.g., '/.netlify/functions/worker-background')
+     */
+    async send(message, queueId) {
+        const url = `${this.baseUrl}${queueId}`;
+        const body = JSON.stringify(message);
+        const headers = { 'Content-Type': 'application/json' };
+
+        const secret = this._secret();
+        if (secret) {
+            Object.assign(headers, signQueueMessage({ body, secret, now: this.now() }));
+        } else if (!allowsUnsignedMessages(this.env)) {
+            // The worker would refuse the message, and a background function
+            // answers 202 either way, so the loss would be silent. Fail here.
+            throw new Error(
+                `${SIGNING_SECRET_ENV} is required to send to a Netlify background function ` +
+                    `(${ALLOW_UNSIGNED_ENV}=true allows unsigned messages outside production only)`
+            );
+        }
+
+        const response = await fetch(url, {
+            method: 'POST',
+            headers,
+            body,
+        });
+
+        if (!response.ok && response.status !== 202) {
+            throw new Error(
+                `Failed to invoke background function at ${queueId}: ${response.status} ${response.statusText}`
+            );
+        }
+
+        return { status: response.status, queueId };
+    }
+
+    /**
+     * Send batch of messages sequentially (background functions are HTTP-triggered).
+     */
+    async batchSend(batch, queueId) {
+        const entries = batch ?? [];
+        const results = [];
+        for (const entry of entries) {
+            const result = await this.send(entry, queueId);
+            results.push(result);
+        }
+        return { results };
+    }
+
+    /**
+     * Check the Frigg signature on an incoming background-function event.
+     *
+     * @param {Object} event - Netlify v1 (Lambda-shaped) event
+     * @returns {Promise<{ ok: boolean, reason?: string, unsigned?: boolean }>}
+     */
+    async verifyEvent(event) {
+        const secret = this._secret();
+        if (!secret) {
+            return allowsUnsignedMessages(this.env)
+                ? { ok: true, unsigned: true }
+                : { ok: false, reason: 'signing_secret_not_configured' };
+        }
+        return verifyQueueMessage({
+            body: readRawBody(event),
+            timestamp: readHeader(event, TIMESTAMP_HEADER),
+            signature: readHeader(event, SIGNATURE_HEADER),
+            secret,
+            now: this.now(),
+        });
+    }
+
+    /**
+     * Parse Netlify Background Function event.
+     * Background functions receive the raw HTTP event body as the event.
+     */
+    parseEvent(event) {
+        const raw = readRawBody(event);
+        const body = raw !== null ? JSON.parse(raw) : event.body;
+
+        // Background functions receive a single message per invocation
+        return [body];
+    }
+}
+
+module.exports = { NetlifyBackgroundProvider };

package/queues/providers/qstash-queue-provider.js

@@ -0,0 +1,219 @@
+/**
+ * QStash Queue Provider (Adapter)
+ *
+ * Upstash QStash implementation - platform-agnostic HTTP-based message queue.
+ * Works on any platform (Netlify, Vercel, AWS, bare metal, etc.)
+ *
+ * Features:
+ * - Configurable retry with exponential backoff
+ * - Dead-letter queue via callbacks
+ * - At-least-once delivery
+ * - Scheduling support (delay, cron)
+ * - Message deduplication
+ *
+ * Requires:
+ * - QSTASH_TOKEN env var (from Upstash console)
+ * - QSTASH_CURRENT_SIGNING_KEY and QSTASH_NEXT_SIGNING_KEY for verification
+ *
+ * Queue ID format: The destination URL that QStash will POST to when delivering the message.
+ *
+ * Verification (verifyEvent), per Upstash's documented scheme and its
+ * @upstash/qstash Receiver: every delivery carries an `Upstash-Signature`
+ * header, a JWT signed HS256 with the current signing key (the next key
+ * during rotation). Its claims are iss "Upstash", sub the destination URL,
+ * exp / nbf / iat, and body = base64url(SHA-256(raw body)). A delivery is
+ * accepted when the JWT verifies with either key, carries exp, nbf, sub and
+ * body, is inside its exp / nbf window, names this request's URL as its sub
+ * (the configured destinationUrl, else the event's rawUrl: a delivery
+ * published to another endpoint cannot be replayed here), and its body claim
+ * matches the body received (trailing '=' padding ignored, as the Receiver
+ * does). A request whose URL cannot be determined is refused. With neither
+ * key configured it is refused, except outside production with
+ * FRIGG_QUEUE_ALLOW_UNSIGNED=true.
+ */
+const crypto = require('crypto');
+const { QueueProvider } = require('../queue-provider');
+const {
+    allowsUnsignedMessages,
+    readHeader,
+    readRawBody,
+} = require('../queue-message-auth');
+
+const QSTASH_API_BASE = 'https://qstash.upstash.io/v2';
+
+/**
+ * @param {*} value
+ * @returns {string|null} the URL in canonical form, or null when it is not one
+ */
+function normalizeUrl(value) {
+    if (typeof value !== 'string' || value.length === 0) return null;
+    try {
+        return new URL(value).href;
+    } catch (_) {
+        return null;
+    }
+}
+
+class QStashQueueProvider extends QueueProvider {
+    constructor(options = {}) {
+        super();
+        this.token =
+            options.token || process.env.QSTASH_TOKEN;
+        this.retries =
+            options.retries !== undefined ? options.retries : 3;
+        this.currentSigningKey = options.currentSigningKey;
+        this.nextSigningKey = options.nextSigningKey;
+        // The URL QStash delivers to. When unset, the JWT's sub is compared
+        // with the request's own URL (event.rawUrl, set by Netlify).
+        this.destinationUrl = options.destinationUrl;
+        this.env = options.env || process.env;
+        this.clockToleranceSeconds = options.clockToleranceSeconds || 0;
+        // verifyEvent() proves an HTTP delivery came from QStash.
+        this.verifiesHttpDelivery = true;
+    }
+
+    // Read per call: secrets may reach the environment after construction.
+    _signingKeys() {
+        return [
+            this.currentSigningKey || this.env.QSTASH_CURRENT_SIGNING_KEY,
+            this.nextSigningKey || this.env.QSTASH_NEXT_SIGNING_KEY,
+        ].filter((key) => typeof key === 'string' && key.length > 0);
+    }
+
+    /**
+     * Verify the Upstash-Signature JWT of a QStash delivery.
+     *
+     * @param {Object} event - Lambda-shaped HTTP event
+     * @returns {Promise<{ ok: boolean, reason?: string, unsigned?: boolean }>}
+     */
+    async verifyEvent(event) {
+        const keys = this._signingKeys();
+        if (keys.length === 0) {
+            return allowsUnsignedMessages(this.env)
+                ? { ok: true, unsigned: true }
+                : { ok: false, reason: 'signing_keys_not_configured' };
+        }
+        const token = readHeader(event, 'upstash-signature');
+        if (!token) return { ok: false, reason: 'missing_signature' };
+        const body = readRawBody(event);
+        if (body === null) return { ok: false, reason: 'missing_body' };
+
+        const jose = require('jose');
+        let payload;
+        for (const key of keys) {
+            try {
+                ({ payload } = await jose.jwtVerify(token, new TextEncoder().encode(key), {
+                    issuer: 'Upstash',
+                    algorithms: ['HS256'],
+                    requiredClaims: ['exp', 'nbf', 'sub', 'body'],
+                    clockTolerance: this.clockToleranceSeconds,
+                }));
+                break;
+            } catch (_) {
+                // try the next key
+            }
+        }
+        if (!payload) return { ok: false, reason: 'invalid_signature' };
+
+        const requestUrl = normalizeUrl(this.destinationUrl || event?.rawUrl);
+        if (!requestUrl) return { ok: false, reason: 'missing_request_url' };
+        if (normalizeUrl(payload.sub) !== requestUrl) {
+            return { ok: false, reason: 'invalid_subject' };
+        }
+        const bodyHash = crypto.createHash('sha256').update(body, 'utf8').digest('base64url');
+        const claimed = typeof payload.body === 'string' ? payload.body.replace(/=+$/, '') : '';
+        if (claimed !== bodyHash.replace(/=+$/, '')) {
+            return { ok: false, reason: 'body_mismatch' };
+        }
+        return { ok: true };
+    }
+
+    /**
+     * Send a message via QStash.
+     *
+     * @param {Object} message - Message payload
+     * @param {string} queueId - Destination URL that QStash will POST to
+     */
+    async send(message, queueId) {
+        if (!this.token) {
+            throw new Error(
+                'QSTASH_TOKEN is required. Get one at https://console.upstash.com'
+            );
+        }
+
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            'Content-Type': 'application/json',
+            'Upstash-Retries': String(this.retries),
+        };
+
+        const response = await fetch(
+            `${QSTASH_API_BASE}/publish/${queueId}`,
+            {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(message),
+            }
+        );
+
+        if (!response.ok) {
+            const errorBody = await response.text().catch(() => 'unknown');
+            throw new Error(
+                `QStash publish failed: ${response.status} ${response.statusText} - ${errorBody}`
+            );
+        }
+
+        return response.json();
+    }
+
+    /**
+     * Send batch of messages via QStash batch API.
+     */
+    async batchSend(batch, queueId) {
+        const entries = batch ?? [];
+        if (!this.token) {
+            throw new Error(
+                'QSTASH_TOKEN is required. Get one at https://console.upstash.com'
+            );
+        }
+
+        const messages = entries.map((entry) => ({
+            destination: queueId,
+            body: JSON.stringify(entry),
+            headers: { 'Content-Type': 'application/json' },
+            retries: this.retries,
+        }));
+
+        const response = await fetch(`${QSTASH_API_BASE}/batch`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(messages),
+        });
+
+        if (!response.ok) {
+            const errorBody = await response.text().catch(() => 'unknown');
+            throw new Error(
+                `QStash batch publish failed: ${response.status} - ${errorBody}`
+            );
+        }
+
+        return response.json();
+    }
+
+    /**
+     * Parse QStash webhook delivery event.
+     * QStash POSTs the message body directly to the destination URL.
+     */
+    parseEvent(event) {
+        const raw = readRawBody(event);
+        const body = raw !== null ? JSON.parse(raw) : event.body;
+
+        // QStash delivers a single message per invocation
+        return [body];
+    }
+}
+
+module.exports = { QStashQueueProvider };

package/queues/providers/sqs-queue-provider.js

@@ -0,0 +1,70 @@
+/**
+ * SQS Queue Provider (Adapter)
+ *
+ * AWS SQS implementation of the QueueProvider port, from
+ * friggframework/frigg#545 (where it lives in @friggframework/provider-aws).
+ * Kept in core here because the AWS SDK is still a core dependency; the SDK
+ * is required on first send, not at module load.
+ */
+const { v4: uuid } = require('uuid');
+const { QueueProvider } = require('../queue-provider');
+const {
+    SqsQueueClient,
+    defaultSqsClientConfig,
+} = require('../sqs-queue-client');
+
+const SQS_BATCH_SIZE = 10;
+
+class SqsQueueProvider extends QueueProvider {
+    /**
+     * @param {Object} [options]
+     * @param {QueueClientInterface} [options.queueClient] - defaults to an SqsQueueClient.
+     */
+    constructor({ queueClient } = {}) {
+        super();
+        this.queueClient =
+            queueClient ||
+            new SqsQueueClient({ clientConfig: defaultSqsClientConfig() });
+    }
+
+    async send(message, queueUrl) {
+        return this.queueClient.sendMessage({
+            MessageBody: JSON.stringify(message),
+            QueueUrl: queueUrl,
+        });
+    }
+
+    async batchSend(batch, queueUrl) {
+        const entries = batch ?? [];
+        let last = {};
+        for (let i = 0; i < entries.length; i += SQS_BATCH_SIZE) {
+            const Entries = entries.slice(i, i + SQS_BATCH_SIZE).map((entry) => ({
+                Id: uuid(),
+                MessageBody: JSON.stringify(entry),
+            }));
+            last = await this.queueClient.sendMessageBatch({
+                Entries,
+                QueueUrl: queueUrl,
+            });
+        }
+        return last;
+    }
+
+    /**
+     * Parse an SQS event: event.Records[].body (JSON string).
+     */
+    parseEvent(event) {
+        const records = event?.Records || [];
+        return records.map((record) => JSON.parse(record.body));
+    }
+
+    /**
+     * SQS events reach a Lambda only through its event source mapping, which
+     * AWS authenticates; there is no public URL to post to.
+     */
+    async verifyEvent() {
+        return { ok: true };
+    }
+}
+
+module.exports = { SqsQueueProvider };

package/queues/queue-client-interface.js

@@ -0,0 +1,55 @@
+/**
+ * Queue Client Interface (Port)
+ *
+ * Defines the contract for low-level queue message operations.
+ * Used by Worker class and QueuerUtil for sending/receiving queue messages.
+ *
+ * Following Frigg's hexagonal architecture pattern:
+ * - Port defines WHAT the service does (contract)
+ * - Adapters implement HOW (AWS SQS, Netlify, QStash, etc.)
+ *
+ * Distinct from QueueProvider which is the higher-level provider for
+ * integration-level queue operations (send/batchSend/parseEvent).
+ * QueueClientInterface is the lower-level "how do I talk to the queue service" port.
+ */
+class QueueClientInterface {
+    /**
+     * Send a single message to a queue
+     *
+     * @param {Object} params
+     * @param {string} params.QueueUrl - Queue endpoint/identifier
+     * @param {string} params.MessageBody - Serialized message body
+     * @param {number} [params.DelaySeconds] - Delay before message becomes visible
+     * @returns {Promise<{MessageId: string}>} Result with message identifier
+     */
+    async sendMessage(params) {
+        throw new Error('Method sendMessage must be implemented by subclass');
+    }
+
+    /**
+     * Send a batch of messages to a queue
+     *
+     * @param {Object} params
+     * @param {string} params.QueueUrl - Queue endpoint/identifier
+     * @param {Array<{Id: string, MessageBody: string}>} params.Entries - Messages to send
+     * @returns {Promise<Object>} Batch send result
+     */
+    async sendMessageBatch(params) {
+        throw new Error(
+            'Method sendMessageBatch must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Resolve a queue name to a URL/endpoint
+     *
+     * @param {Object} params
+     * @param {string} params.QueueName - Queue name to resolve
+     * @returns {Promise<string>} Resolved queue URL/endpoint
+     */
+    async getQueueUrl(params) {
+        throw new Error('Method getQueueUrl must be implemented by subclass');
+    }
+}
+
+module.exports = { QueueClientInterface };