c8y-nitro 0.6.0 → 0.7.1

package/dist/runtime/handlers/invalidateTenantOptions.mjs

@@ -1,17 +1,416 @@
-import { t as createError } from "../../logging-CVlaRS4O.mjs";
+import { t as createError } from "../../logging-BUYT8Z2V.mjs";
+import { t as useDeployedTenantClient } from "../../client-DxmbyZju.mjs";
 import { c8yTenantOptionKeys } from "c8y-nitro/runtime";
+import { defineCachedFunction } from "nitro/cache";
+import { useRuntimeConfig } from "nitro/runtime-config";
 import { defineEventHandler, getQuery } from "nitro/h3";
 //#region src/utils/internal/tenantOptionFetchers.ts
 /**
-* Internal storage for cached functions per key
+* Internal storage for cached option fetchers, keyed by
+* `${tenant}::${category}::${key}`.
+*
+* Including the tenant and category in the key keeps options from different
+* tenants (multi-tenancy) and settings categories from colliding on a shared
+* `key`.
 */
 const tenantOptionFetchers = {};
+/**
+* Builds the composite store key for a tenant/category/key triple.
+* @param tenant - The tenant id owning the option
+* @param category - The settings category
+* @param key - The tenant option key
+*/
+function fetcherStoreKey(tenant, category, key) {
+	return `${tenant}::${category}::${key}`;
+}
+//#endregion
+//#region src/utils/tenantOptions.ts
+/**
+* The microservice's own settings category, resolved once from runtime config
+* (`manifest.settingsCategory` → `contextPath` → `name`). This is independent of
+* which tenant is targeted.
+*/
+function getOwnCategory() {
+	return useRuntimeConfig().c8ySettingsCategory;
+}
+/**
+* Resolves the tenant id a client operates on, used for per-tenant cache keys.
+*
+* Prefers the stamped `client.core.tenant` (set by the `use*Client` helpers);
+* otherwise resolves it on demand via `/tenant/currentTenant` and memoizes it
+* back onto the client.
+* @param client - The Cumulocity client
+*/
+async function resolveClientTenant(client) {
+	if (client.core.tenant) return client.core.tenant;
+	const res = await client.core.fetch("/tenant/currentTenant", {
+		method: "GET",
+		headers: { Accept: "application/json" }
+	});
+	const tenant = res.ok ? (await res.json())?.name : void 0;
+	if (!tenant) throw createError({
+		status: 500,
+		message: "Could not determine the target tenant",
+		fix: "This is unexpected. Retry the request, and contact the microservice operator if it keeps happening.",
+		internal: {
+			reason: res.ok ? "GET /tenant/currentTenant returned no tenant name" : "GET /tenant/currentTenant failed",
+			upstreamStatus: res.status
+		}
+	});
+	client.core.tenant = tenant;
+	return tenant;
+}
+/**
+* Builds the Cumulocity Options API path for a category (and optional key).
+* @param category - The settings category
+* @param key - The tenant option key (omit for category-level operations)
+*/
+function optionsPath(category, key) {
+	const base = `/tenant/options/${encodeURIComponent(category)}`;
+	return key === void 0 ? base : `${base}/${encodeURIComponent(key)}`;
+}
+/**
+* Cumulocity role required to read tenant options.
+*/
+const OPTION_READ_ROLE = "ROLE_OPTION_MANAGEMENT_READ";
+/**
+* Cumulocity role required to create, update or delete tenant options.
+*/
+const OPTION_ADMIN_ROLE = "ROLE_OPTION_MANAGEMENT_ADMIN";
+/**
+* Builds a structured error for a failed Options API request.
+*
+* A failed options request is a microservice/config problem (e.g. a missing
+* `ROLE_OPTION_MANAGEMENT_*` role), not something the frontend caller can act on
+* — so the response is a **generic 500** that reveals nothing about tenant
+* options. All the diagnostic detail (which operation, upstream status, internal
+* endpoint/method, and the Cumulocity role it needs) goes into `internal`, which
+* is logged for debugging but never serialized to the HTTP response.
+* @param status - The upstream HTTP status (for `internal`)
+* @param operation - A human-readable summary of the failed operation (for `internal`)
+* @param internal - Backend-only debugging context (endpoint, method, required role)
+*/
+function optionRequestError(status, operation, internal) {
+	return createError({
+		status: 500,
+		message: "Internal Server Error",
+		internal: {
+			operation,
+			upstreamStatus: status,
+			...internal
+		}
+	});
+}
+/**
+* Reads a single option value directly from the Options API.
+* Returns `undefined` when the option is not set (404).
+* @param client - The Cumulocity client (determines tenant + auth)
+* @param category - The settings category
+* @param key - The tenant option key
+*/
+async function fetchOptionValue(client, category, key) {
+	const endpoint = optionsPath(category, key);
+	const res = await client.core.fetch(endpoint, {
+		method: "GET",
+		headers: { Accept: "application/json" }
+	});
+	if (res.status === 404) return;
+	if (!res.ok) throw optionRequestError(res.status, `Failed to read tenant option '${key}'`, {
+		method: "GET",
+		endpoint,
+		requiredRole: OPTION_READ_ROLE
+	});
+	return (await res.json())?.value;
+}
+/**
+* Creates or updates a single option value (upsert) via the Options API.
+* @param client - The Cumulocity client (determines tenant + auth)
+* @param category - The settings category
+* @param key - The tenant option key
+* @param value - The value to store
+*/
+async function putOptionValue(client, category, key, value) {
+	const endpoint = optionsPath(category, key);
+	const res = await client.core.fetch(endpoint, {
+		method: "PUT",
+		headers: {
+			"Content-Type": "application/json",
+			"Accept": "application/json"
+		},
+		body: JSON.stringify({ value })
+	});
+	if (!res.ok) throw optionRequestError(res.status, `Failed to set tenant option '${key}'`, {
+		method: "PUT",
+		endpoint,
+		requiredRole: OPTION_ADMIN_ROLE
+	});
+}
+/**
+* Deletes a single option via the Options API. Idempotent: a 404 resolves.
+* @param client - The Cumulocity client (determines tenant + auth)
+* @param category - The settings category
+* @param key - The tenant option key
+*/
+async function deleteOptionValue(client, category, key) {
+	const endpoint = optionsPath(category, key);
+	const res = await client.core.fetch(endpoint, {
+		method: "DELETE",
+		headers: { Accept: "application/json" }
+	});
+	if (res.status === 404) return;
+	if (!res.ok) throw optionRequestError(res.status, `Failed to delete tenant option '${key}'`, {
+		method: "DELETE",
+		endpoint,
+		requiredRole: OPTION_ADMIN_ROLE
+	});
+}
+/**
+* Updates the `editable` flag of a single option (management tenant only).
+* @param client - The Cumulocity client (must be the management tenant)
+* @param category - The settings category
+* @param key - The tenant option key
+* @param editable - Whether the option may be edited
+* @param targetTenant - The tenant whose option flag is updated
+*/
+async function putOptionEditable(client, category, key, editable, targetTenant) {
+	const endpoint = `${optionsPath(category, key)}/editable`;
+	const res = await client.core.fetch(`${endpoint}?targetTenant=${encodeURIComponent(targetTenant)}`, {
+		method: "PUT",
+		headers: {
+			"Content-Type": "application/json",
+			"Accept": "application/json"
+		},
+		body: JSON.stringify({ editable })
+	});
+	if (!res.ok) throw optionRequestError(res.status, `Failed to update editable flag for tenant option '${key}'`, {
+		method: "PUT",
+		endpoint,
+		targetTenant,
+		requiredRole: `${OPTION_ADMIN_ROLE} (management tenant only)`
+	});
+}
+/**
+* Lists all options set in a category as a key/value map.
+* @param client - The Cumulocity client (determines tenant + auth)
+* @param category - The settings category
+*/
+async function listCategoryOptions(client, category) {
+	const endpoint = optionsPath(category);
+	const res = await client.core.fetch(endpoint, {
+		method: "GET",
+		headers: { Accept: "application/json" }
+	});
+	if (res.status === 404) return {};
+	if (!res.ok) throw optionRequestError(res.status, `Failed to list tenant options for category '${category}'`, {
+		method: "GET",
+		endpoint,
+		requiredRole: OPTION_READ_ROLE
+	});
+	return { ...await res.json() };
+}
+/**
+* Gets the cache TTL for a specific tenant option key.
+* Uses per-key override if defined, otherwise falls back to the default TTL.
+* @param key - The tenant option key
+*/
+function getTenantOptionCacheTTL(key) {
+	const config = useRuntimeConfig();
+	return config.c8yTenantOptionsPerKeyTTL?.[key] ?? config.c8yDefaultTenantOptionsTTL ?? 600;
+}
+/**
+* Factory that creates a cached read fetcher for a specific tenant/category/key.
+* All fetchers share the same cache group so they can be invalidated together.
+* @param client - The Cumulocity client (determines tenant + auth)
+* @param tenant - The tenant id (for the cache key)
+* @param category - The settings category
+* @param key - The tenant option key
+*/
+function createCachedTenantOptionFetcher(client, tenant, category, key) {
+	const cacheName = `_c8y_nitro_tenant_option_${fetcherStoreKey(tenant, category, key).replace(/[^a-zA-Z0-9]/g, "_")}`;
+	const cachedFetcher = defineCachedFunction(async () => fetchOptionValue(client, category, key), {
+		maxAge: getTenantOptionCacheTTL(key),
+		name: cacheName,
+		group: "c8y_nitro",
+		swr: false
+	});
+	return Object.assign(cachedFetcher, { refresh: async () => {
+		await cachedFetcher.invalidate();
+		return await cachedFetcher();
+	} });
+}
+/**
+* Gets or creates the cached read fetcher for a tenant/category/key triple.
+* @param client - The Cumulocity client (determines tenant + auth)
+* @param tenant - The resolved tenant id
+* @param category - The settings category
+* @param key - The tenant option key
+*/
+function getOrCreateFetcher(client, tenant, category, key) {
+	const storeKey = fetcherStoreKey(tenant, category, key);
+	let fetcher = tenantOptionFetchers[storeKey];
+	if (!fetcher) {
+		fetcher = createCachedTenantOptionFetcher(client, tenant, category, key);
+		tenantOptionFetchers[storeKey] = fetcher;
+	}
+	return fetcher;
+}
+/**
+* Invalidates the cached read for a store key, if one has been created.
+* @param storeKey - The composite `${tenant}::${category}::${key}` store key
+*/
+async function invalidateStoreKey(storeKey) {
+	const fetcher = tenantOptionFetchers[storeKey];
+	if (fetcher) await fetcher.invalidate();
+}
+/**
+* Invalidates every created fetcher whose store key matches the predicate.
+* @param predicate - Selects store keys to invalidate
+*/
+async function invalidateFetchers(predicate) {
+	await Promise.all(Object.entries(tenantOptionFetchers).filter(([storeKey]) => predicate(storeKey)).map(([, fetcher]) => fetcher.invalidate()));
+}
+/**
+* Refreshes every created fetcher whose store key matches the predicate.
+* @param predicate - Selects store keys to refresh
+* @returns Map of matched store keys to their refreshed values
+*/
+async function refreshFetchers(predicate) {
+	const entries = Object.entries(tenantOptionFetchers).filter(([storeKey]) => predicate(storeKey));
+	const values = await Promise.all(entries.map(([, fetcher]) => fetcher.refresh()));
+	return Object.fromEntries(entries.map(([storeKey], i) => [storeKey, values[i]]));
+}
+/**
+* Builds a single-option handle for a client/category/key.
+* @param client - The Cumulocity client (determines tenant + auth)
+* @param category - The settings category
+* @param key - The tenant option key
+*/
+function makeTenantOption(client, category, key) {
+	const currentStoreKey = async () => fetcherStoreKey(await resolveClientTenant(client), category, key);
+	const readFetcher = async () => getOrCreateFetcher(client, await resolveClientTenant(client), category, key);
+	return {
+		read: async () => (await readFetcher())(),
+		set: async (value) => {
+			await putOptionValue(client, category, key, value);
+			await invalidateStoreKey(await currentStoreKey());
+		},
+		getOrInsert: async (fallback) => {
+			const current = await (await readFetcher())();
+			if (current !== void 0) return current;
+			await putOptionValue(client, category, key, fallback);
+			await invalidateStoreKey(await currentStoreKey());
+			return fallback;
+		},
+		delete: async () => {
+			await deleteOptionValue(client, category, key);
+			await invalidateStoreKey(await currentStoreKey());
+		},
+		setEditable: async (editable, options) => {
+			await putOptionEditable(client, category, key, editable, options.targetTenant);
+			await invalidateStoreKey(await currentStoreKey());
+		},
+		refresh: async () => (await readFetcher()).refresh(),
+		invalidate: async () => invalidateStoreKey(await currentStoreKey())
+	};
+}
+/**
+* Builds a category handle. The runtime shape is identical for the own and
+* foreign categories; the public overloads differ only at the type level.
+* @param client - The Cumulocity client (determines tenant + auth)
+* @param category - The settings category
+*/
+function makeTenantOptionCategory(client, category) {
+	const categoryPrefix = async () => `${await resolveClientTenant(client)}::${category}::`;
+	return {
+		option: (key) => makeTenantOption(client, category, key),
+		list: () => listCategoryOptions(client, category),
+		setAll: async (values) => {
+			const entries = Object.entries(values);
+			await Promise.all(entries.map(([key, value]) => putOptionValue(client, category, key, value)));
+			const tenant = await resolveClientTenant(client);
+			await Promise.all(entries.map(([key]) => invalidateStoreKey(fetcherStoreKey(tenant, category, key))));
+		},
+		invalidateAll: async () => {
+			const prefix = await categoryPrefix();
+			await invalidateFetchers((storeKey) => storeKey.startsWith(prefix));
+		},
+		refreshAll: async () => {
+			const prefix = await categoryPrefix();
+			const refreshed = await refreshFetchers((storeKey) => storeKey.startsWith(prefix));
+			return Object.fromEntries(Object.entries(refreshed).map(([storeKey, value]) => [storeKey.slice(prefix.length), value]));
+		}
+	};
+}
+/**
+* Gets a handle for a single tenant option in the microservice's **own** settings
+* category, targeting the tenant of the given `client`.\
+* Reads are cached per tenant, using the client's service user credentials.
+*
+* This is a shortcut for `useTenantOptions(client).option(key)` — it only drops
+* the category argument. For a single option in a **foreign** category, use
+* `useTenantOptions(client, category).option(key)`.
+*
+* Manifest-declared keys are offered via autocomplete, but any dynamic string
+* is accepted too (e.g. `encrypted.password.${hash}`).
+*
+* @param client - The Cumulocity client that determines the target tenant
+* @param key - The tenant option key
+*
+* @config Cache TTL can be configured via:
+* - `c8y.cache.defaultTenantOptionsTTL` — Default TTL for all keys (in seconds)
+* - `c8y.cache.tenantOptions` — Per-key TTL overrides
+* - `NITRO_C8Y_DEFAULT_TENANT_OPTIONS_TTL` — Environment variable for default TTL
+*
+* @example
+* // Read the owner tenant's config:
+* const value = await useTenantOption(await useDeployedTenantClient(), 'featureMode').read()
+*
+* // Read the current request tenant's config (multi-tenant):
+* const value = await useTenantOption(await useUserTenantClient(event), 'featureMode').read()
+*
+* // Create or update, or seed a dynamic key:
+* await useTenantOption(client, 'featureMode').set('advanced')
+* const token = await useTenantOption(client, `encrypted.password.${hash}`).getOrInsert('')
+*/
+function useTenantOption(client, key) {
+	return makeTenantOption(client, getOwnCategory(), key);
+}
+const useTenantOptionsBase = ((client, category) => makeTenantOptionCategory(client, category ?? getOwnCategory()));
+/**
+* Gets a handle for a whole settings category, targeting the tenant of the given
+* `client`.\
+* Omit the category (or pass the own {@link C8YSettingsCategory}) for the
+* microservice's own category; pass any other category to read/write options in
+* a foreign category (where `credentials.*` keys are rejected).
+*
+* @param client - The Cumulocity client that determines the target tenant
+*
+* @example
+* const client = await useUserTenantClient(event)
+*
+* // Own category:
+* const values = await useTenantOptions(client).list()
+* await useTenantOptions(client).option('featureMode').set('advanced')
+*
+* // Foreign category:
+* const value = await useTenantOptions(client, 'other-service').option('someKey').read()
+*
+* // Invalidate all cached options of one tenant + category:
+* await useTenantOptions(client, 'other-service').invalidateAll()
+*
+* // Invalidate everything, across all tenants and categories:
+* await useTenantOptions.invalidateAll()
+*/
+const useTenantOptions = Object.assign(useTenantOptionsBase, {
+	invalidateAll: () => invalidateFetchers(() => true),
+	refreshAll: () => refreshFetchers(() => true)
+});
 //#endregion
 //#region src/module/runtime/handlers/invalidateTenantOptions.ts
 var invalidateTenantOptions_default = defineEventHandler(async (event) => {
 	const query = getQuery(event);
 	if ("all" in query) {
-		await Promise.all(Object.values(tenantOptionFetchers).map((fetcher) => fetcher?.invalidate()));
+		await useTenantOptions.invalidateAll();
 		return { message: "success" };
 	}
 	const key = Array.isArray(query.key) ? query.key[0] : query.key;
@@ -27,8 +426,7 @@ var invalidateTenantOptions_default = defineEventHandler(async (event) => {
 		why: "Only tenant option keys declared in manifest.settings can be invalidated via this route",
 		fix: "Use ?all to invalidate all created tenant option caches or provide a valid manifest-defined key in ?key"
 	});
-	const fetcher = tenantOptionFetchers[key];
-	if (fetcher) await fetcher.invalidate();
+	await useTenantOption(await useDeployedTenantClient(), key).invalidate();
 	return { message: "success" };
 });
 //#endregion

package/dist/runtime/handlers/openapi.mjs

@@ -0,0 +1,56 @@
+import { n as getUserTenantDomain } from "../../client-DxmbyZju.mjs";
+import { c8yManifest } from "c8y-nitro/runtime";
+import { useRuntimeConfig } from "nitro/runtime-config";
+import { getRequestURL } from "nitro/h3";
+import { defineMiddleware } from "nitro";
+//#region src/module/runtime/handlers/openapi.ts
+function isOpenAPIDocument(value) {
+	return Boolean(value) && typeof value === "object" && "openapi" in value;
+}
+function joinURLSegments(origin, ...segments) {
+	const path = segments.map((segment) => segment?.replace(/^\/+|\/+$/g, "") ?? "").filter((segment) => segment.length > 0).join("/");
+	return path ? `${origin}/${path}` : origin;
+}
+async function resolveServer(event) {
+	const baseURL = useRuntimeConfig().app?.baseURL;
+	const contextPath = c8yManifest.contextPath ?? c8yManifest.name;
+	if (!import.meta.dev) try {
+		const domain = await getUserTenantDomain(event);
+		if (domain) return {
+			url: joinURLSegments(`https://${domain}`, "service", contextPath, baseURL),
+			description: "Cumulocity microservice endpoint"
+		};
+	} catch {}
+	const requestUrl = getRequestURL(event, {
+		xForwardedHost: true,
+		xForwardedProto: true
+	});
+	if (event.req.headers.has("x-forwarded-host")) return {
+		url: joinURLSegments(requestUrl.origin, "service", contextPath, baseURL),
+		description: "Cumulocity microservice endpoint"
+	};
+	return {
+		url: joinURLSegments(requestUrl.origin, baseURL),
+		description: "Direct server endpoint"
+	};
+}
+/**
+* Transforms the OpenAPI document generated by Nitro for Cumulocity microservices:
+* strips internal routes (probes, `/_c8y_nitro/**`, the spec/UI routes themselves)
+* and rewrites the advertised server URL to the public tenant endpoint instead of
+* the internal (e.g. cluster-local) host the service listens on.
+*/
+var openapi_default = defineMiddleware(async (event, next) => {
+	const runtimeConfig = useRuntimeConfig();
+	const specRoute = runtimeConfig.nitro?.openAPI?.route || "/_openapi.json";
+	const baseURL = (runtimeConfig.app?.baseURL ?? "/").replace(/\/+$/, "");
+	if (event.url.pathname !== `${baseURL}${specRoute}`) return next();
+	const body = await next();
+	if (!isOpenAPIDocument(body)) return body;
+	const excludedPrefixes = runtimeConfig.c8yOpenApiExcludeRoutes ?? [];
+	if (body.paths && excludedPrefixes.length > 0) body.paths = Object.fromEntries(Object.entries(body.paths).filter(([path]) => !excludedPrefixes.some((prefix) => path.startsWith(prefix))));
+	body.servers = [await resolveServer(event)];
+	return body;
+});
+//#endregion
+export { openapi_default as default };

package/dist/runtime/middlewares/c8y-client.mjs

@@ -1,6 +1,6 @@
-import { t as createError } from "../../logging-CVlaRS4O.mjs";
-import { defineMiddleware } from "nitro";
+import { t as createError } from "../../logging-BUYT8Z2V.mjs";
 import process from "node:process";
+import { defineMiddleware } from "nitro";
 //#region src/module/runtime/middlewares/c8y-client.ts
 function isC8yClientThrownResponse(error) {
 	if (!error || typeof error !== "object") return false;

package/dist/runtime/middlewares/dev-user.dev.mjs

@@ -1,6 +1,6 @@
-import { defineHandler } from "nitro/h3";
-import process from "node:process";
 import { Buffer } from "node:buffer";
+import process from "node:process";
+import { defineHandler } from "nitro/h3";
 import consola from "consola";
 //#region src/module/runtime/middlewares/dev-user.dev.ts
 var dev_user_dev_default = defineHandler((event) => {

package/dist/runtime/plugins/c8y-variables.dev.mjs

@@ -1,5 +1,5 @@
-import { definePlugin } from "nitro";
 import process from "node:process";
+import { definePlugin } from "nitro";
 //#region src/module/runtime/plugins/c8y-variables.dev.ts
 var c8y_variables_dev_default = definePlugin(() => {
 	if (import.meta.dev) {

package/dist/types.d.mts

@@ -1,3 +1,3 @@
-import { a as C8YRoles, c as C8YManifest, i as C8YTenantOptionKeysCacheConfig, l as C8YManifestOptions, n as C8yNitroModuleOptions, o as C8yCacheOptions, r as C8YTenantOptionKey, s as C8YZipOptions, t as C8yDevOptions, u as C8YAPIClientOptions } from "./index-uOwpI6rD.mjs";
-import { t as TenantCredentials } from "./credentials-9FO7rTIR.mjs";
-export { C8YAPIClientOptions, C8YManifest, C8YManifestOptions, C8YRoles, C8YTenantOptionKey, C8YTenantOptionKeysCacheConfig, C8YZipOptions, C8yCacheOptions, C8yDevOptions, C8yNitroModuleOptions, TenantCredentials };
+import { a as C8YTenantOptionKey, c as C8yDockerOptions, d as C8YManifest, f as C8YManifestOptions, i as C8YSettingsCategory, l as C8yCacheOptions, n as C8yNitroModuleOptions, o as C8YTenantOptionKeysCacheConfig, p as C8YAPIClientOptions, r as C8yOpenAPIOptions, s as C8YRoles, t as C8yDevOptions, u as C8YZipOptions } from "./index-vu4xaFkz.mjs";
+import { t as TenantCredentials } from "./credentials-eKnJ7m9Y.mjs";
+export { C8YAPIClientOptions, type C8YManifest, type C8YManifestOptions, C8YRoles, C8YSettingsCategory, C8YTenantOptionKey, C8YTenantOptionKeysCacheConfig, type C8YZipOptions, type C8yCacheOptions, C8yDevOptions, type C8yDockerOptions, C8yNitroModuleOptions, C8yOpenAPIOptions, type TenantCredentials };