@tatara/http 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tatara/http",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "tatara HTTP: Hono app setup, errors, envelope, OpenAPI docs and route mounting",
   "type": "module",
   "license": "MIT",
@@ -12,7 +12,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
   ],
   "engines": {
     "node": ">=24"
@@ -22,14 +24,14 @@
     "@hono/zod-openapi": "^1.6.3",
     "@hono/node-server": "^2.1.5",
     "@scalar/hono-api-reference": "^0.12.12",
-    "@tatara/core": "^0.1.0"
+    "@tatara/core": "^0.1.1"
   },
   "devDependencies": {
     "hono": "^4.13.13",
     "@hono/zod-openapi": "^1.6.3",
     "@hono/node-server": "^2.1.5",
     "@scalar/hono-api-reference": "^0.12.12",
-    "@tatara/core": "^0.1.0",
+    "@tatara/core": "^0.1.1",
     "pino": "^10.4.0",
     "zod": "^4.6.7"
   },

package/src/app.ts

@@ -0,0 +1,164 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { Scalar } from "@scalar/hono-api-reference";
+import { type CoreLogger, runReadinessChecks } from "@tatara/core";
+import type { Context, MiddlewareHandler } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { cors } from "hono/cors";
+import { createMiddleware } from "hono/factory";
+import { HTTPException } from "hono/http-exception";
+import { secureHeaders } from "hono/secure-headers";
+import { AppError } from "./errors.ts";
+import { validationHook } from "./validation.ts";
+
+/** Variables every tatara app has; apps extend them with their own (principal, language, …). */
+export interface HttpEnv {
+	Variables: { requestId: string; logger: CoreLogger };
+}
+
+type Defaults<E extends HttpEnv> = Partial<Omit<E["Variables"], "requestId" | "logger">>;
+
+const REQUEST_ID = /^[\w-]{8,128}$/;
+
+/** Sets requestId, a request-scoped logger and default variables; logs one line per request. */
+export function requestContext<E extends HttpEnv>(logger: CoreLogger, defaults: Defaults<E> = {}) {
+	return createMiddleware<E>(async (c, next) => {
+		const incoming = c.req.header("x-request-id");
+		const requestId = incoming && REQUEST_ID.test(incoming) ? incoming : crypto.randomUUID();
+		const log = logger.child({ requestId });
+		const set = c.set as (key: string, value: unknown) => void;
+		set("requestId", requestId);
+		set("logger", log);
+		for (const [key, value] of Object.entries(defaults)) set(key, value);
+		c.header("x-request-id", requestId);
+		const start = performance.now();
+		await next();
+		const ms = Math.round(performance.now() - start);
+		const status = c.res.status;
+		const entry = { method: c.req.method, path: c.req.path, status, ms };
+		if (status >= 500) log.error(entry, "request failed");
+		else log.info(entry, "request");
+	});
+}
+
+export interface CreateAppOptions<E extends HttpEnv> {
+	logger: CoreLogger;
+	cors: { origins: string[]; exposeHeaders?: string[]; allowHeaders?: string[] };
+	bodyLimitBytes: number;
+	/** initial values for the app's own variables, e.g. `{ principal: null, language: "en" }` */
+	defaults?: Defaults<E>;
+}
+
+/** A plain OpenAPIHono app with request context, secure headers, CORS, body limit, /health and /ready. */
+export function createApp<E extends HttpEnv>(options: CreateAppOptions<E>): OpenAPIHono<E> {
+	const app = new OpenAPIHono<E>({ defaultHook: validationHook });
+	app.use(requestContext<E>(options.logger, options.defaults) as MiddlewareHandler<E>);
+	app.use(secureHeaders());
+	app.use(
+		cors({
+			origin: options.cors.origins,
+			credentials: true,
+			allowHeaders: options.cors.allowHeaders ?? [
+				"Content-Type",
+				"Authorization",
+				"X-Request-Id",
+				"Accept-Language",
+			],
+			exposeHeaders: options.cors.exposeHeaders ?? ["X-Request-Id"],
+		}),
+	);
+	app.use(bodyLimit({ maxSize: options.bodyLimitBytes }));
+	app.get("/health", (c) => c.json({ status: "ok" }));
+	app.get("/ready", async (c) => {
+		const result = await runReadinessChecks();
+		return c.json(result, result.ready ? 200 : 503);
+	});
+	return app;
+}
+
+export interface RouteDefinition<A extends string = string, E extends HttpEnv = HttpEnv> {
+	/** which HTTP app serves these routes */
+	app: A;
+	/** mounted under the prefix + basePath, e.g. "/notes" */
+	basePath: string;
+	router: OpenAPIHono<E>;
+}
+
+/** Default export of every `routes/*.routes.ts`; discovered by `tatara sync`. */
+export function defineRoutes<D extends RouteDefinition<string, any>>(definition: D): D {
+	return definition;
+}
+
+/** A router for one routes file. Attach middleware per route or per path, never `use("*")`. */
+export function createRouter<E extends HttpEnv>(): OpenAPIHono<E> {
+	return new OpenAPIHono<E>({ defaultHook: validationHook });
+}
+
+/** Mounts the discovered routes that belong to `app` under `prefix`. */
+export function mountRoutes<E extends HttpEnv>(
+	app: OpenAPIHono<E>,
+	routes: readonly RouteDefinition<string, any>[],
+	options: { app: string; prefix: string },
+): void {
+	for (const definition of routes) {
+		if (definition.app === options.app)
+			app.route(`${options.prefix}${definition.basePath}`, definition.router);
+	}
+}
+
+type OpenApiDocument = ReturnType<OpenAPIHono["getOpenAPI31Document"]>;
+
+/** `/openapi.json` (built per request so `extend` can add to it) and the Scalar UI at `/docs`. */
+export function serveOpenApi<E extends HttpEnv>(
+	app: OpenAPIHono<E>,
+	options: {
+		title: string;
+		version?: string;
+		extend?: (document: OpenApiDocument) => void | Promise<void>;
+	},
+): void {
+	const config = {
+		openapi: "3.1.0",
+		info: { title: options.title, version: options.version ?? "1.0.0" },
+	} as const;
+	app.get("/openapi.json", async (c) => {
+		const document = app.getOpenAPI31Document(config);
+		await options.extend?.(document);
+		return c.json(document);
+	});
+	app.get("/docs", Scalar({ url: "/openapi.json", pageTitle: options.title }));
+}
+
+/** The error envelope for every error, plus a 404 for unknown routes. */
+export function handleErrors<E extends HttpEnv>(
+	app: OpenAPIHono<E>,
+	options: { message?: (err: AppError, c: Context<E>) => string } = {},
+): void {
+	app.onError((err, c) => {
+		if (err instanceof AppError) {
+			const message = options.message ? options.message(err, c as Context<E>) : err.message;
+			return c.json(
+				{
+					success: false as const,
+					error: message,
+					code: err.code,
+					...(err.details === undefined ? {} : { details: err.details }),
+				},
+				err.status,
+			);
+		}
+		if (err instanceof HTTPException) {
+			return c.json(
+				{ success: false as const, error: err.message || "Request failed", code: "HTTP_ERROR" },
+				err.status,
+			);
+		}
+		(c.get("logger") as CoreLogger).error({ err }, "unhandled error");
+		return c.json(
+			{ success: false as const, error: "Something went wrong", code: "INTERNAL_ERROR" },
+			500,
+		);
+	});
+	app.notFound((c) =>
+		c.json({ success: false as const, error: "Route not found", code: "NOT_FOUND" }, 404),
+	);
+}

package/src/errors.ts

@@ -0,0 +1,79 @@
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+
+export class AppError extends Error {
+	readonly status: ContentfulStatusCode;
+	readonly code: string;
+	readonly details?: unknown;
+	/** True when the message is generic, so the response may replace it with `errors.<code>` in the caller's language. */
+	readonly translatable: boolean;
+
+	constructor(
+		status: ContentfulStatusCode,
+		code: string,
+		message: string,
+		details?: unknown,
+		translatable = false,
+	) {
+		super(message);
+		this.name = new.target.name;
+		this.status = status;
+		this.code = code;
+		this.details = details;
+		this.translatable = translatable;
+	}
+}
+
+export class ValidationError extends AppError {
+	constructor(message?: string, details?: unknown) {
+		super(400, "VALIDATION_ERROR", message ?? "Invalid request", details, message === undefined);
+	}
+}
+
+export class BusinessRuleError extends AppError {
+	constructor(code: string, message: string, details?: unknown) {
+		// codes are specific to the rule, so a translation for the code is never less precise
+		super(400, code, message, details, true);
+	}
+}
+
+export class UnauthorizedError extends AppError {
+	constructor(message?: string) {
+		super(
+			401,
+			"UNAUTHORIZED",
+			message ?? "Authentication required",
+			undefined,
+			message === undefined,
+		);
+	}
+}
+
+export class ForbiddenError extends AppError {
+	constructor(message?: string) {
+		super(
+			403,
+			"FORBIDDEN",
+			message ?? "You do not have permission to do this",
+			undefined,
+			message === undefined,
+		);
+	}
+}
+
+export class NotFoundError extends AppError {
+	constructor(resource?: string) {
+		super(
+			404,
+			"NOT_FOUND",
+			`${resource ?? "Resource"} not found`,
+			undefined,
+			resource === undefined,
+		);
+	}
+}
+
+export class ConflictError extends AppError {
+	constructor(message?: string, details?: unknown) {
+		super(409, "CONFLICT", message ?? "Resource already exists", details, message === undefined);
+	}
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+/** @tatara/http: plain Hono/OpenAPIHono setup, errors, the response envelope and docs. */
+export {
+	type CreateAppOptions,
+	createApp,
+	createRouter,
+	defineRoutes,
+	type HttpEnv,
+	handleErrors,
+	mountRoutes,
+	type RouteDefinition,
+	requestContext,
+	serveOpenApi,
+} from "./app.ts";
+export * from "./errors.ts";
+export * from "./response.ts";
+export { startServer } from "./server.ts";
+export { validationHook } from "./validation.ts";

package/src/response.ts

@@ -0,0 +1,72 @@
+import { z } from "@hono/zod-openapi";
+
+export const errorSchema = z
+	.object({
+		success: z.literal(false),
+		error: z.string(),
+		code: z.string(),
+		details: z.unknown().optional(),
+	})
+	.openapi("Error");
+
+export const paginationMetaSchema = z
+	.object({
+		page: z.number().int(),
+		pageSize: z.number().int(),
+		total: z.number().int(),
+		totalPages: z.number().int(),
+	})
+	.openapi("PaginationMeta");
+
+export const paginationQuerySchema = z.object({
+	page: z.coerce.number().int().min(1).default(1),
+	pageSize: z.coerce.number().int().min(1).max(100).default(20),
+});
+
+export type PaginationQuery = z.infer<typeof paginationQuerySchema>;
+
+export function successSchema<T extends z.ZodType>(data: T) {
+	return z.object({ success: z.literal(true), data });
+}
+
+export function paginatedSchema<T extends z.ZodType>(item: T) {
+	return z.object({ success: z.literal(true), data: z.array(item), meta: paginationMetaSchema });
+}
+
+export function success<T>(data: T) {
+	return { success: true as const, data };
+}
+
+export function paginated<T>(data: T[], page: number, pageSize: number, total: number) {
+	return {
+		success: true as const,
+		data,
+		meta: { page, pageSize, total, totalPages: Math.max(1, Math.ceil(total / pageSize)) },
+	};
+}
+
+export function jsonContent<T extends z.ZodType>(schema: T, description: string) {
+	return { content: { "application/json": { schema } }, description };
+}
+
+/** A required JSON request body. Without `required`, a request with no body skips validation. */
+export function jsonBody<T extends z.ZodType>(schema: T, description: string) {
+	return { ...jsonContent(schema, description), required: true };
+}
+
+const ERROR_DESCRIPTIONS = {
+	400: "Invalid request",
+	401: "Authentication required",
+	403: "Forbidden",
+	404: "Not found",
+	409: "Conflict",
+} as const;
+
+type ErrorStatus = keyof typeof ERROR_DESCRIPTIONS;
+
+/** OpenAPI error responses for the given statuses, all using the shared error envelope. */
+export function errorResponses<const S extends ErrorStatus[]>(...statuses: S) {
+	return Object.fromEntries(
+		statuses.map((status) => [status, jsonContent(errorSchema, ERROR_DESCRIPTIONS[status])]),
+	) as { [K in S[number]]: ReturnType<typeof jsonContent<typeof errorSchema>> };
+}

package/src/server.ts

@@ -0,0 +1,21 @@
+import { serve } from "@hono/node-server";
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import { type CoreLogger, handleSignals, onShutdown } from "@tatara/core";
+import type { HttpEnv } from "./app.ts";
+
+/** Starts an HTTP app; on shutdown stops accepting connections and drains in-flight requests. */
+export function startServer<E extends HttpEnv>(
+	app: OpenAPIHono<E>,
+	options: { port: number; name: string; logger: CoreLogger },
+) {
+	const { port, name, logger } = options;
+	const server = serve({ fetch: app.fetch, port }, (info) => {
+		logger.info(
+			{ port: info.port, app: name },
+			`${name} listening on http://localhost:${info.port}`,
+		);
+	});
+	onShutdown(`${name}-http`, () => new Promise<void>((resolve) => server.close(() => resolve())));
+	handleSignals(logger);
+	return server;
+}

package/src/validation.ts

@@ -0,0 +1,16 @@
+import type { Hook } from "@hono/zod-openapi";
+import { ValidationError } from "./errors.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: the hook is shared by every route schema
+export const validationHook: Hook<any, any, any, any> = (result) => {
+	if (!result.success) {
+		throw new ValidationError(
+			undefined,
+			result.error.issues.map((issue) => ({
+				path: issue.path.join("."),
+				message: issue.message,
+				code: issue.code,
+			})),
+		);
+	}
+};