hanzio 1.1.0 → 1.2.0

package/src/cache/index.ts

@@ -9,6 +9,25 @@ type CachedFunction<T extends AnyFunction> = {
 	clearCache: () => void
 }
 
+export type CacheStoreEntry = {
+	value: unknown
+	timestamp: number
+}
+
+/**
+ * Contract for external cache stores (e.g. a Redis adapter).
+ * Serialization is the adapter's responsibility; this library never imports
+ * the underlying client.
+ */
+export type CacheStore = {
+	get: (key: string) => Promise<CacheStoreEntry | undefined>
+	/** `ttlMs` maps to the store's native expiry (e.g. Redis `PX`). */
+	set: (key: string, entry: CacheStoreEntry, ttlMs: number) => Promise<void>
+	delete: (key: string) => Promise<void>
+	/** Optional; called by clearCache when defined. */
+	clear?: () => Promise<void>
+}
+
 export type CacheFunctionOptions<T extends AnyFunction> = {
 	name: string
 	fn: T
@@ -18,6 +37,13 @@ export type CacheFunctionOptions<T extends AnyFunction> = {
 	cacheKeyFn?: (...args: Parameters<T>) => unknown[]
 	/** Called when a background refresh fails (default: silent). */
 	onBackgroundRefreshError?: (error: unknown, context: { name: string }) => void
+	/**
+	 * External cache store (e.g. a Redis adapter). Only supported for async
+	 * functions; when omitted the built-in in-memory cache is used.
+	 */
+	store?: ReturnType<T> extends Promise<unknown> ? CacheStore : never
+	/** Called when a store get/set/delete/clear fails (default: silent). */
+	onStoreError?: (error: unknown, context: { name: string }) => void
 }
 
 export function cacheFunction<T extends AnyFunction>(
@@ -30,115 +56,256 @@ export function cacheFunction<T extends AnyFunction>(
 		refreshInBackground = false,
 		cacheKeyArgs,
 		cacheKeyFn,
-		onBackgroundRefreshError
+		onBackgroundRefreshError,
+		store,
+		onStoreError
 	} = options
 
+	const externalStore = store as CacheStore | undefined
+
 	const cache = new Map<string, CacheEntry<ReturnType<T>>>()
 	const pendingPromises = new Map<string, Promise<unknown>>()
 
-	const cleanupInterval = setInterval(
-		() => {
-			const now = Date.now()
-			for (const [key, entry] of cache.entries()) {
-				if (now - entry.timestamp >= cacheTimeMs) {
-					cache.delete(key)
+	// Stale entries are kept for an extra TTL so refreshInBackground can serve
+	// them while revalidating.
+	const entryLifetimeMs = refreshInBackground ? cacheTimeMs * 2 : cacheTimeMs
+
+	let cleanupInterval: ReturnType<typeof setInterval> | undefined
+
+	const stopCleanup = () => {
+		if (cleanupInterval !== undefined) {
+			clearInterval(cleanupInterval)
+			cleanupInterval = undefined
+		}
+	}
+
+	// Created lazily on first write and unref'd so it never keeps the process
+	// alive. Stops itself once the cache is empty and restarts on the next
+	// write, so clearCache does not permanently disable sweeping.
+	const ensureCleanup = () => {
+		if (cleanupInterval !== undefined) {
+			return
+		}
+		cleanupInterval = setInterval(
+			() => {
+				const now = Date.now()
+				for (const [key, entry] of cache.entries()) {
+					if (now - entry.timestamp >= entryLifetimeMs) {
+						cache.delete(key)
+					}
 				}
-			}
-		},
-		Math.min(cacheTimeMs / 2, 5 * 60 * 1000)
-	)
+				if (cache.size === 0) {
+					stopCleanup()
+				}
+			},
+			Math.min(cacheTimeMs / 2, 5 * 60 * 1000)
+		)
+		cleanupInterval.unref?.()
+	}
 
-	const wrappedFn = (...args: Parameters<T>): ReturnType<T> => {
+	const buildKey = (args: Parameters<T>): string => {
 		const keyArgs = cacheKeyFn
 			? cacheKeyFn(...args)
 			: cacheKeyArgs
 				? cacheKeyArgs.map((i) => args[i])
 				: args
-		const key = `${name}:${JSON.stringify(keyArgs)}`
-		const now = Date.now()
+		return `${name}:${JSON.stringify(keyArgs)}`
+	}
+
+	const saveEntry = (key: string, value: ReturnType<T>) => {
+		cache.set(key, { value, timestamp: Date.now() })
+		ensureCleanup()
+	}
+
+	const fetchAndPopulate = (
+		key: string,
+		args: Parameters<T>
+	): ReturnType<T> => {
+		const result = fn(...args)
+
+		if (!isPromiseLike(result)) {
+			saveEntry(key, result as ReturnType<T>)
+			return result as ReturnType<T>
+		}
+
+		const promise = (result as Promise<ReturnType<T>>)
+			.then((value) => {
+				saveEntry(key, value)
+				pendingPromises.delete(key)
+				return value
+			})
+			.catch((error: unknown) => {
+				pendingPromises.delete(key)
+				throw error
+			})
+
+		pendingPromises.set(key, promise)
+		return promise as ReturnType<T>
+	}
+
+	const startBackgroundRefresh = (
+		key: string,
+		args: Parameters<T>,
+		staleValue: ReturnType<T>
+	) => {
+		const result = fn(...args)
+
+		if (!isPromiseLike(result)) {
+			saveEntry(key, result as ReturnType<T>)
+			return
+		}
+
+		const promise = (result as Promise<ReturnType<T>>)
+			.then((value) => {
+				saveEntry(key, value)
+				pendingPromises.delete(key)
+				return value
+			})
+			.catch((error: unknown) => {
+				pendingPromises.delete(key)
+				onBackgroundRefreshError?.(error, { name })
+				// Anyone awaiting this promise gets the stale value instead of
+				// undefined or a rejection.
+				return staleValue
+			})
+
+		pendingPromises.set(key, promise)
+	}
+
+	const saveToStore = async (
+		cacheStore: CacheStore,
+		key: string,
+		value: unknown
+	) => {
+		try {
+			await cacheStore.set(
+				key,
+				{ value, timestamp: Date.now() },
+				entryLifetimeMs
+			)
+		} catch (error) {
+			onStoreError?.(error, { name })
+		}
+	}
+
+	const callWithStore = (
+		cacheStore: CacheStore,
+		args: Parameters<T>
+	): Promise<unknown> => {
+		const key = buildKey(args)
 
 		const pending = pendingPromises.get(key)
-		if (pending) {
-			return pending as ReturnType<T>
+		// Background refresh callers can still use an entry from the store.
+		if (pending && !refreshInBackground) {
+			return pending
 		}
 
-		const cached = cache.get(key)
+		return (async () => {
+			let entry: CacheStoreEntry | undefined
+			try {
+				entry = await cacheStore.get(key)
+			} catch (error) {
+				onStoreError?.(error, { name })
+			}
 
-		if (cached) {
-			const isCacheFresh = now - cached.timestamp < cacheTimeMs
+			if (entry) {
+				const isFresh = Date.now() - entry.timestamp < cacheTimeMs
 
-			if (!isCacheFresh && !refreshInBackground) {
-				cache.delete(key)
-			} else {
-				if (isCacheFresh && !refreshInBackground) {
-					return cached.value
+				if (isFresh) {
+					return entry.value
 				}
 
 				if (refreshInBackground) {
-					const existingPending = pendingPromises.get(key)
-					if (existingPending) {
-						return existingPending as ReturnType<T>
-					}
-
-					const backgroundUpdate = fn(...args)
-
-					if (isPromiseLike(backgroundUpdate)) {
-						const backgroundPromise = (
-							backgroundUpdate as Promise<ReturnType<T>>
-						)
-							.then((resolvedValue) => {
-								cache.set(key, { value: resolvedValue, timestamp: now })
+					if (!pendingPromises.has(key)) {
+						const staleValue = entry.value
+						const refresh = (fn(...args) as Promise<unknown>)
+							.then(async (value) => {
+								await saveToStore(cacheStore, key, value)
 								pendingPromises.delete(key)
-								return resolvedValue
+								return value
 							})
 							.catch((error: unknown) => {
 								pendingPromises.delete(key)
 								onBackgroundRefreshError?.(error, { name })
+								return staleValue
 							})
-
-						pendingPromises.set(key, backgroundPromise)
-					} else {
-						cache.set(key, {
-							value: backgroundUpdate as ReturnType<T>,
-							timestamp: now
-						})
+						pendingPromises.set(key, refresh)
 					}
-
-					return cached.value
+					return entry.value
 				}
 
-				if (isCacheFresh) {
-					return cached.value
+				try {
+					await cacheStore.delete(key)
+				} catch (error) {
+					onStoreError?.(error, { name })
 				}
 			}
-		}
 
-		const result = fn(...args)
+			// A concurrent caller may have started a fetch while we awaited the
+			// store lookup.
+			const existing = pendingPromises.get(key)
+			if (existing) {
+				return existing
+			}
 
-		if (isPromiseLike(result)) {
-			const promise = (result as Promise<ReturnType<T>>)
-				.then((resolvedValue) => {
-					cache.set(key, { value: resolvedValue, timestamp: now })
+			const promise = (fn(...args) as Promise<unknown>)
+				.then(async (value) => {
+					await saveToStore(cacheStore, key, value)
 					pendingPromises.delete(key)
-					return resolvedValue
+					return value
 				})
-				.catch((error) => {
+				.catch((error: unknown) => {
 					pendingPromises.delete(key)
 					throw error
 				})
 
 			pendingPromises.set(key, promise)
-			return promise as ReturnType<T>
+			return promise
+		})()
+	}
+
+	const wrappedFn = (...args: Parameters<T>): ReturnType<T> => {
+		if (externalStore) {
+			return callWithStore(externalStore, args) as ReturnType<T>
+		}
+
+		const key = buildKey(args)
+		const cached = cache.get(key)
+
+		if (cached) {
+			const isFresh = Date.now() - cached.timestamp < cacheTimeMs
+
+			if (isFresh) {
+				return cached.value
+			}
+
+			if (refreshInBackground) {
+				if (!pendingPromises.has(key)) {
+					startBackgroundRefresh(key, args, cached.value)
+				}
+				return cached.value
+			}
+
+			cache.delete(key)
 		}
 
-		cache.set(key, { value: result as ReturnType<T>, timestamp: now })
-		return result as ReturnType<T>
+		const pending = pendingPromises.get(key)
+		if (pending) {
+			return pending as ReturnType<T>
+		}
+
+		return fetchAndPopulate(key, args)
 	}
 
 	wrappedFn.clearCache = () => {
 		cache.clear()
 		pendingPromises.clear()
-		clearInterval(cleanupInterval)
+		stopCleanup()
+		if (externalStore?.clear) {
+			externalStore.clear().catch((error: unknown) => {
+				onStoreError?.(error, { name })
+			})
+		}
 	}
 
 	return wrappedFn

package/src/secrets/core.ts

@@ -0,0 +1,348 @@
+import { withSecretDeadline, type SecretRequestOptions } from './deadline'
+import {
+	resolveSecretEnvironment,
+	type EnvironmentVariables,
+	type SecretEnvironmentOption
+} from './environment'
+import { SecretLoadError } from './errors'
+
+export type { SecretEnvironment, SecretEnvironmentOption } from './environment'
+export { SecretLoadError } from './errors'
+
+export type SecretLogAttributes = {
+	readonly environment: string
+	readonly count: number
+	readonly durationMs: number
+	readonly source?: string
+	readonly sources?: Readonly<Record<string, number>>
+	readonly code?: string
+}
+
+export type SecretLogger = {
+	info: (message: string, attributes: SecretLogAttributes) => void
+	error: (message: string, attributes: SecretLogAttributes) => void
+}
+
+export type SecretSchema<K extends string, Parsed> = {
+	parseAsync: (values: Record<K, string>) => Promise<Parsed>
+}
+
+export type CommonSecretSetOptions<
+	K extends string,
+	Parsed = Record<K, string>
+> = SecretRequestOptions & {
+	readonly environment?: SecretEnvironmentOption
+	readonly writeToProcessEnv?: boolean
+	readonly logger?: SecretLogger | false
+	readonly schema?: SecretSchema<K, Parsed>
+}
+
+export type CustomLoaderDefineSecretSetOptions<
+	K extends string,
+	Parsed = Record<K, string>
+> = CommonSecretSetOptions<K, Parsed> & {
+	readonly loader: SecretSetLoader<K>
+}
+
+export type SecretSetLoaderContext<K extends string> = {
+	readonly keys: readonly K[]
+	readonly environment: string
+	readonly signal?: AbortSignal
+	readonly timeoutMs?: number
+
+	/** Report the source actually selected by a dynamic loader. */
+	readonly reportSource?: (source: string) => void
+}
+
+export type SecretSetLoader<K extends string> = ((
+	context: SecretSetLoaderContext<K>
+) => Promise<Partial<Record<K, string>>>) & {
+	readonly source?: string
+}
+
+export type SecretSet<K extends string, Parsed = Record<K, string>> = {
+	secret: (key: K) => string
+	secrets: () => Record<K, string>
+	parsed: () => Parsed
+	sources: () => Record<K, string>
+	reload: (options?: SecretRequestOptions) => Promise<SecretSet<K, Parsed>>
+}
+
+// Shared across bundled entry points and package copies in the same JS realm.
+// Only helper-written values are registered; original environment overrides aren't.
+const registryKey = Symbol.for('hanzio.secrets.environmentWrites.v1')
+const shared = globalThis as typeof globalThis & {
+	[registryKey]?: WeakMap<EnvironmentVariables, Map<string, string>>
+}
+const environmentWrites =
+	shared[registryKey] ??
+	new WeakMap<EnvironmentVariables, Map<string, string>>()
+
+shared[registryKey] = environmentWrites
+
+const defaultLogger: SecretLogger = {
+	info: (message, attrs) =>
+		console.log(
+			`${message} environment=${attrs.environment} count=${attrs.count} source=${attrs.source} durationMs=${attrs.durationMs}`,
+			{ sources: attrs.sources }
+		),
+	error: (message, attrs) => console.error(message, attrs)
+}
+
+function readOverrides<K extends string>(
+	keys: readonly K[],
+	env?: EnvironmentVariables
+): Partial<Record<K, string>> {
+	if (!env) {
+		return {}
+	}
+
+	const writes = environmentWrites.get(env)
+
+	return Object.fromEntries(
+		keys.flatMap((key) => {
+			const value = Object.hasOwn(env, key) ? env[key] : undefined
+
+			// A matching helper write is a mirror, not an explicit user override.
+			if (writes?.has(key)) {
+				if (writes.get(key) === value) {
+					return []
+				}
+
+				// An external change gives ownership back to the environment.
+				writes.delete(key)
+			}
+
+			return value ? [[key, value]] : []
+		})
+	) as Partial<Record<K, string>>
+}
+
+export async function defineSecretSet<
+	const Keys extends readonly string[],
+	Parsed = Record<Keys[number], string>
+>(
+	keys: Keys,
+	options: CustomLoaderDefineSecretSetOptions<Keys[number], Parsed>,
+	environmentVariables?: EnvironmentVariables
+): Promise<SecretSet<Keys[number], Parsed>> {
+	type K = Keys[number]
+
+	const keySet = [...new Set(keys)] as K[]
+	const environment = resolveSecretEnvironment(
+		options.environment,
+		environmentVariables
+	)
+	const logger =
+		options.logger === false ? undefined : (options.logger ?? defaultLogger)
+
+	// These snapshots change together only after an entire load succeeds.
+	let cached: Record<K, string>
+	let parsed: Parsed
+	let sources: Record<K, string>
+	let inFlight: Promise<void> | undefined
+
+	const log = (
+		level: 'info' | 'error',
+		message: string,
+		attributes: SecretLogAttributes
+	) => {
+		try {
+			logger?.[level](message, attributes)
+		} catch {
+			/* Logging cannot change a load result. */
+		}
+	}
+
+	// Build, validate, and commit one snapshot under the caller’s deadline.
+	const loadSnapshot = async (
+		request: SecretRequestOptions,
+		signal: AbortSignal
+	) => {
+		// Fetch only keys that lack genuine local overrides.
+		const local = readOverrides(keySet, environmentVariables)
+		const missing = keySet.filter((key) => !Object.hasOwn(local, key))
+		let loaderSource = options.loader.source ?? 'custom loader'
+		let loaded: Partial<Record<K, string>> = {}
+
+		if (missing.length) {
+			try {
+				loaded = await options.loader({
+					keys: missing,
+					environment,
+					signal,
+					timeoutMs: request.timeoutMs ?? options.timeoutMs ?? 30_000,
+					reportSource: (source) => {
+						loaderSource = source
+					}
+				})
+			} catch (error) {
+				if (error instanceof SecretLoadError) {
+					throw error
+				}
+
+				throw new SecretLoadError('LOADER', 'Secret loader failed.')
+			}
+		}
+
+		// Honor overrides changed while the loader was running.
+		const overrides = readOverrides(keySet, environmentVariables)
+		const next = Object.fromEntries(
+			keySet.map((key) => {
+				if (Object.hasOwn(overrides, key)) {
+					return [key, overrides[key]]
+				}
+
+				if (Object.hasOwn(loaded, key)) {
+					return [key, loaded[key]]
+				}
+
+				return [key, undefined]
+			})
+		) as Record<K, string>
+		const missingKeys = keySet.filter(
+			(key) => typeof next[key] !== 'string' || !next[key]
+		)
+
+		if (missingKeys.length) {
+			throw new SecretLoadError(
+				'MISSING_SECRETS',
+				`Missing secrets: ${missingKeys.join(', ')}`
+			)
+		}
+
+		// Validate the merged snapshot before touching the cache or environment.
+		let nextParsed: Parsed
+
+		try {
+			nextParsed = options.schema
+				? await options.schema.parseAsync({ ...next })
+				: ({ ...next } as Parsed)
+
+			// Validate copyability before committing anything.
+			nextParsed = structuredClone(nextParsed)
+		} catch {
+			throw new SecretLoadError(
+				'VALIDATION',
+				'Secret schema validation failed. Check the configured schema; values are omitted.'
+			)
+		}
+
+		// A custom loader or schema may ignore cancellation while awaiting.
+		// Its late result must never replace the last successful snapshot.
+		signal.throwIfAborted()
+
+		const nextSources = Object.fromEntries(
+			keySet.map((key) => [
+				key,
+				Object.hasOwn(overrides, key) ? 'process.env' : loaderSource
+			])
+		) as Record<K, string>
+
+		// Register only fetched values so future loads can identify our mirrors.
+		if (options.writeToProcessEnv !== false && environmentVariables) {
+			let writes = environmentWrites.get(environmentVariables)
+
+			if (!writes) {
+				writes = new Map()
+				environmentWrites.set(environmentVariables, writes)
+			}
+
+			for (const key of keySet) {
+				if (Object.hasOwn(overrides, key)) {
+					continue
+				}
+
+				environmentVariables[key] = next[key]
+				writes.set(key, next[key])
+			}
+		}
+
+		cached = next
+		parsed = nextParsed
+		sources = nextSources
+	}
+
+	const load = (request: SecretRequestOptions = {}): Promise<void> => {
+		// Concurrent reloads share the first caller's deadline and cancellation.
+		if (inFlight) {
+			return inFlight
+		}
+
+		inFlight = (async () => {
+			const start = Date.now()
+
+			try {
+				await withSecretDeadline(
+					{
+						timeoutMs: request.timeoutMs ?? options.timeoutMs,
+						signal: request.signal ?? options.signal
+					},
+					(signal) => loadSnapshot(request, signal)
+				)
+
+				// Report the sources of committed values, not attempted fetches.
+				const sourceCounts = new Map<string, number>()
+
+				for (const key of keySet) {
+					const source = sources[key]
+
+					sourceCounts.set(source, (sourceCounts.get(source) ?? 0) + 1)
+				}
+
+				const counts = Object.fromEntries(sourceCounts)
+
+				log('info', 'Loaded secrets', {
+					environment,
+					count: keySet.length,
+					durationMs: Date.now() - start,
+					source: Object.keys(counts).join(' + ') || 'none',
+					sources: counts
+				})
+			} catch (error) {
+				const safe =
+					error instanceof SecretLoadError
+						? error
+						: new SecretLoadError('LOADER', 'Secret loading failed.')
+
+				log('error', 'Secret loading failed', {
+					environment,
+					count: keySet.length,
+					durationMs: Date.now() - start,
+					code: safe.code
+				})
+
+				throw safe
+			}
+		})().finally(() => {
+			inFlight = undefined
+		})
+
+		return inFlight
+	}
+
+	const secretSet: SecretSet<K, Parsed> = {
+		secret(key) {
+			if (!Object.hasOwn(cached, key)) {
+				throw new SecretLoadError('MISSING_SECRETS', `Secret ${key} not found`)
+			}
+
+			return cached[key]
+		},
+
+		// Return copies so consumers cannot mutate the internal snapshots.
+		secrets: () => ({ ...cached }),
+		parsed: () => structuredClone(parsed),
+		sources: () => ({ ...sources }),
+
+		async reload(request) {
+			await load(request)
+
+			return secretSet
+		}
+	}
+
+	await load()
+
+	return secretSet
+}