Outbound Request Hygiene

import { Agent, fetch as undiciFetch } from 'undici';

// A single place where the bounds are set, so no call can be created without them.
const agent = new Agent({
  connect: { timeout: 3000 },        // TCP + TLS handshake
  bodyTimeout: 10_000,               // time between body chunks
  headersTimeout: 5000,
  keepAliveTimeout: 4000,
  connections: 50,                   // bound the pool per origin
});

const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;

export async function httpJson(url, {
  method = 'GET', body, headers = {}, timeoutMs = 10_000, schema,
} = {}) {
  const started = Date.now();
  let res;

  try {
    res = await undiciFetch(url, {
      method,
      headers: { Accept: 'application/json', ...headers },
      body: body ? JSON.stringify(body) : undefined,
      dispatcher: agent,
      signal: AbortSignal.timeout(timeoutMs),
      redirect: 'error',              // never follow a redirect blindly
    });
  } catch (err) {
    metrics.increment('outbound.error', { host: new URL(url).host,
      reason: err.name === 'TimeoutError' ? 'timeout' : 'network' });
    throw new UpstreamError('upstream_unavailable', { cause: err });
  } finally {
    metrics.histogram('outbound.duration_ms', Date.now() - started,
      { host: new URL(url).host });
  }

  if (!res.ok) throw new UpstreamError(`upstream_status_${res.status}`);

  // Bound the body as it streams — Content-Length is a claim, not a fact.
  const chunks = [];
  let total = 0;
  for await (const chunk of res.body) {
    total += chunk.length;
    if (total > MAX_RESPONSE_BYTES) throw new UpstreamError('response_too_large');
    chunks.push(chunk);
  }

  const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));

  // Validate as strictly as you would validate a browser request.
  return schema ? schema.parse(parsed) : parsed;
}

// ⚠️ Never do this, in any environment:
//   new Agent({ connect: { rejectUnauthorized: false } })
//   process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'
// It disables certificate validation entirely, and it always ships.

// Retrying a failing dependency without a budget turns their partial outage
// into a full one, for both of you.

class CircuitBreaker {
  #state = 'closed';          // closed → open → half-open → closed
  #failures = 0;
  #openedAt = 0;

  constructor({ threshold = 5, resetMs = 30_000, name }) {
    Object.assign(this, { threshold, resetMs, name });
  }

  async call(fn) {
    if (this.#state === 'open') {
      if (Date.now() - this.#openedAt < this.resetMs) {
        metrics.increment('circuit.rejected', { name: this.name });
        throw new UpstreamError('circuit_open');    // fail FAST, do not queue
      }
      this.#state = 'half-open';                    // allow one probe through
    }

    try {
      const result = await fn();
      this.#failures = 0;
      this.#state = 'closed';
      return result;
    } catch (err) {
      this.#failures++;
      if (this.#state === 'half-open' || this.#failures >= this.threshold) {
        this.#state = 'open';
        this.#openedAt = Date.now();
        logger.error({ name: this.name }, 'circuit opened');
        metrics.increment('circuit.opened', { name: this.name });
      }
      throw err;
    }
  }
}

const paymentsBreaker = new CircuitBreaker({ name: 'payments', threshold: 5 });

// Retries: bounded, jittered, and ONLY for idempotent operations.
async function withRetry(fn, { attempts = 3, baseMs = 200 } = {}) {
  let lastError;
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn();
    } catch (err) {
      lastError = err;
      // Never retry a 4xx — the request is wrong, and repeating it will not help.
      if (err.status >= 400 && err.status < 500 && err.status !== 429) throw err;
      if (i === attempts - 1) break;

      const delay = baseMs * 2 ** i + Math.random() * baseMs;   // jitter
      await sleep(delay);
    }
  }
  throw lastError;
}

export const chargeCard = (payload) =>
  paymentsBreaker.call(() => withRetry(() =>
    httpJson('https://payments.example.com/charges', {
      method: 'POST',
      body: payload,
      // Idempotency key: retrying must not charge twice.
      headers: { 'Idempotency-Key': payload.orderId },
      schema: chargeResponseSchema,
    })));

// Not every dependency failure has the same correct answer. Decide per call,
// in advance, and write down why.

// ── FAIL CLOSED: a security decision ─────────────────────────────────
async function checkFraud(order) {
  try {
    return await fraudService.assess(order, { timeoutMs: 2000 });
  } catch (err) {
    // ❌ return { risk: 'low' };
    //    "The fraud service was down so we approved everything" is a decision
    //    an attacker can trigger by degrading the fraud service.
    metrics.increment('fraud.unavailable');
    throw new ServiceUnavailableError('Cannot process orders right now.');
  }
}

// ── FAIL CLOSED: authorization ───────────────────────────────────────
async function canAccess(user, resource) {
  try {
    return await policyService.check({ user, resource }, { timeoutMs: 1000 });
  } catch {
    return false;                     // deny, always
  }
}

// ── FAIL OPEN: an enrichment that is not a control ───────────────────
async function enrichWithCompanyData(email) {
  try {
    return await clearbit.lookup(email, { timeoutMs: 1500 });
  } catch {
    return null;                      // nice to have; not a gate
  }
}

// ── DEGRADE: a control with a safe conservative fallback ─────────────
async function checkRateLimit(key) {
  try {
    return await redisLimiter.consume(key);
  } catch {
    // Not open, not closed — a conservative local limit.
    metrics.increment('ratelimit.degraded');
    return localLimiter.consume(key, { limit: 10 });
  }
}

// Write the table into the code review checklist:
//
//   Dependency        On failure     Why
//   ───────────────────────────────────────────────────────────────────
//   fraud check       CLOSED (503)   bypassable control
//   authorization     CLOSED (deny)  bypassable control
//   rate limiter      DEGRADE        control, but availability matters
//   feature flags     last known     not a security control
//   enrichment        OPEN (null)    cosmetic
//   payments          CLOSED (503)   never assume success
//
// The failure mode is a design decision. Leaving it to a try/catch written
// during an incident is how bypasses get introduced.