Healthcheck و Restart و Resource Limits: running مش معناها شغّال

أهلًا بيك. docker ps بيقولك Up تلات ساعات. يبقى تمام؟ لأ. Up معناها إن الـ process لسه عايش، وبس. الـ process ممكن يكون عايش والـ event loop مقفول، أو مستني lock، أو فقد الـ connection بالـ database ومش بيعرف يرجع. والـ users شايفين timeout، و Docker شايف كله تمام. وفي الناحية التانية: الـ process ممكن يموت فعلًا، ومحدش يقومه. أو ياكل الـ memory بتاعة الـ server كله، ويوقّع معاه كل الـ containers التانية. بص على compose dot naive dot yaml. المشاكل: الـ api فيه healthcheck، بس بـ curl. والـ image مبنية على node slim، ومفيهاش curl. يعني الـ healthcheck هيفشل كل مرة، والـ container هيفضل unhealthy من أول يوم، والناس هتتعود تتجاهل الكلمة دي. الـ timeout عشر تواني والـ interval خمسة. الـ probe ممكن ياخد أطول من الوقت بين كل probe والتاني. الـ api مالوش restart، فلو وقع بـ exception، هيفضل واقع لحد ما حد يصحى. ومالوش memory limit. والـ worker: الـ limit خمسمية اتناشر ميجا، والـ heap ألف وأربعة وعشرين. V8 فاكر إن عنده مساحة، فمش هيعمل garbage collection بجد، والـ kernel هيقتله قبلها.

الـ healthcheck: command بيشغّله Docker جُوّه الـ container كل interval. exit صفر يعني نجح، أي حاجة تانية يعني فشل، ولو خد أكتر من الـ timeout يبقى فشل برضه. الـ container بيبدأ starting. أول probe ينجح يبقى healthy. لو فشل retries مرة ورا بعض يبقى unhealthy. ونجاح واحد بعدها يرجّعه healthy. start period: وقت في الأول الفشل فيه ما بيتحسبش، علشان الـ app اللي بياخد وقت يقوم، زي migrations أو cache warm up. و start interval: probes أسرع جُوّه الـ start period، علشان يبقى healthy بسرعة. والـ status ده بيستخدمه depends on service healthy من الدرس قبل اللي فات، وبيبان في docker ps. يفحص إيه؟ إن الـ process نفسه بيرد. الـ event loop شغّال والـ server بيسمع. ما تفحصش الـ database هنا: لو الـ database وقعت، كل الـ containers هتبقى unhealthy مرة واحدة، ومش هتفرق حاجة. الفرق بين الحاجتين ده درس الـ readiness والـ liveness بعدين.

app dot js server حقيقي فيه slash healthz. ولو اديته BLOCK AT MS، بعد الوقت ده بيقفل الـ event loop تانيتين، زي JSON parse لـ file ضخم أو regex بايخة. و healthcheck dot js: ده اللي بنحطه في الـ HEALTHCHECK بدل curl. fetch على مِيّة سبعة وعشرين صفر صفر واحد، و AbortSignal timeout، و exit صفر أو واحد. الـ image فيها node أصلًا، فمش محتاجين نزوّد curl ونكبّر الـ image ونزوّد attack surface. وفي الـ Dockerfile: HEALTHCHECK بالـ CMD ده جُوّه الـ image نفسها، فأي حد يشغّلها ياخده. و docker inspect بيوريك آخر خمس نتايج والـ output بتاعهم.

الـ restart policies: no: الـ default. وقع يبقى وقع. always: أي exit يقوم تاني، حتى لو خلص عادي. ولو عملت docker stop، مش هيقوم لوحده، بس لو الـ Docker daemon نفسه عمل restart، أو الـ server عمل reboot، هيقوم. unless stopped: زي always، بس لو انت عملت stop بإيدك، هيفضل واقف حتى بعد reboot. وده الأنسب لأغلب الـ services. on failure colon خمسة: بس لو الـ exit code مش صفر، ولحد خمس مرات. Docker بيستنى بين كل restart والتاني: مِيّة ms، وبعدين الضعف، لحد دقيقة. علشان crash loop ما يحرقش الـ CPU. ومهم أوي: Docker لوحده مش بيعمل restart للـ container الـ unhealthy. الـ healthcheck بيغيّر الـ status بس. اللي بيعمل restart على الـ health هو orchestrator، زي Kubernetes بالـ liveness probe، أو Swarm.

والـ exit codes: صفر: خلص عادي. واحد: error، زي uncaught exception. أي رقم فوق مِيّة تمانية وعشرين معناه اتقتل بـ signal، والـ signal هو الرقم ناقص مِيّة تمانية وعشرين. مِيّة تلاتة وأربعين: SIGTERM، يعني docker stop، وده الطبيعي. مِيّة سبعة وتلاتين: SIGKILL. يا إما docker stop والـ app ما خلصش في عشر تواني، يا إما الـ kernel قتله علشان الـ memory. docker inspect بيقولك OOMKilled true ولا false. الـ memory limit: mem limit، أو deploy resources limits memory. لو الـ container عدّاه، الـ kernel بيقتله فورًا بـ SIGKILL، من غير أي فرصة يعمل cleanup. وده أحسن بكتير من إنه ياكل الـ server. و reservations: اللي الـ container محتاجه على الأقل، للـ scheduling. و cpus: زي نص CPU. ده throttling، مش kill. الـ app بيبقى أبطأ بس.

و Node جُوّه الـ limit: الـ memory بتاعة الـ process، الـ RSS، مش الـ heap بس. فيه Buffers، وفيه الـ native code، والـ threads بتاعة libuv، والـ code نفسه. V8 بيقرّر يعمل garbage collection امتى على حسب الـ max old space size. لو الرقم ده أكبر من الـ limit، V8 هيستنى، والـ kernel هيقتل الـ process قبل ما V8 يحس. Node الجديد بيقرا الـ cgroup limit وبيختار default على أساسه، بس الأوضح إنك تكتبه بإيدك: تلات تربع الـ limit تقريبًا، والباقي للحاجات اللي بره الـ heap. ولو الـ heap خلص فعلًا، Node بيموت بـ heap out of memory، exit code واحد أو مِيّة تلاتة وتلاتين، مع رسالة واضحة في الـ logs. أحسن بكتير من SIGKILL من غير ولا كلمة. والـ cpus: os availableParallelism بيرجّع الـ CPUs بتاعة الـ host كله. فلو بتعمل cluster أو worker threads على حسبه، حدّده من env.

ده compose dot yaml الجديد. الـ healthcheck بـ node healthcheck dot js، و timeout تلات تواني والـ interval عشرة، و start period عشرين تانية، و start interval تانية واحدة. restart unless stopped للـ api، و on failure خمسة للـ worker. memory limit خمسمية اتناشر للاتنين، والـ heap تلتمية أربعة وتمانين. و cpus. و services dot naive dot js و services dot js نفس الكلام كـ JS objects. probe dot js بيعمل اللي Docker بيعمله: بيشغّل app dot js، وبعد شوية الـ app بيقفل الـ event loop، و probe بيشغّل healthcheck dot js الحقيقي كل شوية ويحسب الـ status بالـ healthTimeline بتاعتك. و check dot js بيعمل lint للـ services، وبيقول Docker هيعمل إيه مع شوية exit codes. التحدي: اكتب health dot js. التفاصيل كلها في الكومنت، و test dot js فيه أربعتاشر حالة.

الحل. healthTimeline: state machine صغيرة. status و failing، وكل probe يا إما يصفّر الـ failing، يا إما يزوّده، والـ start period بيحمي بس طول ما احنا لسه starting. shouldRestart: أول سطر هو أهم سطر: exitCode null يبقى false. Docker مش بيعمل restart لحاجة لسه شغّالة. exitReason: الرقم فوق مِيّة تمانية وعشرين يبقى signal. والـ lint: memLimit بيدوّر على deploy الأول وبعدين mem limit، والـ heap من NODE OPTIONS أو الـ command. نشغّل probe dot js. ده app حقيقي و healthcheck حقيقي، فالأرقام هتختلف شوية كل مرة.

// health.js: قواعد Docker في الـ healthcheck والـ restart policies والـ resource limits، و lint
const UNITS = { ms: 1, s: 1000, m: 60000, h: 3600000 };

export function parseDuration(v) {
  if (typeof v === "number") return v;
  const parts = [...String(v).matchAll(/(\d+(?:\.\d+)?)(ms|s|m|h)/g)];
  if (!parts.length || parts.map((p) => p[0]).join("") !== String(v)) throw new Error(`duration مش مفهومة: ${v}`);
  return parts.reduce((sum, [, n, u]) => sum + Number(n) * UNITS[u], 0);
}

export function parseMemory(v) {
  if (v == null) return null;
  if (typeof v === "number") return v / 1024 / 1024; // bytes
  const m = /^(\d+(?:\.\d+)?)([bkmg]?)b?$/i.exec(String(v).trim());
  if (!m) throw new Error(`memory مش مفهومة: ${v}`);
  const n = Number(m[1]), u = m[2].toLowerCase();
  return { "": n / 1048576, b: n / 1048576, k: n / 1024, m: n, g: n * 1024 }[u];
}

export function healthTimeline(results, cfg) {
  const timeout = parseDuration(cfg.timeout ?? "30s"), retries = cfg.retries ?? 3, startPeriod = parseDuration(cfg.start_period ?? "0s");
  let status = "starting", failing = 0;
  return results.map(({ at, ms, ok }) => {
    const pass = ok && ms <= timeout;
    if (pass) { failing = 0; status = "healthy"; }
    else if (!(status === "starting" && at < startPeriod)) { failing++; if (failing >= retries) status = "unhealthy"; }
    return { at, pass, status, failing };
  });
}

export function shouldRestart(policy = "no", { exitCode = null, manualStop = false, restarts = 0, daemonRestart = false } = {}) {
  if (exitCode === null) return false; // الـ container لسه شغّال، حتى لو unhealthy: Docker لوحده مش بيعمل restart
  const [name, max] = String(policy).split(":");
  if (name === "always") return !manualStop || daemonRestart;
  if (name === "unless-stopped") return !manualStop;
  if (name === "on-failure") return exitCode !== 0 && !manualStop && (max === undefined || restarts < Number(max));
  return false;
}

export const restartDelay = (n) => Math.min(100 * 2 ** n, 60000);

export function exitReason(code, { oomKilled = false } = {}) {
  if (code === 0) return "clean";
  if (code === 137) return oomKilled ? "OOM" : "SIGKILL";
  if (code === 143) return "SIGTERM";
  if (code === 130) return "SIGINT";
  if (code > 128) return `signal ${code - 128}`;
  return "error";
}

export const heapFor = (limitMb) => Math.floor(limitMb * 0.75);

export const memLimit = (svc) => parseMemory(svc.deploy?.resources?.limits?.memory ?? svc.mem_limit ?? null);

export function heapOf(svc) {
  const text = [svc.environment?.NODE_OPTIONS ?? "", [].concat(svc.command ?? []).join(" ")].join(" ");
  const m = /--max-old-space-size=(\d+)/.exec(text);
  return m ? Number(m[1]) : null;
}

export function lintService(name, svc) {
  const out = [];
  const add = (rule, severity, msg) => out.push({ rule, service: name, severity, msg });
  const hc = svc.healthcheck;
  const listens = (svc.ports?.length ?? 0) + (svc.expose?.length ?? 0) > 0;
  if (listens && (!hc || hc.disable))
…

$ node probe.js
probe  1: نجح  بعد  87ms ← healthy
probe  2: نجح  بعد  67ms ← healthy
probe  3: نجح  بعد  65ms ← healthy
probe  4: نجح  بعد  67ms ← healthy
probe  5: نجح  بعد  69ms ← healthy
probe  6: فشل  بعد 835ms ← healthy (failing 1)
probe  7: فشل  بعد 580ms ← unhealthy (failing 2)
probe  8: نجح  بعد  67ms ← healthy
probe  9: نجح  بعد  73ms ← healthy
probe 10: نجح  بعد  69ms ← healthy
probe 11: نجح  بعد  74ms ← healthy
الـ process كان عايش طول الوقت: true. يعني من غير healthcheck كان Docker هيقول running وخلاص

أول probe ممكن يفشل، لأن الـ app لسه بيقوم. بس ده جُوّه الـ start period، فالـ status فضل starting وما اتحسبش. وبعدين healthy. ولما الـ event loop اتقفل: الـ probe خد أكتر من الـ timeout، مرتين ورا بعض، فبقى unhealthy. ولما الـ event loop رجع، أول probe نجح رجّعه healthy. والسطر الأخير هو المهم: الـ process كان عايش طول الوقت. من غير healthcheck، Docker كان هيقول running. نشغّل check dot js.

$ node check.js services.naive.js services.js

=== services.naive.js ===
  api: restart no | memory من غير limit
     ERROR HC-NO-CURL: curl مش موجود في shop-api:1.4.0-node22-slim: الـ healthcheck هيفشل على طول
     WARN HC-TIMEOUT: الـ timeout لازم يبقى أقل من الـ interval
     WARN NO-RESTART: لو الـ process وقع مش هيقوم تاني
     WARN NO-MEM-LIMIT: مفيش memory limit: leak واحد ياكل الـ server كله
  worker: restart always | memory 512MB ← heap مقترح 384MB
     ERROR HEAP-OVER-LIMIT: الـ heap 1024MB والـ limit 512MB: الـ kernel هيقتله بـ OOM قبل ما V8 يعمل GC، خليه 384 أو أقل

=== services.js ===
  api: restart unless-stopped | memory 512MB ← heap مقترح 384MB
  worker: restart on-failure:5 | memory 512MB ← heap مقترح 384MB

=== Docker هيعمل إيه؟ ===
  no             crash                                    error    ← لأ
  always         خلص عادي                                 clean    ← restart
  always         شغّال بس unhealthy                       running  ← لأ
  on-failure:5   OOM                                      OOM      ← restart
  on-failure:5   crash للمرة السادسة                      error    ← لأ
  unless-stopped docker stop                              SIGTERM  ← 
…

الـ naive: الـ api فيه أربع مشاكل: curl، والـ timeout، ومفيش restart، ومفيش limit. والـ worker الـ heap ألف وأربعة وعشرين على limit خمسمية اتناشر. الجديد: نضيف، والـ heap المقترح تلتمية أربعة وتمانين. وجدول Docker هيعمل إيه: always بيقوم حتى لو خلص عادي. والـ unhealthy اللي لسه شغّال: لأ. والـ OOM مع on failure: restart. والمرة السادسة مع on failure خمسة: لأ، فيفضل واقف وانت تبص في الـ logs. و docker stop مع unless stopped: يفضل واقف. ومع always بعد restart للـ daemon: يقوم. والـ delay بيتضاعف لحد دقيقة. ونشغّل test dot js.

$ node test.js
✅ parseDuration: ms و s و m و h ومركّبة، والغلط بيرمي 
✅ parseMemory: b و k و m و g بالـ MB، و number بالـ bytes، و null 
✅ healthTimeline: نجاح ← healthy، و retries فشل ورا بعض ← unhealthy، ونجاح واحد يرجّعه 
✅ healthTimeline: probe أبطأ من الـ timeout يعتبر فشل 
✅ healthTimeline: الفشل جُوّه الـ start_period ما بيتحسبش 
✅ healthTimeline: بعد أول healthy، الـ start_period ما بيحميش 
✅ healthTimeline: الـ defaults: timeout 30s و retries 3 
✅ shouldRestart: no و always و unless-stopped 
✅ shouldRestart: on-failure و on-failure:N 
✅ shouldRestart: شغّال unhealthy ← لأ، و always بعد daemon restart ← آه 
✅ restartDelay و exitReason 
✅ heapFor و memLimit و heapOf 
✅ lint: كل rule لوحدها 
✅ services.naive: خمس مشاكل، و services.js نضيف HC-NO-CURL:api HC-TIMEOUT:api NO-RESTART:api NO-MEM-LIMIT:api HEAP-OVER-LIMIT:worker

14/14

كله نجح. لحد دلوقتي الـ image بتتبني بأي حاجة في الـ folder. طب لو الـ build محتاج npm token علشان private package؟ لو حطيته في ARG أو ENV، هيفضل في الـ image، وأي حد يعمل docker history يشوفه. الدرس الجاي: BuildKit، و build secrets، و cache mounts، والـ image layers بتفضح إيه.

# compose.naive.yaml: الـ container "running"... وهو معلّق
services:
  api:
    image: shop-api:1.4.0-node22-slim   # مبنية على node:22-slim
    ports: ["3000:3000"]
    environment:
      NODE_OPTIONS: --max-old-space-size=1024
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/healthz"]   # curl مش موجود في slim
      interval: 5s
      timeout: 10s
    # مفيش restart، ومفيش memory limit

  worker:
    image: shop-api:1.4.0-node22-slim
    command: node worker.js
    restart: always
    mem_limit: 512m
    environment:
      NODE_OPTIONS: --max-old-space-size=1024    # أكبر من الـ limit نفسه

// app.js: server حقيقي فيه /healthz. و BLOCK_AT_MS بيقفل الـ event loop شوية، زي JSON.parse لـ file ضخم
import { createServer } from "node:http";

const port = Number(process.env.PORT ?? 3100);
createServer((req, res) => {
  if (req.url === "/healthz") { res.writeHead(200, { "content-type": "application/json" }); return res.end('{"ok":true}'); }
  res.writeHead(404).end();
}).listen(port, () => console.log(`app على ${port}`));

if (process.env.BLOCK_AT_MS) {
  setTimeout(() => {
    const until = Date.now() + Number(process.env.BLOCK_FOR_MS ?? 2000);
    while (Date.now() < until); // الـ process عايش، والـ port مفتوح، بس مفيش رد
  }, Number(process.env.BLOCK_AT_MS));
}

// healthcheck.js: اللي الـ Dockerfile بيشغّله: HEALTHCHECK CMD ["node", "healthcheck.js"]
// من غير curl: الـ image بتاعة Node فيها node أصلًا. exit 0 ← healthy، exit 1 ← فشل
const port = process.env.PORT ?? 3100;
const timeout = Number(process.env.HC_TIMEOUT_MS ?? 2000);
try {
  const res = await fetch(`http://127.0.0.1:${port}/healthz`, { signal: AbortSignal.timeout(timeout) });
  process.exit(res.ok ? 0 : 1);
} catch {
  process.exit(1);
}

# Dockerfile (آخر جزء): الـ healthcheck جُوّه الـ image نفسها
FROM node:22-slim
WORKDIR /app
COPY --chown=node:node . .
USER node
HEALTHCHECK --interval=10s --timeout=3s --retries=3 --start-period=20s \
  CMD ["node", "healthcheck.js"]
CMD ["node", "server.js"]

# على machine فيها Docker:
# docker ps                                   ← STATUS: Up 2 minutes (healthy)
# docker inspect --format '{{json .State.Health}}' api
# docker inspect --format '{{.State.OOMKilled}} {{.State.ExitCode}}' worker
# docker stats                                ← الـ memory قصاد الـ limit