@stacksjs/ts-cloud 0.7.92 → 0.7.94

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 {};

package/dist/drivers/index.js

@@ -68,7 +68,7 @@ import {
   waitForSsh,
   wrapCloudInitUserData,
   writeResizeCheckpoint
-} from "../chunk-fbwcv2vf.js";
+} from "../chunk-bs3jfnzp.js";
 import"../chunk-hmehkeqx.js";
 import"../chunk-7m60qnc8.js";
 import"../chunk-4cjrg98a.js";

package/dist/drivers/shared/db-provision.d.ts

@@ -15,6 +15,10 @@ import type { ComputeServicesConfig, DatabaseConfig } from '@ts-cloud/core';
  * True when the database is co-located with the box (the managed-services
  * engine): no host configured, or an explicit loopback host. Anything else is
  * an external/managed database reached over TCP.
+ *
+ * An always-external engine is never local regardless of host — pointing one
+ * at 127.0.0.1 means a tunnel or a local proxy, not an engine this box
+ * installed and can administer over a unix socket.
  */
 export declare function isLocalDatabase(database: DatabaseConfig | undefined): boolean;
 /**

package/dist/drivers/shared/deploy-script.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Shared deploy script helpers for Forge-style compute deploys.
+ *
+ * Both server-app and server-static sites deploy with **zero downtime** the same
+ * way PHP/Laravel sites do (Envoyer-style): the artifact is unpacked into a fresh
+ * `releases/<id>` directory, shared paths (`.env`) are symlinked in, and the
+ * `current` symlink is repointed atomically (`mv -Tf`). The gateway serves the
+ * site from `<base>/current`, so a static swap is instantaneous (no window where
+ * the docroot is empty), and an app restart re-execs against the already-staged
+ * release (no window where the code is half-replaced). Old releases are kept for
+ * instant rollback. See {@link import('./releases')}.
+ */
+import type { SharedPathEntry } from '@ts-cloud/core';
 /**
  * Translate a `start` command (e.g. "bun run server.ts") into an absolute
  * systemd ExecStart by swapping the leading runtime word for its absolute path.
@@ -30,8 +43,11 @@ export interface BuildSiteDeployScriptOptions {
      * survive a deploy. `.env` is always shared; anything the app WRITES and must
      * keep (a state directory, a database file) has to be listed here or the next
      * release silently starts from empty.
+     *
+     * A `SharedPathSpec` entry points somewhere other than this site's own
+     * `shared/` — how several sites of one project share one file.
      */
-    sharedPaths?: readonly string[];
+    sharedPaths?: readonly SharedPathEntry[];
     /**
      * True zero-downtime cutover for ported sites: the new release runs as its
      * own systemd instance (`<slug>-<site>@<releaseId>`) that binds the same

package/dist/drivers/shared/package-manager.d.ts

@@ -27,6 +27,8 @@ export declare const PANTRY_PACKAGES: {
     readonly mysql: 'mysql.com';
     readonly mariadb: 'mariadb.com/server';
     readonly postgres: 'postgresql.org';
+    readonly vitess: 'vitess.io';
+    readonly etcd: 'etcd.io';
     readonly redis: 'redis.io';
     readonly memcached: 'memcached.org';
     readonly meilisearch: 'meilisearch.com';

package/dist/drivers/shared/releases.d.ts

@@ -12,6 +12,7 @@
  *   $CREATE_RELEASE   → {@link buildEnsureReleaseLayout} + git clone + {@link buildLinkSharedPaths}
  *   $ACTIVATE_RELEASE → {@link buildActivateRelease} (+ {@link buildPruneReleases})
  */
+import type { SharedPathEntry } from '@ts-cloud/core';
 /** Paths that are always shared across releases (Forge shares `.env` implicitly). */
 export declare const DEFAULT_SHARED_PATHS: readonly string[];
 /** Default number of past releases to retain for rollback. */
@@ -24,6 +25,13 @@ export declare function deployMetaDir(base: string): string;
 export declare function deployHistoryPath(base: string): string;
 /** Per-deploy output log path for a release. */
 export declare function deployLogPath(base: string, releaseId: string): string;
+/**
+ * Manifest of the shared paths the last deploy declared, written on every deploy
+ * so a rollback can relink them into an older release without knowing the site's
+ * config. Lives beside the deploy history (outside `releases/`, so pruning a
+ * release never takes it).
+ */
+export declare function sharedPathsManifestPath(base: string): string;
 export interface ReleasePaths {
     /** Site base directory (`/var/www/<site>`). */
     base: string;
@@ -38,11 +46,25 @@ export interface ReleasePaths {
 }
 /** Resolve the standard release layout paths for a site + release id. */
 export declare function releasePaths(base: string, releaseId: string): ReleasePaths;
+/** The release-relative path an entry links, whichever form it takes. */
+export declare function sharedPathOf(entry: SharedPathEntry): string;
+/**
+ * One entry per release-relative path, last declaration winning — so a site
+ * that spells out `{ path: '.env', target: … }` overrides the implicit `.env`
+ * rather than fighting it. A plain `new Set` cannot do this: two specs for the
+ * same path are distinct objects.
+ */
+export declare function dedupeSharedPaths(entries: readonly SharedPathEntry[]): SharedPathEntry[];
 /**
  * Ensure the releases/ and shared/ skeleton exist, including the Laravel
  * `storage` tree and an empty shared `.env` so symlinks never dangle.
+ *
+ * Also adopts any pre-existing live copy of a newly-shared path (see
+ * {@link buildAdoptSharedPathFn}) and records the shared-path list in
+ * {@link sharedPathsManifestPath}, so {@link buildRollbackScript} can relink an
+ * older release at the same shared state.
  */
-export declare function buildEnsureReleaseLayout(paths: ReleasePaths, sharedPaths?: readonly string[]): string[];
+export declare function buildEnsureReleaseLayout(paths: ReleasePaths, sharedPaths?: readonly SharedPathEntry[]): string[];
 /**
  * Take the site's deploy lock for the rest of the script.
  *
@@ -101,7 +123,18 @@ export declare function buildPromoteStagedRelease(paths: ReleasePaths): string[]
  * Symlink every shared path from `shared/` into the freshly checked-out release,
  * replacing whatever the checkout shipped (e.g. the repo's empty `storage`).
  */
-export declare function buildLinkSharedPaths(paths: ReleasePaths, sharedPaths?: readonly string[]): string[];
+export declare function buildLinkSharedPaths(paths: ReleasePaths, sharedPaths?: readonly SharedPathEntry[]): string[];
+/**
+ * The same links as {@link buildLinkSharedPaths}, but for a release that is
+ * already on disk and a shared-path list read from the box's manifest rather
+ * than from config. `releaseExpr` is a shell expression for the release dir.
+ *
+ * Used by rollback: a release cut before a path became shared still holds its
+ * own real copy there, so activating it would quietly swap the live state (the
+ * database) for that release's stale snapshot. A no-op on a box with no
+ * manifest — one that has never deployed a shared path.
+ */
+export declare function buildRelinkSharedPaths(paths: ReleasePaths, releaseExpr: string): string[];
 /**
  * Atomically repoint `current` at the new release. Writes a temp symlink and
  * `mv -T`s it over `current` so there is no window where `current` is missing.
@@ -114,6 +147,12 @@ export declare function buildActivateRelease(paths: ReleasePaths): string[];
  * -T`), and a no-op-safe guard fails loudly if the target is missing rather than
  * leaving `current` dangling.
  *
+ * Before the flip, every shared path recorded on the box is relinked into the
+ * target release ({@link buildRelinkSharedPaths}) so a rollback moves the CODE
+ * back without moving the DATA back — a release cut before a path became shared
+ * still carries its own copy, and going live with it would silently swap the
+ * database for a stale snapshot.
+ *
  * With `unitBase` set (e.g. `myapp-api`), the script also swaps the running
  * systemd release instance for sites deployed zero-downtime style (templated
  * `<unitBase>@<releaseId>` units pinned to their release dirs): it starts the

package/dist/drivers/shared/vitess-provision.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Vitess provisioning.
+ *
+ * Two modes, because "run Vitess" means two very different things depending on
+ * why you are doing it:
+ *
+ * - **`combo`** runs the entire stack inside a single `vtcombo` process with
+ *   an in-memory topology. It is the right answer for development and CI: one
+ *   unit, one port, nothing to bootstrap, and it goes away cleanly. It is not
+ *   durable and must never be used for real data.
+ * - **`cluster`** runs the real daemons (etcd, vtctld, vttablet beside a
+ *   managed mysqld, vtgate) as separate systemd units on the box, with the
+ *   ordering and topology bootstrap they require.
+ *
+ * ## What cluster mode is and is not
+ *
+ * This provisions a **single-box** Vitess: every component on one machine.
+ * That is a genuine deployment for staging, small production, and any case
+ * where you want Vitess's online DDL and query routing without yet needing
+ * horizontal scale. It is deliberately NOT a multi-box sharded cluster:
+ * spreading tablets across machines means per-shard placement, cross-box
+ * topology, and reparent policy, which are decisions an operator has to make
+ * rather than defaults a provisioner should invent.
+ *
+ * So a sharded keyspace here has its shards' tablets on one host. That gives
+ * you the routing and DDL semantics of Vitess and none of the fault
+ * tolerance, which is the honest trade and is stated in the config docs.
+ *
+ * ## Ordering is the whole problem
+ *
+ * Vitess daemons are not independent. vtctld and vttablet both need the
+ * topology store; vttablet also needs its mysqld; vtgate needs topology to
+ * route. Starting them in the wrong order does not fail cleanly - components
+ * retry, so a mis-ordered stack comes up "green" and then behaves oddly under
+ * load. The units below encode the dependency graph in `After=`/`Requires=`
+ * so systemd enforces it rather than relying on retry luck.
+ */
+import type { VitessKeyspaceConfig, VitessServiceConfig } from '@ts-cloud/core';
+import type { PantrySpec } from './package-manager';
+/** Where pantry exposes installed binaries. */
+export declare const PANTRY_BIN: string;
+/** vtgate's MySQL-protocol port. Applications connect here. */
+export declare const VTGATE_MYSQL_PORT = 15306;
+/** vtgate's gRPC port. */
+export declare const VTGATE_GRPC_PORT = 15991;
+/** vtctld's gRPC port. `vtctldclient --server` targets this. */
+export declare const VTCTLD_GRPC_PORT = 15999;
+/** vttablet's gRPC port. */
+export declare const VTTABLET_GRPC_PORT = 16101;
+/** Where etcd listens for the topology store. */
+export declare const ETCD_CLIENT_PORT = 2379;
+/** Root directory for Vitess state on the box. */
+export declare const VITESS_ROOT = "/var/lib/vitess";
+/**
+ * Tablet UID for the single-box tablet.
+ *
+ * Shared by mysqlctld and vttablet on purpose: they must agree, because
+ * Vitess derives the tablet's working directory (and therefore its mysqld
+ * socket) from `$VTDATAROOT/vt_<uid>`. Two different values silently give
+ * the tablet a mysqld it cannot find.
+ */
+export declare const VITESS_TABLET_UID = 100;
+/** Re-exported so callers of the provisioner need only one import. */
+export type { VitessKeyspaceConfig, VitessServiceConfig };
+export declare function enabled(value: boolean | VitessServiceConfig | undefined): value is true | VitessServiceConfig;
+/** Packages a Vitess box needs, given the mode and whether etcd is external. */
+export declare function vitessPackages(config: VitessServiceConfig): PantrySpec[];
+/**
+ * The unprivileged account every Vitess daemon runs as.
+ *
+ * Not a hardening nicety: Vitess refuses to start as root outright
+ * ("running this as root makes no sense" from servenv.Init), so a unit with
+ * no `User=` crash-loops immediately on every daemon.
+ */
+export declare const VITESS_USER = "vitess";
+/** Directory holding the generated launcher scripts. */
+export declare const VITESS_LIB = "/usr/local/lib/vitess";
+/** The launcher scripts recorded so far, for inspection and testing. */
+export declare function buildLaunchers(): Map<string, string>;
+/**
+ * The single-process development stack.
+ *
+ * `vtcombo` runs vtgate, vttablet, and vtctld together against an in-memory
+ * topology, so there is nothing to order and nothing to bootstrap. The
+ * keyspaces are declared on the command line and exist from the first start.
+ */
+export declare function buildVtcomboUnit(config: VitessServiceConfig): string;
+/** etcd, the topology store every real Vitess component reads. */
+export declare function buildEtcdUnit(): string;
+/** vtctld: the control plane `vtctldclient` talks to. */
+export declare function buildVtctldUnit(config: VitessServiceConfig): string;
+/** vttablet: manages one mysqld and serves its shard. */
+export declare function buildVttabletUnit(config: VitessServiceConfig, keyspace: string, shard: string): string;
+/** mysqlctld: the managed mysqld a tablet owns. */
+export declare function buildMysqlctldUnit(config: VitessServiceConfig): string;
+/** Where the generated vtgate credentials live. */
+export declare const VITESS_AUTH_FILE = "/etc/vitess/auth.json";
+/**
+ * vtgate's static credentials file.
+ *
+ * vtgate defaults to `--mysql-auth-server-impl static` and exits with "no
+ * AuthServer name static registered" when no credentials are supplied, so
+ * this is required, not optional. The alternative Vitess offers is
+ * `none`, which would leave an unauthenticated MySQL endpoint - acceptable
+ * only for the loopback-bound combo stack, never for a cluster.
+ */
+export declare function buildVitessAuthFileScript(config: VitessServiceConfig): string[];
+/** vtgate: the query router applications connect to. */
+export declare function buildVtgateUnit(config: VitessServiceConfig): string;
+/**
+ * Bootstrap the topology: register the cell, then create each keyspace.
+ *
+ * Idempotent. `AddCellInfo` and `CreateKeyspace` both fail when the object
+ * already exists, and a re-provision must not turn that into a failed deploy,
+ * so each is guarded on the corresponding read.
+ */
+export declare function buildVitessBootstrapScript(config: VitessServiceConfig): string[];
+/**
+ * Wait until vtgate actually answers on its MySQL port.
+ *
+ * The deploy should fail here rather than later: a box that finished
+ * provisioning with a vtgate that never came up will accept a deploy and then
+ * fail every request, which is much harder to attribute.
+ */
+export declare function buildVitessHealthCheck(config: VitessServiceConfig): string[];
+/**
+ * Full provisioning script for a Vitess box.
+ *
+ * Order matters and is deliberate: install, write every unit, reload systemd
+ * ONCE, then start in dependency order, then bootstrap, then health-gate.
+ * Reloading per-unit would make systemd act on a half-written stack.
+ */
+export declare function buildVitessProvisionScript(value: boolean | VitessServiceConfig | undefined): string[];

package/dist/drivers/shared/vitess-provision.test.d.ts

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

package/dist/index.d.ts

@@ -33,7 +33,7 @@ export { deployStaticSite, deployStaticSiteFull, uploadStaticFiles, invalidateCa
 export { collectServerDnsDomains, hostAcceptsIpv6, IPV6_EXCLUDED_HOST_LABELS, normalizePublicIpv6, reconcileAddressRecords, removeStaleServerAddressRecords, verifyAddressRecord, } from './deploy/server-dns';
 export type { AddressRecordReport } from './deploy/server-dns';
 export type { EnsureDashboardLogger, ResolvedDashboardAuth, StaticSiteConfig, DeployResult, UploadOptions, ExternalDnsStaticSiteConfig, ExternalDnsDeployResult, DeploySiteConfig, DeploySiteResult, StaticSiteDnsProvider, SiteDeployKind, DeploymentValidationResult, BuildImageOptions, BuiltImage, CodeSource, DeployServerlessOptions, ResolvedContext, } from './deploy';
-export { createCloudDriver, CloudDriverFactory, cloudDrivers, AwsDriver, HetznerDriver, HetznerClient, resolveHetznerApiToken, normalizeSshPublicKey, ensureFirewall, ensureServer, ensureSshKey, serverPublicIpv4, sshExec, sshExecOrThrow, scpUpload, waitForSsh, waitForCloudInit, buildSshArgs, generateUbuntuAppCloudInit, wrapCloudInitUserData, buildHostCleanupScript, buildSiteDeployScript, buildStaticSiteDeployScript, resolveExecStart, deployAllComputeSites, deploySiteRelease, } from './drivers';
+export { createCloudDriver, CloudDriverFactory, cloudDrivers, AwsDriver, HetznerDriver, HetznerClient, resolveHetznerApiToken, normalizeSshPublicKey, ensureFirewall, ensureServer, ensureSshKey, serverPublicIpv4, sshExec, sshExecOrThrow, scpUpload, waitForSsh, waitForCloudInit, buildSshArgs, generateUbuntuAppCloudInit, wrapCloudInitUserData, buildHostCleanupScript, buildSiteDeployScript, buildStaticSiteDeployScript, resolveExecStart, deployAllComputeSites, deploySiteRelease, reloadRpxGateway, renewRpxCertificates, } from './drivers';
 export type { CreateCloudDriverOptions } from './drivers/factory';
 export { dashboardActions, resolveDashboardAction, sanitizeCloudConfig, startLocalDashboardServer, } from './deploy/local-dashboard-server';
 export type { DashboardAction, LocalDashboardServer, LocalDashboardServerOptions, } from './deploy/local-dashboard-server';

package/dist/index.js

@@ -283,7 +283,7 @@ import {
   volumeCapabilities,
   webhookEndpoint,
   zeroCapacity
-} from "./chunk-29fwqkb7.js";
+} from "./chunk-0htae1c2.js";
 import {
   deleteStaticSite,
   deployStaticSite,
@@ -387,7 +387,9 @@ import {
   normalizePublicIpv6,
   normalizeSshPublicKey,
   reconcileAddressRecords,
+  reloadRpxGateway,
   removeStaleServerAddressRecords,
+  renewRpxCertificates,
   resolveDashboardAuth,
   resolveExecStart,
   resolveHetznerApiToken,
@@ -403,7 +405,7 @@ import {
   waitForCloudInit,
   waitForSsh,
   wrapCloudInitUserData
-} from "./chunk-fbwcv2vf.js";
+} from "./chunk-bs3jfnzp.js";
 import {
   ABTestManager,
   AI,
@@ -5254,11 +5256,13 @@ export {
   requiresReplacement,
   requestHash,
   replicaManager,
+  renewRpxCertificates,
   renderServerCron,
   renderComposeTemplate,
   removeStaleServerAddressRecords,
   removeSourceWebhook,
   remapKey,
+  reloadRpxGateway,
   releaseTrafficPlan,
   releaseStrategyCapabilities,
   regionPairManager,

package/dist/telemetry/store.d.ts

@@ -31,4 +31,5 @@ export declare class TelemetryStore {
         compacted: number;
         rollups: number;
     };
+    private rebuildStatusRollups;
 }