@ts-cloud/core 0.16.15 → 0.16.17

package/dist/modules/cdn-failover.d.ts

@@ -0,0 +1,97 @@
+/**
+ * CloudFront origin failover (origin groups).
+ *
+ * An origin group pairs a primary origin with a secondary one. On a cache miss
+ * CloudFront asks the primary; when the primary returns one of the configured
+ * status codes, or cannot be reached (503) or times out (504), CloudFront
+ * retries the same request against the secondary.
+ *
+ * These are pure builders: they produce the `OriginGroups` block and check the
+ * constraints CloudFront enforces, so every distribution builder in ts-cloud
+ * emits the same shape. The block is identical in a CloudFormation
+ * `AWS::CloudFront::Distribution` and in the CloudFront API's
+ * `DistributionConfig`:
+ *
+ * ```
+ * OriginGroups: {
+ *   Quantity: 1,
+ *   Items: [{
+ *     Id,
+ *     FailoverCriteria: { StatusCodes: { Quantity, Items: [500, 502, ...] } },
+ *     Members: { Quantity: 2, Items: [{ OriginId: primary }, { OriginId: secondary }] },
+ *   }],
+ * }
+ * ```
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/high_availability_origin_failover.html
+ * @experimental Built against the AWS documentation; not yet exercised against a live distribution.
+ */
+/** Every status code CloudFront accepts as a failover criterion. */
+export declare const CLOUDFRONT_FAILOVER_STATUS_CODES: readonly number[];
+/** Server-side failures: what ts-cloud fails over on when no codes are given. */
+export declare const DEFAULT_FAILOVER_STATUS_CODES: readonly number[];
+/**
+ * The only methods a cache behavior may allow when it targets an origin group.
+ * CloudFront never fails over a write, so a behavior that accepts writes cannot
+ * point at a group.
+ */
+export declare const ORIGIN_GROUP_ALLOWED_METHODS: readonly string[];
+/** Suffix appended to the primary origin id to name its origin group. */
+export declare const ORIGIN_GROUP_ID_SUFFIX = "-failover-group";
+export interface OriginGroupOptions {
+    /** Id of the origin CloudFront asks first. */
+    primaryOriginId: string;
+    /** Id of the origin CloudFront retries against when the primary fails. */
+    secondaryOriginId: string;
+    /** Status codes from the primary that trigger failover. @default [500, 502, 503, 504] */
+    statusCodes?: readonly number[];
+    /** Origin group id, which cache behaviors use as their `TargetOriginId`. @default `<primaryOriginId>-failover-group` */
+    groupId?: string;
+}
+export interface CloudFrontOriginGroup {
+    Id: string;
+    FailoverCriteria: {
+        StatusCodes: {
+            Quantity: number;
+            Items: number[];
+        };
+    };
+    Members: {
+        Quantity: number;
+        Items: Array<{
+            OriginId: string;
+        }>;
+    };
+}
+export interface CloudFrontOriginGroups {
+    Quantity: number;
+    Items: CloudFrontOriginGroup[];
+}
+/**
+ * Validate failover status codes and return them deduplicated and sorted.
+ * With no codes, returns {@link DEFAULT_FAILOVER_STATUS_CODES}.
+ *
+ * @throws when the list is empty or holds a code CloudFront does not accept.
+ */
+export declare function resolveFailoverStatusCodes(statusCodes?: readonly number[]): number[];
+/** Build one origin group (primary first, secondary second). */
+export declare function buildOriginGroup(options: OriginGroupOptions): CloudFrontOriginGroup;
+/** Build a distribution's `OriginGroups` block holding a single failover group. */
+export declare function buildOriginGroups(options: OriginGroupOptions): CloudFrontOriginGroups;
+/**
+ * Throw unless a cache behavior that targets an origin group allows only
+ * GET, HEAD and OPTIONS.
+ *
+ * Accepts either the CloudFormation form (`['GET', 'HEAD']`) or the CloudFront
+ * API form (`{ Quantity, Items: [...] }`) of `AllowedMethods`.
+ *
+ * @param where Names the behavior in the error, e.g. `the default cache behavior`.
+ */
+export declare function assertOriginGroupMethods(allowedMethods: readonly string[] | {
+    Items?: readonly string[];
+} | undefined, where?: string): void;
+/**
+ * Whether a domain is an S3 REST endpoint (and so takes an `S3OriginConfig`).
+ * S3 *website* endpoints only speak HTTP and are custom origins.
+ */
+export declare function isS3RestEndpoint(domainName: string): boolean;

package/dist/modules/cdn.d.ts

@@ -11,6 +11,30 @@ export interface DistributionOptions {
     edgeFunctions?: EdgeFunctionConfig[];
     http3?: boolean;
     comment?: string;
+    /**
+     * Secondary origin CloudFront fails over to when the primary errors.
+     * Adds an origin group and points the default cache behavior at it.
+     * @experimental See {@link CDN.addOriginFailover}.
+     */
+    failoverOrigin?: FailoverOriginConfig;
+}
+/**
+ * Secondary origin for CloudFront origin failover.
+ * @experimental Built against the AWS documentation; not yet exercised against a live distribution.
+ */
+export interface FailoverOriginConfig {
+    /** Domain of the secondary origin, e.g. a replica bucket in another region. */
+    domainName: string;
+    /** Origin kind. @default 's3' for an S3 REST endpoint, otherwise 'custom' */
+    type?: 's3' | 'alb' | 'custom';
+    /** Origin id for the secondary. @default 'FailoverOrigin' */
+    id?: string;
+    originPath?: string;
+    /**
+     * Primary-origin status codes that trigger failover. Allowed: 400, 403, 404,
+     * 416, 429, 500, 502, 503, 504. @default [500, 502, 503, 504]
+     */
+    statusCodes?: number[];
 }
 export interface OriginConfig {
     type?: 's3' | 'alb' | 'custom';
@@ -48,6 +72,18 @@ export declare class CDN {
         originAccessControl?: CloudFrontOriginAccessControl;
         logicalId: string;
     };
+    /**
+     * Add CloudFront origin failover to a distribution: append the secondary
+     * origin, group it with the default cache behavior's current origin, and
+     * point that behavior at the group.
+     *
+     * CloudFront only fails over GET, HEAD and OPTIONS, and rejects an origin
+     * group behind a cache behavior that allows writes, so this throws if the
+     * default cache behavior allows any other method.
+     *
+     * @experimental Built against the AWS documentation; not yet exercised against a live distribution.
+     */
+    static addOriginFailover(distribution: CloudFrontDistribution, failover: FailoverOriginConfig): CloudFrontDistribution;
     /**
      * Set custom domain on a distribution
      */

package/dist/modules/index.d.ts

@@ -5,6 +5,7 @@
 export * from './storage';
 export * from './registry';
 export * from './cdn';
+export * from './cdn-failover';
 export * from './dns';
 export * from './security';
 export * from './compute';

package/dist/types.d.ts

@@ -3145,6 +3145,107 @@ export interface ComputeConfig {
      * simple as adding an entry here and redeploying.
      */
     sshKeys?: SshKeyConfig[];
+    /**
+     * Bounded disk retention on box hosts (Hetzner and ssh providers, and AWS
+     * EC2 boxes deployed over SSM).
+     *
+     * ts-cloud prunes what it leaves behind on a box: abandoned upload staging,
+     * the release artifact cache, the Bun download cache, journald, unused
+     * container images and the apt cache. Current and rollback releases are never
+     * touched; `keepReleases` governs those. The cleanup runs after every deploy,
+     * after a failed one, and on a systemd timer, so a box that stops deploying
+     * still cleans. It reads root-filesystem usage first: below
+     * `pressure.lowWaterPercent` it skips the expensive rules, and at or above
+     * `pressure.highWaterPercent` it prunes on shorter windows and warns.
+     *
+     * Omit for the defaults. `false` turns the whole mechanism off, including a
+     * timer an earlier deploy installed.
+     */
+    hostCleanup?: boolean | ComputeHostCleanupConfig;
+}
+/**
+ * Retention windows for {@link ComputeConfig.hostCleanup}. Each field is an age
+ * past which the matching files are deleted; omit one to keep its default.
+ */
+export interface HostCleanupRetention {
+    /**
+     * Abandoned upload staging (`/var/ts-cloud/staging`, `/tmp/*-release.tar.gz`).
+     * Doubles as the in-flight bound for a concurrent deploy, so it cannot go
+     * below 15. @default 60
+     */
+    stagingMaxAgeMinutes?: number;
+    /** Completed `*.tar.gz` in the release artifact cache, `-mtime` days. @default 2 */
+    artifactMaxAgeDays?: number;
+    /**
+     * `.tmp` uploads to the artifact cache stranded by a dropped transfer. An
+     * upload in flight is younger than this, so it cannot go below 15. @default 60
+     */
+    artifactUploadMaxAgeMinutes?: number;
+    /** Bun's install (download) cache, `-mtime` days. @default 7 */
+    bunCacheMaxAgeDays?: number;
+    /** journald retention by age. @default 14 */
+    journalMaxAgeDays?: number;
+    /** journald retention by size. @default 512 */
+    journalMaxSizeMb?: number;
+    /** Unused docker/podman images, by age. @default 168 */
+    containerImageMaxAgeHours?: number;
+}
+/** How host cleanup reacts to a filling disk. See {@link ComputeHostCleanupConfig.pressure}. */
+export interface HostCleanupPressureConfig {
+    /**
+     * Below this root-filesystem usage the cleanup runs only the cheap rules
+     * (staging, artifacts, journald, registered paths) and skips the Bun cache
+     * walk, image prunes and `apt-get clean`. `0` always runs everything.
+     * @default 50
+     */
+    lowWaterPercent?: number;
+    /**
+     * At or above this usage the cleanup prunes with {@link escalated} windows,
+     * prints a warning, and notifies the on-box notifier if it is still above
+     * after cleaning. @default 85
+     */
+    highWaterPercent?: number;
+    /**
+     * Windows used at or above the high-water mark. Never looser than the normal
+     * ones: each field is the smaller of the two.
+     * @default { artifactMaxAgeDays: 0, bunCacheMaxAgeDays: 1, journalMaxAgeDays: 3, journalMaxSizeMb: 256, containerImageMaxAgeHours: 24 }
+     */
+    escalated?: HostCleanupRetention;
+}
+/**
+ * A directory another component writes timestamped files into, pruned by the
+ * same cleanup on the same schedule. Only direct children of `path` whose name
+ * matches `pattern` are candidates, and only on the same filesystem.
+ */
+export interface HostCleanupPathRule {
+    /** Absolute directory, e.g. `/root/rpx-backups`. Not `/`, and not under `/var/www`. */
+    path: string;
+    /** `find -name` glob for the entries to prune, e.g. `cert-backup-*`. */
+    pattern: string;
+    /** Delete entries older than this many days (`-mtime`). */
+    maxAgeDays: number;
+    /** Prune matching files, or matching directories with their contents. @default 'file' */
+    type?: 'file' | 'directory';
+}
+/** Host cleanup settings. See {@link ComputeConfig.hostCleanup}. */
+export interface ComputeHostCleanupConfig {
+    /**
+     * Install the `ts-cloud-host-cleanup.timer` systemd timer, so cleanup runs on
+     * a schedule rather than only when something deploys. `false` removes a timer
+     * an earlier deploy installed and keeps the deploy-time run. @default true
+     */
+    timer?: boolean;
+    /** systemd `OnCalendar=` expression for the timer. @default 'daily' */
+    schedule?: string;
+    /** Retention windows; omit a field to keep its default. */
+    retention?: HostCleanupRetention;
+    /**
+     * Disk-pressure thresholds. `false` runs every rule with the normal windows
+     * regardless of usage, as ts-cloud did before the thresholds existed.
+     */
+    pressure?: boolean | HostCleanupPressureConfig;
+    /** Extra directories to prune, e.g. a proxy's own backups. */
+    paths?: HostCleanupPathRule[];
 }
 /** An operator SSH key authorized on the box. See {@link ComputeConfig.sshKeys}. */
 export interface SshKeyConfig {
@@ -4129,6 +4230,25 @@ export interface CdnItemConfig {
     originShield?: boolean;
     /** AWS region used by Origin Shield. Defaults to the deployment region. */
     originShieldRegion?: string;
+    /**
+     * Secondary origin CloudFront fails over to when {@link origin} errors,
+     * e.g. a replica bucket in another region. Adds a CloudFront origin group
+     * (primary + this origin) and serves the default cache behavior from it.
+     * CloudFront only fails over GET, HEAD and OPTIONS requests. An S3 REST
+     * endpoint becomes an S3 origin; any other host an HTTPS-only custom origin.
+     *
+     * @experimental Generated from the AWS documentation; not yet verified
+     * against a live distribution.
+     */
+    failoverOrigin?: string;
+    /**
+     * Status codes from {@link origin} that trigger failover to
+     * {@link failoverOrigin}. CloudFront accepts 400, 403, 404, 416, 429, 500,
+     * 502, 503 and 504; anything else throws at template generation.
+     * @default [500, 502, 503, 504]
+     * @experimental
+     */
+    failoverStatusCodes?: number[];
     /**
      * Cache policy configuration
      */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ts-cloud/core",
   "type": "module",
-  "version": "0.16.15",
+  "version": "0.16.17",
   "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.16.15"
+    "@ts-cloud/aws-types": "0.16.17"
   },
   "devDependencies": {
     "typescript": "^7.0.2"