• Defer engine.io socket flush to microtask for packet coalescing
• Reduces tail latency at mid-load (300-350 concurrent authors)
• Batches multiple sendPacket calls into single transport.send
• Gated by settings.engineFlushDefer (default false)

Engine.io flush deferral installer module

• New module implementing engine.io Socket.sendPacket re-implementation
• Schedules flush via queueMicrotask instead of synchronous call
• Uses Symbol to track scheduled state and prevent duplicate microtasks
• Includes comprehensive documentation of the deferral mechanism

src/node/utils/EngineFlushDeferral.ts

Conditional engine.io flush deferral installation

• Conditionally loads and installs flush deferral before Server creation
• Gated by settings.engineFlushDefer configuration flag
• Applied before socket.io Server instantiation for prototype patching

src/node/hooks/express/socketio.ts

Add engineFlushDefer configuration setting

• Adds engineFlushDefer boolean setting to SettingsType
• Defaults to false for backward compatibility
• Includes detailed documentation of the feature and its benefits
• Positioned alongside other scaling-related settings

src/node/utils/Settings.ts

Description

A new user-visible configuration setting (engineFlushDefer) is introduced and used to change
runtime behavior, but the PR does not include corresponding documentation updates for operators.
This makes the feature flag discoverability and correct usage unclear, increasing operational risk
and support burden.

Code

src/node/utils/Settings.ts[R662-674]

+ /**
+ * Defer engine.io socket flush onto the next microtask so multiple
+ * sendPacket() calls within the same task accumulate in the writeBuffer
+ * before drain. Pairs with engine.io's existing transport.send([packets])
+ * fast path so a batched send produces fewer WebSocket frames.
+ *
+ * Adds no meaningful wall-clock latency — microtasks drain before any
+ * subsequent macrotask. Backward-compatible at the wire level; existing
+ * clients receive identical packet bytes.
+ *
+ * Default false. Enable only when scoring under the scaling dive.
+ */
+ engineFlushDefer: false,

Evidence

The checklist requires documentation updates for user-visible/interface changes. The PR introduces a
new settings key (engineFlushDefer) with operator-facing semantics and uses it to conditionally
install an engine.io patch, but no documentation update is included alongside this new configuration
surface.

src/node/utils/Settings.ts[662-674]
src/node/hooks/express/socketio.ts[71-78]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution
## Issue description
The PR adds a new user-visible config flag `engineFlushDefer` (default `false`) and uses it to conditionally patch engine.io behavior, but there is no accompanying documentation update for operators.
## Issue Context
Per compliance requirements, user-visible/config interface changes must be documented in the same change set (typically in `doc/` and/or the operator-facing settings template).
## Fix Focus Areas
- settings.json.template[709-740]
- src/node/utils/Settings.ts[662-674]
- src/node/hooks/express/socketio.ts[71-78]

i Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

installEngineFlushDeferral() sets installed = true before requiring and validating engine.io, so a
single early failure (require error or unexpected Socket shape) prevents all future installation
attempts in the same process. This can leave settings.engineFlushDefer enabled but ineffective,
with only the first warning logged.

Code

src/node/utils/EngineFlushDeferral.ts[R48-63]

+export const installEngineFlushDeferral = (): void => {
+ if (installed) return;
+ installed = true;
+
+ let SocketProto: {sendPacket: (...a: unknown[]) => unknown};
+ try {
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
+ SocketProto = require('engine.io/build/socket').Socket.prototype;
+ } catch (err: any) {
+ logger.warn(`Unable to install engine.io flush deferral (module not found): ${err && err.message || err}`);
+ return;
+ }
+ if (typeof SocketProto.sendPacket !== 'function') {
+ logger.warn('engine.io Socket shape unexpected; skipping flush deferral patch');
+ return;
+ }

Evidence

The installer marks itself installed before the engine.io require/shape checks and then returns
early on failure, leaving installed true and preventing subsequent attempts.

src/node/utils/EngineFlushDeferral.ts[48-63]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution
## Issue description
`installEngineFlushDeferral()` sets the module-level `installed` flag before it has successfully loaded and validated engine.io’s Socket prototype. If loading/validation fails, the function returns but `installed` remains true, preventing any retries in the same process.
## Issue Context
The installer is called from `expressCreateServer()` when `settings.engineFlushDefer === true`. Even though the setting is opt-in, a one-time failure (bad module path, temporary resolution issue, or unexpected module shape) will permanently disable the optimization until process restart.
## Fix Focus Areas
- src/node/utils/EngineFlushDeferral.ts[48-63]
## Suggested fix
- Move `installed = true` to after successful patching of `SocketProto.sendPacket`.
- Alternatively, keep two flags: `attempted` (to rate-limit logs) and `installed` (set only on success), or explicitly reset `installed = false` on early-return failure paths.

i Copy this prompt and use it to remediate the issue with your preferred AI generation tools