@stacksjs/ts-cloud 0.2.24 → 0.2.26

package/dist/drivers/hetzner/cloud-init.d.ts

@@ -9,6 +9,13 @@ export interface UbuntuBootstrapOptions {
     systemPackages?: string[];
     database?: 'sqlite' | 'mysql' | 'postgres';
     caddyfile?: string;
+    /**
+     * Shell commands that install + start the rpx reverse-proxy gateway, built by
+     * {@link import('../shared/rpx-gateway').buildRpxProvisionScript}. Appended
+     * after the runtime is installed so `bun add -g @stacksjs/rpx` works. Mutually
+     * exclusive with `caddyfile` (the box runs one gateway).
+     */
+    rpxProvision?: string[];
 }
 export declare function generateUbuntuAppCloudInit(options?: UbuntuBootstrapOptions): string;
 /**

package/dist/drivers/index.d.ts

@@ -4,4 +4,8 @@ export { HetznerDriver } from './hetzner/driver';
 export { HetznerClient, resolveHetznerApiToken } from './hetzner/client';
 export { generateUbuntuAppCloudInit, wrapCloudInitUserData } from './hetzner/cloud-init';
 export { buildAwsArtifactFetch, buildLocalArtifactFetch, buildSiteDeployScript, buildStaticSiteDeployScript, resolveExecStart, } from './shared/deploy-script';
-export { deployAllComputeSites, deploySiteRelease } from './shared/compute-deploy';
+export { deployAllComputeSites, deploySiteRelease, reloadRpxGateway } from './shared/compute-deploy';
+export { buildRpxConfig, buildRpxProvisionScript, deriveRouteId, normalizeRoutePath, renderRpxLauncher, DEFAULT_RPX_CERTS_DIR, RPX_DIR, RPX_LAUNCHER_PATH, RPX_SERVICE_NAME, } from './shared/rpx-gateway';
+export type { BuildRpxConfigOptions, BuildRpxProvisionOptions, RpxGatewayConfig, RpxRoute, } from './shared/rpx-gateway';
+export { buildCloudFrontOriginConfig, MANAGED_CACHE_POLICY_DISABLED, MANAGED_CACHE_POLICY_OPTIMIZED, MANAGED_ORIGIN_REQUEST_POLICY_ALL_VIEWER, } from './shared/cloudfront-origin';
+export type { BuildCloudFrontOriginOptions, OriginFrontedBehavior, } from './shared/cloudfront-origin';

package/dist/drivers/shared/cloudfront-origin.d.ts

@@ -0,0 +1,61 @@
+/**
+ * CloudFront-in-front-of-a-custom-origin distribution config.
+ *
+ * When a self-hosted gateway (rpx on a Hetzner box) is the origin behind
+ * CloudFront, the distribution needs a very specific shape — and several
+ * non-obvious settings will silently break it if wrong. This builder encodes
+ * the working configuration so it can't regress:
+ *
+ *  - **One custom origin**, the dedicated origin host (e.g. `origin.example.com`),
+ *    HTTPS-only. It must NOT be a public alias (that loops) and can't be a bare IP.
+ *  - **Host forwarding** via the AWS-managed `AllViewer` origin-request policy, so
+ *    the box receives `Host: <alias>` and routes by it (not by the origin host).
+ *  - **No `DefaultRootObject`.** Setting it to `index.html` makes CloudFront fetch
+ *    `/index.html`, which a gateway with clean-URLs 301-redirects back to `/` — an
+ *    infinite loop. Leave it empty and let the origin serve `/`.
+ *  - **No CloudFront Functions / Lambda@Edge.** S3-era URL-rewrite functions fight
+ *    a gateway that already does its own path-mounting + clean URLs (→ 301 loops).
+ *  - **Dynamic paths** (e.g. `/api/*`) use the managed `CachingDisabled` policy and
+ *    allow all HTTP methods; **static paths** use `CachingOptimized`.
+ *  - **Origin lockdown header** (optional): a secret injected on the origin hop,
+ *    paired with rpx `createOriginGuard`, so the publicly-resolvable origin can't
+ *    be used to bypass the CDN.
+ *
+ * The result is a complete `DistributionConfig` suitable for CloudFront
+ * `CreateDistribution` or `UpdateDistribution`.
+ */
+/** AWS-managed cache/origin-request policy IDs (identical across all accounts). */
+export declare const MANAGED_CACHE_POLICY_OPTIMIZED = "658327ea-f89d-4fab-a63d-7e88639e58f6";
+export declare const MANAGED_CACHE_POLICY_DISABLED = "4135ea2d-6df8-44a3-9df3-4b5a84be39ad";
+export declare const MANAGED_ORIGIN_REQUEST_POLICY_ALL_VIEWER = "216adef6-5c7f-47e4-b989-5492eafa07d3";
+export interface OriginFrontedBehavior {
+    /** Path pattern this behavior owns, e.g. `/api/*`, `/docs`, `/docs/*`. */
+    pathPattern: string;
+    /** `dynamic` → no caching + all methods (apps/APIs); `static` → cached (CachingOptimized). */
+    kind: 'dynamic' | 'static';
+}
+export interface BuildCloudFrontOriginOptions {
+    /** Public aliases (CNAMEs) on the distribution, e.g. `['example.com', 'www.example.com']`. */
+    aliases: string[];
+    /** Dedicated origin hostname CloudFront connects to. MUST resolve to the box, MUST NOT be an alias. */
+    originDomain: string;
+    /** ACM certificate ARN (us-east-1) covering {@link aliases}. */
+    viewerCertificateArn: string;
+    /** Per-path behaviors layered over the default. The default behavior (`/`) is always `static`. */
+    behaviors?: OriginFrontedBehavior[];
+    /** Secret injected on the origin hop (paired with rpx `createOriginGuard`). Omit to leave the origin open. */
+    originSecret?: string;
+    /** Header carrying {@link originSecret}. @default 'X-Origin-Verify' */
+    originSecretHeader?: string;
+    /** Stable id used to deterministically derive `CallerReference`. @default originDomain */
+    callerReference?: string;
+    /** Distribution comment. */
+    comment?: string;
+    /** `PriceClass_All` | `PriceClass_200` | `PriceClass_100`. @default 'PriceClass_All' */
+    priceClass?: string;
+}
+/**
+ * Build a complete CloudFront `DistributionConfig` for a self-hosted origin.
+ * See the module docblock for the rationale behind each fixed setting.
+ */
+export declare function buildCloudFrontOriginConfig(options: BuildCloudFrontOriginOptions): Record<string, any>;

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

@@ -25,3 +25,10 @@ export interface DeployAllSitesOptions {
  * without `start`, shipped to `/var/www/<site>`). Bucket sites are skipped.
  */
 export declare function deployAllComputeSites(options: DeployAllSitesOptions): Promise<boolean>;
+/**
+ * Regenerate the rpx gateway config from the sites model and (re)start the
+ * gateway on the compute targets. No-op (returns `true`) unless
+ * `compute.proxy.engine === 'rpx'`. Re-runnable: the provision script writes the
+ * launcher + unit and `systemctl restart`s, which reloads the new routes.
+ */
+export declare function reloadRpxGateway(options: DeployAllSitesOptions): Promise<boolean>;

package/dist/drivers/shared/rpx-gateway.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Generate the rpx reverse-proxy gateway config + provisioning from the `sites`
+ * model.
+ *
+ * ts-cloud's per-site deploy model resolves each site to one of three kinds
+ * (see {@link import('../../deploy/site-target').resolveSiteKind}):
+ *  - `server-app`    — a dynamic app running on a port (systemd service);
+ *  - `server-static` — a static site shipped to `/var/www/<name>`;
+ *  - `bucket`        — object storage + CDN (not on the box; ignored here).
+ *
+ * The rpx gateway fronts :80/:443 on the box and routes by host **and path**:
+ * several sites can share one `domain` on different `path`s (e.g.
+ * `stacksjs.com/api/*` → app on :3000, `stacksjs.com/docs*` → `/var/www/docs`,
+ * `stacksjs.com/` → `/var/www/public`). This module maps the sites model to the
+ * rpx `proxies` array so `buddy deploy` can ship the config + wire the gateway.
+ *
+ * It replaces the old Caddyfile generation — pantry/stacks use rpx (their own
+ * tooling), so the gateway is rpx, not Caddy.
+ */
+import type { ComputeProxyConfig, SiteConfig } from '@ts-cloud/core';
+/** Default directory on the box that holds real per-domain TLS certs. */
+export declare const DEFAULT_RPX_CERTS_DIR = "/etc/rpx/certs";
+/** A single rpx proxy route, mapped from one site. */
+export interface RpxRoute {
+    /** Public host this route is served under (the site's `domain`). */
+    to: string;
+    /** Path prefix within the host this route owns (e.g. `/api`). Omitted = `/`. */
+    path?: string;
+    /** Upstream `host:port` for a `server-app` route. */
+    from?: string;
+    /** Absolute directory served for a `server-static` route (`/var/www/<name>`). */
+    static?: string;
+    /** Strip `.html` and resolve clean URLs (set for static sites). */
+    cleanUrls?: boolean;
+    /** SPA fallback for static sites. */
+    spa?: boolean;
+    /** Stable id used when rpx registers the route. Derived from `to`+`path`. */
+    id: string;
+}
+/** The rpx daemon/proxy config produced from a sites model. */
+export interface RpxGatewayConfig {
+    /** Multi-proxy route list (host + path keyed). */
+    proxies: RpxRoute[];
+    /**
+     * Production per-domain SNI certs: rpx serves a real PEM per server name from
+     * this directory (`<domain>.crt` / `<domain>.key`).
+     */
+    productionCerts: {
+        certsDir: string;
+    };
+    /**
+     * On-demand TLS (opt-in): lazily issue a real cert for an approved host the
+     * first time it's needed. The site domains form the allowlist.
+     */
+    onDemandTls?: {
+        enabled: true;
+        allowedSuffixes: string[];
+        email?: string;
+        certsDir: string;
+    };
+    /** Always `true` — the gateway terminates TLS on the box. */
+    https: true;
+    /** Never touch `/etc/hosts` on a real server with real DNS. */
+    hostsManagement: false;
+    /** Don't remove certs/hosts on exit. */
+    cleanup: {
+        hosts: false;
+        certs: false;
+    };
+    /**
+     * Origin lockdown (from `proxy.cdn` when a `secret` is set): rpx rejects
+     * direct hits to the CDN-fronted hosts that lack the shared-secret header.
+     */
+    originGuard?: {
+        header: string;
+        value: string;
+        hosts: string[];
+    };
+}
+export interface BuildRpxConfigOptions {
+    /** Proxy config from `infrastructure.compute.proxy`. */
+    proxy: ComputeProxyConfig;
+    /** Directory static sites are shipped to. @default '/var/www' */
+    wwwRoot?: string;
+}
+/**
+ * Normalize a path prefix to a leading-slash, no-trailing-slash form, or
+ * `undefined` for the host default. Mirrors rpx's `normalizePathPrefix`.
+ */
+export declare function normalizeRoutePath(path: string | undefined): string | undefined;
+/** Derive a stable, filesystem/registry-safe id from a host (+ optional path). */
+export declare function deriveRouteId(to: string, path?: string): string;
+/**
+ * Map the sites model to an rpx gateway config. Each non-bucket site with a
+ * `domain` becomes a route:
+ *  - `server-app`    → `{ to: domain, path, from: 'localhost:<port>' }`
+ *  - `server-static` → `{ to: domain, path, static: '<wwwRoot>/<name>' }`
+ *
+ * Routes are grouped by domain so rpx's path-based routing can serve an app +
+ * several static dirs under one host. Bucket sites and sites without a `domain`
+ * (or a `server-app` without a `port`) are skipped.
+ */
+export declare function buildRpxConfig(sites: Record<string, SiteConfig | undefined>, options: BuildRpxConfigOptions): RpxGatewayConfig;
+/**
+ * Render the rpx gateway config as a self-contained launcher TS module. The
+ * systemd unit runs `bun <file>`, which imports `startProxies` from the
+ * globally-installed `@stacksjs/rpx` and starts the gateway with the generated
+ * options. We ship a runnable launcher (not a bare config) because rpx's CLI
+ * resolves its own config from its install dir, not an arbitrary path.
+ */
+export declare function renderRpxLauncher(config: RpxGatewayConfig): string;
+/** Default install location for the gateway launcher + config on the box. */
+export declare const RPX_DIR = "/etc/rpx";
+export declare const RPX_LAUNCHER_PATH = "/etc/rpx/gateway.ts";
+export declare const RPX_SERVICE_NAME = "rpx-gateway.service";
+export interface BuildRpxProvisionOptions {
+    config: RpxGatewayConfig;
+    proxy: ComputeProxyConfig;
+    /** Absolute path to the `bun` binary on the box. @default '/usr/local/bin/bun' */
+    bunBin?: string;
+}
+/**
+ * Build the idempotent, re-runnable shell commands that install rpx as the
+ * gateway, write the generated launcher + ensure the certs dir, install the
+ * systemd unit, and enable + (re)start it on :80/:443.
+ *
+ * Safe to run at first boot (cloud-init) and again on every deploy — the unit
+ * write + `systemctl restart` reloads the regenerated routes so new
+ * server-app/server-static sites appear in the gateway automatically.
+ */
+export declare function buildRpxProvisionScript(options: BuildRpxProvisionOptions): string[];

package/dist/index.js

@@ -81600,7 +81600,8 @@ function generateUbuntuAppCloudInit(options = {}) {
     runtimeVersion = "latest",
     systemPackages = [],
     database,
-    caddyfile
+    caddyfile,
+    rpxProvision
   } = options;
   const packages = new Set(systemPackages);
   if (database === "sqlite")
@@ -81692,6 +81693,13 @@ CADDY_CONFIG_EOF
 systemctl daemon-reload
 systemctl enable caddy
 systemctl start caddy
+`;
+  }
+  if (rpxProvision && rpxProvision.length > 0) {
+    const body = rpxProvision[0] === "set -euo pipefail" ? rpxProvision.slice(1) : rpxProvision;
+    script += `
+${body.join(`
+`)}
 `;
   }
   script += `
@@ -81716,6 +81724,137 @@ runcmd:
 `;
 }
 
+// src/drivers/shared/rpx-gateway.ts
+var DEFAULT_RPX_CERTS_DIR = "/etc/rpx/certs";
+function normalizeRoutePath(path) {
+  if (!path || path === "/")
+    return;
+  let p = `/${path}`.replace(/\/+/g, "/").replace(/\/+$/, "");
+  if (!p.startsWith("/"))
+    p = `/${p}`;
+  return p === "" || p === "/" ? undefined : p;
+}
+function deriveRouteId(to, path) {
+  const base = path ? `${to}${path}` : to;
+  const cleaned = base.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 128);
+  return cleaned.length > 0 ? cleaned : "rpx";
+}
+function buildRpxConfig(sites, options) {
+  const wwwRoot = (options.wwwRoot ?? "/var/www").replace(/\/+$/, "");
+  const certsDir = options.proxy.certsDir ?? DEFAULT_RPX_CERTS_DIR;
+  const proxies = [];
+  const domains = new Set;
+  for (const [name, site] of Object.entries(sites)) {
+    if (!site || !site.domain)
+      continue;
+    const kind = resolveSiteKind(site);
+    if (kind === "bucket")
+      continue;
+    const path = normalizeRoutePath(site.path);
+    const id = deriveRouteId(site.domain, path);
+    if (kind === "server-app") {
+      if (typeof site.port !== "number")
+        continue;
+      proxies.push({ to: site.domain, path, from: `localhost:${site.port}`, id });
+    } else {
+      proxies.push({
+        to: site.domain,
+        path,
+        static: `${wwwRoot}/${name}`,
+        cleanUrls: site.pathRewriteStyle !== "flat",
+        spa: site.spa ?? false,
+        id
+      });
+    }
+    domains.add(site.domain);
+  }
+  proxies.sort((a, b) => {
+    if (a.to !== b.to)
+      return a.to.localeCompare(b.to);
+    return (b.path?.length ?? 0) - (a.path?.length ?? 0);
+  });
+  const config6 = {
+    proxies,
+    productionCerts: { certsDir },
+    https: true,
+    hostsManagement: false,
+    cleanup: { hosts: false, certs: false }
+  };
+  if (options.proxy.onDemandTls && domains.size > 0) {
+    config6.onDemandTls = {
+      enabled: true,
+      allowedSuffixes: [...domains],
+      email: options.proxy.onDemandTlsEmail,
+      certsDir
+    };
+  }
+  const cdn = options.proxy.cdn;
+  if (cdn?.secret && cdn.frontedHosts.length > 0) {
+    config6.originGuard = {
+      header: cdn.secretHeader ?? "X-Origin-Verify",
+      value: cdn.secret,
+      hosts: cdn.frontedHosts
+    };
+  }
+  return config6;
+}
+function renderRpxLauncher(config6) {
+  const json = JSON.stringify(config6, null, 2);
+  return `// Generated by ts-cloud — rpx reverse-proxy gateway.
+// Routes are derived from the \`sites\` model on every \`buddy deploy\`.
+import { startProxies } from '@stacksjs/rpx'
+
+const config = ${json} as const
+
+await startProxies(config as any)
+`;
+}
+var RPX_DIR = "/etc/rpx";
+var RPX_LAUNCHER_PATH = "/etc/rpx/gateway.ts";
+var RPX_SERVICE_NAME = "rpx-gateway.service";
+function writeFileHeredoc(path, content, delimiter) {
+  return [
+    `cat > ${path} <<'${delimiter}'`,
+    content,
+    delimiter
+  ];
+}
+function buildRpxProvisionScript(options) {
+  const { config: config6, proxy } = options;
+  const bunBin = options.bunBin ?? "/usr/local/bin/bun";
+  const version2 = proxy.version ?? "latest";
+  const certsDir = config6.productionCerts.certsDir;
+  const launcher = renderRpxLauncher(config6);
+  return [
+    "set -euo pipefail",
+    `mkdir -p ${RPX_DIR} ${certsDir}`,
+    `${bunBin} add -g @stacksjs/rpx@${version2}`,
+    ...writeFileHeredoc(RPX_LAUNCHER_PATH, launcher, "TS_CLOUD_RPX_EOF"),
+    ...writeFileHeredoc(`/etc/systemd/system/${RPX_SERVICE_NAME}`, [
+      "[Unit]",
+      "Description=rpx reverse-proxy gateway (managed by ts-cloud)",
+      "After=network.target network-online.target",
+      "Wants=network-online.target",
+      "",
+      "[Service]",
+      "Type=simple",
+      `ExecStart=${bunBin} ${RPX_LAUNCHER_PATH}`,
+      `Environment=BUN_INSTALL=/root/.bun`,
+      "Restart=always",
+      "RestartSec=5",
+      "LimitNOFILE=1048576",
+      "AmbientCapabilities=CAP_NET_BIND_SERVICE",
+      "",
+      "[Install]",
+      "WantedBy=multi-user.target"
+    ].join(`
+`), "TS_CLOUD_RPX_UNIT_EOF"),
+    "systemctl daemon-reload",
+    `systemctl enable ${RPX_SERVICE_NAME}`,
+    `systemctl restart ${RPX_SERVICE_NAME}`
+  ];
+}
+
 // src/drivers/hetzner/firewall-rules.ts
 function buildHetznerFirewallRules(config6) {
   const openPorts = new Set([80, 443, ...config6.sitePorts]);
@@ -81852,11 +81991,17 @@ class HetznerDriver {
     }
     const sites = config6.sites || {};
     const sitePorts = this.collectUpstreamPorts(sites);
+    const rpxProvision = compute.proxy?.engine === "rpx" ? buildRpxProvisionScript({
+      proxy: compute.proxy,
+      config: buildRpxConfig(sites, { proxy: compute.proxy }),
+      bunBin: compute.runtime === "node" || compute.runtime === "deno" ? undefined : "/usr/local/bin/bun"
+    }) : undefined;
     const bootstrap = generateUbuntuAppCloudInit({
       runtime: compute.runtime || "bun",
       runtimeVersion: compute.runtimeVersion || "latest",
       systemPackages: compute.systemPackages,
-      database: config6.infrastructure?.database
+      database: config6.infrastructure?.database,
+      rpxProvision
     });
     const userData = wrapCloudInitUserData(bootstrap);
     const serverType = resolveHetznerServerType(compute.size);
@@ -82344,6 +82489,48 @@ async function deployAllComputeSites(options) {
       }
     }
   }
+  const reloaded = await reloadRpxGateway(options);
+  if (!reloaded)
+    return false;
+  return true;
+}
+async function reloadRpxGateway(options) {
+  const { config: config6, environment, driver, logger: logger4 = noopLogger } = options;
+  const proxy = config6.infrastructure?.compute?.proxy;
+  if (proxy?.engine !== "rpx")
+    return true;
+  const sites = config6.sites || {};
+  const rpxConfig = buildRpxConfig(sites, { proxy });
+  if (rpxConfig.proxies.length === 0) {
+    logger4.warn("rpx gateway: no server sites with a domain to route — skipping gateway reload.");
+    return true;
+  }
+  const targets = await driver.findComputeTargets({
+    slug: config6.project.slug,
+    environment,
+    role: "app"
+  });
+  if (targets.length === 0) {
+    logger4.warn("rpx gateway: no compute targets found — skipping gateway reload.");
+    return true;
+  }
+  logger4.step(`Reloading rpx gateway with ${rpxConfig.proxies.length} route(s)...`);
+  const script = buildRpxProvisionScript({ proxy, config: rpxConfig });
+  const result = await driver.runRemoteDeploy({
+    targets,
+    commands: script,
+    comment: `ts-cloud rpx gateway reload ${config6.project.slug}`,
+    tags: {
+      Project: config6.project.slug,
+      Environment: environment,
+      Role: "app"
+    }
+  });
+  if (!result.success) {
+    logger4.error(`rpx gateway reload failed: ${result.error || "unknown error"}`);
+    return false;
+  }
+  logger4.success(`rpx gateway reloaded on ${result.instanceCount} target(s)`);
   return true;
 }
 // src/index.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/ts-cloud",
   "type": "module",
-  "version": "0.2.24",
+  "version": "0.2.26",
   "description": "A lightweight, performant infrastructure-as-code library and CLI for deploying both server-based (EC2) and serverless applications.",
   "author": "Chris Breuer <chris@stacksjs.com>",
   "license": "MIT",
@@ -89,8 +89,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ts-cloud/aws-types": "0.2.24",
-    "@ts-cloud/core": "0.2.24",
+    "@ts-cloud/aws-types": "0.2.26",
+    "@ts-cloud/core": "0.2.26",
     "@stacksjs/ts-xml": "^0.1.0"
   },
   "devDependencies": {