@decohere/http 0.0.1-dev.125 → 0.0.1-dev.5

package/tests/http.global-prefix.integration.spec.ts

@@ -0,0 +1,284 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import "../src/health/health.extensions.js";
+import { Controller, Get } from "../src/index.js";
+import type { OpenApiDocument } from "../src/openapi/openapi.types.js";
+import { bootModule } from "../src/testing/index.js";
+
+// Static files are read by the real server from real disk.
+vi.unmock("fs");
+vi.unmock("fs/promises");
+vi.unmock("node:fs");
+vi.unmock("node:fs/promises");
+
+@Controller({ prefix: "/lp" })
+class PortfolioController {
+	@Get("/portfolio")
+	public portfolio() {
+		return { positions: [] };
+	}
+}
+
+@Controller({ prefix: "/" })
+class PingController {
+	@Get("/ping")
+	public ping() {
+		return { pong: true };
+	}
+}
+
+@Controller({ prefix: "/webhooks", globalPrefix: false })
+class WebhookController {
+	@Get("/:source")
+	public receive() {
+		return { received: true };
+	}
+}
+
+/** Declares `/health` itself: only the opt-out moves a route, never its name. */
+@Controller({ prefix: "/" })
+class OwnHealthController {
+	@Get("/health")
+	public health() {
+		return { mine: true };
+	}
+}
+
+/** What a browser sends when it navigates: the SPA fallback only answers this kind of request. */
+const browser = { accept: "text/html,application/xhtml+xml;q=0.9,*/*;q=0.8" };
+
+let ui: string;
+
+beforeAll(async () => {
+	ui = await mkdtemp(path.join(tmpdir(), "http-prefix-"));
+	await writeFile(path.join(ui, "index.html"), "<!doctype html><title>the app</title>");
+});
+
+afterAll(async () => {
+	await rm(ui, { recursive: true, force: true });
+});
+
+type Configure = NonNullable<Parameters<typeof bootModule>[0]["configure"]>;
+type TestBuilder = Parameters<Configure>[0];
+
+function boot(configure: Configure) {
+	return bootModule({ controllers: [PortfolioController, PingController], configure });
+}
+
+/** Status of a GET. The body is read so a streamed file never holds up stopping the app. */
+async function status(
+	api: { baseUrl: string },
+	url: string,
+	headers?: Record<string, string>,
+) {
+	const response = await fetch(`${api.baseUrl}${url}`, { headers });
+	await response.arrayBuffer();
+	return response.status;
+}
+
+describe("the global prefix and the probes (#646)", () => {
+	it("keeps /health and /ready at the root, and prefixes the controllers", async () => {
+		await using api = await boot((b) => b.withHealth().withGlobalPrefix("/api"));
+
+		expect(await status(api, "/health")).toBe(200);
+		expect(await status(api, "/ready")).toBe(200);
+		expect(await status(api, "/api/health")).toBe(404);
+		expect(await status(api, "/api/ready")).toBe(404);
+		expect(await status(api, "/api/lp/portfolio")).toBe(200);
+		expect(await status(api, "/api/ping")).toBe(200);
+		expect(await status(api, "/lp/portfolio")).toBe(404);
+		expect(await status(api, "/ping")).toBe(404);
+	});
+
+	it("keeps the probes at the root whichever order the builder is called in", async () => {
+		await using api = await boot((b) => b.withGlobalPrefix("/api").withHealth());
+
+		expect(await status(api, "/health")).toBe(200);
+		expect(await status(api, "/api/health")).toBe(404);
+	});
+
+	it("leaves a controller that opts out unprefixed, parameters included", async () => {
+		await using api = await bootModule({
+			controllers: [PortfolioController, WebhookController],
+			configure: (b) => b.withGlobalPrefix("/api"),
+		});
+
+		expect(await status(api, "/webhooks/stripe")).toBe(200);
+		expect(await status(api, "/api/webhooks/stripe")).toBe(404);
+		expect(await status(api, "/api/lp/portfolio")).toBe(200);
+	});
+
+	it("prefixes a controller that declares /health itself: the path alone moves nothing", async () => {
+		await using api = await bootModule({
+			controllers: [OwnHealthController],
+			configure: (b) => b.withGlobalPrefix("/api"),
+		});
+
+		expect(await status(api, "/api/health")).toBe(200);
+		expect(await status(api, "/health")).toBe(404);
+	});
+
+	it("puts the probes under the prefix with underGlobalPrefix", async () => {
+		await using api = await boot((b) =>
+			b.withHealth({ underGlobalPrefix: true }).withGlobalPrefix("/api"),
+		);
+
+		expect(await status(api, "/api/health")).toBe(200);
+		expect(await status(api, "/api/ready")).toBe(200);
+		expect(await status(api, "/health")).toBe(404);
+		expect(await status(api, "/ready")).toBe(404);
+	});
+
+	it("applies underGlobalPrefix whichever order the builder is called in", async () => {
+		await using api = await boot((b) =>
+			b.withGlobalPrefix("/api").withHealth({ underGlobalPrefix: true }),
+		);
+
+		expect(await status(api, "/api/health")).toBe(200);
+		expect(await status(api, "/health")).toBe(404);
+	});
+
+	it("serves the probes at the root with underGlobalPrefix and no prefix", async () => {
+		await using api = await boot((b) => b.withHealth({ underGlobalPrefix: true }));
+
+		expect(await status(api, "/health")).toBe(200);
+		expect(await status(api, "/ready")).toBe(200);
+	});
+
+	it("keeps the OpenAPI path where it was, and lists the prefixed routes", async () => {
+		await using api = await boot((b) =>
+			b
+				.withHealth()
+				.withGlobalPrefix("/api")
+				.withOpenApi({ info: { title: "t", version: "1" } }),
+		);
+
+		expect(await status(api, "/openapi.json")).toBe(200);
+		expect(await status(api, "/api/openapi.json")).toBe(404);
+		const doc = (await (await fetch(`${api.baseUrl}/openapi.json`)).json()) as OpenApiDocument;
+		expect(Object.keys(doc.paths)).toContain("/api/lp/portfolio");
+	});
+
+	it("changes nothing without a global prefix", async () => {
+		await using api = await boot((b) => b.withHealth());
+
+		expect(await status(api, "/health")).toBe(200);
+		expect(await status(api, "/ready")).toBe(200);
+		expect(await status(api, "/lp/portfolio")).toBe(200);
+		expect(await status(api, "/ping")).toBe(200);
+	});
+});
+
+describe("the static fallback with a global prefix (#647)", () => {
+	const withUi = (b: TestBuilder) =>
+		b.withHealth().withGlobalPrefix("/api").withStatic("/", ui);
+
+	it("gives the app to a UI route that shares a first segment with a prefixed controller", async () => {
+		await using api = await boot(withUi);
+
+		const page = await fetch(`${api.baseUrl}/lp/positions`, { headers: browser });
+		expect(page.status).toBe(200);
+		expect(await page.text()).toContain("the app");
+	});
+
+	it("keeps the JSON 404 at and below a route outside the prefix, even to a browser", async () => {
+		await using api = await bootModule({
+			controllers: [PortfolioController, WebhookController],
+			configure: (b) => b.withHealth().withGlobalPrefix("/api").withStatic("/", ui),
+		});
+
+		for (const url of ["/health/x", "/ready/", "/webhooks", "/webhooks/stripe/x"]) {
+			const response = await fetch(`${api.baseUrl}${url}`, { headers: browser });
+			expect(response.status, url).toBe(404);
+			expect(await response.text()).not.toContain("the app");
+		}
+		// The routes themselves answer, and names that only start the same get the app.
+		expect(await status(api, "/health", browser)).toBe(200);
+		expect(await status(api, "/webhooks/stripe", browser)).toBe(200);
+		expect(await status(api, "/healthy", browser)).toBe(200);
+	});
+
+	it("gives the app to a UI route that shares a first segment with the prefix", async () => {
+		await using api = await boot((b) => b.withGlobalPrefix("/api/v1").withStatic("/", ui));
+
+		const page = await fetch(`${api.baseUrl}/api/docs`, { headers: browser });
+		expect(page.status).toBe(200);
+		expect(await page.text()).toContain("the app");
+		expect(await status(api, "/api/v1/nothing", browser)).toBe(404);
+	});
+
+	it("keeps the JSON 404 for any path under the prefix, even to a browser", async () => {
+		await using api = await boot(withUi);
+
+		for (const url of ["/api", "/api/", "/api/lp/portfolo", "/api/nothing/here"]) {
+			const response = await fetch(`${api.baseUrl}${url}`, { headers: browser });
+			expect(response.status).toBe(404);
+			expect(await response.text()).not.toContain("the app");
+		}
+	});
+
+	it("keeps the JSON 404 under the prefix when no controller is under it", async () => {
+		await using api = await bootModule({
+			controllers: [],
+			configure: (b) => b.withGlobalPrefix("/api").withStatic("/", ui),
+		});
+
+		expect(await status(api, "/api/anything", browser)).toBe(404);
+		expect(await status(api, "/anything", browser)).toBe(200);
+	});
+
+	it("does not treat a name that only starts with the prefix as the API", async () => {
+		await using api = await boot(withUi);
+
+		const page = await fetch(`${api.baseUrl}/apiary`, { headers: browser });
+		expect(page.status).toBe(200);
+		expect(await page.text()).toContain("the app");
+	});
+
+	it("keeps the OpenAPI path out of the fallback", async () => {
+		await using api = await boot((b) =>
+			withUi(b).withOpenApi({
+				info: { title: "t", version: "1" },
+				path: "/spec/openapi.json",
+			}),
+		);
+
+		expect(await status(api, "/spec/openapi.json", browser)).toBe(200);
+		expect(await status(api, "/spec/openapi.json/more", browser)).toBe(404);
+		expect(await status(api, "/elsewhere", browser)).toBe(200);
+	});
+
+	it("keeps the other rules: method, extension, Accept and exclude", async () => {
+		await using api = await boot((b) =>
+			b.withGlobalPrefix("/api").withStatic("/", ui, { exclude: ["/docs/**"] }),
+		);
+		const call = (method: string) =>
+			fetch(`${api.baseUrl}/lp/positions`, { method, headers: browser }).then((r) => r.status);
+
+		expect(await status(api, "/lp/positions", { accept: "application/json" })).toBe(404);
+		expect(await status(api, "/lp/positions")).toBe(404);
+		expect(await status(api, "/lp/gone.js", browser)).toBe(404);
+		expect(await status(api, "/docs/x", browser)).toBe(404);
+		expect(await call("POST")).toBe(404);
+		expect(await call("HEAD")).toBe(200);
+	});
+
+	it("still prefixes the controllers and keeps the probes at the root", async () => {
+		await using api = await boot(withUi);
+
+		expect(await status(api, "/api/lp/portfolio")).toBe(200);
+		expect(await status(api, "/health")).toBe(200);
+		expect(await status(api, "/")).toBe(200);
+	});
+
+	it("keeps the first-segment rule without a global prefix", async () => {
+		await using api = await boot((b) => b.withHealth().withStatic("/", ui));
+
+		expect(await status(api, "/lp/positions", browser)).toBe(404);
+		expect(await status(api, "/health/x", browser)).toBe(404);
+		expect(await status(api, "/portfolio", browser)).toBe(200);
+		expect(await status(api, "/lpx", browser)).toBe(200);
+	});
+});

package/tests/http.number-query.integration.spec.ts

@@ -0,0 +1,65 @@
+import axios from "axios";
+import { afterEach, describe, expect, it } from "vitest";
+import type { App } from "../src/app/app.js";
+import { Builder } from "../src/builder/builder.js";
+import "../src/http/http.extensions.js";
+import { FastifyProvider } from "../src/providers/fastify.provider.js";
+import { Controller, Get, Query } from "../src/routing/index.js";
+import { listenEphemeral } from "./helpers/listen-ephemeral.js";
+
+@Controller({ prefix: "/page" })
+class PageController {
+	@Get()
+	public get(@Query("size") size: number) {
+		return { size: size ?? null };
+	}
+}
+
+// #503: a value that isn't a number used to reach the handler as `undefined`, so
+// `?size=abc` behaved like `?size` was missing. It must be rejected with 400, like the
+// boolean and date pipes do.
+describe("NumberPipe over HTTP query", () => {
+	let app: App;
+
+	afterEach(async () => {
+		await app?.dispose();
+	});
+
+	async function start() {
+		app = await Builder.create()
+			.withHttpProvider(FastifyProvider)
+			.withControllers(PageController)
+			.build();
+		axios.defaults.baseURL = await listenEphemeral(app);
+	}
+
+	it.each([
+		["10", 10],
+		["-3", -3],
+		["2.5", 2.5],
+		[" 7 ", 7],
+	] as const)("binds ?size=%s to %s", async (raw, expected) => {
+		await start();
+		const res = await axios.get("/page", { params: { size: raw } });
+		expect(res.data).toEqual({ size: expected });
+	});
+
+	it("leaves a missing value undefined", async () => {
+		await start();
+		const res = await axios.get("/page");
+		expect(res.data).toEqual({ size: null });
+	});
+
+	it.each(["abc", "", "   ", "12abc", "Infinity", "NaN"])(
+		"rejects ?size=%j with 400",
+		async (raw) => {
+			await start();
+			const res = await axios.get("/page", {
+				params: { size: raw },
+				validateStatus: () => true,
+			});
+			expect(res.status).toBe(400);
+			expect(res.data).toMatchObject({ statusCode: 400, error: "Bad Request" });
+		},
+	);
+});

package/tests/http.pino-roll-hmr.integration.spec.ts

@@ -0,0 +1,79 @@
+/**
+ * Reproduces Flux hot-reload + pino-roll: App.dispose must finish so reboot can listen again.
+ *
+ * Scaffold pattern: scribe.withPinoPretty().and.withPinoRoll({ file }) then export default app.
+ * Flux disposeEntry → App.dispose → container asyncDispose → scribe.stop() must not hang on ThreadStream.end().
+ */
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import "@decohere/scribe-pino";
+import { scribe } from "@decohere/scribe";
+import axios from "axios";
+import { afterEach, describe, expect, it } from "vitest";
+import { realFs } from "../../../test/fs.setup.js";
+import type { App } from "../src/app/app.js";
+import { Builder } from "../src/builder/builder.js";
+import "../src/http/http.extensions.js";
+import { FastifyProvider } from "../src/providers/fastify.provider.js";
+import { Controller, Get } from "../src/routing/index.js";
+import { listenEphemeral } from "./helpers/listen-ephemeral.js";
+
+@Controller({ prefix: "/funding-arb" })
+class FundingArbStubController {
+	@Get()
+	public state() {
+		return { ok: true };
+	}
+}
+
+async function bootWithPinoRoll(logFile: string): Promise<App> {
+	scribe.withPinoPretty().and.withPinoRoll({
+		file: logFile,
+		when: "always",
+		size: "1m",
+		keep: 2,
+		mkdir: true,
+	});
+	return Builder.create()
+		.withHttp(FastifyProvider)
+		.withControllers(FundingArbStubController)
+		.build();
+}
+
+describe("Flux-style reboot with pino-roll", () => {
+	let logDir: string;
+	let app: App | undefined;
+
+	afterEach(async () => {
+		if (app != null) {
+			await app.dispose();
+			app = undefined;
+		}
+		await scribe.stop();
+		if (logDir != null) {
+			realFs.rmSync(logDir, { recursive: true, force: true });
+		}
+	});
+
+	it("listens again after App.dispose + withPinoRoll reconfigure (HMR cycle)", async () => {
+		logDir = realFs.mkdtempSync(join(tmpdir(), "http-pino-roll-hmr-"));
+		const logFile = join(logDir, "funding-fee.api.log");
+
+		app = await bootWithPinoRoll(logFile);
+		const origin1 = await listenEphemeral(app);
+		const first = await axios.get(`${origin1}/funding-arb`);
+		expect(first.status).toBe(200);
+		expect(first.data).toEqual({ ok: true });
+
+		const dying = app;
+		app = undefined;
+		await dying.dispose();
+
+		app = await bootWithPinoRoll(logFile);
+		const origin2 = await listenEphemeral(app);
+		const second = await axios.get(`${origin2}/funding-arb`, { timeout: 5_000 });
+
+		expect(second.status).toBe(200);
+		expect(second.data).toEqual({ ok: true });
+	}, 20_000);
+});

package/tests/http.pipeline-order.integration.spec.ts

@@ -0,0 +1,95 @@
+import type { IConfigurationService } from "@decohere/core/configuration";
+import { ConfigurationServiceToken } from "@decohere/core/configuration";
+import type { Constructable } from "@decohere/core/reflection";
+import { scribe } from "@decohere/scribe";
+import axios from "axios";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { App } from "../src/app/app.js";
+import { AuthConfig } from "../src/auth/auth.config.js";
+import "../src/auth/auth.extensions.js";
+import { Builder } from "../src/builder/builder.js";
+import "../src/http/http.extensions.js";
+import { FastifyProvider } from "../src/providers/fastify.provider.js";
+import {
+	Authorize,
+	Controller,
+	Field,
+	HttpAccessLogMiddleware,
+	Post,
+	RequestParts,
+} from "../src/routing/index.js";
+import { listenEphemeral } from "./helpers/listen-ephemeral.js";
+
+class SecretConfigService implements IConfigurationService {
+	public get dataSources() {
+		return [];
+	}
+	public async get<T extends object>(type: Constructable<T> | string): Promise<T> {
+		if (type === AuthConfig) {
+			const config = new AuthConfig();
+			config.secret = "test-secret-at-least-32-bytes-long!!";
+			config.audience = "test-audience";
+			return config as unknown as T;
+		}
+		return {} as T;
+	}
+}
+
+class OrderBody {
+	@Field(RequestParts.body, "item")
+	public item!: string;
+}
+
+@Controller({ prefix: "/orders" })
+class OrderController {
+	@Authorize("create", "Order")
+	@Post()
+	public create(body: OrderBody) {
+		return { item: body.item };
+	}
+}
+
+// #501: auth must run before validation (anonymous callers learn nothing about the body
+// schema), and both must run inside the middleware chain so rejections are access-logged.
+describe("request pipeline order", () => {
+	let app: App;
+	const accessLog = { info: vi.fn() };
+
+	beforeEach(async () => {
+		const original = scribe.logger.bind(scribe);
+		vi.spyOn(scribe, "logger").mockImplementation((name: string) =>
+			name === HttpAccessLogMiddleware.name ? (accessLog as never) : original(name),
+		);
+		app = await Builder.create()
+			.withOpenApi({ info: { title: "Orders", version: "1.0.0" }, path: "/openapi.json" })
+			.withHttp(FastifyProvider)
+			.withServices((c) => {
+				c.registerSingleton(ConfigurationServiceToken, new SecretConfigService());
+			})
+			.withAuth()
+			.withControllers(OrderController)
+			.build();
+		axios.defaults.baseURL = await listenEphemeral(app);
+	});
+
+	afterEach(async () => {
+		await app.dispose();
+		vi.restoreAllMocks();
+		accessLog.info.mockReset();
+	});
+
+	it("rejects an anonymous request with 401 before looking at the body", async () => {
+		const res = await axios.post("/orders", { wrong: 1 }, { validateStatus: () => true });
+
+		expect(res.status).toBe(401);
+		expect(JSON.stringify(res.data)).not.toMatch(/item|additional property/);
+	});
+
+	it("access-logs requests rejected by auth", async () => {
+		await axios.post("/orders", {}, { validateStatus: () => true });
+
+		expect(accessLog.info).toHaveBeenCalledWith(
+			expect.objectContaining({ msg: "access", path: "/orders", status: 401 }),
+		);
+	});
+});

package/tests/http.request-cleanup.integration.spec.ts

@@ -0,0 +1,57 @@
+import { inject, injectable } from "@decohere/di/decorators";
+import axios from "axios";
+import { afterEach, describe, expect, it } from "vitest";
+import type { App } from "../src/app/app.js";
+import { Builder } from "../src/builder/builder.js";
+import "../src/http/http.extensions.js";
+import { FastifyProvider } from "../src/providers/fastify.provider.js";
+import { Controller, Get } from "../src/routing/index.js";
+import { listenEphemeral } from "./helpers/listen-ephemeral.js";
+
+const cleanedUp: string[] = [];
+const WorkToken = Symbol("RequestWork");
+
+/** Stands in for a unit of work: its async cleanup must finish before the response goes out. */
+@injectable()
+class RequestWork {
+	public async [Symbol.asyncDispose]() {
+		await new Promise((resolve) => setTimeout(resolve, 20));
+		cleanedUp.push("done");
+	}
+}
+
+@Controller({ prefix: "/work" })
+class WorkController {
+	public constructor(@inject(WorkToken) private readonly work: RequestWork) {}
+
+	@Get("/fail")
+	public fail() {
+		void this.work;
+		throw new Error("boom");
+	}
+}
+
+// #502: per-request objects were disposed synchronously, so async cleanup (rolling back a
+// transaction, releasing a DB connection) was started but never awaited.
+describe("per-request cleanup", () => {
+	let app: App;
+
+	afterEach(async () => {
+		await app?.dispose();
+		cleanedUp.length = 0;
+	});
+
+	it("awaits async cleanup of request-scoped services, even when the handler throws", async () => {
+		app = await Builder.create()
+			.withHttp(FastifyProvider)
+			.withServices((c) => c.registerRequestScoped(WorkToken, RequestWork))
+			.withControllers(WorkController)
+			.build();
+		const baseURL = await listenEphemeral(app);
+
+		const res = await axios.get("/work/fail", { baseURL, validateStatus: () => true });
+
+		expect(res.status).toBe(500);
+		expect(cleanedUp).toEqual(["done"]);
+	});
+});

package/tests/http.request-id-scope.pentest.spec.ts

@@ -0,0 +1,50 @@
+import axios from "axios";
+import { afterEach, describe, expect, it } from "vitest";
+import type { App } from "../src/app/app.js";
+import { Builder } from "../src/builder/builder.js";
+import "../src/http/http.extensions.js";
+import { FastifyProvider } from "../src/providers/fastify.provider.js";
+import { Controller, Get, REQUEST_ID_HEADER } from "../src/routing/index.js";
+import { listenEphemeral } from "./helpers/listen-ephemeral.js";
+
+@Controller({ prefix: "/slow" })
+class SlowController {
+	@Get()
+	public async slow() {
+		// Keep the request open so a second one with the same id overlaps it.
+		await new Promise((resolve) => setTimeout(resolve, 50));
+		return { ok: true };
+	}
+}
+
+// #497: the request id comes from the client. Two overlapping requests that send the same
+// x-request-id (a retry, a proxy, or an attacker) must both succeed.
+describe("pen test: client-chosen x-request-id", () => {
+	let app: App;
+
+	afterEach(async () => {
+		await app?.dispose();
+	});
+
+	it("serves concurrent requests that share an x-request-id", async () => {
+		app = await Builder.create()
+			.withHttp(FastifyProvider)
+			.withControllers(SlowController)
+			.build();
+		const baseURL = await listenEphemeral(app);
+		const headers = { [REQUEST_ID_HEADER]: "same-id" };
+
+		const responses = await Promise.all(
+			[1, 2, 3].map(() =>
+				axios.get("/slow", { baseURL, headers, validateStatus: () => true }),
+			),
+		);
+
+		expect(responses.map((r) => r.status)).toEqual([200, 200, 200]);
+		expect(responses.map((r) => r.headers[REQUEST_ID_HEADER])).toEqual([
+			"same-id",
+			"same-id",
+			"same-id",
+		]);
+	});
+});