@empyria/restate 0.4.5 → 0.4.6

package/AGENTS.md

@@ -78,6 +78,13 @@ may observe an already-mocked value. See `test/Admin.test.js`.
 ports, installs process-wide `SIGTERM`/`SIGINT` handlers, and its returned `forceClose` calls
 `process.exit()` — none of which are safe to exercise in-process in a test run.
 
+## Cron jobs
+
+`CronJob.ensure` is the idempotent entry point (`ensureCronJob` is its ingress client). Never make a boot-time scheduler
+with `CronJobInitiator.create`: it generates a new random job ID on every call, so each restart would add another copy.
+`ensure` compares the normalised request (`cronExpression`, `service`, `method`, `key`, `payload`) and only reschedules
+when it changed. A change here must keep `initiate`, `execute` and `cancel` behaving as before.
+
 ## Zero-dependency preference
 
 Cron parsing uses `croner` (zero dependencies), not `cron-parser` (pulls in `luxon`). If you

package/README.md

@@ -106,6 +106,21 @@ export const triage = defineAgent({
 | [lib/agent/Errors.js](./lib/agent/Errors.js) | `toRestateLLMError` (AI SDK error → terminal / `RetryableError` / transient) and the default retry policies for LLM steps, tool steps and the agent invocation.                                                                                                                                             |
 | [lib/agent/Model.js](./lib/agent/Model.js)   | `createModel` — AI SDK model for an OpenAI-compatible endpoint (e.g. Bifrost).                                                                                                                                                                                                                              |
 
+### Recurring jobs
+
+`cronJob` (a virtual object) runs a target handler on a cron schedule: each run sends the target, then schedules the
+next one from the current time, so a restart or an outage never causes a backlog of runs. Register `cronJob` on your
+endpoint, then create jobs with either:
+
+- `cronJobInitiator.create(request)`: a new job with a random ID each call (good for jobs created by users);
+- `ensureCronJob({restateURL, id, cronExpression, service, method, key?, payload?})`: **idempotent, for code that
+  starts with the application.** The job has the stable `id` you give it, so calling it on every start never adds a second
+  job: the same request changes nothing, and a changed request (another schedule, target or payload) replaces the pending
+  run under the same ID. Call it once the endpoint has registered, e.g. from `setupRestate`'s `registrationCallbackFn`.
+
+Cron expressions are `croner` patterns (five fields, or six with seconds for tests). The target handler is sent the
+`payload` as its input, or no input when there is none.
+
 ### Shaping an agent
 
 `defineAgent` options beyond the basics:

package/lib/Cron.js

@@ -1,6 +1,7 @@
 import * as restate from '@restatedev/restate-sdk'
 import { TerminalError, serde } from '@restatedev/restate-sdk'
 import { Cron } from 'croner'
+import { sendMessage } from './Admin.js'
 
 let JOB_STATE_NAME = 'empyria-job-state'
 
@@ -32,6 +33,24 @@ export const cronJob = restate.object({
 
 			return await scheduleNextExecution(ctx, request)
 		},
+		/**
+		 * Makes sure this job exists and runs the given request: an idempotent `initiate`, meant for
+		 * code that starts with the application and cannot know whether the job was created before.
+		 *
+		 * - no job yet: schedules it, as `initiate` does;
+		 * - the same request already scheduled: changes nothing and returns the current state;
+		 * - a different request (another schedule, target or payload): cancels the pending run and
+		 *   schedules the new request under the same job ID.
+		 */
+		ensure: async (ctx, request) => {
+			const wanted = normalizeRequest(request)
+			const jobState = await ctx.get(JOB_STATE_NAME)
+
+			if (jobState && sameRequest(jobState.request, wanted)) return jobState
+			if (jobState) ctx.cancel(jobState.next_execution_id)
+
+			return await scheduleNextExecution(ctx, wanted)
+		},
 		execute: async (ctx) => {
 			const jobState = await ctx.get(JOB_STATE_NAME)
 			if (!jobState) {
@@ -76,6 +95,25 @@ export const cronJob = restate.object({
 	},
 })
 
+const REQUEST_FIELDS = ['cronExpression', 'service', 'method', 'key', 'payload']
+
+/** Keeps only the fields a job request has, and checks the required ones. */
+function normalizeRequest(request) {
+	const out = {}
+	for (const field of REQUEST_FIELDS)
+		if (request?.[field] !== undefined) out[field] = request[field]
+	for (const field of ['cronExpression', 'service', 'method']) {
+		if (typeof out[field] !== 'string' || out[field].trim() === '') {
+			throw new TerminalError(`A cron job needs a non-empty "${field}".`, { errorCode: 400 })
+		}
+	}
+	return out
+}
+
+const sameRequest = (a, b) =>
+	JSON.stringify(REQUEST_FIELDS.map((f) => a?.[f] ?? null)) ===
+	JSON.stringify(REQUEST_FIELDS.map((f) => b?.[f] ?? null))
+
 const scheduleNextExecution = async (ctx, request) => {
 	// Parse cron expression
 	// Persist current date in Restate for deterministic replay
@@ -106,4 +144,30 @@ const scheduleNextExecution = async (ctx, request) => {
 	return jobState
 }
 
+/**
+ * Makes sure a recurring job exists, from outside Restate (typically right after the service registered).
+ * Safe to call on every start: the job has a stable ID, so a repeat call changes nothing and a changed
+ * request replaces the old schedule instead of adding a second job.
+ *
+ * Needs the `CronJob` object registered on an endpoint.
+ * @param {{restateURL: string, id: string, cronExpression: string, service: string, method: string, key?: string, payload?: any}} params
+ *   `id` names the job (letters, digits, `.`, `_`, `:`, `-`); `service`/`method`/`key` are the target the
+ *   job calls on each run, with `payload` as its input (none when omitted).
+ * @returns {Promise<{request: object, next_execution_time: string, next_execution_id: string}>}
+ */
+export async function ensureCronJob({ restateURL, id, ...request }) {
+	if (typeof id !== 'string' || !/^[A-Za-z0-9._:-]+$/.test(id)) {
+		throw new TypeError(
+			'ensureCronJob needs an id made of letters, digits, ".", "_", ":" and "-"',
+		)
+	}
+	return sendMessage({
+		restateURL,
+		name: 'CronJob',
+		message: 'ensure',
+		key: id,
+		payload: request,
+	})
+}
+
 export { JOB_STATE_NAME }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@empyria/restate",
-	"version": "0.4.5",
+	"version": "0.4.6",
 	"description": "Restate.dev helpers for the Empyria nanoservice framework",
 	"license": "MIT",
 	"author": "Imre Fazekas <imre.fazekas@icloud.com>",

package/test/Cron.test.js

@@ -1,5 +1,11 @@
-import { describe, test, expect } from 'bun:test'
-import { cronJobInitiator, cronJob, setJobStateName, JOB_STATE_NAME } from '../lib/Cron.js'
+import { afterEach, describe, test, expect } from 'bun:test'
+import {
+	cronJobInitiator,
+	cronJob,
+	ensureCronJob,
+	setJobStateName,
+	JOB_STATE_NAME,
+} from '../lib/Cron.js'
 import { TerminalError } from '@restatedev/restate-sdk'
 
 describe('setJobStateName', () => {
@@ -30,8 +36,11 @@ describe('cronJobInitiator.create', () => {
 // wiring; this factory keeps the mocked context consistent across tests.
 function makeSchedulingCtx({ existing } = {}) {
 	const sets = []
+	const cancelled = []
 	return {
 		sets,
+		cancelled,
+		cancel: (invocationId) => cancelled.push(invocationId),
 		get: async () => existing,
 		date: { now: async () => Date.now() },
 		key: 'job-1',
@@ -149,3 +158,136 @@ describe('cronJob.getInfo', () => {
 		expect(await cronJob.object.getInfo(ctx)).toEqual({ request: {} })
 	})
 })
+
+describe('cronJob.ensure', () => {
+	const request = { cronExpression: '* * * * *', service: 'ReportService', method: 'refresh' }
+
+	test('schedules a job that does not exist yet', async () => {
+		const ctx = makeSchedulingCtx()
+		const state = await cronJob.object.ensure(ctx, request)
+		expect(state.request).toEqual(request)
+		expect(state.next_execution_id).toBe('exec-inv-1')
+		expect(ctx.sets).toEqual([[JOB_STATE_NAME, state]])
+		expect(ctx.cancelled).toEqual([])
+	})
+
+	test('the same request again changes nothing: no second schedule, no cancel', async () => {
+		const existing = { request, next_execution_time: 'T', next_execution_id: 'inv-old' }
+		const ctx = makeSchedulingCtx({ existing })
+		expect(await cronJob.object.ensure(ctx, request)).toBe(existing)
+		expect(ctx.sets).toEqual([])
+		expect(ctx.cancelled).toEqual([])
+	})
+
+	test('unknown fields and field order do not make a request "different"', async () => {
+		const existing = { request, next_execution_time: 'T', next_execution_id: 'inv-old' }
+		const ctx = makeSchedulingCtx({ existing })
+		const same = {
+			method: 'refresh',
+			extra: 'ignored',
+			service: 'ReportService',
+			cronExpression: '* * * * *',
+		}
+		expect(await cronJob.object.ensure(ctx, same)).toBe(existing)
+		expect(ctx.sets).toEqual([])
+	})
+
+	test('a changed schedule cancels the pending run and schedules the new one under the same job', async () => {
+		const existing = { request, next_execution_time: 'T', next_execution_id: 'inv-old' }
+		const ctx = makeSchedulingCtx({ existing })
+		const state = await cronJob.object.ensure(ctx, {
+			...request,
+			cronExpression: '*/5 * * * *',
+		})
+		expect(ctx.cancelled).toEqual(['inv-old'])
+		expect(state.request.cronExpression).toBe('*/5 * * * *')
+		expect(ctx.sets).toHaveLength(1)
+	})
+
+	test('a changed target or payload also replaces the job', async () => {
+		const existing = { request, next_execution_time: 'T', next_execution_id: 'inv-old' }
+		for (const change of [{ method: 'other' }, { payload: { a: 1 } }, { key: 'k' }]) {
+			const ctx = makeSchedulingCtx({ existing })
+			await cronJob.object.ensure(ctx, { ...request, ...change })
+			expect(ctx.cancelled).toEqual(['inv-old'])
+		}
+	})
+
+	test('a request without a schedule, service or method is refused (400)', async () => {
+		for (const bad of [
+			{},
+			{ ...request, cronExpression: '' },
+			{ ...request, service: undefined },
+			{ ...request, method: 3 },
+		]) {
+			const error = await cronJob.object.ensure(makeSchedulingCtx(), bad).catch((e) => e)
+			expect(error).toBeInstanceOf(TerminalError)
+			expect(error.code).toBe(400)
+		}
+	})
+
+	test('an invalid cron expression is a terminal error and leaves an existing job alone', async () => {
+		const ctx = makeSchedulingCtx()
+		await expect(
+			cronJob.object.ensure(ctx, { ...request, cronExpression: 'not a cron' }),
+		).rejects.toThrow(TerminalError)
+		expect(ctx.sets).toEqual([])
+	})
+})
+
+describe('ensureCronJob', () => {
+	const realFetch = globalThis.fetch
+	afterEach(() => {
+		globalThis.fetch = realFetch
+	})
+
+	test('calls CronJob/<id>/ensure through the ingress with the request as the body', async () => {
+		const calls = []
+		globalThis.fetch = async (url, init) => {
+			calls.push([url, JSON.parse(init.body)])
+			return new Response(JSON.stringify({ next_execution_time: 'T' }), { status: 200 })
+		}
+		const state = await ensureCronJob({
+			restateURL: 'http://restate:8080',
+			id: 'reports:refresh',
+			cronExpression: '* * * * *',
+			service: 'ReportService',
+			method: 'refresh',
+		})
+		expect(state).toEqual({ next_execution_time: 'T' })
+		expect(calls).toEqual([
+			[
+				'http://restate:8080/CronJob/reports:refresh/ensure',
+				{ cronExpression: '* * * * *', service: 'ReportService', method: 'refresh' },
+			],
+		])
+	})
+
+	test('refuses an id that is not safe in a URL path', async () => {
+		for (const id of ['', 'a/b', 'a b', 'a?b', undefined]) {
+			await expect(
+				ensureCronJob({
+					restateURL: 'http://x',
+					id,
+					cronExpression: '* * * * *',
+					service: 's',
+					method: 'm',
+				}),
+			).rejects.toThrow(TypeError)
+		}
+	})
+
+	test('a failed call is an error for the caller', async () => {
+		globalThis.fetch = async () =>
+			new Response('nope', { status: 500, statusText: 'Internal Server Error' })
+		await expect(
+			ensureCronJob({
+				restateURL: 'http://x',
+				id: 'j',
+				cronExpression: '* * * * *',
+				service: 's',
+				method: 'm',
+			}),
+		).rejects.toThrow('500')
+	})
+})