@vbarbarosh/node-helpers 3.71.0 → 3.72.1

package/src/pgid_kill_grace.js

@@ -0,0 +1,55 @@
+const Promise = require('bluebird');
+const format_thousands = require('./format_thousands');
+const ignore = require('./ignore');
+const pgid_exists = require('./pgid_exists');
+
+// group id == leader pid
+// keep in sync with pid_kill_grace
+async function pgid_kill_grace(pgid, {grace_timeout_ms = 5000, log = ignore} = {})
+{
+    log(`Terminating process group ${pgid}: sending SIGTERM`);
+    try {
+        process.kill(-pgid, 'SIGTERM');
+    }
+    catch (error) {
+        throw new Error(`Failed to send SIGTERM to process group ${pgid}: ${error.message}`);
+    }
+
+    const end = Date.now() + grace_timeout_ms;
+    while (true) {
+        if (!pgid_exists(pgid)) {
+            return;
+        }
+        if (Date.now() >= end) {
+            break;
+        }
+        const remain = end - Date.now();
+        log(`Process group ${pgid} still alive; grace time remaining: ${format_thousands(remain)}ms`);
+        await Promise.delay(Math.max(0, Math.min(100, remain)));
+    }
+
+    try {
+        log(`SIGTERM grace period expired for group ${pgid}; sending SIGKILL`);
+        process.kill(-pgid, 'SIGKILL');
+    }
+    catch (error) {
+        if (error.code === 'ESRCH' && error.syscall === 'kill') {
+            log(`Process group ${pgid} already terminated`);
+            return;
+        }
+        throw error;
+    }
+
+    // Wait for kernel to deliver SIGKILL
+    const final_deadline = Date.now() + 200;
+    while (Date.now() < final_deadline) {
+        if (!pgid_exists(pgid)) {
+            return;
+        }
+        await Promise.delay(10);
+    }
+
+    throw new Error(`Process group ${pgid} survived SIGKILL`);
+}
+
+module.exports = pgid_kill_grace;

package/src/pid_exists.js

@@ -1,3 +1,4 @@
+// keep in sync with pgid_exists
 function pid_exists(pid)
 {
     try {

package/src/pid_kill_grace.d/ignore-sigterm-for-10ms.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+const Promise = require('bluebird');
+const cli = require('../cli');
+const now_human = require('../now_human');
+
+// Child ignores SIGTERM for 10 ms, but dies naturally before the grace loop ends
+
+cli(main);
+
+async function main()
+{
+    let timer;
+
+    process.on('SIGTERM', function () {
+        console.log(`[${now_human()}][ignore-sigterm-for-10ms] SIGTERM_ignoring...`);
+        timer ??= setTimeout(terminate, 10);
+    });
+    process.on('SIGINT', function () {
+        console.log(`[${now_human()}][ignore-sigterm-for-10ms] SIGINT_ignoring...`);
+    });
+
+    for (let iter = 1, last = 100; iter <= last; ++iter) {
+        console.log(`[${now_human()}][ignore-sigterm-for-10ms] ${iter} of ${last}`);
+        await Promise.delay(10);
+    }
+}
+
+function terminate()
+{
+    console.log(`[${now_human()}][ignore-sigterm-for-10ms] TERMINATE_AFTER_10MS`);
+    process.exit(0);
+}

package/src/pid_kill_grace.d/ignore-sigterm.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+const Promise = require('bluebird');
+const cli = require('../cli');
+const now_human = require('../now_human');
+
+cli(main);
+
+async function main()
+{
+    process.on('SIGTERM', function () {
+        console.log(`[${now_human()}][ignore-sigterm] SIGTERM_ignoring...`);
+    });
+    process.on('SIGINT', function () {
+        console.log(`[${now_human()}][ignore-sigterm] SIGINT_ignoring...`);
+    });
+
+    for (let iter = 1, last = 100; iter <= last; ++iter) {
+        console.log(`[${now_human()}][ignore-sigterm] ${iter} of ${last}`);
+        await Promise.delay(10);
+    }
+}

package/src/pid_kill_grace.js

@@ -3,26 +3,52 @@ const format_thousands = require('./format_thousands');
 const ignore = require('./ignore');
 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} = {})
 {
-    log('Sending SIGTERM');
-    if (!process.kill(pid, 'SIGTERM')) {
-        throw new Error('SIGTERM Failed');
+    log(`Terminating process ${pid}: sending SIGTERM`);
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch (error) {
+        throw new Error(`Failed to send SIGTERM to process ${pid}: ${error.message}`);
     }
 
     const end = Date.now() + grace_timeout_ms;
-    while (Date.now() < end) {
+    while (true) {
         if (!pid_exists(pid)) {
             return;
         }
-        log(`Process is still there, waiting for 100ms, ${format_thousands(end - Date.now())}ms left`);
-        await Promise.delay(100);
+        if (Date.now() >= end) {
+            break;
+        }
+        const remain = end - Date.now();
+        log(`Process ${pid} still alive; grace time remaining: ${format_thousands(remain)}ms`);
+        await Promise.delay(Math.max(0, Math.min(100, remain)));
     }
 
-    log('Sending SIGKILL');
-    if (!process.kill(pid, 'SIGKILL')) {
-        throw new Error('SIGKILL Failed');
+    try {
+        log(`SIGTERM grace period expired for process ${pid}; sending SIGKILL`);
+        process.kill(pid, 'SIGKILL');
+    }
+    catch (error) {
+        if (error.code === 'ESRCH' && error.syscall === 'kill') {
+            log(`Process ${pid} already terminated`);
+            return;
+        }
+        throw error;
     }
+
+    // Give kernel a moment to deliver SIGKILL
+    const final_deadline = Date.now() + 200;
+    while (Date.now() < final_deadline) {
+        if (!pid_exists(pid)) {
+            return;
+        }
+        await Promise.delay(10);
+    }
+
+    throw new Error(`Process ${pid} survived SIGKILL`);
 }
 
 module.exports = pid_kill_grace;

package/src/pid_kill_grace.test.js

@@ -0,0 +1,63 @@
+const assert = require('assert');
+const pid_exists = require('./pid_exists');
+const pid_kill_grace = require('./pid_kill_grace');
+const shell_spawn = require('./shell_spawn');
+const stream = require('stream');
+const stream_each = require('./stream_each');
+const stream_lines = require('./stream_lines');
+const wait_while = require('./wait_while');
+
+describe('pid_kill_grace', function() {
+
+    it('happy path', async function () {
+        const proc = await shell_spawn(['sleep', '1m']).init();
+        assert(pid_exists(proc.pid));
+        await pid_kill_grace(proc.pid);
+        assert(!pid_exists(proc.pid));
+    });
+
+    // handling errors and edge cases
+
+    it('should throw "Failed to send SIGTERM to process 123"', async function () {
+        const pid = 999999; // 🎲 unlikely to exist
+        assert(!pid_exists(pid));
+        await assert.rejects(pid_kill_grace(pid), /Failed to send SIGTERM to process \d+:/);
+    });
+
+    it.skip('should throw "Process 123 survived SIGKILL"', async function () {
+        // How to implement this behavior?
+    });
+
+    it('should KILL process after grace period', async function () {
+        const logs = [];
+        const stdout = [];
+        const proc = shell_spawn([`${__dirname}/pid_kill_grace.d/ignore-sigterm.js`]);
+        const r = stream.promises.pipeline(proc.stdout, stream_lines(), stream_each(v => stdout.push(v)));
+        await wait_while(() => !stdout.length);
+        await Promise.all([
+            r,
+            pid_kill_grace(proc.pid, {grace_timeout_ms: 50, log: s => logs.push(s)})
+        ]);
+        assert(!pid_exists(proc.pid));
+        assert(stdout.some(v => v.includes('SIGTERM_ignoring')));
+        assert(logs.some(v => v.match(/Terminating process \d+: sending SIGTERM/)));
+        assert(logs.some(v => v.match(/SIGTERM grace period expired for process \d+; sending SIGKILL/)));
+    });
+
+    it('Child ignores SIGTERM for 10ms, but dies naturally before the grace loop ends', async function () {
+        const logs = [];
+        const stdout = [];
+        const proc = shell_spawn([`${__dirname}/pid_kill_grace.d/ignore-sigterm-for-10ms.js`]);
+        const r = stream.promises.pipeline(proc.stdout, stream_lines(), stream_each(v => stdout.push(v)));
+        await wait_while(() => !stdout.length);
+        await Promise.all([
+            r,
+            pid_kill_grace(proc.pid, {grace_timeout_ms: 50, log: s => logs.push(s)})
+        ]);
+        assert(!pid_exists(proc.pid));
+        assert(stdout.some(v => v.includes('SIGTERM_ignoring')));
+        assert(stdout.some(v => v.includes('TERMINATE_AFTER_10MS')));
+        assert(logs.some(v => v.match(/Terminating process \d+: sending SIGTERM/)));
+        assert(!logs.some(v => v.match(/SIGTERM grace period expired for process \d+; sending SIGKILL/)));
+    });
+});

package/src/ping_socket.js

@@ -11,19 +11,19 @@ function ping_socket(socket_path, data = 'PING', timeout_ms = 1000)
     return new Promise(function (resolve, reject) {
         let done = false;
         const buf = [];
-        const socket = net.connect(socket_path);
-        socket.setTimeout(timeout_ms, () => finish(new Error('Socket Timeout')));
-        socket.on('end', () => finish(null, Buffer.concat(buf)))
-        socket.on('error', finish);
-        socket.on('connect', () => socket.end(data));
-        socket.on('data', chunk => buf.push(chunk));
+        const client = net.connect(socket_path);
+        client.setTimeout(timeout_ms, () => finish(new Error('Socket Timeout')));
+        client.on('end', () => finish(null, Buffer.concat(buf)))
+        client.on('error', finish);
+        client.on('connect', () => client.end(data));
+        client.on('data', chunk => buf.push(chunk));
         function finish(error, out) {
             if (done) {
                 return;
             }
             done = true;
-            socket.removeAllListeners();
-            socket.destroy();
+            client.removeAllListeners();
+            client.destroy();
             error ? reject(error) : resolve(out);
         }
     });

package/src/ping_socket.test.js

@@ -0,0 +1,58 @@
+const Promise = require('bluebird');
+const assert = require('assert');
+const fs_rmf = require('./fs_rmf');
+const net = require('net');
+const ping_socket = require('./ping_socket');
+const random_hex = require('./random_hex');
+
+const socket = '/tmp/ping_socket_test.sock';
+
+describe('ping_socket', function () {
+
+    afterEach(async function () {
+        await fs_rmf(socket);
+    });
+
+    it('should receive exact string from server', async function () {
+        const uid = random_hex();
+        const server = net.createServer(client => client.resume().end(uid));
+        try {
+            await new Promise(resolve => server.listen(socket, resolve));
+            const buf = await ping_socket(socket);
+            assert.strictEqual(buf.toString(), uid);
+        }
+        finally {
+            await server_close(server);
+        }
+    });
+
+    it('should throw Socket Timeout', async function () {
+        const clients = [];
+        const server = net.createServer(client => clients.push(client));
+        try {
+            await new Promise(resolve => server.listen(socket, resolve));
+            await assert.rejects(ping_socket(socket, 'PING', 100), {message: 'Socket Timeout'});
+        }
+        finally {
+            clients.forEach(v => v.resume().end());
+            await server_close(server);
+        }
+    });
+
+    it('should throw ENOENT', async function () {
+        await assert.rejects(ping_socket(socket), {
+            code: 'ENOENT',
+            syscall: 'connect',
+            address: socket,
+        });
+    });
+});
+
+async function server_close(server)
+{
+    return new Promise(function (resolve, reject) {
+        server.close(function (error) {
+            error ? reject(error) : resolve();
+        });
+    });
+}

package/src/range.js

@@ -0,0 +1,44 @@
+const na = Symbol();
+
+function range(begin, end = na, step = 1, limit = 1E6)
+{
+    if (end === na) {
+        if (begin < 0) {
+            return [];
+        }
+        return range_forward(0, begin, 1, limit);
+    }
+
+    if (begin < end) {
+        return range_forward(begin, end, step, limit);
+    }
+    return range_backward(begin, end, step, limit);
+}
+
+function range_forward(begin, end, step, limit)
+{
+    if (step < 0) {
+        return [];
+    }
+
+    const out = [];
+    for (let value = begin; value < end && out.length < limit; value += step) {
+        out.push(value);
+    }
+    return out;
+}
+
+function range_backward(begin, end, step, limit)
+{
+    if (step > 0) {
+        return [];
+    }
+
+    const out = [];
+    for (let value = begin; value > end && out.length < limit; value += step) {
+        out.push(value);
+    }
+    return out;
+}
+
+module.exports = range;

package/src/range.md

@@ -0,0 +1,15 @@
+Generates a numeric sequence.
+
+**Supported forms:**
+- `range(stop)` — from `0` up to `stop` (exclusive)
+- `range(start, stop)` — from `start` up to `stop` (exclusive)
+- `range(start, stop, step)` — with custom step
+
+**Rules:**
+- The `stop` value is **exclusive**
+- Positive `step` counts **up** while `value < stop`
+- Negative `step` counts **down** while `value > stop`
+- If `step` direction does not allow progress, the result is an empty array
+
+**Returns:**
+An array of numbers.

package/src/range.test.js

@@ -0,0 +1,41 @@
+const assert = require('assert');
+const range = require('./range');
+
+const cases = [
+    // 1-argument: (stop)
+    {args: [10], expected: [0,1,2,3,4,5,6,7,8,9]},
+    {args: [-10], expected: []}, // 💎 Consider non-standard semantics: range(-5) -> [0,-1,-2,-3,-4]
+
+    // 2-arguments: (start, stop)
+    {args: [3, 7], expected: [3,4,5,6]},
+    {args: [0, 0], expected: []},
+    {args: [5, 3], expected: []}, // positive direction, start > stop → empty
+
+    // 3-arguments: (start, stop, step)
+    {args: [3, 10, 2], expected: [3,5,7,9]},
+    {args: [3, 10, 3], expected: [3,6,9]},
+
+    // Negative step
+    {args: [10, 3, -2], expected: [10,8,6,4]},
+    {args: [10, 3, -3], expected: [10,7,4]},
+
+    // Negative step but no progression
+    {args: [3, 10, -1], expected: []}, // step direction does not match range
+
+    // Step = 1 edge
+    {args: [5, 5, 1], expected: []},
+    {args: [5, 6, 1], expected: [5]},
+
+    // Step = -1 edge
+    {args: [5, 5, -1], expected: []},
+    {args: [6, 5, -1], expected: [6]},
+];
+
+describe('range', function () {
+    cases.forEach(function (item, i) {
+        it(`range #${i+1}: ${JSON.stringify(item)}`, function () {
+            const actual = range(...item.args);
+            assert.deepStrictEqual(actual, item.expected);
+        })
+    });
+});

package/src/shell_spawn.js

@@ -1,6 +1,26 @@
+const ExitCodeError = require('./errors/ExitCodeError');
 const Promise = require('bluebird');
 const child_process = require('child_process');
 
+// 📕 Notes by ChatGPT:
+// If the child is killed by a signal (e.g. SIGKILL from outside),
+// Node’s exit event gives code = null, signal = 'SIGKILL'.
+// Your code treats this as success (resolve).
+// That might be fine for your use case, but be aware:
+//
+// If you want “child died by signal” to be treated as non-zero,
+// you’d need to change this check to something like:
+//
+// > function promise_exit(code, signal) {
+// >     out.off('error', promise_error);
+// >     if (code === 0) {
+// >         resolve(signal);
+// >     } else {
+// >         reject(new ExitCodeError(code || 128, `Process terminated with code ${code} and signal ${signal}`));
+// >     }
+// > }
+
+// ⚠️ Both .init and .promise are targets for race conditions!
 function shell_spawn(args, options)
 {
     let init, promise;
@@ -29,7 +49,12 @@ function shell_spawn(args, options)
             }
             function promise_exit(code, signal) {
                 out.off('error', promise_error);
-                code ? reject(new Error(`Process terminated with code ${code}`)) : resolve(signal);
+                if (code === 0) {
+                    resolve();
+                }
+                else {
+                    reject(new ExitCodeError(code || 128, `Process terminated with code ${code} and signal ${signal}`));
+                }
             }
         });
     };

package/src/shell_spawn.test.js

@@ -0,0 +1,23 @@
+const Promise = require('bluebird');
+const assert = require('assert');
+const pid_exists = require('./pid_exists');
+const shell_spawn = require('./shell_spawn');
+
+describe.skip('shell_spawn', function () {
+    describe('Happy Path', function () {
+        it('basic', async function () {
+            await shell_spawn(['true']).promise().timeout(100);
+        });
+        it('init + promise', async function () {
+            const proc = await shell_spawn(['true']).init();
+            await proc.promise().timeout(100);
+        });
+    });
+    it('🏎️ race condition: proc.promise is called after process was terminated', async function () {
+        const proc = shell_spawn(['true']);
+        assert(pid_exists(proc.pid));
+        await Promise.delay(10);
+        assert(!pid_exists(proc.pid));
+        await proc.promise().timeout(100);
+    });
+});

package/src/strtr.js

@@ -0,0 +1,15 @@
+// PHP’s strtr tries the longest possible key first when multiple keys overlap.
+// echo strtr("hello", ["he" => "X", "hell" => "Y"]);
+function strtr(subject, map)
+{
+    let out = subject;
+    Object.entries(map).sort(fcmp).forEach(function ([search, replace]) {
+        out = out.replaceAll(search, replace);
+    });
+    return out;
+    function fcmp(b, a) {
+        return a[0].length - b[0].length;
+    }
+}
+
+module.exports = strtr;