@friggframework/core 2.0.0--canary.522.893db5d.0 → 2.0.0--canary.545.7dc47e9.0

package/index.js

@@ -92,7 +92,12 @@ const utils = require('./utils');
 
 // const {Sync } = require('./syncs/model');
 
-const { QueuerUtil } = require('./queues');
+const {
+    QueuerUtil,
+    QueueProvider,
+    createQueueProvider,
+    QUEUE_PROVIDERS,
+} = require('./queues');
 
 module.exports = {
     // assertions
@@ -187,6 +192,9 @@ module.exports = {
     ModuleFactory,
     // queues
     QueuerUtil,
+    QueueProvider,
+    createQueueProvider,
+    QUEUE_PROVIDERS,
 
     // utils
     ...utils,

package/infrastructure/scheduler/index.js

@@ -5,13 +5,15 @@
  * Follows hexagonal architecture with interface + adapters pattern.
  *
  * Providers:
- * - eventbridge: AWS EventBridge Scheduler (production)
+ * - eventbridge: AWS EventBridge Scheduler (production on AWS)
+ * - netlify: Netlify poll-and-dispatch scheduler (production on Netlify)
  * - mock: In-memory mock scheduler (local development)
  */
 
 const { SchedulerServiceInterface } = require('./scheduler-service-interface');
 const { EventBridgeSchedulerAdapter } = require('./eventbridge-scheduler-adapter');
 const { MockSchedulerAdapter } = require('./mock-scheduler-adapter');
+const { NetlifySchedulerAdapter } = require('./netlify-scheduler-adapter');
 const {
     createSchedulerService,
     SCHEDULER_PROVIDERS,
@@ -25,6 +27,7 @@ module.exports = {
     // Adapters
     EventBridgeSchedulerAdapter,
     MockSchedulerAdapter,
+    NetlifySchedulerAdapter,
 
     // Factory
     createSchedulerService,

package/infrastructure/scheduler/netlify-scheduler-adapter.js

@@ -0,0 +1,173 @@
+/**
+ * Netlify Scheduler Adapter
+ *
+ * Implements SchedulerServiceInterface for Netlify deployments.
+ *
+ * Netlify Scheduled Functions use cron syntax but are defined statically in
+ * netlify.toml or via the @netlify/functions schedule() helper. They cannot
+ * be created dynamically at runtime like EventBridge Scheduler.
+ *
+ * Strategy for one-time scheduled jobs on Netlify:
+ *   1. Store the schedule in the database (same as mock adapter pattern)
+ *   2. A Netlify Scheduled Function runs on a cron interval (e.g., every 5 min)
+ *   3. The cron function queries for due schedules and dispatches them
+ *      to a background function for execution
+ *
+ * This is a "poll-and-dispatch" pattern vs EventBridge's "push" pattern.
+ * Trade-off: slightly less precise timing (up to cron interval delay),
+ * but works on any platform without cloud-specific scheduling APIs.
+ *
+ * For integrations that need the queue provider to dispatch jobs:
+ *   - queueResourceId maps to the background function URL path
+ *   - Payload is stored and forwarded when the cron fires
+ */
+
+const { SchedulerServiceInterface } = require('./scheduler-service-interface');
+
+class NetlifySchedulerAdapter extends SchedulerServiceInterface {
+    /**
+     * @param {Object} options
+     * @param {Object} options.repository - Repository for persisting schedules
+     *   Must implement: save(schedule), delete(scheduleName),
+     *   findByName(scheduleName), findDue(now)
+     * @param {Object} [options.queueProvider] - Queue provider for dispatching due jobs
+     */
+    constructor(options = {}) {
+        super();
+        this.repository = options.repository;
+        this.queueProvider = options.queueProvider;
+
+        if (!this.repository) {
+            console.warn(
+                '[NetlifyScheduler] No repository provided. ' +
+                    'Schedules will be stored in memory (lost on function restart). ' +
+                    'Provide a database-backed repository for production use.'
+            );
+            this._inMemorySchedules = new Map();
+        }
+    }
+
+    async scheduleOneTime({
+        scheduleName,
+        scheduleAt,
+        queueResourceId,
+        payload,
+    }) {
+        if (!scheduleName) throw new Error('scheduleName is required');
+        if (!scheduleAt || !(scheduleAt instanceof Date))
+            throw new Error('scheduleAt must be a valid Date object');
+        if (!queueResourceId) throw new Error('queueResourceId is required');
+
+        const scheduleData = {
+            scheduleName,
+            scheduledAt: scheduleAt.toISOString(),
+            queueResourceId,
+            payload,
+            createdAt: new Date().toISOString(),
+            state: 'PENDING',
+        };
+
+        if (this.repository) {
+            await this.repository.save(scheduleData);
+        } else {
+            this._inMemorySchedules.set(scheduleName, scheduleData);
+        }
+
+        console.log(
+            `[NetlifyScheduler] Scheduled: ${scheduleName} for ${scheduleAt.toISOString()}`
+        );
+
+        return {
+            scheduledJobId: `netlify-schedule-${scheduleName}`,
+            scheduledAt: scheduleAt.toISOString(),
+        };
+    }
+
+    async deleteSchedule(scheduleName) {
+        if (!scheduleName) throw new Error('scheduleName is required');
+
+        if (this.repository) {
+            await this.repository.delete(scheduleName);
+        } else {
+            this._inMemorySchedules.delete(scheduleName);
+        }
+
+        console.log(`[NetlifyScheduler] Deleted schedule: ${scheduleName}`);
+    }
+
+    async getScheduleStatus(scheduleName) {
+        if (!scheduleName) throw new Error('scheduleName is required');
+
+        let schedule;
+        if (this.repository) {
+            schedule = await this.repository.findByName(scheduleName);
+        } else {
+            schedule = this._inMemorySchedules.get(scheduleName);
+        }
+
+        if (!schedule) {
+            return { exists: false };
+        }
+
+        return {
+            exists: true,
+            scheduledAt: schedule.scheduledAt,
+            state: schedule.state,
+        };
+    }
+
+    /**
+     * Process due schedules. Called by the Netlify cron function.
+     *
+     * Finds all schedules where scheduledAt <= now, dispatches them
+     * to the queue provider, and marks them as completed.
+     *
+     * @returns {Promise<{ processed: number, errors: number }>}
+     */
+    async processDueSchedules() {
+        if (!this.repository) {
+            console.warn(
+                '[NetlifyScheduler] Cannot process due schedules without a repository'
+            );
+            return { processed: 0, errors: 0 };
+        }
+
+        const now = new Date();
+        const dueSchedules = await this.repository.findDue(now);
+
+        let processed = 0;
+        let errors = 0;
+
+        for (const schedule of dueSchedules) {
+            try {
+                if (this.queueProvider) {
+                    await this.queueProvider.send(
+                        schedule.payload,
+                        schedule.queueResourceId
+                    );
+                } else {
+                    console.log(
+                        `[NetlifyScheduler] No queue provider — logging payload for: ${schedule.scheduleName}`,
+                        JSON.stringify(schedule.payload)
+                    );
+                }
+
+                await this.repository.delete(schedule.scheduleName);
+                processed++;
+            } catch (error) {
+                console.error(
+                    `[NetlifyScheduler] Error processing schedule ${schedule.scheduleName}:`,
+                    error
+                );
+                errors++;
+            }
+        }
+
+        console.log(
+            `[NetlifyScheduler] Processed ${processed} due schedules, ${errors} errors`
+        );
+        return { processed, errors };
+    }
+}
+
+module.exports = { NetlifySchedulerAdapter };

package/infrastructure/scheduler/scheduler-service-factory.js

@@ -13,10 +13,12 @@
 
 const { EventBridgeSchedulerAdapter } = require('./eventbridge-scheduler-adapter');
 const { MockSchedulerAdapter } = require('./mock-scheduler-adapter');
+const { NetlifySchedulerAdapter } = require('./netlify-scheduler-adapter');
 
 const SCHEDULER_PROVIDERS = {
     EVENTBRIDGE: 'eventbridge',
     MOCK: 'mock',
+    NETLIFY: 'netlify',
 };
 
 const LOCAL_STAGES = ['dev', 'test', 'local'];
@@ -44,9 +46,11 @@ function determineProvider() {
  * Create a scheduler service instance
  *
  * @param {Object} options
- * @param {string} options.provider - Scheduler provider ('eventbridge' or 'mock')
+ * @param {string} options.provider - Scheduler provider ('eventbridge', 'mock', or 'netlify')
  * @param {string} options.region - AWS region (for EventBridge)
  * @param {boolean} options.verbose - Verbose logging (for Mock)
+ * @param {Object} options.repository - Schedule repository (for Netlify - persists schedules)
+ * @param {Object} options.queueProvider - Queue provider (for Netlify - dispatches due jobs)
  * @returns {SchedulerServiceInterface} Implementation of scheduler interface
  */
 function createSchedulerService(options = {}) {
@@ -61,6 +65,11 @@ function createSchedulerService(options = {}) {
             return new MockSchedulerAdapter({
                 verbose: options.verbose,
             });
+        case SCHEDULER_PROVIDERS.NETLIFY:
+            return new NetlifySchedulerAdapter({
+                repository: options.repository,
+                queueProvider: options.queueProvider,
+            });
         default:
             throw new Error(`Unknown scheduler provider: ${provider}`);
     }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.522.893db5d.0",
+    "version": "2.0.0--canary.545.7dc47e9.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -39,9 +39,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.522.893db5d.0",
-        "@friggframework/prettier-config": "2.0.0--canary.522.893db5d.0",
-        "@friggframework/test": "2.0.0--canary.522.893db5d.0",
+        "@friggframework/eslint-config": "2.0.0--canary.545.7dc47e9.0",
+        "@friggframework/prettier-config": "2.0.0--canary.545.7dc47e9.0",
+        "@friggframework/test": "2.0.0--canary.545.7dc47e9.0",
         "@prisma/client": "^6.17.0",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -82,5 +82,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "893db5dc366945920987fecc1e8ab53754f76f63"
+    "gitHead": "7dc47e99f0c313a737dba49babf5c32bad7adae6"
 }

package/queues/index.js

@@ -1,4 +1,23 @@
 const { QueuerUtil } = require('./queuer-util');
+const { QueueProvider } = require('./queue-provider');
+const {
+    createQueueProvider,
+    determineProvider,
+    QUEUE_PROVIDERS,
+} = require('./queue-provider-factory');
+const {
+    SqsQueueProvider,
+    NetlifyBackgroundProvider,
+    QStashQueueProvider,
+} = require('./providers');
+
 module.exports = {
     QueuerUtil,
+    QueueProvider,
+    createQueueProvider,
+    determineProvider,
+    QUEUE_PROVIDERS,
+    SqsQueueProvider,
+    NetlifyBackgroundProvider,
+    QStashQueueProvider,
 };

package/queues/providers/index.js

@@ -0,0 +1,9 @@
+const { SqsQueueProvider } = require('./sqs-queue-provider');
+const { NetlifyBackgroundProvider } = require('./netlify-background-provider');
+const { QStashQueueProvider } = require('./qstash-queue-provider');
+
+module.exports = {
+    SqsQueueProvider,
+    NetlifyBackgroundProvider,
+    QStashQueueProvider,
+};

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

@@ -0,0 +1,76 @@
+/**
+ * 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')
+ *
+ * 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');
+
+class NetlifyBackgroundProvider extends QueueProvider {
+    constructor(options = {}) {
+        super();
+        // Base URL for triggering background functions (e.g., https://mysite.netlify.app)
+        this.baseUrl = options.baseUrl || process.env.URL || '';
+    }
+
+    /**
+     * 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 response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(message),
+        });
+
+        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(entries = [], queueId) {
+        const results = [];
+        for (const entry of entries) {
+            const result = await this.send(entry, queueId);
+            results.push(result);
+        }
+        return { results };
+    }
+
+    /**
+     * Parse Netlify Background Function event.
+     * Background functions receive the raw HTTP event body as the event.
+     */
+    parseEvent(event) {
+        const body =
+            typeof event.body === 'string'
+                ? JSON.parse(event.body)
+                : 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,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 };