Request যাচাই — Zod দিয়ে schema আর নিরাপদ ইনপুট

১ · Server-এ পৌঁছানো কোনো কিছুই বিশ্বাস করবেন না

ডাকঘরের বাছাই টেবিলে একটি খাম এলো। খামের ওপরে লেখা “জরুরি, সরকারি”। বাছাইকর্মী কি সেই কথা মেনে নেন? না। তিনি ঠিকানা, ডাকটিকিট আর ওজন নিজে দেখেন, কারণ খামের লেখা যে কেউ লিখতে পারে। আপনার server-ও ঠিক এই টেবিল। Request যে-ই পাঠাক, প্রতিটি অক্ষর অচেনা মানুষের লেখা ধরে নিতে হয়।

পর্ব ২১-এ (বড় form — React Hook Form, Zod আর দুই দিকের validation) আপনি Zod schema, safeParse আর browser-server-এ ভাগ করা নিয়ম দেখেছেন। সেখানে মূল কথা ছিল, browser-এর যাচাই সুবিধা, server-এর যাচাই নিরাপত্তা। সেই সিদ্ধান্ত এখানে আবার প্রমাণ করব না। এই পর্ব শুধু পরের প্রশ্নটির উত্তর দেবে: Express server-এ এটি পরিষ্কারভাবে, প্রতিটি route-এ, ভুল না করে কীভাবে লিখবেন?

ভেতরের জগৎ আর বাইরের জগতের মাঝের দাগটিকে বলে trust boundary. দাগের বাইরের সব ডেটা সন্দেহজনক। দাগ পেরোনোর মুহূর্তে একবার ভালো করে যাচাই করলে ভেতরের কোড নিশ্চিন্তে চলে। আর সেই কাজটি করতে হয় চারটি জায়গায়:

এখানে একটি ভুল ধারণা ভাঙা দরকার। অনেকে ভাবেন, handler-এ req.body as Order লিখলেই ডেটা Order হয়ে গেল। তা হয় না। পর্ব ০৬-এ দেখেছেন, TypeScript-এর type compile-এর পরে মুছে যায় (type erasure). as দিয়ে আপনি শুধু compiler-কে একটি প্রতিশ্রুতি দিলেন, আর বাইরের লোক সেই প্রতিশ্রুতি জানেন না। চলার সময়ে পাহারা দিতে পারে কেবল চলমান কোড, অর্থাৎ schema.

পুরো পথে কোন ফটক কী আটকায়, নিচের ছবিতে দেখে নিন। পরের অংশগুলো এই ছবির এক একটি ফটক।

২ · একটি validate(schema) middleware

প্রতিটি handler-এর শুরুতে safeParse আর if লিখলে কাজ হয়, কিন্তু ৪০টি route-এ ৪০ বার একই কোড জমে। কোথাও একবার ভুলে গেলেই ফাঁক। হোটেলের রিসেপশনের কথা ভাবুন: প্রতিটি কক্ষের দরজায় আলাদা করে পরিচয়পত্র দেখা হয় না, এক জায়গায় দেখা হয়। Middleware সেই রিসেপশন। পর্ব ২৬-এ (Middleware) আপনি middleware-এর পাইপলাইন দেখেছেন, এখানে সেই পাইপলাইনে একটি ফটক বসছে।

আগে ভাবনাটি হাতে-কলমে দেখুন। Live বাক্সে npm package আসে না, তাই এখানে Zod নেই। orderRules একটি ছোট শেখার মডেল, আর node:http আসল। chain লাইনটি লক্ষ করুন: Express ভেতরে এমন একটি তালিকাই চালায়।

const http = require('node:http');
const orderRules = {
  phone: v => (typeof v === 'string' && /^01[3-9]\d{8}$/.test(v)) || 'phone: 11 digits',
  qty: v => (Number.isInteger(v) && v >= 1 && v <= 10) || 'qty: 1 to 10',
};
function safeParse(rules, input) {
  const box = Object(input), data = {}, errors = [];
  for (const key in rules) {
    const r = rules[key](box[key]);
    if (r === true) data[key] = box[key]; else errors.push({ path: key, message: r });
  }
  return errors.length ? { success: false, errors } : { success: true, data };
}
const send = (res, code, body) => res.writeHead(code, { Connection: 'close' }).end(JSON.stringify(body));
const validate = (rules) => (req, res, next) => {
  const r = safeParse(rules, req.body);
  if (!r.success) return send(res, 422, { code: 'VALIDATION_FAILED', errors: r.errors });
  req.input = r.data; next();               // শুধু যাচাই করা ডেটা সামনে যায়
};
const createOrder = (req, res) => send(res, 201, { saved: req.input, total: 140 * req.input.qty });
const chain = [validate(orderRules), createOrder];
const server = http.createServer(async (req, res) => {
  let raw = '', i = 0;
  for await (const part of req) raw += part;
  req.body = JSON.parse(raw);
  const next = () => chain[i++](req, res, next); next();
});
server.listen(0, '127.0.0.1', async () => {
  const url = `http://127.0.0.1:${server.address().port}/api/orders`;
  for (const body of [{ phone: '0171', qty: 0 }, { phone: '01712345678', qty: 2 }]) {
    const r = await fetch(url, { method: 'POST', body: JSON.stringify(body) });
    console.log(r.status, await r.text());
  }
  server.close();
});

আসল রূপ: Express 5 আর Zod 4

এবার সত্যিকারের project. লেখার সময়ে Express 5.3.0, Zod 4.6.7, TypeScript 7.0.2 আর Node 24 ব্যবহার করা হয়েছে। Project-এর গঠন আর চালানোর রীতি পর্ব ২৫-এর (Express) মতোই। এই ফাইলটি পুরো কোর্সে বারবার কাজে লাগবে:

import type { RequestHandler } from 'express';
import { z } from 'zod';

type Part = 'params' | 'query' | 'headers' | 'body';
type Schemas = Partial<Record<Part, z.ZodType>>;
type Input<S extends Schemas> = { [K in keyof S]: z.output<S[K] & z.ZodType> };

export function validate<S extends Schemas>(
  schemas: S,
): RequestHandler<any, any, any, any, { input: Input<S> }> {
  const parts = Object.keys(schemas) as Part[];
  return (req, res, next) => {
    if (schemas.body && !req.is('application/json')) {
      return res.status(415).json({ code: 'JSON_REQUIRED', message: 'send application/json' });
    }
    const input: Record<string, unknown> = {};
    const errors: { in: Part; path: string; message: string }[] = [];

    for (const part of parts) {
      const result = schemas[part]!.safeParse(req[part]);
      if (result.success) input[part] = result.data;
      else for (const issue of result.error.issues) {
        errors.push({ in: part, path: issue.path.join('.'), message: issue.message });
      }
    }

    if (errors.length) {
      return res.status(422).json({ code: 'VALIDATION_FAILED', errors });
    }
    res.locals.input = input as Input<S>;
    next();
  };
}

তিনটি সিদ্ধান্ত লক্ষ করুন। এক, চারটি অংশ একসাথে যাচাই হয়, তাই ক্লায়েন্ট একবারেই সব ভুল পান। দুই, in ঘরটি বলে ভুলটি কোন অংশের। তিন, ফল যায় res.locals-এ, req.query-তে নয়। শেষ সিদ্ধান্তের পেছনে একটি আসল crash আছে। অনেক পুরোনো টিউটোরিয়ালে, আর AI-এর কোডে, দেখবেন req.query = parsed. Express 5-এ:

সত্যিকারের run · Express 5.3.0, ES module · ~/bazarghar

{"thrown":"Cannot set property query of #<IncomingMessage> which has only a getter"}

Express 5-এ req.query একটি getter, লেখার পথ নেই। তাই মূল request-কে অক্ষত রেখে যাচাই করা ফল আলাদা জায়গায় রাখাই পরিষ্কার পথ। এখন route-গুলো ছোট হয়ে গেল, আর schema আলাদা ফাইলে:

import { z } from 'zod';

export const productParams = z.object({
  id: z.coerce.number().int().positive(),
});

export const listQuery = z.object({
  page: z.coerce.number().int().min(1).max(1000).default(1),
  limit: z.coerce.number().int().min(1).max(100).default(20),
  sort: z.enum(['price', 'name', 'new']).default('new'),
  q: z.string().trim().max(50).optional(),
});

export const orderBody = z.object({
  phone: z.string().regex(/^01[3-9]\d{8}$/, '১১ সংখ্যার মোবাইল নম্বর দিন'),
  items: z.array(z.object({
    sku: z.string().min(1).max(40),
    qty: z.number().int().min(1).max(10, 'একবারে সর্বোচ্চ ১০টি'),
  })).min(1).max(20, 'সর্বোচ্চ ২০টি লাইন'),
  note: z.string().trim().max(200).optional(),
});

export const idemHeaders = z.object({
  'idempotency-key': z.uuid('Idempotency-Key একটি UUID হতে হবে').optional(),
});

app.use(express.json({ limit: '100kb' }));

app.get('/api/products', validate({ query: listQuery }), (req, res) => {
  const { page, limit, sort, q } = res.locals.input.query;
  res.json({ page, limit, sort, q, offset: (page - 1) * limit });
});

app.post('/api/orders', validate({ headers: idemHeaders, body: orderBody }),
  (req, res) => { /* … */ });

একটি ভালো আর একটি ভুল request পাঠিয়ে দেখা যাক। ভুল bad.json-এ ফোন ছোট, একটি qty ০, একটি qty string "2", আর note একটি সংখ্যা। good.json-এ ডাল ২টি (১৪০ × ২) আর চাল ১টি (৪২০).

সত্যিকারের run · 127.0.0.1 · কিছু header ছাঁটা

$ curl -si -X POST -H 'content-type: application/json' \
    --data-binary @good.json http://127.0.0.1:5827/api/orders
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{"orderId":"BG-1001","total":700}

$ curl -si -X POST -H 'content-type: application/json' \
    --data-binary @bad.json http://127.0.0.1:5827/api/orders
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8

{"code":"VALIDATION_FAILED","errors":[
{"in":"body","path":"phone","message":"১১ সংখ্যার মোবাইল নম্বর দিন"},
{"in":"body","path":"items.0.qty","message":"Too small: expected number to be >=1"},
{"in":"body","path":"items.1.qty","message":"Invalid input: expected number, received string"},
{"in":"body","path":"note","message":"Invalid input: expected string, received number"}]}

(পড়ার সুবিধায় ভুলের তালিকায় লাইন ভাঙা হয়েছে।) items.1.qty লক্ষ করুন। Body-র "2" সংখ্যায় বদলায়নি, কারণ JSON নিজেই সংখ্যা পাঠাতে পারে, তাই body-তে z.number() কড়া থাকে। Coerce শুধু URL-এর জন্য, পরের অংশের বিষয়।

ইংরেজি বার্তাগুলো Zod-এর ডিফল্ট। Field ধরে নিজের বার্তা দিতে পারেন, যেমন ফোনে দেওয়া হয়েছে। Zod 4-এ একটি বাংলা locale-ও আছে: z.config(z.locales.bn()) দিলে সত্যিকারের run-এ এলো অনেক বড়: number <=100 হতে হবে. ক্রেতার চোখে পড়ে এমন ঘরে তবু নিজের লেখা বার্তাই ভালো।

এখন একটি request-কে ধীরে ধীরে অনুসরণ করা যাক। URL /api/products?page=2&limit=10&sort=price, আর শেষে একটি বাড়াবাড়ি request. প্রতিটি ধাপে মানের type-এ চোখ রাখুন।

1app.get('/api/products',2  validate({ query: listQuery }),3  (req, res) => {4    const { page, limit, sort } = res.locals.input.query;5    const offset = (page - 1) * limit;6    res.json({ page, limit, sort, offset });7});

৩ · Params আর query — সবই string, তাই z.coerce

JSON-এ সংখ্যা সংখ্যাই থাকে, কিন্তু URL শুধু লেখা বহন করে। মুদি দোকানের ফর্দের মতো: “চাল ৫” লেখা থাকলেও “৫” একটি লেখা, হিসাব করতে হলে আগে সংখ্যা ভাবতে হয়। z.coerce.number() ঠিক সেই কাজটি করে। একে বলে coercion. ভেতরে সে JavaScript-এর Number(value) ডাকে, ফলে Number-এর সব অদ্ভুত আচরণও সঙ্গে আসে। নিচের বাক্সে আগে সেটি দেখুন, তারপর সীমাসহ একটি ছোট শেখার মডেল।

// z.coerce.number() ভেতরে Number(v) ডাকে, তাই আগে Number-এর আচরণ দেখি
for (const raw of ['2', '', ' 7 ', '1e3', 'abc']) console.log(JSON.stringify(raw), '->', Number(raw));
console.log('Boolean("false") ->', Boolean('false'));

function intParam(raw, { def, min, max }) {
  if (raw === undefined) return { value: def };
  const n = Number(raw);
  if (!Number.isInteger(n)) return { error: 'expected integer' };
  if (n < min) return { error: `min ${min}` };
  if (n > max) return { error: `max ${max}` };
  return { value: n };
}
const pageRule = { def: 1, min: 1, max: 1000 };
const limitRule = { def: 20, min: 1, max: 100 };

function list(path) {
  const q = new URL(path, 'http://x').searchParams;
  const get = (k) => (q.has(k) ? q.get(k) : undefined);   // key নেই মানে undefined
  const page = intParam(get('page'), pageRule);
  const limit = intParam(get('limit'), limitRule);
  if (page.error || limit.error) return `422 page: ${page.error ?? 'ok'}, limit: ${limit.error ?? 'ok'}`;
  return `200 page=${page.value} limit=${limit.value} offset=${(page.value - 1) * limit.value}`;
}
for (const path of ['/p', '/p?page=3&limit=20', '/p?limit=100000', '/p?page=0', '/p?page=abc&limit=2.5']) {
  console.log(path.padEnd(24), list(path));
}

এই আচরণ আসল Zod-এ কেমন? মডেল নয়, Zod 4.6.7 চালিয়ে পাওয়া ফল:

সত্যিকারের run · z.coerce · Zod 4.6.7

Express-এর route-এ সত্যিকারের run-এ ?page= ধরা পড়ল min(1)-এ, কারণ "" হলো 0. কিন্তু min না থাকলে, যেমন minPrice ঘরে, ?minPrice= নীরবে “০ টাকার ওপরে” হয়ে যেত।

একই key দুবার, আর array

Express 5-এর ডিফল্ট query parser সরল। সত্যিকারের run-এ ?a[b]=1&c=1&c=2 দিল {"a[b]":"1","c":["1","2"]}. বন্ধনীর nested object আর হয় না (Express 4-এ হতো), কিন্তু একই key দুবার এলে array হয়। তাই ?q=a&q=b-তে handler হঠাৎ array পেতে পারে। Schema থাকলে সমস্যা নেই, সত্যিকারের run-এ উত্তর এলো expected string, received array, আর ?page=1&page=2-এ received NaN.

Pagination-এর সীমা: একটি হিসাব

Pagination-এর ওপরের সীমা কোনো সৌন্দর্য নয়, এটি আপনার সবচেয়ে সস্তা সুরক্ষা। ধরে নিন বাজারঘরে ২,০০,০০০টি পণ্য, আর প্রতিটি JSON সারি গড়ে ৫০০ byte.

page-এরও সীমা রাখা হয়েছে ১০০০, কারণ page=1000&limit=100 মানে offset (১০০০ − ১) × ১০০ = ৯৯,৯০০. Database-কে এতগুলো সারি পেরিয়ে যেতে হয়। এর খরচ আর cursor pagination আসবে পর্ব ৩৪-এ (Pagination, filter আর sort).

৪ · অজানা key আর mass assignment

একজন ক্রেতা নিজের প্রোফাইলে নাম বদলাচ্ছেন। Browser পাঠায় { name }. কিন্তু কেউ curl-এ লিখলেন { name, role: 'admin', walletBalance: 999999 }. Handler-এ যদি থাকে Object.assign(user, req.body), তাহলে ভেতরে যা ঘটে তার নাম mass assignment: client-এর সব key মডেলে বসে গেল। ফরমে যে ঘর ছিলই না, সেটিও বদলে গেল।

Zod-এর z.object ডিফল্টে অচেনা key ফলাফলে তোলে না। এই আচরণটিই এই ভুলের ওষুধ, তবে শর্ত আছে: handler-কে req.body নয়, schema-র ফল ব্যবহার করতে হবে। সত্যিকারের run-এ একই payload দুটি route-এ পাঠিয়ে দেখুন।

{ "name": "Rahima",
  "role": "admin",
  "walletBalance": 999999 }

app.patch('/bad/me', (req, res) => {
  Object.assign(user, req.body);
  res.json(user);
});

{"id":7,"name":"Rahima",
 "role":"admin","walletBalance":999999,
 "city":"dhaka"}

profileBody = z.object({
  name: z.string().trim().min(2).max(60),
  city: z.enum([...]).optional(),
})
// ফল: { name: 'Rahima' }

app.patch('/api/me', validate({ body: profileBody }), …
  Object.assign(user, res.locals.input.body);

{"id":7,"name":"Rahima",
 "role":"customer","walletBalance":50,"city":"dhaka"}

await repo.updateProfile(id, {
  name: input.name,      // ঘরগুলো নাম ধরে লেখা
  city: input.city,
});

অচেনা key নিয়ে কী করবেন, Zod তিনটি পথ দেয়। একই ডেটা { name: 'Rahima', role: 'admin' } তিন রকম schema-য়:

সত্যিকারের run · Zod 4.6.7

z.object       {"name":"Rahima"}                    // strip: নীরবে বাদ
z.strictObject ERR Unrecognized key: "role"          // strict: বাতিল
z.looseObject  {"name":"Rahima","role":"admin"}     // loose: সব রাখে

Strict বাড়তি key পেলে ভুল ধরিয়ে দেয়, তাই নিজের client-এর বানান ভুলও ধরা পড়ে। Strip নতুন-পুরোনো client-কে সহজে চলতে দেয়। দুটিই নিরাপদ, পছন্দটি নিয়ে আলোচনা আছে ভাবনার প্রশ্ন ০৩-এ। looseObject কোনো database-লেখার পথে ব্যবহার করবেন না। নিচের মডেলে পার্থক্যটি, আর একটি বাড়তি ফাঁদ prototype pollution দেখুন।

const newUser = () => ({ id: 7, name: 'Rahima', role: 'customer', isAdmin: false });
const body = { name: 'Rahima Begum', role: 'admin', isAdmin: true };

// ভুল পথ: client যা পাঠাল, সব বসিয়ে দেওয়া
const hurt = Object.assign(newUser(), body);
console.log('blind   ', JSON.stringify(hurt));

// strip: চেনা key নতুন object-এ তোলে, বাকি নীরবে বাদ
const shape = { name: 'string', city: 'string?' };
function strip(input) {
  const out = {};
  for (const key in shape) if (key in input) out[key] = input[key];
  return out;
}
const safe = Object.assign(newUser(), strip(body));
console.log('strip   ', JSON.stringify(safe));

// strict: অচেনা key পেলেই পুরো request বাতিল
function strict(input) {
  const unknown = Object.keys(input).filter((key) => !(key in shape));
  return unknown.length ? { status: 422, unknown } : { status: 200, data: strip(input) };
}
console.log('strict  ', JSON.stringify(strict(body)));
console.log('strict  ', JSON.stringify(strict({ name: 'Rahima Begum' })));

// Object.assign আর __proto__: JSON থেকে আসা key নিজের key হয়
const evil = JSON.parse('{"name":"R","__proto__":{"isAdmin":true}}');
const target = Object.assign({}, evil);
console.log('proto   ', Object.keys(evil), 'target.isAdmin =', target.isAdmin);
console.log('stripped', Object.keys(strip(evil)), 'isAdmin =', strip(evil).isAdmin);

৫ · সীমা — size, array আর string

আকৃতি ঠিক হলেই ডেটা নিরাপদ নয়। একটি নিখুঁত JSON-এ ২ লাখ সারি থাকতে পারে। গুদামের দরজায় “মাল আসবে” বলা যথেষ্ট নয়, ট্রাকের মাপও বলতে হয়। Server-এর CPU আর memory সীমিত, তাই প্রতিটি ইনপুটের ওপরে একটি ছাদ লাগে। ক্রম এখানে জরুরি: সবচেয়ে সস্তা পরীক্ষা আগে।

1. Byte-এর সীমা, parse-এর আগে: express.json({ limit }), যাকে বলে body limit. ডিফল্ট 100kb, সত্যিকারের run-এ যা ১,০২,৪০০ byte.
2. Array-র দৈর্ঘ্য: z.array(…).max(20).
3. String-এর দৈর্ঘ্য: .max(200), প্রতিটি লেখার ঘরে।
4. সংখ্যার সীমা: .min(), .max().

নিচের বাক্সে দেখুন, কোন request কতদূর পৌঁছায়। parsed গুনছে JSON.parse কতবার চলল।

const http = require('node:http');
const LIMIT = 100 * 1024;      // express.json-এর ডিফল্ট 100kb
const MAX_ITEMS = 20;
let parsed = 0;

const server = http.createServer(async (req, res) => {
  const reply = (code, msg) => res.writeHead(code, { Connection: 'close' }).end(msg);
  if (Number(req.headers['content-length']) > LIMIT) {
    req.resume();              // শরীর ফেলে দেওয়া হচ্ছে, জমছে না
    return reply(413, `too large, limit ${LIMIT} bytes`);
  }
  const chunks = [];
  for await (const c of req) chunks.push(c);
  const body = JSON.parse(Buffer.concat(chunks));
  parsed++;
  if (!Array.isArray(body.items)) return reply(422, 'items: expected array');
  if (body.items.length > MAX_ITEMS) return reply(422, `items: max ${MAX_ITEMS}`);
  reply(201, `ok, ${body.items.length} lines`);
});

server.listen(0, '127.0.0.1', async () => {
  const url = `http://127.0.0.1:${server.address().port}/api/orders`;
  for (const n of [3, 21, 200000]) {
    const items = Array.from({ length: n }, () => ({ sku: 'dal-1kg', qty: 1 }));
    const text = JSON.stringify({ items });
    const r = await fetch(url, { method: 'POST', body: text });
    console.log(`${n} lines, ${text.length} bytes ->`, r.status, await r.text(), `| parsed so far: ${parsed}`);
  }
  server.close();
});

আসল Express আর Zod-এ সত্যিকারের ফল একই। ৫২ লাখ byte-এ {"code":"TOO_LARGE","message":"body limit is 102400 bytes"}, status 413. ২১ সারিতে 422, সর্বোচ্চ ২০টি লাইন. একটি স্থানীয় run-এ এই ৫২ লাখ byte-এর JSON.parse নিল প্রায় ২৬ ms, যা body limit পুরো বাঁচিয়ে দিল। সংখ্যাটি একটি মেশিনের, সাধারণ ফল নয়।

কতটুকু সীমা যথেষ্ট? হিসাব করে নিন

অনুমান নয়, আপনার সবচেয়ে বড় বৈধ request মাপুন। UTF-8-এ বাংলা অক্ষর সাধারণত ৩ byte, কিন্তু JavaScript-এর .length, তাই Zod-এর .max()-ও, গোনে UTF-16 একক। সত্যিকারের run-এ “রহিমা”-র length ৫, byte ১৫. 😀-এর length ২, byte ৪.

তাই ডিফল্টের ওপর ভরসা না করে route অনুযায়ী ছোট সীমা দেওয়া যায়, যেমন order-এর route-এ express.json({ limit: '8kb' }). তখন বিশ্বব্যাপী app.use-এ না রেখে route-এর আগে বসাতে হবে। File upload আলাদা পথ, যা আসবে পর্ব ৩০-এ (File upload).

৬ · ভুলের একই ছাঁচ — 400, 413, 415, 422

Frontend-এর কোড একটিই। Server যদি কখনো { error }, কখনো { message }, কখনো HTML পাঠায়, তাহলে client-এ প্রতিটির আলাদা শর্ত লাগে। ব্যাংকের ফরম ফেরত দেওয়ার মতো: কর্মকর্তা প্রতিবার একই ছকে লেখেন কোন ঘরে কী ভুল। এই পর্বের প্রতিটি ফিরতি উত্তরে তাই code আছে, আর যাচাইয়ের ভুলে errors তালিকা। পর্ব ২১-এর form ঠিক এই path ধরেই setError ডাকে, তাই ভুলটি সঠিক ঘরে বসে।

একটি ছোট কথা: RFC 9110 (২০২২) 413 আর 422-এর নাম দিয়েছে Content Too Large আর Unprocessable Content, কিন্তু Node এখনো পুরোনো নাম ছাপে, তাই আউটপুটে Payload Too Large আর Unprocessable Entity দেখবেন। 422 এসেছিল WebDAV-এর RFC 4918 (২০০৭) থেকে।

400 না 422? এই নিয়ে দুই মতই চালু। অনেক API সব ইনপুটের ভুলে 400 দেয়, যা সহজ। এই কোর্সে 400 মানে পড়াই যায়নি, 422 মানে পড়া গেছে কিন্তু নিয়ম ভেঙেছে। দলে যেটি ঠিক করবেন, সব route-এ সেটিই রাখুন। ধারাবাহিকতাই আসল। নকশার যুক্তি আছে পর্ব ৩৩-এ (Status code আর error format), আর system design-এর REST API পর্বে.

400 আর 413-র ভুল validate-এ পৌঁছায় না, কারণ সেগুলো express.json-এর ভেতরেই ঘটে আর error middleware-এ যায়। Handler না থাকলে Express নিজের HTML পাতা পাঠাত, যা এই ছাঁচ ভাঙে। তাই একটি ছোট error middleware লাগে:

const onError: ErrorRequestHandler = (err, _req, res, next) => {
  if (res.headersSent) return next(err);
  if (err.type === 'entity.parse.failed') {
    return res.status(400).json({ code: 'BAD_JSON', message: 'body is not valid JSON' });
  }
  if (err.type === 'entity.too.large') {
    return res.status(413).json({ code: 'TOO_LARGE', message: `body limit is ${err.limit} bytes` });
  }
  res.status(500).json({ code: 'INTERNAL', message: 'something went wrong' });
};
app.use(onError);

সত্যিকারের run · একই server · header ছাঁটা

$ curl -si -X POST -H 'content-type: application/json' -d '{bad' …/api/orders
HTTP/1.1 400 Bad Request
{"code":"BAD_JSON","message":"body is not valid JSON"}

$ curl -si -X POST -H 'content-type: text/plain' --data-binary @good.json …/api/orders
HTTP/1.1 415 Unsupported Media Type
{"code":"JSON_REQUIRED","message":"send application/json"}

$ curl -si -X POST … -H 'Idempotency-Key: 123' --data-binary @good.json …/api/orders
HTTP/1.1 422 Unprocessable Entity
{"code":"VALIDATION_FAILED","errors":[{"in":"headers","path":"idempotency-key",
"message":"Idempotency-Key একটি UUID হতে হবে"}]}

$ curl -si …/api/products/abc
HTTP/1.1 422 Unprocessable Entity
{"code":"VALIDATION_FAILED","errors":[{"in":"params","path":"id",
"message":"Invalid input: expected number, received NaN"}]}

$ curl -si …/api/products/99
HTTP/1.1 404 Not Found
{"code":"NOT_FOUND","message":"product not found"}

415 চেকটি প্রথমে কেন? প্রথম সংস্করণে সেটি ছিল না। তখন text/plain-এ পাঠালে সত্যিকারের উত্তর ছিল {"in":"body","path":"","message":"Invalid input: expected object, received undefined"}. Content-Type না মিললে express.json body ছোঁয় না, আর Express 5-এ req.body তখন undefined, পুরোনো Express-এর মতো {} নয়। validate না থাকলে req.body.items সরাসরি crash করত। এই ছাঁচকে একটি মানে সাজায় Problem Details (RFC 9457), যা আসবে পর্ব ৩৩-এ। Central error handler-এর পূর্ণ রূপ পরের পর্বে।

৭ · Type schema থেকে, আর আকৃতি বনাম ব্যবসার নিয়ম

validate-এর জেনেরিক কোডটি এতক্ষণ চুপচাপ একটি বড় উপহার দিচ্ছিল। Type inference-এর ফলে handler-এর res.locals.input.body-এর type আপনাকে লিখতে হয় না, schema থেকেই আসে। হাতে কোনো interface Order নেই, অথচ ভুল করলে সঙ্গে সঙ্গে ধরা পড়ে:

app.post('/api/orders', validate({ body: orderBody }), (req, res) => {
  const { items, discount } = res.locals.input.body;
  const first: string = items[0].qty;
  res.json({ first, discount });
});

সত্যিকারের run · TypeScript 7.0.2 · npx tsc --noEmit

src/typedemo.ts(9,18): error TS2339: Property 'discount' does not exist on type
  '{ phone: string; items: { sku: string; qty: number; }[]; note?: string | undefined; }'.
src/typedemo.ts(10,9): error TS2322: Type 'number' is not assignable to type 'string'.

নিয়ম আর type এখন একটিই জিনিস, তাই আলাদা হতে পারে না। একটি সূক্ষ্মতা: coerce করা schema-র দুই মুখ। z.output<typeof listQuery>-এ page হলো number, কিন্তু z.input-এ সেটি unknown, কারণ coerce যেকোনো কিছু নিতে রাজি। সত্যিকারের run-এ { page: 'abc' } z.input-এ পাস করল, z.output-এ করল না। z.infer মানে z.output. Handler-এ তাই output-ই চাই।

কোন নিয়ম কোথায়

ব্যাংকের চেক কাউন্টার ভাবুন। কেরানি প্রথমে দেখেন তারিখ আছে, অঙ্ক আর কথায় টাকা মিলছে, স্বাক্ষরের ঘর ভরা। এটি আকৃতি: চেকটি দেখেই বলা যায়, হিসাব-খাতা লাগে না। তারপর তিনি খাতা খুলে দেখেন হিসাবে টাকা আছে কি না। এটি ব্যবসার নিয়ম: ডেটা বৈধ, কিন্তু এখনকার অবস্থার ওপর উত্তর নির্ভর করে।

তিনটি request একই route-এ পাঠিয়ে দেখুন। ডালের মজুত ২টি। db গুনছে database-এর কাজ।

1// route: আকৃতি2validate({ body: orderBody })3// service: ব্যবসার নিয়ম4const stock = await repo.stock(sku);5if (qty > stock) throw new OutOfStock(sku, stock);6await repo.saveOrder(order);

Service-কে কীভাবে route থেকে আলাদা করবেন, তা আসবে পর্ব ২৯-এ (Backend-এর গঠন). শেষ নিয়মটি মনে রাখবেন: database-এর constraint-ও একটি যাচাই, সবচেয়ে শেষের, আর সবচেয়ে নির্ভরযোগ্য।

৮ · Sanitize না validate — একটি জমা review-এর HTML

দুটি শব্দ প্রায়ই গুলিয়ে যায়। Validate মানে ডেটা দেখে হ্যাঁ বা না বলা, ডেটা বদলানো নয়। Sanitize মানে ডেটা বদলে নিরাপদ করা। আর তৃতীয়টি, escape, মানে ডেটা না বদলে যেখানে বসছে সেখানকার ভাষায় নিরীহভাবে লেখা। .trim() ছোট একটি sanitize, যা নির্দোষ। কিন্তু ইনপুট থেকে “বিপজ্জনক” অক্ষর কেটে ফেলা ভুল পথ।

কেন? বাজারঘরের একটি review পড়ুন, যেখানে শেষের অংশটি পরীক্ষার জন্য বসানো নিরীহ লেখা:

দাম <১০০ টাকা, ভালো ডাল <script>alert(1)</script>

< অক্ষরটি নিষিদ্ধ করলে “দাম <১০০ টাকা” লেখাটি নষ্ট হয়। Schema-র কাছে এটি একটি বৈধ string, ৩ থেকে ২,০০০ অক্ষরের মধ্যে, তাই যাচাই ঠিকভাবেই পাস করল। বিপদ যাচাইয়ে নয়, ব্যবহারে। Database-এ HTML কোনো কোড নয়, শুধু লেখা। এই লেখা কোনো পাতায় escape ছাড়া বসলে তবেই browser সেটিকে script ভেবে চালায়। একে বলে stored XSS. একই জমা review, দুটি পাতায়:

const escapeHtml = (s: string) => s.replace(/[&<>"']/g, (c) => ({
  '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
}[c]!));

// ভুল পাতা: শেখার জন্য
app.get('/bad/reviews', (_req, res) => {
  res.type('html').send(`<ul>${reviews.map((r) => `<li>${r.text}</li>`).join('')}</ul>`);
});

app.get('/reviews', (_req, res) => {
  res.type('html').send(`<ul>${reviews.map((r) => `<li>${escapeHtml(r.text)}</li>`).join('')}</ul>`);
});

সত্যিকারের run · একই জমা review · header ছাঁটা

$ curl -si …/api/products/2/reviews -X POST -H 'content-type: application/json' --data-binary @review.json
HTTP/1.1 201 Created
{"saved":{"rating":5,"text":"দাম <১০০ টাকা, ভালো ডাল <script>alert(1)</script>"}}

$ curl -si …/bad/reviews
HTTP/1.1 200 OK
<ul><li>দাম <১০০ টাকা, ভালো ডাল <script>alert(1)</script></li></ul>

$ curl -si …/reviews
HTTP/1.1 200 OK
<ul><li>দাম &lt;১০০ টাকা, ভালো ডাল &lt;script&gt;alert(1)&lt;/script&gt;</li></ul>

লেখাটি অক্ষত রইল, “<১০০” পাঠকের চোখে ঠিকই দেখা যাবে, অথচ script আর script রইল না। মনে রাখুন, পর্ব ০৮-এ দেখেছেন React-এর {text} নিজে থেকেই এই কাজ করে। তাই dangerouslySetInnerHTML ছাড়া React পাতা এই ভুল থেকে সুরক্ষিত। Express-এ template engine ব্যবহার করলে তার ডিফল্ট escape চালু আছে কি না দেখে নিন।

// মান সব সময় আলাদা, SQL লেখায় নয়
const rows = await db.query(
  `SELECT * FROM products WHERE price < $1 ORDER BY ${SORT_COLUMNS[sort]} LIMIT $2 OFFSET $3`,
  [maxPrice, limit, offset],
);

// ORDER BY-তে placeholder চলে না, তাই schema-র enum + এই তালিকা
const SORT_COLUMNS = { price: 'price', name: 'name', new: 'created_at' } as const;

এখানে যাচাই আর parameterized query একসাথে কাজ করছে। Column-এর নাম placeholder-এ বসে না, তাই sort-এর z.enum আর SORT_COLUMNS মিলে allowlist হলো। এটি বিস্তারিত আছে injection প্রতিরক্ষা পর্বের dynamic ORDER BY অংশে। যাচাই একটি বাড়তি স্তর, প্রধান প্রতিকার নয়: text-এর মতো মুক্ত লেখায় ' বৈধ অক্ষর, তাকে আটকানো যায় না, parameterized query-ই সেখানে একমাত্র ঠিক পথ।

৯ · Schema থেকে JSON Schema আর OpenAPI

আপনার Zod schema এখন যাচাই আর type দুটোই দিচ্ছে। Python-এর কোনো সেবা, মোবাইল দল, বা API-র docs কিন্তু TypeScript পড়ে না। Zod 4-এ schema থেকে ভাষানিরপেক্ষ JSON Schema বানানো যায় z.toJSONSchema() দিয়ে, কোনো বাড়তি package ছাড়াই।

সত্যিকারের run · Zod 4.6.7 · ছোট করে সাজানো · z.toJSONSchema(item)

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "qty": { "type": "integer", "minimum": 1, "maximum": 10 },
  "sku": { "type": "string", "maxLength": 40 }
 },
 "required": [ "qty", "sku" ],
 "additionalProperties": false
}

additionalProperties: false লক্ষ করুন। Runtime-এ z.object অচেনা key নীরবে বাদ দেয়, কিন্তু এই ডিফল্ট রূপটি ডেটার output-এর বর্ণনা। { io: 'input' } দিলে ইনপুটের রূপ আসে, যেখানে সত্যিকারের run-এ default দেওয়া ঘরগুলো required-এ থাকল না। Docs বানানোর সময় তাই ঠিক দিকটি বেছে নিন।

পরের ধাপ OpenAPI, যা পুরো API-র চুক্তি। লেখার সময়ে zod-openapi (6.0.2) আর @asteasolutions/zod-to-openapi (9.1.0) ধরনের package-গুলো Zod 4-কে peer হিসেবে দেখায়, যা npm view দিয়ে দেখা হয়েছে। এগুলো এখানে চালানো হয়নি, উদাহরণ হিসেবে নাম দেওয়া হলো। OpenAPI-র পুরো আলোচনা পর্ব ৩৫-এ (Versioning আর OpenAPI), আর typed client পর্ব ৩৭-এ।

১০ · AI-এর যুগে request যাচাই

AI-এর লেখা Express কোডে route চলে, ভালো request-ও পাস করে। সমস্যা ধরা পড়ে ভুল request-এ, যা সে কখনো চালায়নি। পুরোনো টিউটোরিয়াল থেকে শেখা কোড নতুন version-এ crash করে, এই পর্বের দুটি উদাহরণ তারই সত্যিকারের প্রমাণ।

AI-এর লেখা route হাতে পেলে

• Express আর Zod-এর version দেখে official docs-এর সঙ্গে API মিলিয়েছি
• ভুল JSON, ভুল type, বাড়তি isAdmin, বিশাল array, ?limit=1000000 নিজে পাঠিয়েছি
• Handler-এ কোথাও req.body বা req.query সরাসরি নেই, diff পড়ে দেখেছি
• সব ভুলের উত্তর এক ছাঁচে, 500 বা stack trace আসেনি
• ভুল request-এর জন্য অন্তত একটি test লিখেছি, ভালো request-এর পাশাপাশি
• AI-কে কোনো আসল secret বা গ্রাহকের ডেটা দিইনি