hapi-terminator 0.0.6 → 0.2.0

package/README.md

@@ -1,12 +1,12 @@
 # hapi-terminator
 
-A Hapi plugin that terminates requests with payloads that exceed a specified size limit. This plugin helps protect your server from excessively large payloads by destroying the socket connection before the entire payload is processed.
+A Hapi plugin that terminates requests with payloads that exceed a specified size limit. This plugin helps protect your server from excessively large payloads by gracefully ending the socket connection before the entire payload is processed.
 
 ## Features
 
 - 🛡️ Protects against large payload attacks
 - 🔀 Different limits for registered vs unregistered routes
-- 🎯 Configurable thresholds using numbers or custom functions
+- 🎯 Per-route limit configuration
 - ⚡ Terminates connections early to save resources
 - 📦 TypeScript support included
 
@@ -54,46 +54,90 @@ await server.start();
 console.log('Server running on %s', server.info.uri);
 ```
 
-### Using Custom Functions
+### Per-Route Limits
 
-You can provide custom functions to determine whether a request should be terminated:
+You can override the global limits for specific routes by setting the limit in the route options:
 
 ```typescript
-const requestTerminateOptions: TerminatorOptions = {
-  registeredLimit: (request, size) => {
-    // Custom logic based on request properties
-    if (request.path === '/upload') {
-      return size > 10 * 1024 * 1024; // 10MB for upload route
-    }
-    return size > 500 * 1024; // 500KB for other routes
+import Hapi, { type PluginSpecificConfiguration } from '@hapi/hapi';
+import terminatorPlugin, { type TerminatorOptions, type TerminatorRouteOptions } from 'hapi-terminator';
+
+type RoutePluginOptions = PluginSpecificConfiguration & TerminatorRouteOptions;
+
+const server = Hapi.server({ port: 3000, host: '127.0.0.1' });
+
+await server.register({
+  plugin: terminatorPlugin,
+  options: {
+    registeredLimit: 500 * 1024, // 500KB default for registered routes
+    unregisteredLimit: 100 * 1024, // 100KB for unregistered routes
   },
-  unregisteredLimit: (request, size) => {
-    return size > 100 * 1024; // 100KB for unregistered routes
+});
+
+// Standard route with default limit (500KB)
+server.route({
+  method: ['GET', 'POST'],
+  path: '/',
+  handler: () => 'Hello World!',
+});
+
+// Upload route with higher limit (10MB)
+server.route({
+  method: ['POST'],
+  path: '/upload',
+  handler: () => ({ success: true }),
+  options: {
+    plugins: {
+      'hapi-terminator': { limit: 10 * 1024 * 1024 }, // 10MB
+    } as RoutePluginOptions,
   },
-};
+});
+
+// Unlimited route (disable limit for this specific route)
+server.route({
+  method: ['POST'],
+  path: '/stream',
+  handler: () => ({ success: true }),
+  options: {
+    plugins: {
+      'hapi-terminator': { limit: null }, // No limit
+    } as RoutePluginOptions,
+  },
+});
+
+await server.start();
 ```
 
 ## Configuration
 
 ### TerminatorOptions
 
-| Option              | Type                                                      | Description                                                                                                                                   |
-| ------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `registeredLimit`   | `number \| ((request: Request, size: number) => boolean)` | Maximum payload size for registered routes. Can be a number in bytes or a function that returns `true` if the request should be terminated.   |
-| `unregisteredLimit` | `number \| ((request: Request, size: number) => boolean)` | Maximum payload size for unregistered routes. Can be a number in bytes or a function that returns `true` if the request should be terminated. |
+| Option              | Type     | Description                                                                                                   |
+| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
+| `registeredLimit`   | `number` | Maximum payload size in bytes for registered routes. Must be >= 0. Set to `null` or `undefined` to disable.   |
+| `unregisteredLimit` | `number` | Maximum payload size in bytes for unregistered routes. Must be >= 0. Set to `null` or `undefined` to disable. |
+
+### TerminatorRouteOptions
+
+You can configure per-route limits using the route options:
+
+| Option  | Type     | Description                                                                                                                            |
+| ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `limit` | `number` | Maximum payload size in bytes for this specific route. Must be >= 0. Overrides the global `registeredLimit`. Set to `null` to disable. |
 
 ### Behavior
 
-- **Registered Routes**: When a payload exceeds the limit on a registered route, the socket is destroyed and a `413 Payload Too Large` error is thrown.
-- **Unregistered Routes**: When a payload exceeds the limit on an unregistered route, the socket is destroyed and a `404 Not Found` error is thrown.
-- **Disabled**: Set to `null`, `undefined`, or a negative number to disable termination for that category.
+- **Registered Routes**: When a payload exceeds the limit on a registered route, the socket is gracefully ended and a `413 Payload Too Large` error is returned.
+- **Unregistered Routes**: When a payload exceeds the limit on an unregistered route, the socket is gracefully ended and a `404 Not Found` error is returned.
+- **Per-Route Limits**: Route-specific limits take precedence over global limits, allowing you to customize limits for individual routes.
+- **Disabled**: Set to `null` or `undefined` to disable termination for that category or route.
 
 ## How It Works
 
 The plugin hooks into Hapi's `onRequest` extension point and checks the `Content-Length` header of incoming requests. If the content length exceeds the configured threshold:
 
-1. The socket connection is immediately destroyed
-2. An appropriate error response is thrown (413 for registered routes, 404 for unregistered routes)
+1. An appropriate error response is returned (413 for registered routes, 404 for unregistered routes)
+2. The socket connection is gracefully ended after the response is sent
 3. No further processing occurs, saving server resources
 
 ## License

package/dist/index.d.ts

@@ -1,13 +1,7 @@
-import type { Server, Request } from '@hapi/hapi';
-type LimitOption = number | ((request: Request, size: number) => boolean);
-type LimitOptionName = (typeof LIMIT_OPTION_NAMES)[keyof typeof LIMIT_OPTION_NAMES];
-export type TerminatorOptions = {
-    [Name in LimitOptionName]?: LimitOption;
-};
-declare const LIMIT_OPTION_NAMES: {
-    readonly REGISTERED: "registeredLimit";
-    readonly UNREGISTERED: "unregisteredLimit";
-};
+import type { Server } from '@hapi/hapi';
+import { z } from 'zod/mini';
+export type TerminatorRouteOptions = z.infer<typeof TerminatorRouteOptionsSchema>;
+export type TerminatorOptions = z.infer<typeof TerminatorOptionsSchema>;
 export declare const plugin: {
     pkg: {
         name: string;
@@ -34,7 +28,7 @@ export declare const plugin: {
             "typescript-eslint": string;
         };
         dependencies: {
-            "@hapi/boom": string;
+            zod: string;
         };
         prettier: string;
         "lint-staged": {
@@ -59,7 +53,16 @@ export declare const plugin: {
     };
     register: typeof register;
 };
-declare function register(server: Server, options: TerminatorOptions): Promise<void>;
+declare const TerminatorRouteOptionsSchema: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniObject<{
+    "hapi-terminator": z.ZodMiniObject<{
+        limit: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniNumber<number>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>>>;
+declare const TerminatorOptionsSchema: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniObject<{
+    registeredLimit: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniNumber<number>>>;
+    unregisteredLimit: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniNumber<number>>>;
+}, z.core.$strip>>>;
+declare function register(server: Server, rawOptions: TerminatorOptions): Promise<void>;
 declare const _default: {
     plugin: {
         pkg: {
@@ -87,7 +90,7 @@ declare const _default: {
                 "typescript-eslint": string;
             };
             dependencies: {
-                "@hapi/boom": string;
+                zod: string;
             };
             prettier: string;
             "lint-staged": {

package/dist/index.js

@@ -1,16 +1,24 @@
-import Boom from '@hapi/boom';
+import assert from 'node:assert';
+import { z } from 'zod/mini';
 import pkg from './package.json';
 const LIMIT_OPTION_NAMES = {
     REGISTERED: 'registeredLimit',
     UNREGISTERED: 'unregisteredLimit',
 };
+const PACKAGE_NAME = 'hapi-terminator';
+assert(PACKAGE_NAME === pkg.name);
 export const plugin = { pkg, register };
-async function register(server, options) {
-    server.ext('onRequest', onRequest(options));
+const LimitOptionShape = z.nullish(z.number().check(z.minimum(0)));
+const TerminatorRouteOptionsSchema = z.nullish(z.object({ [PACKAGE_NAME]: z.object({ limit: LimitOptionShape }) }));
+const TerminatorOptionsSchema = z.nullish(z.object({ registeredLimit: LimitOptionShape, unregisteredLimit: LimitOptionShape }));
+async function register(server, rawOptions) {
+    const options = TerminatorOptionsSchema.parse(rawOptions);
+    const routeOptionsCache = new Map();
+    server.ext('onRequest', validateHookHandler(options, routeOptionsCache));
 }
-function onRequest(options) {
+function validateHookHandler(pluginOptions, routeOptionsCache) {
     return (request, h) => {
-        const handler = validateRoute(request, h, options);
+        const handler = validateRoute(request, h, pluginOptions);
         const rawContentLength = request.headers['content-length'];
         if (!rawContentLength) {
             return h.continue;
@@ -19,29 +27,56 @@ function onRequest(options) {
         if (Number.isNaN(contentLength)) {
             return h.continue;
         }
-        const matchedRoute = request.server.match(request.method, request.path);
-        if (matchedRoute != null) {
-            return handler(contentLength, LIMIT_OPTION_NAMES.REGISTERED, option => {
-                throw Boom.entityTooLarge(typeof option === 'number' ? `Payload content length greater than maximum allowed: ${option}` : undefined);
+        const { route, options } = getRouteAndOptions(request, routeOptionsCache) ?? {};
+        if (route != null) {
+            return handler(contentLength, LIMIT_OPTION_NAMES.REGISTERED, options, option => {
+                return h
+                    .response({
+                    error: 'Request Entity Too Large',
+                    message: `Payload content length greater than maximum allowed: ${option}`,
+                    statusCode: 413,
+                })
+                    .code(413);
             });
         }
-        return handler(contentLength, LIMIT_OPTION_NAMES.UNREGISTERED, () => {
-            throw Boom.notFound();
+        assert(options == null, "Unregistered routes can't have route options");
+        return handler(contentLength, LIMIT_OPTION_NAMES.UNREGISTERED, null, () => {
+            return h.response({ error: 'Not Found', message: 'Not Found', statusCode: 404 }).code(404);
         });
     };
 }
+function getRouteAndOptions(request, routeOptionsCache) {
+    const matchedRoute = request.server.match(request.method, request.path, request.info.host);
+    if (matchedRoute == null) {
+        return null;
+    }
+    const cacheKey = `${matchedRoute.method}-${matchedRoute.path}`;
+    const cachedResult = routeOptionsCache.get(cacheKey);
+    if (cachedResult != null) {
+        return { options: cachedResult, route: matchedRoute };
+    }
+    const options = getRoutePluginSettings(matchedRoute);
+    routeOptionsCache.set(cacheKey, options);
+    return { options, route: matchedRoute };
+}
 function validateRoute(request, h, options) {
-    return (contentLength, optionName, throwError) => {
-        const option = options[optionName];
-        if (option == null || (typeof option === 'number' && option < 0)) {
+    return (contentLength, optionName, routeOptions, response) => {
+        const option = options?.[optionName];
+        const limit = routeOptions?.[PACKAGE_NAME]?.limit ?? option;
+        if (limit == null) {
             return h.continue;
         }
-        if ((typeof option === 'number' && contentLength > option) ||
-            (typeof option === 'function' && option(request, contentLength))) {
-            request.raw.req.socket?.destroy();
-            throwError(option);
+        if (contentLength <= limit) {
+            return h.continue;
         }
-        return h.continue;
+        const result = response(limit).takeover();
+        request.raw.res.once('finish', () => {
+            request.raw.req.socket.end();
+        });
+        return result;
     };
 }
+function getRoutePluginSettings(matchedRoute) {
+    return TerminatorRouteOptionsSchema.safeParse(matchedRoute?.settings.plugins).data;
+}
 export default { plugin };

package/dist/package.json

@@ -3,7 +3,7 @@
     "main": "dist/index.js",
     "typings": "dist/index.d.ts",
     "type": "module",
-    "version": "0.0.6",
+    "version": "0.2.0",
     "license": "MIT",
     "author": {
         "name": "Kamaal Farah"
@@ -23,7 +23,7 @@
         "typescript-eslint": "^8.52.0"
     },
     "dependencies": {
-        "@hapi/boom": "^10.0.1"
+        "zod": "^4.3.5"
     },
     "prettier": "@kamaalio/prettier-config",
     "lint-staged": {

package/package.json

@@ -3,7 +3,7 @@
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
   "type": "module",
-  "version": "0.0.6",
+  "version": "0.2.0",
   "license": "MIT",
   "author": {
     "name": "Kamaal Farah"
@@ -23,7 +23,7 @@
     "typescript-eslint": "^8.52.0"
   },
   "dependencies": {
-    "@hapi/boom": "^10.0.1"
+    "zod": "^4.3.5"
   },
   "prettier": "@kamaalio/prettier-config",
   "lint-staged": {