@zero-server/sdk 0.9.0 → 0.9.2

package/lib/body/raw.js

@@ -1,71 +1,71 @@
-/**
- * @module body/raw
- * @description Raw-buffer body-parsing middleware.
- *              Stores the full request body as a Buffer on `req.body`.
- *              Also sets `req.rawBody` for signature verification workflows.
- */
-const rawBuffer = require('./rawBuffer');
-const isTypeMatch = require('./typeMatch');
-const sendError = require('./sendError');
-
-/**
- * Create a raw-buffer body-parsing middleware.
- *
- * @param {object}          [options] - Configuration options.
- * @param {string|number}   [options.limit]                           - Max body size. Default `'1mb'`.
- * @param {string|string[]|Function} [options.type='application/octet-stream'] - Content-Type(s) to match.
- * @param {boolean}         [options.requireSecure=false]             - When true, reject non-HTTPS requests with 403.
- * @param {Function}        [options.verify]   - `verify(req, res, buf)` — called before setting body. Throw to reject with 403.
- * @param {boolean}         [options.inflate=true] - Decompress gzip/deflate/br bodies. When false, compressed bodies return 415.
- * @returns {Function} Async middleware `(req, res, next) => void`.
- *
- * @example
- *   const { raw } = require('@zero-server/sdk');
- *
- *   app.use(raw({ type: 'application/octet-stream', limit: '5mb' }));
- *
- *   app.post('/upload', (req, res) => {
- *       console.log(req.body); // Buffer
- *       res.send('received ' + req.body.length + ' bytes');
- *   });
- */
-function raw(options = {})
-{
-    const opts = options || {};
-    const limit = opts.limit !== undefined ? opts.limit : '1mb';
-    const typeOpt = opts.type || 'application/octet-stream';
-    const requireSecure = !!opts.requireSecure;
-    const verify = opts.verify;
-    const inflate = opts.inflate !== undefined ? opts.inflate : true;
-
-    return async (req, res, next) =>
-    {
-        if (requireSecure && !req.secure) return sendError(res, 403, 'HTTPS required');
-        const ct = (req.headers['content-type'] || '');
-        if (!isTypeMatch(ct, typeOpt)) return next();
-        try
-        {
-            const buf = await rawBuffer(req, { limit, inflate });
-
-            // Store raw body for signature verification
-            req.rawBody = buf;
-
-            // Optional verification callback
-            if (verify)
-            {
-                try { verify(req, res, buf); }
-                catch (e) { return sendError(res, 403, e.message || 'verification failed'); }
-            }
-
-            req.body = buf;
-        } catch (err)
-        {
-            if (err && err.status === 413) return sendError(res, 413, 'payload too large');
-            if (err && err.status === 415) return sendError(res, 415, err.message || 'unsupported encoding');
-            req.body = Buffer.alloc(0);
-        }
-        next();
-    };
-}
-
-module.exports = raw;
+/**
+ * @module body/raw
+ * @description Raw-buffer body-parsing middleware.
+ *              Stores the full request body as a Buffer on `req.body`.
+ *              Also sets `req.rawBody` for signature verification workflows.
+ */
+const rawBuffer = require('./rawBuffer');
+const isTypeMatch = require('./typeMatch');
+const sendError = require('./sendError');
+
+/**
+ * Create a raw-buffer body-parsing middleware.
+ *
+ * @param {object}          [options] - Configuration options.
+ * @param {string|number}   [options.limit]                           - Max body size. Default `'1mb'`.
+ * @param {string|string[]|Function} [options.type='application/octet-stream'] - Content-Type(s) to match.
+ * @param {boolean}         [options.requireSecure=false]             - When true, reject non-HTTPS requests with 403.
+ * @param {Function}        [options.verify]   - `verify(req, res, buf)` — called before setting body. Throw to reject with 403.
+ * @param {boolean}         [options.inflate=true] - Decompress gzip/deflate/br bodies. When false, compressed bodies return 415.
+ * @returns {Function} Async middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   const { raw } = require('@zero-server/sdk');
+ *
+ *   app.use(raw({ type: 'application/octet-stream', limit: '5mb' }));
+ *
+ *   app.post('/upload', (req, res) => {
+ *       console.log(req.body); // Buffer
+ *       res.send('received ' + req.body.length + ' bytes');
+ *   });
+ */
+function raw(options = {})
+{
+    const opts = options || {};
+    const limit = opts.limit !== undefined ? opts.limit : '1mb';
+    const typeOpt = opts.type || 'application/octet-stream';
+    const requireSecure = !!opts.requireSecure;
+    const verify = opts.verify;
+    const inflate = opts.inflate !== undefined ? opts.inflate : true;
+
+    return async (req, res, next) =>
+    {
+        if (requireSecure && !req.secure) return sendError(res, 403, 'HTTPS required');
+        const ct = (req.headers['content-type'] || '');
+        if (!isTypeMatch(ct, typeOpt)) return next();
+        try
+        {
+            const buf = await rawBuffer(req, { limit, inflate });
+
+            // Store raw body for signature verification
+            req.rawBody = buf;
+
+            // Optional verification callback
+            if (verify)
+            {
+                try { verify(req, res, buf); }
+                catch (e) { return sendError(res, 403, e.message || 'verification failed'); }
+            }
+
+            req.body = buf;
+        } catch (err)
+        {
+            if (err && err.status === 413) return sendError(res, 413, 'payload too large');
+            if (err && err.status === 415) return sendError(res, 415, err.message || 'unsupported encoding');
+            req.body = Buffer.alloc(0);
+        }
+        next();
+    };
+}
+
+module.exports = raw;

package/lib/body/rawBuffer.js

@@ -1,161 +1,161 @@
-/**
- * @module body/rawBuffer
- * @description Low-level helper that collects the raw request body into a
- *              single Buffer, enforcing an optional byte-size limit.
- *              Supports Content-Encoding decompression (gzip, deflate, br)
- *              and Content-Length pre-checking for early rejection.
- */
-const zlib = require('zlib');
-
-/**
- * Parse a human-readable size string (e.g. `'10kb'`, `'2mb'`) into bytes.
- *
- * @private
- * @param {string|number|null} limit - Size limit value.
- * @returns {number|null} Byte limit, or `null` for unlimited.
- */
-function parseLimit(limit)
-{
-    if (!limit && limit !== 0) return null;
-    if (typeof limit === 'number') return limit;
-    if (typeof limit === 'string')
-    {
-        const v = limit.trim().toLowerCase();
-        const num = Number(v.replace(/[^0-9.]/g, ''));
-        if (v.endsWith('kb')) return Math.floor(num * 1024);
-        if (v.endsWith('mb')) return Math.floor(num * 1024 * 1024);
-        if (v.endsWith('gb')) return Math.floor(num * 1024 * 1024 * 1024);
-        return Math.floor(num);
-    }
-    return null;
-}
-
-/**
- * Extract and normalise the charset from a Content-Type header value
- * into a Node.js-compatible `BufferEncoding` name.
- *
- * @param {string} contentType - Full Content-Type header value.
- * @returns {string|null} Normalised encoding or `null` when not specified.
- */
-function charsetFromContentType(contentType)
-{
-    if (!contentType) return null;
-    const m = contentType.match(/charset=["']?([^\s;"']+)/i);
-    if (!m) return null;
-    const raw = m[1].toLowerCase().replace(/[^a-z0-9]/g, '');
-    if (raw === 'utf8') return 'utf8';
-    if (raw === 'utf16le' || raw === 'utf16' || raw === 'ucs2') return 'utf16le';
-    if (raw === 'latin1' || raw === 'iso88591') return 'latin1';
-    if (raw === 'ascii' || raw === 'usascii') return 'ascii';
-    return 'utf8'; // safe fallback for unknown charsets
-}
-
-/**
- * Collect the raw request body into a Buffer.
- *
- * - Rejects with `{ status: 413 }` when `opts.limit` is exceeded.
- * - Rejects with `{ status: 415 }` for unsupported Content-Encoding or
- *   when `opts.inflate` is `false` and the body is compressed.
- * - Automatically decompresses gzip / deflate / br when `opts.inflate`
- *   is `true` (the default).
- *
- * @param {import('../http/request')} req        - Wrapped request (`.raw` stream, `.headers`).
+/**
+ * @module body/rawBuffer
+ * @description Low-level helper that collects the raw request body into a
+ *              single Buffer, enforcing an optional byte-size limit.
+ *              Supports Content-Encoding decompression (gzip, deflate, br)
+ *              and Content-Length pre-checking for early rejection.
+ */
+const zlib = require('zlib');
+
+/**
+ * Parse a human-readable size string (e.g. `'10kb'`, `'2mb'`) into bytes.
+ *
+ * @private
+ * @param {string|number|null} limit - Size limit value.
+ * @returns {number|null} Byte limit, or `null` for unlimited.
+ */
+function parseLimit(limit)
+{
+    if (!limit && limit !== 0) return null;
+    if (typeof limit === 'number') return limit;
+    if (typeof limit === 'string')
+    {
+        const v = limit.trim().toLowerCase();
+        const num = Number(v.replace(/[^0-9.]/g, ''));
+        if (v.endsWith('kb')) return Math.floor(num * 1024);
+        if (v.endsWith('mb')) return Math.floor(num * 1024 * 1024);
+        if (v.endsWith('gb')) return Math.floor(num * 1024 * 1024 * 1024);
+        return Math.floor(num);
+    }
+    return null;
+}
+
+/**
+ * Extract and normalise the charset from a Content-Type header value
+ * into a Node.js-compatible `BufferEncoding` name.
+ *
+ * @param {string} contentType - Full Content-Type header value.
+ * @returns {string|null} Normalised encoding or `null` when not specified.
+ */
+function charsetFromContentType(contentType)
+{
+    if (!contentType) return null;
+    const m = contentType.match(/charset=["']?([^\s;"']+)/i);
+    if (!m) return null;
+    const raw = m[1].toLowerCase().replace(/[^a-z0-9]/g, '');
+    if (raw === 'utf8') return 'utf8';
+    if (raw === 'utf16le' || raw === 'utf16' || raw === 'ucs2') return 'utf16le';
+    if (raw === 'latin1' || raw === 'iso88591') return 'latin1';
+    if (raw === 'ascii' || raw === 'usascii') return 'ascii';
+    return 'utf8'; // safe fallback for unknown charsets
+}
+
+/**
+ * Collect the raw request body into a Buffer.
+ *
+ * - Rejects with `{ status: 413 }` when `opts.limit` is exceeded.
+ * - Rejects with `{ status: 415 }` for unsupported Content-Encoding or
+ *   when `opts.inflate` is `false` and the body is compressed.
+ * - Automatically decompresses gzip / deflate / br when `opts.inflate`
+ *   is `true` (the default).
+ *
+ * @param {import('../http/request')} req        - Wrapped request (`.raw` stream, `.headers`).
  * @param {object}                    [opts] - Configuration options.
- * @param {string|number|null}        [opts.limit]         - Max body size (post-decompression).
- * @param {boolean}                   [opts.inflate=true]  - Decompress gzip/deflate/br bodies.
- * @returns {Promise<Buffer>} Resolved with the full body buffer.
- */
-function rawBuffer(req, opts = {})
-{
-    const limit = parseLimit(opts.limit);
-    const inflate = opts.inflate !== false;
-
-    return new Promise((resolve, reject) =>
-    {
-        const headers = req.headers || (req.raw && req.raw.headers) || {};
-
-        // Content-Encoding handling
-        const encoding = (headers['content-encoding'] || '').toLowerCase().trim();
-        const isCompressed = encoding && encoding !== 'identity';
-
-        // Content-Length pre-check (skip for compressed bodies — CL is the compressed size)
-        if (!isCompressed)
-        {
-            const cl = parseInt(headers['content-length'], 10);
-            if (limit && cl && cl > limit)
-            {
-                const err = new Error('payload too large');
-                err.status = 413;
-                return reject(err);
-            }
-        }
-
-        // Select stream source (possibly a decompression transform)
-        let stream = req.raw;
-        if (isCompressed)
-        {
-            if (!inflate)
-            {
-                const err = new Error('compressed bodies not accepted');
-                err.status = 415;
-                return reject(err);
-            }
-            if (encoding === 'gzip' || encoding === 'x-gzip')
-            {
-                stream = req.raw.pipe(zlib.createGunzip());
-            }
-            else if (encoding === 'deflate')
-            {
-                stream = req.raw.pipe(zlib.createInflate());
-            }
-            else if (encoding === 'br')
-            {
-                stream = req.raw.pipe(zlib.createBrotliDecompress());
-            }
-            else
-            {
-                const err = new Error('unsupported Content-Encoding: ' + encoding);
-                err.status = 415;
-                return reject(err);
-            }
-        }
-
-        const chunks = [];
-        let total = 0;
-
-        function cleanup()
-        {
-            stream.removeListener('data', onData);
-            stream.removeListener('end', onEnd);
-            stream.removeListener('error', onError);
-        }
-        function onData(c)
-        {
-            total += c.length;
-            if (limit && total > limit)
-            {
-                cleanup();
-                const err = new Error('payload too large');
-                err.status = 413;
-                return reject(err);
-            }
-            chunks.push(c);
-        }
-        function onEnd()
-        {
-            cleanup();
-            resolve(Buffer.concat(chunks));
-        }
-        function onError(e)
-        {
-            cleanup();
-            reject(e);
-        }
-        stream.on('data', onData);
-        stream.on('end', onEnd);
-        stream.on('error', onError);
-    });
-}
-
-module.exports = rawBuffer;
-module.exports.charsetFromContentType = charsetFromContentType;
+ * @param {string|number|null}        [opts.limit]         - Max body size (post-decompression).
+ * @param {boolean}                   [opts.inflate=true]  - Decompress gzip/deflate/br bodies.
+ * @returns {Promise<Buffer>} Resolved with the full body buffer.
+ */
+function rawBuffer(req, opts = {})
+{
+    const limit = parseLimit(opts.limit);
+    const inflate = opts.inflate !== false;
+
+    return new Promise((resolve, reject) =>
+    {
+        const headers = req.headers || (req.raw && req.raw.headers) || {};
+
+        // Content-Encoding handling
+        const encoding = (headers['content-encoding'] || '').toLowerCase().trim();
+        const isCompressed = encoding && encoding !== 'identity';
+
+        // Content-Length pre-check (skip for compressed bodies — CL is the compressed size)
+        if (!isCompressed)
+        {
+            const cl = parseInt(headers['content-length'], 10);
+            if (limit && cl && cl > limit)
+            {
+                const err = new Error('payload too large');
+                err.status = 413;
+                return reject(err);
+            }
+        }
+
+        // Select stream source (possibly a decompression transform)
+        let stream = req.raw;
+        if (isCompressed)
+        {
+            if (!inflate)
+            {
+                const err = new Error('compressed bodies not accepted');
+                err.status = 415;
+                return reject(err);
+            }
+            if (encoding === 'gzip' || encoding === 'x-gzip')
+            {
+                stream = req.raw.pipe(zlib.createGunzip());
+            }
+            else if (encoding === 'deflate')
+            {
+                stream = req.raw.pipe(zlib.createInflate());
+            }
+            else if (encoding === 'br')
+            {
+                stream = req.raw.pipe(zlib.createBrotliDecompress());
+            }
+            else
+            {
+                const err = new Error('unsupported Content-Encoding: ' + encoding);
+                err.status = 415;
+                return reject(err);
+            }
+        }
+
+        const chunks = [];
+        let total = 0;
+
+        function cleanup()
+        {
+            stream.removeListener('data', onData);
+            stream.removeListener('end', onEnd);
+            stream.removeListener('error', onError);
+        }
+        function onData(c)
+        {
+            total += c.length;
+            if (limit && total > limit)
+            {
+                cleanup();
+                const err = new Error('payload too large');
+                err.status = 413;
+                return reject(err);
+            }
+            chunks.push(c);
+        }
+        function onEnd()
+        {
+            cleanup();
+            resolve(Buffer.concat(chunks));
+        }
+        function onError(e)
+        {
+            cleanup();
+            reject(e);
+        }
+        stream.on('data', onData);
+        stream.on('end', onEnd);
+        stream.on('error', onError);
+    });
+}
+
+module.exports = rawBuffer;
+module.exports.charsetFromContentType = charsetFromContentType;

package/lib/body/sendError.js

@@ -1,25 +1,25 @@
-/**
- * @module body/sendError
- * @private
- * @description Shared helper for sending HTTP error responses from body parsers.
- *              Centralizes the pattern used across all parsers so changes only happen in one place.
- */
-
-/**
- * Send an HTTP error response.
- *
- * @private
- * @param {object} res    - The response wrapper (or raw response).
- * @param {number} status - HTTP status code.
- * @param {string} message - Error message string for the JSON body.
- */
-function sendError(res, status, message)
-{
-    const raw = res.raw || res;
-    if (raw.headersSent) return;
-    raw.statusCode = status;
-    raw.setHeader('Content-Type', 'application/json');
-    raw.end(JSON.stringify({ error: message }));
-}
-
-module.exports = sendError;
+/**
+ * @module body/sendError
+ * @private
+ * @description Shared helper for sending HTTP error responses from body parsers.
+ *              Centralizes the pattern used across all parsers so changes only happen in one place.
+ */
+
+/**
+ * Send an HTTP error response.
+ *
+ * @private
+ * @param {object} res    - The response wrapper (or raw response).
+ * @param {number} status - HTTP status code.
+ * @param {string} message - Error message string for the JSON body.
+ */
+function sendError(res, status, message)
+{
+    const raw = res.raw || res;
+    if (raw.headersSent) return;
+    raw.statusCode = status;
+    raw.setHeader('Content-Type', 'application/json');
+    raw.end(JSON.stringify({ error: message }));
+}
+
+module.exports = sendError;

package/lib/body/text.js

@@ -1,75 +1,75 @@
-/**
- * @module body/text
- * @description Plain-text body-parsing middleware.
- *              Reads the request body as a string and sets `req.body`.
- *              Stores the raw buffer on `req.rawBody` for signature verification.
- */
-const rawBuffer = require('./rawBuffer');
-const { charsetFromContentType } = require('./rawBuffer');
-const isTypeMatch = require('./typeMatch');
-const sendError = require('./sendError');
-
-/**
- * Create a plain-text body-parsing middleware.
- *
- * @param {object}          [options] - Configuration options.
- * @param {string|number}   [options.limit]              - Max body size. Default `'1mb'`.
- * @param {string}          [options.encoding='utf8']    - Fallback character encoding when Content-Type has no charset.
- * @param {string|string[]|Function} [options.type='text/*'] - Content-Type(s) to match.
- * @param {boolean}         [options.requireSecure=false] - When true, reject non-HTTPS requests with 403.
- * @param {Function}        [options.verify]   - `verify(req, res, buf, encoding)` — called before decoding. Throw to reject with 403.
- * @param {boolean}         [options.inflate=true] - Decompress gzip/deflate/br bodies. When false, compressed bodies return 415.
- * @returns {Function} Async middleware `(req, res, next) => void`.
- *
- * @example
- *   const { text } = require('@zero-server/sdk');
- *
- *   app.use(text({ type: 'text/plain', limit: '256kb' }));
- *
- *   app.post('/log', (req, res) => {
- *       console.log(req.body); // raw string
- *       res.send('ok');
- *   });
- */
-function text(options = {})
-{
-  const opts = options || {};
-  const limit = opts.limit !== undefined ? opts.limit : '1mb';
-  const defaultEncoding = opts.encoding || 'utf8';
-  const typeOpt = opts.type || 'text/*';
-  const requireSecure = !!opts.requireSecure;
-  const verify = opts.verify;
-  const inflate = opts.inflate !== undefined ? opts.inflate : true;
-
-  return async (req, res, next) =>
-  {
-    if (requireSecure && !req.secure) return sendError(res, 403, 'HTTPS required');
-    const ct = (req.headers['content-type'] || '');
-    if (!isTypeMatch(ct, typeOpt)) return next();
-    try
-    {
-      const buf = await rawBuffer(req, { limit, inflate });
-      const encoding = charsetFromContentType(ct) || defaultEncoding;
-
-      // Store raw body for signature verification
-      req.rawBody = buf;
-
-      // Optional verification callback
-      if (verify)
-      {
-        try { verify(req, res, buf, encoding); }
-        catch (e) { return sendError(res, 403, e.message || 'verification failed'); }
-      }
-
-      req.body = buf.toString(encoding);
-    } catch (err)
-    {
-      if (err && err.status === 413) return sendError(res, 413, 'payload too large');
-      if (err && err.status === 415) return sendError(res, 415, err.message || 'unsupported encoding');
-      req.body = '';
-    }
-    next();
-  };
-}
-
-module.exports = text;
+/**
+ * @module body/text
+ * @description Plain-text body-parsing middleware.
+ *              Reads the request body as a string and sets `req.body`.
+ *              Stores the raw buffer on `req.rawBody` for signature verification.
+ */
+const rawBuffer = require('./rawBuffer');
+const { charsetFromContentType } = require('./rawBuffer');
+const isTypeMatch = require('./typeMatch');
+const sendError = require('./sendError');
+
+/**
+ * Create a plain-text body-parsing middleware.
+ *
+ * @param {object}          [options] - Configuration options.
+ * @param {string|number}   [options.limit]              - Max body size. Default `'1mb'`.
+ * @param {string}          [options.encoding='utf8']    - Fallback character encoding when Content-Type has no charset.
+ * @param {string|string[]|Function} [options.type='text/*'] - Content-Type(s) to match.
+ * @param {boolean}         [options.requireSecure=false] - When true, reject non-HTTPS requests with 403.
+ * @param {Function}        [options.verify]   - `verify(req, res, buf, encoding)` — called before decoding. Throw to reject with 403.
+ * @param {boolean}         [options.inflate=true] - Decompress gzip/deflate/br bodies. When false, compressed bodies return 415.
+ * @returns {Function} Async middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   const { text } = require('@zero-server/sdk');
+ *
+ *   app.use(text({ type: 'text/plain', limit: '256kb' }));
+ *
+ *   app.post('/log', (req, res) => {
+ *       console.log(req.body); // raw string
+ *       res.send('ok');
+ *   });
+ */
+function text(options = {})
+{
+  const opts = options || {};
+  const limit = opts.limit !== undefined ? opts.limit : '1mb';
+  const defaultEncoding = opts.encoding || 'utf8';
+  const typeOpt = opts.type || 'text/*';
+  const requireSecure = !!opts.requireSecure;
+  const verify = opts.verify;
+  const inflate = opts.inflate !== undefined ? opts.inflate : true;
+
+  return async (req, res, next) =>
+  {
+    if (requireSecure && !req.secure) return sendError(res, 403, 'HTTPS required');
+    const ct = (req.headers['content-type'] || '');
+    if (!isTypeMatch(ct, typeOpt)) return next();
+    try
+    {
+      const buf = await rawBuffer(req, { limit, inflate });
+      const encoding = charsetFromContentType(ct) || defaultEncoding;
+
+      // Store raw body for signature verification
+      req.rawBody = buf;
+
+      // Optional verification callback
+      if (verify)
+      {
+        try { verify(req, res, buf, encoding); }
+        catch (e) { return sendError(res, 403, e.message || 'verification failed'); }
+      }
+
+      req.body = buf.toString(encoding);
+    } catch (err)
+    {
+      if (err && err.status === 413) return sendError(res, 413, 'payload too large');
+      if (err && err.status === 415) return sendError(res, 415, err.message || 'unsupported encoding');
+      req.body = '';
+    }
+    next();
+  };
+}
+
+module.exports = text;