HTTP من جُوّه: الـ methods والـ status codes والـ headers

أهلًا بيك في قسم HTTP و Express. قبل أي framework، لازم تفهم HTTP نفسه، لأن كل حاجة فوقه مبنية عليه. والمفاجأة: HTTP one point one مجرد كلام مكتوب بين جهازين. هنعمل server بـ node colon http، وهنكلمه من غير متصفح، بـ socket خام، ونكتب الـ request بإيدينا: سطر أول: الـ method والـ path والإصدار. وبعده headers. وبعده سطر فاضي، ومعناه: خلصت. نشغّل.

import http from "node:http";
import net from "node:net";

const server = http.createServer((req, res) => {
  res.setHeader("Content-Type", "text/plain; charset=utf-8");
  res.end("أهلًا");
});

server.listen(3000, () => {
  // client بإيدينا: بنكتب الـ request كنص على socket
  const socket = net.connect(3000, "localhost", () => {
    socket.write("GET /hello HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n");
  });
  let raw = "";
  socket.on("data", (d) => (raw += d));
  socket.on("end", () => {
    console.log(raw.replace(/^Date: .*\r\n/m, ""));
    server.close();
  });
});

$ node server.js
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Connection: close
Content-Length: 10

أهلًا

ده الـ response الخام، زي ما بيمشي على الشبكة. أول سطر: status line: الإصدار، و two hundred، و OK. بعده headers: Content-Type اللي إحنا حطيناه، و Content-Length بعدد الـ bytes، وخد بالك إنها عشرة مش خمسة، لأن الحروف عربي. وبعدين سطر فاضي. وبعدين الـ body. كل framework، Express أو غيره، في الآخر بيكتب الكلام ده.

الـ methods. كل method ليها معنى، والـ clients والـ caches والـ proxies بيعتمدوا على المعنى ده. GET: هات، وما بتغيّرش حاجة، واسمها safe. POST: اعمل حاجة جديدة. PUT: استبدل الحاجة كلها. PATCH: عدّل جزء. DELETE: امسح. وفيه كلمة مهمة: idempotent، يعني لو بعتّه مرة أو عشرة، النتيجة واحدة. GET و PUT و DELETE كده، و POST لا: كل مرة بيعمل حاجة جديدة. وده بيفرق جامد في الـ retry: الـ client يقدر يعيد الـ idempotent بأمان. server صغير لـ items، بـ node colon http من غير مكتبات، علشان نشوف كل قرار بعينينا. send بتكتب الـ status والـ headers والـ JSON. readJson بتقرا الـ body chunks، لأن الـ request نفسه stream. GET للكل ولواحد. POST بيتأكد إن الـ Content-Type JSON، وإلا four fifteen. ولو name ناقص four hundred. ولو تمام two oh one، ومعاه header اسمه Location فيه مكان الحاجة الجديدة. DELETE بيرد two oh four، يعني تمام ومفيش body. وأي method تانية four oh five، ومعاه Allow.

نشغّل ونبعت requests، وهنطبع الـ headers كمان.

import http from "node:http";

const items = new Map([[1, { id: 1, name: "Node" }]]);
let nextId = 2;

function send(res, status, body, headers = {}) {
  res.writeHead(status, { "Content-Type": "application/json", ...headers });
  res.end(body === undefined ? undefined : JSON.stringify(body));
}

async function readJson(req) {
  let raw = "";
  for await (const chunk of req) raw += chunk;
  return JSON.parse(raw);
}

const server = http.createServer(async (req, res) => {
  const url = new URL(req.url, "http://localhost");
  const match = url.pathname.match(/^\/items(?:\/(\d+))?$/);
  if (!match) return send(res, 404, { error: "مش موجود" });
  const id = match[1] && Number(match[1]);

  if (req.method === "GET" && !id) return send(res, 200, [...items.values()]);
  if (req.method === "GET") {
    const item = items.get(id);
    return item ? send(res, 200, item) : send(res, 404, { error: "مش موجود" });
  }
  if (req.method === "POST" && !id) {
    if (req.headers["content-type"] !== "application/json") {
      return send(res, 415, { error: "ابعت JSON" });
    }
    const body = await readJson(req);
    if (!body.name) return send(res, 400, { error: "name مطلوب" });
    const item = { id: nextId++, name: body.name };
    items.set(item.id, item);
    return send(res, 201, item, { Location: `/items/${item.id}` });
  }
  if (req.method === "DELETE" && id) {
    items.delete(id);
    return send(res, 204);
  }
  send(res, 405, { error: "method مش مسموح" }, { Allow: id ? "GET, DELETE" : "GET, POST" });
});

server.listen(3000, () => console.log("http://localhost:3000"));

$ node server.js
http://localhost:3000

→ GET /items
← 200 OK
[
  {
    "id": 1,
    "name": "Node"
  }
]

→ POST /items
  {"name":"PostgreSQL"}
← 201 Created
  connection: keep-alive
  content-type: application/json
  keep-alive: timeout=5
  location: /items/2
  transfer-encoding: chunked
{
  "id": 2,
  "name": "PostgreSQL"
}

→ POST /items
  {}
← 400 Bad Request
{
  "error": "name مطلوب"
}

→ POST /items
  name=Redis
← 415 Unsupported Media Type
{
  "error": "ابعت JSON"
}

→ GET /items/9
← 404 Not Found
{
  "error": "مش موجود"
}

→ PUT /items
← 405 Method Not Allowed
  allow: GET, POST
  connection: keep-alive
  content-type: application/json
  keep-alive: timeout=5
  transfer-encoding: chunked
{
  "error": "method مش مسموح"
}

→ DELETE /items/2
← 204 No Content

GET رجّعت الـ list. POST رجّعت two oh one، و location slash items slash two. من غير name: four hundred. بـ text plain: four fifteen، Unsupported Media Type. item مش موجود: four oh four. PUT على الـ list: four oh five، و allow بيقول المسموح. و DELETE: two oh four. كل رقم هنا بيقول للـ client حاجة دقيقة، يقدر يتصرف على أساسها من غير ما يقرا الرسالة.

أكواد الـ status، أهم حاجة تحفَظها. two hundreds: نجح. three hundreds: روح حتة تانية، أو استخدم اللي عندك. four hundreds: غلطة الـ client. five hundreds: غلطة الـ server. والأكواد اللي الناس بتلخبط فيها: four oh one: مش عارفك، سجّل دخول. four oh three: عارفك، بس مش مسموحلك. four oh nine: conflict، زي إيميل متسجل قبل كده. four twenty two: الـ JSON سليم بس القيم غلط. four twenty nine: كتير، استنى. five oh three: مش متاح دلوقتي، جرّب بعدين. التحدي: conditional GET بـ ETag. الكورس عنده version، والـ ETag هو بصمة النسخة دي. الـ client بيبعت آخر ETag شافه في header اسمه If-None-Match. لو لسه هو هو: three oh four، يعني استخدم اللي عندك، ومن غير body، فبنوفر bandwidth. لو اتغيّر: two hundred بالجديد. و HEAD: نفس الـ headers من غير body. وأي method تانية four oh five. حالات الاختبار الخمسة في الكومنت.

الحل. أي path غير slash course: four oh four. الـ etag من الـ version بالـ quotes. أي method غير GET و HEAD: four oh five ومعاها Allow. لو If-None-Match مطابق: three oh four بالـ ETag بس. وغير كده two hundred بالـ headers، والـ body بس لو مش HEAD. نشغّل بالخمس حالات.

import http from "node:http";

const course = { id: 1, title: "Node.js", version: 3 };

const server = http.createServer((req, res) => {
  if (req.url !== "/course") {
    res.writeHead(404);
    return res.end();
  }
  const etag = `"v${course.version}"`;
  if (req.method !== "GET" && req.method !== "HEAD") {
    res.writeHead(405, { Allow: "GET, HEAD" });
    return res.end();
  }
  if (req.headers["if-none-match"] === etag) {
    res.writeHead(304, { ETag: etag });
    return res.end();
  }
  res.writeHead(200, {
    "Content-Type": "application/json",
    ETag: etag,
    "Cache-Control": "no-cache",
  });
  res.end(req.method === "HEAD" ? undefined : JSON.stringify(course));
});

server.listen(3000, () => console.log("http://localhost:3000"));

$ node server.js
http://localhost:3000

→ GET /course
← 200 OK
  cache-control: no-cache
  connection: keep-alive
  content-type: application/json
  etag: "v3"
  keep-alive: timeout=5
  transfer-encoding: chunked
{
  "id": 1,
  "title": "Node.js",
  "version": 3
}

→ GET /course
← 304 Not Modified

→ GET /course
← 200 OK
{
  "id": 1,
  "title": "Node.js",
  "version": 3
}

→ HEAD /course
← 200 OK

→ DELETE /course
← 405 Method Not Allowed
  allow: GET, HEAD
  connection: keep-alive
  keep-alive: timeout=5
  transfer-encoding: chunked

two hundred بالـ etag و cache-control. بنفس الـ ETag: three oh four، Not Modified، ومفيش body. بـ ETag قديم: two hundred بالجديد. HEAD: two hundred من غير body. و DELETE: four oh five و allow. المتصفحات والـ CDNs بتعمل الحوار ده لوحدها لو الـ server بيبعت ETag، وده من أرخص طرق تسريع أي API. الدرس الجاي: Express، و الـ routing ومعاملات الـ paths.