refactor: refinement ⚗️

Author: bricss

API.md

@@ -98,35 +98,27 @@ assigned one or more (array):
 
 #### <a name="server.options.compression" /> `server.options.compression`
 
-Default value: `{ minBytes: 1024 }`.
+Default value: `{ encodings: { gzip: true, deflate: true, br: false, zstd: false }, minBytes: 1024 }`.
 
 Defines server handling of content encoding requests. If `false`, response content encoding is
-disabled and no compression is performed by the server.
+disabled, and no compression is performed by the server.
 
-##### <a name="server.options.compression.enableBrotli" /> `server.options.compression.enableBrotli`
+#### <a name="server.options.compression.encodings" /> `server.options.compression.encodings`
 
-Default value: `false`.
-
-Enables built-in support of `brotli` compression algorithm.
+Default value: `{ gzip: true, deflate: true, br: false, zstd: false }`.
 
-Available values:
+Configures the built-in support of compression algorithms aka encodings, represented by the object of kv pairs.
 
-- `false` - no compression.
-- `true` - compression with system defaults.
-- [`BrotliOptions`](https://nodejs.org/api/zlib.html#class-brotlioptions) - compression with specified options.
+Available values for each kv pair:
 
-##### <a name="server.options.compression.enableZstd" /> `server.options.compression.enableZstd`
+- `true` - enables the encoding with default options.
+- `false` - disables the encoding.
+- `{...options}` - enables the encoding using custom options specific to each particular algorithm.
 
-Default value: `false`.
-
-Enables built-in support of `zstd` compression algorithm (node: `>=22.15.0`).  
 Zstd compression is experimental (see [node Zstd documentation](https://nodejs.org/api/zlib.html#zlibcreatezstdcompressoptions)).
 
-Available values:
-
-- `false` - no compression.
-- `true` - compression with system defaults.
-- [`ZstdOptions`](https://nodejs.org/api/zlib.html#class-zstdoptions) - compression with specified options.
+Disabling an encoding allows custom compression algorithm to be applied by
+[`server.encoder()`](#server.encoder()) and [`server.decoder()`](#server.decoder()).
 
 ##### <a name="server.options.compression.minBytes" /> `server.options.compression.minBytes`
 

lib/compression.js

@@ -16,30 +16,64 @@ const internals = {
         'deflate, gzip',
         'gzip',
         'deflate'
-    ]
+    ],
+    provision: new Map([
+        ['zstd', [
+            (options) => Zlib.createZstdCompress(options),
+            (options) => Zlib.createZstdDecompress(options),
+            {
+                params: {
+                    [Zlib.constants.ZSTD_c_compressionLevel]: 6
+                }
+            }
+        ]],
+        ['br', [
+            (options) => Zlib.createBrotliCompress(options),
+            (options) => Zlib.createBrotliDecompress(options),
+            {
+                params: {
+                    [Zlib.constants.BROTLI_PARAM_QUALITY]: 4
+                }
+            }
+        ]],
+        ['deflate', [
+            (options) => Zlib.createDeflate(options),
+            (options) => Zlib.createInflate(options)
+        ]],
+        ['gzip', [
+            (options) => Zlib.createGzip(options),
+            (options) => Zlib.createGunzip(options)
+        ]]
+    ])
 };
 
 
 exports = module.exports = internals.Compression = class {
 
-    decoders = {
-        gzip: (options) => Zlib.createGunzip(options),
-        deflate: (options) => Zlib.createInflate(options)
-    };
+    decoders = {};
 
-    encodings = ['identity', 'gzip', 'deflate'];
+    encodings = ['identity'];
 
     encoders = {
-        identity: null,
-        gzip: (options) => Zlib.createGzip(options),
-        deflate: (options) => Zlib.createDeflate(options)
+        identity: null
     };
 
     #common = null;
 
-    constructor() {
+    constructor({ compression }) {
 
-        this._updateCommons();
+        if (!compression) {
+            this._updateCommons();
+        }
+
+        for (const [alg, [encoder, decoder, defaults = {}]] of internals.provision.entries()) {
+            let conditions = compression?.encodings?.[alg];
+            if (conditions) {
+                conditions = Hoek.applyToDefaults(defaults, conditions);
+                this.addEncoder(alg, (options = {}) => encoder(Hoek.applyToDefaults(conditions, options)));
+                this.addDecoder(alg, (options = {}) => decoder(Hoek.applyToDefaults(conditions, options)));
+            }
+        }
     }
 
     _updateCommons() {
@@ -125,29 +159,6 @@ exports = module.exports = internals.Compression = class {
         return encoder(request.route.settings.compression[encoding]);
     }
 
-    enableBrotliCompression(compressionOptions) {
-
-        const defaults = {
-            params: {
-                [Zlib.constants.BROTLI_PARAM_QUALITY]: 4
-            }
-        };
-        compressionOptions = Hoek.applyToDefaults(defaults, compressionOptions);
-        this.decoders.br = (options) => Zlib.createBrotliDecompress({ ...options, ...compressionOptions });
-        this.encoders.br = (options) => Zlib.createBrotliCompress({ ...options, ...compressionOptions });
-        this.setPriority(['br']);
-    }
-
-    enableZstdCompression(compressionOptions) {
-
-        /* $lab:coverage:off$ */
-        Hoek.assert(!!Zlib.constants.ZSTD_CLEVEL_DEFAULT, 'Zstd is not supported by the engine');
-        this.decoders.zstd = (options) => Zlib.createZstdDecompress({ ...options, ...compressionOptions });
-        this.encoders.zstd = (options) => Zlib.createZstdCompress({ ...options, ...compressionOptions });
-        this.setPriority(['zstd']);
-        /* $lab:coverage:on$ */
-    }
-
     setPriority(priority) {
 
         this.encodings = [...new Set([...priority, ...this.encodings])];

lib/config.js

@@ -241,14 +241,24 @@ internals.server = Validate.object({
     autoListen: Validate.boolean(),
     cache: Validate.allow(null),                                 // Validated elsewhere
     compression: Validate.object({
-        enableBrotli: Validate.alternatives([
-            Validate.boolean(),
-            Validate.object()
-        ]).default(false),
-        enableZstd: Validate.alternatives([
-            Validate.boolean(),
-            Validate.object()
-        ]).default(false),
+        encodings: Validate.object({
+            gzip: Validate.alternatives([
+                Validate.boolean(),
+                Validate.object()
+            ]).default(true),
+            deflate: Validate.alternatives([
+                Validate.boolean(),
+                Validate.object()
+            ]).default(true),
+            br: Validate.alternatives([
+                Validate.boolean(),
+                Validate.object()
+            ]).default(false),
+            zstd: Validate.alternatives([
+                Validate.boolean(),
+                Validate.object()
+            ]).default(false)
+        }).default(),
         minBytes: Validate.number().min(1).integer().default(1024),
         priority: Validate.array().items(Validate.string().valid('gzip', 'deflate', 'br', 'zstd')).default(null)
     })

lib/core.js

@@ -54,7 +54,7 @@ exports = module.exports = internals.Core = class {
     app = {};
     auth = new Auth(this);
     caches = new Map();                                                        // Cache clients
-    compression = new Compression();
+    compression = null;
     controlled = null;                                                         // Other servers linked to the phases of this server
     dependencies = [];                                                         // Plugin dependencies
     events = new Podium.Podium(internals.events);
@@ -119,6 +119,7 @@ exports = module.exports = internals.Core = class {
         this.settings = settings;
         this.type = type;
 
+        this.compression = new Compression(this.settings);
         this.heavy = new Heavy(this.settings.load);
         this.mime = new Mimos(this.settings.mime);
         this.router = new Call.Router(this.settings.router);
@@ -127,16 +128,6 @@ exports = module.exports = internals.Core = class {
         this._debug();
         this._initializeCache();
 
-        if (this.settings.compression.enableBrotli) {
-            this.compression.enableBrotliCompression(this.settings.compression.enableBrotli);
-        }
-
-        /* $lab:coverage:off$ */
-        if (this.settings.compression.enableZstd) {
-            this.compression.enableZstdCompression(this.settings.compression.enableZstd);
-        }
-        /* $lab:coverage:on$ */
-
         if (this.settings.compression.priority) {
             this.compression.setPriority(this.settings.compression.priority);
         }

lib/types/server/options.d.ts

@@ -1,6 +1,6 @@
 import * as http from 'http';
 import * as https from 'https';
-import { BrotliOptions, ZstdOptions } from 'zlib';
+import { BrotliOptions, ZstdOptions, ZlibOptions } from 'zlib';
 
 import { MimosOptions } from '@hapi/mimos';
 
@@ -10,10 +10,14 @@ import { CacheProvider, ServerOptionsCache } from './cache';
 import { SameSitePolicy, ServerStateCookieOptions } from './state';
 
 export interface ServerOptionsCompression {
-    enableBrotli: boolean | BrotliOptions;
-    enableZstd: boolean | ZstdOptions;
+    encodings?: {
+        gzip?: boolean | ZlibOptions;
+        deflate?: boolean | ZlibOptions;
+        br?: boolean | BrotliOptions;
+        zstd?: boolean | ZstdOptions;
+    };
     minBytes: number;
-    priority: string[];
+    priority?: string[];
 }
 
 /**

package.json

@@ -39,7 +39,7 @@
     "@hapi/somever": "^4.1.1",
     "@hapi/statehood": "^8.2.0",
     "@hapi/subtext": "^8.1.1",
-    "@hapi/teamwork": "^6.0.0",
+    "@hapi/teamwork": "^6.0.1",
     "@hapi/topo": "^6.0.2",
     "@hapi/validate": "^2.0.1"
   },
@@ -51,7 +51,7 @@
     "@hapi/lab": "^25.3.2",
     "@hapi/vision": "^7.0.3",
     "@hapi/wreck": "^18.1.0",
-    "@types/node": "^22.17.0",
+    "@types/node": "^22.18.3",
     "handlebars": "^4.7.8",
     "joi": "^17.13.3",
     "legacy-readable-stream": "npm:readable-stream@^1.1.14",

test/payload.js

@@ -530,7 +530,7 @@ describe('Payload', () => {
     it('handles br payload', async () => {
 
         const message = { 'msg': 'This message is going to be brotlied.' };
-        const server = Hapi.server({ compression: { enableBrotli: true } });
+        const server = Hapi.server({ compression: { encodings: { br: true } } });
         server.route({ method: 'POST', path: '/', handler: (request) => request.payload });
 
         const compressed = await new Promise((resolve) => Zlib.brotliCompress(JSON.stringify(message), (ignore, result) => resolve(result)));
@@ -554,7 +554,7 @@ describe('Payload', () => {
     it('handles zstd payload', { skip: !Common.hasZstd }, async () => {
 
         const message = { 'msg': 'This message is going to be zstded.' };
-        const server = Hapi.server({ compression: { enableZstd: true } });
+        const server = Hapi.server({ compression: { encodings: { zstd: true } } });
         server.route({ method: 'POST', path: '/', handler: (request) => request.payload });
 
         const compressed = await new Promise((resolve) => Zlib.zstdCompress(JSON.stringify(message), (ignore, result) => resolve(result)));