Harden API contracts with request IDs and audit telemetry
CI / test (push) Waiting to run

This commit is contained in:
Rbanh committed 2026-02-18 22:19:38 -05:00
1 parent e2445980f9
commit 31a47346ea
5 files changed
+158 -30

No files matched your search

+71 -27
View File
@@ -1,4 +1,5 @@
import { createServer } from "node:http";
import { randomUUID } from "node:crypto";
import { readFile } from "node:fs/promises";
import { extname, join, normalize } from "node:path";
import { pathToFileURL } from "node:url";
@@ -38,14 +39,18 @@ function json(res, status, payload) {
res.end(JSON.stringify(payload, null, 2));
}
export function errorEnvelope(code, message) {
return {
export function errorEnvelope(code, message, details = {}) {
const out = {
ok: false,
error: {
code,
message
}
};
if (details && typeof details === "object") {
Object.assign(out, details);
}
return out;
}
export function isAuthorizedRequest(req) {
@@ -149,11 +154,32 @@ export function parsePayloadOptions(body) {
}
export function withEnvelopeMeta(payload) {
return {
const out = {
api_version: API_VERSION,
schema_version: SCHEMA_VERSION,
...payload
};
if (!out.request_id && payload?.request_id) {
out.request_id = payload.request_id;
}
return out;
}
function requestIdFrom(req) {
const headerId = req.headers?.["x-request-id"];
if (typeof headerId === "string" && headerId.trim()) {
return headerId.trim().slice(0, 128);
}
return randomUUID();
}
function auditLog(entry) {
const line = {
ts: new Date().toISOString(),
service: "schemeta",
...entry
};
console.log(JSON.stringify(line));
}
function clientKey(req) {
@@ -194,8 +220,22 @@ function withinRateLimit(req) {
export function createRequestHandler() {
return async (req, res) => {
const requestId = requestIdFrom(req);
const startedAt = Date.now();
res.setHeader("x-request-id", requestId);
res.on("finish", () => {
auditLog({
request_id: requestId,
method: req.method,
path: req.url,
status: res.statusCode,
duration_ms: Date.now() - startedAt,
client: clientKey(req)
});
});
if (!req.url || !req.method) {
return json(res, 400, errorEnvelope("invalid_request", "Invalid request."));
return json(res, 400, errorEnvelope("invalid_request", "Invalid request.", { request_id: requestId }));
}
const pathname = new URL(req.url, "http://localhost").pathname;
@@ -211,6 +251,7 @@ export function createRequestHandler() {
return json(res, 200, {
ok: true,
service: "schemeta",
request_id: requestId,
api_version: API_VERSION,
schema_version: SCHEMA_VERSION,
status: "ok",
@@ -221,6 +262,7 @@ export function createRequestHandler() {
if (req.method === "GET" && pathname === "/mcp/ui-bundle") {
return json(res, 200, {
ok: true,
request_id: requestId,
name: "schemeta-workspace",
version: "0.2.0",
api_version: API_VERSION,
@@ -234,56 +276,56 @@ export function createRequestHandler() {
if (req.method === "POST" && pathname === "/analyze") {
if (!isAuthorizedRequest(req)) {
res.setHeader("WWW-Authenticate", "Bearer");
return json(res, 401, errorEnvelope("unauthorized", "Missing or invalid API token."));
return json(res, 401, errorEnvelope("unauthorized", "Missing or invalid API token.", { request_id: requestId }));
}
if (!withinRateLimit(req)) {
return json(res, 429, errorEnvelope("rate_limited", "Rate limit exceeded. Try again shortly."));
return json(res, 429, errorEnvelope("rate_limited", "Rate limit exceeded. Try again shortly.", { request_id: requestId }));
}
try {
const body = await readBody(req);
const parsed = parsePayloadOptions(body);
return json(res, 200, withEnvelopeMeta(analyze(parsed.payload, parsed.options)));
return json(res, 200, withEnvelopeMeta({ request_id: requestId, ...analyze(parsed.payload, parsed.options) }));
} catch (err) {
if (err?.code === "PAYLOAD_TOO_LARGE") {
return json(res, 413, errorEnvelope("payload_too_large", `Request body exceeds ${MAX_BODY_BYTES} bytes.`));
return json(res, 413, errorEnvelope("payload_too_large", `Request body exceeds ${MAX_BODY_BYTES} bytes.`, { request_id: requestId }));
}
if (err?.code === "INVALID_JSON") {
return json(res, 400, errorEnvelope("invalid_json", "Invalid JSON payload."));
return json(res, 400, errorEnvelope("invalid_json", "Invalid JSON payload.", { request_id: requestId }));
}
return json(res, 500, errorEnvelope("internal_error", "Request failed."));
return json(res, 500, errorEnvelope("internal_error", "Request failed.", { request_id: requestId }));
}
}
if (req.method === "POST" && pathname === "/compile") {
if (!isAuthorizedRequest(req)) {
res.setHeader("WWW-Authenticate", "Bearer");
return json(res, 401, errorEnvelope("unauthorized", "Missing or invalid API token."));
return json(res, 401, errorEnvelope("unauthorized", "Missing or invalid API token.", { request_id: requestId }));
}
if (!withinRateLimit(req)) {
return json(res, 429, errorEnvelope("rate_limited", "Rate limit exceeded. Try again shortly."));
return json(res, 429, errorEnvelope("rate_limited", "Rate limit exceeded. Try again shortly.", { request_id: requestId }));
}
try {
const body = await readBody(req);
const parsed = parsePayloadOptions(body);
return json(res, 200, withEnvelopeMeta(compile(parsed.payload, parsed.options)));
return json(res, 200, withEnvelopeMeta({ request_id: requestId, ...compile(parsed.payload, parsed.options) }));
} catch (err) {
if (err?.code === "PAYLOAD_TOO_LARGE") {
return json(res, 413, errorEnvelope("payload_too_large", `Request body exceeds ${MAX_BODY_BYTES} bytes.`));
return json(res, 413, errorEnvelope("payload_too_large", `Request body exceeds ${MAX_BODY_BYTES} bytes.`, { request_id: requestId }));
}
if (err?.code === "INVALID_JSON") {
return json(res, 400, errorEnvelope("invalid_json", "Invalid JSON payload."));
return json(res, 400, errorEnvelope("invalid_json", "Invalid JSON payload.", { request_id: requestId }));
}
return json(res, 500, errorEnvelope("internal_error", "Request failed."));
return json(res, 500, errorEnvelope("internal_error", "Request failed.", { request_id: requestId }));
}
}
if (req.method === "POST" && pathname === "/layout/auto") {
if (!isAuthorizedRequest(req)) {
res.setHeader("WWW-Authenticate", "Bearer");
return json(res, 401, errorEnvelope("unauthorized", "Missing or invalid API token."));
return json(res, 401, errorEnvelope("unauthorized", "Missing or invalid API token.", { request_id: requestId }));
}
if (!withinRateLimit(req)) {
return json(res, 429, errorEnvelope("rate_limited", "Rate limit exceeded. Try again shortly."));
return json(res, 429, errorEnvelope("rate_limited", "Rate limit exceeded. Try again shortly.", { request_id: requestId }));
}
try {
const body = await readBody(req);
@@ -293,6 +335,7 @@ export function createRequestHandler() {
const laidOut = applyLayoutToModel(model, { respectLocks: false });
return json(res, 200, {
ok: true,
request_id: requestId,
api_version: API_VERSION,
schema_version: SCHEMA_VERSION,
model: laidOut,
@@ -300,22 +343,22 @@ export function createRequestHandler() {
});
} catch (err) {
if (err?.code === "PAYLOAD_TOO_LARGE") {
return json(res, 413, errorEnvelope("payload_too_large", `Request body exceeds ${MAX_BODY_BYTES} bytes.`));
return json(res, 413, errorEnvelope("payload_too_large", `Request body exceeds ${MAX_BODY_BYTES} bytes.`, { request_id: requestId }));
}
if (err?.code === "INVALID_JSON") {
return json(res, 400, errorEnvelope("invalid_json", "Invalid JSON payload."));
return json(res, 400, errorEnvelope("invalid_json", "Invalid JSON payload.", { request_id: requestId }));
}
return json(res, 500, errorEnvelope("internal_error", "Layout auto failed."));
return json(res, 500, errorEnvelope("internal_error", "Layout auto failed.", { request_id: requestId }));
}
}
if (req.method === "POST" && pathname === "/layout/tidy") {
if (!isAuthorizedRequest(req)) {
res.setHeader("WWW-Authenticate", "Bearer");
return json(res, 401, errorEnvelope("unauthorized", "Missing or invalid API token."));
return json(res, 401, errorEnvelope("unauthorized", "Missing or invalid API token.", { request_id: requestId }));
}
if (!withinRateLimit(req)) {
return json(res, 429, errorEnvelope("rate_limited", "Rate limit exceeded. Try again shortly."));
return json(res, 429, errorEnvelope("rate_limited", "Rate limit exceeded. Try again shortly.", { request_id: requestId }));
}
try {
const body = await readBody(req);
@@ -325,6 +368,7 @@ export function createRequestHandler() {
const laidOut = applyLayoutToModel(model, { respectLocks: true });
return json(res, 200, {
ok: true,
request_id: requestId,
api_version: API_VERSION,
schema_version: SCHEMA_VERSION,
model: laidOut,
@@ -332,12 +376,12 @@ export function createRequestHandler() {
});
} catch (err) {
if (err?.code === "PAYLOAD_TOO_LARGE") {
return json(res, 413, errorEnvelope("payload_too_large", `Request body exceeds ${MAX_BODY_BYTES} bytes.`));
return json(res, 413, errorEnvelope("payload_too_large", `Request body exceeds ${MAX_BODY_BYTES} bytes.`, { request_id: requestId }));
}
if (err?.code === "INVALID_JSON") {
return json(res, 400, errorEnvelope("invalid_json", "Invalid JSON payload."));
return json(res, 400, errorEnvelope("invalid_json", "Invalid JSON payload.", { request_id: requestId }));
}
return json(res, 500, errorEnvelope("internal_error", "Layout tidy failed."));
return json(res, 500, errorEnvelope("internal_error", "Layout tidy failed.", { request_id: requestId }));
}
}
@@ -348,7 +392,7 @@ export function createRequestHandler() {
}
}
return json(res, 404, errorEnvelope("not_found", "Not found."));
return json(res, 404, errorEnvelope("not_found", "Not found.", { request_id: requestId }));
};
}