spooder 4.2.15 → 4.2.17

package/README.md

@@ -47,6 +47,8 @@ The `CLI` component of `spooder` is a global command-line tool for running serve
 	- [`server.default(handler: DefaultHandler)`](#api-routing-server-default)
 	- [`server.error(handler: ErrorHandler)`](#api-routing-server-error)
 	- [`server.on_slow_request(callback: SlowRequestCallback, threshold: number)`](#api-routing-server-on-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)
 	- [`server.dir(path: string, dir: string, handler?: DirHandler, method: HTTP_METHODS)`](#api-routing-server-dir)
 - [API > Routing > Server-Sent Events](#api-routing-server-sent-events)
@@ -676,7 +678,7 @@ By default requests that take longer than `1000ms` to process will trigger the c
 > If your canary reports to a public repository, be cautious about directly including the `req` object in the callback. This can lead to sensitive information being leaked.
 
 ```ts
-server.on_slow_request(async (req, time) => {
+server.on_slow_request(async (req, time, url) => {
 	// avoid `time` in the title to avoid canary spam
 	// see caution() API for information
 	await caution('Slow request warning', { req, time });
@@ -686,6 +688,53 @@ server.on_slow_request(async (req, time) => {
 > [!NOTE]
 > The callback is not awaited internally, so you can use `async/await` freely without blocking the server/request.
 
+<a id="api-routing-validation"></a>
+## API > Routing > Validation
+
+<a id="api-routing-validate-req-json"></a>
+### 🔧 `validate_req_json(handler: JSONRequestHandler)`
+
+In the scenario that you're expecting an endpoint to receive JSON data, you might set up a handler like this:
+
+```ts
+server.route('/api/endpoint', async (req, url) => {
+	const json = await req.json();
+	// do something with json.
+	return 200;
+})
+```
+
+The problem with this is that if the request body is not valid JSON, the server will throw an error (potentially triggering canary reports) and return a `500` response.
+
+What should instead happen is something like this:
+
+```ts
+server.route('/api/endpoint', async (req, url) => {
+	// check content-type header
+	if (req.headers.get('Content-Type') !== 'application/json')
+		return 400;
+
+	try {
+		const json = await req.json();
+		// do something with json.
+		return 200;
+	} catch (err) {
+		return 400;
+	}
+})
+```
+
+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) => {
+	// do something with json.
+	return 200;
+}));
+```
+
+This behaves the same as the code above, where a `400` status code is returned if the `Content-Type` header is not `application/json` or if the request body is not valid JSON, and no error is thrown.
+
 <a id="api-routing-directory-serving"></a>
 ## API > Routing > Directory Serving
 

package/package.json

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

package/src/api.ts

@@ -398,6 +398,8 @@ type ErrorHandler = (err: Error, req: Request, url: URL) => Resolvable<Response>
 type DefaultHandler = (req: Request, status_code: number) => HandlerReturnType;
 type StatusCodeHandler = (req: Request) => HandlerReturnType;
 
+type JSONRequestHandler = (req: Request, url: URL, json: JsonSerializable) => HandlerReturnType;
+
 type ServerSentEventClient = {
 	message: (message: string) => void;
 	event: (event_name: string, message: string) => void;
@@ -442,6 +444,20 @@ function route_directory(route_path: string, dir: string, handler: DirHandler):
 	};
 }
 
+export function validate_req_json(JSONRequestHandler: JSONRequestHandler): RequestHandler {
+	return async (req: Request, url: URL) => {
+		try {
+			// validate content type header
+			if (req.headers.get('Content-Type') !== 'application/json')
+				return 400; // Bad Request
+
+			return JSONRequestHandler(req, url, await req.json());
+		} catch (e) {
+			return 400; // Bad Request
+		}
+	};
+}
+
 function format_query_parameters(search_params: URLSearchParams): string {
 	let result_parts = [];
 
@@ -586,7 +602,7 @@ export function serve(port: number) {
 		}
 	}
 
-	type SlowRequestCallback = (req: Request, request_time: number) => void;
+	type SlowRequestCallback = (req: Request, request_time: number, url: URL) => void;
 
 	let slow_request_callback: SlowRequestCallback | null = null;
 	let slow_request_threshold: number = 1000;
@@ -603,7 +619,7 @@ export function serve(port: number) {
 			const request_time = Date.now() - request_start;
 
 			if (slow_request_callback !== null && request_time > slow_request_threshold)
-				slow_request_callback(req, request_time);
+				slow_request_callback(req, request_time, url);
 
 			return print_request_info(req, response, url, request_time);
 		}