Probing a Half-Open Circuit Breaker Before Restoring Full VIN Decode Traffic

Latency-aware circuit breakers (covered elsewhere) trip when NHTSA DecodeVinValues stays slow or hard-fails, then fail fast while open. The quiet next risk is how you leave open: flooding upstream when cooldown ends, or flipping straight to closed on the first lucky 200. This post is about the half-open probe phase -- admit a tiny number of trial decodes, score them strictly, and only then restore full VIN decode traffic. Initial open/trip behavior is covered elsewhere; here the focus is probing before you trust the circuit again.

Why half-open is not "open but friendlier"

Without a probe cap, cooldown expiry turns waiting forms into a thundering herd. Without strict scoring, one lucky 200 or one soft timeout can close the breaker while the next submits hang again.

Probe rules that stay honest

Define half-open explicitly:

1. After cooldownMs, transition open → half_open and reset the probe counter.
2. Allow at most halfOpenMaxProbes in-flight (start with 1).
3. Extra submits while probing see circuit_half_open (or reuse circuit_open with a distinct UX string) -- not a second upstream call.
4. A probe that finishes inside budget and returns a typed success → recordProbeSuccess → closed.
5. A probe that times out, 5xxs, or network-fails → recordProbeFailure → open again with a fresh cooldown.

Do not count local validation rejects as probe failures. Do not treat a sparse-but-honest 200 (empty ABS, missing optional fields) as failure -- that is still upstream success for breaker purposes. Do not auto-close because "enough time passed" without a successful probe.

TypeScript sketch: half-open probe gate

type BreakerState = "closed" | "open" | "half_open";

export type HalfOpenConfig = {
  cooldownMs: number; // e.g. 20_000
  halfOpenMaxProbes: number; // e.g. 1
  slowThresholdMs: number; // e.g. 7000
};

export class HalfOpenProbeBreaker {
  private state: BreakerState = "closed";
  private openedAt = 0;
  private halfOpenInFlight = 0;

  constructor(private readonly cfg: HalfOpenConfig) {}

  /** Call before starting any DecodeVinValues work. */
  tryAdmit(): "allow" | "reject_open" | "reject_probe_cap" {
    if (this.state === "closed") return "allow";
    if (this.state === "open") {
      if (Date.now() - this.openedAt < this.cfg.cooldownMs) {
        return "reject_open";
      }
      this.state = "half_open";
      this.halfOpenInFlight = 0;
    }
    if (this.halfOpenInFlight >= this.cfg.halfOpenMaxProbes) {
      return "reject_probe_cap";
    }
    this.halfOpenInFlight += 1;
    return "allow";
  }

  recordProbeSuccess(): void {
    this.state = "closed";
    this.halfOpenInFlight = 0;
  }

  recordProbeFailure(): void {
    this.state = "open";
    this.openedAt = Date.now();
    this.halfOpenInFlight = 0;
  }

  /** Closed-path success/failure helpers omitted -- see open-trip article. */
  tripOpen(): void {
    this.state = "open";
    this.openedAt = Date.now();
    this.halfOpenInFlight = 0;
  }
}

export type ProbeResult<T> =
  | { ok: true; data: T }
  | {
      ok: false;
      reason: "circuit_open" | "probe_cap" | "upstream_slow" | "upstream";
    };

export async function decodeWithHalfOpenProbe<T>(
  breaker: HalfOpenProbeBreaker,
  call: (signal: AbortSignal) => Promise<T>,
  cfg: { slowThresholdMs: number },
): Promise<ProbeResult<T>> {
  const admit = breaker.tryAdmit();
  if (admit === "reject_open") {
    return { ok: false, reason: "circuit_open" };
  }
  if (admit === "reject_probe_cap") {
    return { ok: false, reason: "probe_cap" };
  }

  const controller = new AbortController();
  const timer = setTimeout(
    () => controller.abort(),
    cfg.slowThresholdMs,
  );
  const started = Date.now();
  try {
    const data = await call(controller.signal);
    clearTimeout(timer);
    breaker.recordProbeSuccess();
    return { ok: true, data };
  } catch {
    clearTimeout(timer);
    breaker.recordProbeFailure();
    const timedOut =
      controller.signal.aborted &&
      Date.now() - started >= cfg.slowThresholdMs - 50;
    return {
      ok: false,
      reason: timedOut ? "upstream_slow" : "upstream",
    };
  }
}

Gate every submit on tryAdmit() before spinners. When probe_cap rejects, keep the form interactive and say recovery is being tested -- do not queue silent retries that would become a second probe.

What a probe must not do

A half-open probe is still a real DecodeVinValues call with the same per-call budget. Do not lengthen timeouts "just this once" to force a success -- that hides slowness and closes the breaker on a lie. Do not skip VIN normalization, and do not fan out hedges: one probe means one upstream attempt until you reopen or re-trip. Prefer admitting an interactive candidate before batch when both wait for the probe slot.

UX for the probe window

Prefer:

• "Decode recovering -- testing upstream; try again shortly" for probe_cap
• One visible probe spinner, not N stacked loads
• Optional labeled last-good cache while half-open rejects extras

Avoid:

• Mapping probe_cap to "invalid VIN"
• Opening all waiting forms the instant cooldown ends
• Closing the breaker on wall-clock alone without a successful probe
• Letting batch consume the only probe slot ahead of interactive users

Quick checks

import assert from "node:assert/strict";

const b = new HalfOpenProbeBreaker({
  cooldownMs: 1_000,
  halfOpenMaxProbes: 1,
  slowThresholdMs: 7_000,
});

b.tripOpen();
assert.equal(b.tryAdmit(), "reject_open");

// Simulate cooldown elapsed by tripping then forcing time via reopen path:
(b as unknown as { openedAt: number }).openedAt = Date.now() - 2_000;
assert.equal(b.tryAdmit(), "allow");
assert.equal(b.tryAdmit(), "reject_probe_cap");

b.recordProbeSuccess();
assert.equal(b.tryAdmit(), "allow");

b.tripOpen();
(b as unknown as { openedAt: number }).openedAt = Date.now() - 2_000;
assert.equal(b.tryAdmit(), "allow");
b.recordProbeFailure();
assert.equal(b.tryAdmit(), "reject_open");

Review rule: half-open modules must cap probes, distinguish reject reasons, and refuse to restore full traffic without a scored success.

Takeaway

Half-open is a probe phase, not a soft open. Admit a tiny trial budget after cooldown, score timeouts and hard failures strictly, reject excess submits with a clear recovery message, and only then restore full traffic. Keep this separate from the initial trip/open design. Your free decode proxy stays kind to NHTSA when recovery is earned by probes -- not by hope and a herd.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.