الـ Errors على مستوى الـ process: operational و programmer و crash-only

أهلًا بيك. الأخطاء في الـ backend نوعين، والفرق بينهم هو اللي بيحدد تعمل إيه. operational: حاجات متوقعة ممكن تحصل في أي server سليم: الملف مش موجود، الـ database مش بترد، المستخدم بعت input غلط. دي بتتعامل معاها: تعيد المحاولة، أو ترد four hundred، أو تستخدم default. programmer error: bug في الـ code نفسه، زي إنك تقرا property من undefined. ده مفيش علاج ليه وقت التشغيل، غير إنك تصلّح الـ code. نشغّل.

// نوعين من الأخطاء
// 1) operational: متوقعة، بنتعامل معاها (الملف مش موجود، الـ DB واقعة، input غلط)
// 2) programmer: bug في الـ code (قريت property من undefined)

import fs from "node:fs/promises";

async function loadConfig() {
  try {
    return JSON.parse(await fs.readFile("config.json", "utf8"));
  } catch (err) {
    if (err.code === "ENOENT") {
      console.log("operational: مفيش config، هنستخدم الـ defaults");
      return { port: 3000 };
    }
    throw err;
  }
}

const config = await loadConfig();
console.log(config.port);
console.log(config.db.host); // programmer error

$ node main.js
operational: مفيش config، هنستخدم الـ defaults
3000

file:///home/you/my-backend/main.js:21
console.log(config.db.host); // programmer error
                      ^

TypeError: Cannot read properties of undefined (reading 'host')
    at file:///home/you/my-backend/main.js:21:23

Node.js v24.14.1

الـ config مش موجود، واتعاملنا معاه: operational، استخدمنا الـ default، والـ port طلع. وبعدين config dot db: undefined، و host منها: TypeError، والبرنامج وقع. وخد بالك من throw err في الـ catch: أي error مش ENOENT بنرميه تاني، ما نبلعهوش. لأن لو الـ config موجود بس فيه JSON بايز، ده محتاج حد يشوفه، مش default. طب لو حصل error محدش مسكه خالص؟ Node بيدّيك آخر فرصة: event اسمه uncaughtException. هنسجّل handler ليه. و event اسمه exit بيتنادي آخر حاجة قبل الـ process ما يخرج. وبعدين bug جُوّه timer. و promise rejected محدش مسكها. نشغّل.

process.on("uncaughtException", (err, origin) => {
  console.error(`[fatal] ${origin}: ${err.message}`);
  process.exitCode = 1;
});

process.on("exit", (code) => {
  console.error(`[exit] الـ process خارج بـ code ${code}`);
});

setTimeout(() => {
  throw new Error("bug جُوّه timer");
}, 10);

Promise.reject(new Error("promise محدش مسكها"));

$ node main.js

[fatal] unhandledRejection: promise محدش مسكها
[fatal] uncaughtException: bug جُوّه timer
[exit] الـ process خارج بـ code 1

الـ promise اللي محدش مسكها اتمسكت في نفس الـ handler، و origin بيقول unhandledRejection. والـ bug بتاع الـ timer اتمسك، و origin بيقول uncaughtException. والـ process خرج بـ code one. بس خد بالك من حاجة خطيرة: لو الـ handler ما خرجش، الـ process هيكمّل. وده غلط كبير. bug حصل في نص عملية، يعني الـ state ممكن تكون بايزة: transaction نصها اتعمل، lock ما اتفكّش، connection في حالة غريبة. الكمّلة بعد كده مقامرة. الطريقة الصح اسمها crash-only. أول ما يحصل bug: سجّله. بطّل تستقبل requests جديدة بـ server dot close، وسيب اللي شغالة تخلص. ولو ما خلصتش في تلات تواني، اخرج بالعافية. والـ unref معناها: التايمر ده ما يمسكش الـ process عايش لوحده. وبعدين exit one. واللي يقوّم الـ process تاني: Docker أو Kubernetes أو systemd. وفي الـ code ده bug حقيقي: بنعمل push على رقم.

نشغّل.

import http from "node:http";

let state = { orders: 0 };

function shutdown(reason, err) {
  console.error(`[fatal] ${reason}: ${err.message}`);
  // 1) بطّل تستقبل requests جديدة
  server.close(() => {
    console.error("[fatal] اتقفل بنضافة، exit 1");
    process.exit(1);
  });
  // 2) لو ما قفلش في وقت معقول، اقفل بالعافية
  setTimeout(() => process.exit(1), 3000).unref();
}

process.on("uncaughtException", (err) => shutdown("uncaughtException", err));
process.on("unhandledRejection", (err) => shutdown("unhandledRejection", err));

const server = http.createServer((req, res) => res.end("ok"));
server.listen(3000, () => {
  console.log("server شغال");
  setTimeout(() => {
    state.orders.push(1); // bug
  }, 50);
});

$ node main.js
server شغال
[fatal] uncaughtException: state.orders.push is not a function
[fatal] اتقفل بنضافة، exit 1

الـ server اشتغل، والـ bug حصل، فسجّلنا الرسالة، وقفلنا بنضافة، وخرجنا بـ one. وفي الإنتاج، عندك أكتر من نسخة من الـ server، فلو واحدة ماتت، الـ load balancer بيبعت للباقي لحد ما ترجع. ودي حاجة هنبنيها في قسم Docker و Kubernetes. آخر حاجة: الـ exit codes. zero يعني نجح، وأي رقم تاني فشل، والأدوات بتقرا الرقم ده: الـ CI، و Docker، و npm. ممكن تخرج بـ process dot exit، بس ده بيقطع أي حاجة لسه بتتكتب. الأحسن process dot exitCode: بتحدد الرقم، وتسيب Node يخلّص ويخرج لوحده. نجرّب تلات حالات. zero، واتنين، وتلاتة.

const code = Number(process.argv[2]);

if (code === 0) console.log("كله تمام");
else if (code === 2) {
  console.error("الاستخدام غلط");
  process.exitCode = 2;
} else {
  throw new Error("حاجة اتكسرت");
}

$ node main.js 0; echo "exit=$?"; node main.js 2 2>&1; echo "exit=$?"; node main.js 3 2>/dev/null; echo "exit=$?"
كله تمام
exit=0
الاستخدام غلط
exit=2
exit=1

zero: كله تمام، exit zero. اتنين: الرسالة، و exit اتنين. تلاتة: throw من غير ما حد يمسك، و Node خرج بـ one لوحده. و dollar question mark في الـ shell بيطبع exit code آخر أمر. في الـ CI، أي خطوة exit code بتاعها مش zero بتوقف الـ pipeline كله. التحدي: server بيموت بكرامة. slash ok بترد عادي. slash bad-input خطأ operational: يترد عليه four hundred، والـ server يكمّل. slash bug بيعمل bug حقيقي برة أي try. و uncaughtException يسجّل، ويقفل بنضافة، و exit code one. الشروط في الكومنت.

الحل. ok عادي. bad-input: throw جُوّه try، والـ catch بيرد بالـ status. bug: setTimeout بتقرا boom من null. والـ handler: يسجّل، و exitCode one، و server dot close، ومهلة بـ unref. نشغّل، ونبعت تلات requests.

import http from "node:http";

const server = http.createServer((req, res) => {
  if (req.url === "/ok") return res.end("ok");
  if (req.url === "/bad-input") {
    try {
      const err = new Error("input غلط");
      err.status = 400;
      throw err;
    } catch (err) {
      res.statusCode = err.status ?? 500;
      return res.end(err.message);
    }
  }
  if (req.url === "/bug") {
    setTimeout(() => null.boom, 0);
    return res.end("بعتنا الـ bug");
  }
  res.statusCode = 404;
  res.end("not found");
});

process.on("uncaughtException", (err, origin) => {
  console.error(`[fatal] ${origin}: ${err.message}`);
  process.exitCode = 1;
  server.close(() => console.error("[fatal] اتقفل بنضافة"));
  setTimeout(() => process.exit(1), 3000).unref();
});

server.listen(3000, () => console.log("server شغال"));

$ node main.js
server شغال

→ GET /ok
← 200 OK
ok

→ GET /bad-input
← 400 Bad Request
input غلط

→ GET /bug
[fatal] uncaughtException: Cannot read properties of null (reading 'boom')
[fatal] اتقفل بنضافة
← 200 OK
بعتنا الـ bug

ok، و four hundred والـ server لسه شغال، وبعدين الـ bug: اتسجّل fatal، والـ server اتقفل بنضافة. الدرس الجاي آخر درس في القسم ده: الـ test runner بتاع Node، والـ debugging.