@stacksjs/ts-cloud 0.7.93 → 0.7.95

package/dist/deploy/dashboard-database.d.ts

@@ -5,11 +5,71 @@
  * path in {@link import('../drivers/shared/db-provision')}.
  */
 import type { CloudConfig, DatabaseConfig, EnvironmentType } from '@ts-cloud/core';
-export type DbEngine = 'mysql' | 'mariadb' | 'postgres';
+export type DbEngine = 'mysql' | 'mariadb' | 'postgres' | 'singlestore' | 'vitess';
+/** Whether this engine is an external cluster with no on-box socket. */
+export declare function isExternalEngine(engine: DbEngine): boolean;
 /** Valid SQL identifier for a database/user name (kept strict for safety). */
 export declare function isValidDbIdentifier(value: string): boolean;
 export declare function resolveDbEngine(config: CloudConfig): DbEngine;
 export declare function buildListScript(engine: DbEngine, database?: DatabaseConfig): string[];
+/**
+ * Run SQL against an external MySQL-wire cluster over TCP.
+ *
+ * Executed from the app box, which by definition can already reach the
+ * cluster (the application connects to it), so this needs no extra network
+ * path. The password goes through `MYSQL_PWD` rather than `-p<pass>`
+ * because a command-line password is visible to any `ps` on the box; this
+ * mirrors how `pgAdminCommand` handles `PGPASSWORD`.
+ */
+export declare function externalMysqlExec(sql: string[], database: DatabaseConfig | undefined, port: number): string[];
+/** vtgate's MySQL-protocol port. Not 3306, which would reach a tablet's mysqld. */
+export declare const VTGATE_DEFAULT_PORT = 15306;
+/**
+ * List a Vitess cluster's keyspaces in the same `DB=` shape the on-box
+ * engines emit, so {@link parseDbList} handles it unchanged.
+ *
+ * A keyspace is Vitess's unit of sharding and occupies the same slot a
+ * database does elsewhere, which makes it the honest thing to show in the
+ * dashboard's "Databases" list. Users are deliberately not listed: vtgate
+ * authentication is configured on the cluster, not through SQL, so there is
+ * nothing here to enumerate or create.
+ */
+export declare function buildVitessListScript(database?: DatabaseConfig): string[];
+/**
+ * Introspect a Vitess cluster: keyspaces, shards, and tablet health.
+ *
+ * These are vtgate's own `SHOW` commands, served over the MySQL protocol,
+ * so they need nothing beyond the connection the app already uses. Each row
+ * is prefixed so one round trip can carry all three lists.
+ */
+export declare function buildVitessTopologyScript(database?: DatabaseConfig): string[];
+export interface VitessShard {
+    keyspace: string;
+    shard: string;
+}
+export interface VitessTablet {
+    cell: string;
+    keyspace: string;
+    shard: string;
+    type: string;
+    state: string;
+    alias: string;
+    hostname: string;
+}
+export interface VitessTopology {
+    keyspaces: string[];
+    shards: VitessShard[];
+    tablets: VitessTablet[];
+}
+/**
+ * Parse the combined topology output.
+ *
+ * `SHOW VITESS_SHARDS` emits `keyspace/shard` rows and `SHOW VITESS_TABLETS`
+ * emits tab-separated columns, so the two are told apart by shape rather
+ * than by position — the command output order is not something to depend on
+ * when a cluster can legitimately return zero rows for either.
+ */
+export declare function parseVitessTopology(output: string): VitessTopology;
 export declare function buildCreateDatabaseScript(engine: DbEngine, name: string, database?: DatabaseConfig): string[];
 export interface CreateUserInput {
     username: string;
@@ -22,12 +82,13 @@ export declare function parseDbList(output: string): {
     databases: string[];
     users: string[];
 };
-interface DbRunResult {
+export interface DbRunResult {
     ok: boolean;
     stdout?: string;
     stderr?: string;
     error?: string;
 }
+export declare function runDb(config: CloudConfig, environment: EnvironmentType, commands: string[], comment: string): Promise<DbRunResult>;
 export declare function listDatabases(config: CloudConfig, environment: EnvironmentType): Promise<DbRunResult & {
     engine: DbEngine;
     databases: string[];
@@ -62,4 +123,31 @@ export declare function listDatabaseBackups(config: CloudConfig, environment: En
         database: string;
     }>;
 }>;
-export {};
+/**
+ * Read a Vitess cluster's topology for the dashboard.
+ *
+ * Read-only by design. Creating keyspaces, resharding, and moving tables are
+ * vtctld operations with real blast radius, and exposing them behind a
+ * dashboard button would invite someone to reshard production by accident.
+ * The panel shows what exists and where it is unhealthy; changing the
+ * topology stays with `vtctldclient`.
+ */
+export declare function describeVitess(config: CloudConfig, environment: EnvironmentType): Promise<DbRunResult & VitessTopology & {
+    engine: DbEngine;
+}>;
+/**
+ * Tablets that are not serving.
+ *
+ * Surfaced separately because it is the one thing in the topology worth
+ * acting on: a keyspace whose primary is missing is a write outage, and a
+ * flat list of a hundred healthy tablets buries that.
+ */
+export declare function unhealthyTablets(tablets: VitessTablet[]): VitessTablet[];
+/**
+ * Shards with no PRIMARY tablet.
+ *
+ * Vitess routes writes to a shard's primary; without one the shard accepts
+ * reads and silently fails writes, which is the failure most worth naming
+ * explicitly in a dashboard.
+ */
+export declare function shardsMissingPrimary(topology: VitessTopology): VitessShard[];

package/dist/deploy/dashboard-vitess.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Vitess control plane: keyspaces, VSchema, and online schema changes.
+ *
+ * ## Two planes, two transports
+ *
+ * A Vitess cluster is administered through two different endpoints, and
+ * conflating them is the first thing that goes wrong:
+ *
+ * - **vtgate** speaks the MySQL wire protocol and serves queries. It also
+ *   answers a surprising amount of observability (`SHOW VITESS_SHARDS`,
+ *   `SHOW VITESS_MIGRATIONS`) and can even run online DDL, all over the
+ *   connection the application already holds. Nothing extra is needed.
+ * - **vtctld** speaks gRPC and owns the topology. Creating a keyspace and
+ *   applying a VSchema are only possible here, which is why those operations
+ *   need `vitess.vtctldAddr` configured and the `vtctldclient` binary on the
+ *   box.
+ *
+ * Everything in this module is written to prefer vtgate, because that path
+ * needs no extra binary, no extra network hole, and no extra credential. Only
+ * the two genuinely topology-level operations reach for vtctldclient.
+ *
+ * ## Why online DDL is the default
+ *
+ * A `direct` schema change locks the table on every shard at once. On a
+ * sharded keyspace that is an outage, not a migration. Vitess's own online
+ * DDL applies shard by shard, is revertible, and reports progress, so it is
+ * the default here and `direct` has to be asked for explicitly.
+ */
+import type { CloudConfig, DatabaseConfig, EnvironmentType, VitessControlPlaneConfig } from '@ts-cloud/core';
+import type { DbRunResult } from './dashboard-database';
+/** Where `vtctldclient` is installed, matching the pantry CLI's location. */
+export declare const VTCTLDCLIENT_BIN = "/usr/local/bin/vtctldclient";
+/** Pinned default. See `VitessControlPlaneConfig.clientVersion` for why. */
+export declare const DEFAULT_VTCTLDCLIENT_VERSION = "21.0.0";
+export declare function resolveVitessConfig(config: CloudConfig): VitessControlPlaneConfig;
+/**
+ * A keyspace or table identifier accepted by Vitess.
+ *
+ * Deliberately stricter than Vitess itself: these values are interpolated
+ * into a shell command line, so anything outside this set is rejected rather
+ * than escaped. A name that legitimately needs more than this is rare enough
+ * to be worth doing by hand.
+ */
+export declare function isValidKeyspaceName(value: string): boolean;
+/**
+ * A Vitess online-DDL migration UUID, e.g. `a1b2c3d4_1234_5678_9abc_def012345678`.
+ *
+ * Same reasoning as above: the UUID reaches a SQL string literal, and
+ * matching the exact shape is cheaper than reasoning about escaping.
+ */
+export declare function isValidMigrationUuid(value: string): boolean;
+/**
+ * Install `vtctldclient` from its GitHub release.
+ *
+ * Idempotent, and a no-op when the pinned version is already present so a
+ * re-provision does not re-download. Follows the same shape as the pantry
+ * CLI bootstrap: curl the release tarball, extract one binary, mark it
+ * executable.
+ *
+ * Pinned rather than "latest" on purpose. vtctldclient talks gRPC to vtctld
+ * and Vitess supports only a bounded version skew between them, so tracking
+ * latest means the control plane breaks the day the cluster is upgraded, at
+ * a moment nobody is expecting it to.
+ */
+export declare function buildVtctldClientInstallScript(version?: string): string[];
+/** The `vtctldclient --server <addr>` prefix, or null when unconfigured. */
+export declare function vtctldCommand(vitess: VitessControlPlaneConfig): string | null;
+/**
+ * Create a keyspace.
+ *
+ * `sharded` only declares intent: a keyspace becomes genuinely sharded when
+ * its VSchema names a vindex per table, which is the next step. Creating it
+ * sharded with no VSchema yields a keyspace vtgate cannot route to, so the
+ * dashboard flow always pairs the two.
+ */
+export declare function buildCreateKeyspaceScript(vitess: VitessControlPlaneConfig, name: string, options?: {
+    sharded?: boolean;
+}): string[] | null;
+/**
+ * Apply a VSchema document to a keyspace.
+ *
+ * The JSON is written to a temp file rather than passed inline: a VSchema for
+ * a real application is many kilobytes, and shell argument limits are not
+ * where you want to discover that.
+ */
+export declare function buildApplyVSchemaScript(vitess: VitessControlPlaneConfig, keyspace: string, vschemaJson: string): string[] | null;
+/**
+ * Apply a schema change through Vitess online DDL.
+ *
+ * Routed through vtgate rather than vtctldclient so it works on a cluster
+ * where only the query endpoint is reachable. `SET @@ddl_strategy` tells
+ * vtgate to treat the following DDL as an online migration and return a
+ * migration UUID immediately instead of blocking.
+ */
+export declare function buildApplySchemaScript(database: DatabaseConfig | undefined, sql: string, strategy?: 'vitess' | 'direct'): string[];
+export interface VitessMigration {
+    uuid: string;
+    keyspace: string;
+    shard: string;
+    table: string;
+    status: string;
+    strategy: string;
+    added: string;
+    completed: string;
+    progress: string;
+}
+/**
+ * Read online-DDL migration state from vtgate.
+ *
+ * `SHOW VITESS_MIGRATIONS` is the only interface for this. An earlier version
+ * selected from `_vt.schema_migrations` directly, reasoning that an explicit
+ * column list is safer than SHOW's version-dependent layout. The reasoning was
+ * fine and the query was not: `_vt` is a per-tablet sidecar database that
+ * vtgate does not route to, so the statement never ran.
+ *
+ * The layout concern is real, so it is handled rather than avoided: the column
+ * header is kept (no `--skip-column-names`) and mapped by name in
+ * {@link parseMigrations}. That is strictly better than the positional parse
+ * the SELECT would have produced, because it survives upstream adding or
+ * reordering a column.
+ */
+export declare function buildMigrationsScript(database: DatabaseConfig | undefined, keyspace?: string): string[];
+export declare function parseMigrations(output: string): VitessMigration[];
+/** Migrations needing attention: failed, or running long enough to notice. */
+export declare function failedMigrations(migrations: VitessMigration[]): VitessMigration[];
+export declare function runningMigrations(migrations: VitessMigration[]): VitessMigration[];
+export type MigrationAction = 'retry' | 'cancel' | 'cleanup' | 'complete';
+/**
+ * Act on a single online-DDL migration.
+ *
+ * `complete` exists because a migration started with a postponed completion
+ * waits for an explicit cutover; without it the change is applied but never
+ * swapped in, which looks like a migration that finished and did nothing.
+ */
+export declare function buildMigrationActionScript(database: DatabaseConfig | undefined, uuid: string, action: MigrationAction): string[];
+/** Install the pinned `vtctldclient` on the app box. */
+export declare function installVtctldClient(config: CloudConfig, environment: EnvironmentType): Promise<DbRunResult>;
+export declare function createKeyspace(config: CloudConfig, environment: EnvironmentType, name: string, options?: {
+    sharded?: boolean;
+}): Promise<DbRunResult & {
+    keyspace: string;
+}>;
+export declare function applyVSchema(config: CloudConfig, environment: EnvironmentType, keyspace: string, vschemaJson: string): Promise<DbRunResult & {
+    keyspace: string;
+}>;
+export declare function applySchemaChange(config: CloudConfig, environment: EnvironmentType, sql: string): Promise<DbRunResult>;
+export declare function listMigrations(config: CloudConfig, environment: EnvironmentType, keyspace?: string): Promise<DbRunResult & {
+    migrations: VitessMigration[];
+    failed: VitessMigration[];
+    running: VitessMigration[];
+}>;
+export declare function actOnMigration(config: CloudConfig, environment: EnvironmentType, uuid: string, action: MigrationAction): Promise<DbRunResult & {
+    uuid: string;
+}>;

package/dist/deploy/dashboard-vitess.test.d.ts

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

package/dist/deploy/index.js

@@ -30,7 +30,7 @@ import {
   synchronizeDashboardUsers,
   trackDashboardOperation,
   verifyStaticApiOrigin
-} from "../chunk-y5wrqyyz.js";
+} from "../chunk-3d4204h1.js";
 import {
   deleteStaticSite,
   deployStaticSite,
@@ -70,7 +70,7 @@ import {
   siteInstallBase,
   validateDeploymentConfig,
   verifyAddressRecord
-} from "../chunk-fbwcv2vf.js";
+} from "../chunk-xp3txtg9.js";
 import"../chunk-hmehkeqx.js";
 import"../chunk-7m60qnc8.js";
 import"../chunk-4cjrg98a.js";

package/dist/drivers/hetzner/client.d.ts

@@ -65,9 +65,11 @@ export interface HetznerServer {
     public_net: {
         ipv4?: {
             ip: string;
+            id?: number;
         };
         ipv6?: {
             ip: string;
+            id?: number;
         };
     };
     private_net?: Array<{
@@ -113,6 +115,39 @@ export interface HetznerSshKey {
     public_key: string;
     labels?: Record<string, string>;
 }
+export interface HetznerImage {
+    id: number;
+    type: string;
+    status: string;
+    name?: string | null;
+    description?: string;
+    /** Size of the disk the image was taken from, in GB. */
+    disk_size?: number;
+    /** Size of the image itself once stored, in GB. */
+    image_size?: number | null;
+    architecture?: string;
+    created_from?: {
+        id: number;
+        name: string;
+    };
+    labels?: Record<string, string>;
+}
+export interface HetznerPrimaryIp {
+    id: number;
+    ip: string;
+    type: 'ipv4' | 'ipv6';
+    name?: string;
+    assignee_id?: number | null;
+    assignee_type?: string;
+    auto_delete?: boolean;
+    /** Current API shape omits this; retained for recorded fixtures. */
+    datacenter?: {
+        name: string;
+        location?: {
+            name: string;
+        };
+    };
+}
 export interface HetznerAction {
     id: number;
     status: 'running' | 'success' | 'error';
@@ -261,6 +296,67 @@ export declare class HetznerClient {
     shutdownServer(serverId: number): Promise<HetznerAction>;
     powerOnServer(serverId: number): Promise<HetznerAction>;
     changeServerType(serverId: number, serverType: string, upgradeDisk: boolean): Promise<HetznerAction>;
+    /**
+     * Power a server off at the virtual power button.
+     *
+     * Distinct from {@link shutdownServer}, which asks the guest to shut down
+     * cleanly via ACPI and does nothing at all when the guest ignores it. Every
+     * operation that requires a stopped server — rebuild, primary-IP moves —
+     * needs the server to actually reach `off`, so callers shut down first and
+     * fall back to this.
+     */
+    powerOffServer(serverId: number): Promise<HetznerAction>;
+    /**
+     * Stop a server, preferring a clean guest shutdown.
+     *
+     * A guest that has not stopped within the grace period is powered off at the
+     * button: waiting forever on an unresponsive box is worse than a hard stop
+     * on a machine whose disk is about to be replaced anyway.
+     */
+    stopServer(serverId: number, options?: {
+        gracefulWaitMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<void>;
+    renameServer(serverId: number, name: string): Promise<HetznerServer>;
+    listImages(options?: {
+        type?: string;
+    }): Promise<HetznerImage[]>;
+    getImage(id: number): Promise<HetznerImage>;
+    /**
+     * Snapshot a server's disk into a reusable image.
+     *
+     * Hetzner will snapshot a running server, but the result is a crash-consistent
+     * copy: whatever was mid-write is captured mid-write. For anything holding a
+     * database open that is a restore-time problem rather than a snapshot-time
+     * one, so callers that care stop the server first.
+     */
+    createImage(serverId: number, options: {
+        description: string;
+        type?: 'snapshot' | 'backup';
+        labels?: Record<string, string>;
+    }): Promise<{
+        image: HetznerImage;
+        action: HetznerAction;
+    }>;
+    deleteImage(imageId: number): Promise<void>;
+    /**
+     * Replace a server's disk with an image.
+     *
+     * Destructive and not undoable: everything on the target's disk is gone the
+     * moment this succeeds. The image's `disk_size` must be no larger than the
+     * target server type's disk, which is the asymmetry that decides which way a
+     * migration between two differently sized servers can run.
+     */
+    rebuildServer(serverId: number, image: number | string): Promise<HetznerAction>;
+    listPrimaryIps(): Promise<HetznerPrimaryIp[]>;
+    /**
+     * Detach a primary IP from whatever server currently holds it.
+     *
+     * The server has to be off. Hetzner rejects this outright on a running
+     * server rather than dropping its address underneath it.
+     */
+    unassignPrimaryIp(ipId: number): Promise<HetznerAction>;
+    assignPrimaryIp(ipId: number, serverId: number): Promise<HetznerAction>;
     waitForAction(actionId: number, options?: {
         pollIntervalMs?: number;
         maxWaitMs?: number;

package/dist/drivers/hetzner/migrate-server.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Moving a workload from one server onto another.
+ *
+ * This is the half of a role swap that {@link ./role-swap} deliberately refuses
+ * to pretend it does. Exchanging two servers' primary IPs points each address
+ * at the other's disk; unless the workloads moved first, every address now
+ * serves the wrong application.
+ *
+ * There are two ways to move a workload, and which one is available is not a
+ * matter of taste:
+ *
+ *   - **Snapshot and rebuild.** Hetzner images a server's disk and writes it
+ *     over another server's. It carries everything - every service, every unit
+ *     file, the certificates, the databases, the things nobody remembered were
+ *     installed. For a box that accumulated twenty services over a year, this
+ *     is the only honest option, because a reinstall reproduces what you
+ *     documented rather than what you have.
+ *
+ *   - **Redeploy and restore.** Deploy the application onto the target, then
+ *     restore its data. Reproducible and auditable, but it only moves what the
+ *     deployment knows about.
+ *
+ * The choice is forced by one asymmetry: **an image carries the disk size of
+ * the server it came from**, and a rebuild is refused unless the target's disk
+ * is at least that large. So a small server images onto a large one, and a
+ * large server does not image onto a small one - regardless of how little data
+ * it actually holds. An 11GB workload on a 160GB disk cannot be rebuilt onto an
+ * 80GB disk. That is the rule {@link planServerMigration} exists to apply
+ * before anything is destroyed, rather than after.
+ *
+ * Two further facts, learned the expensive way, are encoded here:
+ *
+ *   - A rebuild is **irreversible the instant it succeeds**. The target's disk
+ *     is gone. Anything on it that has not been captured elsewhere is gone with
+ *     it, so the plan refuses to sequence a rebuild before its target's backup.
+ *   - Rebuilding onto a **larger** disk does not grow the filesystem. The
+ *     partition still reports the old size and the extra space is unreachable
+ *     until `growpart` and the filesystem's own resize have run.
+ */
+export type MigrationMethod = 'snapshot-rebuild' | 'redeploy-restore';
+export interface AttachedVolume {
+    id: number;
+    name: string;
+    sizeGb?: number;
+}
+export interface MigrateServer {
+    id: number;
+    name: string;
+    serverType: string;
+    /** The server type's disk, in GB. An image taken here carries this size. */
+    diskSizeGb: number;
+    /** Bytes actually in use, so a move onto a smaller disk is refused early. */
+    usedGb: number;
+    architecture?: string;
+    /**
+     * Block-storage volumes attached to this server.
+     *
+     * These do NOT travel with a snapshot. A volume is a separate device that
+     * happens to be attached, so imaging the machine copies the system disk and
+     * silently leaves the volume behind on the old server - along with whatever
+     * lived on it. The migrated box then boots with an fstab entry for a device
+     * that is not there, and whatever depended on that mount stays down while
+     * every other check looks healthy.
+     */
+    attachedVolumes?: AttachedVolume[];
+}
+export type MigrationStepKind = 'back-up' | 'snapshot' | 'stop' | 'rebuild' | 'power-on' | 'grow-filesystem' | 'move-volume' | 'deploy' | 'restore' | 'verify';
+export interface MigrationStep {
+    kind: MigrationStepKind;
+    /** The server the step acts on. */
+    serverId: number;
+    description: string;
+    /** True for steps that destroy data if the preceding ones were skipped. */
+    destructive?: boolean;
+}
+export interface MigrationPlan {
+    ok: boolean;
+    method: MigrationMethod | null;
+    blockers: string[];
+    /** Why this method rather than the other, for the operator to sanity-check. */
+    rationale: string;
+    steps: MigrationStep[];
+}
+/**
+ * Whether an image of `source` can be written onto `target`.
+ *
+ * Compares disk *sizes*, not disk *usage*. This is the constraint people get
+ * wrong, because it is counter-intuitive: a nearly empty 160GB server cannot be
+ * rebuilt onto an 80GB one. Hetzner is comparing the geometry the image was
+ * captured with, and it has no idea how much of it you were using.
+ */
+export declare function canRebuildFrom(source: Pick<MigrateServer, 'diskSizeGb'>, target: Pick<MigrateServer, 'diskSizeGb'>): boolean;
+/**
+ * Whether the workload's actual bytes fit the target, with room to restore.
+ *
+ * A disk that is exactly full fails on the next write, and a restore needs room
+ * for the archive as well as its expansion.
+ */
+export declare function dataFits(usedGb: number, targetDiskGb: number, marginRatio?: number): boolean;
+/** Whether a rebuild onto this target leaves unclaimed disk behind. */
+export declare function needsFilesystemGrowth(source: Pick<MigrateServer, 'diskSizeGb'>, target: Pick<MigrateServer, 'diskSizeGb'>): boolean;
+/**
+ * The ordered steps to move `source`'s workload onto `target`.
+ *
+ * `preferredMethod` is a request, not an instruction: asking for a snapshot
+ * rebuild that the disk geometry forbids returns the redeploy path with the
+ * reason attached, rather than a plan that fails partway.
+ */
+export declare function planServerMigration(source: MigrateServer, target: MigrateServer, options?: {
+    preferredMethod?: MigrationMethod;
+}): MigrationPlan;
+/**
+ * The commands that claim disk a rebuild left unreachable.
+ *
+ * Split out because the order is load-bearing and easy to get backwards:
+ * `growpart` enlarges the partition, and only then can the filesystem be told
+ * to fill it. Running the filesystem resize first appears to succeed and
+ * changes nothing.
+ */
+export declare function growFilesystemCommands(options?: {
+    device?: string;
+    partition?: number;
+    filesystem?: 'ext4' | 'xfs';
+}): string[];

package/dist/drivers/hetzner/migrate-server.test.d.ts

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

package/dist/drivers/hetzner/role-swap.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Swapping the roles of two servers.
+ *
+ * The situation this exists for: a server type is no longer obtainable. Hetzner
+ * retires older lines, and `available_for_migration` goes false everywhere, so
+ * a `change_type` onto that type can never succeed again. If you already own an
+ * instance of it, that instance is the only one you will ever have — and the
+ * right move is to put your heaviest workload on it rather than to keep trying
+ * to buy another.
+ *
+ * A resize cannot do this. What can is exchanging the two servers' primary IPs,
+ * so each address keeps pointing at the workload that answers on it, with no
+ * DNS change and no waiting on propagation.
+ *
+ * Two constraints decide whether it is possible at all, and both are cheap to
+ * check before anything is powered off:
+ *
+ *   - A primary IP belongs to a datacenter. Two servers in different
+ *     datacenters cannot exchange addresses, and finding that out halfway
+ *     through leaves both boxes down with their addresses detached.
+ *   - Data has to fit. Moving a workload onto a smaller disk fails at restore
+ *     time, which is the worst moment to discover it.
+ *
+ * The planning is pure so those rules can be tested without an account.
+ *
+ * IMPORTANT, and not yet handled here: exchanging addresses does not move the
+ * workload. Each disk keeps the software and data it already had, so a swap on
+ * its own points every address at the wrong application. A complete role swap
+ * is three phases - deploy each workload onto its new host, restore its data,
+ * and only then exchange the addresses - and this module plans the third.
+ * `planRoleSwap` deliberately refuses to look like the whole job.
+ */
+export interface SwapServer {
+    id: number;
+    name: string;
+    /**
+     * Where the server sits, for the purpose of deciding whether an address can
+     * move to it. Derive it with {@link placementOf} rather than reading a field
+     * off the API response, and see that function for why. Null when unknown,
+     * which is a blocker rather than a pass.
+     */
+    placement: string | null;
+    serverType: string;
+    diskSizeGb: number;
+    /** Bytes actually in use, so a move onto a smaller disk can be refused early. */
+    usedGb: number;
+    primaryIpId: number | null;
+    primaryIp: string | null;
+}
+export type SwapStepKind = 'power-off' | 'unassign-ip' | 'assign-ip' | 'power-on' | 'rename';
+export interface SwapStep {
+    kind: SwapStepKind;
+    serverId: number;
+    /** For an IP step, the address being moved. */
+    ipId?: number;
+    /** For a rename, the name to take. */
+    name?: string;
+    description: string;
+}
+export interface SwapPlan {
+    ok: boolean;
+    /** Why the swap cannot proceed. Empty when it can. */
+    blockers: string[];
+    steps: SwapStep[];
+}
+/**
+ * Whether a workload fits on the other server's disk.
+ *
+ * A margin is kept rather than comparing raw numbers: a disk that is exactly
+ * full is a disk that fails on the next write, and a restore needs room for
+ * both the archive and its expansion.
+ */
+export declare function fits(usedGb: number, targetDiskGb: number, marginRatio?: number): boolean;
+/**
+ * Where a server sits, from whichever field the API still reports.
+ *
+ * Primary IPs are bound at datacenter granularity, so `datacenter` is the
+ * field this wants. The API has stopped returning it — `datacenter` is now
+ * null on both the server and the primary IP, leaving only `location`.
+ *
+ * Reading the missing field directly is worse than useless: two servers in
+ * different datacenters both report `undefined`, `undefined === undefined`,
+ * and the guard that exists to stop a cross-datacenter swap waves it through.
+ * The failure then lands halfway, with both boxes off and their addresses
+ * detached, which is the exact outcome the check was written to prevent.
+ *
+ * So: prefer the datacenter when present, fall back to the location, and
+ * return null when neither is known so the caller can refuse. Location is a
+ * sound proxy today because every Hetzner location contains exactly one
+ * datacenter; if that ever stops being true, this returns the coarser answer
+ * and the assign call is the backstop.
+ */
+export declare function placementOf(server: {
+    datacenter?: {
+        name?: string;
+    } | null;
+    location?: {
+        name?: string;
+    } | null;
+}): string | null;
+/**
+ * The parking name one server wears while the other takes its name.
+ *
+ * Hetzner rejects a duplicate server name, so the two cannot cross directly.
+ */
+export declare function swapTempName(name: string): string;
+/**
+ * The ordered steps to exchange two servers' addresses and names.
+ *
+ * Both are powered off before either address moves. Hetzner refuses to detach a
+ * primary IP from a running server, and doing them one at a time would leave
+ * the first server up with no address — reachable by nobody and, worse, still
+ * accepting work it can no longer be reached about.
+ */
+export declare function planRoleSwap(a: SwapServer, b: SwapServer): SwapPlan;
+/**
+ * Whether a type can still be migrated onto in a datacenter.
+ *
+ * `available` answers a different question — whether a NEW server of that type
+ * can be created — and reading it instead is why a doomed `change_type` looks
+ * like bad luck rather than a retired type. `available_for_migration` is the
+ * one `change_type` consults.
+ */
+export declare function canMigrateTo(datacenter: {
+    server_types?: {
+        available_for_migration?: number[];
+    };
+}, serverTypeId: number): boolean;
+/**
+ * The advice to print when a resize is impossible.
+ *
+ * A type that is unobtainable everywhere is not a capacity blip to retry
+ * through; it is retired, and the instance you hold is the last one you get.
+ */
+export declare function resizeAdvice(input: {
+    targetType: string;
+    migratableAnywhere: boolean;
+    ownedInstances: number;
+}): string;

package/dist/drivers/hetzner/role-swap.test.d.ts

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