From fb22ec145f05604565d9eb0aebd5ae89443a6ceb Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Nov 2026 17:08:16 +0000 Subject: [PATCH] fix(report): answer 503 with a stable error code when the PDF render queue is full PdfRenderQueueTimeoutError used to fall through AllExceptionsFilter as a generic 500 "Internal server error". It is a temporary overload, not a server bug, so reply 503 with `code: 'PDF_RENDER_BUSY'`, an English fallback message and a Retry-After header. Clients map the code to a localized "busy, try again shortly" message. Fixes buzz-code/ops#46 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012GTics1vhDVoBFRPcg7nSn --- .../__tests__/all-exceptions.filter.spec.ts | 21 +++++++++++++++++++ utils/logging/all-exceptions.filter.ts | 18 ++++++++++++++++ utils/report/pdf-render.queue.ts | 6 ++++++ 3 files changed, 45 insertions(+) diff --git a/utils/logging/__tests__/all-exceptions.filter.spec.ts b/utils/logging/__tests__/all-exceptions.filter.spec.ts index aee575f..a9fd97b 100644 --- a/utils/logging/__tests__/all-exceptions.filter.spec.ts +++ b/utils/logging/__tests__/all-exceptions.filter.spec.ts @@ -1,6 +1,7 @@ import { BadRequestException } from '@nestjs/common'; import { QueryFailedError } from 'typeorm'; import { AllExceptionsFilter } from '../all-exceptions.filter'; +import { PdfRenderQueueTimeoutError } from '../../report/pdf-render.queue'; function buildFkViolation(referencingTable: string) { const sqlMessage = `Cannot delete or update a parent row: a foreign key constraint fails (\`app_db\`.\`${referencingTable}\`, CONSTRAINT \`FK_x\` FOREIGN KEY (\`teacherReferenceId\`) REFERENCES \`teachers\` (\`id\`))`; @@ -29,6 +30,26 @@ function buildHost(response: any) { } describe('AllExceptionsFilter', () => { + it('replies 503 with the PDF_RENDER_BUSY code and a Retry-After header when the PDF render queue is full', () => { + const httpAdapter = { reply: jest.fn(), setHeader: jest.fn() }; + const filter = new AllExceptionsFilter(httpAdapter as any); + const response: any = {}; + + filter.catch(new PdfRenderQueueTimeoutError(20000, 2), buildHost(response)); + + expect(response.err).toBeUndefined(); + expect(httpAdapter.setHeader).toHaveBeenCalledWith(response, 'Retry-After', '60'); + expect(httpAdapter.reply).toHaveBeenCalledWith( + response, + { + statusCode: 503, + code: 'PDF_RENDER_BUSY', + message: 'PDF generation is busy with other requests. Please try again in a few minutes.', + }, + 503, + ); + }); + it('attaches a non-HttpException to response.err (for pino-http to log) and replies 500', () => { const httpAdapter = { reply: jest.fn() }; const filter = new AllExceptionsFilter(httpAdapter as any); diff --git a/utils/logging/all-exceptions.filter.ts b/utils/logging/all-exceptions.filter.ts index d5f802c..96dd12c 100644 --- a/utils/logging/all-exceptions.filter.ts +++ b/utils/logging/all-exceptions.filter.ts @@ -2,6 +2,7 @@ import { ArgumentsHost, Catch, ExceptionFilter, HttpException, HttpServer, HttpS import { snakeCase } from 'change-case'; import { DataSource, QueryFailedError } from 'typeorm'; import { getTranslatedProperty } from '@shared/utils/validation/class-validator-he'; +import { PdfRenderQueueTimeoutError } from '@shared/utils/report/pdf-render.queue'; interface MysqlDriverError { code?: string; @@ -49,6 +50,9 @@ function getReferencingTable(exception: QueryFailedError): string | null { return match?.[1] || null; } +// Suggested client back-off when the PDF render queue is full. +const PDF_RENDER_BUSY_RETRY_AFTER_SECONDS = 60; + @Catch() export class AllExceptionsFilter implements ExceptionFilter { private readonly logger = new Logger(AllExceptionsFilter.name); @@ -104,6 +108,20 @@ export class AllExceptionsFilter implements ExceptionFilter { return; } + if (exception instanceof PdfRenderQueueTimeoutError) { + // Too many PDF renders at once: a temporary overload, not a server bug. + // The client translates `code` into a localized "try again shortly" message. + this.logger.warn(exception.message); + const body = { + statusCode: HttpStatus.SERVICE_UNAVAILABLE, + code: exception.code, + message: 'PDF generation is busy with other requests. Please try again in a few minutes.', + }; + this.httpAdapter.setHeader(response, 'Retry-After', String(PDF_RENDER_BUSY_RETRY_AFTER_SECONDS)); + this.httpAdapter.reply(response, body, HttpStatus.SERVICE_UNAVAILABLE); + return; + } + const isHttpException = exception instanceof HttpException; const status = isHttpException ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR; const body = isHttpException diff --git a/utils/report/pdf-render.queue.ts b/utils/report/pdf-render.queue.ts index 16b0c3d..d2a71f9 100644 --- a/utils/report/pdf-render.queue.ts +++ b/utils/report/pdf-render.queue.ts @@ -33,7 +33,13 @@ export function getPdfRenderBudgetMs(): number { return Number.isFinite(configured) && configured > 0 ? configured : 45000; } +export const PDF_RENDER_BUSY_CODE = 'PDF_RENDER_BUSY'; + export class PdfRenderQueueTimeoutError extends Error { + // Stable machine-readable code: the HTTP layer sends it to clients, which + // map it to a localized "busy, try again" message. + readonly code = PDF_RENDER_BUSY_CODE; + constructor(allowedWaitMs: number, maxConcurrentBrowsers: number) { super(`PDF render queue wait exceeded ${allowedWaitMs}ms (max ${maxConcurrentBrowsers} concurrent browsers)`); this.name = 'PdfRenderQueueTimeoutError';