Code Story: How We Fixed a Race Condition in a Node.js 22 App Using the New Async Hooks API

// Buggy payment processing service demonstrating the race condition
// Node.js 22.0.0+ (pre-fix)
const http = require('http');
const { randomUUID } = require('crypto');
const { AsyncLocalStorage } = require('async_hooks');

// Incomplete context store with race condition
const requestContext = new AsyncLocalStorage();

// Simulated payment gateway client
class PaymentGateway {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.timeout = 5000;
  }

  async processPayment(amount, currency, cardToken) {
    // Simulate variable latency (100-500ms)
    const latency = Math.floor(Math.random() * 400) + 100;
    await new Promise(resolve => setTimeout(resolve, latency));

    // Bug: Context can be overwritten by concurrent requests here
    const ctx = requestContext.getStore();
    if (!ctx) {
      throw new Error('Missing request context for payment');
    }

    // Simulated gateway response
    const success = Math.random() > 0.05; // 95% success rate
    if (!success) {
      throw new Error(`Payment failed for request ${ctx.requestId}`);
    }

    return {
      transactionId: randomUUID(),
      amount,
      currency,
      requestId: ctx.requestId,
      userId: ctx.userId,
      timestamp: new Date().toISOString()
    };
  }
}

const paymentGateway = new PaymentGateway('sk_live_123456');

const server = http.createServer(async (req, res) => {
  // Only handle POST /process-payment
  if (req.method !== 'POST' || req.url !== '/process-payment') {
    res.writeHead(404, { 'Content-Type': 'application/json' });
    return res.end(JSON.stringify({ error: 'Not found' }));
  }

  let body = '';
  req.on('data', chunk => { body += chunk.toString(); });
  req.on('end', async () => {
    try {
      const { amount, currency, cardToken, userId } = JSON.parse(body);
      const requestId = randomUUID();

      // Set context for this request
      const ctx = { requestId, userId, startTime: Date.now() };
      const result = await requestContext.run(ctx, async () => {
        // Process payment inside context
        return paymentGateway.processPayment(amount, currency, cardToken);
      });

      res.writeHead(200, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify(result));
    } catch (err) {
      console.error(`Request failed: ${err.message}`);
      res.writeHead(500, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ error: 'Payment processing failed', details: err.message }));
    }
  });

  req.on('error', (err) => {
    console.error('Request stream error:', err);
    res.writeHead(500);
    res.end();
  });
});

// Start server
const PORT = process.env.PORT || 3000;
server.listen(PORT, () => {
  console.log(`Buggy payment server running on port ${PORT}`);
});

// Simulated load test (run with autocannon -c 100 -d 30 http://localhost:3000/process-payment)

// Fixed payment processing service using Node.js 22 stable Async Hooks API
// Node.js 22.3.0+ (no experimental flags required)
const http = require('http');
const { randomUUID } = require('crypto');
const { createHook, executionAsyncId } = require('async_hooks');

// Context store mapping async resource IDs to request contexts
const asyncContextMap = new Map();
// Track root async resources (request handlers) to clean up context
const rootAsyncIds = new Set();

// Create stable async hook to propagate context
const asyncHook = createHook({
  init(asyncId, type, triggerAsyncId) {
    // Propagate context from trigger resource to new async resource
    if (asyncContextMap.has(triggerAsyncId)) {
      asyncContextMap.set(asyncId, asyncContextMap.get(triggerAsyncId));
    }
    // Mark HTTP request handlers as root contexts
    if (type === 'HTTPREQUEST') {
      rootAsyncIds.add(asyncId);
    }
  },
  destroy(asyncId) {
    // Clean up context when async resource is destroyed
    asyncContextMap.delete(asyncId);
    rootAsyncIds.delete(asyncId);
  }
});

// Start the async hook (stable in Node 22, no --experimental flag needed)
asyncHook.enable();

// Helper to get current request context
function getCurrentContext() {
  const asyncId = executionAsyncId();
  return asyncContextMap.get(asyncId) || null;
}

// Simulated payment gateway client (updated with context-aware logging)
class PaymentGateway {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.timeout = 5000;
  }

  async processPayment(amount, currency, cardToken) {
    const ctx = getCurrentContext();
    if (!ctx) {
      throw new Error('No request context found for payment processing');
    }

    // Simulate variable latency (100-500ms)
    const latency = Math.floor(Math.random() * 400) + 100;
    await new Promise(resolve => setTimeout(resolve, latency));

    // Simulated gateway response with context-aware logging
    const success = Math.random() > 0.05; // 95% success rate
    if (!success) {
      console.error(`[Request ${ctx.requestId}] Payment failed for user ${ctx.userId}`);
      throw new Error(`Payment failed for request ${ctx.requestId}`);
    }

    console.log(`[Request ${ctx.requestId}] Payment succeeded for user ${ctx.userId}`);
    return {
      transactionId: randomUUID(),
      amount,
      currency,
      requestId: ctx.requestId,
      userId: ctx.userId,
      timestamp: new Date().toISOString()
    };
  }
}

const paymentGateway = new PaymentGateway('sk_live_123456');

const server = http.createServer((req, res) => {
  // Only handle POST /process-payment
  if (req.method !== 'POST' || req.url !== '/process-payment') {
    res.writeHead(404, { 'Content-Type': 'application/json' });
    return res.end(JSON.stringify({ error: 'Not found' }));
  }

  const requestId = randomUUID();
  const startTime = Date.now();

  // Collect request body
  let body = '';
  req.on('data', chunk => { body += chunk.toString(); });

  req.on('end', () => {
    try {
      const { amount, currency, cardToken, userId } = JSON.parse(body);
      // Set context for the current async chain (HTTP request handler is root)
      const currentAsyncId = executionAsyncId();
      asyncContextMap.set(currentAsyncId, {
        requestId,
        userId,
        startTime,
        ip: req.socket.remoteAddress
      });

      // Process payment with context propagation
      paymentGateway.processPayment(amount, currency, cardToken)
        .then(result => {
          const duration = Date.now() - startTime;
          console.log(`[Request ${requestId}] Completed in ${duration}ms`);
          res.writeHead(200, { 'Content-Type': 'application/json' });
          res.end(JSON.stringify(result));
        })
        .catch(err => {
          console.error(`[Request ${requestId}] Failed: ${err.message}`);
          res.writeHead(500, { 'Content-Type': 'application/json' });
          res.end(JSON.stringify({ error: 'Payment processing failed', details: err.message }));
        });
    } catch (err) {
      console.error(`[Request ${requestId}] Invalid request body: ${err.message}`);
      res.writeHead(400, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ error: 'Invalid request body' }));
    }
  });

  req.on('error', (err) => {
    console.error(`[Request ${requestId || 'unknown'}] Request stream error:`, err);
    res.writeHead(500);
    res.end();
  });

  res.on('error', (err) => {
    console.error(`[Request ${requestId || 'unknown'}] Response error:`, err);
  });
});

// Start server
const PORT = process.env.PORT || 3000;
server.listen(PORT, () => {
  console.log(`Fixed payment server running on port ${PORT} using Node.js ${process.version}`);
});

// Cleanup on process exit
process.on('exit', () => {
  asyncHook.disable();
  asyncContextMap.clear();
  rootAsyncIds.clear();
});

// Benchmark script comparing buggy vs fixed payment service performance
// Run with: node benchmark.js (requires autocannon: npm i -g autocannon)
const { spawn } = require('child_process');
const autocannon = require('autocannon');
const { randomUUID } = require('crypto');

// Test configuration
const BENCHMARK_DURATION = 30; // seconds
const CONCURRENT_CONNECTIONS = 100;
const BUGGY_SERVER_PORT = 3001;
const FIXED_SERVER_PORT = 3002;
const PAYLOAD = JSON.stringify({
  amount: 99.99,
  currency: 'USD',
  cardToken: 'tok_visa',
  userId: randomUUID()
});

// Helper to start a server process
function startServer(scriptPath, port) {
  return new Promise((resolve, reject) => {
    const server = spawn('node', [scriptPath, `--port=${port}`], {
      env: { ...process.env, PORT: port },
      stdio: 'pipe'
    });

    server.stdout.on('data', (data) => {
      if (data.toString().includes('running on port')) {
        console.log(`Started server ${scriptPath} on port ${port}`);
        resolve(server);
      }
    });

    server.stderr.on('data', (data) => {
      console.error(`Server ${scriptPath} error: ${data}`);
    });

    server.on('error', reject);

    // Timeout if server doesn't start in 5 seconds
    setTimeout(() => reject(new Error(`Server ${scriptPath} failed to start`)), 5000);
  });
}

// Helper to run autocannon benchmark
async function runBenchmark(url, label) {
  console.log(`Running benchmark for ${label}...`);
  const result = await autocannon({
    url,
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: PAYLOAD,
    connections: CONCURRENT_CONNECTIONS,
    duration: BENCHMARK_DURATION,
    pipelining: 1,
    debug: false
  });

  return {
    label,
    requestsPerSecond: result.requests.mean,
    latencyP50: result.latency.p50,
    latencyP99: result.latency.p99,
    errors: result.errors,
    timeouts: result.timeouts,
    non2xx: result.non2xx
  };
}

// Main benchmark function
async function main() {
  let buggyServer, fixedServer;
  try {
    // Start both servers
    buggyServer = await startServer('./buggy-payment-server.js', BUGGY_SERVER_PORT);
    fixedServer = await startServer('./fixed-payment-server.js', FIXED_SERVER_PORT);

    // Run benchmarks
    const buggyResults = await runBenchmark(
      `http://localhost:${BUGGY_SERVER_PORT}/process-payment`,
      'Buggy Server (ALS only)'
    );
    const fixedResults = await runBenchmark(
      `http://localhost:${FIXED_SERVER_PORT}/process-payment`,
      'Fixed Server (Async Hooks)'
    );

    // Print comparison table
    console.log('\n=== Benchmark Results ===');
    console.log('| Metric                | Buggy Server | Fixed Server | Delta   |');
    console.log('|-----------------------|--------------|--------------|---------|');
    console.log(`| Requests/sec          | ${buggyResults.requestsPerSecond.toFixed(2).padStart(12)} | ${fixedResults.requestsPerSecond.toFixed(2).padStart(12)} | ${(fixedResults.requestsPerSecond - buggyResults.requestsPerSecond).toFixed(2).padStart(7)} |`);
    console.log(`| Latency p50 (ms)      | ${buggyResults.latencyP50.toFixed(2).padStart(12)} | ${fixedResults.latencyP50.toFixed(2).padStart(12)} | ${(fixedResults.latencyP50 - buggyResults.latencyP50).toFixed(2).padStart(7)} |`);
    console.log(`| Latency p99 (ms)      | ${buggyResults.latencyP99.toFixed(2).padStart(12)} | ${fixedResults.latencyP99.toFixed(2).padStart(12)} | ${(fixedResults.latencyP99 - buggyResults.latencyP99).toFixed(2).padStart(7)} |`);
    console.log(`| Errors                | ${buggyResults.errors.toString().padStart(12)} | ${fixedResults.errors.toString().padStart(12)} | ${(fixedResults.errors - buggyResults.errors).toString().padStart(7)} |`);
    console.log(`| Non-2xx Responses     | ${buggyResults.non2xx.toString().padStart(12)} | ${fixedResults.non2xx.toString().padStart(12)} | ${(fixedResults.non2xx - buggyResults.non2xx).toString().padStart(7)} |`);

    // Save results to JSON
    const fs = require('fs');
    fs.writeFileSync('./benchmark-results.json', JSON.stringify({
      buggy: buggyResults,
      fixed: fixedResults,
      timestamp: new Date().toISOString()
    }, null, 2));
    console.log('\nResults saved to benchmark-results.json');

  } catch (err) {
    console.error('Benchmark failed:', err);
    process.exit(1);
  } finally {
    // Cleanup servers
    if (buggyServer) buggyServer.kill();
    if (fixedServer) fixedServer.kill();
    console.log('Servers stopped');
  }
}

// Run benchmark if this is the main module
if (require.main === module) {
  main();
}

// Snippet: Cleanup context on async resource destroy
const asyncHook = createHook({
  destroy(asyncId) {
    // Critical: Clean up context to prevent memory leaks
    asyncContextMap.delete(asyncId);
    rootAsyncIds.delete(asyncId);
    // Log cleanup for debug builds
    if (process.env.DEBUG === 'async-hooks') {
      console.log(`Destroyed context for asyncId ${asyncId}`);
    }
  }
});

// Snippet: Run autocannon benchmark in CI
const autocannon = require('autocannon');
const result = await autocannon({
  url: 'http://localhost:3000/process-payment',
  connections: 100,
  duration: 30,
  method: 'POST',
  body: JSON.stringify({ amount: 99.99, currency: 'USD' })
});
if (result.requests.mean < 1200) {
  throw new Error('Throughput dropped below SLA threshold');
}

// Snippet: Debug third-party async resources
const asyncHook = createHook({
  init(asyncId, type, triggerAsyncId, resource) {
    if (process.env.DEBUG === 'async-hooks') {
      console.log(`Init asyncId: ${asyncId}, type: ${type}, trigger: ${triggerAsyncId}`);
      if (type === 'TIMEOUT' || type === 'TCPWRAP') {
        console.log('Resource stack:', resource.asyncResource?.stack);
      }
    }
  }
});