@wooksjs/event-http 0.6.2 → 0.6.3

package/README.md

@@ -51,6 +51,30 @@ app.listen(3000, () => {
 })
 ```
 
+## AI Agent Skills
+
+This package ships with structured skill files for AI coding agents (Claude Code, Cursor, Windsurf, Codex, etc.).
+
+```bash
+# Project-local (recommended — version-locked, commits with your repo)
+npx @wooksjs/event-http setup-skills
+
+# Global (available across all your projects)
+npx @wooksjs/event-http setup-skills --global
+```
+
+To keep skills automatically up-to-date, add a postinstall script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "npx @wooksjs/event-http setup-skills --postinstall"
+  }
+}
+```
+
+This ensures the skill files are refreshed whenever dependencies are installed, without needing a separate command.
+
 ## Documentation
 
 To check out docs, visit [wooks.moost.org](https://wooks.moost.org/webapp/).

package/dist/index.cjs

@@ -32,6 +32,7 @@ const wooks = __toESM(require("wooks"));
 const stream = __toESM(require("stream"));
 
 //#region packages/event-http/src/event-http.ts
+/** Creates an async event context for an incoming HTTP request/response pair. */
 function createHttpContext(data, options) {
 	return (0, __wooksjs_event_core.createAsyncEventContext)({
 		event: {
@@ -57,7 +58,7 @@ function escapeRegex(s) {
 function safeDecode(f, v) {
 	try {
 		return f(v);
-	} catch (error) {
+	} catch {
 		return v;
 	}
 }
@@ -89,7 +90,12 @@ const units = {
 
 //#endregion
 //#region packages/event-http/src/utils/set-cookie.ts
+const COOKIE_NAME_RE = /^[\w!#$%&'*+\-.^`|~]+$/;
+function sanitizeCookieAttrValue(v) {
+	return v.replace(/[;\r\n]/g, "");
+}
 function renderCookie(key, data) {
+	if (!COOKIE_NAME_RE.test(key)) throw new TypeError(`Invalid cookie name "${key}"`);
 	let attrs = "";
 	for (const [a, v] of Object.entries(data.attrs)) {
 		const func = cookieAttrFunc[a];
@@ -103,8 +109,8 @@ function renderCookie(key, data) {
 const cookieAttrFunc = {
 	expires: (v) => `Expires=${typeof v === "string" || typeof v === "number" ? new Date(v).toUTCString() : v.toUTCString()}`,
 	maxAge: (v) => `Max-Age=${convertTime(v, "s").toString()}`,
-	domain: (v) => `Domain=${v}`,
-	path: (v) => `Path=${v}`,
+	domain: (v) => `Domain=${sanitizeCookieAttrValue(String(v))}`,
+	path: (v) => `Path=${sanitizeCookieAttrValue(String(v))}`,
 	secure: (v) => v ? "Secure" : "",
 	httpOnly: (v) => v ? "HttpOnly" : "",
 	sameSite: (v) => v ? `SameSite=${typeof v === "string" ? v : "Strict"}` : ""
@@ -125,7 +131,7 @@ function encodingSupportsStream(encodings) {
 }
 async function uncompressBody(encodings, compressed) {
 	let buf = compressed;
-	for (const enc of encodings.slice().reverse()) {
+	for (const enc of encodings.slice().toReversed()) {
 		const c = compressors[enc];
 		if (!c) throw new Error(`Unsupported compression type "${enc}".`);
 		buf = await c.uncompress(buf);
@@ -135,7 +141,7 @@ async function uncompressBody(encodings, compressed) {
 async function uncompressBodyStream(encodings, src) {
 	if (!encodingSupportsStream(encodings)) throw new Error("Some encodings lack a streaming decompressor");
 	let out = src;
-	for (const enc of Array.from(encodings).reverse()) out = await compressors[enc].stream.uncompress(out);
+	for (const enc of Array.from(encodings).toReversed()) out = await compressors[enc].stream.uncompress(out);
 	return out;
 }
 
@@ -455,8 +461,9 @@ function error_tl_default(ctx) {
     <title>${statusCode} ${statusMessage}</title>
     <style>
       body {
-        font-family: -apple-system, BlinkMacMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu,
-          Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
+        font-family:
+          -apple-system, BlinkMacMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell,
+          'Open Sans', 'Helvetica Neue', sans-serif;
         display: flex;
         justify-content: center;
         align-items: flex-start;
@@ -690,11 +697,12 @@ function error_tl_default(ctx) {
 //#endregion
 //#region packages/event-http/src/errors/error-renderer.ts
 let framework = {
-	version: "0.6.1",
+	version: "0.6.2",
 	poweredBy: `wooksjs`,
 	link: `https://wooks.moost.org/`,
 	image: `https://wooks.moost.org/wooks-full-logo.png`
 };
+/** Renders HTTP error responses in HTML, JSON, or plain text based on the Accept header. */
 var HttpErrorRenderer = class extends BaseHttpResponseRenderer {
 	constructor(opts) {
 		super();
@@ -766,6 +774,7 @@ function escapeQuotes(s) {
 
 //#endregion
 //#region packages/event-http/src/errors/http-error.ts
+/** Represents an HTTP error with a status code and optional structured body. */
 var HttpError = class extends Error {
 	name = "HttpError";
 	constructor(code = 500, _body = "") {
@@ -797,15 +806,24 @@ var HttpError = class extends Error {
 //#endregion
 //#region packages/event-http/src/composables/request.ts
 const xForwardedFor = "x-forwarded-for";
+/** Default safety limits for request body reading (size, ratio, timeout). */
 const DEFAULT_LIMITS = {
 	maxCompressed: 1 * 1024 * 1024,
 	maxInflated: 10 * 1024 * 1024,
 	maxRatio: 100,
 	readTimeoutMs: 1e4
 };
+/**
+* Provides access to the incoming HTTP request (method, url, headers, body, IP).
+* @example
+* ```ts
+* const { method, url, rawBody, getIp } = useRequest()
+* const body = await rawBody()
+* ```
+*/
 function useRequest() {
 	const { store } = useHttpContext();
-	const { init, get, set } = store("request");
+	const { init } = store("request");
 	const event = store("event");
 	const req = event.get("req");
 	const contentEncoding = req.headers["content-encoding"];
@@ -819,18 +837,33 @@ function useRequest() {
 		].includes(p)) return true;
 		return false;
 	});
-	const getMaxCompressed = () => get("maxCompressed") ?? DEFAULT_LIMITS.maxCompressed;
-	const setMaxCompressed = (limit) => set("maxCompressed", limit);
-	const getReadTimeoutMs = () => get("readTimeoutMs") ?? DEFAULT_LIMITS.readTimeoutMs;
-	const setReadTimeoutMs = (limit) => set("readTimeoutMs", limit);
-	const getMaxInflated = () => get("maxInflated") ?? DEFAULT_LIMITS.maxInflated;
-	const setMaxInflated = (limit) => set("maxInflated", limit);
+	const limits = () => event.get("requestLimits");
+	const setLimit = (key, value) => {
+		let obj = limits();
+		if (!obj?.perRequest) {
+			obj = {
+				...obj,
+				perRequest: true
+			};
+			event.set("requestLimits", obj);
+		}
+		obj[key] = value;
+	};
+	const getMaxCompressed = () => limits()?.maxCompressed ?? DEFAULT_LIMITS.maxCompressed;
+	const setMaxCompressed = (limit) => setLimit("maxCompressed", limit);
+	const getMaxInflated = () => limits()?.maxInflated ?? DEFAULT_LIMITS.maxInflated;
+	const setMaxInflated = (limit) => setLimit("maxInflated", limit);
+	const getMaxRatio = () => limits()?.maxRatio ?? DEFAULT_LIMITS.maxRatio;
+	const setMaxRatio = (limit) => setLimit("maxRatio", limit);
+	const getReadTimeoutMs = () => limits()?.readTimeoutMs ?? DEFAULT_LIMITS.readTimeoutMs;
+	const setReadTimeoutMs = (limit) => setLimit("readTimeoutMs", limit);
 	const rawBody = () => init("rawBody", async () => {
 		const encs = contentEncodings();
 		const isZip = isCompressed();
 		const streamable = isZip && encodingSupportsStream(encs);
 		const maxCompressed = getMaxCompressed();
 		const maxInflated = getMaxInflated();
+		const maxRatio = getMaxRatio();
 		const timeoutMs = getReadTimeoutMs();
 		const cl = Number(req.headers["content-length"] ?? 0);
 		const upfrontLimit = isZip ? maxCompressed : maxInflated;
@@ -888,6 +921,7 @@ function useRequest() {
 			inflatedBytes = body.byteLength;
 			if (inflatedBytes > maxInflated) throw new HttpError(413, "Inflated body too large");
 		}
+		if (isZip && rawBytes > 0 && inflatedBytes / rawBytes > maxRatio) throw new HttpError(413, "Compression ratio too high");
 		return body;
 	});
 	const reqId = (0, __wooksjs_event_core.useEventId)().getId;
@@ -919,15 +953,32 @@ function useRequest() {
 		getReadTimeoutMs,
 		setReadTimeoutMs,
 		getMaxInflated,
-		setMaxInflated
+		setMaxInflated,
+		getMaxRatio,
+		setMaxRatio
 	};
 }
 
 //#endregion
 //#region packages/event-http/src/composables/headers.ts
+/**
+* Returns the incoming request headers.
+* @example
+* ```ts
+* const { host, authorization } = useHeaders()
+* ```
+*/
 function useHeaders() {
 	return useRequest().headers;
 }
+/**
+* Provides methods to set, get, and remove outgoing response headers.
+* @example
+* ```ts
+* const { setHeader, setContentType, enableCors } = useSetHeaders()
+* setHeader('x-request-id', '123')
+* ```
+*/
 function useSetHeaders() {
 	const { store } = useHttpContext();
 	const setHeaderStore = store("setHeader");
@@ -949,6 +1000,7 @@ function useSetHeaders() {
 		enableCors
 	};
 }
+/** Returns a hookable accessor for a single outgoing response header by name. */
 function useSetHeader(name) {
 	const { store } = useHttpContext();
 	const { hook } = store("setHeader");
@@ -957,6 +1009,14 @@ function useSetHeader(name) {
 
 //#endregion
 //#region packages/event-http/src/composables/cookies.ts
+/**
+* Provides access to parsed request cookies.
+* @example
+* ```ts
+* const { getCookie, rawCookies } = useCookies()
+* const sessionId = getCookie('session_id')
+* ```
+*/
 function useCookies() {
 	const { store } = useHttpContext();
 	const { cookie } = useHeaders();
@@ -972,6 +1032,7 @@ function useCookies() {
 		getCookie
 	};
 }
+/** Provides methods to set, get, remove, and clear outgoing response cookies. */
 function useSetCookies() {
 	const { store } = useHttpContext();
 	const cookiesStore = store("setCookies");
@@ -992,6 +1053,7 @@ function useSetCookies() {
 		cookies
 	};
 }
+/** Returns a hookable accessor for a single outgoing cookie by name. */
 function useSetCookie(name) {
 	const { setCookie, getCookie } = useSetCookies();
 	const valueHook = (0, __wooksjs_event_core.attachHook)({
@@ -1013,6 +1075,7 @@ function useSetCookie(name) {
 
 //#endregion
 //#region packages/event-http/src/composables/header-accept.ts
+/** Provides helpers to check the request's Accept header for supported MIME types. */
 function useAccept() {
 	const { store } = useHttpContext();
 	const { accept } = useHeaders();
@@ -1033,6 +1096,14 @@ function useAccept() {
 
 //#endregion
 //#region packages/event-http/src/composables/header-authorization.ts
+/**
+* Provides parsed access to the Authorization header (type, credentials, Basic decoding).
+* @example
+* ```ts
+* const { isBearer, authRawCredentials, basicCredentials } = useAuthorization()
+* if (isBearer()) { const token = authRawCredentials() }
+* ```
+*/
 function useAuthorization() {
 	const { store } = useHttpContext();
 	const { authorization } = useHeaders();
@@ -1105,6 +1176,7 @@ const cacheControlFunc = {
 const renderAge = (v) => convertTime(v, "s").toString();
 const renderExpires = (v) => typeof v === "string" || typeof v === "number" ? new Date(v).toUTCString() : v.toUTCString();
 const renderPragmaNoCache = (v) => v ? "no-cache" : "";
+/** Provides helpers to set cache-related response headers (Cache-Control, Expires, Age, Pragma). */
 function useSetCacheControl() {
 	const { setHeader } = useSetHeaders();
 	const setAge = (value) => {
@@ -1129,6 +1201,14 @@ function useSetCacheControl() {
 
 //#endregion
 //#region packages/event-http/src/composables/response.ts
+/**
+* Provides access to the raw HTTP response and status code management.
+* @example
+* ```ts
+* const { status, rawResponse, hasResponded } = useResponse()
+* status(200)
+* ```
+*/
 function useResponse() {
 	const { store } = useHttpContext();
 	const event = store("event");
@@ -1151,6 +1231,7 @@ function useResponse() {
 		})
 	};
 }
+/** Returns a hookable accessor for the response status code. */
 function useStatus() {
 	const { store } = useHttpContext();
 	return store("status").hook("code");
@@ -1158,6 +1239,11 @@ function useStatus() {
 
 //#endregion
 //#region packages/event-http/src/utils/url-search-params.ts
+const ILLEGAL_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
 var WooksURLSearchParams = class extends url.URLSearchParams {
 	toJson() {
 		const json = Object.create(null);
@@ -1165,7 +1251,7 @@ var WooksURLSearchParams = class extends url.URLSearchParams {
 			const a = json[key] = json[key] || [];
 			a.push(value);
 		} else {
-			if (key === "__proto__") throw new HttpError(400, `Illegal key name "${key}"`);
+			if (ILLEGAL_KEYS.has(key)) throw new HttpError(400, `Illegal key name "${key}"`);
 			if (key in json) throw new HttpError(400, `Duplicate key "${key}"`);
 			json[key] = value;
 		}
@@ -1178,6 +1264,14 @@ function isArrayParam(name) {
 
 //#endregion
 //#region packages/event-http/src/composables/search-params.ts
+/**
+* Provides access to URL search (query) parameters from the request.
+* @example
+* ```ts
+* const { urlSearchParams, jsonSearchParams } = useSearchParams()
+* const page = urlSearchParams().get('page')
+* ```
+*/
 function useSearchParams() {
 	const { store } = useHttpContext();
 	const url$1 = useRequest().url || "";
@@ -1352,7 +1446,7 @@ var BaseHttpResponse = class {
 async function respondWithFetch(fetchBody, res) {
 	if (fetchBody) try {
 		for await (const chunk of fetchBody) res.write(chunk);
-	} catch (error) {}
+	} catch {}
 	res.end();
 }
 
@@ -1380,6 +1474,7 @@ function createWooksResponder(renderer = new BaseHttpResponseRenderer(), errorRe
 
 //#endregion
 //#region packages/event-http/src/http-adapter.ts
+/** HTTP adapter for Wooks that provides route registration, server lifecycle, and request handling. */
 var WooksHttp = class extends wooks.WooksAdapterBase {
 	logger;
 	constructor(opts, wooks$1) {
@@ -1387,27 +1482,35 @@ var WooksHttp = class extends wooks.WooksAdapterBase {
 		this.opts = opts;
 		this.logger = opts?.logger || this.getLogger(`[wooks-http]`);
 	}
+	/** Registers a handler for all HTTP methods on the given path. */
 	all(path, handler) {
 		return this.on("*", path, handler);
 	}
+	/** Registers a GET route handler. */
 	get(path, handler) {
 		return this.on("GET", path, handler);
 	}
+	/** Registers a POST route handler. */
 	post(path, handler) {
 		return this.on("POST", path, handler);
 	}
+	/** Registers a PUT route handler. */
 	put(path, handler) {
 		return this.on("PUT", path, handler);
 	}
+	/** Registers a PATCH route handler. */
 	patch(path, handler) {
 		return this.on("PATCH", path, handler);
 	}
+	/** Registers a DELETE route handler. */
 	delete(path, handler) {
 		return this.on("DELETE", path, handler);
 	}
+	/** Registers a HEAD route handler. */
 	head(path, handler) {
 		return this.on("HEAD", path, handler);
 	}
+	/** Registers an OPTIONS route handler. */
 	options(path, handler) {
 		return this.on("OPTIONS", path, handler);
 	}
@@ -1465,8 +1568,8 @@ var WooksHttp = class extends wooks.WooksAdapterBase {
 	}
 	responder = createWooksResponder();
 	respond(data) {
-		this.responder.respond(data)?.catch((e) => {
-			this.logger.error("Uncaught response exception", e);
+		this.responder.respond(data)?.catch((error) => {
+			this.logger.error("Uncaught response exception", error);
 		});
 	}
 	/**
@@ -1485,7 +1588,8 @@ var WooksHttp = class extends wooks.WooksAdapterBase {
 		return (req, res) => {
 			const runInContext = createHttpContext({
 				req,
-				res
+				res,
+				requestLimits: this.opts?.requestLimits
 			}, this.mergeEventOptions(this.opts?.eventOptions));
 			runInContext(async () => {
 				const { handlers } = this.wooks.lookup(req.method, req.url);
@@ -1525,10 +1629,13 @@ var WooksHttp = class extends wooks.WooksAdapterBase {
 	}
 };
 /**
-* Factory for WooksHttp App
-* @param opts TWooksHttpOptions
-* @param wooks Wooks | WooksAdapterBase
-* @returns WooksHttp
+* Creates a new WooksHttp application instance.
+* @example
+* ```ts
+* const app = createHttpApp()
+* app.get('/hello', () => 'Hello World!')
+* app.listen(3000)
+* ```
 */
 function createHttpApp(opts, wooks$1) {
 	return new WooksHttp(opts, wooks$1);