@friggframework/core 2.0.0--canary.686.df38e8e.0 → 2.0.0--canary.710.9045bbc.0

package/queues/providers/index.js

@@ -1,11 +0,0 @@
-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

@@ -1,187 +0,0 @@
-/**
- * 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');
-
-// A queue target is a background function on this site, named by path and
-// nothing else: no scheme, no host, no '//', no '..', no query. Anything
-// else would let a stored or configured queue id send a signed message to
-// another host (a protocol-relative '//host/x' when the base URL is empty)
-// or to a function that is not a queue worker.
-const BACKGROUND_FUNCTION_PATH = /^\/\.netlify\/functions\/[A-Za-z0-9][A-Za-z0-9_-]*-background$/;
-
-function isBackgroundFunctionPath(queueId) {
-    return typeof queueId === 'string' && BACKGROUND_FUNCTION_PATH.test(queueId);
-}
-
-/**
- * The URL a message for `queueId` is POSTed to, or a thrown error.
- * The base must be an absolute http(s) origin; the path must be a
- * background function (see BACKGROUND_FUNCTION_PATH).
- */
-function backgroundFunctionUrl(baseUrl, queueId) {
-    if (!isBackgroundFunctionPath(queueId)) {
-        throw new Error(
-            `Refusing to send to queue id ${JSON.stringify(String(queueId))}: ` +
-                "a Netlify queue id must be '/.netlify/functions/<name>-background'"
-        );
-    }
-    let base;
-    try {
-        base = new URL(baseUrl);
-    } catch {
-        throw new Error(
-            'NetlifyBackgroundProvider needs an absolute site URL (options.baseUrl or the URL environment variable)'
-        );
-    }
-    if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password) {
-        throw new Error('NetlifyBackgroundProvider site URL must be http(s) with no credentials');
-    }
-    return `${base.origin}${queueId}`;
-}
-
-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 = backgroundFunctionUrl(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, isBackgroundFunctionPath, backgroundFunctionUrl };

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

@@ -1,219 +0,0 @@
-/**
- * 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

@@ -1,70 +0,0 @@
-/**
- * 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

@@ -1,55 +0,0 @@
-/**
- * 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 };