@friggframework/core 2.0.0--canary.522.893db5d.0 → 2.0.0--canary.545.35013d9.0

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

@@ -0,0 +1,122 @@
+/**
+ * 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.
+ */
+const { QueueProvider } = require('../queue-provider');
+
+const QSTASH_API_BASE = 'https://qstash.upstash.io/v2';
+
+class QStashQueueProvider extends QueueProvider {
+    constructor(options = {}) {
+        super();
+        this.token =
+            options.token || process.env.QSTASH_TOKEN;
+        this.retries =
+            options.retries !== undefined ? options.retries : 3;
+    }
+
+    /**
+     * 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(entries = [], queueId) {
+        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 body =
+            typeof event.body === 'string'
+                ? JSON.parse(event.body)
+                : event.body;
+
+        // QStash delivers a single message per invocation
+        return [body];
+    }
+}
+
+module.exports = { QStashQueueProvider };

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

@@ -0,0 +1,84 @@
+/**
+ * SQS Queue Provider (Adapter)
+ *
+ * AWS SQS implementation of the QueueProvider interface.
+ * Extracted from the original queuer-util.js to support multi-provider architecture.
+ */
+const { v4: uuid } = require('uuid');
+const {
+    SQSClient,
+    SendMessageCommand,
+    SendMessageBatchCommand,
+} = require('@aws-sdk/client-sqs');
+const { QueueProvider } = require('../queue-provider');
+
+const awsConfigOptions = () => {
+    const config = {};
+    if (process.env.IS_OFFLINE) {
+        config.credentials = {
+            accessKeyId: 'test-aws-key',
+            secretAccessKey: 'test-aws-secret',
+        };
+        config.region = 'us-east-1';
+    }
+    if (process.env.AWS_ENDPOINT) {
+        config.endpoint = process.env.AWS_ENDPOINT;
+    }
+    return config;
+};
+
+class SqsQueueProvider extends QueueProvider {
+    constructor() {
+        super();
+        this.sqs = new SQSClient(awsConfigOptions());
+    }
+
+    async send(message, queueUrl) {
+        const command = new SendMessageCommand({
+            MessageBody: JSON.stringify(message),
+            QueueUrl: queueUrl,
+        });
+        return this.sqs.send(command);
+    }
+
+    async batchSend(entries = [], queueUrl) {
+        const buffer = [];
+        const batchSize = 10;
+
+        for (const entry of entries) {
+            buffer.push({
+                Id: uuid(),
+                MessageBody: JSON.stringify(entry),
+            });
+
+            if (buffer.length === batchSize) {
+                const command = new SendMessageBatchCommand({
+                    Entries: buffer,
+                    QueueUrl: queueUrl,
+                });
+                await this.sqs.send(command);
+                buffer.splice(0, buffer.length);
+            }
+        }
+
+        if (buffer.length > 0) {
+            const command = new SendMessageBatchCommand({
+                Entries: buffer,
+                QueueUrl: queueUrl,
+            });
+            return this.sqs.send(command);
+        }
+
+        return {};
+    }
+
+    /**
+     * Parse SQS event format: event.Records[].body (JSON string)
+     */
+    parseEvent(event) {
+        const records = event?.Records || [];
+        return records.map((record) => JSON.parse(record.body));
+    }
+}
+
+module.exports = { SqsQueueProvider };

package/queues/queue-provider-factory.js

@@ -0,0 +1,84 @@
+/**
+ * Queue Provider Factory
+ *
+ * Creates queue provider instances based on appDefinition or environment configuration.
+ *
+ * Priority order for determining provider:
+ * 1. Explicit `provider` option passed to factory
+ * 2. `appDefinition.queue.provider` property
+ * 3. `QUEUE_PROVIDER` environment variable
+ * 4. Default: 'sqs' (backward-compatible with existing AWS deployments)
+ *
+ * Supported providers:
+ * - 'sqs' → AWS SQS (default, existing behavior)
+ * - 'netlify-background' → Netlify Background Functions
+ * - 'qstash' → Upstash QStash (platform-agnostic)
+ */
+const { SqsQueueProvider } = require('./providers/sqs-queue-provider');
+const {
+    NetlifyBackgroundProvider,
+} = require('./providers/netlify-background-provider');
+const { QStashQueueProvider } = require('./providers/qstash-queue-provider');
+
+const QUEUE_PROVIDERS = {
+    SQS: 'sqs',
+    NETLIFY_BACKGROUND: 'netlify-background',
+    QSTASH: 'qstash',
+};
+
+/**
+ * Determine the queue provider based on config hierarchy
+ *
+ * @param {Object} [options]
+ * @param {string} [options.provider] - Explicit provider override
+ * @param {Object} [options.appDefinition] - Frigg app definition object
+ * @returns {string} Provider name
+ */
+function determineProvider(options = {}) {
+    if (options.provider) {
+        return options.provider;
+    }
+
+    if (options.appDefinition?.queue?.provider) {
+        return options.appDefinition.queue.provider;
+    }
+
+    if (process.env.QUEUE_PROVIDER) {
+        return process.env.QUEUE_PROVIDER;
+    }
+
+    return QUEUE_PROVIDERS.SQS;
+}
+
+/**
+ * Create a queue provider instance
+ *
+ * @param {Object} [options]
+ * @param {string} [options.provider] - Queue provider name
+ * @param {Object} [options.appDefinition] - Frigg app definition (reads queue.provider)
+ * @param {Object} [options.providerOptions] - Options passed to the provider constructor
+ * @returns {QueueProvider} Implementation of queue provider interface
+ */
+function createQueueProvider(options = {}) {
+    const provider = determineProvider(options);
+    const providerOptions = options.providerOptions || {};
+
+    switch (provider) {
+        case QUEUE_PROVIDERS.SQS:
+            return new SqsQueueProvider(providerOptions);
+        case QUEUE_PROVIDERS.NETLIFY_BACKGROUND:
+            return new NetlifyBackgroundProvider(providerOptions);
+        case QUEUE_PROVIDERS.QSTASH:
+            return new QStashQueueProvider(providerOptions);
+        default:
+            throw new Error(
+                `Unknown queue provider: '${provider}'. Supported: ${Object.values(QUEUE_PROVIDERS).join(', ')}`
+            );
+    }
+}
+
+module.exports = {
+    createQueueProvider,
+    determineProvider,
+    QUEUE_PROVIDERS,
+};

package/queues/queue-provider.js

@@ -0,0 +1,46 @@
+/**
+ * Queue Provider Interface (Port)
+ *
+ * Defines the contract for queue message sending.
+ * All queue adapters must extend this interface.
+ *
+ * Following Frigg's hexagonal architecture pattern:
+ * - Port defines WHAT the service does (contract)
+ * - Adapters implement HOW (AWS SQS, Netlify Background Functions, QStash, etc.)
+ */
+class QueueProvider {
+    /**
+     * Send a single message to a queue
+     *
+     * @param {Object} message - Message payload (will be JSON-serialized)
+     * @param {string} queueId - Queue identifier (URL, name, or endpoint depending on provider)
+     * @returns {Promise<Object>} Provider-specific response
+     */
+    async send(message, queueId) {
+        throw new Error('Method send must be implemented by subclass');
+    }
+
+    /**
+     * Send a batch of messages to a queue
+     *
+     * @param {Object[]} entries - Array of message payloads
+     * @param {string} queueId - Queue identifier
+     * @returns {Promise<Object>} Provider-specific response
+     */
+    async batchSend(entries, queueId) {
+        throw new Error('Method batchSend must be implemented by subclass');
+    }
+
+    /**
+     * Parse an incoming event into an array of message payloads.
+     * Each provider has its own event shape (SQS Records, HTTP body, etc.)
+     *
+     * @param {Object} event - Raw event from the runtime (Lambda event, HTTP request, etc.)
+     * @returns {Object[]} Array of parsed message payloads
+     */
+    parseEvent(event) {
+        throw new Error('Method parseEvent must be implemented by subclass');
+    }
+}
+
+module.exports = { QueueProvider };