@ti-engine/web-framework 1.25.1 → 1.26.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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.26.0
+
+* feat(config-management): report stored documents that no longer satisfy their registered schema.
+  `ConfigService.listSchemaViolations()` returns one entry per registered document whose **stored** value fails its
+  schema, and `ConfigRegistry.validateSchema( configKey, value )` exposes the schema half of validation on its own.
+  Nothing validated a stored value on the way out before this: the store hands back whatever it holds and a consumer
+  freezes it into its config exports, so a release that tightens a schema — adding a required top-level key, say —
+  leaves any deployment seeded before the change serving a document that can no longer be saved. The failure used to
+  surface much later, as an admin edit rejected for a key the admin never touched, in a screen unrelated to the
+  change. Schema-only by design: a semantic validator may need a `ValidatorContext` the caller has no reason to
+  build, and several are about an *edit* rather than the document standing alone. Read-only by design too —
+  reconciling a stale document is the drift panel's job, under audit; an automatic repair here would write config
+  outside the change-set machinery. A document that has never been stored is not a violation.
+* refactor(config-management): `ConfigRegistry.validate()` now delegates its schema step to `validateSchema()`, so
+  the two can never disagree about what is structurally admissible.
+
 ## Version 1.25.1
 
 * fix(ti-framework): resolve a label key whose own name contains a literal dot. `getLabel` split the key on every

package/components/config-registry.js

@@ -197,13 +197,7 @@ class ConfigRegistry {
             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 } );
-            }
-        }
+        const errors = this.validateSchema( configKey, value ).errors.slice();
 
         return Promise.all( registration.validators.map( ( validator ) => {
             return Promise.resolve( validator( value, context ) ).then( ( issues ) => ( Array.isArray( issues ) ? issues : [] ) );
@@ -217,6 +211,38 @@ class ConfigRegistry {
         } );
     }
 
+    /**
+     * Validates a value against a document's registered schema **only**, skipping the semantic validators.
+     * <br/>
+     * Separate from {@link ConfigRegistry#validate} because the two answer different questions. A semantic validator
+     * may need a {@link ValidatorContext} the caller has no reason to build, and several of them are about an edit
+     * (did the version move? does this removal orphan a reference?) rather than about the document standing alone.
+     * A caller that just wants to know whether a value is structurally admissible — a boot-time check on what the
+     * store already holds, say — needs this half and not the other.
+     *
+     * @method
+     * @param {string} configKey
+     * @param {Object} value
+     * @returns {{valid: boolean, errors: ConfigValidationIssue[]}}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} If the document is not registered.
+     * @public
+     */
+    validateSchema( configKey, value ) {
+        const registration = this.#registrations.get( configKey );
+        if ( !registration ) {
+            throw 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 { valid: errors.length === 0, errors: errors };
+    }
+
     /* Private interface */
 
     /**

package/components/config-service.js

@@ -21,6 +21,7 @@ const configDrift = require( "#config-drift" );
 /** @import ConfigChangeNotifier from "#config-change-notifier" */
 /** @import ConfigRegistry from "#config-registry" */
 /** @import ConfigStore from "#config-store" */
+/** @import { ConfigValidationIssue } from "#config-registry" */
 
 /**
  * Orchestrates validated, versioned configuration edits on top of {@link ConfigStore} and {@link ConfigRegistry}.
@@ -374,6 +375,37 @@ class ConfigService {
         } ) );
     }
 
+    /**
+     * Reports every registered document whose **stored** value no longer satisfies its registered schema.
+     * <br/>
+     * Nothing validates a stored value on the way out: the store hands back whatever it holds, and a consumer
+     * freezes it into its config exports. That is fine until a release tightens a schema — adds a required
+     * top-level key, say — at which point a deployment seeded before the change keeps serving a document that
+     * cannot be saved any more. The failure surfaces much later, as an admin edit rejected for a key the admin
+     * never touched, in a screen that has nothing to do with the change.
+     * <br/>
+     * This answers that question at a moment when it is cheap to act on. It is deliberately schema-only (see
+     * {@link ConfigRegistry#validateSchema}) and deliberately read-only: reconciling a stale document is what the
+     * drift panel is for, and an automatic repair here would write config outside the audited change-set machinery.
+     * A document that has never been stored is not a violation and is omitted.
+     *
+     * @method
+     * @returns {Promise<Array<{configKey: string, errors: ConfigValidationIssue[]}>>} Empty when every stored
+     *          document validates.
+     * @public
+     */
+    listSchemaViolations() {
+        return Promise.all( this.#registry.list().map( ( configKey ) => {
+            return this.#store.getCurrent( configKey ).then( ( current ) => {
+                if ( !current ) {
+                    return null;
+                }
+                const result = this.#registry.validateSchema( configKey, current.value );
+                return result.valid ? null : { configKey: configKey, errors: result.errors };
+            } );
+        } ) ).then( ( results ) => results.filter( Boolean ) );
+    }
+
     /**
      * Applies the registered file defaults for the given documents, as a single validated change-set.
      * <br/>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/web-framework",
-  "version": "1.25.1",
+  "version": "1.26.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",

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

@@ -142,6 +142,26 @@ declare class ConfigRegistry {
         valid: boolean;
         errors: ConfigValidationIssue[];
     }>;
+    /**
+     * Validates a value against a document's registered schema **only**, skipping the semantic validators.
+     * <br/>
+     * Separate from {@link ConfigRegistry#validate} because the two answer different questions. A semantic validator
+     * may need a {@link ValidatorContext} the caller has no reason to build, and several of them are about an edit
+     * (did the version move? does this removal orphan a reference?) rather than about the document standing alone.
+     * A caller that just wants to know whether a value is structurally admissible — a boot-time check on what the
+     * store already holds, say — needs this half and not the other.
+     *
+     * @method
+     * @param {string} configKey
+     * @param {Object} value
+     * @returns {{valid: boolean, errors: ConfigValidationIssue[]}}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} If the document is not registered.
+     * @public
+     */
+    validateSchema(configKey: string, value: Object): {
+        valid: boolean;
+        errors: ConfigValidationIssue[];
+    };
 }
 declare namespace ConfigRegistry {
     export { instance };

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

@@ -2,9 +2,11 @@ export = ConfigService;
 import type ConfigChangeNotifier from "#config-change-notifier";
 import type ConfigRegistry from "#config-registry";
 import type ConfigStore from "#config-store";
+import type { ConfigValidationIssue } from "#config-registry";
 /** @import ConfigChangeNotifier from "#config-change-notifier" */
 /** @import ConfigRegistry from "#config-registry" */
 /** @import ConfigStore from "#config-store" */
+/** @import { ConfigValidationIssue } from "#config-registry" */
 /**
  * Orchestrates validated, versioned configuration edits on top of {@link ConfigStore} and {@link ConfigRegistry}.
  *
@@ -223,6 +225,29 @@ declare class ConfigService {
      * @public
      */
     listDrift(): Promise<Array<Object>>;
+    /**
+     * Reports every registered document whose **stored** value no longer satisfies its registered schema.
+     * <br/>
+     * Nothing validates a stored value on the way out: the store hands back whatever it holds, and a consumer
+     * freezes it into its config exports. That is fine until a release tightens a schema — adds a required
+     * top-level key, say — at which point a deployment seeded before the change keeps serving a document that
+     * cannot be saved any more. The failure surfaces much later, as an admin edit rejected for a key the admin
+     * never touched, in a screen that has nothing to do with the change.
+     * <br/>
+     * This answers that question at a moment when it is cheap to act on. It is deliberately schema-only (see
+     * {@link ConfigRegistry#validateSchema}) and deliberately read-only: reconciling a stale document is what the
+     * drift panel is for, and an automatic repair here would write config outside the audited change-set machinery.
+     * A document that has never been stored is not a violation and is omitted.
+     *
+     * @method
+     * @returns {Promise<Array<{configKey: string, errors: ConfigValidationIssue[]}>>} Empty when every stored
+     *          document validates.
+     * @public
+     */
+    listSchemaViolations(): Promise<Array<{
+        configKey: string;
+        errors: ConfigValidationIssue[];
+    }>>;
     /**
      * Applies the registered file defaults for the given documents, as a single validated change-set.
      * <br/>