feat(payload-cloud): set up cron jobs on init (#10106)

If the user has tasks configured, we set up cron jobs on init.
We also make sure to only run on one instance using a instance
identifier stored in a global.

This adds a new property to the payloadCloudPlugin: `jobs`.

Author: GermanJablo

packages/payload-cloud/src/plugin.spec.ts

@@ -5,9 +5,19 @@ import { nodemailerAdapter } from '@payloadcms/email-nodemailer'
 import nodemailer from 'nodemailer'
 import { defaults } from 'payload'
 
-import { payloadCloudPlugin } from './plugin.js'
+// TO-DO: this would be needed for the TO-DO tests below.
+// maybe we have to use jest.unstable_mockModule? (already tried)
+// jest.mock('./plugin.ts', () => ({
+//   // generateRandomString: jest.fn<() => string>().mockReturnValue('instance'),
+//   generateRandomString: jest.fn().mockReturnValue('instance'),
+// }))
+
+const mockedPayload: Payload = {
+  updateGlobal: jest.fn(),
+  findGlobal: jest.fn().mockReturnValue('instance'),
+} as unknown as Payload
 
-const mockedPayload: Payload = jest.fn() as unknown as Payload
+import { payloadCloudPlugin } from './plugin.js'
 
 describe('plugin', () => {
   let createTransportSpy: jest.Spied<any>
@@ -165,6 +175,78 @@ describe('plugin', () => {
       })
     })
   })
+
+  describe('autoRun and cronJobs', () => {
+    beforeEach(() => {
+      process.env.PAYLOAD_CLOUD = 'true'
+      process.env.PAYLOAD_CLOUD_EMAIL_API_KEY = 'test-key'
+      process.env.PAYLOAD_CLOUD_DEFAULT_DOMAIN = 'test-domain.com'
+    })
+
+    test('should always set global instance identifier', async () => {
+      const plugin = payloadCloudPlugin()
+      const config = await plugin(createConfig())
+
+      const globalInstance = config.globals?.find(
+        (global) => global.slug === 'payload-cloud-instance',
+      )
+
+      expect(globalInstance).toBeDefined()
+      expect(globalInstance?.fields).toStrictEqual([
+        {
+          name: 'instance',
+          type: 'text',
+          required: true,
+        },
+      ]),
+        expect(globalInstance?.admin?.hidden).toStrictEqual(true)
+    })
+    // TO-DO: I managed to mock findGlobal, but not generateRandomString
+    test.skip('if autoRun is not set, should return default cron job', async () => {
+      const plugin = payloadCloudPlugin()
+      const config = await plugin(createConfig())
+      const DEFAULT_CRON_JOB = {
+        cron: '* * * * *',
+        limit: 10,
+        queue: 'default (every minute)',
+      }
+      if (typeof config.jobs?.autoRun !== 'function') {
+        throw new Error('autoRun should be a function')
+      }
+      const cronConfig = await config.jobs!.autoRun!(mockedPayload)
+      expect(cronConfig).toStrictEqual([DEFAULT_CRON_JOB])
+    })
+    // TO-DO: I managed to mock findGlobal, but not generateRandomString
+    // Either way when mocking the plugin part this test has little if any importance
+    test.skip('if autoRun is a function, should return the result of the function', async () => {
+      const plugin = payloadCloudPlugin()
+      const config = await plugin(
+        createConfig({
+          jobs: {
+            tasks: [],
+            autoRun: async () => {
+              return [
+                {
+                  cron: '1 2 3 4 5',
+                  limit: 5,
+                  queue: 'test-queue',
+                },
+                {},
+              ]
+            },
+          },
+        }),
+      )
+      expect(config.jobs?.autoRun).toStrictEqual([
+        {
+          cron: '1 2 3 4 5',
+          limit: 5,
+          queue: 'test-queue',
+        },
+        {},
+      ])
+    })
+  })
 })
 
 function assertCloudStorage(config: Config) {

packages/payload-cloud/src/plugin.ts

@@ -1,4 +1,4 @@
-import type { Config } from 'payload'
+import type { Config, Payload } from 'payload'
 
 import type { PluginOptions } from './types.js'
 
@@ -11,6 +11,11 @@ import {
 } from './hooks/uploadCache.js'
 import { getStaticHandler } from './staticHandler.js'
 
+export const generateRandomString = (): string => {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
+  return Array.from({ length: 24 }, () => chars[Math.floor(Math.random() * chars.length)]).join('')
+}
+
 export const payloadCloudPlugin =
   (pluginOptions?: PluginOptions) =>
   async (incomingConfig: Config): Promise<Config> => {
@@ -93,5 +98,72 @@ export const payloadCloudPlugin =
       })
     }
 
+    // We make sure to only run cronjobs on one instance using a instance identifier stored in a global.
+
+    const DEFAULT_CRON = '* * * * *'
+    const DEFAULT_LIMIT = 10
+    const DEFAULT_CRON_JOB = {
+      cron: DEFAULT_CRON,
+      limit: DEFAULT_LIMIT,
+      queue: 'default (every minute)',
+    }
+    config.globals = [
+      ...(config.globals || []),
+      {
+        slug: 'payload-cloud-instance',
+        admin: {
+          hidden: true,
+        },
+        fields: [
+          {
+            name: 'instance',
+            type: 'text',
+            required: true,
+          },
+        ],
+      },
+    ]
+
+    if (pluginOptions?.enableAutoRun === false || !config.jobs) {
+      return config
+    }
+
+    const newAutoRun = async (payload: Payload) => {
+      const instance = generateRandomString()
+
+      await payload.updateGlobal({
+        slug: 'payload-cloud-instance',
+        data: {
+          instance,
+        },
+      })
+
+      await waitRandomTime()
+
+      const cloudInstance = await payload.findGlobal({
+        slug: 'payload-cloud-instance',
+      })
+
+      if (cloudInstance.instance !== instance) {
+        return []
+      }
+      if (!config.jobs?.autoRun) {
+        return [DEFAULT_CRON_JOB]
+      }
+      return typeof config.jobs.autoRun === 'function'
+        ? await config.jobs.autoRun(payload)
+        : config.jobs.autoRun
+    }
+
+    config.jobs.autoRun = newAutoRun
+
     return config
   }
+
+function waitRandomTime(): Promise<void> {
+  const min = 1000 // 1 second in milliseconds
+  const max = 5000 // 5 seconds in milliseconds
+  const randomTime = Math.floor(Math.random() * (max - min + 1)) + min
+
+  return new Promise((resolve) => setTimeout(resolve, randomTime))
+}

packages/payload-cloud/src/types.ts

@@ -65,6 +65,14 @@ export interface PluginOptions {
       }
     | false
 
+  /**
+   *
+   * Configures whether cron jobs defined in config.jobs.autoRun will be run or not
+   *
+   * @default true
+   */
+  enableAutoRun?: boolean
+
   /**
    * Payload Cloud API endpoint
    *