@remix-run/assets 0.2.0 → 0.4.0

package/src/lib/asset-server.ts

@@ -1,9 +1,22 @@
 import * as path from 'node:path'
 import * as fs from 'node:fs'
 import { createAccessPolicy } from './access.ts'
-import { isAssetServerCompilationError } from './compilation-error.ts'
+import {
+  createAssetServerCompilationError,
+  isAssetServerCompilationError,
+} from './compilation-error.ts'
+import { createFileCompiler, createResponseForFile } from './files/compiler.ts'
+import type { FileCompiler } from './files/compiler.ts'
+import { normalizeFilesOptions, serializeAssetTransformInvocations } from './files/config.ts'
+import type {
+  AssetRequestTransformMap,
+  AssetServerFilesOptions,
+  AssetTransformInvocation,
+  ResolvedAssetServerFilesOptions,
+} from './files/config.ts'
 import { getFingerprintRequestCacheControl, parseFingerprintSuffix } from './fingerprint.ts'
-import { normalizeFilePath } from './paths.ts'
+import { getInjectedPackageRouteConfigs } from './injected-packages.ts'
+import { normalizeFilePath, normalizePathname } from './paths.ts'
 import { compileRoutes } from './routes.ts'
 import type { CompiledRoutes } from './routes.ts'
 import { createResponseForScript, createScriptCompiler } from './scripts/compiler.ts'
@@ -53,7 +66,13 @@ interface AssetServerScriptOptions {
 
 const scriptExtensionSet = new Set<string>(supportedScriptExtensions)
 
-export interface AssetServerOptions {
+/**
+ * Options used to construct an {@link AssetServer} via {@link createAssetServer}.
+ */
+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 relative to `basePath`. */
   /** File patterns keyed by public URL patterns. */
   fileMap: Readonly<Record<string, string>>
   /**
@@ -100,6 +119,12 @@ export interface AssetServerOptions {
    * Script-only configuration.
    */
   scripts?: AssetServerScriptOptions
+  /**
+   * Leaf file asset configuration. Files configured here are served directly and can be
+   * referenced from CSS `url(...)` rules. Compiled asset extensions like `.css` and script
+   * module extensions are not allowed here.
+   */
+  files?: AssetServerFilesOptions<transforms>
   /**
    * Enable filesystem-backed cache invalidation for long-lived server instances.
    * Enabled by default. Pass `true` to use the default watcher options, an options
@@ -113,7 +138,26 @@ export interface AssetServerOptions {
   onError?: (error: unknown) => void | Response | Promise<void | Response>
 }
 
-export interface AssetServer {
+type AssetServerCreateOptions<transforms extends AssetRequestTransformMap> = Omit<
+  AssetServerOptions<transforms>,
+  'files'
+> & {
+  files?: Omit<AssetServerFilesOptions<transforms>, 'transforms'> & {
+    transforms?: transforms
+  }
+}
+
+export type AssetServerGetHrefOptions<transforms extends AssetRequestTransformMap> =
+  | undefined
+  | {
+      transform: readonly AssetTransformInvocation<transforms>[]
+    }
+
+/**
+ * Serves compiled scripts and styles for asset requests routed to it.
+ * Construct with {@link createAssetServer}.
+ */
+export interface AssetServer<transforms extends AssetRequestTransformMap = {}> {
   /**
    * Serves a script or style request. Returns `Response | null` — null means the request
    * was not handled by this server, letting the router fall through to a 404.
@@ -122,7 +166,7 @@ export interface AssetServer {
   /**
    * Returns the request href for a served asset file.
    */
-  getHref(filePath: string): Promise<string>
+  getHref(filePath: string, options?: AssetServerGetHrefOptions<transforms>): Promise<string>
   /**
    * Returns preload URLs for one or more served asset files, ordered shallowest-first.
    */
@@ -133,12 +177,14 @@ export interface AssetServer {
   close(): Promise<void>
 }
 
-type ResolvedAssetServerOptions = {
+type ResolvedAssetServerOptions<transforms extends AssetRequestTransformMap> = {
   allow: readonly string[]
+  basePath: string
   buildId?: string
   define?: Record<string, string>
   deny?: readonly string[]
   external: string[]
+  files: ResolvedAssetServerFilesOptions
   fingerprintAssets: boolean
   minify: boolean
   onError: NonNullable<AssetServerOptions['onError']>
@@ -151,14 +197,18 @@ type ResolvedAssetServerOptions = {
   watchOptions: AssetServerWatchOptions | null
 }
 
-const chokidarWatcherByAssetServer = new WeakMap<AssetServer, ChokidarWatcher>()
-const watcherByAssetServer = new WeakMap<AssetServer, AssetServerWatcher>()
+const chokidarWatcherByAssetServer = new WeakMap<object, ChokidarWatcher>()
+const watcherByAssetServer = new WeakMap<object, AssetServerWatcher>()
 
-export function getInternalChokidarWatcher(assetServer: AssetServer): ChokidarWatcher | undefined {
+export function getInternalChokidarWatcher<transforms extends AssetRequestTransformMap>(
+  assetServer: AssetServer<transforms>,
+): ChokidarWatcher | undefined {
   return chokidarWatcherByAssetServer.get(assetServer)
 }
 
-export function getInternalWatchTargets(assetServer: AssetServer): readonly string[] {
+export function getInternalWatchTargets<transforms extends AssetRequestTransformMap>(
+  assetServer: AssetServer<transforms>,
+): readonly string[] {
   return watcherByAssetServer.get(assetServer)?.getWatchedTargets() ?? []
 }
 
@@ -174,8 +224,9 @@ export function getInternalWatchTargets(assetServer: AssetServer): readonly stri
  * @example
  * ```ts
  * let assetServer = createAssetServer({
+ *   basePath: '/assets',
  *   fileMap: {
- *     '/assets/app/*path': 'app/*path',
+ *     '/app/*path': 'app/*path',
  *   },
  *   allow: ['app/**'],
  * })
@@ -183,7 +234,9 @@ export function getInternalWatchTargets(assetServer: AssetServer): readonly stri
  * route('/assets/*path', ({ request }) => assetServer.fetch(request))
  * ```
  */
-export function createAssetServer(options: AssetServerOptions): AssetServer {
+export function createAssetServer<const transforms extends AssetRequestTransformMap = {}>(
+  options: AssetServerCreateOptions<transforms>,
+): AssetServer<transforms> {
   let resolvedOptions = resolveAssetServerOptions(options)
   let accessPolicy = createAccessPolicy({
     allow: resolvedOptions.allow,
@@ -192,12 +245,14 @@ export function createAssetServer(options: AssetServerOptions): AssetServer {
   })
   let watcher: AssetServerWatcher | null = null
   let chokidarWatcher: ChokidarWatcher | null = null
+  let fileCompiler: FileCompiler | null = null
   let scriptCompiler = createScriptCompiler({
     buildId: resolvedOptions.buildId,
     define: resolvedOptions.define,
     external: resolvedOptions.external,
     fingerprintAssets: resolvedOptions.fingerprintAssets,
     isAllowed: accessPolicy.isAllowed,
+    isDenied: accessPolicy.isDenied,
     minify: resolvedOptions.minify,
     onWatchDirectoriesChange: (delta) => {
       if (!watcher) return
@@ -214,11 +269,27 @@ export function createAssetServer(options: AssetServerOptions): AssetServer {
   let styleCompiler = createStyleCompiler({
     buildId: resolvedOptions.buildId,
     fingerprintAssets: resolvedOptions.fingerprintAssets,
+    getServedFileUrl: (identityPath: string, options: { transform: readonly string[] | null }) => {
+      if (!fileCompiler) {
+        throw createAssetServerCompilationError(`File type is not supported: ${identityPath}`, {
+          code: 'FILE_NOT_SUPPORTED',
+        })
+      }
+
+      if (options.transform !== null) {
+        fileCompiler.validateTransformQuery(options.transform)
+      }
+
+      return fileCompiler.getHref(identityPath, { transform: options.transform })
+    },
     isAllowed: accessPolicy.isAllowed,
+    isServedFilePath(filePath) {
+      return fileCompiler?.isServedFilePath(filePath) ?? false
+    },
     minify: resolvedOptions.minify,
     onWatchDirectoriesChange: (delta) => {
       if (!watcher) return
-      watcher.updateWatchedDirectories(delta)
+      watcher.updateWatchedDirectories(delta, { includeAncestors: false })
     },
     rootDir: resolvedOptions.rootDir,
     routes: resolvedOptions.routes,
@@ -227,6 +298,20 @@ export function createAssetServer(options: AssetServerOptions): AssetServer {
     targets: resolvedOptions.stylesTarget,
     watchIgnore: resolvedOptions.watchOptions?.ignore,
   })
+  if (resolvedOptions.files.extensions.length > 0) {
+    fileCompiler = createFileCompiler({
+      buildId: resolvedOptions.buildId,
+      cache: resolvedOptions.files.cache,
+      extensions: resolvedOptions.files.extensions,
+      fingerprintAssets: resolvedOptions.fingerprintAssets,
+      globalTransforms: resolvedOptions.files.globalTransforms,
+      isAllowed: accessPolicy.isAllowed,
+      maxRequestTransforms: resolvedOptions.files.maxRequestTransforms,
+      transforms: resolvedOptions.files.transforms,
+      rootDir: resolvedOptions.rootDir,
+      routes: resolvedOptions.routes,
+    })
+  }
   if (resolvedOptions.watchOptions) {
     watcher = createAssetServerWatcher({
       ...resolvedOptions.watchOptions,
@@ -252,16 +337,19 @@ export function createAssetServer(options: AssetServerOptions): AssetServer {
       let normalizedFilePath = normalizeFilePath(filePath)
       await scriptCompiler.handleFileEvent(normalizedFilePath, event)
       await styleCompiler.handleFileEvent(normalizedFilePath, event)
+      await fileCompiler?.handleFileEvent(normalizedFilePath, event)
     } catch (error) {
       console.error(`There was an error invalidating the asset server cache: ${error}`)
     }
   }
 
-  let assetServer: AssetServer = {
+  let assetServer: AssetServer<transforms> = {
     async fetch(request) {
       if (request.method !== 'GET' && request.method !== 'HEAD') return null
 
-      let parsedRequestPathname = parseAssetRequestPathname(new URL(request.url).pathname, {
+      let requestUrl = new URL(request.url)
+      let requestedTransform = normalizeRequestedTransformQuery(requestUrl.searchParams)
+      let parsedRequestPathname = parseAssetRequestPathname(requestUrl.pathname, {
         fingerprintAssets: resolvedOptions.fingerprintAssets,
         routes: resolvedOptions.routes,
       })
@@ -271,6 +359,11 @@ export function createAssetServer(options: AssetServerOptions): AssetServer {
         let ifNoneMatch = request.headers.get('If-None-Match')
 
         if (isStyleFilePath(parsedRequestPathname.filePath)) {
+          if (requestedTransform !== null) {
+            return badRequest(
+              'Asset request transforms are only supported for configured file assets',
+            )
+          }
           let styleResult = await styleCompiler.getStyle(parsedRequestPathname.filePath, {
             ifNoneMatch,
             isSourceMapRequest: parsedRequestPathname.isSourceMapRequest,
@@ -299,9 +392,43 @@ export function createAssetServer(options: AssetServerOptions): AssetServer {
         }
 
         if (!isScriptFilePath(parsedRequestPathname.filePath)) {
-          return null
+          if (!fileCompiler?.isServedFilePath(parsedRequestPathname.filePath)) {
+            return null
+          }
+          if (parsedRequestPathname.isSourceMapRequest) {
+            return null
+          }
+
+          let fileResult = await fileCompiler.getFile(parsedRequestPathname.filePath, {
+            ifNoneMatch,
+            requestedFingerprint: parsedRequestPathname.requestedFingerprint,
+            transform: requestedTransform,
+          })
+          if (fileResult.type === 'not-modified') {
+            return new Response(null, {
+              status: 304,
+              headers: { ETag: fileResult.etag },
+            })
+          }
+
+          if (parsedRequestPathname.requestedFingerprint !== null) {
+            if (fileResult.file.fingerprint !== parsedRequestPathname.requestedFingerprint) {
+              return null
+            }
+          }
+
+          return createResponseForFile(fileResult.file, {
+            cacheControl: parsedRequestPathname.cacheControl,
+            ifNoneMatch,
+            method: request.method,
+          })
         }
 
+        if (requestedTransform !== null) {
+          return badRequest(
+            'Asset request transforms are only supported for configured file assets',
+          )
+        }
         let scriptResult = await scriptCompiler.getScript(parsedRequestPathname.filePath, {
           ifNoneMatch,
           isSourceMapRequest: parsedRequestPathname.isSourceMapRequest,
@@ -336,52 +463,113 @@ export function createAssetServer(options: AssetServerOptions): AssetServer {
         ) {
           return null
         }
+        if (isAssetServerCompilationError(error) && error.code === 'FILE_TRANSFORM_QUERY_INVALID') {
+          return new Response(error.message, {
+            status: 400,
+            headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+          })
+        }
 
         return responseForError(error)
       }
     },
 
-    async getHref(filePath) {
-      if (isStyleFilePath(filePath)) {
+    async getHref(filePath, hrefOptions) {
+      let transform = getHrefTransform(hrefOptions, resolvedOptions.files)
+      let typeCheckFilePath = stripFilePathUrlSuffix(filePath)
+
+      if (isStyleFilePath(typeCheckFilePath)) {
+        if (transform !== null) {
+          throw new TypeError(
+            'assetServer.getHref() only supports transforms for configured file assets',
+          )
+        }
         return styleCompiler.getHref(filePath)
       }
 
+      if (fileCompiler?.isServedFilePath(typeCheckFilePath)) {
+        return fileCompiler.getHref(filePath, {
+          transform,
+        })
+      }
+
+      if (!isScriptFilePath(typeCheckFilePath)) {
+        throw createAssetServerCompilationError(`File type is not supported: ${filePath}`, {
+          code: 'FILE_NOT_SUPPORTED',
+        })
+      }
+
+      if (transform !== null) {
+        throw new TypeError(
+          'assetServer.getHref() only supports transforms for configured file assets',
+        )
+      }
+
       return scriptCompiler.getHref(filePath)
     },
     async getPreloads(filePath) {
       let filePaths = Array.isArray(filePath) ? filePath : [filePath]
+      let fileAssetFiles: string[] = []
       let styleFiles: string[] = []
       let scriptFiles: string[] = []
+      let groupedAssetTypes: ('script' | 'style' | 'file')[] = []
 
       for (let nextFilePath of filePaths) {
-        if (isStyleFilePath(nextFilePath)) {
+        let typeCheckFilePath = stripFilePathUrlSuffix(nextFilePath)
+
+        if (isStyleFilePath(typeCheckFilePath)) {
+          if (!groupedAssetTypes.includes('style')) {
+            groupedAssetTypes.push('style')
+          }
           styleFiles.push(nextFilePath)
           continue
         }
 
+        if (fileCompiler?.isServedFilePath(typeCheckFilePath)) {
+          if (!groupedAssetTypes.includes('file')) {
+            groupedAssetTypes.push('file')
+          }
+          fileAssetFiles.push(nextFilePath)
+          continue
+        }
+
+        if (!groupedAssetTypes.includes('script')) {
+          groupedAssetTypes.push('script')
+        }
         scriptFiles.push(nextFilePath)
       }
 
-      if (styleFiles.length === 0 && scriptFiles.length === 0) {
+      if (styleFiles.length === 0 && scriptFiles.length === 0 && fileAssetFiles.length === 0) {
         return []
       }
 
-      if (styleFiles.length === 0) {
+      if (styleFiles.length === 0 && fileAssetFiles.length === 0) {
         return flattenPreloadLayers(await scriptCompiler.getPreloadLayers(filePath))
       }
 
-      if (scriptFiles.length === 0) {
+      if (scriptFiles.length === 0 && fileAssetFiles.length === 0) {
         return flattenPreloadLayers(await styleCompiler.getPreloadLayers(filePath))
       }
 
-      // Mixed asset type preloads need to be merged, so we merge in order of first asset type seen
-      let scriptPreloadLayersPromise = scriptCompiler.getPreloadLayers(scriptFiles)
-      let stylePreloadLayersPromise = styleCompiler.getPreloadLayers(styleFiles)
-      let preloadLayerGroups = isStyleFilePath(filePaths[0])
-        ? [stylePreloadLayersPromise, scriptPreloadLayersPromise]
-        : [scriptPreloadLayersPromise, stylePreloadLayersPromise]
+      if (scriptFiles.length === 0 && styleFiles.length === 0) {
+        return flattenPreloadLayers(await getFilePreloadLayers(fileCompiler, fileAssetFiles))
+      }
+
+      // Mixed asset type preloads need to be merged, so we merge in order of first asset type seen.
+      let preloadLayerGroupPromises = groupedAssetTypes.flatMap((assetType) => {
+        switch (assetType) {
+          case 'script':
+            return scriptFiles.length > 0 ? [scriptCompiler.getPreloadLayers(scriptFiles)] : []
+          case 'style':
+            return styleFiles.length > 0 ? [styleCompiler.getPreloadLayers(styleFiles)] : []
+          case 'file':
+            return fileAssetFiles.length > 0
+              ? [getFilePreloadLayers(fileCompiler, fileAssetFiles)]
+              : []
+        }
+      })
 
-      return mergePreloadLayers(await Promise.all(preloadLayerGroups))
+      return mergePreloadLayers(await Promise.all(preloadLayerGroupPromises))
     },
     async close() {
       await watcher?.close()
@@ -398,6 +586,24 @@ export function createAssetServer(options: AssetServerOptions): AssetServer {
   return assetServer
 }
 
+function getHrefTransform<transforms extends AssetRequestTransformMap>(
+  options: AssetServerGetHrefOptions<transforms> | undefined,
+  files: ResolvedAssetServerFilesOptions,
+): readonly string[] | null {
+  if (!options) return null
+  let transform = options.transform
+  if (transform.length === 0) {
+    return null
+  }
+
+  return serializeAssetTransformInvocations(transform, files.transforms, files.maxRequestTransforms)
+}
+
+function normalizeRequestedTransformQuery(searchParams: URLSearchParams): readonly string[] | null {
+  let transforms = searchParams.getAll('transform')
+  return transforms.length > 0 ? transforms : null
+}
+
 function internalServerError(): Response {
   return new Response('Internal Server Error', {
     status: 500,
@@ -405,6 +611,13 @@ function internalServerError(): Response {
   })
 }
 
+function badRequest(message: string): Response {
+  return new Response(message, {
+    status: 400,
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  })
+}
+
 function mergePreloadLayers(preloadLayersByRoot: readonly (readonly string[][])[]): string[] {
   let urls: string[] = []
   let seen = new Set<string>()
@@ -427,12 +640,40 @@ function flattenPreloadLayers(preloadLayers: readonly (readonly string[])[]): st
   return preloadLayers.flatMap((layer) => layer)
 }
 
+async function getFilePreloadLayers<transforms extends AssetRequestTransformMap>(
+  fileCompiler: FileCompiler | null,
+  filePaths: readonly string[],
+): Promise<string[][]> {
+  if (filePaths.length === 0) {
+    return []
+  }
+
+  if (!fileCompiler) {
+    throw createAssetServerCompilationError('File type is not supported', {
+      code: 'FILE_NOT_SUPPORTED',
+    })
+  }
+
+  return [
+    await Promise.all(
+      filePaths.map((filePath) =>
+        fileCompiler.getHref(filePath, {
+          transform: null,
+        }),
+      ),
+    ),
+  ]
+}
+
 function defaultErrorHandler(error: unknown): void {
   console.error(error)
 }
 
-function resolveAssetServerOptions(options: AssetServerOptions): ResolvedAssetServerOptions {
+function resolveAssetServerOptions<transforms extends AssetRequestTransformMap>(
+  options: AssetServerCreateOptions<transforms>,
+): ResolvedAssetServerOptions<transforms> {
   let rootDir = normalizeFilePath(fs.realpathSync(path.resolve(options.rootDir ?? process.cwd())))
+  let basePath = normalizeBasePath(options.basePath)
   let scriptOptions = options.scripts ?? {}
   let fingerprintOptions = normalizeFingerprintOptions({
     fingerprint: options.fingerprint,
@@ -441,18 +682,23 @@ function resolveAssetServerOptions(options: AssetServerOptions): ResolvedAssetSe
 
   return {
     allow: options.allow,
+    basePath,
     buildId: fingerprintOptions.buildId,
     define: scriptOptions.define,
     deny: options.deny,
     external: scriptOptions.external ?? [],
+    files: normalizeFilesOptions(options.files),
     fingerprintAssets: fingerprintOptions.enabled,
     minify: options.minify ?? false,
     onError: options.onError ?? defaultErrorHandler,
     rootDir,
-    routes: compileRoutes({
-      fileMap: options.fileMap,
-      rootDir,
-    }),
+    routes: compileRoutes(basePath, [
+      {
+        fileMap: options.fileMap,
+        rootDir,
+      },
+      ...getInjectedPackageRouteConfigs(),
+    ]),
     sourceMapSourcePaths: options.sourceMapSourcePaths ?? 'url',
     sourceMaps: options.sourceMaps,
     scriptsTarget: resolveScriptTarget(options.target),
@@ -461,6 +707,14 @@ function resolveAssetServerOptions(options: AssetServerOptions): ResolvedAssetSe
   }
 }
 
+function normalizeBasePath(basePath: string): string {
+  if (typeof basePath !== 'string') {
+    throw new TypeError('basePath must be a string')
+  }
+
+  return normalizePathname(basePath || '/').replace(/\/+$/, '') || '/'
+}
+
 function normalizeFingerprintOptions(options: {
   fingerprint: AssetServerOptions['fingerprint']
   watch: AssetServerOptions['watch']
@@ -535,3 +789,12 @@ function parseAssetRequestPathname(
 function isScriptFilePath(filePath: string): boolean {
   return scriptExtensionSet.has(path.extname(filePath).toLowerCase())
 }
+
+function stripFilePathUrlSuffix(filePath: string): string {
+  if (filePath.startsWith('file://')) {
+    return new URL(filePath).pathname
+  }
+
+  let queryIndex = filePath.indexOf('?')
+  return queryIndex === -1 ? filePath : filePath.slice(0, queryIndex)
+}

package/src/lib/compilation-error.ts

@@ -1,7 +1,12 @@
 type AssetServerCompilationErrorCode =
   | 'FILE_NOT_FOUND'
   | 'FILE_NOT_ALLOWED'
+  | 'FILE_NOT_SUPPORTED'
   | 'FILE_OUTSIDE_FILE_MAP'
+  | 'FILE_TRANSFORM_QUERY_INVALID'
+  | 'FILE_TRANSFORM_NOT_SUPPORTED'
+  | 'FILE_TRANSFORM_RESULT_INVALID'
+  | 'FILE_TRANSFORM_FAILED'
   | 'COMMONJS_NOT_SUPPORTED'
   | 'TRANSFORM_FAILED'
   | 'EMIT_FAILED'
@@ -9,6 +14,10 @@ type AssetServerCompilationErrorCode =
   | 'IMPORT_NOT_SUPPORTED'
   | 'IMPORT_NOT_ALLOWED'
   | 'IMPORT_OUTSIDE_FILE_MAP'
+  | 'URL_RESOLUTION_FAILED'
+  | 'URL_NOT_SUPPORTED'
+  | 'URL_NOT_ALLOWED'
+  | 'URL_OUTSIDE_FILE_MAP'
 
 /**
  * Internal error used by the request-time asset compilation pipeline.