@cosmicdrift/kumiko-framework 0.404.0 → 0.405.0

package/dist/search/reindex-tenants-search.js

@@ -0,0 +1,69 @@
+import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
+import { createFallbackLogger } from "../logging/utils.js";
+import { runWithTimeout } from "../utils/run-with-timeout.js";
+import { collectSearchableFieldNames } from "./configure-tenant-index.js";
+import { isEntitySearchable } from "./is-entity-searchable.js";
+import { reindexEntity } from "./reindex-entity.js";
+const defaultLog = createFallbackLogger("search");
+const DEFAULT_CONFIGURE_TIMEOUT_MS = 5_000;
+const DEFAULT_REINDEX_TIMEOUT_MS = 60_000;
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+// Reindexing an unconfigured index falls back to searchableAttributes ["*"],
+// so a tenant whose configure failed is reported and skipped, not fatal.
+async function configureTolerant(tenantIds, registry, searchAdapter, timeoutMs, warn) {
+    const fields = collectSearchableFieldNames(registry);
+    const configured = [];
+    let failedConfigures = 0;
+    for (const tenantId of tenantIds) {
+        const outcome = await runWithTimeout(() => searchAdapter.configure(tenantId, { searchableFields: fields, rankingFields: fields }), timeoutMs);
+        if (outcome.ok) {
+            configured.push(tenantId);
+        }
+        else {
+            failedConfigures += 1;
+            warn(`[search] configure for tenant ${tenantId} failed: ${messageOf(outcome.error)}`);
+        }
+    }
+    return { configured, failedConfigures };
+}
+export async function reindexTenantsSearch(db, registry, searchAdapter, options) {
+    const warn = options.warn ?? ((message) => defaultLog.warn(message));
+    const reindexTimeoutMs = options.timeoutMs ?? DEFAULT_REINDEX_TIMEOUT_MS;
+    const dryRun = options.dryRun === true;
+    const { configured, failedConfigures } = dryRun
+        ? { configured: [...options.tenantIds], failedConfigures: 0 }
+        : await configureTolerant(options.tenantIds, registry, searchAdapter, options.configureTimeoutMs ?? DEFAULT_CONFIGURE_TIMEOUT_MS, warn);
+    let entities = 0;
+    let indexedRows = 0;
+    let failedRows = 0;
+    let failedReindexes = 0;
+    for (const [entityName, entity] of registry.getAllEntities()) {
+        if (!isEntitySearchable(registry, entityName))
+            continue;
+        entities += 1;
+        const targetTenantIds = entity.systemStream === true ? [SYSTEM_TENANT_ID] : configured;
+        for (const tenantId of targetTenantIds) {
+            const outcome = await runWithTimeout(() => reindexEntity(db, registry, searchAdapter, entityName, tenantId, dryRun ? { dryRun } : {}), reindexTimeoutMs);
+            if (!outcome.ok) {
+                failedReindexes += 1;
+                warn(`[search] reindex "${entityName}" tenant=${tenantId} failed: ${messageOf(outcome.error)}`);
+                continue;
+            }
+            indexedRows += outcome.value.indexedRows;
+            if (outcome.value.failures.length > 0) {
+                failedRows += outcome.value.failures.length;
+                warn(`[search] reindex "${entityName}" tenant=${tenantId}: ${outcome.value.failures.length} row(s) failed, first: ${outcome.value.failures[0]?.reason}`);
+            }
+        }
+    }
+    return {
+        tenants: options.tenantIds.length,
+        entities,
+        indexedRows,
+        failedRows,
+        failedReindexes,
+        failedConfigures,
+    };
+}

package/dist/utils/chunk.d.ts

@@ -0,0 +1 @@
+export declare function chunk<T>(items: readonly T[], size: number): T[][];

package/dist/utils/chunk.js

@@ -0,0 +1,7 @@
+export function chunk(items, size) {
+    const chunks = [];
+    for (let start = 0; start < items.length; start += size) {
+        chunks.push(items.slice(start, start + size));
+    }
+    return chunks;
+}

package/dist/utils/hex.d.ts

@@ -0,0 +1,3 @@
+export type DigestAlgorithm = "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512";
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function digestHex(algorithm: DigestAlgorithm, text: string): Promise<string>;

package/dist/utils/hex.js

@@ -0,0 +1,11 @@
+export function bytesToHex(bytes) {
+    let out = "";
+    for (let i = 0; i < bytes.length; i++) {
+        out += (bytes[i] ?? 0).toString(16).padStart(2, "0");
+    }
+    return out;
+}
+export async function digestHex(algorithm, text) {
+    const digest = await crypto.subtle.digest(algorithm, new TextEncoder().encode(text));
+    return bytesToHex(new Uint8Array(digest));
+}

package/dist/utils/index.d.ts

@@ -1,6 +1,9 @@
 export { assertUnreachable } from "./assert.ts";
+export { chunk } from "./chunk.ts";
+export { bytesToHex, type DigestAlgorithm, digestHex } from "./hex.ts";
 export { generateDeterministicId, generateId } from "./ids.ts";
 export { isPlainObject } from "./is-plain-object.ts";
+export { createLruCache, type LruCache, type LruCacheOptions } from "./lru-cache.ts";
 export { parseStringArrayJson } from "./parse-string-array-json.ts";
 export { parseJsonOrThrow, parseJsonSafe } from "./safe-json.ts";
 export { parseRoles } from "./serialization.ts";

package/dist/utils/index.js

@@ -1,6 +1,9 @@
 export { assertUnreachable } from "./assert.js";
+export { chunk } from "./chunk.js";
+export { bytesToHex, digestHex } from "./hex.js";
 export { generateDeterministicId, generateId } from "./ids.js";
 export { isPlainObject } from "./is-plain-object.js";
+export { createLruCache } from "./lru-cache.js";
 export { parseStringArrayJson } from "./parse-string-array-json.js";
 export { parseJsonOrThrow, parseJsonSafe } from "./safe-json.js";
 export { parseRoles } from "./serialization.js";

package/dist/utils/lru-cache.d.ts

@@ -0,0 +1,17 @@
+export type LruCacheOptions<V> = {
+    readonly maxEntries: number;
+    /** Entries at least this old count as misses; omitted = no expiry. */
+    readonly ttlMs?: number;
+    readonly now?: () => number;
+    /** Summed `sizeOf` budget; a value larger than the whole budget is never cached. */
+    readonly maxTotalSize?: number;
+    readonly sizeOf?: (value: V) => number;
+};
+export type LruCache<K, V> = {
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    delete(key: K): void;
+    clear(): void;
+    readonly size: number;
+};
+export declare function createLruCache<K, V>(options: LruCacheOptions<V>): LruCache<K, V>;

package/dist/utils/lru-cache.js

@@ -0,0 +1,56 @@
+// Map iteration is insertion order: re-inserting on a hit keeps the most recently used entry last.
+export function createLruCache(options) {
+    const now = options.now ?? Date.now;
+    const sizeOf = options.sizeOf ?? (() => 0);
+    const entries = new Map();
+    let totalSize = 0;
+    function remove(key) {
+        const stored = entries.get(key);
+        // skip: key not cached, nothing to remove
+        if (stored === undefined)
+            return;
+        totalSize -= stored.size;
+        entries.delete(key);
+    }
+    function overBudget() {
+        if (entries.size > options.maxEntries)
+            return true;
+        return options.maxTotalSize !== undefined && totalSize > options.maxTotalSize;
+    }
+    return {
+        get(key) {
+            const hit = entries.get(key);
+            if (hit === undefined)
+                return undefined;
+            remove(key);
+            if (options.ttlMs !== undefined && now() - hit.storedAt >= options.ttlMs)
+                return undefined;
+            entries.set(key, hit);
+            totalSize += hit.size;
+            return hit.value;
+        },
+        set(key, value) {
+            remove(key);
+            const size = sizeOf(value);
+            // skip: a value larger than the whole budget would evict everything and still not fit
+            if (options.maxTotalSize !== undefined && size > options.maxTotalSize)
+                return;
+            entries.set(key, { value, storedAt: now(), size });
+            totalSize += size;
+            while (overBudget()) {
+                const oldest = entries.keys().next();
+                if (oldest.done)
+                    break;
+                remove(oldest.value);
+            }
+        },
+        delete: remove,
+        clear() {
+            entries.clear();
+            totalSize = 0;
+        },
+        get size() {
+            return entries.size;
+        },
+    };
+}

package/dist/utils/run-with-timeout.d.ts

@@ -0,0 +1,11 @@
+export type TimedRunResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+    readonly latencyMs: number;
+} | {
+    readonly ok: false;
+    readonly error: unknown;
+    readonly timedOut: boolean;
+    readonly latencyMs: number;
+};
+export declare function runWithTimeout<T>(run: () => Promise<T>, timeoutMs: number): Promise<TimedRunResult<T>>;

package/dist/utils/run-with-timeout.js

@@ -0,0 +1,30 @@
+class TimeoutError extends Error {
+}
+export async function runWithTimeout(run, timeoutMs) {
+    const start = performance.now();
+    const elapsedMs = () => Math.round(performance.now() - start);
+    let timer;
+    try {
+        const value = await Promise.race([
+            run(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new TimeoutError(`timeout after ${timeoutMs}ms`)), timeoutMs);
+                // Don't keep the event loop alive on a hung run during shutdown.
+                timer.unref?.();
+            }),
+        ]);
+        return { ok: true, value, latencyMs: elapsedMs() };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error,
+            timedOut: error instanceof TimeoutError,
+            latencyMs: elapsedMs(),
+        };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.404.0",
+  "version": "0.405.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -203,21 +203,21 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.404.0",
-    "bullmq": "^5.76.7",
+    "@cosmicdrift/kumiko-types": "0.405.0",
+    "bullmq": "^5.81.5",
     "hono": "^4.13.14",
-    "i18next": "^26.1.0",
-    "ioredis": "^5.10.1",
-    "jose": "^6.2.13",
-    "pino": "^10.3.1",
+    "i18next": "^26.5.12",
+    "ioredis": "^5.11.1",
+    "jose": "^6.2.14",
+    "pino": "^10.4.0",
     "temporal-polyfill": "^0.3.2",
-    "uuid": "^14.0.0",
+    "uuid": "^14.0.3",
     "write-excel-file": "^4.1.1",
     "zod": "^4.6.7"
   },
   "peerDependencies": {
     "bun-types": "^1.4.4",
-    "meilisearch": "^0.58.0"
+    "meilisearch": "^0.62.0"
   },
   "peerDependenciesMeta": {
     "meilisearch": {
@@ -225,11 +225,11 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.404.0",
+    "@cosmicdrift/kumiko-testing": "0.405.0",
     "bun-types": "^1.4.4",
     "fflate": "^0.8.3",
-    "meilisearch": "^0.58.0",
-    "pino-pretty": "^13.1.3"
+    "meilisearch": "^0.62.0",
+    "pino-pretty": "^13.2.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/presets/biome-app.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.5.7/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.6.4/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",

package/src/changes.json

@@ -1,4 +1,40 @@
 [
+  {
+    "version": "0.405.0",
+    "type": "improvement",
+    "title": "chunk in framework utils",
+    "detail": "@cosmicdrift/kumiko-framework/utils exports chunk(items, size), which splits an array into slices of at most size elements. files-tenant-data, subscription-paddle and template-resolver use it instead of local copies."
+  },
+  {
+    "version": "0.405.0",
+    "type": "improvement",
+    "title": "Search sweep helpers in framework/search",
+    "detail": "@cosmicdrift/kumiko-framework/search exports collectSearchableFieldNames, isEntitySearchable and reindexTenantsSearch(db, registry, adapter, { tenantIds, timeoutMs?, configureTimeoutMs?, dryRun?, warn? }). The sweep configures each given tenant index, then reindexes every searchable entity for those tenants (system-stream entities once under the system tenant) and returns counts of indexed rows and failures. A failed configure or reindex is reported through warn and does not stop the sweep. Apps no longer need their own configure-on-boot seed: the server's default search config is applied lazily to a missing or factory-default index."
+  },
+  {
+    "version": "0.405.0",
+    "type": "improvement",
+    "title": "createLruCache in framework utils",
+    "detail": "@cosmicdrift/kumiko-framework/utils exports createLruCache({ maxEntries, ttlMs?, now?, maxTotalSize?, sizeOf? }) with get, set, delete, clear and size. The tenant timezone cache and the managed-pages body cache use it. runWithTimeout moves to the utils module; the api barrel export stays."
+  },
+  {
+    "version": "0.405.0",
+    "type": "improvement",
+    "title": "Engine and db helpers deduplicated",
+    "detail": "The engine uses one findEntity lookup instead of three copies, the PII subject resolver and the boot validator use isFileField, insertOne builds its SQL through the same insert helpers as insertMany, the projection rebuild maps event rows through the shared toStoredEvent, and the app-schema role projection filters row, toolbar and related-list actions through one helper. No behavior change."
+  },
+  {
+    "version": "0.405.0",
+    "type": "improvement",
+    "title": "One key split for file variants and derivatives",
+    "detail": "deriveKey and the derivative key helpers split a storage key into base and extension through the same function, so both always agree on where the extension starts. No behavior change."
+  },
+  {
+    "version": "0.405.0",
+    "type": "improvement",
+    "title": "Opaque-token hash and hex helpers exported",
+    "detail": "@cosmicdrift/kumiko-framework/crypto exports hashOpaqueToken (async, Web Crypto), hashOpaqueTokenSync (node:crypto, for synchronous server paths) and opaqueTokenHashMatches (timing-safe comparison against a stored SHA-256 hex hash). @cosmicdrift/kumiko-framework/utils exports bytesToHex and digestHex(algorithm, text). The framework's own token hashes (personal access tokens, single-use token store, preauth MFA key, export download tokens, termination revocation) use them and produce the same hex as before. Apps that hash share or heartbeat tokens themselves can switch to these helpers without migrating stored hashes."
+  },
   {
     "version": "0.404.0",
     "type": "improvement",