Error handling — async error, central handler আর নিরাপদ বার্তা

১ · দুই রকম ভুল: প্রত্যাশিত সমস্যা আর কোডের বাগ

রেস্তোরাঁয় আপনি বিরিয়ানি চাইলেন। ওয়েটার বললেন, “আজ শেষ হয়ে গেছে, তেহারি আছে।” এটি স্বাভাবিক ঘটনা। রেস্তোরাঁ জানত এমন হতে পারে, উত্তরও তৈরি ছিল। এবার ভাবুন রান্নাঘরে গ্যাসের লাইন ফেটে গেছে। ওয়েটার তখন খদ্দেরকে পাইপের নকশা বোঝাবেন না, হাসিমুখে অর্ডারও নিতে থাকবেন না। তিনি বলবেন “আজ বন্ধ”, আর ভেতরে মিস্ত্রি ডাকা হবে।

Backend-এও ঠিক এই দুই ভাগ। পর্ব ২৬-এ আপনি middleware-এর সারি দেখেছেন। পর্ব ২৭-এ দেখেছেন ইনপুট যাচাই। এই পর্বে দেখব সারির কোথাও গোলমাল হলে কী হয়।

এই ভাগ কেন দরকার? একই catch দিয়ে সব ধরলে দুটি ভুল হয়। Bug-কে “পণ্য পাওয়া যায়নি” বলে চালিয়ে দিলে কেউ টের পান না যে কোড ভাঙা। আবার ভুল ইনপুটকে 500 বললে alert বাজে অকারণে, আর ব্যবহারকারী জানেন না কী বদলাবেন।

JavaScript-এর try/catch, throw আর exception কীভাবে ছড়ায়, তা JavaScript কোর্সের error handling পর্বে আছে। এখানে সেগুলো ধরে নিয়ে server-এর দিকে তাকাব।

২ · Error কীভাবে ছড়ায়: sync, async আর Express ৪ বনাম ৫

একটি synchronous handler-এ throw করলে Express সেটি ধরে, কারণ handler ডাকার লাইনটি তার নিজের try/catch-এর ভেতরে। Async হলে গল্প বদলায়। async ফাংশন throw করলে কিছুই ওপরে ওঠে না। সে শুধু একটি rejected promise ফেরত দেয়। সেই promise কেউ দেখলে ভালো, না দেখলে সমস্যা।

নিচের block-এ Express নেই, কারণ Wandbox-এ npm package চলে না। এটি node:http দিয়ে বানানো ছোট মডেল। একই handler দুভাবে ডাকা হয়েছে। চালিয়ে দেখুন।

const http = require('node:http');
// Express 4-এর মতো: handler-এর ফেরত দেওয়া promise কেউ দেখে না
const plain = (fn) => (req, res) => { fn(req, res); };
// Express 5-এর মতো: promise ধরা হয়, ভুল যায় একটি কেন্দ্রীয় জায়গায়
const wrap = (fn) => (req, res) =>
  Promise.resolve().then(() => fn(req, res)).catch((err) => {
    console.log('  central handler:', err.message);
    res.statusCode = 500;
    res.end('{"error":"internal"}');
  });
async function getProduct() { await null; throw new Error('db down'); }
// এই hook না থাকলে প্রথম চেষ্টাতেই পুরো process মরে যেত
process.on('unhandledRejection', (r) => console.log('  unhandledRejection:', r.message));
const get = (url) => new Promise((resolve, reject) => {
  http.get(url, { signal: AbortSignal.timeout(200) }, (res) => {
    let body = '';
    res.on('data', (c) => { body += c; });
    res.on('end', () => resolve(`${res.statusCode} ${body}`));
  }).on('error', reject);
});
async function tryIt(name, handler) {
  const server = http.createServer(handler);
  await new Promise((r) => server.listen(0, r));
  console.log(name);
  try {
    console.log('  client got:', await get(`http://127.0.0.1:${server.address().port}/`));
  } catch (e) {
    console.log('  client gave up:', e.name);
  }
  server.closeAllConnections();
  server.close();
}
tryIt('without wrapper', plain(getProduct))
  .then(() => tryIt('with wrapper', wrap(getProduct)));

without wrapper
  unhandledRejection: db down
  client gave up: AbortError
with wrapper
  central handler: db down
  client got: 500 {"error":"internal"}

একই ফাইল, দুই Express: সত্যিকারের run

এবার আসল জিনিস। একটি ফাইলে ছয় রকম route আর চার argument-এর একটি error handler লেখা হলো। সেটি Express 4.22.3 আর 5.3.0 দিয়ে চালানো হলো, Node 24.15.0-তে। Route-গুলোর মূল অংশ:

app.get('/sync', (req, res) => { throw new Error('sync boom'); });

app.get('/async', async (req, res) => {
  await null;
  throw new Error('async boom');
});

app.get('/reject-empty', () => Promise.reject());

app.get('/floating', (req, res) => {
  Promise.reject(new Error('floating boom')); // return নেই
});

app.get('/timer', (req, res) => {
  setTimeout(() => { throw new Error('timer boom'); }, 5);
});

app.get('/callback', (req, res, next) => {
  fs.readFile('no-such-file.txt', (err, data) => {
    if (err) return next(err);
    res.send(data);
  });
});

app.use((err, req, res, next) => {
  console.error('error handler got:', err.message);
  res.status(500).json({ error: 'internal' });
});

Express ৪-এ /async-এর সত্যিকারের run (path বদলে ~/bazarghar করা, লেখা ছোট করা):

$ curl -i http://127.0.0.1:47281/async
  [server] ~/bazarghar/compare.cjs:17
  throw new Error('async boom');
        ^
Error: async boom
    at ~/bazarghar/compare.cjs:17:9
    at process.processTicksAndRejections (node:internal/process/task_queues:104:5)
Node.js v24.15.0
curl: (56) Recv failure: Connection was reset
  [server exited code=1 signal=null]

আর Express ৫-এ একই ফাইল, একই অনুরোধ:

$ curl -i http://127.0.0.1:47283/async
  [server] error handler got: async boom
HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8

{"error":"internal"}

একটি অনুরোধ দিয়ে পুরো server নামিয়ে দেওয়া গেল Express ৪-এ, যদি handler-এ ধরা না থাকে। ছয়টি route-এর পুরো ফল:

টেবিলের নিচের দিকটিই আসল শিক্ষা। Express ৫ কোনো জাদু করে না। সে শুধু handler-এর ফেরত দেওয়া promise-এর দিকে তাকায়। অফিসিয়াল গাইডও বলছে, promise ফেরত না দিলে Express তার অস্তিত্বই জানে না। তাই তিনটি নিয়ম:

• Handler-কে async রাখুন আর প্রতিটি promise-এ await দিন।
• Callback API হলে next(err) নিজে ডাকুন, অথবা fs.promises ধরনের promise সংস্করণ নিন।
• Timer বা event-এর callback-এর ভেতরে try/catch সেই callback-এর ভেতরেই লিখুন।

Express ৪ এখনো চালাতে হলে একটি ছোট wrapper যথেষ্ট। Express ৫-এ এটি মুছে ফেলুন, এর আর কাজ নেই।

const asyncHandler = (fn) => (req, res, next) =>
  Promise.resolve(fn(req, res, next)).catch(next);

app.get('/async', asyncHandler(async (req, res) => { /* … */ }));

৩ · চার argument-এর error middleware: জায়গা, ক্রম আর 404

ডাকঘরে চিঠি বাছাইয়ের সারি ভাবুন। ঠিকানা ভুল হলেই চিঠি সারি থেকে সরে যায় “ফেরত” টেবিলে। মাঝের বাকি টেবিলগুলোয় আর যায় না। Express-এর error পথও তাই। next(err) বা throw হলেই সে সাধারণ middleware-গুলো ডিঙিয়ে পরের চার argument-এর ফাংশনে চলে যায়।

এই আকৃতি পাওয়ার জন্য app.js-এর শেষের অংশটি সবসময় এমন:

// … সব middleware আর route ওপরে
app.use(notFound);       // কোনো route না মিললে এখানে আসে
app.use(errorHandler);   // একদম শেষে, চার argument

Express একটি ফাংশনকে error middleware হিসেবে চেনে শুধু তার argument-এর সংখ্যা দেখে। চারটি থাকলেই সে error পথের। তাই ব্যবহার না করলেও next লিখতে হবে। দুটি ভুল আমরা ইচ্ছা করে করে দেখেছি (Express 5.3.0, NODE_ENV=production, সত্যিকারের run):

দ্বিতীয় ভুলটি মজার। ফাংশনটি তিন argument-এর সাধারণ middleware হয়ে গেছে। তাই err নামে এসেছে req, আর res নামে এসেছে next. নাম আপনার, অবস্থান Express-এর।

এখন একটি ভুলের পুরো যাত্রা দেখুন। অনুরোধটি বাজারঘরে এমন পণ্য চেয়েছে, যা নেই। “পরে” চেপে এগোন।

$ curl -i http://127.0.0.1:47301/api/products/999

app.use((req, res, next) => {
  req.id = randomUUID().slice(0, 8);   // 34d3376d
  next();
});
app.use(express.json({ limit: '1kb' }));

const row = db.prepare(...).get(999);   // undefined
if (!row) throw new AppError(404,
  'PRODUCT_NOT_FOUND', 'এই পণ্যটি পাওয়া যায়নি');

handler ফেরত দিল: Promise { <rejected> AppError }
router ডাকল:     next(err)

notFound(req, res, next)              3টি: বাদ
errorHandler(err, req, res, next)     4টি: এটিই

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{"error":{"code":"PRODUCT_NOT_FOUND",
 "message":"এই পণ্যটি পাওয়া যায়নি",
 "requestId":"34d3376d"}}

৪ · AppError আর একটি স্থির JSON আকার

সাধারণ Error-এর শুধু বার্তা থাকে। Handler-এর জানা দরকার আরও দুটি জিনিস: কোন status, আর কোন যন্ত্রপাঠ্য code. তাই নিজের একটি class. বাজারঘরের কোডে এটি একটি ফাইলেই থাকে।

export class AppError extends Error {
  constructor(status, code, message, extra = {}) {
    super(message, { cause: extra.cause });
    this.name = 'AppError';
    this.status = status;
    this.code = code;
    this.fields = extra.fields;
    this.retryAfter = extra.retryAfter;
  }
}

export function notFound(req, res, next) {
  next(new AppError(404, 'ROUTE_NOT_FOUND', 'এই ঠিকানায় কিছু নেই'));
}

message বদলাতে পারে, অনুবাদ হতে পারে। code বদলায় না। Frontend code দেখে সিদ্ধান্ত নেয়, বার্তার লেখা মিলিয়ে নয়। cause রাখে মূল ভুলটি, যাতে log-এ আসল কারণ থাকে। আর সব উত্তরের আকার এক:

{
  "error": {
    "code": "PRODUCT_NOT_FOUND",     // স্থির, যন্ত্রের জন্য
    "message": "এই পণ্যটি পাওয়া যায়নি",  // মানুষের জন্য
    "requestId": "34d3376d",         // log খোঁজার সূত্র
    "fields": [ … ]                  // শুধু ঘর-ভিত্তিক ভুলে
  }
}

এবার চালিয়ে দেখুন, একই তিনটি ভুল অসাবধান handler আর নিরাপদ handler কীভাবে সামলায়।

class AppError extends Error {
  constructor(status, code, message) {
    super(message);
    this.name = 'AppError';
    this.status = status;
    this.code = code;
  }
}
// খারাপ: যা ভুল, হুবহু তাই client-কে
const leaky = (err) => ({
  status: err.status ?? 500,
  message: err.message,
  stackHasPaths: /[\\/]/.test(err.stack),
});
// ভালো: চেনা ভুলের বার্তা যায়, অচেনা ভুলে একটি সাধারণ বাক্য
const safe = (err) => err instanceof AppError
  ? { status: err.status, code: err.code, message: err.message }
  : { status: 500, code: 'INTERNAL', message: 'Something went wrong on our side' };

function bug() {
  const coupon = null;
  return coupon.percent; // সত্যিকারের TypeError
}
const sqlErr = new Error(
  'relation "prodcts" does not exist: SELECT * FROM prodcts WHERE id = 7');

const errors = [new AppError(404, 'PRODUCT_NOT_FOUND', 'Product not found'), sqlErr];
try { bug(); } catch (e) { errors.push(e); }

for (const err of errors) {
  console.log(err.name);
  console.log('  leaky:', JSON.stringify(leaky(err)));
  console.log('  safe :', JSON.stringify(safe(err)));
}

Error
  leaky: {"status":500,"message":"relation \"prodcts\" does not exist: SELECT * FROM prodcts WHERE id = 7","stackHasPaths":true}
  safe : {"status":500,"code":"INTERNAL","message":"Something went wrong on our side"}

মান হিসেবে: RFC 9457 problem details

নিজের আকার বানানোর বদলে একটি প্রকাশিত মানও নেওয়া যায়। Problem Details এসেছিল RFC 7807 (২০১৬) হিসেবে, আর জুলাই ২০২৩-এ RFC 9457 তার জায়গা নিয়েছে। Media type application/problem+json; মূল সদস্য type, title, status, detail, instance. বাড়তি সদস্য যোগ করা যায়, আর client অচেনা সদস্য উপেক্ষা করবে। type না থাকলে ধরে নেওয়া হয় about:blank. একই app-এ ERROR_FORMAT=problem দিয়ে চালানো সত্যিকারের run:

HTTP/1.1 404 Not Found
Content-Type: application/problem+json; charset=utf-8

{"type":"https://bazarghar.example/problems/product_not_found","title":"এই পণ্যটি পাওয়া যায়নি","status":404,"instance":"/api/products/999","code":"PRODUCT_NOT_FOUND","requestId":"157c7435"}

কোনটি নেবেন? Public API বা অনেক দলের ব্যবহারের API হলে মান নেওয়ার যুক্তি শক্ত, কারণ টুল আর client আগে থেকেই আকারটি চেনে। শুধু নিজের frontend-এর জন্য হলে ছোট নিজস্ব আকারও ঠিক আছে। আসল নিয়ম একটাই: একটি আকার বেছে সব জায়গায় সেটিই রাখা। এই পর্বে নিজস্ব আকার রাখছি; বিস্তারিত তুলনা পর্ব ৩৩-এ।

৫ · চেনা ভুলকে সঠিক উত্তরে বদলানো

সব ভুল আপনার AppError হয়ে আসে না। Zod ছোড়ে ZodError, database ছোড়ে নিজের error, express.json ছোড়ে নিজের। কেন্দ্রীয় handler-এর কাজ এদের চিনে একটি ভাষায় আনা। অনেকটা হোটেলের রিসেপশনের মতো: ভেতরের বিভাগ যে ভাষাতেই বলুক, অতিথি শোনেন একই ধরনের ভদ্র বাক্য।

import { ZodError } from 'zod';

export function toAppError(err) {
  if (err instanceof AppError) return err;
  if (err instanceof ZodError) {
    const fields = err.issues.map((i) => ({
      path: i.path.join('.'), message: i.message,
    }));
    return new AppError(422, 'VALIDATION_FAILED',
      'কিছু ঘরের তথ্য ঠিক নেই', { fields, cause: err });
  }
  if (err.type === 'entity.parse.failed') {
    return new AppError(400, 'MALFORMED_JSON',
      'পাঠানো JSON পড়া গেল না', { cause: err });
  }
  if (err.type === 'entity.too.large') {
    return new AppError(413, 'BODY_TOO_LARGE',
      'পাঠানো তথ্য সীমার চেয়ে বড়', { cause: err });
  }
  if (err.code === 'ERR_SQLITE_ERROR' && err.errcode === 2067) {
    return new AppError(409, 'DUPLICATE_SKU', 'এই SKU আগেই আছে', {
      fields: [{ path: 'sku', message: 'এই SKU আগেই আছে' }], cause: err,
    });
  }
  if (err.name === 'TimeoutError') {
    return new AppError(504, 'UPSTREAM_TIMEOUT',
      'পেমেন্ট সার্ভিস সময়মতো সাড়া দেয়নি', { cause: err, retryAfter: 5 });
  }
  if (err.message === 'fetch failed') {
    return new AppError(503, 'UPSTREAM_DOWN',
      'পেমেন্ট সার্ভিসে এখন যাওয়া যাচ্ছে না', { cause: err, retryAfter: 30 });
  }
  return null;   // অচেনা মানে bug
}

Unique violation-এর code নির্ভর করে database আর library-র ওপর। উপরের 2067 হলো SQLite-এর SQLITE_CONSTRAINT_UNIQUE, কারণ lab-এ Node-এর built-in SQLite চলেছে। PostgreSQL-এ এটি SQLSTATE 23505, MySQL-এ error 1062, আর Prisma-য় P2002 (পর্ব ৩৯). SELECT করে দেখে তারপর INSERT করার বদলে unique constraint-এর ওপর ভরসা রাখা নিরাপদ, কারণ দুই অনুরোধ একসাথে এলে আগের যাচাই দুজনেই পাস করতে পারে (পর্ব ৪৩).

এবার errorHandler নিজে। চেনা হলে তার বার্তা, অচেনা হলে সাধারণ বাক্য। Log-এ সবসময় পুরো ঘটনা।

const isDev = process.env.NODE_ENV === 'development';

export function errorHandler(err, req, res, next) {
  if (res.headersSent) return next(err);

  const known = toAppError(err);
  const status = known?.status ?? 500;
  const code = known?.code ?? 'INTERNAL';
  const message = known?.message ?? 'আমাদের দিকে একটি সমস্যা হয়েছে';

  console.error(JSON.stringify({
    level: status >= 500 ? 'error' : 'warn',
    requestId: req.id, method: req.method, path: req.originalUrl,
    status, code, name: err.name, message: err.message,
    stack: status >= 500 ? err.stack : undefined,
  }));

  if (known?.retryAfter) res.set('Retry-After', String(known.retryAfter));

  res.status(status).json({
    error: {
      code, message, requestId: req.id, fields: known?.fields,
      stack: isDev ? err.stack : undefined,
    },
  });
}

নিচের ডিবাগারে পাঁচটি আলাদা ভুল toAppError-এর ভেতর দিয়ে যাচ্ছে। সবুজ দাগ দেখাচ্ছে কোন লাইনে সিদ্ধান্ত হলো।

1function toAppError(err) {2  if (err instanceof AppError) return err;3  if (err instanceof ZodError) return E422;4  if (err.errcode === 2067)   return E409;5  if (err.name === 'TimeoutError') return E504;6  return null;  // অচেনা মানে bug7}

সত্যিকারের run-এ (Express 5.3.0, Zod 4.6.7) তিনটি অনুরোধের উত্তর:

$ curl -i -X POST -H content-type:application/json -d '{"sku":"x","price":-5}' …/api/products
HTTP/1.1 422 Unprocessable Entity
{"error":{"code":"VALIDATION_FAILED","message":"কিছু ঘরের তথ্য ঠিক নেই","requestId":"df83861b","fields":[{"path":"sku","message":"Too small: expected string to have >=3 characters"},{"path":"name","message":"Invalid input: expected string, received undefined"}, …]}}

$ curl -i -X POST -H content-type:application/json -d '{"sku":"RICE-5KG","name":"abc","price":10}' …/api/products
  [server] {"level":"warn",…,"status":409,"code":"DUPLICATE_SKU","name":"Error","message":"UNIQUE constraint failed: products.sku"}
HTTP/1.1 409 Conflict
{"error":{"code":"DUPLICATE_SKU","message":"এই SKU আগেই আছে","requestId":"3428cc89","fields":[{"path":"sku","message":"এই SKU আগেই আছে"}]}}

$ curl -i -X POST -H content-type:application/json -d '{bad' …/api/products
HTTP/1.1 400 Bad Request
{"error":{"code":"MALFORMED_JSON","message":"পাঠানো JSON পড়া গেল না","requestId":"ce86c87e"}}

দ্বিতীয় উত্তরের [server] লাইনটি log, আর তার নিচেরটি client-এর উত্তর। SQL-এর ভাষা ভেতরে রইল, বাইরে গেল সহজ বাংলা। অজানা ঠিকানায় (/nope) এসেছে একই আকারে ROUTE_NOT_FOUND, আর প্রায় ২ KB-র body-তে (সীমা 1kb) 413 BODY_TOO_LARGE.

৬ · Client-কে কী বলবেন না: stack, SQL, path আর NODE_ENV

Error বার্তা আক্রমণকারীর কাছে মানচিত্রের মতো। Stack trace বলে দেয় ফাইলের path, framework-এর নাম আর সংস্করণের ইঙ্গিত। SQL বলে দেয় টেবিল আর কলামের নাম। connect ECONNREFUSED ধরনের বার্তা বলে দেয় ভেতরের IP আর port. এসব বাইরে গেলে পরের আক্রমণ সহজ হয়, যেমন injection-এর জন্য সঠিক টেবিলের নাম জানা। তাই নিয়ম সহজ: পুরো সত্য log-এ, সংক্ষিপ্ত সত্য client-এ, আর দুটিকে জোড়ে requestId.

Express-এর default handler NODE_ENV দেখে আচরণ বদলায়। একই route, একই ভুল, দুটি সত্যিকারের run:

$ curl -i http://127.0.0.1:47291/boom
HTTP/1.1 500 Internal Server Error
Content-Security-Policy: default-src 'none'
X-Content-Type-Options: nosniff
Content-Type: text/html; charset=utf-8

<pre>Error: secret table prodcts missing<br> &nbsp; &nbsp;at ~/bazarghar/mistakes.mjs:9:38<br> &nbsp; &nbsp;at Layer.handleRequest (~/bazarghar/node_modules/router/lib/layer.js:152:17)<br> …</pre>

$ curl -i http://127.0.0.1:47292/boom
HTTP/1.1 500 Internal Server Error
Content-Security-Policy: default-src 'none'
X-Content-Type-Options: nosniff
Content-Type: text/html; charset=utf-8

<pre>Internal Server Error</pre>

উপরের আউটপুট ছোট করা, আর path বদলে ~/bazarghar লেখা। লক্ষ করুন, ফাঁসটি ঘটছে NODE_ENV সেট না থাকলে। সেট করতে ভুলে গেলে production-এও stack বাইরে যাবে। Express-এর এই default-এর ওপর নির্ভর করবেন না। নিজের handler-এ উল্টো নিয়ম নিন: শুধু NODE_ENV === 'development' হলে stack দিন। আমাদের run-এ NODE_ENV সেট না করে /api/bug/null চালালে উত্তরে stack আসেনি:

{"error":{"code":"INTERNAL","message":"আমাদের দিকে একটি সমস্যা হয়েছে","requestId":"09c0175f"}}

আর NODE_ENV=development-এ (নিজের ল্যাপটপে কাজের সুবিধার জন্য) stack এসেছে:

{"error":{"code":"INTERNAL","message":"আমাদের দিকে একটি সমস্যা হয়েছে","requestId":"e634043a","stack":"TypeError: Cannot read properties of null (reading 'percent')\n    at ~/bazarghar/src/app.js:42:31\n    at Layer.handleRequest (~/bazarghar/node_modules/router/lib/layer.js:152:17)\n    …"}}

আরেকটি সূক্ষ্ম বিষয়: 500-এ বার্তা সাধারণ হলেও 4xx-এর বার্তাও ভেবে লিখতে হয়। “এই ইমেইলে অ্যাকাউন্ট নেই” বললে কার অ্যাকাউন্ট আছে তা জানা যায়। এজন্য login-এর ভুলে একই বার্তা দেওয়া ভালো (পর্ব ৪৯). অন্যের order চাইলে অনেক API 403-র বদলে 404 দেয়, যাতে order-টি আছে কি না সেটিও বোঝা না যায়।

৭ · Timeout আর ভেঙে পড়া dependency

বাজারঘরের চেকআউট একটি বাইরের পেমেন্ট সার্ভিসকে ডাকে। সেটি ধীর হলে কী হবে? রিকশা ডাকতে গিয়ে আপনি অনন্তকাল গলির মোড়ে দাঁড়িয়ে থাকবেন না। কিছুক্ষণ পরে অন্য ব্যবস্থা দেখবেন। Server-এরও সেই সীমা দরকার, আর সেটি আপনাকেই লিখতে হবে। fetch-এর নিজে থেকে কোনো ছোট সীমা নেই বলে ধরে নিন।

app.post('/api/pay', async (req, res) => {
  const r = await fetch(`${GATEWAY}/charge`, {
    method: 'POST',
    signal: AbortSignal.timeout(300),   // ৩০০ ms-এর বেশি নয়
  });
  res.json(await r.json());
});

একটি নকল gateway বানানো হলো, যে ২ সেকেন্ড পরে উত্তর দেয়। আরেক run-এ gateway বন্ধ রাখা হলো। দুটি সত্যিকারের ফল (log-এর লাইন ছোট করা):

# gateway ধীর
  [server] {"level":"error",…,"status":504,"code":"UPSTREAM_TIMEOUT","name":"TimeoutError","message":"The operation was aborted due to timeout"}
HTTP/1.1 504 Gateway Timeout
Retry-After: 5
{"error":{"code":"UPSTREAM_TIMEOUT","message":"পেমেন্ট সার্ভিস সময়মতো সাড়া দেয়নি","requestId":"eb85dcf8"}}

# gateway বন্ধ
  [server] {"level":"error",…,"status":503,"code":"UPSTREAM_DOWN","name":"TypeError","message":"fetch failed"}
HTTP/1.1 503 Service Unavailable
Retry-After: 30
{"error":{"code":"UPSTREAM_DOWN","message":"পেমেন্ট সার্ভিসে এখন যাওয়া যাচ্ছে না","requestId":"b6496af5"}}

Retry-After header client-কে বলে কতক্ষণ পরে আবার চেষ্টা করা যুক্তিসঙ্গত। সংখ্যা দুটি এখানে উদাহরণ, আপনার সার্ভিস অনুযায়ী ঠিক করবেন। err.message === 'fetch failed' মেলানো ভঙ্গুর নিয়ম; বড় কোডে gateway client-এর ভেতরে ভুল ধরে নিজের AppError ছোড়াই পরিষ্কার (পর্ব ২৯). TimeoutError-এর আসল অর্থ ফলাফল অজানা। টাকা কাটা হয়েছে কি হয়নি, আমরা জানি না। তাই পেমেন্টে অন্ধভাবে আবার পাঠানো বিপজ্জনক (পর্ব ৬৫).

Timeout না থাকলে কত ক্ষতি: একটি হিসাব

একসাথে কতগুলো অনুরোধ আটকে থাকবে, তার হিসাব Little's law: L = λ × W, যেখানে λ হলো প্রতি সেকেন্ডে আসা অনুরোধ আর W হলো প্রতিটির অপেক্ষা। ধরুন /api/pay-তে সেকেন্ডে ৫০টি অনুরোধ আসে (ধরে নেওয়া সংখ্যা)।

৩০০০টি খোলা অনুরোধ মানে ৩০০০টি সংযোগ, memory আর সম্ভবত database connection. একটি বাইরের সার্ভিসের সমস্যা তখন আপনার পুরো শপ নামিয়ে দেয়। একে বলে cascading failure.

Node-এর নিজের timeout-গুলো এই কাজ করে না। লেখার সময়ের ডকুমেন্টে server.requestTimeout-এর default ৩০০,০০০ ms আর server.headersTimeout-এর ৬০,০০০ ms; দুটিই client থেকে অনুরোধ পড়ার সীমা, আপনার handler কতক্ষণ ভাববে তার নয়। server.timeout-এর default 0, অর্থাৎ সীমা নেই। Handler-এর সীমা আপনার কোডের দায়িত্ব।

Retry: একটি ছোট নোট

ক্ষণিকের ভুলে আবার চেষ্টা কাজের, কিন্তু তিনটি শর্তে। প্রথমত, শুধু এমন কাজে, যা দুবার হলে ক্ষতি নেই (GET, অথবা idempotency key সহ POST). দ্বিতীয়ত, 4xx-এ নয়; ভুল ইনপুট আবার পাঠালেও ভুলই থাকবে। তৃতীয়ত, মোট সময় আর চেষ্টার সীমা থাকতে হবে। ৩০০ ms timeout-এ ৩ বার চেষ্টা, মাঝে ১০০ আর ২০০ ms exponential backoff: সবচেয়ে খারাপ ক্ষেত্রে 3 × 300 + 100 + 200 = 1200 ms. স্তর বাড়লে গুণ হয়: তিন স্তরের প্রতিটি ৩ বার চেষ্টা করলে একটি ক্লিকে নিচের সার্ভিসে 3 × 3 × 3 = 27টি অনুরোধ। এই retry storm ঠেকাতে সাধারণত একটি স্তরেই retry রাখা হয়, সাথে jitter. গভীরে পড়তে System Design কোর্সের resilience পর্ব দেখুন, যেখানে circuit breaker-ও আছে। আর queue-র retry পর্ব ৬২-তে।

৮ · শেষ পাহারাদার আর graceful shutdown

কেন্দ্রীয় handler শুধু request-এর পথের ভুল ধরে। তার বাইরের ভুল সোজা process-এর কাছে যায়। Node দুটি event দেয়। uncaughtException চলে কোনো catch না পাওয়া throw-তে। unhandledRejection চলে যে promise-এর কোনো handler নেই তাতে। Node 15 থেকে default হলো: rejection-এর hook না থাকলে সেটি uncaught exception হয়ে ওঠে।

// শেষ পাহারাদার। আসল server-এ এখানে log লিখে process.exit(1)
process.on('uncaughtException', (err, origin) => {
  console.log(`[${origin}] ${err.message}`);
});
process.on('rejectionHandled', () => console.log('rejectionHandled: too late'));
process.on('exit', () => console.log('process ended'));

// ১) await ভুলে যাওয়া promise
async function chargeCustomer() {
  throw new Error('forgot await on chargeCustomer');
}
chargeCustomer();

// ২) পরে catch জুড়লে দেরি হয়ে যায়
const late = Promise.reject(new Error('catch attached too late'));
setTimeout(() => late.catch(() => console.log('late catch ran')), 30);

// ৩) timer-এর callback: কোনো try/catch-এর ভেতরে নেই
try {
  setTimeout(() => { throw new Error('thrown inside timer'); }, 10);
} catch (e) {
  console.log('this line never runs');
}

// ৪) ঠিক পথ: এখানেই ধরা হলো, কোনো hook চলবে না
chargeCustomer().catch((e) => console.log('handled here:', e.message));

handled here: forgot await on chargeCustomer
[unhandledRejection] forgot await on chargeCustomer
[unhandledRejection] catch attached too late
[uncaughtException] thrown inside timer
late catch ran
rejectionHandled: too late
process ended

Node-এর ডকুমেন্ট পরিষ্কার: uncaughtException-এর পরে স্বাভাবিক কাজ চালিয়ে যাওয়া নিরাপদ নয়। এর ঠিক ব্যবহার হলো synchronous পরিষ্কার করে process বন্ধ করা। কেন? ভুলটি কোথায় হয়েছিল, কোন lock ধরা ছিল, কোন হিসাব অর্ধেক হয়েছিল, কেউ জানে না। আধখোলা গুদামে বিক্রি চালানোর চেয়ে দোকান বন্ধ করে নতুন করে খোলা ভালো। নতুন করে চালু করার কাজ বাইরের কারও: process supervisor, যেমন systemd, Docker-এর restart policy, Kubernetes বা pm2-এর মতো টুল।

import { app, db } from './app.js';

const PORT = Number(process.env.PORT ?? 3000);
const server = app.listen(PORT, '127.0.0.1');

let closing = false;
function shutdown(signal) {
  if (closing) return;
  closing = true;
  console.log(`${signal}: নতুন অনুরোধ বন্ধ`);
  app.locals.ready = false;              // health check 503 দেবে

  const force = setTimeout(() => {
    console.error('সময় শেষ, জোর করে বন্ধ');
    process.exit(1);
  }, 10_000);
  force.unref();

  server.close((err) => {
    db.close();
    console.log('সব অনুরোধ শেষ, DB বন্ধ');
    process.exitCode = err ? 1 : 0;
  });
  // keep-alive সংযোগ: উত্তর শেষে খালি হলেই বন্ধ
  setInterval(() => server.closeIdleConnections(), 200).unref();
}
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));

process.on('uncaughtException', (err, origin) => {
  console.error(JSON.stringify({
    level: 'fatal', origin, name: err.name, message: err.message,
  }));
  process.exit(1);   // অবস্থা অজানা: supervisor নতুন করে চালু করবে
});

সত্যিকারের run-এ এই পাহারাদার দুটি ভুলই ধরেছে। /api/crash-এর timer-এ throw আর /api/floating-এর ভুলে যাওয়া promise, দুটিতেই exit code 1:

$ curl http://127.0.0.1:47306/api/crash
{"scheduled":true}
  [server] {"level":"fatal","origin":"uncaughtException","name":"Error","message":"timer callback bug"}
  [server exited code=1 signal=null]

$ curl http://127.0.0.1:47306/api/floating
  [server] {"level":"fatal","origin":"unhandledRejection","name":"Error","message":"forgot to await this"}
{"ok":true}
  [server exited code=1 signal=null]

দ্বিতীয়টি ভয়ের। Client পেয়েছে {"ok":true}, অথচ যে কাজটি হওয়ার কথা ছিল সেটি ব্যর্থ, আর server নেমে গেছে। “Fire and forget” promise-এর এটাই ঝুঁকি।

Graceful shutdown: দোকান বন্ধের নিয়ম

নতুন version deploy হলে পুরোনো process-কে থামতেই হবে। Orchestrator সাধারণত প্রথমে SIGTERM পাঠায়, কিছুক্ষণ অপেক্ষা করে, তারপর SIGKILL, যেটি ধরা যায় না। ভালো দোকানদার ঠিক এভাবে বন্ধ করেন: শাটার অর্ধেক নামিয়ে নতুন খদ্দের বন্ধ, ভেতরের খদ্দেরের কেনা শেষ, হিসাব মেলানো, তালা। নিচের block-এ সত্যিকারের SIGTERM চলে, process নিজেই নিজেকে পাঠায়।

const http = require('node:http');
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const server = http.createServer(async (req, res) => {
  console.log('start', req.url);
  await sleep(150);                 // ধীর কাজ, যেমন order লেখা
  res.end('done ' + req.url);
  console.log('sent ', req.url);
});
let closing = false;
process.on('SIGTERM', () => {
  if (closing) return;
  closing = true;
  console.log('SIGTERM: no new connections');
  const force = setTimeout(() => process.exit(1), 500);
  force.unref();                    // এই timer নিজে process-কে বাঁচিয়ে রাখবে না
  server.close(() => {
    console.log('all requests finished: close DB, exit');
  });
  setInterval(() => server.closeIdleConnections(), 50).unref();
});

server.listen(0, '127.0.0.1', async () => {
  const url = `http://127.0.0.1:${server.address().port}`;
  const order = fetch(url + '/order').then((r) => r.text());
  await new Promise((r) => server.once('request', r)); // /order পৌঁছেছে
  process.kill(process.pid, 'SIGTERM'); // সত্যিকারের signal, নিজেকেই পাঠানো
  await sleep(20);
  try {
    await fetch(url + '/late');
  } catch (e) {
    console.log('new request refused:', e.cause.code);
  }
  console.log('client got:', await order);
});

start /order
SIGTERM: no new connections
new request refused: ECONNREFUSED
sent  /order
all requests finished: close DB, exit
client got: done /order

একই কাজ আসল Express app-এ, Linux-এ (WSL Ubuntu, Node 24.15.0, সত্যিকারের kill -TERM). /api/slow ১.৫ সেকেন্ড সময় নেয়:

$ curl -s -w " [%{http_code} %{time_total}s]\n" localhost:47331/api/slow &
$ kill -TERM <server pid>
SIGTERM: নতুন অনুরোধ বন্ধ
$ curl -sS localhost:47331/health
curl: (7) Failed to connect to 127.0.0.1 port 47331 after 0 ms: Couldn't connect to server
{"done":true} [200 1.501047s]
সব অনুরোধ শেষ, DB বন্ধ
server exit code: 0

৯ · Client-এ ফেরা: error থেকে UI

স্থির আকারের আসল লাভ পাওয়া যায় frontend-এ। সব fetch একটি ছোট ফাংশনের ভেতর দিয়ে গেলে React-এর কোডে একটি মাত্র error ধরন থাকে।

export class ApiError extends Error {
  constructor(status, body, retryAfter) {
    super(body?.error?.message ?? 'সংযোগে সমস্যা হয়েছে');
    this.status = status;
    this.code = body?.error?.code ?? 'UNKNOWN';
    this.fields = body?.error?.fields ?? [];
    this.requestId = body?.error?.requestId;
    this.retryAfter = retryAfter;
  }
}

export async function api(path, init) {
  const res = await fetch(path, init);
  const isJson = res.headers.get('content-type')?.includes('json');
  const body = isJson ? await res.json() : null;
  if (!res.ok) {
    throw new ApiError(res.status, body, res.headers.get('retry-after'));
  }
  return body;
}

isJson যাচাই কেন? Reverse proxy বা load balancer নিজের HTML পাতা পাঠাতে পারে, যেমন 502-তে। তখন res.json() নিজেই ভেঙে যেত, আর আসল status হারিয়ে যেত। এই ফাংশন lab-এর server-এর সাথে Node 24-এ চালিয়ে দেখা হয়েছে: /api/products/999-এ এসেছে 404 PRODUCT_NOT_FOUND, /health-এ সফল উত্তর। প্রতিটি code-এর জন্য UI আলাদা:

useQuery({
  queryKey: ['product', id],
  queryFn: () => api(`/api/products/${id}`),
  retry: (count, err) => err.status >= 500 && count < 2,   // 404-এ retry নয়
});

const save = useMutation({
  mutationFn: (data) => api('/api/products', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(data),
  }),
  onError: (err) => {
    err.fields.forEach((f, i) => form.setError(f.path, {
      type: 'server', message: f.message,
    }, { shouldFocus: i === 0 }));
  },
});

লক্ষ করুন, f.path-এর আকার sku বা items.0.qty, যা React Hook Form সরাসরি বোঝে। Server-এর একটি ছোট সিদ্ধান্ত frontend-এর অনেক কোড বাঁচাল। উপরের React অংশটি উদাহরণ, এখানে চালানো হয়নি; মূল ধরন পর্ব ১৯ আর পর্ব ২১-এ চালিয়ে দেখানো আছে।

১০ · AI-এর যুগে: error handling যাচাই

AI দিয়ে লেখা server কোড সুন্দর দেখায়, সুখের পথেও চলে। সমস্যা লুকিয়ে থাকে ভুলের পথে, যেটি demo-তে কেউ চালায় না। তাই ইচ্ছা করে ভুল ঘটিয়ে দেখা ছাড়া এই কোড বিশ্বাস করা যায় না।

AI-এর লেখা error handling হাতে পেলে

• Express-এর version দেখে docs মিলিয়েছি, আর অদরকারি package বাদ দিয়েছি
• ইচ্ছা করে একটি bug ঘটিয়েছি, আর উত্তরে কোনো stack, SQL বা path পাইনি
• NODE_ENV সেট না করেও উত্তর নিরাপদ পেয়েছি
• অজানা ঠিকানা, ভাঙা JSON আর বড় body-তে একই JSON আকার পেয়েছি
• প্রতিটি বাইরের call-এ timeout আছে, আর ধীর নকল সার্ভিসে সেটি চলেছে
• Linux বা Docker-এ SIGTERM পাঠিয়ে চলমান অনুরোধ শেষ হতে দেখেছি
• Log-এ password, token বা secret যাচ্ছে না, আর AI-কে আসল secret পাঠাইনি