@f5-sales-demo/pi-resource-management 23.9.5 → 23.10.3

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/pi-resource-management",
-	"version": "23.9.5",
+	"version": "23.10.3",
 	"description": "Shared resource management for F5 XC manifest parsing, validation, diff, and CRUD operations",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Robin Mordasiewicz",

package/src/catalog-kind-resolver.ts

@@ -0,0 +1,74 @@
+import { createKindResolver } from "./kind-resolver";
+import { type MapConstraints, validateMapConstraints } from "./map-constraints";
+import type { ApiSpecIndex, ApiSpecValidationResourceEntry, KindResolver, ValidationError } from "./types";
+
+export interface ValidationCatalogCategory {
+	readonly operations: readonly {
+		readonly method: string;
+		readonly path: string;
+		readonly fieldMetadata?: Readonly<Record<string, { readonly constraints?: Record<string, unknown> }>>;
+	}[];
+}
+
+export function createCatalogKindResolver(
+	index: ApiSpecIndex,
+	validation: Readonly<Record<string, ApiSpecValidationResourceEntry>>,
+	catalog: Readonly<Record<string, ValidationCatalogCategory>>,
+): KindResolver {
+	const baseResolver = createKindResolver(index, validation);
+	const normalizePath = (path: string) =>
+		path.replace(/\{metadata\.namespace\}/g, "{namespace}").replace(/\{metadata\.name\}/g, "{name}");
+
+	function valuesAtPath(object: unknown, path: string): unknown[] {
+		if (!path) return [object];
+		const [part, ...remaining] = path.split(".");
+		const name = part!.replace(/(?:\[\]|\{\})$/, "");
+		if (!object || typeof object !== "object") return [];
+		const child = (object as Record<string, unknown>)[name];
+		if (child === undefined || child === null) return [];
+		const rest = remaining.join(".");
+		if (part!.endsWith("[]")) return Array.isArray(child) ? child.flatMap(item => valuesAtPath(item, rest)) : [];
+		if (part!.endsWith("{}"))
+			return typeof child === "object" ? Object.values(child).flatMap(item => valuesAtPath(item, rest)) : [];
+		return valuesAtPath(child, rest);
+	}
+
+	return {
+		...baseResolver,
+		resolveKind(kind: string) {
+			const resolved = baseResolver.resolveKind(kind);
+			return {
+				...resolved,
+				validateFields(object: Record<string, unknown>, operation: "create" | "update"): ValidationError[] {
+					const method = operation === "update" ? "put" : "post";
+					const errors: ValidationError[] = [];
+					const seen = new Set<string>();
+					for (const category of Object.values(catalog)) {
+						for (const entry of category.operations) {
+							if (
+								entry.method.toLowerCase() !== method ||
+								normalizePath(entry.path) !== resolved.paths[operation]
+							)
+								continue;
+							for (const [field, metadata] of Object.entries(entry.fieldMetadata ?? {})) {
+								if (metadata.constraints?.constraintType !== "map") continue;
+								const fingerprint = `${field}:${JSON.stringify(metadata.constraints)}`;
+								if (seen.has(fingerprint)) continue;
+								seen.add(fingerprint);
+								for (const value of valuesAtPath(object, field)) {
+									for (const message of validateMapConstraints(
+										value,
+										metadata.constraints as unknown as MapConstraints,
+									)) {
+										errors.push({ path: field, message, code: "INVALID_MAP" });
+									}
+								}
+							}
+						}
+					}
+					return errors;
+				},
+			};
+		},
+	};
+}

package/src/defaults-metadata.generated.ts

@@ -1,6 +1,6 @@
 // AUTO-GENERATED by scripts/generate-defaults.ts — DO NOT EDIT BY HAND.
 // Per-kind defaults knowledge for minimum-settings export. Regenerate with: bun run generate-defaults
-// Source: https://github.com/f5-sales-demo/api-specs-enriched/releases/download/v12.1.4/minimal-export-defaults.json (api-specs-enriched 12.1.4)
+// Source: https://github.com/f5-sales-demo/api-specs-enriched/releases/download/v12.5.1/minimal-export-defaults.json (api-specs-enriched 12.5.1)
 import type { KindDefaultsMetadata } from "./defaults-metadata";
 
 export const DEFAULTS_METADATA: Record<string, KindDefaultsMetadata> = {
@@ -1577,10 +1577,8 @@ export const DEFAULTS_METADATA: Record<string, KindDefaultsMetadata> = {
 		},
 	},
 	malicious_user_mitigation: {
-		serverDefaultFields: ["spec.mitigation_type"],
-		fieldDefaults: {
-			"spec.mitigation_type": null,
-		},
+		serverDefaultFields: [],
+		fieldDefaults: {},
 		minimumConfigFields: ["spec.mitigation_type.rules"],
 		fieldConflicts: {},
 	},
@@ -2059,10 +2057,8 @@ export const DEFAULTS_METADATA: Record<string, KindDefaultsMetadata> = {
 		fieldConflicts: {},
 	},
 	service_policy: {
-		serverDefaultFields: ["spec.port_matcher"],
-		fieldDefaults: {
-			"spec.port_matcher": null,
-		},
+		serverDefaultFields: [],
+		fieldDefaults: {},
 		minimumConfigFields: [
 			"spec.action",
 			"spec.api_group_matcher.match",
@@ -2131,10 +2127,8 @@ export const DEFAULTS_METADATA: Record<string, KindDefaultsMetadata> = {
 		},
 	},
 	service_policy_views: {
-		serverDefaultFields: ["spec.port_matcher"],
-		fieldDefaults: {
-			"spec.port_matcher": null,
-		},
+		serverDefaultFields: [],
+		fieldDefaults: {},
 		minimumConfigFields: [
 			"spec.action",
 			"spec.api_group_matcher.match",

package/src/immutable-selection.ts

@@ -0,0 +1,189 @@
+export interface OpenAPISpec {
+	readonly info: { readonly title: string; readonly version: string; readonly [key: string]: unknown };
+	readonly paths: Record<
+		string,
+		Record<string, { readonly requestBody?: Record<string, unknown>; readonly [key: string]: unknown }>
+	>;
+	readonly components?: {
+		readonly schemas?: Record<string, Record<string, unknown>>;
+		readonly [key: string]: unknown;
+	};
+	readonly [key: string]: unknown;
+}
+
+type ObjectValue = Record<string, unknown>;
+export interface ImmutableGroup {
+	path: string[];
+	name: string;
+	members: string[];
+}
+export function objectValue(value: unknown): ObjectValue {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Expected a JSON object");
+	return value as ObjectValue;
+}
+export function resolveSchema(schema: ObjectValue, spec: OpenAPISpec, seen = new Set<string>()): ObjectValue {
+	const ref = schema.$ref;
+	let result = { ...schema };
+	if (typeof ref === "string") {
+		if (!ref.startsWith("#/components/schemas/") || seen.has(ref)) return {};
+		const target = spec.components?.schemas?.[ref.slice("#/components/schemas/".length)];
+		if (!target) throw new Error(`Missing schema ${ref}`);
+		result = { ...resolveSchema(target, spec, new Set([...seen, ref])), ...schema };
+	}
+	for (const child of (schema.allOf as ObjectValue[] | undefined) ?? []) {
+		const resolved = resolveSchema(child, spec, seen);
+		result = {
+			...result,
+			...resolved,
+			properties: { ...(result.properties as ObjectValue), ...(resolved.properties as ObjectValue) },
+			required: [...new Set([...((result.required as string[]) ?? []), ...((resolved.required as string[]) ?? [])])],
+		};
+	}
+	return result;
+}
+export function immutableGroups(
+	schema: ObjectValue,
+	spec: OpenAPISpec,
+	path: string[] = [],
+	seen = new Set<string>(),
+): ImmutableGroup[] {
+	if (typeof schema.$ref === "string" && seen.has(schema.$ref)) return [];
+	const next = new Set(seen);
+	if (typeof schema.$ref === "string") next.add(schema.$ref);
+	const resolved = resolveSchema(schema, spec);
+	const groups: ImmutableGroup[] = [];
+	for (const [name, members] of Object.entries((resolved["x-f5xc-immutable-oneof-groups"] as ObjectValue) ?? {})) {
+		if (!Array.isArray(members) || members.length < 2 || !members.every(m => typeof m === "string"))
+			throw new Error(`Invalid immutable group ${name}`);
+		groups.push({ path, name, members });
+	}
+	for (const [name, child] of Object.entries((resolved.properties as ObjectValue) ?? {}))
+		groups.push(...immutableGroups(objectValue(child), spec, [...path, name], next));
+	return groups;
+}
+export function valueAt(value: ObjectValue, path: string[]): ObjectValue {
+	let result = value;
+	for (const key of path) result = objectValue(result[key]);
+	return result;
+}
+export function selectedMember(value: ObjectValue, group: ImmutableGroup): string {
+	const owner = valueAt(value, group.path);
+	const selected = group.members.filter(member => owner[member] !== undefined && owner[member] !== null);
+	if (selected.length !== 1)
+		throw new Error(`${[...group.path, group.name].join(".")} requires exactly one of ${group.members.join(", ")}`);
+	objectValue(owner[selected[0]!]);
+	return selected[0]!;
+}
+export function formatImmutableGroups(groups: ImmutableGroup[]): string {
+	return groups
+		.map(
+			g =>
+				`Immutable selection ${[...g.path, g.name].join(".")}: ${g.members.join(" | ")}. Changing the selected member requires DELETE then POST; child settings remain mutable.`,
+		)
+		.join("\n");
+}
+export function createBody(value: unknown, schema: ObjectValue, spec: OpenAPISpec): unknown {
+	const s = resolveSchema(schema, spec);
+	if (value === null || value === undefined || s.readOnly === true || s["x-field-mutability"] === "read-only")
+		return undefined;
+	if (Array.isArray(value)) return value.map(v => createBody(v, objectValue(s.items ?? {}), spec));
+	if (typeof value !== "object") return value;
+	const props = s.properties as ObjectValue | undefined;
+	const out: ObjectValue = {};
+	const input = { ...(value as ObjectValue) };
+	if (
+		props?.response_body_encoded &&
+		typeof input.response_body === "string" &&
+		input.response_body &&
+		!input.response_body_encoded
+	)
+		input.response_body_encoded = `string:///${Buffer.from(input.response_body).toString("base64")}`;
+	for (const [key, child] of Object.entries(input)) {
+		if (props && !(key in props)) continue;
+		const childSchema = props?.[key] ?? (typeof s.additionalProperties === "object" ? s.additionalProperties : {});
+		const projected = createBody(child, objectValue(childSchema), spec);
+		if (projected !== undefined) out[key] = projected;
+	}
+	return out;
+}
+export function validateBody(value: unknown, schema: ObjectValue, spec: OpenAPISpec, path = "body"): string[] {
+	const s = resolveSchema(schema, spec);
+	const errors: string[] = [];
+	if (value === undefined || value === null) return errors;
+	const type = Array.isArray(value) ? "array" : typeof value;
+	if (
+		typeof s.type === "string" &&
+		s.type !== type &&
+		!(s.type === "integer" && typeof value === "number" && Number.isInteger(value))
+	)
+		return [`${path}: expected ${s.type}`];
+	if (Array.isArray(s.enum) && !s.enum.includes(value)) errors.push(`${path}: invalid enum value`);
+	if (typeof value === "number") {
+		if (typeof s.minimum === "number" && value < s.minimum) errors.push(`${path}: below minimum`);
+		if (typeof s.maximum === "number" && value > s.maximum) errors.push(`${path}: above maximum`);
+	}
+	if (typeof value === "string") {
+		if (typeof s.minLength === "number" && value.length < s.minLength) errors.push(`${path}: too short`);
+		if (typeof s.maxLength === "number" && value.length > s.maxLength) errors.push(`${path}: too long`);
+		if (typeof s.pattern === "string" && !new RegExp(s.pattern).test(value)) errors.push(`${path}: pattern mismatch`);
+	}
+	if (Array.isArray(value)) {
+		if (typeof s.minItems === "number" && value.length < s.minItems) errors.push(`${path}: too few items`);
+		if (typeof s.maxItems === "number" && value.length > s.maxItems) errors.push(`${path}: too many items`);
+		value.forEach((v, i) => {
+			errors.push(...validateBody(v, objectValue(s.items ?? {}), spec, `${path}[${i}]`));
+		});
+	} else if (typeof value === "object") {
+		const o = objectValue(value);
+		for (const key of (s.required as string[] | undefined) ?? [])
+			if (o[key] === undefined || o[key] === null) errors.push(`${path}.${key}: required`);
+		for (const [key, child] of Object.entries(o)) {
+			const p = (s.properties as ObjectValue)?.[key];
+			if (p) errors.push(...validateBody(child, objectValue(p), spec, `${path}.${key}`));
+		}
+		for (const [key, members] of Object.entries(s))
+			if (key.startsWith("x-ves-oneof-field-")) {
+				const choices = typeof members === "string" ? JSON.parse(members) : members;
+				if (Array.isArray(choices) && choices.filter(k => o[k] !== undefined && o[k] !== null).length > 1)
+					errors.push(`${path}.${key}: mutually exclusive members`);
+			}
+	}
+	return errors;
+}
+export interface MutationContract {
+	spec: OpenAPISpec;
+	schema: ObjectValue;
+	createSchema: ObjectValue;
+	groups: ImmutableGroup[];
+	collection: string;
+}
+export function mutationContract(
+	data: Readonly<Record<string, unknown>>,
+	method: string,
+	path: string,
+): MutationContract | undefined {
+	for (const raw of Object.values(data)) {
+		const spec = raw as OpenAPISpec;
+		for (const [template, operations] of Object.entries(spec.paths)) {
+			const parts = template.split("/");
+			const actual = path.split("/");
+			if (parts.length !== actual.length || !parts.every((p, i) => /^\{[^}]+\}$/.test(p) || p === actual[i]))
+				continue;
+			const op = operations[method.toLowerCase()];
+			if (!op?.requestBody) continue;
+			const schema = ((op.requestBody.content as ObjectValue)?.["application/json"] as ObjectValue)
+				?.schema as ObjectValue;
+			if (!schema) continue;
+			const groups = immutableGroups(schema, spec);
+			if (!groups.length) continue;
+			const collection = path.slice(0, path.lastIndexOf("/"));
+			const createTemplate = template.slice(0, template.lastIndexOf("/"));
+			const create = (
+				(spec.paths[createTemplate]?.post?.requestBody?.content as ObjectValue)?.["application/json"] as ObjectValue
+			)?.schema as ObjectValue;
+			if (!create) throw new Error("Immutable mutation has no create schema");
+			return { spec, schema, createSchema: create, groups, collection };
+		}
+	}
+	return undefined;
+}

package/src/index.ts

@@ -1,9 +1,11 @@
 export { parseExportArgs, parseResourceArgs } from "./arg-parser";
+export { createCatalogKindResolver, type ValidationCatalogCategory } from "./catalog-kind-resolver";
 export type { KindDefaultsMetadata } from "./defaults-metadata";
 export { buildFilterFromMetadata, buildMinimalExportFilter } from "./defaults-metadata";
 export { DEFAULTS_METADATA } from "./defaults-metadata.generated";
 export { computeResourceDiff, formatDiff } from "./diff-engine";
 export { ManifestFileError, readManifestFiles } from "./file-reader";
+export * from "./immutable-selection";
 export { createKindResolver, KindResolutionError } from "./kind-resolver";
 export type { ExportedManifest, ManifestOutputFormat, MinimalExportFilter } from "./manifest-export";
 export { applyMinimalExportFilter, formatManifestOutput, toManifest, toManifestList } from "./manifest-export";
@@ -18,7 +20,7 @@ export {
 	formatResourceDetail,
 	formatResourceList,
 } from "./output-formatter";
-export { FetchTransport, ResourceClient } from "./resource-client";
+export { computeManifestDiff, FetchTransport, ResourceClient } from "./resource-client";
 export type {
 	ApiSpecDomainEntry,
 	ApiSpecDomainResource,

package/src/resource-client.ts

@@ -133,7 +133,7 @@ export class ResourceClient {
 
 		if (existing.error) return { status: "error", error: existing.error };
 
-		const diff = this.#computeManifestDiff(existing.body!, manifest);
+		const diff = computeManifestDiff(existing.body!, manifest);
 
 		if (!diff.hasDifferences) {
 			return { status: "unchanged", resource: existing.body! };
@@ -170,7 +170,7 @@ export class ResourceClient {
 
 		if (existing.error) return { status: "error", error: existing.error };
 
-		const diff = this.#computeManifestDiff(existing.body!, manifest);
+		const diff = computeManifestDiff(existing.body!, manifest);
 		if (!diff.hasDifferences) return { status: "unchanged", resource: existing.body! };
 		if (dryRun) return { status: "dry-run", action: "update", diff };
 		return this.#updateResource(manifest, resolved, namespace, diff, startMs);
@@ -281,29 +281,17 @@ export class ResourceClient {
 		}
 		if (existing.error) return { isNew: false, error: existing.error };
 
-		const diff = this.#computeManifestDiff(existing.body!, manifest);
+		const diff = computeManifestDiff(existing.body!, manifest);
 		return { diff, isNew: false };
 	}
 
-	#computeManifestDiff(serverResource: Record<string, unknown>, manifest: ResourceManifest): ResourceDiff {
-		const currentSpec = (serverResource.spec ?? {}) as Record<string, unknown>;
-		const filteredSpec = filterToManifestKeys(currentSpec, manifest.spec) as Record<string, unknown>;
-		const specDiff = computeResourceDiff(filteredSpec, manifest.spec);
-
-		const currentMeta = (serverResource.metadata ?? {}) as Record<string, unknown>;
-		const desiredMeta = manifest.rawObject.metadata as Record<string, unknown>;
-		const metaDiff = computeResourceDiff(
-			filterToManifestKeys(currentMeta, desiredMeta) as Record<string, unknown>,
-			desiredMeta,
-		);
-
-		return {
-			hasDifferences: specDiff.hasDifferences || metaDiff.hasDifferences,
-			added: [...specDiff.added, ...metaDiff.added],
-			removed: [...specDiff.removed, ...metaDiff.removed],
-			changed: [...specDiff.changed, ...metaDiff.changed],
-			unchangedCount: specDiff.unchangedCount + metaDiff.unchangedCount,
-		};
+	async inspectForMutation(
+		resolved: ResolvedKind,
+		name: string,
+		namespaceOverride?: string,
+	): Promise<{ status: number; body?: Record<string, unknown>; error?: ResourceError }> {
+		const namespace = namespaceOverride ?? this.#defaultNamespace;
+		return this.#fetchComparisonResource(this.#buildUrl(resolved.paths.get, namespace, name), resolved);
 	}
 
 	#resolveNamespace(manifest: ResourceManifest, override?: string): string {
@@ -473,3 +461,24 @@ function filterToManifestKeys(serverVal: unknown, manifestVal: unknown): unknown
 	}
 	return filtered;
 }
+
+export function computeManifestDiff(serverResource: Record<string, unknown>, manifest: ResourceManifest): ResourceDiff {
+	const currentSpec = (serverResource.spec ?? {}) as Record<string, unknown>;
+	const filteredSpec = filterToManifestKeys(currentSpec, manifest.spec) as Record<string, unknown>;
+	const specDiff = computeResourceDiff(filteredSpec, manifest.spec);
+
+	const currentMeta = (serverResource.metadata ?? {}) as Record<string, unknown>;
+	const desiredMeta = manifest.rawObject.metadata as Record<string, unknown>;
+	const metaDiff = computeResourceDiff(
+		filterToManifestKeys(currentMeta, desiredMeta) as Record<string, unknown>,
+		desiredMeta,
+	);
+
+	return {
+		hasDifferences: specDiff.hasDifferences || metaDiff.hasDifferences,
+		added: [...specDiff.added, ...metaDiff.added],
+		removed: [...specDiff.removed, ...metaDiff.removed],
+		changed: [...specDiff.changed, ...metaDiff.changed],
+		unchangedCount: specDiff.unchangedCount + metaDiff.unchangedCount,
+	};
+}