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

import * as Hetzner from "@distilled.cloud/hetzner";
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 {
  alchemyStackSelector,
  createInternalLabels,
  diffLabels,
  hasAlchemyLabels,
  labelSelector,
  stripInternalLabels,
  toLabels,
} from "./Labels.ts";
import type { Providers } from "./Providers.ts";

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

export type NetworkSubnetType = "cloud" | "server" | "vswitch";

export interface NetworkSubnet {
  /**
   * Subnet type. `cloud` is the usual choice for Cloud Servers and Load
   * Balancers. `vswitch` attaches a Robot vSwitch and requires `vswitchId`.
   */
  type: NetworkSubnetType;
  /**
   * IPv4 range of the subnet in CIDR notation. Must be a subnet of the
   * parent network `ipRange` and must not overlap other subnets or route
   * destinations. Minimum size is `/30`. If omitted on create, Hetzner
   * allocates the first free `/24`.
   */
  ipRange?: string;
  /**
   * Network zone this subnet lives in (`eu-central`, `us-east`, `us-west`,
   * `ap-southeast`). `nbg1` / `fsn1` / `hel1` are in `eu-central`.
   */
  networkZone: string;
  /**
   * Robot vSwitch id. Required when `type` is `vswitch`.
   */
  vswitchId?: number;
}

export interface NetworkRoute {
  /**
   * Destination prefix. Must be an RFC1918 IPv4 range or `0.0.0.0/0`, and
   * must not overlap any subnet or other route destination.
   */
  destination: string;
  /**
   * Next-hop IP inside the network. Cannot be the first IP of the
   * network's `ipRange` or `172.31.1.1`.
   */
  gateway: string;
}

export interface NetworkProps {
  /**
   * Name of the Network. Must be unique per project. If omitted, a unique
   * name is generated from the app, stage, and logical ID.
   */
  name?: string;
  /**
   * IPv4 range of the whole Network in CIDR notation. Must be RFC1918 and
   * at least `/24`. Can only be **extended** later (`change_ip_range`);
   * shrinking or moving to a non-superset range replaces the Network.
   */
  ipRange: string;
  /**
   * Subnets allocated in this Network. Synced via `add_subnet` /
   * `delete_subnet` — they are not their own resources.
   */
  subnets?: NetworkSubnet[];
  /**
   * Static routes in this Network. Synced via `add_route` / `delete_route`.
   */
  routes?: NetworkRoute[];
  /**
   * Expose this Network's routes to a connected Robot vSwitch.
   * @default false
   */
  exposeRoutesToVswitch?: boolean;
  /**
   * Prevent the Network from being deleted in the Cloud Console / API
   * until this is cleared. The provider disables protection before delete.
   * @default false
   */
  deleteProtection?: boolean;
  /**
   * User-defined labels. Alchemy ownership labels (`alchemy.stack` /
   * `alchemy.stage` / `alchemy.id`) are merged in automatically.
   */
  labels?: Record<string, string>;
}

export interface NetworkSubnetAttr extends NetworkSubnet {
  /** Gateway Hetzner assigned to this subnet. */
  gateway: string;
}

export type Network = Resource<
  "Hetzner.Network",
  NetworkProps,
  {
    /** Numeric Hetzner Network id. */
    networkId: number;
    /** Observed Network name. */
    name: string;
    /** Observed IPv4 range (CIDR). */
    ipRange: string;
    /** Observed subnets, including the assigned gateway. */
    subnets: NetworkSubnetAttr[];
    /** Observed static routes. */
    routes: NetworkRoute[];
    /** Server ids currently attached to this Network. */
    servers: number[];
    /** Load Balancer ids currently attached to this Network. */
    loadBalancers: number[];
    /** Whether delete protection is enabled. */
    deleteProtection: boolean;
    /** Whether routes are exposed to a connected vSwitch. */
    exposeRoutesToVswitch: boolean;
    /** User-facing labels (Alchemy ownership labels stripped). */
    labels: Record<string, string>;
    /** RFC3339 creation timestamp. */
    created: string;
  },
  never,
  Providers
>;

/**
 * A Hetzner Cloud private Network — an isolated IPv4 range that Cloud
 * Servers and Load Balancers attach to. Subnets, routes, delete protection,
 * and labels are synced on the Network itself; `network_actions` are not
 * modeled as their own resources.
 *
 * @see https://docs.hetzner.cloud/reference/cloud#networks
 *
 * ### Creating a Network
 * **Example:** Basic Network
 * ```typescript
 * const network = yield* Hetzner.Network("vpc", {
 *   ipRange: "10.0.0.0/16",
 * });
 * ```
 *
 * **Example:** Network with a cloud subnet
 * ```typescript
 * const network = yield* Hetzner.Network("vpc", {
 *   ipRange: "10.0.0.0/16",
 *   subnets: [
 *     { type: "cloud", ipRange: "10.0.1.0/24", networkZone: "eu-central" },
 *   ],
 * });
 * ```
 *
 * ### Routes and protection
 * **Example:** Static route and delete protection
 * ```typescript
 * const network = yield* Hetzner.Network("vpc", {
 *   ipRange: "10.0.0.0/16",
 *   subnets: [
 *     { type: "cloud", ipRange: "10.0.1.0/24", networkZone: "eu-central" },
 *   ],
 *   routes: [{ destination: "10.10.0.0/24", gateway: "10.0.1.2" }],
 *   deleteProtection: true,
 * });
 * ```
 *
 * ### Labels
 * **Example:** User labels
 * ```typescript
 * const network = yield* Hetzner.Network("vpc", {
 *   ipRange: "10.0.0.0/16",
 *   labels: { env: "prod", role: "vpc" },
 * });
 * ```
 *
 * @resource
 * @product Network
 */
export const Network = Resource<Network>("Hetzner.Network");

type ObservedNetwork = {
  id: number;
  name: string;
  ip_range: string;
  subnets: ReadonlyArray<{
    type: string;
    ip_range?: string;
    network_zone: string;
    gateway: string;
    vswitch_id?: number | null;
  }>;
  routes: ReadonlyArray<{ destination: string; gateway: string }>;
  servers: ReadonlyArray<number>;
  load_balancers?: ReadonlyArray<number>;
  protection: { delete: boolean };
  labels: Record<string, string | undefined>;
  created: string;
  expose_routes_to_vswitch: boolean;
};

const busy = (e: { readonly _tag: string }): boolean =>
  e._tag === "Locked" || e._tag === "Conflict";

const busyRetry = {
  while: busy,
  times: 8,
  schedule: Schedule.min([
    Schedule.exponential(Duration.millis(500), 1.5),
    Schedule.spaced(Duration.seconds(5)),
  ]),
} as const;

const alreadyThere = (e: { readonly _tag: string }): boolean =>
  e._tag === "Conflict" || e._tag === "UnprocessableEntity";

const alreadyGone = (e: { readonly _tag: string }): boolean =>
  e._tag === "NotFound" || e._tag === "UnprocessableEntity";

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

const desiredLabelsOf = Effect.fn(function* (
  id: string,
  labels: Record<string, string> | undefined,
) {
  return {
    ...toLabels(labels),
    ...(yield* createInternalLabels(id)),
  };
});

const subnetKey = (subnet: {
  type: string;
  ipRange?: string;
  networkZone: string;
  vswitchId?: number | null;
}): string =>
  `${subnet.type}|${subnet.ipRange ?? ""}|${subnet.networkZone}|${subnet.vswitchId ?? ""}`;

const routeKey = (route: { destination: string; gateway: string }): string =>
  `${route.destination}|${route.gateway}`;

const toSubnetAttr = (subnet: ObservedNetwork["subnets"][number]): NetworkSubnetAttr => ({
  type: subnet.type as NetworkSubnetType,
  ipRange: subnet.ip_range,
  networkZone: subnet.network_zone,
  gateway: subnet.gateway,
  vswitchId: subnet.vswitch_id ?? undefined,
});

const toAttrs = (network: ObservedNetwork): Network["Attributes"] => ({
  networkId: network.id,
  name: network.name,
  ipRange: network.ip_range,
  subnets: network.subnets.map(toSubnetAttr),
  routes: network.routes.map((route) => ({
    destination: route.destination,
    gateway: route.gateway,
  })),
  servers: [...network.servers],
  loadBalancers: [...(network.load_balancers ?? [])],
  deleteProtection: network.protection.delete,
  exposeRoutesToVswitch: network.expose_routes_to_vswitch,
  labels: stripInternalLabels(tagRecord(network.labels)),
  created: network.created,
});

const parseCidr = (cidr: string): { ip: number; prefix: number } | undefined => {
  const [addr, prefixRaw] = cidr.split("/");
  if (addr === undefined || prefixRaw === undefined) return undefined;
  const parts = addr.split(".").map(Number);
  if (
    parts.length !== 4 ||
    parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)
  ) {
    return undefined;
  }
  const prefix = Number(prefixRaw);
  if (!Number.isInteger(prefix) || prefix < 0 || prefix > 32) return undefined;
  const ip = ((parts[0]! << 24) | (parts[1]! << 16) | (parts[2]! << 8) | parts[3]!) >>> 0;
  return { ip, prefix };
};

/** True when `outer` is equal to or a supernet of `inner`. */
const cidrContains = (outer: string, inner: string): boolean => {
  const a = parseCidr(outer);
  const b = parseCidr(inner);
  if (a === undefined || b === undefined) return false;
  if (a.prefix > b.prefix) return false;
  const mask = a.prefix === 0 ? 0 : (0xffffffff << (32 - a.prefix)) >>> 0;
  return (a.ip & mask) === (b.ip & mask);
};

const getById = (id: number) =>
  Hetzner.networks.getNetwork({ id }).pipe(
    Effect.map(({ network }) => network),
    Effect.catchTag("NotFound", () => Effect.undefined),
  );

const findByName = (name: string) =>
  Hetzner.networks
    .listNetworks({ name, per_page: 50 })
    .pipe(Effect.map(({ networks }) => networks.find((item) => item.name === name)));

const findByLabels = (labels: Record<string, string>) =>
  Hetzner.networks
    .listNetworks({
      label_selector: labelSelector(labels),
      per_page: 50,
    })
    .pipe(Effect.map(({ networks }) => networks[0]));

const observe = (networkId: number | undefined, name: string, id: string) =>
  Effect.gen(function* () {
    if (networkId !== undefined) {
      const byId = yield* getById(networkId);
      if (byId) return byId;
    }
    const byLabels = yield* findByLabels(yield* createInternalLabels(id));
    if (byLabels) return byLabels;
    return yield* findByName(name);
  });

const runAction = <E extends { readonly _tag: string }, R>(
  effect: Effect.Effect<{ action: { id: number } }, E, R>,
) =>
  effect.pipe(
    Effect.retry(busyRetry),
    Effect.flatMap(({ action }) => waitForAction(action)),
  );

const syncIpRange = (networkId: number, observed: string, desired: string) =>
  Effect.gen(function* () {
    if (observed === desired) return;
    yield* runAction(
      Hetzner.networkActions.changeNetworkIpRange({
        id: networkId,
        ip_range: desired,
      }),
    );
  });

const syncMetadata = (args: {
  networkId: number;
  observed: ObservedNetwork;
  name: string;
  exposeRoutesToVswitch: boolean;
  labels: Record<string, string>;
}) =>
  Effect.gen(function* () {
    const observedLabels = tagRecord(args.observed.labels);
    const { removed, upsert } = diffLabels(observedLabels, args.labels);
    const labelsChanged = removed.length > 0 || upsert.length > 0;
    const nameChanged = args.observed.name !== args.name;
    const exposeChanged = args.observed.expose_routes_to_vswitch !== args.exposeRoutesToVswitch;
    if (!labelsChanged && !nameChanged && !exposeChanged) return;
    yield* Hetzner.networks
      .updateNetwork({
        id: args.networkId,
        name: nameChanged ? args.name : undefined,
        expose_routes_to_vswitch: exposeChanged ? args.exposeRoutesToVswitch : undefined,
        labels: labelsChanged ? args.labels : undefined,
      })
      .pipe(Effect.retry(busyRetry));
  });

const syncSubnets = (
  networkId: number,
  observed: ObservedNetwork["subnets"],
  desired: readonly NetworkSubnet[],
) =>
  Effect.gen(function* () {
    const observedMapped = observed.map((subnet) => ({
      type: subnet.type,
      ipRange: subnet.ip_range,
      networkZone: subnet.network_zone,
      vswitchId: subnet.vswitch_id ?? undefined,
    }));
    const observedKeys = new Set(observedMapped.map(subnetKey));
    const desiredKeys = new Set(desired.map(subnetKey));

    for (const subnet of observedMapped) {
      if (desiredKeys.has(subnetKey(subnet))) continue;
      if (subnet.ipRange === undefined) continue;
      yield* runAction(
        Hetzner.networkActions.deleteNetworkSubnet({
          id: networkId,
          ip_range: subnet.ipRange,
        }),
      ).pipe(Effect.catchIf(alreadyGone, () => Effect.void));
    }

    for (const subnet of desired) {
      if (observedKeys.has(subnetKey(subnet))) continue;
      yield* runAction(
        Hetzner.networkActions.addNetworkSubnet({
          id: networkId,
          type: subnet.type,
          ip_range: subnet.ipRange,
          network_zone: subnet.networkZone,
          vswitch_id: subnet.vswitchId,
        }),
      ).pipe(Effect.catchIf(alreadyThere, () => Effect.void));
    }
  });

const syncRoutes = (
  networkId: number,
  observed: ObservedNetwork["routes"],
  desired: readonly NetworkRoute[],
) =>
  Effect.gen(function* () {
    const observedKeys = new Set(observed.map(routeKey));
    const desiredKeys = new Set(desired.map(routeKey));

    for (const route of observed) {
      if (desiredKeys.has(routeKey(route))) continue;
      yield* runAction(
        Hetzner.networkActions.deleteNetworkRoute({
          id: networkId,
          destination: route.destination,
          gateway: route.gateway,
        }),
      ).pipe(Effect.catchIf(alreadyGone, () => Effect.void));
    }

    for (const route of desired) {
      if (observedKeys.has(routeKey(route))) continue;
      yield* runAction(
        Hetzner.networkActions.addNetworkRoute({
          id: networkId,
          destination: route.destination,
          gateway: route.gateway,
        }),
      ).pipe(Effect.catchIf(alreadyThere, () => Effect.void));
    }
  });

const syncProtection = (networkId: number, observed: boolean, desired: boolean) =>
  Effect.gen(function* () {
    if (observed === desired) return;
    yield* runAction(
      Hetzner.networkActions.changeNetworkProtection({
        id: networkId,
        delete: desired,
      }),
    );
  });

export const NetworkProvider = () =>
  Provider.succeed(Network, {
    stables: ["networkId", "created"],

    list: Effect.fn(function* () {
      return yield* Hetzner.networks.listNetworks
        .items({ label_selector: alchemyStackSelector, per_page: 50 })
        .pipe(
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk, toAttrs)),
        );
    }),

    diff: Effect.fn(function* ({ news, output }) {
      if (!isResolved(news)) return undefined;
      if (
        output !== undefined &&
        news.ipRange !== output.ipRange &&
        !cidrContains(news.ipRange, output.ipRange)
      ) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const name = yield* createNetworkName(id, olds?.name ?? output?.name);
      const observed = yield* observe(output?.networkId, name, id);
      if (observed === undefined) return undefined;
      const attrs = toAttrs(observed);
      return (yield* hasAlchemyLabels(id, tagRecord(observed.labels))) ? attrs : Unowned(attrs);
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const name = yield* createNetworkName(
        id,
        news.name ?? (output === undefined ? undefined : output.name),
      );
      const desiredLabels = yield* desiredLabelsOf(id, news.labels);
      const desiredSubnets = news.subnets ?? [];
      const desiredRoutes = news.routes ?? [];
      const exposeRoutesToVswitch = news.exposeRoutesToVswitch ?? false;
      const deleteProtection = news.deleteProtection ?? false;

      // Observe — cached `output.networkId` is a hint. Fall back to
      // ownership labels, then the deterministic name.
      let current = yield* observe(output?.networkId, name, id);

      // A replacement create shares the logical id (and thus ownership
      // labels) with the outgoing generation. If the observed row cannot
      // accept the desired `ipRange` (Hetzner can only extend a range),
      // do not reuse it — create a new Network and let the engine delete
      // the old generation.
      if (
        current !== undefined &&
        current.ip_range !== news.ipRange &&
        !cidrContains(news.ipRange, current.ip_range)
      ) {
        current = undefined;
      }

      // Ensure — create when missing. A name-collision race is treated as
      // the peer winning; we pick that row up and continue into sync.
      if (current === undefined) {
        const created = yield* Hetzner.networks
          .createNetwork({
            name,
            ip_range: news.ipRange,
            labels: desiredLabels,
            subnets: desiredSubnets.map((subnet) => ({
              type: subnet.type,
              ip_range: subnet.ipRange,
              network_zone: subnet.networkZone,
              vswitch_id: subnet.vswitchId,
            })),
            routes: desiredRoutes.map((route) => ({
              destination: route.destination,
              gateway: route.gateway,
            })),
            expose_routes_to_vswitch: exposeRoutesToVswitch,
          })
          .pipe(
            Effect.retry(busyRetry),
            Effect.map((response) => response.network),
            Effect.catchIf(alreadyThere, () => findByName(name)),
          );
        current = created;
      }

      if (current === undefined) {
        return yield* new NetworkNotCreated({ resourceName: name });
      }

      // Sync each mutable aspect from observed cloud state, not `olds`.
      yield* syncIpRange(current.id, current.ip_range, news.ipRange);
      yield* syncMetadata({
        networkId: current.id,
        observed: current,
        name,
        exposeRoutesToVswitch,
        labels: desiredLabels,
      });
      const afterMeta = (yield* getById(current.id)) ?? current;
      yield* syncSubnets(current.id, afterMeta.subnets, desiredSubnets);
      const afterSubnets = (yield* getById(current.id)) ?? afterMeta;
      yield* syncRoutes(current.id, afterSubnets.routes, desiredRoutes);
      const afterRoutes = (yield* getById(current.id)) ?? afterSubnets;
      yield* syncProtection(current.id, afterRoutes.protection.delete, deleteProtection);

      const fresh = yield* getById(current.id);
      return toAttrs(fresh ?? afterRoutes);
    }),

    delete: Effect.fn(function* ({ output }) {
      if (output.deleteProtection) {
        yield* runAction(
          Hetzner.networkActions.changeNetworkProtection({
            id: output.networkId,
            delete: false,
          }),
        ).pipe(Effect.catchIf(alreadyGone, () => Effect.void));
      }
      yield* Hetzner.networks.deleteNetwork({ id: output.networkId }).pipe(
        Effect.retry(busyRetry),
        Effect.catchTag("NotFound", () => Effect.void),
      );
    }),
  });