openapi, contract, and errors in middleware

[stuartin]

I'm just starting to play around with orpc and its amazing getting things up and running so quickly - thanks for your hard work!

I'm using contract first development approach with open API and using scalar to render things, this is all appears to be working.
I've started looking into adding some context, middleware and auth type things and had some questions.

Can we allow middleware to update openapi spec regarding errors/responses?

contract

export const PlanetSchema = z.object({
    id: z.number().int().min(1),
    name: z.string(),
    description: z.string().optional(),
})

export const planetsContract = oc
    .router({
        list: oc
            .route({ method: 'GET', path: '/planets', description: "get a list of planets" })
            .input(
                z.object({
                    limit: z.number().int().min(1).max(100).optional(),
                    cursor: z.number().int().min(0).default(0),
                }),
            )
            .output(z.array(PlanetSchema)),

        find: oc
            .route({ method: 'GET', path: '/planets/{id}', description: "get a planet" })
            .input(PlanetSchema.pick({ id: true }))
            .output(PlanetSchema),

        create: oc
            .route({ method: 'PUT', path: '/planets', description: "create a planet" })
            // Adding this has the desired affect
            //
            // .errors({
            //     UNAUTHORIZED: oo.spec({}, {
            //         security: authDocs.security
            //     })
            // })
            .input(PlanetSchema.omit({ id: true }))
            .output(PlanetSchema)
    })

router

const os = createRouter(planetsContract) // <-- Ensures Context type is set: implement<typeof contract, Context>(contract)

export const planetsRouter = os
    .router({
        list: os.list
            .handler(({ input }) => {
                return [{ id: 123, name: "Planet X" }]
            }),
        find: os.find
            .handler(({ input }) => {
                return { id: 123, name: 'Planet X' }
            }),
        create: os.create
            .use(requireAuth)
            .handler(({ input }) => {
                return { id: 123, name: 'Planet X' }
            })
    })

openapi spec

const openAPIGenerator = new OpenAPIGenerator({
    schemaConverters: [
        new ZodToJsonSchemaConverter(),
    ],
})

const apiSpec = await openAPIGenerator.generate(planetsContract, {
        info: {
            title: 'My App',
            version: '0.0.0',
        },
    }),
    components: {
        securitySchemes: authDocs.securitySchemes
    }
})

require auth

export const requireAuth = os
    .$context<Context>()
    .errors({
        UNAUTHORIZED: oo.spec({}, {
            security: authDocs.security // <-- This doesnt have any affect
        })
    })
    .middleware(async ({ context, next, errors }) => {
        if (!context.user) throw errors.UNAUTHORIZED()
        return next()
    })

With the above code, the generated responses for PUT /planets does not list 401 unauthorized, even though the middleware is on the router.

Using oo.spec() on the contract allows me to ensure it is marked with the correct security/auth, but this means I have to duplicate it on all my contracts instead of just on the middleware, and middleware can only be implemented on the router.

Is there a way to work around this? While also maintaining type safe errors on the client?

[unnoq]

You can reduce duplication when defining oo.spec() like this:

import { oc } from '@orpc/contract'

const publicContractBuilder = oc

const authedContractBuilder = publicContractBuilder.errors({
  UNAUTHORIZED: oo.spec({}, {
    security: authDocs.security
  })
})

Now, any contract built using authedContractBuilder will automatically include the UNAUTHORIZED error and apply authDocs.security as its security scheme.

[stuartin]

Thanks for the prompt answer!
I should be able to work with this, is it possible to have the contract enforced on the implementation side?
So if we have a contract that uses the authedContractBuilder it must have the requireAuth middleware (or something that throws the ORCPError('UNAUTHORIZED'))?

[unnoq]

Something like this:

const base = os.use(({ context, errors, procedure, path, next }) => {

   if("UNAUTHORIZED" in errors && !procedure['~orpc'].middlewares.includes(authMiddleware)){
      throw new Error('Missing implement authMiddleware for procedure at: ' + path.join('.'))
   }

  return next()
})