@empyria/restate 0.1.0

package/lib/Caller.js

@@ -0,0 +1,50 @@
+/**
+ * @typedef {Object} CallerParams
+ * @property {string} name - Target service name as registered in Restate.
+ * @property {string} handler - Handler name to invoke on the target service.
+ * @property {object} payload - JSON payload forwarded to the handler.
+ */
+
+/**
+ * CallerServiceDef — a generic Restate service that dispatches a fire-and-
+ * forget call to any handler on any other service by name.
+ *
+ * Why does this exist?
+ * Inside a Restate workflow or virtual object you cannot call another service
+ * handler dynamically by string name using the typed SDK clients — the client
+ * is bound to a specific service definition at compile time. CallerService
+ * breaks that constraint: a workflow sends a {@link CallerParams} message to
+ * this service, which then uses `ctx.serviceSendClient` to fan the call out
+ * to the target, and returns the resulting invocation ID.
+ *
+ * The retry policy is intentionally set to 1 attempt. The caller is
+ * responsible for deciding whether to retry; this service is a thin proxy.
+ */
+export const CallerServiceDef = {
+	name: 'CallerService',
+	handlers: {
+		/**
+		 * @param {import('@restatedev/restate-sdk').Context} ctx
+		 * @param {CallerParams} params
+		 * @returns {Promise<string>} The invocation ID of the dispatched call.
+		 * @throws {Error} If `handler` isn't a function on the target service's client.
+		 */
+		dispatch: async (ctx, { name, payload, handler }) => {
+			const client = ctx.serviceSendClient({ name })
+
+			const candidate = client[handler]
+			if (typeof candidate !== 'function') {
+				throw new Error(`Handler "${handler}" is not a function on service "${name}"`)
+			}
+
+			const { invocationId } = await candidate(payload)
+
+			return await invocationId
+		},
+	},
+	options: {
+		retryPolicy: {
+			maxAttempts: 1,
+		},
+	},
+}

package/lib/Cron.js

@@ -0,0 +1,109 @@
+import * as restate from '@restatedev/restate-sdk'
+import { TerminalError, serde } from '@restatedev/restate-sdk'
+import { Cron } from 'croner'
+
+let JOB_STATE_NAME = 'principia-job-state'
+
+export const setJobStateName = (jobStateName) => {
+	JOB_STATE_NAME = jobStateName
+	return JOB_STATE_NAME
+}
+
+export const cronJobInitiator = restate.service({
+	name: 'CronJobInitiator',
+	handlers: {
+		create: async (ctx, request) => {
+			// Create a new job ID and initiate the cron job object for that ID
+			// We can then address this job object by its ID
+			const jobId = ctx.rand.uuidv4()
+			const job = await ctx.objectClient(cronJob, jobId).initiate(request)
+			return `Job created with ID ${jobId} and next execution time ${job.next_execution_time}`
+		},
+	},
+})
+
+export const cronJob = restate.object({
+	name: 'CronJob',
+	handlers: {
+		initiate: async (ctx, request) => {
+			if (await ctx.get(JOB_STATE_NAME)) {
+				throw new TerminalError('Job already exists for this ID.')
+			}
+
+			return await scheduleNextExecution(ctx, request)
+		},
+		execute: async (ctx) => {
+			const jobState = await ctx.get(JOB_STATE_NAME)
+			if (!jobState) {
+				throw new TerminalError('Job not found.')
+			}
+
+			// execute the task
+			const { service, method, key, payload } = jobState.request
+			if (payload) {
+				ctx.genericSend({
+					service,
+					method,
+					parameter: payload,
+					key,
+					inputSerde: serde.json,
+				})
+			} else {
+				ctx.genericSend({
+					service,
+					method,
+					parameter: undefined,
+					key,
+					inputSerde: serde.empty,
+				})
+			}
+
+			await scheduleNextExecution(ctx, jobState.request)
+		},
+		cancel: async (ctx) => {
+			// Cancel the next execution
+			const jobState = await ctx.get(JOB_STATE_NAME)
+			if (jobState) {
+				ctx.cancel(jobState.next_execution_id)
+			}
+
+			// Clear the job state
+			ctx.clearAll()
+		},
+		getInfo: restate.handlers.object.shared(async (ctx) => {
+			return ctx.get(JOB_STATE_NAME)
+		}),
+	},
+})
+
+const scheduleNextExecution = async (ctx, request) => {
+	// Parse cron expression
+	// Persist current date in Restate for deterministic replay
+	const currentDate = await ctx.date.now()
+	let next
+	try {
+		next = new Cron(request.cronExpression).nextRun(new Date(currentDate))
+	} catch (e) {
+		throw new TerminalError(`Invalid cron expression: ${e.message}`)
+	}
+	if (!next) {
+		throw new TerminalError(`Cron expression '${request.cronExpression}' has no future run`)
+	}
+
+	const delay = next.getTime() - currentDate
+
+	// Schedule next execution for this job
+	const thisJobId = ctx.key // This got generated by the CronJobInitiator
+	const handle = ctx.objectSendClient(cronJob, thisJobId).execute(restate.rpc.sendOpts({ delay }))
+
+	// Store the job information
+	const jobState = {
+		request,
+		next_execution_time: next.toString(),
+		next_execution_id: await handle.invocationId,
+	}
+	ctx.set(JOB_STATE_NAME, jobState)
+	return jobState
+}
+
+export { JOB_STATE_NAME }

package/lib/Validation.js

@@ -0,0 +1,39 @@
+import { createValidator } from '@empyria/common'
+
+/**
+ * withValidation — higher-order function that wraps a Restate workflow handler
+ * with AJV schema validation on both the input and the output.
+ *
+ * Why validate at this layer?
+ * Restate deserialises the workflow payload from JSON and passes it directly to
+ * the handler. Without explicit validation there is no guarantee the shape
+ * matches what the handler expects — especially across service versions. By
+ * validating here we get a clear, early error rather than a confusing runtime
+ * failure deep inside business logic.
+ *
+ * The output schema acts as a contract check: if the handler returns something
+ * that doesn't match the declared output type, the error is caught before
+ * Restate records the result.
+ *
+ * Usage:
+ *   handlers: {
+ *     run: withValidation(InputSchema, OutputSchema, async (ctx, input) => { ... })
+ *   }
+ */
+export function withValidation(inputSchema, outputSchema, handler) {
+	const validateInput = createValidator(inputSchema)
+	const validateOutput = createValidator(outputSchema)
+
+	return async (ctx, input) => {
+		// Validate input — throws ValidationError if the payload is malformed.
+		const validatedInput = validateInput(input)
+
+		// Execute the actual workflow logic.
+		const result = await handler(ctx, validatedInput)
+
+		// Validate output — guards against handler implementation drift.
+		const validatedOutput = validateOutput(result)
+
+		return validatedOutput
+	}
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+	"name": "@empyria/restate",
+	"version": "0.1.0",
+	"description": "Restate.dev helpers for the Principia nanoservice framework",
+	"license": "MIT",
+	"author": "Imre Fazekas <imre.fazekas@icloud.com>",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/imrefazekas/empyria-guard-restate.git"
+	},
+	"type": "module",
+	"main": "./index.js",
+	"exports": {
+		".": "./index.js",
+		"./lib/*": "./lib/*.js",
+		"./package.json": "./package.json"
+	},
+	"scripts": {
+		"format": "bun oxfmt --check",
+		"format:fix": "bun oxfmt",
+		"lint": "bun oxlint",
+		"lint:fix": "bun oxlint --fix",
+		"test": "bun test --coverage",
+		"test:watch": "bun test --watch"
+	},
+	"dependencies": {
+		"@empyria/classification": "0.1.0",
+		"@empyria/common": "0.1.0",
+		"@restatedev/restate-sdk": "1.16.6",
+		"@restatedev/restate-sdk-clients": "1.16.6",
+		"@restatedev/restate-sdk-core": "1.16.6",
+		"croner": "10.0.1"
+	},
+	"devDependencies": {
+		"@restatedev/restate-server": "1.7.3",
+		"oxfmt": "0.63.0",
+		"oxlint": "1.78.0"
+	},
+	"engines": {
+		"bun": ">=1.4.0",
+		"node": ">=26"
+	},
+	"packageManager": "bun@1.4.0"
+}