src/app/core/config/config-validation/config-validation.service.ts
A problem in the config that the app can work around at runtime (e.g. by falling back to a default), but which an admin should fix.
Properties |
| configId |
configId:
|
Type : string
|
|
id of the config item, e.g. "entity:Child" |
| field |
field:
|
Type : string
|
| Optional |
|
the field of an entity type the problem is in, if any |
| message |
message:
|
Type : string
|
|
human-readable description of the problem, including a hint how to fix it |
import { inject, Injectable, Injector } from "@angular/core";
import { FaIconLibrary } from "@fortawesome/angular-fontawesome";
import { EntitySchemaService } from "../../entity/schema/entity-schema.service";
import { EntitySchemaField } from "../../entity/schema/entity-schema-field";
import { EntityConfig } from "../../entity/entity-config";
import { EntityRegistry } from "../../entity/database-entity.decorator";
import { Entity } from "../../entity/model/entity";
import { DefaultValueStrategy } from "../../default-values/default-value-strategy.interface";
import { DynamicValidatorsService } from "../../common-components/entity-form/dynamic-form-validators/dynamic-validators.service";
import { ConfigValidationContext } from "../../common-components/entity-form/dynamic-form-validators/field-validator";
import {
FormValidatorConfig,
WARNING_ONLY_KEY,
} from "../../common-components/entity-form/dynamic-form-validators/form-validator-config";
import { asArray } from "#src/app/utils/asArray";
import { resolveIconDefinition } from "../../common-components/fa-dynamic-icon/fa-icon-utils";
import { MenuItem } from "../../ui/navigation/menu-item";
import { EntityAbility } from "../../permissions/ability/entity-ability";
import { AlertService } from "../../alerts/alert.service";
import { Logging } from "../../logging/logging.service";
import { Config } from "../config";
import { resolveLocaleText } from "../../language/active-locale";
/**
* A problem in the config that the app can work around at runtime
* (e.g. by falling back to a default), but which an admin should fix.
*/
export interface ConfigProblem {
/** id of the config item, e.g. "entity:Child" */
configId: string;
/** the field of an entity type the problem is in, if any */
field?: string;
/** human-readable description of the problem, including a hint how to fix it */
message: string;
}
const ENTITY_CONFIG_PREFIX = "entity:";
const NAVIGATION_MENU_CONFIG_ID = "navigationMenu";
/**
* Checks the config for problems that would otherwise only show up at runtime
* (as a silently ignored setting), so that admins can be told about them when saving.
*
* Problems are not reported to remote monitoring: they are instance configuration,
* not bugs in our code (see "Error Handling & Remote Logging" in AGENTS.md).
*/
@Injectable({
providedIn: "root",
})
export class ConfigValidationService {
// resolved lazily: the checked services (e.g. datatypes, default value strategies) may depend on the ConfigService
private readonly injector = inject(Injector);
/**
* Tell the current user about problems in the given (just saved) config,
* if they are allowed to edit the config.
* Saving is not blocked: problems are only shown as a warning.
*/
warnAdminAboutProblems(config: Record<string, any>): void {
if (this.injector.get(EntityAbility).cannot("update", Config)) {
return;
}
const problems = this.validate(config);
if (problems.length === 0) {
return;
}
Logging.debug("Saved config has problems", problems);
const listed = problems.map((p) => `• ${formatProblem(p)}`);
this.injector
.get(AlertService)
.addWarning(
$localize`:config validation:The configuration has problems that should be fixed:` +
"\n" +
listed.join("\n"),
);
}
/**
* Check the given config data (the full config document's `data`).
* @returns the problems found, empty if the config is fine
*/
validate(config: Record<string, any> | undefined | null): ConfigProblem[] {
if (!config || typeof config !== "object") {
return [];
}
const problems: ConfigProblem[] = [];
for (const [configId, value] of Object.entries(config)) {
if (configId.startsWith(ENTITY_CONFIG_PREFIX)) {
problems.push(...this.validateEntityConfig(configId, value, config));
} else if (configId === NAVIGATION_MENU_CONFIG_ID) {
problems.push(...this.validateMenuItems(configId, value?.items));
}
}
return problems;
}
private validateEntityConfig(
configId: string,
entityConfig: EntityConfig,
config: Record<string, any>,
): ConfigProblem[] {
const problems: ConfigProblem[] = [];
if (entityConfig?.icon && !this.isKnownIcon(entityConfig.icon)) {
problems.push({
configId,
message: $localize`:config validation:Unknown icon "${entityConfig.icon}:icon:". A default icon is shown instead.`,
});
}
const context: ConfigValidationContext = {
entityType: configId.substring(ENTITY_CONFIG_PREFIX.length),
fieldsOf: (entityType) => this.getFields(entityType, config),
};
for (const [field, schema] of Object.entries(
entityConfig?.attributes ?? {},
)) {
problems.push(
...this.validateField(schema, config, context).map((message) => ({
configId,
field,
message,
})),
);
}
return problems;
}
/**
* The fields of a record type as the app sets them up from the config (see `EntityConfigService`):
* the fields of its code, each replaced by a field of the same id in the checked config.
* `undefined` for an unknown record type.
*/
private getFields(
entityType: string,
config: Record<string, any>,
): Map<string, EntitySchemaField> | undefined {
const registry = this.injector.get(EntityRegistry);
const entityConfig: EntityConfig | undefined =
config[ENTITY_CONFIG_PREFIX + entityType];
if (!registry.has(entityType) && !entityConfig) {
return undefined;
}
// the check runs before the saved config is applied: a type new in it starts from the type it extends
const codeType = registry.has(entityType)
? entityType
: entityConfig.extends;
const fields = new Map(
registry.has(codeType) ? registry.get(codeType).schema : Entity.schema,
);
for (const [id, field] of Object.entries(entityConfig?.attributes ?? {})) {
fields.set(id, field);
}
return fields;
}
private validateField(
schema: EntitySchemaField,
config: Record<string, any>,
context: ConfigValidationContext,
): string[] {
if (!schema || typeof schema !== "object") {
return [];
}
const problems: string[] = [];
if (schema.dataType && !this.isKnownDataType(schema.dataType)) {
// e.g. `dataType: "School"` where a link to "School" records was intended
const isEntityType =
this.injector.get(EntityRegistry).has(schema.dataType) ||
!!config[ENTITY_CONFIG_PREFIX + schema.dataType];
problems.push(
isEntityType
? $localize`:config validation:Unknown data type "${schema.dataType}:dataType:". To link to records of this type, use data type "entity" and select "${schema.dataType}:dataType:" as the linked record type.`
: $localize`:config validation:Unknown data type "${schema.dataType}:dataType:". The field is treated as plain text.`,
);
}
problems.push(...this.validateValidators(schema, context));
if (schema.defaultValue && !this.isKnownDefaultValueMode(schema)) {
problems.push(
schema.defaultValue.mode
? $localize`:config validation:The default value has no valid mode ("${schema.defaultValue.mode}:mode:"), so it is not applied.`
: $localize`:config validation:The default value has no mode, so it is not applied.`,
);
}
return problems;
}
private validateValidators(
schema: EntitySchemaField,
context: ConfigValidationContext,
): string[] {
const rules = this.injector.get(DynamicValidatorsService);
const datatype = this.injector
.get(EntitySchemaService)
.getDatatypeOrDefault(schema.dataType);
return Object.entries(schema.validators ?? {}).flatMap(([key, value]) => {
if (key === WARNING_ONLY_KEY) {
return this.validateWarningOnly(schema.validators, rules);
}
const rule = rules.rules.get(key);
if (!rule) {
return [
key === "regex"
? $localize`:config validation:Unknown validator "regex", it is ignored. Use "pattern" instead.`
: $localize`:config validation:Unknown validator "${key}:validator:", it is ignored.`,
];
}
const problems = rule.validateConfig(value, schema, datatype, context);
// without a dataType (e.g. overriding a field of the record type's code) the type is not known here
if (
problems.length === 0 &&
schema.dataType &&
!rule.isSwitchedOff(value) &&
!rule.appliesTo(datatype, schema)
) {
problems.push(
$localize`:config validation:The validator "${key}:validator:" does not fit the type of this field ("${schema.dataType}:dataType:"). It is removed once an admin edits the field's validation settings.`,
);
}
return problems;
});
}
/** `_warningOnly` lists validators of the field that can be only a warning */
private validateWarningOnly(
validators: FormValidatorConfig,
rules: DynamicValidatorsService,
): string[] {
return asArray(validators[WARNING_ONLY_KEY] ?? [])
.filter(
(key) =>
!(key in validators) || rules.rules.get(key)?.warning !== "optional",
)
.map(
(key) =>
$localize`:config validation:"${key}:validator:" is listed in "_warningOnly", but is not a validator of this field that can be only a warning. It is ignored there.`,
);
}
private validateMenuItems(
configId: string,
items: MenuItem[] | undefined,
): ConfigProblem[] {
if (!Array.isArray(items)) {
return [];
}
return items.flatMap((item) => [
...(item?.icon && !this.isKnownIcon(item.icon)
? [
{
configId,
message: $localize`:config validation:Unknown icon "${item.icon}:icon:" for menu item "${resolveLocaleText(item.label)}:label:". A default icon is shown instead.`,
},
]
: []),
...this.validateMenuItems(configId, item?.subMenu),
]);
}
private isKnownDataType(dataType: string): boolean {
try {
this.injector
.get(EntitySchemaService)
.getDatatypeOrDefault(dataType, false);
return true;
} catch {
return false;
}
}
private isKnownDefaultValueMode(schema: EntitySchemaField): boolean {
const strategies = this.injector.get(
DefaultValueStrategy,
) as unknown as DefaultValueStrategy[];
return strategies.some((s) => s.mode === schema.defaultValue?.mode);
}
private isKnownIcon(icon: string): boolean {
return !!resolveIconDefinition(icon, this.injector.get(FaIconLibrary));
}
}
function formatProblem(problem: ConfigProblem): string {
const location = problem.field
? `${problem.configId} → ${problem.field}`
: problem.configId;
return `${location}: ${problem.message}`;
}