@xplane/core 1.0.1 → 1.2.0

package/dist/index.mjs

@@ -46,6 +46,30 @@ var Composition = class extends Construct$1 {
 	graph;
 	/** The edge collector accumulating dependency edges. */
 	collector;
+	/**
+	* When `true`, the runtime injects a structured `status.xplane` payload on
+	* the XR containing `emittedResources` and `blockedResources`. Defaults to
+	* `false` because writing this field requires the XRD's `openAPIV3Schema`
+	* to declare `status.xplane` (or `status` to allow unknown fields) — typed
+	* patches will otherwise be rejected by Crossplane.
+	*
+	* To enable, set in your composition's constructor:
+	*
+	* ```ts
+	* this.emitXplaneStatus = true;
+	* ```
+	*
+	* and add the following to your XRD's status schema:
+	*
+	* ```yaml
+	* status:
+	*   properties:
+	*     xplane:
+	*       type: object
+	*       x-kubernetes-preserve-unknown-fields: true
+	* ```
+	*/
+	emitXplaneStatus = false;
 	constructor() {
 		super(void 0, "Composition");
 		const ctx = getCompositionContext();
@@ -219,6 +243,114 @@ var DependencyGraph = class {
 	}
 };
 //#endregion
+//#region src/tracking/types.ts
+/**
+* A Pending marker stored in a desired document when a ReadProxy value
+* is assigned. Carries full source info so the resolve phase knows
+* where to look for the concrete value.
+*/
+const PENDING_TAG = Symbol.for("xplane.pending");
+var Pending = class {
+	source;
+	path;
+	static TAG = PENDING_TAG;
+	[PENDING_TAG] = true;
+	constructor(source, path) {
+		this.source = source;
+		this.path = path;
+	}
+	static is(value) {
+		return typeof value === "object" && value !== null && value[PENDING_TAG] === true;
+	}
+};
+/**
+* A Pending-like marker for strings produced by template literals that
+* interpolate one or more unresolved ReadProxy values.
+*
+* Holds the template structure so the resolve phase can reconstruct the
+* final string once all dependency slots are available.
+*
+* Invariant: parts.length === slots.length + 1
+*   result = parts[0] + resolved[0] + parts[1] + … + resolved[n-1] + parts[n]
+*/
+const PENDING_TEMPLATE_TAG = Symbol.for("xplane.pendingTemplate");
+var PendingTemplate = class {
+	parts;
+	slots;
+	static TAG = PENDING_TEMPLATE_TAG;
+	[PENDING_TEMPLATE_TAG] = true;
+	constructor(parts, slots) {
+		this.parts = parts;
+		this.slots = slots;
+	}
+	static is(value) {
+		return typeof value === "object" && value !== null && value[PENDING_TEMPLATE_TAG] === true;
+	}
+};
+//#endregion
+//#region src/tracking/token-registry.ts
+/**
+* Per-run AsyncLocalStorage for the template-literal token registry.
+* Kept separate from compositionStorage (core/) to avoid circular deps.
+*/
+const tokenRegistryStorage = new AsyncLocalStorage();
+function createTokenRegistry() {
+	return {
+		byToken: /* @__PURE__ */ new Map(),
+		byKey: /* @__PURE__ */ new Map(),
+		counter: 0
+	};
+}
+/**
+* Get or create a stable token for a given (owner, path) pair.
+* Returns null when no registry is active (outside of a composition run).
+*/
+function getOrCreateToken(owner, path) {
+	const registry = tokenRegistryStorage.getStore();
+	if (!registry) return null;
+	const key = `${owner.id}\0${path}`;
+	const existing = registry.byKey.get(key);
+	if (existing !== void 0) return existing;
+	const token = `__pending__tpl_${registry.counter++}__`;
+	registry.byToken.set(token, {
+		owner,
+		path
+	});
+	registry.byKey.set(key, token);
+	return token;
+}
+function lookupToken(token) {
+	return tokenRegistryStorage.getStore()?.byToken.get(token);
+}
+const TEMPLATE_TOKEN_RE = /__pending__tpl_\d+__/g;
+/**
+* Scan a string for pending template tokens. If any are found, calls
+* `onSlot` for each registered token and returns a PendingTemplate.
+* Returns the original string if no tokens are found or none are registered.
+*/
+function processStringValue(value, onSlot) {
+	const parts = [];
+	const slots = [];
+	let lastIndex = 0;
+	let hasSlots = false;
+	TEMPLATE_TOKEN_RE.lastIndex = 0;
+	for (const match of value.matchAll(TEMPLATE_TOKEN_RE)) {
+		const meta = lookupToken(match[0]);
+		if (!meta) continue;
+		hasSlots = true;
+		parts.push(value.slice(lastIndex, match.index));
+		slots.push({
+			source: meta.owner,
+			path: meta.path
+		});
+		onSlot(meta);
+		lastIndex = match.index + match[0].length;
+	}
+	if (!hasSlots) return value;
+	parts.push(value.slice(lastIndex));
+	return new PendingTemplate(parts, slots);
+}
+//#endregion
 //#region src/tracking/read-proxy.ts
 /**
 * WeakMap storing metadata for ReadProxy instances.
@@ -277,13 +409,15 @@ function createReadProxy(target, owner, basePath) {
 * coerced to a primitive.
 */
 function createLeafReadProxy(owner, path) {
-	const proxy = new Proxy(Object.create(null), {
+	const target = Object.create(null);
+	const getToken = () => getOrCreateToken(owner, path) ?? `__pending__${owner.id}__${path}`;
+	const proxy = new Proxy(target, {
 		get(_obj, prop) {
 			if (prop === READ_PROXY_TAG) return true;
-			if (prop === Symbol.toPrimitive) return () => `__pending__${owner.id}__${path}`;
+			if (prop === Symbol.toPrimitive) return () => getToken();
 			if (typeof prop === "symbol") return void 0;
 			if (prop === "toJSON") return () => void 0;
-			if (prop === "toString") return () => `__pending__${owner.id}__${path}`;
+			if (prop === "toString") return () => getToken();
 			if (prop === "valueOf") return () => proxy;
 			return createLeafReadProxy(owner, `${path}.${String(prop)}`);
 		},
@@ -326,27 +460,6 @@ function createPrimitiveReadProxy(value, owner, path) {
 	return proxy;
 }
 //#endregion
-//#region src/tracking/types.ts
-/**
-* A Pending marker stored in a desired document when a ReadProxy value
-* is assigned. Carries full source info so the resolve phase knows
-* where to look for the concrete value.
-*/
-const PENDING_TAG = Symbol.for("xplane.pending");
-var Pending = class {
-	source;
-	path;
-	static TAG = PENDING_TAG;
-	[PENDING_TAG] = true;
-	constructor(source, path) {
-		this.source = source;
-		this.path = path;
-	}
-	static is(value) {
-		return typeof value === "object" && value !== null && value[PENDING_TAG] === true;
-	}
-};
-//#endregion
 //#region src/tracking/write-proxy.ts
 /**
 * Collector that accumulates dependency edges discovered during
@@ -422,6 +535,17 @@ function createWriteProxy(target, opts) {
 					return Reflect.set(obj, prop, new Pending(meta.owner, meta.path));
 				}
 			}
+			if (typeof value === "string") {
+				const processed = processStringValue(value, (meta) => {
+					collector.add({
+						from: meta.owner,
+						fromPath: meta.path,
+						to: owner,
+						toPath: targetPath
+					});
+				});
+				return Reflect.set(obj, prop, processed);
+			}
 			if (typeof value === "object" && value !== null && !Pending.is(value)) {
 				const processed = deepProcessValue(value, owner, targetPath, collector);
 				return Reflect.set(obj, prop, processed);
@@ -453,6 +577,14 @@ function tryExtractPrimitive$2(proxy) {
 */
 function deepProcessValue(value, owner, basePath, collector) {
 	if (value === null || value === void 0) return value;
+	if (typeof value === "string") return processStringValue(value, (meta) => {
+		collector.add({
+			from: meta.owner,
+			fromPath: meta.path,
+			to: owner,
+			toPath: basePath
+		});
+	});
 	if (typeof value !== "object") return value;
 	if (isReadProxy(value)) {
 		const meta = getReadProxyMeta(value);
@@ -517,8 +649,14 @@ var Resource = class Resource extends Construct$1 {
 			collector
 		};
 		internals.set(this, internal);
+		const ctx = compositionStorage.getStore();
+		if (ctx) {
+			const observed = ctx.observedComposed.get(this.node.path);
+			if (observed) Object.assign(internal.observed, observed);
+		}
 		const proxy = createResourceProxy(this, internal);
 		scope.node._children[this.node.id] = proxy;
+		this.node.host = proxy;
 		return proxy;
 	}
 	/**
@@ -581,6 +719,33 @@ var Resource = class Resource extends Construct$1 {
 		if (withHash.length <= maxLength) return withHash;
 		return `${full.slice(0, maxLength - hash.length - separator.length)}${separator}${hash}`;
 	}
+	/**
+	* Like {@link uniqueName} but produces names compliant with RFC 1123 DNS labels:
+	* lowercase alphanumeric characters and hyphens only, starting and ending with
+	* an alphanumeric character. Suitable for use as Kubernetes resource names.
+	*/
+	static uniqueNameRfc1123(scope, options = {}) {
+		const maxLength = options.maxLength ?? 63;
+		const clean = (s) => s.toLowerCase().replace(/\s+/g, "").replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+		const xrMeta = scope.node.tryGetContext("xplane:xr-meta");
+		const parts = [];
+		if (xrMeta?.namespace) parts.push(clean(xrMeta.namespace));
+		if (xrMeta?.name) parts.push(clean(xrMeta.name));
+		for (const s of scope.node.scopes.slice(1)) {
+			const c = clean(s.node.id);
+			if (c) parts.push(c);
+		}
+		if (options.extra) {
+			const c = clean(options.extra);
+			if (c) parts.push(c);
+		}
+		const full = parts.join("-");
+		const hash = shortHash(full);
+		const withHash = `${full}-${hash}`;
+		if (withHash.length <= maxLength) return withHash;
+		const trimmedPrefix = full.slice(0, maxLength - hash.length - 1).replace(/-+$/, "");
+		return trimmedPrefix ? `${trimmedPrefix}-${hash}` : hash;
+	}
 };
 function getResourceInternals(resource) {
 	const internal = internals.get(resource);
@@ -642,6 +807,14 @@ function processDesiredProps(props, owner, collector) {
 }
 function processValue(value, owner, path, collector) {
 	if (value === null || value === void 0) return value;
+	if (typeof value === "string") return processStringValue(value, (meta) => {
+		collector.add({
+			from: meta.owner,
+			fromPath: meta.path,
+			to: owner,
+			toPath: path
+		});
+	});
 	if (typeof value !== "object") return value;
 	if (isReadProxy(value)) {
 		const meta = getReadProxyMeta(value);
@@ -805,12 +978,12 @@ function diagnose(state) {
 		if (!ref) continue;
 		const observed = getObservedDocument(resource);
 		if (Object.keys(observed).length > 0) continue;
-		const nameDisplay = typeof ref.name === "string" ? ref.name : ref.name == null ? "(unresolved)" : "(unresolved)";
+		if (typeof ref.name !== "string" || ref.name.startsWith("__pending__")) continue;
 		const nsDisplay = ref.namespace ? ` in namespace '${ref.namespace}'` : "";
 		diagnostics.push({
 			resource: getResourceRef(resource).id,
 			reason: "not-found",
-			detail: `External resource ${ref.apiVersion}/${ref.kind} '${nameDisplay}'${nsDisplay} was required but not found by Crossplane`
+			detail: `External resource ${ref.apiVersion}/${ref.kind} '${ref.name}'${nsDisplay} was required but not found by Crossplane`
 		});
 	}
 	const pendingDiagnostics = [];
@@ -874,22 +1047,39 @@ function findPendingPaths(obj, basePath) {
 * Kubernetes resource document ready for Crossplane.
 *
 * Also extracts the XR desired status from this.xr.status assignments.
+*
+* For resources classified as 'blocked' that have previously-observed state,
+* emits the observed document as-is (marked `preserved: true`) so that
+* Crossplane does not delete them while their dependencies are still resolving.
 */
 function emit(state) {
 	const emitted = [];
 	for (const resource of state.resources) {
 		if (isExternal(resource)) continue;
 		const ref = getResourceRef(resource);
-		if (state.classification.get(ref.id) !== "emit") continue;
-		const internal = getResourceInternals(resource);
-		const desired = getDesiredDocument(resource);
-		const name = ref.id.startsWith("Composition/") ? ref.id.slice(12) : ref.id;
-		emitted.push({
-			name,
-			document: deepClean(desired),
-			autoReady: internal.config.autoReady,
-			readyChecks: getReadyChecks(resource)
-		});
+		const classification = state.classification.get(ref.id);
+		if (classification === "emit") {
+			const internal = getResourceInternals(resource);
+			const desired = getDesiredDocument(resource);
+			const name = ref.id.startsWith("Composition/") ? ref.id.slice(12) : ref.id;
+			emitted.push({
+				name,
+				document: deepClean(desired),
+				autoReady: internal.config.autoReady,
+				readyChecks: getReadyChecks(resource)
+			});
+		} else if (classification === "blocked") {
+			const observed = getObservedDocument(resource);
+			if (Object.keys(observed).length === 0) continue;
+			const name = ref.id.startsWith("Composition/") ? ref.id.slice(12) : ref.id;
+			emitted.push({
+				name,
+				document: stripServerFields(deepClean(observed)),
+				autoReady: false,
+				readyChecks: [],
+				preserved: true
+			});
+		}
 	}
 	const resourceById = new Map(state.resources.map((r) => [getResourceRef(r).id, r]));
 	const xrStatusPatches = resolveXrStatus(getXrDesiredStatus(state.composition), resourceById);
@@ -911,12 +1101,43 @@ function deepClean(obj) {
 function cleanValue(value) {
 	if (value === null || value === void 0) return value;
 	if (typeof value !== "object") return value;
+	if (PendingTemplate.is(value)) throw new Error(`PendingTemplate reached emit phase — resource should have been classified as blocked. Parts: ${JSON.stringify(value.parts)}`);
 	if (Array.isArray(value)) return value.map(cleanValue);
 	const result = {};
 	for (const [key, val] of Object.entries(value)) result[key] = cleanValue(val);
 	return result;
 }
 /**
+* Strip server-managed Kubernetes fields from an observed document before
+* emitting it as a preserved desired resource.
+*
+* These fields are set by the API server / controllers and must not appear
+* in the desired state — including them causes Crossplane to try propagating
+* them (e.g. `uid`) into XR resourceRefs fields that the XRD schema may not
+* declare, resulting in a typed-patch validation failure.
+*/
+const SERVER_MANAGED_METADATA = new Set([
+	"uid",
+	"resourceVersion",
+	"generation",
+	"creationTimestamp",
+	"deletionTimestamp",
+	"deletionGracePeriodSeconds",
+	"managedFields",
+	"ownerReferences",
+	"selfLink"
+]);
+function stripServerFields(doc) {
+	const result = { ...doc };
+	delete result.status;
+	if (result.metadata && typeof result.metadata === "object") {
+		const meta = { ...result.metadata };
+		for (const field of SERVER_MANAGED_METADATA) delete meta[field];
+		result.metadata = meta;
+	}
+	return result;
+}
+/**
 * Resolve ReadProxy values in XR status using observed resource data.
 * This is needed because XR status is written at construction time (before hydration),
 * so read proxy references need to be resolved post-hydration.
@@ -1017,6 +1238,9 @@ function resolvePending(obj, resourceById) {
 			const resolved = getNestedValue(getObservedDocument(sourceResource), value.path);
 			if (resolved !== void 0) obj[key] = resolved;
 		}
+	} else if (PendingTemplate.is(value)) {
+		const resolved = resolvePendingTemplate(value, resourceById);
+		if (resolved !== void 0) obj[key] = resolved;
 	} else if (Array.isArray(value)) resolveArray(value, resourceById);
 	else if (value !== null && typeof value === "object") resolvePending(value, resourceById);
 }
@@ -1029,6 +1253,9 @@ function resolveArray(arr, resourceById) {
 				const resolved = getNestedValue(getObservedDocument(sourceResource), value.path);
 				if (resolved !== void 0) arr[i] = resolved;
 			}
+		} else if (PendingTemplate.is(value)) {
+			const resolved = resolvePendingTemplate(value, resourceById);
+			if (resolved !== void 0) arr[i] = resolved;
 		} else if (Array.isArray(value)) resolveArray(value, resourceById);
 		else if (value !== null && typeof value === "object") resolvePending(value, resourceById);
 	}
@@ -1046,6 +1273,23 @@ function getNestedValue(obj, path) {
 	}
 	return current;
 }
+/**
+* Attempt to resolve all slots of a PendingTemplate.
+* Returns the reconstructed string if all slots resolve, undefined otherwise.
+*/
+function resolvePendingTemplate(template, resourceById) {
+	const values = [];
+	for (const slot of template.slots) {
+		const sourceResource = resourceById.get(slot.source.id);
+		if (!sourceResource) return void 0;
+		const resolved = getNestedValue(getObservedDocument(sourceResource), slot.path);
+		if (resolved === void 0 || resolved === null) return void 0;
+		values.push(String(resolved));
+	}
+	let result = template.parts[0];
+	for (let i = 0; i < values.length; i++) result += values[i] + template.parts[i + 1];
+	return result;
+}
 //#endregion
 //#region src/pipeline/sequence.ts
 /**
@@ -1083,6 +1327,7 @@ function sequence(state) {
 function containsPending(obj) {
 	if (obj === null || obj === void 0) return false;
 	if (Pending.is(obj)) return true;
+	if (PendingTemplate.is(obj)) return true;
 	if (typeof obj !== "object") return false;
 	if (Array.isArray(obj)) return obj.some(containsPending);
 	for (const value of Object.values(obj)) if (containsPending(value)) return true;
@@ -1267,15 +1512,23 @@ function runComposition(CompositionClass, input) {
 		xr: input.xr,
 		pipelineContext,
 		requiredResources: observedRequired,
+		observedComposed,
 		graph,
 		collector
 	};
+	const composition = compositionStorage.run(ctx, () => tokenRegistryStorage.run(createTokenRegistry(), () => new CompositionClass()));
 	const state = runPipeline({
-		composition: compositionStorage.run(ctx, () => new CompositionClass()),
+		composition,
 		observedComposed,
 		observedRequired
 	});
 	const resources = state.emitted.map((emitted) => {
+		if (emitted.preserved) return {
+			name: emitted.name,
+			document: emitted.document,
+			ready: false,
+			preserved: true
+		};
 		const allChecks = [...emitted.readyChecks, ...DEFAULT_CHECKS];
 		const observed = observedComposed.get(`Composition/${emitted.name}`);
 		const ready = emitted.autoReady ? evaluateReadiness(allChecks, observed) : true;
@@ -1299,14 +1552,51 @@ function runComposition(CompositionClass, input) {
 			...ref.namespace ? { namespace: ref.namespace } : {}
 		});
 	}
+	const blockedResources = [];
+	for (const resource of state.resources) {
+		if (isExternal(resource)) continue;
+		const ref = getResourceRef(resource);
+		if (state.classification.get(ref.id) !== "blocked") continue;
+		const name = ref.id.startsWith("Composition/") ? ref.id.slice(12) : ref.id;
+		const desired = getDesiredDocument(resource);
+		const apiVersion = typeof desired.apiVersion === "string" ? desired.apiVersion : "";
+		const kind = typeof desired.kind === "string" ? desired.kind : "";
+		const metadata = desired.metadata && typeof desired.metadata === "object" ? desired.metadata : void 0;
+		const resourceName = metadata && typeof metadata.name === "string" ? metadata.name : void 0;
+		const waitingFor = describeWaitingFor(name, state.diagnostics);
+		blockedResources.push({
+			name,
+			apiVersion,
+			kind,
+			...resourceName ? { resourceName } : {},
+			...waitingFor && waitingFor.length > 0 ? { waitingFor } : {}
+		});
+	}
 	return {
 		resources,
+		blockedResources,
 		externalResources,
 		xrStatus: state.xrStatusPatches,
-		diagnostics: state.diagnostics
+		diagnostics: state.diagnostics,
+		emitXplaneStatus: composition.emitXplaneStatus === true
 	};
 }
+/**
+* Build a human-readable `waitingFor` list for a blocked resource from the
+* matching diagnostic. Each entry describes one thing the resource is waiting
+* on (one entry per pending path, or a single entry for cycle/not-found).
+*/
+function describeWaitingFor(name, diagnostics) {
+	const id = `Composition/${name}`;
+	const diag = diagnostics.find((d) => d.resource === id || d.resource === name);
+	if (!diag) return void 0;
+	if (diag.reason === "cycle") return [`circular dependency: ${(diag.cycle ?? []).join(" → ")}`];
+	if (diag.reason === "not-found") return [diag.detail ?? "external resource not found"];
+	if (diag.pendingPaths && diag.pendingPaths.length > 0) return diag.pendingPaths.map((p) => {
+		return `${p.waitingOn.resource.startsWith("Composition/") ? p.waitingOn.resource.slice(12) : p.waitingOn.resource}.${p.waitingOn.path}`;
+	});
+}
 //#endregion
-export { Composition, Construct, DEFAULT_CHECKS, DependencyGraph, EdgeCollector, Pending, Resource, compositionStorage, createPrimitiveReadProxy, createReadProxy, createWriteProxy, diagnose, emit, evaluateReadiness, getCompositionContext, getDesiredDocument, getExternalRef, getLogger, getObservedDocument, getReadProxyMeta, getReadyChecks, getResourceInternals, getResourceRef, getXrDesiredStatus, hydrate, hydrateObserved, isExternal, isReadProxy, resolve, runComposition, runPipeline, sequence, withLogger };
+export { Composition, Construct, DEFAULT_CHECKS, DependencyGraph, EdgeCollector, Pending, PendingTemplate, Resource, compositionStorage, createPrimitiveReadProxy, createReadProxy, createTokenRegistry, createWriteProxy, diagnose, emit, evaluateReadiness, getCompositionContext, getDesiredDocument, getExternalRef, getLogger, getObservedDocument, getReadProxyMeta, getReadyChecks, getResourceInternals, getResourceRef, getXrDesiredStatus, hydrate, hydrateObserved, isExternal, isReadProxy, resolve, runComposition, runPipeline, sequence, tokenRegistryStorage, withLogger };
 
 //# sourceMappingURL=index.mjs.map