mikroserve 1.0.1 → 1.1.0

package/README.md

@@ -14,10 +14,14 @@
 
 - Native Node.js [http](https://nodejs.org/api/http.html)/[https](https://nodejs.org/api/https.html)/[http2](https://nodejs.org/api/http2.html) implementation, meaning maximum performance
 - [Hono](https://hono.dev)-style API semantics for GET, POST, PATCH, PUT, DELETE operations
+- Binary file upload/download support (images, PDFs, videos, etc.)
+- Multipart form-data parsing for HTML file uploads
 - Supports being exposed over HTTP, HTTPS, and HTTP2
 - Supports custom middlewares
 - Out-of-the-box CORS support
 - Built-in customizable rate limiter
+- Configurable request timeout protection against slow clients
+- Configurable body size limits
 - Tiny (~5kb gzipped)
 - Only a single dependency: [MikroConf](https://github.com/mikaelvesavuori/mikroconf)
 
@@ -189,6 +193,150 @@ api.get('/error', () => {
 api.start();
 ```
 
+### Binary File Uploads
+
+MikroServe automatically handles binary file uploads by preserving the raw Buffer for binary content types.
+
+```typescript
+import { MikroServe, type Context } from 'mikroserve';
+import { writeFile } from 'node:fs/promises';
+
+const api = new MikroServe();
+
+// Handle binary file upload (e.g., image, PDF, video)
+api.post('/upload', async (c: Context) => {
+  const buffer = c.body as Buffer;
+
+  // Save to disk
+  await writeFile('/uploads/file.bin', buffer);
+
+  return c.json({
+    success: true,
+    size: buffer.length,
+    message: 'File uploaded successfully'
+  });
+});
+
+// Handle image upload with binary response
+api.post('/process-image', async (c: Context) => {
+  const imageBuffer = c.body as Buffer;
+
+  // Process the image (resize, compress, etc.)
+  const processedImage = await processImage(imageBuffer);
+
+  // Return binary image
+  return c.binary(processedImage, 'image/jpeg');
+});
+
+api.start();
+```
+
+**Supported binary content types:**
+
+- Images: `image/*` (PNG, JPEG, GIF, WebP, etc.)
+- Videos: `video/*` (MP4, WebM, etc.)
+- Audio: `audio/*` (MP3, WAV, etc.)
+- Documents: `application/pdf`, Office documents, etc.
+- Archives: `application/zip`, `application/gzip`, etc.
+- Generic: `application/octet-stream`
+
+### Multipart Form-Data (File Uploads from HTML Forms)
+
+Handle file uploads from HTML forms with automatic multipart parsing.
+
+```typescript
+import { MikroServe, type Context, type MultipartFormData } from 'mikroserve';
+
+const api = new MikroServe();
+
+// Handle HTML form with file upload
+api.post('/submit-form', async (c: Context) => {
+  const { fields, files } = c.body as MultipartFormData;
+
+  // Access form fields
+  console.log(fields.username); // "john_doe"
+  console.log(fields.email);    // "john@example.com"
+
+  // Access uploaded file
+  const uploadedFile = files.avatar;
+  console.log(uploadedFile.filename);    // "profile.jpg"
+  console.log(uploadedFile.contentType); // "image/jpeg"
+  console.log(uploadedFile.size);        // 45234
+
+  // uploadedFile.data is a Buffer
+  await saveFile(`/uploads/${uploadedFile.filename}`, uploadedFile.data);
+
+  return c.json({
+    success: true,
+    user: fields.username,
+    file: uploadedFile.filename
+  });
+});
+
+// Handle multiple file uploads
+api.post('/upload-multiple', async (c: Context) => {
+  const { fields, files } = c.body as MultipartFormData;
+
+  // Multiple files with same field name become an array
+  const uploadedFiles = files.documents as Array<MultipartFile>;
+
+  for (const file of uploadedFiles) {
+    await saveFile(`/uploads/${file.filename}`, file.data);
+  }
+
+  return c.json({
+    success: true,
+    count: uploadedFiles.length
+  });
+});
+
+api.start();
+```
+
+**Example HTML form:**
+
+```html
+<form action="http://localhost:3000/submit-form" method="POST" enctype="multipart/form-data">
+  <input type="text" name="username" value="john_doe">
+  <input type="email" name="email" value="john@example.com">
+  <input type="file" name="avatar">
+  <button type="submit">Upload</button>
+</form>
+```
+
+### Custom Configuration
+
+Configure body size limits, request timeouts, and more.
+
+```typescript
+import { MikroServe } from 'mikroserve';
+
+const api = new MikroServe({
+  port: 3000,
+  host: '0.0.0.0',
+
+  // Set maximum request body size (default: 1MB)
+  maxBodySize: 50 * 1024 * 1024, // 50MB for large file uploads
+
+  // Set request timeout to prevent slow clients (default: 30 seconds)
+  requestTimeout: 60000, // 60 seconds, set to 0 to disable
+
+  // Rate limiting
+  rateLimit: {
+    enabled: true,
+    requestsPerMinute: 100
+  },
+
+  // CORS configuration
+  allowedDomains: ['https://yourdomain.com', 'https://app.yourdomain.com'],
+
+  // Enable debug logging
+  debug: false
+});
+
+api.start();
+```
+
 ## Configuration
 
 All of the settings already presented in the above examples can be provided in multiple ways.
@@ -203,6 +351,24 @@ All of the settings already presented in the above examples can be provided in m
 
 ### Options
 
+| Option                  | Type      | Default      | Description                                           |
+|------------------------|-----------|--------------|-------------------------------------------------------|
+| `port`                 | `number`  | `3000`       | Port to listen on                                     |
+| `host`                 | `string`  | `'0.0.0.0'`  | Host address to bind to                               |
+| `useHttps`             | `boolean` | `false`      | Enable HTTPS                                          |
+| `useHttp2`             | `boolean` | `false`      | Enable HTTP/2                                         |
+| `sslCert`              | `string`  | `''`         | Path to SSL certificate file                          |
+| `sslKey`               | `string`  | `''`         | Path to SSL key file                                  |
+| `sslCa`                | `string`  | `''`         | Path to SSL CA file                                   |
+| `debug`                | `boolean` | `false`      | Enable debug logging                                  |
+| `maxBodySize`          | `number`  | `1048576`    | Maximum request body size in bytes (1MB default)      |
+| `requestTimeout`       | `number`  | `30000`      | Request timeout in milliseconds (30s default, 0 = disabled) |
+| `rateLimit.enabled`    | `boolean` | `true`       | Enable rate limiting                                  |
+| `rateLimit.requestsPerMinute` | `number` | `100` | Maximum requests per minute per IP            |
+| `allowedDomains`       | `string[]`| `['*']`      | CORS allowed domains (wildcard `*` allows all)        |
+
+### CLI Arguments
+
 | CLI argument | CLI value                   | JSON (config file) value    | Environment variable |
 |--------------|-----------------------------|-----------------------------|----------------------|
 | --port       | `<number>`                  | port                        | PORT                 |
@@ -236,6 +402,73 @@ openssl req -x509 -newkey rsa:2048 -keyout local-key.pem -out local-cert.pem -da
 
 Feel free to change the key and cert names as you wish.
 
+## Response Helpers
+
+MikroServe provides convenient response helpers on the context object:
+
+```typescript
+// Text response
+c.text('Plain text content', 200);
+
+// JSON response
+c.json({ message: 'Success' }, 200);
+
+// HTML response
+c.html('<h1>Hello World</h1>', 200);
+
+// Binary response (for files, images, etc.)
+c.binary(buffer, 'image/png', 200);
+
+// Form-urlencoded response
+c.form({ key: 'value' }, 200);
+
+// Redirect
+c.redirect('/new-location', 302);
+
+// Custom status code
+c.status(404).json({ error: 'Not Found' });
+
+// Access raw response object
+const res = c.raw();
+```
+
+## TypeScript Support
+
+MikroServe is written in TypeScript and exports all necessary types:
+
+```typescript
+import {
+  MikroServe,
+  type Context,
+  type MultipartFile,
+  type MultipartFormData
+} from 'mikroserve';
+
+// Context provides full type information for request/response
+api.post('/upload', async (c: Context) => {
+  // c.body, c.params, c.query, c.headers are all typed
+  const data = c.body as MultipartFormData;
+  // ...
+});
+```
+
+## Performance Tips
+
+1. **Adjust body size limits** based on your use case:
+   - For JSON APIs: Keep default 1MB or lower
+   - For file uploads: Increase to 50-100MB or as needed
+
+2. **Enable request timeouts** to prevent resource exhaustion:
+   - Default 30 seconds is good for most APIs
+   - Increase for large file uploads
+   - Set to 0 only if you have other timeout mechanisms
+
+3. **Use rate limiting** to protect against abuse:
+   - Default 100 requests/minute per IP
+   - Adjust based on your traffic patterns
+
+4. **Binary responses**: Use `c.binary()` for files to avoid JSON serialization overhead
+
 ## License
 
 MIT. See the `LICENSE` file.

package/lib/MikroServe.d.mts

@@ -10,6 +10,7 @@ declare class MikroServe {
     private config;
     private rateLimiter;
     private router;
+    private shutdownHandlers;
     /**
      * @description Creates a new MikroServe instance.
      */
@@ -70,6 +71,10 @@ declare class MikroServe {
      * @description Parses the request body based on content type.
      */
     private parseBody;
+    /**
+     * @description Checks if a content type is binary.
+     */
+    private isBinaryContentType;
     /**
      * @description CORS middleware.
      */
@@ -86,6 +91,10 @@ declare class MikroServe {
      * @description Sets up graceful shutdown handlers for a server.
      */
     setupGracefulShutdown(server: ServerType): void;
+    /**
+     * @description Cleans up shutdown event listeners to prevent memory leaks.
+     */
+    private cleanupShutdownHandlers;
 }
 
 export { MikroServe };

package/lib/MikroServe.d.ts

@@ -10,6 +10,7 @@ declare class MikroServe {
     private config;
     private rateLimiter;
     private router;
+    private shutdownHandlers;
     /**
      * @description Creates a new MikroServe instance.
      */
@@ -70,6 +71,10 @@ declare class MikroServe {
      * @description Parses the request body based on content type.
      */
     private parseBody;
+    /**
+     * @description Checks if a content type is binary.
+     */
+    private isBinaryContentType;
     /**
      * @description CORS middleware.
      */
@@ -86,6 +91,10 @@ declare class MikroServe {
      * @description Sets up graceful shutdown handlers for a server.
      */
     setupGracefulShutdown(server: ServerType): void;
+    /**
+     * @description Cleans up shutdown event listeners to prevent memory leaks.
+     */
+    private cleanupShutdownHandlers;
 }
 
 export { MikroServe };