Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,122 @@
import { describe, expect, test } from "vitest";
import { Hono } from "hono";
import { createRequestIdMiddleware, type ApiRequestIdVariables } from "../../middleware/request-id.js";
import {
createApiMaintenanceMiddleware,
getApiMaintenanceConfig,
isApiMaintenanceExemptPath,
} from "./maintenance.js";
type TestEnv = {
Variables: ApiRequestIdVariables;
};
function createTestApp(config: { enabled: boolean; retryAfterSeconds?: number }) {
const app = new Hono<TestEnv>();
app.use("*", createRequestIdMiddleware());
app.use("*", createApiMaintenanceMiddleware(() => config));
app.get("/v1/widgets", (c) => c.json({ status: "ok", requestId: c.get("requestId") }));
app.get("/healthz", (c) => c.json({ status: "ok", requestId: c.get("requestId") }));
return app;
}
describe("API maintenance middleware", () => {
test("parses enabled and retry-after config from safe env values", () => {
expect(
getApiMaintenanceConfig({
TOOLCTRL_API_MAINTENANCE_MODE: "1",
TOOLCTRL_API_MAINTENANCE_RETRY_AFTER_SECONDS: "120",
})
).toEqual({ enabled: true, retryAfterSeconds: 120 });
});
test("ignores disabled flags and invalid retry-after values", () => {
expect(
getApiMaintenanceConfig({
TOOLCTRL_API_MAINTENANCE_MODE: "true",
TOOLCTRL_API_MAINTENANCE_RETRY_AFTER_SECONDS: "postgres://user:secret@db.local/app",
})
).toEqual({ enabled: false, retryAfterSeconds: undefined });
expect(
getApiMaintenanceConfig({
TOOLCTRL_API_MAINTENANCE_MODE: "1",
TOOLCTRL_API_MAINTENANCE_RETRY_AFTER_SECONDS: "1.5",
})
).toEqual({ enabled: true, retryAfterSeconds: undefined });
});
test.each(["/healthz", "/readyz", "/v1/openapi.json", "/v1/docs", "/v1/docs/"])("exempts operator path %s", (path) => {
expect(isApiMaintenanceExemptPath(path)).toBe(true);
});
test("passes through requests when maintenance mode is disabled", async () => {
const app = createTestApp({ enabled: false });
const response = await app.request("/v1/widgets", {
headers: { "x-request-id": "req_disabled" },
});
expect(response.status).toBe(200);
expect(response.headers.get("x-request-id")).toBe("req_disabled");
await expect(response.json()).resolves.toEqual({ status: "ok", requestId: "req_disabled" });
});
test("returns request-id-correlated maintenance response with retry-after", async () => {
const app = createTestApp({ enabled: true, retryAfterSeconds: 60 });
const response = await app.request("/v1/widgets", {
headers: { "x-request-id": "req_maintenance" },
});
expect(response.status).toBe(503);
expect(response.headers.get("x-request-id")).toBe("req_maintenance");
expect(response.headers.get("retry-after")).toBe("60");
await expect(response.json()).resolves.toEqual({
status: "maintenance",
service: "api",
requestId: "req_maintenance",
error: {
code: "maintenance_mode",
message: "The API is temporarily unavailable for maintenance. Please retry later.",
},
});
});
test("does not include secret-like env values in maintenance response", async () => {
const app = createTestApp({ enabled: true });
const response = await app.request("/v1/widgets", {
headers: { "x-request-id": "req_redacted" },
});
const bodyText = await response.text();
expect(response.status).toBe(503);
expect(response.headers.get("retry-after")).toBeNull();
expect(bodyText).not.toContain("postgres://user:secret@db.local/app");
expect(bodyText).not.toContain("super-secret");
expect(bodyText).not.toContain("stack trace");
expect(JSON.parse(bodyText)).toEqual({
status: "maintenance",
service: "api",
requestId: "req_redacted",
error: {
code: "maintenance_mode",
message: "The API is temporarily unavailable for maintenance. Please retry later.",
},
});
});
test("allows exempt health path while maintenance mode is enabled", async () => {
const app = createTestApp({ enabled: true });
const response = await app.request("/healthz", {
headers: { "x-request-id": "req_health" },
});
expect(response.status).toBe(200);
await expect(response.json()).resolves.toEqual({ status: "ok", requestId: "req_health" });
});
});