refactor: extract deepFreezeObject into utils, cache frozenConfig, improve prod error messages

- Move recursive deep-freeze logic into libs/utils.js as
  deepFreezeObject() — deep-clones, recursively freezes all
  nesting levels, safe for non-plain values (pass-through)
- Cache frozen config in getConfigOptions() after first call
  to avoid re-cloning and re-freezing on every invocation
- Use http.STATUS_CODES in parseErr() production mode so
  error messages match the status code (e.g. 404 → 'Not Found',
  502 → 'Bad Gateway') instead of always 'Internal Server Error'
- Fix documented default errorHandler to match actual
  statusCode computation instead of undefined 'code' variable

Author: jkyberneees

docs/README.md

@@ -80,7 +80,7 @@ Optionally, learn through examples:
 - `server`: Allows to optionally override the HTTP server instance to be used.
 - `prioRequestsProcessing`: If `TRUE`, HTTP requests processing/handling is prioritized using `setImmediate`. Default value: `TRUE`
 - `defaultRoute`: Optional route handler when no route match occurs. Default value: `((req, res) => res.send(404))`
-- `errorHandler`: Optional global error handler function. Default value: `(err, req, res) => res.send({ code, message: 'Internal Server Error' }, code)`. The default handler returns a generic error message to prevent leaking sensitive internal details (e.g. database connection strings, file paths, stack traces). The appropriate HTTP status code is still preserved from `err.status`, `err.code`, or `err.statusCode`.
+- `errorHandler`: Optional global error handler function. Default value: `(err, req, res) => { const statusCode = typeof (err.status || err.code || err.statusCode) === 'number' ? (err.status || err.code || err.statusCode) : 500; res.send({ code: statusCode, message: 'Internal Server Error' }, statusCode) }`. The default handler returns a generic error message to prevent leaking sensitive internal details (e.g. database connection strings, file paths, stack traces). The appropriate HTTP status code is still preserved from `err.status`, `err.code`, or `err.statusCode`.
 - `routerCacheSize`: The router matching cache size, indicates how many request matches will be kept in memory. Default value: `2000`
 - `enableTrace`: When `TRUE`, the `TRACE` HTTP method handler is available for debugging purposes. Default value: `FALSE`. ⚠️ Not recommended for production deployments.
 - `securityHeaders`: When `TRUE`, default security headers are set on every response. Set to `FALSE` to disable (e.g. when using Helmet or serving non-browser clients). Default value: `TRUE`.

index.js

@@ -8,26 +8,12 @@
 
 const requestRouter = require('./libs/request-router')
 const applySecurityHeaders = require('./libs/security-headers')
-const { deepObjectClone } = require('./libs/utils')
+const { deepFreezeObject } = require('./libs/utils')
 const exts = {
   request: {},
   response: require('./libs/response-extensions')
 }
 
-/**
- * Recursively freezes a plain object and all nested plain objects.
- * Skips arrays, Buffers, class instances, and other non-plain types.
- */
-function deepFreezePlain (obj) {
-  if (obj && typeof obj === 'object' && obj.constructor === Object && !Object.isFrozen(obj)) {
-    Object.freeze(obj)
-    for (const key of Object.keys(obj)) {
-      deepFreezePlain(obj[key])
-    }
-  }
-  return obj
-}
-
 module.exports = (options = {}) => {
   options.errorHandler =
     options.errorHandler ||
@@ -63,6 +49,7 @@ module.exports = (options = {}) => {
   }
 
   const service = handle
+  let frozenConfig = null
 
   const service_ = {
     errorHandler: options.errorHandler,
@@ -76,17 +63,18 @@ module.exports = (options = {}) => {
     },
 
     getConfigOptions () {
-      const copy = { ...options }
-      // Deep-clone + deep-freeze nested plain objects so the user's originals
-      // are not mutated as a side effect of calling getConfigOptions().
-      for (const key of Object.keys(copy)) {
-        const val = copy[key]
-        if (val && typeof val === 'object' && !Array.isArray(val) &&
-            key !== 'server' && val.constructor === Object) {
-          copy[key] = deepFreezePlain(deepObjectClone(val))
+      if (!frozenConfig) {
+        const copy = { ...options }
+        // Deep-clone + deep-freeze nested plain objects so the user's originals
+        // are not mutated as a side effect of calling getConfigOptions().
+        for (const key of Object.keys(copy)) {
+          if (key !== 'server') {
+            copy[key] = deepFreezeObject(copy[key])
+          }
         }
+        frozenConfig = Object.freeze(copy)
       }
-      return Object.freeze(copy)
+      return frozenConfig
     },
 
     handle,

libs/response-extensions.js

@@ -26,6 +26,8 @@ const stringify = obj => {
   return JSON.stringify(obj)
 }
 
+const STATUS_TEXTS = require('http').STATUS_CODES
+
 const beforeEnd = (res, contentType, statusCode, data) => {
   if (contentType) {
     res.setHeader(CONTENT_TYPE_HEADER, contentType)
@@ -44,7 +46,7 @@ const parseErr = error => {
       statusCode,
       data: stringify({
         code: statusCode,
-        message: 'Internal Server Error'
+        message: STATUS_TEXTS[statusCode] || 'Internal Server Error'
       })
     }
   }

libs/utils.js

@@ -1,3 +1,5 @@
+'use strict'
+
 module.exports.forEachObject = (obj, cb) => {
   const keys = Object.keys(obj)
   const length = keys.length
@@ -8,13 +10,32 @@ module.exports.forEachObject = (obj, cb) => {
 }
 
 /**
- * Creates a deep clone of a serializable plain object.
- * Uses JSON.parse/stringify for a clean, immutable copy.
- * Skips non-serializable values (functions, symbols, undefined).
+ * Deep-clones a serializable plain object, then recursively freezes
+ * the clone and all nested plain objects. Skips arrays, Buffers,
+ * class instances, and other non-plain types.
+ *
+ * The original object is never mutated — safe to call on user-provided config.
  *
  * @param {Object} obj
- * @returns {Object}
+ * @returns {Object} Deep-cloned, deeply frozen copy
  */
-module.exports.deepObjectClone = (obj) => {
-  return JSON.parse(JSON.stringify(obj))
+module.exports.deepFreezeObject = (obj) => {
+  // Pass through non-plain values (functions, arrays, primitives, etc.)
+  if (!obj || typeof obj !== 'object' || obj.constructor !== Object) {
+    return obj
+  }
+
+  const clone = JSON.parse(JSON.stringify(obj))
+
+  function freeze (val) {
+    if (val && typeof val === 'object' && val.constructor === Object && !Object.isFrozen(val)) {
+      Object.freeze(val)
+      for (const key of Object.keys(val)) {
+        freeze(val[key])
+      }
+    }
+    return val
+  }
+
+  return freeze(clone)
 }

specs/security-review-2026.test.js

@@ -250,8 +250,8 @@ describe('Security Review — April 2026', () => {
         .get('/leak')
         .expect(502)
 
-      // In production, the actual error message must be masked
-      expect(res.body.message).to.equal('Internal Server Error')
+      // In production, the actual error message must be masked with a generic status text
+      expect(res.body.message).to.equal('Bad Gateway')
       expect(res.body.message).to.not.include('ECONNREFUSED')
       expect(res.body.message).to.not.include('database.internal')
     })