Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Directory guard: an `async` Socket.IO handler may not let an `await` reject.
*
* ## The bug class
*
* socket.on('voice:call:detach', async () => {
* emitCallState(await detachHost(socket)); // ← rejects on a failed teardown
* });
*
* Socket.IO hands the promise a listener returns to nobody, and a handler runs
* outside the Express request lifecycle, so there is no `next(err)` for a throw
* to bubble to. A rejection therefore surfaces as an unhandled rejection, which
* Node >= 15 treats as fatal — the server process dies, taking every agent run,
* PTY session and media job with it. `voice:call:detach` shipped exactly that
* (#5661), and it held across the other handlers here by review alone.
*
* `server/sockets/` is the largest population of "outside the request lifecycle"
* async code in the tree. This is the same rule and the same shape as
* `server/timerCallbackConventions.test.js` — the two share their lexer,
* callback parser and await checker via `server/lib/sourceScan.js`, so they
* cannot drift on what "owns its rejection" means.
*
* ## Scope
*
* Every `<emitter>.on('<event>', …)` in this directory, not just `socket.on` —
* `ns.on('connection', …)` and the `pm2 logs` child's `.on('data', …)` in
* `logs.js` sit in the identical blast radius, and scoping to the literal
* `socket.` would let the next one in unnoticed. `server/routes/` is out of
* scope (the centralized error middleware owns those), and so are timer and
* child-process callbacks (their own guard files).
*
* ## Allowlist
*
* None, on purpose. If you are reading this because the scan just failed, wrap
* the handler body in `try { … } catch (err) { console.error(…); }` or append
* `.catch(…)` to the awaited expression.
*/
import { describe, it, expect } from 'vitest';
import { readdirSync, readFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { blankLiterals, matchBracket, parseCallbackAt, unguardedAwaits } from '../lib/sourceScan.js';
const HERE = dirname(fileURLToPath(import.meta.url));
// `.once` as well as `.on`: a one-shot listener returns its promise to nobody
// exactly the same way, so leaving it out would be a silent hole rather than a
// narrower rule.
const REGISTRATION = /(?<![\w$.])[\w$]+(?:\.[\w$]+)*\.(?:on|once)\s*\(/g;
/** Index of the `,` separating a call's first two arguments, or -1. */
function firstArgumentEnd(blanked, from, limit) {
let i = from;
while (i < limit) {
const c = blanked[i];
if (c === '(' || c === '[' || c === '{') {
i = matchBracket(blanked, i);
if (i === -1) return -1;
continue;
}
if (c === ',') return i;
i += 1;
}
return -1;
}
/**
* Every `<emitter>.on('<event>', <callback>)` registration in `src`, with the
* callback body captured whole by a bracket-balanced walk.
*
* Bracket-balanced rather than a fixed character window: a window reads the NEXT
* statement and attributes it to this handler, so an unguarded handler followed
* by a guarded one would pass on its neighbour's `try`.
*
* The event name is read out of the ORIGINAL source at the offsets the blanked
* copy reports — `blankLiterals` preserves length, so every index still maps
* back. A registration with a computed event name is skipped rather than
* reported under a wrong name.
* @param {string} src
* @returns {{event: string, isAsync: boolean, body: string, line: number}[]}
*/
export function socketHandlers(src) {
const blanked = blankLiterals(src);
const handlers = [];
for (const match of blanked.matchAll(REGISTRATION)) {
const callOpen = match.index + match[0].length - 1;
const callEnd = matchBracket(blanked, callOpen);
if (callEnd === -1) continue;
const comma = firstArgumentEnd(blanked, callOpen + 1, callEnd - 1);
if (comma === -1) continue;
const event = /^(['"])((?:[^'"\\]|\\.)*)\1$/.exec(src.slice(callOpen + 1, comma).trim())?.[2];
if (event === undefined) continue;
const callback = parseCallbackAt(blanked, comma + 1, callEnd - 1);
if (!callback) continue;
handlers.push({
event,
isAsync: callback.isAsync,
body: callback.text,
line: blanked.slice(0, match.index).split('\n').length,
});
}
return handlers;
}
/** Every unguarded await in every async event handler in one file's source. */
export function findUnguardedHandlerAwaits(src) {
return socketHandlers(src)
.filter((handler) => handler.isAsync)
.flatMap((handler) => unguardedAwaits(handler.body)
.map((chain) => `line ${handler.line} '${handler.event}': ${chain}`));
}
// `.mjs`/`.cjs` alongside `.js`: nothing under this directory ships those
// extensions today, but a `.js`-only filter would silently drop one that did
// (#7953) — the recognizer test below proves the filter itself, not just the
// current directory contents, actually accepts them.
const SOCKET_FILE_RE = /\.(?:js|mjs|cjs)$/;
const socketFiles = readdirSync(HERE)
.filter((f) => SOCKET_FILE_RE.test(f) && !f.includes('.test.'))
.sort();
describe('async socket handlers own their rejections (#5661)', () => {
it('finds the handlers it is meant to guard', () => {
// Without this, a refactor of the registration shape would leave the scan
// below iterating nothing and passing green forever.
expect(socketFiles.length).toBeGreaterThan(3);
const handlers = socketFiles.flatMap((f) => socketHandlers(readFileSync(join(HERE, f), 'utf8')));
expect(handlers.filter((h) => h.isAsync).length).toBeGreaterThan(10);
// Sync handlers must survive extraction too, or `isAsync` is doing nothing.
expect(handlers.filter((h) => !h.isAsync).length).toBeGreaterThan(0);
expect(handlers.map((h) => h.event)).toEqual(expect.arrayContaining([
'voice:call:detach', 'logs:subscribe', 'shell:start', 'app:update',
]));
});
// Nothing under this directory ships `.mjs`/`.cjs` today, so the scan above
// cannot prove the filter would catch one that did — assert the filter
// itself, not just this directory's current contents (#7953).
it('would scan a .mjs or .cjs handler file, not just .js', () => {
expect(SOCKET_FILE_RE.test('example.mjs')).toBe(true);
expect(SOCKET_FILE_RE.test('example.cjs')).toBe(true);
expect(SOCKET_FILE_RE.test('example.test.mjs')).toBe(true);
});
it('has no unguarded await in any async socket handler', () => {
const violations = socketFiles.flatMap((file) => (
findUnguardedHandlerAwaits(readFileSync(join(HERE, file), 'utf8'))
.map((hit) => `server/sockets/${file} ${hit}`)
));
expect(
violations,
'These awaits sit in an `async` Socket.IO handler with nothing to own a rejection. '
+ 'A handler runs outside the request lifecycle and nobody holds the promise it returns, '
+ 'so a rejected await becomes an unhandled rejection — fatal on Node >= 15, which is how '
+ 'voice:call:detach could have killed the server on a failed teardown (#5661).\n'
+ 'Fix: wrap the body in `try { … } catch (err) { console.error(`❌ …: ${err.message}`); }`, '
+ 'or append `.catch(…)` to the awaited expression.\n'
+ `Offenders:\n ${violations.join('\n ')}`,
).toEqual([]);
});
});
// Guards the guard: if the recognizer stops seeing the broken shape, the scan
// above goes green and the bug class walks straight back in.
describe('the socket-handler recognizer', () => {
it('flags a bare await in an async handler', () => {
expect(findUnguardedHandlerAwaits("socket.on('x', async () => { await boom(); });"))
.toEqual(["line 1 'x': await boom()"]);
// An early return before the await does not make it safe — the fableLoomHosted
// handlers all open with a role check.
expect(findUnguardedHandlerAwaits(`
socket.on('hosted:mic:start', async () => {
if (socket.hostedRole !== 'audience') return;
await startListening(sessionId);
});
`)).toEqual(["line 2 'hosted:mic:start': await startListening(sessionId)"]);
});
it('does not accept a try that only exists in a comment', () => {
// The comment blanking is what stops a rule being *described* in prose from
// satisfying the scan. Drop it and this fixture reads as guarded.
expect(findUnguardedHandlerAwaits(`
socket.on('x', async () => {
// try { … } catch — describing the rule, not applying it
await boom();
});
`)).toEqual(["line 2 'x': await boom()"]);
});
it('accepts the two guarded shapes', () => {
// A default-valued parameter puts an object literal before the body ever
// opens — half of voice.js is spelled this way.
expect(findUnguardedHandlerAwaits(`
socket.on('voice:text', async (payload = {}) => {
try {
await respond(payload);
} catch (err) {
console.error(\`❌ voice:text failed: \${err.message}\`);
}
});
`)).toEqual([]);
// Chained across lines — the shape logs.js uses on its pm2-home lookups. A
// scan that ended the statement at the newline would never see the .catch.
expect(findUnguardedHandlerAwaits(`
socket.on('logs:subscribe', async ({ appId }) => {
const home = await getAppById(appId)
.then((app) => app?.pm2Home || null)
.catch((err) => { console.error(\`❌ \${err.message}\`); return null; });
stream(home);
});
`)).toEqual([]);
});
it('captures each handler body whole, not a window into the next one', () => {
const found = findUnguardedHandlerAwaits(`
socket.on('unguarded', async () => {
await boom();
});
socket.on('guarded', async () => {
try { await fine(); } catch (err) { console.error(err.message); }
});
`);
// The offender must not borrow its neighbour's \`try\`, and the guarded
// handler must not be dragged down by its neighbour's bare await.
expect(found).toEqual(["line 2 'unguarded': await boom()"]);
});
it('leaves synchronous handlers and non-function arguments alone', () => {
expect(findUnguardedHandlerAwaits("socket.on('sync', (chunk) => { buffer.push(chunk); });")).toEqual([]);
expect(socketHandlers("emitter.on('forwarded', handlerRef);")).toEqual([]);
// A computed event name is skipped rather than reported under a wrong name.
expect(socketHandlers('socket.on(EVENT, async () => { await boom(); });')).toEqual([]);
});
it('reads a non-socket emitter, and a one-shot listener, in this directory too', () => {
// `ns.on('connection', …)` and the pm2-logs child's `.on('data', …)` are in
// the same blast radius; scoping the scan to the literal `socket.` would let
// the next one in unnoticed. `.once` returns its promise to nobody the same
// way `.on` does.
expect(findUnguardedHandlerAwaits("logProcess.stdout.on('data', async (chunk) => { await flush(chunk); });"))
.toEqual(["line 1 'data': await flush(chunk)"]);
expect(findUnguardedHandlerAwaits("socket.once('shell:attach', async () => { await attach(); });"))
.toEqual(["line 1 'shell:attach': await attach()"]);
});
it('sees a parenthesized concise body rather than stepping over it', () => {
// `parseCallbackAt` used to skip a second `(` after the `=>`, reading it as
// a parameter list and jumping the whole body — so every await inside was
// invisible and the handler passed green.
expect(findUnguardedHandlerAwaits("socket.on('x', async () => (await boom()));"))
.toEqual(["line 1 'x': await boom()"]);
});
it('reports the voice call handlers as guarded', () => {
// The site that motivated the rule — pinned so a revert is caught here and
// not only by the directory-wide scan.
const src = readFileSync(join(HERE, 'voice.js'), 'utf8');
expect(src).toContain("socket.on('voice:call:detach'");
expect(findUnguardedHandlerAwaits(src)).toEqual([]);
});
});