@constructive-io/site-deploy 0.1.0

package/manifest.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Manifest construction: the site-specific half of a deploy.
+ *
+ * The bytes of a build are content-addressed and say nothing about how the
+ * site is served; the manifest is what turns a bag of hashes into a site, by
+ * mapping each logical path to the hash, content type and size the edge
+ * serves for it.
+ */
+import type { DeployFile, ReleaseManifest } from './types';
+/** Prefix every file's bytes are stored under, in the site's own bucket. */
+export declare const CAS_PREFIX = "cas/sha256/";
+/** The one legal shape of a CAS key. */
+export declare const CAS_KEY_PATTERN: RegExp;
+/** The content-addressed bucket key holding the bytes with this hash. */
+export declare function casKey(hash: string): string;
+/** SHA-256 of some bytes, hex — the CAS address and the served ETag. */
+export declare function hashBytes(bytes: Uint8Array): string;
+/**
+ * Normalize a logical path to the form the gateway looks up.
+ *
+ * Windows separators become `/` and a leading `./` or `/` is dropped, so the
+ * same build deploys identically from any OS. Anything that would escape the
+ * site root or collide with the CAS namespace is a hard error — a silently
+ * dropped file is a silently broken site.
+ */
+export declare function normalizePath(path: string): string;
+/** A hashed file, ready to be uploaded and named in a manifest. */
+export interface HashedFile {
+    /** Normalized logical path. */
+    path: string;
+    /** Content-addressed bucket key for these bytes. */
+    key: string;
+    hash: string;
+    contentType: string;
+    size: number;
+    bytes: Uint8Array;
+}
+/** Hash one file and resolve its content type. */
+export declare function hashFile(file: DeployFile, contentTypes?: Record<string, string>): HashedFile;
+/**
+ * Build the release manifest from hashed files.
+ *
+ * `file_count`/`total_bytes` are derived here rather than trusted from a
+ * caller, so they can never disagree with `files`.
+ */
+export declare function buildManifest(files: Iterable<HashedFile>): ReleaseManifest;
+/** Whether two manifests would serve byte-identical sites. */
+export declare function manifestsEqual(a: ReleaseManifest, b: ReleaseManifest): boolean;

package/manifest.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Manifest construction: the site-specific half of a deploy.
+ *
+ * The bytes of a build are content-addressed and say nothing about how the
+ * site is served; the manifest is what turns a bag of hashes into a site, by
+ * mapping each logical path to the hash, content type and size the edge
+ * serves for it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CAS_KEY_PATTERN = exports.CAS_PREFIX = void 0;
+exports.casKey = casKey;
+exports.hashBytes = hashBytes;
+exports.normalizePath = normalizePath;
+exports.hashFile = hashFile;
+exports.buildManifest = buildManifest;
+exports.manifestsEqual = manifestsEqual;
+const sha2_1 = require("@decryption/hashes/sha2");
+const utils_1 = require("@decryption/hashes/utils");
+const content_type_1 = require("./content-type");
+const types_1 = require("./types");
+/** Prefix every file's bytes are stored under, in the site's own bucket. */
+exports.CAS_PREFIX = 'cas/sha256/';
+/** The one legal shape of a CAS key. */
+exports.CAS_KEY_PATTERN = /^cas\/sha256\/[0-9a-f]{64}$/;
+/** The content-addressed bucket key holding the bytes with this hash. */
+function casKey(hash) {
+    return `${exports.CAS_PREFIX}${hash}`;
+}
+/** SHA-256 of some bytes, hex — the CAS address and the served ETag. */
+function hashBytes(bytes) {
+    return (0, utils_1.bytesToHex)((0, sha2_1.sha256)(bytes));
+}
+/**
+ * Normalize a logical path to the form the gateway looks up.
+ *
+ * Windows separators become `/` and a leading `./` or `/` is dropped, so the
+ * same build deploys identically from any OS. Anything that would escape the
+ * site root or collide with the CAS namespace is a hard error — a silently
+ * dropped file is a silently broken site.
+ */
+function normalizePath(path) {
+    const normalized = path.replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
+    if (!normalized) {
+        throw new types_1.DeployError('INVALID_PATH', `Empty logical path (from "${path}")`);
+    }
+    if (normalized.split('/').some((segment) => segment === '..' || segment === '.')) {
+        throw new types_1.DeployError('INVALID_PATH', `Logical path must not contain "." or ".." segments: "${path}"`);
+    }
+    if (normalized.startsWith(exports.CAS_PREFIX)) {
+        throw new types_1.DeployError('INVALID_PATH', `Logical path must not start with "${exports.CAS_PREFIX}" (that is the byte namespace): "${path}"`);
+    }
+    return normalized;
+}
+/** Hash one file and resolve its content type. */
+function hashFile(file, contentTypes) {
+    const path = normalizePath(file.path);
+    const hash = hashBytes(file.bytes);
+    return {
+        path,
+        key: casKey(hash),
+        hash,
+        contentType: file.contentType ?? (0, content_type_1.contentTypeFor)(path, contentTypes),
+        size: file.bytes.byteLength,
+        bytes: file.bytes,
+    };
+}
+/**
+ * Build the release manifest from hashed files.
+ *
+ * `file_count`/`total_bytes` are derived here rather than trusted from a
+ * caller, so they can never disagree with `files`.
+ */
+function buildManifest(files) {
+    const entries = {};
+    let totalBytes = 0;
+    let count = 0;
+    for (const file of files) {
+        if (entries[file.path]) {
+            throw new types_1.DeployError('INVALID_PATH', `Duplicate logical path: "${file.path}"`);
+        }
+        entries[file.path] = {
+            hash: file.hash,
+            content_type: file.contentType,
+            size: file.size,
+        };
+        totalBytes += file.size;
+        count += 1;
+    }
+    if (count === 0) {
+        throw new types_1.DeployError('EMPTY_SOURCE', 'Refusing to release an empty manifest');
+    }
+    return { files: entries, file_count: count, total_bytes: totalBytes };
+}
+/** Whether two manifests would serve byte-identical sites. */
+function manifestsEqual(a, b) {
+    const aPaths = Object.keys(a.files);
+    const bPaths = Object.keys(b.files);
+    if (aPaths.length !== bPaths.length)
+        return false;
+    return aPaths.every((path) => {
+        const left = a.files[path];
+        const right = b.files[path];
+        return (right !== undefined &&
+            left.hash === right.hash &&
+            left.content_type === right.content_type &&
+            left.size === right.size);
+    });
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@constructive-io/site-deploy",
+  "version": "0.1.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "Deploy a static build as an immutable Constructive release: hash, content-addressed upload with dedupe, one manifest commit, publish/rollback and preview refs",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "@constructive-io/upload-client": "^0.27.1",
+    "@decryption/hashes": "^0.4.0"
+  },
+  "devDependencies": {
+    "makage": "^0.3.0"
+  },
+  "keywords": [
+    "constructive",
+    "static-site",
+    "deploy",
+    "release",
+    "preview",
+    "content-addressed"
+  ],
+  "gitHead": "a0b996a60ff2e9b88ade4362ad494cfa7b498ab6"
+}

package/types.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Types for the site deploy pipeline.
+ *
+ * A deploy is bytes plus one manifest: every file's bytes live in the site's
+ * bucket at `cas/sha256/<hash>`, and one `siteRelease` row maps logical paths
+ * to those hashes. Writing that row commits it into the site's own merkle
+ * store, so the returned commit id *is* the release id.
+ */
+/**
+ * Executes a GraphQL document and returns its `data`, throwing on GraphQL
+ * errors. The only integration point with a GraphQL client — works with the
+ * generated SDK, urql, Apollo or plain fetch.
+ */
+export type GraphQLExecutor = (query: string, variables: Record<string, unknown>) => Promise<Record<string, unknown>>;
+/** One file of a build, as the caller hands it over. */
+export interface DeployFile {
+    /** Logical path served by the site, POSIX-relative (`assets/app.js`). */
+    path: string;
+    /** The file's bytes. */
+    bytes: Uint8Array;
+    /** MIME type; inferred from the extension when omitted. */
+    contentType?: string;
+}
+/** A build to deploy: a directory path (Node) or the files themselves. */
+export type DeploySource = string | Iterable<DeployFile> | AsyncIterable<DeployFile>;
+/** One manifest entry: where the bytes are and how to serve them. */
+export interface ManifestEntry {
+    /** SHA-256 of the bytes, hex — the CAS address and the served ETag. */
+    hash: string;
+    content_type: string;
+    size: number;
+}
+/** The release manifest, exactly as the gateway reads it. */
+export interface ReleaseManifest {
+    files: Record<string, ManifestEntry>;
+    file_count: number;
+    total_bytes: number;
+}
+/**
+ * GraphQL field names of one scope's deploy surface.
+ *
+ * Every name is generated per scope: unprefixed for the tenant (`database`)
+ * scope, `platform`-prefixed for the self-hosted lane. Override individual
+ * names when a plane's inflection differs.
+ */
+export interface SiteDeployNames {
+    /** Bulk presigned-upload mutation, e.g. `uploadFiles`. */
+    bulkUploadMutation: string;
+    /** Site release collection query, e.g. `siteReleases`. */
+    releasesQuery: string;
+    /** Create mutation for the release row, e.g. `createSiteRelease`. */
+    createRelease: string;
+    /** Input field holding the new row, e.g. `siteRelease`. */
+    releaseInputField: string;
+    /** Update mutation for the release row, e.g. `updateSiteRelease`. */
+    updateRelease: string;
+    /** Patch field on the update input, e.g. `siteReleasePatch`. */
+    releasePatchField: string;
+    /** Payload field holding the row, e.g. `siteRelease`. */
+    releasePayloadField: string;
+    /** Site update mutation, e.g. `updateSite`. */
+    updateSite: string;
+    /** Patch field on the site update input, e.g. `sitePatch`. */
+    sitePatchField: string;
+    /** Payload field holding the site, e.g. `site`. */
+    sitePayloadField: string;
+    /** Preview provisioning mutation, e.g. `provisionSitePreview`. */
+    provisionPreview: string;
+    /** Preview ref move mutation, e.g. `setSitePreview`. */
+    setPreview: string;
+}
+/** Progress events, in the order a deploy emits them. */
+export type DeployProgress = {
+    type: 'hashed';
+    path: string;
+    hash: string;
+    size: number;
+    index: number;
+} | {
+    type: 'diffed';
+    files: number;
+    toUpload: number;
+    skipped: number;
+    bytesToUpload: number;
+} | {
+    type: 'uploaded';
+    path: string;
+    key: string;
+    size: number;
+    done: number;
+    total: number;
+} | {
+    type: 'manifest';
+    commitId: string;
+    storeId: string;
+    created: boolean;
+} | {
+    type: 'unchanged';
+    commitId: string;
+} | {
+    type: 'published';
+    commitId: string;
+} | {
+    type: 'preview';
+    name: string;
+    commitId: string;
+    url: string | null;
+};
+/** PUT bytes to a presigned URL. Injectable so tests need no network. */
+export type PutObject = (url: string, body: Uint8Array, contentType: string, signal?: AbortSignal) => Promise<void>;
+export interface DeploySiteOptions {
+    /** Executor for the tenant API target (releases, sites, previews). */
+    api: GraphQLExecutor;
+    /** Executor for the storage target. Defaults to `api`. */
+    storage?: GraphQLExecutor;
+    /** The site to deploy to. */
+    siteId: string;
+    /**
+     * Database that owns the release row. Required on the first deploy of a
+     * site at `database` scope, where the column is NOT NULL.
+     */
+    databaseId?: string;
+    /** Bucket key of the site's bucket (`allow_custom_keys` must be on). */
+    bucketKey: string;
+    /** The build: a directory path, or the files themselves. */
+    source: DeploySource;
+    /** Which generated surface to talk to. Defaults to `database`. */
+    scope?: 'database' | 'platform';
+    /** Override individual generated field names. */
+    names?: Partial<SiteDeployNames>;
+    /** Move `site.activeCommitId` to the new release when it lands. */
+    publish?: boolean;
+    /** Also point `preview/<name>` at the new release. */
+    preview?: string;
+    /** Apex for a newly provisioned preview hostname. */
+    previewApex?: string;
+    /** Parallel PUTs. Defaults to 8. */
+    concurrency?: number;
+    /** Files per upload mutation. Defaults to 100 (the server's batch cap). */
+    batchSize?: number;
+    /** Retries per PUT on a network/5xx failure. Defaults to 2. */
+    retries?: number;
+    /** Return the live release untouched when the tree already matches it. */
+    skipIfUnchanged?: boolean;
+    /** Hash and diff only: upload nothing, write no manifest. */
+    dryRun?: boolean;
+    /** Skip paths — receives the logical path. */
+    ignore?: (path: string) => boolean;
+    /** Extra or overriding extension → MIME mappings (keys without the dot). */
+    contentTypes?: Record<string, string>;
+    /** Progress callback. */
+    onProgress?: (event: DeployProgress) => void;
+    /** Cancellation. */
+    signal?: AbortSignal;
+    /** PUT implementation. Defaults to a presigned fetch PUT. */
+    putObject?: PutObject;
+}
+export interface DeploySiteResult {
+    /** The release commit — the immutable id of this deploy. */
+    commitId: string;
+    /** Merkle store holding the site's release history. */
+    storeId: string;
+    /** The `siteRelease` row id. */
+    releaseId: string;
+    /** The manifest that was committed. */
+    manifest: ReleaseManifest;
+    /** Files in the manifest. */
+    files: number;
+    /** Files whose bytes were PUT. */
+    uploaded: number;
+    /** Files the server already had. */
+    skipped: number;
+    /** Bytes actually PUT. */
+    bytesUploaded: number;
+    /** Whether `site.activeCommitId` now points at this release. */
+    published: boolean;
+    /** Preview hostname, when a preview was provisioned with an apex. */
+    previewUrl: string | null;
+    /** True when `skipIfUnchanged` matched and nothing was written. */
+    unchanged: boolean;
+}
+export type DeployErrorCode = 'ABORTED' | 'EMPTY_SOURCE' | 'GRAPHQL_ERROR' | 'INVALID_PATH' | 'INVALID_PREVIEW_NAME' | 'KEY_MISMATCH' | 'MISSING_DATABASE_ID' | 'PREVIEW_FAILED' | 'PUBLISH_FAILED' | 'RELEASE_NOT_VERSIONED' | 'UPLOAD_FAILED';
+/**
+ * A deploy failure. Never swallowed and never partially reported: if this
+ * throws before the manifest write, production is untouched.
+ */
+export declare class DeployError extends Error {
+    readonly code: DeployErrorCode;
+    readonly cause?: unknown;
+    constructor(code: DeployErrorCode, message: string, cause?: unknown);
+}

package/types.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Types for the site deploy pipeline.
+ *
+ * A deploy is bytes plus one manifest: every file's bytes live in the site's
+ * bucket at `cas/sha256/<hash>`, and one `siteRelease` row maps logical paths
+ * to those hashes. Writing that row commits it into the site's own merkle
+ * store, so the returned commit id *is* the release id.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeployError = void 0;
+/**
+ * A deploy failure. Never swallowed and never partially reported: if this
+ * throws before the manifest write, production is untouched.
+ */
+class DeployError extends Error {
+    code;
+    cause;
+    constructor(code, message, cause) {
+        super(message);
+        this.name = 'DeployError';
+        this.code = code;
+        this.cause = cause;
+    }
+}
+exports.DeployError = DeployError;

package/walk.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Reading a build off disk.
+ *
+ * Node-only and loaded lazily, so the package stays usable in a browser (a UI
+ * that already holds the built files in memory passes them directly instead of
+ * a directory path).
+ */
+import type { DeployFile } from './types';
+/**
+ * Yield every file under `dir` with its POSIX path relative to `dir`.
+ *
+ * Dotfiles are included: a static build legitimately ships `.well-known/…`,
+ * and dropping files by a rule the caller cannot see is how a deploy silently
+ * loses a route. Use `ignore` to exclude paths explicitly.
+ */
+export declare function walkDirectory(dir: string, ignore?: (path: string) => boolean): AsyncGenerator<DeployFile>;

package/walk.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Reading a build off disk.
+ *
+ * Node-only and loaded lazily, so the package stays usable in a browser (a UI
+ * that already holds the built files in memory passes them directly instead of
+ * a directory path).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.walkDirectory = walkDirectory;
+const types_1 = require("./types");
+/**
+ * Yield every file under `dir` with its POSIX path relative to `dir`.
+ *
+ * Dotfiles are included: a static build legitimately ships `.well-known/…`,
+ * and dropping files by a rule the caller cannot see is how a deploy silently
+ * loses a route. Use `ignore` to exclude paths explicitly.
+ */
+async function* walkDirectory(dir, ignore) {
+    const { readdir, readFile } = await loadFs();
+    const { join, posix } = await loadPath();
+    async function* walk(absolute, prefix) {
+        const entries = await readdir(absolute, { withFileTypes: true });
+        for (const entry of entries) {
+            const logical = prefix ? posix.join(prefix, entry.name) : entry.name;
+            if (ignore?.(logical))
+                continue;
+            const child = join(absolute, entry.name);
+            if (entry.isDirectory()) {
+                yield* walk(child, logical);
+                continue;
+            }
+            // Symlinks to files are followed by readFile; anything that is neither a
+            // file nor a directory (socket, fifo) has no meaning in a static site.
+            if (!entry.isFile() && !entry.isSymbolicLink())
+                continue;
+            yield { path: logical, bytes: new Uint8Array(await readFile(child)) };
+        }
+    }
+    yield* walk(dir, '');
+}
+async function loadFs() {
+    try {
+        return await Promise.resolve().then(() => __importStar(require('fs/promises')));
+    }
+    catch (err) {
+        throw new types_1.DeployError('INVALID_PATH', 'Deploying from a directory path requires Node; pass the files directly instead', err);
+    }
+}
+async function loadPath() {
+    return Promise.resolve().then(() => __importStar(require('path')));
+}