ignotum 0.0.13 → 0.0.15

package/src/cli/build/managed-server.ts

@@ -0,0 +1,294 @@
+import { Crypto, Effect, Encoding, FileSystem, Path, Schema } from "effect";
+import { normalizePath, type Plugin } from "vite";
+import {
+  AppModuleId,
+  AppArtifactPath,
+  type AppArtifact,
+  type AppDefinition,
+  type AppModule,
+  type ModuleImport,
+  type UploadDeclaration,
+} from "@ignotum/contracts/app-definition";
+import { EnvironmentArtifact, serverEnvironmentPath } from "@ignotum/contracts/version";
+import {
+  artifactReference,
+  encodeCanonical,
+  schemaIdentity,
+  sha256,
+  utf8Bytes,
+  validateAppModuleBytes,
+  validateManagedServerDefinition,
+} from "@ignotum/versions";
+import { managedGuestExports } from "../managed-exports.js";
+import { moduleBoundariesPlugin } from "../module-boundaries.js";
+import { InvalidBuildOutput, runViteBuild, sourceMapPathTransform } from "./artifact.js";
+import type { ServerDiscoveryManifest } from "./server.js";
+
+export interface ManagedServerBuildResult {
+  readonly server: AppDefinition["server"];
+  readonly artifacts: ReadonlyArray<AppArtifact>;
+  readonly bytes: ReadonlyMap<string, Uint8Array>;
+  readonly environment: {
+    readonly bytes: Uint8Array;
+    readonly path: typeof serverEnvironmentPath;
+    readonly declaration: NonNullable<UploadDeclaration["environment"]>;
+  };
+}
+
+const literal = Schema.encodeSync(Schema.fromJsonString(Schema.String));
+const externals = managedGuestExports
+  .filter((entry) => entry.specifier !== "ignotum/internal/host")
+  .map((entry) => entry.specifier);
+
+export const compileManagedServer = Effect.fn("Deploy.compileManagedServer")(function* (
+  appDirectory: string,
+  outputDirectory: string,
+  conditions: ReadonlyArray<string>,
+  discovered: ServerDiscoveryManifest,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const crypto = yield* Crypto.Crypto;
+  const sources = new Map<string, string>();
+  const input: Record<string, string> = {};
+  const addEntry = (name: string, modulePath: string, exportName: string) => {
+    const id = `virtual:ignotum/managed-server/${name}`;
+    input[name] = id;
+    sources.set(
+      `\0${id}`,
+      `export { ${exportName} as default } from ${literal(normalizePath(modulePath))};\n`,
+    );
+  };
+  addEntry("schema", path.join(appDirectory, "server/schema.ts"), "default");
+  for (const [index, definition] of discovered.functions.entries()) {
+    addEntry(`function-${index}`, definition.modulePath, definition.exportName);
+  }
+  const emittedMaps = new Map<string, Uint8Array>();
+  const entryPlugin: Plugin = {
+    name: "ignotum:managed-server-entries",
+    resolveId: (id) => (sources.has(`\0${id}`) ? `\0${id}` : undefined),
+    load: (id) => sources.get(id),
+    generateBundle(_options, bundle) {
+      for (const item of Object.values(bundle)) {
+        if (item.type !== "chunk") continue;
+        if (item.map === null) {
+          if (Object.values(item.modules).some((module) => module.renderedLength > 0))
+            this.error(`Missing source map for app implementation '${item.fileName}'.`);
+          continue;
+        }
+        const encodedDirectory = JSON.stringify(normalizePath(appDirectory)).slice(1, -1);
+        emittedMaps.set(
+          `${item.fileName}.map`,
+          utf8Bytes(item.map.toString().replaceAll(encodedDirectory, "ignotum://app")),
+        );
+      }
+    },
+  };
+  const runPromise = Effect.runPromiseWith(yield* Effect.context<never>());
+  const packageNames = new Map<string, string | undefined>();
+  const packageName = Effect.fn("Deploy.managedServerPackageName")(function* (id: string) {
+    if (!path.isAbsolute(id)) return undefined;
+    let directory = path.dirname(id.split("?", 1)[0]!);
+    const start = directory;
+    if (packageNames.has(start)) return packageNames.get(start);
+    while (path.dirname(directory) !== directory) {
+      const manifest = path.join(directory, "package.json");
+      if (yield* fs.exists(manifest)) {
+        const metadata = yield* Schema.decodeUnknownEffect(
+          Schema.fromJsonString(Schema.Struct({ name: Schema.optional(Schema.String) })),
+        )(yield* fs.readFileString(manifest));
+        packageNames.set(start, metadata.name);
+        return metadata.name;
+      }
+      directory = path.dirname(directory);
+    }
+    packageNames.set(start, undefined);
+    return undefined;
+  });
+  const boundaries = yield* moduleBoundariesPlugin("Server", appDirectory);
+  const staging = yield* fs.makeTempDirectoryScoped({ prefix: "ignotum-managed-server-" });
+  const output = yield* runViteBuild("managed server graph", {
+    root: appDirectory,
+    configFile: false,
+    publicDir: false,
+    logLevel: "warn",
+    mode: "production",
+    resolve: { conditions: [...conditions], noExternal: true, tsconfigPaths: true },
+    plugins: [
+      boundaries,
+      entryPlugin,
+      {
+        name: "ignotum:managed-server-platform-boundary",
+        async transform(_code, id) {
+          const relative = normalizePath(path.relative(appDirectory, id));
+          if (
+            !relative.startsWith("../") &&
+            !path.isAbsolute(relative) &&
+            !relative.split("/").includes("node_modules")
+          )
+            return;
+          const owner = await runPromise(packageName(id));
+          if (
+            owner === "ignotum" ||
+            owner === "effect" ||
+            owner?.startsWith("@ignotum/") ||
+            owner?.startsWith("@effect/")
+          ) {
+            throw InvalidBuildOutput.make({
+              message: `App server graph embeds private platform implementation '${id}'.`,
+            });
+          }
+        },
+      },
+    ],
+    build: {
+      emptyOutDir: false,
+      minify: "oxc",
+      modulePreload: false,
+      outDir: staging,
+      sourcemap: true,
+      target: "es2020",
+      rolldownOptions: {
+        input,
+        external: externals,
+        preserveEntrySignatures: "strict",
+        output: {
+          format: "es",
+          entryFileNames: "[name].mjs",
+          chunkFileNames: "shared-[hash].mjs",
+          sourcemapPathTransform: yield* sourceMapPathTransform(appDirectory),
+        },
+      },
+    },
+  });
+  const chunks = output.filter((item) => item.type === "chunk");
+  if (chunks.some((chunk) => chunk.dynamicImports.length > 0))
+    return yield* InvalidBuildOutput.make({
+      message: "Managed server modules cannot use dynamic imports.",
+    });
+  if (output.some((item) => item.type === "asset" && !item.fileName.endsWith(".map")))
+    return yield* InvalidBuildOutput.make({
+      message: "Managed server modules cannot emit browser assets.",
+    });
+  const files = new Map<string, Uint8Array>();
+  for (const item of output)
+    files.set(item.fileName, yield* fs.readFile(path.join(staging, item.fileName)));
+  for (const chunk of chunks) {
+    const mapName = `${chunk.fileName}.map`;
+    if (yield* fs.exists(path.join(staging, mapName)))
+      files.set(mapName, yield* fs.readFile(path.join(staging, mapName)));
+  }
+  for (const [name, map] of emittedMaps) files.set(name, map);
+  // Hash the complete emitted inventory before assigning its namespace. Relative imports and
+  // cyclic chunks do not contain this digest, so naming never requires a hash fixed point.
+  const inventory = yield* Effect.forEach(
+    [...files].sort(([a], [b]) => a.localeCompare(b)),
+    ([name, bytes]) => sha256(bytes).pipe(Effect.map((digest) => ({ name, digest }))),
+  );
+  const graphDigest = yield* sha256(utf8Bytes(JSON.stringify(inventory)));
+  const moduleId = (file: string) => AppModuleId.make(`app/server/${graphDigest}/${file}`);
+  const artifacts: AppArtifact[] = [];
+  const bytes = new Map<string, Uint8Array>();
+  const modules: AppModule[] = [];
+  const chunkNames = new Set(chunks.map((chunk) => chunk.fileName));
+  for (const chunk of chunks) {
+    const id = moduleId(chunk.fileName);
+    const artifactPath = AppArtifactPath.make(`server/${graphDigest}/${chunk.fileName}`);
+    const sourceMap = AppArtifactPath.make(`${artifactPath}.map`);
+    const source = files.get(chunk.fileName)!;
+    const map = files.get(`${chunk.fileName}.map`);
+    const imports: ModuleImport[] = [];
+    for (const imported of chunk.imports) {
+      if (chunkNames.has(imported)) {
+        const relative = normalizePath(path.relative(path.dirname(chunk.fileName), imported));
+        imports.push({
+          kind: "App",
+          specifier: relative.startsWith(".") ? relative : `./${relative}`,
+          module: moduleId(imported),
+        });
+      } else if (imported === "ignotum/server")
+        imports.push({ kind: "Runtime", specifier: imported });
+      else if (imported === "ignotum/internal/server" || imported === "ignotum/internal/api")
+        imports.push({ kind: "Compiler", specifier: imported });
+      else
+        return yield* InvalidBuildOutput.make({
+          message: `Unsupported managed server import '${imported}'.`,
+        });
+    }
+    const baseModule = { id, artifact: artifactPath, imports };
+    const module: AppModule = map === undefined ? baseModule : { ...baseModule, sourceMap };
+    const artifact: AppArtifact = {
+      ...(yield* artifactReference(artifactPath, source)),
+      kind: "ServerModule",
+      visibility: "private",
+      contentType: "text/javascript",
+    };
+    yield* validateAppModuleBytes(module, artifact, source, chunk.isEntry ? ["default"] : []);
+    modules.push(module);
+    artifacts.push(artifact);
+    bytes.set(artifactPath, source);
+    if (map !== undefined) {
+      artifacts.push({
+        ...(yield* artifactReference(sourceMap, map)),
+        kind: "SourceMap",
+        visibility: "private",
+        contentType: "application/json",
+        owner: id,
+      });
+      bytes.set(sourceMap, map);
+    }
+  }
+  const reference = (name: string) => ({ module: moduleId(`${name}.mjs`), exportName: "default" });
+  const schemaEntry = reference("schema");
+  const server: AppDefinition["server"] = {
+    graph: {
+      entries: chunks.filter((chunk) => chunk.isEntry).map((chunk) => moduleId(chunk.fileName)),
+      modules,
+    },
+    functions: discovered.functions.map((definition, index) => {
+      const fn: AppDefinition["server"]["functions"][number] = {
+        address: definition.address,
+        kind: definition.kind,
+        entry: reference(`function-${index}`),
+        args: definition.args ?? { type: "object", fields: [] },
+        errors: definition.errors ?? { type: "never" },
+      };
+      return definition.returns === undefined ? fn : { ...fn, returns: definition.returns };
+    }),
+    schema: {
+      entry: schemaEntry,
+      descriptor: discovered.schema,
+      identity: yield* schemaIdentity(discovered.schema),
+      conversions: discovered.conversions.map((conversion) => ({
+        ...conversion,
+        entry: schemaEntry,
+      })),
+    },
+  };
+  yield* validateManagedServerDefinition(server, artifacts);
+  const environmentBytes = utf8Bytes(
+    `${encodeCanonical(EnvironmentArtifact, {
+      formatVersion: 1,
+      nonce: Encoding.encodeBase64Url(yield* crypto.randomBytes(32)),
+      values: discovered.environment.values,
+    })}\n`,
+  );
+  for (const [name, content] of bytes) {
+    const target = path.join(outputDirectory, name);
+    yield* fs.makeDirectory(path.dirname(target), { recursive: true });
+    yield* fs.writeFile(target, content);
+  }
+  return {
+    server,
+    artifacts,
+    bytes,
+    environment: {
+      bytes: environmentBytes,
+      path: serverEnvironmentPath,
+      declaration: {
+        artifact: yield* artifactReference(serverEnvironmentPath, environmentBytes),
+        fields: discovered.environment.fields,
+      },
+    },
+  } satisfies ManagedServerBuildResult;
+});

package/src/cli/build/managed.ts

@@ -0,0 +1,67 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { UploadDeclaration } from "@ignotum/contracts/app-definition";
+import { RuntimeRequirements } from "@ignotum/contracts/platform";
+import { encodeCanonical, validateUploadDeclaration, utf8Bytes } from "@ignotum/versions";
+import { generate } from "../codegen.js";
+import { replaceBuildDirectory } from "./output.js";
+import { managedCompatibility } from "../managed-exports.js";
+import { buildManagedClient } from "./managed-client.js";
+import { buildManagedServer } from "./server.js";
+
+export interface ManagedVersionBuildResult {
+  readonly declaration: UploadDeclaration;
+  readonly declarationBytes: Uint8Array;
+  readonly outputDirectory: string;
+  readonly bytes: ReadonlyMap<string, Uint8Array>;
+  readonly environment: { readonly path: string; readonly bytes: Uint8Array };
+}
+
+/** Platform selection never enters application bytes. */
+export const buildManagedVersion = Effect.fn("Deploy.buildManagedVersion")(function* (
+  appDirectory: string,
+  options: { readonly applicationName: string },
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const stateDirectory = path.join(appDirectory, ".ignotum");
+  const outputDirectory = path.join(stateDirectory, "build");
+  yield* fs.makeDirectory(stateDirectory, { recursive: true });
+  const generated = yield* generate(appDirectory);
+  return yield* Effect.scoped(
+    Effect.gen(function* () {
+      const staging = yield* Effect.acquireRelease(
+        fs.makeTempDirectory({ directory: stateDirectory, prefix: ".build-staging-" }),
+        (directory) => fs.remove(directory, { force: true, recursive: true }).pipe(Effect.orDie),
+      );
+      const client = yield* buildManagedClient(appDirectory, staging, options);
+      const server = yield* buildManagedServer(appDirectory, staging, generated.functionModules);
+      const requirements = yield* Schema.decodeUnknownEffect(RuntimeRequirements)({
+        clientApiVersion: managedCompatibility.clientApiVersion,
+        serverApiVersion: managedCompatibility.serverApiVersion,
+        capabilities: managedCompatibility.capabilities,
+      });
+      const declaration = yield* validateUploadDeclaration({
+        formatVersion: 1,
+        definition: {
+          formatVersion: 1,
+          appName: client.appName,
+          requirements,
+          client: client.client,
+          server: server.server,
+          artifacts: [...client.artifacts, ...server.artifacts],
+        },
+        environment: server.environment.declaration,
+      });
+      const declarationBytes = utf8Bytes(`${encodeCanonical(UploadDeclaration, declaration)}\n`);
+      yield* fs.writeFile(path.join(staging, "declaration.json"), declarationBytes);
+      yield* replaceBuildDirectory(stateDirectory, staging, outputDirectory);
+      return {
+        declaration,
+        declarationBytes,
+        outputDirectory,
+        bytes: new Map([...client.bytes, ...server.bytes]),
+        environment: { path: server.environment.path, bytes: server.environment.bytes },
+      } satisfies ManagedVersionBuildResult;
+    }),
+  );
+});

package/src/cli/build/output.ts

@@ -0,0 +1,47 @@
+import { Effect, FileSystem, Result, Schema } from "effect";
+
+export class BuildReplacementFailed extends Schema.TaggedError<BuildReplacementFailed>()(
+  "BuildReplacementFailed",
+  {
+    backupPath: Schema.String,
+    cause: Schema.Defect(),
+    message: Schema.String,
+  },
+) {}
+
+export const replaceBuildDirectory = Effect.fn("Deploy.replaceBuildDirectory")(function* (
+  stateDirectory: string,
+  stagingDirectory: string,
+  buildDirectory: string,
+) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const currentExists = yield* fileSystem.exists(buildDirectory);
+  if (!currentExists) {
+    yield* fileSystem.rename(stagingDirectory, buildDirectory);
+    return;
+  }
+
+  const backupPath = yield* fileSystem.makeTempDirectory({
+    directory: stateDirectory,
+    prefix: ".build-backup-",
+  });
+  yield* fileSystem.remove(backupPath, { recursive: true });
+  yield* fileSystem.rename(buildDirectory, backupPath);
+
+  const replacement = yield* Effect.result(fileSystem.rename(stagingDirectory, buildDirectory));
+  if (Result.isSuccess(replacement)) {
+    yield* fileSystem.remove(backupPath, { recursive: true });
+    return;
+  }
+
+  const restoration = yield* Effect.result(fileSystem.rename(backupPath, buildDirectory));
+  if (Result.isFailure(restoration)) {
+    return yield* BuildReplacementFailed.make({
+      backupPath,
+      cause: restoration.failure,
+      message: `Could not install the new build or restore the previous build. The previous build remains at ${backupPath}.`,
+    });
+  }
+
+  return yield* replacement.failure;
+});