@fastify/static 8.2.0 → 8.3.0

package/.github/workflows/ci.yml

@@ -14,6 +14,11 @@ on:
       - 'docs/**'
       - '*.md'
 
+# This allows a subsequently queued workflow run to interrupt previous runs
+concurrency:
+    group: "${{ github.workflow }}-${{ github.event.pull_request.head.label || github.head_ref || github.ref }}"
+    cancel-in-progress: true
+
 permissions:
   contents: read
 

package/LICENSE

@@ -1,6 +1,8 @@
 MIT License
 
-Copyright (c) 2017-2023 Fastify
+Copyright (c) 2017-present The Fastify team
+
+The Fastify team members are listed at https://github.com/fastify/fastify#team.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -16,7 +16,7 @@ npm i @fastify/static
 | Plugin version | Fastify version |
 | ---------------|-----------------|
 | `>=8.x`        | `^5.x`          |
-| `^7.x`         | `^4.x`          |
+| `>=7.x <8.x`   | `^4.x`          |
 | `>=5.x <7.x`   | `^3.x`          |
 | `>=2.x <5.x`   | `^2.x`          |
 | `^1.x`         | `^1.x`          |
@@ -138,7 +138,12 @@ fastify.get('/favicon.ico', function (req, reply) {
 
 ### Options
 
-#### `root` (required)
+#### `serve`
+Default: `true`
+
+If set to `false`, the plugin will not serve files from the `root` directory.
+
+#### `root` (required if `serve` is not false)
 
 The absolute path of the directory containing the files to serve.
 The file to serve is determined by combining `req.url` with the
@@ -278,7 +283,7 @@ Example:
 fastify.register(require('@fastify/static'), {
   root: path.join(__dirname, 'public'),
   prefix: '/public/',
-  index: false
+  index: false,
   list: true
 })
 ```
@@ -364,7 +369,7 @@ Default: `['']`
 
 Directory list can respond to different routes declared in `list.names`.
 
-> 🛈 Note: If a file with the same name exists, the actual file is sent.
+> ℹ️ Note: If a file with the same name exists, the actual file is sent.
 
 Example:
 

package/index.js

@@ -16,10 +16,17 @@ const asteriskRegex = /\*/gu
 
 const supportedEncodings = ['br', 'gzip', 'deflate']
 send.mime.default_type = 'application/octet-stream'
+const encodingExtensionMap = {
+  br: '.br',
+  gzip: '.gz'
+}
 
+/** @type {import("fastify").FastifyPluginAsync<import("./types").FastifyStaticOptions>} */
 async function fastifyStatic (fastify, opts) {
-  opts.root = normalizeRoot(opts.root)
-  checkRootPathForErrors(fastify, opts.root)
+  if (opts.serve !== false || opts.root !== undefined) {
+    opts.root = normalizeRoot(opts.root)
+    checkRootPathForErrors(fastify, opts.root)
+  }
 
   const setHeaders = opts.setHeaders
   if (setHeaders !== undefined && typeof setHeaders !== 'function') {
@@ -31,9 +38,7 @@ async function fastifyStatic (fastify, opts) {
     throw invalidDirListOpts
   }
 
-  if (opts.dotfiles === undefined) {
-    opts.dotfiles = 'allow'
-  }
+  opts.dotfiles ??= 'allow'
 
   const sendOptions = {
     root: opts.root,
@@ -49,7 +54,7 @@ async function fastifyStatic (fastify, opts) {
     maxAge: opts.maxAge
   }
 
-  let prefix = opts.prefix ?? (opts.prefix = '/')
+  let prefix = opts.prefix ??= '/'
 
   if (!opts.prefixAvoidTrailingSlash) {
     prefix =
@@ -62,7 +67,7 @@ async function fastifyStatic (fastify, opts) {
   const routeOpts = {
     constraints: opts.constraints,
     schema: {
-      hide: opts.schemaHide !== undefined ? opts.schemaHide : true
+      hide: opts.schemaHide ?? true
     },
     logLevel: opts.logLevel,
     errorHandler (error, request, reply) {
@@ -126,7 +131,7 @@ async function fastifyStatic (fastify, opts) {
         })
       }
     } else {
-      const indexes = opts.index === undefined ? ['index.html'] : [].concat(opts.index)
+      const indexes = new Set(opts.index === undefined ? ['index.html'] : [].concat(opts.index))
       const indexDirs = new Map()
       const routes = new Set()
 
@@ -151,7 +156,7 @@ async function fastifyStatic (fastify, opts) {
           setUpHeadAndGet(routeOpts, route, `/${file}`, rootPath)
 
           const key = path.posix.basename(route)
-          if (indexes.includes(key) && !indexDirs.has(key)) {
+          if (indexes.has(key) && !indexDirs.has(key)) {
             indexDirs.set(path.posix.dirname(route), rootPath)
           }
         }
@@ -171,6 +176,15 @@ async function fastifyStatic (fastify, opts) {
 
   const allowedPath = opts.allowedPath
 
+  /**
+   * @param {import("fastify").FastifyRequest} request
+   * @param {import("fastify").FastifyReply} reply
+   * @param {string} pathname
+   * @param {import("./types").FastifyStaticOptions['root']} rootPath
+   * @param {number} [rootPathOffset]
+   * @param {import("@fastify/send").SendOptions} [pumpOptions]
+   * @param {Set<string>} [checkedEncodings]
+   */
   async function pumpSendToReply (
     request,
     reply,
@@ -189,6 +203,8 @@ async function fastifyStatic (fastify, opts) {
       } else {
         options.root = rootPath
       }
+    } else if (path.isAbsolute(pathname) === false) {
+      return reply.callNotFound()
     }
 
     if (allowedPath && !allowedPath(pathname, options.root, request)) {
@@ -203,9 +219,7 @@ async function fastifyStatic (fastify, opts) {
        * We conditionally create this structure to track our attempts
        * at sending pre-compressed assets
        */
-      if (!checkedEncodings) {
-        checkedEncodings = new Set()
-      }
+      checkedEncodings ??= new Set()
 
       encoding = getEncodingHeader(request.headers, checkedEncodings)
 
@@ -215,9 +229,9 @@ async function fastifyStatic (fastify, opts) {
           if (!pathname) {
             return reply.callNotFound()
           }
-          pathnameForSend = pathnameForSend + pathname + '.' + getEncodingExtension(encoding)
+          pathnameForSend = pathnameForSend + pathname + encodingExtensionMap[encoding]
         } else {
-          pathnameForSend = pathname + '.' + getEncodingExtension(encoding)
+          pathnameForSend = pathname + encodingExtensionMap[encoding]
         }
       }
     }
@@ -360,9 +374,7 @@ async function fastifyStatic (fastify, opts) {
         // otherwise use send provided status code
         const newStatusCode = reply.statusCode !== 200 ? reply.statusCode : statusCode
         reply.code(newStatusCode)
-        if (setHeaders !== undefined) {
-          setHeaders(reply.raw, metadata.path, metadata.stat)
-        }
+        setHeaders?.(reply.raw, metadata.path, metadata.stat)
         reply.headers(headers)
         if (encoding) {
           reply.header('content-type', getContentType(pathname))
@@ -380,20 +392,23 @@ async function fastifyStatic (fastify, opts) {
       url: route,
       handler: serveFileHandler
     })
-    toSetUp.config = toSetUp.config || {}
+    toSetUp.config ??= {}
     toSetUp.config.file = file
     toSetUp.config.rootPath = rootPath
     fastify.route(toSetUp)
   }
 
+  /** @type {import("fastify").RouteHandlerMethod} */
   async function serveFileHandler (req, reply) {
-    // TODO: remove the fallback branch when bump major
-    /* c8 ignore next */
-    const routeConfig = req.routeOptions?.config || req.routeConfig
+    const routeConfig = req.routeOptions?.config
     return pumpSendToReply(req, reply, routeConfig.file, routeConfig.rootPath)
   }
 }
 
+/**
+ * @param {import("./types").FastifyStaticOptions['root']} root
+ * @returns {import("./types").FastifyStaticOptions['root']}
+ */
 function normalizeRoot (root) {
   if (root === undefined) {
     return root
@@ -417,6 +432,11 @@ function normalizeRoot (root) {
   return root
 }
 
+/**
+ * @param {import("fastify").FastifyInstance} fastify
+ * @param {import("./types").FastifyStaticOptions['root']} rootPath
+ * @returns {void}
+ */
 function checkRootPathForErrors (fastify, rootPath) {
   if (rootPath === undefined) {
     throw new Error('"root" option is required')
@@ -445,6 +465,11 @@ function checkRootPathForErrors (fastify, rootPath) {
   throw new Error('"root" option must be a string or array of strings')
 }
 
+/**
+ * @param {import("fastify").FastifyInstance} fastify
+ * @param {import("./types").FastifyStaticOptions['root']} rootPath
+ * @returns {void}
+ */
 function checkPath (fastify, rootPath) {
   if (typeof rootPath !== 'string') {
     throw new TypeError('"root" option must be a string')
@@ -471,6 +496,10 @@ function checkPath (fastify, rootPath) {
   }
 }
 
+/**
+ * @param {string} path
+ * @return {string}
+ */
 function getContentType (path) {
   const type = send.mime.getType(path) || send.mime.default_type
 
@@ -480,6 +509,12 @@ function getContentType (path) {
   return `${type}; charset=utf-8`
 }
 
+/**
+ * @param {string} pathname
+ * @param {*} root
+ * @param {import("./types").FastifyStaticOptions['index']} [indexFiles]
+ * @return {string|boolean}
+ */
 function findIndexFile (pathname, root, indexFiles = ['index.html']) {
   if (Array.isArray(indexFiles)) {
     return indexFiles.find(filename => {
@@ -496,7 +531,11 @@ function findIndexFile (pathname, root, indexFiles = ['index.html']) {
   return false
 }
 
-// Adapted from https://github.com/fastify/fastify-compress/blob/665e132fa63d3bf05ad37df3c20346660b71a857/index.js#L451
+/**
+ * Adapted from https://github.com/fastify/fastify-compress/blob/665e132fa63d3bf05ad37df3c20346660b71a857/index.js#L451
+ * @param {import('fastify').FastifyRequest['headers']} headers
+ * @param {Set<string>} checked
+ */
 function getEncodingHeader (headers, checked) {
   if (!('accept-encoding' in headers)) return
 
@@ -509,24 +548,18 @@ function getEncodingHeader (headers, checked) {
   )
 }
 
-function getEncodingExtension (encoding) {
-  switch (encoding) {
-    case 'br':
-      return 'br'
-
-    case 'gzip':
-      return 'gz'
-  }
-}
-
+/**
+ * @param {string} url
+ * @return {string}
+ */
 function getRedirectUrl (url) {
   let i = 0
   // we detect how many slash before a valid path
-  for (; i < url.length; ++i) {
+  for (const ul = url.length; i < ul; ++i) {
     if (url[i] !== '/' && url[i] !== '\\') break
   }
   // turns all leading / or \ into a single /
-  url = '/' + url.substr(i)
+  url = '/' + url.slice(i)
   try {
     const parsed = new URL(url, 'http://localhost.com/')
     const parsedPathname = parsed.pathname

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastify/static",
-  "version": "8.2.0",
+  "version": "8.3.0",
   "description": "Plugin for serving static files as fast as possible.",
   "main": "index.js",
   "type": "commonjs",
@@ -67,8 +67,7 @@
   },
   "devDependencies": {
     "@fastify/compress": "^8.0.0",
-    "@fastify/pre-commit": "^2.1.0",
-    "@types/node": "^22.0.0",
+    "@types/node": "^24.0.13",
     "borp": "^0.20.0",
     "c8": "^10.1.3",
     "concat-stream": "^2.0.0",
@@ -77,7 +76,7 @@
     "neostandard": "^0.12.0",
     "pino": "^9.1.0",
     "proxyquire": "^2.1.3",
-    "tsd": "^0.32.0"
+    "tsd": "^0.33.0"
   },
   "tsd": {
     "directory": "test/types"

package/test/static.test.js

@@ -753,6 +753,51 @@ test('serving disabled', async (t) => {
   })
 })
 
+test('serving disabled without root', async (t) => {
+  t.plan(2)
+
+  const pluginOptions = {
+    prefix: '/static/',
+    serve: false
+  }
+  const fastify = Fastify()
+  fastify.register(fastifyStatic, pluginOptions)
+
+  t.after(() => fastify.close())
+
+  fastify.get('/foo/bar/r', (_request, reply) => {
+    reply.sendFile('index.html')
+  })
+
+  fastify.get('/foo/bar/a', (_request, reply) => {
+    reply.sendFile(path.join(__dirname, pluginOptions.prefix, 'index.html'))
+  })
+
+  t.after(() => fastify.close())
+
+  await fastify.listen({ port: 0 })
+
+  fastify.server.unref()
+
+  await t.test('/static/index.html via sendFile not found', async (t) => {
+    t.plan(3 + GENERIC_RESPONSE_CHECK_COUNT)
+
+    const response = await fetch('http://localhost:' + fastify.server.address().port + '/foo/bar/a')
+    t.assert.ok(response.ok)
+    t.assert.deepStrictEqual(response.status, 200)
+    t.assert.deepStrictEqual(await response.text(), indexContent)
+    genericResponseChecks(t, response)
+  })
+
+  await t.test('/static/index.html via sendFile with relative path not found', async (t) => {
+    t.plan(2)
+
+    const response = await fetch('http://localhost:' + fastify.server.address().port + '/foo/bar/r')
+    t.assert.ok(!response.ok)
+    t.assert.deepStrictEqual(response.status, 404)
+  })
+})
+
 test('sendFile', async (t) => {
   t.plan(4)
 
@@ -1215,7 +1260,7 @@ test('maxAge option', async (t) => {
 })
 
 test('errors', async (t) => {
-  t.plan(11)
+  t.plan(12)
 
   await t.test('no root', async (t) => {
     t.plan(1)
@@ -1280,6 +1325,16 @@ test('errors', async (t) => {
     await t.assert.rejects(async () => await fastify.register(fastifyStatic, pluginOptions))
   })
 
+  await t.test('no root and serve: false', async (t) => {
+    t.plan(1)
+    const pluginOptions = {
+      serve: false,
+      root: []
+    }
+    const fastify = Fastify({ logger: false })
+    await t.assert.rejects(async () => await fastify.register(fastifyStatic, pluginOptions))
+  })
+
   await t.test('duplicate root paths are not allowed', async (t) => {
     t.plan(1)
     const pluginOptions = {
@@ -1936,8 +1991,6 @@ test('register /static with wildcard false and alternative index', async t => {
 
     const { promise, resolve } = Promise.withResolvers()
 
-    // simple-get doesn't tell us about redirects so use http.request directly
-    // to verify we do not get a redirect when not requested
     const testurl = 'http://localhost:' + fastify.server.address().port + '/static'
     const req = http.request(url.parse(testurl), res => {
       t.assert.deepStrictEqual(res.statusCode, 200)
@@ -2042,7 +2095,6 @@ test('register /static with redirect true', async t => {
 
     const { promise, resolve } = Promise.withResolvers()
 
-    // simple-get doesn't tell us about redirects so use http.request directly
     const testurl = 'http://localhost:' + fastify.server.address().port + '/static?a=b'
     const req = http.request(url.parse(testurl), res => {
       t.assert.deepStrictEqual(res.statusCode, 301)
@@ -2066,7 +2118,6 @@ test('register /static with redirect true', async t => {
 
     const { promise, resolve } = Promise.withResolvers()
 
-    // simple-get doesn't tell us about redirects so use http.request directly
     const testurl = 'http://localhost:' + fastify.server.address().port + '/static'
     const req = http.request(url.parse(testurl), res => {
       t.assert.deepStrictEqual(res.statusCode, 301)
@@ -2104,7 +2155,6 @@ test('register /static with redirect true', async t => {
 
     const { promise, resolve } = Promise.withResolvers()
 
-    // simple-get doesn't tell us about redirects so use http.request directly
     const testurl = 'http://localhost:' + fastify.server.address().port + '/static/deep/path/for/test?a=b'
     const req = http.request(url.parse(testurl), res => {
       t.assert.deepStrictEqual(res.statusCode, 301)
@@ -2161,7 +2211,6 @@ test('register /static with redirect true and wildcard false', async t => {
 
     const { promise, resolve } = Promise.withResolvers()
 
-    // simple-get doesn't tell us about redirects so use http.request directly
     const testurl = 'http://localhost:' + fastify.server.address().port + '/static?a=b'
     const req = http.request(url.parse(testurl), res => {
       t.assert.deepStrictEqual(res.statusCode, 301)
@@ -2213,7 +2262,6 @@ test('register /static with redirect true and wildcard false', async t => {
 
     const { promise, resolve } = Promise.withResolvers()
 
-    // simple-get doesn't tell us about redirects so use http.request directly
     const testurl = 'http://localhost:' + fastify.server.address().port + '/static/deep/path/for/test?a=b'
     const req = http.request(url.parse(testurl), res => {
       t.assert.deepStrictEqual(res.statusCode, 301)

package/types/index.d.ts

@@ -84,40 +84,52 @@ declare namespace fastifyStatic {
     serveDotFiles?: boolean;
   }
 
-  export interface FastifyStaticOptions extends SendOptions {
-    root: string | string[] | URL | URL[];
-    prefix?: string;
-    prefixAvoidTrailingSlash?: boolean;
-    serve?: boolean;
-    decorateReply?: boolean;
-    schemaHide?: boolean;
-    setHeaders?: (res: SetHeadersResponse, path: string, stat: Stats) => void;
-    redirect?: boolean;
-    wildcard?: boolean;
-    globIgnore?: string[];
-    list?: boolean | ListOptionsJsonFormat | ListOptionsHtmlFormat;
-    allowedPath?: (pathName: string, root: string, request: FastifyRequest) => boolean;
-    /**
-     * @description
-     * Opt-in to looking for pre-compressed files
-     */
-    preCompressed?: boolean;
-
-    // Passed on to `send`
-    acceptRanges?: boolean;
-    contentType?: boolean;
-    cacheControl?: boolean;
-    dotfiles?: 'allow' | 'deny' | 'ignore';
-    etag?: boolean;
-    extensions?: string[];
-    immutable?: boolean;
-    index?: string[] | string | false;
-    lastModified?: boolean;
-    maxAge?: string | number;
-    constraints?: RouteOptions['constraints'];
-    logLevel?: RouteOptions['logLevel'];
+  type Root = string | string[] | URL | URL[]
+
+  type RootOptions = {
+    serve: true;
+    root: Root;
+  } | {
+    serve?: false;
+    root?: Root;
   }
 
+  export type FastifyStaticOptions =
+    SendOptions
+    & RootOptions
+    & {
+      // Added by this plugin
+      prefix?: string;
+      prefixAvoidTrailingSlash?: boolean;
+      decorateReply?: boolean;
+      schemaHide?: boolean;
+      setHeaders?: (res: SetHeadersResponse, path: string, stat: Stats) => void;
+      redirect?: boolean;
+      wildcard?: boolean;
+      globIgnore?: string[];
+      list?: boolean | ListOptionsJsonFormat | ListOptionsHtmlFormat;
+      allowedPath?: (pathName: string, root: string, request: FastifyRequest) => boolean;
+      /**
+       * @description
+       * Opt-in to looking for pre-compressed files
+       */
+      preCompressed?: boolean;
+
+      // Passed on to `send`
+      acceptRanges?: boolean;
+      contentType?: boolean;
+      cacheControl?: boolean;
+      dotfiles?: 'allow' | 'deny' | 'ignore';
+      etag?: boolean;
+      extensions?: string[];
+      immutable?: boolean;
+      index?: string[] | string | false;
+      lastModified?: boolean;
+      maxAge?: string | number;
+      constraints?: RouteOptions['constraints'];
+      logLevel?: RouteOptions['logLevel'];
+    }
+
   export const fastifyStatic: FastifyStaticPlugin
 
   export { fastifyStatic as default }

package/types/index.test-d.ts

@@ -67,7 +67,7 @@ const options: FastifyStaticOptions = {
     return true
   },
   constraints: {
-    host: /.*\.example\.com/,
+    host: /^.*\.example\.com$/,
     version: '1.0.2'
   },
   logLevel: 'warn'
@@ -120,6 +120,19 @@ expectAssignable<FastifyStaticOptions>({
   root: [new URL('')]
 })
 
+expectError<FastifyStaticOptions>({
+  serve: true
+})
+
+expectAssignable<FastifyStaticOptions>({
+  serve: true,
+  root: ''
+})
+
+expectAssignable<FastifyStaticOptions>({
+  serve: false
+})
+
 appWithImplicitHttp
   .register(fastifyStatic, options)
   .after(() => {