Node.js Backend Development Bootcamp · درس

المعترضات والمهل والبيانات الوصفية

أضف المصادقة والتسجيل المشتركين بين الوظائف عبر المعترضات مع فرض المهل وتمرير البيانات الوصفية

المعترضات والمهل والبيانات الوصفية درس مجاني في Node.js Backend Development Bootcamp على CoddyKit. هذا هو الدرس 3 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Node.js Backend Development Bootcamp، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Node.js Backend Development Bootcamp 4 دروس في المجموع.

بعض أجزاء هذا الدرس لم تُترجم بعد وتظهر باللغة الإنجليزية.

Cross-Cutting Concerns in gRPC

Once your gRPC service grows, you'll repeat the same logic in every handler: authentication, logging, timing, error shaping. Copy-pasting that into each method is fragile.

gRPC gives you three tools to handle this cleanly:

Interceptors — middleware that wraps every call (client or server side).
Metadata — key/value headers that travel alongside the request, perfect for auth tokens and request IDs.
Deadlines — an absolute time by which a call must complete, propagated across services.

In this lesson we'll wire all three together with @grpc/grpc-js in Node.js.

What Metadata Actually Is

Metadata is a multimap of string keys to values sent with a gRPC call, similar to HTTP headers. Keys are case-insensitive. Values are usually ASCII strings; keys ending in -bin carry binary Buffer values.

On the client you attach metadata; on the server you read it from the call object. Use it for things that aren't part of the business payload — auth tokens, trace IDs, locale.

const grpc = require('@grpc/grpc-js');

// Build metadata on the client
const md = new grpc.Metadata();
md.set('authorization', 'Bearer abc123');
md.set('x-request-id', 'req-42');

// Reading is case-insensitive
console.log(md.get('Authorization')); // [ 'Bearer abc123' ]
console.log(md.get('x-request-id')); // [ 'req-42' ]

Sending Metadata With a Unary Call

Every generated client method accepts an optional Metadata argument before the callback (or options). The token you set here arrives at the server before your handler runs.

Keep auth concerns out of your protobuf messages — put the token in metadata so the same auth logic works for every RPC.

const grpc = require('@grpc/grpc-js');

function callWithAuth(client, token) {
  const md = new grpc.Metadata();
  md.set('authorization', 'Bearer ' + token);

  client.GetUser({ id: '7' }, md, (err, res) => {
    if (err) return console.error('RPC failed:', err.message);
    console.log('User:', res);
  });
}

Reading Metadata on the Server

On the server, the call object exposes metadata via call.metadata.get(key), which returns an array (a key can repeat). For auth, read the authorization header and validate it before doing work.

If validation fails, return an error with grpc.status.UNAUTHENTICATED so clients can react correctly.

const grpc = require('@grpc/grpc-js');

function getUser(call, callback) {
  const auth = call.metadata.get('authorization')[0];
  if (!auth || !auth.startsWith('Bearer ')) {
    return callback({
      code: grpc.status.UNAUTHENTICATED,
      message: 'Missing or invalid token',
    });
  }
  const token = auth.slice('Bearer '.length);
  // ... verify token, then respond
  callback(null, { id: call.request.id, name: 'Ada' });
}

Server Interceptors: The Idea

Reading and validating tokens inside every handler is repetitive. A server interceptor lets you run logic once for all RPCs.

In @grpc/grpc-js, server-side interception is provided through the interceptors option on server.addService (and via ServerInterceptingCall in newer versions). The classic, widely-supported pattern is the client interceptor; on the server, many teams wrap handlers with a small higher-order function for auth and logging.

Let's start with that handler-wrapping pattern — it's portable and easy to test.

An Auth Wrapper for Handlers

A higher-order function takes a handler and returns a new handler that first checks auth, then delegates. This is a clean, framework-free way to add a cross-cutting concern.

The wrapper short-circuits with UNAUTHENTICATED when the token is bad, otherwise it calls through.

const grpc = require('@grpc/grpc-js');

function withAuth(handler) {
  return (call, callback) => {
    const auth = call.metadata.get('authorization')[0];
    if (auth !== 'Bearer good-token') {
      return callback({
        code: grpc.status.UNAUTHENTICATED,
        message: 'Unauthorized',
      });
    }
    return handler(call, callback);
  };
}

// Usage when registering the service:
// server.addService(svc, { GetUser: withAuth(getUser) });

A Logging Wrapper You Can Compose

The same pattern works for logging and timing. Because each wrapper takes a handler and returns a handler, you can compose them: withLogging(withAuth(getUser)).

Here the logger records the method label, latency, and the request id from metadata. Notice it's a complete, standalone program you can run to see the composition in action with a fake call object.

function withLogging(name, handler) {
  return (call, callback) => {
    const start = Date.now();
    const reqId = call.metadata.reqId || 'none';
    handler(call, (err, res) => {
      const ms = Date.now() - start;
      console.log(`[${name}] req=${reqId} ${err ? 'ERR' : 'OK'} ${ms}ms`);
      callback(err, res);
    });
  };
}

function getUser(call, callback) {
  callback(null, { id: call.request.id, name: 'Ada' });
}

const handler = withLogging('GetUser', getUser);
handler(
  { request: { id: '7' }, metadata: { reqId: 'req-42' } },
  (err, res) => console.log('Response:', res)
);

Client Interceptors

The official extension point on the client is the interceptor: a function that receives options and a nextCall, returning an InterceptingCall. You override lifecycle methods like start to inject metadata, or onReceiveStatus to observe results.

Below, every outgoing call automatically gets an authorization header — callers never have to remember it.

const grpc = require('@grpc/grpc-js');

function authInterceptor(token) {
  return (options, nextCall) =>
    new grpc.InterceptingCall(nextCall(options), {
      start(metadata, listener, next) {
        metadata.set('authorization', 'Bearer ' + token);
        next(metadata, listener);
      },
    });
}

// const client = new UserService(addr, creds, {
//   interceptors: [authInterceptor('abc123')],
// });

Understanding Deadlines

A deadline is an absolute point in time by which a call must finish. It is NOT a per-hop timeout — it's a wall-clock instant that propagates downstream, so a chain of services shares one budget.

Set it in the call options as deadline: either a Date or epoch milliseconds. The idiom is "now plus N ms".

If the deadline passes, the call fails with DEADLINE_EXCEEDED (status 4).
Servers can check the remaining time and abandon work early.

const grpc = require('@grpc/grpc-js');

function callWithDeadline(client) {
  const deadline = new Date(Date.now() + 2000); // 2s budget
  client.GetUser({ id: '7' }, { deadline }, (err, res) => {
    if (err && err.code === grpc.status.DEADLINE_EXCEEDED) {
      return console.error('Timed out');
    }
    if (err) return console.error(err.message);
    console.log(res);
  });
}

Deadlines on the Server Side

The server receives the deadline as call.getDeadline(). Before starting expensive work, compute the remaining budget and bail out early if it's already gone — this avoids wasting CPU on a call the client has given up on.

When you fan out to downstream services, pass the SAME deadline through so the whole tree respects one budget.

const grpc = require('@grpc/grpc-js');

function slowHandler(call, callback) {
  const deadline = call.getDeadline(); // ms or Date
  const remaining = Number(deadline) - Date.now();
  if (remaining <= 0) {
    return callback({ code: grpc.status.DEADLINE_EXCEEDED, message: 'No time left' });
  }
  // Forward the same deadline downstream:
  // downstream.Fetch(req, { deadline }, cb);
  callback(null, { ok: true, budgetMs: remaining });
}

Putting It Together: A Budgeted Pipeline

Here's the mental model for one request: the client sets a deadline and auth metadata. A client interceptor injects the token; the call carries a request id. On the server, an auth wrapper validates, a logging wrapper times it, and handlers check the remaining deadline before fanning out — propagating both metadata and the deadline downstream.

This standalone simulation shows the full chain of wrappers and a deadline check without any server, so you can run it directly.

function withAuth(h) {
  return (call, cb) =>
    call.metadata.authorization === 'Bearer good'
      ? h(call, cb)
      : cb({ code: 16, message: 'UNAUTHENTICATED' });
}
function withDeadline(h) {
  return (call, cb) =>
    call.deadline - Date.now() <= 0
      ? cb({ code: 4, message: 'DEADLINE_EXCEEDED' })
      : h(call, cb);
}
function getUser(call, cb) {
  cb(null, { id: call.request.id, name: 'Ada' });
}

const pipeline = withAuth(withDeadline(getUser));
const call = {
  request: { id: '7' },
  metadata: { authorization: 'Bearer good' },
  deadline: Date.now() + 1000,
};
pipeline(call, (err, res) =>
  console.log(err ? 'Error ' + err.code : 'OK', res || '')
);

Quick Check

A client sets deadline = Date.now() + 3000 and calls service A, which then calls service B. What is the correct behavior for the deadline?

Recap

You now have the toolkit for production-grade gRPC calls:

Metadata carries out-of-band data like authorization and x-request-id; read it server-side with call.metadata.get(key) (returns an array, case-insensitive keys).
Interceptors centralize cross-cutting logic: client interceptors use InterceptingCall to inject metadata in start; on the server, composable handler wrappers add auth and logging once.
Deadlines are absolute instants set via call options.deadline, propagated unchanged downstream so a whole chain shares one budget; exceeding it yields DEADLINE_EXCEEDED (status 4).

Combine them: inject auth + request id via an interceptor, wrap handlers for auth/logging, and always pass the deadline through when fanning out.

الأسئلة الشائعة

هل درس «المعترضات والمهل والبيانات الوصفية» مجاني؟

نعم — نص درس «المعترضات والمهل والبيانات الوصفية» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Node.js Backend Development Bootcamp، انتقل إلى CoddyKit PRO. تتضمن دورة Node.js Backend Development Bootcamp 4 دروس في المجموع.

ماذا ستتعلم في «المعترضات والمهل والبيانات الوصفية»؟

أضف المصادقة والتسجيل المشتركين بين الوظائف عبر المعترضات مع فرض المهل وتمرير البيانات الوصفية تتمرن على Node.js Backend Development Bootcamp مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Node.js Backend Development Bootcamp؟

لا تُشترط خبرة سابقة. Node.js Backend Development Bootcamp على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 3 من أصل 4.

كم من الوقت يستغرق درس «المعترضات والمهل والبيانات الوصفية»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Node.js Backend Development Bootcamp هذا؟

نعم. كل درس في Node.js Backend Development Bootcamp يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

تعريف الخدمات والرسائل باستخدام Protobuf IDL
استدعاءات RPC أحادية الاتجاه ومن الخادم ومن العميل وثنائية الاتجاه
المعترضات والمهل والبيانات الوصفية
تطوّر Proto والتوافق مع الإصدارات السابقة

← العودة إلى Node.js Backend Development Bootcamp