DEV Community: Emmanue; Nodolo

Scoping Multi-Tenant Runtime Context in Fastify Without Protecting Every Route

Emmanue; Nodolo — Mon, 21 Sep 2026 18:19:32 +0000

Multi-tenancy does not always belong at the root of an application.

A production API may have routes such as:

/health
/status
/metrics

that should remain independent from tenant resolution, while application routes such as:

/users
/orders
/projects

need a tenant-aware execution boundary.

Fastify's plugin encapsulation makes this separation surprisingly natural.

While building the Fastify framework track for Ambiten, I ended up with a pattern that expresses this boundary directly in the application structure.

import Fastify from "fastify";
import {
  createFastifyAdapter
} from "@ambiten/adapter-fastify";

import {
  AmbitenContext,
  MultiTenantManager
} from "@ambiten/core";

import {
  registerDemoTenants
} from "./core/tenancy";

export function buildApp(
  logger = false
) {
  registerDemoTenants();

  const app =
    Fastify({
      logger
    });

  // This route lives outside the
  // tenant-protected child plugin.
  app.get(
    "/health",
    async () => ({
      status: "ok"
    })
  );

  app.register(
    async api => {
      const adapter =
        createFastifyAdapter();

      await adapter.install(
        api,
        {
          tenancy: {
            header:
              "x-tenant-id",

            validate:
              async tenantId => {
                const tenant =
                  await MultiTenantManager
                    .resolveTenant(
                      tenantId
                    );

                if (!tenant) {
                  throw new Error(
                    `Tenant with ID "${tenantId}" not found.`
                  );
                }

                return true;
              }
          }
        }
      );

      api.get(
        "/context",
        async () => {
          await new Promise<void>(
            resolve =>
              setImmediate(
                resolve
              )
          );

          const ctx =
            AmbitenContext.get();

          return {
            tenantId:
              ctx.tenantId,

            requestId:
              ctx.requestId,

            dbName:
              ctx.dbName
          };
        }
      );
    }
  );

  return app;
}

The interesting part is not the amount of code.

It is where the adapter is installed.

The Root Application Stays Public

The health route is registered directly on the root Fastify instance:

app.get(
  "/health",
  async () => ({
    status: "ok"
  })
);

It does not need tenant identity.

A monitoring system should be able to ask whether the process is healthy without first pretending to belong to a customer tenant.

Conceptually:

GET /health
      ↓
Fastify
      ↓
{ status: "ok" }

No tenant resolution is involved.

That is a useful distinction because infrastructure endpoints and application endpoints often have different execution requirements.

The Child Plugin Becomes the Tenant Boundary

The application routes live inside:

app.register(
  async api => {
    // tenant-aware application
  }
);

Inside that scope, the Ambiten Fastify adapter is installed:

const adapter =
  createFastifyAdapter();

await adapter.install(
  api,
  {
    tenancy: {
      header:
        "x-tenant-id",

      validate:
        async tenantId => {
          const tenant =
            await MultiTenantManager
              .resolveTenant(
                tenantId
              );

          if (!tenant) {
            throw new Error(
              `Tenant with ID "${tenantId}" not found.`
            );
          }

          return true;
        }
    }
  }
);

The structure now communicates the architecture:

Fastify Application
│
├── /health
│     └── public infrastructure route
│
└── Child Plugin
      │
      ├── Ambiten execution boundary
      │
      ├── tenant resolution
      │
      └── /context
            └── tenant-aware route

This is different from installing tenant behavior globally and then creating exceptions everywhere else.

The protected part of the application is explicitly contained.

Fastify Encapsulation Becomes an Architectural Tool

Fastify's plugin model gives child scopes their own encapsulated environment.

That means a runtime integration can be installed inside a particular plugin instead of automatically becoming a requirement for every route in the process.

For a larger application, the same idea could evolve into:

Application
│
├── /health
├── /metrics
│
├── /public/*
│
└── /api/*
      ↓
   tenant-aware runtime
      ↓
   services
      ↓
   models

You could also create separate application areas with different policies:

/customer/*
      ↓
customer tenant policy

/admin/*
      ↓
administrative tenant policy

The framework hierarchy starts reflecting the execution hierarchy.

That is much easier to reason about than one global middleware layer containing many conditional branches.

The Adapter Must Be Installed Before the Routes

There is an important ordering detail.

The adapter should be installed before routes are registered inside the protected scope:

app.register(
  async api => {
    await createFastifyAdapter()
      .install(
        api,
        options
      );

    api.get(
      "/context",
      handler
    );
  }
);

This ordering matters because the adapter establishes the framework execution boundary for routes registered in that scope.

Putting the route first would mean the route had already been registered before that integration was attached.

So the mental model is:

Create scope
     ↓
Install execution policy
     ↓
Register application routes

rather than:


Register application routes
     ↓
Try to retrofit execution policy

Proving That Context Survives Async Work

The /context endpoint deliberately contains this:

await new Promise<void>(resolve =>
    setImmediate(
      resolve
    )
);

It is not necessary for the endpoint itself.

It is there to demonstrate something more important.

After crossing an asynchronous boundary, the resolver still reads:

const ctx = AmbitenContext.get();

and the active tenant remains available:

return {
  tenantId:
    ctx.tenantId,

  requestId:
    ctx.requestId,

  dbName:
    ctx.dbName
};

The desired execution path is:

Incoming Request
      ↓
Tenant Resolution
      ↓
Ambiten Execution Context
      ↓
Route Handler
      ↓
await
      ↓
Nested Async Work
      ↓
AmbitenContext.get()
      ↓
same execution state

That is the point of an execution-scoped runtime.

Application code should not have to pass:

tenantId
requestId
session
runtime metadata

through every function signature simply because the call stack became asynchronous.

Trying It

The health endpoint does not require a tenant:

curl http://localhost:3000/health

Response:

{
  "status": "ok"
}

The tenant-aware route does:

curl \
  -H "x-tenant-id: tenant-a" \
  http://localhost:3000/context

A response may look like:

{
  "tenantId": "tenant-a"
}

requestId and dbName may also appear when they are resolved or configured for the execution.

Calling the protected endpoint without a resolvable tenant should fail before application logic proceeds.

That gives the application two very different boundaries without maintaining two separate Fastify servers.

Tenant Resolution Is Not Authorization

There is one distinction worth keeping explicit.

Resolving:

x-tenant-id: tenant-a

answers:

Which tenant is this execution for?

It does not automatically answer:

Is this caller allowed to act for tenant-a?

A production application will often have a flow closer to:

Request
   ↓
Authentication
   ↓
Authorization
   ↓
Tenant Resolution
   ↓
Runtime Context
   ↓
Application Logic

These responsibilities can cooperate without being collapsed into the same concept.

Why I Like This Pattern

What I like most about this structure is that the code communicates the boundary without requiring much explanation.

The root application contains process-level and public endpoints.

The registered plugin contains tenant-aware application execution.

Inside that scope, the adapter establishes runtime continuity.

The result is:

Infrastructure routes
        ≠
Tenant application routes

while still keeping both inside one Fastify application.

This is one of those cases where framework encapsulation becomes more than an organizational feature.

It becomes part of the system architecture.

A More General Principle

The pattern also reflects a broader rule I have been following while developing Ambiten:

Execution policy should live at the boundary
where that policy actually becomes valid.

Not every route needs tenancy.

Not every operation needs a transaction.

Not every process-level resource belongs to a request.

Making those lifetimes explicit usually produces simpler code than applying everything globally and then adding exceptions.

For this Fastify example, the boundary is visible directly in app.register().

And that is exactly where the tenant-aware runtime begins.

Ambiten is an execution runtime for context-aware, multi-tenant MongoDB applications.

Documentation: https://docs.ambiten.dev

GitHub: https://github.com/AmbitenHQ/ambiten

npm: https://www.npmjs.com/package/@ambiten/adapter-fastify

Why Request Context Becomes Infrastructure in Multi-Tenant Node.js Applications

Emmanue; Nodolo — Fri, 18 Sep 2026 10:05:32 +0000

A multi-tenant Node.js application often starts with something that looks harmless:

const tenantId =
  req.headers["x-tenant-id"];

You resolve the tenant from the incoming request, pass it to a service, select the right database, and continue.

At first, this feels like ordinary application plumbing.

Then the application grows.

Soon the request also carries:

tenantId
requestId
database selection
transaction session
logging metadata
debug state
instrumentation
operation metadata

And suddenly the question is no longer:

How do I get the tenant ID into this function?

The real question becomes:

How should execution state move through the entire application?

That is the point where request context stops being a convenience and starts becoming infrastructure.

The simple version works — until it spreads everywhere

Imagine a straightforward service:

async function createUser(
  tenantId: string,
  input: CreateUserInput
) {
  const db =
    await resolveTenantDatabase(
      tenantId
    );

  return db
    .collection("users")
    .insertOne(input);

Nothing is particularly wrong with this.

The tenant is explicit.

The code is easy to understand.

Then another layer appears:

async function registerUser(
  tenantId: string,
  input: CreateUserInput
) {
  return createUser(
    tenantId,
    input
  );
}

Then another:

async function handleRegistration(
  tenantId: string,
  requestId: string,
  input: CreateUserInput
) {
  return registerUser(
    tenantId,
    input
  );
}

Then transactions arrive:

async function handleRegistration(
  tenantId: string,
  requestId: string,
  session: ClientSession,
  input: CreateUserInput
) {
  // ...
}

Then logging:

async function handleRegistration(
  tenantId: string,
  requestId: string,
  session: ClientSession,
  loggerMeta: Record<string, unknown>,
  input: CreateUserInput
) {
  // ...
}

The business function is slowly becoming an infrastructure transport layer.

The problem is not that these values exist.

They should exist.

The problem is that every application layer becomes responsible for carrying them correctly.

Context propagation becomes a correctness problem

Passing runtime state manually creates several failure modes.

A service can forget to forward the tenant:

await updateAccount(
  accountId,
  update
);

when it should have called:

await updateAccount(
  tenantId,
  accountId,
  update
);

A nested operation can lose the active transaction session.

A logger can emit an event without the request identifier.

A model can resolve the default database because a database name was not forwarded.

None of these failures necessarily produce obvious syntax errors.

The application can still run.

It can simply run with the wrong execution state.

That makes context propagation a runtime correctness concern.

A tenant is not just another function argument

This distinction matters.

A value like:

productName

belongs to application data.

A value like:

tenantId

often determines where and how the operation executes.

For example:

tenantId
   ↓
tenant configuration
   ↓
MongoClient
   ↓
database
   ↓
collection

Likewise, a transaction session determines whether a database operation belongs to an existing atomic unit of work.

A request ID determines how runtime signals can be correlated.

These values describe the execution environment around the application.

That is why treating them exactly like ordinary domain parameters eventually becomes awkward.

Node.js already has a primitive for this

Node.js provides AsyncLocalStorage for storing state associated with an asynchronous execution chain.

A simplified execution context might look like this:

import {
  AsyncLocalStorage
} from "node:async_hooks";

import type {
  ClientSession
} from "mongodb";

interface ExecutionContext {
  tenantId?: string;
  requestId?: string;
  session?: ClientSession;
}

const storage =
  new AsyncLocalStorage<
    ExecutionContext
  >();

We can establish an execution boundary:

function runWithContext<R>(
  context: ExecutionContext,
  operation: () => Promise<R>
) {
  return storage.run(
    context,
    operation
  );
}

And read it deeper in the call tree:

function getContext() {
  return storage.getStore();
}

Now the request boundary can resolve infrastructure state once:

await runWithContext(
  {
    tenantId:
      "tenant-a",

    requestId:
      "req-123"
  },

  async () => {
    await applicationLogic();
  }
);

Inside applicationLogic():

const context =
  getContext();

console.log(
  context?.tenantId
);

The application does not have to forward the tenant through every intermediate function manually.

The important part is not AsyncLocalStorage itself

AsyncLocalStorage solves propagation.

It does not define your architecture.

You still need to decide:

Who establishes the context?

What belongs inside it?

Who is allowed to read it?

How does tenant identity resolve infrastructure?

How are transactions added?

How does context interact with models?

How is the boundary cleaned up?

What happens outside HTTP?

Those decisions are where context turns into runtime design.

The HTTP adapter becomes an execution boundary

In an HTTP application, the framework boundary is a natural place to resolve execution state.

Conceptually:

HTTP Request
      ↓
Framework Middleware
      ↓
Tenant Resolution
      ↓
Request ID
      ↓
Execution Context
      ↓
Application Logic

For example:

app.use(
  async (
    req,
    res,
    next
  ) => {
    const tenantId =
      req.header(
        "x-tenant-id"
      );

    if (!tenantId) {
      return res
        .status(400)
        .json({
          error:
            "Tenant is required."
        });
    }

    const requestId =
      crypto.randomUUID();

    return runWithContext(
      {
        tenantId,
        requestId
      },

      async () => {
        next();
      }
    );
  }
);

The exact implementation varies by framework.

The architectural idea does not:

Resolve execution state at the boundary, then let the runtime carry it.

Tenant resolution and tenant infrastructure are different problems

This separation is particularly important in multi-tenant systems.

The incoming request may tell us:

tenant-a

That answers:

Who is this execution for?

It does not necessarily answer:

Which MongoDB client or database should handle it?

That is an infrastructure problem.

A useful separation is:

Request
      ↓
Tenant Resolver
      ↓
tenantId
      ↓
Execution Context
      ↓
Application
      ↓
Tenant Infrastructure Resolver
      ↓
MongoClient
      ↓
Tenant Database

The request carries tenant identity.

The infrastructure layer owns tenant topology.

That means application code does not need to know that:

tenant-a

currently maps to:

mongodb://cluster-3
database: workspace_eu_17

Those details can change without changing application behavior.

This becomes even more important with models

Consider:

await UserModel.find({
  active: true
});

In a context-aware runtime, that operation can conceptually resolve:

UserModel.find()
      ↓
Active Execution Context
      ↓
tenantId
      ↓
Tenant Infrastructure
      ↓
Correct Database
      ↓
users collection

The application remains focused on:

find active users

while infrastructure resolves:

where this operation belongs

This is much easier to reason about than passing the database identity through every service method.

Transactions reveal why context matters

Transactions make the value of execution context even clearer.

Imagine a workflow:

Create User
      +
Write Audit Log

Both operations should participate in one MongoDB transaction.

A manual approach often means passing the session everywhere:

await createUser(
  input,
  session
);

await createAuditLog(
  audit,
  session
);

That works.

But it pushes transaction plumbing into application APIs.

A context-aware execution can instead establish the session at the transaction boundary:

Transaction Boundary
      ↓
ClientSession
      ↓
Execution Context
      ↓
UserModel
      +
AuditLogModel

Both participating operations can resolve the same active session.

The important principle is:

The transaction boundary owns atomicity. Individual model operations participate in that boundary.

Again, execution state is doing more than carrying metadata.

It is preserving runtime behavior.

Context also improves instrumentation

Suppose every database operation produces an instrumentation signal.

Without execution context, a signal might look like:

{
  "operation": "find",
  "collection": "users"
}

That tells us something happened.

But not much else.

With execution context:

{
  "requestId": "req-123",
  "tenantId": "tenant-a",
  "operation": "find",
  "collection": "users"
}

Now the operation can be correlated with the execution that caused it.

That becomes useful for:

structured logging
query analysis
latency investigation
tenant-level usage patterns
debugging
operational monitoring

Instrumentation becomes far more meaningful when runtime identity automatically follows execution.

Context is not authorization

There is an important security boundary here.

Resolving:

tenantId = tenant-a

does not prove that the caller is allowed to operate on Tenant A.

These remain separate concerns:

Authentication
→ Who is the caller?

Tenant Resolution
→ Which tenant is this execution for?

Authorization
→ May this caller act for this tenant?

Execution context can carry tenant identity after those decisions are made.

It should not be mistaken for the authorization decision itself.

That distinction is especially important when tenant identity comes from something as simple as an HTTP header.

Request context eventually becomes execution context

The phrase request context is useful when discussing HTTP.

But the architecture eventually outgrows the request.

Consider a background worker:

Queue Job
      ↓
tenantId
      ↓
Worker Handler
      ↓
Execution Context
      ↓
UserModel

There is no HTTP request.

The same is true for:

scheduled tasks
event consumers
CLI commands
migration scripts
serverless invocations
MCP tool calls
agent workflows

So the more general concept is not request context.

It is execution context.

HTTP is simply one way to enter that execution.

This is where context becomes infrastructure

At this point the context is coordinating:

tenant identity

request or job identity

database resolution

transaction continuity

logging metadata

instrumentation

model execution

That is no longer a convenience object.

It is runtime infrastructure.

A useful mental model is:

Execution Source
      ↓
Execution Boundary
      ↓
Context
      ↓
Application Logic
      ↓
Persistence Runtime
      ↓
Infrastructure

The application should still own its business logic.

The runtime should own the consistency of execution state.

Where Ambiten fits into this idea

This runtime problem is one of the reasons I have been building Ambiten.

Ambiten is a context-aware runtime for MongoDB applications.

The goal is not to hide MongoDB behind an entirely different programming model.

The goal is to give execution concerns a consistent place to live.

Conceptually:

Request / Worker / Agent
          ↓
    Execution Boundary
          ↓
     AmbitenContext
          ↓
     Application
          ↓
     AmbitenModel
          ↓
 Effective ModelContext
          ↓
Tenant / Transaction /
Middleware / Instrumentation
          ↓
       MongoDB

The application can still perform familiar operations such as:

await UserModel.find({});

await UserModel.create({
  name:
    "Ada"
});

But the runtime can already know:

which tenant is active

which transaction session exists

which database should be used

which instrumentation belongs
to the execution

That allows infrastructure concerns to stay out of the business API without making them implicit global state.

The important word is boundary

Context is useful only when its boundaries are clear.

You should know where execution begins.

You should know what state belongs to it.

You should know when that state stops being valid.

A healthy model looks like:

PROCESS
      ↓
Reusable Infrastructure

EXECUTION
      ↓
Context

OPERATION
      ↓
Model / Database Work

Process infrastructure may live for hours.

An execution may live for milliseconds or seconds.

A database operation may be shorter still.

Keeping those lifetimes separate makes multi-tenant systems easier to reason about.

Final thought

Multi-tenancy is often introduced as a database-routing problem.

It is bigger than that.

Once an application has to preserve tenant identity across services, transactions, models, logs, workers, and instrumentation, the deeper problem is execution consistency.

That is why request context eventually becomes infrastructure.

Not because every variable belongs in context.

Not because function arguments are bad.

But because some state describes the execution itself.

And once that state affects where operations run, which transaction they join, and how they are observed, it deserves a runtime boundary of its own.