fastify · gurgunday · Feb 1, 2024 · Feb 1, 2024 · Feb 1, 2024 · Feb 1, 2024
diff --git a/README.md b/README.md
@@ -194,6 +194,66 @@ for getting the file list.
 This option cannot be set to `false` with `redirect` set to `true` on a server
 with `ignoreTrailingSlash` set to `true`.
 
+#### `hash`
+
+Default: `undefined`
+
+Enabling `hash` will turn off the `wildcard` option if it wasn't explicitly set to `true`, and both cannot be set to `true`. When enabled, `hash` lets the user access assets dynamically using the decorated `getHashedStaticPath` function. This in turn makes possible the usage of a very high `maxAge` so that the content can be cached as long as possible. If any modifications are made to a file, its hash will simply be recalculated during the next startup and the cache will bust for that asset.
+
+##### Example:
+
+```js
+const fastify = require('fastify')()
+fastify.register(require('fastify-static'), {
+  root: path.join(__dirname, 'public'),
+  hash: true,
+  immutable: true,
+  maxAge: 31536000 // You can set a very long maxAge
+})
+
+fastify.listen(3000, (err) => {
+  if (err) throw err
+  console.log('Server listening at http://localhost:3000')
+})
+```
+
+Then in your templates:
+
+```handlebars
+<script src="{{ fastify.getHashedStaticPath('js/main.js') }}"></script>
+<link href="{{ fastify.getHashedStaticPath('css/main.css') }}" rel="stylesheet">
+```
+
+**Note:** Hashes can be generated in advance to speed up cold start times, ideally during the build phase:
+
+```sh
+npx fastify-static-prehash <root-paths> <write-location> <include-dot-files> <ignore-patterns>
+```
+
+##### Example:
+
+```sh
+npx fastify-static-prehash example/public/,example/public2/ example/hashes.json true '**/*.json'
+```
+
+And then, during plugin initialization:
+
+```js
+const fastify = require('fastify')()
+fastify.register(require('fastify-static'), {
+  root: path.join(__dirname, 'public'),
+  hash: { path: path.join(__dirname, 'example/hashes.json') },
+  serveDotFiles: true,
+  immutable: true,
+  maxAge: 31536000
+})
+
+fastify.listen(3000, (err) => {
+  if (err) throw err
+  console.log('Server listening at http://localhost:3000')
+})
+```
+
 #### `allowedPath`
 
 Default: `(pathName, root, request) => true`

diff --git a/bin/fastify-static-prehash.js b/bin/fastify-static-prehash.js
@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+'use strict'
+
+const { generateHashes } = require('../lib/hash')
+const path = require('path')
+
+async function run () {
+  let [rootPaths, writeLocation, includeDotFiles, ignorePatterns] = process.argv.slice(2)
+
+  if (rootPaths === undefined || writeLocation === undefined) {
+    console.error('Usage: hash <root-paths> <write-location> <include-dot-files> <ignore-patterns>')
+    process.exit(1)
+  }
+
+  rootPaths = rootPaths.split(',').map(p => path.resolve(p.trim()))
+  includeDotFiles = includeDotFiles === 'true'
+  ignorePatterns = ignorePatterns ? ignorePatterns.split(',') : []
+
+  try {
+    await generateHashes({
+      rootPaths,
+      includeDotFiles,
+      skipPatterns: ignorePatterns,
+      writeToFile: true,
+      outputPath: writeLocation
+    }
+    )
+    console.log('Hashes generated successfully.')
+  } catch (error) {
+    console.error('Error generating hashes:', error)
+  }
+}
+
+run()
diff --git a/example/hashes.json b/example/hashes.json
@@ -0,0 +1,8 @@
+{
+  "index.js": "1f49271e60e53b00",
+  "index.html": "8e27d2f424d541b4",
+  "index.css": "712708f47c759d37",
+  "images/sample.jpg": "4c67e0488b3afa81",
+  "test.html": "6944c8b16078a588",
+  "test.css": "b305efc33fe211f7"
+}
diff --git a/example/server-hash-pregenerated.mjs b/example/server-hash-pregenerated.mjs
@@ -0,0 +1,33 @@
+import fastify from 'fastify'
+import fastifyStatic from '../index.js'
+
+const server = fastify()
+
+await server.register(fastifyStatic, {
+  root: new URL('./public', import.meta.url).pathname,
+  prefix: '/assets/',
+  hash: { path: new URL('hashes.json', import.meta.url).pathname },
+  immutable: true,
+  maxAge: 31536000 * 1000 // 1 year
+})
+
+server.register(import('fastify-html'))
+
+// Define a route for the root URL
+server.get('/', async (request, reply) => {
+  return reply.html`
+  <html>
+    <head>
+      <link rel="stylesheet" href="${server.getHashedStaticPath('index.css')}">
+    </head>
+    <body>
+      <h1>Hello, world!</h1>
+      <img src="${server.getHashedStaticPath('images/sample.jpg')}" alt="An image">
+    </body>
+  </html>
+  `
+})
+
+// Start the server
+await server.listen({ port: 3000 })
+console.log('Server is running on port 3000')
diff --git a/example/server-hash.mjs b/example/server-hash.mjs
@@ -0,0 +1,33 @@
+import fastify from 'fastify'
+import fastifyStatic from '../index.js'
+
+const server = fastify()
+
+await server.register(fastifyStatic, {
+  root: new URL('./public', import.meta.url).pathname,
+  prefix: '/assets/',
+  hash: true,
+  immutable: true,
+  maxAge: 31536000 * 1000 // 1 year
+})
+
+server.register(import('fastify-html'))
+
+// Define a route for the root URL
+server.get('/', async (request, reply) => {
+  return reply.html`
+  <html>
+    <head>
+      <link rel="stylesheet" href="${server.getHashedStaticPath('index.css')}">
+    </head>
+    <body>
+      <h1>Hello, world!</h1>
+      <img src="${server.getHashedStaticPath('images/sample.jpg')}" alt="An image">
+    </body>
+  </html>
+  `
+})
+
+// Start the server
+await server.listen({ port: 3000 })
+console.log('Server is running on port 3000')
diff --git a/index.js b/index.js
@@ -1,20 +1,23 @@
 'use strict'
 
+const { readFile } = require('node:fs/promises')
 const { PassThrough } = require('node:stream')
 const path = require('node:path')
 const { fileURLToPath } = require('node:url')
 const { statSync } = require('node:fs')
-const { glob } = require('glob')
+const { Glob } = require('glob')
 const fp = require('fastify-plugin')
 const send = require('@fastify/send')
 const encodingNegotiator = require('@fastify/accept-negotiator')
 const contentDisposition = require('content-disposition')
 
 const dirList = require('./lib/dirList')
+const { generateHashes } = require('./lib/hash')
 
-const endForwardSlashRegex = /\/$/u
-const doubleForwardSlashRegex = /\/\//gu
 const asteriskRegex = /\*/gu
+const endForwardSlashRegex = /\/$/u
+
+const kFileHashes = Symbol('fileHashes')
 
 const supportedEncodings = ['br', 'gzip', 'deflate']
 send.mime.default_type = 'application/octet-stream'
@@ -59,6 +62,27 @@ async function fastifyStatic (fastify, opts) {
         : prefix + '/'
   }
 
+  if (opts.hash) {
+    if (opts.wildcard) {
+      throw new Error('"wildcard" has to be disabled to use "hash"')
+    }
+
+    opts.wildcard = false
+
+    fastify.decorate('getHashedStaticPath', getHashedStaticPath)
+    if (opts.hash.path) {
+      const hashesContent = await readFile(opts.hash.path, 'utf8')
+      fastify.decorate(kFileHashes, new Map(Object.entries(JSON.parse(hashesContent))))
+    } else {
+      fastify.decorate(kFileHashes, await generateHashes({
+        rootPaths: opts.root,
+        includeDotFiles: opts.serveDotFiles,
+        skipPatterns: opts.hash.skipPatterns
+      }
+      ))
+    }
+  }
+
   // Set the schema hide property if defined in opts or true by default
   const routeOpts = {
     constraints: opts.constraints,
@@ -112,11 +136,14 @@ async function fastifyStatic (fastify, opts) {
       throw new Error('"wildcard" option must be a boolean')
     }
     if (opts.wildcard === undefined || opts.wildcard === true) {
-      fastify.head(prefix + '*', routeOpts, function (req, reply) {
-        pumpSendToReply(req, reply, '/' + req.params['*'], sendOptions.root)
-      })
-      fastify.get(prefix + '*', routeOpts, function (req, reply) {
-        pumpSendToReply(req, reply, '/' + req.params['*'], sendOptions.root)
+      fastify.route({
+        ...routeOpts,
+        exposeHeadRoute: true,
+        method: 'GET',
+        url: `${prefix}*`,
+        handler (req, reply) {
+          pumpSendToReply(req, reply, `/${req.params['*']}`, sendOptions.root)
+        }
       })
       if (opts.redirect === true && prefix !== opts.prefix) {
         fastify.get(opts.prefix, routeOpts, function (req, reply) {
@@ -127,18 +154,21 @@ async function fastifyStatic (fastify, opts) {
       const indexes = opts.index === undefined ? ['index.html'] : [].concat(opts.index)
       const indexDirs = new Map()
       const routes = new Set()
-      const globPattern = '**/**'
 
       const roots = Array.isArray(sendOptions.root) ? sendOptions.root : [sendOptions.root]
-      for (let i = 0; i < roots.length; ++i) {
-        const rootPath = roots[i]
-        const posixRootPath = rootPath.split(path.win32.sep).join(path.posix.sep)
-        const files = await glob(`${posixRootPath}/${globPattern}`, { follow: true, nodir: true, dot: opts.serveDotFiles })
+      for (let rootPath of roots) {
+        rootPath = rootPath.split(path.win32.sep).join(path.posix.sep)
+        if (!rootPath.endsWith('/')) {
+          rootPath += '/'
+        }
+
+        const filesIterable = new Glob('**/**', {
+          cwd: rootPath, absolute: false, follow: true, nodir: true, dot: opts.serveDotFiles
+        })
 
-        for (let i = 0; i < files.length; ++i) {
-          const file = files[i].split(path.win32.sep).join(path.posix.sep)
-            .replace(`${posixRootPath}/`, '')
-          const route = (prefix + file).replace(doubleForwardSlashRegex, '/')
+        for (let file of filesIterable) {
+          file = file.split(path.win32.sep).join(path.posix.sep)
+          const route = prefix + file
 
           if (routes.has(route)) {
             continue
@@ -168,14 +198,13 @@ async function fastifyStatic (fastify, opts) {
   }
 
   const allowedPath = opts.allowedPath
-
   function pumpSendToReply (
     request,
     reply,
     pathname,
     rootPath,
     rootPathOffset = 0,
-    pumpOptions = {},
+    pumpOptions,
     checkedEncodings
   ) {
     const options = Object.assign({}, sendOptions, pumpOptions)
@@ -237,7 +266,7 @@ async function fastifyStatic (fastify, opts) {
 
     wrap.getHeader = reply.getHeader.bind(reply)
     wrap.setHeader = reply.header.bind(reply)
-    wrap.removeHeader = () => {}
+    wrap.removeHeader = noop
     wrap.finished = false
 
     Object.defineProperty(wrap, 'filename', {
@@ -381,10 +410,12 @@ async function fastifyStatic (fastify, opts) {
 
   function setUpHeadAndGet (routeOpts, route, file, rootPath) {
     const toSetUp = Object.assign({}, routeOpts, {
-      method: ['HEAD', 'GET'],
+      exposeHeadRoute: true,
+      method: 'GET',
       url: route,
       handler: serveFileHandler
     })
+
     toSetUp.config = toSetUp.config || {}
     toSetUp.config.file = file
     toSetUp.config.rootPath = rootPath
@@ -397,6 +428,11 @@ async function fastifyStatic (fastify, opts) {
     const routeConfig = req.routeOptions?.config || req.routeConfig
     pumpSendToReply(req, reply, routeConfig.file, routeConfig.rootPath)
   }
+
+  function getHashedStaticPath (unhashedRelativePath) {
+    const hash = fastify[kFileHashes].get(unhashedRelativePath)
+    return `${prefix}${unhashedRelativePath}${hash ? `?hash=${hash}` : ''}`
+  }
 }
 
 function normalizeRoot (root) {
@@ -549,6 +585,8 @@ function getRedirectUrl (url) {
   }
 }
 
+function noop () {}
+
 module.exports = fp(fastifyStatic, {
   fastify: '4.x',
   name: '@fastify/static'