@ti-engine/web-framework 1.23.0 → 1.24.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 This document will contain the list of changes made to the framework. The format is based on the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
 
+## Version 1.24.0
+
+A configuration file change shipped in a release could never reach a deployment that had already been seeded. The
+store writes a file default only when the document has never been written, and the consuming application then lets
+the stored value overwrite the file value on every boot — so the file default is consulted exactly once in a
+deployment's lifetime. Restore could not help either, since it replays a previous version and the oldest version
+*is* the stale one. The framework now detects that difference and lets an admin apply it deliberately.
+
+* feat(config-drift): new `#config-drift` module — a pure structural diff between a document's registered file
+  default and its stored value. Recurses into objects to report leaf paths, **set-diffs arrays of primitives** so a
+  code-list change reads as `+27 codes` rather than an opaque "changed", and compares arrays of objects atomically.
+  Paths use the same dot/bracket dialect as schema validation issues
+* feat(config-service): `getDrift`, `listDrift` and `applyDefaults`. Applying routes through `applyEdits`, so a
+  file default lands validated, versioned, correlated into one change-set, in the audit feed, and restorable —
+  never as a side-channel write
+* feat(config-service): interdependent documents apply as a **single** change-set, which is required rather than
+  merely convenient: a semantic validator resolves its siblings at their *pending* value, so a document whose
+  constraint spans another can only pass when both are applied together
+* feat(admin-config-handlers): `GET /admin/config/drift`, `GET /admin/config/drift/:configKey` and
+  `POST /admin/config/drift/apply`, all admin-gated
+* build(release): bump package version from `1.23.0` to `1.24.0`
+
+**Note on statuses:** `absent` (never seeded) is deliberately distinct from `drifted`. A document that is registered
+but never seeded is not a problem to act on, and folding the two together would flag it on every boot of a clean
+install — training operators to ignore exactly the signal this feature exists to raise.
+
 ## Version 1.23.0
 
 Local (username/password) authentication is real. It had never been implemented: the constructor overwrote whatever

package/bin/web-server.js

@@ -585,6 +585,9 @@ class TiWebServer extends ServiceConsumer {
         this.#webServer.get( "/admin/config/changes/:changeSetID", requireAdmin, adminConfigHandlers.getChange( service ) );
         this.#webServer.post( "/admin/config/changes/:changeSetID/restore", requireAdmin, adminConfigHandlers.restoreChangeSet( service ) );
         this.#webServer.get( "/admin/config/export", requireAdmin, adminConfigHandlers.exportBundle( service ) );
+        this.#webServer.get( "/admin/config/drift", requireAdmin, adminConfigHandlers.listDrift( service ) );
+        this.#webServer.get( "/admin/config/drift/:configKey", requireAdmin, adminConfigHandlers.getDrift( service ) );
+        this.#webServer.post( "/admin/config/drift/apply", requireAdmin, adminConfigHandlers.applyDefaults( service ) );
     }
 
     /**

package/components/admin-config-handlers.js

@@ -93,3 +93,34 @@ module.exports.exportBundle = ( service ) => ( request, response, next ) => {
         response.status( exceptions.httpCode.C_200 ).send( JSON.stringify( bundle, null, 2 ) );
     } ).catch( ( error ) => forward( next, error ) );
 };
+
+/**
+ * `GET /admin/config/drift` — drift summaries for every registered document.
+ *
+ * @param {ConfigService} service
+ * @returns {ExpressHandler} The Express handler.
+ */
+module.exports.listDrift = ( service ) => ( request, response, next ) => {
+    service.listDrift().then( ( drift ) => sendData( response, drift ) ).catch( ( error ) => forward( next, error ) );
+};
+
+/**
+ * `GET /admin/config/drift/:configKey` — one document's drift, including the full entry list.
+ *
+ * @param {ConfigService} service
+ * @returns {ExpressHandler} The Express handler.
+ */
+module.exports.getDrift = ( service ) => ( request, response, next ) => {
+    service.getDrift( request.params.configKey ).then( ( drift ) => sendData( response, drift ) ).catch( ( error ) => forward( next, error ) );
+};
+
+/**
+ * `POST /admin/config/drift/apply` — applies the file defaults for the named documents as one change-set.
+ *
+ * @param {ConfigService} service
+ * @returns {ExpressHandler} The Express handler.
+ */
+module.exports.applyDefaults = ( service ) => ( request, response, next ) => {
+    const body = request.body || {};
+    service.applyDefaults( body.configKeys, { adminID: adminID( request ), note: body.note } ).then( ( result ) => sendData( response, result ) ).catch( ( error ) => forward( next, error ) );
+};

package/components/config-drift.js

@@ -0,0 +1,141 @@
+/*
+ * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
+ * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+/**
+ * Pure structural diff between a configuration document's file default and the value currently held in the store.
+ * <br/>
+ * The store seeds from a file default exactly once ({@link ConfigStore#seedIfEmpty}), so a release that changes a
+ * config file changes nothing an already-seeded deployment serves. This module is the detection half of the remedy:
+ * it answers "how does the shipped default differ from what this deployment is running", in terms legible enough for
+ * an admin to judge whether applying it is safe.
+ * <br/>
+ * No I/O — the caller supplies both values.
+ *
+ * @module config-drift
+ */
+
+const { isDeepStrictEqual } = require( "node:util" );
+
+const STATUS_IN_SYNC = "in-sync";
+const STATUS_DRIFTED = "drifted";
+const STATUS_ABSENT = "absent";
+const STATUS_NO_DEFAULT = "no-default";
+
+const KIND_ADDED = "added";
+const KIND_REMOVED = "removed";
+const KIND_CHANGED = "changed";
+
+/**
+ * @typedef {Object} ConfigDriftEntry
+ * @property {string} path Dot/bracket data path, matching the dialect used for schema validation issues.
+ * @property {string} kind One of "added", "removed", "changed".
+ * @property {number} [addedMembers] For a primitive array: how many members the file default adds.
+ * @property {number} [removedMembers] For a primitive array: how many members the file default drops.
+ */
+
+/**
+ * @param {*} value
+ * @returns {boolean} True for a non-null, non-array object.
+ */
+function isPlainObject( value ) {
+    return value !== null && typeof value === "object" && !Array.isArray( value );
+}
+
+/**
+ * @param {*} value
+ * @returns {boolean} True for an array holding no objects (a code list, a set of flags, …).
+ */
+function isPrimitiveArray( value ) {
+    return Array.isArray( value ) && value.every( ( item ) => item === null || typeof item !== "object" );
+}
+
+/**
+ * @param {string} base
+ * @param {string} key
+ * @returns {string} The child path, numeric keys in bracket notation.
+ */
+function joinPath( base, key ) {
+    return ( /^\d+$/.test( key ) ) ? `${ base }[${ key }]` : `${ base }.${ key }`;
+}
+
+/**
+ * Recursive worker. Appends to `entries` in place.
+ *
+ * @param {*} fileValue
+ * @param {*} storedValue
+ * @param {string} path
+ * @param {ConfigDriftEntry[]} entries
+ */
+function diffValue( fileValue, storedValue, path, entries ) {
+    if ( isPlainObject( fileValue ) && isPlainObject( storedValue ) ) {
+        const keys = new Set( [ ...Object.keys( fileValue ), ...Object.keys( storedValue ) ] );
+        for ( const key of keys ) {
+            const childPath = joinPath( path, key );
+            const inFile = Object.prototype.hasOwnProperty.call( fileValue, key );
+            const inStored = Object.prototype.hasOwnProperty.call( storedValue, key );
+            if ( inFile && !inStored ) {
+                entries.push( { path: childPath, kind: KIND_ADDED } );
+            } else if ( !inFile && inStored ) {
+                entries.push( { path: childPath, kind: KIND_REMOVED } );
+            } else {
+                diffValue( fileValue[ key ], storedValue[ key ], childPath, entries );
+            }
+        }
+        return;
+    }
+
+    // A list of codes is a set, not a sequence: report which members moved, and treat a pure reorder as no change.
+    // This is what turns "role-family-competencies changed" into the far more useful "QE +27 codes".
+    // <br/>
+    // Set semantics also mean MULTIPLICITY is ignored — `[ "A", "A" ]` and `[ "A" ]` compare as in-sync even though
+    // applying would replace one with the other. That is deliberate for a list of codes, where a repeated member is
+    // a data error rather than a meaningful difference, and it is unreachable for the documents shipped here: the
+    // array-valued competence schemas all declare `uniqueItems`, so a duplicate cannot pass validation on save. A
+    // consumer whose arrays are genuinely multisets should not model them as primitive arrays for this diff.
+    if ( isPrimitiveArray( fileValue ) && isPrimitiveArray( storedValue ) ) {
+        const storedMembers = new Set( storedValue );
+        const fileMembers = new Set( fileValue );
+        const addedMembers = fileValue.filter( ( item ) => !storedMembers.has( item ) ).length;
+        const removedMembers = storedValue.filter( ( item ) => !fileMembers.has( item ) ).length;
+        if ( addedMembers > 0 || removedMembers > 0 ) {
+            entries.push( { path: path, kind: KIND_CHANGED, addedMembers: addedMembers, removedMembers: removedMembers } );
+        }
+        return;
+    }
+
+    if ( !isDeepStrictEqual( fileValue, storedValue ) ) {
+        entries.push( { path: path, kind: KIND_CHANGED } );
+    }
+}
+
+/**
+ * Diffs a document's registered file default against its stored value.
+ *
+ * @method
+ * @param {*} fileDefault The value registered with {@link ConfigRegistry#register}; `undefined` when none was.
+ * @param {*} storedValue The value currently in the store; `null`/`undefined` when never written.
+ * @returns {{status: string, entries: ConfigDriftEntry[], counts: {added: number, removed: number, changed: number}}}
+ * @public
+ */
+module.exports.diffDocument = ( fileDefault, storedValue ) => {
+    if ( fileDefault === undefined ) {
+        return { status: STATUS_NO_DEFAULT, entries: [], counts: { added: 0, removed: 0, changed: 0 } };
+    }
+    if ( storedValue === undefined || storedValue === null ) {
+        return { status: STATUS_ABSENT, entries: [], counts: { added: 0, removed: 0, changed: 0 } };
+    }
+
+    const entries = [];
+    diffValue( fileDefault, storedValue, "", entries );
+
+    const counts = { added: 0, removed: 0, changed: 0 };
+    for ( const entry of entries ) {
+        counts[ entry.kind ] += 1;
+    }
+    return { status: ( entries.length > 0 ) ? STATUS_DRIFTED : STATUS_IN_SYNC, entries: entries, counts: counts };
+};

package/components/config-service.js

@@ -7,6 +7,7 @@
 */
 
 const exceptions = require( "@ti-engine/core/exceptions" );
+const configDrift = require( "#config-drift" );
 
 /** @import ConfigChangeNotifier from "#config-change-notifier" */
 /** @import ConfigRegistry from "#config-registry" */
@@ -307,6 +308,102 @@ class ConfigService {
         } ) );
     }
 
+    /* Public interface — drift against file defaults */
+
+    /**
+     * Compares a document's registered file default against the value currently in the store. This is how a
+     * configuration change shipped in a release becomes visible on a deployment that was seeded before it — the
+     * store seeds only once, so a later file change is otherwise invisible.
+     *
+     * @method
+     * @param {string} configKey
+     * @returns {Promise<{configKey: string, status: string, counts: Object, entries: Array, storedVersion: number, editable: boolean, label: string}>}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} If the document is not registered.
+     * @public
+     */
+    getDrift( configKey ) {
+        if ( !this.#registry.has( configKey ) ) {
+            return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "unknown-config", configKey: configKey } ) );
+        }
+        const metadata = this.#registry.metadataFor( configKey ) || {};
+        return this.#store.getCurrent( configKey ).then( ( current ) => {
+            const diff = configDrift.diffDocument( this.#registry.getDefault( configKey ), current ? current.value : null );
+            return {
+                configKey: configKey,
+                status: diff.status,
+                counts: diff.counts,
+                entries: diff.entries,
+                storedVersion: current ? current.version : 0,
+                editable: metadata.editable !== false,
+                label: metadata.label || configKey
+            };
+        } );
+    }
+
+    /**
+     * Drift summaries for every registered document. This still computes each document's full entry list internally
+     * (it delegates to {@link ConfigService#getDrift} per document) — the saving is in the response shape, not the
+     * computation: `entries` is omitted here to keep the payload small enough for a landing screen and a startup log,
+     * where only the counts are shown.
+     *
+     * @method
+     * @returns {Promise<Array<Object>>}
+     * @public
+     */
+    listDrift() {
+        return Promise.all( this.#registry.list().map( ( configKey ) => {
+            return this.getDrift( configKey ).then( ( drift ) => ( {
+                configKey: drift.configKey,
+                status: drift.status,
+                counts: drift.counts,
+                storedVersion: drift.storedVersion,
+                editable: drift.editable,
+                label: drift.label
+            } ) );
+        } ) );
+    }
+
+    /**
+     * Applies the registered file defaults for the given documents, as a single validated change-set.
+     * <br/>
+     * Routing through {@link ConfigService#applyEdits} is deliberate: the application is schema- and
+     * semantically validated, versioned, correlated into one change-set, added to the audit feed, and restorable —
+     * and, because a validator sees its siblings at their *pending* value, interdependent documents applied
+     * together validate against each other rather than against the stale stored state.
+     *
+     * @method
+     * @param {string[]} configKeys
+     * @param {Object} meta
+     * @param {string} meta.adminID
+     * @param {string} [meta.note]
+     * @returns {Promise<{ok: true, changeSetID: string, versions: Object}|{ok: false, errors: Object}>}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} On bad input, an unknown key, or a key with no default.
+     * @public
+     */
+    applyDefaults( configKeys, meta ) {
+        if ( !Array.isArray( configKeys ) || configKeys.length === 0 || !meta || !meta.adminID ) {
+            return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "invalid-apply-defaults-input" } ) );
+        }
+        const keys = Array.from( new Set( configKeys ) );
+        const unknown = keys.filter( ( key ) => !this.#registry.has( key ) );
+        if ( unknown.length > 0 ) {
+            return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "unknown-config", configKeys: unknown } ) );
+        }
+        const withoutDefault = keys.filter( ( key ) => this.#registry.getDefault( key ) === undefined );
+        if ( withoutDefault.length > 0 ) {
+            return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "no-default", configKeys: withoutDefault } ) );
+        }
+
+        return Promise.all( keys.map( ( key ) => this.#store.getCurrent( key ) ) ).then( ( currents ) => {
+            const edits = keys.map( ( key, index ) => ( {
+                configKey: key,
+                value: this.#registry.getDefault( key ),
+                expectedVersion: currents[ index ] ? currents[ index ].version : 0
+            } ) );
+            return this.applyEdits( edits, { adminID: meta.adminID, note: meta.note || "applied file defaults" } );
+        } );
+    }
+
     /**
      * Seeds a document's default value into the store only if it has never been written (idempotent bootstrap).
      * Used by an application to bring its file defaults into the store at startup before serving live config.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/web-framework",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "A web-framework based on the ti-engine. It provides a customizable ready-to-use web-server microservice and a set of tools for creating web applications. NOTICE: This is still a work in progress and the full architecture, design, and functionality are not available!",
   "keywords": [
     "ti-engine",
@@ -15,6 +15,10 @@
   "author": "Boris Kostadinov <kostadinov.boris@gmail.com>",
   "license": "GPL-3.0-or-later",
   "exports": {
+    "./config-drift": {
+      "types": "./types/components/config-drift.d.ts",
+      "default": "./components/config-drift.js"
+    },
     "./config-management": {
       "types": "./types/components/config-service.d.ts",
       "default": "./components/config-service.js"
@@ -57,6 +61,10 @@
       "types": "./types/components/config-change-notifier.d.ts",
       "default": "./components/config-change-notifier.js"
     },
+    "#config-drift": {
+      "types": "./types/components/config-drift.d.ts",
+      "default": "./components/config-drift.js"
+    },
     "#config-registry": {
       "types": "./types/components/config-registry.d.ts",
       "default": "./components/config-registry.js"

package/types/components/admin-config-handlers.d.ts

@@ -7,5 +7,8 @@ export declare var listChanges: (service: any) => (request: any, response: any,
 export declare var getChange: (service: any) => (request: any, response: any, next: any) => void;
 export declare var restoreChangeSet: (service: any) => (request: any, response: any, next: any) => void;
 export declare var exportBundle: (service: any) => (request: any, response: any, next: any) => void;
+export declare var listDrift: (service: ConfigService) => ExpressHandler;
+export declare var getDrift: (service: ConfigService) => ExpressHandler;
+export declare var applyDefaults: (service: ConfigService) => ExpressHandler;
 import type ConfigService from "#config-service";
 import type { ExpressHandler } from "#web-handlers";

package/types/components/config-drift.d.ts

@@ -0,0 +1,27 @@
+export declare var diffDocument: (fileDefault: any, storedValue: any) => {
+    status: string;
+    entries: ConfigDriftEntry[];
+    counts: {
+        added: number;
+        removed: number;
+        changed: number;
+    };
+};
+export type ConfigDriftEntry = {
+    /**
+     * Dot/bracket data path, matching the dialect used for schema validation issues.
+     */
+    path: string;
+    /**
+     * One of "added", "removed", "changed".
+     */
+    kind: string;
+    /**
+     * For a primitive array: how many members the file default adds.
+     */
+    addedMembers?: number;
+    /**
+     * For a primitive array: how many members the file default drops.
+     */
+    removedMembers?: number;
+};

package/types/components/config-service.d.ts

@@ -191,6 +191,65 @@ declare class ConfigService {
             value: Object;
         }>;
     }>;
+    /**
+     * Compares a document's registered file default against the value currently in the store. This is how a
+     * configuration change shipped in a release becomes visible on a deployment that was seeded before it — the
+     * store seeds only once, so a later file change is otherwise invisible.
+     *
+     * @method
+     * @param {string} configKey
+     * @returns {Promise<{configKey: string, status: string, counts: Object, entries: Array, storedVersion: number, editable: boolean, label: string}>}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} If the document is not registered.
+     * @public
+     */
+    getDrift(configKey: string): Promise<{
+        configKey: string;
+        status: string;
+        counts: Object;
+        entries: any[];
+        storedVersion: number;
+        editable: boolean;
+        label: string;
+    }>;
+    /**
+     * Drift summaries for every registered document. This still computes each document's full entry list internally
+     * (it delegates to {@link ConfigService#getDrift} per document) — the saving is in the response shape, not the
+     * computation: `entries` is omitted here to keep the payload small enough for a landing screen and a startup log,
+     * where only the counts are shown.
+     *
+     * @method
+     * @returns {Promise<Array<Object>>}
+     * @public
+     */
+    listDrift(): Promise<Array<Object>>;
+    /**
+     * Applies the registered file defaults for the given documents, as a single validated change-set.
+     * <br/>
+     * Routing through {@link ConfigService#applyEdits} is deliberate: the application is schema- and
+     * semantically validated, versioned, correlated into one change-set, added to the audit feed, and restorable —
+     * and, because a validator sees its siblings at their *pending* value, interdependent documents applied
+     * together validate against each other rather than against the stale stored state.
+     *
+     * @method
+     * @param {string[]} configKeys
+     * @param {Object} meta
+     * @param {string} meta.adminID
+     * @param {string} [meta.note]
+     * @returns {Promise<{ok: true, changeSetID: string, versions: Object}|{ok: false, errors: Object}>}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} On bad input, an unknown key, or a key with no default.
+     * @public
+     */
+    applyDefaults(configKeys: string[], meta: {
+        adminID: string;
+        note?: string;
+    }): Promise<{
+        ok: true;
+        changeSetID: string;
+        versions: Object;
+    } | {
+        ok: false;
+        errors: Object;
+    }>;
     /**
      * Seeds a document's default value into the store only if it has never been written (idempotent bootstrap).
      * Used by an application to bring its file defaults into the store at startup before serving live config.