@hardlydifficult/http 1.0.4 → 1.0.6

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/http
 
-HTTP utilities for safe request/response handling, including constant-time string comparison, body reading with size limits, and JSON responses with CORS headers.
+HTTP utilities for safe request/response handling: body reading with size limits, constant-time comparison, and JSON responses with CORS.
 
 ## Installation
 
@@ -11,75 +11,149 @@ npm install @hardlydifficult/http
 ## Quick Start
 
 ```typescript
-import { readBody, sendJson, safeCompare } from '@hardlydifficult/http';
+import { createServer } from "http";
+import { readBody, sendJson, safeCompare } from "@hardlydifficult/http";
+
+const server = createServer(async (req, res) => {
+  // Read request body safely
+  const body = await readBody(req);
+  const token = JSON.parse(body).token;
+
+  // Compare tokens securely
+  const isMatch = safeCompare(token, process.env.SECRET_TOKEN ?? "");
+  if (!isMatch) {
+    sendJson(res, 401, { error: "Unauthorized" }, "https://example.com");
+    return;
+  }
+
+  // Send JSON response with CORS headers
+  sendJson(res, 200, { message: "Access granted" }, "https://example.com");
+});
+
+server.listen(3000);
+```
+
+## Core HTTP Utilities
+
+### Reading Request Body
 
-// Safe string comparison
-const isMatch = safeCompare('secret', 'secret'); // true
+Safely reads request body with a configurable size limit (default 1 MB) to prevent memory exhaustion.
 
-// Read request body with 1MB limit
-const body = await readBody(req); // max 1MB
+```typescript
+import { readBody, MAX_BODY_BYTES } from '@hardlydifficult/http';
+import { IncomingMessage } from 'http';
 
-// Send JSON response with CORS headers
-sendJson(res, { status: 'ok' });
+// Default: 1,048,576 bytes (1 MB)
+const body = await readBody(req as IncomingMessage);
+const text = body.toString();
+
+// Explicit limit
+const body2 = await readBody(req as IncomingMessage, 500_000); // 500 KB limit
 ```
 
-## HTTP Utilities
+| Parameter | Type | Description |
+|---|---|---|
+| req | `IncomingMessage` | HTTP request stream |
+| maxBytes? | `number` | Maximum body size in bytes (default: `MAX_BODY_BYTES`) |
+
+**Throws:** `Error` if body exceeds `maxBytes`.
 
-### Safe String Comparison
+### Sending JSON Responses
 
-Performs constant-time comparison of two strings to prevent timing attacks.
+Sends JSON with `Content-Type: application/json` and CORS headers.
 
 ```typescript
-import { safeCompare } from '@hardlydifficult/http';
+import { sendJson } from '@hardlydifficult/http';
+import { ServerResponse } from 'http';
 
-const result = safeCompare('abc123', 'abc123'); // true
-const fail = safeCompare('abc123', 'abc124');   // false
+sendJson(res as ServerResponse, { success: true });
+// Sets headers: Content-Type: application/json, Access-Control-Allow-Origin: *
 ```
 
-| Parameter | Type   | Description         |
-|-----------|--------|---------------------|
-| a         | string | First string to compare |
-| b         | string | Second string to compare |
+| Parameter | Type | Description |
+|---|---|---|
+| res | `ServerResponse` | HTTP response object |
+| data | `any` | Serializable data to send as JSON |
 
-### Reading Request Body
+## Response Handling
 
-Reads and returns the request body as a string, enforcing a maximum size limit of 1 MB.
+### `sendJson`
+
+Sends a JSON response with CORS headers.
 
 ```typescript
-import { readBody, MAX_BODY_BYTES } from '@hardlydifficult/http';
+import { sendJson } from "@hardlydifficult/http";
 
-const body = await readBody(req); // max 1,048,576 bytes (1 MB)
-// Throws Error if body exceeds MAX_BODY_BYTES
+sendJson(res, 200, { data: "example" }, "https://example.com");
 ```
 
-| Parameter | Type               | Description                    |
-|-----------|--------------------|--------------------------------|
-| req       | IncomingMessage    | Node.js HTTP request object    |
+| Parameter | Type | Description |
+|---|---|---|
+| `res` | `ServerResponse` | Node.js HTTP response |
+| `status` | `number` | HTTP status code |
+| `body` | `unknown` | Serializable data to send |
+| `corsOrigin` | `string` | `Access-Control-Allow-Origin` value |
 
-### Sending JSON Responses
+Sets headers:
+- `Content-Type: application/json`
+- `Access-Control-Allow-Origin: corsOrigin`
+- `Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS`
+- `Access-Control-Allow-Headers: Content-Type, Authorization`
+
+## Security
 
-Sends a JSON response with appropriate `Content-Type` and `Access-Control-Allow-Origin` headers.
+### `safeCompare`
+
+Constant-time string comparison to prevent timing attacks.
 
 ```typescript
-import { sendJson } from '@hardlydifficult/http';
+import { safeCompare } from "@hardlydifficult/http";
 
-sendJson(res, { message: 'Hello world' });
-// Sends: {"message":"Hello world"} with CORS headers
+const isValid = safeCompare(userInput, secretToken);
 ```
 
-| Parameter | Type     | Description                     |
-|-----------|----------|---------------------------------|
-| res       | ServerResponse | Node.js HTTP response object |
-| data      | unknown  | Data to serialize as JSON       |
+Returns `true` for identical strings (including empty strings) and `false` otherwise, regardless of string length or content differences.
+
+Handles:
+- Equal/unequal strings
+- Different-length strings
+- Unicode characters
+- Empty strings
+
+All comparisons run in time proportional to the first string's length.
 
-## Appendix
+```typescript
+import { safeCompare } from '@hardlydifficult/http';
 
-### Body Size Limit Behavior
+// True (same content)
+const match1 = safeCompare('abc', 'abc'); // => true
 
-The `readBody` function enforces a strict 1 MB (`MAX_BODY_BYTES = 1024 * 1024`) limit. If the request body exceeds this, it throws an error:
+// False (different content)
+const match2 = safeCompare('abc', 'abd'); // => false
+
+// False (different length)
+const match3 = safeCompare('abc', 'abcd'); // => false
+
+// Works with unicode
+const match4 = safeCompare('你好', '你好'); // => true
+```
+
+| Parameters | Type | Description |
+|---|---|---|
+| a | `string` | First string |
+| b | `string` | Second string |
+
+**Returns:** `boolean` — `true` if strings are identical, `false` otherwise.
+
+## Constants
+
+### `MAX_BODY_BYTES`
+
+Default maximum body size in bytes (1,048,576 = 1 MB).
 
 ```typescript
-if (received > MAX_BODY_BYTES) {
-  throw new Error(`Body exceeded maximum size of ${MAX_BODY_BYTES} bytes`);
-}
+import { MAX_BODY_BYTES } from '@hardlydifficult/http';
+
+// MAX_BODY_BYTES === 1024 * 1024
+console.log(MAX_BODY_BYTES); // 1048576
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/http",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [