@ti-engine/web-framework 1.21.0 → 1.24.0

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.