Support passing custom metadata per query to middleware

Problem

Currently the middleware are essentially stateless. There is one example that uses global state but in practice this is not very common nor desirable. It would be necessary for a tracing middleware.

Suggested solution

It would be nice if all prisma calls add a context parameter that would be passed down to middlewares. It could look like:

export type TicketCreateArgs = {
    select?: TicketSelect | null
    include?: TicketInclude | null
    data: XOR<TicketCreateInput, TicketUncheckedCreateInput>
    context: Record<string, any>
}

export type MiddlewareParams = {
    model?: ModelName
    action: PrismaAction
    args: any
    dataPath: string[]
    runInTransaction: boolean
    context: Record<string, any>
}

Alternatives

No good alternative currently if you want to respect typing, unsure if I could pass the context in the data and remove it in the middleware, but I would prefer not too.

[lorenzobersano]

Any news about this feature? I would love it in order to cleanly implement audit trails using Prisma Middlewares 🙂

[matthewmueller]

Hey folks, we started speccing this out this and we’re ready to share our proposal. Please let us know what you think! I’d also like to invite you to jump on a quick call with me to get your thoughts on the proposal.

Overview

Today Prisma users can’t selectively opt-in or out of middleware functionality.

If we allowed developers to turn on certain middleware per-query, we could make middleware more useful because the middleware would be able to make decisions based on the context the query was made.

Use Cases

• Custom middleware that omits returning the password everywhere except login: https://github.com/prisma/prisma/issues/4217
• Using metadata to run a set roles and users in a custom middleware for row-level security (RLS): https://github.com/prisma/prisma/issues/5128#issuecomment-848890199 & https://github.com/prisma/prisma/issues/10895
• Selectively decrypt certain fields: https://github.com/prisma/prisma/issues/9879
  • For example, if a metadata object containing { decrypt: true } is passed, we decrypt fields. Otherwise the default is to pass fields back to the application in their encrypted state.
• Pass a trace ID through and use custom middleware to add tracing: https://github.com/prisma/prisma/issues/6882
• Soft Delete middleware from cal.com
• https://github.com/prisma/prisma/issues/62816882

Goals and Product Requirements

• You can pass arbitrary data per query to middleware
• The metadata is modifiable along the middleware chain
• Nice to have: There should be some way for users to make it type-safe.
  • Sharing a user-defined type across files would be fine.

Out of Scope

• Automatically passing context to multiple queries: We can potentially address this with a feature like Model Scopes, but for now you need to pass metadata per query.

Open Questions

• How would this affect transaction rollbacks?
• Would middleware be the only part of the API that has access to this metadata?
• Is there a use case for global metadata? (PR includes this support)

Approach

Add support for a meta field that can to be passed through all of our query objects code. This meta field would be accessible through the middleware stack:

// include a password only when explicitly passed in
prisma.$use(async (params, next) => {
  const result = await next(params);

  // TODO: is there a way to make "params.meta" type-safe?
  if (params.model === "User" && !params.meta.includePassword) {
    const { password, ...rest } = result;
    return rest;
  }

  return result;
})

// encrypt by default
prisma.$use(async (params, next) => {
  if (params.model !== "User") {
    return next(params)
  }
  // encrypt by default
  if (params.action == "create") {
    if (args.data["secret"]) {
      args.data["secret"] = encrypt(secretKey, args.data["secret"])
    }
  }
  // pass along
  const result = await next(params);
  // return encrypted unless
  if (params.meta.decrypt) {
    result["secret"] = decrypt(secretKey, result["secret"])
  }
  return result
})

All APIs that can be modified by middleware would support this meta field:

// Omit passwords unless includePassword is true
prisma.user.findMany({
  where: {
    email: "[e-mail]"
  },
  meta: {
    includePassword: true
  },
})

// Encrypt secrets unless decrypt is true
prisma.user.findMany({
  where: {
    email: "[e-mail]"
  },
  meta: {
    decrypt: true
  },
})

// Create an encrypted user that gets returned back encrypted
prisma.user.create({
  data: {
    name: "Alice",
    email: "[e-mail]",
    secret: "my dark secret",
  },
  meta: {
    decrypt: false
  },
})

// Yes, even groupBy!
prisma.user.groupBy({
  by: ["email"]
  meta: {
    decrypt: true
  },
})

Type of basic meta field is defined in Prisma namespace as:

interface Meta {
   [key:string]: unknown.
}

Additionally, we define a meta type for all of the actions, for example:

interface FindFirstMeta extends Meta {
}

Each action method signature will use it’s corresponding meta type.

This allows meta property to accept any data without type-checking. If users want to have a stricter type checking for the meta fields that make sense for their application, they have an option to augment provided interfaces in their codebases. For example, decrypt middleware can ensure strict type-checking for decrypt prop by declaring:

declare module "@prisma/client" {
  export namespace Prisma {
      export interface Meta {
        decrypt?: boolean;
     }
  }
}

If certain option makes sense only for specific action, users have an option to augment only this actions interface. For example, soft delete middleware could do:

declare module "@prisma/client" {
  export namespace Prisma {
      export interface DeleteMeta {
        soft?: boolean;
     }
  }
}

References

• Discussion that aggregated some of these requests together https://github.com/prisma/prisma/discussions/13366