معالجة الأخطاء الآمنة في APIs

// سيئ - يكشف بنية قاعدة البيانات وإصدار المكتبة والمسار الداخلي
app.get('/api/orders/:id', async (req, res) => {
  try {
    const order = await db.order.findUniqueOrThrow({ where: { id: req.params.id } });
    res.json(order);
  } catch (err) {
    res.status(500).json({ error: err.message, stack: err.stack });
    // err.message قد يحوي: "relation orders_v2 does not exist"
    // أو "connect ECONNREFUSED 10.0.4.12:5432" — يكشف بنية الشبكة الداخلية
  }
});

مهاجم يجمع هذه الرسائل من عشرات الطلبات المتعمَّدة (IDs غير موجودة، قيم
حدّية، رموز غريبة) يبني تدريجيًا خريطة لبنية قاعدة بياناتك، إصدارات
مكتباتك، وحتى عناوين IP داخلية — دون أن يخترق شيئًا بعد، فقط بقراءة
رسائل الخطأ التي منحته إياها أنت.

app.get('/api/orders/:id', async (req, res) => {
  try {
    const order = await db.order.findUniqueOrThrow({ where: { id: req.params.id } });
    res.json(order);
  } catch (err) {
    logger.error({ err, requestId: req.id, route: req.path }); // التفاصيل الكاملة هنا فقط
    res.status(404).json({ error: 'الطلب غير موجود', requestId: req.id }); // رسالة عامة + مرجع للدعم
  }
});

// middleware/error-handler.js — آخر middleware في السلسلة
function globalErrorHandler(err, req, res, next) {
  logger.error({ err, requestId: req.id, path: req.path, method: req.method });

  // في بيئة التطوير فقط تُعرض التفاصيل - أبدًا في الإنتاج
  const isDev = process.env.NODE_ENV === 'development';

  const statusCode = err.statusCode || 500;
  res.status(statusCode).json({
    error: err.publicMessage || 'حدث خطأ غير متوقع',
    requestId: req.id,
    ...(isDev && { details: err.message, stack: err.stack }),
  });
}

app.use(globalErrorHandler); // بعد كل الـ routes مباشرة

// سيئ - لو فشلت processImage()، الملف المؤقت لا يُحذف أبدًا
app.post('/api/upload', async (req, res) => {
  const tempFile = await saveToTemp(req.files.image);
  const processed = await processImage(tempFile); // قد يرمي استثناء
  await deleteTemp(tempFile);
  res.json({ url: processed.url });
});

مهاجم يرفع ملفات مصمَّمة عمدًا لتفشل أثناء المعالجة (صيغة تالفة، أبعاد
غير منطقية) بشكل متكرر. كل طلب فاشل يترك ملفًا مؤقتًا معلّقًا. بعد آلاف
الطلبات، القرص يمتلئ ويتعطل النظام كاملًا — لكل المستخدمين، لا فقط
المهاجم.

app.post('/api/upload', async (req, res) => {
  const tempFile = await saveToTemp(req.files.image);
  try {
    const processed = await withTimeout(processImage(tempFile), 10_000); // حد زمني صارم
    res.json({ url: processed.url });
  } catch (err) {
    logger.error({ err, requestId: req.id });
    res.status(422).json({ error: 'تعذّرت معالجة الملف' });
  } finally {
    await deleteTemp(tempFile); // ينفَّذ دائمًا - نجاح أو فشل
  }
});

function withTimeout(promise, ms) {
  return Promise.race([
    promise,
    new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), ms)),
  ]);
}

// سيئ - لو فشل الخطوة الثانية، المبلغ خُصم من الحساب الأول لكن لم يُضَف للثاني
async function transferFunds(fromId, toId, amount) {
  await db.account.update({ where: { id: fromId }, data: { balance: { decrement: amount } } });
  // انقطاع شبكي هنا = المبلغ اختفى فعليًا
  await db.account.update({ where: { id: toId }, data: { balance: { increment: amount } } });
}

async function transferFunds(fromId, toId, amount) {
  return db.$transaction(async (tx) => {
    const from = await tx.account.update({
      where: { id: fromId },
      data: { balance: { decrement: amount } },
    });
    if (from.balance < 0) {
      throw new Error('رصيد غير كافٍ'); // يُلغي المعاملة كاملة تلقائيًا
    }
    await tx.account.update({ where: { id: toId }, data: { balance: { increment: amount } } });
  });
  // فشل أي خطوة = تراجع كامل، لا حالة وسطى أبدًا
}

✅ رسائل خطأ عامة للمستخدم دائمًا، التفاصيل الكاملة في السجلات فقط
✅ معالج أخطاء مركزي واحد بدل منطق مبعثر في كل route
✅ finally أو try/finally يحرر أي مورد محجوز (ملفات، اتصالات، أقفال)
✅ حد زمني (timeout) على أي عملية خارجية قد تتعلّق
✅ المعاملات متعددة الخطوات داخل DB Transaction واحدة — لا حالة وسطى أبدًا
✅ الفشل الافتراضي دائمًا "رفض" (Fail Closed) لا "سماح" (Fail Open)
✅ لا تُظهر stack traces أو أسماء مكتبات/إصدارات في الاستجابة للمستخدم النهائي