hedge-fetch

Adaptive, speculative request hedging for the modern web. hedgehog-fetch is a high-performance wrapper around the Fetch API designed to eliminate "tail latency" (the slow P95/P99 requests). By intelligently firing a second "speculative" request when the first one takes too long, Hedgehog ensures your users never wait on a stray slow server.

Key Features

• Adaptive P95 Delay: No hardcoded timeouts. Hedgehog learns your network's latency and hedges exactly when a request is statistically "late."
• Idempotency Safety: Automatically handles Idempotency-Key headers for POST requests to prevent duplicate server-side actions.
• Zero Leakage: Uses modern AbortSignal.any() to ensure that once a winner is found, the loser is aborted immediately—no dangling connections.
• Plugin-Ready Buckets: Ship with a local token bucket, or plug in Redis to coordinate hedging budgets across a global cluster.
• Developer Visibility: Built-in hooks and response decoration (res.isHedged) for deep observability.

Installation

npm install hedge-fetch

Quick Start

import { HedgedContext, LocalTokenBucket, LatencyTracker } from 'hedge-fetch';

// 1. Initialize the context
const hedge = new HedgedContext(
  new LocalTokenBucket(10), // Allow 10% hedging overhead
  new LatencyTracker()      // Adaptive learning
);

// 2. Use it just like native fetch
const response = await hedge.fetch('https://api.example.com/data', {
  timeoutMs: 5000, // Global safety net
  onHedge: () => console.log('Hedging triggered!')
});

// 3. Check if the hedge saved the day
if ((response as any).isHedged) {
  console.log('Speculative request won!');
}

Deep Dive: How it Works

1. The Adaptive Delay (P95 Algorithm)

Instead of guessing a timeout (e.g., "wait 200ms"), Hedgehog uses the LatencyTracker. It maintains a sliding window of recent request durations and calculates the 95th percentile. If your primary request hasn't responded by the P95 mark, it is statistically likely to be a "tail latency" request, and Hedgehog fires the speculative request.

2. Idempotency & Safety

Hedging POST or PATCH requests is usually dangerous. Hedgehog makes it safe:

• Safe Methods: GET, HEAD, OPTIONS are hedged by default.
• Unsafe Methods: POST is only hedged if forceHedge: true is passed.
• Auto-Key: If enabled, Hedgehog generates a UUID and attaches it to the Idempotency-Key header, ensuring your backend doesn't process the same action twice.

3. Distributed Budgets (Redis)

To prevent your fleet of servers from DDOSing your own backend during a slowdown, Hedgehog uses a Token Bucket. You can implement the IHedgeBucket interface to sync this budget across multiple instances using Redis.

class RedisBucket implements IHedgeBucket {
  async canHedge() {
    const tokens = await redis.get('hedge_tokens');
    return parseInt(tokens) > 0;
  }
  // ...
}

Technical Reference

HedgeFetchOptions

Extends the standard RequestInit with:

| Option | Type | Description | | --- | --- | --- | | timeoutMs | number | The global safety net. Aborts everything if no response in X ms. | | forceHedge | boolean | Bypass safety checks for non-idempotent methods. | | onHedge | () => void | Callback when the speculative request is fired. | | onPrimaryWin | (ms) => void | Callback when the first request succeeds. | | onSpeculativeWin | (ms) => void | Callback when the second request succeeds. |

Response Decoration

Successful responses from a speculative request are decorated with a non-enumerable property:

const res = await hedge.fetch(...);
console.log(res.isHedged); // true if the speculative request won

Best Practices

1. Backend Support: Ensure your backend ignores duplicate Idempotency-Key headers for the best experience.
2. Budgeting: Start with a 5-10% budget (LocalTokenBucket) to improve latency without significantly increasing server cost.
3. Global Timeouts: Always set a timeoutMs to prevent "hanging" UI states in extreme network failure scenarios.

Contributing

Contributions are welcome! If you have ideas for new resilience patterns (like Rate Limiting or Timeouts), feel free to open an issue or a PR.

License

MIT © Ali nazari

Built with ❤️ for the Node.js community. Star this repo if it helped you sleep better at night! ⭐