Adding an option to surpress or modify the non-existent root directory warning (#524)

Author: xen143

README.md

@@ -7,108 +7,108 @@
 Plugin for serving static files as fast as possible.
 
 ## Install
+
 ```
 npm i @fastify/static
 ```
 
 ### Compatibility
 
 | Plugin version | Fastify version |
-| ---------------|-----------------|
+| -------------- | --------------- |
 | `>=8.x`        | `^5.x`          |
 | `^7.x`         | `^4.x`          |
 | `>=5.x <7.x`   | `^3.x`          |
 | `>=2.x <5.x`   | `^2.x`          |
 | `^1.x`         | `^1.x`          |
 
-
 Please note that if a Fastify version is out of support, then so are the corresponding versions of this plugin
 in the table above.
 See [Fastify's LTS policy](https://github.com/fastify/fastify/blob/main/docs/Reference/LTS.md) for more details.
 
 ## Usage
 
 ```js
-const fastify = require('fastify')({logger: true})
-const path = require('node:path')
+const fastify = require("fastify")({ logger: true });
+const path = require("node:path");
 
-fastify.register(require('@fastify/static'), {
-  root: path.join(__dirname, 'public'),
-  prefix: '/public/', // optional: default '/'
-  constraints: { host: 'example.com' } // optional: default {}
-})
+fastify.register(require("@fastify/static"), {
+  root: path.join(__dirname, "public"),
+  prefix: "/public/", // optional: default '/'
+  constraints: { host: "example.com" }, // optional: default {}
+});
 
-fastify.get('/another/path', function (req, reply) {
-  reply.sendFile('myHtml.html') // serving path.join(__dirname, 'public', 'myHtml.html') directly
-})
+fastify.get("/another/path", function (req, reply) {
+  reply.sendFile("myHtml.html"); // serving path.join(__dirname, 'public', 'myHtml.html') directly
+});
 
-fastify.get('/another/patch-async', async function (req, reply) {
-  return reply.sendFile('myHtml.html')
-})
+fastify.get("/another/patch-async", async function (req, reply) {
+  return reply.sendFile("myHtml.html");
+});
 
-fastify.get('/path/with/different/root', function (req, reply) {
-  reply.sendFile('myHtml.html', path.join(__dirname, 'build')) // serving a file from a different root location
-})
+fastify.get("/path/with/different/root", function (req, reply) {
+  reply.sendFile("myHtml.html", path.join(__dirname, "build")); // serving a file from a different root location
+});
 
-fastify.get('/another/path', function (req, reply) {
-  reply.sendFile('myHtml.html', { cacheControl: false }) // overriding the options disabling cache-control headers
-})
+fastify.get("/another/path", function (req, reply) {
+  reply.sendFile("myHtml.html", { cacheControl: false }); // overriding the options disabling cache-control headers
+});
 
 // Run the server!
 fastify.listen({ port: 3000 }, (err, address) => {
-  if (err) throw err
+  if (err) throw err;
   // Server is now listening on ${address}
-})
+});
 ```
 
 ### Multiple prefixed roots
 
 ```js
-const fastify = require('fastify')()
-const fastifyStatic = require('@fastify/static')
-const path = require('node:path')
+const fastify = require("fastify")();
+const fastifyStatic = require("@fastify/static");
+const path = require("node:path");
 // first plugin
 fastify.register(fastifyStatic, {
-  root: path.join(__dirname, 'public')
-})
+  root: path.join(__dirname, "public"),
+});
 
 // second plugin
 fastify.register(fastifyStatic, {
-  root: path.join(__dirname, 'node_modules'),
-  prefix: '/node_modules/',
-  decorateReply: false // the reply decorator has been added by the first plugin registration
-})
-
+  root: path.join(__dirname, "node_modules"),
+  prefix: "/node_modules/",
+  decorateReply: false, // the reply decorator has been added by the first plugin registration
+});
 ```
 
 ### Sending a file with `content-disposition` header
 
 ```js
-const fastify = require('fastify')()
-const path = require('node:path')
+const fastify = require("fastify")();
+const path = require("node:path");
 
-fastify.register(require('@fastify/static'), {
-  root: path.join(__dirname, 'public'),
-  prefix: '/public/', // optional: default '/'
-})
+fastify.register(require("@fastify/static"), {
+  root: path.join(__dirname, "public"),
+  prefix: "/public/", // optional: default '/'
+});
 
-fastify.get('/another/path', function (req, reply) {
-  reply.download('myHtml.html', 'custom-filename.html') // sending path.join(__dirname, 'public', 'myHtml.html') directly with custom filename
-})
+fastify.get("/another/path", function (req, reply) {
+  reply.download("myHtml.html", "custom-filename.html"); // sending path.join(__dirname, 'public', 'myHtml.html') directly with custom filename
+});
 
-fastify.get('another/patch-async', async function (req, reply) {
+fastify.get("another/patch-async", async function (req, reply) {
   // an async handler must always return the reply object
-  return reply.download('myHtml.html', 'custom-filename.html')
-})
-
-fastify.get('/path/without/cache/control', function (req, reply) {
-  reply.download('myHtml.html', { cacheControl: false }) // serving a file disabling cache-control headers
-})
-
-fastify.get('/path/without/cache/control', function (req, reply) {
-  reply.download('myHtml.html', 'custom-filename.html', { cacheControl: false })
-})
-
+  return reply.download("myHtml.html", "custom-filename.html");
+});
+
+fastify.get("/path/without/cache/control", function (req, reply) {
+  reply.download("myHtml.html", { cacheControl: false }); // serving a file disabling cache-control headers
+});
+
+fastify.get("/path/without/cache/control", function (req, reply) {
+  reply.download("myHtml.html", "custom-filename.html", {
+    cacheControl: false,
+  });
+});
 ```
 
 ### Managing cache-control headers
@@ -117,23 +117,23 @@ Production sites should use a reverse-proxy to manage caching headers.
 However, here is an example of using fastify-static to host a Single Page Application (for example a [vite.js](https://vite.dev/) build) with sane caching.
 
 ```js
-fastify.register(require('@fastify/static'), {
-  root: path.join(import.meta.dirname, 'dist'), // import.meta.dirname node.js >= v20.11.0
+fastify.register(require("@fastify/static"), {
+  root: path.join(import.meta.dirname, "dist"), // import.meta.dirname node.js >= v20.11.0
   // By default all assets are immutable and can be cached for a long period due to cache bursting techniques
-  maxAge: '30d',
+  maxAge: "30d",
   immutable: true,
-})
+});
 
 // Explicitly reduce caching of assets that don't use cache bursting techniques
-fastify.get('/', function (req, reply) {
+fastify.get("/", function (req, reply) {
   // index.html should never be cached
-  reply.sendFile('index.html', {maxAge: 0, immutable: false})
-})
+  reply.sendFile("index.html", { maxAge: 0, immutable: false });
+});
 
-fastify.get('/favicon.ico', function (req, reply) {
+fastify.get("/favicon.ico", function (req, reply) {
   // favicon can be cached for a short period
-  reply.sendFile('favicon.ico', {maxAge: '1d', immutable: false})
-})
+  reply.sendFile("favicon.ico", { maxAge: "1d", immutable: false });
+});
 ```
 
 ### Options
@@ -148,6 +148,12 @@ An array of directories can be provided to serve multiple static directories
 under a single prefix. Files are served in a "first found, first served" manner,
 so list directories in order of priority. Duplicate paths will raise an error.
 
+#### `getPathNotFoundWarning`
+
+A custom function that returns a warning message to log when a specified root directory is not found.
+It receives a single argument: the path of the missing root directory.
+The function should return a string describing the missing path.
+
 #### `prefix`
 
 Default: `'/'`
@@ -275,12 +281,12 @@ If `dotfiles` is `deny` or `ignore`, dotfiles are excluded.
 Example:
 
 ```js
-fastify.register(require('@fastify/static'), {
-  root: path.join(__dirname, 'public'),
-  prefix: '/public/',
+fastify.register(require("@fastify/static"), {
+  root: path.join(__dirname, "public"),
+  prefix: "/public/",
   index: false,
-  list: true
-})
+  list: true,
+});
 ```
 
 Request
@@ -314,25 +320,32 @@ Returns the response as JSON, regardless of `list.format`.
 Example:
 
 ```js
-fastify.register(require('@fastify/static'), {
-  root: path.join(__dirname, 'public'),
-  prefix: '/public/',
+fastify.register(require("@fastify/static"), {
+  root: path.join(__dirname, "public"),
+  prefix: "/public/",
   list: {
-    format: 'html',
+    format: "html",
     render: (dirs, files) => {
       return `
 <html><body>
 <ul>
-  ${dirs.map(dir => `<li><a href="${dir.href}">${dir.name}</a></li>`).join('\n  ')}
+  ${dirs
+    .map((dir) => `<li><a href="${dir.href}">${dir.name}</a></li>`)
+    .join("\n  ")}
 </ul>
 <ul>
-  ${files.map(file => `<li><a href="${file.href}" target="_blank">${file.name}</a></li>`).join('\n  ')}
+  ${files
+    .map(
+      (file) =>
+        `<li><a href="${file.href}" target="_blank">${file.name}</a></li>`
+    )
+    .join("\n  ")}
 </ul>
 </body></html>
-`
-      },
-  }
-})
+`;
+    },
+  },
+});
 ```
 
 Request
@@ -344,18 +357,20 @@ GET /public
 Response
 
 ```html
-<html><body>
-<ul>
-  <li><a href="/dir1">dir1</a></li>
-  <li><a href="/dir1">dir2</a></li>
-</ul>
-<ul>
-  <li><a href="/foo.html" target="_blank">foo.html</a></li>
-  <li><a href="/foobar.html" target="_blank">foobar.html</a></li>
-  <li><a href="/index.css" target="_blank">index.css</a></li>
-  <li><a href="/index.html" target="_blank">index.html</a></li>
-</ul>
-</body></html>
+<html>
+  <body>
+    <ul>
+      <li><a href="/dir1">dir1</a></li>
+      <li><a href="/dir1">dir2</a></li>
+    </ul>
+    <ul>
+      <li><a href="/foo.html" target="_blank">foo.html</a></li>
+      <li><a href="/foobar.html" target="_blank">foobar.html</a></li>
+      <li><a href="/index.css" target="_blank">index.css</a></li>
+      <li><a href="/index.html" target="_blank">index.html</a></li>
+    </ul>
+  </body>
+</html>
 ```
 
 #### `list.names`
@@ -369,15 +384,15 @@ Directory list can respond to different routes declared in `list.names`.
 Example:
 
 ```js
-fastify.register(require('@fastify/static'), {
-  root: path.join(__dirname, '/static'),
-  prefix: '/public',
+fastify.register(require("@fastify/static"), {
+  root: path.join(__dirname, "/static"),
+  prefix: "/public",
   prefixAvoidTrailingSlash: true,
   list: {
-    format: 'json',
-    names: ['index', 'index.json', '/']
-  }
-})
+    format: "json",
+    names: ["index", "index.json", "/"],
+  },
+});
 ```
 
 Dir list respond with the same content to:
@@ -418,20 +433,16 @@ Options: `names`, `extended`
 Determines the output format when `json` is selected.
 
 `names`:
+
 ```json
 {
-  "dirs": [
-    "dir1",
-    "dir2"
-  ],
-  "files": [
-    "file1.txt",
-    "file2.txt"
-  ]
+  "dirs": ["dir1", "dir2"],
+  "files": ["file1.txt", "file2.txt"]
 }
 ```
 
 `extended`:
+
 ```json
 {
   "dirs": [
@@ -496,18 +507,21 @@ handler is called. Set a custom 404 handler with [`fastify.setNotFoundHandler()`
 When registering `@fastify/static` within an encapsulated context, the `wildcard` option may need to be set to `false` to support index resolution and nested not-found-handler:
 
 ```js
-const app = require('fastify')();
+const app = require("fastify")();
 
-app.register((childContext, _, done) => {
-    childContext.register(require('@fastify/static'), {
-        root: path.join(__dirname, 'docs'), // docs is a folder that contains `index.html` and `404.html`
-        wildcard: false
+app.register(
+  (childContext, _, done) => {
+    childContext.register(require("@fastify/static"), {
+      root: path.join(__dirname, "docs"), // docs is a folder that contains `index.html` and `404.html`
+      wildcard: false,
     });
     childContext.setNotFoundHandler((_, reply) => {
-        return reply.code(404).type('text/html').sendFile('404.html');
+      return reply.code(404).type("text/html").sendFile("404.html");
     });
     done();
-}, { prefix: 'docs' });
+  },
+  { prefix: "docs" }
+);
 ```
 
 This code will send the `index.html` for the paths `docs`, `docs/`, and `docs/index.html`. For all other `docs/<undefined-routes>` it will reply with `404.html`.
@@ -522,10 +536,10 @@ Set a custom handler with [`fastify.setErrorHandler()`](https://fastify.dev/docs
 Access the file path inside the `onSend` hook using `payload.path`.
 
 ```js
-fastify.addHook('onSend', function (req, reply, payload, next) {
-  console.log(payload.path)
-  next()
-})
+fastify.addHook("onSend", function (req, reply, payload, next) {
+  console.log(payload.path);
+  next();
+});
 ```
 
 ## License