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

import * as Hetzner from "@distilled.cloud/hetzner";
import * as Bundle from "alchemy/Bundle/Bundle";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import { Platform, type Main, type PlatformProps } from "alchemy/Platform";
import * as Provider from "alchemy/Provider";
import { Resource, type ResourceBinding } from "alchemy/Resource";
import type { ServerHost } from "alchemy/Runtime/Process";
import { Stack } from "alchemy/Stack";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import {
  collectBindingState,
  createHetznerHostedSupport,
  createHetznerHostRuntimeContext,
  type HetznerBuildOptions,
  type HetznerHostRuntimeContext,
} from "./hosted.ts";
import type { ServiceBinding } from "./MountVolume.ts";
import type { Providers } from "./Providers.ts";
import type { Server } from "./Server.ts";
import { sshClientForServer } from "./Ssh.ts";

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

export interface ServiceProps extends PlatformProps {
  /**
   * Server this Service runs on. Accepts a `Hetzner.Server` or an Effect
   * that produces one. Changing the Server replaces the Service.
   */
  server: Ref<Server>;
  /**
   * Module entrypoint bundled with rolldown and copied onto the Server
   * over SSH as a systemd unit.
   */
  main: string;
  /**
   * Port the hosted HTTP server listens on. Written to `PORT` and used
   * to build {@link Service} `url`.
   *
   * @default 3000
   */
  port?: number;
  /**
   * Named export to load from `main`.
   *
   * @default "default"
   */
  handler?: string;
  /**
   * Additional environment variables for the hosted process. Merged after
   * binding-injected `env`.
   */
  env?: Record<string, any>;
  /**
   * Bundler configuration for `main`: rolldown `input`/`output` overrides
   * plus pure-annotation options (`pure`) and `install` for packages that
   * must ship as real `node_modules` (see {@link HetznerBuildOptions}).
   */
  build?: HetznerBuildOptions;
  /**
   * Extra host directories packed into the unit archive next to the
   * bundled entry (e.g. a website `clientDirectory` at `dist/`). Hashed
   * into `code.hash` so asset changes update the unit. Destination is
   * relative to the unit root (`/opt/<unit>/`).
   */
  extraFiles?: ReadonlyArray<{
    source: string;
    destination: string;
  }>;
}

export type Service = Resource<
  "Hetzner.Service",
  ServiceProps,
  {
    /** Numeric Hetzner Server ID the unit runs on. */
    serverId: number;
    /** Public IPv4 of the Server, if attached. */
    ipv4: string | undefined;
    /** Port the process listens on. */
    port: number;
    /** `http://<ipv4>:<port>` when the Server has a public IPv4. */
    url: string | undefined;
    /** systemd unit name (`<name>.service`). */
    unitName: string;
    /** Content hash of the bundled program. */
    code: {
      hash: string;
    };
  },
  ServiceBinding,
  Providers
>;

export const isService = (value: unknown): value is Service =>
  typeof value === "object" &&
  value !== null &&
  (value as { Type?: string }).Type === "Hetzner.Service";

export type ServiceServices = ServerHost;

export type ServiceShape = Main<ServiceServices>;

export type ServiceRuntimeContext = HetznerHostRuntimeContext;

/**
 * An Effect program hosted on a Hetzner Cloud Server as a systemd unit.
 *
 * N Services can share one Server. Each Service is bundled with rolldown,
 * copied over SSH, and restarted as its own unit. Bind
 * `Hetzner.MountVolume` inside the impl to attach a Volume and mount it
 * at a path — the same `(volume, server, path)` from two Services is one
 * attach and one mount.
 *
 * @see https://docs.hetzner.cloud/reference/cloud#servers
 *
 * ### Hosting a Service
 * **Example:** HTTP server on a Server
 * ```typescript
 * const server = yield* Hetzner.Server("box", {
 *   serverType: "cpx12",
 *   image: "ubuntu-24.04",
 *   location: "nbg1",
 * });
 *
 * export default class Api extends Hetzner.Service<Api>()(
 *   "Api",
 *   { server, main: import.meta.url, port: 3000 },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.json({ ok: true })),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### Volumes
 * **Example:** Mount a Volume
 * ```typescript
 * const mount = yield* Hetzner.MountVolume(volume, { path: "/data" });
 * // write/read files under mount.path inside the hosted process
 * ```
 *
 * @resource
 * @product Service
 */
export const Service: Platform<Service, ServiceServices, ServiceShape, ServiceRuntimeContext> =
  Platform("Hetzner.Service", {
    createRuntimeContext: createHetznerHostRuntimeContext("Hetzner.Service"),
    // `{ server: Box }` at module scope is an Effect. Yield it here so the
    // Server is registered and `news.server` is resolved attributes at
    // reconcile (same DX as `yield* Server(...)` inside Effect.gen).
    transformProps: (_id, props) =>
      Effect.gen(function* () {
        if (globalThis.__ALCHEMY_RUNTIME__) return props;
        const server = Effect.isEffect(props.server)
          ? yield* props.server as Effect.Effect<Server, never, Providers>
          : props.server;
        return { ...props, server };
      }),
  });

export class ServiceError extends Data.TaggedError("Hetzner.ServiceError")<{
  message: string;
}> {}

const DEFAULT_PORT = 3000;

const serverIdOf = (value: unknown): number | undefined => {
  if (value === null || typeof value !== "object") return undefined;
  const rec = value as { serverId?: unknown; id?: unknown };
  if (typeof rec.serverId === "number") return rec.serverId;
  if (typeof rec.id === "number") return rec.id;
  return undefined;
};

const ipv4Of = (value: unknown): string | undefined => {
  if (value === null || typeof value !== "object") return undefined;
  const rec = value as { ipv4?: unknown };
  return typeof rec.ipv4 === "string" ? rec.ipv4 : undefined;
};

const unwrapKey = (value: Redacted.Redacted<string> | string | undefined): string | undefined => {
  if (value === undefined) return undefined;
  return typeof value === "string" ? value : Redacted.value(value);
};

const privateKeyOf = (value: unknown): string | undefined => {
  if (value === null || typeof value !== "object") return undefined;
  return unwrapKey((value as { privateKey?: Redacted.Redacted<string> | string }).privateKey);
};

const createUnitName = (id: string, existing?: string) =>
  existing !== undefined
    ? Effect.succeed(existing)
    : createPhysicalName({
        id,
        maxLength: 64,
        lowercase: true,
      }).pipe(Effect.map((name) => name.replaceAll(/[^a-z0-9-]/g, "-")));

const serviceUrl = (ipv4: string | undefined, port: number) =>
  ipv4 !== undefined ? `http://${ipv4}:${port}` : undefined;

export const ServiceProvider = () =>
  Provider.effect(
    Service,
    Effect.gen(function* () {
      const stack = yield* Stack;
      const virtualEntryPlugin = yield* Bundle.virtualEntryPlugin;
      const hosted = createHetznerHostedSupport({
        stackName: stack.name,
        stage: stack.stage,
        virtualEntryPlugin,
      });

      const openSession = (news: ServiceProps) =>
        sshClientForServer(news.server as Server, {
          privateKey: privateKeyOf(news.server),
        });

      return Service.Provider.of({
        stables: ["serverId", "unitName"],
        // systemd units have no Hetzner list API. Nuke deletes the
        // Server they live on; empty list is the documented shape for
        // parent-keyed resources (Provider.list).
        nuke: { dependsOn: ["Hetzner.Server"] },
        list: () => Effect.succeed([]),
        diff: Effect.fn(function* ({ id, news, output }) {
          if (!isResolved(news)) return undefined;
          const nextServer = serverIdOf(news.server);
          if (output !== undefined && nextServer !== undefined && output.serverId !== nextServer) {
            return { action: "replace" } as const;
          }
          if (output !== undefined && news.main) {
            const { hash } = yield* hosted.bundleProgram(id, news);
            if (hash !== output.code.hash) {
              return { action: "update" } as const;
            }
          }
          return undefined;
        }),
        read: Effect.fn(function* ({ olds, output }) {
          if (output === undefined) return undefined;
          const serverId =
            output.serverId ?? (olds !== undefined ? serverIdOf(olds.server) : undefined);
          if (serverId === undefined) return undefined;
          const live = yield* Hetzner.servers.getServer({ id: serverId }).pipe(
            Effect.map(({ server }) => server),
            Effect.catchTag("NotFound", () => Effect.undefined),
          );
          if (live === undefined) return undefined;
          return {
            ...output,
            serverId: live.id,
            ipv4: live.public_net.ipv4?.ip,
            url: serviceUrl(live.public_net.ipv4?.ip, output.port),
          };
        }),
        reconcile: Effect.fn(function* ({ id, news, output, bindings }) {
          const serverId = serverIdOf(news.server);
          if (serverId === undefined) {
            return yield* new ServiceError({
              message: "Service requires a resolved Server",
            });
          }
          const ipv4 = ipv4Of(news.server);
          if (ipv4 === undefined) {
            return yield* new ServiceError({
              message: "Service requires the Server to have a public IPv4",
            });
          }
          const port = news.port ?? DEFAULT_PORT;
          const unitName = yield* createUnitName(id, output?.unitName);
          const { env: bindingEnv, volumes } = collectBindingState(
            bindings as ResourceBinding<ServiceBinding>[],
          );
          const env = {
            ...bindingEnv,
            ...hosted.alchemyEnv,
            ...(news.port !== undefined ? { PORT: String(news.port) } : {}),
            ...news.env,
          };

          const { archive, hash, entryRel } = yield* hosted.bundleProgram(id, news);

          const ssh = yield* openSession(news);
          yield* Effect.ensuring(
            Effect.gen(function* () {
              yield* hosted.waitForSsh(ssh);
              // Attach (no automount) then mkdir+mount+fstab. The same
              // (volume, server, path) from two Services is one attach
              // and one mount — both steps are independently idempotent.
              yield* hosted.attachAndMount({
                ssh,
                serverId,
                volumes,
              });
              yield* hosted.deployUnit({
                ssh,
                unitName,
                archive,
                env,
                entryRel,
              });
            }),
            ssh.close,
          );

          return {
            serverId,
            ipv4,
            port,
            url: serviceUrl(ipv4, port),
            unitName,
            code: { hash },
          };
        }),
        delete: Effect.fn(function* ({ olds, output }) {
          const ssh = yield* openSession(olds).pipe(
            Effect.catchTag("Hetzner.SshError", () => Effect.undefined),
          );
          if (ssh === undefined) return;
          yield* Effect.ensuring(hosted.removeUnit({ ssh, unitName: output.unitName }), ssh.close);
        }),
      });
    }),
  );