@friggframework/core 2.0.0--canary.680.daae24e.0 → 2.0.0--canary.686.e94de4d.0

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

@@ -0,0 +1,216 @@
+/**
+ * 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');
+
+// The one queue worker every Netlify deployment has (provider-netlify's
+// worker-background function); it dispatches by integrationName.
+const DEFAULT_WORKER_PATH = '/.netlify/functions/worker-background';
+const DEFAULT_LEASE_MS = 5 * 60 * 1000;
+
+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
+     * @param {number} [options.leaseMs] - how long a claimed (PROCESSING) job
+     *   is held before another tick may take it again (default 5 minutes,
+     *   well past a Netlify scheduled function's 60-second limit)
+     */
+    constructor(options = {}) {
+        super();
+        this.repository = options.repository;
+        this.queueProvider = options.queueProvider;
+        this.leaseMs = options.leaseMs ?? DEFAULT_LEASE_MS;
+
+        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();
+        }
+    }
+
+    /**
+     * Where a due job is sent. Netlify has no per-integration queues, so an
+     * SQS-style queue URL (often unset here) maps to the worker function;
+     * a function path is kept as given.
+     *
+     * @param {string} [queueUrl]
+     * @returns {string} a path NetlifyBackgroundProvider.send() accepts
+     */
+    toQueueResourceId(queueUrl) {
+        return typeof queueUrl === 'string' && queueUrl.startsWith('/')
+            ? queueUrl
+            : DEFAULT_WORKER_PATH;
+    }
+
+    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, skipped: 0 };
+        }
+
+        const now = new Date();
+        const lease = { leaseMs: this.leaseMs };
+        const dueSchedules = await this.repository.findDue(now, lease);
+
+        let processed = 0;
+        let errors = 0;
+        let skipped = 0;
+
+        for (const schedule of dueSchedules) {
+            try {
+                // Claim before dispatch. Two overlapping ticks can both see
+                // the row in findDue; only the one whose conditional update
+                // wins sends it. A repository without claim() (a custom one)
+                // keeps the old unconditional PROCESSING write.
+                const claimed =
+                    typeof this.repository.claim === 'function'
+                        ? await this.repository.claim(schedule.scheduleName, now, lease)
+                        : (await this.repository.save({ ...schedule, state: 'PROCESSING' }), true);
+                if (!claimed) {
+                    skipped++;
+                    continue;
+                }
+
+                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
+                );
+                // Mark as FAILED so it won't be re-dispatched automatically.
+                // Operators can inspect FAILED schedules and retry manually.
+                await this.repository
+                    .save({ ...schedule, state: 'FAILED' })
+                    .catch(() => {});
+                errors++;
+            }
+        }
+
+        console.log(
+            `[NetlifyScheduler] Processed ${processed} due schedules, ${errors} errors, ${skipped} claimed elsewhere`
+        );
+        return { processed, errors, skipped };
+    }
+}
+
+module.exports = { NetlifySchedulerAdapter, DEFAULT_WORKER_PATH, DEFAULT_LEASE_MS };

package/infrastructure/scheduler/scheduled-job-repository.js

@@ -0,0 +1,118 @@
+/**
+ * Scheduled Job Repository
+ *
+ * Prisma-based implementation of the repository interface required by
+ * NetlifySchedulerAdapter. Persists one-time scheduled jobs to the
+ * ScheduledJob model so they survive function restarts.
+ *
+ * Repository interface:
+ *   save(scheduleData)        — Upsert a scheduled job
+ *   delete(scheduleName)      — Remove a scheduled job
+ *   findByName(scheduleName)  — Find a single scheduled job
+ *   findDue(now, { leaseMs }) — Find due jobs: PENDING, or PROCESSING with an
+ *                               expired lease (a dispatcher that died after
+ *                               claiming), where scheduledAt <= now
+ *   claim(scheduleName, now, { leaseMs })
+ *                             — Atomically move one due job to PROCESSING;
+ *                               true only for the one caller that won it
+ *
+ * The lease clock is the row's updatedAt: a claim writes it, so a PROCESSING
+ * row whose updatedAt is older than now - leaseMs is claimable again.
+ */
+
+const DEFAULT_LEASE_MS = 5 * 60 * 1000;
+
+// Rows a dispatcher may take: never claimed, or claimed by one that has not
+// finished within the lease.
+function claimableWhere(now, leaseMs = DEFAULT_LEASE_MS) {
+    return {
+        OR: [
+            { state: 'PENDING' },
+            {
+                state: 'PROCESSING',
+                updatedAt: { lt: new Date(now.getTime() - leaseMs) },
+            },
+        ],
+    };
+}
+
+class ScheduledJobRepository {
+    /**
+     * @param {Object} options
+     * @param {import('@prisma/client').PrismaClient} options.prismaClient
+     */
+    constructor({ prismaClient }) {
+        if (!prismaClient) {
+            throw new Error(
+                'ScheduledJobRepository requires a prismaClient instance'
+            );
+        }
+        this.prisma = prismaClient;
+    }
+
+    async save(scheduleData) {
+        return this.prisma.scheduledJob.upsert({
+            where: { scheduleName: scheduleData.scheduleName },
+            update: {
+                scheduledAt: new Date(scheduleData.scheduledAt),
+                queueResourceId: scheduleData.queueResourceId,
+                payload: scheduleData.payload ?? undefined,
+                state: scheduleData.state || 'PENDING',
+            },
+            create: {
+                scheduleName: scheduleData.scheduleName,
+                scheduledAt: new Date(scheduleData.scheduledAt),
+                queueResourceId: scheduleData.queueResourceId,
+                payload: scheduleData.payload ?? undefined,
+                state: scheduleData.state || 'PENDING',
+            },
+        });
+    }
+
+    async delete(scheduleName) {
+        try {
+            await this.prisma.scheduledJob.delete({
+                where: { scheduleName },
+            });
+        } catch (error) {
+            // P2025 = record not found — safe to ignore on delete
+            if (error.code !== 'P2025') {
+                throw error;
+            }
+        }
+    }
+
+    async findByName(scheduleName) {
+        return this.prisma.scheduledJob.findUnique({
+            where: { scheduleName },
+        });
+    }
+
+    async findDue(now, { leaseMs = DEFAULT_LEASE_MS } = {}) {
+        return this.prisma.scheduledJob.findMany({
+            where: {
+                scheduledAt: { lte: now },
+                ...claimableWhere(now, leaseMs),
+            },
+            orderBy: { scheduledAt: 'asc' },
+        });
+    }
+
+    /**
+     * Conditional update: only a row that is still claimable moves to
+     * PROCESSING, so of two overlapping ticks exactly one gets count === 1.
+     * (PostgreSQL re-checks the WHERE on the row it locked; MongoDB updates
+     * each document atomically.)
+     *
+     * @returns {Promise<boolean>} true when this caller claimed the job
+     */
+    async claim(scheduleName, now, { leaseMs = DEFAULT_LEASE_MS } = {}) {
+        const { count } = await this.prisma.scheduledJob.updateMany({
+            where: { scheduleName, ...claimableWhere(now, leaseMs) },
+            data: { state: 'PROCESSING', updatedAt: now },
+        });
+        return count === 1;
+    }
+}
+
+module.exports = { ScheduledJobRepository, DEFAULT_LEASE_MS };

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

@@ -7,16 +7,22 @@
  * Environment Detection:
  * - SCHEDULER_PROVIDER=eventbridge -> Use AWS EventBridge Scheduler
  * - SCHEDULER_PROVIDER=mock -> Use in-memory mock scheduler
+ * - SCHEDULER_PROVIDER=netlify -> Netlify poll-and-dispatch scheduler
+ *   (friggframework/frigg#545; needs `repository`, usually `queueProvider`)
+ * - Default on Netlify (NETLIFY=true, set by the Netlify runtime and build;
+ *   provider-netlify's generated functions also set SCHEDULER_PROVIDER) -> Netlify
  * - Default in dev/test/local stages -> Mock scheduler
  * - Default in other stages -> EventBridge scheduler
+ * - Any other name -> require('@friggframework/provider-<name>').SchedulerAdapter
+ *
+ * Adapters are required inside their branch so building one never loads
+ * another's SDK (@aws-sdk/client-scheduler is not a core dependency).
  */
 
-const { EventBridgeSchedulerAdapter } = require('./eventbridge-scheduler-adapter');
-const { MockSchedulerAdapter } = require('./mock-scheduler-adapter');
-
 const SCHEDULER_PROVIDERS = {
     EVENTBRIDGE: 'eventbridge',
     MOCK: 'mock',
+    NETLIFY: 'netlify',
 };
 
 const LOCAL_STAGES = ['dev', 'test', 'local'];
@@ -32,6 +38,12 @@ function determineProvider() {
         return explicitProvider;
     }
 
+    // Checked before the stage: a Netlify site with no STAGE (or STAGE=dev)
+    // must still persist schedules where scheduled-sync reads them.
+    if (process.env.NETLIFY === 'true') {
+        return SCHEDULER_PROVIDERS.NETLIFY;
+    }
+
     const stage = process.env.STAGE || 'dev';
     if (LOCAL_STAGES.includes(stage)) {
         return SCHEDULER_PROVIDERS.MOCK;
@@ -40,6 +52,13 @@ function determineProvider() {
     return SCHEDULER_PROVIDERS.EVENTBRIDGE;
 }
 
+function createDefaultScheduledJobRepository() {
+    const { ScheduledJobRepository } = require('./scheduled-job-repository');
+    // The prisma export is a lazy proxy: nothing connects until a query runs.
+    const { prisma } = require('../../database/prisma');
+    return new ScheduledJobRepository({ prismaClient: prisma });
+}
+
 /**
  * Create a scheduler service instance
  *
@@ -47,22 +66,51 @@ function determineProvider() {
  * @param {string} options.provider - Scheduler provider ('eventbridge' or 'mock')
  * @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 = {}) {
     const provider = options.provider || determineProvider();
 
     switch (provider) {
-        case SCHEDULER_PROVIDERS.EVENTBRIDGE:
+        case SCHEDULER_PROVIDERS.EVENTBRIDGE: {
+            const { EventBridgeSchedulerAdapter } = require('./eventbridge-scheduler-adapter');
             return new EventBridgeSchedulerAdapter({
                 region: options.region,
             });
-        case SCHEDULER_PROVIDERS.MOCK:
+        }
+        case SCHEDULER_PROVIDERS.MOCK: {
+            const { MockSchedulerAdapter } = require('./mock-scheduler-adapter');
             return new MockSchedulerAdapter({
                 verbose: options.verbose,
             });
-        default:
-            throw new Error(`Unknown scheduler provider: ${provider}`);
+        }
+        case SCHEDULER_PROVIDERS.NETLIFY: {
+            const { NetlifySchedulerAdapter } = require('./netlify-scheduler-adapter');
+            return new NetlifySchedulerAdapter({
+                // Default: the Prisma ScheduledJob rows that the Netlify
+                // scheduled-sync function polls. Without it the adapter
+                // falls back to memory, and a schedule made in one function
+                // is never seen by the cron.
+                repository: options.repository || createDefaultScheduledJobRepository(),
+                queueProvider: options.queueProvider,
+            });
+        }
+        default: {
+            let plugin;
+            try {
+                plugin = require('../../providers/resolve-provider').resolveProvider(null, {
+                    provider,
+                });
+            } catch (error) {
+                throw new Error(`Unknown scheduler provider: ${provider} (${error.message})`);
+            }
+            if (!plugin.SchedulerAdapter) {
+                throw new Error(`Unknown scheduler provider: ${provider}`);
+            }
+            return new plugin.SchedulerAdapter(options);
+        }
     }
 }
 

package/integrations/index.js

@@ -4,6 +4,9 @@ const {
     createIntegrationRouter,
     checkRequiredParams,
 } = require('./integration-router');
+const {
+    getModulesDefinitionFromIntegrationClasses,
+} = require('./utils/map-integration-dto');
 const {
     LoadIntegrationContextUseCase,
 } = require('./use-cases/load-integration-context');
@@ -18,6 +21,8 @@ module.exports = {
     Options,
     createIntegrationRouter,
     checkRequiredParams,
+    // Deprecated (ADR-059): a wrapper over getEntityTypeRegistry.
+    getModulesDefinitionFromIntegrationClasses,
     LoadIntegrationContextUseCase,
     validateExtensionBinding,
     getExtensionRoutes,