feat(tasks): allow management of job intervals and disabling them (#3408)

packages/cron-job-api/eslint.config.js

@@ -0,0 +1,9 @@
+import baseConfig from "@homarr/eslint-config/base";
+
+/** @type {import('typescript-eslint').Config} */
+export default [
+  {
+    ignores: [],
+  },
+  ...baseConfig,
+];

packages/cron-job-api/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@homarr/cron-job-api",
+  "version": "0.1.0",
+  "private": true,
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./env": "./src/env.ts",
+    "./constants": "./src/constants.ts",
+    "./client": "./src/client.ts"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "src/*"
+      ]
+    }
+  },
+  "scripts": {
+    "clean": "rm -rf .turbo node_modules",
+    "format": "prettier --check . --ignore-path ../../.gitignore",
+    "lint": "eslint",
+    "typecheck": "tsc --noEmit"
+  },
+  "prettier": "@homarr/prettier-config",
+  "dependencies": {
+    "@homarr/common": "workspace:^0.1.0",
+    "@homarr/cron-jobs": "workspace:^0.1.0",
+    "@homarr/env": "workspace:^0.1.0",
+    "@homarr/log": "workspace:^0.1.0",
+    "@tanstack/react-query": "^5.81.5",
+    "@trpc/client": "^11.4.3",
+    "@trpc/server": "^11.4.3",
+    "@trpc/tanstack-react-query": "^11.4.3",
+    "node-cron": "^4.2.0",
+    "react": "19.1.0",
+    "zod": "^3.25.67"
+  },
+  "devDependencies": {
+    "@homarr/eslint-config": "workspace:^0.2.0",
+    "@homarr/prettier-config": "workspace:^0.1.0",
+    "@homarr/tsconfig": "workspace:^0.1.0",
+    "@types/node-cron": "^3.0.11",
+    "@types/react": "19.1.8",
+    "eslint": "^9.30.1",
+    "typescript": "^5.8.3"
+  }
+}

packages/cron-job-api/src/client.ts

@@ -0,0 +1,20 @@
+import { createTRPCClient, httpLink } from "@trpc/client";
+
+import type { JobRouter } from ".";
+import { CRON_JOB_API_KEY_HEADER, CRON_JOB_API_PATH, CRON_JOB_API_PORT } from "./constants";
+import { env } from "./env";
+
+export const cronJobApi = createTRPCClient<JobRouter>({
+  links: [
+    httpLink({
+      url: `${getBaseUrl()}${CRON_JOB_API_PATH}`,
+      headers: {
+        [CRON_JOB_API_KEY_HEADER]: env.CRON_JOB_API_KEY,
+      },
+    }),
+  ],
+});
+
+function getBaseUrl() {
+  return `http://localhost:${CRON_JOB_API_PORT}`;
+}

packages/cron-job-api/src/constants.ts

@@ -0,0 +1,3 @@
+export const CRON_JOB_API_PORT = 3002;
+export const CRON_JOB_API_PATH = "/trpc";
+export const CRON_JOB_API_KEY_HEADER = "cron-job-api-key";

packages/cron-job-api/src/env.ts

@@ -0,0 +1,11 @@
+import { z } from "zod/v4";
+
+import { env as commonEnv } from "@homarr/common/env";
+import { createEnv } from "@homarr/env";
+
+export const env = createEnv({
+  server: {
+    CRON_JOB_API_KEY: commonEnv.NODE_ENV === "development" ? z.string().default("test") : z.string(),
+  },
+  experimental__runtimeEnv: process.env,
+});

packages/cron-job-api/src/index.ts

@@ -0,0 +1,82 @@
+import { initTRPC, TRPCError } from "@trpc/server";
+import { validate } from "node-cron";
+import { z } from "zod/v4";
+
+import type { JobGroupKeys } from "@homarr/cron-jobs";
+import { jobGroup } from "@homarr/cron-jobs";
+
+import { env } from "./env";
+
+export const jobGroupKeys = jobGroup.getKeys();
+export const jobNameSchema = z.enum(jobGroup.getKeys());
+
+export interface IJobManager {
+  startAsync(name: JobGroupKeys): Promise<void>;
+  triggerAsync(name: JobGroupKeys): Promise<void>;
+  stopAsync(name: JobGroupKeys): Promise<void>;
+  updateIntervalAsync(name: JobGroupKeys, cron: string): Promise<void>;
+  disableAsync(name: JobGroupKeys): Promise<void>;
+  enableAsync(name: JobGroupKeys): Promise<void>;
+  getAllAsync(): Promise<{ name: JobGroupKeys; cron: string; preventManualExecution: boolean; isEnabled: boolean }[]>;
+}
+
+const t = initTRPC
+  .context<{
+    manager: IJobManager;
+    apiKey?: string;
+  }>()
+  .create();
+
+const createTrpcRouter = t.router;
+const apiKeyProcedure = t.procedure.use(({ ctx, next }) => {
+  if (ctx.apiKey !== env.CRON_JOB_API_KEY) {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "Missing or invalid API key",
+    });
+  }
+
+  return next({
+    ctx: {
+      ...ctx,
+      apiKey: undefined, // Clear the API key after checking
+    },
+  });
+});
+
+export const cronExpressionSchema = z.string().refine((expression) => validate(expression), {
+  error: "Invalid cron expression",
+});
+
+export const jobRouter = createTrpcRouter({
+  start: apiKeyProcedure.input(jobNameSchema).mutation(async ({ input, ctx }) => {
+    await ctx.manager.startAsync(input);
+  }),
+  trigger: apiKeyProcedure.input(jobNameSchema).mutation(async ({ input, ctx }) => {
+    await ctx.manager.triggerAsync(input);
+  }),
+  stop: apiKeyProcedure.input(jobNameSchema).mutation(async ({ input, ctx }) => {
+    await ctx.manager.stopAsync(input);
+  }),
+  updateInterval: apiKeyProcedure
+    .input(
+      z.object({
+        name: jobNameSchema,
+        cron: cronExpressionSchema,
+      }),
+    )
+    .mutation(async ({ input, ctx }) => {
+      await ctx.manager.updateIntervalAsync(input.name, input.cron);
+    }),
+  disable: apiKeyProcedure.input(jobNameSchema).mutation(async ({ input, ctx }) => {
+    await ctx.manager.disableAsync(input);
+  }),
+  enable: apiKeyProcedure.input(jobNameSchema).mutation(async ({ input, ctx }) => {
+    await ctx.manager.enableAsync(input);
+  }),
+  getAll: apiKeyProcedure.query(({ ctx }) => {
+    return ctx.manager.getAllAsync();
+  }),
+});
+
+export type JobRouter = typeof jobRouter;

packages/cron-job-api/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@homarr/tsconfig/base.json",
+  "compilerOptions": {
+    "tsBuildInfoFile": "node_modules/.cache/tsbuildinfo.json"
+  },
+  "include": ["*.ts", "src"],
+  "exclude": ["node_modules"]
+}