@puls-dev/hcloud 0.5.3 → 0.5.4

package/README.md

@@ -10,20 +10,20 @@ This package is the official Hetzner Cloud provider plug-in for Puls. It manages
 
 ## Available Builders
 
-* **\`HCloud.Server\`**: Provision cloud servers (analogous to Droplets) with support for SSH keys, server types, locations, and our signature Ansible playbook provisioning.
-* **\`HCloud.SSHKey\`**: Register SSH public keys on your Hetzner Cloud account.
-* **\`HCloud.Network\`**: Create private networks (VPCs) with custom IP ranges.
-* **\`HCloud.Firewall\`**: Define inbound/outbound firewall rules.
+* **`HCloud.Server`**: Provision cloud servers (analogous to Droplets) with support for SSH keys, server types, locations, and our signature Ansible playbook provisioning.
+* **`HCloud.SSHKey`**: Register SSH public keys on your Hetzner Cloud account.
+* **`HCloud.Network`**: Create private networks (VPCs) with custom IP ranges.
+* **`HCloud.Firewall`**: Define inbound/outbound firewall rules.
 
 ## Installation
 
-\`\`\`bash
+```bash
 npm install @puls-dev/core @puls-dev/hcloud
-\`\`\`
+```
 
 ## Quick Example
 
-\`\`\`typescript
+```typescript
 import { Stack, Deploy } from "@puls-dev/core";
 import { HCloud, SERVER_TYPE, LOCATION, OS_IMAGE } from "@puls-dev/hcloud";
 
@@ -43,13 +43,13 @@ class MyStack extends Stack {
     .networks([this.net])
     .provision(["playbooks/web.yml"]);
 }
-\`\`\`
+```
 
 ## Authentication
 
 Declare your Hetzner Cloud API token in your \`.env\` file:
-\`\`\`bash
+```bash
 HCLOUD_TOKEN=your-hetzner-cloud-api-token
-\`\`\`
+```
 
-Learn more at **[pulsdev.io/providers/hcloud](https://pulsdev.io/providers/hcloud.md)**.
+Learn more at **[pulsdev.io/providers/hcloud](https://pulsdev.io/providers/hcloud)**.

package/dist/api.js

@@ -78,6 +78,31 @@ export class HCloudApiClient {
                 firewalls: []
             };
         }
+        if (path.includes("/volumes")) {
+            return {
+                volume: {
+                    id: 8080,
+                    name: body?.name ?? "mock-volume",
+                    size: body?.size ?? 10,
+                    linux_device: "/dev/disk/by-id/scsi-0HC_Volume_8080"
+                },
+                volumes: [],
+                action: { id: 7890, status: "success" }
+            };
+        }
+        if (path.includes("/load_balancers")) {
+            return {
+                load_balancer: {
+                    id: 9090,
+                    name: body?.name ?? "mock-lb",
+                    public_net: {
+                        ipv4: { ip: "1.2.3.4" }
+                    }
+                },
+                load_balancers: [],
+                action: { id: 7890, status: "success" }
+            };
+        }
         if (path.includes("/actions/")) {
             return { action: { id: 7890, status: "success" } };
         }

package/dist/index.d.ts

@@ -3,6 +3,8 @@ import { ServerBuilder } from "./server.js";
 import { SSHKeyBuilder } from "./ssh_key.js";
 import { NetworkBuilder } from "./network.js";
 import { FirewallBuilder } from "./firewall.js";
+import { VolumeBuilder } from "./volume.js";
+import { LoadBalancerBuilder } from "./load_balancer.js";
 export declare const HCloud: {
     init: (opts: {
         token: string;
@@ -13,11 +15,15 @@ export declare const HCloud: {
     SSHKey: (name: string) => SSHKeyBuilder;
     Network: (name: string) => NetworkBuilder;
     Firewall: (name: string) => FirewallBuilder;
+    Volume: (name: string) => VolumeBuilder;
+    LoadBalancer: (name: string) => LoadBalancerBuilder;
 };
 export * from "./types/hcloud.js";
 export { ServerBuilder } from "./server.js";
 export { SSHKeyBuilder } from "./ssh_key.js";
 export { NetworkBuilder } from "./network.js";
 export { FirewallBuilder } from "./firewall.js";
+export { VolumeBuilder } from "./volume.js";
+export { LoadBalancerBuilder } from "./load_balancer.js";
 export { HCloudApiClient, getHCloudApi } from "./api.js";
 export { listHCloudResources } from "./list.js";

package/dist/index.js

@@ -4,6 +4,8 @@ import { ServerBuilder } from "./server.js";
 import { SSHKeyBuilder } from "./ssh_key.js";
 import { NetworkBuilder } from "./network.js";
 import { FirewallBuilder } from "./firewall.js";
+import { VolumeBuilder } from "./volume.js";
+import { LoadBalancerBuilder } from "./load_balancer.js";
 export const HCloud = {
     init: (opts) => {
         Config.set({
@@ -17,11 +19,15 @@ export const HCloud = {
     SSHKey: (name) => new SSHKeyBuilder(name),
     Network: (name) => new NetworkBuilder(name),
     Firewall: (name) => new FirewallBuilder(name),
+    Volume: (name) => new VolumeBuilder(name),
+    LoadBalancer: (name) => new LoadBalancerBuilder(name),
 };
 export * from "./types/hcloud.js";
 export { ServerBuilder } from "./server.js";
 export { SSHKeyBuilder } from "./ssh_key.js";
 export { NetworkBuilder } from "./network.js";
 export { FirewallBuilder } from "./firewall.js";
+export { VolumeBuilder } from "./volume.js";
+export { LoadBalancerBuilder } from "./load_balancer.js";
 export { HCloudApiClient, getHCloudApi } from "./api.js";
 export { listHCloudResources } from "./list.js";

package/dist/list.js

@@ -16,10 +16,12 @@ function priceForType(type) {
 }
 export async function listHCloudResources() {
     const api = getHCloudApi();
-    const [serversData, firewallsData, networksData] = await Promise.all([
+    const [serversData, firewallsData, networksData, volumesData, lbData] = await Promise.all([
         api.get('/servers'),
         api.get('/firewalls'),
         api.get('/networks'),
+        api.get('/volumes'),
+        api.get('/load_balancers'),
     ]);
     const servers = serversData.servers.map((s) => ({
         id: s.id,
@@ -40,6 +42,19 @@ export async function listHCloudResources() {
         name: n.name,
         ipRange: n.ip_range ?? '',
     }));
+    const volumes = volumesData.volumes.map((v) => ({
+        id: v.id,
+        name: v.name,
+        size: v.size,
+        serverId: v.server ?? undefined,
+    }));
+    const loadBalancers = lbData.load_balancers.map((lb) => ({
+        id: lb.id,
+        name: lb.name,
+        ip: lb.public_net?.ipv4?.ip ?? undefined,
+        location: lb.location?.name ?? '',
+        type: lb.load_balancer_type?.name ?? '',
+    }));
     const totalMonthlyCost = servers.reduce((sum, s) => sum + s.monthlyCost, 0);
-    return { servers, firewalls, networks, totalMonthlyCost };
+    return { servers, firewalls, networks, volumes, loadBalancers, totalMonthlyCost };
 }

package/dist/load_balancer.d.ts

@@ -0,0 +1,35 @@
+import { BaseBuilder, Output } from '@puls-dev/core';
+import { ServerBuilder } from './server.js';
+export interface HCloudForwardingRule {
+    listenPort: number;
+    targetPort: number;
+    protocol: 'http' | 'https' | 'tcp';
+}
+export declare class LoadBalancerBuilder extends BaseBuilder {
+    readonly out: {
+        id: Output<number>;
+        ip: Output<string>;
+    };
+    private _type;
+    private _location;
+    private _algorithm;
+    private _services;
+    private _targets;
+    private lbId?;
+    private resolvedIp?;
+    constructor(name: string);
+    private discoverLb;
+    type(lbType: string): this;
+    location(loc: string): this;
+    algorithm(algo: 'round_robin' | 'least_connections'): this;
+    forward(listenPort: number, targetPort: number, protocol?: 'http' | 'https' | 'tcp'): this;
+    target(...servers: (ServerBuilder | number)[]): this;
+    private log;
+    getDiff(existing: any): {
+        field: string;
+        declared: string;
+        live: any;
+    }[];
+    deploy(): Promise<void>;
+    destroy(): Promise<void>;
+}

package/dist/load_balancer.js

@@ -0,0 +1,226 @@
+import { BaseBuilder, Output, Config } from '@puls-dev/core';
+import { getHCloudApi } from './api.js';
+import { ServerBuilder } from './server.js';
+export class LoadBalancerBuilder extends BaseBuilder {
+    out = {
+        id: new Output(),
+        ip: new Output(),
+    };
+    _type = 'lb11';
+    _location = Config.get().providers.hcloud?.defaultLocation || 'nbg1';
+    _algorithm = 'round_robin';
+    _services = [];
+    _targets = [];
+    lbId;
+    resolvedIp;
+    constructor(name) {
+        super(name);
+        this.discoveryPromise = this.discoverLb(name);
+    }
+    async discoverLb(name) {
+        const api = getHCloudApi();
+        const data = await api.get('/load_balancers');
+        const match = data.load_balancers.find(lb => lb.name === name) ?? null;
+        if (match) {
+            this.lbId = match.id;
+            this.resolvedIp = match.public_net?.ipv4?.ip;
+            this.out.id.resolve(match.id);
+            if (this.resolvedIp)
+                this.out.ip.resolve(this.resolvedIp);
+        }
+        return match;
+    }
+    type(lbType) {
+        this._type = lbType;
+        return this;
+    }
+    location(loc) {
+        this._location = loc;
+        return this;
+    }
+    algorithm(algo) {
+        this._algorithm = algo;
+        return this;
+    }
+    forward(listenPort, targetPort, protocol = 'http') {
+        this._services.push({ listenPort, targetPort, protocol });
+        return this;
+    }
+    target(...servers) {
+        this._targets.push(...servers);
+        return this;
+    }
+    log(msg) {
+        console.log(`   ⚖️ [HCloud.LoadBalancer] ${msg}`);
+    }
+    getDiff(existing) {
+        const diffs = [];
+        if (existing && existing.load_balancer_type?.name !== this._type) {
+            diffs.push({ field: "type", declared: this._type, live: existing.load_balancer_type?.name });
+        }
+        if (existing && existing.location?.name !== this._location) {
+            diffs.push({ field: "location", declared: this._location, live: existing.location?.name });
+        }
+        if (existing && existing.algorithm?.type !== this._algorithm) {
+            diffs.push({ field: "algorithm", declared: this._algorithm, live: existing.algorithm?.type });
+        }
+        return diffs;
+    }
+    async deploy() {
+        const dryRun = this.isDryRunActive();
+        const existing = await this.discoveryPromise;
+        const api = getHCloudApi();
+        const hasChanges = existing ? this.getDiff(existing).length > 0 : true;
+        // Resolve Targets
+        const targetServerIds = [];
+        for (const t of this._targets) {
+            if (t instanceof ServerBuilder) {
+                targetServerIds.push(await t.out.id.get());
+            }
+            else {
+                targetServerIds.push(t);
+            }
+        }
+        if (dryRun) {
+            this.log(`Planning load balancer "${this.name}"...`);
+            if (!existing) {
+                this.log(`[PLAN] Create load balancer ${this.name} (${this._type} in ${this._location})`);
+                this._services.forEach(s => {
+                    this.log(`      └─ Forward: ${s.protocol.toUpperCase()} ${s.listenPort} -> ${s.targetPort}`);
+                });
+                if (targetServerIds.length > 0) {
+                    this.log(`      └─ Targets: [${targetServerIds.join(', ')}]`);
+                }
+                this.out.id.resolve(-1);
+                this.out.ip.resolve('0.0.0.0');
+            }
+            else if (hasChanges) {
+                this.log(`[PLAN] Recreate load balancer ${this.name} due to type/location change`);
+            }
+            else {
+                this.log(`Load balancer is up to date.`);
+            }
+            return;
+        }
+        this.log(`Finalizing load balancer...`);
+        const servicesPayload = this._services.map(s => ({
+            protocol: s.protocol,
+            listen_port: s.listenPort,
+            destination_port: s.targetPort,
+            proxyprotocol: false,
+            health_check: {
+                protocol: s.protocol === 'tcp' ? 'tcp' : 'http',
+                port: s.targetPort,
+                interval: 15,
+                timeout: 10,
+                retries: 3,
+                ...(s.protocol !== 'tcp' && {
+                    http: {
+                        path: '/',
+                        status_codes: ['2??', '3??']
+                    }
+                })
+            }
+        }));
+        const targetsPayload = targetServerIds.map(id => ({
+            type: 'server',
+            server: { id }
+        }));
+        if (!existing || hasChanges) {
+            if (existing && hasChanges) {
+                this.log(`Load balancer type/location changed. Re-creating...`);
+                await api.delete(`/load_balancers/${existing.id}`);
+                await this.waitFor('load balancer deletion to complete', async () => {
+                    try {
+                        const res = await api.get('/load_balancers');
+                        return !res.load_balancers.some(lb => lb.name === this.name);
+                    }
+                    catch {
+                        return true;
+                    }
+                });
+            }
+            const res = await api.post('/load_balancers', {
+                name: this.name,
+                load_balancer_type: this._type,
+                location: this._location,
+                algorithm: { type: this._algorithm },
+                services: servicesPayload,
+                targets: targetsPayload,
+            });
+            this.lbId = res.load_balancer.id;
+            this.resolvedIp = res.load_balancer.public_net?.ipv4?.ip;
+            this.out.id.resolve(this.lbId);
+            if (this.resolvedIp)
+                this.out.ip.resolve(this.resolvedIp);
+            await api.waitForAction(res.action.id);
+            this.log(`Created load balancer (id=${this.lbId}, ip=${this.resolvedIp})`);
+        }
+        else {
+            // Update existing load balancer services/targets if they differ
+            const currentServices = existing.services || [];
+            const currentTargets = existing.targets || [];
+            // Check if services match
+            const servicesChanged = servicesPayload.length !== currentServices.length ||
+                servicesPayload.some((s, idx) => {
+                    const curr = currentServices[idx];
+                    return !curr || curr.listen_port !== s.listen_port || curr.destination_port !== s.destination_port || curr.protocol !== s.protocol;
+                });
+            if (servicesChanged) {
+                this.log(`Updating services...`);
+                // Delete old services
+                for (const s of currentServices) {
+                    const res = await api.post(`/load_balancers/${this.lbId}/actions/delete_service`, {
+                        listen_port: s.listen_port
+                    });
+                    await api.waitForAction(res.action.id);
+                }
+                // Add new services
+                for (const s of servicesPayload) {
+                    const res = await api.post(`/load_balancers/${this.lbId}/actions/add_service`, s);
+                    await api.waitForAction(res.action.id);
+                }
+            }
+            // Check if targets match
+            const currentTargetServerIds = currentTargets
+                .filter((t) => t.type === 'server')
+                .map((t) => t.server.id);
+            const targetsChanged = targetServerIds.length !== currentTargetServerIds.length ||
+                targetServerIds.some(id => !currentTargetServerIds.includes(id));
+            if (targetsChanged) {
+                this.log(`Updating targets...`);
+                // Remove old targets
+                for (const t of currentTargets) {
+                    if (t.type === 'server') {
+                        const res = await api.post(`/load_balancers/${this.lbId}/actions/remove_target`, {
+                            type: 'server',
+                            server: { id: t.server.id }
+                        });
+                        await api.waitForAction(res.action.id);
+                    }
+                }
+                // Add new targets
+                for (const id of targetServerIds) {
+                    const res = await api.post(`/load_balancers/${this.lbId}/actions/add_target`, {
+                        type: 'server',
+                        server: { id }
+                    });
+                    await api.waitForAction(res.action.id);
+                }
+            }
+            this.log(`Load balancer is up to date.`);
+        }
+    }
+    async destroy() {
+        const existing = await this.discoveryPromise;
+        if (existing) {
+            this.log(`Deleting load balancer...`);
+            const api = getHCloudApi();
+            await api.delete(`/load_balancers/${existing.id}`);
+            this.log(`Deleted load balancer.`);
+        }
+        else {
+            this.log(`Load balancer does not exist. Skipping deletion.`);
+        }
+    }
+}

package/dist/load_balancer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/load_balancer.test.js

@@ -0,0 +1,86 @@
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { LoadBalancerBuilder } from './load_balancer.js';
+import { Config } from '@puls-dev/core';
+describe('LoadBalancerBuilder Unit Tests', () => {
+    let originalFetch;
+    let fetchCalls = [];
+    let mockResponses = {};
+    beforeEach(() => {
+        Config.set({
+            dryRun: false,
+            providers: {
+                hcloud: { token: 'fake-hcloud-token', defaultLocation: 'nbg1' }
+            }
+        });
+        originalFetch = globalThis.fetch;
+        fetchCalls = [];
+        mockResponses = {};
+        mockResponses['GET /load_balancers'] = {
+            status: 200,
+            body: { load_balancers: [] }
+        };
+        globalThis.fetch = async (input, init) => {
+            const url = String(input);
+            const method = init?.method ?? 'GET';
+            const body = init?.body ? JSON.parse(init.body) : undefined;
+            fetchCalls.push({ url, method, body });
+            const matchKey = Object.keys(mockResponses)
+                .filter(key => {
+                const [mMethod, mPath] = key.split(' ');
+                return method === mMethod && url.includes(mPath);
+            })
+                .sort((a, b) => b.split(' ')[1].length - a.split(' ')[1].length)[0];
+            if (matchKey) {
+                const resp = mockResponses[matchKey];
+                return {
+                    ok: resp.status >= 200 && resp.status < 300,
+                    status: resp.status,
+                    json: async () => resp.body,
+                    text: async () => JSON.stringify(resp.body),
+                };
+            }
+            return {
+                ok: false,
+                status: 404,
+                json: async () => ({ error: { message: 'Not found' } }),
+            };
+        };
+    });
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+    });
+    test('creates a load balancer when it does not exist', async () => {
+        mockResponses['POST /load_balancers'] = {
+            status: 201,
+            body: {
+                load_balancer: {
+                    id: 9090,
+                    name: 'web-lb',
+                    public_net: { ipv4: { ip: '1.2.3.4' } }
+                },
+                action: { id: 7890 }
+            }
+        };
+        mockResponses['GET /actions/7890'] = {
+            status: 200,
+            body: { action: { status: 'success' } }
+        };
+        const lb = new LoadBalancerBuilder('web-lb')
+            .type('lb11')
+            .location('nbg1')
+            .forward(80, 8080, 'http')
+            .target(123);
+        await lb.deploy();
+        assert.strictEqual(await lb.out.id.get(), 9090);
+        assert.strictEqual(await lb.out.ip.get(), '1.2.3.4');
+        const postCall = fetchCalls.find(c => c.method === 'POST' && c.url.includes('/load_balancers'));
+        assert.ok(postCall);
+        assert.strictEqual(postCall.body.name, 'web-lb');
+        assert.strictEqual(postCall.body.load_balancer_type, 'lb11');
+        assert.strictEqual(postCall.body.location, 'nbg1');
+        assert.strictEqual(postCall.body.services[0].listen_port, 80);
+        assert.strictEqual(postCall.body.services[0].destination_port, 8080);
+        assert.strictEqual(postCall.body.targets[0].server.id, 123);
+    });
+});

package/dist/plugin.js

@@ -30,11 +30,25 @@ export const hcloudPlugin = {
                 { header: "IP Range", width: 20, render: (n) => n.ipRange },
             ]);
         }
+        if (inv.volumes && inv.volumes.length > 0) {
+            printSection(`Hetzner Cloud Volumes  ·  ${inv.volumes.length}`, inv.volumes, [
+                { header: "Name", width: 24, render: (v) => v.name },
+                { header: "Size (GB)", width: 10, render: (v) => `${v.size} GB` },
+                { header: "Attached Server", width: 18, render: (v) => v.serverId ? String(v.serverId) : "None" },
+            ]);
+        }
+        if (inv.loadBalancers && inv.loadBalancers.length > 0) {
+            printSection(`Hetzner Cloud Load Balancers  ·  ${inv.loadBalancers.length}`, inv.loadBalancers, [
+                { header: "Name", width: 24, render: (lb) => lb.name },
+                { header: "Type", width: 10, render: (lb) => lb.type },
+                { header: "Location", width: 10, render: (lb) => lb.location },
+                { header: "IP", width: 15, render: (lb) => lb.ip ?? "-" },
+            ]);
+        }
     },
     configure: (pOpts) => {
         Config.set({
             providers: {
-                ...Config.get().providers,
                 hcloud: pOpts,
             },
         });

package/dist/volume.d.ts

@@ -0,0 +1,29 @@
+import { BaseBuilder, Output } from '@puls-dev/core';
+import { ServerBuilder } from './server.js';
+export declare class VolumeBuilder extends BaseBuilder {
+    readonly out: {
+        id: Output<number>;
+        linuxDevice: Output<string>;
+    };
+    private _size;
+    private _location;
+    private _server?;
+    private _automount;
+    private _format?;
+    private volumeId?;
+    constructor(name: string);
+    private discoverVolume;
+    size(gb: number): this;
+    location(loc: string): this;
+    server(server: ServerBuilder | number): this;
+    automount(auto: boolean): this;
+    format(fsType: 'ext4' | 'xfs'): this;
+    private log;
+    getDiff(existing: any): {
+        field: string;
+        declared: number;
+        live: any;
+    }[];
+    deploy(): Promise<void>;
+    destroy(): Promise<void>;
+}

package/dist/volume.js

@@ -0,0 +1,164 @@
+import { BaseBuilder, Output, Config } from '@puls-dev/core';
+import { getHCloudApi } from './api.js';
+import { ServerBuilder } from './server.js';
+export class VolumeBuilder extends BaseBuilder {
+    out = {
+        id: new Output(),
+        linuxDevice: new Output(),
+    };
+    _size = 10; // GB
+    _location = Config.get().providers.hcloud?.defaultLocation || 'nbg1';
+    _server;
+    _automount = false;
+    _format;
+    volumeId;
+    constructor(name) {
+        super(name);
+        this.discoveryPromise = this.discoverVolume(name);
+    }
+    async discoverVolume(name) {
+        const api = getHCloudApi();
+        const data = await api.get('/volumes');
+        const match = data.volumes.find(v => v.name === name) ?? null;
+        if (match) {
+            this.volumeId = match.id;
+            this.out.id.resolve(match.id);
+            this.out.linuxDevice.resolve(match.linux_device);
+        }
+        return match;
+    }
+    size(gb) {
+        this._size = gb;
+        return this;
+    }
+    location(loc) {
+        this._location = loc;
+        return this;
+    }
+    server(server) {
+        this._server = server;
+        return this;
+    }
+    automount(auto) {
+        this._automount = auto;
+        return this;
+    }
+    format(fsType) {
+        this._format = fsType;
+        return this;
+    }
+    log(msg) {
+        console.log(`   💾 [HCloud.Volume] ${msg}`);
+    }
+    getDiff(existing) {
+        const diffs = [];
+        if (existing && existing.size !== this._size) {
+            diffs.push({ field: "size", declared: this._size, live: existing.size });
+        }
+        return diffs;
+    }
+    async deploy() {
+        const dryRun = this.isDryRunActive();
+        const existing = await this.discoveryPromise;
+        const api = getHCloudApi();
+        const targetServerId = this._server instanceof ServerBuilder
+            ? await this._server.out.id.get()
+            : this._server;
+        if (dryRun) {
+            this.log(`Planning volume "${this.name}"...`);
+            if (!existing) {
+                this.log(`[PLAN] Create volume ${this.name} (${this._size} GB in ${this._location})`);
+                if (targetServerId) {
+                    this.log(`      └─ Attach to server: ${targetServerId}`);
+                }
+                this.out.id.resolve(-1);
+                this.out.linuxDevice.resolve('/dev/disk/by-id/scsi-0HC_Volume_mock');
+            }
+            else {
+                const diffs = this.getDiff(existing);
+                if (diffs.length > 0) {
+                    this.log(`[PLAN] Resize volume ${this.name} ${existing.size} GB -> ${this._size} GB`);
+                }
+                const currentServerId = existing.server;
+                if (targetServerId !== currentServerId) {
+                    if (currentServerId && !targetServerId) {
+                        this.log(`[PLAN] Detach volume from server ${currentServerId}`);
+                    }
+                    else if (!currentServerId && targetServerId) {
+                        this.log(`[PLAN] Attach volume to server ${targetServerId}`);
+                    }
+                    else if (currentServerId && targetServerId) {
+                        this.log(`[PLAN] Detach from server ${currentServerId} and attach to ${targetServerId}`);
+                    }
+                }
+            }
+            return;
+        }
+        this.log(`Finalizing volume...`);
+        if (!existing) {
+            const payload = {
+                name: this.name,
+                size: this._size,
+                automount: this._automount,
+            };
+            if (this._format)
+                payload.format = this._format;
+            if (targetServerId) {
+                payload.server = targetServerId;
+            }
+            else {
+                payload.location = this._location;
+            }
+            const res = await api.post('/volumes', payload);
+            this.volumeId = res.volume.id;
+            this.out.id.resolve(res.volume.id);
+            this.out.linuxDevice.resolve(res.volume.linux_device);
+            if (res.action) {
+                await api.waitForAction(res.action.id);
+            }
+            this.log(`Created volume (id=${this.volumeId})`);
+        }
+        else {
+            const diffs = this.getDiff(existing);
+            if (diffs.length > 0) {
+                this.log(`Resizing volume to ${this._size} GB...`);
+                const res = await api.post(`/volumes/${this.volumeId}/actions/resize`, { size: this._size });
+                await api.waitForAction(res.action.id);
+            }
+            const currentServerId = existing.server;
+            if (targetServerId !== currentServerId) {
+                if (currentServerId) {
+                    this.log(`Detaching volume from server ${currentServerId}...`);
+                    const res = await api.post(`/volumes/${this.volumeId}/actions/detach`, {});
+                    await api.waitForAction(res.action.id);
+                }
+                if (targetServerId) {
+                    this.log(`Attaching volume to server ${targetServerId}...`);
+                    const res = await api.post(`/volumes/${this.volumeId}/actions/attach`, {
+                        server: targetServerId,
+                        automount: this._automount,
+                    });
+                    await api.waitForAction(res.action.id);
+                }
+            }
+            this.log(`Volume is up to date.`);
+        }
+    }
+    async destroy() {
+        const existing = await this.discoveryPromise;
+        if (existing) {
+            this.log(`Deleting volume...`);
+            const api = getHCloudApi();
+            if (existing.server) {
+                this.log(`Detaching from server first...`);
+                const res = await api.post(`/volumes/${existing.id}/actions/detach`, {});
+                await api.waitForAction(res.action.id);
+            }
+            await api.delete(`/volumes/${existing.id}`);
+            this.log(`Deleted volume.`);
+        }
+        else {
+            this.log(`Volume does not exist. Skipping deletion.`);
+        }
+    }
+}

package/dist/volume.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/volume.test.js

@@ -0,0 +1,111 @@
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { VolumeBuilder } from './volume.js';
+import { Config } from '@puls-dev/core';
+describe('VolumeBuilder Unit Tests', () => {
+    let originalFetch;
+    let fetchCalls = [];
+    let mockResponses = {};
+    beforeEach(() => {
+        Config.set({
+            dryRun: false,
+            providers: {
+                hcloud: { token: 'fake-hcloud-token', defaultLocation: 'nbg1' }
+            }
+        });
+        originalFetch = globalThis.fetch;
+        fetchCalls = [];
+        mockResponses = {};
+        mockResponses['GET /volumes'] = {
+            status: 200,
+            body: { volumes: [] }
+        };
+        mockResponses['GET /servers'] = {
+            status: 200,
+            body: { servers: [] }
+        };
+        globalThis.fetch = async (input, init) => {
+            const url = String(input);
+            const method = init?.method ?? 'GET';
+            const body = init?.body ? JSON.parse(init.body) : undefined;
+            fetchCalls.push({ url, method, body });
+            const matchKey = Object.keys(mockResponses)
+                .filter(key => {
+                const [mMethod, mPath] = key.split(' ');
+                return method === mMethod && url.includes(mPath);
+            })
+                .sort((a, b) => b.split(' ')[1].length - a.split(' ')[1].length)[0];
+            if (matchKey) {
+                const resp = mockResponses[matchKey];
+                return {
+                    ok: resp.status >= 200 && resp.status < 300,
+                    status: resp.status,
+                    json: async () => resp.body,
+                    text: async () => JSON.stringify(resp.body),
+                };
+            }
+            return {
+                ok: false,
+                status: 404,
+                json: async () => ({ error: { message: 'Not found' } }),
+            };
+        };
+    });
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+    });
+    test('creates a volume when it does not exist', async () => {
+        mockResponses['POST /volumes'] = {
+            status: 201,
+            body: {
+                volume: {
+                    id: 8080,
+                    name: 'db-data',
+                    size: 20,
+                    linux_device: '/dev/disk/by-id/scsi-0HC_Volume_8080'
+                }
+            }
+        };
+        const volume = new VolumeBuilder('db-data')
+            .size(20)
+            .location('nbg1');
+        await volume.deploy();
+        assert.strictEqual(await volume.out.id.get(), 8080);
+        assert.strictEqual(await volume.out.linuxDevice.get(), '/dev/disk/by-id/scsi-0HC_Volume_8080');
+        const postCall = fetchCalls.find(c => c.method === 'POST' && c.url.includes('/volumes'));
+        assert.ok(postCall);
+        assert.strictEqual(postCall.body.name, 'db-data');
+        assert.strictEqual(postCall.body.size, 20);
+        assert.strictEqual(postCall.body.location, 'nbg1');
+    });
+    test('resizes a volume when size differs', async () => {
+        mockResponses['GET /volumes'] = {
+            status: 200,
+            body: {
+                volumes: [
+                    {
+                        id: 8080,
+                        name: 'db-data',
+                        size: 10,
+                        linux_device: '/dev/disk/by-id/scsi-0HC_Volume_8080',
+                        server: null
+                    }
+                ]
+            }
+        };
+        mockResponses['POST /volumes/8080/actions/resize'] = {
+            status: 201,
+            body: { action: { id: 7890 } }
+        };
+        mockResponses['GET /actions/7890'] = {
+            status: 200,
+            body: { action: { status: 'success' } }
+        };
+        const volume = new VolumeBuilder('db-data')
+            .size(30);
+        await volume.deploy();
+        const resizeCall = fetchCalls.find(c => c.method === 'POST' && c.url.includes('/volumes/8080/actions/resize'));
+        assert.ok(resizeCall);
+        assert.strictEqual(resizeCall.body.size, 30);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@puls-dev/hcloud",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Hetzner Cloud (HCloud) Provider for Puls IaC",
   "type": "module",
   "main": "./dist/index.js",