Solvix

Enterprise-Grade HTTP Orchestration Engine for Modern JavaScript

Resilience • Security • Observability • Control

---

Solvix is an HTTP orchestration engine — not just a client. It transforms simple API requests into secure, observable, resilient, and fully controlled execution pipelines.

Unlike traditional HTTP clients (Axios, Got, SuperAgent) that leave resilience, security, and observability to the developer, Solvix bakes ~50 features into a single 33 KB package.

---

Why Solvix?

Feature	Solvix	Axios	Got
Security (CRLF protection, size guards, method allowlisting, HTTPS enforcement, header sanitization)	12 features	Cookie/XSS only	Basic
Circuit Breaker	Built-in
Rate Limiter (token bucket + adaptive from headers)	Built-in
Request Deduplication	Built-in
Priority Queue with concurrency control	Built-in
SSE / JSON Lines streaming	Built-in
W3C Distributed Tracing	Built-in
Health Checks	Built-in
Correlation IDs	Built-in
Structured Logging	Built-in
Metrics (counters + histograms)	Built-in
Request Timeline & Profiling	Built-in
Snapshot Debugging	Built-in
Shadow Mode (dual API testing)	Built-in
Offline Queue	Built-in
Token Refresh (stampede-safe)	Built-in
CSRF Protection	Built-in
Cookie Jar	Built-in
ETag / Conditional Requests	Built-in
Fallback URLs	Built-in
Upload/Download Progress	Built-in
Custom Middleware	client.use()	Interceptors
SSL/TLS Customization	(via undici)
HTTP Proxy	(via undici)
Bundle Size	33 KB	~52 KB	~42 KB

---

Quick Start

npm install @adityadev13/solvix

import { createClient } from "@adityadev13/solvix";

const api = createClient({ baseURL: "https://api.example.com" });

const res = await api.get("/users");
console.log(res.data);        // parsed JSON
console.log(res.status);      // 200
console.log(res.meta);        // timing, timeline, profiling

---

Core Features

Security

const api = createClient({
  security: {
    enforceHTTPS: true,
    allowedDomains: ["api.example.com"],
    allowedMethods: ["GET", "POST"],
    maxBodySize: 1_000_000,
    maxResponseSize: 10_000_000,
  },
  csrf: { enabled: true },               // Auto-inject CSRF token from cookie
  tls: { rejectUnauthorized: false },     // Self-signed certs (Node.js)
  proxy: { host: "gateway.corp.com", port: 8080 }, // Corporate proxy
});

• CRLF injection protection (always on)
• Forbidden header stripping (Host, Connection, Content-Length)
• Insecure header stripping (Authorization, Cookie, X-Api-Key)
• Snapshot redaction (passwords masked in debug output)
• Domain whitelisting, method allowlisting, size guards

Resilience

const api = createClient({
  retry: { retries: 3, factor: 2, jitter: true },
  circuitBreaker: { failureThreshold: 5, rollingWindow: 10000 },
  rateLimit: { capacity: 10, refillRate: 5, interval: 1000 },
  dedupe: true,                           // 1000 identical calls → 1 network request
  fallbackURLs: ["https://backup.example.com"],
  maxConcurrency: 50,
});

• Retry with exponential backoff, jitter, and adaptive timing
• Circuit breaker per-host with half-open probes
• Token bucket rate limiter with server-side header sync
• Priority queue with concurrency control and drop strategies
• Automatic deduplication via SHA-256 fingerprinting

Observability

const api = createClient({
  timeline: { enabled: true },
  profiling: { enabled: true },
  correlation: { enabled: true },
  tracing: { enabled: true },
  logger: console,
  metrics: { enabled: true },
  healthCheck: { enabled: true, endpoint: "/health" },
});

// Events — subscribe globally
import { SolvixBus } from "@adityadev13/solvix";
SolvixBus.on("request:complete", (e) => {
  console.log(`${e.context.url} → ${e.context.response?.status}`);
});

// Metrics — aggregate counters
const m = api.metrics();
console.log(m.totalRequests, m.successCount, m.failureCount, m.durationHistogram);

// Health — check backend status
console.log(api.healthCheck?.isHealthy());

• 15-stage request timeline with microsecond precision
• Profile metrics: queue wait, rate limit wait, network, parse, total time
• W3C traceparent header for distributed tracing
• Correlation IDs (X-Request-ID) in every log line
• Duration histogram with configurable buckets
• Periodic health endpoint pinging with status change callbacks

Data Handling

// Streaming (SSE / JSON Lines)
for await (const event of api.get("/events", { sse: true })) {
  console.log(event.data);
}

// Upload progress
const api = createClient({
  hooks: {
    onUploadProgress: ({ loaded, total }) => console.log(`${loaded}/${total}`),
    onDownloadProgress: ({ percent }) => updateProgressBar(percent ?? 0),
  },
});

// Custom response validation
const api = createClient({
  validateResponse: (data) => {
    if (!data.id) throw new Error("Missing id");
    return data as MyType;
  },
});

// Custom params format
const api = createClient({
  paramsSerializer: (params) =>
    `https://api.example.com/search?${Object.entries(params).map(([k, v]) => `${k}[]=${v}`).join("&")}`,
});

• Body types: json, form, multipart, text, blob, arrayBuffer, raw
• Response types: json, text, blob, arrayBuffer, formData, stream, raw
• Transform pipeline: transformRequest → buildRequestBody → transport → parseResponse → transformResponse → validateResponse
• SSE parsing, JSON Lines (NDJSON), raw stream iteration
• Upload/download progress via ReadableStream counting

Middleware

const api = createClient({ baseURL: "https://api.example.com" });

api.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  console.log(`${ctx.url} took ${Date.now() - start}ms`);
});

Custom middleware runs in the request pipeline before the transport layer. Compose multiple middleware in order (onion model).

---

Architecture

Every request flows through a controlled pipeline:

Security Checks → Query Params → Fingerprinting → Dedup/Cache Check
→ Dependency Wait → Priority Queue → Rate Limiter → Circuit Breaker
→ Retry Loop (sanitize → build body → middleware stack → parse)
→ Validation → Caching → Events → Logging → Response

All stages are opt-in. Nothing runs unless configured.

---

Documentation

For full documentation, API reference, and advanced guides:

• Detailed Docs — solvix-client.github.io/solvix-docs
• API Reference — Full JSDoc available in-editor via TypeScript declarations
• Benchmarks — Run npm run bench:all locally to see performance on your hardware

---

Supported Runtimes

• Node.js 18+
• Modern browsers (Chrome, Firefox, Safari, Edge)
• Deno, Bun
• Edge runtimes (Cloudflare Workers, Vercel Edge)

---

Installation

npm install @adityadev13/solvix
pnpm add @adityadev13/solvix
yarn add @adityadev13/solvix
bun add @adityadev13/solvix

---

License

MIT

---

Contributing

We welcome feature proposals, bug reports, security reviews, and performance improvements.

Solvix transforms API communication into a reliable, observable, secure, and orchestrated execution system. It is not just a client — it is infrastructure.