@rhythmjs/http 0.0.4 → 0.0.5

package/README.md

@@ -119,6 +119,57 @@ new RhythmRouter().use<I18nContext>(i18n({ i18next })).get("/greet", (ctx) => {
 - The standalone `detectLanguage(request, options?)` and `parseAcceptLanguage(header)` helpers are
   exported too.
 
+## `@rhythmjs/http/sse`
+
+Route middleware that applies the Server-Sent Events response headers. The handler owns the body:
+assign any `ReadableStream` of SSE frames — driven by a writer, a generator, an observable bridge, or
+anything else.
+
+```ts
+import { sse } from "@rhythmjs/http/sse";
+
+new RhythmRouter().get("/events", sse(), (ctx) => {
+  const encoder = new TextEncoder();
+  ctx.response.body = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(encoder.encode("data: hello\n\n"));
+      controller.close();
+    },
+  });
+});
+```
+
+- Defaults, each applied only if absent after the handler runs: `content-type: text/event-stream`,
+  `cache-control: no-cache, no-transform`, `connection: keep-alive`, `x-accel-buffering: no`
+  (disables nginx proxy buffering). Headers set by the handler or by other middleware win over them.
+- `SseOptions.headers` — extra headers that override everything, including handler-set values.
+- Every server adapter streams `ReadableStream` bodies with backpressure; `ctx.request.signal` aborts
+  on client disconnect, so producers can stop cleanly. The body streams after the middleware chain
+  resolves, so after-`next()` middleware sees time-to-headers, not the lifetime of the stream.
+
+## `@rhythmjs/http/stream`
+
+Route middleware that applies plain streaming response headers — the non-SSE sibling of
+`@rhythmjs/http/sse`. The handler owns the body: assign any `ReadableStream` (progressive text,
+NDJSON, LLM tokens, proxied upstream bodies).
+
+```ts
+import { stream } from "@rhythmjs/http/stream";
+
+new RhythmRouter().get("/report", stream(), (ctx) => {
+  ctx.response.body = upstream.body;
+});
+```
+
+- Defaults, each applied only if absent after the handler runs: `content-type: text/plain`,
+  `cache-control: no-cache, no-transform`, `connection: keep-alive`, `x-accel-buffering: no`, and
+  `x-content-type-options: nosniff` (stops browsers sniffing the stream into another type). Headers
+  set by the handler or by other middleware win over them.
+- `StreamOptions.headers` — extra headers that override everything, including handler-set values.
+- Same streaming model as `sse`: adapters stream `ReadableStream` bodies with backpressure,
+  `ctx.request.signal` aborts on client disconnect, and the body streams after the middleware chain
+  resolves.
+
 ## `@rhythmjs/http/timeout`
 
 Fails requests that exceed a deadline with `504 { "success": false, "status": 504, "message": "Gateway Timeout" }`.
@@ -147,6 +198,32 @@ new RhythmRouter().use(bodyLimit(1024 * 1024)).post("/upload", async (ctx) => {
 });
 ```
 
+## `@rhythmjs/http/multipart`
+
+Parses `multipart/form-data` request bodies once and exposes a `MultipartForm` on the context, with
+limits enforced before the handler runs. Uses the runtime's native multipart parser.
+
+```ts
+import { multipart, type MultipartContext } from "@rhythmjs/http/multipart";
+
+new RhythmRouter().post("/upload", multipart({ maxBytes: 10_000_000, maxFiles: 3 }), (ctx) => {
+  ctx.form.get("title"); // string | undefined
+  ctx.form.file("avatar"); // File | undefined
+  ctx.form.files(); // File[]
+  ctx.response.body = "stored";
+});
+```
+
+- `ctx.form` — `get(name)` / `getAll(name)` (string fields), `file(name)` / `files(name?)` (`File`
+  entries), and `data` (the raw `FormData`).
+- Rejections, all as `{ "success": false, "status": ..., "message": ... }`: `415` for non-multipart
+  content types, `400` for a missing or malformed body, `413` when `maxBytes` (total body, enforced
+  while reading via `Content-Length` or byte counting), `maxFileSize`, `maxFiles`, or `maxFields` is
+  exceeded.
+- The body is parsed once; downstream middleware and handlers share `ctx.form` instead of re-reading
+  the single-use body stream. Fields and files are held in memory — set `maxBytes` in production, and
+  keep streaming-to-disk uploads out of scope for this module.
+
 ## `@rhythmjs/http/request-scope`
 
 Opens a per-request scope (backed by

package/dist/multipart/multipart.d.ts

@@ -0,0 +1,23 @@
+import { DeriveMiddleware } from "@rhythmjs/rhythm/types";
+import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
+//#region src/multipart/multipart.d.ts
+export interface MultipartOptions {
+  maxBytes?: number;
+  maxFileSize?: number;
+  maxFiles?: number;
+  maxFields?: number;
+}
+export declare class MultipartForm {
+  #private;
+  constructor(data: FormData);
+  get data(): FormData;
+  get(name: string): string | undefined;
+  getAll(name: string): string[];
+  file(name: string): File | undefined;
+  files(name?: string): File[];
+}
+export type MultipartContext = {
+  form: MultipartForm;
+};
+export declare function multipart(options?: MultipartOptions): DeriveMiddleware<RhythmHttpContext, MultipartContext>;
+//#endregion

package/dist/multipart/multipart.js

@@ -0,0 +1,109 @@
+//#region src/multipart/multipart.ts
+var MultipartForm = class {
+	#data;
+	constructor(data) {
+		this.#data = data;
+	}
+	get data() {
+		return this.#data;
+	}
+	get(name) {
+		const value = this.#data.get(name);
+		return typeof value === "string" ? value : void 0;
+	}
+	getAll(name) {
+		return this.#data.getAll(name).filter((value) => typeof value === "string");
+	}
+	file(name) {
+		for (const value of this.#data.getAll(name)) if (value instanceof File) return value;
+	}
+	files(name) {
+		return (name === void 0 ? [...this.#data.values()] : this.#data.getAll(name)).filter((value) => value instanceof File);
+	}
+};
+var PayloadTooLargeError = class extends Error {};
+function isTooLarge(error) {
+	let current = error;
+	for (let depth = 0; depth < 8 && current !== null && current !== void 0; depth++) {
+		if (current instanceof PayloadTooLargeError) return true;
+		current = current.cause;
+	}
+	return false;
+}
+function parse(request, maxBytes) {
+	if (maxBytes === void 0 || request.body === null) return request.formData();
+	let total = 0;
+	const reader = request.body.getReader();
+	const limited = new ReadableStream({ async pull(controller) {
+		const { done, value } = await reader.read();
+		if (done) {
+			controller.close();
+			return;
+		}
+		total += value.byteLength;
+		if (total > maxBytes) controller.error(new PayloadTooLargeError());
+		else controller.enqueue(value);
+	} });
+	const headers = new Headers(request.headers);
+	headers.delete("content-length");
+	const init = {
+		method: request.method,
+		headers,
+		body: limited,
+		duplex: "half"
+	};
+	return new Request(request.url, init).formData();
+}
+function multipart(options = {}) {
+	const { maxBytes, maxFileSize, maxFiles, maxFields } = options;
+	const middleware = async (ctx, next) => {
+		const reject = (status, message) => {
+			ctx.response.status = status;
+			ctx.response.headers.set("content-type", "application/json");
+			ctx.response.body = JSON.stringify({
+				success: false,
+				status,
+				message
+			});
+		};
+		if (!(ctx.request.headers.get("content-type") ?? "").toLowerCase().startsWith("multipart/form-data")) {
+			reject(415, "Unsupported Media Type");
+			return;
+		}
+		if (ctx.request.body === null) {
+			reject(400, "Bad Request");
+			return;
+		}
+		const contentLength = ctx.request.headers.get("content-length");
+		if (maxBytes !== void 0 && contentLength !== null && Number(contentLength) > maxBytes) {
+			reject(413, "Payload Too Large");
+			return;
+		}
+		let data;
+		try {
+			data = await parse(ctx.request, maxBytes);
+		} catch (error) {
+			if (isTooLarge(error)) reject(413, "Payload Too Large");
+			else reject(400, "Bad Request");
+			return;
+		}
+		let fileCount = 0;
+		let fieldCount = 0;
+		for (const value of data.values()) if (value instanceof File) {
+			fileCount++;
+			if (maxFileSize !== void 0 && value.size > maxFileSize) {
+				reject(413, "Payload Too Large");
+				return;
+			}
+		} else fieldCount++;
+		if (maxFiles !== void 0 && fileCount > maxFiles || maxFields !== void 0 && fieldCount > maxFields) {
+			reject(413, "Payload Too Large");
+			return;
+		}
+		ctx.form = new MultipartForm(data);
+		await next();
+	};
+	return middleware;
+}
+//#endregion
+export { MultipartForm, multipart };

package/dist/sse/sse.d.ts

@@ -0,0 +1,8 @@
+import { Middleware } from "@rhythmjs/rhythm/types";
+import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
+//#region src/sse/sse.d.ts
+export interface SseOptions {
+  headers?: ConstructorParameters<typeof Headers>[0];
+}
+export declare function sse(options?: SseOptions): Middleware<RhythmHttpContext>;
+//#endregion

package/dist/sse/sse.js

@@ -0,0 +1,17 @@
+//#region src/sse/sse.ts
+const defaults = [
+	["content-type", "text/event-stream; charset=utf-8"],
+	["cache-control", "no-cache, no-transform"],
+	["connection", "keep-alive"],
+	["x-accel-buffering", "no"]
+];
+function sse(options = {}) {
+	const overrides = new Headers(options.headers);
+	return async (ctx, next) => {
+		await next();
+		for (const [name, value] of defaults) if (!ctx.response.headers.has(name)) ctx.response.headers.set(name, value);
+		for (const [name, value] of overrides) ctx.response.headers.set(name, value);
+	};
+}
+//#endregion
+export { sse };

package/dist/stream/stream.d.ts

@@ -0,0 +1,8 @@
+import { Middleware } from "@rhythmjs/rhythm/types";
+import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
+//#region src/stream/stream.d.ts
+export interface StreamOptions {
+  headers?: ConstructorParameters<typeof Headers>[0];
+}
+export declare function stream(options?: StreamOptions): Middleware<RhythmHttpContext>;
+//#endregion

package/dist/stream/stream.js

@@ -0,0 +1,18 @@
+//#region src/stream/stream.ts
+const defaults = [
+	["content-type", "text/plain; charset=utf-8"],
+	["cache-control", "no-cache, no-transform"],
+	["connection", "keep-alive"],
+	["x-accel-buffering", "no"],
+	["x-content-type-options", "nosniff"]
+];
+function stream(options = {}) {
+	const overrides = new Headers(options.headers);
+	return async (ctx, next) => {
+		await next();
+		for (const [name, value] of defaults) if (!ctx.response.headers.has(name)) ctx.response.headers.set(name, value);
+		for (const [name, value] of overrides) ctx.response.headers.set(name, value);
+	};
+}
+//#endregion
+export { stream };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rhythmjs/http",
-  "version": "0.0.4",
-  "description": "HTTP utility middleware (cookies, sessions, etag, timeout, body limit) for Rhythm routers and handlers.",
+  "version": "0.0.5",
+  "description": "HTTP utility middleware (cookies, sessions, etag, sse, streaming, multipart, timeout, body limit) for Rhythm routers and handlers.",
   "keywords": [
     "async-local-storage",
     "body-limit",
@@ -11,9 +11,13 @@
     "i18n",
     "i18next",
     "middleware",
+    "multipart",
     "request-scope",
     "rhythm",
+    "server-sent-events",
     "session",
+    "sse",
+    "streaming",
     "timeout"
   ],
   "license": "ISC",
@@ -43,6 +47,10 @@
       "types": "./dist/i18n/i18n.d.ts",
       "default": "./dist/i18n/i18n.js"
     },
+    "./multipart": {
+      "types": "./dist/multipart/multipart.d.ts",
+      "default": "./dist/multipart/multipart.js"
+    },
     "./request-scope": {
       "types": "./dist/request-scope/request-scope.d.ts",
       "default": "./dist/request-scope/request-scope.js"
@@ -51,6 +59,14 @@
       "types": "./dist/session/session.d.ts",
       "default": "./dist/session/session.js"
     },
+    "./sse": {
+      "types": "./dist/sse/sse.d.ts",
+      "default": "./dist/sse/sse.js"
+    },
+    "./stream": {
+      "types": "./dist/stream/stream.d.ts",
+      "default": "./dist/stream/stream.js"
+    },
     "./timeout": {
       "types": "./dist/timeout/timeout.d.ts",
       "default": "./dist/timeout/timeout.js"