Document rate limit headers in OpenAPI spec
Some checks failed
Build & Deploy to Staging / Build & Deploy to Staging (push) Has been cancelled
Some checks failed
Build & Deploy to Staging / Build & Deploy to Staging (push) Has been cancelled
- Add reusable header components (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After) - Reference headers in 200 responses on all conversion and demo endpoints - Add Retry-After header to 429 responses - Update Rate Limits section in API description to mention response headers - Add comprehensive tests for header documentation (21 new tests) - All 809 tests passing
This commit is contained in:
OpenClaw Subagent
parent
a3bba8f0d5
commit
70eb6908e3
18 changed files with 801 additions and 821 deletions
183
dist/routes/convert.js
vendored
183
dist/routes/convert.js
vendored
|
|
@ -2,10 +2,9 @@ import { Router } from "express";
|
|||
import { renderPdf, renderUrlPdf } from "../services/browser.js";
|
||||
import { markdownToHtml, wrapHtml } from "../services/markdown.js";
|
||||
import dns from "node:dns/promises";
|
||||
import logger from "../services/logger.js";
|
||||
import { isPrivateIP } from "../utils/network.js";
|
||||
import { sanitizeFilename } from "../utils/sanitize.js";
|
||||
import { validatePdfOptions } from "../utils/pdf-options.js";
|
||||
import { handlePdfRoute } from "../utils/pdf-handler.js";
|
||||
export const convertRouter = Router();
|
||||
/**
|
||||
* @openapi
|
||||
|
|
@ -38,6 +37,13 @@ export const convertRouter = Router();
|
|||
* responses:
|
||||
* 200:
|
||||
* description: PDF document
|
||||
* headers:
|
||||
* X-RateLimit-Limit:
|
||||
* $ref: '#/components/headers/X-RateLimit-Limit'
|
||||
* X-RateLimit-Remaining:
|
||||
* $ref: '#/components/headers/X-RateLimit-Remaining'
|
||||
* X-RateLimit-Reset:
|
||||
* $ref: '#/components/headers/X-RateLimit-Reset'
|
||||
* content:
|
||||
* application/pdf:
|
||||
* schema:
|
||||
|
|
@ -53,60 +59,25 @@ export const convertRouter = Router();
|
|||
* description: Unsupported Content-Type (must be application/json)
|
||||
* 429:
|
||||
* description: Rate limit or usage limit exceeded
|
||||
* headers:
|
||||
* Retry-After:
|
||||
* $ref: '#/components/headers/Retry-After'
|
||||
* 500:
|
||||
* description: PDF generation failed
|
||||
*/
|
||||
convertRouter.post("/html", async (req, res) => {
|
||||
let slotAcquired = false;
|
||||
try {
|
||||
// Reject non-JSON content types
|
||||
const ct = req.headers["content-type"] || "";
|
||||
if (!ct.includes("application/json")) {
|
||||
res.status(415).json({ error: "Unsupported Content-Type. Use application/json." });
|
||||
return;
|
||||
}
|
||||
await handlePdfRoute(req, res, async (sanitizedOptions) => {
|
||||
const body = typeof req.body === "string" ? { html: req.body } : req.body;
|
||||
if (!body.html) {
|
||||
res.status(400).json({ error: "Missing 'html' field" });
|
||||
return;
|
||||
return null;
|
||||
}
|
||||
// Validate PDF options
|
||||
const validation = validatePdfOptions(body);
|
||||
if (!validation.valid) {
|
||||
res.status(400).json({ error: validation.error });
|
||||
return;
|
||||
}
|
||||
// Acquire concurrency slot
|
||||
if (req.acquirePdfSlot) {
|
||||
await req.acquirePdfSlot();
|
||||
slotAcquired = true;
|
||||
}
|
||||
// Wrap bare HTML fragments
|
||||
const fullHtml = body.html.includes("<html")
|
||||
? body.html
|
||||
: wrapHtml(body.html, body.css);
|
||||
const { pdf, durationMs } = await renderPdf(fullHtml, {
|
||||
...validation.sanitized,
|
||||
});
|
||||
const filename = sanitizeFilename(body.filename || "document.pdf");
|
||||
res.setHeader("Content-Type", "application/pdf");
|
||||
res.setHeader("Content-Disposition", `inline; filename="${filename}"`);
|
||||
res.setHeader("X-Render-Time", String(durationMs));
|
||||
res.send(pdf);
|
||||
}
|
||||
catch (err) {
|
||||
logger.error({ err }, "Convert HTML error");
|
||||
if (err.message === "QUEUE_FULL") {
|
||||
res.status(429).json({ error: "Server busy - too many concurrent PDF generations. Please try again in a few seconds." });
|
||||
return;
|
||||
}
|
||||
res.status(500).json({ error: `PDF generation failed: ${err.message}` });
|
||||
}
|
||||
finally {
|
||||
if (slotAcquired && req.releasePdfSlot) {
|
||||
req.releasePdfSlot();
|
||||
}
|
||||
}
|
||||
const { pdf, durationMs } = await renderPdf(fullHtml, { ...sanitizedOptions });
|
||||
return { pdf, durationMs, filename: sanitizeFilename(body.filename || "document.pdf") };
|
||||
});
|
||||
});
|
||||
/**
|
||||
* @openapi
|
||||
|
|
@ -138,6 +109,13 @@ convertRouter.post("/html", async (req, res) => {
|
|||
* responses:
|
||||
* 200:
|
||||
* description: PDF document
|
||||
* headers:
|
||||
* X-RateLimit-Limit:
|
||||
* $ref: '#/components/headers/X-RateLimit-Limit'
|
||||
* X-RateLimit-Remaining:
|
||||
* $ref: '#/components/headers/X-RateLimit-Remaining'
|
||||
* X-RateLimit-Reset:
|
||||
* $ref: '#/components/headers/X-RateLimit-Reset'
|
||||
* content:
|
||||
* application/pdf:
|
||||
* schema:
|
||||
|
|
@ -153,57 +131,23 @@ convertRouter.post("/html", async (req, res) => {
|
|||
* description: Unsupported Content-Type
|
||||
* 429:
|
||||
* description: Rate limit or usage limit exceeded
|
||||
* headers:
|
||||
* Retry-After:
|
||||
* $ref: '#/components/headers/Retry-After'
|
||||
* 500:
|
||||
* description: PDF generation failed
|
||||
*/
|
||||
convertRouter.post("/markdown", async (req, res) => {
|
||||
let slotAcquired = false;
|
||||
try {
|
||||
// Reject non-JSON content types
|
||||
const ct = req.headers["content-type"] || "";
|
||||
if (!ct.includes("application/json")) {
|
||||
res.status(415).json({ error: "Unsupported Content-Type. Use application/json." });
|
||||
return;
|
||||
}
|
||||
await handlePdfRoute(req, res, async (sanitizedOptions) => {
|
||||
const body = typeof req.body === "string" ? { markdown: req.body } : req.body;
|
||||
if (!body.markdown) {
|
||||
res.status(400).json({ error: "Missing 'markdown' field" });
|
||||
return;
|
||||
}
|
||||
// Validate PDF options
|
||||
const validation = validatePdfOptions(body);
|
||||
if (!validation.valid) {
|
||||
res.status(400).json({ error: validation.error });
|
||||
return;
|
||||
}
|
||||
// Acquire concurrency slot
|
||||
if (req.acquirePdfSlot) {
|
||||
await req.acquirePdfSlot();
|
||||
slotAcquired = true;
|
||||
return null;
|
||||
}
|
||||
const html = markdownToHtml(body.markdown, body.css);
|
||||
const { pdf, durationMs } = await renderPdf(html, {
|
||||
...validation.sanitized,
|
||||
});
|
||||
const filename = sanitizeFilename(body.filename || "document.pdf");
|
||||
res.setHeader("Content-Type", "application/pdf");
|
||||
res.setHeader("Content-Disposition", `inline; filename="${filename}"`);
|
||||
res.setHeader("X-Render-Time", String(durationMs));
|
||||
res.send(pdf);
|
||||
}
|
||||
catch (err) {
|
||||
logger.error({ err }, "Convert MD error");
|
||||
if (err.message === "QUEUE_FULL") {
|
||||
res.status(429).json({ error: "Server busy - too many concurrent PDF generations. Please try again in a few seconds." });
|
||||
return;
|
||||
}
|
||||
res.status(500).json({ error: `PDF generation failed: ${err.message}` });
|
||||
}
|
||||
finally {
|
||||
if (slotAcquired && req.releasePdfSlot) {
|
||||
req.releasePdfSlot();
|
||||
}
|
||||
}
|
||||
const { pdf, durationMs } = await renderPdf(html, { ...sanitizedOptions });
|
||||
return { pdf, durationMs, filename: sanitizeFilename(body.filename || "document.pdf") };
|
||||
});
|
||||
});
|
||||
/**
|
||||
* @openapi
|
||||
|
|
@ -240,6 +184,13 @@ convertRouter.post("/markdown", async (req, res) => {
|
|||
* responses:
|
||||
* 200:
|
||||
* description: PDF document
|
||||
* headers:
|
||||
* X-RateLimit-Limit:
|
||||
* $ref: '#/components/headers/X-RateLimit-Limit'
|
||||
* X-RateLimit-Remaining:
|
||||
* $ref: '#/components/headers/X-RateLimit-Remaining'
|
||||
* X-RateLimit-Reset:
|
||||
* $ref: '#/components/headers/X-RateLimit-Reset'
|
||||
* content:
|
||||
* application/pdf:
|
||||
* schema:
|
||||
|
|
@ -255,22 +206,18 @@ convertRouter.post("/markdown", async (req, res) => {
|
|||
* description: Unsupported Content-Type
|
||||
* 429:
|
||||
* description: Rate limit or usage limit exceeded
|
||||
* headers:
|
||||
* Retry-After:
|
||||
* $ref: '#/components/headers/Retry-After'
|
||||
* 500:
|
||||
* description: PDF generation failed
|
||||
*/
|
||||
convertRouter.post("/url", async (req, res) => {
|
||||
let slotAcquired = false;
|
||||
try {
|
||||
// Reject non-JSON content types
|
||||
const ct = req.headers["content-type"] || "";
|
||||
if (!ct.includes("application/json")) {
|
||||
res.status(415).json({ error: "Unsupported Content-Type. Use application/json." });
|
||||
return;
|
||||
}
|
||||
await handlePdfRoute(req, res, async (sanitizedOptions) => {
|
||||
const body = req.body;
|
||||
if (!body.url) {
|
||||
res.status(400).json({ error: "Missing 'url' field" });
|
||||
return;
|
||||
return null;
|
||||
}
|
||||
// URL validation + SSRF protection
|
||||
let parsed;
|
||||
|
|
@ -278,59 +225,31 @@ convertRouter.post("/url", async (req, res) => {
|
|||
parsed = new URL(body.url);
|
||||
if (!["http:", "https:"].includes(parsed.protocol)) {
|
||||
res.status(400).json({ error: "Only http/https URLs are supported" });
|
||||
return;
|
||||
return null;
|
||||
}
|
||||
}
|
||||
catch {
|
||||
res.status(400).json({ error: "Invalid URL" });
|
||||
return;
|
||||
return null;
|
||||
}
|
||||
// DNS lookup to block private/reserved IPs + pin resolution to prevent DNS rebinding
|
||||
// DNS lookup to block private/reserved IPs + pin resolution
|
||||
let resolvedAddress;
|
||||
try {
|
||||
const { address } = await dns.lookup(parsed.hostname);
|
||||
if (isPrivateIP(address)) {
|
||||
res.status(400).json({ error: "URL resolves to a private/internal IP address" });
|
||||
return;
|
||||
return null;
|
||||
}
|
||||
resolvedAddress = address;
|
||||
}
|
||||
catch {
|
||||
res.status(400).json({ error: "DNS lookup failed for URL hostname" });
|
||||
return;
|
||||
}
|
||||
// Validate PDF options
|
||||
const validation = validatePdfOptions(body);
|
||||
if (!validation.valid) {
|
||||
res.status(400).json({ error: validation.error });
|
||||
return;
|
||||
}
|
||||
// Acquire concurrency slot
|
||||
if (req.acquirePdfSlot) {
|
||||
await req.acquirePdfSlot();
|
||||
slotAcquired = true;
|
||||
return null;
|
||||
}
|
||||
const { pdf, durationMs } = await renderUrlPdf(body.url, {
|
||||
...validation.sanitized,
|
||||
...sanitizedOptions,
|
||||
hostResolverRules: `MAP ${parsed.hostname} ${resolvedAddress}`,
|
||||
});
|
||||
const filename = sanitizeFilename(body.filename || "page.pdf");
|
||||
res.setHeader("Content-Type", "application/pdf");
|
||||
res.setHeader("Content-Disposition", `inline; filename="${filename}"`);
|
||||
res.setHeader("X-Render-Time", String(durationMs));
|
||||
res.send(pdf);
|
||||
}
|
||||
catch (err) {
|
||||
logger.error({ err }, "Convert URL error");
|
||||
if (err.message === "QUEUE_FULL") {
|
||||
res.status(429).json({ error: "Server busy - too many concurrent PDF generations. Please try again in a few seconds." });
|
||||
return;
|
||||
}
|
||||
res.status(500).json({ error: `PDF generation failed: ${err.message}` });
|
||||
}
|
||||
finally {
|
||||
if (slotAcquired && req.releasePdfSlot) {
|
||||
req.releasePdfSlot();
|
||||
}
|
||||
}
|
||||
return { pdf, durationMs, filename: sanitizeFilename(body.filename || "page.pdf") };
|
||||
});
|
||||
});
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue