sailfork / t3code-github / .repos/ alchemy-effect/ packages/ hetzner/ src/ Website/ FrameworkSite.ts

import { AlchemyContext } from "alchemy/AlchemyContext";
import type { MemoOptions } from "alchemy/Command/Memo";
import * as DNS from "alchemy/DNS/Adapter";
import type { Input } from "alchemy/Input";
import * as Output from "alchemy/Output";
import { ProviderModePolicy } from "alchemy/ProviderMode";
import { initialCwd } from "alchemy/Util/Node";
import {
  staticConfigFromAssets,
  type WebsiteAssetsProps,
  type WebsiteNotFoundHandling,
} from "alchemy/Website/assets";
import { packSiteExtraFiles } from "alchemy/Website/packExtraFiles";
import { Server as FrameworkServer, type ServerDevProps } from "alchemy/Website/Server";
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 type { Providers } from "../Providers.ts";
import { RecordSet } from "../RecordSet.ts";
import { Server } from "../Server.ts";
import { Service } from "../Service.ts";
import type { Zone } from "../Zone.ts";

/**
 * A resource-valued prop: the resource itself, or an Effect that produces
 * it (so `yield* Server(...)` and `Server(...)` both type-check).
 */
export type Ref<T> = T | Effect.Effect<T, never, Providers>;

const resolveRef = <T>(ref: Ref<T>): Effect.Effect<T, never, Providers> =>
  Effect.isEffect(ref) ? ref : Effect.succeed(ref);

/** Default listen port. Hetzner `deployUnit` curls `/health` whenever `PORT` is set. */
export const DEFAULT_WEBSITE_PORT = 3000;

export type { ServerDevProps, WebsiteAssetsProps, WebsiteNotFoundHandling };
export { staticConfigFromAssets };

/**
 * Custom domain of a Hetzner website: the hostname itself (an `A`
 * {@link RecordSet} in {@link FrameworkSiteProps.zone}), or `{ name, dns }`
 * to publish the record through a DNS adapter instead.
 */
export type WebsiteDomain =
  | string
  | {
      /** Hostname, e.g. `app.example.com`. */
      name: string;
      /**
       * DNS host that publishes the `A` record at the Server's public
       * IPv4 (see [DNS Adapters](/infrastructure-as-code/dns-adapters)),
       * e.g. `Hetzner.DNS.Adapter()` or `Cloudflare.DNS.Adapter()`. When
       * set, `zone` is not required (and is ignored). Omitted: the `A`
       * {@link RecordSet} in `zone`.
       */
      dns?: DNS.DnsConfig;
    };

/** The hostname of a {@link WebsiteDomain}. */
export const websiteDomainName = (domain: WebsiteDomain | undefined): string | undefined =>
  domain === undefined || typeof domain === "string" ? domain : domain.name;

/** The DNS adapter config of a {@link WebsiteDomain}, when it names one. */
const websiteDomainDns = (domain: WebsiteDomain | undefined): DNS.DnsConfig | undefined =>
  typeof domain === "object" ? domain.dns : undefined;

/**
 * Dies unless a custom domain can be published: `domain.dns` names a DNS
 * host, or `zone` is set for the `A` {@link RecordSet}.
 */
export const requireWebsiteDomainZone = (
  label: string,
  props: {
    readonly domain?: WebsiteDomain | undefined;
    readonly zone?: Ref<Zone> | undefined;
  },
): Effect.Effect<void> =>
  props.domain !== undefined &&
  websiteDomainDns(props.domain) === undefined &&
  props.zone === undefined
    ? Effect.die(
        `${label}: "domain" requires "zone" (an existing Hetzner.Zone) or "domain.dns" (a DNS adapter).`,
      )
    : Effect.void;

/**
 * Point a website's custom domain at its Server: through `domain.dns` when
 * set (`Domain` alias, an address target), otherwise an `A`
 * {@link RecordSet} named `Domain` in `zone` (unchanged from before DNS
 * adapters existed).
 */
export const publishWebsiteDomain = Effect.fn("Hetzner.Website.publishDomain")(function* (props: {
  readonly domain?: WebsiteDomain | undefined;
  readonly zone?: Ref<Zone> | undefined;
  readonly server: Server;
  readonly tags?: Record<string, string> | undefined;
}) {
  const name = websiteDomainName(props.domain);
  if (name === undefined) return;
  const dnsConfig = websiteDomainDns(props.domain);
  if (dnsConfig !== undefined) {
    const dns = yield* DNS.resolve(dnsConfig);
    yield* dns.alias("Domain", {
      name,
      target: {
        ipv4: Output.map(props.server.ipv4, (ip) =>
          ip === undefined ? [] : [ip],
        ) as unknown as Input<string[]>,
      },
    });
    return;
  }
  if (props.zone !== undefined) {
    yield* bindWebsiteDomain({
      domain: name,
      zone: props.zone,
      server: props.server,
      tags: props.tags,
    });
  }
});

/**
 * Props shared by every Hetzner framework website composite.
 */
export interface FrameworkSiteProps {
  /**
   * Project root directory (the directory containing `package.json`).
   * @default "."
   */
  rootDir?: string;
  /**
   * Controls which files are hashed to decide whether the build re-runs.
   * @default true
   */
  memo?: MemoOptions | boolean;
  /**
   * Options for the local dev server that runs this site under
   * `alchemy dev`.
   */
  dev?: ServerDevProps;
  /**
   * Process environment for the hosted unit (and the local framework
   * dev server). Not Cloudflare Worker bindings. 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`).
   */
  assets?: WebsiteAssetsProps;
  /**
   * Optional custom domain pointed at the Server's public IPv4. The site
   * `url` becomes `http://{domain}:{port}` (no TLS on Service).
   *
   * A string (or `{ name }`) creates an `A` {@link RecordSet} in
   * {@link zone}. Set `dns` (e.g.
   * `{ name: "app.example.com", dns: Cloudflare.DNS.Adapter() }`) to
   * publish the `A` record through that DNS host instead — any adapter
   * works, including `Hetzner.DNS.Adapter()` and `AWS.Route53.Adapter()`.
   * See [DNS Adapters](/infrastructure-as-code/dns-adapters).
   */
  domain?: WebsiteDomain;
  /**
   * Existing Hetzner DNS Zone `domain` is created in. Required when
   * {@link domain} is set without `dns` — v1 does not provision a Zone.
   * Ignored when `domain.dns` is set.
   */
  zone?: Ref<Zone>;
  /**
   * Server the site's Service runs on. Accepts a `Hetzner.Server` or an
   * Effect that produces one. When omitted, a `cpx12` / `ubuntu-24.04`
   * Server is created in `fsn1` (public IPv4 is the Server default).
   */
  server?: Ref<Server>;
  /**
   * User-defined labels applied to auto-created Server / RecordSet.
   */
  tags?: Record<string, string>;
}

/** 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 container 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 mode: no server modules (or every page prerendered). The
   * composite generates a static-file server as `main`.
   */
  static?:
    | {
        spa?: boolean | undefined;
        errorPage?: string | undefined;
        htmlHandling?: "none" | "drop-trailing-slash" | undefined;
      }
    | undefined;
  /**
   * Vocs/Waku: serve `about/index.html` at `/about`.
   * @default "none"
   */
  htmlHandling?: "none" | "drop-trailing-slash";
  /**
   * Skip baking `clientDirectory` at `dist/`. Next.js serves `.next`
   * from the unit root instead.
   */
  skipClientAssets?: boolean | undefined;
  /**
   * Native packages to `npm install` into the unit instead of bundling
   * (Next.js needs `next` / `react` / `react-dom`).
   */
  install?: string[] | undefined;
}

export interface Website {
  /**
   * Local framework URL under `alchemy dev`, or the live Service URL
   * (`http://{ipv4}:{port}` / `http://{domain}:{port}`).
   */
  readonly url: string | Output.Output<string | undefined> | undefined;
  /** Server the unit runs on. `undefined` during `alchemy dev`. */
  readonly server: Server | undefined;
  /** Hosted systemd unit. `undefined` during `alchemy dev`. */
  readonly service: Service | undefined;
}

export class FrameworkSiteError extends Data.TaggedError("Hetzner.Website.FrameworkSiteError")<{
  readonly framework: string;
  readonly message: string;
  readonly cause?: unknown;
}> {}

export const unwrapEnv = (
  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,
    ]),
  );
};

export const resolveWebsiteServer = Effect.fn(function* (props: {
  readonly server?: Ref<Server> | undefined;
  readonly tags?: Record<string, string> | undefined;
}) {
  if (props.server !== undefined) {
    return yield* resolveRef(props.server);
  }
  return yield* Server("Server", {
    serverType: "cpx12",
    image: "ubuntu-24.04",
    location: "fsn1",
    labels: props.tags,
  });
});

export const bindWebsiteDomain = Effect.fn(function* (props: {
  readonly domain: string;
  readonly zone: Ref<Zone>;
  readonly server: Server;
  readonly tags?: Record<string, string> | undefined;
}) {
  const zone = yield* resolveRef(props.zone);
  const name = Output.map((apex: string | undefined) => {
    const domain = props.domain;
    if (apex === undefined || domain === apex) return "@";
    const suffix = `.${apex}`;
    if (domain.endsWith(suffix)) return domain.slice(0, -suffix.length);
    throw new Error(`Hetzner.Website domain "${domain}" is not inside zone "${apex}"`);
  })(zone.name as never);
  yield* RecordSet("Domain", {
    zone,
    name: name as never,
    type: "A",
    records: [{ value: props.server.ipv4 as never }],
    labels: props.tags,
  });
});

export const websiteUrl = (args: {
  readonly domain?: string | undefined;
  readonly service: Service;
  readonly port: number;
}) => (args.domain !== undefined ? `http://${args.domain}:${String(args.port)}` : args.service.url);

/**
 * Shared implementation behind the Hetzner framework website composites:
 * build through the Node deploy target, then host one Service on a
 * Hetzner Server (auto-created `cpx12` in `fsn1` when `server` is omitted).
 *
 * During `alchemy dev` the site is the framework's own dev server and no
 * cloud resources are declared; `Alchemy.remote()` opts back into the
 * live Service path.
 */
const runFrameworkSite = Effect.fn("Hetzner.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 port = DEFAULT_WEBSITE_PORT;

  if (config.static?.spa && config.static.errorPage) {
    return yield* Effect.die(
      `Cannot provide both "spa" and "errorPage". A SPA answers misses with the index page (200); "errorPage" answers them with a real 404.`,
    );
  }
  yield* requireWebsiteDomainZone(`Hetzner.Website "${config.name}"`, props);

  const build = yield* FrameworkServer("Build", {
    framework: config.framework,
    target: config.target,
    root: props.rootDir,
    env: unwrapEnv(props.env),
    options: config.options,
    memo: props.memo,
    dev: props.dev,
  });

  if (isLocal) {
    return {
      url: build.url,
      server: undefined,
      service: undefined,
    };
  }

  // 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 FrameworkSiteError({
              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 FrameworkSiteError({
              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);

  const server = yield* resolveWebsiteServer(props);
  const env = {
    ...unwrapEnv(props.env),
    PORT: String(port),
  };

  const extraFiles = Output.mapEffect((out: { distDir: string; main: string }) =>
    packSiteExtraFiles(out.distDir, config.skipClientAssets === true ? "next" : "client").pipe(
      Effect.map((files) =>
        files?.map((file) => ({
          source: file.source,
          destination: file.dest,
        })),
      ),
    ),
  )(buildOut);

  const service = yield* Service("Service", {
    server,
    main: main as unknown as string,
    extraFiles: extraFiles as unknown as Array<{
      source: string;
      destination: string;
    }>,
    port,
    env,
    isExternal: true,
    build:
      config.install !== undefined && config.install.length > 0
        ? { install: config.install }
        : undefined,
  });

  yield* publishWebsiteDomain({
    domain: props.domain,
    zone: props.zone,
    server,
    tags: props.tags,
  });

  return {
    url: websiteUrl({
      domain: websiteDomainName(props.domain),
      service,
      port,
    }),
    server,
    service,
  };
});

/**
 * Composite-level tagged errors (`FrameworkSiteError`, 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);