@stacksjs/ts-cloud 0.9.2 → 0.9.3

package/dist/{chunk-hg7rhrgd.js → chunk-1c8dbv57.js}

@@ -1371,7 +1371,7 @@ function resolveSiteKind(site) {
 function hasComputeConfigured(config) {
   return config.infrastructure?.compute != null || Boolean(config.cloud?.attachTo?.trim());
 }
-function validateDeploymentConfig(config) {
+function validateDeploymentConfig(config, options = {}) {
   const errors = [];
   const warnings = [];
   const sites = config.sites || {};
@@ -1444,6 +1444,10 @@ function validateDeploymentConfig(config) {
         errors.push(`Site '${name}' deploys to a server (deploy:'server'${site.deploy ? "" : " inferred from `start`"}) but no \`infrastructure.compute\` is configured. Set deploy:'bucket' or add a server (infrastructure.compute).`);
       }
       if (typeof site.port === "number") {
+        const coTenant = options.occupiedPorts?.get(site.port);
+        if (coTenant) {
+          errors.push(`Site '${name}' wants port ${site.port}, which project '${coTenant}' already serves on this box. ` + `Attached projects share one port namespace. Give '${name}' a free port, or let the attach allocate one.`);
+        }
         const existing = portOwners.get(site.port);
         if (existing) {
           errors.push(`Sites '${existing}' and '${name}' both use port ${site.port}. Server apps sharing a box must use distinct ports.`);

package/dist/{chunk-rxgchb08.js → chunk-q0st3se8.js}

@@ -50,7 +50,7 @@ import {
   resolveSiteKind,
   resolveUiSource,
   siteInstallBase
-} from "./chunk-hg7rhrgd.js";
+} from "./chunk-1c8dbv57.js";
 import {
   SSMClient
 } from "./chunk-7m60qnc8.js";

package/dist/deploy/attach-credentials.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The minimum a driver has to produce for a server to be attributed.
+ *
+ * Structural rather than a provider type so a Hetzner server satisfies it as-is
+ * and another driver can satisfy it without importing anything.
+ */
+export interface ReachableServer {
+    name: string;
+    labels?: Record<string, string>;
+}
+export interface CredentialReach {
+    /** Every server the credential enumerated. */
+    total: number;
+    /** Servers belonging to the project being attached TO. Expected reach. */
+    owner: string[];
+    /** Servers belonging to the attaching project itself, if it has any. */
+    self: string[];
+    /** Servers owned by unrelated ts-cloud projects, keyed by project slug. */
+    others: Map<string, string[]>;
+    /**
+     * Servers carrying no ts-cloud project label.
+     *
+     * Counted separately because they are the reach most likely to surprise: not
+     * managed by ts-cloud at all, and so not visible in any ts-cloud config, yet
+     * just as writable by the token.
+     */
+    unmanaged: string[];
+}
+/**
+ * Attribute every server the credential can see to a project.
+ *
+ * `ownerSlug` is what `cloud.attachTo` names; `selfSlug` is the deploying
+ * project. Splitting those two out of `others` is the point: reach over the owner
+ * is the reach being asked for, reach over anything else is the reach nobody
+ * asked for, and only the second number is an argument against attaching.
+ */
+export declare function describeCredentialReach(servers: ReachableServer[], options: {
+    ownerSlug: string;
+    selfSlug?: string;
+}): CredentialReach;
+/** Servers the credential reaches that neither project being joined owns. */
+export declare function unrelatedReachCount(reach: CredentialReach): number;
+/**
+ * The credential radius as plan lines, ready to print.
+ *
+ * Returns lines rather than printing so the caller owns the output stream and
+ * this stays testable. Sorted, because a plan that reorders itself between runs
+ * is a plan nobody diffs.
+ *
+ * When the reach is exactly the owner's box and this project's own, there is
+ * nothing to warn about and the summary says so in one line - a warning that
+ * fires every time is a warning that gets skipped.
+ */
+export declare function formatCredentialReach(reach: CredentialReach, options: {
+    ownerSlug: string;
+    selfSlug?: string;
+}): string[];

package/dist/deploy/index.js

@@ -36,7 +36,7 @@ import {
   synchronizeDashboardUsers,
   trackDashboardOperation,
   verifyStaticApiOrigin
-} from "../chunk-rxgchb08.js";
+} from "../chunk-q0st3se8.js";
 import {
   deleteStaticSite,
   deployStaticSite,
@@ -83,7 +83,7 @@ import {
   siteInstallBase,
   validateDeploymentConfig,
   verifyAddressRecord
-} from "../chunk-hg7rhrgd.js";
+} from "../chunk-1c8dbv57.js";
 import"../chunk-7m60qnc8.js";
 import"../chunk-4cjrg98a.js";
 import"../chunk-rds0sy87.js";

package/dist/deploy/site-ports.d.ts

@@ -0,0 +1,151 @@
+import type { CloudConfig } from '@ts-cloud/core';
+/**
+ * Port ownership across the projects sharing one box.
+ *
+ * A box can host several independent projects: each one's deploy writes its own
+ * rpx registry fragment and the assembler merges them (see `RPX_SITES_DIR`).
+ * That composes cleanly for ROUTES, because routes are keyed by host. It does
+ * not compose for PORTS, because every app generated from the same template
+ * declares the same loopback ports, and `validateDeploymentConfig` only ever
+ * sees one project's `sites`.
+ *
+ * The second attach therefore passes validation, and then does something worse
+ * than failing: ts-cloud's units do not set exclusive binding, so both listeners
+ * bind and the kernel load-balances between them. Nothing errors, both services
+ * look healthy, and each domain answers with the other project's site for about
+ * half its requests. That is not hypothetical - it is what happened to
+ * predicthq.org when a storefront picked a port by reading other projects'
+ * config files rather than the box (see `assertPortsAreFree` in stacks).
+ *
+ * `assertPortsAreFree` catches this late, from the deploying box over SSH, by
+ * comparing wanted ports against live listeners. That is the better evidence and
+ * it stays the last line of defence. What it cannot do is avoid the clash: it
+ * exits and tells the operator to go pick free ports by hand. This module is the
+ * other half - deciding the ports before anything is shipped, from data a plan
+ * already has.
+ *
+ * The fix does not need new bookkeeping on the box. The fragments already record
+ * every upstream a project serves, so the host is its own port registry - it was
+ * simply never read. This module turns those fragments into a port -> owner map,
+ * finds the collisions, and allocates around them.
+ *
+ * Everything here is pure. The one thing that must touch the box, reading the
+ * fragments, is split into a script builder and a parser so both halves are
+ * testable without a server.
+ *
+ * @see https://github.com/stacksjs/ts-cloud/issues/168
+ */
+/**
+ * Where the rpx gateway keeps one registry fragment per project.
+ *
+ * Deliberately duplicated from `RPX_SITES_DIR` rather than imported:
+ * `rpx-gateway.ts` imports `site-target.ts`, and this module imports it too, so
+ * importing the constant from there would close a cycle. `site-ports.test.ts`
+ * asserts the two stay equal, so the duplicate cannot drift silently.
+ */
+export declare const HOST_SITES_DIR = "/etc/rpx/sites.d";
+export interface SitePortRange {
+    /** Lowest port the allocator may hand out, inclusive. */
+    start: number;
+    /** Highest port the allocator may hand out, inclusive. */
+    end: number;
+}
+/**
+ * The window the allocator searches.
+ *
+ * Chosen to contain the template's own defaults (3022/3023) so that an app which
+ * has never thought about ports keeps the ports it already had whenever they are
+ * free - see {@link allocateSitePorts}, which only moves a site that actually
+ * collides.
+ */
+export declare const DEFAULT_SITE_PORT_RANGE: SitePortRange;
+/**
+ * One project's registry fragment, as written by the deploy:
+ * `JSON.stringify({ slug, ...RpxGatewayConfig })`.
+ *
+ * Only the fields this module reads are declared. A fragment written by an older
+ * ts-cloud may be missing `slug`, which the writer defaults to `'app'`.
+ */
+export interface HostSiteFragment {
+    slug?: string;
+    proxies?: Array<{
+        from?: string | string[];
+    }>;
+}
+/** Port -> the slug of the project that already serves it on this box. */
+export type PortOwners = Map<number, string>;
+/**
+ * The port from an rpx upstream (`host:port`).
+ *
+ * Splits on the LAST colon so a bracketed IPv6 literal (`[::1]:3022`) parses as
+ * port 3022 rather than as part of the address. Returns `undefined` for anything
+ * that is not a valid TCP port, so a malformed fragment narrows the map instead
+ * of poisoning it with NaN.
+ */
+export declare function parseUpstreamPort(upstream: string): number | undefined;
+/**
+ * Every port the box already serves, mapped to the project that owns it.
+ *
+ * `ignoreSlug` must be set to the deploying project's own slug. Its fragment is
+ * already on the box from the previous deploy, so without that the second deploy
+ * of an attached app reports a conflict with itself and can never succeed.
+ *
+ * First writer wins for a given port, which keeps the result deterministic when
+ * two fragments disagree - a state that is itself the bug being reported, so the
+ * caller sees one stable owner rather than an order-dependent one.
+ */
+export declare function occupiedHostPorts(fragments: HostSiteFragment[], options?: {
+    ignoreSlug?: string;
+}): PortOwners;
+/**
+ * A shell snippet that dumps every registry fragment on the box, one
+ * base64-encoded JSON document per line.
+ *
+ * base64 rather than raw `cat`, because the fragments are pretty-printed and so
+ * span many lines; encoding makes the output unambiguously one record per line
+ * without depending on a JSON tool being installed. Only POSIX utilities plus
+ * `base64` are used, both present on the provisioned image - the same reason
+ * `resize-remote.ts` enumerates these files with plain `find`.
+ *
+ * A missing directory is not an error: a box with no fragments yet prints
+ * nothing, and {@link parseHostSiteFragments} reads that as "no co-tenants".
+ */
+export declare function buildHostSitePortsScript(sitesDir?: string): string;
+/**
+ * Parse the output of {@link buildHostSitePortsScript}.
+ *
+ * A fragment that will not decode or parse is skipped rather than thrown, which
+ * matches how the box's own assembler treats a corrupt fragment: one bad file
+ * must not take the operation down. The cost is that its ports are invisible to
+ * the collision check, which is strictly better than today, where every
+ * project's ports are.
+ */
+export declare function parseHostSiteFragments(stdout: string): HostSiteFragment[];
+export interface SitePortAllocation {
+    /** Site name within the deploying project's `sites`. */
+    site: string;
+    /** The port the site should bind after allocation. */
+    port: number;
+    /** What the config asked for, when it asked for anything. */
+    declared?: number;
+    /** Did the allocation have to move the site off its declared port? */
+    moved: boolean;
+}
+export interface SitePortAllocationResult {
+    allocations: SitePortAllocation[];
+    errors: string[];
+}
+/**
+ * Assign a free port to every server-app site, preferring the one it declared.
+ *
+ * The declared port is kept whenever it is free, so allocation is a no-op on a
+ * box with no co-tenants and an app's ports stay stable across deploys. A site
+ * whose port is taken walks upward to the next free one, which keeps the result
+ * deterministic and close to what the author wrote - a template app landing on
+ * 3024 rather than an arbitrary high port.
+ *
+ * Only `server-app` sites are considered. A bucket, static, redirect or proxy
+ * site binds nothing, and `validateDeploymentConfig` already warns when one of
+ * those declares a port.
+ */
+export declare function allocateSitePorts(config: CloudConfig, occupied: ReadonlyMap<number, string>, range?: SitePortRange): SitePortAllocationResult;

package/dist/deploy/site-target.d.ts

@@ -72,6 +72,29 @@ export interface DeploymentValidationResult {
     errors: string[];
     warnings: string[];
 }
+export interface ValidateDeploymentOptions {
+    /**
+     * Ports this box already serves for OTHER projects, as port -> owning slug.
+     *
+     * Validation is otherwise blind to co-tenants: it only ever sees one project's
+     * `sites`, so two apps attached to the same server can both declare the
+     * template's default port and both pass. The box does not reject the second
+     * one either - ts-cloud's units do not set exclusive binding, so both bind and
+     * the kernel load-balances, leaving each domain serving the other project's
+     * site about half the time with nothing logged as an error. Supplying this
+     * turns that into a plan-time error naming the project holding the port.
+     *
+     * Build it with `occupiedHostPorts()` from `./site-ports`, passing the
+     * deploying project's own slug as `ignoreSlug` - its fragment is already on the
+     * box from the last deploy, and counting it would make every redeploy conflict
+     * with itself.
+     *
+     * Omitted means "no co-tenant information", which validates exactly as before.
+     *
+     * @see https://github.com/stacksjs/ts-cloud/issues/168
+     */
+    occupiedPorts?: ReadonlyMap<number, string>;
+}
 /**
  * Validate the per-site deployment configuration up front, turning what used to
  * be silent runtime failures (e.g. a `start` site with no compute server) into
@@ -80,7 +103,7 @@ export interface DeploymentValidationResult {
  * Never throws — returns structured `{ errors, warnings }`. Callers should abort
  * on any error and print warnings while continuing.
  */
-export declare function validateDeploymentConfig(config: CloudConfig): DeploymentValidationResult;
+export declare function validateDeploymentConfig(config: CloudConfig, options?: ValidateDeploymentOptions): DeploymentValidationResult;
 /**
  * Does this site produce a release the compute deploy has to build, package and
  * ship?

package/dist/drivers/index.js

@@ -70,7 +70,7 @@ import {
   waitForSsh,
   wrapCloudInitUserData,
   writeResizeCheckpoint
-} from "../chunk-hg7rhrgd.js";
+} from "../chunk-1c8dbv57.js";
 import"../chunk-7m60qnc8.js";
 import"../chunk-4cjrg98a.js";
 import"../chunk-rds0sy87.js";

package/dist/index.js

@@ -208,7 +208,7 @@ import {
   verifyUpdateSignature,
   webhookEndpoint,
   zeroCapacity
-} from "./chunk-rxgchb08.js";
+} from "./chunk-q0st3se8.js";
 import {
   deleteStaticSite,
   deployStaticSite,
@@ -350,7 +350,7 @@ import {
   waitForCloudInit,
   waitForSsh,
   wrapCloudInitUserData
-} from "./chunk-hg7rhrgd.js";
+} from "./chunk-1c8dbv57.js";
 import {
   EC2Client,
   SSMClient