@innovatorstack/harness 0.0.0-stage → 0.1.1

package/src/methods/csharp/base-input.ts

@@ -0,0 +1,215 @@
+import { Item } from "../../items/item.js";
+import type { ItemNode } from "../../items/item.js";
+import { itemNodes, itemOrigin } from "../../items/origins.js";
+import { PlatformError } from "../../platform/errors.js";
+import { bindRequestDocument, requestDocument } from "../../platform/events/input.js";
+import { documentInput, documentRoot, readDocument, rememberDocument } from "./documents.js";
+import type { DocumentInput } from "./documents.js";
+import type { ManagedOrigins, OriginFrame } from "./origins.js";
+import { requestDifference } from "./request-change.js";
+import type { RequestChange } from "./request-change.js";
+
+export interface BaseInputChange {
+    readonly request?: RequestChange;
+    readonly origins: OriginFrame;
+    readonly document?: DocumentInput;
+    readonly documentChange?: RequestChange;
+    readonly documentOrigins?: OriginFrame;
+    readonly retainedDocument?: RequestChange;
+    readonly retainedOrigins?: OriginFrame;
+}
+
+export function decodeBaseInput(
+    payload: Record<string, unknown>,
+    origins: ManagedOrigins,
+): BaseInput {
+    if (typeof payload.xml !== "string") {
+        throw new PlatformError("InvalidProtocol", "A base action requires request XML.");
+    }
+
+    if (payload.document !== undefined && typeof payload.document !== "boolean") {
+        throw new PlatformError("InvalidProtocol", "The base document marker must be boolean.");
+    }
+
+    const item = new Item(readDocument(payload.xml));
+
+    if (item.getItemCount() !== 1 || item.isError() || item.payload.result !== undefined) {
+        throw new PlatformError(
+            "InvalidServerEventContext",
+            "A base action requires one request Item.",
+        );
+    }
+
+    origins.bind(item.payload, payload.origins);
+
+    if (payload.document === true) {
+        rememberDocument(item, payload.xml);
+    }
+
+    bindCurrentDocument(item, payload, origins);
+
+    return new BaseInput(item);
+}
+
+function bindCurrentDocument(
+    request: Item,
+    payload: Record<string, unknown>,
+    origins: ManagedOrigins,
+): void {
+    if (payload.currentDocument === undefined || payload.currentDocument === null) {
+        if (payload.currentOrigins !== undefined && payload.currentOrigins !== null) {
+            throw new PlatformError("InvalidProtocol", "Current document origins have no XML.");
+        }
+
+        return;
+    }
+
+    if (typeof payload.currentDocument !== "string") {
+        throw new PlatformError("InvalidProtocol", "Current base document XML must be text.");
+    }
+
+    const document = new Item(readDocument(payload.currentDocument));
+    origins.bind(document.payload, payload.currentOrigins);
+    const retained = new Set([...itemNodes(request.payload)].map(itemOrigin));
+
+    for (const node of itemNodes(document.payload)) {
+        if (retained.has(itemOrigin(node))) {
+            throw new PlatformError(
+                "InvalidProtocol",
+                "Detached base input and current document cannot share pending Item origins.",
+            );
+        }
+    }
+
+    rememberDocument(document, payload.currentDocument);
+    bindRequestDocument(request, document);
+}
+
+/** Keep the default action's selected node independent of its changing document. */
+export class BaseInput {
+    private readonly before;
+    private readonly selected;
+    private readonly root;
+    private readonly document;
+    private readonly beforeDocument;
+    private readonly selectedDocument;
+
+    constructor(readonly item: Item) {
+        this.before = item.clone().node;
+        this.selected = item.node;
+        this.document = requestDocument(item);
+        this.beforeDocument = this.document === item ? undefined : this.document.clone();
+        this.selectedDocument = this.document.getItemCount() === 1 ? this.document.node : undefined;
+        this.root = documentRoot(this.document);
+    }
+
+    change(origins: ManagedOrigins): BaseInputChange | undefined {
+        const current = this.document.payload.items[0];
+        const detached = !current || itemOrigin(current) !== itemOrigin(this.selected);
+        const captured = this.document === this.item && detached ? this.selected : this.item.node;
+        const request = requestDifference(this.before, captured);
+
+        if (!detached) {
+            if (documentRoot(this.document) !== this.root) {
+                throw new PlatformError(
+                    "UnsupportedRequestIdentity",
+                    "Moving a retained base request into another XML container is not qualified.",
+                );
+            }
+
+            return request ? { request, origins: origins.capture(this.item.payload) } : undefined;
+        }
+
+        if (this.document !== this.item && documentRoot(this.document) === this.root) {
+            return this.changedDocument(request, origins, captured);
+        }
+
+        const document = documentInput(this.document);
+
+        if (!document) {
+            throw new PlatformError(
+                "UnsupportedRequestIdentity",
+                "A replaced base document requires its native XML and captured request.",
+            );
+        }
+
+        this.assertReplacementOrigins();
+        const retainedDocument = this.retainedDocumentChange();
+
+        return {
+            ...(request ? { request } : {}),
+            origins: origins.capture({ items: [captured] }),
+            document,
+            documentOrigins: origins.capture(this.document.payload),
+            ...(retainedDocument && this.selectedDocument
+                ? {
+                      retainedDocument,
+                      retainedOrigins: origins.capture({ items: [this.selectedDocument] }),
+                  }
+                : {}),
+        };
+    }
+
+    private retainedDocumentChange(): RequestChange | undefined {
+        if (!this.beforeDocument || !this.selectedDocument) {
+            return undefined;
+        }
+
+        return requestDifference(this.beforeDocument.node, this.selectedDocument);
+    }
+
+    private assertReplacementOrigins(): void {
+        const originals = new Set([...itemNodes({ items: [this.before] })].map(itemOrigin));
+
+        if (this.beforeDocument) {
+            for (const node of itemNodes(this.beforeDocument.payload)) {
+                originals.add(itemOrigin(node));
+            }
+        }
+
+        for (const node of itemNodes(this.document.payload)) {
+            if (originals.has(itemOrigin(node))) {
+                throw new PlatformError(
+                    "UnsupportedRequestIdentity",
+                    "Moving retained input Items into a replacement document is not qualified.",
+                );
+            }
+        }
+    }
+
+    private changedDocument(
+        request: RequestChange | undefined,
+        origins: ManagedOrigins,
+        captured: ItemNode,
+    ): BaseInputChange | undefined {
+        if (!this.beforeDocument) {
+            throw new Error("A separate base document must retain its initial projection.");
+        }
+
+        if (this.beforeDocument.getItemCount() !== 1 || this.document.getItemCount() !== 1) {
+            if (Bun.deepEquals(this.beforeDocument.payload, this.document.payload)) {
+                return request
+                    ? { request, origins: origins.capture({ items: [captured] }) }
+                    : undefined;
+            }
+
+            throw new PlatformError(
+                "UnsupportedRequestIdentity",
+                "Changing the base document's scalar or collection requires a qualified XML mapping.",
+            );
+        }
+
+        const documentChange = requestDifference(this.beforeDocument.node, this.document.node);
+
+        if (!request && !documentChange) {
+            return undefined;
+        }
+
+        return {
+            ...(request ? { request } : {}),
+            origins: origins.capture({ items: [captured] }),
+            ...(documentChange ? { documentChange } : {}),
+            documentOrigins: origins.capture(this.document.payload),
+        };
+    }
+}

package/src/methods/csharp/cache.ts

@@ -0,0 +1,67 @@
+import { mkdir, readdir, rename, rm, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import { withTemporaryDirectory } from "../../core/resources.js";
+
+/** Publish complete builds atomically; another Bun process may share the same cache. */
+export async function cachedAssembly(
+    directory: string,
+    filename: string,
+    build: (staging: string) => Promise<void>,
+): Promise<string> {
+    await assertCacheDirectory(directory);
+    const assembly = join(directory, "bin", filename);
+
+    if (await Bun.file(assembly).exists()) {
+        return assembly;
+    }
+
+    await mkdir(dirname(directory), { recursive: true });
+
+    return await withTemporaryDirectory(`${directory}.build-`, async (staging) => {
+        await build(staging);
+
+        if (!(await Bun.file(join(staging, "bin", filename)).exists())) {
+            throw new Error("The managed build succeeded without producing its assembly.");
+        }
+
+        for (const name of await readdir(staging)) {
+            if (name !== "bin") {
+                await rm(join(staging, name), { recursive: true, force: true });
+            }
+        }
+
+        try {
+            await rename(staging, directory);
+        } catch (error) {
+            if (!isPublishRace(error) || !(await Bun.file(assembly).exists())) {
+                throw error;
+            }
+        }
+
+        return assembly;
+    });
+}
+
+async function assertCacheDirectory(directory: string): Promise<void> {
+    try {
+        const metadata = await stat(directory);
+
+        if (!metadata.isDirectory()) {
+            throw new Error("The managed cache destination must be a directory.");
+        }
+    } catch (error) {
+        if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+}
+
+function isPublishRace(error: unknown): boolean {
+    return (
+        error instanceof Error &&
+        "code" in error &&
+        // Windows reports an existing, in-use destination directory as EPERM.
+        (error.code === "EEXIST" || error.code === "ENOTEMPTY" || error.code === "EPERM")
+    );
+}

package/src/methods/csharp/callbacks.ts

@@ -0,0 +1,121 @@
+import { decodePayload, object } from "../../items/codec.js";
+import { Item } from "../../items/item.js";
+import { parseItems } from "../../items/xml.js";
+import { PlatformError } from "../../platform/errors.js";
+import type { MethodPorts } from "../types.js";
+import { decodeBaseInput } from "./base-input.js";
+import type { BaseInput, BaseInputChange } from "./base-input.js";
+import type { ManagedOrigins } from "./origins.js";
+import type { ManagedSecurity } from "./security.js";
+
+export interface ManagedCallbackState {
+    readonly origins: ManagedOrigins;
+    request?: BaseInput;
+}
+
+export function requestChange(state: ManagedCallbackState): BaseInputChange | undefined {
+    return state.request?.change(state.origins);
+}
+
+export async function managedCallback(
+    message: Record<string, unknown>,
+    ports: MethodPorts,
+    security: ManagedSecurity,
+    state: ManagedCallbackState,
+): Promise<Item> {
+    if (security.handles(message.operation)) {
+        return security.invoke(message.operation, message.payload, ports);
+    }
+
+    if (message.operation === "session") {
+        return new Item({ items: [], result: ports.getUserId() });
+    }
+
+    if (message.operation === "newId") {
+        if (!ports.getNewId) {
+            return ports.fail("The Method executor has no Item ID port.");
+        }
+
+        return new Item({ items: [], result: ports.getNewId() });
+    }
+
+    if (message.operation === "sql") {
+        return await sql(message.payload, ports);
+    }
+
+    if (message.operation === "eventBase") {
+        return await applyEventBase(message.payload, ports, state);
+    }
+
+    if (message.operation === "apply") {
+        return await ports.apply(new Item(decodePayload(message.payload)));
+    }
+
+    if (
+        message.operation === "aml" &&
+        object(message.payload) &&
+        typeof message.payload.xml === "string"
+    ) {
+        return await ports.applyAML(message.payload.xml);
+    }
+
+    if (message.operation === "method") {
+        return await method(message.payload, ports);
+    }
+
+    return ports.fail(
+        object(message.payload) && typeof message.payload.capability === "string"
+            ? message.payload.capability
+            : "Unsupported managed callback operation.",
+    );
+}
+
+async function applyEventBase(
+    payload: unknown,
+    ports: MethodPorts,
+    state: ManagedCallbackState,
+): Promise<Item> {
+    if (
+        !ports.serverEvent ||
+        !object(payload) ||
+        payload.name !== ports.serverEvent.name ||
+        typeof payload.xml !== "string"
+    ) {
+        return ports.fail("Native base actions require the matching active replacement event.");
+    }
+
+    const input = decodeBaseInput(payload, state.origins);
+    state.request = input;
+
+    return await ports.serverEvent.applyBase(input.item);
+}
+
+async function sql(payload: unknown, ports: MethodPorts): Promise<Item> {
+    if (!ports.applySQL || !object(payload) || typeof payload.sql !== "string") {
+        return ports.fail("T-SQL execution is not implemented.");
+    }
+
+    const parameters = payload.parameters;
+
+    if (parameters !== undefined && typeof parameters !== "string") {
+        throw new PlatformError("InvalidProtocol", "SQL parameters must be XML text.");
+    }
+
+    return await ports.applySQL(payload.sql, parameters);
+}
+
+async function method(payload: unknown, ports: MethodPorts): Promise<Item> {
+    if (!object(payload) || typeof payload.name !== "string" || typeof payload.body !== "string") {
+        throw new PlatformError("InvalidProtocol", "Method callbacks require a name and AML body.");
+    }
+
+    const context = parseItems(`<Item type="Method" action="get">${payload.body}</Item>`)[0];
+
+    if (!context) {
+        throw new PlatformError("InvalidMethodContext", "Missing Method context.");
+    }
+
+    context.setAction(payload.name);
+
+    return await ports.applyMethod(payload.name, context);
+}

package/src/methods/csharp/compiler.ts

@@ -0,0 +1,284 @@
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+import { Deadline } from "../../core/deadline.js";
+import { errorMessage } from "../../core/errors.js";
+import { readBinaryFile, readTextFile } from "../../core/files.js";
+import { readProcessOutput } from "../../core/process.js";
+import { PlatformError } from "../../platform/errors.js";
+import type { MethodDefinition } from "../types.js";
+import { cachedAssembly } from "./cache.js";
+import { methodBuildIdentity, methodCompilerArguments } from "./method-build.js";
+import { eventArgumentType, methodTemplate, renderMethod } from "./templates.js";
+
+export interface CSharpOptions {
+    readonly dotnet?: string;
+    readonly cacheDirectory?: string;
+    readonly references?: readonly string[];
+    readonly timeoutMs?: number;
+}
+
+export interface CompiledMethod {
+    readonly assembly: string;
+    readonly typeName: string;
+}
+
+const buildsMax = 128;
+const buildTimeoutMs = 60_000;
+const builds = new Map<string, Promise<string>>();
+const interopDirectory = Bun.fileURLToPath(new URL("managed/", import.meta.url));
+
+const hostBuildArguments = [
+    "build",
+    "Project.csproj",
+    "--nologo",
+    "--verbosity",
+    "quiet",
+    "--output",
+    "bin",
+];
+
+async function compileOnce(key: string, build: () => Promise<string>): Promise<string> {
+    const existing = builds.get(key);
+
+    if (existing) {
+        return await existing;
+    }
+
+    if (builds.size >= buildsMax) {
+        throw new PlatformError("CSharpUnavailable", "The managed build queue is full.");
+    }
+
+    const pending = build();
+    builds.set(key, pending);
+
+    try {
+        return await pending;
+    } finally {
+        builds.delete(key);
+    }
+}
+
+export class CSharpCompiler {
+    readonly references: readonly string[];
+    readonly dotnet: string;
+    readonly timeoutMs: number;
+    private readonly cache: string;
+    private hostBuild: Promise<string> | undefined;
+
+    constructor(options: CSharpOptions) {
+        this.dotnet = options.dotnet ?? "dotnet";
+        this.references = (options.references ?? []).map((path) => resolve(path));
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+
+        if (
+            !Number.isSafeInteger(this.timeoutMs) ||
+            this.timeoutMs < 1 ||
+            this.timeoutMs > 2_147_483_647
+        ) {
+            throw new TypeError(
+                "The C# timeout must be a positive integer within the timer range.",
+            );
+        }
+
+        if (this.references.length > 128) {
+            throw new TypeError("Too many C# reference assemblies were supplied.");
+        }
+
+        this.cache =
+            options.cacheDirectory ??
+            join(Bun.env.XDG_CACHE_HOME ?? tmpdir(), "innovator-harness", "csharp");
+    }
+
+    host(): Promise<string> {
+        this.hostBuild ??= this.compileHost();
+
+        return this.hostBuild;
+    }
+
+    private async compileHost(): Promise<string> {
+        const sourceDirectory = interopDirectory;
+        const files = [
+            "Protocol.cs",
+            "ProtocolInput.cs",
+            "ProtocolJson.cs",
+            "DomChanges.cs",
+            "Item.cs",
+            "ItemDocuments.cs",
+            "ManagedDocuments.cs",
+            "ItemXml.cs",
+            "PropertyItems.cs",
+            "LogicalData.cs",
+            "LogicalXml.cs",
+            "PayloadXml.cs",
+            "XmlTraversal.cs",
+            "WorkLimits.cs",
+            "Innovator.cs",
+            "CallContext.cs",
+            "ErrorLookup.cs",
+            "Identity.cs",
+            "Permissions.cs",
+            "RemoteContext.cs",
+            "MethodContext.cs",
+            "MethodAssemblies.cs",
+            "MethodInvocation.cs",
+            "ContextSafety.cs",
+            "Connections.cs",
+            "ServerEventArgs.cs",
+            "MethodEventArgs.cs",
+            "EventMetadata.cs",
+            "InOutInvocation.cs",
+            "ResponseXml.cs",
+            "RequestXml.cs",
+            "RequestRelationships.cs",
+            "RequestOrigins.cs",
+            "XmlProperties.cs",
+            "Program.cs",
+        ];
+        const sources = await Promise.all(
+            files.map(async (file) => ({
+                file,
+                bytes: await readBinaryFile(join(sourceDirectory, file)),
+            })),
+        );
+        const project = await readTextFile(join(sourceDirectory, "Worker.csproj"));
+        const nuget = await readTextFile(join(sourceDirectory, "NuGet.Config"));
+        const hash = new Bun.CryptoHasher("sha256").update("managed-worker-v3:net10.0");
+
+        for (const source of sources) {
+            hash.update(JSON.stringify([source.file, source.bytes.length])).update(source.bytes);
+        }
+
+        hash.update(JSON.stringify([project, nuget]));
+        const identity = hash.digest("hex");
+        const output = join(this.cache, "host", identity);
+
+        return await compileOnce(`${this.dotnet}:${output}`, () =>
+            cachedAssembly(output, "InnovatorHarness.Managed.dll", async (staging) => {
+                for (const source of sources) {
+                    await Bun.write(join(staging, source.file), source.bytes);
+                }
+
+                await this.writeProject(staging, project);
+                await this.build(staging, hostBuildArguments);
+            }),
+        );
+    }
+
+    async method(
+        method: MethodDefinition,
+        host: string,
+        eventName?: string,
+    ): Promise<CompiledMethod> {
+        const selected = methodTemplate(method.code);
+        const methodSource = await readTextFile(join(interopDirectory, selected));
+        const eventType = eventArgumentType(eventName);
+        const identity = await methodBuildIdentity(
+            { method, host, source: methodSource, event: eventType },
+            this.references,
+        );
+        const typeName = `InnovatorHarness.Generated.Method_${identity}`;
+        const output = join(this.cache, "methods", identity);
+        const assembly = await compileOnce(
+            `${this.dotnet}:${output}`,
+            async () =>
+                await cachedAssembly(output, `Method_${identity}.dll`, async (staging) => {
+                    const source = renderMethod(
+                        methodSource,
+                        method,
+                        `Method_${identity}`,
+                        eventType,
+                    );
+                    await Bun.write(join(staging, "Method.cs"), source);
+
+                    try {
+                        await this.build(
+                            staging,
+                            await methodCompilerArguments(
+                                host,
+                                staging,
+                                `Method_${identity}`,
+                                this.references,
+                            ),
+                        );
+                    } catch (error) {
+                        throw new PlatformError(
+                            "MethodCompilationFailed",
+                            `Cannot compile '${method.name}' from ` +
+                                `${method.source.file}:${method.source.line}. ${errorMessage(error)}`,
+                            { cause: error },
+                        );
+                    }
+                }),
+        );
+
+        return { assembly, typeName };
+    }
+
+    private async writeProject(directory: string, project: string): Promise<void> {
+        await Bun.write(join(directory, "Project.csproj"), project);
+        await Bun.write(
+            join(directory, "NuGet.Config"),
+            await readTextFile(join(interopDirectory, "NuGet.Config")),
+        );
+    }
+
+    private startCompiler(
+        directory: string,
+        arguments_: readonly string[],
+    ): Bun.Subprocess<"ignore", "pipe", "pipe"> {
+        try {
+            return Bun.spawn([this.dotnet, ...arguments_], {
+                cwd: directory,
+                stdin: "ignore",
+                stdout: "pipe",
+                stderr: "pipe",
+                timeout: 60_000,
+                env: {
+                    ...Bun.env,
+                    DOTNET_NOLOGO: "1",
+                    DOTNET_SKIP_FIRST_TIME_EXPERIENCE: "1",
+                    DOTNET_CLI_TELEMETRY_OPTOUT: "1",
+                },
+            });
+        } catch (error) {
+            throw new PlatformError(
+                "CSharpUnavailable",
+                "The C# executor requires an installed .NET 10 SDK. No SDK is downloaded automatically.",
+                { cause: error },
+            );
+        }
+    }
+
+    private async build(directory: string, arguments_: readonly string[]): Promise<void> {
+        const process = this.startCompiler(directory, arguments_);
+
+        using deadline = new Deadline(
+            buildTimeoutMs,
+            () =>
+                new PlatformError("CSharpBuildFailed", "The managed build exceeded its deadline."),
+        );
+        let result: [number, string, string];
+
+        try {
+            result = await deadline.wait(
+                Promise.all([
+                    process.exited,
+                    readProcessOutput(process.stdout, deadline.signal),
+                    readProcessOutput(process.stderr, deadline.signal),
+                ]),
+            );
+        } finally {
+            process.kill("SIGKILL");
+        }
+
+        const [exitCode, stdout, stderr] = result;
+
+        if (exitCode !== 0) {
+            throw new PlatformError(
+                "CSharpBuildFailed",
+                `Managed build failed (${exitCode}):\n${stdout}\n${stderr}`,
+            );
+        }
+    }
+}