canopycms 0.7.1 → 0.8.1

package/dist/branch-schema-cache.d.ts

@@ -33,8 +33,15 @@ export interface ResolvedBranchSchema {
     issues: SchemaIssue[];
 }
 /**
- * Per-branch schema cache: one file in {@link schemaCacheDir} with no in-memory
- * layer, so it stays coherent across Lambda invocations.
+ * Per-branch schema cache: one file in {@link schemaCacheDir}, the only state
+ * shared across processes. Each process keeps the entries it parsed or wrote,
+ * keyed by the file's identity, so it parses an unchanged file once while the
+ * entry stays in its size-bounded memo. Every call still opens the file and
+ * runs every freshness check below on the entry, and the file is only ever
+ * replaced by rename (see {@link fileIdentity}), so a process is as fresh as if
+ * it re-read the file. The identity is fstat'ed on an open handle because NFS
+ * revalidates attributes on open (close-to-open), while a bare stat() may
+ * answer from its attribute cache.
  *
  * Freshness follows the generation-marker protocol owned by
  * resource-generation.ts, and this is one of that protocol's durable-snapshot
@@ -58,6 +65,16 @@ export interface ResolvedBranchSchema {
 export declare class BranchSchemaCache {
     /** Tracks when we last checked mtimes per contentRoot, to debounce rapid requests */
     private lastMtimeCheck;
+    /** Parsed cache files, by absolute path; see the class doc. */
+    private readonly snapshots;
+    /**
+     * In-flight resolves of the checkout during a build, by content root and registry. A build
+     * reads a checkout that does not change under it, so those two are its whole input and the
+     * result needs no revalidation. Only {@link isBuildMode}: `CANOPY_BUILD_MODE` is a build and
+     * script switch, and a long-lived process setting it would see a schema edit only on
+     * restart. A rejected resolve is dropped, so a strict-mode failure fails every read.
+     */
+    private readonly buildResolves;
     private readonly devMode;
     constructor(mode?: OperatingMode);
     /**
@@ -79,6 +96,9 @@ export declare class BranchSchemaCache {
      */
     protected resolveFresh(contentRoot: string, entrySchemaRegistry: EntrySchemaRegistry, unknownSchema: UnknownSchemaPolicy): Promise<SchemaResolutionResult>;
     private loadFromCacheOrResolve;
+    private resolveForBuild;
+    /** The parsed cache file, or null when it is absent or unreadable. */
+    private readSnapshot;
     /**
      * Resolve the schema fresh from disk and persist it (subject to the
      * skip-persist rule below), UNCONDITIONALLY -- never through the cache-read

package/dist/branch-schema-cache.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { LRUCache } from 'lru-cache';
 import { resolveSchema, isValidSchema } from './schema/resolver.js';
 import { registryFingerprint } from './schema/registry-fingerprint.js';
 import { flattenSchema } from './config/flatten.js';
@@ -13,6 +14,8 @@ import { canopyLogWarn } from './utils/logger.js';
 const SCHEMA_CACHE_VERSION = 4;
 /** Minimum interval between mtime staleness checks (ms) */
 const MTIME_CHECK_DEBOUNCE_MS = 1000;
+/** Cap on the parsed snapshots one process keeps, counted in bytes of their files. */
+const SNAPSHOT_MEMO_MAX_BYTES = 64 * 1024 * 1024;
 /** File name of the schema cache inside {@link schemaCacheDir}. */
 export const SCHEMA_CACHE_FILE = 'schema-cache.json';
 /** resource-generation.ts resource key for the schema cache's marker. */
@@ -65,6 +68,13 @@ async function isStaleByMtime(dir, cachedAt) {
     }
     return false;
 }
+/**
+ * Names one version of a file. Every write of the schema cache renames a new temp file into
+ * place, so a rewrite always changes the inode, whatever token or content it carries.
+ */
+function fileIdentity(stat) {
+    return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}`;
+}
 /**
  * Directory holding a branch's schema cache: `{branchRoot}/.git/canopycms` when
  * the branch root is a full clone (every canopycms branch workspace is), else
@@ -80,8 +90,15 @@ async function schemaCacheDir(branchRoot) {
     return isClone ? path.join(gitDir, 'canopycms') : path.join(branchRoot, CANOPY_META_DIR);
 }
 /**
- * Per-branch schema cache: one file in {@link schemaCacheDir} with no in-memory
- * layer, so it stays coherent across Lambda invocations.
+ * Per-branch schema cache: one file in {@link schemaCacheDir}, the only state
+ * shared across processes. Each process keeps the entries it parsed or wrote,
+ * keyed by the file's identity, so it parses an unchanged file once while the
+ * entry stays in its size-bounded memo. Every call still opens the file and
+ * runs every freshness check below on the entry, and the file is only ever
+ * replaced by rename (see {@link fileIdentity}), so a process is as fresh as if
+ * it re-read the file. The identity is fstat'ed on an open handle because NFS
+ * revalidates attributes on open (close-to-open), while a bare stat() may
+ * answer from its attribute cache.
  *
  * Freshness follows the generation-marker protocol owned by
  * resource-generation.ts, and this is one of that protocol's durable-snapshot
@@ -106,6 +123,19 @@ export class BranchSchemaCache {
     constructor(mode = 'prod') {
         /** Tracks when we last checked mtimes per contentRoot, to debounce rapid requests */
         this.lastMtimeCheck = new Map();
+        /** Parsed cache files, by absolute path; see the class doc. */
+        this.snapshots = new LRUCache({
+            maxSize: SNAPSHOT_MEMO_MAX_BYTES,
+            sizeCalculation: (snapshot) => Math.max(1, snapshot.bytes),
+        });
+        /**
+         * In-flight resolves of the checkout during a build, by content root and registry. A build
+         * reads a checkout that does not change under it, so those two are its whole input and the
+         * result needs no revalidation. Only {@link isBuildMode}: `CANOPY_BUILD_MODE` is a build and
+         * script switch, and a long-lived process setting it would see a schema edit only on
+         * restart. A rejected resolve is dropped, so a strict-mode failure fails every read.
+         */
+        this.buildResolves = new Map();
         this.devMode = mode === 'dev';
     }
     /**
@@ -135,17 +165,12 @@ export class BranchSchemaCache {
     async loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName) {
         const contentRoot = path.join(branchRoot, contentRootName);
         const fromCheckout = this.readsCheckout(branchRoot);
+        if (fromCheckout && isBuildMode()) {
+            return this.resolveForBuild(branchRoot, entrySchemaRegistry, contentRootName);
+        }
         if (!fromCheckout) {
             const cachePath = path.join(await schemaCacheDir(branchRoot), SCHEMA_CACHE_FILE);
-            let cacheData = null;
-            try {
-                const cacheContent = await fs.readFile(cachePath, 'utf-8');
-                cacheData = JSON.parse(cacheContent);
-            }
-            catch {
-                // Cache doesn't exist or can't be read
-                cacheData = null;
-            }
+            let cacheData = await this.readSnapshot(cachePath);
             // Strict version check, not truthiness: a snapshot from an older version
             // left on EFS by a rolling deploy has no `generation` field, and an
             // `undefined` token breaks the freshness comparison below.
@@ -187,6 +212,44 @@ export class BranchSchemaCache {
             fromCheckout,
         });
     }
+    resolveForBuild(branchRoot, entrySchemaRegistry, contentRootName) {
+        const key = `${path.resolve(branchRoot, contentRootName)}\0${registryFingerprint(entrySchemaRegistry)}`;
+        let pending = this.buildResolves.get(key);
+        if (!pending) {
+            pending = this.resolveFreshAndPersist(branchRoot, entrySchemaRegistry, contentRootName, {
+                fromCheckout: true,
+            });
+            this.buildResolves.set(key, pending);
+            pending.catch(() => this.buildResolves.delete(key));
+        }
+        return pending;
+    }
+    /** The parsed cache file, or null when it is absent or unreadable. */
+    async readSnapshot(cachePath) {
+        let handle;
+        try {
+            handle = await fs.open(cachePath, 'r');
+        }
+        catch {
+            return null;
+        }
+        try {
+            const stat = await handle.stat({ bigint: true });
+            const identity = fileIdentity(stat);
+            const memo = this.snapshots.get(cachePath);
+            if (memo?.identity === identity)
+                return memo.entry;
+            const entry = JSON.parse(await fs.readFile(handle, 'utf-8'));
+            this.snapshots.set(cachePath, { identity, entry, bytes: Number(stat.size) });
+            return entry;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            await handle.close().catch(() => { });
+        }
+    }
     /**
      * Resolve the schema fresh from disk and persist it (subject to the
      * skip-persist rule below), UNCONDITIONALLY -- never through the cache-read
@@ -241,16 +304,29 @@ export class BranchSchemaCache {
                 };
                 // Temp file then rename, with the temp file unlinked on a failed
                 // rename so a transient error leaves no stray `.tmp` beside the cache.
+                // The memo is seeded from the temp file's own identity, which the
+                // rename keeps: stat'ing cachePath afterwards could see a concurrent
+                // writer's file and pair it with this entry. It holds the parsed body,
+                // as every reader does, not the resolver's objects, which alias the
+                // registry and keep values JSON changes or drops.
                 await fs.mkdir(cacheDir, { recursive: true });
                 const tmpPath = path.join(cacheDir, `schema-cache.tmp.${Date.now()}.${Math.random()}.json`);
-                await fs.writeFile(tmpPath, JSON.stringify(newCache, null, 2), 'utf-8');
+                const body = JSON.stringify(newCache);
+                let identity;
                 try {
+                    await fs.writeFile(tmpPath, body, 'utf-8');
+                    identity = fileIdentity(await fs.stat(tmpPath, { bigint: true }));
                     await fs.rename(tmpPath, cachePath);
                 }
                 catch (err) {
                     await fs.unlink(tmpPath).catch(() => { });
                     throw err;
                 }
+                this.snapshots.set(cachePath, {
+                    identity,
+                    entry: JSON.parse(body),
+                    bytes: Buffer.byteLength(body),
+                });
             }
             // else: the marker read failed for a reason other than "never bumped",
             // so no token can be attributed to this resolve, and a snapshot stamped

package/dist/branch-workspace.js

@@ -1,8 +1,9 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { BranchPathError, isSettingsBranchName, resolveBranchPath } from './paths/index.js';
+import { BranchPathError, isSettingsBranchName, parseBranchRef, resolveBranchPath } from './paths/index.js';
 import { buildInitialBranchMetadata, loadBranchContext } from './branch-metadata.js';
 import { BRANCH_META_DIR, BRANCH_META_FILE, readBranchMetadataFile } from './branch-metadata-file.js';
+import { shortNameOf } from './branch-param.js';
 import { BranchRegistry } from './branch-registry.js';
 import { BranchDirOccupiedError, BranchProvisioningBusyError, CREATE_RESIDUE_MIN_QUIET_MS, classifyFinalDir, removeLeftoverDir, lockBranchName, publishStaging, quietAgeMs, stageBranchWorkspace, } from './branch-provisioning.js';
 import { recordSparseCone, sparseConeFor } from './branch-sparse.js';
@@ -49,12 +50,17 @@ export class BranchWorkspaceManager {
         if (isSettingsBranchName(options.branchName, operatingStrategy(options.mode).getSettingsBranchName(this.config))) {
             throw new BranchPathError('Settings branches are not content branches');
         }
-        const { branchRoot, baseRoot, branchName: safeName } = resolveBranchPath(options);
+        // The name reaches git and branch.json as given; only the directory is sanitized.
+        const named = parseBranchRef(options.branchName);
+        if (!named.ok)
+            throw new BranchPathError(named.error);
+        const { branchRoot, baseRoot } = resolveBranchPath(options);
         const paths = {
             branchRoot,
             baseRoot,
             dirName: path.basename(branchRoot),
-            safeName,
+            ref: options.branchName,
+            shortName: shortNameOf({ ...this.config, mode: options.mode }, options.branchName),
         };
         const existing = await readBranchMetadataFile(branchRoot);
         if (existing) {
@@ -73,7 +79,7 @@ export class BranchWorkspaceManager {
         }
     }
     async provisionUnshared(options, paths) {
-        const { branchRoot, baseRoot, dirName } = paths;
+        const { branchRoot, baseRoot, dirName, shortName } = paths;
         await fs.mkdir(baseRoot, { recursive: true });
         // Resolve the fork point once so the clone and the recorded metadata agree, and the remote
         // before any clone is paid for.
@@ -93,7 +99,7 @@ export class BranchWorkspaceManager {
         });
         const metadata = buildInitialBranchMetadata({
             branch: {
-                name: paths.safeName,
+                name: paths.ref,
                 title: options.title,
                 description: options.description,
                 access: options.access,
@@ -107,7 +113,7 @@ export class BranchWorkspaceManager {
         if (state.kind === 'live' || state.kind === 'corrupt')
             return this.existing(paths);
         if (state.kind === 'protected')
-            throw new BranchProvisioningBusyError(dirName);
+            throw new BranchProvisioningBusyError(dirName, shortName);
         if (state.kind === 'foreign') {
             // dev's CLI sync builds a branch workspace by `git init` and real commits, with no
             // remote and no branch.json; it is adopted where it is.
@@ -116,7 +122,7 @@ export class BranchWorkspaceManager {
             return this.adoptInPlace(options, paths, baseBranch, metadata);
         }
         if (state.kind === 'residue' && (await this.recentlyActive(paths))) {
-            throw new BranchProvisioningBusyError(dirName);
+            throw new BranchProvisioningBusyError(dirName, shortName);
         }
         const sparseCone = sparseConeFor(this.config.contentRoot);
         await recordSparseCone(baseRoot, sparseCone).catch((err) => {
@@ -142,11 +148,11 @@ export class BranchWorkspaceManager {
         return outcome;
     }
     async stageAndPublish(paths, run) {
-        const { branchRoot, baseRoot, dirName } = paths;
+        const { branchRoot, baseRoot, dirName, shortName } = paths;
         const staged = await stageBranchWorkspace({
             baseRoot,
             dirName,
-            branchName: paths.safeName,
+            branchName: paths.ref,
             baseBranch: run.baseBranch,
             remoteUrl: run.remoteUrl,
             clone: {
@@ -166,6 +172,7 @@ export class BranchWorkspaceManager {
             published = await run.provisionLog.step('publish', () => publishStaging({
                 baseRoot,
                 dirName,
+                shortName,
                 stagingPath: staged.stagingPath,
                 writeId: staged.meta.writeId,
                 expectedRemoteUrl: run.remoteUrl,
@@ -186,16 +193,16 @@ export class BranchWorkspaceManager {
      * is, given branch.json under the branch's lock.
      */
     async adoptInPlace(options, paths, baseBranch, metadata) {
-        const { branchRoot, baseRoot, dirName } = paths;
+        const { branchRoot, baseRoot, dirName, shortName } = paths;
         const provisionLog = new ProvisionLog(dirName);
         let created = false;
         try {
-            const release = await provisionLog.step('lock', () => lockBranchName(baseRoot, dirName));
+            const release = await provisionLog.step('lock', () => lockBranchName(baseRoot, dirName, shortName));
             try {
                 if (!(await readBranchMetadataFile(branchRoot))) {
                     await GitManager.initializeWorkspace({
                         workspacePath: branchRoot,
-                        branchName: paths.safeName,
+                        branchName: paths.ref,
                         mode: options.mode,
                         baseBranch,
                         sourceRoot: this.config.sourceRoot,
@@ -231,7 +238,7 @@ export class BranchWorkspaceManager {
             return this.existing(paths);
         const meta = await readBranchMetadataFile(branchRoot);
         if (!meta)
-            throw new BranchProvisioningBusyError(dirName);
+            throw new BranchProvisioningBusyError(dirName, shortName);
         return { kind: 'created', context: { branch: meta.branch, branchRoot, baseRoot } };
     }
     /** Whether residue at the branch path may still belong to a live process. */
@@ -241,10 +248,10 @@ export class BranchWorkspaceManager {
             return true;
         return (await quietAgeMs(branchRoot)) < CREATE_RESIDUE_MIN_QUIET_MS;
     }
-    async existing({ branchRoot, baseRoot, dirName, }) {
+    async existing({ branchRoot, baseRoot, dirName, shortName, }) {
         const meta = await readBranchMetadataFile(branchRoot);
         if (!meta)
-            throw new BranchProvisioningBusyError(dirName);
+            throw new BranchProvisioningBusyError(dirName, shortName);
         return { kind: 'exists', context: { branch: meta.branch, branchRoot, baseRoot } };
     }
 }