The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import * as Hetzner from "@distilled.cloud/hetzner"; |
| 2 | import type { GetVolumeResponseVolume } from "@distilled.cloud/hetzner/volumes"; |
| 3 | import { isResolved } from "alchemy/Diff"; |
| 4 | import * as Provider from "alchemy/Provider"; |
| 5 | import { Resource } from "alchemy/Resource"; |
| 6 | import * as Data from "effect/Data"; |
| 7 | import * as Duration from "effect/Duration"; |
| 8 | import * as Effect from "effect/Effect"; |
| 9 | import * as Schedule from "effect/Schedule"; |
| 10 | import * as Stream from "effect/Stream"; |
| 11 | import { waitForAction } from "./actions.ts"; |
| 12 | import { alchemyStackSelector } from "./Labels.ts"; |
| 13 | import type { Providers } from "./Providers.ts"; |
| 14 | |
| 15 | /** |
| 16 | * A resource-valued prop: the resource itself, or an Effect that produces |
| 17 | * it (so `yield* Volume(...)` and `Volume(...)` both type-check). |
| 18 | */ |
| 19 | type Ref<T> = T | Effect.Effect<T, never, Providers>; |
| 20 | |
| 21 | /** |
| 22 | * Volume identity. A `Hetzner.Volume` resource satisfies this via `id`. |
| 23 | */ |
| 24 | export type VolumeAttachmentVolume = { |
| 25 | readonly id: number; |
| 26 | }; |
| 27 | |
| 28 | /** |
| 29 | * Server identity. A `Hetzner.Server` resource satisfies this via |
| 30 | * `serverId`. |
| 31 | */ |
| 32 | export type VolumeAttachmentServer = { |
| 33 | readonly serverId: number; |
| 34 | }; |
| 35 | |
| 36 | export interface VolumeAttachmentProps { |
| 37 | /** |
| 38 | * Volume to attach. Accepts a `Hetzner.Volume` or `{ id }`. Changing |
| 39 | * the Volume replaces the attachment. |
| 40 | */ |
| 41 | volume: Ref<VolumeAttachmentVolume>; |
| 42 | /** |
| 43 | * Server to attach the Volume to. Accepts a `Hetzner.Server` or |
| 44 | * `{ serverId }`. Changing the Server replaces the attachment. |
| 45 | */ |
| 46 | server: Ref<VolumeAttachmentServer>; |
| 47 | /** |
| 48 | * Auto-mount the Volume after attach. Updating this detaches and |
| 49 | * re-attaches the Volume so the new value is applied. |
| 50 | * |
| 51 | * @default false |
| 52 | */ |
| 53 | automount?: boolean; |
| 54 | } |
| 55 | |
| 56 | export type VolumeAttachment = Resource< |
| 57 | "Hetzner.VolumeAttachment", |
| 58 | VolumeAttachmentProps, |
| 59 | { |
| 60 | /** Numeric Hetzner Volume ID. */ |
| 61 | volumeId: number; |
| 62 | /** Numeric Hetzner Server ID the Volume is attached to. */ |
| 63 | serverId: number; |
| 64 | /** |
| 65 | * Last-applied automount flag. Hetzner does not expose the live |
| 66 | * automount state, so this is the desired value from the last |
| 67 | * successful reconcile. |
| 68 | */ |
| 69 | automount: boolean; |
| 70 | /** Device path on the file system (e.g. `/dev/disk/by-id/scsi-…`). */ |
| 71 | linuxDevice: string; |
| 72 | }, |
| 73 | never, |
| 74 | Providers |
| 75 | >; |
| 76 | |
| 77 | /** |
| 78 | * Attaches a Hetzner Cloud Volume to a Server in the same Location. |
| 79 | * The Volume and Server must already exist. Deleting the attachment |
| 80 | * detaches the Volume; it does not delete the Volume or the Server. |
| 81 | * |
| 82 | * This is an existence-style resource — its identity is the |
| 83 | * `volume`/`server` pair. Changing either replaces the attachment. |
| 84 | * `automount` updates in place (detach + re-attach). |
| 85 | * |
| 86 | * @see https://docs.hetzner.cloud/reference/cloud#volume-actions-attach-volume-to-a-server |
| 87 | * |
| 88 | * ### Attaching a Volume |
| 89 | * **Example:** Attach a Volume to a Server |
| 90 | * ```typescript |
| 91 | * const server = yield* Hetzner.Server("web", { |
| 92 | * serverType: "cx23", |
| 93 | * image: "ubuntu-24.04", |
| 94 | * location: "nbg1", |
| 95 | * }); |
| 96 | * const volume = yield* Hetzner.Volume("data", { |
| 97 | * size: 10, |
| 98 | * format: "ext4", |
| 99 | * location: "nbg1", |
| 100 | * }); |
| 101 | * const attachment = yield* Hetzner.VolumeAttachment("data-attach", { |
| 102 | * volume, |
| 103 | * server, |
| 104 | * }); |
| 105 | * ``` |
| 106 | * |
| 107 | * **Example:** Attach with automount |
| 108 | * ```typescript |
| 109 | * const attachment = yield* Hetzner.VolumeAttachment("data-attach", { |
| 110 | * volume, |
| 111 | * server, |
| 112 | * automount: true, |
| 113 | * }); |
| 114 | * ``` |
| 115 | * |
| 116 | * @resource |
| 117 | * @product Volume |
| 118 | */ |
| 119 | export const VolumeAttachment = Resource<VolumeAttachment>("Hetzner.VolumeAttachment"); |
| 120 | |
| 121 | class VolumeAttachmentError extends Data.TaggedError("Hetzner.VolumeAttachmentError")<{ |
| 122 | message: string; |
| 123 | }> {} |
| 124 | |
| 125 | class VolumeNotFound extends Data.TaggedError("Hetzner.VolumeNotFound")<{ |
| 126 | volumeId: number; |
| 127 | }> {} |
| 128 | |
| 129 | class AttachmentPending extends Data.TaggedError("AttachmentPending")<{ |
| 130 | volumeId: number; |
| 131 | serverId: number | null; |
| 132 | }> {} |
| 133 | |
| 134 | class AttachmentTimeout extends Data.TaggedError("AttachmentTimeout")<{ |
| 135 | volumeId: number; |
| 136 | serverId: number | null; |
| 137 | }> {} |
| 138 | |
| 139 | const retryable = (e: { readonly _tag: string }): boolean => |
| 140 | e._tag === "AttachmentPending" || |
| 141 | e._tag === "TooManyRequests" || |
| 142 | e._tag === "ServiceUnavailable" || |
| 143 | e._tag === "InternalServerError" || |
| 144 | e._tag === "BadGateway" || |
| 145 | e._tag === "GatewayTimeout" || |
| 146 | e._tag === "Locked"; |
| 147 | |
| 148 | const backoff = Schedule.min([ |
| 149 | Schedule.exponential(Duration.millis(500), 1.5), |
| 150 | Schedule.spaced(Duration.seconds(5)), |
| 151 | ]); |
| 152 | |
| 153 | const volumeIdOf = (value: unknown): number | undefined => { |
| 154 | if (value === null || typeof value !== "object") return undefined; |
| 155 | const rec = value as { id?: unknown; volumeId?: unknown }; |
| 156 | if (typeof rec.id === "number") return rec.id; |
| 157 | if (typeof rec.volumeId === "number") return rec.volumeId; |
| 158 | return undefined; |
| 159 | }; |
| 160 | |
| 161 | const serverIdOf = (value: unknown): number | undefined => { |
| 162 | if (value === null || typeof value !== "object") return undefined; |
| 163 | const rec = value as { serverId?: unknown; id?: unknown }; |
| 164 | if (typeof rec.serverId === "number") return rec.serverId; |
| 165 | if (typeof rec.id === "number") return rec.id; |
| 166 | return undefined; |
| 167 | }; |
| 168 | |
| 169 | const getById = (id: number) => |
| 170 | Hetzner.volumes.getVolume({ id }).pipe( |
| 171 | Effect.map(({ volume }) => volume), |
| 172 | Effect.catchTag("NotFound", () => Effect.undefined), |
| 173 | ); |
| 174 | |
| 175 | const toAttrs = ( |
| 176 | volume: GetVolumeResponseVolume, |
| 177 | automount: boolean, |
| 178 | ): VolumeAttachment["Attributes"] | undefined => { |
| 179 | if (volume.server === null) return undefined; |
| 180 | return { |
| 181 | volumeId: volume.id, |
| 182 | serverId: volume.server, |
| 183 | automount, |
| 184 | linuxDevice: volume.linux_device, |
| 185 | }; |
| 186 | }; |
| 187 | |
| 188 | const waitUntilServer = (volumeId: number, serverId: number | null) => |
| 189 | getById(volumeId).pipe( |
| 190 | Effect.flatMap((volume) => { |
| 191 | if (volume === undefined) { |
| 192 | return serverId === null |
| 193 | ? Effect.undefined |
| 194 | : Effect.fail( |
| 195 | new AttachmentPending({ |
| 196 | volumeId, |
| 197 | serverId: null, |
| 198 | }), |
| 199 | ); |
| 200 | } |
| 201 | const attached = volume.server; |
| 202 | if (attached === serverId) return Effect.succeed(volume); |
| 203 | return Effect.fail( |
| 204 | new AttachmentPending({ |
| 205 | volumeId, |
| 206 | serverId: attached, |
| 207 | }), |
| 208 | ); |
| 209 | }), |
| 210 | Effect.retry({ |
| 211 | while: retryable, |
| 212 | times: 10, |
| 213 | schedule: backoff, |
| 214 | }), |
| 215 | Effect.catchTag( |
| 216 | "AttachmentPending", |
| 217 | (e) => |
| 218 | new AttachmentTimeout({ |
| 219 | volumeId: e.volumeId, |
| 220 | serverId: e.serverId, |
| 221 | }), |
| 222 | ), |
| 223 | ); |
| 224 | |
| 225 | const detach = (volumeId: number) => |
| 226 | Hetzner.volumeActions.detachVolume({ id: volumeId }).pipe( |
| 227 | Effect.tap(({ action }) => |
| 228 | waitForAction(action).pipe( |
| 229 | // Volume detach can outlive the action poll under load; observe |
| 230 | // the Volume's `server` field instead of failing the reconcile. |
| 231 | Effect.catchTag("ActionTimeout", () => Effect.void), |
| 232 | ), |
| 233 | ), |
| 234 | Effect.catchTag(["NotFound", "UnprocessableEntity"], () => Effect.void), |
| 235 | ); |
| 236 | |
| 237 | const attach = (volumeId: number, serverId: number, automount: boolean) => |
| 238 | Hetzner.volumeActions |
| 239 | .attachVolume({ |
| 240 | id: volumeId, |
| 241 | server: serverId, |
| 242 | automount, |
| 243 | }) |
| 244 | .pipe( |
| 245 | Effect.tap(({ action }) => |
| 246 | waitForAction(action).pipe(Effect.catchTag("ActionTimeout", () => Effect.void)), |
| 247 | ), |
| 248 | Effect.catchTag("UnprocessableEntity", () => Effect.void), |
| 249 | Effect.retry({ |
| 250 | while: retryable, |
| 251 | times: 10, |
| 252 | schedule: backoff, |
| 253 | }), |
| 254 | ); |
| 255 | |
| 256 | export const VolumeAttachmentProvider = () => |
| 257 | Provider.succeed(VolumeAttachment, { |
| 258 | stables: ["volumeId", "serverId", "linuxDevice"], |
| 259 | nuke: { dependsOn: ["Hetzner.Volume", "Hetzner.Server"] }, |
| 260 | list: Effect.fn(function* () { |
| 261 | const items = yield* Hetzner.volumes.listVolumes |
| 262 | .items({ label_selector: alchemyStackSelector, per_page: 50 }) |
| 263 | .pipe( |
| 264 | Stream.runCollect, |
| 265 | Effect.map((chunk) => Array.from(chunk)), |
| 266 | ); |
| 267 | return items.flatMap((volume) => { |
| 268 | if (volume.server === null) return []; |
| 269 | return [ |
| 270 | { |
| 271 | volumeId: volume.id, |
| 272 | serverId: volume.server, |
| 273 | automount: false, |
| 274 | linuxDevice: volume.linux_device, |
| 275 | }, |
| 276 | ]; |
| 277 | }); |
| 278 | }), |
| 279 | diff: Effect.fn(function* ({ news, output }) { |
| 280 | if (!isResolved(news)) return undefined; |
| 281 | const nextVolume = volumeIdOf(news.volume); |
| 282 | const nextServer = serverIdOf(news.server); |
| 283 | if ( |
| 284 | output !== undefined && |
| 285 | nextVolume !== undefined && |
| 286 | nextServer !== undefined && |
| 287 | (output.volumeId !== nextVolume || output.serverId !== nextServer) |
| 288 | ) { |
| 289 | return { action: "replace" } as const; |
| 290 | } |
| 291 | return undefined; |
| 292 | }), |
| 293 | read: Effect.fn(function* ({ olds, output }) { |
| 294 | const volumeId = |
| 295 | output?.volumeId ?? (olds !== undefined ? volumeIdOf(olds.volume) : undefined); |
| 296 | const serverId = |
| 297 | output?.serverId ?? (olds !== undefined ? serverIdOf(olds.server) : undefined); |
| 298 | if (volumeId === undefined || serverId === undefined) { |
| 299 | return undefined; |
| 300 | } |
| 301 | const found = yield* getById(volumeId); |
| 302 | if (found === undefined || found.server !== serverId) { |
| 303 | return undefined; |
| 304 | } |
| 305 | return toAttrs(found, output?.automount ?? olds?.automount ?? false); |
| 306 | }), |
| 307 | reconcile: Effect.fn(function* ({ news }) { |
| 308 | const volumeId = volumeIdOf(news.volume); |
| 309 | const serverId = serverIdOf(news.server); |
| 310 | if (volumeId === undefined || serverId === undefined) { |
| 311 | return yield* new VolumeAttachmentError({ |
| 312 | message: "VolumeAttachment requires a resolved volume and server", |
| 313 | }); |
| 314 | } |
| 315 | const desiredAutomount = news.automount ?? false; |
| 316 | |
| 317 | // Observe — cached output.volumeId is a hint; the Volume is the |
| 318 | // source of truth for whether this attachment exists. |
| 319 | let current = yield* getById(volumeId); |
| 320 | if (current === undefined) { |
| 321 | return yield* new VolumeNotFound({ volumeId }); |
| 322 | } |
| 323 | |
| 324 | // Ensure — attach when missing or attached to a different Server. |
| 325 | // Already-attached (UnprocessableEntity) is a race; re-observe. |
| 326 | if (current.server !== serverId) { |
| 327 | if (current.server !== null) { |
| 328 | yield* detach(current.id); |
| 329 | current = (yield* waitUntilServer(current.id, null)) ?? current; |
| 330 | } |
| 331 | yield* attach(current.id, serverId, desiredAutomount); |
| 332 | current = (yield* waitUntilServer(current.id, serverId)) ?? (yield* getById(volumeId)); |
| 333 | if (current === undefined) { |
| 334 | return yield* new VolumeNotFound({ volumeId }); |
| 335 | } |
| 336 | } |
| 337 | |
| 338 | // Automount is only accepted on attach. Hetzner has no update API, |
| 339 | // and detach+reattach to flip it unmounts the disk — skip when the |
| 340 | // Volume is already on the desired Server. |
| 341 | const attrs = toAttrs(current, desiredAutomount); |
| 342 | if (attrs === undefined) { |
| 343 | return yield* new AttachmentTimeout({ |
| 344 | volumeId, |
| 345 | serverId: current.server, |
| 346 | }); |
| 347 | } |
| 348 | return attrs; |
| 349 | }), |
| 350 | delete: Effect.fn(function* ({ output }) { |
| 351 | const current = yield* getById(output.volumeId); |
| 352 | if (current === undefined) return; |
| 353 | if (current.server !== output.serverId) return; |
| 354 | |
| 355 | yield* detach(current.id); |
| 356 | yield* waitUntilServer(current.id, null); |
| 357 | }), |
| 358 | }); |