Blocking I/O in Async Systems — The Node.js Event Loop Killer

Node.js event loop (single thread):

┌─────────────────────────────────────────┐
│  Handle Request A (50ms async I/O)      │ ← Yields during I/O
│  Handle Request B (30ms async I/O)      │ ← Concurrent! ✅
│  Handle Request C (200ms SYNC CPU work) │ ← BLOCKS EVERYTHING 🚨
└─────────────────────────────────────────┘

During Request C's 200ms sync work:
- Request A cannot receive its I/O callback
- Request B cannot receive its I/O callback
- New requests cannot be accepted
- Health checks fail
- EVERYTHING waits

// ❌ Parsing a 10MB JSON response blocks the event loop
app.get('/large-data', async (req, res) => {
  const rawData = await fetchLargeApiResponse()  // Returns 10MB JSON string
  const parsed = JSON.parse(rawData)  // BLOCKS for ~200ms!
  res.json(parsed)
})

// ✅ FIX: Stream JSON parsing
import { parser } from 'stream-json'
import { streamArray } from 'stream-json/streamers/StreamArray'
import { pipeline } from 'stream/promises'

app.get('/large-data', async (req, res) => {
  const response = await fetch('https://api.example.com/huge')

  res.setHeader('Content-Type', 'application/json')
  res.write('[')

  let first = true
  const jsonStream = response.body.pipe(parser()).pipe(streamArray())

  jsonStream.on('data', ({ value }) => {
    if (!first) res.write(',')
    res.write(JSON.stringify(processItem(value)))
    first = false
  })

  jsonStream.on('end', () => {
    res.write(']')
    res.end()
  })
})

// ❌ Synchronous file reads block the event loop
app.get('/file', (req, res) => {
  const data = fs.readFileSync('large-file.txt')  // BLOCKS!
  res.send(data)
})

// ✅ Always use async file operations
app.get('/file', async (req, res) => {
  const data = await fs.promises.readFile('large-file.txt')  // Non-blocking
  res.send(data)
})

// ✅ Even better: stream it
app.get('/file', (req, res) => {
  const stream = fs.createReadStream('large-file.txt')
  stream.pipe(res)  // No blocking, no buffering entire file in memory
})

// ❌ CPU-intensive loop blocks for 500ms+
app.get('/process', async (req, res) => {
  const items = await db.fetchMillionItems()

  let result = 0
  for (const item of items) {
    result += expensiveComputation(item)  // 500ms total!
  }

  res.json({ result })
})

// ✅ FIX 1: Offload to Worker Thread
import { Worker } from 'worker_threads'

app.get('/process', async (req, res) => {
  const items = await db.fetchMillionItems()

  const result = await runInWorker('./computation-worker.js', { items })
  res.json({ result })
})

// ✅ FIX 2: Break into async chunks
app.get('/process', async (req, res) => {
  const items = await db.fetchMillionItems()

  let result = 0
  const CHUNK_SIZE = 1000

  for (let i = 0; i < items.length; i += CHUNK_SIZE) {
    const chunk = items.slice(i, i + CHUNK_SIZE)

    for (const item of chunk) {
      result += expensiveComputation(item)
    }

    // Yield to event loop after each chunk
    await new Promise(resolve => setImmediate(resolve))
  }

  res.json({ result })
})

// ❌ crypto.randomBytes SYNC version blocks
app.post('/token', (req, res) => {
  const token = crypto.randomBytes(32).toString('hex')  // BLOCKS!
  res.json({ token })
})

// ✅ Use async version
app.post('/token', (req, res) => {
  crypto.randomBytes(32, (err, buf) => {
    if (err) return res.status(500).json({ error: err.message })
    res.json({ token: buf.toString('hex') })
  })
})

// ✅ Or promisified
const { randomBytes } = crypto.promises  // Node.js 18+

app.post('/token', async (req, res) => {
  const token = (await randomBytes(32)).toString('hex')  // Non-blocking
  res.json({ token })
})

// ❌ Complex regex on large input — can run for seconds
app.post('/validate', (req, res) => {
  const { content } = req.body  // Could be 1MB of text

  // This regex could backtrack catastrophically
  const isValid = /^(a+)+$/.test(content)  // BLOCKS!
  res.json({ isValid })
})

// ✅ Limit input size BEFORE regex
app.post('/validate', (req, res) => {
  const { content } = req.body

  if (content.length > 10_000) {
    return res.status(400).json({ error: 'Input too large' })
  }

  const isValid = /safe-regex-here/.test(content)
  res.json({ isValid })
})

// Method 1: Basic lag measurement
function measureEventLoopLag(): Promise<number> {
  return new Promise(resolve => {
    const start = process.hrtime.bigint()
    setImmediate(() => {
      const lag = Number(process.hrtime.bigint() - start) / 1_000_000
      resolve(lag)
    })
  })
}

// Check every second
setInterval(async () => {
  const lag = await measureEventLoopLag()
  if (lag > 50) console.warn(`Event loop lag: ${lag.toFixed(1)}ms`)
}, 1000)

// Method 2: Built-in histogram (Node.js 16+)
import { monitorEventLoopDelay } from 'perf_hooks'
const h = monitorEventLoopDelay({ resolution: 20 })
h.enable()

setInterval(() => {
  console.log({
    mean: (h.mean / 1e6).toFixed(2) + 'ms',
    p99: (h.percentile(99) / 1e6).toFixed(2) + 'ms',
    max: (h.max / 1e6).toFixed(2) + 'ms',
  })
}, 10_000)

# Use clinic.js to auto-detect blocking operations
npm install -g clinic

# Generate a flame graph showing blocking code
clinic flame -- node app.js

# Or use the doctor to auto-diagnose
clinic doctor -- node app.js

# Run with load
autocannon -c 100 -d 30 http://localhost:3000/api

import { Worker, isMainThread, parentPort, workerData } from 'worker_threads'
import os from 'os'

if (!isMainThread) {
  // This code runs in worker threads
  const { task, data } = workerData
  const result = performTask(task, data)
  parentPort!.postMessage(result)
}

// Main thread pool
export class CPUWorkerPool {
  private workers: Worker[] = []
  private queue: Array<{ resolve: Function, reject: Function, data: any }> = []
  private available: Worker[] = []

  constructor(workerFile: string, size = os.cpus().length) {
    for (let i = 0; i < size; i++) {
      const worker = new Worker(workerFile)
      worker.on('message', (result) => {
        const task = this.queue.shift()
        if (task) {
          worker.postMessage(task.data)
          task.resolve(result)
        } else {
          this.available.push(worker)
        }
      })
      this.available.push(worker)
    }
  }

  execute(data: any): Promise<any> {
    return new Promise((resolve, reject) => {
      const worker = this.available.pop()
      if (worker) {
        worker.once('message', resolve)
        worker.once('error', reject)
        worker.postMessage(data)
      } else {
        this.queue.push({ resolve, reject, data })
      }
    })
  }
}