canopycms 0.0.68-int.98 → 0.1.0

package/dist/assets/asset-url.js

@@ -1,36 +1,60 @@
 /**
  * Build/adjust transform URLs for `<img>`/srcset without pulling in the
- * server-only transform engine. Isomorphic - depends only on
- * transform-directives.ts, the plain `ASSET_PREFIXES` constant, and
- * utils/url-prefix.ts, none of which import node builtins, so this is safe to
- * import from client (editor) code as well as during static builds.
+ * server-only transform engine. Isomorphic - none of its imports reach a node
+ * builtin, so this is safe to import from client (editor) code as well as during
+ * static builds.
  */
 import { isUnprefixablePath, joinUrlPrefix, sanitizeUnprefixedPath, stripTrailingSlashes, } from '../utils/url-prefix.js';
+import { getPreviewAssetBase } from '../editor/preview-asset-base.js';
 import { ASSET_PREFIXES } from './asset-prefixes.js';
 import { formatDirectives, isAllowedTransformWidth, parseTransformPath, } from './transform-directives.js';
 const TRANSFORM_URL_PREFIX = `/${ASSET_PREFIXES.transform}/`;
+const ASSET_SPACE_PREFIX = `/${ASSET_PREFIXES.public}/`;
 /**
- * Merge `opts` over an already-parsed directive set - opts win when given,
- * otherwise the existing value (if any) carries over. Returns `undefined`
- * fields as "unset" (there is no way to explicitly clear a directive via
- * opts - only to override it).
+ * Whether `src` is in canopycms's own `/assets` URL space - a transform or static asset src the
+ * asset store serves. Every other src (a site's own static file, an off-site URL, a `data:` URI)
+ * is the host's, and the asset store never serves it.
  */
-function mergeDirectives(current, opts) {
+export function isAssetStoreSrc(src) {
+    return src.startsWith(ASSET_SPACE_PREFIX);
+}
+/**
+ * Test-only. A function stored on `globalThis` under this symbol is called with every URL
+ * `assetUrl` returns; the dual-build fixture installs one during a static export to prove
+ * `collect-asset-refs` finds every URL its pages emitted.
+ */
+const EMITTED_URL_LISTENER = Symbol.for('canopycms.assetUrl.emitted');
+function emitted(url) {
+    const listener = globalThis[EMITTED_URL_LISTENER];
+    if (typeof listener === 'function')
+        listener(url);
+    return url;
+}
+/**
+ * Merge `opts` and the ref's crop over the directives already in its src. Precedence per
+ * directive: `opts`, then `ref.crop` (crop only), then the src. There is no way to clear a
+ * directive, only to override it.
+ */
+function mergeDirectives(current, refCrop, opts) {
     const existing = current.identity ? undefined : current;
     const width = opts.width ?? existing?.width;
     const format = opts.format ?? existing?.format;
     const quality = opts.quality ?? existing?.quality;
-    const crop = opts.crop ?? existing?.crop;
+    const crop = opts.crop ?? refCrop ?? existing?.crop;
     if (width === undefined && format === undefined && quality === undefined && crop === undefined) {
         return { identity: true };
     }
     return { identity: false, width, format, quality, crop };
 }
 /**
- * Build a transform URL, merging `opts` over the directives already present
- * in `ref.src` (opts win). For static srcs (svg/pdf under `/assets/{hash}/...`,
- * or any src that isn't one of our own transform URLs) the src is returned
- * unchanged and `opts` are ignored - there is nothing to transform.
+ * Build a transform URL, merging `opts` and `ref.crop` over the directives already present
+ * in `ref.src` (see `mergeDirectives` for precedence). For static srcs (svg/pdf under
+ * `/assets/{hash}/...`, or any src that isn't one of our own transform URLs) the src is
+ * returned unchanged and every directive is ignored - there is nothing to transform.
+ *
+ * In a live preview, a transform URL goes behind the editor's authenticated route
+ * (`editor/preview-asset-base.ts`) instead of `opts.baseUrl`: a draft's crop or width may exist
+ * nowhere a build put it. Static srcs keep `opts.baseUrl`, since finalize wrote them.
  */
 export function assetUrl(ref, opts = {}) {
     const { src } = ref;
@@ -46,35 +70,37 @@ export function assetUrl(ref, opts = {}) {
         // `joinUrlPrefix`'s own contract. Plain `!opts.baseUrl` made '' and '/' disagree.
         const mount = opts.baseUrl ? stripTrailingSlashes(opts.baseUrl) : '';
         if (!mount || isUnprefixablePath(src))
-            return sanitizeUnprefixedPath(src);
-        return joinUrlPrefix(opts.baseUrl, src);
+            return emitted(sanitizeUnprefixedPath(src));
+        return emitted(joinUrlPrefix(opts.baseUrl, src));
     }
+    const base = getPreviewAssetBase() ?? opts.baseUrl;
     const rest = src.slice(TRANSFORM_URL_PREFIX.length);
-    const parsed = parseTransformPath(rest.split('/'));
+    const parsed = parseTransformPath(rest.split('/'), 'any');
     if (!parsed.ok) {
         // Malformed src (shouldn't happen for a src canopycms itself wrote) -
         // nothing sensible to merge onto, so return it unchanged rather than throw.
-        return joinUrlPrefix(opts.baseUrl, src);
+        return emitted(joinUrlPrefix(base, src));
     }
-    const merged = mergeDirectives(parsed.directives, opts);
+    const merged = mergeDirectives(parsed.directives, ref.crop, opts);
     // Ext follows the format: an explicit format (new or carried over) always
     // wins; with no format at all, the ext must keep preserving the source's
     // real extension, which is exactly what `parsed.ext` already is here.
     const ext = !merged.identity && merged.format !== undefined ? merged.format : parsed.ext;
     const newSrc = `${TRANSFORM_URL_PREFIX}${formatDirectives(merged)}/${parsed.hash32}/${parsed.slug}.${ext}`;
-    return joinUrlPrefix(opts.baseUrl, newSrc);
+    return emitted(joinUrlPrefix(base, newSrc));
 }
 /**
  * Build a comma-joined `url w` srcset descriptor list. `widths` must all be
- * on the transform width allowlist (multiples of 160 in [160, 4096]) - this
- * is developer-facing (a host app's own responsive-image markup), so an
- * invalid width throws rather than silently dropping it.
+ * integers in [1, 8192] (the `any` width policy) - this is developer-facing (a
+ * host app's own responsive-image markup), so an invalid width throws rather
+ * than silently dropping it. A site serving the opt-in lazy public path, which
+ * transforms only allowlisted widths, must pick widths from that allowlist.
  */
 export function assetSrcSet(ref, widths, opts = {}) {
     return widths
         .map((width) => {
-        if (!isAllowedTransformWidth(width)) {
-            throw new Error(`assetSrcSet: width ${width} is not allowed (must be a multiple of 160 between 160 and 4096)`);
+        if (!isAllowedTransformWidth(width, 'any')) {
+            throw new Error(`assetSrcSet: width ${width} is not allowed (must be an integer between 1 and 8192)`);
         }
         return `${assetUrl(ref, { ...opts, width })} ${width}w`;
     })

package/dist/assets/finalize.js

@@ -39,6 +39,9 @@ export async function finalizeAsset(store, input) {
     const existing = await store.getMeta(meta.hash32);
     if (existing)
         return { ok: true, meta: existing };
+    // Either put may find its key taken (`already-exists`): by an earlier attempt that stopped
+    // before the meta commit, or by a concurrent identical upload. The object kept there is this
+    // content's, so finalize goes on to commit the meta either way.
     await store.putOriginal({ hash32: meta.hash32, ext: meta.ext, data, contentType: meta.mime });
     if (publicObject) {
         await store.putPublicObject(publicObject);

package/dist/assets/index.d.ts

@@ -14,6 +14,6 @@ export { ALLOWED_UPLOAD_CONTENT_TYPES, runFinalizePipeline, type FinalizeInput,
 export { finalizeAsset, finalizeStagedUpload, type FinalizeAssetResult } from './finalize.js';
 export { sanitizeSvg } from './svg-sanitizer.js';
 export { assetSrc } from './asset-src.js';
-export { formatDirectives, isAllowedTransformWidth, isValidCropRect, parseTransformPath, type CropRect, type OutputFormat, type ParsedTransformPath, type ParseTransformPathResult, type TransformDirectives, } from './transform-directives.js';
+export { formatDirectives, isAllowedTransformWidth, isValidCropRect, parseTransformPath, type CropRect, type OutputFormat, type ParsedTransformPath, type ParseTransformPathResult, type TransformDirectives, type TransformWidthPolicy, } from './transform-directives.js';
 export { applyTransform, type ApplyTransformInput, type TransformResult } from './transform.js';
 export { assetUrl, assetSrcSet, type AssetRef, type AssetUrlOptions } from './asset-url.js';

package/dist/assets/materialize.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Writing transform outputs into the store. Server-only.
+ *
+ * `storeTransform` computes one key and is shared by the authenticated raw route
+ * (api/assets.ts), `materializeAssets` (the batch run that writes every key a build references
+ * before that build is released) and canopycms-cdk's lazy transform Lambda.
+ */
+import { type ParsedTransformPath } from './transform-directives.js';
+import type { AssetStore, CreateOnlyResult } from './types.js';
+/** Every transform output is stored under a content-addressed key, so it never changes. */
+export declare const TRANSFORM_CACHE_CONTROL = "public, max-age=31536000, immutable";
+/**
+ * The object tag on every derivative the lazy transform Lambda writes. Its bucket's `assets/t/`
+ * expiry filters on it, so what `materializeAssets` writes, which the Lambda's allowlist may refuse
+ * to recompute, is never expired. canopycms-cdk's `AssetSupport` copies these two strings as
+ * literals.
+ */
+export declare const LAZY_TRANSFORM_TAG: {
+    readonly key: "canopy-transform";
+    readonly value: "lazy";
+};
+/**
+ * `data` is the computed output whether or not it was stored: `stored: 'already-exists'` means
+ * another writer stored the key first, and the store kept that object.
+ */
+export type StoreTransformResult = {
+    ok: true;
+    data: Uint8Array;
+    contentType: string;
+    stored: CreateOnlyResult;
+} | {
+    ok: false;
+    status: 400 | 404 | 413 | 422;
+    error: string;
+};
+/**
+ * Compute the transform `parsed` names from the asset's original and write it under `key`: the
+ * canonical key, or that key beneath an output prefix. `parsed` must come from
+ * `canonicalizeTransformPath`, so the stored pixels always match their key. A rejection is a fact
+ * about the asset or the URL and is never worth retrying; a thrown error belongs to the store or
+ * the environment. A 404's `error` names what was missing, so a caller answering a browser
+ * replaces it.
+ */
+export declare function storeTransform(store: AssetStore, parsed: ParsedTransformPath, key: string, options?: {
+    tags?: Readonly<Record<string, string>>;
+}): Promise<StoreTransformResult>;
+/** One key a build references, and where it was referenced, for the failure report. */
+export interface MaterializeTarget {
+    /** `assets/t/{directives}/{hash32}/{slug}.{ext}`. */
+    key: string;
+    routes: readonly string[];
+    files: readonly string[];
+}
+/**
+ * `content`: the key cannot be produced from what the store holds (asset deleted, wrong slug,
+ * undecodable input, malformed key), so a retry would fail the same way and the page must change.
+ * `store`: the store kept failing, or refused the request outright; rerunning may succeed.
+ */
+type MaterializeFailureKind = 'content' | 'store';
+export type MaterializeResult = {
+    key: string;
+    routes: string[];
+    files: string[];
+} & ({
+    status: 'existed' | 'created' | 'copied';
+} | {
+    status: 'failed';
+    failure: MaterializeFailureKind;
+    error: string;
+});
+/** The `schemaVersion` of every `MaterializeReport`; a consumer gating on the JSON checks it. */
+export declare const MATERIALIZE_REPORT_SCHEMA_VERSION = 1;
+export interface MaterializeReport {
+    schemaVersion: typeof MATERIALIZE_REPORT_SCHEMA_VERSION;
+    /** `MaterializeOptions.outputPrefix`, present only when one was given. */
+    outputPrefix?: string;
+    summary: {
+        total: number;
+        existed: number;
+        created: number;
+        /** Keys copied from the canonical prefix into an output prefix; 0 until one is configured. */
+        copied: number;
+        failed: number;
+        contentFailures: number;
+        storeFailures: number;
+    };
+    /** Sorted by key. */
+    results: MaterializeResult[];
+}
+export interface MaterializeOptions {
+    store: AssetStore;
+    targets: readonly MaterializeTarget[];
+    /**
+     * `assets/{hash32}/{slug}.{ext}` keys (svg, pdf) a build references. These are never produced
+     * here (finalize writes them at upload), only checked, or copied under an `outputPrefix`, so a
+     * missing one is a content failure, unless the bucket itself is missing: a store failure.
+     */
+    statics?: readonly MaterializeTarget[];
+    /**
+     * Write every key `k` at `outputPrefix + k` instead, for a build whose writes must never land
+     * where production reads (a PR preview). A key production already stores is copied from there;
+     * the rest are transformed from the canonical originals. Production's own run, with no prefix,
+     * never reads beneath it. See `assertValidOutputPrefix` for what is accepted.
+     */
+    outputPrefix?: string;
+    /** Store requests in flight at once. Default 8. */
+    concurrency?: number;
+    /**
+     * Transforms in flight at once. Each holds a decoded image, up to about 1.2 GiB at
+     * `MAX_INPUT_PIXELS`, so this stays small whatever `concurrency` is. Default 2.
+     */
+    transformConcurrency?: number;
+    /**
+     * A directive string referenced by at least this many keys has its whole `assets/t/{directives}/`
+     * prefix listed once instead of a HEAD per key, when the store can list. Default 100.
+     */
+    listThreshold?: number;
+    /** Attempts per store operation, including the first. Default 3. */
+    attempts?: number;
+    /** First retry delay; each later one doubles. Default 500. */
+    baseDelayMs?: number;
+    /** @internal Test seam for the retry delay. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** sharp cannot load in this process, so nothing missing can be produced here. */
+export declare class SharpUnavailableError extends Error {
+    constructor(cause: unknown);
+}
+/** `MaterializeOptions.outputPrefix` broke a rule of `assertValidOutputPrefix`; nothing was read or written. */
+export declare class InvalidOutputPrefixError extends Error {
+    constructor(prefix: string, reason: string);
+}
+/**
+ * Throws `InvalidOutputPrefixError` unless `prefix` is relative, ends in `/`, and is a run of
+ * `[A-Za-z0-9._-]` segments, none empty, `.` or `..`, whose first segments are not a canopy
+ * prefix. Production trusts whatever is under its own prefixes, so a write beneath one is a write
+ * production serves. Compared by segment: `assets-x/` is accepted, `assets/x/` is not.
+ */
+export declare function assertValidOutputPrefix(prefix: string): void;
+/**
+ * @internal Exported for tests. Throttling, 5xx and dropped connections are transient. Any other
+ * 4xx (AccessDenied, NoSuchBucket) is a configuration fault that a retry only delays.
+ */
+export declare function isTransientStoreError(err: unknown): boolean;
+/**
+ * Make every referenced transform key exist in `store`, and check every static key does. A key
+ * already stored is left alone:
+ * keys are content-addressed, so an existing object is the right one. sharp is loaded only when
+ * something must be transformed, and a sharp that cannot load throws `SharpUnavailableError` rather
+ * than failing each key. An invalid `outputPrefix` throws `InvalidOutputPrefixError` first.
+ */
+export declare function materializeAssets(options: MaterializeOptions): Promise<MaterializeReport>;
+export {};