@rhythmjs/http 0.0.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 rhythmjs
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @rhythmjs/http
+
+HTTP utility middleware for [Rhythm](https://github.com/rhythmjs/rhythm) routers and handlers. Each module
+is exported by its own subpath — there is no root barrel export.
+
+## Install
+
+```sh
+pnpm add @rhythmjs/http @rhythmjs/rhythm @rhythmjs/router
+```
+
+## `@rhythmjs/http/cookies`
+
+Parses the request `Cookie` header and exposes a `Cookies` jar on the context for reading and writing.
+
+```ts
+import { RhythmRouter } from "@rhythmjs/router";
+import { cookies, type CookiesContext } from "@rhythmjs/http/cookies";
+
+new RhythmRouter().use<CookiesContext>(cookies()).get("/", (ctx) => {
+  ctx.cookies.get("theme"); // string | undefined
+  ctx.cookies.set("theme", "dark", { httpOnly: true, sameSite: "lax", maxAge: 3600 });
+  ctx.cookies.delete("legacy");
+  ctx.response.body = "ok";
+});
+```
+
+- `ctx.cookies` — `get(name)`, `getAll()`, `set(name, value, options?)` (defaults to `Path=/`), and
+  `delete(name)` (sets `Max-Age=0`). Multiple `set()` calls emit separate `Set-Cookie` headers.
+- `CookieOptions` — `domain`, `expires`, `httpOnly`, `maxAge`, `path`, `sameSite`, `secure`.
+- The standalone `parseCookies(header)` and `serializeCookie(name, value, options?)` helpers are exported
+  too.
+
+## `@rhythmjs/http/session`
+
+Cookie-based sessions with a pluggable store.
+
+```ts
+import { session, type SessionContext } from "@rhythmjs/http/session";
+
+new RhythmRouter()
+  .use<SessionContext>(session())
+  .post("/login", (ctx) => {
+    ctx.session.set("user", "ada");
+    ctx.response.body = "logged in";
+  })
+  .get("/me", (ctx) => {
+    ctx.response.body = String(ctx.session.get("user") ?? "anonymous");
+  })
+  .post("/logout", (ctx) => {
+    ctx.session.destroy();
+    ctx.response.body = "logged out";
+  });
+```
+
+- `ctx.session` — `id`, `get(key)`, `set(key, value)`, `delete(key)`, `destroy()`.
+- The session cookie (`sid` by default; `HttpOnly`, `SameSite=Lax`, `Path=/`) is only written when the
+  session is first used, and `destroy()` deletes the stored session and expires the cookie. Unknown or
+  expired session ids get a fresh session — the cookie value is never trusted as-is.
+- `SessionOptions` — `store` (any `SessionStore` implementation; the bundled `MemoryStore` by default,
+  suitable for a single process), `cookieName`, `maxAge` (seconds, default 86400), `path`, `secure`,
+  `sameSite`.
+
+## `@rhythmjs/http/etag`
+
+Adds an `ETag` header derived from the response body (SHA-1) and answers `304 Not Modified` when the
+request's `If-None-Match` matches.
+
+```ts
+import { etag } from "@rhythmjs/http/etag";
+
+new RhythmRouter().use(etag()).get("/report", (ctx) => {
+  ctx.response.body = expensiveReport();
+});
+```
+
+- `etag({ weak: true })` emits `W/"..."` tags.
+- Only successful (2xx) string bodies are tagged; a pre-set `ETag` is left alone.
+
+## `@rhythmjs/http/timeout`
+
+Fails requests that exceed a deadline with `504 { "success": false, "status": 504, "message": "Gateway Timeout" }`.
+
+```ts
+import { timeout } from "@rhythmjs/http/timeout";
+
+new RhythmRouter().use(timeout(5000)).get("/slow", async (ctx) => {
+  ctx.response.body = await slowUpstream();
+});
+```
+
+Downstream errors still propagate as errors; only the deadline produces a 504. Note that the downstream
+work is not aborted — its result is discarded.
+
+## `@rhythmjs/http/body-limit`
+
+Rejects request bodies larger than a byte limit with `413 Payload Too Large`, using `Content-Length` when
+present and measuring the body otherwise.
+
+```ts
+import { bodyLimit } from "@rhythmjs/http/body-limit";
+
+new RhythmRouter().use(bodyLimit(1024 * 1024)).post("/upload", async (ctx) => {
+  ctx.response.body = "stored";
+});
+```
+
+## Development
+
+```sh
+pnpm install
+pnpm test       # vp test
+pnpm typecheck  # tsc --noEmit
+pnpm build      # vp pack
+```

package/dist/body-limit/body-limit.d.ts

@@ -0,0 +1,5 @@
+import { Middleware } from "@rhythmjs/rhythm";
+import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
+//#region src/body-limit/body-limit.d.ts
+export declare function bodyLimit(maxBytes: number): Middleware<RhythmHttpContext>;
+//#endregion

package/dist/body-limit/body-limit.js

@@ -0,0 +1,29 @@
+//#region src/body-limit/body-limit.ts
+function bodyLimit(maxBytes) {
+	return async (ctx, next) => {
+		const reject = () => {
+			ctx.response.status = 413;
+			ctx.response.headers.set("content-type", "application/json");
+			ctx.response.body = JSON.stringify({
+				success: false,
+				status: 413,
+				message: "Payload Too Large"
+			});
+		};
+		const contentLength = ctx.request.headers.get("content-length");
+		if (contentLength !== null) {
+			if (Number(contentLength) > maxBytes) {
+				reject();
+				return;
+			}
+		} else if (ctx.request.body !== null) {
+			if ((await ctx.request.clone().arrayBuffer()).byteLength > maxBytes) {
+				reject();
+				return;
+			}
+		}
+		await next();
+	};
+}
+//#endregion
+export { bodyLimit };

package/dist/cookies/cookies.d.ts

@@ -0,0 +1,27 @@
+import { Middleware } from "@rhythmjs/rhythm";
+import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
+//#region src/cookies/cookies.d.ts
+export interface CookieOptions {
+  domain?: string;
+  expires?: Date;
+  httpOnly?: boolean;
+  maxAge?: number;
+  path?: string;
+  sameSite?: "strict" | "lax" | "none";
+  secure?: boolean;
+}
+export declare function parseCookies(header: string | null): Record<string, string>;
+export declare function serializeCookie(name: string, value: string, options?: CookieOptions): string;
+export declare class Cookies {
+  #private;
+  constructor(incoming: Record<string, string>, headers: Headers);
+  get(name: string): string | undefined;
+  getAll(): Record<string, string>;
+  set(name: string, value: string, options?: CookieOptions): void;
+  delete(name: string, options?: CookieOptions): void;
+}
+export type CookiesContext = {
+  cookies: Cookies;
+};
+export declare function cookies(): Middleware<RhythmHttpContext>;
+//#endregion

package/dist/cookies/cookies.js

@@ -0,0 +1,64 @@
+//#region src/cookies/cookies.ts
+function parseCookies(header) {
+	const out = {};
+	if (!header) return out;
+	for (const part of header.split(/;\s*/)) {
+		const eq = part.indexOf("=");
+		if (eq === -1) continue;
+		const name = part.slice(0, eq).trim();
+		if (!name) continue;
+		let value = part.slice(eq + 1).trim();
+		if (value.startsWith("\"") && value.endsWith("\"")) value = value.slice(1, -1);
+		try {
+			out[name] = decodeURIComponent(value);
+		} catch {
+			out[name] = value;
+		}
+	}
+	return out;
+}
+function serializeCookie(name, value, options = {}) {
+	let cookie = `${name}=${encodeURIComponent(value)}`;
+	if (options.maxAge !== void 0) cookie += `; Max-Age=${Math.trunc(options.maxAge)}`;
+	if (options.domain !== void 0) cookie += `; Domain=${options.domain}`;
+	if (options.path !== void 0) cookie += `; Path=${options.path}`;
+	if (options.expires !== void 0) cookie += `; Expires=${options.expires.toUTCString()}`;
+	if (options.httpOnly) cookie += "; HttpOnly";
+	if (options.secure) cookie += "; Secure";
+	if (options.sameSite !== void 0) cookie += `; SameSite=${options.sameSite.charAt(0).toUpperCase()}${options.sameSite.slice(1)}`;
+	return cookie;
+}
+var Cookies = class {
+	#incoming;
+	#headers;
+	constructor(incoming, headers) {
+		this.#incoming = incoming;
+		this.#headers = headers;
+	}
+	get(name) {
+		return this.#incoming[name];
+	}
+	getAll() {
+		return { ...this.#incoming };
+	}
+	set(name, value, options = {}) {
+		this.#headers.append("set-cookie", serializeCookie(name, value, {
+			path: "/",
+			...options
+		}));
+	}
+	delete(name, options = {}) {
+		this.set(name, "", {
+			...options,
+			expires: void 0,
+			maxAge: 0
+		});
+	}
+};
+function cookies() {
+	return async (ctx, next) => {
+		await next({ cookies: new Cookies(parseCookies(ctx.request.headers.get("cookie")), ctx.response.headers) });
+	};
+}
+//#endregion
+export { Cookies, cookies, parseCookies, serializeCookie };

package/dist/etag/etag.d.ts

@@ -0,0 +1,8 @@
+import { Middleware } from "@rhythmjs/rhythm";
+import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
+//#region src/etag/etag.d.ts
+export interface EtagOptions {
+  weak?: boolean;
+}
+export declare function etag(options?: EtagOptions): Middleware<RhythmHttpContext>;
+//#endregion

package/dist/etag/etag.js

@@ -0,0 +1,25 @@
+//#region src/etag/etag.ts
+async function hash(body) {
+	const digest = await crypto.subtle.digest("SHA-1", new TextEncoder().encode(body));
+	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function etag(options = {}) {
+	return async (ctx, next) => {
+		await next();
+		const { response } = ctx;
+		if (response.status < 200 || response.status >= 300) return;
+		if (typeof response.body !== "string") return;
+		if (response.headers.get("etag") !== null) return;
+		const tag = `${options.weak ? "W/" : ""}"${await hash(response.body)}"`;
+		response.headers.set("etag", tag);
+		const ifNoneMatch = ctx.request.headers.get("if-none-match");
+		if (ifNoneMatch !== null && ifNoneMatch.split(/\s*,\s*/).includes(tag)) {
+			response.status = 304;
+			response.statusText = "Not Modified";
+			response.body = null;
+			response.headers.delete("content-length");
+		}
+	};
+}
+//#endregion
+export { etag };

package/dist/session/session.d.ts

@@ -0,0 +1,35 @@
+import { Middleware } from "@rhythmjs/rhythm";
+import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
+//#region src/session/session.d.ts
+export type SessionData = Record<string, unknown>;
+export interface SessionStore {
+  get(id: string): Promise<SessionData | undefined> | SessionData | undefined;
+  set(id: string, data: SessionData, maxAge: number): Promise<void> | void;
+  delete(id: string): Promise<void> | void;
+}
+export declare class MemoryStore implements SessionStore {
+  #private;
+  get(id: string): SessionData | undefined;
+  set(id: string, data: SessionData, maxAge: number): void;
+  delete(id: string): void;
+}
+export interface Session {
+  readonly id: string;
+  get<T = unknown>(key: string): T | undefined;
+  set(key: string, value: unknown): void;
+  delete(key: string): void;
+  destroy(): void;
+}
+export type SessionContext = {
+  session: Session;
+};
+export interface SessionOptions {
+  store?: SessionStore;
+  cookieName?: string;
+  maxAge?: number;
+  path?: string;
+  secure?: boolean;
+  sameSite?: "strict" | "lax" | "none";
+}
+export declare function session(options?: SessionOptions): Middleware<RhythmHttpContext>;
+//#endregion

package/dist/session/session.js

@@ -0,0 +1,77 @@
+//#region src/session/session.ts
+var MemoryStore = class {
+	#entries = /* @__PURE__ */ new Map();
+	get(id) {
+		const entry = this.#entries.get(id);
+		if (!entry) return void 0;
+		if (entry.expires <= Date.now()) {
+			this.#entries.delete(id);
+			return;
+		}
+		return entry.data;
+	}
+	set(id, data, maxAge) {
+		this.#entries.set(id, {
+			data,
+			expires: Date.now() + maxAge * 1e3
+		});
+	}
+	delete(id) {
+		this.#entries.delete(id);
+	}
+};
+function readCookie(header, name) {
+	if (!header) return void 0;
+	for (const part of header.split(/;\s*/)) {
+		const eq = part.indexOf("=");
+		if (eq === -1) continue;
+		if (part.slice(0, eq).trim() !== name) continue;
+		try {
+			return decodeURIComponent(part.slice(eq + 1).trim());
+		} catch {
+			return part.slice(eq + 1).trim();
+		}
+	}
+}
+function session(options = {}) {
+	const store = options.store ?? new MemoryStore();
+	const cookieName = options.cookieName ?? "sid";
+	const maxAge = options.maxAge ?? 86400;
+	const path = options.path ?? "/";
+	const sameSite = options.sameSite ?? "lax";
+	const baseAttributes = `; Path=${path}; HttpOnly; SameSite=${`${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`}${options.secure ? "; Secure" : ""}`;
+	return async (ctx, next) => {
+		const incomingId = readCookie(ctx.request.headers.get("cookie"), cookieName);
+		const existing = incomingId === void 0 ? void 0 : await store.get(incomingId);
+		const id = existing === void 0 ? crypto.randomUUID() : incomingId;
+		const data = { ...existing };
+		let dirty = false;
+		let destroyed = false;
+		await next({ session: {
+			id,
+			get: (key) => data[key],
+			set: (key, value) => {
+				data[key] = value;
+				dirty = true;
+			},
+			delete: (key) => {
+				delete data[key];
+				dirty = true;
+			},
+			destroy: () => {
+				destroyed = true;
+			}
+		} });
+		if (destroyed) {
+			if (incomingId !== void 0) await store.delete(incomingId);
+			ctx.response.headers.append("set-cookie", `${cookieName}=; Max-Age=0${baseAttributes}`);
+			return;
+		}
+		if (dirty) {
+			await store.set(id, data, maxAge);
+			if (existing === void 0) ctx.response.headers.append("set-cookie", `${cookieName}=${id}; Max-Age=${maxAge}${baseAttributes}`);
+		}
+	};
+}
+//#endregion
+export { MemoryStore, session };

package/dist/timeout/timeout.d.ts

@@ -0,0 +1,5 @@
+import { Middleware } from "@rhythmjs/rhythm";
+import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
+//#region src/timeout/timeout.d.ts
+export declare function timeout(ms: number): Middleware<RhythmHttpContext>;
+//#endregion

package/dist/timeout/timeout.js

@@ -0,0 +1,26 @@
+//#region src/timeout/timeout.ts
+function timeout(ms) {
+	return async (ctx, next) => {
+		let timer;
+		const expired = new Promise((resolve) => {
+			timer = setTimeout(() => resolve("expired"), ms);
+		});
+		try {
+			const pending = next().then(() => "completed");
+			if (await Promise.race([pending, expired]) === "expired") {
+				pending.catch(() => void 0);
+				ctx.response.status = 504;
+				ctx.response.headers.set("content-type", "application/json");
+				ctx.response.body = JSON.stringify({
+					success: false,
+					status: 504,
+					message: "Gateway Timeout"
+				});
+			}
+		} finally {
+			clearTimeout(timer);
+		}
+	};
+}
+//#endregion
+export { timeout };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@rhythmjs/http",
+  "version": "0.0.1",
+  "description": "HTTP utility middleware (cookies, sessions, etag, timeout, body limit) for Rhythm routers and handlers.",
+  "keywords": [
+    "body-limit",
+    "cookies",
+    "etag",
+    "http",
+    "middleware",
+    "rhythm",
+    "session",
+    "timeout"
+  ],
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rhythmjs/http.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./body-limit": {
+      "types": "./dist/body-limit/body-limit.d.ts",
+      "default": "./dist/body-limit/body-limit.js"
+    },
+    "./cookies": {
+      "types": "./dist/cookies/cookies.d.ts",
+      "default": "./dist/cookies/cookies.js"
+    },
+    "./etag": {
+      "types": "./dist/etag/etag.d.ts",
+      "default": "./dist/etag/etag.js"
+    },
+    "./session": {
+      "types": "./dist/session/session.d.ts",
+      "default": "./dist/session/session.js"
+    },
+    "./timeout": {
+      "types": "./dist/timeout/timeout.d.ts",
+      "default": "./dist/timeout/timeout.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "prepublishOnly": "vp check && vp test && vp pack",
+    "typecheck": "tsc --noEmit",
+    "test": "vp test",
+    "lint": "vp lint",
+    "fmt": "vp fmt",
+    "fmt:check": "vp fmt --check",
+    "check": "vp check"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "typescript": "^7.0.2",
+    "vite-plus": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@rhythmjs/rhythm": "^0.0.1",
+    "@rhythmjs/router": "^0.0.1"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "packageManager": "pnpm@10.33.2"
+}