@harperfast/harper 5.0.30 → 5.1.0-beta.2

package/resources/analytics/metadata.ts

@@ -6,6 +6,7 @@ export const METRIC = {
 	RESOURCE_USAGE: 'resource-usage',
 	UTILIZATION: 'utilization',
 	NODE_STORAGE: 'node-storage',
+	ROCKSDB_STATS: 'rocksdb-stats',
 } as const;
 
 export type BuiltInMetricName = (typeof METRIC)[keyof typeof METRIC];

package/resources/analytics/read.ts

@@ -1,16 +1,20 @@
 import type { Metric } from './write.ts';
-import harperLogger from '../../utility/logging/harper_logger.js';
+import harperLogger from '../../utility/logging/harper_logger.ts';
 const { forComponent } = harperLogger;
 import { getAnalyticsHostnameTable, stableNodeId } from './hostnames.ts';
 import type { Condition, Conditions } from '../ResourceInterface.ts';
 import { METRIC, type BuiltInMetricName } from './metadata.ts';
 import { CONFIG_PARAMS } from '../../utility/hdbTerms.ts';
-import { get as envGet } from '../../utility/environment/environmentManager.js';
+import { get as envGet } from '../../utility/environment/environmentManager.ts';
+import { validateGetAnalytics } from '../../validation/analyticsValidator.ts';
+import { handleHDBError, hdbErrors } from '../../utility/errors/hdbError.ts';
+import { getThisNodeName } from '../../server/nodeName.ts';
 
 // default to one week time window for finding custom metrics
 const defaultCustomMetricWindow = 1000 * 60 * 60 * 24 * 7;
 
-const log = forComponent('analytics').conditional;
+const logger = forComponent('analytics');
+const log = logger.conditional;
 
 async function lookupHostname(nodeId: number): Promise<string | undefined> {
 	const result = await getAnalyticsHostnameTable().get(nodeId);
@@ -24,25 +28,110 @@ function isSelected(querySelect: string[], attr: string) {
 }
 
 interface GetAnalyticsRequest {
+	operation?: string;
 	metric: string;
 	start_time?: number;
 	end_time?: number;
 	get_attributes?: string[];
 	coalesce_time?: boolean;
 	conditions?: Conditions;
+	// When true, fan the query out to every peer node and merge the results into one
+	// cluster-wide response. Cleared before forwarding so peers only return their own.
+	replicated?: boolean;
 }
 
-type GetAnalyticsResponse = Metric[];
+type GetAnalyticsResponse = AsyncIterable<Metric> | Metric[];
 
-export function getOp(req: GetAnalyticsRequest): Promise<GetAnalyticsResponse> {
+/**
+ * Validates the `get_analytics` request and returns the analytics results.
+ * @param req
+ * @returns
+ */
+export async function getOp(req: GetAnalyticsRequest): Promise<GetAnalyticsResponse> {
 	log.trace?.('get_analytics request:', req);
-	return get(req.metric, {
-		getAttributes: req.get_attributes,
+	const validationError = validateGetAnalytics(req);
+	if (validationError) {
+		throw handleHDBError(
+			validationError,
+			validationError.message,
+			hdbErrors.HTTP_STATUS_CODES.BAD_REQUEST,
+			undefined,
+			undefined,
+			true
+		);
+	}
+	// `replicated` fans the query out to every peer node and merges each node's
+	// analytics into one cluster-wide result set. Fan-out is skipped when:
+	//  - the request did not ask for it;
+	//  - this is standalone core, which has no `server.nodes` (harper-pro populates it);
+	//  - `hdb_analytics` already replicates across the cluster, in which case a local
+	//    query already holds every node's rows and fanning out would double-count.
+	//    The DB layer marks the table `replicate === false` only when it is *not*
+	//    replicated (`analytics_replicate: false`), which is exactly when fan-out helps.
+	const analyticsReplicatedByDb = databases.system.hdb_analytics.replicate !== false;
+	const peers = req.replicated && !analyticsReplicatedByDb && server.nodes?.length ? server.nodes : undefined;
+
+	// When merging across the cluster, make sure every row keeps its origin `node`
+	// attribute so callers can tell the nodes apart. An empty/absent `get_attributes`
+	// already selects everything (including `node`), so only an explicit list needs it.
+	let getAttributes = req.get_attributes;
+	if (peers && getAttributes?.length && !getAttributes.includes('node')) {
+		getAttributes = [...getAttributes, 'node'];
+	}
+
+	const localResults = await get(req.metric, {
+		getAttributes,
 		startTime: req.start_time,
 		endTime: req.end_time,
 		coalesceTime: req.coalesce_time,
 		additionalConditions: req.conditions,
 	});
+
+	if (!peers) return localResults;
+	return mergeAnalyticsFromPeers(localResults, { ...req, get_attributes: getAttributes }, peers);
+}
+
+/**
+ * Streams the local analytics, then appends each peer node's analytics. The same
+ * query is forwarded to every peer with `replicated` cleared so each returns only
+ * its own local metrics (no recursive fan-out). Best-effort: a peer that fails is
+ * logged and omitted rather than failing the whole query.
+ */
+async function* mergeAnalyticsFromPeers(
+	localResults: AsyncIterable<Metric> | Iterable<Metric>,
+	req: GetAnalyticsRequest,
+	peers: { name: string }[]
+): AsyncGenerator<Metric> {
+	const thisNode = getThisNodeName();
+	const peerReq = { ...req, replicated: false };
+	// `sendOperationToNode` is typed for a node name string, but the replication
+	// implementation expects the full node object (the stub-vs-impl mismatch that
+	// `restart` works around the same way).
+	const sendOperationToNode = server.replication.sendOperationToNode as unknown as (
+		node: { name: string },
+		operation: unknown
+	) => Promise<{ results?: Metric[] } | Metric[]>;
+
+	const peerResults = peers
+		.filter((node) => node.name !== thisNode)
+		.map((node) =>
+			sendOperationToNode(node, peerReq).then(
+				// an array response is wrapped as `{ results }` over the replication channel;
+				// fall back to an empty list for any other (malformed) shape so a bad peer
+				// can't break the merge
+				(response): Metric[] =>
+					Array.isArray(response) ? response : Array.isArray(response?.results) ? response.results : [],
+				(error: Error): Metric[] => {
+					logger.warn(`get_analytics replication to node '${node.name}' failed; omitting its results`, error);
+					return [];
+				}
+			)
+		);
+
+	yield* localResults;
+	for (const peerResult of peerResults) {
+		yield* await peerResult;
+	}
 }
 
 function conformCondition(condition: Condition): Condition {
@@ -120,7 +209,7 @@ export async function get(metric: string, opts?: GetAnalyticsOpts): Promise<Metr
 		}
 	}
 
-	const request = { conditions, allowConditionsOnDynamicAttributes: true };
+	const request: any = { conditions, allowConditionsOnDynamicAttributes: true };
 	if (select.length > 0) {
 		request['select'] = select;
 	}
@@ -192,7 +281,7 @@ export async function listMetrics(
 			} as Condition;
 		});
 		conditions.push(...metricConditions);
-		const customMetricsSearch = {
+		const customMetricsSearch: any = {
 			select: ['metric'],
 			conditions: conditions,
 		};
@@ -226,7 +315,7 @@ export function describeMetricOp(req: DescribeMetricRequest): Promise<DescribeMe
 }
 
 export async function describeMetric(metric: string): Promise<DescribeMetricResponse> {
-	const lastEntrySearch = {
+	const lastEntrySearch: any = {
 		conditions: [{ attribute: 'metric', comparator: 'equals', value: metric }],
 		sort: {
 			attribute: 'id',

package/resources/analytics/write.ts

@@ -1,14 +1,14 @@
 import { parentPort, threadId } from 'worker_threads';
 import { onMessageByType } from '../../server/threads/manageThreads.js';
-import { getDatabases, table } from '../databases.ts';
+import { getDatabases, table, isReadOnlyMode } from '../databases.ts';
 import type { Databases, Table, Tables } from '../databases.ts';
-import harperLogger from '../../utility/logging/harper_logger.js';
+import harperLogger from '../../utility/logging/harper_logger.ts';
 import { stat, readdir } from 'node:fs/promises';
 const { getLogFilePath, forComponent } = harperLogger;
 import { dirname, join } from 'path';
 import { open } from 'fs/promises';
-import { getNextMonotonicTime } from '../../utility/lmdb/commonUtility.js';
-import { get as envGet, getHdbBasePath, initSync } from '../../utility/environment/environmentManager.js';
+import { getNextMonotonicTime } from '../../utility/lmdb/commonUtility.ts';
+import { get as envGet, getHdbBasePath, initSync } from '../../utility/environment/environmentManager.ts';
 import { CONFIG_PARAMS } from '../../utility/hdbTerms.ts';
 import { server } from '../../server/Server.ts';
 import * as fs from 'node:fs';
@@ -17,6 +17,7 @@ import { METRIC } from './metadata.ts';
 import { RocksDatabase } from '@harperfast/rocksdb-js';
 
 const log = forComponent('analytics').conditional;
+const isBun = typeof globalThis.Bun !== 'undefined';
 
 initSync();
 
@@ -37,8 +38,20 @@ interface Action {
 
 let activeActions = new Map<string, Action>();
 let analyticsEnabled = envGet(CONFIG_PARAMS.ANALYTICS_AGGREGATEPERIOD) > -1;
+let analyticsReadOnlyChecked = false;
 let sendAnalyticsTimeout: NodeJS.Timeout;
 
+// Check read-only mode lazily to avoid circular dependency at module load time
+function checkAnalyticsEnabled(): boolean {
+	if (!analyticsReadOnlyChecked) {
+		analyticsReadOnlyChecked = true;
+		if (isReadOnlyMode()) {
+			analyticsEnabled = false;
+		}
+	}
+	return analyticsEnabled;
+}
+
 export function setAnalyticsEnabled(enabled: boolean) {
 	analyticsEnabled = enabled;
 	clearTimeout(sendAnalyticsTimeout); // reset this
@@ -47,7 +60,7 @@ export function setAnalyticsEnabled(enabled: boolean) {
 
 function recordExistingAction(value: Value, action: Action) {
 	if (typeof value === 'number') {
-		let values: Float32Array = action.values;
+		let values: any = action.values;
 		const index = values.index++;
 		if (index >= values.length) {
 			const oldValues = values;
@@ -71,7 +84,7 @@ function recordNewAction(key: string, value: Value, metric?: string, path?: stri
 	if (typeof value === 'number') {
 		action.total = value;
 		action.values = new Float32Array(4);
-		action.values.index = 1;
+		(action.values as any).index = 1;
 		action.values[0] = value;
 		action.total = value;
 	} else if (typeof value === 'boolean') {
@@ -101,7 +114,7 @@ function recordNewAction(key: string, value: Value, metric?: string, path?: stri
  * @param type
  */
 export function recordAction(value: Value, metric: string, path?: string, method?: string, type?: string) {
-	if (!analyticsEnabled) return;
+	if (!checkAnalyticsEnabled()) return;
 	// TODO: May want to consider nested paths, as they may yield faster hashing of (fixed) strings that hashing concatenated strings
 	let key = metric + (path ? '-' + path : '');
 	if (method !== undefined) key += '-' + method;
@@ -151,7 +164,7 @@ function sendAnalytics() {
 		};
 		for (const [_name, action] of activeActions) {
 			if (action.values) {
-				const values = action.values.subarray(0, action.values.index);
+				const values = action.values.subarray(0, (action.values as any).index);
 				values.sort();
 				const count = values.length;
 				// compute the stats
@@ -214,6 +227,8 @@ function sendAnalytics() {
 }
 
 export async function recordHostname() {
+	// Skip writes in read-only mode
+	if (isReadOnlyMode()) return;
 	const hostname = server.hostname;
 	log.trace?.('recordHostname server.hostname:', hostname);
 	const nodeId = stableNodeId(hostname);
@@ -224,7 +239,7 @@ export async function recordHostname() {
 		hostname,
 	};
 	log.trace?.(`recordHostname storing hostname: ${JSON.stringify(hostnameRecord)}`);
-	await hostnamesTable.put(hostnameRecord.id, hostnameRecord);
+	await (hostnamesTable as any).put(hostnameRecord.id, hostnameRecord);
 }
 
 export interface Metric {
@@ -244,6 +259,8 @@ function getHostNodeId(hostname: string) {
 }
 
 function storeMetric(table: Table, metric: Metric) {
+	// Skip writes in read-only mode
+	if (isReadOnlyMode()) return;
 	const nodeId = getHostNodeId(server.hostname);
 	const metricValue = {
 		id: [getNextMonotonicTime(), nodeId],
@@ -379,6 +396,194 @@ function storeVolumeMetrics(analyticsTable: Table, databases: Databases) {
 	}
 }
 
+// RocksDB stat names are kebab-case with a "rocksdb." prefix (e.g. "rocksdb.block.cache.hit");
+// camelCase them to match the field shape used throughout systemInformation.
+export function toRocksDBCamelCase(key: string): string {
+	return key.replace(/^rocksdb\./, '').replace(/[-.]([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+// Every column family on the same physical RocksDB shares one Statistics object, so all ticker
+// counters returned by getStats() — including memtableHit/memtableMiss — are DB-wide, not per-CF.
+// Listing them as DB-level avoids emitting the same delta on every table row.
+const ROCKSDB_DB_COUNTERS = [
+	'bytesRead',
+	'bytesWritten',
+	'numberKeysRead',
+	'numberKeysWritten',
+	'blockCacheHit',
+	'blockCacheMiss',
+	'blockCacheDataHit',
+	'blockCacheDataMiss',
+	'blockCacheIndexHit',
+	'blockCacheIndexMiss',
+	'blockCacheFilterHit',
+	'blockCacheFilterMiss',
+	'stallMicros',
+	'memtableHit',
+	'memtableMiss',
+] as const;
+// Gauges are scalar values that are not cumulative. They go up and down over time.
+const ROCKSDB_DB_GAUGES = ['blockCacheUsage', 'blockCacheCapacity', 'numRunningFlushes'] as const;
+const ROCKSDB_TABLE_GAUGES = ['numRunningCompactions', 'compactionPending'] as const;
+
+const lastRocksDBDbStats = new Map<string, Record<string, number>>();
+let lastRocksDBStatsTime = 0;
+
+export function diffRocksDBCounter(curr: number, last: number | undefined): number {
+	// A negative delta means RocksDB itself reset the counter mid-process (e.g. an internal
+	// statistics reset). Process restarts are handled separately because the module-level
+	// last-stats maps are reinitialized, which takes the no-prior-reading path below.
+	if (last === undefined || curr < last) return curr;
+	return curr - last;
+}
+
+/**
+ * Filter a raw RocksDB stats record to numeric scalar entries, camelCasing the keys.
+ * Histogram entries (objects) are dropped — they don't fit the flat analytics row model.
+ * @param raw - The raw RocksDB stats record to normalize.
+ * @returns The normalized RocksDB stats record.
+ */
+export function normalizeRocksDBStats(raw: Record<string, unknown>): Record<string, number> {
+	const out: Record<string, number> = {};
+	if (!raw) return out;
+	for (const [key, value] of Object.entries(raw)) {
+		if (typeof value === 'number') out[toRocksDBCamelCase(key)] = value;
+	}
+	return out;
+}
+
+/**
+ * Gathers metrics for a RocksDB database.
+ * @param dbName - The name of the database.
+ * @param stats - The stats to build the metric from.
+ * @param lastStats - The last stats to diff the stats from.
+ * @param now - The current time.
+ * @param period - The period to store the metrics for.
+ */
+export function buildRocksDBDbMetric(
+	dbName: string,
+	stats: Record<string, number>,
+	lastStats: Record<string, number> | undefined,
+	now: number,
+	period: number | undefined
+): Record<string, unknown> {
+	const metric: Record<string, unknown> = {
+		metric: METRIC.ROCKSDB_STATS,
+		database: dbName,
+		time: now,
+	};
+	if (period !== undefined) metric.period = period;
+	for (const field of ROCKSDB_DB_COUNTERS) {
+		metric[field] = diffRocksDBCounter(stats[field] ?? 0, lastStats?.[field]);
+	}
+	for (const field of ROCKSDB_DB_GAUGES) {
+		metric[field] = stats[field] ?? 0;
+	}
+	return metric;
+}
+
+/**
+ * Gathers metrics for a RocksDB table. Only gauges are reported per-table; ticker counters
+ * are DB-wide (see ROCKSDB_DB_COUNTERS comment) and live on the DB-level metric.
+ * @param dbName - The name of the database.
+ * @param tableName - The name of the table.
+ * @param stats - The stats to build the metric from.
+ * @param now - The current time.
+ * @param period - The period to store the metrics for.
+ */
+export function buildRocksDBTableMetric(
+	dbName: string,
+	tableName: string,
+	stats: Record<string, number>,
+	now: number,
+	period: number | undefined
+): Record<string, unknown> {
+	const metric: Record<string, unknown> = {
+		metric: METRIC.ROCKSDB_STATS,
+		database: dbName,
+		table: tableName,
+		time: now,
+	};
+	if (period !== undefined) metric.period = period;
+	for (const field of ROCKSDB_TABLE_GAUGES) {
+		metric[field] = stats[field] ?? 0;
+	}
+	return metric;
+}
+
+/**
+ * Stores the RocksDB stats metrics for the given databases.
+ * @param analyticsTable - The analytics table to store the metrics in.
+ * @param databases - The databases to store the metrics for.
+ * @param now - The current time.
+ * @param period - The period to store the metrics for.
+ */
+function storeRocksDBStatsMetrics(
+	analyticsTable: Table,
+	databases: Databases,
+	now: number,
+	period: number | undefined
+) {
+	for (const [db, tables] of Object.entries(databases)) {
+		if (!tables) continue; // no tables or not loaded/initialized yet
+		const tableEntries = Object.entries(tables);
+		const [, firstTable] = tableEntries[0] ?? [];
+		if (!(firstTable?.primaryStore instanceof RocksDatabase)) continue;
+
+		let firstNormalizedStats: Record<string, number> | undefined;
+		for (const [tableName, tbl] of tableEntries) {
+			try {
+				const tableStats = normalizeRocksDBStats(tbl.primaryStore.getStats());
+				if (!firstNormalizedStats) firstNormalizedStats = tableStats;
+				const tableMetric = buildRocksDBTableMetric(db, tableName, tableStats, now, period);
+				storeMetric(analyticsTable, tableMetric);
+			} catch (error) {
+				// A table may be removed mid-collection — keep iterating siblings.
+				log.warn?.(`Error getting RocksDB stats for table ${db}.${tableName}`, error);
+			}
+		}
+
+		if (firstNormalizedStats) {
+			// Any table's getStats() returns the same DB-wide counters; reuse the first one's.
+			const lastDbStats = lastRocksDBDbStats.get(db);
+			// Skip the first sample for a db — counters are cumulative since process start,
+			// so reporting them as a delta would produce a misleading spike.
+			if (lastDbStats !== undefined) {
+				const dbMetric = buildRocksDBDbMetric(db, firstNormalizedStats, lastDbStats, now, period);
+				storeMetric(analyticsTable, dbMetric);
+				log.trace?.(`db ${db} rocksdb stats metric: ${JSON.stringify(dbMetric)}`);
+			}
+			lastRocksDBDbStats.set(db, firstNormalizedStats);
+		}
+	}
+}
+
+/**
+ * Drop cached counter readings for databases that no longer exist, to bound memory
+ * growth across drop/recreate cycles and prevent stale baselines from producing wrong diffs.
+ * @param databases - The databases to prune the stats cache for.
+ */
+function pruneRocksDBStatsCache(databases: Databases) {
+	const activeDbs = new Set<string>(Object.keys(databases));
+	for (const key of lastRocksDBDbStats.keys()) {
+		if (!activeDbs.has(key)) lastRocksDBDbStats.delete(key);
+	}
+}
+
+/**
+ * Returns a Databases view that includes the `system` database as an enumerable property.
+ * getDatabases() marks `system` non-enumerable so general consumers skip it; analytics
+ * needs to iterate over it like any other database.
+ */
+function getDatabasesIncludingSystem(): Databases {
+	const databases = getDatabases();
+	if (!databases.system) return databases;
+	const all: Databases = Object.create(null);
+	Object.assign(all, databases);
+	all.system = databases.system;
+	return all;
+}
+
 export async function getDirectorySizeAsync(dirPath: string): Promise<number> {
 	try {
 		const entries = await readdir(dirPath, { withFileTypes: true });
@@ -425,7 +630,7 @@ async function aggregation(fromPeriod, toPeriod = 60000) {
 		await stat(getLogFilePath());
 		const delay = performance.now() - start;
 		if (delay > 5000) {
-			log.warn?.('Unusually high task queue latency on the main thread of ' + Math.round(now - start) + 'ms');
+			log.warn?.('Unusually high task queue latency on the main thread of ' + Math.round(delay) + 'ms');
 		}
 		return delay;
 	})();
@@ -565,7 +770,9 @@ async function aggregation(fromPeriod, toPeriod = 60000) {
 		}
 	}
 	const now = Date.now();
-	const { idle, active } = performance.eventLoopUtilization();
+	const { idle, active } = (globalThis as any).Bun
+		? { idle: 0, active: 0 }
+		: (performance as any).eventLoopUtilization();
 	// don't record boring entries
 	if (hasUpdates || active * 10 > idle) {
 		const value = {
@@ -600,14 +807,21 @@ async function aggregation(fromPeriod, toPeriod = 60000) {
 	storeMetric(analyticsTable, cruMetric);
 	lastResourceUsage = resourceUsage;
 
+	// `system` is set as non-enumerable on the object returned by getDatabases() so most
+	// callers skip it; for analytics we want it included, so build a view where it's enumerable.
+	const databases = getDatabasesIncludingSystem();
+
 	// database-size & table-size metrics
-	const databases = getDatabases();
 	storeDBSizeMetrics(analyticsTable, databases);
-	storeDBSizeMetrics(analyticsTable, { system: databases.system });
 
 	// database storage volume metrics
 	storeVolumeMetrics(analyticsTable, databases);
-	storeVolumeMetrics(analyticsTable, { system: databases.system });
+
+	// rocksdb engine stats (only for RocksDB-backed databases)
+	const rocksDBPeriod = lastRocksDBStatsTime ? now - lastRocksDBStatsTime : undefined;
+	storeRocksDBStatsMetrics(analyticsTable, databases, now, rocksDBPeriod);
+	pruneRocksDBStatsCache(databases);
+	lastRocksDBStatsTime = now;
 
 	// node storage metric (total HDB directory size)
 	await storeNodeStorageMetric(analyticsTable);
@@ -622,6 +836,8 @@ let lastResourceUsage: ResourceUsage = {
 const rest = () => new Promise(setImmediate);
 
 async function cleanup(AnalyticsTable, expiration) {
+	// Skip writes in read-only mode
+	if (isReadOnlyMode()) return;
 	const end = Date.now() - expiration;
 	for (const key of AnalyticsTable.primaryStore.getKeys({ start: false, end })) {
 		AnalyticsTable.primaryStore.remove(key);
@@ -694,11 +910,16 @@ function startScheduledTasks() {
 	nodeStorageInterval = envGet(CONFIG_PARAMS.ANALYTICS_STORAGEINTERVAL) ?? DEFAULT_STORAGE_INTERVAL;
 	const AGGREGATE_PERIOD = envGet(CONFIG_PARAMS.ANALYTICS_AGGREGATEPERIOD) * 1000;
 	if (AGGREGATE_PERIOD) {
+		// Clamp raw retention to at least one full aggregation period so raw records
+		// are never deleted before they can be rolled up.
+		const rawRetentionMs = Math.max(envGet(CONFIG_PARAMS.ANALYTICS_RAWRETENTIONMS) ?? RAW_EXPIRATION, AGGREGATE_PERIOD);
+		const aggregateRetentionMs = envGet(CONFIG_PARAMS.ANALYTICS_AGGREGATERETENTIONMS) ?? AGGREGATE_EXPIRATION;
 		setInterval(
 			async () => {
 				await aggregation(analyticsDelay, AGGREGATE_PERIOD);
-				await cleanup(getRawAnalyticsTable(), RAW_EXPIRATION);
-				await cleanup(getAnalyticsTable(), AGGREGATE_EXPIRATION);
+				await cleanup(getRawAnalyticsTable(), rawRetentionMs);
+				// 0 means "keep forever" — skip aggregate cleanup, matching storageInterval: 0 convention
+				if (aggregateRetentionMs) await cleanup(getAnalyticsTable(), aggregateRetentionMs);
 			},
 			Math.min(AGGREGATE_PERIOD / 2, 0x7fffffff)
 		).unref();
@@ -709,6 +930,8 @@ let totalBytesProcessed = 0;
 const lastUtilizations = new Map();
 const LOG_ANALYTICS = false; // TODO: Make this a config option if we really want this
 function recordAnalytics(message, worker?) {
+	// Skip writes in read-only mode
+	if (isReadOnlyMode()) return;
 	const report = message.report;
 	report.threadId = worker?.threadId || threadId;
 	// Add system information stats as well
@@ -718,7 +941,7 @@ function recordAnalytics(message, worker?) {
 		}
 	}
 	report.totalBytesProcessed = totalBytesProcessed;
-	if (worker) {
+	if (worker && !isBun) {
 		report.metrics.push({
 			metric: METRIC.UTILIZATION,
 			...worker.performance.eventLoopUtilization(lastUtilizations.get(worker)),

package/resources/auditStore.ts

@@ -1,16 +1,17 @@
 import { readKey, writeKey } from 'ordered-binary';
-import { initSync, get as envGet } from '../utility/environment/environmentManager.js';
-import { AUDIT_STORE_NAME } from '../utility/lmdb/terms.js';
+import { initSync, get as envGet } from '../utility/environment/environmentManager.ts';
+import { AUDIT_STORE_NAME } from '../utility/lmdb/terms.ts';
 import { CONFIG_PARAMS } from '../utility/hdbTerms.ts';
 import { getWorkerIndex, getWorkerCount } from '../server/threads/manageThreads.js';
-import { convertToMS } from '../utility/common_utils.js';
+import { convertToMS } from '../utility/common_utils.ts';
 import { PREVIOUS_TIMESTAMP_PLACEHOLDER, LAST_TIMESTAMP_PLACEHOLDER } from './RecordEncoder.ts';
-import * as harperLogger from '../utility/logging/harper_logger.js';
+import * as harperLogger from '../utility/logging/harper_logger.ts';
 import { getRecordAtTime } from './crdt.ts';
 import { decodeFromDatabase } from './blob.ts';
 import { onStorageReclamation } from '../server/storageReclamation.ts';
 import { RocksDatabase } from '@harperfast/rocksdb-js';
 import { RocksTransactionLogStore } from './RocksTransactionLogStore.ts';
+import { isReadOnlyMode } from './databases.ts';
 
 /**
  * This module is responsible for the binary representation of audit records in an efficient form.
@@ -32,24 +33,29 @@ import { RocksTransactionLogStore } from './RocksTransactionLogStore.ts';
 initSync();
 
 export type AuditRecord = {
-	version?: number;
-	localTime?: number; // only to be used by LMDB (from the key)
+	version: number;
+	localTime: number; // only to be used by LMDB (from the key)
 	type: string;
-	encodedRecord: Buffer;
-	extendedType: number;
-	residencyId: number;
-	previousResidencyId: number;
-	expiresAt: Date | null;
+	encodedRecord?: Buffer;
+	extendedType?: number;
+	residencyId?: number;
+	previousResidencyId?: number;
+	expiresAt: number | null;
 	originatingOperation: string;
-	tableId: number;
-	recordId: number;
-	previousVersion: number;
+	tableId?: number;
+	recordId?: number;
+	previousVersion?: number;
 	user?: string;
 	nodeId?: number;
-	previousNodeId?: number;
-	previousAdditionalAuditRefs?: Array<{ version: number; nodeId: number }>;
-	endTxn?: boolean;
+	previousNodeId: number;
+	previousAdditionalAuditRefs?: Array<{ version?: number; nodeId: number }>;
+	key?: any;
+	encoded?: any;
+	size: number;
+	getValue?: any;
+	getBinaryValue?: any;
 	structureVersion?: number;
+	endTxn?: boolean;
 	getBinaryRecordId?: any;
 };
 
@@ -156,6 +162,8 @@ export function openAuditStore(rootStore) {
 		}
 	});
 	function scheduleAuditCleanup(newCleanupDelay?: number): Promise<void> {
+		// Skip audit cleanup/purge in read-only mode
+		if (isReadOnlyMode()) return;
 		if (auditStore instanceof RocksTransactionLogStore) {
 			auditStore.rootStore.purgeLogs({
 				before: Date.now() - auditRetention / (1 + cleanupPriority * cleanupPriority),
@@ -269,6 +277,8 @@ export function setAuditRetention(retentionTime, defaultDelay = DEFAULT_AUDIT_CL
  * needs are never removed. Returns the names of the purged files. See harper#1115.
  */
 export function purgeAgedLogs(rootStore: RocksDatabase): string[] {
+	// Mirror the read-only guard in scheduleAuditCleanup: never delete log files in read-only mode.
+	if (isReadOnlyMode()) return [];
 	return rootStore.purgeLogs({ before: Date.now() - auditRetention });
 }
 
@@ -452,7 +462,8 @@ export function createAuditEntry(auditRecord: AuditRecord, start = 0) {
 export function readAuditEntry(buffer: Uint8Array, start = 0, end = undefined): AuditRecord {
 	try {
 		const decoder =
-			buffer.decoder || (buffer.decoder = new Decoder(buffer.buffer, buffer.byteOffset, buffer.byteLength));
+			(buffer as any).decoder ||
+			((buffer as any).decoder = new Decoder(buffer.buffer, buffer.byteOffset, buffer.byteLength));
 		decoder.position = start;
 		let previousVersion;
 		if (buffer[decoder.position] == 66) {
@@ -575,7 +586,7 @@ export function readAuditEntry(buffer: Uint8Array, start = 0, end = undefined):
 			expiresAt,
 			originatingOperation,
 			previousAdditionalAuditRefs,
-		};
+		} as any;
 	} catch (error) {
 		harperLogger.error('Reading audit entry error', error, buffer);
 		return createCorruptAuditSentinel(buffer, start, end);