0Pricing
Node.js Backend Development Bootcamp · Leçon

Intercepteurs, échéances et métadonnées

Ajoutez l’authentification et la journalisation transversales via des intercepteurs, tout en imposant des échéances et en transmettant les métadonnées.

Intercepteurs, échéances et métadonnées est une leçon Node.js Backend Development Bootcamp gratuite sur CoddyKit. Ceci est la leçon 3 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage Node.js Backend Development Bootcamp, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours Node.js Backend Development Bootcamp comprend 4 leçons au total.

Certaines parties de cette leçon n'ont pas encore été traduites et s'affichent en anglais.

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.

Questions Fréquemment Posées

La leçon « Intercepteurs, échéances et métadonnées » est-elle gratuite ?

Oui — le texte complet de « Intercepteurs, échéances et métadonnées » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours Node.js Backend Development Bootcamp, passe à CoddyKit PRO. Le cours Node.js Backend Development Bootcamp comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Intercepteurs, échéances et métadonnées » ?

Ajoutez l’authentification et la journalisation transversales via des intercepteurs, tout en imposant des échéances et en transmettant les métadonnées. Tu pratiques Node.js Backend Development Bootcamp avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer Node.js Backend Development Bootcamp ?

Aucune expérience préalable n'est requise. Node.js Backend Development Bootcamp sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 3 sur 4.

Combien de temps prend la leçon « Intercepteurs, échéances et métadonnées » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon Node.js Backend Development Bootcamp ?

Oui. Chaque leçon Node.js Backend Development Bootcamp inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

  1. Définir des services et des messages avec l’IDL Protobuf
  2. RPC de flux unaires, serveur, client et bidirectionnels
  3. Intercepteurs, échéances et métadonnées
  4. Évolution de Proto et compatibilité ascendante
← Retour à Node.js Backend Development Bootcamp