Route handler আর middleware — Next.js-এর backend

১ · Next.js-এর ভেতরেই backend — route.ts কী

“বাজারঘর”-এর পাতাগুলো এখন Next.js-এ। কিন্তু দোকানের কাজ শুধু পাতা দেখানো নয়। মোবাইল অ্যাপকে পণ্যের তালিকা দিতে হয়। পেমেন্ট সফল হলে payment gateway নিজে এসে খবর দেয়। যোগাযোগের form-এর ডেটা নিতে হয়। এসবের জন্য পাতা নয়, JSON বা সাধারণ HTTP উত্তর লাগে। মডিউল ৪-এ এই কাজ করেছিলেন Express দিয়ে। Next.js-এ একই কাজ হয় route handler দিয়ে।

নিয়মটি সরল। app ফোল্ডারের ভেতরে যে ফোল্ডারে route.ts রাখবেন, সেই path-এ একটি API তৈরি হবে। ফাইলে HTTP method-এর নামে ফাংশন export করুন: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. Route handler প্রথম আসে Next.js 13.2-এ (২০২৩), App Router-এর অংশ হিসেবে। পুরোনো Pages Router-এর pages/api এর পূর্বসূরি। File-ভিত্তিক routing-এর বিস্তার পর্ব ৫১-এ (Next.js App Router) দেখবেন; এখানে শুধু API-র দিকটি।

import { NextRequest } from 'next/server';
import { db } from '@/lib/store';

export async function GET(request: NextRequest) {
  const q = request.nextUrl.searchParams.get('q')?.toLowerCase() ?? '';
  const items = db.products.filter((p) => p.name.toLowerCase().includes(q));
  return Response.json({ items, count: items.length });
}

এখানে দুটি জিনিস Express থেকে আলাদা। প্রথমত, ফাংশন একটি Request নেয় আর একটি Response ফেরত দেয়; res.send() ডাকার কিছু নেই। দ্বিতীয়ত, এই Request আর Response Next.js-এর বানানো নয়। এগুলো ব্রাউজারের Fetch API-র সেই একই class, যা WHATWG-এর Fetch মানে লেখা, আর Node.js 18 থেকে global হিসেবে পাওয়া যায়। Next.js শুধু এর ওপর NextRequest (বাড়তি nextUrl, cookies) আর NextResponse (বাড়তি redirect, rewrite, cookies) দেয়। সাধারণ কাজে Web-এর নিজের class-ই যথেষ্ট।

একটি নিয়ম মনে রাখুন: একই path-এ page.tsx আর route.ts দুটি একসাথে থাকতে পারে না। app/page.tsx আর app/route.ts সংঘাত; app/page.tsx আর app/api/route.ts ঠিক আছে। তাই প্রচলিত রীতি হলো API-গুলো app/api/...-এর নিচে রাখা। Route handler layout-এ অংশ নেয় না, client-side navigation-এও নয়; এটি সবচেয়ে নিচের স্তরের routing.

Next.js চালানো যায় না এই পাতায়। কিন্তু একটি route handler আসলে সাধারণ JavaScript ফাংশন। তাই নিচের ব্লকে শিক্ষার একটি মডেল: হুবহু একই আকৃতির GET, যাকে আমরা নিজে একটি Web Request দিয়ে ডাকছি। Node-এর নিজের Request আর Response, কোনো package নেই।

// শিক্ষার মডেল: route.ts-এর GET যেমন Request পায় আর Response ফেরত দেয়
const products = [
  { id: 1, name: "Miniket chal 5kg", price: 420 },
  { id: 2, name: "Masur dal 1kg", price: 135 },
];

function problem(status, title, detail) {
  return Response.json({ type: "about:blank", title, status, detail }, {
    status, headers: { "Content-Type": "application/problem+json" },
  });
}

// app/api/products/[id]/route.ts-এর GET-এর মতো
async function GET(request, { params }) {
  const { id } = await params;             // Next.js 15+ এ params একটি Promise
  const n = Number(id);
  if (!Number.isInteger(n) || n < 1) return problem(400, "Bad Request", "id must be a positive integer");
  const p = products.find((x) => x.id === n);
  if (!p) return problem(404, "Not Found", `No product with id ${n}`);
  const fields = new URL(request.url).searchParams.get("fields");
  return Response.json(fields === "name" ? { name: p.name } : p);
}

async function call(path, id) {
  const req = new Request("http://bazarghar.test" + path);
  const res = await GET(req, { params: Promise.resolve({ id }) });
  console.log(res.status, res.headers.get("content-type"), await res.text());
}

(async () => {
  await call("/api/products/2", "2");
  await call("/api/products/2?fields=name", "2");
  await call("/api/products/9", "9");
  await call("/api/products/abc", "abc");
})();

এই পর্বের সব দাবি একটি সত্যিকারের ল্যাব থেকে। লেখার সময়ের version: Next.js 16.4.4 (npm-এর latest), React 19.3.1, Zod 4.6.7, TypeScript 6.0.3, Node 24.15.0. প্রকল্পের path ছোট করে ~/bazarghar লেখা হয়েছে। Server চলেছে next build আর next start দিয়ে, শুধু 127.0.0.1-এ। Version বদলায়, তাই নিজের package.json মিলিয়ে নেবেন।

২ · Method, dynamic param আর ইনপুট পড়া — JSON, form, cookie, header

Express-এ ডেটা আসত তিন জায়গা থেকে: req.params, req.query, req.body (পর্ব ২৫)। Next.js-এ জায়গাগুলো একই, শুধু পড়ার পথ আলাদা। নিচের সারণিটি একবার মিলিয়ে নিন।

Body পড়ার জন্য কোনো parser middleware লাগে না, কারণ Web Request নিজেই json(), formData(), text() জানে। তবে একটি body একবারই পড়া যায়, কারণ এটি একটি stream. text() পড়ার পর আবার json() ডাকলে error হবে। Webhook-এ এই কথাটি খুব কাজে লাগবে।

Dynamic param: [id] আর async params

ফোল্ডারের নাম বন্ধনীতে লিখলে সেটি route param: app/api/products/[id]/route.ts. দ্বিতীয় argument-এর params Next.js 15 থেকে একটি Promise, তাই await লাগে। পুরোনো tutorial-এ params.id সরাসরি পড়া দেখবেন; Next.js 16-এ সেই synchronous পথ আর নেই। TypeScript-এ RouteContext নামের একটি global helper আছে, যা next build বা next dev চালানোর সময় তৈরি হয়, আর path থেকে param-এর type বানিয়ে দেয়:

import { db, problem } from '@/lib/store';

export async function GET(_req: Request, ctx: RouteContext<'/api/products/[id]'>) {
  const { id } = await ctx.params;               // id: string
  const n = Number(id);
  if (!Number.isInteger(n) || n < 1) return problem(400, 'Bad Request', 'id must be a positive integer');
  const product = db.products.find((p) => p.id === n);
  if (!product) return problem(404, 'Not Found', `No product with id ${n}`);
  return Response.json(product);
}

Param সবসময় string, ঠিক Express-এর মতো। "2" আর 2 এক নয়, তাই সংখ্যায় বদলে যাচাই করা হয়েছে। সত্যিকারের run (Next.js 16.4.4, next start, অপ্রাসঙ্গিক header বাদ):

$ curl -si http://127.0.0.1:47857/api/products/2
HTTP/1.1 200 OK
x-request-id: 777d17aa-4420-4d27-abec-5b939f70114e
vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch
content-type: application/json

{"id":2,"name":"Masur dal 1kg","price":135,"stock":12}

$ curl -si -X DELETE http://127.0.0.1:47857/api/products
HTTP/1.1 405 Method Not Allowed

$ curl -si -X OPTIONS http://127.0.0.1:47857/api/products
HTTP/1.1 204 No Content
allow: GET, HEAD, OPTIONS, POST

তিনটি জিনিস লক্ষ করুন। x-request-id এসেছে আমাদের proxy থেকে (৭ ও ৮ অংশে দেখবেন)। ফাইলে DELETE export করা নেই, তাই Next.js নিজেই 405 দিয়েছে। আর OPTIONS না লিখলেও Next.js নিজে একটি বানিয়ে allow header-এ বৈধ method জানিয়েছে। GET থাকলে HEAD-ও পাওয়া যায়। (HTTP-র নিয়মে 405-এর সাথে Allow header পাঠানোর কথা; আমাদের run-এ 405-এর উত্তরে তা ছিল না। কঠোর API চাইলে নিজে বসাতে পারেন।)

Form data, cookie আর header

যোগাযোগের form multipart/form-data বা application/x-www-form-urlencoded হিসেবে আসে। request.formData() দুটিই পড়ে। FormData-র সব মান string (বা ফাইল), তাই সংখ্যা চাইলে নিজে বদলাতে হয়।

import { z } from 'zod';
import { problem } from '@/lib/store';

const Contact = z.object({
  name: z.string().trim().min(2).max(60),
  phone: z.string().regex(/^01[3-9]\d{8}$/, 'Bangladeshi mobile number expected'),
});

export async function POST(request: Request) {
  const form = await request.formData();
  const parsed = Contact.safeParse(Object.fromEntries(form));
  if (!parsed.success) return problem(422, 'Validation failed', parsed.error.issues[0].message);
  return Response.json({ ok: true, name: parsed.data.name });
}

Cookie আর header পড়ার দুটি পথ। request.cookies আর request.headers সরাসরি request থেকে। অথবা next/headers-এর cookies() আর headers(), যা Next.js 15 থেকে async. দ্বিতীয় পথটি server component আর server action-এও একই রকম কাজ করে, তাই ভাগ করা helper লিখতে সুবিধা।

import { cookies, headers } from 'next/headers';
import { problem } from '@/lib/store';

export async function GET() {
  const cookieStore = await cookies();
  const h = await headers();
  const sid = cookieStore.get('sid')?.value;
  if (!sid) return problem(401, 'Unauthorized', 'Please log in');
  return Response.json({
    user: sid === 'demo-session' ? 'rahima' : 'unknown', // ল্যাবের নকল session
    requestId: h.get('x-request-id'),
    lang: h.get('accept-language') ?? 'none',
  });
}

$ curl -s http://127.0.0.1:47857/api/contact -F name=Rahima -F phone=01712345678
{"ok":true,"name":"Rahima"}
$ curl -s http://127.0.0.1:47857/api/contact -F name=Rahima -F phone=12345
{"type":"about:blank","title":"Validation failed","status":422,"detail":"Bangladeshi mobile number expected"}

$ curl -s http://127.0.0.1:47857/api/me
{"type":"about:blank","title":"Unauthorized","status":401,"detail":"Please log in"}
$ curl -s http://127.0.0.1:47857/api/me -H 'Cookie: sid=demo-session' -H 'Accept-Language: bn-BD'
{"user":"rahima","requestId":"ec5a9b33-9d3f-4b48-9cf8-43e5597e84d7","lang":"bn-BD"}

ল্যাবে sid=demo-session একটি নকল মান, শুধু পথ দেখানোর জন্য। আসল session কীভাবে তৈরি আর যাচাই হয়, তা পর্ব ৪৫ আর পর্ব ৪৬-এ। Route handler শুধু সেই যাচাইকে ডাকবে। নিচের stepper-এ এই শেষ অনুরোধটি proxy থেকে handler পর্যন্ত ধাপে ধাপে দেখুন।

GET /api/me HTTP/1.1
Cookie: sid=demo-session
Accept-Language: bn-BD

matcher: /((?!_next/static|…).*)
/api/me → মিলেছে
[proxy] GET /api/me runtime=nodejs 24.15.0

headers.set('x-request-id', id)
NextResponse.next({ request: { headers } })
res.headers.set('x-request-id', id)
id = ec5a9b33-9d3f-4b48-9cf8-43e5597e84d7

(await cookies()).get('sid')  → demo-session
(await headers()).get('x-request-id')
  → ec5a9b33-…   (proxy বসিয়েছে)
accept-language → bn-BD

{"user":"rahima",
 "requestId":"ec5a9b33-9d3f-4b48-9cf8-43e5597e84d7",
 "lang":"bn-BD"}

৩ · Status code, problem details আর Zod দিয়ে যাচাই

Framework বদলালেও API-র চুক্তি বদলায় না। পর্ব ২৭-এ শিখেছেন: server-এ পৌঁছানো কোনো কিছু বিশ্বাস নয়, Zod schema দিয়ে যাচাই। পর্ব ৩৩-এ শিখেছেন: ভুলের উত্তর এক ছাঁচে, problem details (RFC 9457). Next.js-এ শুধু এগুলো Response দিয়ে লিখতে হয়। ল্যাবে একটি ছোট helper সব route-এ ভাগ করা:

export function problem(status: number, title: string, detail: string, extra: Record<string, unknown> = {}) {
  return Response.json(
    { type: 'about:blank', title, status, detail, ...extra },
    { status, headers: { 'Content-Type': 'application/problem+json' } },
  );
}

এবার পণ্য যোগ করার POST. ক্রম গুরুত্বপূর্ণ: আগে body JSON কি না, তারপর schema, তারপর কাজ।

const NewProduct = z.object({
  name: z.string().trim().min(2).max(80),
  price: z.number().int().positive().max(1_000_000),
  stock: z.number().int().min(0).default(0),
});

export async function POST(request: Request) {
  let body: unknown;
  try {
    body = await request.json();
  } catch {
    return problem(400, 'Bad Request', 'Body must be valid JSON');
  }
  const parsed = NewProduct.safeParse(body);
  if (!parsed.success) {
    return problem(422, 'Validation failed', 'Some fields are invalid', {
      errors: parsed.error.issues.map((i) => ({ path: i.path.join('.'), message: i.message })),
    });
  }
  const product = { id: db.nextId++, ...parsed.data };   // শুধু যাচাই করা ঘর
  db.products.push(product);
  return Response.json(product, { status: 201, headers: { Location: `/api/products/${product.id}` } });
}

সত্যিকারের run, তিনটি অনুরোধ:

$ curl -si -X POST http://127.0.0.1:47857/api/products -H 'Content-Type: application/json' \
    -d '{"name":"Chini 1kg","price":140,"stock":20}'
HTTP/1.1 201 Created
content-type: application/json
location: /api/products/4

{"id":4,"name":"Chini 1kg","price":140,"stock":20}

$ curl -si -X POST … -d '{"name":"X","price":-5}'
HTTP/1.1 422 Unprocessable Entity
content-type: application/problem+json

{"type":"about:blank","title":"Validation failed","status":422,"detail":"Some fields are invalid",
 "errors":[{"path":"name","message":"Too small: expected string to have >=2 characters"},
           {"path":"price","message":"Too small: expected number to be >0"}]}

$ curl -s -X POST … -d '{bad json'
{"type":"about:blank","title":"Bad Request","status":400,"detail":"Body must be valid JSON"}

লক্ষ করুন, {bad json-এ request.json() throw করে। try না থাকলে Next.js একটি সাধারণ 500 দিত, যা আসলে client-এর ভুল, server-এর নয়। Zod 4-এর বার্তা (Too small: expected …) Zod 3-এর থেকে আলাদা, তাই পুরোনো উদাহরণের লেখা হুবহু মিলবে না। ...parsed.data নিরাপদ, কারণ Zod-এর object অজানা key ফেলে দেয়; কেউ "id": 1 বা "isAdmin": true পাঠালেও তা ঢুকবে না (mass assignment, পর্ব ২৭)।

৪ · GET handler-এর cache — Next.js 16-এ আসলে কী হয়

খেয়াল রাখুন: “খালি config” মানে next.config.ts-এ কিছু চালু নেই। create-next-app-এর template কিন্তু cacheComponents চালু করেই প্রকল্প বানায় (পর্ব ৫১), তাই নতুন প্রকল্পে নিচের দ্বিতীয় আচরণটিই পাবেন।

এখানে পুরোনো tutorial সবচেয়ে বেশি ভুল পথে নেয়। Next.js 13 আর 14-এ request না পড়া একটি GET handler build-এর সময় একবার চলে static হয়ে যেত। অনেকে অবাক হতেন: “আমার API তো একই উত্তর দিচ্ছে!” Next.js 15-এ এই ডিফল্ট উল্টে যায়: GET handler আর ডিফল্টে cache হয় না। Next.js 16-এ কী হয়, docs পড়ার পর নিজে মেপে দেখি। দুটি প্রায় একই ফাইল:

export async function GET() {
  return Response.json({ at: new Date().toISOString() });
}

export const dynamic = 'force-static';

export async function GET() {
  return Response.json({ at: new Date().toISOString() });
}

সাথে একটি তৃতীয়, app/api/info/route.ts, যা শুধু {"shop":"Bazarghar","currency":"BDT"} ফেরত দেয়; এতে সময় বা request কিছুই নেই। সত্যিকারের next build, খালি config (cacheComponents বন্ধ) (route table থেকে পাতাগুলো বাদ দেওয়া হয়নি):

▲ Next.js 16.4.4 (Turbopack)
✓ Compiled successfully in 1305ms
…
Route (app)
┌ ○ /
├ ○ /_not-found
├ ○ /account
├ ƒ /api/clock
├ ○ /api/clock-static
├ ƒ /api/contact
├ ƒ /api/info
├ ƒ /api/me
├ ƒ /api/mobile/products
├ ƒ /api/products
├ ƒ /api/products/[id]
├ ƒ /api/webhooks/payment
├ ○ /login
├ ○ /offer/a
└ ○ /offer/b

ƒ Proxy (Middleware)

○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand

চিহ্নগুলো পড়ুন। ○ মানে build-এর সময় তৈরি, ƒ মানে প্রতি অনুরোধে চলে। /api/info-তে কোনো পরিবর্তনশীল কিছুই নেই, তবু ƒ. অর্থাৎ ডিফল্টে কোনো GET handler cache হয়নি। শুধু force-static দেওয়াটি ○. নিচে Proxy-র লাইনেও লক্ষ করুন, “Proxy (Middleware)”: নতুন নাম, পুরোনোটি বন্ধনীতে। next start-এর পর দুবার করে ডাকলে:

$ curl -s http://127.0.0.1:47857/api/clock ; curl -s http://127.0.0.1:47857/api/clock
{"at":"2026-11-02T17:33:38.443Z"}
{"at":"2026-11-02T17:33:38.461Z"}

$ curl -s http://127.0.0.1:47857/api/clock-static ; curl -s http://127.0.0.1:47857/api/clock-static
{"at":"2026-11-02T17:33:26.163Z"}
{"at":"2026-11-02T17:33:26.163Z"}

$ curl -si http://127.0.0.1:47857/api/clock-static | grep -i cache
x-nextjs-cache: HIT
cache-control: s-maxage=31536000

প্রথমটি প্রতিবার নতুন সময়, ১৮ মিলিসেকেন্ডের ব্যবধানে। দ্বিতীয়টি দুবারই 17:33:26.163: এটি build-এর মুহূর্ত, server চালুর আগের সময়। x-nextjs-cache: HIT বলছে উত্তর cache থেকে এসেছে, আর s-maxage=31536000 (৩৬৫ দিন) CDN-এর মতো shared cache-কেও রাখতে বলছে। force-static-এ handler-এর ভেতরে request.headers বা cookie পড়লে খালি মান পাবেন, কারণ build-এর সময় কোনো আসল অনুরোধ থাকে না। তাই এটি শুধু সবার জন্য একই উত্তরের API-তে মানায়, যেমন জেলার তালিকা।

Cache Components চালু থাকলে

Next.js 16-এর নতুন মডেল Cache Components (next.config.ts-এ cacheComponents: true). Docs অনুযায়ী তখন GET handler সাধারণ পাতার মতো আচরণ করে: অনিশ্চিত বা অনুরোধ-নির্ভর কিছু না ছুঁলে build-এর সময় prerender হয়। একই প্রকল্পে চালু করে আবার build:

- Cache Components enabled
- Partial Prefetching enabled
Error: Route segment config "dynamic" is not compatible with `nextConfig.cacheComponents`. Please remove it.
  (clock-static সরিয়ে আবার build)
├ ƒ /api/clock
├ ○ /api/info
├ ƒ /api/me
…

এবার /api/info ○, কারণ এটি কিছুই পড়ে না। /api/clock ƒ, কারণ new Date() অনিশ্চিত। আর পুরোনো dynamic config এই মোডে নিষিদ্ধ, build থেমে যায়। একটি সতর্কতাও এসেছিল: cacheComponents-এর সাথে partialPrefetching-ও লিখতে বলছে, আর পরের major version-এ দুটিই সর্বত্র চালু হবে বলে জানাচ্ছে। Database-এর ডেটা cache করতে হলে docs-এর পথ হলো একটি আলাদা helper ফাংশনে 'use cache' আর cacheLife; সরাসরি handler-এর ভেতরে নয়। Cache-এর পুরো মডেল পর্ব ৫৩ (Data fetching আর cache)-এর বিষয়, rendering-এর ছক পর্ব ৫৫-এর।

৫ · Webhook — HMAC, raw body আর একবারই জমা

ক্রেতা বিকাশ বা কার্ডে টাকা দিলেন। Gateway পরে নিজে এসে বাজারঘরের একটি URL-এ POST করে জানায়: “order BG-2041-এর টাকা এসেছে”। একেই বলে webhook. সমস্যা হলো, URL-টি তো খোলা। যে কেউ সেখানে একই আকৃতির JSON পাঠাতে পারেন। তাই প্রশ্ন একটিই: এই বার্তা কি সত্যিই gateway-র, আর পথে কেউ বদলায়নি তো?

এখানে কোনো আসল gateway-র API নকল করা হয়নি। প্রতিটি gateway-র header-এর নাম, স্বাক্ষরের ধরন আর retry-র নিয়ম আলাদা; সেগুলো তাদের নিজের docs থেকে নেবেন। ল্যাবে আমরা একটি কাল্পনিক “BazarPay” ধরেছি, যার header x-bazarpay-signature: t=<সময়>,v1=<hex>, আর স্বাক্ষর হয় HMAC-SHA256(secret, t + "." + rawBody). অনেক বাস্তব gateway এর কাছাকাছি ধরন ব্যবহার করে। Secret ল্যাবে example-webhook-secret, .env.local-এ, কোডে নয়।

import { createHmac, timingSafeEqual } from 'node:crypto';
import { z } from 'zod';
import { db, problem } from '@/lib/store';

const SECRET = process.env.PAYMENT_WEBHOOK_SECRET ?? '';
const TOLERANCE_SEC = 300;
const Event = z.object({ id: z.string().min(1), type: z.literal('payment.succeeded'),
  orderId: z.string().min(1), amount: z.number().int().positive() });

function validSignature(header: string | null, raw: string, nowSec: number) {
  if (!header || !SECRET) return false;
  const parts = Object.fromEntries(header.split(',').map((kv) => kv.split('=') as [string, string]));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(nowSec - t) > TOLERANCE_SEC) return false;
  const expected = createHmac('sha256', SECRET).update(`${t}.${raw}`).digest();
  const given = Buffer.from(parts.v1 ?? '', 'hex');
  return given.length === expected.length && timingSafeEqual(given, expected);
}

export async function POST(request: Request) {
  const raw = await request.text();               // raw body: যাচাইয়ের আগে parse নয়
  if (!validSignature(request.headers.get('x-bazarpay-signature'), raw, Math.floor(Date.now() / 1000))) {
    return problem(401, 'Invalid signature', 'Webhook signature check failed');
  }
  const parsed = Event.safeParse(JSON.parse(raw));
  if (!parsed.success) return problem(422, 'Bad event', 'Unexpected event shape');
  const ev = parsed.data;
  if (db.seenEvents.has(ev.id)) return Response.json({ received: true, duplicate: true });
  db.seenEvents.add(ev.id);                       // বাস্তবে: unique column, একই transaction-এ
  db.paidOrders.set(ev.orderId, ev.id);
  return Response.json({ received: true, duplicate: false });
}

চারটি সিদ্ধান্ত আলাদা করে দেখুন।

• Raw body. স্বাক্ষর হয় byte-এর ওপর। request.json() দিয়ে parse করে আবার JSON.stringify করলে space, key-এর ক্রম বা সংখ্যার লেখা বদলাতে পারে, আর স্বাক্ষর মিলবে না। তাই request.text(). Express-এ এর জন্য আলাদা express.raw() লাগত; route handler-এ body কেউ আগে পড়ে না, তাই সমস্যা নেই।
• সমান সময়ের তুলনা। === দিয়ে string মেলালে প্রথম অমিলেই থামে, আর সময়ের পার্থক্য থেকে তথ্য ফাঁস হতে পারে (timing leak). timingSafeEqual সমান দৈর্ঘ্যের দুটি buffer পুরোটা তুলনা করে; দৈর্ঘ্য আলাদা হলে এটি throw করে, তাই আগে দৈর্ঘ্য মেলানো।
• সময়ের সীমা। একটি বৈধ বার্তা কেউ হাতে পেলে পরে হুবহু আবার পাঠাতে পারেন: replay. t স্বাক্ষরের ভেতরে, তাই বদলানো যায় না, আর ৩০০ সেকেন্ডের বেশি পুরোনো হলে বাতিল।
• একবারই কাজ। Gateway নিজেও একই ঘটনা একাধিকবার পাঠাতে পারে, যেমন আপনার উত্তর সময়মতো না পৌঁছালে retry. তাই event id দেখে দ্বিতীয়বার কিছুই করা হয় না, কিন্তু 200 দেওয়া হয়, যাতে gateway retry থামায়। এটি পর্ব ৩৩-এর idempotency-র একই নীতি, এখানে key দিচ্ছে gateway নিজে।

নিচের ব্লকে একই যুক্তি, নির্দিষ্ট সময় দিয়ে, যাতে ফল সবসময় এক থাকে। শেষ লাইনটি সবচেয়ে শিক্ষণীয়।

const { createHmac, timingSafeEqual } = require("node:crypto");
const SECRET = "example-webhook-secret";          // নকল মান
const seen = new Set();                            // বাস্তবে database-এর unique column

const sign = (t, raw) => createHmac("sha256", SECRET).update(`${t}.${raw}`).digest("hex");

function verify(header, raw, now) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
  if (Math.abs(now - Number(t)) > 300) return "too old";
  const expected = Buffer.from(sign(t, raw), "hex");
  const given = Buffer.from(v1 ?? "", "hex");
  const ok = given.length === expected.length && timingSafeEqual(given, expected);
  return ok ? "ok" : "bad signature";
}

function handle(header, raw, now) {
  const check = verify(header, raw, now);
  if (check !== "ok") return `401 ${check}`;
  const ev = JSON.parse(raw);                      // যাচাইয়ের পরেই parse
  if (seen.has(ev.id)) return `200 duplicate ${ev.id}, nothing changed`;
  seen.add(ev.id);
  return `200 order ${ev.orderId} paid (${ev.amount} BDT)`;
}

const now = 1793640000;                            // নির্দিষ্ট সময়, যাতে ফল একই থাকে
const raw = '{"id":"evt_1001","orderId":"BG-2041","amount":1250}';
const header = `t=${now},v1=${sign(now, raw)}`;
const tampered = raw.replace("1250", "9");

console.log("1 valid    :", handle(header, raw, now + 2));
console.log("2 retry    :", handle(header, raw, now + 40));
console.log("3 tampered :", handle(header, tampered, now + 3));
console.log("4 replay   :", handle(header, raw, now + 3600));
console.log("same JSON, new spacing:", handle(header, JSON.stringify(JSON.parse(raw), null, 1), now + 5));

এবার আসল Next.js server-এ। ল্যাবের একটি ছোট script (sign.mjs) একই নকল secret দিয়ে header বানায়। সত্যিকারের run:

$ SIG=$(node sign.mjs body.json); echo $SIG
t=1793640841,v1=8d785f56b5269fdc116bda3230e83c86443ce14b795b137808435dfecb3fcb66
$ curl -s -w ' [%{http_code}]\n' $URL -H "x-bazarpay-signature: $SIG" --data-binary @body.json
{"received":true,"duplicate":false} [200]
$ curl … একই অনুরোধ আবার
{"received":true,"duplicate":true} [200]
$ curl … একই header, tampered.json (amount 9)
{"type":"about:blank","title":"Invalid signature","status":401,"detail":"Webhook signature check failed"} [401]
$ curl … ৯০০ সেকেন্ড পুরোনো t দিয়ে স্বাক্ষর
… "Invalid signature" … [401]
$ curl … কোনো header ছাড়া
… "Invalid signature" … [401]

server log:
[webhook] order BG-2041 marked paid (event evt_1001)

পাঁচটি অনুরোধ, কিন্তু server log-এ marked paid মাত্র একবার। লক্ষ করুন, --data-binary ব্যবহার হয়েছে; শুধু -d দিলে curl ফাইলের newline ফেলে দিতে পারে, আর তখন byte বদলে যায়।

x-bazarpay-signature: t=1793640841,
  v1=8d785f56…cb66
{"id":"evt_1001","type":"payment.succeeded",
 "orderId":"BG-2041","amount":1250}

raw = await request.text()
expected = HMAC(secret, "1793640841." + raw)
         = 8d785f56…cb66
timingSafeEqual → true
|now − t| ≤ 300 → true

seenEvents = { evt_1001 }
paidOrders = { BG-2041 → evt_1001 }
200 {"received":true,"duplicate":false}

স্বাক্ষর → বৈধ
seenEvents.has("evt_1001") → true
200 {"received":true,"duplicate":true}
paidOrders অপরিবর্তিত

raw-এ "amount":9
expected ≠ v1
401 Invalid signature
seenEvents, paidOrders অপরিবর্তিত

৬ · মোবাইল অ্যাপের জন্য CORS

বাজারঘরের একটি মোবাইল অ্যাপও আছে। প্রথম প্রশ্ন: অ্যাপটি কী দিয়ে বানানো? এখানে একটি প্রচলিত ভুল ধারণা আছে। CORS browser-এর নিয়ম। Kotlin বা Swift-এ লেখা native অ্যাপ, বা React Native-এর সাধারণ network call, browser নয়; তারা CORS মানে না, preflight-ও পাঠায় না। তাদের জন্য CORS header দেওয়া বা না দেওয়া, কিছুই বদলায় না। কিন্তু অ্যাপটি যদি WebView-এ চলা web কোড হয়, বা m.bazarghar.test-এর মতো আলাদা origin-এর web অ্যাপ হয়, তখন browser-এর নিয়ম খাটে, আর CORS লাগবে। তত্ত্ব আছে পর্ব ২৬-এর CORS অংশে আর পর্ব ৫০-এ।

import { db } from '@/lib/store';

const ALLOWED = new Set(['https://m.bazarghar.test', 'http://localhost:8100']);

function corsHeaders(origin: string | null): Record<string, string> {
  const h: Record<string, string> = { Vary: 'Origin' };
  if (origin && ALLOWED.has(origin)) {
    h['Access-Control-Allow-Origin'] = origin;
    h['Access-Control-Allow-Methods'] = 'GET, OPTIONS';
    h['Access-Control-Allow-Headers'] = 'Authorization, Content-Type';
    h['Access-Control-Max-Age'] = '600';
  }
  return h;
}

export async function OPTIONS(request: Request) {
  return new Response(null, { status: 204, headers: corsHeaders(request.headers.get('origin')) });
}

export async function GET(request: Request) {
  const items = db.products.map(({ id, name, price }) => ({ id, name, price }));
  return Response.json({ items }, { headers: corsHeaders(request.headers.get('origin')) });
}

সত্যিকারের run, দুটি preflight:

$ curl -si -X OPTIONS http://127.0.0.1:47857/api/mobile/products \
    -H 'Origin: https://m.bazarghar.test' -H 'Access-Control-Request-Method: GET' \
    -H 'Access-Control-Request-Headers: authorization'
HTTP/1.1 204 No Content
access-control-allow-headers: Authorization, Content-Type
access-control-allow-methods: GET, OPTIONS
access-control-allow-origin: https://m.bazarghar.test
access-control-max-age: 600

$ curl -si -X OPTIONS … -H 'Origin: https://evil.example' -H 'Access-Control-Request-Method: GET'
HTTP/1.1 204 No Content
x-request-id: 2664dd47-42a3-4a65-abce-d2ccf8dd8d13

অচেনা origin-কে কোনো access-control-* header দেওয়া হয়নি, তাই browser তার পাতাকে উত্তর পড়তে দেবে না। তিনটি সিদ্ধান্ত লক্ষ করুন। * নয়, নির্দিষ্ট তালিকা। Vary: Origin, যাতে কোনো cache এক origin-এর উত্তর অন্যকে না দেয়। আর Authorization header-এর অনুমতি, কারণ মোবাইল অ্যাপ সাধারণত cookie নয়, token পাঠায় (পর্ব ৪৬)। মনে রাখুন, CORS server রক্ষা করে না। Curl বা native অ্যাপ যেকোনো origin লিখে পাঠাতে পারে। তাই অনুমতির আসল যাচাই token দিয়ে, handler-এ। অনেকগুলো route-এ একই CORS লাগলে docs-এর পরামর্শ: proxy-তে বা next.config-এর headers-এ এক জায়গায় লিখুন।

৭ · proxy.ts — middleware-এর নতুন নাম, matcher আর runtime

এবার দারোয়ান। Next.js 12-এ (২০২১) middleware.ts নামে একটি ফাইল আসে, যা route মেলার আগে চলে। Next.js 16-এ এর নাম বদলে হয়েছে proxy.ts, আর ফাংশনের নাম middleware থেকে proxy. কাজ একই। Docs-এ কারণ দুটি বলা হয়েছে। এক, “middleware” শব্দটি Express-এর middleware-এর সাথে গুলিয়ে যায়, যেখানে route-এর ভেতরে স্তরে স্তরে অনেক কাজ চলে (পর্ব ২৬)। Next.js-এর এই ফাইল আসলে অ্যাপের সামনে একটি network সীমানা, অনেকটা reverse proxy-র মতো। দুই, Next.js চায় এটি শেষ উপায় হিসেবে ব্যবহার হোক, তাই নামেই তা বোঝানো।

পুরোনো নামে কী হয়? ফাইলের নাম middleware.ts রেখে সত্যিকারের next build:

▲ Next.js 16.4.4 (Turbopack)
⚠ The "middleware" file convention is deprecated. Please use "proxy" instead.

  To migrate automatically, run:
  npx @next/codemod@canary middleware-to-proxy .

  Learn more: https://nextjs.org/docs/messages/middleware-to-proxy

শুধু সতর্কতা, এখনো চলে। Codemod ফাইল আর ফাংশন দুটির নাম বদলে দেয়। কিন্তু এই run-এ আরও একটি জিনিস বেরিয়ে এলো, যা docs-এর version table থেকে অনুমান করা কঠিন।

কোন runtime-এ চলে — নিজে মেপে দেখা

ল্যাবের proxy শুরুতে নিজের runtime ছাপে: EdgeRuntime global থাকলে edge, না হলে Node-এর version. proxy.ts নামে চালালে log:

[proxy] GET /api/me runtime=nodejs 24.15.0

একই ফাইল middleware.ts নামে build করলে:

Error: Turbopack build failed with 1 error:
./middleware.ts:6:15
Error: A Node.js API is used (process.versions at line: 6) which is not supported in the Edge Runtime.
> 6 |   : `nodejs ${process.versions.node}`;

process.versions সরিয়ে আবার চালালে log-এ runtime=edge. অর্থাৎ Next.js 16.4.4-এ proxy.ts ডিফল্টে Node.js runtime-এ চলে, আর পুরোনো middleware.ts এখনো Edge runtime-এ। Docs-এর version table বলে Next.js 15.5-এ middleware-এ Node.js runtime stable হয়েছিল (চাইলে বেছে নিতে হতো), আর 16-এ Proxy ডিফল্টে Node.js. আর proxy ফাইলে runtime config লেখা যায় না; docs অনুযায়ী লিখলে error হয়। শুধু নাম বদলালে তাই আচরণও বদলায়: Edge-এ যে node:crypto বা database driver চলত না, Node-এ তা চলবে। এটি সুবিধা, আবার ফাঁদও, কারণ “চলে” বলেই proxy-তে ভারী কাজ ঢোকানো লোভনীয় হয়ে ওঠে।

Matcher — কোন অনুরোধে proxy চলবে

Matcher না দিলে proxy প্রতিটি অনুরোধে চলে: পাতা, API, _next/static-এর JS আর CSS, ছবি, সব। একটি পাতা খুললেই তাই ডজনখানেক বার। Matcher লেখা হয় path-to-regexp-এর ধরনে, regex-সহ। ল্যাবের নিয়ম:

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\.(?:png|jpg|svg|css|js)$).*)'],
};

(?!…) হলো negative lookahead: “এর পরে এগুলোর কোনোটি না থাকলে মেলাও”। নিয়মটি build-এর সময় পড়া হয়, তাই এখানে variable বা ফাংশন চলে না; শুধু ধ্রুব লেখা। নিচের ব্লকে একই regex-কে সাধারণ JavaScript-এ মেলানো হলো। এটি শিক্ষার মডেল: Next.js ভেতরে আরও কিছু করে (যেমন has/missing শর্ত, locale), কিন্তু path-এর অংশটি এভাবেই কাজ করে।

// proxy.ts-এর matcher, নিচে একটি সরল মডেলে পরীক্ষা
const source = "/((?!_next/static|_next/image|favicon.ico|.*\\.(?:png|jpg|svg|css|js)$).*)";
const re = new RegExp("^" + source + "$");

const paths = [
  "/",
  "/account/orders",
  "/api/products/2",
  "/_next/static/chunks/main-abc123.js",
  "/_next/image",
  "/favicon.ico",
  "/logo.png",
  "/products/chal.png/reviews",
  "/static-offer",
];

let runs = 0;
for (const p of paths) {
  const hit = re.test(p);
  if (hit) runs++;
  console.log((hit ? "RUN  " : "skip ") + p);
}
console.log(`proxy runs on ${runs} of ${paths.length} paths`);

আসল server-এ: curl /logo.png দিল 200, আর server log-এ ওই অনুরোধের কোনো [proxy] লাইন নেই। Docs-এর একটি সতর্কতা মনে রাখুন: matcher-এ _next/data বাদ দিলেও proxy সেখানে চলে, ইচ্ছা করেই, যাতে পাতা রক্ষা করে তার ডেটার পথ ভুলে খোলা না থাকে।

"/account" → lookahead: _next/static? না
শেষে .png/.js? না → RUN
proxy চলেছে: 1   বাদ: 0

lookahead: _next/static → মিলেছে
→ skip, সরাসরি ফাইল
proxy চলেছে: 1   বাদ: 1

শেষে .png$ → skip
curl → 200, log-এ [proxy] লাইন নেই
proxy চলেছে: 1   বাদ: 2

কোনো বাদের শর্ত মেলেনি → RUN
[proxy] GET /api/me runtime=nodejs 24.15.0
proxy চলেছে: 2   বাদ: 2

৮ · Proxy-র কাজ: redirect, header, rewrite — আর যা করবেন না

ল্যাবের পুরো proxy.ts. তিনটি কাজ: login ছাড়া /account-এ এলে login পাতায় পাঠানো, /offer-এ A/B test, আর বাকি সবার জন্য একটি request id.

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function proxy(request: NextRequest) {
  const { pathname, search } = request.nextUrl;
  const requestId = crypto.randomUUID();

  // ১. login ছাড়া /account নয় (শুধু হালকা প্রাথমিক যাচাই)
  const isAccount = pathname === '/account' || pathname.startsWith('/account/');
  if (isAccount && !request.cookies.has('sid')) {
    const login = new URL('/login', request.url);
    login.searchParams.set('next', pathname + search);
    return NextResponse.redirect(login);
  }

  // ২. A/B: URL থাকে /offer, ভেতরের পাতা /offer/a বা /offer/b
  if (pathname === '/offer') {
    const bucket = request.cookies.get('ab')?.value ?? (Math.random() < 0.5 ? 'a' : 'b');
    const res = NextResponse.rewrite(new URL(`/offer/${bucket}`, request.url));
    res.cookies.set('ab', bucket, { path: '/', maxAge: 60 * 60 * 24 * 30, sameSite: 'lax' });
    return res;
  }

  // ৩. এগিয়ে যান, handler আর উত্তরে request id দিয়ে
  const headers = new Headers(request.headers);
  headers.set('x-request-id', requestId);
  const res = NextResponse.next({ request: { headers } });
  res.headers.set('x-request-id', requestId);
  return res;
}

প্রথম শর্তটি একসময় ছিল pathname.startsWith('/account'). নিচের ব্লকে দেখুন কেন বদলাতে হলো।

// শিক্ষার মডেল: proxy-র সিদ্ধান্ত, শুধু cookie আছে কি না দেখে
function proxy(request) {
  const url = new URL(request.url);
  const cookie = request.headers.get("cookie") ?? "";
  const hasSid = /(?:^|;\s*)sid=/.test(cookie);

  if (url.pathname.startsWith("/account") && !hasSid) {
    const login = new URL("/login", url);
    login.searchParams.set("next", url.pathname + url.search);
    return Response.redirect(login, 307);
  }
  return null; // null মানে "এগিয়ে যান" (Next.js-এ NextResponse.next())
}

const cases = [
  ["/account/orders?page=2", ""],
  ["/account/orders?page=2", "theme=dark; sid=abc123"],
  ["/products", ""],
  ["/accounts-help", ""],
];

for (const [path, cookie] of cases) {
  const req = new Request("http://bazarghar.test" + path, { headers: { cookie } });
  const res = proxy(req);
  const out = res ? `${res.status} -> ${res.headers.get("location")}` : "next()";
  console.log(`${path.padEnd(24)} cookie=${(cookie || "-").padEnd(22)} ${out}`);
}

আসল server-এর সত্যিকারের run:

$ curl -si "http://127.0.0.1:47857/account?tab=orders"
HTTP/1.1 307 Temporary Redirect
location: /login?next=%2Faccount%3Ftab%3Dorders

$ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:47857/account -H 'Cookie: sid=demo-session'
200

$ curl -si http://127.0.0.1:47857/offer
HTTP/1.1 200 OK
set-cookie: ab=a; Path=/; Expires=Wed, 02 Dec 2026 17:33:48 GMT; Max-Age=2592000; SameSite=lax
x-middleware-rewrite: http://localhost:47857/offer/a
…<h1>Offer variant A</h1>…
$ curl -s http://127.0.0.1:47857/offer -H 'Cookie: ab=b' | grep -o 'Offer variant [AB]' | head -1
Offer variant B

Build-এ /account ছিল ○, অর্থাৎ static HTML. তবু redirect কাজ করেছে, কারণ proxy চলে filesystem route-এর আগে। Docs-এর ক্রম: next.config-এর headers, তারপর redirects, তারপর proxy, তারপর beforeFiles rewrite, তারপর public/, _next/static, app/-এর route, তারপর dynamic route. Rewrite-এ browser-এর ঠিকানা /offer-ই থাকে, অথচ উত্তর আসে /offer/a থেকে; redirect-এর মতো দ্বিতীয় অনুরোধ লাগে না। Cookie থাকায় একই ক্রেতা বারবার একই রূপ দেখেন। একটি পর্যবেক্ষণ: ল্যাবের log-এ rewrite-এর পরে গন্তব্য /offer/a-এর জন্যও একটি [proxy] লাইন এসেছিল; proxy-র কাজ তাই এমন রাখুন, যাতে দুবার চললেও ক্ষতি না হয়। ভাষা অনুযায়ী /bn বা /en-এ পাঠানোও একই কৌশল; বাংলা সাইটের locale routing পর্ব ৫৯ (বাংলা সাইট: i18n)-এ।

যা proxy-তে করবেন না

Docs স্পষ্ট বলে: proxy ধীর ডেটা আনার জায়গা নয়, আর পূর্ণ session বা অনুমতি ব্যবস্থাও নয়; এটি optimistic check-এর জন্য। fetch-এর cache option-ও এখানে কাজ করে না। কেন এত জোর? একটি হিসাব দেখুন।

সংখ্যাগুলো অনুমান, কিন্তু অনুপাতটি আসল: proxy সংখ্যায় সবচেয়ে বেশিবার চলে, তাই এর প্রতিটি মিলিসেকেন্ড গুণ হয়। আর অনুমতি কেন শুধু proxy-তে নয়, তার একটি বাস্তব কারণও আছে। ২০২৫ সালের মার্চে Next.js-এ একটি গুরুতর দুর্বলতা প্রকাশ পায় (CVE-2025-29927): একটি internal header-এর অপব্যবহারে কিছু self-hosted অ্যাপে middleware পুরোপুরি এড়িয়ে যাওয়া সম্ভব ছিল। যেসব অ্যাপ অনুমতি শুধু middleware-এ যাচাই করত, তারা খোলা হয়ে পড়েছিল। ঠিক করা version (যেমন 15.2.3 আর 14.2.25) দ্রুত প্রকাশিত হয়। শিক্ষা: proxy একটি স্তর, একমাত্র দেয়াল নয়। Docs-ও বলে, প্রতিটি Server Function-এর ভেতরে আলাদা অনুমতি যাচাই করুন, কারণ matcher বা route বদলালে proxy নিঃশব্দে বাদ পড়তে পারে। অনুমতির নকশা পর্ব ৪৮-এ।

৯ · কোনটি কখন — route handler, server action, না আলাদা Express API

Next.js-এ server-এ কোড চালানোর তিনটি পথ পাশাপাশি। Server action (পর্ব ৫৪) হলো আপনার নিজের পাতার form আর বোতামের জন্য; Next.js ভেতরে এটিকে সেই পাতার route-এ একটি POST হিসেবে পাঠায়, URL আপনি ঠিক করেন না। Route handler হলো একটি নিজস্ব URL, যা বাইরের যে কেউ জানে আর ডাকে। আর মডিউল ৪-এর মতো আলাদা Express বা অন্য server একটি পুরো স্বাধীন backend.

আলাদা Express API কখন রাখবেন? (১) Backend-এর ক্রেতা অনেক: web, Android, iOS, partner. তখন API নিজেই একটি পণ্য, Next.js তার একটি ক্রেতা মাত্র। (২) দীর্ঘ সংযোগ বা কাজ: WebSocket (পর্ব ৬০), queue worker (পর্ব ৬২)। (৩) দল আলাদা, release আলাদা। (৪) মডিউল ৪-এর পরিপক্ক middleware-এর বাস্তুতন্ত্র (পর্ব ২৪ থেকে পর্ব ৩১) যদি আপনার কাছে জরুরি হয়। আবার উল্টো দিকে, ছোট দলে একটি Next.js প্রকল্পই পাতা, server action আর কয়েকটি route handler নিয়ে পুরো অ্যাপ চালাতে পারে; deploy একটি, type একটি। মাঝামাঝি একটি পথও প্রচলিত: Next.js-এর route handler পাতলা BFF হিসেবে, যা পেছনের আলাদা API-কে ডাকে। এখানে সম্প্রদায় একমত নয়, আর সঠিক উত্তর দলের আকার, client-এর সংখ্যা আর hosting-এর ওপর নির্ভর করে।

১০ · AI-এর যুগে route handler আর proxy

Next.js-এর API এত দ্রুত বদলেছে যে AI-এর লেখা কোডে পুরোনো ধরন খুব সাধারণ। pages/api-এর req, res, synchronous params.id, middleware.ts, “GET ডিফল্টে static” — সবই কোনো না কোনো সময়ে সঠিক ছিল। AI সেই মিশ্রণ থেকে লেখে। নিচের ভুলগুলো খেয়াল রাখুন।

AI-এর লেখা route handler আর proxy মেলানোর চেকলিস্ট

• next build-এর route table-এ প্রতিটি API-র ○ বা ƒ নিজে দেখেছি, আর তা আমার প্রত্যাশার সাথে মেলে
• ফাইলের নাম proxy.ts, আর build-এ কোনো deprecation সতর্কতা নেই
• Webhook-এ বৈধ, retry, বদলানো আর পুরোনো, চারটি curl চালিয়ে 200, 200, 401, 401 পেয়েছি
• Matcher-এ static ফাইল বাদ, আর /logo.png-এর জন্য log-এ proxy-র লাইন নেই
• Proxy-র অনুমতির নিয়ম সরালেও handler নিজে 401 বা 403 দেয়
• Diff-এ কোনো secret, * origin বা অপ্রয়োজনীয় package নেই