@ts-cloud/core 0.7.93 → 0.7.94

package/dist/types.d.ts

@@ -812,6 +812,35 @@ export interface SiteRedirectConfig {
     /** Append the request path + query to `to`. Default `true`. */
     preservePath?: boolean;
 }
+/**
+ * A shared path pointed at an explicit location instead of the site's own
+ * `shared/` directory.
+ *
+ * Every site installs under its own base (`/var/www/<slug>-<site>`), so two
+ * sites of one project that both list `database/app.sqlite` get two separate
+ * databases — each surviving its own deploys, and drifting apart forever.
+ * Naming one absolute `target` makes them the same file.
+ */
+export interface SharedPathSpec {
+    /** Release-relative path that receives the symlink, e.g. `database/app.sqlite`. */
+    path: string;
+    /**
+     * Absolute path the symlink points at. Defaults to `<base>/shared/<path>`,
+     * which is what a plain string entry means.
+     */
+    target?: string;
+    /**
+     * May this site CREATE the target — placehold it, and seed it from this
+     * site's own live release? Default `true`.
+     *
+     * Set `false` on every site but one when several share a target. Otherwise
+     * whichever site happens to deploy first creates the file, and the site that
+     * actually holds the data finds the target already there and never seeds it.
+     */
+    seed?: boolean;
+}
+/** A shared path: a release-relative path, or {@link SharedPathSpec}. */
+export type SharedPathEntry = string | SharedPathSpec;
 export interface SiteConfig {
     /**
      * Directory to deploy.
@@ -983,10 +1012,16 @@ export interface SiteConfig {
      * A release is a fresh directory, so anything the app WRITES and must keep
      * has to be listed here or the next deploy silently starts it from empty.
      *
+     * An entry may instead be a {@link SharedPathSpec} naming an absolute
+     * `target`, which is how SEVERAL sites of one project point at ONE file —
+     * an app and its API sharing a single SQLite database, say. Each site
+     * installs under its own base, so a plain string can only ever give each of
+     * them a database of its own.
+     *
      * Honored by both PHP/Laravel sites and server-app sites (`start`).
      * @default ['storage', '.env'] for PHP sites; `['.env']` for server-app sites
      */
-    sharedPaths?: string[];
+    sharedPaths?: SharedPathEntry[];
     /**
      * Number of past releases to retain on the box for rollback.
      * @default 4
@@ -1318,7 +1353,7 @@ export interface BucketConfig {
 }
 export interface DatabaseConfig {
     type?: 'rds' | 'dynamodb';
-    engine?: 'postgres' | 'mysql' | 'mariadb' | 'singlestore';
+    engine?: 'postgres' | 'mysql' | 'mariadb' | 'singlestore' | 'vitess';
     instanceType?: string;
     /** Database/schema name to create (e.g. `forge`). */
     name?: string;
@@ -1328,7 +1363,7 @@ export interface DatabaseConfig {
     password?: string;
     /** Hostname for a managed/external database (default `127.0.0.1` on-box). */
     host?: string;
-    /** Port (defaults: mysql/mariadb/singlestore 3306, postgres 5432). */
+    /** Port (defaults: mysql/mariadb/singlestore 3306, vitess 15306, postgres 5432). */
     port?: number;
     /**
      * Require TLS to the database. Defaults on for managed SingleStore (Helios),
@@ -1342,6 +1377,53 @@ export interface DatabaseConfig {
      * engine.
      */
     users?: DatabaseUserConfig[];
+    /** Control-plane settings, only meaningful when `engine` is `vitess`. */
+    vitess?: VitessControlPlaneConfig;
+}
+/**
+ * How to reach a Vitess cluster's control plane.
+ *
+ * The application talks to vtgate over the MySQL protocol, which is enough
+ * for queries and for most observability (`SHOW VITESS_SHARDS`,
+ * `SHOW VITESS_MIGRATIONS`). It is NOT enough to create a keyspace or apply
+ * a VSchema: those are vtctld gRPC operations, so managing them needs the
+ * separate address below plus the `vtctldclient` binary on the box.
+ *
+ * Leaving this unset keeps everything read-only. The dashboard still shows
+ * topology and migrations through vtgate; it just cannot change anything,
+ * which is the right default for a cluster ts-cloud did not build.
+ */
+export interface VitessControlPlaneConfig {
+    /**
+     * vtctld's gRPC address, e.g. `vtctld.internal:15999`.
+     *
+     * Distinct from the vtgate address in {@link DatabaseConfig.host}: vtgate
+     * routes queries, vtctld administers the cluster. Pointing this at vtgate
+     * fails with a protocol error rather than doing anything useful.
+     */
+    vtctldAddr?: string;
+    /**
+     * Default cell (failure domain) for operations that need one, e.g.
+     * `zone1`. Vitess clusters always have at least one.
+     */
+    cell?: string;
+    /**
+     * `vtctldclient` release to install, e.g. `21.0.0`.
+     *
+     * Pinned rather than tracking latest: vtctldclient talks gRPC to vtctld
+     * and Vitess only supports a bounded version skew between them, so an
+     * unpinned client can start failing the day the cluster is upgraded.
+     */
+    clientVersion?: string;
+    /**
+     * DDL strategy for schema changes applied through the dashboard.
+     *
+     * `vitess` (the default) runs Vitess's own online DDL, which applies
+     * shard by shard without locking the keyspace and is revertible.
+     * `direct` runs the DDL synchronously and WILL lock; it exists for
+     * unsharded keyspaces where that is acceptable and faster.
+     */
+    ddlStrategy?: 'vitess' | 'direct';
 }
 /**
  * An extra database user provisioned on the on-box engine (per-user grants).
@@ -2570,7 +2652,82 @@ export interface ComputePhpConfig {
  * Each entry is `true` (install with defaults) or an object pinning a version.
  * See {@link ComputeConfig.services}.
  */
+export interface VitessKeyspaceConfig {
+    /** Keyspace name. */
+    name: string;
+    /**
+     * Whether the keyspace is sharded. An unsharded keyspace has one shard
+     * (`0`) and needs no VSchema to be routable, which makes it the right
+     * starting point for an application that has not yet decided how to shard.
+     */
+    sharded?: boolean;
+}
+export interface VitessServiceConfig {
+    /**
+     * `combo` for a single-process development stack, `cluster` for real
+     * daemons. Defaults to `cluster`, because a config that provisions
+     * infrastructure should not quietly give you a non-durable one.
+     */
+    mode?: 'combo' | 'cluster';
+    /**
+     * Pantry version spec for `vitess.io`. Omit for the registry's latest.
+     *
+     * **Requires Vitess 20 or newer.** Vitess renamed every daemon flag from
+     * `snake_case` to `kebab-case` in v20 and removed the old spellings in a
+     * later release; the generated systemd units use the current names, so
+     * pinning an older version produces daemons that refuse to start.
+     */
+    version?: string;
+    /** Cell (failure domain) name. Vitess requires at least one. */
+    cell?: string;
+    /** Keyspaces to create at provision time. */
+    keyspaces?: VitessKeyspaceConfig[];
+    /** Override vtgate's MySQL port. Applications connect here. */
+    vtgatePort?: number;
+    /**
+     * Username applications authenticate to vtgate with. Defaults to `vitess`.
+     *
+     * vtgate requires an auth server; there is no unauthenticated cluster mode
+     * worth offering, since its port would otherwise be an open database.
+     */
+    username?: string;
+    /** Password for {@link username}. */
+    password?: string;
+    /**
+     * Address vtgate binds its MySQL port to. Defaults to `127.0.0.1`.
+     *
+     * The single-box model puts the application on this same host, so the
+     * default keeps the database off the network entirely. Set `0.0.0.0` only
+     * when something off-box genuinely needs to connect, and pair it with a
+     * firewall rule.
+     */
+    bindAddress?: string;
+    /**
+     * External topology store, e.g. `http://etcd-a.internal:2379`. When set,
+     * etcd is not installed on the box and the daemons point here instead.
+     */
+    etcdEndpoint?: string;
+    /**
+     * MySQL port for the tablet's managed mysqld. Not something applications
+     * should connect to: writing directly to a tablet's mysqld bypasses Vitess.
+     */
+    mysqlPort?: number;
+}
 export interface ComputeServicesConfig {
+    /**
+     * Provision Vitess on this box.
+     *
+     * `true` provisions a single-box cluster (etcd, vtctld, vttablet beside a
+     * managed mysqld, vtgate) with default ports. Pass an object for keyspaces,
+     * an external topology store, or `mode: 'combo'` - a single-process
+     * development stack that is NOT durable.
+     *
+     * Single-box by design: spreading tablets across machines needs per-shard
+     * placement and reparent policy, which are operator decisions rather than
+     * provisioner defaults. A sharded keyspace here gets Vitess's routing and
+     * online DDL, not fault tolerance.
+     */
+    vitess?: boolean | VitessServiceConfig;
     mysql?: boolean | {
         version?: string;
     };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ts-cloud/core",
   "type": "module",
-  "version": "0.7.93",
+  "version": "0.7.94",
   "description": "Core CloudFormation generation library for ts-cloud",
   "author": "Chris Breuer <chris@stacksjs.com>",
   "license": "MIT",
@@ -31,7 +31,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@ts-cloud/aws-types": "0.7.93"
+    "@ts-cloud/aws-types": "0.7.94"
   },
   "devDependencies": {
     "typescript": "^7.0.2"