@innovatorstack/harness 0.0.0-stage → 0.1.1

package/src/methods/csharp/retained-items.ts

@@ -0,0 +1,128 @@
+import { setOwn } from "../../core/data.js";
+import type { ItemNode, ItemPayload } from "../../items/item.js";
+import { decodeLogical } from "../../items/logical.js";
+import { itemNodes, itemOrigin } from "../../items/origins.js";
+import { PlatformError } from "../../platform/errors.js";
+
+/** Reconcile one invocation's wire projections without rebinding retained Item nodes. */
+export class RetainedItems {
+    private readonly original = new Map<symbol, ItemNode>();
+
+    constructor(payload: ItemPayload) {
+        for (const node of itemNodes(payload)) {
+            this.original.set(requiredOrigin(node), node);
+        }
+    }
+
+    synchronize(payloads: readonly ItemPayload[]): void {
+        const sources = new Map<symbol, ItemNode>();
+        const canonical = new Map<unknown, ItemNode>();
+
+        for (const payload of payloads) {
+            for (const node of itemNodes(payload)) {
+                const origin = requiredOrigin(node);
+                const previous = sources.get(origin);
+
+                if (previous && !sameProjection(previous, node)) {
+                    throw new PlatformError(
+                        "InvalidProtocol",
+                        "Managed document and retained input disagree about the same Item.",
+                    );
+                }
+
+                const source = previous ?? node;
+                sources.set(origin, source);
+                canonical.set(node, this.original.get(origin) ?? source);
+            }
+        }
+
+        const patches = [...sources.values()].map((source) => ({
+            target: requireCanonical(canonical, source),
+            projection: projectNode(source, canonical),
+        }));
+        const roots = payloads.map((payload) =>
+            payload.items.map((node) => requireCanonical(canonical, node)),
+        );
+
+        // Validate every projection before changing any retained caller object.
+        for (const { target, projection } of patches) {
+            Object.assign(target, projection);
+
+            if (projection.logical === undefined) {
+                delete target.logical;
+            }
+        }
+
+        for (const [index, payload] of payloads.entries()) {
+            const selected = roots[index];
+
+            if (!selected) {
+                throw new Error("Every managed payload must retain its projected roots.");
+            }
+
+            payload.items = selected;
+        }
+    }
+}
+
+function projectNode(source: ItemNode, canonical: ReadonlyMap<unknown, ItemNode>): ItemNode {
+    const propertyItems: Record<string, ItemNode> = {};
+
+    for (const [name, item] of Object.entries(source.propertyItems)) {
+        setOwn(propertyItems, name, requireCanonical(canonical, item));
+    }
+
+    return {
+        type: source.type,
+        attributes: source.attributes,
+        properties: source.properties,
+        propertyAttributes: source.propertyAttributes,
+        propertyItems,
+        relationships: source.relationships.map((node) => requireCanonical(canonical, node)),
+        ...(source.logical
+            ? {
+                  logical: decodeLogical(source.logical, (node) =>
+                      requireCanonical(canonical, node),
+                  ),
+              }
+            : {}),
+    };
+}
+
+function requireCanonical(canonical: ReadonlyMap<unknown, ItemNode>, node: unknown): ItemNode {
+    const selected = canonical.get(node);
+
+    if (!selected) {
+        throw new PlatformError("InvalidProtocol", "A managed Item projection has no source.");
+    }
+
+    return selected;
+}
+
+export function requiredOrigin(node: ItemNode): symbol {
+    const origin = itemOrigin(node);
+
+    if (origin === undefined) {
+        throw new PlatformError("InvalidProtocol", "A managed Item has no invocation origin.");
+    }
+
+    return origin;
+}
+
+function sameProjection(left: ItemNode, right: ItemNode): boolean {
+    if (!Bun.deepEquals(left, right)) {
+        return false;
+    }
+
+    const previous = itemNodes({ items: [left] });
+
+    for (const node of itemNodes({ items: [right] })) {
+        const selected = previous.next();
+
+        if (selected.done || requiredOrigin(selected.value) !== requiredOrigin(node)) {
+            return false;
+        }
+    }
+
+    return previous.next().done === true;
+}

package/src/methods/csharp/security.ts

@@ -0,0 +1,121 @@
+import { requestOperationsMax } from "../../core/limits.js";
+import { object } from "../../items/codec.js";
+import { Item } from "../../items/item.js";
+import { PlatformError } from "../../platform/errors.js";
+import type { MethodPorts } from "../types.js";
+
+const operations = new Set([
+    "securityIdentities",
+    "securityIdentity",
+    "securityGrant",
+    "securityRevoke",
+]);
+
+/** Tokens belong to one managed invocation; they never consume business Item identities. */
+export class ManagedSecurity implements Disposable {
+    private readonly grants = new Map<string, Disposable>();
+    private nextToken = 0;
+    private closed = false;
+
+    handles(operation: unknown): boolean {
+        return typeof operation === "string" && operations.has(operation);
+    }
+
+    invoke(operation: unknown, payload: unknown, ports: MethodPorts): Item {
+        const security = ports.security;
+
+        if (this.closed) {
+            throw new PlatformError(
+                "ExpiredSecurityScope",
+                "The managed security scope has completed.",
+            );
+        }
+
+        if (!security) {
+            return ports.fail("The Method executor has no native security port.");
+        }
+
+        if (operation === "securityIdentities") {
+            return new Item({ items: [], result: security.getIdentities().join(",") });
+        }
+
+        if (!object(payload)) {
+            throw new PlatformError(
+                "InvalidProtocol",
+                "Native security requests need an object payload.",
+            );
+        }
+
+        if (operation === "securityIdentity" && typeof payload.name === "string") {
+            const identity = security.getIdentityByName(payload.name);
+
+            if (!identity) {
+                return new Item({ items: [] });
+            }
+
+            const item = Item.create("Identity");
+            item.setProperty("id", identity.id);
+            item.setProperty("name", identity.name);
+
+            return item;
+        }
+
+        if (operation === "securityGrant" && typeof payload.id === "string") {
+            if (this.nextToken >= requestOperationsMax) {
+                throw new PlatformError(
+                    "ProtocolLimit",
+                    "Managed identity grants exceed their invocation budget.",
+                );
+            }
+
+            const token = String(++this.nextToken);
+            this.grants.set(token, security.grantIdentity(payload.id));
+
+            return new Item({ items: [], result: token });
+        }
+
+        if (operation === "securityRevoke" && typeof payload.token === "string") {
+            return this.revoke(payload.token);
+        }
+
+        throw new PlatformError("InvalidProtocol", "Unknown or malformed native security request.");
+    }
+
+    [Symbol.dispose](): void {
+        this.closed = true;
+        const failures: unknown[] = [];
+
+        for (const grant of this.grants.values()) {
+            try {
+                grant[Symbol.dispose]();
+            } catch (error) {
+                failures.push(error);
+            }
+        }
+
+        this.grants.clear();
+
+        if (failures.length > 0) {
+            throw new AggregateError(
+                failures,
+                "Managed identity grants could not all be disposed.",
+            );
+        }
+    }
+
+    private revoke(token: string): Item {
+        const grant = this.grants.get(token);
+
+        if (!grant) {
+            throw new PlatformError(
+                "InvalidSecurityGrant",
+                "The identity grant does not belong to this invocation.",
+            );
+        }
+
+        grant[Symbol.dispose]();
+        this.grants.delete(token);
+
+        return new Item({ items: [] });
+    }
+}

package/src/methods/csharp/templates.ts

@@ -0,0 +1,92 @@
+import { PlatformError } from "../../platform/errors.js";
+import type { MethodDefinition } from "../types.js";
+
+const baseEventArguments: ReadonlyMap<string, string> = new Map([
+    ["onget", "Aras.Server.Core.OnGetEventArgs"],
+    ["onadd", "Aras.Server.Core.OnAddEventArgs"],
+    ["onupdate", "Aras.Server.Core.OnUpdateEventArgs"],
+    ["ondelete", "Aras.Server.Core.OnDeleteEventArgs"],
+    ["onlock", "Aras.Server.Core.OnLockEventArgs"],
+    ["onunlock", "Aras.Server.Core.OnUnlockEventArgs"],
+    ["onpromote", "Aras.Server.Core.OnPromoteEventArgs"],
+]);
+const baseArgumentTypes = new Set(baseEventArguments.values());
+const eventArguments: ReadonlyMap<string, string> = new Map([
+    ...baseEventArguments,
+    ["onbeforeupdate", "Aras.Server.Core.OnBeforeUpdateEventArgs"],
+    ["onafteradd", "Aras.Server.Core.OnAfterAddEventArgs"],
+    ["onafterupdate", "Aras.Server.Core.OnAfterUpdateEventArgs"],
+    ["onafterversion", "Aras.Server.Core.AfterVersionEventArgs"],
+]);
+
+export function methodTemplate(code: string): string {
+    for (const line of code.split(/\r?\n/u)) {
+        const content = line.trim();
+
+        if (!content.startsWith("//") && content.length > 0) {
+            break;
+        }
+
+        const match = /^\/\/\s*MethodTemplateName\s*=\s*([A-Za-z][\w]*)\s*;\s*$/u.exec(content);
+        const name = match?.[1];
+
+        if (name === "CSharpInOut") {
+            return "InOut.cs.template";
+        }
+
+        if (name !== undefined && name !== "CSharp") {
+            throw new PlatformError(
+                "UnsupportedMethodTemplate",
+                `C# template '${name}' is unavailable.`,
+            );
+        }
+    }
+
+    return "Method.cs.template";
+}
+
+export function eventArgumentType(name: string | undefined): string {
+    if (name === undefined) {
+        return "Aras.Server.Core.ServerEventArgs";
+    }
+
+    const type = eventArguments.get(name.toLowerCase());
+
+    if (!type) {
+        throw new PlatformError(
+            "UnsupportedEventData",
+            `CSharpInOut event data for '${name}' is unavailable.`,
+        );
+    }
+
+    return type;
+}
+
+export function renderMethod(
+    source: string,
+    method: MethodDefinition,
+    typeName: string,
+    eventType: string,
+): string {
+    const replacements = new Map([
+        ["__TYPE_NAME__", typeName],
+        ["__SOURCE_LINE__", String(method.source.line)],
+        ["__SOURCE_PATH__", method.source.file.replaceAll("\\", "\\\\").replaceAll('"', '\\"')],
+        ["__METHOD_CODE__", method.code],
+        ["__EVENT_ARGS_TYPE__", eventType],
+        [
+            "__EVENT_ARGS_CONSTRUCTOR__",
+            `new ${eventType}(${baseArgumentTypes.has(eventType) ? "Remote, InputDocument" : "Remote"})`,
+        ],
+    ]);
+
+    return source.replaceAll(/__[A-Z_]+__/gu, (placeholder) => {
+        const value = replacements.get(placeholder);
+
+        if (value === undefined) {
+            throw new Error(`Missing managed template value '${placeholder}'.`);
+        }
+
+        return value;
+    });
+}

package/src/methods/csharp/worker.ts

@@ -0,0 +1,234 @@
+import { PlatformError } from "../../platform/errors.js";
+import { encodeMessage, pendingCallsMax, readMessages } from "./protocol.js";
+
+export type ManagedProcess = Bun.Subprocess<"pipe", "pipe", "inherit">;
+
+const contextsPerWorkerMax = 32;
+const workers = new Set<ManagedWorker>();
+
+export interface WorkerReceiver {
+    message(value: Record<string, unknown>): void;
+    failed(error: unknown): void;
+}
+
+/** Own the process transport independently of a world's collectible managed context. */
+export class ManagedWorker {
+    readonly process: ManagedProcess;
+    private receiver: WorkerReceiver | undefined;
+    private stopped = false;
+    private contexts = 0;
+    private readonly invocations = new Set<string>();
+    private resumeReading: ((active: boolean) => void) | undefined;
+    reusable = true;
+    private resetPending:
+        | { resolve(): void; reject(error: unknown): void; timer: ReturnType<typeof setTimeout> }
+        | undefined;
+    ready: Promise<void> = Promise.resolve();
+
+    constructor(dotnet: string, host: string, references: readonly string[]) {
+        this.process = Bun.spawn([dotnet, host, ...references], {
+            stdin: "pipe",
+            stdout: "pipe",
+            stderr: "inherit",
+        });
+        workers.add(this);
+        void this.observe();
+    }
+
+    attach(receiver: WorkerReceiver): void {
+        if (this.stopped || this.receiver) {
+            throw new PlatformError(
+                "WorkerUnavailable",
+                "The C# worker cannot accept another owner.",
+            );
+        }
+
+        this.receiver = receiver;
+        this.process.ref();
+        this.process.stdin.ref();
+    }
+
+    get available(): boolean {
+        return !this.stopped && this.process.exitCode === null;
+    }
+
+    expectInvocation(id: string): void {
+        if (this.stopped || this.invocations.has(id) || this.invocations.size >= pendingCallsMax) {
+            throw new PlatformError(
+                "ProtocolLimit",
+                "The C# invocation queue is unavailable or full.",
+            );
+        }
+
+        this.invocations.add(id);
+        this.wakeReader(true);
+    }
+
+    release(): void {
+        this.receiver = undefined;
+        this.contexts += 1;
+
+        if (
+            this.contexts >= contextsPerWorkerMax ||
+            this.resetPending ||
+            this.invocations.size > 0
+        ) {
+            this.close();
+
+            return;
+        }
+
+        this.ready = new Promise<void>((resolve, reject) => {
+            const timer = setTimeout(
+                () =>
+                    this.close(
+                        new PlatformError("WorkerUnavailable", "C# context reset timed out."),
+                    ),
+                1000,
+            );
+            timer.unref();
+            this.resetPending = { resolve, reject, timer };
+        });
+        void this.ready.catch(() => {
+            /* Acquisition observes reset failures before reuse. */
+        });
+        this.wakeReader(true);
+        void this.resetContext();
+        this.process.unref();
+        this.process.stdin.unref();
+    }
+
+    private async resetContext(): Promise<void> {
+        try {
+            await this.process.stdin.write(encodeMessage({ kind: "reset", id: "reset" }));
+            await this.process.stdin.flush();
+        } catch (error) {
+            this.close(error);
+        }
+    }
+
+    close(error: unknown = new PlatformError("WorkerExited", "The C# worker closed.")): void {
+        if (this.stopped) {
+            return;
+        }
+
+        this.stopped = true;
+        workers.delete(this);
+        this.invocations.clear();
+        this.wakeReader(false);
+        this.process.kill("SIGKILL");
+        const reset = this.resetPending;
+        this.resetPending = undefined;
+
+        if (reset) {
+            clearTimeout(reset.timer);
+            reset.reject(error);
+        }
+
+        const receiver = this.receiver;
+        this.receiver = undefined;
+        receiver?.failed(error);
+    }
+
+    private receive(message: Record<string, unknown>): void {
+        if (message.reusable === false) {
+            this.reusable = false;
+        }
+
+        if (message.kind === "result" || message.kind === "failure") {
+            this.invocations.delete(String(message.id));
+        }
+
+        if (message.kind === "reset" && this.resetPending) {
+            const reset = this.resetPending;
+            this.resetPending = undefined;
+            clearTimeout(reset.timer);
+            reset.resolve();
+        } else if (this.receiver) {
+            this.receiver.message(message);
+        } else {
+            this.close(
+                new PlatformError("InvalidProtocol", "An idle C# worker emitted a request."),
+            );
+        }
+    }
+
+    private readWhenActive(): boolean | Promise<boolean> {
+        // Keep an owned pipe armed between calls. Reset acknowledgement ends the active world.
+        if (this.stopped || this.receiver || this.resetPending || this.invocations.size > 0) {
+            return !this.stopped;
+        }
+
+        return new Promise<boolean>((resolve) => {
+            this.resumeReading = resolve;
+        });
+    }
+
+    private wakeReader(active: boolean): void {
+        const resume = this.resumeReading;
+        this.resumeReading = undefined;
+        resume?.(active);
+    }
+
+    private async observe(): Promise<void> {
+        try {
+            await Promise.all([
+                readMessages(
+                    this.process.stdout,
+                    (message) => this.receive(message),
+                    () => this.readWhenActive(),
+                ),
+                this.process.exited.then((exit) =>
+                    this.close(new PlatformError("WorkerExited", `C# worker exited (${exit}).`)),
+                ),
+            ]);
+        } catch (error) {
+            this.close(error);
+        }
+    }
+}
+
+let idle: { readonly key: string; readonly worker: ManagedWorker } | undefined;
+
+process.once("beforeExit", () => {
+    idle?.worker.close();
+    idle = undefined;
+});
+
+process.once("exit", () => {
+    for (const worker of workers) {
+        worker.close();
+    }
+});
+
+export async function acquireWorker(
+    dotnet: string,
+    host: string,
+    references: readonly string[],
+): Promise<ManagedWorker> {
+    const key = JSON.stringify([dotnet, host, references]);
+
+    if (idle?.key === key && idle.worker.available) {
+        const worker = idle.worker;
+        idle = undefined;
+
+        try {
+            await worker.ready;
+
+            if (worker.available) {
+                return worker;
+            }
+        } catch {
+            // Reuse is optional. A failed reset belongs to the disposed context.
+            worker.close();
+        }
+    }
+
+    return new ManagedWorker(dotnet, host, references);
+}
+
+export function releaseWorker(key: string, worker: ManagedWorker): void {
+    idle?.worker.close();
+    worker.release();
+    idle = { key, worker };
+}

package/src/methods/event-data.ts

@@ -0,0 +1,39 @@
+export enum MethodEventDataKind {
+    BeforeUpdate = "onBeforeUpdate",
+    AfterAdd = "onAfterAdd",
+    AfterUpdate = "onAfterUpdate",
+    AfterVersion = "onAfterVersion",
+}
+
+export interface BeforeUpdateEventData {
+    readonly kind: MethodEventDataKind.BeforeUpdate;
+    readonly id: string;
+    readonly idList: readonly string[];
+}
+
+export interface AfterAddEventData {
+    readonly kind: MethodEventDataKind.AfterAdd;
+    readonly typeId: string;
+    readonly id: string;
+    readonly idList: readonly string[];
+}
+
+export interface AfterUpdateEventData {
+    readonly kind: MethodEventDataKind.AfterUpdate;
+    readonly typeId: string;
+    readonly id: string | null;
+    readonly oldIdsNewIdsMap: Readonly<Record<string, string>>;
+}
+
+export interface AfterVersionEventData {
+    readonly kind: MethodEventDataKind.AfterVersion;
+    readonly typeId: string;
+    readonly newItemId: string;
+    readonly oldIdsNewIdsMap: Readonly<Record<string, string>>;
+}
+
+export type MethodEventData =
+    | BeforeUpdateEventData
+    | AfterAddEventData
+    | AfterUpdateEventData
+    | AfterVersionEventData;

package/src/methods/types.ts

@@ -0,0 +1,59 @@
+import type { SourceLocation } from "../diagnostics/source-location.js";
+import type { Item } from "../items/item.js";
+import type { MethodEventData } from "./event-data.js";
+
+export { MethodEventDataKind } from "./event-data.js";
+export type {
+    MethodEventData,
+    BeforeUpdateEventData,
+    AfterAddEventData,
+    AfterUpdateEventData,
+    AfterVersionEventData,
+} from "./event-data.js";
+
+export interface MethodDefinition {
+    readonly id: string;
+    readonly name: string;
+    readonly language: string;
+    readonly code: string;
+    readonly hash: string;
+    readonly source: SourceLocation;
+}
+
+export interface MethodPorts {
+    /** Notify when source evaluation begins, after compilation and host setup. */
+    executionStarted?(): void;
+    getUserId(): string;
+    getNewId?(): string;
+    apply(item: Item): Promise<Item>;
+    applyAML(xml: string): Promise<Item>;
+    applyMethod(name: string, context: Item): Promise<Item>;
+    applySQL?(query: string, parameters?: string): Promise<Item>;
+    readonly security?: MethodSecurity;
+    readonly serverEvent?: MethodServerEvent;
+    readonly eventData?: MethodEventData;
+    fail(message: string): never;
+}
+
+export interface MethodServerEvent {
+    readonly name: string;
+    applyBase(request: Item): Promise<Item>;
+}
+
+export interface MethodIdentity {
+    readonly id: string;
+    readonly name: string;
+}
+
+export interface MethodSecurity {
+    getIdentities(): readonly string[];
+    getIdentityByName(name: string): MethodIdentity | undefined;
+    grantIdentity(id: string): Disposable;
+}
+
+export interface MethodExecutor {
+    readonly language: string;
+    execute(method: MethodDefinition, context: Item, ports: MethodPorts): Promise<Item>;
+    reset?(): void;
+    dispose?(): void;
+}