@remix-run/assets 0.5.0 → 0.7.0

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')
+  )
+}

package/src/lib/routes.ts

@@ -1,186 +1,218 @@
-import {
-  getRoutePatternCaptures,
-  RoutePattern,
-  type RoutePatternCapture,
-} from '@remix-run/route-pattern'
-import { createHref } from '@remix-run/route-pattern/href'
-import { createMatcher, type Matcher } from '@remix-run/route-pattern/match'
+import * as fs from 'node:fs'
 
 import {
-  getRelativeFilePath,
   isAbsoluteFilePath,
   normalizeFilePath,
   normalizePathname,
   resolveFilePath,
 } from './paths.ts'
 
-interface AssetRouteDefinition {
-  urlPattern: string
-  filePattern: string
-}
-
-interface RouteConfig {
-  fileMap: Readonly<Record<string, string>>
+interface MountConfig {
+  mounts: Readonly<Record<string, string>>
   rootDir: string
 }
 
-interface CompiledRoute {
-  rootDir: string
-  urlPattern: RoutePattern
-  urlMatcher: Matcher
-  filePattern: RoutePattern
-  fileMatcher: Matcher
+interface CompiledMount {
+  fileRoot: string
+  fileRootValue: string
+  urlRoot: string
+  urlRootKey: string
 }
 
 export interface CompiledRoutes {
   resolveUrlPathname(pathname: string): string | null
+  matchUrlPathname(pathname: string): AssetRouteMatch | null
   toUrlPathname(filePath: string): string | null
+  matchFilePath(filePath: string): AssetRouteMatch | null
 }
 
-function normalizeFilePattern(pattern: string): string {
-  if (isAbsoluteFilePath(pattern)) {
-    throw new Error(
-      `File route patterns must be relative to the asset server root.\nPattern: ${pattern}`,
-    )
-  }
-
-  return normalizePathname(pattern)
+export interface AssetRouteMatch {
+  filePath: string
+  fileRoot: string
+  urlPathname: string
+  urlRoot: string
 }
 
 export function compileRoutes(
   basePath: string,
-  routeConfigs: readonly RouteConfig[],
+  mountConfigs: readonly MountConfig[],
 ): CompiledRoutes {
-  if (routeConfigs.every((routeConfig) => Object.keys(routeConfig.fileMap).length === 0)) {
-    throw new Error('createAssetServer() requires at least one configured fileMap entry.')
-  }
-
-  let compiledRoutes = routeConfigs.flatMap((routeConfig) =>
-    Object.entries(routeConfig.fileMap).map(([urlPattern, filePattern]) =>
-      compileRoute(
-        {
-          filePattern,
-          urlPattern,
-        },
-        {
-          basePath,
-          rootDir: routeConfig.rootDir,
-        },
-      ),
-    ),
-  )
+  let compiledMounts = mountConfigs.flatMap((mountConfig) => {
+    let configMounts = Object.entries(mountConfig.mounts).map(([urlRoot, fileRoot]) =>
+      compileMount(urlRoot, fileRoot, {
+        basePath,
+        rootDir: mountConfig.rootDir,
+      }),
+    )
+    validateNoOverlappingMounts(configMounts)
+    return configMounts
+  })
+  validateNoOverlappingUrlRoots(compiledMounts)
 
   return {
     resolveUrlPathname(pathname) {
-      let normalizedPathname = normalizePathname(pathname)
-
-      for (let route of compiledRoutes) {
-        let match = route.urlMatcher.match(`http://remix.run${normalizedPathname}`)
-        if (!match) continue
-        let relativeFilePath = decodeURIComponent(
-          createHref(route.filePattern, match.params),
-        ).replace(/^\/+/, '')
-        return resolveFilePath(route.rootDir, relativeFilePath)
-      }
-
-      return null
+      return matchUrlPathname(pathname)?.filePath ?? null
     },
+    matchUrlPathname,
     toUrlPathname(filePath) {
-      let normalizedFilePath = normalizeFilePath(filePath)
+      return matchFilePath(filePath)?.urlPathname ?? null
+    },
+    matchFilePath,
+  }
 
-      for (let route of compiledRoutes) {
-        let relativeFilePath = getRelativeFilePath(route.rootDir, normalizedFilePath)
-        let match = route.fileMatcher.match(`http://remix.run/${relativeFilePath}`)
-        if (!match) continue
-        return normalizePathname(createHref(route.urlPattern, match.params))
+  function matchUrlPathname(pathname: string): AssetRouteMatch | null {
+    let normalizedPathname = normalizePathname(pathname)
+
+    for (let mount of compiledMounts) {
+      let relativePathname = getPathWithinRoot(mount.urlRoot, normalizedPathname)
+      if (relativePathname === null) continue
+      let filePath = resolveFilePath(mount.fileRoot, decodeURIComponent(relativePathname))
+      if (getPathWithinRoot(mount.fileRoot, filePath) === null) return null
+
+      return {
+        filePath,
+        fileRoot: mount.fileRootValue,
+        urlPathname: normalizedPathname,
+        urlRoot: mount.urlRoot,
       }
+    }
 
-      return null
-    },
+    return null
+  }
+
+  function matchFilePath(filePath: string): AssetRouteMatch | null {
+    let normalizedFilePath = normalizeFilePath(filePath)
+
+    for (let mount of compiledMounts) {
+      let relativeFilePath = getPathWithinRoot(mount.fileRoot, normalizedFilePath)
+      if (relativeFilePath === null) continue
+      let encodedFilePath = relativeFilePath.split('/').map(encodeURIComponent).join('/')
+
+      return {
+        filePath: normalizedFilePath,
+        fileRoot: mount.fileRootValue,
+        urlPathname: joinUrlPath(mount.urlRoot, encodedFilePath),
+        urlRoot: mount.urlRoot,
+      }
+    }
+
+    return null
   }
 }
 
-function compileRoute(
-  route: AssetRouteDefinition,
+function compileMount(
+  urlRoot: string,
+  fileRoot: string,
   options: {
     basePath: string
     rootDir: string
   },
-): CompiledRoute {
-  let basePath = normalizePathname(options.basePath).replace(/\/+$/, '') || '/'
-  let relativeUrlPattern = normalizePathname(route.urlPattern)
-  let urlPatternSource = normalizePathname(
-    `${basePath.replace(/\/+$/, '')}/${relativeUrlPattern.replace(/^\/+/, '')}`,
-  )
-  let filePatternSource = normalizeFilePattern(route.filePattern)
-
-  let urlPattern = RoutePattern.parse(urlPatternSource)
-  let filePattern = RoutePattern.parse(filePatternSource)
-
-  validateNoUnnamedWildcards(urlPattern, 'URL')
-  validateNoUnnamedWildcards(filePattern, 'File')
-  validateRoutePatterns(urlPattern, filePattern)
+): CompiledMount {
+  if (isAbsoluteFilePath(fileRoot)) {
+    throw new TypeError(`mounts values must be relative to rootDir. Received "${fileRoot}".`)
+  }
 
   return {
-    rootDir: normalizeFilePath(options.rootDir).replace(/\/+$/, ''),
-    urlPattern,
-    urlMatcher: createMatcher(urlPattern),
-    filePattern,
-    fileMatcher: createMatcher(stripDotSegments(filePatternSource)),
+    fileRoot: resolveMountFileRoot(options.rootDir, fileRoot),
+    fileRootValue: fileRoot,
+    urlRoot: joinUrlPath(normalizeMountUrlRoot(options.basePath), normalizeMountUrlRoot(urlRoot)),
+    urlRootKey: urlRoot,
   }
 }
 
-function stripDotSegments(pattern: string): string {
-  let segments: string[] = []
+function normalizeMountUrlRoot(urlRoot: string): string {
+  let normalizedRoot = normalizePathname(urlRoot).replace(/\/+$/, '') || '/'
+  let url = new URL(normalizedRoot, 'http://remix.run')
 
-  for (let segment of pattern.split('/')) {
-    if (segment === '' || segment === '.') continue
-    if (segment === '..') {
-      segments.pop()
-      continue
-    }
-    segments.push(segment)
+  if (
+    url.search !== '' ||
+    url.hash !== '' ||
+    getUrlPathSegmentCount(url.pathname) !== getUrlPathSegmentCount(normalizedRoot)
+  ) {
+    throw new TypeError(
+      `mounts keys must be URL pathnames without query strings, fragments, or encoded dot segments. Received "${urlRoot}".`,
+    )
   }
 
-  return segments.join('/')
+  return url.pathname.replace(/\/+$/, '') || '/'
 }
 
-function validateRoutePatterns(urlPattern: RoutePattern, filePattern: RoutePattern): void {
-  let urlCaptures = getPathnameCaptures(urlPattern)
-  let fileCaptures = getPathnameCaptures(filePattern)
-  if (urlCaptures.length !== fileCaptures.length) {
-    throw new Error(
-      `Route patterns must have matching capture structure.\nURL: ${urlPattern}\nFile: ${filePattern}`,
-    )
+export function resolveMountFileRoot(rootDir: string, fileRoot: string): string {
+  let resolvedRoot = resolveFilePath(rootDir, fileRoot)
+
+  try {
+    resolvedRoot = normalizeFilePath(fs.realpathSync(resolvedRoot))
+  } catch (error) {
+    if (!isUnresolvedPathError(error, resolvedRoot)) throw error
   }
 
-  for (let i = 0; i < urlCaptures.length; i++) {
-    let urlCapture = urlCaptures[i]
-    let fileCapture = fileCaptures[i]
-    if (urlCapture.type !== fileCapture.type || urlCapture.name !== fileCapture.name) {
-      throw new Error(
-        `Route patterns must have matching capture structure.\nURL: ${urlPattern}\nFile: ${filePattern}`,
-      )
+  return resolvedRoot.replace(/\/+$/, '') || '/'
+}
+
+function getUrlPathSegmentCount(pathname: string): number {
+  return pathname.split('/').filter((segment) => segment !== '').length
+}
+
+function joinUrlPath(root: string, path: string): string {
+  if (path === '' || path === '/') return normalizeMountUrlRoot(root)
+  return normalizePathname(`${root.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`)
+}
+
+function getPathWithinRoot(root: string, value: string): string | null {
+  if (value === root) return ''
+  if (root === '/') return value.slice(1)
+  if (!value.startsWith(`${root}/`)) return null
+  return value.slice(root.length + 1)
+}
+
+function validateNoOverlappingMounts(mounts: readonly CompiledMount[]): void {
+  for (let index = 0; index < mounts.length; index++) {
+    let mount = mounts[index]
+
+    for (let otherIndex = index + 1; otherIndex < mounts.length; otherIndex++) {
+      let otherMount = mounts[otherIndex]
+
+      if (rootsOverlap(mount.fileRoot, otherMount.fileRoot)) {
+        throw new TypeError(
+          `mounts values must not overlap. Received "${mount.fileRootValue}" and "${otherMount.fileRootValue}", resolving to "${mount.fileRoot}" and "${otherMount.fileRoot}".`,
+        )
+      }
     }
   }
 }
 
-function validateNoUnnamedWildcards(pattern: RoutePattern, label: string): void {
-  if (
-    getRoutePatternCaptures(pattern).some(
-      (capture) => capture.part === 'pathname' && capture.type === '*' && capture.name === '*',
-    )
-  ) {
-    throw new Error(
-      `${label} route patterns must use named wildcards for reversible mapping.\nPattern: ${pattern}`,
-    )
+function validateNoOverlappingUrlRoots(mounts: readonly CompiledMount[]): void {
+  for (let index = 0; index < mounts.length; index++) {
+    let mount = mounts[index]
+
+    for (let otherIndex = index + 1; otherIndex < mounts.length; otherIndex++) {
+      let otherMount = mounts[otherIndex]
+      if (!rootsOverlap(mount.urlRoot, otherMount.urlRoot)) continue
+
+      throw new TypeError(
+        `mounts keys must not overlap. Received "${mount.urlRootKey}" and "${otherMount.urlRootKey}".`,
+      )
+    }
   }
 }
 
-type PathnameCapture = RoutePatternCapture & { readonly part: 'pathname' }
+function rootsOverlap(root: string, otherRoot: string): boolean {
+  return (
+    root === otherRoot ||
+    root === '/' ||
+    otherRoot === '/' ||
+    root.startsWith(`${otherRoot}/`) ||
+    otherRoot.startsWith(`${root}/`)
+  )
+}
 
-function getPathnameCaptures(pattern: RoutePattern): Array<PathnameCapture> {
-  return getRoutePatternCaptures(pattern).filter(
-    (capture): capture is PathnameCapture => capture.part === 'pathname',
+function isUnresolvedPathError(error: unknown, filePath: string): boolean {
+  // Windows reports UNKNOWN rather than ENOENT when a UNC share cannot be reached.
+  return (
+    error instanceof Error &&
+    'code' in error &&
+    (error.code === 'ENOENT' ||
+      error.code === 'ENOTDIR' ||
+      (error.code === 'UNKNOWN' && filePath.startsWith('//')))
   )
 }