@remix-run/assets 0.5.0 → 0.6.0

package/src/lib/asset-server.ts

@@ -17,7 +17,7 @@ import type {
 import { getFingerprintRequestCacheControl, parseFingerprintSuffix } from './fingerprint.ts'
 import { createHmrClientSource } from './hmr.ts'
 import type { HmrPayload } from './hmr.ts'
-import { getInjectedPackageRouteConfigs } from './injected-packages.ts'
+import { getInjectedPackageMountConfigs } from './injected-packages.ts'
 import type { ModuleLoader } from './loaders.ts'
 import { normalizeFilePath, normalizePathname } from './paths.ts'
 import { compileRoutes } from './routes.ts'
@@ -29,6 +29,7 @@ import { createResponseForStyle, createStyleCompiler, isStyleFilePath } from './
 import { resolveScriptTarget, resolveStyleTarget } from './target.ts'
 import type { AssetTarget, ResolvedScriptTarget, ResolvedStyleTarget } from './target.ts'
 import { createAssetServerWatcher } from './watch.ts'
+import { createAssetInspector, type AssetDetails } from './inspection.ts'
 import type { AssetServerWatcher, ChokidarWatcher } from './watch.ts'
 
 interface AssetServerWatchOptions {
@@ -172,6 +173,10 @@ interface AssetServerScriptOptions {
 }
 
 const scriptExtensionSet = new Set<string>(supportedScriptExtensions)
+const defaultMounts = {
+  app: 'app',
+  npm: 'node_modules',
+} as const
 
 /**
  * Options used to construct an {@link AssetServer} via {@link createAssetServer}.
@@ -179,8 +184,14 @@ const scriptExtensionSet = new Set<string>(supportedScriptExtensions)
 export interface AssetServerOptions<transforms extends AssetRequestTransformMap = {}> {
   /** Public mount path for this asset server, e.g. `'/assets'`. */
   basePath: string
-  /** File patterns keyed by public URL patterns. */
-  fileMap: Readonly<Record<string, string>>
+  /**
+   * Directories to mount at public URL paths.
+   *
+   * Each key is a public URL path and its value is a directory relative to `rootDir`. Defaults to
+   * `{ app: 'app', npm: 'node_modules' }`. Public paths must not contain query strings, fragments,
+   * or encoded dot segments.
+   */
+  mounts?: Readonly<Record<string, string>>
   /**
    * Root directory used to resolve relative file paths. Defaults to `process.cwd()`.
    */
@@ -191,7 +202,7 @@ export interface AssetServerOptions<transforms extends AssetRequestTransformMap
   allowFiles: readonly string[]
   /**
    * Exact package names whose files are allowed to be served. Dependencies and installed optional
-   * dependencies are allowed automatically. Package files must still match `fileMap`.
+   * dependencies are allowed automatically. Package files must still be within a configured mount.
    */
   allowPackages?: readonly string[]
   /**
@@ -289,6 +300,16 @@ export interface AssetServer<transforms extends AssetRequestTransformMap = {}> {
    * Returns preload URLs for one or more served asset files, ordered shallowest-first.
    */
   getPreloads(filePath: string | readonly string[]): Promise<string[]>
+  /**
+   * Returns diagnostic details about one public asset URL or file path, including the matched mount
+   * roots, access rules, file type, and browser-reachability status.
+   */
+  getAssetDetails(input: string): Promise<AssetDetails>
+  /**
+   * Returns every file currently reachable through this asset server, sorted by public URL and
+   * then absolute file path.
+   */
+  getAssets(): Promise<AssetDetails[]>
   /**
    * Closes this server's filesystem watcher and browser HMR channel.
    *
@@ -312,6 +333,7 @@ type ResolvedAssetServerOptions<transforms extends AssetRequestTransformMap> = {
   loaders: readonly ModuleLoader[]
   onError: NonNullable<AssetServerOptions['onError']>
   rootDir: string
+  mounts: Readonly<Record<string, string>>
   routes: CompiledRoutes
   sourceMapSourcePaths: 'url' | 'absolute'
   sourceMaps?: 'inline' | 'external'
@@ -339,7 +361,7 @@ export function getInternalWatchTargets<transforms extends AssetRequestTransform
  * Create an asset server instance
  *
  * Compiles TypeScript/JavaScript scripts and CSS styles on demand with optional
- * source-based URL fingerprinting, caching, and configurable file mapping.
+ * source-based URL fingerprinting, caching, and configurable directory mounts.
  *
  * @param options Server configuration
  * @returns A {@link AssetServer} with `fetch()`, `getHref()`, and `getPreloads()` methods
@@ -348,9 +370,6 @@ export function getInternalWatchTargets<transforms extends AssetRequestTransform
  * ```ts
  * let assetServer = createAssetServer({
  *   basePath: '/assets',
- *   fileMap: {
- *     '/app/*path': 'app/*path',
- *   },
  *   allowFiles: ['app/routes.ts', 'app/**\/public/**'],
  *   allowPackages: ['remix'],
  *   denyFiles: ['app/**\/*.test.*'],
@@ -368,10 +387,17 @@ export function createAssetServer<const transforms extends AssetRequestTransform
     allowPackages: resolvedOptions.allowPackages,
     denyFiles: resolvedOptions.denyFiles,
     packageSearchRoots: hasPackages(resolvedOptions.allowPackages)
-      ? getPackageSearchRoots(options.fileMap, resolvedOptions.rootDir)
+      ? getPackageSearchRoots(resolvedOptions.mounts, resolvedOptions.rootDir)
       : undefined,
     rootDir: resolvedOptions.rootDir,
   })
+  let assetInspector = createAssetInspector({
+    accessPolicy,
+    allowFiles: resolvedOptions.allowFiles,
+    fileExtensions: resolvedOptions.files.extensions,
+    rootDir: resolvedOptions.rootDir,
+    routes: resolvedOptions.routes,
+  })
   let watcher: AssetServerWatcher | null = null
   let chokidarWatcher: ChokidarWatcher | null = null
   let fileCompiler: FileCompiler | null = null
@@ -575,6 +601,12 @@ export function createAssetServer<const transforms extends AssetRequestTransform
   }
 
   let assetServer: AssetServer<transforms> = {
+    getAssetDetails(input) {
+      return assetInspector.getAssetDetails(input)
+    },
+    getAssets() {
+      return assetInspector.getAssets()
+    },
     async fetch(request) {
       if (request.method !== 'GET' && request.method !== 'HEAD') return null
       let requestPathname = new URL(request.url).pathname
@@ -1006,10 +1038,14 @@ function resolveAssetServerOptions<transforms extends AssetRequestTransformMap>(
   })
   let watchOptions = normalizeWatchOptions(options.watch)
   let hmrFactory = normalizeHmrFactory(options.hmr)
+  let mounts = options.mounts ?? defaultMounts
 
   if (hmrFactory && watchOptions === null) {
     throw new TypeError('hmr requires watch mode')
   }
+  if (Object.keys(mounts).length === 0) {
+    throw new TypeError('mounts must include at least one entry')
+  }
   return {
     allowFiles: options.allowFiles,
     allowPackages: options.allowPackages,
@@ -1022,15 +1058,16 @@ function resolveAssetServerOptions<transforms extends AssetRequestTransformMap>(
     fingerprintAssets: fingerprintOptions.enabled,
     hmr: hmrFactory,
     minify: options.minify ?? false,
+    mounts,
     loaders: scriptOptions.loaders ?? [],
     onError: options.onError ?? defaultErrorHandler,
     rootDir,
     routes: compileRoutes(basePath, [
       {
-        fileMap: options.fileMap,
+        mounts,
         rootDir,
       },
-      ...getInjectedPackageRouteConfigs(),
+      ...getInjectedPackageMountConfigs(),
     ]),
     sourceMapSourcePaths: options.sourceMapSourcePaths ?? 'url',
     sourceMaps: options.sourceMaps,
@@ -1154,19 +1191,10 @@ function hasPackages(packages: readonly string[] | undefined): boolean {
 }
 
 function getPackageSearchRoots(
-  fileMap: AssetServerOptions['fileMap'],
+  mounts: Readonly<Record<string, string>>,
   rootDir: string,
 ): readonly string[] {
-  return Object.values(fileMap).map((filePattern) =>
-    path.resolve(rootDir, getStaticFilePatternPrefix(filePattern)),
-  )
-}
-
-function getStaticFilePatternPrefix(filePattern: string): string {
-  let firstDynamicIndex = filePattern.search(/[*:]/)
-  let staticPrefix =
-    firstDynamicIndex === -1 ? filePattern : filePattern.slice(0, firstDynamicIndex)
-  return staticPrefix.replace(/[/\\]*$/, '')
+  return Object.values(mounts).map((fileRoot) => path.resolve(rootDir, fileRoot))
 }
 
 function parseAssetRequestPathname(

package/src/lib/compilation-error.ts

@@ -2,7 +2,7 @@ type AssetServerCompilationErrorCode =
   | 'FILE_NOT_FOUND'
   | 'FILE_NOT_ALLOWED'
   | 'FILE_NOT_SUPPORTED'
-  | 'FILE_OUTSIDE_FILE_MAP'
+  | 'FILE_OUTSIDE_MOUNTS'
   | 'FILE_TRANSFORM_QUERY_INVALID'
   | 'FILE_TRANSFORM_NOT_SUPPORTED'
   | 'FILE_TRANSFORM_RESULT_INVALID'
@@ -14,11 +14,11 @@ type AssetServerCompilationErrorCode =
   | 'IMPORT_RESOLUTION_FAILED'
   | 'IMPORT_NOT_SUPPORTED'
   | 'IMPORT_NOT_ALLOWED'
-  | 'IMPORT_OUTSIDE_FILE_MAP'
+  | 'IMPORT_OUTSIDE_MOUNTS'
   | 'URL_RESOLUTION_FAILED'
   | 'URL_NOT_SUPPORTED'
   | 'URL_NOT_ALLOWED'
-  | 'URL_OUTSIDE_FILE_MAP'
+  | 'URL_OUTSIDE_MOUNTS'
 
 /**
  * Internal error used by the request-time asset compilation pipeline.

package/src/lib/files/compiler.ts

@@ -566,9 +566,9 @@ export function resolveServedFileOrThrow(filePath: string, args: ResolveArgs): R
   let stableUrlPathname = args.routes.toUrlPathname(identityPath)
   if (!stableUrlPathname) {
     throw createAssetServerCompilationError(
-      `File ${identityPath} is outside all configured fileMap entries.`,
+      `File ${identityPath} is outside all configured mounts.`,
       {
-        code: 'FILE_OUTSIDE_FILE_MAP',
+        code: 'FILE_OUTSIDE_MOUNTS',
       },
     )
   }

package/src/lib/injected-packages.ts

@@ -28,23 +28,29 @@ export function isInjectedPackageFilePath(filePath: string): boolean {
   return false
 }
 
-export function getInjectedPackageRouteConfigs(): {
-  fileMap: Record<string, string>
+export function getInjectedPackageMountConfigs(): {
+  mounts: Record<string, string>
   rootDir: string
 }[] {
   return injectedPackageNames.map((packageName) => {
     let { packageRoot } = getResolvedInjectedPackage(packageName)
-    let { filePattern, routeRoot } = getInjectedPackageRoute(packageRoot, packageName)
+    let { fileRoot, routeRoot } = getInjectedPackageRoute(packageRoot, packageName)
 
     return {
-      fileMap: {
-        [getInjectedPackageRoutePattern(packageName)]: filePattern,
+      mounts: {
+        [getInjectedPackageMountPath(packageName)]: fileRoot,
       },
       rootDir: routeRoot,
     }
   })
 }
 
+export function getInjectedPackageRoots(): readonly string[] {
+  return injectedPackageNames.map(
+    (packageName) => getResolvedInjectedPackage(packageName).packageRoot,
+  )
+}
+
 export function getInjectedPackageNameForSpecifier(specifier: string): string | null {
   for (let injectedSpecifier of generatedInjectedPackageSpecifiers) {
     if (specifier === injectedSpecifier) {
@@ -119,17 +125,17 @@ function getResolvedInjectedPackage(packageName: string): ResolvedInjectedPackag
   return resolvedInjectedPackage
 }
 
-function getInjectedPackageRoutePattern(packageName: string): string {
-  return `${injectedPackagesBasePath}/${packageName}/*path`
+function getInjectedPackageMountPath(packageName: string): string {
+  return `${injectedPackagesBasePath}/${packageName}`
 }
 
 function getInjectedPackageRoute(
   packageRoot: string,
   packageName: string,
-): { filePattern: string; routeRoot: string } {
+): { fileRoot: string; routeRoot: string } {
   if (!packageRoot.endsWith(`/${packageName}`)) {
     return {
-      filePattern: `${packageRoot.slice(getFilePathDirectory(packageRoot).length + 1)}/*path`,
+      fileRoot: packageRoot.slice(getFilePathDirectory(packageRoot).length + 1),
       routeRoot: getFilePathDirectory(packageRoot),
     }
   }
@@ -141,7 +147,7 @@ function getInjectedPackageRoute(
   }
 
   return {
-    filePattern: `${packageName}/*path`,
+    fileRoot: packageName,
     routeRoot,
   }
 }

package/src/lib/inspection.ts

@@ -0,0 +1,229 @@
+import * as fs from 'node:fs'
+import * as fsPromises from 'node:fs/promises'
+import * as path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import type { AccessPolicy, AssetAccessDetails } from './access.ts'
+import { parseFingerprintSuffix } from './fingerprint.ts'
+import { getInjectedPackageRoots } from './injected-packages.ts'
+import { isAbsoluteFilePath, normalizeFilePath, resolveFilePath } from './paths.ts'
+import type { AssetRouteMatch, CompiledRoutes } from './routes.ts'
+import { supportedScriptExtensions } from './scripts/resolve.ts'
+import { isStyleFilePath } from './styles/compiler.ts'
+
+const scriptExtensions = new Set<string>(supportedScriptExtensions)
+const globSyntaxPattern = /[*?[\]{}()!+@]/
+
+/** How the asset server handles an inspected file. */
+export type AssetKind = 'file' | 'script' | 'style' | 'unsupported'
+
+/** Browser-reachability result for an inspected asset. */
+export type AssetStatus =
+  | 'denied'
+  | 'missing'
+  | 'not-allowed'
+  | 'reachable'
+  | 'unmapped'
+  | 'unsupported'
+
+/** Diagnostic information about a configured asset URL or file path. */
+export interface AssetDetails {
+  /** Access-control decision and the rules responsible for it. */
+  access?: AssetAccessDetails
+  /** Absolute mapped file path. */
+  filePath?: string
+  /** Configured filesystem mount root that matched the asset. */
+  fileRoot?: string
+  /** Browser-reachability result. */
+  status: AssetStatus
+  /** How the asset server handles the file. */
+  type?: AssetKind
+  /** Stable public URL pathname for the asset. */
+  url?: string
+  /** Public mount root that matched the asset. */
+  urlRoot?: string
+}
+
+interface AssetInspectorOptions {
+  accessPolicy: AccessPolicy
+  allowFiles: readonly string[]
+  fileExtensions: readonly string[]
+  rootDir: string
+  routes: CompiledRoutes
+}
+
+export interface AssetInspector {
+  /** Returns diagnostic information for a public URL or file path. */
+  getAssetDetails(input: string): Promise<AssetDetails>
+  /** Returns every file currently reachable through the configured asset server. */
+  getAssets(): Promise<AssetDetails[]>
+}
+
+export function createAssetInspector(options: AssetInspectorOptions): AssetInspector {
+  let fileExtensions = new Set(options.fileExtensions.map((extension) => extension.toLowerCase()))
+
+  return {
+    async getAssetDetails(input) {
+      let routeMatch = await resolveInput(input, options)
+      if (routeMatch === null) return { status: 'unmapped' }
+      return inspectRouteMatch(routeMatch, options, fileExtensions)
+    },
+    async getAssets() {
+      let filePaths = await discoverFilePaths(options)
+      let assets: AssetDetails[] = []
+
+      for (let filePath of filePaths) {
+        let routeMatch = options.routes.matchFilePath(filePath)
+        if (routeMatch === null) continue
+
+        let details = await inspectRouteMatch(routeMatch, options, fileExtensions)
+        if (details.status === 'reachable') assets.push(details)
+      }
+
+      assets.sort((left, right) => {
+        let urlOrder = (left.url ?? '').localeCompare(right.url ?? '')
+        return urlOrder === 0 ? (left.filePath ?? '').localeCompare(right.filePath ?? '') : urlOrder
+      })
+      return assets
+    },
+  }
+}
+
+async function resolveInput(
+  input: string,
+  options: Pick<AssetInspectorOptions, 'rootDir' | 'routes'>,
+): Promise<AssetRouteMatch | null> {
+  if (input.startsWith('file://')) {
+    return options.routes.matchFilePath(fileURLToPath(input))
+  }
+
+  if (/^[A-Za-z][A-Za-z\d+.-]*:\/\//.test(input)) {
+    let pathname = parseFingerprintSuffix(new URL(input).pathname).pathname
+    return options.routes.matchUrlPathname(pathname)
+  }
+
+  let filePath = resolveFilePath(options.rootDir, input)
+  if (!input.startsWith('/') || isAbsoluteFilePath(input)) {
+    if (await pathExists(filePath)) return options.routes.matchFilePath(filePath)
+    if (!input.startsWith('/')) return options.routes.matchFilePath(filePath)
+  }
+
+  let pathname = parseFingerprintSuffix(new URL(input, 'http://remix.run').pathname).pathname
+  return options.routes.matchUrlPathname(pathname)
+}
+
+async function inspectRouteMatch(
+  routeMatch: AssetRouteMatch,
+  options: Pick<AssetInspectorOptions, 'accessPolicy' | 'rootDir'>,
+  fileExtensions: ReadonlySet<string>,
+): Promise<AssetDetails> {
+  let exists = await pathExists(routeMatch.filePath)
+  let identityPath = exists ? fs.realpathSync(routeMatch.filePath) : routeMatch.filePath
+  let normalizedIdentityPath = normalizeFilePath(identityPath)
+  let access = options.accessPolicy.inspect(normalizedIdentityPath)
+
+  let type = getAssetKind(routeMatch.filePath, fileExtensions)
+  let details = {
+    access,
+    filePath: routeMatch.filePath,
+    fileRoot: routeMatch.fileRoot,
+    type,
+    url: routeMatch.urlPathname,
+    urlRoot: routeMatch.urlRoot,
+  }
+
+  if (!exists) return { ...details, status: 'missing' }
+  if (!access.allowed) {
+    return { ...details, status: access.deniedBy === undefined ? 'not-allowed' : 'denied' }
+  }
+  if (type === 'unsupported') return { ...details, status: 'unsupported' }
+  return { ...details, status: 'reachable' }
+}
+
+function getAssetKind(filePath: string, fileExtensions: ReadonlySet<string>): AssetKind {
+  let extension = path.extname(filePath).toLowerCase()
+  if (scriptExtensions.has(extension)) return 'script'
+  if (isStyleFilePath(filePath)) return 'style'
+  if (fileExtensions.has(extension)) return 'file'
+  return 'unsupported'
+}
+
+async function discoverFilePaths(options: AssetInspectorOptions): Promise<string[]> {
+  let roots = new Set<string>()
+
+  for (let pattern of options.allowFiles) {
+    roots.add(resolveDiscoveryRoot(options.rootDir, pattern))
+  }
+  for (let packageRoot of options.accessPolicy.getAllowedPackageRoots()) {
+    roots.add(packageRoot)
+  }
+  for (let packageRoot of getInjectedPackageRoots()) {
+    roots.add(packageRoot)
+  }
+
+  let filePaths = new Set<string>()
+  for (let root of roots) {
+    await collectFiles(root, filePaths)
+  }
+
+  return [...filePaths]
+}
+
+function resolveDiscoveryRoot(rootDir: string, pattern: string): string {
+  let dynamicIndex = pattern.search(globSyntaxPattern)
+  if (dynamicIndex === -1) return resolveFilePath(rootDir, pattern)
+
+  let rawStaticPrefix = pattern.slice(0, dynamicIndex)
+  let staticPrefix = rawStaticPrefix.replace(/[/\\]+$/, '')
+  if (staticPrefix.length === 0) return rootDir
+  return resolveFilePath(
+    rootDir,
+    /[/\\]$/.test(rawStaticPrefix) ? staticPrefix : path.dirname(staticPrefix),
+  )
+}
+
+async function collectFiles(root: string, filePaths: Set<string>): Promise<void> {
+  let stat
+  try {
+    stat = await fsPromises.stat(root)
+  } catch (error) {
+    if (isPathNotFoundError(error)) return
+    throw error
+  }
+
+  if (stat.isFile()) {
+    filePaths.add(normalizeFilePath(root))
+    return
+  }
+  if (!stat.isDirectory()) return
+
+  let entries = await fsPromises.readdir(root, { withFileTypes: true })
+  for (let entry of entries) {
+    let entryPath = path.join(root, entry.name)
+    if (entry.isDirectory()) {
+      await collectFiles(entryPath, filePaths)
+    } else if (entry.isFile()) {
+      filePaths.add(normalizeFilePath(entryPath))
+    }
+  }
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await fsPromises.access(filePath)
+    return true
+  } catch (error) {
+    if (isPathNotFoundError(error)) return false
+    throw error
+  }
+}
+
+function isPathNotFoundError(
+  error: unknown,
+): error is NodeJS.ErrnoException & { code: 'ENOENT' | 'ENOTDIR' } {
+  return (
+    error instanceof Error &&
+    'code' in error &&
+    (error.code === 'ENOENT' || error.code === 'ENOTDIR')
+  )
+}