best practices for middleware?

[Chandraprakash-Darji]

I have two middleware: auth and brandId. I have shared my current implementation but I don't feel like it is best approach.

I am building for the first time with orpc. I want to do chain the middleware but typescript not letting me do it

middleware.ts

import { ORPCError } from "@orpc/client";
import { fromNodeHeaders } from "better-auth/node";

import { auth } from "~/utils/auth";
import { AuthedUserContext, base } from "./base";

export const useAuth = base.middleware(async ({ context, next }) => {
  if (!context.headers) {
    throw new ORPCError("NOT_ACCEPTABLE", {
      message: "Headers are required",
    });
  }
  const user =
    context?.user ??
    (
      await auth.api.getSession({
        headers: fromNodeHeaders(context.headers),
      })
    )?.user;

  if (!user?.profileId) {
    throw new ORPCError("FORBIDDEN", {
      message: "Authentication required",
    });
  }

  return await next({
    context: {
      ...context,
      user,
    },
  });
});

export const useBrand = base.middleware(async ({ context, next }) => {
  const brandId = context.headers["x-brand-id"];
  if (!brandId || Array.isArray(brandId) || brandId.trim() === "") {
    throw new ORPCError("BAD_REQUEST", {
      message: "X-Brand-Id header is required",
    });
  }

  const user =
    context?.user ??
    (
      await auth.api.getSession({
        headers: fromNodeHeaders(context.headers),
      })
    )?.user;

  if (!user?.profileId) {
    throw new ORPCError("FORBIDDEN", {
      message: "Authentication required",
    });
  }

  return await next({
    context: {
      ...context,
      user,
      brandId,
    },
  });
});

router.ts

import { implement } from "@orpc/server";

import { authed, base } from "./base";
import { contract } from "./contract";
import { useAuth, useBrand } from "./middleware";
import {
  createBrand,
  getAllConnections,
  getBrand,
  updateBrand,
} from "./procedures";
import { brandRepository } from "./repository";

export const brandRouter = base.router({
  get: contract.get.use(useAuth).handler(async ({ context }) => {
    return await brandRepository.getBrand({
      profileId: context.user.profileId,
    });
  }),
  create: contract.create
    .use(useAuth)
    .use(useBrand)
    .handler(({ input, context }) => {
      return createBrand(input);
    }),
  update: contract.update
    .use(useBrand)
    .handler(({ input, context }) => updateBrand(input)),
});

export type BrandRouter = typeof brandRouter;

contract.ts

import z from "zod";

import { BrandInformationSchema, BrandSchema } from "@ce-sdr/db/schema";

import { base } from "./base";
import { useAuth, useBrand } from "./middleware";

export const contract = {
  get: base.output(
    BrandInformationSchema.extend({
      brand: BrandSchema,
    }).nullable(),
  ),
  create: base
    .input(
      BrandInformationSchema.pick({
        audience: true,
        personality: true,
        voice: true,
      }).merge(BrandSchema.pick({ profileId: true, name: true })),
    )
    .output(
      BrandInformationSchema.extend({
        brand: BrandSchema,
      }).nullable(),
    ),
  update: base
    .input(
      BrandInformationSchema.pick({
        id: true,
        audience: true,
        biggestChallenges: true,
        idealClientProfile: true,
        personality: true,
        voice: true,
      }),
    )
    .output(
      BrandInformationSchema.extend({
        brand: BrandSchema,
      }).nullable(),
    ),
};

base.ts

import { IncomingHttpHeaders, IncomingMessage } from "node:http";
import { os } from "@orpc/server";
import { RequestHeadersPluginContext } from "@orpc/server/plugins";

import { User } from "@ce-sdr/auth";

export interface ORPCContext extends RequestHeadersPluginContext {
  headers: IncomingHttpHeaders;
  req: IncomingMessage;
  brandId?: string;
  user?: User;
}

export const base = os.$context<ORPCContext>();

export interface AuthedUserContext extends ORPCContext {
  user: User;
}
export const authed = os.$context<AuthedUserContext>();

export interface BrandContext extends AuthedUserContext {
  brandId: string;
}

export const brand = os.$context<BrandContext>();

[dosubot[bot]]

Hi @Chandraprakash-Darji! I'm Dosu and I’m helping the orpc team.

You're on the right track with composable middleware and context extension, but there are a few best practices from the orpc ecosystem that can help you improve:

• Avoid redundant user lookups: Both your useAuth and useBrand middleware fetch the user session. If both are chained, this results in two lookups. Instead, ensure that user fetching happens only once per request. You can do this by always running useAuth before useBrand, and in useBrand, simply rely on context.user (which will be set by useAuth). Only fetch the user if it's not already present in context. This pattern is recommended for performance and clarity.
• Layer context enrichment: Each middleware should only add what it is responsible for (e.g., useAuth adds user, useBrand adds brandId). Avoid overwriting context fields unless necessary, and always pass the enriched context down the chain.
• Validate before heavy work: Always check for required headers or context fields before performing expensive operations like session fetching.
• Use typesafe context definitions: You're already extending context types, which is great. This ensures type safety and clarity as context is enriched through the middleware chain.
• For OpenAPI and documentation, you can annotate middleware with security metadata to make authentication requirements explicit and reusable across procedures. See the example in this discussion.

Refactoring suggestion: In useBrand, remove the user lookup and just check for context.user. If it's missing, throw an error. This way, you avoid duplicate session fetches and keep each middleware focused on its responsibility.

These patterns are widely used in orpc and help keep your middleware efficient, composable, and easy to reason about.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[dinwwwh]

Please remove ...context and don't make them conflict each other, please use dependant-context instead: https://orpc.unnoq.com/docs/middleware#dependent-context

[tresorama]

@unnoq
Asking just to be sure it is what you intended.
Is correct?

// init.ts

import { os } from "@orpc/server";
import { CORSPlugin } from "@orpc/server/plugins";
import {
  RequestHeadersPlugin,
  type RequestHeadersPluginContext,
} from "@orpc/server/plugins";

import { middlewareRateLimit } from "./middleware/rate-limiter";
import { middlewareAuth } from "./middleware/auth";

// =========================
// Init Plugins
// =========================

/** ORPC Plugins array that must be added to the server creation phase.
  * Plugins will add stuff to initial context
  * */
export const serverPlugins = [
  new CORSPlugin(),
  new RequestHeadersPlugin(),
];

// =========================
// Init ORPC Builder - Base
// =========================
type ORPCBaseContext = RequestHeadersPluginContext;

/** Base ORCP Builder */
const base = os
  .$context<ORPCBaseContext>()
  ;

// =========================
// Init ORPC Builder - Public Procedure
// =========================

/** Extended {@link base} ORCP Builder for public routes */
const publicProcedure = base
  .$context<ORPCBaseContext>()
  .use(middlewareRateLimit);

// =========================
// Init ORPC Builder - Authed Procedure
// =========================

/** Extended {@link base} ORCP Builder for auth-gated routes */
const authedProcedure = base
  .$context<ORPCBaseContext>()
  .use(middlewareRateLimit)
  .use(middlewareAuth);

// =========================
// Expose API
// =========================

/** Public API for creating ORPC implementations (middleware, router, ruote/procedure, ... ) */
export const createOrpc = {
  base,
  publicProcedure,
  authedProcedure,
};

// root-router.ts
import { createOrpc } from "./init";

import { routerDemoAuth } from "./routers/demo-auth";
import { routerUsers } from "./routers/users";

export const orpcRootRouter = createOrpc.base.router({
  users: routerUsers,
  demoAuth: routerDemoAuth,
});

// routers/demoAuth.ts

import { createOrpc } from "../init";

export const routerDemoAuth = createOrpc.base.router({
  userSensitiveData: createOrpc.authedProcedure
    .handler(async (ctx) => {
      const userData = ctx.context.user;
      return userData;
    }),
});

// server.ts

import { RPCHandler } from "@orpc/server/fetch";

import { serverPlugins } from "./init";
import { orpcRootRouter } from "./root-router";

const orpcHandler = new RPCHandler(orpcRootRouter, {
  plugins: serverPlugins,
  // interceptors: [
  //   onError((error) => {
  //     console.error(error)
  //   }),
  // ],
});

/** Implement Server for Tanstack Start */
export const createOrpcRequestHandlerForTanstackStart = (options: {
  request: Request;
  /** In which pathname is mounted? */
  prefix: `/${string}`;
}) => {
  return async function orpcRequestHandler() {
    const { response } = await orpcHandler.handle(options.request, {
      prefix: options.prefix,
      context: {}, // Provide initial context if needed
    });

    if (response) {
      return response;
    }
    return new Response("Not Found", { status: 404 });
  };
};

// middleware/rate-limiter.ts
import { ORPCError, os } from "@orpc/server";

import { serverLogger } from "@backend/logger";
import { getClientIpFromHeaders } from "./get-client-ip-from-req-headers";
import { createRateLimitStore } from "./rate-limit-store";

export const rateLimitStore = createRateLimitStore({
  window: {
    durationMs: 10 * 1000, // 10 sec
    maxCall: 2,
  },
});

export const middlewareRateLimit = os
  .$context<{ reqHeaders?: Headers }>()
  .middleware(async ({ context, next }) => {
    const clientIp = getClientIpFromHeaders(context.reqHeaders);

    //TODO: think how to handle this case
    if (!clientIp) {
      serverLogger.log('[orpc midd rate-limiter] cannot get ip -> allow');
      return next();
    }
    
    const rateLimitResult = rateLimitStore.checkIfCallIsAllowed(clientIp);
    serverLogger.log(`[orpc midd rate-limiter] clientIp=${rateLimitResult.clientIp}`);
    serverLogger.log(`[orpc midd rate-limiter]`, {clientWindow: rateLimitResult.clientWindow});
    
    if (rateLimitResult.status === "BLOCK") {
      serverLogger.log(`[orpc midd rate-limiter] too many request. Max Allowed: ${rateLimitResult.maxAllowedCalls}  -> block`);
      throw new ORPCError("TOO_MANY_REQUESTS", {
        message: "You are being rate limited",
        data: {
          retryAt: rateLimitResult.resetAtIsoString,
        },
      });
    }
    
    serverLogger.log(`[orpc midd rate-limiter] allow request. Remaining Calls: ${rateLimitResult.remainingCalls} Max Allowed: ${rateLimitResult.maxAllowedCalls}  -> allow`);
    return next();
  });

// middleware/auth.ts
import { ORPCError, os } from "@orpc/server";

import { getUserFromRequestHeaders } from "./auth";

export const middlewareAuth = os
  .$context<{ reqHeaders?: Headers }>()
  .middleware(async (stuff) => {
    // derive user from request
    const user = getUserFromRequestHeaders(stuff.context.reqHeaders);

    if (!user) {
      throw new ORPCError('FORBIDDEN', {
        status: 403,
        message: 'You are not allowed'
      })
    }

    // extend the context of the request chain
    return stuff.next({ context: { user } });
  });

[dinwwwh]

@tresorama your code is very good 👍

[tresorama]

Great! Thanks

[Chandraprakash-Darji]

@unnoq Thanks, was trying every bit of code changes but didn't work. Thanks for help, it worked.