c8y-nitro 0.4.2 → 0.6.0

package/dist/utils.mjs

@@ -3,11 +3,14 @@ import process from "node:process";
 import { useLogger } from "evlog/nitro/v3";
 import { BasicAuth, Client, MicroserviceClientRequestAuth } from "@c8y/client";
 import { defineCachedFunction } from "nitro/cache";
-import { createHash, randomBytes } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { HTTPError, defineHandler } from "nitro/h3";
-import { useStorage } from "nitro/storage";
 import { useRuntimeConfig } from "nitro/runtime-config";
+import { useNitroHooks } from "nitro/app";
+import { c8yManifest } from "c8y-nitro/runtime";
 import { createError, createLogger } from "evlog";
+import { ms } from "itty-time";
+import { tasks } from "#nitro/virtual/tasks";
 //#region src/utils/internal/common.ts
 /**
 * Converts undici Request headers to the format expected by MicroserviceClientRequestAuth.\
@@ -82,6 +85,14 @@ const getCurrentUserTenantId = defineCachedFunction(async (requestOrEvent) => {
 });
 //#endregion
 //#region src/utils/credentials.ts
+let prevCredentials = null;
+function shouldEmitTenantCredentialsUpdated(prev, next) {
+	if (!prev) return true;
+	const prevTenantIds = Object.keys(prev);
+	const nextTenantIds = Object.keys(next);
+	if (prevTenantIds.length !== nextTenantIds.length) return true;
+	return new Set(nextTenantIds).symmetricDifference(new Set(prevTenantIds)).size > 0;
+}
 /**
 * Fetches credentials for all tenants subscribed to this microservice.\
 * Uses bootstrap credentials from runtime config to query the microservice subscriptions API.\
@@ -89,7 +100,7 @@ const getCurrentUserTenantId = defineCachedFunction(async (requestOrEvent) => {
 * @returns Object mapping tenant IDs to their respective credentials
 * @config Cache TTL can be configured via:
 * - `c8y.cache.credentialsTTL` in the Nitro config (value in seconds)
-* - `NITRO_C8Y_CACHE_CREDENTIALS_TTL` environment variable
+* - `NITRO_C8Y_CREDENTIALS_CACHE_TTL` environment variable
 * @example
 * // Get all subscribed tenant credentials:
 * const credentials = await useSubscribedTenantCredentials()
@@ -104,8 +115,8 @@ const getCurrentUserTenantId = defineCachedFunction(async (requestOrEvent) => {
 * // Force refresh:
 * const freshCreds = await useSubscribedTenantCredentials.refresh()
 */
-const useSubscribedTenantCredentials = Object.assign(defineCachedFunction(async () => {
-	return (await Client.getMicroserviceSubscriptions({
+const cachedSubscribedTenantCredentials = defineCachedFunction(async () => {
+	const newCredentials = (await Client.getMicroserviceSubscriptions({
 		tenant: process.env.C8Y_BOOTSTRAP_TENANT,
 		user: process.env.C8Y_BOOTSTRAP_USER,
 		password: process.env.C8Y_BOOTSTRAP_PASSWORD
@@ -113,18 +124,26 @@ const useSubscribedTenantCredentials = Object.assign(defineCachedFunction(async
 		if (cred.tenant) acc[cred.tenant] = cred;
 		return acc;
 	}, {});
+	if (shouldEmitTenantCredentialsUpdated(prevCredentials, newCredentials)) useNitroHooks().callHook("c8y:tenantCredentialsUpdated", prevCredentials, newCredentials);
+	prevCredentials = newCredentials;
+	return newCredentials;
 }, {
 	maxAge: useRuntimeConfig().c8yCredentialsCacheTTL ?? 600,
 	name: "_c8y_nitro_get_subscribed_tenant_credentials",
 	group: "c8y_nitro",
 	swr: false
-}), {
-	invalidate: async () => {
-		await useStorage("cache").removeItem(`c8y_nitro:functions:_c8y_nitro_get_subscribed_tenant_credentials.json`);
-	},
+});
+const useSubscribedTenantCredentials = Object.assign(async () => {
+	const credentials = await cachedSubscribedTenantCredentials();
+	prevCredentials = credentials;
+	return credentials;
+}, {
+	invalidate: cachedSubscribedTenantCredentials.invalidate,
 	refresh: async () => {
-		await useSubscribedTenantCredentials.invalidate();
-		return await useSubscribedTenantCredentials();
+		await cachedSubscribedTenantCredentials.invalidate();
+		const credentials = await cachedSubscribedTenantCredentials();
+		prevCredentials = credentials;
+		return credentials;
 	}
 });
 /**
@@ -157,7 +176,7 @@ const useDeployedTenantCredentials = Object.assign(async () => {
 }, {
 	invalidate: useSubscribedTenantCredentials.invalidate,
 	refresh: async () => {
-		await useDeployedTenantCredentials.invalidate();
+		await useSubscribedTenantCredentials.refresh();
 		return await useDeployedTenantCredentials();
 	}
 });
@@ -318,8 +337,13 @@ async function useUserRoles(requestOrEvent) {
 }
 //#endregion
 //#region src/utils/middleware.ts
+const probePaths = [c8yManifest.livenessProbe?.httpGet?.path, c8yManifest.readinessProbe?.httpGet?.path].filter((path) => Boolean(path));
+function isProbeRequest(pathname) {
+	return probePaths.some((probePath) => pathname.startsWith(probePath));
+}
 function hasUserRequiredRole(roleOrRoles) {
 	return defineHandler(async (event) => {
+		if (isProbeRequest(event.url.pathname)) return;
 		const requiredRoles = Array.isArray(roleOrRoles) ? roleOrRoles : [roleOrRoles];
 		const userRoles = await useUserRoles(event);
 		if (!requiredRoles.some((role) => userRoles.includes(role))) throw new HTTPError({
@@ -331,6 +355,7 @@ function hasUserRequiredRole(roleOrRoles) {
 }
 function isUserFromAllowedTenant(tenantIdOrIds) {
 	return defineHandler(async (event) => {
+		if (isProbeRequest(event.url.pathname)) return;
 		const allowedTenants = Array.isArray(tenantIdOrIds) ? tenantIdOrIds : [tenantIdOrIds];
 		const userTenantId = await getCurrentUserTenantId(event);
 		if (!allowedTenants.includes(userTenantId)) throw new HTTPError({
@@ -357,6 +382,7 @@ function isUserFromAllowedTenant(tenantIdOrIds) {
 */
 function isUserFromDeployedTenant() {
 	return defineHandler(async (event) => {
+		if (isProbeRequest(event.url.pathname)) return;
 		const userTenantId = await getCurrentUserTenantId(event);
 		const deployedTenantId = process.env.C8Y_BOOTSTRAP_TENANT;
 		if (!deployedTenantId) throw new HTTPError({
@@ -372,6 +398,12 @@ function isUserFromDeployedTenant() {
 	});
 }
 //#endregion
+//#region src/utils/internal/tenantOptionFetchers.ts
+/**
+* Internal storage for cached functions per key
+*/
+const tenantOptionFetchers = {};
+//#endregion
 //#region src/utils/tenantOptions.ts
 /**
 * Gets the cache TTL for a specific tenant option key.
@@ -383,22 +415,17 @@ function getTenantOptionCacheTTL(key) {
 	return config.c8yTenantOptionsPerKeyTTL?.[key] ?? config.c8yDefaultTenantOptionsTTL ?? 600;
 }
 /**
-* Internal storage for cached functions per key
-*/
-const tenantOptionFetchers = {};
-/**
 * Factory function that creates a cached fetcher for a specific tenant option key.
 * @param key - The tenant option key
 */
 function createCachedTenantOptionFetcher(key) {
 	const cacheName = `_c8y_nitro_tenant_option_${key.replace(/\./g, "_")}`;
-	const fetcher = defineCachedFunction(async () => {
+	const cachedFetcher = defineCachedFunction(async () => {
 		const client = await useDeployedTenantClient();
 		const category = useRuntimeConfig().c8ySettingsCategory;
-		const apiKey = key.replace(/^credentials\./, "");
 		try {
 			return (await client.options.tenant.detail({
-				key: apiKey,
+				key,
 				category
 			})).data.value;
 		} catch (error) {
@@ -411,17 +438,10 @@ function createCachedTenantOptionFetcher(key) {
 		group: "c8y_nitro",
 		swr: false
 	});
-	return Object.assign(fetcher, {
-		invalidate: async () => {
-			const completeKey = `c8y_nitro:functions:${cacheName}.json`;
-			await useStorage("cache").removeItem(completeKey);
-		},
-		refresh: async () => {
-			const completeKey = `c8y_nitro:functions:${cacheName}.json`;
-			await useStorage("cache").removeItem(completeKey);
-			return await fetcher();
-		}
-	});
+	return Object.assign(cachedFetcher, { refresh: async () => {
+		await cachedFetcher.invalidate();
+		return await cachedFetcher();
+	} });
 }
 /**
 * Gets or creates a cached fetcher for a specific tenant option key.
@@ -448,11 +468,6 @@ function getOrCreateFetcher(key) {
 * - `c8y.cache.tenantOptions` — Per-key TTL overrides
 * - `NITRO_C8Y_DEFAULT_TENANT_OPTIONS_TTL` — Environment variable for default TTL
 *
-* @note For encrypted options (keys starting with `credentials.`), the value is automatically
-* decrypted by Cumulocity if this microservice is the owner of the option (category matches
-* the microservice's settingsCategory/contextPath/name). The `credentials.` prefix is
-* automatically stripped when calling the API.
-*
 * @example
 * // Fetch a tenant option:
 * const value = await useTenantOption('myOption')
@@ -475,16 +490,33 @@ function getOrCreateFetcher(key) {
 const useTenantOption = Object.assign(async (key) => {
 	return await getOrCreateFetcher(key)();
 }, {
+	/**
+	* Invalidate the cache for a specific tenant option key.
+	* @param key - The tenant option key to invalidate
+	*/
 	invalidate: async (key) => {
 		const fetcher = tenantOptionFetchers[key];
 		if (fetcher) await fetcher.invalidate();
 	},
+	/**
+	* Force refresh a specific tenant option key (invalidates and re-fetches).
+	* @param key - The tenant option key to refresh
+	*/
 	refresh: async (key) => {
 		return await getOrCreateFetcher(key).refresh();
 	},
+	/**
+	* Invalidate all tenant option caches that have been accessed.
+	* Only invalidates keys that have been fetched at least once.
+	*/
 	invalidateAll: async () => {
 		await Promise.all(Object.values(tenantOptionFetchers).map((fetcher) => fetcher?.invalidate()));
 	},
+	/**
+	* Refresh all tenant options that have been accessed.
+	* Only refreshes keys that have been fetched at least once.
+	* @returns Object mapping keys to their refreshed values
+	*/
 	refreshAll: async () => {
 		const entries = Object.entries(tenantOptionFetchers);
 		const values = await Promise.all(entries.map(([, fetcher]) => fetcher?.refresh()));
@@ -492,4 +524,168 @@ const useTenantOption = Object.assign(async (key) => {
 	}
 });
 //#endregion
-export { createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };
+//#region src/utils/schedule.ts
+const MAX_TIMEOUT_MS = 2147483647;
+const SCHEDULE_LOOKAHEAD_MS = 3600 * 1e3;
+const SCHEDULER_TICK_MS = 100;
+const scheduledTasks = /* @__PURE__ */ new Map();
+const scheduledTaskTimers = /* @__PURE__ */ new Map();
+const schedulerReady = Promise.resolve();
+let schedulerInterval;
+function createScheduledTaskId() {
+	return randomUUID();
+}
+function resolveScheduleTime(schedule) {
+	if (schedule instanceof Date) {
+		const timestamp = schedule.getTime();
+		if (Number.isNaN(timestamp)) throw new TypeError("schedule date must be valid");
+		return timestamp;
+	}
+	if (typeof schedule === "number") {
+		if (!Number.isFinite(schedule) || schedule < 0) throw new TypeError("schedule number must be a non-negative number of seconds");
+		return Date.now() + schedule * 1e3;
+	}
+	const delay = ms(schedule);
+	if (!Number.isFinite(delay) || delay < 0) throw new TypeError("schedule string must be a valid non-negative duration");
+	return Date.now() + delay;
+}
+async function executeScheduledTask(id) {
+	const record = scheduledTasks.get(id);
+	if (!record) return;
+	if (record.timeoutId !== void 0) scheduledTaskTimers.delete(record.timeoutId);
+	scheduledTasks.delete(id);
+	stopSchedulerIntervalIfIdle();
+	const taskDef = tasks[record.taskName];
+	if (!taskDef) throw new Error(`Task "${record.taskName}" is not available!`);
+	if (!taskDef.resolve) throw new Error(`Task "${record.taskName}" is not implemented!`);
+	await (await taskDef.resolve()).run({
+		name: record.taskName,
+		payload: record.payload,
+		context: record.context
+	});
+}
+function armScheduledTaskTimeout(id) {
+	const record = scheduledTasks.get(id);
+	if (!record || record.timeoutId !== void 0) return;
+	const remainingMs = Math.max(record.runAt - Date.now(), 0);
+	if (remainingMs > SCHEDULE_LOOKAHEAD_MS) return;
+	const timeout = setTimeout(() => {
+		executeScheduledTask(id);
+	}, Math.min(remainingMs, MAX_TIMEOUT_MS));
+	record.timeoutId = Number(timeout);
+	scheduledTaskTimers.set(record.timeoutId, timeout);
+}
+function runSchedulerTick() {
+	for (const record of scheduledTasks.values()) armScheduledTaskTimeout(record.id);
+}
+function ensureSchedulerInterval() {
+	if (schedulerInterval) return;
+	schedulerInterval = setInterval(runSchedulerTick, SCHEDULER_TICK_MS);
+}
+function stopSchedulerIntervalIfIdle() {
+	if (!schedulerInterval || scheduledTasks.size > 0) return;
+	clearInterval(schedulerInterval);
+	schedulerInterval = void 0;
+}
+/**
+* Schedules a Nitro task to run once in the future.\
+* Resolves and calls the task handler directly from Nitro's virtual task registry\
+* Numbers are treated as seconds, strings are parsed as human-readable durations, and dates are used as exact run times.
+*
+* @param taskName - The Nitro task name to run (from `tasks/*.ts`)
+* @param options - Task payload, context, and the schedule time
+* @returns Information about the scheduled task
+*
+* @example
+* // Run a task in 30 seconds:
+* const scheduled = await scheduleTask('emails:send', {
+*   payload: { messageId: 'abc123' },
+*   schedule: 30,
+* })
+*
+* @example
+* // Run a task using a human-readable duration:
+* await scheduleTask('reports:generate', {
+*   payload: { reportId: 'report-1' },
+*   schedule: '1 hour',
+* })
+*
+* @example
+* // Run a task at an exact time:
+* await scheduleTask('cleanup:tenant', {
+*   payload: { tenant: 't12345' },
+*   schedule: new Date('2026-05-01T12:00:00Z'),
+* })
+*/
+async function scheduleTask(taskName, options) {
+	if (!import.meta._tasks) throw new Error("scheduleTask() requires tasks to be enabled. Set `experimental: { tasks: true }` in your nitro.config.ts.");
+	if (!taskName) throw new TypeError("taskName is required");
+	const runAt = resolveScheduleTime(options.schedule);
+	const record = {
+		id: createScheduledTaskId(),
+		taskName,
+		payload: options.payload ?? {},
+		context: options.context ?? {},
+		runAt
+	};
+	scheduledTasks.set(record.id, record);
+	armScheduledTaskTimeout(record.id);
+	ensureSchedulerInterval();
+	return {
+		id: record.id,
+		task: record.taskName,
+		runAt: new Date(record.runAt).toISOString()
+	};
+}
+/**
+* Lists all tasks that are currently scheduled and have not started yet.\
+* The returned object is keyed by the scheduled task UUID for easy lookup and cancellation.
+*
+* @returns Object mapping scheduled task IDs to their public task information
+*
+* @example
+* const tasks = await listScheduledTasks()
+* for (const [id, task] of Object.entries(tasks)) {
+*   console.log(id, task.task, task.runAt)
+* }
+*/
+async function listScheduledTasks() {
+	await schedulerReady;
+	return Object.fromEntries([...scheduledTasks.values()].map((record) => [record.id, {
+		id: record.id,
+		task: record.taskName,
+		runAt: new Date(record.runAt).toISOString()
+	}]));
+}
+/**
+* Cancels a scheduled task before it starts running.\
+* Once the underlying Nitro task has started, it cannot be cancelled with this utility.
+*
+* @param id - The scheduled task UUID returned by `scheduleTask()` or `listScheduledTasks()`
+* @returns `true` when a pending task was cancelled, otherwise `false`
+*
+* @example
+* const scheduled = await scheduleTask('emails:send', {
+*   payload: { messageId: 'abc123' },
+*   schedule: '10 minutes',
+* })
+*
+* const cancelled = await cancelScheduledTask(scheduled.id)
+*/
+async function cancelScheduledTask(id) {
+	await schedulerReady;
+	const record = scheduledTasks.get(id);
+	if (!record) return false;
+	if (record.timeoutId !== void 0) {
+		const timeout = scheduledTaskTimers.get(record.timeoutId);
+		if (timeout) {
+			clearTimeout(timeout);
+			scheduledTaskTimers.delete(record.timeoutId);
+		}
+	}
+	const cancelled = scheduledTasks.delete(id);
+	stopSchedulerIntervalIfIdle();
+	return cancelled;
+}
+//#endregion
+export { cancelScheduledTask, createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, listScheduledTasks, scheduleTask, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8y-nitro",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "type": "module",
   "description": "Lightning fast Cumulocity IoT microservice development powered by Nitro",
   "keywords": [
@@ -23,22 +23,12 @@
     "url": "https://github.com/schplitt/c8y-nitro/issues"
   },
   "exports": {
-    ".": {
-      "types": "./dist/index.d.mts",
-      "import": "./dist/index.mjs"
-    },
-    "./types": {
-      "types": "./dist/types.d.mts",
-      "import": "./dist/types.mjs"
-    },
-    "./utils": {
-      "types": "./dist/utils.d.mts",
-      "import": "./dist/utils.mjs"
-    }
+    ".": "./dist/index.mjs",
+    "./cli": "./dist/cli/index.mjs",
+    "./types": "./dist/types.mjs",
+    "./utils": "./dist/utils.mjs",
+    "./package.json": "./package.json"
   },
-  "main": "./dist/index.mjs",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.mts",
   "bin": {
     "c8y-nitro": "./dist/cli/index.mjs"
   },
@@ -48,30 +38,34 @@
     "dist"
   ],
   "dependencies": {
-    "c12": "^4.0.0-beta.4",
-    "citty": "^0.2.1",
+    "c12": "^4.0.0-beta.5",
+    "citty": "^0.2.2",
     "consola": "^3.4.2",
-    "evlog": "^2.9.0",
+    "evlog": "^2.17.0",
+    "itty-time": "^2.0.2",
     "jszip": "^3.10.1",
     "pathe": "^2.0.3",
-    "pkg-types": "^2.3.0",
+    "pkg-types": "^2.3.1",
     "spinnies": "^0.5.1",
-    "tinyexec": "^1.0.4"
+    "tinyexec": "^1.1.2"
   },
   "devDependencies": {
-    "@schplitt/eslint-config": "^1.3.1",
+    "@schplitt/eslint-config": "^1.5.0",
+    "@types/node": "^24.12.3",
     "@types/spinnies": "^0.5.3",
-    "bumpp": "^11.0.1",
+    "bumpp": "^11.1.0",
     "changelogithub": "^14.0.0",
-    "eslint": "^10.1.0",
-    "memfs": "^4.57.1",
-    "tsdown": "^0.21.4",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.0"
+    "eslint": "^10.3.0",
+    "memfs": "^4.57.2",
+    "tsdown": "^0.22.0",
+    "tsnapi": "^0.3.3",
+    "typescript": "^6.0.3",
+    "vitepress": "2.0.0-alpha.17",
+    "vitest": "^4.1.6"
   },
   "peerDependencies": {
     "@c8y/client": ">=1021",
-    "nitro": "3.0.260311-beta"
+    "nitro": "3.0.260429-beta"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -79,12 +73,16 @@
   "scripts": {
     "dev": "tsdown --watch",
     "build": "tsdown",
+    "build:update": "tsdown --update-snapshot",
     "lint": "eslint",
     "lint:fix": "eslint --fix",
     "typecheck": "tsc --noEmit",
     "prerelease": "eslint && tsc --noEmit && tsdown && vitest run",
     "release": "bumpp",
     "test": "vitest",
-    "test:run": "vitest run"
+    "test:run": "vitest run",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   }
 }