@constructive-io/site-deploy 0.1.0

package/deploy.js

@@ -0,0 +1,266 @@
+"use strict";
+/**
+ * The deploy pipeline.
+ *
+ * Everything below the manifest is server-owned: writing the release row fires
+ * the trigger that commits the manifest into the site's own merkle store, so
+ * the commit id this returns *is* the release — history, time travel and
+ * rollback are then pointer moves, not client bookkeeping.
+ *
+ * Ordering is the contract: bytes land before the manifest names them, and the
+ * manifest lands before anything points at it. A failure anywhere leaves the
+ * live site exactly as it was.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deploySite = deploySite;
+exports.publishCommit = publishCommit;
+const cas_upload_1 = require("./cas-upload");
+const documents_1 = require("./documents");
+const manifest_1 = require("./manifest");
+const types_1 = require("./types");
+const walk_1 = require("./walk");
+/** Preview ref names become hostname labels, so they must be one. */
+const PREVIEW_NAME_PATTERN = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+/**
+ * Deploy a build as an immutable release.
+ *
+ * Hashes every file, uploads only the bytes the server does not already have,
+ * writes one manifest — and optionally publishes it or points a preview ref at
+ * it.
+ */
+async function deploySite(options) {
+    const { api, storage = options.api, siteId, databaseId, bucketKey, scope = 'database', publish = false, preview, previewApex, concurrency = 8, batchSize = 100, retries = 2, skipIfUnchanged = false, dryRun = false, signal, onProgress, } = options;
+    const names = { ...(0, documents_1.deployNames)(scope), ...options.names };
+    if (preview !== undefined && !PREVIEW_NAME_PATTERN.test(preview)) {
+        throw new types_1.DeployError('INVALID_PREVIEW_NAME', `Preview name must be a lowercase DNS label: "${preview}"`);
+    }
+    // 1. Hash the build. Content addressing means this is also the diff key.
+    const files = [];
+    let index = 0;
+    for await (const file of iterateSource(options.source, options.ignore)) {
+        (0, cas_upload_1.throwIfAborted)(signal);
+        if (options.ignore?.(file.path))
+            continue;
+        const hashed = (0, manifest_1.hashFile)(file, options.contentTypes);
+        files.push(hashed);
+        onProgress?.({
+            type: 'hashed',
+            path: hashed.path,
+            hash: hashed.hash,
+            size: hashed.size,
+            index: index++,
+        });
+    }
+    const manifest = (0, manifest_1.buildManifest)(files);
+    // 2. The release row is UNIQUE per site, so the first deploy creates it and
+    //    every later one patches it — the caller should not have to know which.
+    const existing = await fetchExistingRelease(api, names, siteId);
+    if (skipIfUnchanged &&
+        existing?.commitId &&
+        existing.storeId &&
+        existing.manifest &&
+        (0, manifest_1.manifestsEqual)(existing.manifest, manifest)) {
+        onProgress?.({ type: 'unchanged', commitId: existing.commitId });
+        return {
+            commitId: existing.commitId,
+            storeId: existing.storeId,
+            releaseId: existing.id,
+            manifest,
+            files: manifest.file_count,
+            uploaded: 0,
+            skipped: manifest.file_count,
+            bytesUploaded: 0,
+            published: false,
+            previewUrl: null,
+            unchanged: true,
+        };
+    }
+    // 3. Register the bytes and learn which ones are missing.
+    const uploadOptions = {
+        storage,
+        mutation: names.bulkUploadMutation,
+        bucketKey,
+        batchSize,
+        concurrency,
+        retries,
+        putObject: options.putObject,
+        signal,
+    };
+    const diff = await (0, cas_upload_1.diffCas)(files, uploadOptions);
+    onProgress?.({
+        type: 'diffed',
+        files: manifest.file_count,
+        toUpload: diff.missing.length,
+        skipped: diff.deduplicated.length,
+        bytesToUpload: diff.missing.reduce((sum, entry) => sum + entry.file.size, 0),
+    });
+    if (dryRun) {
+        return {
+            commitId: existing?.commitId ?? '',
+            storeId: existing?.storeId ?? '',
+            releaseId: existing?.id ?? '',
+            manifest,
+            files: manifest.file_count,
+            uploaded: 0,
+            skipped: diff.deduplicated.length,
+            bytesUploaded: 0,
+            published: false,
+            previewUrl: null,
+            unchanged: false,
+        };
+    }
+    // 4. Upload. Any failure here throws, so the manifest is never written over
+    //    bytes that are not there.
+    let done = 0;
+    const uploadResult = await (0, cas_upload_1.uploadMissing)(diff, {
+        ...uploadOptions,
+        onUploaded: (file) => {
+            done += 1;
+            onProgress?.({
+                type: 'uploaded',
+                path: file.path,
+                key: file.key,
+                size: file.size,
+                done,
+                total: diff.missing.length,
+            });
+        },
+    });
+    // 5. Write the manifest — this is the commit.
+    const release = existing
+        ? await updateRelease(api, names, existing.id, manifest)
+        : await createRelease(api, names, siteId, databaseId, manifest);
+    onProgress?.({
+        type: 'manifest',
+        commitId: release.commitId,
+        storeId: release.storeId,
+        created: !existing,
+    });
+    const result = {
+        commitId: release.commitId,
+        storeId: release.storeId,
+        releaseId: release.id,
+        manifest,
+        files: manifest.file_count,
+        uploaded: uploadResult.uploaded,
+        skipped: uploadResult.skipped,
+        bytesUploaded: uploadResult.bytesUploaded,
+        published: false,
+        previewUrl: null,
+        unchanged: false,
+    };
+    // 6. Point things at the commit. Separate steps: a failure here leaves a
+    //    complete, retryable release rather than a half-published site.
+    if (preview !== undefined) {
+        result.previewUrl = await pointPreview(api, names, {
+            siteId,
+            name: preview,
+            commitId: release.commitId,
+            apex: previewApex,
+        });
+        onProgress?.({
+            type: 'preview',
+            name: preview,
+            commitId: release.commitId,
+            url: result.previewUrl,
+        });
+    }
+    if (publish) {
+        await publishCommit(api, names, siteId, release.commitId);
+        result.published = true;
+        onProgress?.({ type: 'published', commitId: release.commitId });
+    }
+    return result;
+}
+/** Move `site.activeCommitId` — the go-live and the rollback are one thing. */
+async function publishCommit(api, names, siteId, commitId) {
+    try {
+        await api((0, documents_1.buildPublishMutation)(names), {
+            input: { id: siteId, [names.sitePatchField]: { activeCommitId: commitId } },
+        });
+    }
+    catch (err) {
+        throw new types_1.DeployError('PUBLISH_FAILED', `Release ${commitId} was written but publishing it failed: ${(0, cas_upload_1.errorMessage)(err)}`, err);
+    }
+}
+async function* iterateSource(source, ignore) {
+    if (typeof source === 'string') {
+        yield* (0, walk_1.walkDirectory)(source, ignore);
+        return;
+    }
+    if (Symbol.asyncIterator in source) {
+        yield* source;
+        return;
+    }
+    yield* source;
+}
+async function fetchExistingRelease(api, names, siteId) {
+    const data = await api((0, documents_1.buildReleaseQuery)(names), { siteId });
+    const connection = data[names.releasesQuery];
+    return connection?.nodes?.[0] ?? null;
+}
+async function createRelease(api, names, siteId, databaseId, manifest) {
+    if (!databaseId) {
+        throw new types_1.DeployError('MISSING_DATABASE_ID', `Site ${siteId} has no release yet, so databaseId is required to create one`);
+    }
+    const data = await api((0, documents_1.buildCreateReleaseMutation)(names), {
+        input: {
+            [names.releaseInputField]: { siteId, databaseId, manifest },
+        },
+    });
+    return readWrittenRelease(data, names);
+}
+async function updateRelease(api, names, releaseId, manifest) {
+    const data = await api((0, documents_1.buildUpdateReleaseMutation)(names), {
+        input: {
+            id: releaseId,
+            [names.releasePatchField]: { manifest },
+        },
+    });
+    return readWrittenRelease(data, names);
+}
+/**
+ * Read back the versioning the trigger stamped on the row.
+ *
+ * A release without a commit is not a release: it cannot be published, rolled
+ * back to, or previewed, so a missing id is a hard failure rather than a
+ * result with empty strings in it.
+ */
+function readWrittenRelease(data, names) {
+    const mutation = (data[names.createRelease] ?? data[names.updateRelease]);
+    const row = mutation?.[names.releasePayloadField];
+    if (!row?.id || !row.commitId || !row.storeId) {
+        throw new types_1.DeployError('RELEASE_NOT_VERSIONED', 'Release row came back without a commitId/storeId — the manifest was not committed');
+    }
+    return { id: row.id, commitId: row.commitId, storeId: row.storeId };
+}
+async function pointPreview(api, names, args) {
+    try {
+        // With an apex, provision so the hostname and its route exist (idempotent
+        // and it moves the ref too); without one, just move the ref.
+        if (args.apex) {
+            const data = await api((0, documents_1.buildProvisionPreviewMutation)(names), {
+                input: {
+                    siteId: args.siteId,
+                    name: args.name,
+                    commitId: args.commitId,
+                    apex: args.apex,
+                },
+            });
+            const payload = data[names.provisionPreview];
+            const hostname = payload?.result?.domain?.hostname;
+            return hostname ? `https://${hostname}` : null;
+        }
+        await api((0, documents_1.buildSetPreviewMutation)(names), {
+            input: {
+                targetSiteId: args.siteId,
+                targetName: args.name,
+                targetCommitId: args.commitId,
+            },
+        });
+        return null;
+    }
+    catch (err) {
+        throw new types_1.DeployError('PREVIEW_FAILED', `Release ${args.commitId} was written but preview "${args.name}" could not be pointed at it: ${(0, cas_upload_1.errorMessage)(err)}`, err);
+    }
+}

package/documents.d.ts

@@ -0,0 +1,24 @@
+/**
+ * GraphQL documents and generated-name derivation.
+ *
+ * Plain strings, no graphql dependency: the same documents work through the
+ * generated SDK, urql, Apollo or a bare fetch. Every field name is generated
+ * per scope — unprefixed at the tenant (`database`) scope, `platform`-prefixed
+ * on the self-hosted lane — so the names are derived in one place here rather
+ * than spelled out at each call site.
+ */
+import type { SiteDeployNames } from './types';
+/** Derive the deploy surface's field names for a scope. */
+export declare function deployNames(scope?: 'database' | 'platform'): SiteDeployNames;
+/** Bulk presigned-upload mutation for one storage plane. */
+export declare function buildBulkUploadMutation(mutation: string): string;
+/** The site's existing release row, if it has one (the row is UNIQUE per site). */
+export declare function buildReleaseQuery(names: SiteDeployNames): string;
+export declare function buildCreateReleaseMutation(names: SiteDeployNames): string;
+export declare function buildUpdateReleaseMutation(names: SiteDeployNames): string;
+/** Publishing and rollback are the same mutation: move the pointer. */
+export declare function buildPublishMutation(names: SiteDeployNames): string;
+/** Claims (or reuses) the preview hostname and points the ref at a commit. */
+export declare function buildProvisionPreviewMutation(names: SiteDeployNames): string;
+/** Moves an existing ref without touching routing. */
+export declare function buildSetPreviewMutation(names: SiteDeployNames): string;

package/documents.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * GraphQL documents and generated-name derivation.
+ *
+ * Plain strings, no graphql dependency: the same documents work through the
+ * generated SDK, urql, Apollo or a bare fetch. Every field name is generated
+ * per scope — unprefixed at the tenant (`database`) scope, `platform`-prefixed
+ * on the self-hosted lane — so the names are derived in one place here rather
+ * than spelled out at each call site.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deployNames = deployNames;
+exports.buildBulkUploadMutation = buildBulkUploadMutation;
+exports.buildReleaseQuery = buildReleaseQuery;
+exports.buildCreateReleaseMutation = buildCreateReleaseMutation;
+exports.buildUpdateReleaseMutation = buildUpdateReleaseMutation;
+exports.buildPublishMutation = buildPublishMutation;
+exports.buildProvisionPreviewMutation = buildProvisionPreviewMutation;
+exports.buildSetPreviewMutation = buildSetPreviewMutation;
+/** Derive the deploy surface's field names for a scope. */
+function deployNames(scope = 'database') {
+    const Prefix = scope === 'platform' ? 'Platform' : '';
+    const prefix = scope === 'platform' ? 'platform' : '';
+    const lower = (name) => (prefix ? `${prefix}${name}` : lowerFirst(name));
+    return {
+        bulkUploadMutation: `upload${Prefix}Files`,
+        releasesQuery: `${lower('SiteReleases')}`,
+        createRelease: `create${Prefix}SiteRelease`,
+        releaseInputField: lower('SiteRelease'),
+        updateRelease: `update${Prefix}SiteRelease`,
+        releasePatchField: `${lower('SiteRelease')}Patch`,
+        releasePayloadField: lower('SiteRelease'),
+        updateSite: `update${Prefix}Site`,
+        sitePatchField: `${lower('Site')}Patch`,
+        sitePayloadField: lower('Site'),
+        // Preview procedures are exposed unprefixed; a plane that generates them
+        // per scope can override these two.
+        provisionPreview: 'provisionSitePreview',
+        setPreview: 'setSitePreview',
+    };
+}
+function lowerFirst(value) {
+    return value.charAt(0).toLowerCase() + value.slice(1);
+}
+/** Bulk presigned-upload mutation for one storage plane. */
+function buildBulkUploadMutation(mutation) {
+    return `
+  mutation BulkUpload($input: ${inputTypeName(mutation)}!) {
+    ${mutation}(input: $input) {
+      files {
+        uploadUrl
+        fileId
+        key
+        deduplicated
+      }
+    }
+  }
+`;
+}
+/** `uploadFiles` → `UploadFileBulkInput`, `uploadPlatformFiles` → … */
+function inputTypeName(mutation) {
+    const capitalized = mutation.charAt(0).toUpperCase() + mutation.slice(1);
+    return `${capitalized.replace(/s$/, '')}BulkInput`;
+}
+/** The site's existing release row, if it has one (the row is UNIQUE per site). */
+function buildReleaseQuery(names) {
+    return `
+  query SiteRelease($siteId: UUID!) {
+    ${names.releasesQuery}(where: { siteId: { equalTo: $siteId } }, first: 1) {
+      nodes {
+        id
+        commitId
+        storeId
+        manifest
+      }
+    }
+  }
+`;
+}
+function buildCreateReleaseMutation(names) {
+    return `
+  mutation CreateSiteRelease($input: ${typeName(names.createRelease)}Input!) {
+    ${names.createRelease}(input: $input) {
+      ${names.releasePayloadField} {
+        id
+        commitId
+        storeId
+      }
+    }
+  }
+`;
+}
+function buildUpdateReleaseMutation(names) {
+    return `
+  mutation UpdateSiteRelease($input: ${typeName(names.updateRelease)}Input!) {
+    ${names.updateRelease}(input: $input) {
+      ${names.releasePayloadField} {
+        id
+        commitId
+        storeId
+      }
+    }
+  }
+`;
+}
+/** Publishing and rollback are the same mutation: move the pointer. */
+function buildPublishMutation(names) {
+    return `
+  mutation PublishSiteRelease($input: ${typeName(names.updateSite)}Input!) {
+    ${names.updateSite}(input: $input) {
+      ${names.sitePayloadField} {
+        id
+        activeCommitId
+      }
+    }
+  }
+`;
+}
+/** Claims (or reuses) the preview hostname and points the ref at a commit. */
+function buildProvisionPreviewMutation(names) {
+    return `
+  mutation ProvisionSitePreview($input: ${typeName(names.provisionPreview)}Input!) {
+    ${names.provisionPreview}(input: $input) {
+      result {
+        id
+        previewRef
+        domain {
+          hostname
+        }
+      }
+    }
+  }
+`;
+}
+/** Moves an existing ref without touching routing. */
+function buildSetPreviewMutation(names) {
+    return `
+  mutation SetSitePreview($input: ${typeName(names.setPreview)}Input!) {
+    ${names.setPreview}(input: $input) {
+      result
+    }
+  }
+`;
+}
+function typeName(field) {
+    return field.charAt(0).toUpperCase() + field.slice(1);
+}

package/esm/cas-upload.js

@@ -0,0 +1,126 @@
+/**
+ * Content-addressed bulk upload.
+ *
+ * The generic pieces come from `@constructive-io/upload-client` (a presigned
+ * PUT); what is added here is the part a static release needs: many files in
+ * one round trip, explicit `cas/sha256/<hash>` keys, and skipping every file
+ * the server already has. That skip is the whole incremental-deploy win — a
+ * one-file change re-uploads one file however large the site is.
+ */
+import { putToPresignedUrl } from '@constructive-io/upload-client';
+import { buildBulkUploadMutation } from './documents';
+import { CAS_KEY_PATTERN } from './manifest';
+import { DeployError } from './types';
+/**
+ * Register every file and learn which bytes are missing.
+ *
+ * Batched because the server caps files per call; one failed batch fails the
+ * whole diff rather than leaving a half-registered release.
+ */
+export async function diffCas(files, options) {
+    const mutation = buildBulkUploadMutation(options.mutation);
+    const missing = [];
+    const deduplicated = [];
+    for (let offset = 0; offset < files.length; offset += options.batchSize) {
+        throwIfAborted(options.signal);
+        const batch = files.slice(offset, offset + options.batchSize);
+        const data = await options.storage(mutation, {
+            input: {
+                bucketKey: options.bucketKey,
+                files: batch.map((file) => ({
+                    contentHash: file.hash,
+                    contentType: file.contentType,
+                    size: file.size,
+                    filename: file.path.slice(file.path.lastIndexOf('/') + 1),
+                    key: file.key,
+                })),
+            },
+        });
+        const payload = (data[options.mutation] ?? null);
+        const results = payload?.files;
+        if (!results || results.length !== batch.length) {
+            throw new DeployError('UPLOAD_FAILED', `${options.mutation} returned ${results?.length ?? 0} results for ${batch.length} files`);
+        }
+        results.forEach((result, index) => {
+            const file = batch[index];
+            // The server does not enforce the CAS key form yet, so a mismatch here
+            // would publish a manifest pointing at bytes nobody can serve.
+            if (result.key !== file.key || !CAS_KEY_PATTERN.test(result.key)) {
+                throw new DeployError('KEY_MISMATCH', `Expected key "${file.key}" for "${file.path}", server returned "${result.key}"`);
+            }
+            if (result.deduplicated) {
+                deduplicated.push(file);
+                return;
+            }
+            if (!result.uploadUrl) {
+                throw new DeployError('UPLOAD_FAILED', `No upload URL for "${file.path}" and deduplicated=false`);
+            }
+            missing.push({ file, uploadUrl: result.uploadUrl });
+        });
+    }
+    return { missing, deduplicated };
+}
+/**
+ * PUT the missing bytes.
+ *
+ * Any file that cannot be uploaded after its retries aborts the deploy: a
+ * manifest written over a partial upload is a site with holes in it.
+ */
+export async function uploadMissing(diff, options) {
+    const put = options.putObject ?? defaultPut;
+    let bytesUploaded = 0;
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            throwIfAborted(options.signal);
+            const index = next++;
+            if (index >= diff.missing.length)
+                return;
+            const { file, uploadUrl } = diff.missing[index];
+            await withRetries(() => put(uploadUrl, file.bytes, file.contentType, options.signal), options.retries, file.path, options.signal);
+            bytesUploaded += file.size;
+            options.onUploaded?.(file);
+        }
+    };
+    const workers = Math.max(1, Math.min(options.concurrency, diff.missing.length));
+    await Promise.all(Array.from({ length: workers }, worker));
+    return {
+        uploaded: diff.missing.length,
+        skipped: diff.deduplicated.length,
+        bytesUploaded,
+    };
+}
+const defaultPut = async (url, body, contentType, signal) => {
+    // A fresh copy: putToPresignedUrl takes a BodyInit, and a Uint8Array view
+    // over a pooled Buffer would send the whole pool.
+    const buffer = body.slice().buffer;
+    await putToPresignedUrl(url, buffer, contentType, signal);
+};
+async function withRetries(attempt, retries, path, signal) {
+    let lastError;
+    for (let tries = 0; tries <= retries; tries++) {
+        throwIfAborted(signal);
+        try {
+            await attempt();
+            return;
+        }
+        catch (err) {
+            lastError = err;
+            if (tries === retries)
+                break;
+            await delay(2 ** tries * 250);
+        }
+    }
+    throw new DeployError('UPLOAD_FAILED', `Upload of "${path}" failed after ${retries + 1} attempt(s): ${errorMessage(lastError)}`, lastError);
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw new DeployError('ABORTED', 'Deploy was cancelled');
+    }
+}
+export function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/esm/content-type.js

@@ -0,0 +1,57 @@
+/**
+ * Extension → MIME mapping for static builds.
+ *
+ * Deliberately small: it covers what a site generator emits. Anything else
+ * falls back to `application/octet-stream` rather than being guessed — the
+ * manifest's `content_type` is what the edge serves verbatim.
+ */
+export const DEFAULT_CONTENT_TYPE = 'application/octet-stream';
+const CONTENT_TYPES = {
+    avif: 'image/avif',
+    css: 'text/css; charset=utf-8',
+    csv: 'text/csv; charset=utf-8',
+    eot: 'application/vnd.ms-fontobject',
+    gif: 'image/gif',
+    htm: 'text/html; charset=utf-8',
+    html: 'text/html; charset=utf-8',
+    ico: 'image/x-icon',
+    jpeg: 'image/jpeg',
+    jpg: 'image/jpeg',
+    js: 'text/javascript; charset=utf-8',
+    json: 'application/json; charset=utf-8',
+    map: 'application/json; charset=utf-8',
+    md: 'text/markdown; charset=utf-8',
+    mjs: 'text/javascript; charset=utf-8',
+    mp3: 'audio/mpeg',
+    mp4: 'video/mp4',
+    otf: 'font/otf',
+    pdf: 'application/pdf',
+    png: 'image/png',
+    svg: 'image/svg+xml',
+    ttf: 'font/ttf',
+    txt: 'text/plain; charset=utf-8',
+    wasm: 'application/wasm',
+    webm: 'video/webm',
+    webmanifest: 'application/manifest+json',
+    webp: 'image/webp',
+    woff: 'font/woff',
+    woff2: 'font/woff2',
+    xml: 'application/xml',
+    yaml: 'text/yaml; charset=utf-8',
+    yml: 'text/yaml; charset=utf-8',
+    zip: 'application/zip',
+};
+/**
+ * Resolve the content type of a logical path.
+ *
+ * @param path - Logical path (`assets/app.js`)
+ * @param overrides - Extra or overriding mappings, keyed without the dot
+ */
+export function contentTypeFor(path, overrides) {
+    const base = path.slice(path.lastIndexOf('/') + 1);
+    const dot = base.lastIndexOf('.');
+    if (dot <= 0)
+        return DEFAULT_CONTENT_TYPE;
+    const ext = base.slice(dot + 1).toLowerCase();
+    return overrides?.[ext] ?? CONTENT_TYPES[ext] ?? DEFAULT_CONTENT_TYPE;
+}