Configuration

Volten applications are initialized and configured using the VoltenAppOptions object passed to the App constructor. This document details all available configuration options, their defaults, and best practices.

Basic Usage

import { App } from "volten";

const app = new App({
  bodyLimit: 2 * 1024 * 1024, // 2MB limit
  caseInsensitive: true,
  RequestPoolSize: 4096,
});

---

VoltenAppOptions Reference

export type VoltenAppOptions<CustomLevels extends string = never> = {
  bodyLimit?: number;
  caseInsensitive?: boolean;
  RequestPoolSize?: number;
  shutdownTimeoutMs?: number;
  https?: VoltenHttpsOptions | undefined;
  loggerOptions?: CustomLoggerOptions<CustomLevels>;
  adaptiveTriage?: AdaptiveTriageOptions;
};

Options Overview

VoltenAppOptions7 properties

Core options passed to new App(options)

Property	Type	Default	Description
	number	1048576 (1 MB)	Maximum request payload size in bytes before returning 413 Payload Too Large.
	boolean	true	Enables case-insensitive route matching in the radix router.
	number	2048	Number of pre-allocated internal storage slots in the memory pool to minimize GC pressure.
	number	10000 (10s)	Maximum time to wait for active requests to finish during a graceful shutdown (app.close).
	VoltenHttpsOptions | undefined	undefined	TLS/SSL certificate configuration for native Node.js HTTPS server.
	CustomLoggerOptions	{ level: 'warn' }	Configuration for the integrated high-performance structured JSON logger.
	AdaptiveTriageOptions	See details	Settings for real-time traffic shedding based on event-loop lag monitoring.

Typenumber

Default1048576 (1 MB)

Maximum request payload size in bytes before returning 413 Payload Too Large.

Typeboolean

Defaulttrue

Enables case-insensitive route matching in the radix router.

Typenumber

Default2048

Number of pre-allocated internal storage slots in the memory pool to minimize GC pressure.

Typenumber

Default10000 (10s)

Maximum time to wait for active requests to finish during a graceful shutdown (app.close).

TypeVoltenHttpsOptions | undefined

Defaultundefined

TLS/SSL certificate configuration for native Node.js HTTPS server.

TypeCustomLoggerOptions

Default{ level: 'warn' }

Configuration for the integrated high-performance structured JSON logger.

TypeAdaptiveTriageOptions

DefaultSee details

Settings for real-time traffic shedding based on event-loop lag monitoring.

---

Option Details

RequestPoolSize

• Type: number
• Default: 2048

Volten utilizes an advanced storage pooling architecture for request lifecycles. Heavy resources (pre-allocated 64KB response buffers and write queues) are held in pooled storage instances (NodeContextStorage and EdgeContextStorage), while each incoming request receives an isolated per-request handle with an immutable request token.

How It Works

1. Upon new App(), Volten manages an internal pool of storage instances bounded by RequestPoolSize.
2. When a request arrives, a storage slot is retrieved from the pool in $O(1)$ time, bound to a fresh per-request context with a unique token, and initialized with the active socket/request streams.
3. Once both the response closes and the handler chain settles, the context is invalidated, and the storage is reset and returned to the pool.

Pool Exhaustion

If concurrent requests exceed the pool size:

• Node.js: The server immediately responds with 503 Service Unavailable (Connection: close) to avoid unbounded memory allocation and process crashes.
• Edge / Fetch: A transient fallback context is created dynamically.

const app = new App({
  // Scale up for high-concurrency environments with adequate memory
  RequestPoolSize: 8192,
});

TIP

Tune RequestPoolSize according to your expected concurrent connections. For high-traffic production workloads with thousands of concurrent connections, setting RequestPoolSize: 4096 or 8192 ensures zero garbage collection overhead.

---

https

• Type: VoltenHttpsOptions | undefined
• Default: undefined

Configures the underlying Node.js server to run as a native https.Server with TLS encryption.

export type VoltenHttpsOptions = {
  /** The full private key as a string */
  key: string;
  /** The full certificate as a string */
  cert: string;
};

VoltenHttpsOptions2 properties

TLS/SSL certificate configuration for native Node.js HTTPS server

Property	Type	Default	Description
Required	string	-	The full private key string contents (e.g. read from privkey.pem).
Required	string	-	The full certificate chain string contents (e.g. read from fullchain.pem).

Required

Typestring

Default-

The full private key string contents (e.g. read from privkey.pem).

Required

Typestring

Default-

The full certificate chain string contents (e.g. read from fullchain.pem).

Example: HTTPS Server

import { App } from "volten";
import fs from "node:fs";

const app = new App({
  https: {
    key: fs.readFileSync("./certs/privkey.pem", "utf8"),
    cert: fs.readFileSync("./certs/fullchain.pem", "utf8"),
  },
});

app.get("/", (ctx) => {
  ctx.send("Serving securely over HTTPS!");
});

app.listen(8443, () => {
  console.log("HTTPS server listening on https://localhost:8443");
});

When https is provided, Volten delegates server creation to Node's https.createServer(...). If omitted, standard http.createServer(...) is used.

---

bodyLimit

• Type: number
• Default: 1048576 (1 MB in bytes)

Defines the maximum allowed byte size for incoming request bodies (e.g., JSON, URL-encoded, or raw buffers).

Fast Early Rejection

When an incoming request arrives, Volten performs an instant check on the Content-Length header before buffering any chunks into memory. If Content-Length exceeds bodyLimit, the request socket is paused and Volten terminates the request with 413 Payload Too Large.

For chunked transfer encoding (where Content-Length may not be present), the internal body parsers enforce this limit continuously while consuming the stream.

const app = new App({
  // Increase limit to 10MB for file uploads or large JSON payloads
  bodyLimit: 10 * 1024 * 1024,
});

NOTE

You can also override the body limit per individual route using route options:

app.post("/upload", { bodyLimit: 50 * 1024 * 1024 }, async (ctx) => {
  const body = await ctx.body();
  ctx.json({ received: true });
});

---

caseInsensitive

• Type: boolean
• Default: true

Controls whether URL path matching in the radix router is case-insensitive.

• When true: /Users/Profile and /users/profile resolve to the same handler.
• When false: Paths are treated with strict casing.

const app = new App({
  caseInsensitive: false, // Strict case sensitivity
});

---

loggerOptions

• Type: CustomLoggerOptions<CustomLevels>
• Default: { level: 'warn' }

Configures the built-in high-performance structured JSON logger. For detailed documentation on logger levels, serializers, mixins, and redaction, refer to the Logging API Reference.

const app = new App({
  loggerOptions: {
    level: "info",
    pretty: process.env.NODE_ENV !== "production",
    redact: ["password", "authorization"],
  },
});

---

adaptiveTriage

• Type: AdaptiveTriageOptions
• Default:

  {
    enabled: false,
    warningThresholdMs: 40,
    criticalThresholdMs: 100,
    resolutionMs: 10,
    checkIntervalMs: 500,
  }

AdaptiveTriageOptions5 properties

Event loop delay monitoring and automated traffic load shedding options

Property	Type	Default	Description
	boolean	false	Enables real-time event loop latency monitoring and automated traffic load shedding.
	number	40	Event loop delay in milliseconds triggering WARNING state (drops low priority requests).
	number	100	Event loop delay in milliseconds triggering CRITICAL state (drops low and normal priority requests).
	number	10	Resolution in milliseconds of event loop delay histogram samples recorded via perf_hooks.
	number	500	Interval in milliseconds between background health evaluation ticks.

Typeboolean

Defaultfalse

Enables real-time event loop latency monitoring and automated traffic load shedding.

Typenumber

Default40

Event loop delay in milliseconds triggering WARNING state (drops low priority requests).

Typenumber

Default100

Event loop delay in milliseconds triggering CRITICAL state (drops low and normal priority requests).

Typenumber

Default10

Resolution in milliseconds of event loop delay histogram samples recorded via perf_hooks.

Typenumber

Default500

Interval in milliseconds between background health evaluation ticks.

Configures Volten's automated event loop health monitor and intelligent load shedding. For an in-depth breakdown of load-shedding states and route priority tagging, see the Performance & Architecture Reference.

---

shutdownTimeoutMs

• Type: number
• Default: 10000 (10 seconds)

When you call app.close(), Volten stops accepting new incoming connections and waits for all active, in-flight requests in the pool to finish processing (graceful shutdown).

If the active requests do not finish within the shutdownTimeoutMs window, Volten will forcefully close all active connections and terminate the server to prevent the process from hanging indefinitely.

const app = new App({
  shutdownTimeoutMs: 5000, // Force close connections after 5 seconds
});

---

Default Configuration Object

Volten exposes the default configuration constant DefaultVoltenOptions:

import { DefaultVoltenOptions } from "volten";

console.log(DefaultVoltenOptions);
/*
{
  bodyLimit: 1048576,
  caseInsensitive: true,
  RequestPoolSize: 2048,
  shutdownTimeoutMs: 10000,
  https: undefined,
  loggerOptions: {
    level: "warn"
  },
  adaptiveTriage: {
    enabled: false,
    warningThresholdMs: 40,
    criticalThresholdMs: 100,
    resolutionMs: 10,
    checkIntervalMs: 500
  }
}
*/