@tatara/http 0.1.1 → 0.1.2

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { Hook, OpenAPIHono, z } from "@hono/zod-openapi";
 import { CoreLogger } from "@tatara/core";
+import { ServerType } from "@hono/node-server";
 import { Context, MiddlewareHandler } from "hono";
 import { ContentfulStatusCode } from "hono/utils/http-status";
 //#region src/errors.d.ts
@@ -29,6 +30,26 @@ export declare class NotFoundError extends AppError {
 export declare class ConflictError extends AppError {
   constructor(message?: string, details?: unknown);
 }
+export declare class TooManyRequestsError extends AppError {
+  /** seconds until the caller may try again, sent as Retry-After */
+  readonly retryAfterSeconds: number;
+  constructor(retryAfterSeconds: number);
+}
+export declare class RequestTimeoutError extends AppError {
+  constructor();
+}
+//#endregion
+//#region src/timeout.d.ts
+interface TimeoutOptions {
+  defaultMs: number;
+  /** longer (or shorter) limits by path: "/api/uploads/*" matches everything under it */
+  paths?: Record<string, number>;
+}
+/**
+ * Answers 504 REQUEST_TIMEOUT when a handler takes longer than its path's limit. The handler isn't
+ * stopped: what it does after the 504 still happens, so give slow paths a longer limit instead.
+ */
+export declare function requestTimeout(options: TimeoutOptions): MiddlewareHandler;
 //#endregion
 //#region src/app.d.ts
 /** Variables every tatara app has; apps extend them with their own (principal, language, …). */
@@ -43,15 +64,20 @@ type Defaults<E extends HttpEnv> = Partial<Omit<E["Variables"], "requestId" | "l
 export declare function requestContext<E extends HttpEnv>(logger: CoreLogger, defaults?: Defaults<E>): MiddlewareHandler<E, string, {}, Response>;
 interface CreateAppOptions<E extends HttpEnv> {
   logger: CoreLogger;
+  /** origins are exact (`https://app.example.com`) or one-label patterns (`https://*.example.com`) */
   cors: {
     origins: string[];
     exposeHeaders?: string[];
     allowHeaders?: string[];
   };
   bodyLimitBytes: number;
+  /** a limit on how long a handler may take, with longer ones for slow paths */
+  timeouts?: TimeoutOptions;
   /** initial values for the app's own variables, e.g. `{ principal: null, language: "en" }` */
   defaults?: Defaults<E>;
 }
+/** Matches exact origins and `*.`-patterns, where `*` is exactly one DNS label (tenant subdomains). */
+export declare function corsOrigin(origins: string[]): (origin: string) => string | null;
 /** A plain OpenAPIHono app with request context, secure headers, CORS, body limit, /health and /ready. */
 export declare function createApp<E extends HttpEnv>(options: CreateAppOptions<E>): OpenAPIHono<E>;
 interface RouteDefinition<A extends string = string, E extends HttpEnv = HttpEnv> {
@@ -82,6 +108,79 @@ export declare function handleErrors<E extends HttpEnv>(app: OpenAPIHono<E>, opt
   message?: (err: AppError, c: Context<E>) => string;
 }): void;
 //#endregion
+//#region src/client-ip.d.ts
+/**
+ * The client address from X-Forwarded-For, counting `trustedHops` proxies from the right.
+ * Entries to the left of those were sent by the client and can be forged.
+ */
+export declare function trustedClientIp(forwardedFor: string | null | undefined, trustedHops: number): string | undefined;
+/**
+ * The caller's address: from X-Forwarded-For when `trustedHops` proxies sit in front (Cloud Run,
+ * a load balancer: 1), else the socket's peer. Undefined when neither is known (in-process tests).
+ */
+export declare function clientIp(c: Context, options?: {
+  trustedHops?: number;
+}): string | undefined;
+/**
+ * A copy of `request` whose X-Forwarded-For is only `ip`, for handlers like better-auth that key
+ * rate limits on that header and would otherwise trust whatever the client sent.
+ */
+export declare function withClientIp(request: Request, ip: string | undefined): Request;
+//#endregion
+//#region src/cursor.d.ts
+export declare const cursorQuerySchema: z.ZodObject<{
+  cursor: z.ZodOptional<z.ZodString>;
+  limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type CursorQuery = z.infer<typeof cursorQuerySchema>;
+export declare const cursorMetaSchema: z.ZodObject<{
+  nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare function cursorPageSchema<T extends z.ZodType>(item: T): z.ZodObject<{
+  success: z.ZodLiteral<true>;
+  data: z.ZodArray<T>;
+  meta: z.ZodObject<{
+    nextCursor: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>;
+}, z.core.$strip>;
+/** An opaque cursor: base64url JSON of where the next page starts (e.g. `{ createdAt, id }`). */
+export declare function encodeCursor(position: unknown): string;
+/** The position in `cursor`, checked against `schema`; a 400 INVALID_CURSOR when it doesn't parse. */
+export declare function decodeCursor<T extends z.ZodType>(schema: T, cursor: string): z.infer<T>;
+/**
+ * One page from rows fetched with `limit + 1`: the extra row only says there's another page.
+ * `positionOf` gives the cursor position of the last row on this page.
+ */
+export declare function cursorPage<T>(rows: T[], limit: number, positionOf: (row: T) => unknown): {
+  success: true;
+  data: T[];
+  meta: {
+    nextCursor: string | null;
+  };
+};
+//#endregion
+//#region src/rate-limit.d.ts
+/** What a rate limit counts with; `cache` from `@tatara/cache` is one. */
+interface RateLimitCounter {
+  increment(key: string, options: {
+    ttlMs: number;
+  }): Promise<number>;
+}
+interface RateLimitOptions {
+  counter: RateLimitCounter;
+  /** names the limit in its keys, e.g. "sign-in" */
+  name: string;
+  /** who is counted: an IP, a user id; null skips the limit for this request */
+  key: (c: Context) => string | null | undefined | Promise<string | null | undefined>;
+  windowMs: number;
+  max: number;
+}
+/**
+ * A fixed-window limit: `max` requests per `windowMs` per key, then 429 with Retry-After.
+ * A failing counter lets the request through (and logs it) rather than taking the API down.
+ */
+export declare function rateLimit(options: RateLimitOptions): MiddlewareHandler;
+//#endregion
 //#region src/response.d.ts
 export declare const errorSchema: z.ZodObject<{
   success: z.ZodLiteral<false>;
@@ -152,6 +251,7 @@ declare const ERROR_DESCRIPTIONS: {
   readonly 403: "Forbidden";
   readonly 404: "Not found";
   readonly 409: "Conflict";
+  readonly 429: "Too many requests";
 };
 type ErrorStatus = keyof typeof ERROR_DESCRIPTIONS;
 /** OpenAPI error responses for the given statuses, all using the shared error envelope. */
@@ -163,9 +263,11 @@ export declare function startServer<E extends HttpEnv>(app: OpenAPIHono<E>, opti
   port: number;
   name: string;
   logger: CoreLogger;
-}): import("@hono/node-server").ServerType;
+  /** runs once the server exists, e.g. to attach a websocket server to it */
+  onServer?: (server: ServerType) => void;
+}): ServerType;
 //#endregion
 //#region src/validation.d.ts
 export declare const validationHook: Hook<any, any, any, any>;
 //#endregion
-export type { CreateAppOptions, HttpEnv, RouteDefinition };
+export type { CreateAppOptions, HttpEnv, RateLimitCounter, RateLimitOptions, RouteDefinition, TimeoutOptions };

package/dist/index.mjs

@@ -6,6 +6,7 @@ import { cors } from "hono/cors";
 import { createMiddleware } from "hono/factory";
 import { HTTPException } from "hono/http-exception";
 import { secureHeaders } from "hono/secure-headers";
+import { getConnInfo } from "@hono/node-server/conninfo";
 import { serve } from "@hono/node-server";
 //#region src/errors.ts
 var AppError = class extends Error {
@@ -53,6 +54,50 @@ var ConflictError = class extends AppError {
 		super(409, "CONFLICT", message ?? "Resource already exists", details, message === void 0);
 	}
 };
+var TooManyRequestsError = class extends AppError {
+	/** seconds until the caller may try again, sent as Retry-After */
+	retryAfterSeconds;
+	constructor(retryAfterSeconds) {
+		super(429, "RATE_LIMITED", "Too many requests, try again later", void 0, true);
+		this.retryAfterSeconds = retryAfterSeconds;
+	}
+};
+var RequestTimeoutError = class extends AppError {
+	constructor() {
+		super(504, "REQUEST_TIMEOUT", "The request took too long", void 0, true);
+	}
+};
+//#endregion
+//#region src/timeout.ts
+function limitFor(path, options) {
+	let best;
+	for (const [pattern, ms] of Object.entries(options.paths ?? {})) {
+		const prefix = pattern.endsWith("/*") ? pattern.slice(0, -1) : void 0;
+		if ((prefix ? path.startsWith(prefix) || `${path}/` === prefix : path === pattern) && (!best || pattern.length > best.length)) best = {
+			length: pattern.length,
+			ms
+		};
+	}
+	return best?.ms ?? options.defaultMs;
+}
+/**
+* Answers 504 REQUEST_TIMEOUT when a handler takes longer than its path's limit. The handler isn't
+* stopped: what it does after the 504 still happens, so give slow paths a longer limit instead.
+*/
+function requestTimeout(options) {
+	return createMiddleware(async (c, next) => {
+		const ms = limitFor(c.req.path, options);
+		let timer;
+		const expired = new Promise((_, reject) => {
+			timer = setTimeout(() => reject(new RequestTimeoutError()), ms);
+		});
+		try {
+			await Promise.race([next(), expired]);
+		} finally {
+			clearTimeout(timer);
+		}
+	});
+}
 //#endregion
 //#region src/validation.ts
 const validationHook = (result) => {
@@ -90,13 +135,23 @@ function requestContext(logger, defaults = {}) {
 		else log.info(entry, "request");
 	});
 }
+/** Matches exact origins and `*.`-patterns, where `*` is exactly one DNS label (tenant subdomains). */
+function corsOrigin(origins) {
+	const exact = new Set(origins.filter((o) => !o.includes("*")));
+	const patterns = origins.filter((o) => o.includes("*")).map((o) => {
+		if (!/^https?:\/\/\*\.[^*]+$/.test(o)) throw new Error(`CORS origin pattern "${o}" must look like https://*.example.com`);
+		const escaped = o.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace("*", "[a-z0-9-]+");
+		return new RegExp(`^${escaped}$`, "i");
+	});
+	return (origin) => exact.has(origin) || patterns.some((p) => p.test(origin)) ? origin : null;
+}
 /** A plain OpenAPIHono app with request context, secure headers, CORS, body limit, /health and /ready. */
 function createApp(options) {
 	const app = new OpenAPIHono({ defaultHook: validationHook });
 	app.use(requestContext(options.logger, options.defaults));
 	app.use(secureHeaders());
 	app.use(cors({
-		origin: options.cors.origins,
+		origin: corsOrigin(options.cors.origins),
 		credentials: true,
 		allowHeaders: options.cors.allowHeaders ?? [
 			"Content-Type",
@@ -107,6 +162,7 @@ function createApp(options) {
 		exposeHeaders: options.cors.exposeHeaders ?? ["X-Request-Id"]
 	}));
 	app.use(bodyLimit({ maxSize: options.bodyLimitBytes }));
+	if (options.timeouts) app.use(requestTimeout(options.timeouts));
 	app.get("/health", (c) => c.json({ status: "ok" }));
 	app.get("/ready", async (c) => {
 		const result = await runReadinessChecks();
@@ -149,6 +205,7 @@ function serveOpenApi(app, options) {
 function handleErrors(app, options = {}) {
 	app.onError((err, c) => {
 		if (err instanceof AppError) {
+			if (err instanceof TooManyRequestsError) c.header("Retry-After", String(err.retryAfterSeconds));
 			const message = options.message ? options.message(err, c) : err.message;
 			return c.json({
 				success: false,
@@ -176,6 +233,110 @@ function handleErrors(app, options = {}) {
 	}, 404));
 }
 //#endregion
+//#region src/client-ip.ts
+/**
+* The client address from X-Forwarded-For, counting `trustedHops` proxies from the right.
+* Entries to the left of those were sent by the client and can be forged.
+*/
+function trustedClientIp(forwardedFor, trustedHops) {
+	if (!forwardedFor || trustedHops <= 0) return void 0;
+	const hops = forwardedFor.split(",").map((entry) => entry.trim()).filter(Boolean);
+	if (hops.length === 0) return void 0;
+	return hops[Math.max(0, hops.length - trustedHops)];
+}
+/**
+* The caller's address: from X-Forwarded-For when `trustedHops` proxies sit in front (Cloud Run,
+* a load balancer: 1), else the socket's peer. Undefined when neither is known (in-process tests).
+*/
+function clientIp(c, options = {}) {
+	const forwarded = trustedClientIp(c.req.header("x-forwarded-for"), options.trustedHops ?? 0);
+	if (forwarded) return forwarded;
+	try {
+		return getConnInfo(c).remote.address;
+	} catch {
+		return;
+	}
+}
+/**
+* A copy of `request` whose X-Forwarded-For is only `ip`, for handlers like better-auth that key
+* rate limits on that header and would otherwise trust whatever the client sent.
+*/
+function withClientIp(request, ip) {
+	const headers = new Headers(request.headers);
+	if (ip) headers.set("x-forwarded-for", ip);
+	else headers.delete("x-forwarded-for");
+	return new Request(request, { headers });
+}
+//#endregion
+//#region src/cursor.ts
+const cursorQuerySchema = z.object({
+	cursor: z.string().max(512).optional(),
+	limit: z.coerce.number().int().min(1).max(100).default(20)
+});
+const cursorMetaSchema = z.object({ nextCursor: z.string().nullable() }).openapi("CursorMeta");
+function cursorPageSchema(item) {
+	return z.object({
+		success: z.literal(true),
+		data: z.array(item),
+		meta: cursorMetaSchema
+	});
+}
+/** An opaque cursor: base64url JSON of where the next page starts (e.g. `{ createdAt, id }`). */
+function encodeCursor(position) {
+	return Buffer.from(JSON.stringify(position)).toString("base64url");
+}
+/** The position in `cursor`, checked against `schema`; a 400 INVALID_CURSOR when it doesn't parse. */
+function decodeCursor(schema, cursor) {
+	try {
+		return schema.parse(JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")));
+	} catch {
+		throw new AppError(400, "INVALID_CURSOR", "Invalid cursor", void 0, true);
+	}
+}
+/**
+* One page from rows fetched with `limit + 1`: the extra row only says there's another page.
+* `positionOf` gives the cursor position of the last row on this page.
+*/
+function cursorPage(rows, limit, positionOf) {
+	const data = rows.slice(0, limit);
+	const last = data.at(-1);
+	return {
+		success: true,
+		data,
+		meta: { nextCursor: rows.length > limit && last !== void 0 ? encodeCursor(positionOf(last)) : null }
+	};
+}
+//#endregion
+//#region src/rate-limit.ts
+/**
+* A fixed-window limit: `max` requests per `windowMs` per key, then 429 with Retry-After.
+* A failing counter lets the request through (and logs it) rather than taking the API down.
+*/
+function rateLimit(options) {
+	if (!(options.max > 0 && options.windowMs > 0)) throw new Error("rateLimit needs a positive max and windowMs");
+	const retryAfter = Math.ceil(options.windowMs / 1e3);
+	return createMiddleware(async (c, next) => {
+		const who = await options.key(c);
+		if (who) {
+			let count;
+			try {
+				count = await options.counter.increment(`rate:${options.name}:${who}`, { ttlMs: options.windowMs });
+			} catch (err) {
+				c.get("logger")?.warn({
+					err,
+					limit: options.name
+				}, "rate limit counter unavailable, allowing the request");
+			}
+			if (count !== void 0) {
+				c.header("RateLimit-Limit", String(options.max));
+				c.header("RateLimit-Remaining", String(Math.max(0, options.max - count)));
+				if (count > options.max) throw new TooManyRequestsError(retryAfter);
+			}
+		}
+		await next();
+	});
+}
+//#endregion
 //#region src/response.ts
 const errorSchema = z.object({
 	success: z.literal(false),
@@ -242,7 +403,8 @@ const ERROR_DESCRIPTIONS = {
 	401: "Authentication required",
 	403: "Forbidden",
 	404: "Not found",
-	409: "Conflict"
+	409: "Conflict",
+	429: "Too many requests"
 };
 /** OpenAPI error responses for the given statuses, all using the shared error envelope. */
 function errorResponses(...statuses) {
@@ -262,9 +424,10 @@ function startServer(app, options) {
 			app: name
 		}, `${name} listening on http://localhost:${info.port}`);
 	});
+	options.onServer?.(server);
 	onShutdown(`${name}-http`, () => new Promise((resolve) => server.close(() => resolve())));
 	handleSignals(logger);
 	return server;
 }
 //#endregion
-export { AppError, BusinessRuleError, ConflictError, ForbiddenError, NotFoundError, UnauthorizedError, ValidationError, createApp, createRouter, defineRoutes, errorResponses, errorSchema, handleErrors, jsonBody, jsonContent, mountRoutes, paginated, paginatedSchema, paginationMetaSchema, paginationQuerySchema, requestContext, serveOpenApi, startServer, success, successSchema, validationHook };
+export { AppError, BusinessRuleError, ConflictError, ForbiddenError, NotFoundError, RequestTimeoutError, TooManyRequestsError, UnauthorizedError, ValidationError, clientIp, corsOrigin, createApp, createRouter, cursorMetaSchema, cursorPage, cursorPageSchema, cursorQuerySchema, decodeCursor, defineRoutes, encodeCursor, errorResponses, errorSchema, handleErrors, jsonBody, jsonContent, mountRoutes, paginated, paginatedSchema, paginationMetaSchema, paginationQuerySchema, rateLimit, requestContext, requestTimeout, serveOpenApi, startServer, success, successSchema, trustedClientIp, validationHook, withClientIp };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tatara/http",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "tatara HTTP: Hono app setup, errors, envelope, OpenAPI docs and route mounting",
   "type": "module",
   "license": "MIT",
@@ -24,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.1"
+    "@tatara/core": "^0.1.2"
   },
   "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.1",
+    "@tatara/core": "^0.1.2",
     "pino": "^10.4.0",
     "zod": "^4.6.7"
   },

package/src/app.ts

@@ -7,7 +7,8 @@ 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 { AppError, TooManyRequestsError } from "./errors.ts";
+import { requestTimeout, type TimeoutOptions } from "./timeout.ts";
 import { validationHook } from "./validation.ts";
 
 /** Variables every tatara app has; apps extend them with their own (principal, language, …). */
@@ -42,12 +43,29 @@ export function requestContext<E extends HttpEnv>(logger: CoreLogger, defaults:
 
 export interface CreateAppOptions<E extends HttpEnv> {
 	logger: CoreLogger;
+	/** origins are exact (`https://app.example.com`) or one-label patterns (`https://*.example.com`) */
 	cors: { origins: string[]; exposeHeaders?: string[]; allowHeaders?: string[] };
 	bodyLimitBytes: number;
+	/** a limit on how long a handler may take, with longer ones for slow paths */
+	timeouts?: TimeoutOptions;
 	/** initial values for the app's own variables, e.g. `{ principal: null, language: "en" }` */
 	defaults?: Defaults<E>;
 }
 
+/** Matches exact origins and `*.`-patterns, where `*` is exactly one DNS label (tenant subdomains). */
+export function corsOrigin(origins: string[]): (origin: string) => string | null {
+	const exact = new Set(origins.filter((o) => !o.includes("*")));
+	const patterns = origins
+		.filter((o) => o.includes("*"))
+		.map((o) => {
+			if (!/^https?:\/\/\*\.[^*]+$/.test(o))
+				throw new Error(`CORS origin pattern "${o}" must look like https://*.example.com`);
+			const escaped = o.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace("*", "[a-z0-9-]+");
+			return new RegExp(`^${escaped}$`, "i");
+		});
+	return (origin) => (exact.has(origin) || patterns.some((p) => p.test(origin)) ? origin : null);
+}
+
 /** 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 });
@@ -55,7 +73,7 @@ export function createApp<E extends HttpEnv>(options: CreateAppOptions<E>): Open
 	app.use(secureHeaders());
 	app.use(
 		cors({
-			origin: options.cors.origins,
+			origin: corsOrigin(options.cors.origins),
 			credentials: true,
 			allowHeaders: options.cors.allowHeaders ?? [
 				"Content-Type",
@@ -67,6 +85,7 @@ export function createApp<E extends HttpEnv>(options: CreateAppOptions<E>): Open
 		}),
 	);
 	app.use(bodyLimit({ maxSize: options.bodyLimitBytes }));
+	if (options.timeouts) app.use(requestTimeout(options.timeouts));
 	app.get("/health", (c) => c.json({ status: "ok" }));
 	app.get("/ready", async (c) => {
 		const result = await runReadinessChecks();
@@ -135,6 +154,8 @@ export function handleErrors<E extends HttpEnv>(
 ): void {
 	app.onError((err, c) => {
 		if (err instanceof AppError) {
+			if (err instanceof TooManyRequestsError)
+				c.header("Retry-After", String(err.retryAfterSeconds));
 			const message = options.message ? options.message(err, c as Context<E>) : err.message;
 			return c.json(
 				{

package/src/client-ip.ts

@@ -0,0 +1,44 @@
+import { getConnInfo } from "@hono/node-server/conninfo";
+import type { Context } from "hono";
+
+/**
+ * The client address from X-Forwarded-For, counting `trustedHops` proxies from the right.
+ * Entries to the left of those were sent by the client and can be forged.
+ */
+export function trustedClientIp(
+	forwardedFor: string | null | undefined,
+	trustedHops: number,
+): string | undefined {
+	if (!forwardedFor || trustedHops <= 0) return undefined;
+	const hops = forwardedFor
+		.split(",")
+		.map((entry) => entry.trim())
+		.filter(Boolean);
+	if (hops.length === 0) return undefined;
+	return hops[Math.max(0, hops.length - trustedHops)];
+}
+
+/**
+ * The caller's address: from X-Forwarded-For when `trustedHops` proxies sit in front (Cloud Run,
+ * a load balancer: 1), else the socket's peer. Undefined when neither is known (in-process tests).
+ */
+export function clientIp(c: Context, options: { trustedHops?: number } = {}): string | undefined {
+	const forwarded = trustedClientIp(c.req.header("x-forwarded-for"), options.trustedHops ?? 0);
+	if (forwarded) return forwarded;
+	try {
+		return getConnInfo(c).remote.address;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * A copy of `request` whose X-Forwarded-For is only `ip`, for handlers like better-auth that key
+ * rate limits on that header and would otherwise trust whatever the client sent.
+ */
+export function withClientIp(request: Request, ip: string | undefined): Request {
+	const headers = new Headers(request.headers);
+	if (ip) headers.set("x-forwarded-for", ip);
+	else headers.delete("x-forwarded-for");
+	return new Request(request, { headers });
+}

package/src/cursor.ts

@@ -0,0 +1,43 @@
+import { z } from "@hono/zod-openapi";
+import { AppError } from "./errors.ts";
+
+export const cursorQuerySchema = z.object({
+	cursor: z.string().max(512).optional(),
+	limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+
+export type CursorQuery = z.infer<typeof cursorQuerySchema>;
+
+export const cursorMetaSchema = z
+	.object({ nextCursor: z.string().nullable() })
+	.openapi("CursorMeta");
+
+export function cursorPageSchema<T extends z.ZodType>(item: T) {
+	return z.object({ success: z.literal(true), data: z.array(item), meta: cursorMetaSchema });
+}
+
+/** An opaque cursor: base64url JSON of where the next page starts (e.g. `{ createdAt, id }`). */
+export function encodeCursor(position: unknown): string {
+	return Buffer.from(JSON.stringify(position)).toString("base64url");
+}
+
+/** The position in `cursor`, checked against `schema`; a 400 INVALID_CURSOR when it doesn't parse. */
+export function decodeCursor<T extends z.ZodType>(schema: T, cursor: string): z.infer<T> {
+	try {
+		return schema.parse(JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")));
+	} catch {
+		throw new AppError(400, "INVALID_CURSOR", "Invalid cursor", undefined, true);
+	}
+}
+
+/**
+ * One page from rows fetched with `limit + 1`: the extra row only says there's another page.
+ * `positionOf` gives the cursor position of the last row on this page.
+ */
+export function cursorPage<T>(rows: T[], limit: number, positionOf: (row: T) => unknown) {
+	const data = rows.slice(0, limit);
+	const last = data.at(-1);
+	const nextCursor =
+		rows.length > limit && last !== undefined ? encodeCursor(positionOf(last)) : null;
+	return { success: true as const, data, meta: { nextCursor } };
+}

package/src/errors.ts

@@ -77,3 +77,18 @@ export class ConflictError extends AppError {
 		super(409, "CONFLICT", message ?? "Resource already exists", details, message === undefined);
 	}
 }
+
+export class TooManyRequestsError extends AppError {
+	/** seconds until the caller may try again, sent as Retry-After */
+	readonly retryAfterSeconds: number;
+	constructor(retryAfterSeconds: number) {
+		super(429, "RATE_LIMITED", "Too many requests, try again later", undefined, true);
+		this.retryAfterSeconds = retryAfterSeconds;
+	}
+}
+
+export class RequestTimeoutError extends AppError {
+	constructor() {
+		super(504, "REQUEST_TIMEOUT", "The request took too long", undefined, true);
+	}
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 /** @tatara/http: plain Hono/OpenAPIHono setup, errors, the response envelope and docs. */
 export {
 	type CreateAppOptions,
+	corsOrigin,
 	createApp,
 	createRouter,
 	defineRoutes,
@@ -11,7 +12,11 @@ export {
 	requestContext,
 	serveOpenApi,
 } from "./app.ts";
+export { clientIp, trustedClientIp, withClientIp } from "./client-ip.ts";
+export * from "./cursor.ts";
 export * from "./errors.ts";
+export { type RateLimitCounter, type RateLimitOptions, rateLimit } from "./rate-limit.ts";
 export * from "./response.ts";
 export { startServer } from "./server.ts";
+export { requestTimeout, type TimeoutOptions } from "./timeout.ts";
 export { validationHook } from "./validation.ts";

package/src/rate-limit.ts

@@ -0,0 +1,51 @@
+import type { CoreLogger } from "@tatara/core";
+import type { Context, MiddlewareHandler } from "hono";
+import { createMiddleware } from "hono/factory";
+import { TooManyRequestsError } from "./errors.ts";
+
+/** What a rate limit counts with; `cache` from `@tatara/cache` is one. */
+export interface RateLimitCounter {
+	increment(key: string, options: { ttlMs: number }): Promise<number>;
+}
+
+export interface RateLimitOptions {
+	counter: RateLimitCounter;
+	/** names the limit in its keys, e.g. "sign-in" */
+	name: string;
+	/** who is counted: an IP, a user id; null skips the limit for this request */
+	key: (c: Context) => string | null | undefined | Promise<string | null | undefined>;
+	windowMs: number;
+	max: number;
+}
+
+/**
+ * A fixed-window limit: `max` requests per `windowMs` per key, then 429 with Retry-After.
+ * A failing counter lets the request through (and logs it) rather than taking the API down.
+ */
+export function rateLimit(options: RateLimitOptions): MiddlewareHandler {
+	if (!(options.max > 0 && options.windowMs > 0))
+		throw new Error("rateLimit needs a positive max and windowMs");
+	const retryAfter = Math.ceil(options.windowMs / 1000);
+	return createMiddleware(async (c, next) => {
+		const who = await options.key(c);
+		if (who) {
+			let count: number | undefined;
+			try {
+				count = await options.counter.increment(`rate:${options.name}:${who}`, {
+					ttlMs: options.windowMs,
+				});
+			} catch (err) {
+				(c.get("logger") as CoreLogger | undefined)?.warn(
+					{ err, limit: options.name },
+					"rate limit counter unavailable, allowing the request",
+				);
+			}
+			if (count !== undefined) {
+				c.header("RateLimit-Limit", String(options.max));
+				c.header("RateLimit-Remaining", String(Math.max(0, options.max - count)));
+				if (count > options.max) throw new TooManyRequestsError(retryAfter);
+			}
+		}
+		await next();
+	});
+}

package/src/response.ts

@@ -60,6 +60,7 @@ const ERROR_DESCRIPTIONS = {
 	403: "Forbidden",
 	404: "Not found",
 	409: "Conflict",
+	429: "Too many requests",
 } as const;
 
 type ErrorStatus = keyof typeof ERROR_DESCRIPTIONS;

package/src/server.ts

@@ -1,4 +1,4 @@
-import { serve } from "@hono/node-server";
+import { type ServerType, 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";
@@ -6,7 +6,13 @@ 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 },
+	options: {
+		port: number;
+		name: string;
+		logger: CoreLogger;
+		/** runs once the server exists, e.g. to attach a websocket server to it */
+		onServer?: (server: ServerType) => void;
+	},
 ) {
 	const { port, name, logger } = options;
 	const server = serve({ fetch: app.fetch, port }, (info) => {
@@ -15,6 +21,7 @@ export function startServer<E extends HttpEnv>(
 			`${name} listening on http://localhost:${info.port}`,
 		);
 	});
+	options.onServer?.(server);
 	onShutdown(`${name}-http`, () => new Promise<void>((resolve) => server.close(() => resolve())));
 	handleSignals(logger);
 	return server;

package/src/timeout.ts

@@ -0,0 +1,39 @@
+import type { MiddlewareHandler } from "hono";
+import { createMiddleware } from "hono/factory";
+import { RequestTimeoutError } from "./errors.ts";
+
+export interface TimeoutOptions {
+	defaultMs: number;
+	/** longer (or shorter) limits by path: "/api/uploads/*" matches everything under it */
+	paths?: Record<string, number>;
+}
+
+function limitFor(path: string, options: TimeoutOptions): number {
+	let best: { length: number; ms: number } | undefined;
+	for (const [pattern, ms] of Object.entries(options.paths ?? {})) {
+		const prefix = pattern.endsWith("/*") ? pattern.slice(0, -1) : undefined;
+		const matches = prefix ? path.startsWith(prefix) || `${path}/` === prefix : path === pattern;
+		// the most specific pattern wins
+		if (matches && (!best || pattern.length > best.length)) best = { length: pattern.length, ms };
+	}
+	return best?.ms ?? options.defaultMs;
+}
+
+/**
+ * Answers 504 REQUEST_TIMEOUT when a handler takes longer than its path's limit. The handler isn't
+ * stopped: what it does after the 504 still happens, so give slow paths a longer limit instead.
+ */
+export function requestTimeout(options: TimeoutOptions): MiddlewareHandler {
+	return createMiddleware(async (c, next) => {
+		const ms = limitFor(c.req.path, options);
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const expired = new Promise<never>((_, reject) => {
+			timer = setTimeout(() => reject(new RequestTimeoutError()), ms);
+		});
+		try {
+			await Promise.race([next(), expired]);
+		} finally {
+			clearTimeout(timer);
+		}
+	});
+}