@vbarbarosh/node-helpers 3.77.0 → 3.78.1

package/src/format_error_report.md

@@ -10,3 +10,50 @@ errors get special treatment; everything else becomes indented JSON.
   split into an array of lines (circular-safe via `json_stringify_safe`).
 - Falsy error — `{"error":null}`-style JSON; `undefined` is reported as the
   string `'---undefined---'`.
+
+**Masking:** credentials are replaced by `***` in the REQUEST
+section so the report can be logged or sent to error tracking.
+
+Header values are masked when the name, matched case-insensitively, is one
+of:
+
+- `api-key`
+- `authorization`
+- `cookie`
+- `proxy-authorization`
+- `set-cookie`
+- `x-api-key`
+- `x-auth-token`
+
+Headers nested per method the Axios way (`headers.common`, `headers.get`,
+...) and `AxiosHeaders` instances (via `toJSON`) are handled; the error
+object itself is not modified.
+
+URL userinfo is masked (`https://user:pass@host` becomes
+`https://***@host`), and so is the value of every query parameter with a
+secret-looking name (`?token=abc&page=2` becomes `?token=***&page=2`). A
+name is secret-looking when, split on `_`/`-`/`.` and camelCase boundaries
+and lower-cased, any segment is one of the words below, or when the whole
+name with separators removed is one of them:
+
+- `accesstoken`
+- `apikey`
+- `auth`
+- `authorization`
+- `key`
+- `pass`
+- `passwd`
+- `password`
+- `pwd`
+- `secret`
+- `sig`
+- `signature`
+- `token`
+
+So `api_key`, `apiKey`, `access_token`, `x-auth-token`, `client_secret`,
+`sig` and `key` are masked while `keyword`, `design`, `author`,
+`keyboard`, `signal` and `client_id` are not. The rest of the URL is
+reported verbatim.
+
+The response body is **not** sanitized — only truncated to 10240
+characters — and the request body is never included.

package/src/http_get_stream_range.js

@@ -46,7 +46,11 @@ async function http_get_stream_range(url, first, last, options)
     else if (b !== '') {
         const actual_length = out.content_range.last - out.content_range.first + 1;
         const expected_length = out.content_range.total === null ? Math.min(actual_length, b) : Math.min(out.content_range.total, b);
-        if (actual_length !== expected_length) {
+        if (out.content_range.last === null) {
+            // Chunked 200 with no Content-Range: the server ignored the suffix range
+            out.destroy(new Error(`Server ignored the requested suffix range of ${fmt(b)} bytes and returned a response of unknown length`));
+        }
+        else if (actual_length !== expected_length) {
             out.destroy(new Error(`Length of a returned range (${fmt(actual_length)}) is not as expected: [${fmt(expected_length)}]`));
         }
         else if (out.content_range.total !== null && out.content_range.last !== out.content_range.total - 1) {

package/src/http_get_stream_range.md

@@ -14,7 +14,8 @@ chunked 200 response (neither header) is accepted as
 The returned range is validated according to the requested form. Closed ranges
 accept a `last` clamped to the end of the resource; open-ended ranges must end
 at the resource end when its size is known; suffix ranges validate their
-length and resource end. A server that ignores a range and replies 200 is
+length and resource end, and a chunked 200 (unknown length) in reply to a
+suffix request is rejected. A server that ignores a range and replies 200 is
 rejected.
 
 ```js

package/src/http_stream_range.js

@@ -1,4 +1,5 @@
 const escape_content_disposition = require('./escape_content_disposition');
+const escape_content_disposition_utf8 = require('./escape_content_disposition_utf8');
 const fs_fclose = require('./fs_fclose');
 const fs_fopen = require('./fs_fopen');
 const fs_fread = require('./fs_fread');
@@ -30,7 +31,7 @@ async function http_stream_range(req, res, file)
         res.header('Accept-Ranges', 'bytes');
         res.header('Content-Type', mime);
         res.header('Content-Length', total);
-        res.header('Content-Disposition', `inline; filename=${escape_content_disposition(fs_path_basename(file))};`);
+        res.header('Content-Disposition', content_disposition(fs_path_basename(file)));
         res.status(200);
         res.end();
         return;
@@ -122,4 +123,16 @@ async function http_stream_range(req, res, file)
     }
 }
 
+function content_disposition(name)
+{
+    // The quoted `filename` degrades anything outside ISO-8859-1 to '?', so a
+    // non-ASCII name also gets the RFC 5987 `filename*` that browsers prefer.
+    let out = `inline; filename=${escape_content_disposition(name)}`;
+    // eslint-disable-next-line no-control-regex
+    if (/[^\x00-\x7f]/.test(name)) {
+        out += `; filename*=${escape_content_disposition_utf8(name)}`;
+    }
+    return out + ';';
+}
+
 module.exports = http_stream_range;

package/src/http_stream_range.md

@@ -11,7 +11,9 @@ http_stream_range(req, res, file) → Promise
 
 - `HEAD` → 200 with `Content-Type`, `Content-Length`, and an
   `inline; filename=...` `Content-Disposition` (escaped via
-  `escape_content_disposition`); no body.
+  `escape_content_disposition`, so control characters are encoded and a
+  non-ASCII basename is also sent as an RFC 5987 `filename*=UTF-8''...`
+  parameter); no body.
 - `GET` with `Range` → 206 with `Content-Range: bytes first-last/total` and a
   matching `Content-Length`.
 - `GET` without `Range` → 200 with the whole file.

package/src/make_progress.js

@@ -21,10 +21,16 @@ function make_progress(total)
         progress: null,
         percents: null,
         add: function (delta = 0) {
-            const now_minus_10sec = Date.now() - 10000;
-            history.splice(0, history.findLastIndex(v => v.time < now_minus_10sec) + 1);
-            history.push({time: Date.now(), delta});
+            const now = Date.now();
+            // The oldest sample is the anchor the rate is measured from, so
+            // the newest sample older than 10s is kept: the window then
+            // stays close to 10s instead of shrinking after each eviction
+            const expired = history.findLastIndex(v => v.time < now - 10000);
+            if (expired > 0) {
+                history.splice(0, expired);
+            }
             out.done += delta;
+            history.push({time: now, done: out.done});
             out.refresh();
         },
         update: function (done) {
@@ -32,16 +38,17 @@ function make_progress(total)
         },
         refresh: function () {
             out.duration = (Date.now() - time0)/1000;
-            // `rate` and `eta` are null while unknown (same as before the
-            // first add): a zero time window would give rate = Infinity,
-            // and a zero rate would give eta = Infinity.
-            if (history.length) {
-                const delta = history.reduce((a,v) => a + v.delta, 0);
+            // `rate` and `eta` are null while unknown: a single sample says
+            // nothing about how long its delta took to accumulate (counting
+            // it doubled the rate early on), a zero time window would give
+            // rate = Infinity, and a zero rate would give eta = Infinity.
+            if (history.length > 1) {
+                const delta = out.done - history[0].done;
                 const time_sec = (Date.now() - history[0].time)/1000;
                 out.rate = time_sec ? delta/time_sec : null;
             }
             else {
-                out.rate = out.duration ? out.done/out.duration : null;
+                out.rate = null;
             }
             out.percents = !out.total ? null : out.done/out.total;
             out.eta = (!out.total || !out.rate) ? null : (out.total - out.done)/out.rate;

package/src/make_progress.md

@@ -3,10 +3,13 @@ rows created). Pass the snapshot to `format_progress_bytes` /
 `format_progress_kilo` for display.
 
 **Fields:** `done`, `total`, `duration` (seconds since creation), `rate`
-(units/second over a sliding 10-second history window), `eta` (seconds),
-`percents` (a fraction, `done/total`). `rate` and `eta` are `null` while
-unknown — before the first `add`, or when they would be `Infinity` (zero
-time window, zero rate); `percents` is `null` when `total` is falsy.
+(units/second over a sliding ~10-second history window), `eta` (seconds),
+`percents` (a fraction, `done/total`). The rate is measured between the
+oldest sample in the window and now, so the first sample's own delta is
+not counted (how long it took to accumulate is unknown). `rate` and `eta`
+are `null` while unknown — until two `add` calls exist, or when they would
+be `Infinity` (zero time window, zero rate); `percents` is `null` when
+`total` is falsy.
 
 **Methods:**
 - `add(delta)` — add `delta` to `done` and recompute

package/src/pgid_exists.js

@@ -2,6 +2,11 @@
 // keep in sync with pid_exists
 function pgid_exists(pgid)
 {
+    // kill(-0, ...) targets the caller's own group and kill(-1, ...) every
+    // process the user may signal: never let such ids reach the kernel
+    if (!Number.isInteger(pgid) || pgid <= 1) {
+        throw new TypeError(`pgid_exists: invalid pgid: ${pgid}`);
+    }
     try {
         process.kill(-pgid, 0);
         return true;

package/src/pgid_exists.md

@@ -3,4 +3,8 @@ Checks whether a process group is alive by sending signal `0` to the group via
 at least one member, `false` on any error (no such group, or no permission).
 A group id equals the pid of the group leader.
 
+Throws `TypeError` when `pgid` is not an integer greater than `1`: `0` would
+probe the caller's own process group and `1` every process the user may
+signal (`kill(-1, ...)`), so such values never reach `kill(2)`.
+
 See `pid_exists` for the single-process variant.

package/src/pgid_kill_grace.js

@@ -7,6 +7,11 @@ const pgid_exists = require('./pgid_exists');
 // keep in sync with pid_kill_grace
 async function pgid_kill_grace(pgid, {grace_timeout_ms = 5000, log = ignore} = {})
 {
+    // kill(-0, ...) targets the caller's own group and kill(-1, ...) every
+    // process the user may signal: never let such ids reach the kernel
+    if (!Number.isInteger(pgid) || pgid <= 1) {
+        throw new TypeError(`pgid_kill_grace: invalid pgid: ${pgid}`);
+    }
     log(`Terminating process group ${pgid}: sending SIGTERM`);
     try {
         process.kill(-pgid, 'SIGTERM');

package/src/pgid_kill_grace.md

@@ -5,6 +5,9 @@ to deliver it. A group id equals the pid of the group leader.
 
 - Options: `grace_timeout_ms` (default `5000`) and `log` (progress callback,
   default no-op).
+- Throws `TypeError` before sending anything when `pgid` is not an integer
+  greater than `1` (`0` would signal the caller's own group, `1` every
+  process the user may signal via `kill(-1, ...)`).
 - Throws `Failed to send SIGTERM to process group <pgid>: ...` when the
   initial signal cannot be sent.
 - A group that dies on its own during the grace period skips the `SIGKILL`;

package/src/pid_exists.js

@@ -1,6 +1,11 @@
 // keep in sync with pgid_exists
 function pid_exists(pid)
 {
+    // kill(0, ...) targets the caller's own group and kill(-1, ...) every
+    // process the user may signal: never let such ids reach the kernel
+    if (!Number.isInteger(pid) || pid <= 1) {
+        throw new TypeError(`pid_exists: invalid pid: ${pid}`);
+    }
     try {
         process.kill(pid, 0);
         return true;

package/src/pid_exists.md

@@ -2,4 +2,8 @@ Checks whether a process is alive by sending signal `0` via
 `process.kill(pid, 0)`. Returns `true` when the signal can be delivered,
 `false` on any error (no such process, or no permission to signal it).
 
+Throws `TypeError` when `pid` is not an integer greater than `1`: `0` would
+probe the caller's own process group and `-1` every process the user may
+signal, so such values never reach `kill(2)`.
+
 See `pgid_exists` for the process-group variant.

package/src/pid_kill_grace.js

@@ -6,6 +6,11 @@ const pid_exists = require('./pid_exists');
 // keep in sync with pgid_kill_grace
 async function pid_kill_grace(pid, {grace_timeout_ms = 5000, log = ignore} = {})
 {
+    // kill(0, ...) targets the caller's own group and kill(-1, ...) every
+    // process the user may signal: never let such ids reach the kernel
+    if (!Number.isInteger(pid) || pid <= 1) {
+        throw new TypeError(`pid_kill_grace: invalid pid: ${pid}`);
+    }
     log(`Terminating process ${pid}: sending SIGTERM`);
     try {
         process.kill(pid, 'SIGTERM');

package/src/pid_kill_grace.md

@@ -4,6 +4,9 @@ waits up to 200ms more for the kernel to deliver it.
 
 - Options: `grace_timeout_ms` (default `5000`) and `log` (progress callback,
   default no-op).
+- Throws `TypeError` before sending anything when `pid` is not an integer
+  greater than `1` (`0` would signal the caller's own group, `-1` every
+  process the user may signal).
 - Throws `Failed to send SIGTERM to process <pid>: ...` when the initial
   signal cannot be sent (e.g. the process does not exist).
 - A process that dies on its own during the grace period skips the `SIGKILL`

package/src/redis_poll_zshift_callback_rpush.js

@@ -64,6 +64,10 @@ async function redis_poll_zshift_callback_rpush(options)
                 log(`[${log_waiter_error_parse}] ${error.message}`);
                 continue;
             }
+            if (!message || typeof message !== 'object') {
+                log(`[${log_waiter_error_parse}] message is not an object; skipped`);
+                continue;
+            }
 
             try {
                 const uid = message.uid;

package/src/redis_poll_zshift_callback_rpush.md

@@ -5,9 +5,10 @@ type, value}` to `redis_output_queue` — `type: 'resolve'` with the callback's
 return value, or `'reject'` with the error stack/message. An empty poll
 sleeps a random 500–1500ms; the loop runs at most 86400 iterations.
 
-- Unparseable messages and messages without `uid` are skipped; a missing or
-  past `expires_at` rejects the message (payloads carry signed urls with
-  limited lifetime).
+- Unparseable messages, valid JSON that is not an object (`null`, numbers,
+  strings), and messages without `uid` are skipped; a missing or past
+  `expires_at` rejects the message (payloads carry signed urls with limited
+  lifetime).
 - `user_friendly_status(value)` rpushes `{uid, version, type:
   'user_friendly_status', value}` to the output queue; a generic
   `'Started...'` status is always pushed first so the consumer starts

package/src/redis_poll_zshift_spawn_rpush.js

@@ -73,6 +73,10 @@ async function redis_poll_zshift_spawn_rpush(options)
                 log(`[${log_waiter_error_parse}] ${error.message}`);
                 continue;
             }
+            if (!message || typeof message !== 'object') {
+                log(`[${log_waiter_error_parse}] message is not an object; skipped`);
+                continue;
+            }
 
             try {
                 const uid = message.uid;

package/src/redis_poll_zshift_spawn_rpush.md

@@ -12,9 +12,10 @@ iterations.
   `'Started...'` status is always pushed first. stdout/stderr are logged
   line by line under the `log_worker_stdout`/`log_worker_stderr` tags.
 - Only exit code 0 is a success — a signal-killed child (code `null`) fails.
-- Unparseable messages and messages without `uid` are skipped; a missing or
-  past `expires_at` fails the message (payloads carry signed urls with
-  limited lifetime).
+- Unparseable messages, valid JSON that is not an object (`null`, numbers,
+  strings), and messages without `uid` are skipped; a missing or past
+  `expires_at` fails the message (payloads carry signed urls with limited
+  lifetime).
 - `options.log` must provide `spawn()`; queue access goes through
   `redis_zshift`/`redis_rpush`, so any redis client from redis@1 to redis@6
   works. See `redis_poll_zshift_callback_rpush` for the in-process

package/src/shell.js

@@ -7,7 +7,7 @@ function shell(args, options)
             if (error) {
                 reject(error);
             }
-            else if (stderr) {
+            else if (stderr.length) {
                 reject(new Error(`Process terminated with the following STDERR:\n\n${stderr}`));
             }
             else {

package/src/shell.md

@@ -2,7 +2,8 @@ Basic helper for running external commands via `execFile`.
 
 - Fails if the command exits with non-zero code.
 - Fails if anything is printed to `stderr`.
-- Resolves with `stdout` (string), exactly as produced.
+- Resolves with `stdout` (string), exactly as produced; a `Buffer` with
+  `{encoding: 'buffer'}`.
 
 ## Signature
 

package/src/shell_json.js

@@ -7,7 +7,7 @@ function shell_json(args, options)
             if (error) {
                 reject(error);
             }
-            else if (stderr) {
+            else if (stderr.length) {
                 reject(new Error(`Process terminated with the following STDERR:\n\n${stderr}`));
             }
             else {

package/src/shell_json.md

@@ -3,7 +3,8 @@ Basic helper for running external commands via `execFile`, and parse result by J
 - Fails if the command exits with non-zero code.
 - Fails if anything is printed to `stderr`.
 - Fails if stdout is not valid JSON.
-- Resolves with parsed JSON value.
+- Resolves with parsed JSON value (`{encoding: 'buffer'}` is accepted;
+  `JSON.parse` stringifies the `Buffer`).
 
 ## Signature
 

package/src/stream_strpbrk.js

@@ -1,4 +1,5 @@
 const stream = require('stream');
+const {StringDecoder} = require('string_decoder');
 
 /**
  * Split the input stream by consecutive delimiters in `chars`
@@ -6,10 +7,13 @@ const stream = require('stream');
 function stream_strpbrk(chars = '\r\n')
 {
     const pending = [];
+    // StringDecoder buffers a multi-byte character split across chunk
+    // boundaries; plain buf.toString() would corrupt it into �.
+    const decoder = new StringDecoder('utf8');
     return new stream.Transform({
         objectMode: true,
         transform: function (str, encoding, callback) {
-            str = Buffer.isBuffer(str) ? str.toString() : str;
+            str = Buffer.isBuffer(str) ? decoder.write(str) : str;
 
             let off = 0;
             // leading delimiters
@@ -67,6 +71,10 @@ function stream_strpbrk(chars = '\r\n')
             callback();
         },
         flush: function (callback) {
+            const tail = decoder.end();
+            if (tail) {
+                pending.push(tail);
+            }
             if (pending.length) {
                 this.push(''.concat(...pending.splice(0)));
             }

package/src/stream_xml_analyze.js

@@ -17,7 +17,12 @@ function stream_xml_analyze()
         onopentag: function (name, attrs) {
             path.push(name);
             path_str = path.join(' > ');
-            analytics[path_str] ??= 0;
+            // Element names come from the outside world: `??=` on a plain
+            // object would see Object.prototype.constructor and produce NaN
+            // for a root element named `constructor`.
+            if (!Object.hasOwn(analytics, path_str)) {
+                Object.defineProperty(analytics, path_str, {value: 0, enumerable: true, writable: true, configurable: true});
+            }
             analytics[path_str]++;
         },
         onclosetag: function (name) {

package/src/stream_xml_parse.js

@@ -99,22 +99,30 @@ function guess(node)
 
     node.children.forEach(function (child) {
         const tmp = stream_xml_parse.guess(child);
-        if (child.name in out) {
+        // Element names come from the outside world: `in` and plain
+        // assignment would let `__proto__`, `constructor`, `toString`...
+        // hit Object.prototype instead of becoming own data properties.
+        if (Object.hasOwn(out, child.name)) {
             if (Array.isArray(out[child.name])) {
                 out[child.name].push(tmp);
             }
             else {
-                out[child.name] = [out[child.name], tmp];
+                define(out, child.name, [out[child.name], tmp]);
             }
         }
         else  {
-            out[child.name] = tmp;
+            define(out, child.name, tmp);
         }
     });
 
     return out;
 }
 
+function define(obj, name, value)
+{
+    Object.defineProperty(obj, name, {value, enumerable: true, writable: true, configurable: true});
+}
+
 function ashtml(node)
 {
     return node.raw.map(fn).filter(v => v).join('').trim();

package/src/urlmod.md

@@ -7,7 +7,9 @@ parameters, or an empty parameters object, returns the input unchanged.
 
 `null` and `undefined` remove a parameter. Boolean values are encoded as `1`
 and `0`; other values use the standard `URLSearchParams` conversion and
-encoding rules.
+encoding rules. Special names such as `__proto__`, `constructor`, and
+`hasOwnProperty` are handled as ordinary query parameter keys when provided as
+enumerable own properties.
 
 ```js
 urlmod('', {a: 1})                      // '?a=1'

package/src/urlparts.js

@@ -1,20 +1,116 @@
-function urlparts(url)
+/**
+ * Parse an absolute or relative URL-like string without rejecting malformed
+ * URL text. Missing components are returned as null.
+ */
+function urlparts(input)
 {
-    const tmp = url instanceof URL
-        ? url
-        : new URL((typeof url === 'string' ? url : ''), 'fake://fake/');
-    return {
-        href: tmp.href,
-        protocol: tmp.protocol,
-        hostname: tmp.hostname,
-        username: tmp.username,
-        password: tmp.password,
-        host: tmp.host,
-        port: tmp.port,
-        path: tmp.pathname,
-        search: tmp.search,
-        hash: tmp.hash,
+    const out = {
+        protocol: null,
+        username: null,
+        password: null,
+        host: null,
+        port: null,
+        path: null,
+        search: null,
+        hash: null,
+        query: {},
+        fragment: {},
     };
+
+    if (typeof input !== 'string') {
+        return out;
+    }
+
+    let resource = input;
+    const hash_pos = resource.indexOf('#');
+    if (hash_pos !== -1) {
+        out.hash = resource.slice(hash_pos);
+        out.fragment = parse_params(resource.slice(hash_pos + 1));
+        resource = resource.slice(0, hash_pos);
+    }
+
+    const query_pos = resource.indexOf('?');
+    if (query_pos !== -1) {
+        out.search = resource.slice(query_pos);
+        out.query = parse_params(resource.slice(query_pos + 1));
+        resource = resource.slice(0, query_pos);
+    }
+
+    const protocol_match = resource.match(/^([A-Za-z][A-Za-z0-9+.-]*):/);
+    if (protocol_match) {
+        out.protocol = protocol_match[1].toLowerCase();
+        resource = resource.slice(protocol_match[0].length);
+    }
+
+    if (resource.startsWith('//')) {
+        // WHATWG parsers treat `\` as `/` for special schemes, so the
+        // authority ends at the first of either.
+        const slash_offset = resource.slice(2).search(/[/\\]/);
+        const slash_pos = slash_offset === -1 ? -1 : slash_offset + 2;
+        const authority = slash_pos === -1
+            ? resource.slice(2)
+            : resource.slice(2, slash_pos);
+
+        out.path = slash_pos === -1 ? null : resource.slice(slash_pos) || null;
+        parse_authority(authority, out);
+    }
+    else {
+        out.path = resource || null;
+    }
+
+    return out;
+}
+
+function parse_params(value)
+{
+    const out = {};
+    for (const field of value.split('&')) {
+        const item = new URLSearchParams(field).entries().next();
+        if (!item.done) {
+            const [key, value] = item.value;
+            Object.defineProperty(out, key, {
+                configurable: true,
+                enumerable: true,
+                value,
+                writable: true,
+            });
+        }
+    }
+    return out;
+}
+
+function parse_authority(authority, parts)
+{
+    const at_pos = authority.lastIndexOf('@');
+    let host = authority;
+
+    if (at_pos !== -1) {
+        const userinfo = authority.slice(0, at_pos);
+        const colon_pos = userinfo.indexOf(':');
+
+        parts.username = colon_pos === -1 ? userinfo : userinfo.slice(0, colon_pos);
+        parts.password = colon_pos === -1 ? null : userinfo.slice(colon_pos + 1);
+        host = authority.slice(at_pos + 1);
+    }
+
+    if (host.startsWith('[')) {
+        const bracket_pos = host.indexOf(']');
+        if (bracket_pos !== -1 && host[bracket_pos + 1] === ':') {
+            parts.host = host.slice(0, bracket_pos + 1) || null;
+            parts.port = host.slice(bracket_pos + 2);
+            return;
+        }
+    }
+
+    const first_colon_pos = host.indexOf(':');
+    const last_colon_pos = host.lastIndexOf(':');
+    if (first_colon_pos !== -1 && first_colon_pos === last_colon_pos) {
+        parts.host = host.slice(0, first_colon_pos) || null;
+        parts.port = host.slice(first_colon_pos + 1);
+        return;
+    }
+
+    parts.host = host || null;
 }
 
 module.exports = urlparts;