Improvements to decorated middleware

[HamishWHC]

These are some features for decorated middleware that I feel are missing right now.

1. $meta/meta combining meta objects (similarly to context returned from middleware) instead of replacing it entirely. Alternatively, the ability to pass a function to transform the existing metadata. A key use-case I'd like this for is the ability to make all procedures that .use a decorated middleware have some metadata related to that middleware (e.g. a permissions-checking middleware that adds metadata that describe the required permissions, which I can then use to modify my OpenAPI document to document permissions automatically).
2. The ability to use .errors and .$meta decorated middleware, before using .concat, so that I can then .concat another middleware that uses/adds the new errors/metadata.

Code example of what I'm hoping will be possible

import { os } from "@orpc/server";
import { getCookie, getHeader } from "vinxi/http";

export type Context = { user: { id: string; admin: boolean } | null };

const _base = os
	.$context<Partial<Context>>()
	.$meta({ requiresAuth: false, requiresAdmin: false })
	.$route({ inputStructure: "detailed", outputStructure: "detailed", method: "GET" });

const base = _base.use(({ context, next }) => {
	return next({ context: context ?? { user: null } });
});

const mBase = _base.$context<Context>();
const requireAuth = mBase
	.$meta({ requiresAuth: true })
	.errors({
		FORBIDDEN: {
			status: 403,
			description: "You must be authenticated to use this route.",
			message: "You must be authenticated to use this route.",
		},
	})
	.middleware(({ next, errors }) => {
		const auth = getHeader("Authorization");
		if (auth) {
			const match = /^Bearer ([A-Za-z0-9_-]*\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*)$/i.exec(auth);
			if (match) {
				return next({
					context: {
						user: { id: match[1], admin: true },
					},
				});
			} else {
				throw errors.FORBIDDEN({
					message: "Invalid `Authorization` header.",
				});
			}
		}

		const session = getCookie("session");
		if (session) {
			return next({
				context: {
					user: { id: session, admin: false },
				},
			});
		}

		throw errors.FORBIDDEN({
			message: "Missing `Authorization` header or `session` cookie.",
		});
	});

const requireAdmin = requireAuth
	.$meta({ requiresAdmin: true })
	.errors({
		ADMIN_REQUIRED: {
			status: 401,
			description: "You must be an admin to use this route.",
			message: "You must be an admin to use this route.",
		},
	})
	.concat(async ({ errors, context, next }) => {
		if (!context.user.admin) {
			throw errors.ADMIN_REQUIRED();
		}

		return next({});
	});

Let me know what you think!

[unnoq]

I understand that you want a way to customize the OpenAPI spec based on middleware. However, I believe we can achieve this in a simpler way by using middleware references.

Here’s a draft implementation:

const openAPIGenerator = new OpenAPIGenerator({
  a_hook_that_allows_you_to_override_specs: (procedure, oldSpec) => {
    if (procedure['~orpc'].middlewares.includes(requireAuthMiddleware)) {
      return modifiedSpec;
    }
    
    return oldSpec;
  }
});

Additionally, I think we should stick with the current meta behavior. Meta is useful when you want to build on top of oRPC or when you need reusable logic, such as:

const _base = os.$meta<{ requireAuth?: boolean }>({});

const base = _base.use(({ next, procedure }) => {
  if (procedure['~orpc'].meta.requireAuth) {
    // Perform authentication check here
  }

  return next();
});

To define .errors before .concat, I believe we can achieve this by creating two separate middleware functions and concatenating them. However, I think you want to attach errors inside the middleware so that when .use is called, the error is automatically associated with that procedure. If that's the case, it might be a bit challenging at the moment, but it's still possible if it's actually useful.

[unnoq]

I think we find the best way now for customize openapi spec base on middleware or error-map (if you use contract-first)

const middlewareOrErrorMapItem = oo.spec(middlewareOrErrorMapItem_, { // or a callback allow you override specs
  security: [
    {
      'api-key': [],
    },
  ],
}) 

// middlewareOrErrorMapItem can use directly as middleware or error map item

[unnoq]

This api has been available in oRPC

[unnoq]

I think we need to conclude that we can't support this, at least for now.

[HananoshikaYomaru]

what does this mean? I am trying out the spec but it doesn't seem to do anything.

[unnoq]

Here is the docs for oo.spec https://orpc.unnoq.com/docs/openapi/openapi-specification#customizing-operation-objects