The best way to control Claude Code, Codex and more from any computer or phone

main
ts 1,083 lines 35.9 KB
Raw
1 import { generateKeyPairSync } from "node:crypto";
2 import * as Hetzner from "@distilled.cloud/hetzner";
3 import type {
4 GetServerResponseServer,
5 ListServersResponseServersItem,
6 } from "@distilled.cloud/hetzner/servers";
7 import { Unowned } from "alchemy/AdoptPolicy";
8 import { isResolved } from "alchemy/Diff";
9 import { createPhysicalName } from "alchemy/PhysicalName";
10 import * as Provider from "alchemy/Provider";
11 import { Resource } from "alchemy/Resource";
12 import { tagRecord } from "alchemy/Tags";
13 import * as Data from "effect/Data";
14 import * as Duration from "effect/Duration";
15 import * as Effect from "effect/Effect";
16 import * as Redacted from "effect/Redacted";
17 import * as Schedule from "effect/Schedule";
18 import * as Stream from "effect/Stream";
19 import { waitForAction, waitForActions } from "./actions.ts";
20 import {
21 alchemyStackSelector,
22 createInternalLabels,
23 diffLabels,
24 hasAlchemyLabels,
25 stripInternalLabels,
26 toLabels,
27 } from "./Labels.ts";
28 import type { Providers } from "./Providers.ts";
29
30 const DEFAULT_LOCATION = "nbg1";
31 const MAX_NAME_LENGTH = 63;
32
33 /**
34 * A resource-valued prop: the resource itself, or an Effect that produces
35 * it (so `yield* SshKey(...)` and `SshKey(...)` both type-check).
36 */
37 type Ref<T> = T | Effect.Effect<T, never, Providers>;
38
39 /**
40 * SSH key identity injected at create time. Accepts a `Hetzner.SshKey`
41 * resource or a `{ id }` stub.
42 */
43 export type ServerSshKey = { readonly id: number };
44
45 /**
46 * Private Network identity. Accepts a `Hetzner.Network` resource or a
47 * `{ networkId }` stub.
48 */
49 export type ServerNetwork = { readonly networkId: number };
50
51 /**
52 * Firewall identity applied to the public NIC. Accepts a
53 * `Hetzner.Firewall` resource or a `{ id }` stub.
54 */
55 export type ServerFirewall = { readonly id: number };
56
57 /**
58 * Volume identity attached at create/sync time. Accepts a
59 * `Hetzner.Volume` resource or a `{ id }` stub.
60 */
61 export type ServerVolume = { readonly id: number };
62
63 /**
64 * Placement Group identity. Accepts a `Hetzner.PlacementGroup` resource
65 * or a `{ id }` stub.
66 */
67 export type ServerPlacementGroup = { readonly id: number };
68
69 export type ServerStatus =
70 | "running"
71 | "initializing"
72 | "starting"
73 | "stopping"
74 | "off"
75 | "deleting"
76 | "migrating"
77 | "rebuilding"
78 | "unknown";
79
80 export interface ServerProps {
81 /**
82 * Server name. Must be unique per project and a valid RFC 1123
83 * hostname (letters, digits, periods, dashes). If omitted, a unique
84 * name is generated from the stack, stage and logical ID.
85 */
86 name?: string;
87 /**
88 * Server type name (`cpx12`, `cx23`, …) or numeric id. Cannot be
89 * changed after creation — changing it replaces the Server.
90 */
91 serverType: string;
92 /**
93 * Image name (`ubuntu-24.04`, …) or numeric id the Server is created
94 * from. Cannot be changed after creation — changing it replaces the
95 * Server.
96 */
97 image: string;
98 /**
99 * Location name (`nbg1`, `fsn1`, `hel1`, …) or numeric id. Cannot be
100 * changed after creation — changing it replaces the Server.
101 *
102 * @default "nbg1"
103 */
104 location?: string;
105 /**
106 * SSH keys injected at create time. Accepts `Hetzner.SshKey` resources
107 * or `{ id }` stubs. Hetzner cannot change injected keys after
108 * create — this list is applied only when the Server is provisioned.
109 */
110 sshKeys?: Array<Ref<ServerSshKey>>;
111 /**
112 * Private Networks to attach. Accepts `Hetzner.Network` resources or
113 * `{ networkId }` stubs. Synced on update when set.
114 */
115 networks?: Array<Ref<ServerNetwork>>;
116 /**
117 * Firewalls applied to the public NIC. Accepts `Hetzner.Firewall`
118 * resources or `{ id }` stubs. Synced on update when set.
119 */
120 firewalls?: Array<Ref<ServerFirewall>>;
121 /**
122 * Volumes to attach. Accepts `Hetzner.Volume` resources or `{ id }`
123 * stubs. Synced on update when set. Omit to leave Volume-side attach
124 * alone.
125 */
126 volumes?: Array<Ref<ServerVolume>>;
127 /**
128 * Placement Group to assign. Accepts a `Hetzner.PlacementGroup` or
129 * `{ id }`. Synced on update when set.
130 */
131 placementGroup?: Ref<ServerPlacementGroup>;
132 /**
133 * Cloud-init user data run on the Server's **first boot** — the place to
134 * install packages, write config files, or add users.
135 *
136 * Accepts a shell script (`#!/bin/bash …`), a `#cloud-config` document,
137 * or a bare shell snippet (a `#!/bin/bash` shebang is added for you).
138 * Alchemy combines it with its own bootstrap script (which preinstalls
139 * Node 26 for `Hetzner.Service`) into a multipart cloud-init document, so
140 * both run — the bootstrap first. A document that already starts with a
141 * `Content-Type:` / `MIME-Version:` header is passed through untouched,
142 * taking over the whole payload including the bootstrap.
143 *
144 * Capped at 32 KiB (Hetzner's limit) after composition.
145 *
146 * Cloud-init only runs once, on first boot, so changing this replaces
147 * the Server.
148 */
149 userData?: string;
150 /**
151 * Attach a public IPv4. Applied only at create time.
152 *
153 * @default true
154 */
155 enableIpv4?: boolean;
156 /**
157 * Attach a public IPv6. Applied only at create time.
158 *
159 * @default true
160 */
161 enableIpv6?: boolean;
162 /**
163 * Power the Server on after create.
164 *
165 * @default true
166 */
167 startAfterCreate?: boolean;
168 /**
169 * Prevent the Server from being deleted or rebuilt via the API until
170 * this is cleared. The provider disables protection before delete.
171 *
172 * @default false
173 */
174 deleteProtection?: boolean;
175 /**
176 * User-defined labels. Alchemy ownership labels (`alchemy.stack` /
177 * `alchemy.stage` / `alchemy.id`) are always merged in.
178 */
179 labels?: Record<string, string>;
180 }
181
182 export type Server = Resource<
183 "Hetzner.Server",
184 ServerProps,
185 {
186 /** Numeric Hetzner Server ID. */
187 id: number;
188 /**
189 * Same as {@link id}. Present so Volume / Firewall `server` /
190 * `applyTo` props accept this resource directly.
191 */
192 serverId: number;
193 /** Server name (unique per project). */
194 name: string;
195 /** Server status. */
196 status: ServerStatus;
197 /** Server type name (`cx22`, …). */
198 serverType: string;
199 /** Numeric Server type id. */
200 serverTypeId: number;
201 /** Image name, or `undefined` for snapshot/backup images without a name. */
202 image: string | undefined;
203 /** Numeric Image id, or `undefined` if no image is attached. */
204 imageId: number | undefined;
205 /** Location name (`nbg1`, `fsn1`, …). */
206 location: string;
207 /** Numeric location ID. */
208 locationId: number;
209 /** Public IPv4 address, or `undefined` if IPv4 is disabled. */
210 ipv4: string | undefined;
211 /** Public IPv6 network (`…/64`), or `undefined` if IPv6 is disabled. */
212 ipv6: string | undefined;
213 /** Attached Volume IDs. */
214 volumeIds: number[];
215 /** Attached private Network IDs. */
216 networkIds: number[];
217 /** Firewall IDs applied to the public NIC. */
218 firewallIds: number[];
219 /** Placement Group ID, or `undefined` if unassigned. */
220 placementGroupId: number | undefined;
221 /** Whether delete/rebuild protection is enabled. */
222 deleteProtection: boolean;
223 /** RFC3339 creation timestamp. */
224 created: string;
225 /** User-defined labels (Alchemy ownership labels stripped). */
226 labels: Record<string, string>;
227 /**
228 * Alchemy-managed deploy SSH private key (PKCS8 PEM). Injected at
229 * create via a companion SSH key so `Hetzner.Ssh` / `Hetzner.Service`
230 * can reach the box. Persisted in state; not present on adopted
231 * foreign servers.
232 */
233 privateKey?: Redacted.Redacted<string>;
234 /** Numeric id of the Alchemy-managed deploy SSH key. */
235 deploySshKeyId?: number;
236 },
237 {
238 /** Environment variables collected from bindings. */
239 env?: Record<string, any>;
240 /**
241 * Volumes to attach and mount. Collected from `Hetzner.MountVolume`
242 * when the Server is the bind host.
243 */
244 volumes?: Array<{ volumeId: number; path: string }>;
245 },
246 Providers
247 >;
248
249 /**
250 * A Hetzner Cloud Server — a virtual machine in a Location, created from
251 * a Server type and an Image. `serverType`, `image`, and `location` are
252 * immutable (changing any of them replaces the Server). Name, labels,
253 * delete protection, and (when set) Networks / Firewalls / Volumes /
254 * Placement Group update in place. SSH keys are injected only at create.
255 *
256 * @see https://docs.hetzner.cloud/reference/cloud#servers
257 *
258 * ### Creating a Server
259 * **Example:** Basic Server
260 * ```typescript
261 * const server = yield* Hetzner.Server("web", {
262 * serverType: "cpx12",
263 * image: "ubuntu-24.04",
264 * location: "nbg1",
265 * });
266 * ```
267 *
268 * **Example:** Named Server with labels
269 * ```typescript
270 * const server = yield* Hetzner.Server("web", {
271 * name: "app-web",
272 * serverType: "cpx12",
273 * image: "ubuntu-24.04",
274 * location: "nbg1",
275 * labels: { role: "web" },
276 * });
277 * ```
278 *
279 * ### Attachments
280 * **Example:** SSH key and Placement Group
281 * ```typescript
282 * const key = yield* Hetzner.SshKey("deploy", {
283 * publicKey: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI… user@host",
284 * });
285 * const group = yield* Hetzner.PlacementGroup("web");
286 * const server = yield* Hetzner.Server("web", {
287 * serverType: "cpx12",
288 * image: "ubuntu-24.04",
289 * location: "nbg1",
290 * sshKeys: [key],
291 * placementGroup: group,
292 * });
293 * ```
294 *
295 * ### Custom init script
296 * **Example:** Install packages on first boot
297 * ```typescript
298 * const server = yield* Hetzner.Server("web", {
299 * serverType: "cpx12",
300 * image: "ubuntu-24.04",
301 * userData: `#!/bin/bash
302 * apt-get update
303 * DEBIAN_FRONTEND=noninteractive apt-get install -y nginx
304 * systemctl enable --now nginx`,
305 * });
306 * ```
307 *
308 * **Example:** cloud-config document
309 * ```typescript
310 * const server = yield* Hetzner.Server("web", {
311 * serverType: "cpx12",
312 * image: "ubuntu-24.04",
313 * userData: `#cloud-config
314 * packages:
315 * - nginx
316 * - postgresql-client`,
317 * });
318 * ```
319 *
320 * `userData` is merged with Alchemy's own bootstrap script into a
321 * multipart cloud-init document, so both run. It is applied on first boot
322 * only — changing it replaces the Server.
323 *
324 * @resource
325 * @product Server
326 */
327 export const Server = Resource<Server>("Hetzner.Server");
328
329 export class ServerNotResolved extends Data.TaggedError("Hetzner.ServerNotResolved")<{
330 resourceName: string;
331 }> {}
332
333 /**
334 * The composed cloud-init document (Alchemy's bootstrap plus the Server's
335 * `userData`) exceeds Hetzner's 32 KiB user-data limit.
336 */
337 export class ServerUserDataTooLarge extends Data.TaggedError("Hetzner.ServerUserDataTooLarge")<{
338 resourceName: string;
339 bytes: number;
340 limit: number;
341 }> {}
342
343 type CloudServer = GetServerResponseServer | ListServersResponseServersItem;
344
345 class ServerPending extends Data.TaggedError("ServerPending")<{
346 serverId: number;
347 status: string;
348 }> {}
349
350 class ServerTimeout extends Data.TaggedError("ServerTimeout")<{
351 serverId: number;
352 status: string;
353 }> {}
354
355 const asStatus = (status: string): ServerStatus => {
356 switch (status) {
357 case "running":
358 case "initializing":
359 case "starting":
360 case "stopping":
361 case "off":
362 case "deleting":
363 case "migrating":
364 case "rebuilding":
365 case "unknown":
366 return status;
367 default:
368 return "unknown";
369 }
370 };
371
372 const userLabels = (
373 labels: Record<string, string | undefined> | null | undefined,
374 ): Record<string, string> => stripInternalLabels(tagRecord(labels));
375
376 const toAttrs = (server: CloudServer): Server["Attributes"] => ({
377 id: server.id,
378 serverId: server.id,
379 name: server.name,
380 status: asStatus(server.status),
381 serverType: server.server_type.name,
382 serverTypeId: server.server_type.id,
383 image: server.image?.name ?? undefined,
384 imageId: server.image?.id,
385 location: server.location.name,
386 locationId: server.location.id,
387 ipv4: server.public_net.ipv4?.ip,
388 ipv6: server.public_net.ipv6?.ip,
389 volumeIds: [...(server.volumes ?? [])],
390 networkIds: server.private_net
391 .map((item) => item.network)
392 .filter((id): id is number => typeof id === "number"),
393 firewallIds: (server.public_net.firewalls ?? [])
394 .map((item) => item.id)
395 .filter((id): id is number => typeof id === "number"),
396 placementGroupId: server.placement_group?.id,
397 deleteProtection: server.protection.delete,
398 created: server.created,
399 labels: userLabels(server.labels),
400 });
401
402 const retryable = (e: { readonly _tag: string }): boolean =>
403 e._tag === "ServerPending" ||
404 e._tag === "TooManyRequests" ||
405 e._tag === "ServiceUnavailable" ||
406 e._tag === "InternalServerError" ||
407 e._tag === "BadGateway" ||
408 e._tag === "GatewayTimeout" ||
409 e._tag === "Locked";
410
411 const backoff = Schedule.min([
412 Schedule.exponential(Duration.millis(500), 1.5),
413 Schedule.spaced(Duration.seconds(5)),
414 ]);
415
416 /** Companion deploy keys are not stack resources — delete must be idempotent. */
417 const deleteDeployKey = (id: number | undefined) =>
418 id === undefined
419 ? Effect.void
420 : Hetzner.sshKeys.deleteSshKey({ id }).pipe(
421 Effect.retry({
422 while: (e) => retryable(e) || e._tag === "UnprocessableEntity" || e._tag === "Conflict",
423 times: 8,
424 schedule: backoff,
425 }),
426 Effect.catchTag("NotFound", () => Effect.void),
427 );
428
429 const createServerName = (id: string, name: string | undefined, existing?: string) =>
430 Effect.gen(function* () {
431 return (
432 name ??
433 existing ??
434 (yield* createPhysicalName({ id, maxLength: MAX_NAME_LENGTH, lowercase: true }))
435 );
436 });
437
438 /**
439 * Preinstall Node 26 so `Hetzner.Service`'s first deploy does not have to.
440 * Mirrors the SSH-side install in `./hosted.ts`. Never fails the boot:
441 * `hosted.ts` installs Node over SSH if this did not manage to.
442 */
443 const ALCHEMY_BOOTSTRAP = `#!/bin/bash
444 set -uo pipefail
445 export HOME=/root
446 if ! command -v curl >/dev/null 2>&1 || ! command -v unzip >/dev/null 2>&1; then
447 apt-get update || true
448 DEBIAN_FRONTEND=noninteractive apt-get install -y curl unzip ca-certificates || true
449 fi
450 if ! command -v node >/dev/null 2>&1; then
451 for attempt in 1 2 3; do
452 curl -fsSL https://deb.nodesource.com/setup_26.x | bash - && DEBIAN_FRONTEND=noninteractive apt-get install -y nodejs && break
453 sleep 5
454 done
455 fi
456 exit 0
457 `;
458
459 /** Hetzner rejects user data larger than 32 KiB. */
460 const MAX_USER_DATA_BYTES = 32 * 1024;
461
462 const MIME_BOUNDARY = "==ALCHEMY==";
463
464 /**
465 * Cloud-init dispatches on a document's first line. Anything unrecognized
466 * is treated as a shell script.
467 */
468 const CLOUD_INIT_FORMATS: ReadonlyArray<readonly [string, string]> = [
469 ["#cloud-config", "text/cloud-config"],
470 ["#cloud-boothook", "text/cloud-boothook"],
471 ["#include", "text/x-include-url"],
472 ["#upstart-job", "text/upstart-job"],
473 ["#part-handler", "text/part-handler"],
474 ["#!", "text/x-shellscript"],
475 ];
476
477 type UserDataPart = { readonly contentType: string; readonly body: string };
478
479 const classifyUserData = (doc: string): UserDataPart => {
480 const first = doc.split("\n", 1)[0]?.trim() ?? "";
481 for (const [prefix, contentType] of CLOUD_INIT_FORMATS) {
482 if (first.startsWith(prefix)) return { contentType, body: doc };
483 }
484 // A bare snippet (`apt-get install -y nginx`) is the common case —
485 // cloud-init needs a shebang before it will execute one.
486 return { contentType: "text/x-shellscript", body: `#!/bin/bash\n${doc}` };
487 };
488
489 /**
490 * Wrap the parts in a multipart cloud-init document. Parts are named
491 * `part-001`, `part-002`, … the way cloud-init names anonymous parts
492 * itself — scripts run in that (lexical) order, so the bootstrap goes
493 * first.
494 */
495 const mimeMultipart = (parts: ReadonlyArray<UserDataPart>) =>
496 [
497 `Content-Type: multipart/mixed; boundary="${MIME_BOUNDARY}"`,
498 "MIME-Version: 1.0",
499 "",
500 ...parts.flatMap((part, index) => [
501 `--${MIME_BOUNDARY}`,
502 `Content-Type: ${part.contentType}; charset="utf-8"`,
503 "MIME-Version: 1.0",
504 `Content-Disposition: attachment; filename="part-${String(index + 1).padStart(3, "0")}"`,
505 "",
506 part.body.replace(/\n+$/, ""),
507 ]),
508 `--${MIME_BOUNDARY}--`,
509 "",
510 ].join("\n");
511
512 /**
513 * Compose the cloud-init document sent at create: Alchemy's bootstrap
514 * script plus the caller's `userData`, if any.
515 */
516 export const composeUserData = (userData: string | undefined): string => {
517 if (userData === undefined) return ALCHEMY_BOOTSTRAP;
518 const doc = userData.replace(/^\uFEFF/, "").replace(/^[\s\n]+/, "");
519 if (doc === "") return ALCHEMY_BOOTSTRAP;
520 // An explicit MIME document is passed through verbatim — the caller owns
521 // the whole payload, bootstrap included.
522 if (/^(content-type|mime-version):/i.test(doc)) return userData;
523 return mimeMultipart([
524 { contentType: "text/x-shellscript", body: ALCHEMY_BOOTSTRAP },
525 classifyUserData(doc),
526 ]);
527 };
528
529 const buildUserData = Effect.fn(function* (input: { name: string; userData: string | undefined }) {
530 const doc = yield* Effect.sync(() => composeUserData(input.userData));
531 const bytes = yield* Effect.sync(() => Buffer.byteLength(doc, "utf8"));
532 if (bytes > MAX_USER_DATA_BYTES) {
533 return yield* new ServerUserDataTooLarge({
534 resourceName: input.name,
535 bytes,
536 limit: MAX_USER_DATA_BYTES,
537 });
538 }
539 return doc;
540 });
541
542 const u32be = (n: number) => {
543 const buf = Buffer.alloc(4);
544 buf.writeUInt32BE(n);
545 return buf;
546 };
547
548 const sshString = (data: Buffer | string) => {
549 const buf = typeof data === "string" ? Buffer.from(data) : data;
550 return Buffer.concat([u32be(buf.length), buf]);
551 };
552
553 /**
554 * Encode an ed25519 keypair as OpenSSH public + private key files.
555 * `ssh -i` on macOS rejects PKCS8 ed25519 PEMs with exit 255.
556 */
557 const encodeOpenSshEd25519 = (publicRaw: Buffer, seed: Buffer, comment: string) => {
558 const algo = Buffer.from("ssh-ed25519");
559 const pubBlob = Buffer.concat([sshString(algo), sshString(publicRaw)]);
560 const publicKey = `ssh-ed25519 ${pubBlob.toString("base64")} ${comment}`;
561
562 const check = Buffer.alloc(4);
563 check.writeUInt32BE(0xa1b2c3d4);
564 const secret = Buffer.concat([seed, publicRaw]);
565 let inner = Buffer.concat([
566 check,
567 check,
568 sshString(algo),
569 sshString(publicRaw),
570 sshString(secret),
571 sshString(comment),
572 ]);
573 const padLen = (8 - (inner.length % 8)) % 8;
574 const pad = Buffer.alloc(padLen);
575 for (let i = 0; i < padLen; i++) pad[i] = i + 1;
576 inner = Buffer.concat([inner, pad]);
577
578 const body = Buffer.concat([
579 Buffer.from("openssh-key-v1\0"),
580 sshString("none"),
581 sshString("none"),
582 sshString(""),
583 u32be(1),
584 sshString(pubBlob),
585 sshString(inner),
586 ]);
587 const b64 = body.toString("base64");
588 const wrapped = b64.match(/.{1,70}/g)?.join("\n") ?? b64;
589 const privateKey = `-----BEGIN OPENSSH PRIVATE KEY-----\n${wrapped}\n-----END OPENSSH PRIVATE KEY-----\n`;
590 return { publicKey, privateKey };
591 };
592
593 const generateDeployKey = Effect.sync(() => {
594 const { publicKey, privateKey } = generateKeyPairSync("ed25519");
595 const spki = publicKey.export({ type: "spki", format: "der" });
596 const pkcs8 = privateKey.export({ type: "pkcs8", format: "der" });
597 const publicRaw = spki.subarray(spki.length - 32);
598 const seed = pkcs8.subarray(pkcs8.length - 32);
599 return encodeOpenSshEd25519(publicRaw, seed, "alchemy-deploy");
600 });
601
602 const unwrapPrivateKey = (
603 value: Redacted.Redacted<string> | string | undefined,
604 ): string | undefined => {
605 if (value === undefined) return undefined;
606 return typeof value === "string" ? value : Redacted.value(value);
607 };
608
609 const deployKeyName = (name: string) => `${name.slice(0, 55)}-d`;
610
611 const findDeployKeyId = Effect.fn(function* (id: string, name: string) {
612 const keyName = deployKeyName(name);
613 const { ssh_keys } = yield* Hetzner.sshKeys.listSshKeys({ name: keyName, per_page: 50 });
614 const key = ssh_keys.find((item) => item.name === keyName);
615 return key !== undefined && (yield* hasAlchemyLabels(id, tagRecord(key.labels)))
616 ? key.id
617 : undefined;
618 });
619
620 const ensureDeployKey = Effect.fn(function* (input: {
621 name: string;
622 labels: Record<string, string>;
623 output?: Pick<Server["Attributes"], "privateKey" | "deploySshKeyId">;
624 creating: boolean;
625 }) {
626 const existingKey = unwrapPrivateKey(input.output?.privateKey);
627 const existingId = input.output?.deploySshKeyId;
628 if (existingKey !== undefined && existingId !== undefined) {
629 return { privateKey: Redacted.make(existingKey), deploySshKeyId: existingId };
630 }
631 if (!input.creating) {
632 return { privateKey: input.output?.privateKey, deploySshKeyId: existingId };
633 }
634 const generated = yield* generateDeployKey;
635 const keyName = deployKeyName(input.name);
636 const created = yield* Hetzner.sshKeys
637 .createSshKey({ name: keyName, public_key: generated.publicKey, labels: input.labels })
638 .pipe(
639 Effect.catchTag("Conflict", () =>
640 Hetzner.sshKeys.listSshKeys({ name: keyName, per_page: 50 }).pipe(
641 Effect.map(({ ssh_keys }) => ssh_keys.find((item) => item.name === keyName)),
642 Effect.flatMap((hit) =>
643 hit !== undefined
644 ? Effect.succeed({ ssh_key: hit })
645 : Hetzner.sshKeys.createSshKey({
646 name: keyName,
647 public_key: generated.publicKey,
648 labels: input.labels,
649 }),
650 ),
651 ),
652 ),
653 );
654 return { privateKey: Redacted.make(generated.privateKey), deploySshKeyId: created.ssh_key.id };
655 });
656
657 const getById = (id: number) =>
658 Hetzner.servers.getServer({ id }).pipe(
659 Effect.map(({ server }) => server),
660 Effect.catchTag("NotFound", () => Effect.undefined),
661 );
662
663 const getByName = (name: string) =>
664 Hetzner.servers
665 .listServers({ name, per_page: 50 })
666 .pipe(Effect.map(({ servers }) => servers.find((item) => item.name === name)));
667
668 const observe = Effect.fn(function* ({
669 name,
670 outputId,
671 }: {
672 id: string;
673 name?: string;
674 outputId?: number;
675 }) {
676 if (outputId !== undefined) {
677 const byId = yield* getById(outputId);
678 if (byId !== undefined) return byId;
679 }
680 if (name !== undefined) {
681 return yield* getByName(name);
682 }
683 return undefined;
684 });
685
686 const READY = new Set<string>(["running", "off"]);
687
688 const waitUntilReady = (serverId: number) =>
689 Hetzner.servers.getServer({ id: serverId }).pipe(
690 Effect.flatMap(({ server }) =>
691 server !== undefined && READY.has(server.status)
692 ? Effect.succeed(server)
693 : Effect.fail(new ServerPending({ serverId, status: server?.status ?? "missing" })),
694 ),
695 Effect.retry({ while: retryable, times: 10, schedule: backoff }),
696 Effect.catchTag(
697 "ServerPending",
698 (e) => new ServerTimeout({ serverId: e.serverId, status: e.status }),
699 ),
700 );
701
702 const waitUntilGone = (serverId: number) =>
703 Hetzner.servers.getServer({ id: serverId }).pipe(
704 Effect.map(() => false),
705 Effect.catchTag("NotFound", () => Effect.succeed(true)),
706 Effect.repeat({
707 schedule: Schedule.spaced(Duration.seconds(1)),
708 until: (gone) => gone,
709 times: 10,
710 }),
711 Effect.flatMap((gone) =>
712 gone ? Effect.void : Effect.fail(new ServerTimeout({ serverId, status: "deleting" })),
713 ),
714 );
715
716 const numericId = (value: unknown, keys: readonly string[]): number | undefined => {
717 if (value === null || typeof value !== "object") return undefined;
718 const rec = value as Record<string, unknown>;
719 for (const key of keys) {
720 if (typeof rec[key] === "number") return rec[key];
721 }
722 return undefined;
723 };
724
725 const idsOf = (items: ReadonlyArray<unknown> | undefined, keys: readonly string[]): number[] => {
726 const ids = new Set<number>();
727 for (const item of items ?? []) {
728 const id = numericId(item, keys);
729 if (id !== undefined) ids.add(id);
730 }
731 return [...ids];
732 };
733
734 const sameRef = (desired: string, name: string, id: number): boolean =>
735 desired === name || desired === String(id);
736
737 const setEquals = (a: ReadonlyArray<number>, b: ReadonlyArray<number>) => {
738 if (a.length !== b.length) return false;
739 const left = new Set(a);
740 return b.every((id) => left.has(id));
741 };
742
743 const refresh = (id: number) =>
744 getById(id).pipe(
745 Effect.flatMap((server) =>
746 server !== undefined ? Effect.succeed(server) : waitUntilReady(id),
747 ),
748 );
749
750 const syncNetworks = Effect.fn(function* (input: {
751 serverId: number;
752 observed: ReadonlyArray<number>;
753 desired: ReadonlyArray<number>;
754 }) {
755 const observed = new Set(input.observed);
756 const desired = new Set(input.desired);
757 for (const networkId of input.observed) {
758 if (desired.has(networkId)) continue;
759 const { action } = yield* Hetzner.serverActions.detachServerFromNetwork({
760 id: input.serverId,
761 network: networkId,
762 });
763 yield* waitForAction(action);
764 }
765 for (const networkId of input.desired) {
766 if (observed.has(networkId)) continue;
767 const { action } = yield* Hetzner.serverActions.attachServerToNetwork({
768 id: input.serverId,
769 network: networkId,
770 });
771 yield* waitForAction(action);
772 }
773 });
774
775 const syncVolumes = Effect.fn(function* (input: {
776 serverId: number;
777 observed: ReadonlyArray<number>;
778 desired: ReadonlyArray<number>;
779 }) {
780 const observed = new Set(input.observed);
781 const desired = new Set(input.desired);
782 for (const volumeId of input.observed) {
783 if (desired.has(volumeId)) continue;
784 const { action } = yield* Hetzner.volumeActions.detachVolume({ id: volumeId });
785 yield* waitForAction(action);
786 }
787 for (const volumeId of input.desired) {
788 if (observed.has(volumeId)) continue;
789 const { action } = yield* Hetzner.volumeActions.attachVolume({
790 id: volumeId,
791 server: input.serverId,
792 });
793 yield* waitForAction(action);
794 }
795 });
796
797 const firewallApplyItems = (serverId: number) => [
798 { type: "server" as const, server: { id: serverId } },
799 ];
800
801 const syncFirewalls = Effect.fn(function* (input: {
802 serverId: number;
803 observed: ReadonlyArray<number>;
804 desired: ReadonlyArray<number>;
805 }) {
806 const observed = new Set(input.observed);
807 const desired = new Set(input.desired);
808 for (const firewallId of input.observed) {
809 if (desired.has(firewallId)) continue;
810 const { actions } = yield* Hetzner.firewallActions.removeFirewallFromResources({
811 id: firewallId,
812 remove_from: firewallApplyItems(input.serverId),
813 });
814 yield* waitForActions(actions);
815 }
816 for (const firewallId of input.desired) {
817 if (observed.has(firewallId)) continue;
818 const { actions } = yield* Hetzner.firewallActions.applyFirewallToResources({
819 id: firewallId,
820 apply_to: firewallApplyItems(input.serverId),
821 });
822 yield* waitForActions(actions);
823 }
824 });
825
826 const syncPlacementGroup = Effect.fn(function* (input: {
827 serverId: number;
828 observed: number | undefined;
829 desired: number | undefined;
830 }) {
831 if (input.desired === input.observed) return;
832 if (input.observed !== undefined) {
833 const { action } = yield* Hetzner.serverActions.removeServerFromPlacementGroup({
834 id: input.serverId,
835 });
836 yield* waitForAction(action);
837 }
838 if (input.desired !== undefined) {
839 const { action } = yield* Hetzner.serverActions.addServerToPlacementGroup({
840 id: input.serverId,
841 placement_group: input.desired,
842 });
843 yield* waitForAction(action);
844 }
845 });
846
847 export const ServerProvider = () =>
848 Provider.succeed(Server, {
849 stables: [
850 "id",
851 "serverId",
852 "created",
853 "location",
854 "locationId",
855 "ipv4",
856 "ipv6",
857 "privateKey",
858 "deploySshKeyId",
859 ],
860 list: Effect.fn(function* () {
861 const items = yield* Hetzner.servers.listServers
862 .items({ label_selector: alchemyStackSelector, per_page: 50 })
863 .pipe(
864 Stream.runCollect,
865 Effect.map((chunk) => Array.from(chunk)),
866 );
867 return items.map(toAttrs);
868 }),
869 diff: Effect.fn(function* ({ news, olds, output }) {
870 if (!isResolved(news)) return undefined;
871 if (output !== undefined) {
872 // Cloud-init runs once, on first boot — a changed init script can
873 // only take effect on a freshly provisioned Server.
874 if (news.userData !== olds?.userData) {
875 return { action: "replace" } as const;
876 }
877 const location = news.location ?? DEFAULT_LOCATION;
878 if (!sameRef(location, output.location, output.locationId)) {
879 return { action: "replace" } as const;
880 }
881 if (!sameRef(news.serverType, output.serverType, output.serverTypeId)) {
882 return { action: "replace" } as const;
883 }
884 const imageId = output.imageId;
885 const imageMatches =
886 output.image !== undefined && news.image === output.image
887 ? true
888 : imageId !== undefined && news.image === String(imageId);
889 if (!imageMatches) {
890 return { action: "replace" } as const;
891 }
892 }
893 return undefined;
894 }),
895 read: Effect.fn(function* ({ id, olds, output }) {
896 const name = yield* createServerName(id, olds?.name, output?.name);
897 const found = yield* observe({ id, name, outputId: output?.id ?? output?.serverId });
898 if (found === undefined) return undefined;
899 const attrs = {
900 ...toAttrs(found),
901 privateKey: output?.privateKey,
902 deploySshKeyId: output?.deploySshKeyId,
903 };
904 if (!(yield* hasAlchemyLabels(id, tagRecord(found.labels)))) {
905 return Unowned(attrs);
906 }
907 return {
908 ...attrs,
909 deploySshKeyId: attrs.deploySshKeyId ?? (yield* findDeployKeyId(id, found.name)),
910 };
911 }),
912 reconcile: Effect.fn(function* ({ id, news, output }) {
913 const name = yield* createServerName(id, news.name, output?.name);
914 const internalLabels = yield* createInternalLabels(id);
915 const desiredLabels = { ...toLabels(news.labels), ...internalLabels };
916 const location = news.location ?? DEFAULT_LOCATION;
917 const userSshKeyIds = idsOf(news.sshKeys, ["id"]);
918 const networkIds = idsOf(news.networks, ["networkId", "id"]);
919 const firewallIds = idsOf(news.firewalls, ["id"]);
920 const volumeIds = idsOf(news.volumes, ["id"]);
921 const placementGroupId = numericId(news.placementGroup, ["id"]);
922 const startAfterCreate = news.startAfterCreate ?? true;
923 const desiredProtection = news.deleteProtection ?? false;
924 const userData = yield* buildUserData({ name, userData: news.userData });
925
926 // Observe by id then desired name only. Do not fall back to
927 // ownership labels — a create-first replacement still has the old
928 // generation live under the same logical id.
929 let current = output?.id !== undefined ? yield* getById(output.id) : undefined;
930 if (current === undefined) {
931 current = yield* getByName(name);
932 }
933
934 const deployKey = yield* ensureDeployKey({
935 name,
936 labels: desiredLabels,
937 output,
938 creating: current === undefined,
939 });
940 const sshKeyIds = [
941 ...userSshKeyIds,
942 ...(deployKey.deploySshKeyId !== undefined ? [deployKey.deploySshKeyId] : []),
943 ];
944
945 // Ensure — create only when missing. A Conflict is a race with a
946 // peer reconciler or a name that just became visible; re-observe.
947 if (current === undefined) {
948 const created = yield* Hetzner.servers
949 .createServer({
950 name,
951 server_type: news.serverType,
952 image: news.image,
953 location,
954 labels: desiredLabels,
955 start_after_create: startAfterCreate,
956 ssh_keys: sshKeyIds.length > 0 ? sshKeyIds : undefined,
957 networks: networkIds.length > 0 ? networkIds : undefined,
958 firewalls:
959 firewallIds.length > 0 ? firewallIds.map((firewall) => ({ firewall })) : undefined,
960 volumes: volumeIds.length > 0 ? volumeIds : undefined,
961 placement_group: placementGroupId,
962 user_data: userData,
963 public_net:
964 news.enableIpv4 !== undefined || news.enableIpv6 !== undefined
965 ? { enable_ipv4: news.enableIpv4 ?? true, enable_ipv6: news.enableIpv6 ?? true }
966 : undefined,
967 })
968 .pipe(
969 Effect.retry({
970 while: (e) => e._tag === "ServerLimitExceeded" || e._tag === "ServerPlacementError",
971 schedule: Schedule.spaced("5 seconds"),
972 times: 8,
973 }),
974 Effect.catchTag("Conflict", () => Effect.undefined),
975 // The deploy key is a side-effect, not a stack resource. If
976 // createServer fails after minting it (quota skip, timeout),
977 // nothing is persisted for Server.delete to clean up.
978 Effect.tapError(() => deleteDeployKey(deployKey.deploySshKeyId).pipe(Effect.ignore)),
979 );
980 if (created !== undefined) {
981 if (created.action) {
982 yield* waitForActions([created.action, ...created.next_actions]);
983 }
984 current = yield* waitUntilReady(created.server.id);
985 } else {
986 const hit = yield* getByName(name);
987 if (hit === undefined) {
988 return yield* new ServerNotResolved({ resourceName: name });
989 }
990 current = yield* waitUntilReady(hit.id);
991 }
992 }
993
994 // Sync name + labels against observed cloud labels, not olds.
995 // updateServer overwrites the full label set.
996 const observedLabels = tagRecord(current.labels);
997 const { upsert, removed } = diffLabels(observedLabels, desiredLabels);
998 const needsMeta = current.name !== name || upsert.length > 0 || removed.length > 0;
999 if (needsMeta) {
1000 yield* Hetzner.servers.updateServer({ id: current.id, name, labels: desiredLabels });
1001 current = yield* refresh(current.id);
1002 }
1003
1004 if (current.protection.delete !== desiredProtection) {
1005 const { action } = yield* Hetzner.serverActions.changeServerProtection({
1006 id: current.id,
1007 delete: desiredProtection,
1008 rebuild: desiredProtection,
1009 });
1010 yield* waitForAction(action);
1011 current = yield* refresh(current.id);
1012 }
1013
1014 // Attachment props are opt-in: omit them to leave Volume / Firewall
1015 // / Network / PlacementGroup as the owner of the relationship.
1016 if (news.networks !== undefined) {
1017 const observed = current.private_net
1018 .map((item) => item.network)
1019 .filter((netId): netId is number => typeof netId === "number");
1020 if (!setEquals(observed, networkIds)) {
1021 yield* syncNetworks({ serverId: current.id, observed, desired: networkIds });
1022 current = yield* refresh(current.id);
1023 }
1024 }
1025
1026 if (news.volumes !== undefined) {
1027 const observed = current.volumes ?? [];
1028 if (!setEquals(observed, volumeIds)) {
1029 yield* syncVolumes({ serverId: current.id, observed, desired: volumeIds });
1030 current = yield* refresh(current.id);
1031 }
1032 }
1033
1034 if (news.firewalls !== undefined) {
1035 const observed = (current.public_net.firewalls ?? [])
1036 .map((item) => item.id)
1037 .filter((fwId): fwId is number => typeof fwId === "number");
1038 if (!setEquals(observed, firewallIds)) {
1039 yield* syncFirewalls({ serverId: current.id, observed, desired: firewallIds });
1040 current = yield* refresh(current.id);
1041 }
1042 }
1043
1044 if (news.placementGroup !== undefined) {
1045 const observed = current.placement_group?.id;
1046 if (observed !== placementGroupId) {
1047 yield* syncPlacementGroup({ serverId: current.id, observed, desired: placementGroupId });
1048 current = yield* refresh(current.id);
1049 }
1050 }
1051
1052 return {
1053 ...toAttrs(current),
1054 privateKey: deployKey.privateKey,
1055 deploySshKeyId: deployKey.deploySshKeyId,
1056 };
1057 }),
1058 delete: Effect.fn(function* ({ output }) {
1059 // Keep the server discoverable if key deletion fails. Removing the project
1060 // key does not revoke the public key already injected into the server.
1061 yield* deleteDeployKey(output.deploySshKeyId);
1062 const current = yield* getById(output.id);
1063 if (current !== undefined) {
1064 if (current.protection.delete) {
1065 const { action } = yield* Hetzner.serverActions.changeServerProtection({
1066 id: current.id,
1067 delete: false,
1068 rebuild: false,
1069 });
1070 yield* waitForAction(action);
1071 }
1072
1073 const deleted = yield* Hetzner.servers.deleteServer({ id: current.id }).pipe(
1074 Effect.catchTag("NotFound", () => Effect.undefined),
1075 Effect.retry({ while: retryable, times: 8, schedule: backoff }),
1076 );
1077 if (deleted?.action) {
1078 yield* waitForAction(deleted.action);
1079 }
1080 yield* waitUntilGone(current.id);
1081 }
1082 }),
1083 });