@wasm-oj/server 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,221 @@
+import { Compiler, Runner, RuntimeDriverRegistry, TrustedJudgeProgram, ArtifactStore, JudgeEngineOptions, Engine } from '@wasm-oj/core';
+import { ServerToolchainSource, Project, BuildResult, WorkerProgress, BuildArtifact, RunConfig, RunResult, InteractiveRunConfig, InteractiveRunResult } from '@wasm-oj/contracts';
+export { ServerToolchainSource } from '@wasm-oj/contracts';
+
+interface VerifiedServerDistributionEvidence {
+    readonly compilerExecutable: string;
+    readonly compilerSha256: string;
+    readonly runtimeExecutable: string;
+    readonly runnerSha256: string;
+    readonly toolchains: readonly ServerToolchainSource[];
+    /** Descriptor asset path to the digest verified by immutable-container startup. */
+    readonly toolchainAssets: Readonly<Record<string, string>>;
+    readonly toolchainRootSha256: string;
+}
+interface VerifiedServerDistribution {
+    readonly compilerExecutable: string;
+    readonly runtimeExecutable: string;
+    readonly toolchainAssetFiles: Readonly<Record<string, string>>;
+    readonly toolchainRootSha256: string;
+}
+/** @internal Create a process-local capability from already verified container inventory. */
+declare function createVerifiedServerDistribution(evidence: VerifiedServerDistributionEvidence): VerifiedServerDistribution;
+
+interface ServerCompilerOptions {
+    /** Native `wasm-oj-compiler` executable built from `crates/runtime-core`. */
+    compilerExecutable: string;
+    /** Explicit package-owned toolchain sources. */
+    toolchains: readonly ServerToolchainSource[];
+    /** @internal Verified immutable-container capability. */
+    verifiedDistribution?: VerifiedServerDistribution;
+    /** @internal Inherited only by the private isolated build stage. */
+    verifiedToolchain?: boolean;
+}
+declare const IN_PROCESS_STAGE: unique symbol;
+interface ServerCompilerStageOptions extends ServerCompilerOptions {
+    /** @internal Canonical stage root inherited from the package entry process. */
+    stageDirectory: string;
+}
+/**
+ * Node/server compiler host using the exact language drivers and Wasmer
+ * packages used by the browser Worker.
+ */
+declare class ServerCompiler implements Compiler {
+    private readonly progressListeners;
+    private readonly compilerExecutable;
+    private readonly toolchains;
+    private initialization;
+    private generation;
+    private disposed;
+    private readonly inProcess;
+    private readonly verifiedToolchain;
+    private readonly stageDirectory;
+    private readonly activeChildren;
+    private activeOperation;
+    constructor(options: ServerCompilerOptions);
+    /** @internal */
+    constructor(options: ServerCompilerStageOptions, stage: typeof IN_PROCESS_STAGE);
+    cacheIdentity(project: Project): string;
+    ready(): Promise<void>;
+    build(project: Project, cacheKey: string): Promise<BuildResult>;
+    onProgress(listener: (progress: WorkerProgress) => void): () => void;
+    clearToolchainCache(): Promise<void>;
+    cancel(): void;
+    restart(): void;
+    dispose(): void;
+    private initialize;
+    private buildIsolated;
+    private compileRust;
+    private compilePython;
+    private compileGo;
+    private compileJava;
+    private runCompilerStage;
+    private loadToolchainAsset;
+    private loadToolchainFile;
+    private verifyToolchainAsset;
+    private beginOperation;
+    private endOperation;
+    private assertCurrent;
+    private isCurrent;
+    private terminateChildren;
+    private assertActive;
+}
+
+interface ServerRunnerOptions {
+    /** Native `wasm-oj-runner` executable built from `crates/runtime-core`. */
+    runtimeExecutable: string;
+    /** Explicit package-owned toolchain sources. */
+    toolchains: readonly ServerToolchainSource[];
+    /** Writable directory for deterministic runtime filesystem archives. */
+    cacheDirectory: string;
+    /** Optional runtime-driver registry, used by calibration and embedders. */
+    runtimeDrivers?: RuntimeDriverRegistry;
+    /** Calibrated profiles for downstream languages using the built-in runtime drivers. */
+    additionalCostBaselines?: Readonly<Record<string, number>>;
+    /** @internal Verified immutable-container capability. */
+    verifiedDistribution?: VerifiedServerDistribution;
+}
+declare class ServerRunner implements Runner {
+    private readonly runtimeExecutable;
+    private readonly toolchains;
+    private readonly cacheDirectory;
+    private readonly verifiedToolchain;
+    private readonly stageDirectory;
+    private resolvedCacheDirectory;
+    private readonly runtimeDrivers;
+    private readonly packageCommands;
+    private readonly packageFileSystems;
+    private readonly progressListeners;
+    private readonly streamListeners;
+    private initialization;
+    private readonly activeNativeRuns;
+    private readonly activePreparationStages;
+    private readonly inFlightRuns;
+    private activeOperation;
+    private cacheClearActive;
+    private generation;
+    private disposed;
+    constructor(options: ServerRunnerOptions);
+    ready(): Promise<void>;
+    run(artifact: BuildArtifact, config: RunConfig): Promise<RunResult>;
+    runTrusted(program: TrustedJudgeProgram, config: RunConfig): Promise<RunResult>;
+    interact(contestantArtifact: BuildArtifact, interactorArtifact: BuildArtifact, config: InteractiveRunConfig): Promise<InteractiveRunResult>;
+    interactTrusted(contestantArtifact: BuildArtifact, interactorProgram: TrustedJudgeProgram, config: InteractiveRunConfig): Promise<InteractiveRunResult>;
+    onProgress(listener: (progress: WorkerProgress) => void): () => void;
+    onStream(listener: (stream: "stdout" | "stderr", chunk: string) => void): () => void;
+    clearRuntimeCache(): Promise<void>;
+    cancel(): void;
+    cancelAndWait(): Promise<void>;
+    restart(): void;
+    dispose(): void;
+    private initialize;
+    private runtimeCacheDirectory;
+    private resolver;
+    private prepareWithDeadline;
+    private prepareInteractiveWithDeadline;
+    private prepareTrustedWithDeadline;
+    private loadQuickJsForOperation;
+    private loadQuickJs;
+    private packageCommand;
+    private assertPinnedPackageCommand;
+    private loadCompressedToolchainAsset;
+    private verifyDigest;
+    private packageFileSystem;
+    private loadOrExportPackageFileSystem;
+    private runPackageStage;
+    private readRuntimeCacheArchive;
+    private removeInvalidRuntimeCacheArchive;
+    private persistVerifiedRuntimeCacheArchive;
+    private reportRuntimeCacheIssue;
+    private runNativeCore;
+    private runNativeInteractive;
+    private progress;
+    private stream;
+    private assertCurrent;
+    private abortPreparationStages;
+    private terminateActiveNativeRuns;
+    private assertActive;
+    private assertArtifactToolchain;
+}
+
+interface DependencyCache {
+    load(integritySha256: string): Promise<Uint8Array | undefined>;
+    save(integritySha256: string, payload: Uint8Array): Promise<void>;
+    delete(integritySha256: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/** Atomic server-side content-addressed dependency cache. */
+declare class FileSystemDependencyCache implements DependencyCache {
+    private readonly directory;
+    private initialized;
+    constructor(directory: string);
+    load(integritySha256: string): Promise<Uint8Array | undefined>;
+    save(integritySha256: string, payload: Uint8Array): Promise<void>;
+    delete(integritySha256: string): Promise<void>;
+    clear(): Promise<void>;
+    private ready;
+    private pathFor;
+}
+
+/** Atomic, content-addressed artifact storage for the Node/server host. */
+declare class FileSystemArtifactStore implements ArtifactStore {
+    private readonly directory;
+    private initialized;
+    constructor(directory: string);
+    load(cacheKey: string): Promise<BuildArtifact | undefined>;
+    save(artifact: BuildArtifact): Promise<void>;
+    delete(cacheKey: string): Promise<void>;
+    clear(): Promise<void>;
+    private ready;
+    private pathFor;
+}
+
+interface ServerEngineOptions {
+    /** Directory containing provisioned `wasm-oj-compiler` and `wasm-oj-runner` binaries. */
+    runtimeDirectory: string;
+    /** Explicit package-owned toolchain sources. No toolchain is installed implicitly. */
+    toolchains: readonly ServerToolchainSource[];
+    /** Writable WASM-OJ cache root. Defaults to `<cwd>/.wasm-oj`. */
+    cacheDirectory?: string;
+    /** Set false to disable the server artifact cache. */
+    artifactCache?: boolean;
+    runtimeDrivers?: RuntimeDriverRegistry;
+    additionalCostBaselines?: Readonly<Record<string, number>>;
+    judge?: JudgeEngineOptions;
+    /** @internal Process-local capability emitted by container identity verification. */
+    verifiedDistribution?: VerifiedServerDistribution;
+}
+interface ResolvedServerPaths {
+    compilerExecutable: string;
+    runtimeExecutable: string;
+    toolchains: readonly ServerToolchainSource[];
+    cacheDirectory: string;
+}
+/** Resolve an explicitly provisioned WASM-OJ distribution without performing I/O. */
+declare function resolveServerPaths(options: ServerEngineOptions): ResolvedServerPaths;
+/** Verify the explicit local distribution and construct one ready server engine. */
+declare function createServerEngine(options: ServerEngineOptions): Promise<Engine>;
+
+export { FileSystemArtifactStore, FileSystemDependencyCache, ServerCompiler, ServerRunner, createServerEngine, createVerifiedServerDistribution, resolveServerPaths };
+export type { ResolvedServerPaths, ServerCompilerOptions, ServerEngineOptions, ServerRunnerOptions, VerifiedServerDistribution, VerifiedServerDistributionEvidence };