Request Utility

The Request utility provides functions for handling HTTP request data, such as parsing multipart form data, and utilities for creating secure Content-Disposition headers.

parseMultipartBody

The parseMultipartBody function is an asynchronous utility for parsing multipart/form-data request bodies, which is essential for handling file uploads. It can store the uploaded files in memory or on disk.

parseMultipartBody(opts)

• opts (object):
  • context (object with req property): The Hono context object for the current request. Uses context.req.formData() internally.
  • storage ('memory' | 'disk', optional): The storage strategy for uploaded files. Defaults to 'memory'.
  • uploadDir (string, optional): The directory to save files to when using the 'disk' storage strategy. Defaults to './uploads'. The directory is created recursively if it does not exist.

The function returns a Promise that resolves to an array of IParsedFile objects. String form fields are skipped (only File entries are processed).

IParsedFile Interface

• fieldname: The name of the form field.
• originalname: The original name of the uploaded file.
• encoding: The file's encoding (always 'utf8').
• mimetype: The MIME type of the file.
• size: The size of the file in bytes.
• buffer (Buffer, optional): The file's content as a Buffer (if storage is 'memory').
• filename (string, optional): The generated name of the file on disk (if storage is 'disk'). Format: {timestamp}-{randomString}-{sanitizedOriginalName}.
• path (string, optional): The full path to the file on disk (if storage is 'disk').

Example

Here is an example of how to use parseMultipartBody in a controller to handle a file upload.

import { BaseRestController, controller } from '@venizia/ignis';
import { parseMultipartBody, HTTP } from '@venizia/ignis-helpers';

@controller({ path: '/files' })
export class FileController extends BaseRestController {
  // ...
  override binding() {
    this.defineRoute({
      configs: {
        path: '/upload',
        method: 'post',
        // Note: You would typically define a request body schema
        // for multipart/form-data in your OpenAPI spec.
      },
      handler: async (c) => {
        try {
          const files = await parseMultipartBody({
            context: c,
            storage: 'disk', // or 'memory'
            uploadDir: './my-uploads',
          });

          console.log('Uploaded files:', files);

          return c.json(
            { message: `${files.length} file(s) uploaded successfully.` },
            HTTP.ResultCodes.RS_2.Ok,
          );
        } catch (error) {
          return c.json(
            { message: 'Failed to upload files', error: error.message },
            HTTP.ResultCodes.RS_5.InternalServerError,
          );
        }
      },
    });
  }
}

---

Content-Disposition Utilities

These utilities help create secure, RFC-compliant Content-Disposition headers for file downloads.

createContentDispositionHeader

Creates a safe Content-Disposition header with proper filename encoding for file downloads.

createContentDispositionHeader(opts)

• opts (object):
  • filename (string): The filename to use in the Content-Disposition header.
  • type ('attachment' | 'inline'): The disposition type.

The function returns a properly formatted Content-Disposition header string with both ASCII and UTF-8 encoded filenames for maximum browser compatibility.

Features:

• Automatic filename sanitization via sanitizeFilename()
• UTF-8 encoding support via encodeRFC5987()
• RFC 5987 compliant
• Dual filename / filename* for browser compatibility

Example:

import { createContentDispositionHeader } from '@venizia/ignis-helpers';

// Attachment (file download)
ctx.header('content-disposition', createContentDispositionHeader({
  filename: 'my-document.pdf',
  type: 'attachment',
}));
// Output: attachment; filename="my-document.pdf"; filename*=UTF-8''my-document.pdf

// Inline (display in browser)
ctx.header('content-disposition', createContentDispositionHeader({
  filename: 'report.pdf',
  type: 'inline',
}));
// Output: inline; filename="report.pdf"; filename*=UTF-8''report.pdf

---

sanitizeFilename

Sanitizes a filename for safe use, removing path components and dangerous characters. Useful for HTTP headers (e.g., Content-Disposition) and general file handling.

sanitizeFilename(filename: string): string

• filename (string): The filename to sanitize.

Returns a safe filename suitable for use in headers or filesystem operations.

Features:

• Removes path components via path.basename() (prevents directory traversal attacks)
• Allows only word characters (\w), spaces, hyphens, underscores, and dots
• Replaces dangerous characters with underscores
• Removes leading dots (prevents hidden files)
• Replaces consecutive dots with a single dot
• Removes ".." patterns (additional path traversal protection)
• Returns 'download' for empty, suspicious, or invalid filenames

Example:

import { sanitizeFilename } from '@venizia/ignis-helpers';

sanitizeFilename('../../etc/passwd');        // Returns: 'passwd'
sanitizeFilename('my<file>name.txt');        // Returns: 'my_file_name.txt'
sanitizeFilename('.hidden');                 // Returns: 'hidden'
sanitizeFilename('file...txt');              // Returns: 'file.txt'
sanitizeFilename('');                        // Returns: 'download'
sanitizeFilename('..');                      // Returns: 'download'

encodeRFC5987

Encodes a filename according to RFC 5987 for use in HTTP headers. Encodes using encodeURIComponent and additionally escapes single quotes, parentheses, and asterisks.

encodeRFC5987(filename: string): string

• filename (string): The filename to encode.

Returns an RFC 5987 encoded string suitable for the filename* parameter in Content-Disposition headers.

Example:

import { encodeRFC5987 } from '@venizia/ignis-helpers';

encodeRFC5987('my document.pdf');     // Returns: 'my%20document.pdf'

IRequestedRemark Interface

The Request utility also exports the IRequestedRemark interface, which describes a request remark object:

• id (string): The request identifier.
• url (string): The request URL.
• method (string): The HTTP method.
• [extra: string | symbol]: Additional arbitrary properties.

Complete File Download Example

Here's a complete example combining multipart upload parsing with secure file downloads:

import { BaseRestController, controller } from '@venizia/ignis';
import { parseMultipartBody, createContentDispositionHeader, HTTP } from '@venizia/ignis-helpers';
import fs from 'node:fs';
import path from 'node:path';

@controller({ path: '/files' })
export class FileController extends BaseRestController {
  override binding() {
    // Upload endpoint
    this.bindRoute({
      configs: { path: '/upload', method: 'post' },
    }).to({
      handler: async (ctx) => {
        const files = await parseMultipartBody({
          context: ctx,
          storage: 'disk',
          uploadDir: './uploads',
        });

        return ctx.json(
          {
            message: 'Files uploaded successfully',
            files: files.map(f => ({ name: f.originalname, size: f.size })),
          },
          HTTP.ResultCodes.RS_2.Ok,
        );
      },
    });

    // Download endpoint
    this.bindRoute({
      configs: { path: '/:filename', method: 'get' },
    }).to({
      handler: async (ctx) => {
        const { filename } = ctx.req.valid('param');
        const filePath = path.join('./uploads', filename);

        // Read file
        const fileStat = fs.statSync(filePath);
        const fileStream = fs.createReadStream(filePath);

        // Set secure headers
        ctx.header('content-type', 'application/octet-stream');
        ctx.header('content-length', fileStat.size.toString());
        ctx.header('content-disposition', createContentDispositionHeader({
          filename,
          type: 'attachment',
        }));
        ctx.header('x-content-type-options', 'nosniff');

        return new Response(fileStream, {
          headers: ctx.res.headers,
          status: HTTP.ResultCodes.RS_2.Ok,
        });
      },
    });
  }
}