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

import * as Hetzner from "@distilled.cloud/hetzner";
import type { GetPrimaryIpResponsePrimaryIp } from "@distilled.cloud/hetzner/primary_ips";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { tagRecord } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { waitForAction } from "./actions.ts";
import { findLocation } from "./Catalog.ts";
import {
  alchemyStackSelector,
  createInternalLabels,
  diffLabels,
  hasAlchemyLabels,
  stripInternalLabels,
  toLabels,
} from "./Labels.ts";
import type { Providers } from "./Providers.ts";

export type PrimaryIpType = "ipv4" | "ipv6";

export interface PrimaryIpProps {
  /**
   * Address family. Cannot be changed after creation — changing it
   * triggers a replacement.
   */
  type: PrimaryIpType;
  /**
   * Location name (`nbg1`, `fsn1`, `hel1`, …) or numeric Location ID.
   * Required unless `datacenter` is set. Cannot be changed after
   * creation — changing it triggers a replacement.
   */
  location?: string | number;
  /**
   * Datacenter name (`nbg1-dc3`, `fsn1-dc14`, …) or numeric Datacenter
   * ID. Alternative to `location`; a name is mapped onto the parent
   * Location (`nbg1-dc3` → `nbg1`). Cannot be changed after creation —
   * changing it triggers a replacement.
   */
  datacenter?: string | number;
  /**
   * Name of the Primary IP. Must be unique per Hetzner project. If
   * omitted, a unique name is generated from the stack, stage, and
   * logical ID.
   */
  name?: string;
  /**
   * If enabled, Hetzner deletes this Primary IP when its assigned
   * resource is deleted.
   * @default false
   */
  autoDelete?: boolean;
  /**
   * User-defined labels (`key`/`value` pairs) applied to the Primary IP.
   * Alchemy ownership labels are added automatically.
   */
  labels?: Record<string, string>;
  /**
   * Prevent the Primary IP from being deleted via the API.
   * @default false
   */
  deleteProtection?: boolean;
}

export type PrimaryIp = Resource<
  "Hetzner.PrimaryIp",
  PrimaryIpProps,
  {
    /**
     * Numeric Hetzner ID of the Primary IP.
     */
    id: number;
    /**
     * Name of the Primary IP.
     */
    name: string;
    /**
     * Address family of the Primary IP.
     */
    type: PrimaryIpType;
    /**
     * Assigned address. For `ipv6` this is the `/64` network.
     */
    ip: string;
    /**
     * Location name the IP is bound to (`nbg1`, `fsn1`, …).
     */
    location: string;
    /**
     * Numeric Location id.
     */
    locationId: number;
    /**
     * Datacenter name or id from props, when the resource was placed via
     * `datacenter`. Not returned by the API.
     */
    datacenter: string | undefined;
    /**
     * Whether Hetzner has blocked the Primary IP.
     */
    blocked: boolean;
    /**
     * Auto-delete flag.
     */
    autoDelete: boolean;
    /**
     * Assigned resource id, or `null` if unassigned.
     */
    assigneeId: number | null;
    /**
     * Assigned resource type (`server`), when assigned.
     */
    assigneeType: string | undefined;
    /**
     * RFC3339 timestamp when the Primary IP was created.
     */
    created: string;
    /**
     * User-defined labels (Alchemy ownership labels are stripped).
     */
    labels: Record<string, string>;
    /**
     * Whether delete protection is enabled.
     */
    deleteProtection: boolean;
  },
  never,
  Providers
>;

/**
 * An unassigned Hetzner Cloud Primary IP. Provide `type` and either a
 * `location` or a `datacenter`; Alchemy generates a unique name unless
 * you set `name`. Assignee wiring is a later resource.
 *
 * `type`, `location`, and `datacenter` are immutable — changing any of
 * them replaces the Primary IP (new address). `name`, `autoDelete`,
 * `labels`, and `deleteProtection` update in place.
 *
 * @see https://docs.hetzner.cloud/reference/cloud#primary-ips
 *
 * ### Creating a Primary IP
 * **Example:** IPv6 in Nuremberg
 * ```typescript
 * const ip = yield* Hetzner.PrimaryIp("web-ipv6", {
 *   type: "ipv6",
 *   location: "nbg1",
 * });
 * ```
 *
 * **Example:** IPv4 placed by datacenter
 * ```typescript
 * const ip = yield* Hetzner.PrimaryIp("web-ipv4", {
 *   type: "ipv4",
 *   datacenter: "nbg1-dc3",
 * });
 * ```
 *
 * ### Labels and auto-delete
 * **Example:** Named IP with labels
 * ```typescript
 * const ip = yield* Hetzner.PrimaryIp("mail", {
 *   name: "mail-ipv4",
 *   type: "ipv4",
 *   location: "fsn1",
 *   autoDelete: false,
 *   labels: { role: "mail" },
 * });
 * ```
 *
 * @resource
 * @product IP Address
 */
export const PrimaryIp = Resource<PrimaryIp>("Hetzner.PrimaryIp");

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

type CloudPrimaryIp = GetPrimaryIpResponsePrimaryIp;

const asType = (type: string): PrimaryIpType => (type === "ipv6" ? "ipv6" : "ipv4");

const userLabels = (
  labels: Record<string, string | undefined> | null | undefined,
): Record<string, string> => stripInternalLabels(tagRecord(labels));

/**
 * Hetzner datacenter names are `{location}-dc{n}` (e.g. `nbg1-dc3`).
 * Numeric ids are passed through — Locations use a different id space.
 */
export const locationFromDatacenter = (datacenter: string | number): string | number => {
  if (typeof datacenter === "number") return datacenter;
  const match = /^([a-z0-9]+)-dc\d+$/i.exec(datacenter);
  return match ? match[1]!.toLowerCase() : datacenter;
};

const resolvePlacement = (
  props: Pick<PrimaryIpProps, "location" | "datacenter">,
): string | number | undefined => {
  if (props.location !== undefined) return props.location;
  if (props.datacenter !== undefined) {
    return locationFromDatacenter(props.datacenter);
  }
  return undefined;
};

const samePlacement = (
  news: Pick<PrimaryIpProps, "location" | "datacenter">,
  attrs: PrimaryIp["Attributes"],
): boolean => {
  const desired = resolvePlacement(news);
  if (desired === undefined) return true;
  return (
    desired === attrs.location ||
    desired === attrs.locationId ||
    String(desired) === String(attrs.locationId)
  );
};

const toAttrs = (
  ip: CloudPrimaryIp,
  extras?: { datacenter?: string | number },
): PrimaryIp["Attributes"] => ({
  id: ip.id,
  name: ip.name,
  type: asType(ip.type),
  ip: ip.ip,
  location: ip.location.name,
  locationId: ip.location.id,
  datacenter: extras?.datacenter !== undefined ? String(extras.datacenter) : undefined,
  blocked: ip.blocked,
  autoDelete: ip.auto_delete,
  assigneeId: ip.assignee_id,
  assigneeType: ip.assignee_type,
  created: ip.created,
  labels: userLabels(ip.labels),
  deleteProtection: ip.protection.delete,
});

const createPrimaryIpName = (id: string, name: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    return name ?? existing ?? (yield* createPhysicalName({ id, maxLength: 63 }));
  });

const getById = (id: number) =>
  Hetzner.primaryIps.getPrimaryIp({ id }).pipe(
    Effect.map(({ primary_ip }) => primary_ip),
    Effect.catchTag("NotFound", () => Effect.undefined),
  );

const getByName = (name: string) =>
  Hetzner.primaryIps
    .listPrimaryIps({ name, per_page: 50 })
    .pipe(Effect.map(({ primary_ips }) => primary_ips[0]));

const observe = Effect.fn(function* ({
  name,
  outputId,
}: {
  id: string;
  name?: string;
  outputId?: number;
}) {
  // Identity is the numeric id (cached on `output`) or the unique
  // project-scoped name. Do NOT fall back to alchemy.* labels: a
  // replacement shares the logical id with the old generation, so a
  // label lookup would adopt the IP we are replacing.
  if (outputId !== undefined) {
    const byId = yield* getById(outputId);
    if (byId !== undefined) return byId;
  }
  if (name !== undefined) {
    return yield* getByName(name);
  }
  return undefined;
});

const refresh = (id: number) =>
  Hetzner.primaryIps.getPrimaryIp({ id }).pipe(
    Effect.map(({ primary_ip }) => primary_ip),
    Effect.retry({
      while: (e) => e._tag === "NotFound",
      times: 5,
      schedule: Schedule.min([
        Schedule.exponential(Duration.millis(200), 1.5),
        Schedule.spaced(Duration.seconds(2)),
      ]),
    }),
  );

const disableProtection = (id: number) =>
  Hetzner.primaryIpActions
    .changePrimaryIpProtection({ id, delete: false })
    .pipe(Effect.flatMap(({ action }) => waitForAction(action)));

export const PrimaryIpProvider = () =>
  Provider.succeed(PrimaryIp, {
    stables: ["id", "ip", "type", "location", "locationId", "created"],
    nuke: { dependsOn: ["Hetzner.Server"] },
    list: Effect.fn(function* () {
      const items = yield* Hetzner.primaryIps.listPrimaryIps
        .items({ label_selector: alchemyStackSelector, per_page: 50 })
        .pipe(
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk)),
        );
      return items.map((ip) => toAttrs(ip));
    }),
    diff: Effect.fn(function* ({ news, output }) {
      if (!isResolved(news)) return undefined;
      if (output !== undefined) {
        if (news.type !== output.type) {
          return { action: "replace" } as const;
        }
        if (!samePlacement(news, output)) {
          return { action: "replace" } as const;
        }
      }
      return undefined;
    }),
    read: Effect.fn(function* ({ id, olds, output }) {
      const found = yield* observe({ id, name: olds?.name ?? output?.name, outputId: output?.id });
      if (found === undefined) return undefined;
      const attrs = toAttrs(found, { datacenter: olds?.datacenter ?? output?.datacenter });
      const owned = yield* hasAlchemyLabels(id, tagRecord(found.labels));
      return owned ? attrs : Unowned(attrs);
    }),
    reconcile: Effect.fn(function* ({ id, news, output }) {
      const name = yield* createPrimaryIpName(id, news.name, output?.name);
      const internalLabels = yield* createInternalLabels(id);
      const desiredLabels = { ...toLabels(news.labels), ...internalLabels };
      const desiredAutoDelete = news.autoDelete ?? false;
      const desiredProtection = news.deleteProtection ?? false;

      // Observe — cloud state is authoritative. `output.id` is a cache
      // for the stable identifier; if the IP is gone, we recreate.
      let current = yield* observe({ id, name, outputId: output?.id });

      // Ensure — create only when missing. A Conflict is a race with a
      // peer reconciler or a name that just became visible; re-observe.
      if (current === undefined) {
        const placement = resolvePlacement(news);
        if (placement === undefined) {
          return yield* new PrimaryIpPlacementRequired({
            message: "PrimaryIp requires `location` or `datacenter` when creating",
          });
        }
        const location = yield* findLocation(placement);
        const created = yield* Hetzner.primaryIps
          .createPrimaryIp({
            name,
            type: news.type,
            location: location.name,
            labels: desiredLabels,
            auto_delete: desiredAutoDelete,
          })
          .pipe(
            Effect.catchTag("Conflict", () =>
              observe({ id, name }).pipe(
                Effect.flatMap((hit) =>
                  hit !== undefined
                    ? Effect.succeed({ primary_ip: hit, action: undefined })
                    : Hetzner.primaryIps.createPrimaryIp({
                        name,
                        type: news.type,
                        location: location.name,
                        labels: desiredLabels,
                        auto_delete: desiredAutoDelete,
                      }),
                ),
              ),
            ),
          );
        if (created.action) {
          yield* waitForAction(created.action);
        }
        current = created.primary_ip;
      }

      // Sync — name / auto_delete / labels via PUT (labels overwrite the
      // full set). Protection is a separate Action.
      const observedLabels = tagRecord(current.labels);
      const { upsert, removed } = diffLabels(observedLabels, desiredLabels);
      const needsUpdate =
        current.name !== name ||
        current.auto_delete !== desiredAutoDelete ||
        upsert.length > 0 ||
        removed.length > 0;
      if (needsUpdate) {
        const updated = yield* Hetzner.primaryIps.updatePrimaryIp({
          id: current.id,
          name,
          auto_delete: desiredAutoDelete,
          labels: desiredLabels,
        });
        current = updated.primary_ip;
      }

      if (current.protection.delete !== desiredProtection) {
        const { action } = yield* Hetzner.primaryIpActions.changePrimaryIpProtection({
          id: current.id,
          delete: desiredProtection,
        });
        yield* waitForAction(action);
      }

      return toAttrs(yield* refresh(current.id), { datacenter: news.datacenter });
    }),
    delete: Effect.fn(function* ({ output }) {
      const current = yield* getById(output.id);
      if (current === undefined) return;
      if (current.protection.delete) {
        yield* disableProtection(current.id);
      }
      if (current.assignee_id !== null) {
        const { action } = yield* Hetzner.primaryIpActions.unassignPrimaryIp({ id: current.id });
        yield* waitForAction(action);
      }
      yield* Hetzner.primaryIps
        .deletePrimaryIp({ id: current.id })
        .pipe(Effect.catchTag("NotFound", () => Effect.void));
    }),
  });