@easy-cms/core 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -855,8 +855,9 @@ interface CreateEasyCMSOptions {
     /** Project root. Default `process.cwd()`. */
     readonly cwd?: string;
     /**
-     * Run due scheduled jobs every minute in this process. Default: on when a collection or
-     * global has `schedule`. Turn it off where a cron calls `runScheduled` instead.
+     * Run due scheduled jobs and webhook retries every minute in this process. Default: on when
+     * a collection or global has `schedule`, or `webhooks` is set. Turn it off where a cron calls
+     * `runJobs` (or `GET <api>/jobs/run`) instead.
      */
     readonly scheduler?: boolean;
     /** Default `verify` when `NODE_ENV=production`, otherwise `push`. */
@@ -992,8 +993,30 @@ declare class EasyCMS<C extends Config = Config> {
     destroy(): Promise<void>;
     private schedulerTimer;
     private running;
-    /** Runs due jobs every `interval` ms in this process (`createEasyCMS` does this by default). */
+    /** Runs `runJobs` every `interval` ms in this process (`createEasyCMS` does this by default). */
     startScheduler(interval?: number): void;
+    /**
+     * Runs due scheduled publishes and unpublishes, and retries failed webhook deliveries. What the
+     * scheduler and the cron endpoint (`GET <api>/jobs/run`) call.
+     */
+    runJobs(now?: Date): Promise<{
+        ran: number;
+        failed: number;
+        webhooks: {
+            sent: number;
+            failed: number;
+        };
+    }>;
+    /**
+     * Tries webhook deliveries that are due for another attempt. Deliveries are kept in the
+     * database until they succeed, so they survive restarts.
+     */
+    retryWebhooks(now?: Date): Promise<{
+        sent: number;
+        failed: number;
+    }>;
+    /** Webhook deliveries until they succeed, stored in `webhook-deliveries`. */
+    private webhookQueue;
     /**
      * Publishes or unpublishes documents whose scheduled time has come. Safe to call often, e.g.
      * from a cron job (`GET <api>/jobs/run`) where no process keeps running.

package/dist/index.js

@@ -189,11 +189,13 @@ var SESSIONS = "sessions";
 var LOGIN_ATTEMPTS = "login-attempts";
 var VERSIONS = "document-versions";
 var SCHEDULED_JOBS = "scheduled-jobs";
+var WEBHOOK_DELIVERIES = "webhook-deliveries";
 var INTERNAL_COLLECTIONS = /* @__PURE__ */ new Set([
   SESSIONS,
   LOGIN_ATTEMPTS,
   VERSIONS,
-  SCHEDULED_JOBS
+  SCHEDULED_JOBS,
+  WEBHOOK_DELIVERIES
 ]);
 var DEFAULT_ROLES = ["admin", "editor"];
 var adminOrSelf = ({ user }) => {
@@ -390,6 +392,22 @@ var scheduledJobsCollection = {
     { name: "author", type: "number" }
   ]
 };
+var webhookDeliveriesCollection = {
+  slug: WEBHOOK_DELIVERIES,
+  access: { read: nobody, create: nobody, update: nobody, delete: nobody },
+  fields: [
+    { name: "url", type: "text", required: true },
+    { name: "event", type: "text", required: true },
+    // The JSON body as first sent: retries are byte-for-byte the same, signature included.
+    { name: "body", type: "textarea", required: true },
+    { name: "delivery", type: "text", required: true },
+    { name: "attempts", type: "number", required: true },
+    { name: "nextAttemptAt", type: "text", required: true, index: true },
+    // pending | failed
+    { name: "state", type: "text", required: true, index: true },
+    { name: "error", type: "text" }
+  ]
+};
 
 // src/auth/password.ts
 import { randomBytes, scrypt, timingSafeEqual } from "crypto";
@@ -1009,71 +1027,157 @@ var WEBHOOK_EVENTS = [
   "draft"
 ];
 var RETRY_DELAYS = [1e3, 5e3];
+var QUEUE_DELAYS = [6e4, 5 * 6e4, 30 * 6e4, 2 * 36e5, 6 * 36e5, 12 * 36e5];
+var CLAIM = 5 * 6e4;
 var TIMEOUT = 1e4;
 var Webhooks = class {
-  constructor(hooks, logger, fetcher = (...args) => fetch(...args), retryDelays = RETRY_DELAYS) {
+  constructor(hooks, logger, queue, fetcher = (...args) => fetch(...args), retryDelays = RETRY_DELAYS) {
     this.hooks = hooks;
     this.logger = logger;
+    this.queue = queue;
     this.fetcher = fetcher;
     this.retryDelays = retryDelays;
   }
   hooks;
   logger;
+  queue;
   fetcher;
   retryDelays;
   pending = /* @__PURE__ */ new Set();
+  /** Deliveries are saved one after another, so they are first sent in the order of events. */
+  saving = Promise.resolve();
   emit(event, target, doc) {
     if (this.hooks.length === 0) return;
     const payload = { event, ...target, doc, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
     for (const hook of this.hooks) {
       if (!matches(hook, payload)) continue;
-      const delivery = this.deliver(hook, payload).finally(() => this.pending.delete(delivery));
-      this.pending.add(delivery);
+      this.track(this.deliver(hook, payload));
     }
   }
   /** Waits for deliveries in progress, e.g. before a serverless function returns. */
   async flush() {
     while (this.pending.size > 0) await Promise.allSettled([...this.pending]);
   }
+  /**
+   * Tries queued deliveries whose next attempt is due. Runs with scheduled jobs: every minute
+   * in a server, or from the cron endpoint.
+   */
+  async retry(now = /* @__PURE__ */ new Date()) {
+    if (!this.queue) return { sent: 0, failed: 0 };
+    let sent = 0;
+    let failed = 0;
+    for (const entry of await this.queue.due(now, 50)) {
+      const { id, ...queued } = entry;
+      const hook = this.hooks.find((h) => h.url === queued.url);
+      if (!hook) {
+        await this.queue.remove(id);
+        continue;
+      }
+      const attempts = queued.attempts + 1;
+      await this.queue.update(id, { ...queued, attempts, nextAttemptAt: later(now, CLAIM) });
+      const result = await this.attempt(hook, queued.event, queued.body, queued.delivery);
+      if (result.ok) {
+        await this.queue.remove(id);
+        sent++;
+        continue;
+      }
+      const delay = QUEUE_DELAYS[Math.max(0, attempts - this.retryDelays.length - 1)];
+      if (delay === void 0) failed++;
+      await this.queue.update(id, {
+        ...queued,
+        attempts,
+        nextAttemptAt: later(now, delay ?? 0),
+        state: delay === void 0 ? "failed" : "pending",
+        error: result.error
+      });
+      if (delay === void 0) this.giveUp(hook, queued.event, result.error, attempts);
+    }
+    return { sent, failed };
+  }
+  track(delivery) {
+    const tracked = delivery.catch((error) => this.logger.error(`Webhook queue failed: ${error.message}`)).finally(() => this.pending.delete(tracked));
+    this.pending.add(tracked);
+  }
   async deliver(hook, payload) {
+    const delivery = randomUUID2();
     const body = JSON.stringify(payload);
+    const { event } = payload;
+    const entry = (attempts, nextAttemptAt, error) => ({
+      url: hook.url,
+      event,
+      body,
+      delivery,
+      attempts,
+      nextAttemptAt,
+      state: "pending",
+      error
+    });
+    const { queue } = this;
+    const saved = queue ? this.saving.then(() => queue.add(entry(0, later(/* @__PURE__ */ new Date(), CLAIM), null))) : Promise.resolve(void 0);
+    this.saving = saved.catch(() => {
+    });
+    let queued;
+    try {
+      queued = await saved;
+    } catch (error) {
+      this.logger.error(`Could not save webhook delivery: ${error.message}`);
+    }
+    for (let attempt = 0; ; attempt++) {
+      const result = await this.attempt(hook, event, body, delivery);
+      if (result.ok) {
+        if (queued !== void 0) await this.queue?.remove(queued);
+        return;
+      }
+      const delay = this.retryDelays[attempt];
+      if (delay === void 0) {
+        if (queued === void 0 || !this.queue)
+          return this.giveUp(hook, event, result.error, attempt + 1);
+        const next = later(/* @__PURE__ */ new Date(), QUEUE_DELAYS[0]);
+        await this.queue.update(queued, entry(attempt + 1, next, result.error));
+        this.logger.warn(
+          `Webhook ${hook.url} failed for ${event} (${result.error}); will retry later`
+        );
+        return;
+      }
+      await new Promise((resolve3) => setTimeout(resolve3, delay));
+    }
+  }
+  /** One POST. Client errors other than rate limiting count as done: retrying won't help. */
+  async attempt(hook, event, body, delivery) {
     const headers = {
       "content-type": "application/json",
       "user-agent": "easy-cms-webhooks",
-      "x-easy-cms-event": payload.event,
-      "x-easy-cms-delivery": randomUUID2(),
+      "x-easy-cms-event": event,
+      "x-easy-cms-delivery": delivery,
       ...hook.headers
     };
     if (hook.secret) {
       headers["x-easy-cms-signature"] = `sha256=${createHmac2("sha256", hook.secret).update(body).digest("hex")}`;
     }
-    for (let attempt = 0; ; attempt++) {
-      try {
-        const response = await this.fetcher(hook.url, {
-          method: "POST",
-          headers,
-          body,
-          signal: AbortSignal.timeout(TIMEOUT)
-        });
-        if (response.ok || response.status < 500 && response.status !== 429) {
-          if (!response.ok)
-            this.logger.warn(`Webhook ${hook.url} answered ${response.status} to ${payload.event}`);
-          return;
-        }
-        throw new Error(`status ${response.status}`);
-      } catch (error) {
-        const delay = this.retryDelays[attempt];
-        if (delay === void 0) {
-          this.logger.error(
-            `Webhook ${hook.url} failed for ${payload.event}: ${error.message}`
-          );
-          return;
-        }
-        await new Promise((resolve3) => setTimeout(resolve3, delay));
+    try {
+      const response = await this.fetcher(hook.url, {
+        method: "POST",
+        headers,
+        body,
+        signal: AbortSignal.timeout(TIMEOUT)
+      });
+      if (response.ok || response.status < 500 && response.status !== 429) {
+        if (!response.ok)
+          this.logger.warn(`Webhook ${hook.url} answered ${response.status} to ${event}`);
+        return { ok: true };
       }
+      return { ok: false, error: `status ${response.status}` };
+    } catch (error) {
+      return { ok: false, error: error.message };
     }
   }
+  giveUp(hook, event, error, attempts) {
+    this.logger.error(
+      `Webhook ${hook.url} failed for ${event} after ${attempts} attempts: ${error}`
+    );
+  }
 };
+var later = (from, ms) => new Date(from.getTime() + ms).toISOString();
 function matches(hook, payload) {
   if (hook.events && !hook.events.includes(payload.event)) return false;
   if (payload.collection !== void 0)
@@ -1091,6 +1195,7 @@ var RESERVED_SLUGS = /* @__PURE__ */ new Set([
   "login-attempts",
   "document-versions",
   "scheduled-jobs",
+  "webhook-deliveries",
   "jobs",
   "migrations",
   "access"
@@ -1580,7 +1685,8 @@ async function resolveConfig(input) {
       ...config.collections ?? [],
       ...internalCollections,
       ...usesVersions(config) ? [versionsCollection] : [],
-      ...usesSchedule(config) ? [scheduledJobsCollection] : []
+      ...usesSchedule(config) ? [scheduledJobsCollection] : [],
+      ...(config.webhooks?.length ?? 0) > 0 ? [webhookDeliveriesCollection] : []
     ],
     globals: config.globals ?? []
   };
@@ -1712,6 +1818,10 @@ function localizePath(fields, path, locale, locales = []) {
       list = field.fields;
       continue;
     }
+    if (field.type === "blocks") {
+      list = field.blocks.flatMap((block) => block.fields);
+      continue;
+    }
     return path;
   }
   return path;
@@ -2099,7 +2209,7 @@ async function createEasyCMS(config, options = {}) {
     interactive: options.interactive ?? false
   });
   const cms = new EasyCMS(resolved2, db, logger, storage);
-  const scheduling = [...resolved2.collections, ...resolved2.globals].some((c) => c.schedule);
+  const scheduling = [...resolved2.collections, ...resolved2.globals].some((c) => c.schedule) || (resolved2.webhooks?.length ?? 0) > 0;
   if (scheduling && options.scheduler !== false) cms.startScheduler();
   return cms;
 }
@@ -2127,7 +2237,11 @@ var EasyCMS = class {
     this.logger = logger;
     this.storage = storage;
     this.versions = new VersionStore(db);
-    this.webhooks = new Webhooks(config.webhooks ?? [], logger);
+    this.webhooks = new Webhooks(
+      config.webhooks ?? [],
+      logger,
+      config.collections.some((c) => c.slug === WEBHOOK_DELIVERIES) ? this.webhookQueue() : void 0
+    );
     this.auth = new Auth(this);
   }
   async find(collection2, options = {}) {
@@ -2743,18 +2857,67 @@ var EasyCMS = class {
   // --- Scheduled publishing --------------------------------------------------
   schedulerTimer;
   running = Promise.resolve();
-  /** Runs due jobs every `interval` ms in this process (`createEasyCMS` does this by default). */
+  /** Runs `runJobs` every `interval` ms in this process (`createEasyCMS` does this by default). */
   startScheduler(interval = 6e4) {
     if (this.schedulerTimer) return;
     this.schedulerTimer = setInterval(() => {
       this.running = this.running.then(
-        () => this.runScheduled().catch(
+        () => this.runJobs().catch(
           (error) => this.logger.error(`Scheduled jobs failed: ${error.message}`)
         )
       );
     }, interval);
     this.schedulerTimer.unref?.();
   }
+  /**
+   * Runs due scheduled publishes and unpublishes, and retries failed webhook deliveries. What the
+   * scheduler and the cron endpoint (`GET <api>/jobs/run`) call.
+   */
+  async runJobs(now = /* @__PURE__ */ new Date()) {
+    const scheduled = await this.runScheduled(now);
+    return { ...scheduled, webhooks: await this.retryWebhooks(now) };
+  }
+  /**
+   * Tries webhook deliveries that are due for another attempt. Deliveries are kept in the
+   * database until they succeed, so they survive restarts.
+   */
+  retryWebhooks(now = /* @__PURE__ */ new Date()) {
+    return this.webhooks.retry(now);
+  }
+  /** Webhook deliveries until they succeed, stored in `webhook-deliveries`. */
+  webhookQueue() {
+    const collection2 = WEBHOOK_DELIVERIES;
+    const toRow = (d, createdAt) => {
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      return { ...d, createdAt: createdAt ?? now, updatedAt: now };
+    };
+    return {
+      add: async (delivery) => (await this.db.create({ collection: collection2, data: toRow(delivery) })).id,
+      update: async (id, delivery) => {
+        const current = await this.db.findById({ collection: collection2, id });
+        await this.db.update({
+          collection: collection2,
+          id,
+          data: toRow(delivery, current?.createdAt)
+        });
+      },
+      remove: async (id) => {
+        await this.db.delete({ collection: collection2, id });
+      },
+      due: async (now, limit) => {
+        const { docs } = await this.db.find({
+          collection: collection2,
+          where: {
+            and: [{ state: { equals: "pending" } }, { nextAttemptAt: { lte: now.toISOString() } }]
+          },
+          sort: ["nextAttemptAt"],
+          limit,
+          page: 1
+        });
+        return docs;
+      }
+    };
+  }
   /**
    * Publishes or unpublishes documents whose scheduled time has come. Safe to call often, e.g.
    * from a cron job (`GET <api>/jobs/run`) where no process keeps running.
@@ -3693,7 +3856,7 @@ async function route(cms, ctx, method, segments, options) {
     if (!byCron && ctx.user?.role !== "admin") {
       throw ctx.user ? new HttpError("Forbidden", 403) : new UnauthorizedError();
     }
-    return { body: await cms.runScheduled() };
+    return { body: await cms.runJobs() };
   }
   if (first === "admin") {
     if (method !== "GET") throw methodNotAllowed(ctx, "GET");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easy-cms/core",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Embedded, code-first headless CMS for Nuxt and Next.js",
   "license": "MIT",
   "type": "module",