spooder 4.4.2 → 4.4.4

package/README.md

@@ -46,7 +46,9 @@ The `CLI` component of `spooder` is a global command-line tool for running serve
 	- [`server.handle(status_code: number, handler: RequestHandler)`](#api-routing-server-handle)
 	- [`server.default(handler: DefaultHandler)`](#api-routing-server-default)
 	- [`server.error(handler: ErrorHandler)`](#api-routing-server-error)
+- [API > Routing > Slow Requests](#api-routing-slow-requests)
 	- [`server.on_slow_request(callback: SlowRequestCallback, threshold: number)`](#api-routing-server-on-slow-request)
+	- [`server.allow_slow_request(req: Request)`](#api-routing-server-allow-slow-request)
 - [API > Routing > Validation](#api-routing-validation)
 	- [`validate_req_json(handler: JSONRequestHandler)`](#api-routing-validate-req-json)
 - [API > Routing > Directory Serving](#api-routing-directory-serving)
@@ -671,6 +673,9 @@ server.error((err, req, url) => {
 });
 ```
 
+<a id="api-routing-slow-requests"></a>
+## API > Routing > Slow Requests
+
 <a id="api-routing-server-on-slow-request"></a>
 ### 🔧 `server.on_slow_request(callback: SlowRequestCallback, threshold: number)`
 
@@ -692,6 +697,27 @@ server.on_slow_request(async (req, time, url) => {
 > [!NOTE]
 > The callback is not awaited internally, so you can use `async/await` freely without blocking the server/request.
 
+<a id="api-routing-server-allow-slow-request"></a>
+### 🔧 `server.allow_slow_request(req: Request)`
+
+In some scenarios, mitigation throttling or heavy workloads may cause slow requests intentionally. To prevent these triggering a caution, requests can be marked as slow.
+
+```ts
+server.on_slow_request(async (req, time, url) => {
+	await caution('Slow request warning', { req, time });
+}, 500);
+
+server.route('/test', async (req) => {
+	// this request is marked as slow, therefore won't
+	// trigger on_slow_request despite taking 5000ms+
+	server.allow_slow_request(req);
+	await new Promise(res => setTimeout(res, 5000));
+});
+```
+
+> [!NOTE]
+> This will have no effect if a handler hasn't been registered with `on_slow_request`.
+
 <a id="api-routing-validation"></a>
 ## API > Routing > Validation
 
@@ -734,7 +760,7 @@ server.route('/api/endpoint', async (req, url) => {
 As you can see this is quite verbose and adds a lot of boilerplate to your handlers. `validate_req_json` can be used to simplify this.
 
 ```ts
-server.route('/api/endpoint', validate_req_json(async (json, req, url) => {
+server.route('/api/endpoint', validate_req_json(async (req, url, json) => {
 	// do something with json.
 	return 200;
 }));

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "spooder",
 	"type": "module",
-	"version": "4.4.2",
+	"version": "4.4.4",
 	"exports": {
 		".": {
 			"bun": "./src/api.ts",

package/src/api.ts

@@ -463,10 +463,10 @@ type Resolvable<T> = T | Promise<T>;
 type PromiseType<T extends Promise<any>> = T extends Promise<infer U> ? U : never;
 
 // The following types cover JSON serializable objects/classes.
-type JsonPrimitive = string | number | boolean | null;
-type JsonArray = JsonSerializable[];
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonArray = JsonSerializable[];
 
-interface JsonObject {
+export interface JsonObject {
 	[key: string]: JsonSerializable;
 }
 
@@ -698,6 +698,8 @@ export function serve(port: number) {
 	let slow_request_callback: SlowRequestCallback | null = null;
 	let slow_request_threshold: number = 1000;
 
+	const slow_requests = new WeakSet();
+
 	const server = Bun.serve({
 		port,
 		development: false,
@@ -709,9 +711,13 @@ export function serve(port: number) {
 			const response = await generate_response(req, url);
 			const request_time = Date.now() - request_start;
 
-			if (slow_request_callback !== null && request_time > slow_request_threshold)
+			const is_known_slow = slow_requests.has(req);
+			if (slow_request_callback !== null && request_time > slow_request_threshold && is_known_slow)
 				slow_request_callback(req, request_time, url);
 
+			if (is_known_slow)
+				slow_requests.delete(req);
+
 			return print_request_info(req, response, url, request_time);
 		}
 	});
@@ -758,6 +764,11 @@ export function serve(port: number) {
 			slow_request_threshold = threshold;
 		},
 
+		/** Mark a request as slow, preventing it from triggering slow request callback. */
+		allow_slow_request: (req: Request): void => {
+			slow_requests.add(req);
+		},
+
 		/** Register a default handler for all status codes. */
 		default: (handler: DefaultHandler): void => {
 			default_handler = handler;