spooder 4.2.16 → 4.2.18

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)
@@ -686,6 +688,59 @@ 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-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();
+		if (json === null || typeof json !== 'object' || Array.isArray(json))
+			return 400;
+
+		// 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.
+
+> [!NOTE]
+> While arrays and other primitives are valid JSON, `validate_req_json` will only pass objects to the handler, since they are the most common use case for JSON request bodies and it removes the need to validate that in the handler. If you need to use arrays or other primitives, either box them in an object or provide your own validation.
+
 <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.16",
+	"version": "4.2.18",
 	"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: JsonObject) => HandlerReturnType;
+
 type ServerSentEventClient = {
 	message: (message: string) => void;
 	event: (event_name: string, message: string) => void;
@@ -442,6 +444,26 @@ 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
+
+			const json = await req.json();
+
+			// validate json is a plain object
+			if (json === null || typeof json !== 'object' || Array.isArray(json))
+				return 400; // Bad Request
+
+			return JSONRequestHandler(req, url, json);
+		} catch (e) {
+			return 400; // Bad Request
+		}
+	};
+}
+
 function format_query_parameters(search_params: URLSearchParams): string {
 	let result_parts = [];