spooder 6.1.1 → 6.1.3

package/README.md

@@ -104,6 +104,7 @@ The `CLI` component of `spooder` is a global command-line tool for running serve
 	- [API > HTTP > Webhooks](#api-http-webhooks)
 	- [API > HTTP > Websocket Server](#api-http-websockets)
 	- [API > HTTP > Bootstrap](#api-http-bootstrap)
+	- [API > HTTP > Cookies](#api-http-cookies)
 - [API > Error Handling](#api-error-handling)
 - [API > Workers](#api-workers)
 - [API > Caching](#api-caching)
@@ -603,6 +604,7 @@ server.stop(immediate: boolean): Promise<void>;
 // routing
 server.route(path: string, handler: RequestHandler, method?: HTTP_METHODS);
 server.json(path: string, handler: JSONRequestHandler, method?: HTTP_METHODS);
+server.throttle(delta: number, handler: JSONRequestHandler|RequestHandler);
 server.unroute(path: string);
 
 // fallback handlers
@@ -892,6 +894,24 @@ server.route('/test/route', () => {});
 server.unroute('/test/route');
 ```
 
+### 🔧 `server.throttle(delta: number, handler: JSONRequestHandler|RequestHandler)`
+
+Throttles requests going through the provided handler so that they take a **minimum** of `delta` milliseconds. Useful for preventing brute-force of sensitive endpoints.
+
+> [!IMPORTANT]
+> This is a rudimentary countermeasure for brute-force attacks, **not** a defence against timing-attacks. Always use constant-time/timing-safe comparison functions in sensitive endpoints.
+
+```ts
+server.json('/api/login', server.throttle(1000, (req, url, json) => {
+	// this endpoint will always take at least 1000ms to execute
+}));
+
+// works with regular routes
+server.route('/reset-password', server.throttle(1000, (req, url) => {
+	// this route will also take at least 1000ms to execute
+}));
+```
+
 ### 🔧 `server.json(path: string, handler: JSONRequestHandler, method?: HTTP_METHODS)`
 
 Register a JSON endpoint with automatic content validation. This method automatically validates that the request has the correct `Content-Type: application/json` header and that the request body contains a valid JSON object.
@@ -1397,6 +1417,35 @@ server.websocket('/path/to/websocket', {
 > [!IMPORTANT]
 > While it is possible to register multiple routes for websockets, the only handler which is unique per route is `accept()`. The last handlers provided to any route (with the exception of `accept()`) will apply to ALL websocket routes. This is a limitation in Bun.
 
+<a id="api-http-cookies"></a>
+## API > HTTP > Cookies
+
+### 🔧 `cookies_get(req: Request): Bun.CookieMap`
+
+When called on a request, the `cookies_get` function will return a `Bun.CookieMap` contains all of the cookies parsed from the `Cookie` header on the request.
+
+```ts
+server.route('/', (req, url) => {
+	const cookies = cookies_get(req);
+	return `Hello ${cookies.get('person') ?? 'unknown'}`;
+});
+```
+
+The return `Bun.CookieMap` is an iterable map with a custom API for reading/setting cookies. The full API [can be seen here](https://bun.com/docs/runtime/cookies).
+
+Any changes made to the cookie map (adding, deletion, editing, etc) will be sent as `Set-Cookie` headers on the response automatically. Unchanged cookies are not sent.
+
+```ts
+server.route('/', (req, url) => {
+	const cookies = cookies_get(req);
+	cookies.set('test', 'foobar');
+	return 'Hello, world!';
+
+	// the response automatically gets:
+	// Set-Cookie test=foobar; Path=/; SameSite=Lax
+});
+```
+
 <a id="api-http-bootstrap"></a>
 ## API > HTTP > Bootstrap
 

package/bun.lock

@@ -11,7 +11,7 @@
   "packages": {
     "@types/bun": ["@types/bun@1.3.1", "", { "dependencies": { "bun-types": "1.3.1" } }, "sha512-4jNMk2/K9YJtfqwoAa28c8wK+T7nvJFOjxI4h/7sORWcypRNxBpr+TPNaCfVWq70tLCJsqoFwcf0oI0JU/fvMQ=="],
 
-    "@types/node": ["@types/node@24.9.1", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-QoiaXANRkSXK6p0Duvt56W208du4P9Uye9hWLWgGMDTEoKPhuenzNcC4vGUmrNkiOKTlIrBoyNQYNpSwfEZXSg=="],
+    "@types/node": ["@types/node@24.9.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-uWN8YqxXxqFMX2RqGOrumsKeti4LlmIMIyV0lgut4jx7KQBcBiW6vkDtIBvHnHIquwNfJhk8v2OtmO8zXWHfPA=="],
 
     "@types/react": ["@types/react@19.2.2", "", { "dependencies": { "csstype": "^3.0.2" } }, "sha512-6mDvHUFSjyT2B2yeNx2nUgMxh9LtOWvkhIU3uePn2I2oyNymUAX1NIsdgviM4CH+JSrp2D2hsMvJOkxY+0wNRA=="],
 

package/package.json

@@ -2,7 +2,7 @@
 	"name": "spooder",
 	"author": "Kruithne <kruithne@gmail.com>",
 	"type": "module",
-	"version": "6.1.1",
+	"version": "6.1.3",
 	"module": "./src/api.ts",
 	"bin": {
 		"spooder": "./src/cli.ts"

package/src/api.ts

@@ -1143,6 +1143,26 @@ export function git_get_hashes_sync(length = 7): Record<string, string> {
 }
 // endregion
 
+// region cookies
+const cookie_map = new WeakMap<Request, Bun.CookieMap>();
+
+export function cookies_get(req: Request): Bun.CookieMap {
+	const jar = new Bun.CookieMap(req.headers.get('Cookie') ?? undefined);
+	cookie_map.set(req, jar);
+	return jar;
+}
+
+function apply_cookies(req: Request, res: Response) {
+	const jar = cookie_map.get(req);
+	if (jar === undefined)
+		return;
+
+	const cookies = jar.toSetCookieHeaders();
+	for (const cookie of cookies)
+		res.headers.append('Set-Cookie', cookie);
+}
+// endregion
+
 // region serving
 export const HTTP_STATUS_TEXT: Record<number, string> = {
 	// 1xx Informational Response
@@ -1736,6 +1756,8 @@ export function http_serve(port: number, hostname?: string) {
 			
 			const response = await generate_response(req, url);
 			const request_time = Date.now() - request_start;
+
+			apply_cookies(req, response);
 			
 			const is_known_slow = slow_requests.has(req);
 			if (slow_request_callback !== null && request_time > slow_request_threshold && !is_known_slow)
@@ -1782,6 +1804,11 @@ export function http_serve(port: number, hostname?: string) {
 	
 	log_spooder(`server started on port {${port}} (host: {${hostname ?? 'unspecified'}})`);
 	
+	type ThrottleHandler = {
+		(delta: number, handler: JSONRequestHandler): JSONRequestHandler;
+		(delta: number, handler: RequestHandler): RequestHandler;
+	};
+
 	return {
 		/** Register a handler for a specific route. */
 		route: (path: string, handler: RequestHandler, method: HTTP_METHODS = 'GET'): void => {
@@ -1789,6 +1816,23 @@ export function http_serve(port: number, hostname?: string) {
 				path = path.slice(0, -1);
 			routes.push([path.split('/'), handler, method]);
 		},
+
+		/** Throttles an endpoint to take at least the specified delta time (in ms) */
+		throttle: ((delta: number, handler: JSONRequestHandler | RequestHandler): any => {
+			return async (req: Request, ...args: any[]) => {
+				const t_start = Date.now();
+				const result = await (handler as any)(req, ...args);
+
+				const t_elapsed = Date.now() - t_start;
+				const t_remaining = Math.max(0, delta - t_elapsed);
+
+				if (t_remaining > 0)
+					await Bun.sleep(t_remaining);
+
+				slow_requests.add(req);
+				return result;
+			};
+		}) as ThrottleHandler,
 		
 		/** Register a JSON endpoint with automatic content validation. */
 		json: (path: string, handler: JSONRequestHandler, method: HTTP_METHODS = 'POST'): void => {

package/test.ts

@@ -1,10 +0,0 @@
-import { SQL } from 'bun';
-import * as spooder from 'spooder';
-
-type TestRow = {
-	ID: number;
-	test: string;
-};
-
-const db = new SQL('mysql://test:1141483652@localhost:3306/test');
-await spooder.db_schema(db, './db/revisions');