@bleedingdev/modern-js-app-tools-extensions 3.9.0-ultramodern.14 → 3.9.0-ultramodern.16

package/src/deploy-output/public-assets.ts

@@ -0,0 +1,224 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { normalizeRelativePath } from '../cloudflare/utils';
+
+/**
+ * Deploy output directory that receives declared public assets on every
+ * target: Cloudflare Worker Static Assets and the Node deploy output.
+ */
+export const DECLARED_PUBLIC_ASSET_DIRECTORY = 'public';
+
+export interface DeclaredPublicAssetConfig {
+  from: string;
+  to: string;
+}
+
+export interface DeclaredPublicAssetScope {
+  /** Config path used in errors, for example `deploy.node.publicAssets`. */
+  label: string;
+  /** Output described in destination errors. */
+  output: string;
+}
+
+export interface DeclaredPublicAsset {
+  from: string;
+  to: string;
+  index: number;
+}
+
+export const CLOUDFLARE_PUBLIC_ASSET_SCOPE: DeclaredPublicAssetScope = {
+  label: 'deploy.worker.publicAssets',
+  output: 'Cloudflare public output',
+};
+
+export const NODE_PUBLIC_ASSET_SCOPE: DeclaredPublicAssetScope = {
+  label: 'deploy.node.publicAssets',
+  output: 'Node public output',
+};
+
+export const normalizeDeclaredPublicAssets = (
+  assets: readonly DeclaredPublicAssetConfig[] | undefined,
+  scope: DeclaredPublicAssetScope,
+): DeclaredPublicAsset[] =>
+  (assets ?? []).map((asset, index) => ({
+    from: normalizeRelativePath(
+      asset?.from,
+      `${scope.label}[${index}].from`,
+      'app root',
+    ),
+    to: normalizeRelativePath(
+      asset?.to,
+      `${scope.label}[${index}].to`,
+      scope.output,
+      { allowRoot: true },
+    ),
+    index,
+  }));
+
+interface DeclaredPublicAssetFile {
+  index: number;
+  /** Destination relative to the deploy output root, POSIX separators. */
+  logicalPath: string;
+}
+
+const isMissingPathError = (error: unknown) =>
+  error instanceof Error &&
+  'code' in error &&
+  (error as NodeJS.ErrnoException).code === 'ENOENT';
+
+const pathExists = async (filePath: string) => {
+  try {
+    await fs.lstat(filePath);
+    return true;
+  } catch (error) {
+    if (isMissingPathError(error)) {
+      return false;
+    }
+    throw error;
+  }
+};
+
+const listDeclaredPublicAssetFiles = async (
+  appDirectory: string,
+  assets: readonly DeclaredPublicAsset[],
+  scope: DeclaredPublicAssetScope,
+): Promise<DeclaredPublicAssetFile[]> => {
+  const files: DeclaredPublicAssetFile[] = [];
+  const owners = new Map<string, number>();
+  const add = (index: number, logicalPath: string) => {
+    const owner = owners.get(logicalPath);
+    if (owner !== undefined) {
+      throw new Error(
+        `${scope.label}[${index}] and ${scope.label}[${owner}] both stage ${JSON.stringify(logicalPath)}.`,
+      );
+    }
+    owners.set(logicalPath, index);
+    files.push({ index, logicalPath });
+  };
+  const visit = async (
+    asset: DeclaredPublicAsset,
+    sourcePath: string,
+    destination: string,
+  ): Promise<void> => {
+    const stat = await fs.lstat(sourcePath);
+    if (stat.isSymbolicLink()) {
+      throw new Error(
+        `${scope.label}[${asset.index}].from must not contain symbolic links: ${path
+          .relative(appDirectory, sourcePath)
+          .replace(/\\/gu, '/')}`,
+      );
+    }
+    if (stat.isFile()) {
+      if (destination === DECLARED_PUBLIC_ASSET_DIRECTORY) {
+        throw new Error(
+          `${scope.label}[${asset.index}].to must name a file when ${scope.label}[${asset.index}].from is a file.`,
+        );
+      }
+      add(asset.index, destination);
+      return;
+    }
+    if (!stat.isDirectory()) {
+      throw new Error(
+        `${scope.label}[${asset.index}].from must contain only files and directories: ${path
+          .relative(appDirectory, sourcePath)
+          .replace(/\\/gu, '/')}`,
+      );
+    }
+    const entries = (await fs.readdir(sourcePath)).sort();
+    for (const entry of entries) {
+      await visit(
+        asset,
+        path.join(sourcePath, entry),
+        path.posix.join(destination, entry),
+      );
+    }
+  };
+
+  for (const asset of assets) {
+    const sourcePath = path.join(appDirectory, asset.from);
+    if (!(await pathExists(sourcePath))) {
+      throw new Error(
+        `${scope.label}[${asset.index}].from does not exist: ${asset.from}`,
+      );
+    }
+    await visit(
+      asset,
+      sourcePath,
+      path.posix.join(DECLARED_PUBLIC_ASSET_DIRECTORY, asset.to),
+    );
+  }
+  return files;
+};
+
+/**
+ * Resolve the files declared public assets add to a deploy output that was
+ * copied from `generatedRoot`, relative to the deploy output root. Declared
+ * files that replace a generated file are not part of the result, matching
+ * {@link stageDeclaredPublicAssets}.
+ */
+export const resolveAddedDeclaredPublicAssetPaths = async ({
+  appDirectory,
+  assets,
+  generatedRoot,
+  scope,
+}: {
+  appDirectory: string;
+  assets: readonly DeclaredPublicAsset[];
+  generatedRoot: string;
+  scope: DeclaredPublicAssetScope;
+}): Promise<string[]> => {
+  const added: string[] = [];
+  for (const file of await listDeclaredPublicAssetFiles(
+    appDirectory,
+    assets,
+    scope,
+  )) {
+    if (!(await pathExists(path.join(generatedRoot, file.logicalPath)))) {
+      added.push(file.logicalPath);
+    }
+  }
+  return added.sort();
+};
+
+/**
+ * Copy declared public assets into the deploy output after the framework has
+ * staged its own public files.
+ *
+ * A declared file may replace a generated public file, such as an app-owned
+ * `robots.txt`; the replaced file keeps its generated release classification.
+ *
+ * @returns the files the declarations added, relative to the deploy output
+ * root. The release envelope records these as declared public assets.
+ */
+export const stageDeclaredPublicAssets = async ({
+  appDirectory,
+  outputDirectory,
+  assets,
+  scope,
+}: {
+  appDirectory: string;
+  outputDirectory: string;
+  assets: readonly DeclaredPublicAsset[];
+  scope: DeclaredPublicAssetScope;
+}): Promise<string[]> => {
+  const files = await listDeclaredPublicAssetFiles(appDirectory, assets, scope);
+  const added: string[] = [];
+  for (const file of files) {
+    const asset = assets.find(candidate => candidate.index === file.index)!;
+    const relativePath = path.posix.relative(
+      path.posix.join(DECLARED_PUBLIC_ASSET_DIRECTORY, asset.to),
+      file.logicalPath,
+    );
+    const destination = path.join(outputDirectory, file.logicalPath);
+    const replacesGeneratedFile = await pathExists(destination);
+    await fs.mkdir(path.dirname(destination), { recursive: true });
+    await fs.copyFile(
+      path.join(appDirectory, asset.from, relativePath),
+      destination,
+    );
+    if (!replacesGeneratedFile) {
+      added.push(file.logicalPath);
+    }
+  }
+  return added.sort();
+};

package/src/release-envelope/framework-output.ts

@@ -43,6 +43,28 @@ const isPublicMetadataPath = (logicalPath: string) =>
   logicalPath === 'public/_headers' ||
   /^public\/\.well-known\/[^/]+\.json$/u.test(logicalPath);
 const PUBLIC_BUILD_ARTIFACT_PATH = `public/${ULTRAMODERN_BUILD_ARTIFACT_FILE}`;
+// Files an app declared through `deploy.<target>.publicAssets`. The deploy
+// output stages them from app-root sources; they are served data, not a
+// UI/client surface, so API-only units may carry them.
+const DECLARED_PUBLIC_ASSET_RUNTIME = 'public-asset';
+
+const resolveDeclaredPublicAssets = (
+  files: readonly string[],
+  declaredPublicAssets: readonly string[],
+  target: 'Node' | 'Cloudflare',
+) => {
+  const staged = new Set(files);
+  const declared = new Set<string>();
+  for (const logicalPath of declaredPublicAssets) {
+    if (!logicalPath.startsWith('public/') || !staged.has(logicalPath)) {
+      throw new Error(
+        `[ultramodern-release-envelope] final ${target} staging has no declared public asset file ${JSON.stringify(logicalPath)}.`,
+      );
+    }
+    declared.add(logicalPath);
+  }
+  return declared;
+};
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -902,8 +924,14 @@ const createNodeStagedReleaseArtifactInputs = async (
   outputDirectory: string,
   identity: MicroVerticalReleaseIdentity,
   apiOnly: boolean,
+  declaredPublicAssets: readonly string[],
 ) => {
   const files = await collectFiles(outputDirectory);
+  const declaredPublicAssetPaths = resolveDeclaredPublicAssets(
+    files,
+    declaredPublicAssets,
+    'Node',
+  );
   for (const requiredPath of [
     'index.js',
     'package.json',
@@ -928,7 +956,8 @@ const createNodeStagedReleaseArtifactInputs = async (
       topLevel === 'html' ||
       (topLevel === 'public' &&
         logicalPath !== CRAWLER_POLICY_PATH &&
-        !isPublicMetadataPath(logicalPath)) ||
+        !isPublicMetadataPath(logicalPath) &&
+        !declaredPublicAssetPaths.has(logicalPath)) ||
       [
         'index.html',
         'mf-manifest.json',
@@ -992,6 +1021,9 @@ const createNodeStagedReleaseArtifactInputs = async (
   for (const logicalPath of uiClientPaths) {
     runtimeByPath.set(logicalPath, 'browser');
   }
+  for (const logicalPath of declaredPublicAssetPaths) {
+    runtimeByPath.set(logicalPath, DECLARED_PUBLIC_ASSET_RUNTIME);
+  }
   if (files.includes(CRAWLER_POLICY_PATH)) {
     runtimeByPath.set(CRAWLER_POLICY_PATH, 'crawler-policy');
   }
@@ -1058,9 +1090,12 @@ const createNodeStagedReleaseArtifactInputs = async (
 };
 
 export const emitNodeStagedReleaseEnvelope = async ({
+  declaredPublicAssets = [],
   distDirectory,
   outputDirectory,
 }: {
+  /** Staged `deploy.node.publicAssets` files, relative to `outputDirectory`. */
+  declaredPublicAssets?: readonly string[];
   distDirectory: string;
   outputDirectory: string;
 }) => {
@@ -1072,6 +1107,7 @@ export const emitNodeStagedReleaseEnvelope = async ({
     outputDirectory,
     source.identity,
     source.surfaces.uiClient.length === 0,
+    declaredPublicAssets,
   );
   const staged = await createMicroVerticalReleaseEnvelope({
     artifactRoot: outputDirectory,
@@ -1114,8 +1150,14 @@ const createCloudflareStagedReleaseArtifactInputs = async (
   outputDirectory: string,
   identity: MicroVerticalReleaseIdentity,
   apiOnly: boolean,
+  declaredPublicAssets: readonly string[],
 ) => {
   const files = await collectFiles(outputDirectory);
+  const declaredPublicAssetPaths = resolveDeclaredPublicAssets(
+    files,
+    declaredPublicAssets,
+    'Cloudflare',
+  );
   for (const requiredPath of [
     'server/index.mjs',
     'server/modern-worker-manifest.json',
@@ -1160,6 +1202,7 @@ const createCloudflareStagedReleaseArtifactInputs = async (
       logicalPath.startsWith('public/') &&
       logicalPath !== CRAWLER_POLICY_PATH &&
       !isPublicMetadataPath(logicalPath) &&
+      !declaredPublicAssetPaths.has(logicalPath) &&
       logicalPath !== PUBLIC_BUILD_ARTIFACT_PATH &&
       logicalPath !== backendManifestPath &&
       logicalPath !== backendContainerPath,
@@ -1229,6 +1272,7 @@ const createCloudflareStagedReleaseArtifactInputs = async (
     }
   };
   add(uiClientPaths, 'browser');
+  add([...declaredPublicAssetPaths], DECLARED_PUBLIC_ASSET_RUNTIME);
   if (files.includes(CRAWLER_POLICY_PATH)) {
     runtimeByPath.set(CRAWLER_POLICY_PATH, 'crawler-policy');
   }
@@ -1285,9 +1329,12 @@ const createCloudflareStagedReleaseArtifactInputs = async (
 };
 
 export const emitCloudflareStagedReleaseEnvelope = async ({
+  declaredPublicAssets = [],
   distDirectory,
   outputDirectory,
 }: {
+  /** Staged `deploy.worker.publicAssets` files, relative to `outputDirectory`. */
+  declaredPublicAssets?: readonly string[];
   distDirectory: string;
   outputDirectory: string;
 }) => {
@@ -1303,6 +1350,7 @@ export const emitCloudflareStagedReleaseEnvelope = async ({
       outputDirectory,
       source.identity,
       source.surfaces.uiClient.length === 0,
+      declaredPublicAssets,
     );
   const staged = await createMicroVerticalReleaseEnvelope({
     artifactRoot: outputDirectory,

package/src/release-envelope/plugin.ts

@@ -1,4 +1,10 @@
 import path from 'node:path';
+import type { NodePublicAssetConfig } from '../config';
+import {
+  NODE_PUBLIC_ASSET_SCOPE,
+  normalizeDeclaredPublicAssets,
+  resolveAddedDeclaredPublicAssetPaths,
+} from '../deploy-output/public-assets';
 import {
   emitFrameworkMicroVerticalReleaseEnvelope,
   emitNodeStagedReleaseEnvelope,
@@ -9,7 +15,10 @@ import {
 type ReleaseEnvelopeTarget = 'cloudflare' | 'node' | string;
 
 export interface ReleaseEnvelopeConfig {
-  deploy?: { target?: string };
+  deploy?: {
+    target?: string;
+    node?: { publicAssets?: NodePublicAssetConfig[] };
+  };
 }
 
 export interface ReleaseEnvelopeAppContext {
@@ -71,6 +80,7 @@ export const createUltramodernReleaseEnvelopePlugin = <
       '@modern-js/backend-federation-build',
       '@modern-js/plugin-bff',
       '@modern-js/deploy-output-aliases',
+      '@modern-js/deploy-output-public-assets',
     ],
     post: ['@modern-js/plugin-deploy'],
     setup(api) {
@@ -123,6 +133,17 @@ export const createUltramodernReleaseEnvelopePlugin = <
         const { appDirectory, distDirectory } = api.getAppContext();
         const outputDirectory = path.join(appDirectory, '.output');
         const releaseEnvelope = await emitNodeStagedReleaseEnvelope({
+          // The Node deploy output is a copy of dist, so a declared file
+          // added output exactly when dist has no file at its path.
+          declaredPublicAssets: await resolveAddedDeclaredPublicAssetPaths({
+            appDirectory,
+            assets: normalizeDeclaredPublicAssets(
+              api.getNormalizedConfig().deploy?.node?.publicAssets,
+              NODE_PUBLIC_ASSET_SCOPE,
+            ),
+            generatedRoot: distDirectory,
+            scope: NODE_PUBLIC_ASSET_SCOPE,
+          }),
           distDirectory,
           outputDirectory,
         });

package/src/templates/cloudflare-entry.005-worker-dispatch.mjs

@@ -160,14 +160,46 @@ async function dispatchRouteWorker(route, request, env, ctx) {
   );
 }
 
-function matchesPrefix(pathname, prefix) {
+// Worker Static Assets decode percent-encoded paths, so an encoded spelling
+// of a mounted prefix (`/%70refix/...`, `/prefix%2F...`) would otherwise skip
+// the BFF or service binding that owns the prefix and reach ASSETS directly.
+// Resolve such spellings to the canonical pathname the owner sees; a
+// backslash or undecodable spelling becomes a path the owner rejects.
+function resolvePrefixPathname(pathname, prefix) {
   if (!prefix || prefix === '/') {
-    return true;
+    return pathname;
   }
 
   const normalized = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+  let candidate = pathname;
+
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    if (candidate === normalized || candidate.startsWith(`${normalized}/`)) {
+      return candidate;
+    }
+    if (candidate.startsWith(`${normalized}\\`)) {
+      return `${normalized}/__invalid_encoded_path__`;
+    }
+
+    let decoded;
+    try {
+      decoded = decodeURIComponent(candidate);
+    } catch {
+      return candidate.toLowerCase().startsWith(normalized.toLowerCase())
+        ? `${normalized}/__invalid_encoded_path__`
+        : null;
+    }
+    if (decoded === candidate) {
+      return null;
+    }
+    candidate = decoded;
+  }
 
-  return pathname === normalized || pathname.startsWith(`${normalized}/`);
+  return null;
+}
+
+function matchesPrefix(pathname, prefix) {
+  return resolvePrefixPathname(pathname, prefix) !== null;
 }
 
 function createRequestForMountedPrefix(request, prefix) {
@@ -177,12 +209,13 @@ function createRequestForMountedPrefix(request, prefix) {
 
   const url = new URL(request.url);
   const normalized = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+  const matchedPathname = resolvePrefixPathname(url.pathname, normalized);
 
-  if (!matchesPrefix(url.pathname, normalized)) {
+  if (matchedPathname === null) {
     return request;
   }
 
-  const nextPath = url.pathname.slice(normalized.length) || '/';
+  const nextPath = matchedPathname.slice(normalized.length) || '/';
   url.pathname = nextPath.startsWith('/') ? nextPath : `/${nextPath}`;
 
   return new Request(url, request);
@@ -309,12 +342,21 @@ function getEffectBffDispatcher(bff, runtime) {
 async function dispatchBffRequest(request, env) {
   const bff = MODERN_WORKER_MANIFEST.bff;
 
-  if (
-    !bff?.worker ||
-    !matchesPrefix(new URL(request.url).pathname, bff.prefix)
-  ) {
+  const requestUrl = new URL(request.url);
+  const matchedPathname = resolvePrefixPathname(
+    requestUrl.pathname,
+    bff?.prefix,
+  );
+  if (!bff?.worker || matchedPathname === null) {
     return null;
   }
+  const canonicalRequest =
+    matchedPathname === requestUrl.pathname
+      ? request
+      : new Request(
+          Object.assign(requestUrl, { pathname: matchedPathname }),
+          request,
+        );
   if (bff.runtimeFramework !== 'effect') {
     return createEffectBffDispatcherErrorResponse(
       bff,
@@ -347,7 +389,7 @@ async function dispatchBffRequest(request, env) {
       return createEffectBffDispatcherErrorResponse(bff, error);
     }
 
-    return effectDispatcher.dispatch(request, { env });
+    return effectDispatcher.dispatch(canonicalRequest, { env });
   }
 
   const directHandler =