@ti-engine/web-framework 1.13.1

package/components/config-registry.js

@@ -0,0 +1,246 @@
+/*
+ * 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/>.
+*/
+
+const Ajv = require( "ajv" );
+const exceptions = require( "@ti-engine/core/exceptions" );
+
+/**
+ * Converts an ajv `instancePath` (a JSON Pointer, e.g. `/competencies/E1-1/name`) into the dot/bracket data path this
+ * registry has always exposed on schema issues (e.g. `.competencies.E1-1.name`, array indices rendered as `[0]`).
+ * ajv 8 renamed `dataPath` (dot style) to `instancePath` (JSON Pointer); normalizing here keeps the public
+ * {@link ConfigValidationIssue} `path` contract stable across the ajv 6 → 8 upgrade.
+ *
+ * @param {string} [instancePath] The ajv instance path (JSON Pointer), or empty for the document root.
+ * @returns {string} The dot/bracket data path, or "" for the document root.
+ */
+const instancePathToDataPath = ( instancePath ) => {
+    if ( !instancePath ) {
+        return "";
+    }
+    return instancePath
+        .split( "/" )
+        .slice( 1 )
+        .map( ( segment ) => {
+            const key = segment.replace( /~1/g, "/" ).replace( /~0/g, "~" );
+            return ( /^\d+$/.test( key ) ) ? `[${ key }]` : `.${ key }`;
+        } )
+        .join( "" );
+};
+
+/**
+ * @typedef {Object} ConfigValidationIssue
+ * @property {string} path A JSON pointer / data path to the offending value (e.g. ".competencies.E1-1.name"), or "".
+ * @property {string} message Human-readable problem description.
+ * @property {string} code "schema" for JSON-Schema failures, or a validator-supplied code (default "semantic").
+ * @property {Object} [params] Optional structured details (e.g. ajv params).
+ */
+
+/**
+ * @typedef {function(Object, Object): (ConfigValidationIssue[]|Promise<ConfigValidationIssue[]>)} SemanticValidator
+ * A semantic validator receives the candidate value and a context object (e.g. `{ getConfig(key) }` to read other
+ * current configs for cross-document checks) and returns the issues it found (empty array = OK). May be async.
+ */
+
+/**
+ * Registry of editable configuration *documents* and the gate that validates a candidate value against a
+ * document's JSON Schema (ajv) plus its semantic validators. The framework stays domain-agnostic: an application
+ * registers its config documents (schemas, validators, defaults, editor metadata) at startup; this component knows
+ * only "validated, versioned JSON documents". Validation must pass *before* {@link ConfigStore#saveChangeSet}.
+ *
+ * @class ConfigRegistry
+ * @public
+ */
+class ConfigRegistry {
+
+    #ajv;
+    #registrations = new Map();
+
+    constructor() {
+        // ajv 8 speaks Draft-07 by default; our schema files annotate Draft 2020-12 only for editor support, so we
+        // strip that annotation (see #stripUnsupportedMeta) and skip meta-validation.
+        this.#ajv = new Ajv( { allErrors: true, schemaId: "$id", meta: true, validateSchema: false } );
+    }
+
+    /* Public interface */
+
+    /**
+     * Registers an editable configuration document.
+     *
+     * @method
+     * @param {string} configKey Stable identifier for the document (also the ConfigStore key).
+     * @param {Object} definition
+     * @param {Object} definition.schema A JSON Schema for the document.
+     * @param {SemanticValidator[]} [definition.validators] Cross-cutting/semantic checks beyond the schema.
+     * @param {Object} [definition.defaultValue] The bootstrap default (seeds an empty store).
+     * @param {Object} [definition.metadata] Editor metadata (label, editor type, group, risk class, …).
+     * @returns {ConfigRegistry} this (chainable)
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} On missing key/schema.
+     * @public
+     */
+    register( configKey, definition ) {
+        const { schema, validators = [], defaultValue, metadata = {} } = definition || {};
+        if ( !configKey || !schema || typeof schema !== "object" ) {
+            throw exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "invalid-config-registration", configKey: configKey } );
+        }
+        const prepared = this.#stripUnsupportedMeta( schema );
+        this.addSchema( prepared );
+        this.#registrations.set( configKey, {
+            schema: prepared,
+            validators: Array.isArray( validators ) ? validators : [],
+            defaultValue: defaultValue,
+            metadata: metadata || {},
+            compiled: null
+        } );
+        return this;
+    }
+
+    /**
+     * Adds a schema that is referenced (via `$ref`/`$id`) by document schemas but is not itself a document.
+     *
+     * @method
+     * @param {Object} schema
+     * @returns {ConfigRegistry} this (chainable)
+     * @public
+     */
+    addSchema( schema ) {
+        const prepared = this.#stripUnsupportedMeta( schema );
+        if ( prepared && prepared.$id && !this.#ajv.getSchema( prepared.$id ) ) {
+            this.#ajv.addSchema( prepared );
+        }
+        return this;
+    }
+
+    /**
+     * @method
+     * @param {string} configKey
+     * @returns {boolean}
+     * @public
+     */
+    has( configKey ) {
+        return this.#registrations.has( configKey );
+    }
+
+    /**
+     * @method
+     * @returns {string[]} All registered configuration keys.
+     * @public
+     */
+    list() {
+        return Array.from( this.#registrations.keys() );
+    }
+
+    /**
+     * @method
+     * @param {string} configKey
+     * @returns {Object|undefined} The editor metadata registered for the document.
+     * @public
+     */
+    metadataFor( configKey ) {
+        const registration = this.#registrations.get( configKey );
+        return registration ? registration.metadata : undefined;
+    }
+
+    /**
+     * @method
+     * @param {string} configKey
+     * @returns {Object|undefined} The bootstrap default value registered for the document.
+     * @public
+     */
+    getDefault( configKey ) {
+        const registration = this.#registrations.get( configKey );
+        return registration ? registration.defaultValue : undefined;
+    }
+
+    /**
+     * Validates a candidate value for a registered document: JSON Schema first, then the semantic validators.
+     * Resolves with `{ valid, errors }` (errors is an array of {@link ConfigValidationIssue}).
+     *
+     * @method
+     * @param {string} configKey
+     * @param {Object} value
+     * @param {Object} [context] Passed to each semantic validator (e.g. `{ getConfig(key) }`).
+     * @returns {Promise<{valid: boolean, errors: ConfigValidationIssue[]}>}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} If the document is not registered.
+     * @public
+     */
+    validate( configKey, value, context = {} ) {
+        const registration = this.#registrations.get( configKey );
+        if ( !registration ) {
+            return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "unknown-config", configKey: configKey } ) );
+        }
+
+        const errors = [];
+        const validateSchema = this.#schemaValidator( registration );
+        if ( !validateSchema( value ) ) {
+            for ( const error of ( validateSchema.errors || [] ) ) {
+                errors.push( { path: error.dataPath || instancePathToDataPath( error.instancePath ), message: error.message || "schema violation", code: "schema", params: error.params } );
+            }
+        }
+
+        return Promise.all( registration.validators.map( ( validator ) => {
+            return Promise.resolve( validator( value, context ) ).then( ( issues ) => ( Array.isArray( issues ) ? issues : [] ) );
+        } ) ).then( ( results ) => {
+            for ( const issues of results ) {
+                for ( const issue of issues ) {
+                    errors.push( this.#normalizeIssue( issue ) );
+                }
+            }
+            return { valid: errors.length === 0, errors: errors };
+        } );
+    }
+
+    /* Private interface */
+
+    /**
+     * @method
+     * @param {Object} registration
+     * @returns {Function} The compiled (and cached) ajv validate function for the document's schema.
+     * @private
+     */
+    #schemaValidator( registration ) {
+        if ( !registration.compiled ) {
+            registration.compiled = registration.schema.$id
+                ? this.#ajv.getSchema( registration.schema.$id )
+                : this.#ajv.compile( registration.schema );
+        }
+        return registration.compiled;
+    }
+
+    /**
+     * @method
+     * @param {Object} schema
+     * @returns {Object} A shallow copy without the ajv-6-incompatible Draft-2020-12 `$schema` annotation.
+     * @private
+     */
+    #stripUnsupportedMeta( schema ) {
+        if ( schema && schema.$schema && String( schema.$schema ).includes( "draft/2020-12" ) ) {
+            const clone = { ...schema };
+            delete clone.$schema;
+            return clone;
+        }
+        return schema;
+    }
+
+    /**
+     * @method
+     * @param {ConfigValidationIssue|string} issue
+     * @returns {ConfigValidationIssue}
+     * @private
+     */
+    #normalizeIssue( issue ) {
+        if ( typeof issue === "string" ) {
+            return { path: "", message: issue, code: "semantic" };
+        }
+        return { path: issue.path || "", message: issue.message || "validation failed", code: issue.code || "semantic", params: issue.params };
+    }
+
+}
+
+const instance = new ConfigRegistry();
+module.exports = ConfigRegistry;
+module.exports.instance = instance;

package/components/config-service.js

@@ -0,0 +1,349 @@
+/*
+ * 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/>.
+*/
+
+const exceptions = require( "@ti-engine/core/exceptions" );
+
+/**
+ * Orchestrates validated, versioned configuration edits on top of {@link ConfigStore} and {@link ConfigRegistry}.
+ *
+ * Two layers:
+ *  - **Document level** — {@link ConfigService#applyEdits}: validate every affected document (schema + semantic,
+ *    with a cross-document context that sees the *pending* values of the same edit) and, only if all pass, commit
+ *    them as one change-set. Validation failures return `{ ok:false, errors }` and write nothing; a version
+ *    conflict from the store surfaces as a rejection.
+ *  - **Entity level** — composite editors registered with `compose(docs)→view` / `decompose(edited, docs)→{key:value}`,
+ *    so the UI edits a domain entity (e.g. a "competency") that is projected from, and scattered back into, several
+ *    documents. {@link ConfigService#saveEditorEdit} decomposes the edit and routes it through `applyEdits`.
+ *
+ * @class ConfigService
+ * @public
+ */
+class ConfigService {
+
+    #store;
+    #registry;
+    #notifier;
+    #editors = new Map();
+
+    /**
+     * @constructor
+     * @param {Object} [options]
+     * @param {ConfigStore} [options.store] Defaults to the ConfigStore singleton.
+     * @param {ConfigRegistry} [options.registry] Defaults to the ConfigRegistry singleton.
+     * @param {ConfigChangeNotifier} [options.notifier] Defaults to the ConfigChangeNotifier singleton.
+     */
+    constructor( options = {} ) {
+        this.#store = options.store || require( "#config-store" ).instance;
+        this.#registry = options.registry || require( "#config-registry" ).instance;
+        this.#notifier = options.notifier || require( "#config-change-notifier" ).instance;
+    }
+
+    /* Public interface — document level */
+
+    /**
+     * Validates and commits a set of document edits atomically. Each edit: `{ configKey, value, expectedVersion }`.
+     *
+     * @method
+     * @param {Array<{configKey: string, value: Object, expectedVersion: number}>} edits
+     * @param {Object} meta
+     * @param {string} meta.adminID
+     * @param {string} [meta.note]
+     * @returns {Promise<{ok: true, changeSetID: string, versions: Object<string, number>} | {ok: false, errors: Object<string, Array>}>}
+     * @public
+     */
+    applyEdits( edits, meta ) {
+        if ( !Array.isArray( edits ) || edits.length === 0 || !meta || !meta.adminID ) {
+            return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "invalid-apply-input" } ) );
+        }
+
+        // Cross-document validation context: a document being edited is seen at its *pending* value; others are read
+        // from the store. This lets a validator on one document check against the post-edit state of its siblings.
+        const pending = {};
+        for ( const edit of edits ) {
+            pending[ edit.configKey ] = edit.value;
+        }
+        const context = {
+            getConfig: ( key ) => {
+                if ( Object.prototype.hasOwnProperty.call( pending, key ) ) {
+                    return Promise.resolve( clone( pending[ key ] ) );
+                }
+                return this.#store.getCurrent( key ).then( ( current ) => ( current ? current.value : null ) );
+            }
+        };
+
+        return Promise.all( edits.map( ( edit ) => {
+            return this.#registry.validate( edit.configKey, edit.value, context ).then( ( result ) => ( { configKey: edit.configKey, valid: result.valid, errors: result.errors } ) );
+        } ) ).then( ( results ) => {
+            const errorsByKey = {};
+            for ( const result of results ) {
+                if ( !result.valid ) {
+                    errorsByKey[ result.configKey ] = result.errors;
+                }
+            }
+            if ( Object.keys( errorsByKey ).length > 0 ) {
+                return { ok: false, errors: errorsByKey };
+            }
+            return this.#store.saveChangeSet( edits, meta ).then( ( saved ) => {
+                this.#notifier.publish( { changeSetID: saved.changeSetID, configKeys: Object.keys( saved.versions ), adminID: meta.adminID, timestamp: new Date().toISOString() } );
+                return { ok: true, changeSetID: saved.changeSetID, versions: saved.versions };
+            } );
+        } );
+    }
+
+    /* Public interface — entity level (composite editors) */
+
+    /**
+     * Registers a composite editor over one or more documents.
+     *
+     * @method
+     * @param {string} editorKey
+     * @param {Object} definition
+     * @param {string[]} definition.documents The configKeys this editor spans.
+     * @param {function(Object): *} definition.compose Maps `{ [configKey]: value }` → a view for the UI.
+     * @param {function(*, Object): Object<string, Object>} definition.decompose Maps `(editedView, currentDocs)` → the
+     *        full new values for the documents that changed (`{ [configKey]: newValue }`).
+     * @param {Object} [definition.metadata]
+     * @returns {ConfigService} this (chainable)
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS}
+     * @public
+     */
+    registerEditor( editorKey, definition ) {
+        const { documents, compose, decompose, metadata = {} } = definition || {};
+        if ( !editorKey || !Array.isArray( documents ) || documents.length === 0 || typeof compose !== "function" || typeof decompose !== "function" ) {
+            throw exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "invalid-editor-registration", editorKey: editorKey } );
+        }
+        this.#editors.set( editorKey, { documents: documents.slice(), compose: compose, decompose: decompose, metadata: metadata || {} } );
+        return this;
+    }
+
+    /**
+     * @method
+     * @param {string} editorKey
+     * @returns {boolean}
+     * @public
+     */
+    hasEditor( editorKey ) {
+        return this.#editors.has( editorKey );
+    }
+
+    /**
+     * @method
+     * @returns {string[]}
+     * @public
+     */
+    listEditors() {
+        return Array.from( this.#editors.keys() );
+    }
+
+    /**
+     * Loads the editor's documents and composes them into a view. Returns the view plus the current per-document
+     * versions, which the client must echo back on save for optimistic locking.
+     *
+     * @method
+     * @param {string} editorKey
+     * @returns {Promise<{rows: *, versions: Object<string, number>}>}
+     * @public
+     */
+    composeView( editorKey ) {
+        const editor = this.#editors.get( editorKey );
+        if ( !editor ) {
+            return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "unknown-editor", editorKey: editorKey } ) );
+        }
+        return this.#loadDocuments( editor.documents ).then( ( { docs, versions } ) => ( { rows: editor.compose( clone( docs ) ), versions: versions } ) );
+    }
+
+    /**
+     * Applies an edit made against a composite editor: decompose the edited view into per-document new values, then
+     * route through {@link ConfigService#applyEdits} (validate-all → atomic change-set). `expectedVersions` should be
+     * the versions returned by {@link ConfigService#composeView} when the edit started.
+     *
+     * @method
+     * @param {string} editorKey
+     * @param {*} editedView
+     * @param {Object} meta
+     * @param {Object<string, number>} [expectedVersions]
+     * @returns {Promise<Object>} The {@link ConfigService#applyEdits} result (or `{ ok:true, changeSetID:null }` if nothing changed).
+     * @public
+     */
+    saveEditorEdit( editorKey, editedView, meta, expectedVersions = {} ) {
+        const editor = this.#editors.get( editorKey );
+        if ( !editor ) {
+            return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "unknown-editor", editorKey: editorKey } ) );
+        }
+        return this.#loadDocuments( editor.documents ).then( ( { docs, versions } ) => {
+            const newValues = editor.decompose( editedView, clone( docs ) ) || {};
+            const edits = Object.keys( newValues ).map( ( key ) => ( {
+                configKey: key,
+                value: newValues[ key ],
+                expectedVersion: ( expectedVersions && expectedVersions[ key ] != null ) ? expectedVersions[ key ] : versions[ key ]
+            } ) );
+            if ( edits.length === 0 ) {
+                return { ok: true, changeSetID: null, versions: {} };
+            }
+            return this.applyEdits( edits, meta );
+        } );
+    }
+
+    /* Public interface — audit, history, and restore */
+
+    /**
+     * Restores a prior change-set through the validated path: rebuild edits from the change-set's historic snapshots
+     * and route them through {@link ConfigService#applyEdits} — so the restore is **re-validated against the current
+     * schemas/validators** (a snapshot valid when written may be invalid now) and emits `config:changed`. Returns the
+     * `applyEdits` result (`{ ok:false, errors }` if a snapshot no longer validates; nothing is written then).
+     *
+     * @method
+     * @param {string} changeSetID
+     * @param {Object} meta
+     * @param {string} meta.adminID
+     * @param {string} [meta.note]
+     * @returns {Promise<Object>}
+     * @public
+     */
+    restoreChangeSet( changeSetID, meta ) {
+        if ( !meta || !meta.adminID ) {
+            return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "invalid-restore-input" } ) );
+        }
+        return this.#store.getChangeSet( changeSetID ).then( ( record ) => {
+            if ( !record ) {
+                throw exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "unknown-changeset", changeSetID: changeSetID } );
+            }
+            return Promise.all( record.documents.map( ( doc ) => {
+                return Promise.all( [ this.#store.getVersion( doc.configKey, doc.version ), this.#store.getCurrent( doc.configKey ) ] ).then( ( [ historic, current ] ) => ( {
+                    configKey: doc.configKey,
+                    value: historic ? historic.snapshot : null,
+                    expectedVersion: current ? current.version : 0
+                } ) );
+            } ) ).then( ( edits ) => this.applyEdits( edits, { adminID: meta.adminID, note: meta.note || ( "restored from change-set " + changeSetID ) } ) );
+        } );
+    }
+
+    /**
+     * @method
+     * @param {string} configKey
+     * @returns {Promise<Object|null>} The current envelope for a configuration document.
+     * @public
+     */
+    getCurrent( configKey ) {
+        return this.#store.getCurrent( configKey );
+    }
+
+    /**
+     * @method
+     * @param {string} configKey
+     * @returns {Promise<Array<Object>>} The document's version history (ascending), each a full snapshot entry.
+     * @public
+     */
+    getHistory( configKey ) {
+        return this.#store.listHistory( configKey );
+    }
+
+    /**
+     * @method
+     * @param {string} changeSetID
+     * @returns {Promise<Object|null>} A single change-set record.
+     * @public
+     */
+    getChange( changeSetID ) {
+        return this.#store.getChangeSet( changeSetID );
+    }
+
+    /**
+     * @method
+     * @returns {Promise<Array<Object>>} The cross-document audit feed (change-sets, most-recent first).
+     * @public
+     */
+    listChanges() {
+        return this.#store.listChangeSets();
+    }
+
+    /**
+     * Builds a downloadable snapshot of the current live configuration — for every registered document, its repo file
+     * `path` (from registration metadata, if provided), current `version`, and `value`. This is the one-way export
+     * *out* of the store; an admin downloads it and commits the files to git. The store remains the live truth.
+     *
+     * @method
+     * @param {Object} [meta]
+     * @param {string} [meta.adminID]
+     * @returns {Promise<{exportedAt: string, exportedBy: (string|null), documents: Array<{configKey: string, path: (string|null), version: number, value: Object}>}>}
+     * @public
+     */
+    exportBundle( meta = {} ) {
+        const keys = this.#registry.list();
+        return Promise.all( keys.map( ( configKey ) => {
+            return this.#store.getCurrent( configKey ).then( ( current ) => {
+                const metadata = this.#registry.metadataFor( configKey ) || {};
+                return {
+                    configKey: configKey,
+                    path: metadata.path || null,
+                    version: current ? current.version : 0,
+                    value: current ? current.value : null
+                };
+            } );
+        } ) ).then( ( documents ) => ( {
+            exportedAt: new Date().toISOString(),
+            exportedBy: meta.adminID || null,
+            documents: documents
+        } ) );
+    }
+
+    /**
+     * 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.
+     *
+     * @method
+     * @param {string} configKey
+     * @param {Object} defaultValue
+     * @returns {Promise<Object>} The current envelope.
+     * @public
+     */
+    seedDefault( configKey, defaultValue ) {
+        return this.#store.seedIfEmpty( configKey, defaultValue );
+    }
+
+    /**
+     * Subscribes a listener to `config:changed` events (delegates to the change notifier). Returns an unsubscribe fn.
+     *
+     * @method
+     * @param {function(Object): void} listener
+     * @returns {function(): void}
+     * @public
+     */
+    onConfigChanged( listener ) {
+        return this.#notifier.subscribe( listener );
+    }
+
+    /* Private interface */
+
+    /**
+     * @method
+     * @param {string[]} keys
+     * @returns {Promise<{docs: Object<string, Object>, versions: Object<string, number>}>}
+     * @private
+     */
+    #loadDocuments( keys ) {
+        return Promise.all( keys.map( ( key ) => this.#store.getCurrent( key ) ) ).then( ( currents ) => {
+            const docs = {};
+            const versions = {};
+            keys.forEach( ( key, index ) => {
+                docs[ key ] = currents[ index ] ? currents[ index ].value : null;
+                versions[ key ] = currents[ index ] ? currents[ index ].version : 0;
+            } );
+            return { docs: docs, versions: versions };
+        } );
+    }
+
+}
+
+function clone( value ) {
+    return value === undefined || value === null ? value : JSON.parse( JSON.stringify( value ) );
+}
+
+const instance = new ConfigService();
+module.exports = ConfigService;
+module.exports.instance = instance;