import * as Hetzner from "@distilled.cloud/hetzner";
import type { GetFloatingIpResponseFloatingIp } from "@distilled.cloud/hetzner/floating_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,
labelSelector,
stripInternalLabels,
toLabels,
} from "./Labels.ts";
import type { Providers } from "./Providers.ts";
export type FloatingIpType = "ipv4" | "ipv6";
export interface FloatingIpProps {
/**
* Address family of the Floating IP. Cannot be changed after creation —
* changing it triggers a replacement.
*/
type: FloatingIpType;
/**
* Home Location for the Floating IP (`nbg1`, `fsn1`, `hel1`, …) or the
* Location's numeric id. Routing is optimized for this Location. Cannot
* be changed after creation — changing it triggers a replacement.
*/
homeLocation: string | number;
/**
* Name of the Floating IP. Must be unique per Hetzner project. If
* omitted, a unique name is generated from the stack, stage, and
* logical ID.
*/
name?: string;
/**
* Free-form description shown in the Hetzner Cloud Console.
*/
description?: string | null;
/**
* User-defined labels (`key`/`value` pairs) applied to the Floating IP.
* Alchemy ownership labels are added automatically.
*/
labels?: Record<string, string>;
/**
* Prevent the Floating IP from being deleted via the API.
* @default false
*/
deleteProtection?: boolean;
}
export type FloatingIp = Resource<
"Hetzner.FloatingIp",
FloatingIpProps,
{
/**
* Numeric Hetzner ID of the Floating IP.
*/
id: number;
/**
* Name of the Floating IP.
*/
name: string;
/**
* Address family of the Floating IP.
*/
type: FloatingIpType;
/**
* Assigned address. For `ipv6` this is the `/64` network.
*/
ip: string;
/**
* Home Location name (`nbg1`, `fsn1`, …).
*/
homeLocation: string;
/**
* Numeric ID of the home Location.
*/
homeLocationId: number;
/**
* Description of the Floating IP, or `null` if unset.
*/
description: string | null;
/**
* Whether Hetzner has blocked the Floating IP.
*/
blocked: boolean;
/**
* Whether delete protection is enabled.
*/
deleteProtection: boolean;
/**
* User-defined labels (Alchemy ownership labels are stripped).
*/
labels: Record<string, string>;
/**
* RFC3339 timestamp when the Floating IP was created.
*/
created: string;
/**
* Numeric Server ID this Floating IP is assigned to, or `null` if
* unassigned. Assignment is managed by `FloatingIpAssignment`.
*/
serverId: number | null;
},
never,
Providers
>;
/**
* An unassigned Hetzner Cloud Floating IP. Provide `type` and a
* `homeLocation`; Alchemy generates a unique name unless you set `name`.
* Assignment to a Server is a separate `FloatingIpAssignment` resource.
*
* `type` and `homeLocation` are immutable — changing either replaces the
* Floating IP (new address). `name`, `description`, `labels`, and
* `deleteProtection` update in place.
*
* @see https://docs.hetzner.cloud/reference/cloud#floating-ips
*
* ### Creating a Floating IP
* **Example:** Unassigned IPv4 in nbg1
* ```typescript
* const ip = yield* Hetzner.FloatingIp("public-ip", {
* type: "ipv4",
* homeLocation: "nbg1",
* });
* ```
*
* **Example:** IPv6 with description and labels
* ```typescript
* const ip = yield* Hetzner.FloatingIp("v6", {
* type: "ipv6",
* homeLocation: "nbg1",
* description: "edge anycast",
* labels: { role: "edge" },
* });
* ```
*
* ### Updating a Floating IP
* **Example:** Rename and relabel
* ```typescript
* const ip = yield* Hetzner.FloatingIp("public-ip", {
* type: "ipv4",
* homeLocation: "nbg1",
* name: "public-ip-prod",
* description: "production frontend",
* labels: { env: "prod" },
* });
* ```
*
* @resource
* @product IP Address
*/
export const FloatingIp = Resource<FloatingIp>("Hetzner.FloatingIp");
type CloudFloatingIp = GetFloatingIpResponseFloatingIp;
const asType = (type: string): FloatingIpType => (type === "ipv6" ? "ipv6" : "ipv4");
const userLabels = (
labels: Record<string, string | undefined> | null | undefined,
): Record<string, string> => stripInternalLabels(tagRecord(labels));
const toAttrs = (ip: CloudFloatingIp): FloatingIp["Attributes"] => ({
id: ip.id,
name: ip.name,
type: asType(ip.type),
ip: ip.ip,
homeLocation: ip.home_location.name,
homeLocationId: ip.home_location.id,
description: ip.description,
blocked: ip.blocked,
deleteProtection: ip.protection.delete,
labels: userLabels(ip.labels),
created: ip.created,
serverId: ip.server,
});
const createFloatingIpName = (id: string, name: string | undefined, existing?: string) =>
Effect.gen(function* () {
return name ?? existing ?? (yield* createPhysicalName({ id, maxLength: 63 }));
});
const getById = (id: number) =>
Hetzner.floatingIps.getFloatingIp({ id }).pipe(
Effect.map(({ floating_ip }) => floating_ip),
Effect.catchTag("NotFound", () => Effect.undefined),
);
const getByName = (name: string) =>
Hetzner.floatingIps
.listFloatingIps({ name, per_page: 50 })
.pipe(Effect.map(({ floating_ips }) => floating_ips[0]));
const getByLabels = (labels: Record<string, string>) =>
Hetzner.floatingIps
.listFloatingIps({ label_selector: labelSelector(labels), per_page: 50 })
.pipe(Effect.map(({ floating_ips }) => floating_ips[0]));
const observe = Effect.fn(function* ({
id,
name,
outputId,
}: {
id: string;
name?: string;
outputId?: number;
}) {
if (outputId !== undefined) {
const byId = yield* getById(outputId);
if (byId !== undefined) return byId;
}
if (name !== undefined) {
const byName = yield* getByName(name);
if (byName !== undefined) return byName;
}
const internal = yield* createInternalLabels(id);
return yield* getByLabels(internal);
});
const refresh = (id: number) =>
Hetzner.floatingIps.getFloatingIp({ id }).pipe(
Effect.map(({ floating_ip }) => floating_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 sameHomeLocation = (
desired: string | number,
attrs: Pick<FloatingIp["Attributes"], "homeLocation" | "homeLocationId">,
): boolean =>
desired === attrs.homeLocation ||
desired === attrs.homeLocationId ||
String(desired) === String(attrs.homeLocationId);
const matchesDesired = (
ip: CloudFloatingIp,
type: FloatingIpType,
location: { name: string; id: number },
): boolean =>
asType(ip.type) === type &&
sameHomeLocation(location.name, {
homeLocation: ip.home_location.name,
homeLocationId: ip.home_location.id,
});
const disableProtection = (id: number) =>
Hetzner.floatingIpActions
.changeFloatingIpProtection({ id, delete: false })
.pipe(Effect.flatMap(({ action }) => waitForAction(action)));
export class FloatingIpNotCreated extends Data.TaggedError("Hetzner.FloatingIpNotCreated")<{
resourceName: string;
}> {}
export const FloatingIpProvider = () =>
Provider.succeed(FloatingIp, {
stables: ["id", "ip", "type", "homeLocation", "homeLocationId", "created"],
nuke: { dependsOn: ["Hetzner.Server"] },
list: Effect.fn(function* () {
const items = yield* Hetzner.floatingIps.listFloatingIps
.items({ label_selector: alchemyStackSelector, per_page: 50 })
.pipe(
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk)),
);
return items.map(toAttrs);
}),
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 (!sameHomeLocation(news.homeLocation, 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);
const owned = yield* hasAlchemyLabels(id, tagRecord(found.labels));
return owned ? attrs : Unowned(attrs);
}),
reconcile: Effect.fn(function* ({ id, news, output }) {
const location = yield* findLocation(news.homeLocation);
const name = yield* createFloatingIpName(id, news.name, output?.name);
const internalLabels = yield* createInternalLabels(id);
const desiredLabels = { ...toLabels(news.labels), ...internalLabels };
const desiredDescription = news.description ?? null;
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: CloudFloatingIp | undefined = yield* observe({ id, name, outputId: output?.id });
// A previous generation found via ownership labels (same logical id,
// different type/location) is the resource being replaced — do not
// take it over; create a new Floating IP instead.
if (
current !== undefined &&
current.id !== output?.id &&
!matchesDesired(current, news.type, location)
) {
current = undefined;
}
// 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 created = yield* Hetzner.floatingIps
.createFloatingIp({
type: news.type,
home_location: location.name,
name,
description: desiredDescription,
labels: desiredLabels,
})
.pipe(Effect.catchTag("Conflict", () => Effect.undefined));
if (created !== undefined) {
if (created.action) {
yield* waitForAction(created.action);
}
current = created.floating_ip;
} else {
const hit = yield* observe({ id, name });
if (hit !== undefined && matchesDesired(hit, news.type, location)) {
current = hit;
}
}
}
if (current === undefined) {
return yield* new FloatingIpNotCreated({ resourceName: name });
}
// Sync — name / description / 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.description ?? null) !== desiredDescription ||
upsert.length > 0 ||
removed.length > 0;
if (needsUpdate) {
const updated = yield* Hetzner.floatingIps.updateFloatingIp({
id: current.id,
name,
description: desiredDescription,
labels: desiredLabels,
});
current = updated.floating_ip;
}
if (current.protection.delete !== desiredProtection) {
const { action } = yield* Hetzner.floatingIpActions.changeFloatingIpProtection({
id: current.id,
delete: desiredProtection,
});
yield* waitForAction(action);
}
return toAttrs(yield* refresh(current.id));
}),
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.server !== null) {
const { action } = yield* Hetzner.floatingIpActions.unassignFloatingIp({ id: current.id });
yield* waitForAction(action);
}
yield* Hetzner.floatingIps
.deleteFloatingIp({ id: current.id })
.pipe(Effect.catchTag("NotFound", () => Effect.void));
}),
});