Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ls1vMdg2GYqbnKZmPaX1ot
125 lines
5.0 KiB
TypeScript
125 lines
5.0 KiB
TypeScript
import type { Request, RequestHandler, Response, Router } from 'express';
|
|
import { z } from 'zod';
|
|
import { ApiError } from './errors';
|
|
import auth from '../middleware/authMiddleware';
|
|
|
|
/**
|
|
* Every /api/v2 endpoint is declared with `defineRoute`: method, path, who may call it, and zod
|
|
* schemas for the params, query, body and response. The same declaration
|
|
* - validates the request (400 VALIDATION_FAILED with per-field messages),
|
|
* - checks the response against its schema and strips anything it doesn't list (so a field
|
|
* can't leak by being added to a Prisma include), and
|
|
* - becomes the OpenAPI document (openapi.ts) — the docs can't drift from the code.
|
|
*/
|
|
|
|
export type Access = 'public' | 'optional' | 'user' | 'staff' | 'supervisor' | 'admin';
|
|
|
|
/** The signed-in person, as the auth middleware puts it on the request. */
|
|
export type ApiUser = { id: string; name: string; email: string; role: 'admin' | 'supervisor' | 'staff' | 'user' };
|
|
|
|
export type Ctx<P, Q, B> = {
|
|
params: P;
|
|
query: Q;
|
|
body: B;
|
|
user: ApiUser | null;
|
|
req: Request;
|
|
res: Response;
|
|
};
|
|
|
|
type Schema = z.ZodType;
|
|
type Infer<S> = S extends z.ZodType ? z.infer<S> : undefined;
|
|
|
|
export type RouteDef<P extends Schema | undefined, Q extends Schema | undefined, B extends Schema | undefined, R extends Schema> = {
|
|
method: 'get' | 'post' | 'put' | 'patch' | 'delete';
|
|
/** Express-style, relative to /api/v2: "/events/:id". */
|
|
path: string;
|
|
summary: string;
|
|
description?: string;
|
|
tag: string;
|
|
access: Access;
|
|
/**
|
|
* Staff and supervisor routes must say how they treat campus-scoped staff (see
|
|
* utils/campusScope.js and tests/campusScopeRoutes.test.js) — e.g. "scopeEvent(params.id)".
|
|
*/
|
|
campusScope?: string;
|
|
params?: P;
|
|
query?: Q;
|
|
body?: B;
|
|
response: R;
|
|
/** HTTP status on success (default 200). */
|
|
status?: number;
|
|
/** Runs after the access check, e.g. a rate limiter. */
|
|
middleware?: RequestHandler[];
|
|
/** A multipart upload (the file in `field`, saved by a multer step in `middleware`). */
|
|
upload?: { field: string; description: string };
|
|
/**
|
|
* The answer is a file, not JSON: the handler returns `{ data: { contentType, filename, body } }`
|
|
* and `response` is `fileResponse`. `contentType` here is what the docs show.
|
|
*/
|
|
file?: { contentType: string };
|
|
handler: (ctx: Ctx<Infer<P>, Infer<Q>, Infer<B>>) => Promise<z.input<R>> | z.input<R>;
|
|
};
|
|
|
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
export type AnyRoute = RouteDef<any, any, any, any>;
|
|
|
|
export const routes: AnyRoute[] = [];
|
|
|
|
const ACCESS: Record<Access, RequestHandler[]> = {
|
|
public: [],
|
|
optional: [auth.optionalAuth],
|
|
user: [auth.protect],
|
|
staff: [auth.protect, auth.staff],
|
|
supervisor: [auth.protect, auth.supervisor],
|
|
admin: [auth.protect, auth.admin],
|
|
};
|
|
|
|
export function defineRoute<P extends Schema | undefined, Q extends Schema | undefined, B extends Schema | undefined, R extends Schema>(def: RouteDef<P, Q, B, R>): RouteDef<P, Q, B, R> {
|
|
if ((def.access === 'staff' || def.access === 'supervisor') && !def.campusScope) {
|
|
throw new Error(`${def.method.toUpperCase()} /api/v2${def.path}: staff and supervisor routes must declare campusScope`);
|
|
}
|
|
routes.push(def as AnyRoute);
|
|
return def;
|
|
}
|
|
|
|
const parse = <S extends Schema | undefined>(schema: S, value: unknown): Infer<S> =>
|
|
(schema ? schema.parse(value) : undefined) as Infer<S>;
|
|
|
|
/** Adds every defined route to the router. */
|
|
export function mount(router: Router, list: AnyRoute[] = routes): void {
|
|
for (const def of list) {
|
|
const run: RequestHandler = async (req, res, next) => {
|
|
try {
|
|
const ctx = {
|
|
params: parse(def.params, req.params),
|
|
query: parse(def.query, req.query),
|
|
body: parse(def.body, req.body ?? {}),
|
|
user: (req as Request & { user?: ApiUser }).user ?? null,
|
|
req,
|
|
res,
|
|
};
|
|
const result = await def.handler(ctx);
|
|
const checked = def.response.safeParse(result);
|
|
if (!checked.success) {
|
|
console.error(`[api/v2] ${def.method.toUpperCase()} ${def.path}: response doesn't match its schema`, checked.error.issues);
|
|
throw new ApiError('INTERNAL', 'Something went wrong on the server.');
|
|
}
|
|
if (def.file) {
|
|
const f = (checked.data as { data: { contentType: string; filename: string; body: string } }).data;
|
|
res.setHeader('Content-Type', f.contentType);
|
|
res.setHeader('Content-Disposition', `attachment; filename="${f.filename.replace(/"/g, '')}"`);
|
|
res.status(def.status ?? 200).send(f.body);
|
|
return;
|
|
}
|
|
res.status(def.status ?? 200).json(checked.data);
|
|
} catch (err) {
|
|
next(err);
|
|
}
|
|
};
|
|
router[def.method](def.path, ...ACCESS[def.access], ...(def.middleware ?? []), run);
|
|
}
|
|
}
|
|
|
|
/** The `response` of a `file` route: what the handler hands back to be sent as a download. */
|
|
export const fileResponse = z.object({ data: z.object({ contentType: z.string(), filename: z.string(), body: z.string() }) });
|