0Pricing
Node.js Backend Development Bootcamp · Lesson

Interceptors, Deadlines, and Metadata

Add cross-cutting auth and logging via interceptors while enforcing deadlines and passing metadata.

Interceptors, Deadlines, and Metadata is a free Node.js Backend Development Bootcamp lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Node.js Backend Development Bootcamp learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

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.

Frequently asked questions

Is the “Interceptors, Deadlines, and Metadata” lesson free?

Yes — the full text of “Interceptors, Deadlines, and Metadata” is free to read here on the web, and the Node.js Backend Development Bootcamp course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Node.js Backend Development Bootcamp course, upgrade to CoddyKit PRO.

What will I learn in “Interceptors, Deadlines, and Metadata”?

Add cross-cutting auth and logging via interceptors while enforcing deadlines and passing metadata. You practise Node.js Backend Development Bootcamp with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Node.js Backend Development Bootcamp?

No prior experience is required. Node.js Backend Development Bootcamp on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Interceptors, Deadlines, and Metadata” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Node.js Backend Development Bootcamp lesson?

Yes. Every Node.js Backend Development Bootcamp lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Defining Services and Messages with Protobuf IDL
  2. Unary, Server, Client, and Bidirectional Streaming RPCs
  3. Interceptors, Deadlines, and Metadata
  4. Proto Evolution and Backward Compatibility
← Back to Node.js Backend Development Bootcamp