@innovatorstack/harness 0.0.0-stage → 0.1.1

package/src/platform/queries/validation.ts

@@ -0,0 +1,105 @@
+import type { ItemNode } from "../../items/item.js";
+import type { AmlLogicalTerm, AmlPropertyCondition } from "../../items/logical.js";
+import { PredicateParser } from "../../queries/parser.js";
+import { queryDepthMax, queryNodesMax } from "../../queries/types.js";
+import type { HarnessStorage, ItemTypeDefinition } from "../../storage/types.js";
+import { PlatformError } from "../errors.js";
+import { compileProjection } from "../projection.js";
+import { relationshipType } from "../relationship-type.js";
+import { validateRequest } from "../request.js";
+import { propertyPredicate } from "./conditions.js";
+import { resolveField, selectorType } from "./fields.js";
+import { orderBy } from "./order.js";
+import { pageRows } from "./paging.js";
+
+/** Validate nested queries even when no parent rows exist. This never executes business hooks. */
+export function validateEmptyQuery(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    request: ItemNode,
+): void {
+    const pending = [{ definition, request, depth: 0 }];
+    let visited = 0;
+
+    while (pending.length > 0) {
+        const frame = pending.pop();
+
+        if (!frame || ++visited > queryNodesMax || frame.depth > queryDepthMax) {
+            throw new PlatformError(
+                "InvalidSelector",
+                "Nested query exceeds its traversal budget.",
+            );
+        }
+
+        const { definition, request, depth } = frame;
+        validateRequest(request, "get");
+        compileProjection(storage, definition, request.attributes.select);
+        orderBy(storage, definition, request.attributes.orderBy);
+        pageRows(request, []);
+
+        if (request.attributes.where) {
+            new PredicateParser(request.attributes.where, (names) =>
+                resolveField(storage, definition, names),
+            ).parse();
+        }
+
+        for (const property of conditions(request)) {
+            if (property.item) {
+                pending.push({
+                    definition: selectorType(storage, definition, property),
+                    request: property.item,
+                    depth: depth + 1,
+                });
+            } else {
+                propertyPredicate(resolveField(storage, definition, [property.name]), property);
+            }
+        }
+
+        for (const child of request.relationships) {
+            if ((child.attributes.action ?? "get") !== "get") {
+                throw new PlatformError("InvalidSelector", "Nested queries require get actions.");
+            }
+
+            pending.push({
+                definition: relationshipType(storage, definition, child.type),
+                request: child,
+                depth: depth + 1,
+            });
+        }
+    }
+}
+
+function* conditions(request: ItemNode): Generator<AmlPropertyCondition, void, void> {
+    for (const [name, value] of Object.entries(request.properties)) {
+        yield { name, value, attributes: request.propertyAttributes[name] ?? {} };
+    }
+
+    for (const [name, item] of Object.entries(request.propertyItems)) {
+        yield { name, item, attributes: request.propertyAttributes[name] ?? {} };
+    }
+
+    const pending: { readonly term: AmlLogicalTerm; readonly depth: number }[] = (
+        request.logical ?? []
+    ).map((term) => ({ term, depth: 0 }));
+    let visited = 0;
+
+    while (pending.length > 0) {
+        const frame = pending.pop();
+
+        if (!frame || ++visited > queryNodesMax || frame.depth > queryDepthMax) {
+            throw new PlatformError("InvalidSelector", "Logical criteria exceed their budget.");
+        }
+
+        if ("operator" in frame.term) {
+            if (frame.term.terms.length === 0) {
+                throw new PlatformError("InvalidSelector", "Logical groups require criteria.");
+            }
+
+            for (const term of frame.term.terms) {
+                pending.push({ term, depth: frame.depth + 1 });
+            }
+        } else {
+            yield frame.term;
+        }
+    }
+}

package/src/platform/query.ts

@@ -0,0 +1,178 @@
+import { getOwn, setOwn } from "../core/data.js";
+import { dataDepthMax } from "../core/limits.js";
+import type { ItemNode } from "../items/item.js";
+import { compareValues } from "../queries/values.js";
+import type {
+    HarnessStorage,
+    ItemTypeDefinition,
+    PropertyDefinition,
+    StorageValue,
+    StoredItem,
+} from "../storage/types.js";
+import { PlatformError } from "./errors.js";
+import { fieldValue, resolveField } from "./queries/fields.js";
+
+export interface EqualityPredicate {
+    readonly name: string;
+    readonly value: StorageValue;
+}
+
+export function matches(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    record: StoredItem,
+    predicate: EqualityPredicate,
+): boolean {
+    const field = resolveField(storage, definition, [predicate.name]);
+    const actual = fieldValue(storage, record, field);
+
+    if (predicate.value === null) {
+        return actual === null;
+    }
+
+    return compareValues(field.kind, actual, predicate.value) === 0;
+}
+
+export function projectedProperties(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    record: StoredItem,
+    selected?: readonly string[],
+    visiting = new Set<string>(),
+): Record<string, StorageValue> {
+    const properties: Record<string, StorageValue> = {};
+    const names = selected ?? definition.properties.map((property) => property.name);
+
+    for (const name of names) {
+        if (name === "id") {
+            continue;
+        }
+
+        const property = definition.properties.find((property) => property.name === name);
+
+        if (!property) {
+            throw new PlatformError(
+                "UnknownProperty",
+                `Unknown property '${definition.name}.${name}'.`,
+            );
+        }
+
+        if (property.isFederated) {
+            setOwn(properties, name, null);
+            continue;
+        }
+
+        if (property.dataType !== "foreign") {
+            const value = getOwn(record.properties, name);
+
+            if (value !== undefined) {
+                setOwn(properties, name, value);
+            }
+
+            continue;
+        }
+
+        setOwn(properties, name, foreignValue(storage, definition, record, property, visiting));
+    }
+
+    return properties;
+}
+
+function foreignValue(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    record: StoredItem,
+    property: PropertyDefinition,
+    ancestors: ReadonlySet<string>,
+): StorageValue {
+    const visiting = new Set(ancestors);
+    let current = { definition, record, property };
+
+    while (true) {
+        const { definition, record, property } = current;
+
+        if (visiting.size >= dataDepthMax) {
+            throw new PlatformError(
+                "InvalidForeignProperty",
+                "The foreign-property chain is too deep.",
+            );
+        }
+
+        const key = `${record.type}:${record.id}:${property.name}`;
+
+        if (visiting.has(key)) {
+            throw new PlatformError(
+                "ForeignPropertyCycle",
+                `Foreign property cycle at '${definition.name}.${property.name}'.`,
+            );
+        }
+
+        visiting.add(key);
+        const { source, targetDefinition, targetProperty } = foreignTarget(
+            storage,
+            definition,
+            property,
+        );
+
+        const targetId = getOwn(record.properties, source.name);
+        const target =
+            typeof targetId === "string" && targetId !== ""
+                ? storage.getItem(targetDefinition.name, targetId)
+                : undefined;
+
+        if (!target) {
+            return null;
+        }
+
+        if (targetProperty.name === "id") {
+            return target.id;
+        }
+
+        if (targetProperty.isFederated) {
+            return null;
+        }
+
+        if (targetProperty.dataType !== "foreign") {
+            return getOwn(target.properties, targetProperty.name) ?? null;
+        }
+
+        current = { definition: targetDefinition, record: target, property: targetProperty };
+    }
+}
+
+function foreignTarget(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    property: PropertyDefinition,
+) {
+    const source = definition.properties.find((candidate) => candidate.id === property.dataSource);
+    const targetDefinition = storage.listItemTypes().find((type) => type.id === source?.dataSource);
+    const targetProperty = targetDefinition?.properties.find(
+        (candidate) => candidate.id === property.foreignProperty,
+    );
+
+    if (!source || !targetDefinition || !targetProperty) {
+        throw new PlatformError(
+            "InvalidForeignProperty",
+            `Cannot resolve foreign property '${definition.name}.${property.name}'.`,
+        );
+    }
+
+    return { source, targetDefinition, targetProperty };
+}
+
+export function selectedProperties(request: ItemNode): readonly string[] | undefined {
+    const select = request.attributes.select;
+
+    if (!select || select === "*") {
+        return undefined;
+    }
+
+    const names = select.split(",").map((name) => name.trim());
+
+    if (names.some((name) => !/^[A-Za-z_][\w]*$/.test(name))) {
+        throw new PlatformError("UnsupportedSelect", `Unsupported select '${select}'.`);
+    }
+
+    return names;
+}

package/src/platform/references/behavior.ts

@@ -0,0 +1,36 @@
+import type { StorageValue } from "../../storage/types.js";
+import { PlatformError } from "../errors.js";
+
+export enum ReferenceBehavior {
+    Fixed = "fixed",
+    Float = "float",
+    HardFixed = "hard_fixed",
+    HardFloat = "hard_float",
+}
+
+export function referenceBehavior(value: StorageValue | undefined): ReferenceBehavior | undefined {
+    if (value === undefined || value === null || value === "") {
+        return undefined;
+    }
+
+    const behavior = Object.values(ReferenceBehavior).find(
+        (behavior: string) => behavior === value,
+    );
+
+    if (behavior === undefined) {
+        throw new PlatformError(
+            "InvalidReferenceBehavior",
+            `Unknown reference behavior '${value}'.`,
+        );
+    }
+
+    return behavior;
+}
+
+export function hardBehavior(behavior: ReferenceBehavior): boolean {
+    return behavior === ReferenceBehavior.HardFixed || behavior === ReferenceBehavior.HardFloat;
+}
+
+export function floats(behavior: ReferenceBehavior): boolean {
+    return behavior === ReferenceBehavior.Float || behavior === ReferenceBehavior.HardFloat;
+}

package/src/platform/references/catalog.ts

@@ -0,0 +1,256 @@
+import { spendContext } from "../../core/context.js";
+import { dataNodesMax } from "../../core/limits.js";
+import type { ExecutionContext } from "../../core/types.js";
+import type {
+    CatalogEntry,
+    HarnessStorage,
+    ItemTypeDefinition,
+    PropertyDefinition,
+    StoredItem,
+} from "../../storage/types.js";
+import { PlatformError } from "../errors.js";
+
+export interface IncomingReference {
+    readonly definition: ItemTypeDefinition;
+    readonly property: PropertyDefinition;
+    readonly record: StoredItem;
+}
+
+export function recordKey(record: Pick<StoredItem, "type" | "id">): string {
+    return JSON.stringify([record.type.toLowerCase(), record.id.toLowerCase()]);
+}
+
+export class ReferenceCatalog {
+    constructor(private readonly storage: HarnessStorage) {}
+
+    dependent(definition: ItemTypeDefinition): boolean {
+        const value = this.storage.getCatalogEntry("ItemType", definition.id)?.properties
+            .is_dependent;
+
+        if (value !== undefined && value !== null && !["0", "1"].includes(String(value))) {
+            throw new PlatformError(
+                "InvalidDependency",
+                `Invalid is_dependent on '${definition.name}'.`,
+            );
+        }
+
+        return String(value ?? "0") === "1";
+    }
+
+    relationship(definition: ItemTypeDefinition): CatalogEntry | undefined {
+        const candidates = this.storage
+            .listCatalogEntries("RelationshipType")
+            .filter(
+                (entry) =>
+                    String(entry.properties.relationship_id).toLowerCase() ===
+                    definition.id.toLowerCase(),
+            );
+
+        if (candidates.length > 1) {
+            throw new PlatformError(
+                "AmbiguousRelationship",
+                `Multiple RelationshipTypes own '${definition.name}'.`,
+            );
+        }
+
+        return candidates[0];
+    }
+
+    target(property: PropertyDefinition): ItemTypeDefinition | undefined {
+        if (property.dataType !== "item" || !property.dataSource) {
+            return undefined;
+        }
+
+        return this.storage
+            .listItemTypes()
+            .find(
+                (definition) => definition.id.toLowerCase() === property.dataSource?.toLowerCase(),
+            );
+    }
+
+    *incoming(
+        target: StoredItem,
+        context: ExecutionContext,
+        ids: ReadonlySet<string> = new Set([target.id.toLowerCase()]),
+    ): Generator<IncomingReference, void, void> {
+        const definition = this.storage.getItemType(target.type);
+
+        if (!definition) {
+            throw new PlatformError(
+                "MissingItemType",
+                `Reference target '${target.type}' has no schema.`,
+            );
+        }
+
+        for (const source of this.storage.listItemTypes()) {
+            spendContext(context, source.properties.length + 1);
+            const properties = source.properties.filter(
+                (property) =>
+                    property.dataType === "item" &&
+                    property.name !== "config_id" &&
+                    property.dataSource?.toLowerCase() === definition.id.toLowerCase(),
+            );
+
+            if (properties.length === 0) {
+                continue;
+            }
+
+            for (const record of this.storage.listItems(source.name)) {
+                spendContext(context, properties.length + 1);
+
+                for (const property of properties) {
+                    if (ids.has(String(record.properties[property.name]).toLowerCase())) {
+                        yield { definition: source, property, record };
+                    }
+                }
+            }
+        }
+    }
+
+    *owned(parent: StoredItem, context: ExecutionContext): Generator<StoredItem, void, void> {
+        const definition = this.storage.getItemType(parent.type);
+
+        if (!definition) {
+            throw new PlatformError(
+                "MissingItemType",
+                `Relationship owner '${parent.type}' has no schema.`,
+            );
+        }
+
+        for (const incoming of this.incoming(parent, context)) {
+            if (incoming.definition.isRelationship && incoming.property.name === "source_id") {
+                yield incoming.record;
+            }
+        }
+    }
+
+    hasOwner(record: StoredItem, context: ExecutionContext): boolean {
+        const pending = [...this.family(record)];
+        const visited = new Set<string>();
+
+        while (pending.length > 0) {
+            const target = pending.pop();
+
+            if (!target || visited.size >= dataNodesMax) {
+                throw new PlatformError(
+                    "ProtocolLimit",
+                    "Dependent ownership exceeds its graph budget.",
+                );
+            }
+
+            const key = recordKey(target);
+
+            if (visited.has(key)) {
+                continue;
+            }
+
+            visited.add(key);
+            spendContext(context);
+
+            for (const owner of this.owners(target, context)) {
+                const type = this.storage.getItemType(owner.type);
+
+                if (!type) {
+                    throw new PlatformError(
+                        "MissingItemType",
+                        `Reference owner '${owner.type}' has no schema.`,
+                    );
+                }
+
+                if (!this.dependent(type) && !type.isRelationship) {
+                    return true;
+                }
+
+                pending.push(...this.family(owner));
+            }
+        }
+
+        return false;
+    }
+
+    family(record: StoredItem): readonly StoredItem[] {
+        const definition = this.storage.getItemType(record.type);
+
+        if (!definition?.isVersionable) {
+            return [record];
+        }
+
+        const configId = String(record.properties.config_id ?? record.id).toLowerCase();
+
+        return this.storage
+            .listItems(record.type)
+            .filter(
+                (candidate) =>
+                    String(candidate.properties.config_id ?? candidate.id).toLowerCase() ===
+                    configId,
+            );
+    }
+
+    current(record: StoredItem): StoredItem {
+        const definition = this.storage.getItemType(record.type);
+
+        if (!definition?.isVersionable) {
+            const current = this.storage.getItem(record.type, record.id);
+
+            if (!current) {
+                throw new PlatformError(
+                    "MissingItem",
+                    `Reference target '${record.type}:${record.id}' disappeared.`,
+                );
+            }
+
+            return current;
+        }
+
+        const current = this.family(record).filter(
+            (candidate) => String(candidate.properties.is_current) === "1",
+        );
+        const result = current[0];
+
+        if (current.length !== 1 || !result) {
+            throw new PlatformError(
+                "InvalidGeneration",
+                `Reference family '${record.type}:${record.properties.config_id}' needs one current generation.`,
+            );
+        }
+
+        return result;
+    }
+
+    private *owners(
+        record: StoredItem,
+        context: ExecutionContext,
+    ): Generator<StoredItem, void, void> {
+        const definition = this.storage.getItemType(record.type);
+
+        if (definition?.isRelationship) {
+            const parent = this.parent(definition, record);
+
+            if (parent) {
+                yield parent;
+            }
+        }
+
+        for (const incoming of this.incoming(record, context)) {
+            if (incoming.definition.isRelationship && incoming.property.name === "source_id") {
+                continue;
+            }
+
+            const owner = incoming.definition.isRelationship
+                ? this.parent(incoming.definition, incoming.record)
+                : incoming.record;
+
+            if (owner) {
+                yield owner;
+            }
+        }
+    }
+
+    private parent(definition: ItemTypeDefinition, record: StoredItem): StoredItem | undefined {
+        const source = definition.properties.find((property) => property.name === "source_id");
+        const type = source ? this.target(source) : undefined;
+        const id = record.properties.source_id;
+
+        return type && typeof id === "string" ? this.storage.getItem(type.name, id) : undefined;
+    }
+}

package/src/platform/references/deletion.ts

@@ -0,0 +1,130 @@
+import { spendContext } from "../../core/context.js";
+import { dataNodesMax } from "../../core/limits.js";
+import type { ExecutionContext } from "../../core/types.js";
+import { Item } from "../../items/item.js";
+import type { HarnessStorage, StoredItem } from "../../storage/types.js";
+import { ApplicationError, PlatformError, requireSuccess } from "../errors.js";
+import type { ApplyQueryItem } from "../queries/planner.js";
+import { recordKey } from "./catalog.js";
+import type { ReferenceCatalog } from "./catalog.js";
+import type { ReferenceSessions } from "./sessions.js";
+
+export class DependentDeletion {
+    constructor(
+        private readonly storage: HarnessStorage,
+        private readonly catalog: ReferenceCatalog,
+        private readonly sessions: ReferenceSessions,
+        private readonly apply: ApplyQueryItem,
+        private readonly removeOwned: (
+            parent: StoredItem,
+            child: StoredItem,
+            enabled: boolean,
+            context: ExecutionContext,
+        ) => Promise<Item>,
+    ) {}
+
+    prepare(records: readonly StoredItem[], context: ExecutionContext): void {
+        const pending = [...records];
+        const visited = new Set<string>();
+
+        while (pending.length > 0) {
+            const record = pending.pop();
+
+            if (!record || visited.size >= dataNodesMax) {
+                throw new PlatformError("ProtocolLimit", "Deletion exceeds its graph budget.");
+            }
+
+            spendContext(context);
+            const key = recordKey(record);
+
+            if (visited.has(key)) {
+                continue;
+            }
+
+            visited.add(key);
+            this.sessions.schedule(record, context);
+            pending.push(...this.catalog.owned(record, context));
+        }
+    }
+
+    async children(record: StoredItem, enabled: boolean, context: ExecutionContext): Promise<void> {
+        for (const child of this.catalog.owned(record, context)) {
+            if (this.storage.getItem(child.type, child.id)) {
+                requireSuccess(await this.removeOwned(record, child, enabled, context));
+            }
+        }
+    }
+
+    assertRemovable(record: StoredItem, context: ExecutionContext): void {
+        for (const incoming of this.catalog.incoming(record, context)) {
+            if (!this.sessions.scheduled(incoming.record, context)) {
+                throw new ApplicationError(
+                    Item.error(
+                        `Cannot delete '${record.type}:${record.id}': referenced by ` +
+                            `'${incoming.definition.name}.${incoming.property.name}'.`,
+                        "ReferencedItem",
+                    ),
+                );
+            }
+        }
+    }
+
+    async changed(
+        before: StoredItem,
+        after: StoredItem | undefined,
+        enabled: boolean,
+        context: ExecutionContext,
+    ): Promise<void> {
+        const definition = this.storage.getItemType(before.type);
+
+        if (!definition) {
+            throw new PlatformError(
+                "MissingItemType",
+                `Changed reference source '${before.type}' has no schema.`,
+            );
+        }
+
+        for (const property of definition.properties) {
+            if (property.name === "config_id" || property.name === "source_id") {
+                continue;
+            }
+
+            const previous = before.properties[property.name];
+            const target = this.catalog.target(property);
+
+            if (
+                !target ||
+                !this.catalog.dependent(target) ||
+                typeof previous !== "string" ||
+                after?.properties[property.name] === previous
+            ) {
+                continue;
+            }
+
+            const orphan = this.storage.getItem(target.name, previous);
+
+            if (
+                orphan &&
+                !this.sessions.active(orphan, context) &&
+                !this.catalog.hasOwner(orphan, context)
+            ) {
+                await this.remove(orphan, enabled, context);
+            }
+        }
+    }
+
+    private async remove(
+        record: StoredItem,
+        enabled: boolean,
+        context: ExecutionContext,
+    ): Promise<void> {
+        const request = Item.create(record.type, "delete");
+        request.setProperty("id", record.id);
+
+        if (!enabled) {
+            request.setAttribute("serverEvents", "0");
+        }
+
+        requireSuccess(await this.apply(request, context));
+    }
+}