alchemy 2.0.0-beta.74 → 2.0.0-beta.76

package/src/Util/extraFiles.ts

@@ -0,0 +1,246 @@
+/**
+ * Extra files packed next to a Fly/Hetzner/Railway program (Docker
+ * context or unit zip).
+ *
+ * `dest: "."` means "this directory IS the image/unit root" (`COPY . /app`),
+ * not a subfolder. {@link contextRootOf} then treats that source as the
+ * context, and {@link posixRelUnder} places `main` relative to it so
+ * `isExternal` ENTRYPOINT is `node /app/serve-node.mjs` instead of
+ * bundling `index.mjs`. Hashing skips gitignore (a parent `dist` rule
+ * would empty the hash) but still excludes `node_modules` / `.git` /
+ * `.next/cache` / `.alchemy` so the glob stays bounded.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { hashDirectory } from "../Command/Memo.ts";
+import { initialCwd } from "./Node.ts";
+import { sha256 } from "./sha256.ts";
+
+const ioConcurrency = 16;
+
+/** Extra-file dest that means "merge this directory into the image/unit root". */
+export const CONTEXT_ROOT_DEST = ".";
+
+export const isContextRootDest = (dest: string): boolean =>
+  dest === "." || dest === "";
+
+/**
+ * Hash extra-file trees without gitignore (a parent `dist` rule would
+ * empty the hash) but skip the directories that make a recursive glob
+ * unbounded.
+ */
+export const EXTRA_FILES_HASH_EXCLUDE = [
+  "**/node_modules/**",
+  "**/.git/**",
+  "**/.next/cache/**",
+  "**/.alchemy/**",
+];
+
+/**
+ * Extra file or directory copied next to a bundled program (Docker
+ * context, unit archive, …). `dest` is relative to the image/unit root.
+ */
+export interface ExtraFile {
+  /** Local file or directory (absolute, or relative to {@link initialCwd}). */
+  readonly source: string;
+  /**
+   * Destination relative to the image/unit root (e.g. `"dist"`, `".next"`).
+   * `"."` means merge into the root.
+   */
+  readonly dest: string;
+}
+
+const posix = (value: string): string => value.replaceAll("\\", "/");
+
+/**
+ * Path of `file` relative to `root`, POSIX. Empty string if they are the
+ * same directory. Returns `undefined` when `file` is not under `root`.
+ */
+export const posixRelUnder = (
+  root: string,
+  file: string,
+  path: {
+    readonly resolve: (...segments: string[]) => string;
+    readonly relative: (from: string, to: string) => string;
+    readonly isAbsolute: (value: string) => boolean;
+  },
+): string | undefined => {
+  const from = posix(path.resolve(root));
+  const to = posix(path.resolve(file));
+  const rel = posix(path.relative(from, to));
+  if (rel === "") return "";
+  if (path.isAbsolute(rel) || rel === ".." || rel.startsWith("../")) {
+    return undefined;
+  }
+  return rel;
+};
+
+/**
+ * Docker/zip context root for an unbundled (`isExternal`) program. If
+ * some extraFile is `dest: "."`, that source is the context; otherwise
+ * the context is `dirname(main)`.
+ */
+export const contextRootOf = (
+  main: string,
+  extraFiles: ReadonlyArray<{ source: string; dest: string }>,
+  path: Path.Path,
+  resolveSource: (source: string) => string,
+): string => {
+  const root = extraFiles.find((file) => isContextRootDest(file.dest));
+  return root !== undefined ? resolveSource(root.source) : path.dirname(main);
+};
+
+/** Normalize a COPY destination so it cannot escape the root. `"."` is the root. */
+export const extraFileDestination = (destination: string): string => {
+  const normalized = destination.replaceAll("\\", "/").replace(/^\/+/, "");
+  if (isContextRootDest(normalized)) return CONTEXT_ROOT_DEST;
+  const parts = normalized
+    .split("/")
+    .filter((part) => part.length > 0 && part !== "." && part !== "..");
+  return parts.length === 0 ? "dist" : parts.join("/");
+};
+
+export const resolveExtraSource = (
+  source: string,
+  path: {
+    readonly isAbsolute: (value: string) => boolean;
+    readonly resolve: (...segments: string[]) => string;
+  },
+) => (path.isAbsolute(source) ? source : path.resolve(initialCwd, source));
+
+const skipCopySegment = (segment: string) =>
+  segment === ".git" || segment === ".alchemy";
+
+export const hashExtraFiles = Effect.fn(function* (
+  extraFiles: ReadonlyArray<ExtraFile> | undefined,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const entries = yield* Effect.all(
+    (extraFiles ?? []).map((extra) =>
+      Effect.gen(function* () {
+        const dest = extraFileDestination(extra.dest);
+        const source = resolveExtraSource(extra.source, path);
+        const exists = yield* fs
+          .exists(source)
+          .pipe(Effect.orElseSucceed(() => false));
+        if (!exists) return [dest, ""] as const;
+        const stat = yield* fs.stat(source);
+        const hash =
+          stat.type === "Directory"
+            ? yield* hashDirectory({
+                cwd: source,
+                memo: {
+                  exclude: EXTRA_FILES_HASH_EXCLUDE,
+                  lockfile: false,
+                },
+              }).pipe(Effect.orElseSucceed(() => ""))
+            : yield* sha256(yield* fs.readFile(source));
+        return [dest, hash] as const;
+      }),
+    ),
+    { concurrency: ioConcurrency },
+  );
+  return Object.fromEntries(entries) as Record<string, string>;
+});
+
+/**
+ * Copy a file or directory without macOS `clonefile`. Nitro/Nuxt
+ * `.output/server` trees (and their nested `node_modules`) fail
+ * `fs.copy` with `EINVAL: invalid argument, clonefile`. Nested
+ * `node_modules` are copied — nitro's node preset emits runtime
+ * deps there (`solid-js`, `seroval`, …) and the host imports them.
+ */
+export const copyTree = Effect.fn(function* (from: string, to: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const stat = yield* fs
+    .stat(from)
+    .pipe(Effect.catch(() => Effect.succeed(undefined)));
+  if (stat === undefined) return;
+  if (stat.type !== "Directory") {
+    if (stat.type !== "File") return;
+    yield* fs.makeDirectory(path.dirname(to), { recursive: true });
+    const contents = yield* fs.readFile(from);
+    yield* fs.writeFile(to, contents);
+    return;
+  }
+  yield* fs.makeDirectory(to, { recursive: true });
+  const names = yield* fs.readDirectory(from, { recursive: true });
+  yield* Effect.all(
+    names.flatMap((name) => {
+      if (name.split(/[\\/]/).some(skipCopySegment)) return [];
+      return [
+        Effect.gen(function* () {
+          const src = path.join(from, name);
+          const item = yield* fs
+            .stat(src)
+            .pipe(Effect.catch(() => Effect.succeed(undefined)));
+          if (item === undefined || item.type !== "File") return;
+          const dst = path.join(to, name);
+          yield* fs.makeDirectory(path.dirname(dst), { recursive: true });
+          const contents = yield* fs.readFile(src);
+          yield* fs.writeFile(dst, contents);
+        }),
+      ];
+    }),
+    { concurrency: ioConcurrency },
+  );
+});
+
+export const copyExtraFiles = Effect.fn(function* (
+  contextDir: string,
+  extraFiles: ReadonlyArray<ExtraFile> | undefined,
+  options?: {
+    readonly onMissing?: (file: {
+      readonly source: string;
+      readonly dest: string;
+    }) => Effect.Effect<unknown, any>;
+  },
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  yield* Effect.all(
+    (extraFiles ?? []).map((extra) =>
+      Effect.gen(function* () {
+        const source = resolveExtraSource(extra.source, path);
+        const destName = extraFileDestination(extra.dest);
+        const exists = yield* fs
+          .exists(source)
+          .pipe(Effect.orElseSucceed(() => false));
+        if (!exists) {
+          if (options?.onMissing !== undefined) {
+            yield* options.onMissing({ source, dest: destName });
+          }
+          return;
+        }
+        if (isContextRootDest(destName)) {
+          const stat = yield* fs.stat(source);
+          if (stat.type === "Directory") {
+            const names = yield* fs.readDirectory(source);
+            yield* Effect.all(
+              names.map((name) =>
+                copyTree(path.join(source, name), path.join(contextDir, name)),
+              ),
+              { concurrency: ioConcurrency },
+            );
+          } else {
+            yield* copyTree(
+              source,
+              path.join(contextDir, path.basename(source)),
+            );
+          }
+          return;
+        }
+        const dest = path.join(contextDir, destName);
+        if (yield* fs.exists(dest).pipe(Effect.orElseSucceed(() => false))) {
+          yield* fs.remove(dest, { recursive: true });
+        }
+        yield* fs.makeDirectory(path.dirname(dest), { recursive: true });
+        yield* copyTree(source, dest);
+      }),
+    ),
+    { concurrency: ioConcurrency },
+  );
+});

package/src/Util/index.ts

@@ -3,6 +3,7 @@ export * from "./camel.ts";
 export * from "./data.ts";
 export * from "./dedent.ts";
 export * from "./equal.ts";
+export * from "./extraFiles.ts";
 export * from "./md5.ts";
 export * from "./service.ts";
 export * from "./sha256.ts";

package/src/Util/tarGzip.ts

@@ -0,0 +1,180 @@
+/**
+ * Gzipped ustar of a directory. Used to upload a generated Docker
+ * context (Railway `/up`, and any other gzip-tarball consumer).
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as zlib from "node:zlib";
+
+const encoder = new TextEncoder();
+
+const pad512 = (size: number) => (512 - (size % 512)) % 512;
+
+const writeBytes = (
+  buf: Uint8Array,
+  offset: number,
+  value: string,
+  length: number,
+) => {
+  const bytes = encoder.encode(value);
+  buf.set(bytes.subarray(0, length), offset);
+};
+
+const writeOctal = (
+  buf: Uint8Array,
+  offset: number,
+  value: number,
+  length: number,
+) => {
+  writeBytes(
+    buf,
+    offset,
+    `${value.toString(8).padStart(length - 1, "0")}\0`,
+    length,
+  );
+};
+
+const headerBlock = (input: {
+  name: string;
+  size: number;
+  type: string;
+  mode: number;
+  prefix?: string;
+}): Uint8Array => {
+  const buf = new Uint8Array(512);
+  writeBytes(buf, 0, input.name, 100);
+  writeOctal(buf, 100, input.mode, 8);
+  writeOctal(buf, 108, 0, 8);
+  writeOctal(buf, 116, 0, 8);
+  writeOctal(buf, 124, input.size, 12);
+  writeOctal(buf, 136, Math.floor(Date.now() / 1000), 12);
+  for (let i = 148; i < 156; i++) buf[i] = 0x20;
+  buf[156] = input.type.charCodeAt(0);
+  writeBytes(buf, 257, "ustar", 6);
+  buf[262] = 0;
+  writeBytes(buf, 263, "00", 2);
+  if (input.prefix !== undefined) {
+    writeBytes(buf, 345, input.prefix, 155);
+  }
+  let sum = 0;
+  for (const byte of buf) sum += byte;
+  writeBytes(buf, 148, `${sum.toString(8).padStart(6, "0")}\0 `, 8);
+  return buf;
+};
+
+const splitUstarName = (
+  rel: string,
+): { name: string; prefix?: string } | undefined => {
+  if (rel.length <= 100) return { name: rel };
+  for (let i = rel.length - 101; i >= 1; i--) {
+    if (rel[i] !== "/") continue;
+    const prefix = rel.slice(0, i);
+    const name = rel.slice(i + 1);
+    if (prefix.length <= 155 && name.length > 0 && name.length <= 100) {
+      return { prefix, name };
+    }
+  }
+  return undefined;
+};
+
+const gnuLongLink = (name: string): Uint8Array[] => {
+  const bytes = encoder.encode(`${name}\0`);
+  const header = headerBlock({
+    name: "././@LongLink",
+    size: bytes.length,
+    type: "L",
+    mode: 0,
+  });
+  const pad = pad512(bytes.length);
+  return pad > 0 ? [header, bytes, new Uint8Array(pad)] : [header, bytes];
+};
+
+const concat = (chunks: ReadonlyArray<Uint8Array>): Uint8Array => {
+  const total = chunks.reduce((n, chunk) => n + chunk.byteLength, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out;
+};
+
+type WalkEntry = {
+  rel: string;
+  abs: string;
+  dir: boolean;
+};
+
+const walkDirectory = (
+  root: string,
+): Effect.Effect<WalkEntry[], unknown, FileSystem.FileSystem | Path.Path> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const files: WalkEntry[] = [];
+    const walk = (dir: string, rel: string): Effect.Effect<void, unknown> =>
+      Effect.gen(function* () {
+        const entries = [...(yield* fs.readDirectory(dir))].sort();
+        for (const entry of entries) {
+          const abs = path.join(dir, entry);
+          const childRel = rel.length === 0 ? entry : `${rel}/${entry}`;
+          const posixRel = childRel.replaceAll("\\", "/");
+          const stat = yield* fs.stat(abs);
+          if (stat.type === "Directory") {
+            files.push({ rel: posixRel, abs, dir: true });
+            yield* walk(abs, posixRel);
+          } else if (stat.type === "File") {
+            files.push({ rel: posixRel, abs, dir: false });
+          }
+        }
+      });
+    yield* walk(root, "");
+    return files;
+  });
+
+const fileBlocks = (
+  rel: string,
+  size: number,
+  type: "0" | "5",
+  mode: number,
+): Uint8Array[] => {
+  const split = splitUstarName(rel);
+  if (split === undefined) {
+    return [
+      ...gnuLongLink(rel),
+      headerBlock({
+        name: rel.slice(0, 100),
+        size,
+        type,
+        mode,
+      }),
+    ];
+  }
+  return [headerBlock({ ...split, size, type, mode })];
+};
+
+/**
+ * Pack `root` into a gzipped tar (ustar + GNU long-name). Paths are
+ * relative to `root` with POSIX separators.
+ */
+export const tarGzipDirectory = Effect.fn(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const files = yield* walkDirectory(root);
+  const chunks: Uint8Array[] = [];
+  for (const file of files) {
+    if (file.dir) {
+      chunks.push(...fileBlocks(`${file.rel}/`, 0, "5", 0o755));
+      continue;
+    }
+    const content = yield* fs.readFile(file.abs);
+    chunks.push(...fileBlocks(file.rel, content.byteLength, "0", 0o644));
+    chunks.push(content);
+    const pad = pad512(content.byteLength);
+    if (pad > 0) chunks.push(new Uint8Array(pad));
+  }
+  chunks.push(new Uint8Array(1024));
+  const tar = concat(chunks);
+  return yield* Effect.sync(() => zlib.gzipSync(tar));
+});

package/src/Util/types.ts

@@ -30,3 +30,16 @@ export const asEffect = <T, Err = never, Req = never>(
       : Effect.succeed(effect as T);
 
 export type IsNever<T> = [T] extends [never] ? true : false;
+
+/**
+ * `Omit` that distributes over a union instead of collapsing it.
+ *
+ * Bare `Omit<A | B, K>` computes `keyof (A | B)` — the COMMON keys — and
+ * merges the members into one object type. For discriminated prop unions
+ * (e.g. a Function's zip-XOR-image props) that silently erases the
+ * discrimination: required members become optional and mutually exclusive
+ * fields become simultaneously allowed. Distributing preserves each member.
+ */
+export type DistributiveOmit<T, K extends keyof any> = T extends any
+  ? Omit<T, K>
+  : never;

package/src/{AWS/Website → Website}/Server.ts

@@ -4,14 +4,14 @@ import * as Equal from "effect/Equal";
 import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
 import * as NodeNet from "node:net";
-import { hashDirectory, type MemoOptions } from "../../Command/Memo.ts";
-import { havePropsChanged, isResolved } from "../../Diff.ts";
-import * as LocalProvider from "../../Local/LocalProvider.ts";
-import * as ProviderLayer from "../../Local/ProviderLayer.ts";
-import * as Provider from "../../Provider.ts";
-import { Resource } from "../../Resource.ts";
-import { initialCwd } from "../../Util/Node.ts";
-import { sha256Object } from "../../Util/sha256.ts";
+import { hashDirectory, type MemoOptions } from "../Command/Memo.ts";
+import { havePropsChanged, isResolved } from "../Diff.ts";
+import * as LocalProvider from "../Local/LocalProvider.ts";
+import * as ProviderLayer from "../Local/ProviderLayer.ts";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+import { initialCwd } from "../Util/Node.ts";
+import { sha256Object } from "../Util/sha256.ts";
 
 /**
  * The structural slice of a framework-integration module
@@ -27,6 +27,7 @@ interface FrameworkModule {
     {
       readonly build: (options?: {
         readonly root?: string;
+        readonly env?: Record<string, string>;
       }) => Effect.Effect<FrameworkBuildOutputSlice, unknown>;
       readonly dev: (options?: {
         readonly root?: string;
@@ -54,6 +55,18 @@ export class FrameworkServerError extends Data.TaggedError(
   readonly cause?: unknown;
 }> {}
 
+/** Drops `undefined`-valued entries from {@link ServerProps.env}. */
+const definedEnv = (
+  env: Record<string, string | undefined> | undefined,
+): Record<string, string> | undefined =>
+  env === undefined
+    ? undefined
+    : Object.fromEntries(
+        Object.entries(env).filter(
+          (entry): entry is [string, string] => entry[1] !== undefined,
+        ),
+      );
+
 /**
  * Options for the local dev server that runs a framework site under
  * `alchemy dev`.
@@ -136,8 +149,12 @@ export interface ServerProps {
    * applied to the dev server's process environment (the dev sidecar and
    * any child it spawns) so server code reads the same values in both
    * modes. Changing a value restarts the dev server.
+   *
+   * Entries whose value is `undefined` are dropped — this lets website
+   * composites forward optional values (e.g. an `Output` service URL that
+   * resolves to `undefined`) without filtering first.
    */
-  env?: Record<string, string>;
+  env?: Record<string, string | undefined>;
   /**
    * Controls which files are hashed to decide whether the build should
    * re-run. By default every non-gitignored file in the root is hashed,
@@ -148,7 +165,7 @@ export interface ServerProps {
 }
 
 export interface Server extends Resource<
-  "AWS.Website.Server",
+  "Website.Server",
   ServerProps,
   {
     /**
@@ -189,11 +206,12 @@ export interface Server extends Resource<
 > {}
 
 /**
- * The framework toolchain half of an AWS website: on `alchemy deploy` it
+ * The framework toolchain half of a website: on `alchemy deploy` it
  * runs the framework's production build with a platform deploy target and
  * tracks the on-disk output in state; on `alchemy dev` it runs the
  * framework's OWN dev server (native HMR via the framework's kit) in the
- * dev sidecar and exposes its local URL.
+ * dev sidecar and exposes its local URL. Shared by AWS, Fly, Hetzner, and
+ * Railway website composites.
  *
  * The framework package and the target module are loaded from *your*
  * project's `node_modules`, so your project's framework version drives the
@@ -215,8 +233,8 @@ export interface Server extends Resource<
  *
  * @resource
  */
-export const Server = Resource<Server>("AWS.Website.Server", {
-  aliases: ["AWS.Website.FrameworkBuild"],
+export const Server = Resource<Server>("Website.Server", {
+  aliases: ["AWS.Website.Server", "AWS.Website.FrameworkBuild"],
 });
 
 const importFrameworkModule = (specifier: string) =>
@@ -279,7 +297,7 @@ export const ServerProviderLive = () =>
         const root = path.resolve(initialCwd, props.root ?? ".");
         const service = yield* makeFramework(props, root);
         return yield* Effect.mapError(
-          service.build({ root }),
+          service.build({ root, env: definedEnv(props.env) }),
           (cause) =>
             new FrameworkServerError({
               framework: props.framework,
@@ -438,6 +456,21 @@ const resolveDevPort = Effect.fn(function* (options: {
   );
 });
 
+/**
+ * A framework dev server may advertise its *bind* address — nuxt echoes the
+ * host it was told to listen on, so a Router-attached site (which binds
+ * `0.0.0.0` to be reachable from the emulator container) reports
+ * `http://0.0.0.0:{port}/`. The unspecified address is not a connectable
+ * host: normalize it to `localhost` for the `url` attribute (browser links,
+ * Router dev routing, the emulated CloudFront edge dialing the origin). The
+ * server itself still listens on every interface.
+ */
+const normalizeAdvertisedUrl = (url: string) =>
+  url.replace(
+    /^(https?:\/\/)(?:0\.0\.0\.0|\[::\]|\[0+(?::0+){7}\])(?=[:/]|$)/,
+    "$1localhost",
+  );
+
 /**
  * The `alchemy dev` variant: runs the framework's own dev server (native
  * HMR through the framework's kit — nuxt, astro, ...) inside the dev
@@ -480,6 +513,7 @@ export const ServerProviderLocal = () =>
           if (props.env !== undefined) {
             yield* Effect.sync(() => {
               for (const [key, value] of Object.entries(props.env!)) {
+                if (value === undefined) continue;
                 process.env[key] = String(value);
               }
             });
@@ -517,7 +551,7 @@ export const ServerProviderLocal = () =>
             distDir: undefined,
             clientDir: undefined,
             serverEntry: undefined,
-            url,
+            url: normalizeAdvertisedUrl(url),
             hash: { input: undefined, output: undefined },
           };
         }),

package/src/Website/ServerLocal.ts

@@ -0,0 +1,4 @@
+import * as RpcServer from "../Local/RpcServer.ts";
+import { ServerProviderLocal } from "./Server.ts";
+
+ServerProviderLocal().pipe(RpcServer.launch);