hapi-terminator 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kamaal Farah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# 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.
+
+## Features
+
+- 🛡️ Protects against large payload attacks
+- 🔀 Different limits for registered vs unregistered routes
+- 🎯 Configurable thresholds using numbers or custom functions
+- ⚡ Terminates connections early to save resources
+- 📦 TypeScript support included
+
+## Installation
+
+```bash
+npm install hapi-terminator
+```
+
+or with other package managers:
+
+```bash
+yarn add hapi-terminator
+bun add hapi-terminator
+pnpm add hapi-terminator
+```
+
+## Usage
+
+### Basic Example
+
+```typescript
+import Hapi from '@hapi/hapi';
+import terminatorPlugin, { type TerminatorOptions } from 'hapi-terminator';
+
+const server = Hapi.server({ port: 3000, host: '127.0.0.1' });
+
+const requestTerminateOptions: TerminatorOptions = {
+  unregisteredLimit: 500 * 1024, // 500KB for unregistered routes
+  registeredLimit: 500 * 1024, // 500KB for registered routes
+};
+
+await server.register({
+  plugin: terminatorPlugin,
+  options: requestTerminateOptions,
+});
+
+server.route({
+  method: ['GET', 'POST'],
+  path: '/',
+  handler: () => 'Hello World!',
+});
+
+await server.start();
+console.log('Server running on %s', server.info.uri);
+```
+
+### Using Custom Functions
+
+You can provide custom functions to determine whether a request should be terminated:
+
+```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
+  },
+  unregisteredLimit: (request, size) => {
+    return size > 100 * 1024; // 100KB for unregistered routes
+  },
+};
+```
+
+## 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. |
+
+### 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.
+
+## 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)
+3. No further processing occurs, saving server resources
+
+## License
+
+MIT
+
+## Author
+
+Kamaal Farah

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+import type { Server, Request } from '@hapi/hapi';
+export type TerminatorOptions = {
+    registeredLimit?: number | ((request: Request, size: number) => boolean);
+    unregisteredLimit?: number | ((request: Request, size: number) => boolean);
+};
+export declare const plugin: {
+    pkg: {
+        name: string;
+        main: string;
+        typings: string;
+        type: string;
+        version: string;
+        license: string;
+        author: {
+            name: string;
+        };
+        devDependencies: {
+            "@eslint/js": string;
+            "@hapi/hapi": string;
+            "@kamaalio/prettier-config": string;
+            "@types/bun": string;
+            eslint: string;
+            globals: string;
+            husky: string;
+            jiti: string;
+            "lint-staged": string;
+            prettier: string;
+            typescript: string;
+            "typescript-eslint": string;
+        };
+        dependencies: {
+            "@hapi/boom": string;
+        };
+        prettier: string;
+        "lint-staged": {
+            "**/*.{js,ts,tsx}": string[];
+            "**/*": string;
+        };
+        scripts: {
+            compile: string;
+            format: string;
+            "format:check": string;
+            lint: string;
+            prepare: string;
+            prepack: string;
+            quality: string;
+            test: string;
+            typecheck: string;
+        };
+        publishConfig: {
+            access: string;
+        };
+        files: string[];
+    };
+    register: typeof register;
+};
+declare function register(server: Server, options: TerminatorOptions): Promise<void>;
+declare const _default: {
+    plugin: {
+        pkg: {
+            name: string;
+            main: string;
+            typings: string;
+            type: string;
+            version: string;
+            license: string;
+            author: {
+                name: string;
+            };
+            devDependencies: {
+                "@eslint/js": string;
+                "@hapi/hapi": string;
+                "@kamaalio/prettier-config": string;
+                "@types/bun": string;
+                eslint: string;
+                globals: string;
+                husky: string;
+                jiti: string;
+                "lint-staged": string;
+                prettier: string;
+                typescript: string;
+                "typescript-eslint": string;
+            };
+            dependencies: {
+                "@hapi/boom": string;
+            };
+            prettier: string;
+            "lint-staged": {
+                "**/*.{js,ts,tsx}": string[];
+                "**/*": string;
+            };
+            scripts: {
+                compile: string;
+                format: string;
+                "format:check": string;
+                lint: string;
+                prepare: string;
+                prepack: string;
+                quality: string;
+                test: string;
+                typecheck: string;
+            };
+            publishConfig: {
+                access: string;
+            };
+            files: string[];
+        };
+        register: typeof register;
+    };
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,56 @@
+import Boom from '@hapi/boom';
+import pkg from './package.json';
+export const plugin = { pkg, register };
+async function register(server, options) {
+    server.ext('onRequest', onRequest(options));
+}
+function onRequest(options) {
+    return (request, h) => {
+        const unregisteredRouteHandler = handleUnregisteredRoute(request, h, options);
+        const registeredRouteHandler = handleRegisteredRoute(request, h, options);
+        const rawContentLength = request.headers['content-length'];
+        if (!rawContentLength) {
+            return h.continue;
+        }
+        const contentLength = Number.parseInt(rawContentLength, 10);
+        if (Number.isNaN(contentLength)) {
+            return h.continue;
+        }
+        const matchedRoute = request.server.match(request.method, request.path);
+        if (matchedRoute != null) {
+            return registeredRouteHandler(contentLength);
+        }
+        return unregisteredRouteHandler(contentLength);
+    };
+}
+function handleUnregisteredRoute(request, h, options) {
+    return (contentLength) => {
+        if (options.unregisteredLimit == null ||
+            (typeof options.unregisteredLimit === 'number' && options.unregisteredLimit < 0)) {
+            return h.continue;
+        }
+        if ((typeof options.unregisteredLimit === 'number' && contentLength > options.unregisteredLimit) ||
+            (typeof options.unregisteredLimit === 'function' && options.unregisteredLimit(request, contentLength))) {
+            request.raw.req.socket?.destroy();
+            throw Boom.notFound();
+        }
+        return h.continue;
+    };
+}
+function handleRegisteredRoute(request, h, options) {
+    return (contentLength) => {
+        if (options.registeredLimit == null ||
+            (typeof options.registeredLimit === 'number' && options.registeredLimit < 0)) {
+            return h.continue;
+        }
+        if ((typeof options.registeredLimit === 'number' && contentLength > options.registeredLimit) ||
+            (typeof options.registeredLimit === 'function' && options.registeredLimit(request, contentLength))) {
+            request.raw.req.socket?.destroy();
+            throw Boom.entityTooLarge(typeof options.registeredLimit === 'number'
+                ? `Payload content length greater than maximum allowed: ${options.registeredLimit}`
+                : undefined);
+        }
+        return h.continue;
+    };
+}
+export default { plugin };

package/dist/package.json

@@ -0,0 +1,52 @@
+{
+    "name": "hapi-terminator",
+    "main": "index.js",
+    "typings": "index.d.ts",
+    "type": "module",
+    "version": "0.0.1",
+    "license": "MIT",
+    "author": {
+        "name": "Kamaal Farah"
+    },
+    "devDependencies": {
+        "@eslint/js": "^9.39.2",
+        "@hapi/hapi": "^21.4.4",
+        "@kamaalio/prettier-config": "^0.1.2",
+        "@types/bun": "latest",
+        "eslint": "^9.39.2",
+        "globals": "^17.0.0",
+        "husky": "^9.1.7",
+        "jiti": "^2.6.1",
+        "lint-staged": "^16.2.7",
+        "prettier": "^3.7.4",
+        "typescript": "^5.9.3",
+        "typescript-eslint": "^8.52.0"
+    },
+    "dependencies": {
+        "@hapi/boom": "^10.0.1"
+    },
+    "prettier": "@kamaalio/prettier-config",
+    "lint-staged": {
+        "**/*.{js,ts,tsx}": [
+            "eslint --fix"
+        ],
+        "**/*": "prettier --write --ignore-unknown"
+    },
+    "scripts": {
+        "compile": "tsc --project tsconfig.build.json",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "lint": "eslint .",
+        "prepare": "bunx husky",
+        "prepack": "rm -rf dist && bun run compile",
+        "quality": "bun run format:check && bun run lint && bun run typecheck",
+        "test": "bun test",
+        "typecheck": "tsc --noEmit"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "files": [
+        "dist"
+    ]
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "hapi-terminator",
+  "main": "index.js",
+  "typings": "index.d.ts",
+  "type": "module",
+  "version": "0.0.1",
+  "license": "MIT",
+  "author": {
+    "name": "Kamaal Farah"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@hapi/hapi": "^21.4.4",
+    "@kamaalio/prettier-config": "^0.1.2",
+    "@types/bun": "latest",
+    "eslint": "^9.39.2",
+    "globals": "^17.0.0",
+    "husky": "^9.1.7",
+    "jiti": "^2.6.1",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.4",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.52.0"
+  },
+  "dependencies": {
+    "@hapi/boom": "^10.0.1"
+  },
+  "prettier": "@kamaalio/prettier-config",
+  "lint-staged": {
+    "**/*.{js,ts,tsx}": [
+      "eslint --fix"
+    ],
+    "**/*": "prettier --write --ignore-unknown"
+  },
+  "scripts": {
+    "compile": "tsc --project tsconfig.build.json",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "prepare": "bunx husky",
+    "prepack": "rm -rf dist && bun run compile",
+    "quality": "bun run format:check && bun run lint && bun run typecheck",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ]
+}