Carbon HTTP (v3.0.1)

Carbon HTTP is a zero-dependency, ultrasonic HTTP(S) client engineered specifically for enterprise Node.js microservices and financial infrastructure. Built with TypeScript targeting ES2022, it leverages native Node.js core modules (node:http, node:https, node:url, node:zlib) to deliver bulletproof resilience, low latency, and zero supply-chain risk.

---

🛡️ Key Enterprise Architectural Guarantees

Architectural Dimension	Carbon HTTP Implementation	Risk Mitigated
Memory Protection	Bounded streaming payload limit (maxBodyLength, default 10MB)	Prevents Out-of-Memory (OOM) process crashes from malicious/large responses
Timeout Model	Absolute wall-clock timer with active socket destruction	Eliminates Slowloris idle socket deadline evasion attacks
Connection Pooling	Native HTTP/HTTPS Keep-Alive agents (defaultHttpAgent, defaultHttpsAgent)	Eliminates TCP/TLS handshake round-trip latency overhead
Compression	Automatic Accept-Encoding: gzip, deflate, br with native zlib stream piping	Minimizes network bandwidth utilization by up to 85%
Observability & Errors	Standard ES2022 Error.cause taxonomy (CarbonHttpError hierarchy)	Enables APMs (Datadog, New Relic, Sentry) and loggers (Pino, Winston) to trace origin causes
Supply Chain Security	0 External Dependencies	Eliminates transitive dependency vulnerability vectors

---

🚀 Quickstart

Installation

# NPM
npm install carbon-http

# Yarn
yarn add carbon-http

# pnpm
pnpm add carbon-http

---

💡 API Reference & Examples

1. High-Throughput Service-to-Service Request (GET)

import {
  Request,
  CarbonHttpTimeoutError,
  CarbonHttpMaxBodyLengthError,
  CarbonHttpNetworkError,
} from 'carbon-http';

interface PaymentAccount {
  accountId: string;
  balance: number;
  currency: string;
}

async function fetchAccount(accountId: string): Promise<PaymentAccount> {
  try {
    const res = await Request(`https://api.hsbc.internal/v1/accounts/${accountId}`, {
      timeoutMs: 3000,                // 3s absolute wall-clock deadline
      maxBodyLength: 2 * 1024 * 1024, // 2MB max memory buffer threshold
      decompress: true,               // Transparent gzip/brotli decompression
    });

    // Safely parse JSON with explicit runtime validation callback
    return res.json((raw: unknown) => {
      const data = raw as PaymentAccount;
      if (!data.accountId || typeof data.balance !== 'number') {
        throw new Error('Invalid schema payload returned from upstream service');
      }
      return data;
    });
  } catch (err) {
    if (err instanceof CarbonHttpTimeoutError) {
      console.error(`[TIMEOUT] Request to ${err.url} exceeded ${err.timeoutMs}ms deadline`);
    } else if (err instanceof CarbonHttpMaxBodyLengthError) {
      console.error(`[OOM-GUARD] Payload exceeded ${err.maxBodyLength} bytes`);
    } else if (err instanceof CarbonHttpNetworkError) {
      console.error(`[NETWORK] Socket failure: ${err.cause.message}`);
    }
    throw err;
  }
}

2. Request Cancellation with AbortSignal (POST)

import { Request, HttpMethod, CarbonHttpAbortError } from 'carbon-http';

const controller = new AbortController();

// Cancel request if processing takes longer than expected externally
const timeoutId = setTimeout(() => controller.abort(), 2000);

try {
  const res = await Request('https://api.syniol.com/v2/transactions', {
    method: HttpMethod.POST,
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: 500.0,
      recipient: 'GB1234567890',
    }),
    signal: controller.signal,
  });

  clearTimeout(timeoutId);
  console.log(`Status: ${res.status}`);
} catch (err) {
  if (err instanceof CarbonHttpAbortError) {
    console.warn(`[ABORTED] Request to ${err.url} was cancelled via AbortSignal`);
  }
}

---

🚨 Error Taxonomy

All exceptions thrown by carbon-http extend CarbonHttpError and propagate standard Error.cause objects:

CarbonHttpError (Base Error Class)
 ├── CarbonHttpNetworkError     (DNS, TCP connection refused, socket drops)
 ├── CarbonHttpTimeoutError     (Absolute wall-clock deadline exceeded)
 ├── CarbonHttpAbortError       (Request cancelled via AbortSignal)
 ├── CarbonHttpJsonParseError   (JSON syntax error with HTTP status & 200-char body preview)
 └── CarbonHttpMaxBodyLengthError (Response payload exceeded maxBodyLength limit)

---

⚙️ Public Configuration & Types

CarbonHttpRequestOption

• headers?: Record<string, string> — Custom request header map.
• method?: HttpMethod — HTTP verb (HttpMethod.GET, HttpMethod.POST, etc.).
• body?: string | Uint8Array | Buffer — Payload content.
• port?: number — Override port.
• timeoutMs?: number — Absolute wall-clock timeout in milliseconds (default: 30,000ms).
• signal?: AbortSignal — Standard AbortSignal instance for cancellation.
• maxBodyLength?: number — Maximum response memory buffer threshold in bytes (default: 10MB).
• decompress?: boolean — Enable automatic Accept-Encoding and native zlib stream decompression (default: true).
• agent?: HttpAgent | HttpsAgent | boolean — Custom Node.js HTTP/HTTPS Agent or false to disable pooling.

CarbonHttpResponse

• status: number — Numerical HTTP status code.
• headers: HttpHeaders — Normalized response header object.
• incomingMessage: IncomingMessage — Raw Node.js stream reference.
• text(): string — Returns body as UTF-8 string.
• json<T>(parser?: (raw: unknown) => T): T — Parses response body as JSON with optional runtime parser callback.

---

📜 Governance & License

Copyright © 2022-2026 Syniol Limited.
Distributed under the BSD 3-Clause License.