alchemy 2.0.0-beta.74 → 2.0.0-beta.75

package/src/Railway/Website/Astro.ts

@@ -0,0 +1,105 @@
+import * as Namespace from "../../Namespace.ts";
+import {
+  makeFrameworkSite,
+  staticConfigFromAssets,
+  type FrameworkSiteProps,
+} from "./FrameworkSite.ts";
+
+/** The framework-integration package that drives the Astro build. */
+export const ASTRO_FRAMEWORK_SPECIFIER =
+  "@alchemy.run/frontend-frameworks/astro";
+
+/** The Node container deploy target for the Astro build. */
+export const ASTRO_NODE_TARGET_SPECIFIER =
+  "@alchemy.run/frontend-frameworks/astro/node";
+
+export interface AstroProps extends FrameworkSiteProps {
+  /**
+   * Serializable Astro config merged OVER the project's own
+   * `astro.config.*` (which loads natively). `adapter` is owned by the Node
+   * deploy target and may not be set here.
+   */
+  astro?: {
+    /** The full URL the site deploys to (`Astro.site`). */
+    site?: string;
+    /** Base path the site deploys under. */
+    base?: string;
+    /**
+     * Astro output target. `"server"` renders pages on demand in the
+     * container; individual pages opt into prerendering with
+     * `export const prerender = true`. `"static"` prerenders every page at
+     * build time and deploys assets-only (no framework handler).
+     * @default "server"
+     */
+    output?: "server" | "static";
+    /** Source directory, relative to `rootDir`. @default "./src" */
+    srcDir?: string;
+    /** Public (static passthrough) directory. @default "./public" */
+    publicDir?: string;
+    /** Build output directory. @default "./dist" */
+    outDir?: string;
+    /** Trailing-slash handling for routes. */
+    trailingSlash?: "always" | "never" | "ignore";
+  };
+}
+
+/**
+ * Deploy an [Astro](https://astro.build) application to Railway: the Node
+ * SSR bundle (assets first, then the Astro fetch handler) on one
+ * `Railway.Service`. Pages render on demand by default
+ * (`output: "server"`); pages that `export const prerender = true` are
+ * prerendered at build time and served as static files. With
+ * `astro: { output: "static" }` every page is prerendered and the deploy
+ * is assets-only.
+ *
+ * The build runs through `@alchemy.run/frontend-frameworks/astro` with the
+ * `@alchemy.run/frontend-frameworks/astro/node` deploy target (a Node
+ * adapter is injected — your `astro.config.*` must not declare one).
+ *
+ * During `alchemy dev` the site is Astro's own dev server and no cloud
+ * resources are created. `Alchemy.remote()` opts back into the live
+ * Service path.
+ *
+ * ### Creating Astro Sites
+ * **Example:** Basic Astro App
+ * ```typescript
+ * const site = yield* Railway.Website.Astro("Web", {
+ *   rootDir: "./app",
+ * });
+ * ```
+ *
+ * ### Static Sites
+ * **Example:** Fully Static Astro Site
+ * ```typescript
+ * const site = yield* Railway.Website.Astro("Docs", {
+ *   rootDir: "./docs",
+ *   astro: { output: "static" },
+ *   errorPage: "404.html",
+ * });
+ * ```
+ *
+ * ### Server Configuration
+ * **Example:** Process Environment
+ * ```typescript
+ * const site = yield* Railway.Website.Astro("Web", {
+ *   rootDir: "./app",
+ *   env: {
+ *     API_BASE: "https://api.example.com",
+ *   },
+ * });
+ * ```
+ *
+ * @resource
+ * @product Website
+ */
+export const Astro = (id: string, props: AstroProps = {}) => {
+  const output = props.astro?.output ?? "server";
+  return makeFrameworkSite(id, props, {
+    name: "Astro",
+    framework: ASTRO_FRAMEWORK_SPECIFIER,
+    target: ASTRO_NODE_TARGET_SPECIFIER,
+    options: { astro: { ...props.astro, output } },
+    static:
+      output === "static" ? staticConfigFromAssets(props.assets) : undefined,
+  }).pipe(Namespace.push(id));
+};

package/src/Railway/Website/Cdn.ts

@@ -0,0 +1,198 @@
+import type { PurgeOnDeploy } from "@distilled.cloud/railway";
+import * as railway from "@distilled.cloud/railway";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import { isResolved } from "../../Diff.ts";
+import * as Provider from "../../Provider.ts";
+import { Resource } from "../../Resource.ts";
+import type { Providers } from "../Providers.ts";
+import { isRailwayTransient } from "../transient.ts";
+
+type Ref<T> = T | Effect.Effect<T, never, Providers>;
+
+export type CdnService = {
+  readonly serviceId: string;
+};
+
+export type CdnEnvironment = {
+  readonly environmentId: string;
+};
+
+export interface CdnProps {
+  /**
+   * Parent Railway Service whose domains receive CDN caching.
+   */
+  service: Ref<CdnService>;
+  /**
+   * Environment the Service instance lives in.
+   */
+  environment: Ref<CdnEnvironment>;
+  /**
+   * HTML caching mode. `"AUTO"` caches HTML only when the origin sends
+   * `max-age` / `s-maxage`. `"FORCE"` uses the default TTL. `"NEVER"`
+   * skips HTML.
+   * @default "AUTO"
+   */
+  htmlCaching?: "AUTO" | "FORCE" | "NEVER" | (string & {});
+  /**
+   * What to purge after a successful deploy.
+   * @default "HTML"
+   */
+  purgeOnDeploy?: PurgeOnDeploy;
+  /**
+   * Fallback TTL in seconds when the origin sends no freshness.
+   * @default 7200
+   */
+  defaultTtlSeconds?: number;
+}
+
+export interface Cdn extends Resource<
+  "Railway.Website.Cdn",
+  CdnProps,
+  {
+    serviceId: string;
+    environmentId: string;
+    edgeConfigId: string;
+    enabled: boolean;
+  },
+  never,
+  Providers
+> {}
+
+/**
+ * Enable Railway's built-in CDN on a Website Service. Static assets
+ * (by Content-Type) are cached at the edge; HTML follows
+ * {@link CdnProps.htmlCaching}.
+ *
+ * @resource
+ */
+export const Cdn = Resource<Cdn>("Railway.Website.Cdn");
+
+export class CdnServiceMissing extends Data.TaggedError(
+  "Railway.Website.CdnServiceMissing",
+)<{
+  message: string;
+}> {}
+
+const serviceIdOf = (value: unknown): string | undefined => {
+  if (value === null || typeof value !== "object") return undefined;
+  const rec = value as { serviceId?: unknown };
+  return typeof rec.serviceId === "string" && rec.serviceId.length > 0
+    ? rec.serviceId
+    : undefined;
+};
+
+const environmentIdOf = (value: unknown): string | undefined => {
+  if (value === null || typeof value !== "object") return undefined;
+  const rec = value as { environmentId?: unknown };
+  return typeof rec.environmentId === "string" && rec.environmentId.length > 0
+    ? rec.environmentId
+    : undefined;
+};
+
+const cachingInput = (props: CdnProps) => ({
+  htmlCaching: props.htmlCaching ?? "AUTO",
+  purgeOnDeploy: props.purgeOnDeploy ?? "HTML",
+  defaultTtlSeconds: props.defaultTtlSeconds ?? 7200,
+});
+
+export const CdnProvider = () =>
+  Provider.succeed(Cdn, {
+    stables: ["serviceId", "environmentId", "edgeConfigId"],
+    nuke: { dependsOn: ["Railway.Service"] },
+
+    diff: Effect.fn(function* ({ news, output }) {
+      if (news === undefined || !isResolved(news) || output === undefined) {
+        return undefined;
+      }
+      const serviceId = serviceIdOf(news.service);
+      const environmentId = environmentIdOf(news.environment);
+      if (
+        (serviceId !== undefined && serviceId !== output.serviceId) ||
+        (environmentId !== undefined && environmentId !== output.environmentId)
+      ) {
+        return { action: "replace" as const, deleteFirst: true };
+      }
+      return undefined;
+    }),
+
+    list: () => Effect.succeed([]),
+
+    read: Effect.fn(function* ({ output }) {
+      return output;
+    }),
+
+    reconcile: Effect.fn(function* ({ news, output }) {
+      const serviceId = serviceIdOf(news.service) ?? output?.serviceId ?? "";
+      const environmentId =
+        environmentIdOf(news.environment) ?? output?.environmentId ?? "";
+      if (serviceId.length === 0 || environmentId.length === 0) {
+        return yield* new CdnServiceMissing({
+          message: "Railway.Website.Cdn requires a Service and environment.",
+        });
+      }
+      const config = { caching: cachingInput(news) };
+      const retryTransient = {
+        while: (e: { _tag: string }) =>
+          e._tag === "RailwayInternalError" ||
+          e._tag === "TimeoutError" ||
+          isRailwayTransient(e),
+        times: 2 as const,
+        schedule: Schedule.spaced("1 second"),
+      };
+      const enabled = yield* railway
+        .enableServiceCdn({
+          input: {
+            environmentId,
+            serviceId,
+            config,
+          },
+        })
+        .pipe(
+          Effect.timeout("5 seconds"),
+          Effect.retry(retryTransient),
+          Effect.catchTag("UnknownRailwayError", () =>
+            railway
+              .updateServiceEdgeConfig({
+                input: {
+                  serviceId,
+                  environmentId,
+                  config,
+                },
+              })
+              .pipe(Effect.timeout("5 seconds"), Effect.retry(retryTransient)),
+          ),
+          Effect.catchTag(["TimeoutError", "RailwayInternalError"], () =>
+            Effect.succeed({
+              id: output?.edgeConfigId ?? "",
+              enabled: output?.enabled ?? false,
+            }),
+          ),
+        );
+      return {
+        serviceId,
+        environmentId,
+        edgeConfigId: enabled.id,
+        enabled: enabled.enabled,
+      };
+    }),
+
+    delete: Effect.fn(function* ({ output }) {
+      if (output === undefined) return;
+      if (output.edgeConfigId.length === 0) return;
+      yield* railway
+        .disableServiceCdn({
+          input: {
+            environmentId: output.environmentId,
+            serviceId: output.serviceId,
+          },
+        })
+        .pipe(
+          Effect.catchTag(
+            ["UnknownRailwayError", "RailwayValidationError"],
+            () => Effect.void,
+          ),
+        );
+    }),
+  });

package/src/Railway/Website/Foldkit.ts

@@ -0,0 +1,48 @@
+import { Vite, type ViteProps } from "./Vite.ts";
+
+export interface FoldkitProps extends ViteProps {}
+
+/**
+ * Deploy a [Foldkit](https://foldkit.dev) app to Railway: a Vite SPA with
+ * unmatched paths falling back to `index.html` so deep links boot the
+ * Foldkit router. Same Node static-file Service as {@link Vite}.
+ *
+ * Foldkit apps are client-only Vite projects — the Foldkit Vite plugin in
+ * the app's `vite.config.ts` composes with the project's own Vite build.
+ *
+ * During `alchemy dev` the site is Vite's own dev server and no cloud
+ * resources are created. `Alchemy.remote()` opts back into the live
+ * Service path.
+ *
+ * ### Deploying a Foldkit App
+ * **Example:** Foldkit app
+ * ```typescript
+ * const site = yield* Railway.Website.Foldkit("Website");
+ * ```
+ *
+ * **Example:** Foldkit project in a subdirectory
+ * ```typescript
+ * const site = yield* Railway.Website.Foldkit("Website", {
+ *   rootDir: "applications/web",
+ * });
+ * ```
+ *
+ * ### Single-Page Application Routing
+ * **Example:** Serving a real 404 page
+ * ```typescript
+ * const site = yield* Railway.Website.Foldkit("Website", {
+ *   assets: { notFoundHandling: "404-page" },
+ * });
+ * ```
+ *
+ * @resource
+ * @product Website
+ */
+export const Foldkit = (id: string, props: FoldkitProps = {}) =>
+  Vite(id, {
+    ...props,
+    assets: {
+      notFoundHandling: "single-page-application",
+      ...props.assets,
+    },
+  });

package/src/Railway/Website/FrameworkSite.ts

@@ -0,0 +1,344 @@
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Redacted from "effect/Redacted";
+import { AlchemyContext } from "../../AlchemyContext.ts";
+import type { PackageInstall } from "../../Bundle/InstalledPackages.ts";
+import type { MemoOptions } from "../../Command/Memo.ts";
+import * as Output from "../../Output.ts";
+import { ProviderModePolicy } from "../../ProviderMode.ts";
+import { initialCwd } from "../../Util/Node.ts";
+import {
+  staticConfigFromAssets,
+  type WebsiteAssetsProps,
+  type WebsiteNotFoundHandling,
+} from "../../Website/assets.ts";
+import { packSiteExtraFiles } from "../../Website/packExtraFiles.ts";
+import {
+  Server as FrameworkServer,
+  type ServerDevProps,
+} from "../../Website/Server.ts";
+import { CustomDomain } from "../CustomDomain.ts";
+import type { ExtraFile } from "../hosted.ts";
+import { Project, type Project as ProjectResource } from "../Project.ts";
+import type { Environment as EnvironmentResource } from "../ProjectEnvironment.ts";
+import type { Providers } from "../Providers.ts";
+import { Service, type Service as ServiceResource } from "../Service.ts";
+import { Cdn } from "./Cdn.ts";
+
+/** Port the generated Node serve entry and Railway Service listen on. */
+export const WEBSITE_PORT = 3000;
+
+/**
+ * A resource-valued prop: the resource itself, or an Effect that produces
+ * it (so `yield* Project(...)` and `Project(...)` both type-check).
+ */
+export type Ref<T> = T | Effect.Effect<T, never, Providers>;
+
+export type { ServerDevProps, WebsiteAssetsProps, WebsiteNotFoundHandling };
+export { staticConfigFromAssets };
+
+/**
+ * Props shared by every Railway framework website composite.
+ */
+export interface FrameworkSiteProps {
+  /**
+   * Parent Railway Project. Accepts a `Railway.Project` or an Effect
+   * that produces one. When omitted, a `Railway.Project("Project")` is
+   * created under this site's namespace.
+   */
+  project?: Ref<ProjectResource>;
+  /**
+   * Environment to deploy the Service into. Accepts a `Railway.Project`
+   * (primary environment), a `Railway.Environment`, or `{ environmentId }`.
+   * Defaults to the project's primary environment.
+   */
+  environment?: Ref<
+    EnvironmentResource | ProjectResource | { readonly environmentId: string }
+  >;
+  /**
+   * Project root directory (the directory containing `package.json`).
+   * @default "."
+   */
+  rootDir?: string;
+  /**
+   * Controls which files are hashed to decide whether the build re-runs.
+   * Forwarded to the framework integration when it honors memo options.
+   * @default true
+   */
+  memo?: MemoOptions | boolean;
+  /**
+   * Process environment for the deployed Service (and, under
+   * `alchemy dev`, the framework dev server). Accepts `Output`s
+   * (e.g. `VITE_API_URL: api.url`).
+   */
+  env?: Record<
+    string,
+    string | Redacted.Redacted<string> | Output.Output<string | undefined>
+  >;
+  /**
+   * Static-asset routing (`notFoundHandling`, `htmlHandling`). Railway
+   * CDN caches hashed files by Content-Type regardless of this bag.
+   */
+  assets?: WebsiteAssetsProps;
+  /**
+   * Options for the local dev server that runs this site under
+   * `alchemy dev`.
+   */
+  dev?: ServerDevProps;
+  /**
+   * Optional custom hostname attached via `Railway.CustomDomain`. A
+   * string is the hostname (`www.example.com`). When set, `url` is
+   * `https://{domain}` instead of the generated `*.up.railway.app`.
+   */
+  domain?: string;
+  /**
+   * User-defined tags. Railway Services do not persist tags; accepted
+   * for API parity with AWS/Cloudflare Website composites.
+   */
+  tags?: Record<string, string>;
+}
+
+/**
+ * Static-asset serving options mapped from Cloudflare `AssetsConfig`
+ * onto the generated Node serve entry.
+ */
+export interface WebsiteStaticConfig {
+  /**
+   * Answer misses with `index.html` (200) so client-side routes
+   * deep-link. Mutually exclusive with {@link errorPage}.
+   */
+  spa?: boolean;
+  /**
+   * Serve this page (e.g. `404.html`) with status 404 when no file
+   * matches. Mutually exclusive with {@link spa}.
+   */
+  errorPage?: string;
+  /**
+   * Vocs/Waku: serve `about/index.html` at `/about`.
+   * @default "none"
+   */
+  htmlHandling?: "none" | "drop-trailing-slash";
+}
+
+/** Per-framework wiring for {@link makeFrameworkSite}. */
+export interface FrameworkSiteConfig {
+  /** Display name used in error messages (e.g. `"SvelteKit"`). */
+  name: string;
+  /** Framework-integration module specifier. */
+  framework: string;
+  /** Node deploy-target module specifier. */
+  target: string;
+  /**
+   * Framework-specific build options forwarded to the integration (e.g.
+   * `{ kit }`, `{ nuxt }`, `{ astro }`). Must be JSON-serializable.
+   */
+  options?: Record<string, unknown> | undefined;
+  /**
+   * Assets-only serving: used when the build produced no server modules
+   * (Vite, Foldkit, Vocs, Astro `output: "static"`).
+   */
+  static?: WebsiteStaticConfig | undefined;
+  /**
+   * Native packages to `npm install` into the image instead of bundling
+   * (Next.js needs `next` / `react`).
+   */
+  install?: PackageInstall | undefined;
+  /**
+   * How to bake the build into the image.
+   * - `"client"` (default): `COPY dist /app/dist` from `clientDirectory`
+   * - `"next"`: `COPY .next` + `public` (and `next.config.*`)
+   * @default "client"
+   */
+  bake?: "client" | "next" | undefined;
+}
+
+export interface Website {
+  /**
+   * Public site URL. Under `alchemy dev` this is the framework (or
+   * static) dev server (`http://localhost:<port>`). On deploy it is
+   * `https://{domain}` (`*.up.railway.app`, or the custom hostname).
+   */
+  url: string | Output.Output<string | undefined> | undefined;
+  /**
+   * The Railway Service that serves the site. `undefined` under
+   * `alchemy dev` (no cloud resources are declared).
+   */
+  service: ServiceResource | undefined;
+  /**
+   * The Railway Project the Service belongs to. `undefined` under
+   * `alchemy dev`.
+   */
+  project: ProjectResource | undefined;
+}
+
+export class FrameworkServerError extends Data.TaggedError(
+  "Railway.Website.FrameworkServerError",
+)<{
+  readonly framework: string;
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+const envRecord = (
+  env:
+    | Record<
+        string,
+        string | Redacted.Redacted<string> | Output.Output<string | undefined>
+      >
+    | undefined,
+): Record<string, string | Output.Output<string | undefined>> | undefined => {
+  if (env === undefined) return undefined;
+  return Object.fromEntries(
+    Object.entries(env).map(([key, value]) => [
+      key,
+      Redacted.isRedacted(value) ? Redacted.value(value) : value,
+    ]),
+  );
+};
+
+/**
+ * Shared implementation behind the Railway framework website composites:
+ * build the framework through its Node deploy target, then deploy one
+ * `Railway.Service` whose image bakes the Node serve entry plus
+ * `clientDirectory`.
+ *
+ * During `alchemy dev` the site is the framework's own dev server (native
+ * HMR) and no cloud resources are declared; `Alchemy.remote()` opts back
+ * into the live Service path.
+ *
+ * Callers pipe `Namespace.push(id)` themselves (the composites do).
+ */
+const runFrameworkSite = Effect.fn("Railway.Website.FrameworkSite")(function* (
+  _id: string,
+  props: FrameworkSiteProps,
+  config: FrameworkSiteConfig,
+) {
+  const ctx = yield* AlchemyContext;
+  const remoted = yield* ProviderModePolicy;
+  const isLocal = ctx.dev && remoted !== true;
+  const path = yield* Path.Path;
+  const fs = yield* FileSystem.FileSystem;
+  const root = path.resolve(initialCwd, props.rootDir ?? ".");
+  const bake = config.bake ?? "client";
+
+  const build = yield* FrameworkServer("Build", {
+    framework: config.framework,
+    target: config.target,
+    root: props.rootDir,
+    env: envRecord(props.env),
+    options: config.options,
+    memo: props.memo,
+    dev: props.dev,
+  });
+
+  if (isLocal) {
+    return {
+      url: build.url,
+      service: undefined,
+      project: undefined,
+    } satisfies Website;
+  }
+
+  // The build runs at APPLY time (`Website.Server` is a resource), so its
+  // attributes are Outputs here — derive every deploy input lazily and let
+  // the engine resolve them once the build has produced real paths. Reading
+  // `build.distDir` eagerly in the composite body would observe an Output
+  // proxy, not a string.
+  const buildOut = Output.mapEffect(
+    ([serverEntry, distDir]: [string | undefined, string | undefined]) =>
+      Effect.gen(function* () {
+        if (serverEntry === undefined || distDir === undefined) {
+          return yield* Effect.die(
+            new FrameworkServerError({
+              framework: config.framework,
+              message: `The ${config.name} build produced no Node serve entry (serverModules[0]). The Node deploy target should write serve-node.mjs.`,
+            }),
+          );
+        }
+        const main = path.resolve(initialCwd, serverEntry);
+        if (!(yield* fs.exists(main).pipe(Effect.orElseSucceed(() => false)))) {
+          return yield* Effect.die(
+            new FrameworkServerError({
+              framework: config.framework,
+              message: `The ${config.name} build produced no server entry at ${main}`,
+            }),
+          );
+        }
+        return { distDir: path.resolve(initialCwd, distDir), main };
+      }),
+  )(
+    Output.all(
+      build.serverEntry as unknown as Output.Output<string | undefined>,
+      build.distDir as unknown as Output.Output<string | undefined>,
+    ) as unknown as Output.Output<[string | undefined, string | undefined]>,
+  );
+  const main = Output.map(buildOut, (out) => out.main);
+
+  // `bake === "next"` ships `.next`/`public`/`next.config.*` from the
+  // project root; every other bake ships the build's dist directory. BOTH
+  // must be derived from `buildOut`: the artifacts only exist once the
+  // build has run at apply — probing the root here (pre-build) would miss
+  // a fresh project's `.next` entirely.
+  const extraFiles = Output.mapEffect(
+    (out: { distDir: string; main: string }) =>
+      packSiteExtraFiles(bake === "next" ? root : out.distDir, bake),
+  )(buildOut);
+
+  const project = Effect.isEffect(props.project)
+    ? yield* props.project
+    : (props.project ?? (yield* Project("Project")));
+  const environment = Effect.isEffect(props.environment)
+    ? yield* props.environment
+    : (props.environment ?? project);
+  const service = yield* Service("Service", {
+    project,
+    environment,
+    main: main as unknown as string,
+    port: WEBSITE_PORT,
+    healthcheck: "/health",
+    isExternal: true,
+    env: envRecord(props.env),
+    extraFiles: extraFiles as unknown as ExtraFile[] | undefined,
+    build:
+      config.install !== undefined ? { install: config.install } : undefined,
+  });
+  yield* Cdn("Cdn", {
+    service,
+    environment,
+    htmlCaching: "AUTO",
+    purgeOnDeploy: "HTML",
+  });
+
+  if (props.domain !== undefined && props.domain.length > 0) {
+    yield* CustomDomain("Domain", {
+      service,
+      environment,
+      domain: props.domain,
+      targetPort: WEBSITE_PORT,
+    });
+    return {
+      url: `https://${props.domain}`,
+      service,
+      project,
+    } satisfies Website;
+  }
+
+  return {
+    url: service.url,
+    service,
+    project,
+  } satisfies Website;
+});
+
+/**
+ * Composite-level tagged errors (`FrameworkServerError`, filesystem)
+ * are defects — `Alchemy.Stack` only admits `ConfigError` on the user
+ * effect.
+ */
+export const makeFrameworkSite = (
+  id: string,
+  props: FrameworkSiteProps,
+  config: FrameworkSiteConfig,
+) => runFrameworkSite(id, props, config).pipe(Effect.orDie);