DEV Community: Vin Lookup

Gracefully Degrading Secondary VIN Enrichment When NHTSA Latency Spikes

Vin Lookup — Thu, 08 Oct 2026 09:15:29 +0000

A free VIN decode card often layers a critical DecodeVinValues body with secondary enrichers -- recall snippets, stolen-check stubs, photo hints, or analytics side calls. When NHTSA latency spikes, waiting for every enricher makes the whole card feel broken. Load shedding (covered elsewhere) rejects or drops work at the edge to protect capacity. Circuit breakers (elsewhere) open on failure rates. Concurrency limits and retry budgets (elsewhere) bound sockets and attempts. This post is different: graceful degradation -- still return the core vPIC decode on time, mark secondary enrichers as skipped/degraded with honest UI labels, and never invent enrichment rows to keep the card looking "complete."

The goal is narrow: under a latency deadline, finish primary decode first; cancel or skip non-critical enrichers; show partial results with clear provenance; refuse fake filler specs.

Graceful degrade vs load-shed, circuits, concurrency, retry budget

Load shed -- refuse or drop requests when the edge is overloaded
Circuit breaker -- stop calling an unhealthy dependency globally for a cool-down
Concurrency / retry budget -- cap in-flight calls and per-VIN attempts
Graceful degrade -- keep serving the critical decode path; secondary enrichers become optional under a remaining-time budget

Degrade is about partial success for one request. Shed is about protecting the fleet. You can degrade without shedding, and shed without offering a partial card.

Priority tiers and a remaining-time budget

Assign each step a priority. Primary DecodeVinValues is required. Secondary enrichers run only while remaining deadline allows. On skip, record reason -- never fabricate their fields.

export type EnricherId =
  | "vpic-primary"
  | "recall-snippet"
  | "photo-hint"
  | "analytics-ping";

export type EnricherResult =
  | { id: EnricherId; status: "ok"; data: Record<string, string> }
  | { id: EnricherId; status: "skipped"; reason: "deadline" | "dependency" }
  | { id: EnricherId; status: "error"; message: string };

export type Deadline = { startMs: number; budgetMs: number };

export function remainingMs(d: Deadline, now = Date.now()): number {
  return d.budgetMs - (now - d.startMs);
}

export type Enricher = {
  id: EnricherId;
  critical: boolean;
  minMs: number; // bail if remaining below this
  run: (vin: string, signal: AbortSignal) => Promise<Record<string, string>>;
};

export async function runWithGracefulDegrade(
  vin: string,
  enrichers: Enricher[],
  deadline: Deadline,
): Promise<EnricherResult[]> {
  const out: EnricherResult[] = [];
  for (const e of enrichers) {
    const left = remainingMs(deadline);
    if (!e.critical && left < e.minMs) {
      out.push({ id: e.id, status: "skipped", reason: "deadline" });
      continue;
    }
    const ac = new AbortController();
    const timer = setTimeout(
      () => ac.abort(),
      Math.max(0, e.critical ? left : Math.min(left, e.minMs * 2)),
    );
    try {
      const data = await e.run(vin, ac.signal);
      out.push({ id: e.id, status: "ok", data });
    } catch (err) {
      if (e.critical) {
        out.push({
          id: e.id,
          status: "error",
          message: err instanceof Error ? err.message : "primary failed",
        });
        break;
      }
      out.push({ id: e.id, status: "skipped", reason: "deadline" });
    } finally {
      clearTimeout(timer);
    }
  }
  return out;
}

export type CardRow = { label: string; value: string };

export function cardFromResults(results: EnricherResult[]): CardRow[] {
  const rows: CardRow[] = [];
  for (const r of results) {
    if (r.status === "ok") {
      for (const [k, v] of Object.entries(r.data)) {
        rows.push({ label: k, value: v });
      }
      continue;
    }
    if (r.id === "vpic-primary" && r.status !== "ok") {
      rows.push({ label: "Decode", value: "primary decode unavailable" });
      continue;
    }
    // Secondary: honest skip -- never invent enrichment values
    rows.push({
      label: r.id,
      value:
        r.status === "skipped"
          ? `skipped (${r.reason}) -- not provided this request`
          : `error -- not provided this request`,
    });
  }
  return rows;
}

Primary failure fails the request (or returns a clear error). Secondary skips leave the core Make/Model/Year rows intact when primary succeeded.

UI honesty under degrade

Prefer:

Core vPIC rows from a successful primary
"Recall snippet: skipped (deadline) -- not provided this request"
A banner: "Partial decode -- secondary enrichment deferred"

Avoid:

Grey fake recall counts or "no recalls" invented on skip
Hiding that photo-hint never ran
Relabeling a degraded card as "full enrichment complete"

Forbidden upgrades

Inventing secondary enrichment fields when skipped for deadline
Blocking the whole card on non-critical enrichers after primary succeeded
Treating graceful degrade as a license to ignore concurrency / retry budgets
Opening the circuit solely because one enricher skipped (different tool)
Shedding healthy primary decodes when you only needed to skip analytics

Refuse those. Partial + labeled beats complete + fake.

Quick checks

import assert from "node:assert/strict";

const enrichers: Enricher[] = [
  {
    id: "vpic-primary",
    critical: true,
    minMs: 50,
    run: async () => ({ Make: "HONDA", Model: "Accord" }),
  },
  {
    id: "recall-snippet",
    critical: false,
    minMs: 80,
    run: async (_v, signal) => {
      await new Promise((r, j) => {
        const t = setTimeout(r, 200);
        signal.addEventListener("abort", () => {
          clearTimeout(t);
          j(new Error("aborted"));
        });
      });
      return { recalls: "0" };
    },
  },
];

const results = await runWithGracefulDegrade("1HGCM82633A004352", enrichers, {
  startMs: Date.now(),
  budgetMs: 100,
});
assert.ok(results.some((r) => r.id === "vpic-primary" && r.status === "ok"));
assert.ok(
  results.some(
    (r) => r.id === "recall-snippet" && r.status === "skipped",
  ),
);
const rows = cardFromResults(results);
assert.ok(rows.some((r) => r.label === "Make" && r.value === "HONDA"));
assert.ok(
  rows.some((r) => /skipped|not provided this request/i.test(r.value)),
);
assert.ok(!rows.some((r) => r.label === "recalls" && r.value === "0"));

Review rule: degrade modules must preserve primary success and must not invent secondary fields on skip.

Takeaway

Graceful degradation keeps the critical DecodeVinValues path on time when NHTSA latency spikes, while secondary enrichers skip under a remaining-time budget with honest labels. Pair it with load shedding, circuits, concurrency limits, and retry budgets -- each owns a different pressure valve. Your free VIN card stays trustworthy when partial results are labeled partial -- never padded with invented enrichment marketing.

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

Propagating Deadlines from VIN Form Submit to NHTSA Proxy Without Orphaned Work

Vin Lookup — Thu, 08 Oct 2026 08:56:30 +0000

A free VIN form that abandons a slow decode still often leaves a DecodeVinValues call running behind the proxy. The user navigated away, a client timeout fired, or a newer submit superseded the old one -- yet the edge kept waiting on NHTSA and burned quota on a response nobody will display. Per-request budgets (covered elsewhere) decide how long a serverless handler may wait. This post is about propagating that deadline as an AbortSignal from form submit through your BFF so orphaned upstream work is cancelled early.

The goal is narrow: one submit, one deadline, one cancellable fetch chain. Do not confuse this with hedged dual-fire, idempotency keys, or jittered retries. Here the job is: when the UI no longer wants the result, stop waiting on the proxy path that would call NHTSA.

Where orphaned work comes from

Orphans appear when deadlines live only at one layer:

Browser AbortController aborts the BFF fetch, but the BFF ignores req.signal and keeps calling DecodeVinValues
BFF has a hard setTimeout that returns 504 to the client while the outbound NHTSA promise is still pending
A second form submit starts a new decode without aborting the first in-flight attempt
Serverless budgets shrink remaining time, but nobody wires that remaining budget into fetch(..., { signal })

Each case spends free-quota units on work the card will never show. Propagation means the same abort reason travels from submit handler to outbound proxy call.

Mint a deadline at submit, pass the signal

Create the controller when the user submits (or when the form auto-decodes once). Attach a wall-clock deadline, pass signal to your BFF, and abort on unmount, navigation, or superseding submit.

export type DecodeSubmitOpts = {
  vin: string;
  deadlineMs: number; // e.g. 8_000 from UX budget
  fetchProxy: (vin: string, signal: AbortSignal) => Promise<unknown>;
};

export function submitDecodeWithDeadline(
  opts: DecodeSubmitOpts,
): { promise: Promise<unknown>; abort: (reason?: unknown) => void } {
  const ctrl = new AbortController();
  const timer = setTimeout(() => {
    ctrl.abort(new Error("CLIENT_DEADLINE"));
  }, opts.deadlineMs);

  const promise = opts
    .fetchProxy(opts.vin, ctrl.signal)
    .finally(() => clearTimeout(timer));

  return {
    promise,
    abort: (reason) => ctrl.abort(reason ?? new Error("CLIENT_CANCEL")),
  };
}

export function supersedePrevious(
  previous: { abort: (reason?: unknown) => void } | null,
): void {
  previous?.abort(new Error("SUPERSEDED"));
}

On a second tap, abort the previous handle before minting a new one. Do not let two proxy calls race "for completeness" when only the latest submit should paint the card.

Proxy: forward the inbound signal to NHTSA

Your BFF must treat the inbound request signal as authoritative. Compose it with any remaining serverless budget so either expiry aborts the outbound DecodeVinValues fetch.

export function mergeAbortSignals(
  ...signals: AbortSignal[]
): AbortSignal {
  const ctrl = new AbortController();
  for (const s of signals) {
    if (s.aborted) {
      ctrl.abort(s.reason);
      return ctrl.signal;
    }
    s.addEventListener(
      "abort",
      () => ctrl.abort(s.reason),
      { once: true },
    );
  }
  return ctrl.signal;
}

export async function proxyDecodeVin(args: {
  vin: string;
  inbound: AbortSignal;
  budgetSignal: AbortSignal;
  decodeVinValues: (vin: string, signal: AbortSignal) => Promise<unknown>;
}): Promise<unknown> {
  const signal = mergeAbortSignals(args.inbound, args.budgetSignal);
  if (signal.aborted) {
    throw signal.reason ?? new Error("ABORTED_BEFORE_UPSTREAM");
  }
  return args.decodeVinValues(args.vin, signal);
}

If the client already aborted, do not open a new upstream socket "to populate cache anyway." Cache warming is a separate, explicitly scheduled job -- not a side effect of a cancelled user decode.

Budgets and propagation compose: the serverless remaining-time check decides whether a retry is allowed; the AbortSignal decides whether work already in flight should stop. Propagating a deadline without aborting outbound fetch only returns early to the browser while NHTSA keeps running -- the orphan problem this post targets.

Forbidden upgrades

Product pressure often asks for:

Ignoring client aborts so the proxy "finishes for analytics"
Returning a synthetic 200 after abort by merging a partial body
Letting superseded submits complete in the background without metrics
Treating deadline abort as a retry trigger (that belongs in backoff modules)
Counting only displayed responses against quota while aborted upstreams stay invisible

Refuse those. Log decode_aborted_client, decode_aborted_budget, and decode_superseded. Count issued DecodeVinValues calls, including ones cancelled after the request left your edge.

Ops copy that stays honest

Prefer:

Metrics that separate user cancel, deadline, and supersede
Proxy logs that record whether outbound fetch received an AbortSignal
A kill switch that fails closed (reject new submits) when abort rate spikes with dual open upstreams

Avoid:

Silent background completion after the UI showed a timeout
Alerting only on HTTP 5xx while orphans inflate NHTSA traffic
Documenting "we always finish the decode" as a reliability feature when the card is gone

Quick checks

import assert from "node:assert/strict";

const calls: string[] = [];
const { promise, abort } = submitDecodeWithDeadline({
  vin: "1HGCM82633A004352",
  deadlineMs: 50,
  fetchProxy: async (_vin, signal) => {
    calls.push("start");
    await new Promise<void>((resolve, reject) => {
      const t = setTimeout(() => resolve(), 500);
      signal.addEventListener("abort", () => {
        clearTimeout(t);
        reject(signal.reason);
      });
    });
    calls.push("done");
    return {};
  },
});

await assert.rejects(promise);
assert.ok(!calls.includes("done"));

const inbound = AbortSignal.abort(new Error("CLIENT_CANCEL"));
await assert.rejects(
  proxyDecodeVin({
    vin: "1HGCM82633A004352",
    inbound,
    budgetSignal: new AbortController().signal,
    decodeVinValues: async () => {
      calls.push("upstream");
      return {};
    },
  }),
);
assert.ok(!calls.includes("upstream"));

Review rule: proxy decode modules must pass a merged AbortSignal into outbound NHTSA fetch and must not start upstream work when the inbound signal is already aborted.

Takeaway

Deadline propagation turns a form-level cancel into a cancellable NHTSA proxy call. Without it, client timeouts and superseded submits leave orphaned DecodeVinValues work that burns free quota for a card nobody will see. Mint the AbortController at submit, forward the signal through the BFF, merge it with any serverless budget, and refuse background "finish anyway" completions. Keep this path separate from hedges and idempotency keys so abandoned VIN lookups stop spending upstream time as soon as the UI stops caring.

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

Bulkheading VIN Decode Workers So One Bad VIN Path Cannot Starve the Pool

Vin Lookup — Thu, 08 Oct 2026 08:38:55 +0000

A free VIN decode proxy often shares one worker pool across every DecodeVinValues call. One pathological path -- a hung upstream, a retry storm on a bad VIN, or a client that floods the same edge -- can exhaust concurrency and leave healthy submissions waiting behind the pile-up. Per-request deadlines and hedged fetches (covered elsewhere) limit how long a single attempt lives. This post is about bulkheading: partitioning concurrency so one bad VIN path cannot starve the rest of the pool.

The goal is narrow: isolate in-flight decode slots by tenant, route, or failure class so a saturated bulkhead rejects or queues locally instead of consuming every shared worker. Do not confuse this with circuit breakers that open on error rates, idempotency keys, or jittered retries. Here the job is: cap how many concurrent NHTSA-bound calls one noisy path may hold.

Where pool starvation comes from

Starvation appears when every decode shares one unbounded (or globally capped) queue:

A single API key or browser session opens dozens of parallel DecodeVinValues calls
A stuck upstream keeps workers occupied until client timeouts pile retries on top
Batch import and interactive form traffic share the same pool with no separate ceilings
A "bad VIN" hot path retries forever while interactive users wait for free slots

Each case turns free-quota and worker time into a tragedy of the commons. Bulkheads give each path its own concurrency budget so exhaustion stays local.

Cap concurrency per bulkhead key

Assign each decode a bulkhead key (tenant id, route name, or interactive vs batch). Acquire a slot before calling the proxy; release it in finally. When the bulkhead is full, fail fast or queue with a short local timeout -- do not steal slots from other keys.

export type Bulkhead = {
  key: string;
  limit: number;
  inFlight: number;
  waiters: Array<() => void>;
};

export function createBulkhead(key: string, limit: number): Bulkhead {
  return { key, limit, inFlight: 0, waiters: [] };
}

export async function withBulkhead<T>(
  bh: Bulkhead,
  run: () => Promise<T>,
): Promise<T> {
  if (bh.inFlight >= bh.limit) {
    await new Promise<void>((resolve, reject) => {
      const timer = setTimeout(() => {
        const i = bh.waiters.indexOf(wake);
        if (i >= 0) bh.waiters.splice(i, 1);
        reject(new Error("BULKHEAD_TIMEOUT"));
      }, 2_000);
      const wake = () => {
        clearTimeout(timer);
        resolve();
      };
      bh.waiters.push(wake);
    });
  }
  bh.inFlight += 1;
  try {
    return await run();
  } finally {
    bh.inFlight -= 1;
    const next = bh.waiters.shift();
    if (next) next();
  }
}

export function bulkheadKey(opts: {
  tenantId?: string;
  route: "interactive" | "batch";
}): string {
  return `${opts.route}:${opts.tenantId ?? "anon"}`;
}

Interactive form traffic can use a higher per-tenant limit than batch imports. Anonymous clients get a small shared ceiling so one scraper cannot monopolize DecodeVinValues.

Forbidden "fixes"

Product pressure often asks for:

Raising the global worker limit instead of partitioning noisy paths
Letting batch jobs borrow interactive slots when the batch bulkhead is full
Retrying BULKHEAD_TIMEOUT immediately without backoff (which re-saturates the same key)
Sharing one bulkhead across all tenants "for simplicity"
Treating bulkhead rejection as an NHTSA outage and opening a global breaker

Refuse those. A full bulkhead is a local capacity signal, not proof that vPIC is down. Keep breaker logic on upstream error rates; keep bulkheads on concurrency ownership.

export type DecodePool = Map<string, Bulkhead>;

export function getBulkhead(
  pool: DecodePool,
  key: string,
  limits: { interactive: number; batch: number },
): Bulkhead {
  let bh = pool.get(key);
  if (!bh) {
    const route = key.startsWith("batch:") ? "batch" : "interactive";
    bh = createBulkhead(
      key,
      route === "batch" ? limits.batch : limits.interactive,
    );
    pool.set(key, bh);
  }
  return bh;
}

export async function decodeBehindBulkhead<T>(
  pool: DecodePool,
  opts: { tenantId?: string; route: "interactive" | "batch" },
  run: () => Promise<T>,
): Promise<T> {
  const key = bulkheadKey(opts);
  const bh = getBulkhead(pool, key, { interactive: 8, batch: 2 });
  return withBulkhead(bh, run);
}

Separate interactive and batch ceilings. Never let a saturated batch key drain the interactive pool, and never map bulkhead rejection into a fabricated "NHTSA unavailable" banner when other bulkheads still succeed.

UI and API copy that stays honest

Prefer:

"Decode busy for this session -- try again shortly" on BULKHEAD_TIMEOUT
Metrics labeled by bulkhead key, not a single global "queue depth"
A short footnote in ops docs: local concurrency cap, not an upstream grade

Avoid:

"NHTSA is down" when only one tenant bulkhead is full
Silently queueing batch work on interactive workers
Grey spinners that look like a decode in flight after you already rejected the slot

Quick checks

import assert from "node:assert/strict";

const bh = createBulkhead("interactive:t1", 1);
let released = false;
const first = withBulkhead(bh, async () => {
  await new Promise((r) => setTimeout(r, 50));
  released = true;
  return "ok";
});

await assert.rejects(
  withBulkhead(bh, async () => "nope"),
  /BULKHEAD_TIMEOUT/,
);
assert.equal(released, false);
assert.equal(await first, "ok");
assert.equal(bh.inFlight, 0);

assert.equal(
  bulkheadKey({ tenantId: "a", route: "batch" }),
  "batch:a",
);

const pool: DecodePool = new Map();
const interactive = getBulkhead(pool, "interactive:x", {
  interactive: 8,
  batch: 2,
});
const batch = getBulkhead(pool, "batch:x", { interactive: 8, batch: 2 });
assert.equal(interactive.limit, 8);
assert.equal(batch.limit, 2);
assert.notEqual(interactive, batch);

Review rule: bulkhead modules must fail closed on local saturation, never steal slots across keys, and must not relabel rejection as a global NHTSA outage.

Takeaway

Bulkheading VIN decode workers keeps one bad path from starving the shared pool. Cap concurrency per tenant and route, fail or wait locally when a bulkhead is full, and keep that signal separate from breakers, hedges, and deadlines. Your free VIN proxy stays fair when interactive decodes cannot be crowded out by a single noisy batch or retry storm -- and when rejection copy admits local capacity, not invented upstream failure.

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

Cache-Aside VIN Decodes So Misses Hit NHTSA Once and Hits Stay Honest About Age

Vin Lookup — Wed, 07 Oct 2026 15:42:22 +0000

A free VIN decode edge that always calls NHTSA wastes quota; one that serves cache forever lies about freshness. Stale-while-revalidate (covered elsewhere) serves soft-stale bodies while refreshing. ETag caching (elsewhere) skips unchanged representations. Negative cache (elsewhere) remembers invalid VINs. Stampede control and warmup (elsewhere) manage herds and prefetch. This post is different: classic cache-aside (lazy loading) -- on miss, fetch DecodeVinValues once, populate the cache, return the body; on hit, return the cached body with an honest age/freshness label; never invent specs on miss.

The goal is narrow: implement get-or-load for normalized VINs, single-populate on miss, expose cache age to the UI, and keep misses from becoming folklore cards. Cache-aside is deliberately boring infrastructure -- its value is correct loading and honest labeling, not clever speculation about what a VIN "should" contain.

Cache-aside vs SWR, ETag, negative, stampede, warmup

SWR -- serve soft-stale while revalidating in background
ETag -- conditional revalidation with validators
Negative cache -- remember failures / invalid VINs
Stampede control -- one refresher when many hit expiry together
Warmup -- populate before first user miss
Cache-aside -- read path loads on miss; writer is the read path (or explicit put after live success)

Cache-aside is the default lazy pattern. Pair it with stampede control when popular keys expire; do not confuse a simple miss-fill with SWR's soft-stale serve. On a cold miss you wait for live; on a warm hit you must still admit the body's age.

Get-or-load with honest age

export type CacheAsideEntry = {
  vinNormalized: string;
  body: string;
  storedAt: number;
  maxAgeMs: number;
};

export type CacheAsideStore = Map<string, CacheAsideEntry>;

export type CacheAsideResult = {
  body: string;
  hit: boolean;
  ageMs: number;
  source: "cache" | "live";
};

export type LiveDecode = (vin: string) => Promise<string>;

export function getAside(
  store: CacheAsideStore,
  vinNormalized: string,
  now = Date.now(),
): CacheAsideEntry | null {
  const e = store.get(vinNormalized);
  if (!e) return null;
  if (now - e.storedAt > e.maxAgeMs) {
    store.delete(vinNormalized);
    return null;
  }
  return e;
}

export function putAside(
  store: CacheAsideStore,
  vinNormalized: string,
  body: string,
  maxAgeMs = 86_400_000,
  now = Date.now(),
): CacheAsideEntry {
  const e: CacheAsideEntry = { vinNormalized, body, storedAt: now, maxAgeMs };
  store.set(vinNormalized, e);
  return e;
}

export async function getOrLoad(
  store: CacheAsideStore,
  vinNormalized: string,
  live: LiveDecode,
  maxAgeMs = 86_400_000,
  now = Date.now(),
): Promise<CacheAsideResult> {
  const hit = getAside(store, vinNormalized, now);
  if (hit) {
    return {
      body: hit.body,
      hit: true,
      ageMs: now - hit.storedAt,
      source: "cache",
    };
  }
  const body = await live(vinNormalized);
  putAside(store, vinNormalized, body, maxAgeMs, Date.now());
  return { body, hit: false, ageMs: 0, source: "live" };
}

export function freshnessLabel(r: CacheAsideResult): string {
  if (r.source === "live") {
    return "Decoded from live NHTSA (cache miss filled)";
  }
  const ageSec = Math.round(r.ageMs / 1000);
  return `Cache hit -- catalog body age ~${ageSec}s (not inventing newer specs)`;
}

On live failure, do not put a folklore body. Leave the key missing so the next call retries, or use negative cache (separate tool) for known-invalid VINs. If many clients miss the same key together, wrap getOrLoad's live call in singleflight or stampede leadership so you still count one NHTSA fill -- cache-aside defines where the body lives; those tools define who may load it.

Honesty rules for hits and misses

Prefer:

One live fill per miss (add singleflight/stampede if many waiters share the miss)
Age labels on hits so UI does not say "live just now"
TTL expiry deletes or treats as miss -- no eternal silent hits
No write of partial invented fields when live returns sparse Results (partial payload honesty elsewhere)

Avoid serving a hit while claiming live completion, and avoid miss paths that invent Make from WMI charts. Emit metrics for hit ratio, miss latency, and average age-at-hit so you can tune maxAgeMs from data instead of folklore about how often vPIC changes.

Forbidden upgrades

Populating cache with guessed catalog JSON when NHTSA fails
Labeling every hit as "live NHTSA just now"
Skipping TTL because "VIN decode never changes" (patterns and fields do evolve)
Using cache-aside put to store negative failures as successful empty cars
Warming by writing folklore for popular makes without a live body

Refuse those. Cache-aside speeds repeats; it does not mint specs.

Quick checks

import assert from "node:assert/strict";

const store: CacheAsideStore = new Map();
let liveCalls = 0;
const live: LiveDecode = async () => {
  liveCalls += 1;
  return JSON.stringify({ Results: [{ Make: "HONDA" }] });
};

const a = await getOrLoad(store, "1HGCM82633A004352", live);
assert.equal(a.hit, false);
assert.equal(a.source, "live");
assert.equal(liveCalls, 1);

const b = await getOrLoad(store, "1HGCM82633A004352", live);
assert.equal(b.hit, true);
assert.equal(b.source, "cache");
assert.equal(liveCalls, 1);
assert.ok(/Cache hit/i.test(freshnessLabel(b)));
assert.ok(!/live NHTSA just now/i.test(freshnessLabel(b)));

// expired entry becomes miss
const e = store.get("1HGCM82633A004352")!;
e.storedAt = Date.now() - e.maxAgeMs - 1;
const c = await getOrLoad(store, "1HGCM82633A004352", live);
assert.equal(c.hit, false);
assert.equal(liveCalls, 2);

Review rule: cache-aside modules must fill from live on miss, label hit age honestly, and must not invent bodies on upstream failure.

Takeaway

Cache-aside VIN decodes hit NHTSA once per miss, store the real body, and serve repeats with an honest age label. Leave SWR, ETag, negative cache, stampede control, and warmup for their own jobs. Your free VIN edge stays fast when the cache is a shelf for sourced payloads -- never a factory for folklore catalog cards. Speed without age labels is how cached data pretends to be live.

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

Preventing VIN Decode Cache Stampedes When Soft TTL Expires Across Many Tabs

Vin Lookup — Wed, 07 Oct 2026 15:25:56 +0000

A free VIN decode that serves soft-stale bodies (SWR, covered elsewhere) still herds: when soft TTL expires for a popular VIN, many tabs each start live NHTSA DecodeVinValues. Singleflight (elsewhere) merges in-flight promises in one process; warmup and negative caches handle other paths. This post is different: cache stampede control at soft-TTL expiry -- one revalidate wins, others keep serving stale, and jitter spreads expiry so popular keys do not wake together.

The goal: stop a thundering herd when soft TTL ends across tabs or workers, without inventing specs mid-herd, and without claiming a stampede-safe serve is "live just now."

Stampede vs SWR, singleflight, warmup, negative cache

SWR -- when a soft-stale body may be served while refreshing
Singleflight -- merge identical in-flight promises once refresh starts
Warmup / negative cache -- preload popular keys; skip known-bad VINs
Stampede control -- who may start a refresh when many clients hit soft expiry, plus jitter so TTLs do not align

Stampede without singleflight still doubles live calls across workers; SWR without stampede control invites a herd the moment soft TTL flips.

Detect the herd window

When soft TTL has expired but hard TTL has not, every concurrent reader wants a refresh. Without a leader lock, each calls live NHTSA.

export type StampedeEntry = {
  vinNormalized: string;
  body: string;
  storedAt: number;
  softTtlMs: number;
  hardTtlMs: number;
  refreshLockUntil?: number; // epoch ms; leader holds refresh
  inflight?: Promise<string>;
};

export type StampedeStore = Map<string, StampedeEntry>;

export function softExpired(e: StampedeEntry, now = Date.now()): boolean {
  return now - e.storedAt > e.softTtlMs;
}

export function hardExpired(e: StampedeEntry, now = Date.now()): boolean {
  return now - e.storedAt > e.hardTtlMs;
}

/** Jitter soft TTL so popular VINs do not expire in lockstep. */
export function softTtlWithJitter(
  baseMs: number,
  vinNormalized: string,
  jitterFrac = 0.1,
): number {
  let h = 0;
  for (let i = 0; i < vinNormalized.length; i++) {
    h = (Math.imul(31, h) + vinNormalized.charCodeAt(i)) | 0;
  }
  const unit = ((h >>> 0) % 1000) / 1000; // 0..1
  const delta = (unit * 2 - 1) * jitterFrac; // -jitter..+jitter
  return Math.floor(baseMs * (1 + delta));
}

Jitter alone does not stop a herd after expiry -- it only desynchronizes when soft expiry hits. You still need a refresh leader.

One leader revalidates; others serve stale

On soft-stale hit: try to acquire a short refresh lock. Winner starts one live decode (optionally via singleflight). Losers return the stale body with an honest revalidating / stale label. Never invent Make/Model/Year while waiting.

export type LiveDecode = (vin: string) => Promise<string>;

export type StampedeResult = {
  body: string;
  freshness: "fresh" | "stale" | "revalidating";
  source: "cache" | "live";
  leader: boolean;
};

const LOCK_MS = 5_000;

export async function getAvoidingStampede(
  store: StampedeStore,
  vinNormalized: string,
  live: LiveDecode,
  now = Date.now(),
): Promise<StampedeResult> {
  let entry = store.get(vinNormalized);
  if (!entry || hardExpired(entry, now)) {
    const body = await live(vinNormalized);
    const softTtlMs = softTtlWithJitter(3_600_000, vinNormalized);
    store.set(vinNormalized, {
      vinNormalized,
      body,
      storedAt: now,
      softTtlMs,
      hardTtlMs: 86_400_000,
    });
    return { body, freshness: "fresh", source: "live", leader: true };
  }

  if (!softExpired(entry, now)) {
    return {
      body: entry.body,
      freshness: "fresh",
      source: "cache",
      leader: false,
    };
  }

  // Soft-stale: elect a leader for refresh
  const lockHeld =
    entry.refreshLockUntil !== undefined && entry.refreshLockUntil > now;
  if (!lockHeld && !entry.inflight) {
    entry.refreshLockUntil = now + LOCK_MS;
    entry.inflight = live(vinNormalized)
      .then((body) => {
        store.set(vinNormalized, {
          vinNormalized,
          body,
          storedAt: Date.now(),
          softTtlMs: softTtlWithJitter(3_600_000, vinNormalized),
          hardTtlMs: 86_400_000,
        });
        return body;
      })
      .finally(() => {
        const cur = store.get(vinNormalized);
        if (cur) {
          delete cur.inflight;
          delete cur.refreshLockUntil;
        }
      });
    return {
      body: entry.body,
      freshness: "revalidating",
      source: "cache",
      leader: true,
    };
  }

  // Followers: serve stale, do not start another live call
  return {
    body: entry.body,
    freshness: entry.inflight ? "revalidating" : "stale",
    source: "cache",
    leader: false,
  };
}

export function stampedeFootnote(r: StampedeResult): string {
  if (r.freshness === "fresh" && r.source === "live") {
    return "Decoded from live NHTSA for this request";
  }
  if (r.freshness === "revalidating") {
    return r.leader
      ? "Serving soft-stale body; this tab leads refresh"
      : "Serving soft-stale body; another tab leads refresh";
  }
  return "Serving soft-stale catalog body; soft TTL expired";
}

Across processes, replace the in-memory lock with Redis SET NX or a similar lease. Honesty stays: followers never invent a card; leaders never label a pre-refresh stale body as live.

Forbidden upgrades

Letting every soft-expired tab call NHTSA "just to be sure"
Extending hard TTL forever to dodge stampedes (hides staleness forever)
Filling missing fields during the herd with Make/Model/Year folklore
Labeling follower stale serves as "live NHTSA just now"
Dropping the stale body and returning an empty spinner for every follower

Refuse those. Stampede control is about upstream calm and honest freshness -- not fake completeness.

Quick checks

import assert from "node:assert/strict";

const store: StampedeStore = new Map();
const vin = "1HGCM82633A004352";
let liveCalls = 0;
const live: LiveDecode = async () => {
  liveCalls += 1;
  await new Promise((r) => setTimeout(r, 20));
  return JSON.stringify({ Results: [{ Make: "HONDA" }] });
};

const t0 = 1_000;
const first = await getAvoidingStampede(store, vin, live, t0);
assert.equal(first.source, "live");
assert.equal(liveCalls, 1);

const softAt = t0 + store.get(vin)!.softTtlMs + 1;
const a = getAvoidingStampede(store, vin, live, softAt);
const b = getAvoidingStampede(store, vin, live, softAt);
const [ra, rb] = await Promise.all([a, b]);
assert.equal(ra.source, "cache");
assert.equal(rb.source, "cache");
assert.ok(ra.leader !== rb.leader); // exactly one leader
assert.equal(liveCalls, 2); // miss + one revalidate, not three
assert.ok(!/live NHTSA just now/i.test(stampedeFootnote(rb)));
await store.get(vin)?.inflight;

Review rule: stampede modules must elect one refresh leader per key and must not invent specs for followers.

Takeaway

When soft TTL expires across many tabs, a VIN decode cache can stampede NHTSA unless one leader revalidates and followers keep serving soft-stale bodies with honest labels. Jitter desynchronizes expiry; locks or singleflight collapse the herd; hard TTL still forces a live wait when the body is too old. Stampede control beside SWR stays fast and truthful -- without pretending every stale serve was a fresh live decode.

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

Singleflight VIN Decode Lookups So Concurrent Identical VINs Share One In-Flight Promise

Vin Lookup — Wed, 07 Oct 2026 15:08:19 +0000

A free VIN decode edge or API route often fans out to NHTSA DecodeVinValues under concurrency. Two serverless isolates, two queue workers, or two browser tabs can hit the same normalized VIN in the same millisecond. Without a server-side singleflight gate, each request opens its own upstream call even when the work is identical and already in flight on that process.

This post is about server/edge singleflight: a process-local map from normalized VIN to one in-flight promise so concurrent identical lookups share one DecodeVinValues. Client-side request coalesce (duplicate pastes in one browser session) is a related idea with a different boundary -- see that pattern separately. Debounce decides when typing may start a call. ETag caches skip repeats after success. Here the focus is sharing one in-flight promise across concurrent server callers for the same VIN.

The failure mode

Typical sequence without singleflight on the edge:

Request A arrives for VIN X; the handler starts DecodeVinValues.
Request B arrives for the same normalized X before A settles (second tab, prefetch, or parallel SSR).
The handler starts a second identical upstream fetch.
NHTSA sees two calls; your edge latency and quota budget take a hit for no new information.
Both responses return; you still paid twice for one pattern.

Client coalesce does not fix this: the duplicates already crossed the network as separate HTTP requests. A response cache helps after success, not while the first edge fetch is still pending. A global mutex that serializes all VINs is worse -- unrelated lookups wait on each other.

One promise per normalized VIN on the process

Own a module-scoped map from normalized VIN to the in-flight Promise. On decode:

Normalize and validate the VIN.
If the map already has an entry for that key, return it.
Otherwise create the upstream promise, store it, and finally delete the key when settled.

Concurrent waiters on the same isolate share the result. Distinct VINs still run in parallel -- singleflight is keyed by identity, not a process-wide lock. Multi-isolate cold starts still duplicate until you add a shared cache; singleflight only collapses concurrency inside one runtime.

const VIN_RE = /^[A-HJ-NPR-Z0-9]{17}$/;

export function normalizeVin(raw: string): string {
  return raw.trim().toUpperCase().replace(/[\s\-._]/g, "");
}

export type DecodeRow = Record<string, string>;

export type SingleflightMap = Map<string, Promise<DecodeRow>>;

export function singleflightDecode(
  inflight: SingleflightMap,
  rawVin: string,
  fetchDecode: (vin: string) => Promise<DecodeRow>,
): Promise<DecodeRow> {
  const vin = normalizeVin(rawVin);
  if (!VIN_RE.test(vin)) {
    return Promise.reject(new Error("invalid_vin"));
  }

  const existing = inflight.get(vin);
  if (existing) return existing;

  const pending = fetchDecode(vin).finally(() => {
    if (inflight.get(vin) === pending) inflight.delete(vin);
  });
  inflight.set(vin, pending);
  return pending;
}

The finally cleanup matters. Leaving settled promises in the map would pin memory and block honest retries after a failed attempt. Delete only when the map still points at this promise so a concurrent re-entry after failure can start fresh work.

Forbidden shortcuts

Product pressure often asks for:

A process-wide lock so every decode waits on whichever VIN started first
Treating singleflight as a substitute for a shared Redis/ETag cache across isolates
Claiming "instant decode -- no NHTSA" when you only shared one in-flight edge call
Keeping failed 5xx promises in the map so retries never leave
Keying by raw query string without normalize (case or hyphens create duplicate flights)

Refuse those. Singleflight identical valid in-flight work on one process. Keep client coalesce for same-session duplicate pastes, debounce for typing, and durable caches for post-success repeats across instances. Do not invent offline or "skipped upstream" marketing from a shared promise.

export function assertNoSingleflightAbuse(moduleSource: string): void {
  const banned = [
    /global.?lock.?all.?vins/i,
    /skip.?nhtsa.?via.?singleflight/i,
    /instant.?decode.?no.?upstream/i,
    /singleflight.?replaces.?cache/i,
  ];
  for (const re of banned) {
    if (re.test(moduleSource)) {
      throw new Error(`Singleflight module misuse: ${re}`);
    }
  }
}

export async function decodeWithSingleflight(
  inflight: SingleflightMap,
  rawVin: string,
  fetchDecode: (vin: string) => Promise<DecodeRow>,
  onShared: () => void,
): Promise<DecodeRow> {
  const vin = normalizeVin(rawVin);
  const wasShared = inflight.has(vin);
  const row = await singleflightDecode(inflight, rawVin, fetchDecode);
  if (wasShared) onShared();
  return row;
}

Instrument onShared (or a metric) so you can see how often concurrent edge callers joined. That is observability, not a claim that decode is free or that NHTSA was skipped.

API copy that stays honest

Prefer:

Silent share: concurrent waiters see the same loading outcome without a second upstream span
Optional quiet log or metric: "joined in-flight singleflight for this VIN"
Clear error if the shared promise rejects -- every waiter sees the same failure

Avoid:

"Cached instantly -- no NHTSA call" when you only singleflighted an open edge request
Hiding a shared failure from secondary waiters
Showing success for VIN B because A's in-flight promise was incorrectly keyed

Quick checks

import assert from "node:assert/strict";

const inflight: SingleflightMap = new Map();
let calls = 0;
const fetchDecode = async (vin: string): Promise<DecodeRow> => {
  calls += 1;
  await new Promise((r) => setTimeout(r, 20));
  return { VIN: vin, Make: "TEST" };
};

const p1 = singleflightDecode(inflight, "1HGCM82633A004352", fetchDecode);
const p2 = singleflightDecode(inflight, "1hgcm82633a004352", fetchDecode);
assert.equal(p1, p2);
const [a, b] = await Promise.all([p1, p2]);
assert.equal(a.Make, "TEST");
assert.equal(b.Make, "TEST");
assert.equal(calls, 1);
assert.equal(inflight.size, 0);

const p3 = singleflightDecode(inflight, "1HGCM82633A004352", fetchDecode);
await p3;
assert.equal(calls, 2);

Review rule: singleflight modules must share by normalized VIN only while pending on this process, clear on settle, and never claim to replace client coalesce, debounce, or durable response caches.

Takeaway

Server/edge singleflight collapses concurrent identical VIN lookups into one upstream DecodeVinValues call per process. Pair it with client coalesce (same-session duplicates), debounce (start timing), and ETag caches (post-success repeats) -- do not substitute one for another. Your free VIN API stays kind to NHTSA when mid-flight work on one runtime shares a promise, then clears so the next lookup can run honestly.

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

Limiting Concurrent VIN Decode Upstream Calls So Browser Tabs Do Not Exhaust NHTSA

Vin Lookup — Wed, 07 Oct 2026 15:06:06 +0000

A free VIN decode edge that forwards every browser tab's paste straight to live NHTSA DecodeVinValues can open dozens of simultaneous upstream sockets. Token buckets (covered elsewhere) shape request rate over time. Quota-header handlers (elsewhere) back off when NHTSA says so. Singleflight (elsewhere) merges identical in-flight VINs. Stampede control (elsewhere) elects one soft-TTL refresher. This post is different: a concurrency limit -- a semaphore / max-in-flight pool so only N DecodeVinValues calls run at once, with clear queue-wait vs reject behavior and no invented specs while waiting.

The goal is narrow: cap simultaneous upstream calls from your edge (or BFF), queue excess work briefly or reject with an honest busy signal, and never fabricate a decode card to "keep the UI full" under load.

Concurrency limit vs rate limit, singleflight, stampede

Token bucket / rate limit -- how many starts per second over a window
Quota headers -- honor upstream Retry-After / remaining when told
Singleflight -- one shared promise per identical VIN key
Stampede control -- one soft-TTL refresh leader per key
Concurrency limit -- how many live upstream calls may be in flight at once, regardless of VIN identity

A rate limit of 10/s can still open 50 sockets if each call takes 5s. A concurrency cap of 8 keeps peak sockets honest even when many distinct VINs arrive together.

Semaphore shape

Track inFlight and a FIFO wait queue. Acquire before calling live NHTSA; release in finally. Bound queue length and wait time so tabs do not hang forever.

export type LiveDecode = (vin: string) => Promise<string>;

export type LimitResult =
  | { ok: true; body: string; waitedMs: number }
  | { ok: false; reason: "queue-full" | "wait-timeout"; waitedMs: number };

export type ConcurrencyLimit = {
  maxInFlight: number;
  maxQueue: number;
  maxWaitMs: number;
  inFlight: number;
  waiters: Array<{
    enqueuedAt: number;
    resolve: (granted: boolean) => void;
    timer: ReturnType<typeof setTimeout>;
  }>;
};

export function createLimit(
  maxInFlight = 8,
  maxQueue = 32,
  maxWaitMs = 3_000,
): ConcurrencyLimit {
  return { maxInFlight, maxQueue, maxWaitMs, inFlight: 0, waiters: [] };
}

function grant(limit: ConcurrencyLimit): void {
  limit.inFlight += 1;
}

function release(limit: ConcurrencyLimit): void {
  limit.inFlight -= 1;
  const next = limit.waiters.shift();
  if (!next) return;
  clearTimeout(next.timer);
  next.resolve(true);
}

async function acquire(
  limit: ConcurrencyLimit,
  now = Date.now(),
): Promise<{ granted: boolean; waitedMs: number }> {
  if (limit.inFlight < limit.maxInFlight) {
    grant(limit);
    return { granted: true, waitedMs: 0 };
  }
  if (limit.waiters.length >= limit.maxQueue) {
    return { granted: false, waitedMs: 0 };
  }
  const enqueuedAt = now;
  const granted = await new Promise<boolean>((resolve) => {
    const timer = setTimeout(() => {
      const idx = limit.waiters.findIndex((w) => w.resolve === resolve);
      if (idx >= 0) limit.waiters.splice(idx, 1);
      resolve(false);
    }, limit.maxWaitMs);
    limit.waiters.push({ enqueuedAt, resolve, timer });
  });
  const waitedMs = Date.now() - enqueuedAt;
  if (!granted) return { granted: false, waitedMs };
  grant(limit);
  return { granted: true, waitedMs };
}

export async function decodeWithLimit(
  limit: ConcurrencyLimit,
  vinNormalized: string,
  live: LiveDecode,
): Promise<LimitResult> {
  const { granted, waitedMs } = await acquire(limit);
  if (!granted) {
    return {
      ok: false,
      reason: waitedMs > 0 ? "wait-timeout" : "queue-full",
      waitedMs,
    };
  }
  try {
    const body = await live(vinNormalized);
    return { ok: true, body, waitedMs };
  } finally {
    release(limit);
  }
}

export function busyMessage(r: Extract<LimitResult, { ok: false }>): string {
  return r.reason === "queue-full"
    ? "Decode busy: upstream concurrency queue full -- try again shortly"
    : "Decode busy: waited too long for an upstream slot -- try again shortly";
}

Never map a reject into a fake Make/Model/Year card. Show the busy message; optionally retry client-side with backoff after the user confirms.

Queue wait vs reject

Product pressure often wants infinite queues so "nobody sees an error." Prefer bounded wait:

Short queue + timeout -- absorb bursts, then reject honestly
Reject fast when full -- protects NHTSA and your edge memory
Do not invent specs while a tab waits for a slot
Combine with singleflight after acquire so identical VINs still share one live body
Combine with token bucket so even under the concurrency cap you do not exceed sustained rate

Concurrency limits are about peak sockets; rate limits are about sustained starts. Use both.

Forbidden upgrades

Raising maxInFlight to "unlimited" under load so every tab opens a socket
Returning folklore catalog rows when queue-full or wait-timeout fires
Labeling a queued wait as "live NHTSA completed" before acquire succeeds
Dropping the semaphore because singleflight "already dedupes" (it does not cap distinct VINs)
Ignoring NHTSA quota headers because the concurrency cap "should be enough"

Refuse those. An honest busy state beats a stampeded upstream and a lying card.

Quick checks

import assert from "node:assert/strict";

const limit = createLimit(2, 2, 50);
let liveCalls = 0;
const live: LiveDecode = async (vin) => {
  liveCalls += 1;
  await new Promise((r) => setTimeout(r, 80));
  return JSON.stringify({ Results: [{ VIN: vin }] });
};

const jobs = ["VINAAAA", "VINBBBB", "VINCCCC", "VINDDDD", "VINEEEE"].map(
  (v) => decodeWithLimit(limit, v, live),
);
const results = await Promise.all(jobs);
const oks = results.filter((r) => r.ok);
const fails = results.filter((r) => !r.ok);
assert.ok(oks.length >= 2);
assert.ok(fails.length >= 1);
assert.ok(liveCalls <= 4); // cap + short queue, not five parallel forever
assert.ok(
  fails.every((f) => !f.ok && /busy|queue|waited/i.test(busyMessage(f))),
);
assert.ok(
  !results.some(
    (r) => r.ok && /folklore|invented/i.test(r.body),
  ),
);

Review rule: concurrency modules must bound in-flight upstream calls and must not invent decode bodies on reject.

Takeaway

A concurrency limit keeps browser tabs from opening unbounded DecodeVinValues sockets against NHTSA. Cap in-flight calls, bound the wait queue, reject with an honest busy signal, and leave rate limits, quota headers, singleflight, and stampede control in their own lanes. Your free VIN edge stays calm when peak concurrency is explicit -- and never fills a busy moment with invented catalog marketing.

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

Serving Stale-While-Revalidate VIN Decodes So Repeat Lookups Stay Fast Without Lying About Freshness

Vin Lookup — Wed, 07 Oct 2026 14:48:40 +0000

A free VIN decode that always waits for live NHTSA DecodeVinValues on every repeat paste feels slow even when the catalog barely changes. ETag caches, negative caches, and warmup (covered elsewhere) solve other problems. This post is different: stale-while-revalidate (SWR) -- serve a slightly stale cached decode immediately, refresh in the background, and label freshness honestly so the UI never pretends a background refresh already finished.

The goal is narrow: return a cached body past soft TTL while a revalidate runs, expose fresh vs stale vs revalidating to callers, and never invent specs or claim "live NHTSA just now" when you served stale.

SWR vs ETag, negative cache, and warmup

Use SWR when:

Soft TTL expired but hard TTL has not -- body may still be useful
A repeat lookup should paint fast while a background DecodeVinValues runs
Callers can show "catalog snapshot; refreshing..." without blocking

Do not confuse SWR with:

ETag / If-None-Match conditional fetches (validator equality, not soft-stale serve)
Negative cache of invalid VINs (no successful body to serve stale)
Make-pattern warmup (prefetch popular keys before first user hit)

SWR is about freshness semantics on a successful cached body. When hard TTL expires, drop the entry and require a blocking live fetch. Never serve a negative entry as a successful card.

Soft TTL, hard TTL, and honesty labels

Store soft and hard windows. Soft expiry allows stale serve + background revalidate. Hard expiry forces a live wait. Label every response so the UI cannot lie.

export type Freshness = "fresh" | "stale" | "revalidating" | "miss";

export type SwrEntry = {
  vinNormalized: string;
  body: string;
  storedAt: number; // epoch ms
  softTtlMs: number;
  hardTtlMs: number;
  revalidating?: Promise<string>;
};

export type SwrStore = Map<string, SwrEntry>;

export type SwrResult = {
  body: string | null;
  freshness: Freshness;
  source: "cache" | "live" | "missing";
};

const SOFT_TTL_MS = 60 * 60 * 1000; // 1h soft
const HARD_TTL_MS = 24 * 60 * 60 * 1000; // 24h hard

export function ageMs(entry: SwrEntry, now = Date.now()): number {
  return now - entry.storedAt;
}

export function classify(entry: SwrEntry, now = Date.now()): Freshness {
  const age = ageMs(entry, now);
  if (age > entry.hardTtlMs) return "miss";
  if (age <= entry.softTtlMs) return "fresh";
  if (entry.revalidating) return "revalidating";
  return "stale";
}

A fresh body may still be hours old relative to wall clock -- that is fine if soft TTL allows it. What is not fine is labeling a soft-stale serve as "live decode completed just now."

Serve stale, revalidate once

On soft-stale hit: return the cached body immediately, start one background revalidate (coalesce concurrent callers onto the same promise), and surface revalidating so the UI can footnote.

export type LiveDecode = (vin: string) => Promise<string>;

export async function getWithSwr(
  store: SwrStore,
  vinNormalized: string,
  live: LiveDecode,
  now = Date.now(),
): Promise<SwrResult> {
  const entry = store.get(vinNormalized);
  if (!entry || ageMs(entry, now) > entry.hardTtlMs) {
    const body = await live(vinNormalized);
    store.set(vinNormalized, {
      vinNormalized,
      body,
      storedAt: now,
      softTtlMs: SOFT_TTL_MS,
      hardTtlMs: HARD_TTL_MS,
    });
    return { body, freshness: "fresh", source: "live" };
  }

  const freshness = classify(entry, now);
  if (freshness === "fresh") {
    return { body: entry.body, freshness: "fresh", source: "cache" };
  }

  // Soft-stale: serve body, kick revalidate if not already running
  if (!entry.revalidating) {
    entry.revalidating = live(vinNormalized)
      .then((body) => {
        store.set(vinNormalized, {
          vinNormalized,
          body,
          storedAt: Date.now(),
          softTtlMs: SOFT_TTL_MS,
          hardTtlMs: HARD_TTL_MS,
        });
        return body;
      })
      .finally(() => {
        const cur = store.get(vinNormalized);
        if (cur) delete cur.revalidating;
      });
  }

  return {
    body: entry.body,
    freshness: "revalidating",
    source: "cache",
  };
}

export function freshnessFootnote(r: SwrResult): string {
  switch (r.freshness) {
    case "fresh":
      return r.source === "live"
        ? "Decoded from live NHTSA for this request"
        : "Cached catalog body within soft TTL";
    case "stale":
      return "Serving stale catalog body; soft TTL expired";
    case "revalidating":
      return "Serving stale catalog body while refreshing from NHTSA";
    case "miss":
      return "No usable cache entry; live decode required";
  }
}

Never rewrite the stale body while revalidate is in flight. Swap only when the live promise resolves. If revalidate fails, keep serving the prior body with an honest error footnote -- do not invent Make/Model/Year to "heal" the miss.

Forbidden upgrades

Product pressure often asks for:

Labeling every SWR serve as "live NHTSA just now"
Extending hard TTL forever so stale bodies never expire
Serving negative-cache failures as successful decode cards
Inventing missing catalog fields while a revalidate is pending
Hiding the revalidating footnote so cards look always-fresh

Refuse those. Speed without honesty is a lie about freshness.

Quick checks

import assert from "node:assert/strict";

const store: SwrStore = new Map();
const vin = "1HGCM82633A004352";
let liveCalls = 0;
const live: LiveDecode = async () => {
  liveCalls += 1;
  return JSON.stringify({ Results: [{ Make: "HONDA" }] });
};

const first = await getWithSwr(store, vin, live, 1_000);
assert.equal(first.freshness, "fresh");
assert.equal(first.source, "live");
assert.equal(liveCalls, 1);

const softStaleAt = 1_000 + SOFT_TTL_MS + 1;
const second = await getWithSwr(store, vin, live, softStaleAt);
assert.equal(second.source, "cache");
assert.equal(second.freshness, "revalidating");
assert.ok(/stale|refreshing/i.test(freshnessFootnote(second)));
assert.ok(!/live NHTSA just now/i.test(freshnessFootnote(second)));

// Concurrent soft-stale callers share one revalidate
const third = await getWithSwr(store, vin, live, softStaleAt);
assert.equal(third.freshness, "revalidating");
await store.get(vin)!.revalidating;
assert.equal(liveCalls, 2); // one live + one revalidate, not three

Review rule: SWR modules must expose freshness labels and must not claim live completion for stale serves.

Takeaway

Stale-while-revalidate keeps repeat VIN lookups fast by serving a soft-stale catalog body while NHTSA refreshes in the background. Pair soft and hard TTLs, coalesce revalidates, and label every response so users never confuse a stale snapshot with a just-completed live decode. Speed and honesty travel together; ETag, negative, and warmup caches stay in their own lanes.

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

Client Idempotency Keys for VIN Decode Retries Without Double-Charging Upstream Quotas

Vin Lookup — Wed, 07 Oct 2026 14:30:43 +0000

Mobile networks drop mid-response. Users tap Decode twice. Your fetch layer retries a 504 with the same VIN. Each attempt that reaches NHTSA burns the same free-quota unit even when the user intent was one decode. Handler-side idempotency stores (covered elsewhere) protect your API after the request arrives. This post is about the client-generated key that travels with every retry so an edge, BFF, or gateway can refuse a second upstream call before quota is spent.

The goal is narrow: one logical decode attempt, one client key, zero duplicate NHTSA hits when the network or the user repeats themselves. Do not confuse this with VIN-content caching ("same VIN forever") or with circuit breakers that open on slow upstreams.

Why the client must mint the key

Server-derived keys built only from normalized VIN + userId collide across different user intents: yesterday's decode and today's deliberate refresh share the same fingerprint. For quota protection on retries, you want the opposite of forever-dedupe: a short-lived key that is stable for one button press and its automatic retries, then expires so a later deliberate click is a new charge.

The browser (or mobile app) is the right place to mint that key:

User taps Decode (or the form auto-submits once)
Client creates a UUID (or ULID) and stores it next to the in-flight VIN
Every retry of that attempt sends the same Idempotency-Key header
A fresh tap after success or cancel mints a new key

That pattern preserves legitimate second decodes while collapsing double-clicks and transport retries onto one upstream budget.

Shape the request, not the VIN

export type DecodeAttempt = {
  vinNormalized: string;
  idempotencyKey: string;
  createdAt: number;
};

const ATTEMPT_TTL_MS = 60_000;

export function mintDecodeAttempt(vinNormalized: string): DecodeAttempt {
  return {
    vinNormalized,
    idempotencyKey: crypto.randomUUID(),
    createdAt: Date.now(),
  };
}

export function headerForAttempt(attempt: DecodeAttempt): HeadersInit {
  return {
    "Idempotency-Key": attempt.idempotencyKey,
    "Content-Type": "application/json",
  };
}

export function isAttemptFresh(attempt: DecodeAttempt, now = Date.now()): boolean {
  return now - attempt.createdAt < ATTEMPT_TTL_MS;
}

Send the key on POST (or on your BFF's decode route). Do not bake the key into the VIN string. Do not reuse yesterday's key from localStorage across sessions -- that silently merges unrelated user actions and can skip a decode the buyer intended.

Edge / BFF: honor the key before calling NHTSA

Your product layer still owns side effects (metrics, audit rows, UI history). The client key lets the edge short-circuit before DecodeVinValues:

type GateResult =
  | { kind: "proceed" }
  | { kind: "replay"; body: unknown }
  | { kind: "inflight" };

type StoredAttempt = {
  status: "pending" | "complete";
  body?: unknown;
  expiresAt: number;
};

const attempts = new Map<string, StoredAttempt>(); // Redis in production

export function gateUpstream(
  key: string,
  ttlMs = 60_000,
): GateResult {
  const now = Date.now();
  const existing = attempts.get(key);
  if (existing && existing.expiresAt > now) {
    if (existing.status === "complete") {
      return { kind: "replay", body: existing.body };
    }
    return { kind: "inflight" };
  }
  attempts.set(key, { status: "pending", expiresAt: now + ttlMs });
  return { kind: "proceed" };
}

export function completeAttempt(key: string, body: unknown, ttlMs = 60_000): void {
  attempts.set(key, {
    status: "complete",
    body,
    expiresAt: Date.now() + ttlMs,
  });
}

On proceed, call NHTSA once, then completeAttempt. On replay, return the stored body without touching upstream. On inflight, return 409 or a typed "decode already in progress" so the client waits instead of opening a second socket.

Client retry loop that keeps the key

export async function decodeWithClientKey(
  attempt: DecodeAttempt,
  post: (init: RequestInit) => Promise<Response>,
  maxRetries = 2,
): Promise<Response> {
  if (!isAttemptFresh(attempt)) {
    throw new Error("idempotency attempt expired; mint a new key");
  }
  let last: Response | undefined;
  for (let i = 0; i <= maxRetries; i++) {
    last = await post({
      method: "POST",
      headers: headerForAttempt(attempt),
      body: JSON.stringify({ vin: attempt.vinNormalized }),
    });
    if (last.status === 409) {
      await new Promise((r) => setTimeout(r, 200 * (i + 1)));
      continue;
    }
    if (last.ok || last.status < 500) return last;
  }
  return last!;
}

Critical rule: retries must not call mintDecodeAttempt again. Minting on each retry is how you double-charge quota while believing you are being careful.

Quota accounting stays honest

Count an upstream charge only when DecodeVinValues actually leaves your process. Replays from gateUpstream and 409-inflight waits must not increment NHTSA counters or "decodes today" meters. If the dashboard shows three upstream calls for one client key, the gate is wrong or the retry loop is minting keys. Keep server TTL short (30â€“90s) so deliberate refreshes stay real charges.

Forbidden patterns

Deriving the only key from VIN alone (collides intentional refreshes; also skips cache-bust when you need one)
Minting a new UUID on every retry tick
Persisting keys forever in localStorage so next week's visit replays last week's body
Treating a client key as proof the VIN is valid -- still validate length and check digit locally
Counting local validation failures as upstream quota events

Client keys protect transport and double-submit windows. They do not replace honest field display, circuit breakers, or long-term VIN result caches.

Quick checks

import assert from "node:assert/strict";

const a = mintDecodeAttempt("1HGCM82633A004352");
const b = mintDecodeAttempt("1HGCM82633A004352");
assert.notEqual(a.idempotencyKey, b.idempotencyKey);

assert.equal(gateUpstream(a.idempotencyKey).kind, "proceed");
assert.equal(gateUpstream(a.idempotencyKey).kind, "inflight");
completeAttempt(a.idempotencyKey, { make: "HONDA" });
const replay = gateUpstream(a.idempotencyKey);
assert.equal(replay.kind, "replay");

const headers = headerForAttempt(a);
assert.equal(
  (headers as Record<string, string>)["Idempotency-Key"],
  a.idempotencyKey,
);

Review rule: retry helpers must accept an existing attempt object; they must not mint inside the loop.

Takeaway

Client idempotency keys stop retry storms and double-clicks from burning NHTSA quota twice for one decode intent. Mint once per tap, send the same header on every retry, gate upstream before DecodeVinValues, and expire keys quickly so deliberate refreshes remain real. Handler idempotency and VIN caches remain useful -- they solve different windows. Quota honesty starts at the client key.

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

Showing ESC from vPIC Without Inventing Stability-Control Safety Grades

Vin Lookup — Wed, 07 Oct 2026 14:23:00 +0000

NHTSA vPIC often returns electronic stability control catalog fields on DecodeVinValues-style payloads -- commonly under keys such as ESC when the pattern includes that token. Those strings are useful on a free VIN decode card. The trap is turning a single sourced field into a stability-control safety grade, "ESC verified working," or skid-prevention claim that the catalog never asserted.

This post is about honest display: show the ESC catalog value when vPIC provides it, refuse stability-safety inventing, and allow a clean "not provided" state when the field is empty. Keep ESC catalog tokens separate from yaw-rate sensor health, brake-pressure tests, and road-course handling scores. A sourced token is still only a token: it does not prove the system is present, calibrated, or undamaged on the listed vehicle. (ABS honesty is a separate topic; here the focus is ESC.)

What ESC is (and is not) in vPIC

ESC (or the equivalent electronic stability control field your decode maps) is a catalog attribute associated with the VIN pattern. It answers a narrow question: which ESC-related token did the decode associate with this pattern?

It does not answer:

Whether the vehicle currently meets a stability or rollover performance standard
Whether ESC modules, yaw sensors, or hydraulic actuators work on this specific vehicle today
Traction control, ABS, or brake-assist packages you did not source as separate keys
Whether a dashboard ESC light is on, off, or silenced after a repair
A composite "stability safety score" built from missing neighboring fields

Empty ESC does not authorize a default "Standard" badge, and a positive token does not mean "skid control verified." Do not fill gaps from Make/Model/Year folklore or a chart keyed only by model year.

Normalize empties, do not invent grades

Treat blank, "Not Applicable", "N/A", and similar tokens as missing. Keep a sourced string when present; do not rewrite it into "ESC Grade A" or a stability-inspection score.

const EMPTY = new Set([
  "",
  "not applicable",
  "n/a",
  "na",
  "null",
  "none",
  "unknown",
]);

export type EscView = {
  value: string | null;
  source: "vpic" | "missing";
};

export function viewEsc(fields: {
  ESC?: string | null;
}): EscView {
  const raw = (fields.ESC ?? "").trim();
  if (!raw || EMPTY.has(raw.toLowerCase())) {
    return { value: null, source: "missing" };
  }
  return { value: raw, source: "vpic" };
}

export function escLines(view: EscView): string[] {
  if (view.source === "missing") {
    return ["ESC: not provided by vPIC for this VIN"];
  }
  return [
    `ESC (vPIC): ${view.value}`,
    "Catalog token only -- not a stability-control safety grade",
  ];
}

The footnote matters. Buyers over-read a single ESC field as verified skid prevention. Show the sourced token; if blank, say "not provided" -- no greyed "Standard" and no invented stability grade.

Forbidden upgrades

Product pressure often asks for:

Mapping any non-empty ESC into "electronic stability control verified"
Inventing IIHS / Euro NCAP / star-equivalent stability-safety language from the catalog field
Bundling ESC with ABS or traction-control keys into "Full Stability Safety Package"
Defaulting blank ESC to "Standard" so mid-trim cars look complete
Renaming catalog tokens into OEM chassis-suite marketing names you did not source

Refuse those. If you show neighboring catalog fields from separate sourced keys, show each on its own row. Never invent skid-prevention or package language inside the ESC mapper.

export function assertNoEscStabilityInvent(moduleSource: string): void {
  const banned = [
    /esc verified/i,
    /stability.?control safety grade/i,
    /skid prevention verified/i,
    /iihs/i,
    /full stability safety/i,
    /euro ncap/i,
  ];
  for (const re of banned) {
    if (re.test(moduleSource)) {
      throw new Error(
        `ESC module must not invent stability grades: ${re}`,
      );
    }
  }
}

export type CardRow = { label: string; value: string };

export function cardRows(fields: {
  ESC?: string | null;
  ABS?: string | null;
  TractionControl?: string | null;
}): CardRow[] {
  const view = viewEsc(fields);
  const out: CardRow[] = [];
  if (view.source === "missing") {
    out.push({ label: "ESC", value: "not provided" });
  } else {
    out.push({ label: "ESC", value: String(view.value) });
  }

  const abs = (fields.ABS ?? "").trim();
  if (abs && !EMPTY.has(abs.toLowerCase())) {
    out.push({ label: "ABS (vPIC)", value: abs });
  }
  const tc = (fields.TractionControl ?? "").trim();
  if (tc && !EMPTY.has(tc.toLowerCase())) {
    out.push({ label: "Traction control (vPIC)", value: tc });
  }
  return out;
}

Keep neighboring catalog fields on their own labeled rows. Never concatenate them into "Full Stability Safety Package," and never treat a separate ABS catalog key as proof that ESC implies a safety grade.

UI copy that stays honest

Prefer:

"ESC (vPIC): Standard"
"ESC: not provided by vPIC for this VIN"
A short footnote: catalog token, not a stability-control safety grade

Avoid:

"IIHS stability Superior -- verified"
"ESC Grade A included"
Grey placeholders that look like real ESC data when the field was empty

Quick checks

import assert from "node:assert/strict";

assert.equal(viewEsc({}).source, "missing");
assert.deepEqual(escLines(viewEsc({})), [
  "ESC: not provided by vPIC for this VIN",
]);

const std = viewEsc({ ESC: "Standard" });
assert.equal(std.value, "Standard");
assert.ok(
  escLines(std).some((l) => /not a stability-control safety grade/i.test(l)),
);
assert.ok(
  !escLines(std).some((l) =>
    /iihs|esc verified|stability safety package/i.test(l),
  ),
);

const rows = cardRows({
  ESC: "",
  ABS: "Standard",
  TractionControl: "Standard",
});
assert.ok(
  rows.some((r) => r.label === "ESC" && r.value === "not provided"),
);
assert.ok(rows.some((r) => r.label.includes("ABS")));
assert.ok(rows.some((r) => r.label.includes("Traction")));
assert.ok(!rows.some((r) => /iihs|esc verified/i.test(r.value)));

Review rule: ESC modules must not contain stability-upgrade or safety-grade phrases except in forbidding tests. Never upgrade a blank into "Standard."

Takeaway

ESC is a catalog token. Display it with clear sourcing, allow "not provided," and never use it as a key into invented stability-control safety grades, skid-prevention claims, or "full stability safety" bundles. Your free VIN UI stays trustworthy when ESC data is either a real vPIC value with a modest footnote -- or absent -- and chassis-performance marketing lives somewhere else, clearly labeled, or not at all.

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

Displaying AdaptiveCruiseControl from vPIC Without Inventing Autonomy Claims

Vin Lookup — Wed, 07 Oct 2026 14:17:29 +0000

NHTSA vPIC often returns adaptive-cruise catalog fields on DecodeVinValues-style payloads -- including AdaptiveCruiseControl when the pattern includes that token. Those strings are useful on a free VIN decode card. The trap is turning a single sourced field into a Level-2 autonomy claim, "self-driving capable," or hands-free highway package that the catalog never asserted.

This post is about honest display: show AdaptiveCruiseControl when vPIC provides it, refuse autonomy inventing, and allow a clean "not provided" state when the field is empty. Keep adaptive-cruise catalog values separate from SAE automation levels, OEM suite marketing, and highway-pilot branding. A sourced token is still only a token: it does not prove the feature is present, calibrated, or undamaged on the listed vehicle. Do not upgrade a cruise catalog string into a driverless narrative. (Forward-collision honesty is a separate topic; here the focus is AdaptiveCruiseControl.)

What AdaptiveCruiseControl is (and is not)

AdaptiveCruiseControl is a catalog attribute associated with the VIN decode. It answers a narrow question: which adaptive-cruise token did the decode associate with this pattern?

It does not answer:

Whether the vehicle is SAE Level 2, Level 3, or "autonomous"
Whether lane-centering, hands-free, or traffic-jam assist is included
Radar vs camera hardware, following-distance modes, or stop-and-go behavior you did not source
Whether the feature works today, was optioned, or was deleted after manufacture
A composite "autonomy score" built from missing neighboring fields

Empty AdaptiveCruiseControl does not authorize a default "Standard" badge, and a positive token does not mean "self-driving verified." Do not fill gaps from Make/Model/Year folklore or a chart keyed only by model year.

Normalize empties, do not invent autonomy

Treat blank, "Not Applicable", "N/A", and similar tokens as missing. Keep a sourced string when present; do not rewrite it into "Level 2 Standard" or an autonomy marketing grade.

const EMPTY = new Set([
  "",
  "not applicable",
  "n/a",
  "na",
  "null",
  "none",
  "unknown",
]);

export type AccView = {
  value: string | null;
  source: "vpic" | "missing";
};

export function viewAdaptiveCruiseControl(fields: {
  AdaptiveCruiseControl?: string | null;
}): AccView {
  const raw = (fields.AdaptiveCruiseControl ?? "").trim();
  if (!raw || EMPTY.has(raw.toLowerCase())) {
    return { value: null, source: "missing" };
  }
  return { value: raw, source: "vpic" };
}

export function adaptiveCruiseLines(view: AccView): string[] {
  if (view.source === "missing") {
    return [
      "Adaptive cruise control: not provided by vPIC for this VIN",
    ];
  }
  return [
    `Adaptive cruise control (vPIC): ${view.value}`,
    "Catalog token only -- not an autonomy or SAE level claim",
  ];
}

The footnote matters. Buyers over-read a single adaptive-cruise field as verified hands-free driving. Show the sourced token; if blank, say "not provided" -- no greyed "Standard" and no invented autonomy claim.

Forbidden upgrades

Product pressure often asks for:

Mapping any non-empty AdaptiveCruiseControl into "Level 2 included"
Inventing SAE / NHTSA automation-level language from the catalog field
Bundling AdaptiveCruiseControl with lane-keep keys into "Full Autonomy Package"
Defaulting blank AdaptiveCruiseControl to "Standard" so mid-trim cars look complete
Renaming catalog tokens into OEM highway-pilot marketing names you did not source

Refuse those. If you show other ADAS catalog fields from separate sourced keys, show each on its own row. Never invent SAE levels or package language inside the AdaptiveCruiseControl mapper.

export function assertNoAccAutonomyInvent(moduleSource: string): void {
  const banned = [
    /level\s*[123]/i,
    /self-?driving/i,
    /autonom(y|ous)/i,
    /hands-?free/i,
    /full autonomy package/i,
    /sae\s*level/i,
  ];
  for (const re of banned) {
    if (re.test(moduleSource)) {
      throw new Error(
        `AdaptiveCruiseControl module must not invent autonomy: ${re}`,
      );
    }
  }
}

export type CardRow = { label: string; value: string };

export function cardRows(fields: {
  AdaptiveCruiseControl?: string | null;
  ForwardCollisionWarning?: string | null;
  LaneKeepingSystem?: string | null;
}): CardRow[] {
  const view = viewAdaptiveCruiseControl(fields);
  const out: CardRow[] = [];
  if (view.source === "missing") {
    out.push({
      label: "Adaptive cruise control",
      value: "not provided",
    });
  } else {
    out.push({
      label: "Adaptive cruise control",
      value: String(view.value),
    });
  }

  const fcw = (fields.ForwardCollisionWarning ?? "").trim();
  if (fcw && !EMPTY.has(fcw.toLowerCase())) {
    out.push({ label: "Forward collision (vPIC)", value: fcw });
  }
  const lks = (fields.LaneKeepingSystem ?? "").trim();
  if (lks && !EMPTY.has(lks.toLowerCase())) {
    out.push({ label: "Lane keeping (vPIC)", value: lks });
  }
  return out;
}

Keep neighboring catalog fields on their own labeled rows. Never concatenate them into "Full Autonomy Package," and never treat a separate lane-keeping catalog key as proof that AdaptiveCruiseControl implies SAE Level 2.

UI copy that stays honest

Prefer:

"Adaptive cruise control (vPIC): Standard"
"Adaptive cruise control: not provided by vPIC for this VIN"
A short footnote: catalog token, not an autonomy or SAE level claim

Avoid:

"SAE Level 2 -- verified"
"Self-driving / hands-free included"
Grey placeholders that look like real adaptive-cruise data when the field was empty

Quick checks

import assert from "node:assert/strict";

assert.equal(viewAdaptiveCruiseControl({}).source, "missing");
assert.deepEqual(
  adaptiveCruiseLines(viewAdaptiveCruiseControl({})),
  ["Adaptive cruise control: not provided by vPIC for this VIN"],
);

const std = viewAdaptiveCruiseControl({
  AdaptiveCruiseControl: "Standard",
});
assert.equal(std.value, "Standard");
assert.ok(
  adaptiveCruiseLines(std).some((l) =>
    /not an autonomy or SAE level/i.test(l),
  ),
);
assert.ok(
  !adaptiveCruiseLines(std).some((l) =>
    /level\s*2|self-driving|autonomy package/i.test(l),
  ),
);

const rows = cardRows({
  AdaptiveCruiseControl: "",
  ForwardCollisionWarning: "Standard",
  LaneKeepingSystem: "Standard",
});
assert.ok(
  rows.some(
    (r) =>
      r.label.includes("Adaptive cruise") && r.value === "not provided",
  ),
);
assert.ok(rows.some((r) => r.label.includes("Forward collision")));
assert.ok(rows.some((r) => r.label.includes("Lane keeping")));
assert.ok(!rows.some((r) => /level\s*2|self-driving/i.test(r.value)));

Review rule: adaptive-cruise modules must not contain SAE-upgrade or autonomy-package phrases except in forbidding tests. Never upgrade a blank into "Standard."

Takeaway

AdaptiveCruiseControl is a catalog token. Display it with clear sourcing, allow "not provided," and never use it as a key into invented SAE levels, self-driving claims, or "full autonomy" bundles. Your free VIN UI stays trustworthy when adaptive-cruise data is either a real vPIC value with a modest footnote -- or absent -- and autonomy marketing lives somewhere else, clearly labeled, or not at all.

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

Circuit-Breaking NHTSA Calls So One Slow Upstream Does Not Stall Every VIN Form

Vin Lookup — Wed, 07 Oct 2026 14:12:04 +0000

Error-rate breakers trip when NHTSA is failing hard. A quieter failure mode is worse for forms: the upstream is merely slow. One hung DecodeVinValues call holds a shared client, saturates your concurrency budget, and every other VIN submit waits behind a spinner that never resolves. Retries with longer timeouts make the pile deeper.

This post is about latency-aware circuit breaking for free VIN decode: treat sustained slowness as a trip condition, fail fast for concurrent forms while open, and keep one slow call from stalling the whole UI surface. Classic consecutive-failure breakers are covered elsewhere; here the focus is slow upstream stalls every form.

Slow is not the same as down

Signal	Typical user experience	Breaker role
Hard 5xx / network error	Immediate error card	Count as failure
Sparse 200 with Make/Model	Partial but usable card	Success (not a trip)
Hang past budget	Spinner forever; other forms blocked	Count as slow failure
Burst of 8s+ latencies	Queue of submits backs up	Open on rate of slow calls

A form that shares one decode client (module singleton, server action pool, or browser fetch queue) is especially fragile. Without a breaker, the first hung request occupies the only in-flight slot; the second submit waits; the third looks "broken" even though validation is fine.

What should count as slow failure

Define an explicit per-call budget (for example 6â€“8s wall time). When the call exceeds the budget -- via AbortSignal.timeout, a racing Promise, or your HTTP client's deadline -- record a slow failure for the breaker, abort the in-flight work, and return a typed UPSTREAM_SLOW result.

Count toward the trip:

Timeouts and deadline aborts
Network errors that leave the request unresolved
HTTP 502 / 503 / 504 after a long wait (still a failure; also slow)

Do not count:

Local validation rejects (never called upstream)
Fast 200s with empty ABS / Make gaps (honest sparse success)
User-aborted navigations when you already cancelled cleanly

Mixing validation noise into slow-failure counts opens the circuit on bad paste days and blocks good VINs for no reason.

TypeScript sketch: latency trips + form gate

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

export type LatencyBreakerConfig = {
  slowThresholdMs: number; // e.g. 7000
  failureThreshold: number; // e.g. 3 consecutive slow/hard failures
  cooldownMs: number; // e.g. 20_000
  halfOpenMaxProbes: number; // e.g. 1
};

export class LatencyCircuitBreaker {
  private state: BreakerState = "closed";
  private consecutiveFailures = 0;
  private openedAt = 0;
  private halfOpenProbes = 0;

  constructor(private readonly cfg: LatencyBreakerConfig) {}

  canRequest(): boolean {
    if (this.state === "closed") return true;
    if (this.state === "open") {
      if (Date.now() - this.openedAt >= this.cfg.cooldownMs) {
        this.state = "half_open";
        this.halfOpenProbes = 0;
        return true;
      }
      return false;
    }
    return this.halfOpenProbes < this.cfg.halfOpenMaxProbes;
  }

  beforeRequest(): void {
    if (this.state === "half_open") this.halfOpenProbes += 1;
  }

  recordSuccess(): void {
    this.consecutiveFailures = 0;
    this.state = "closed";
    this.halfOpenProbes = 0;
  }

  recordFailure(): void {
    this.consecutiveFailures += 1;
    if (
      this.state === "half_open" ||
      this.consecutiveFailures >= this.cfg.failureThreshold
    ) {
      this.state = "open";
      this.openedAt = Date.now();
      this.halfOpenProbes = 0;
    }
  }
}

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

export async function decodeWithLatencyBreaker<T>(
  breaker: LatencyCircuitBreaker,
  call: (signal: AbortSignal) => Promise<T>,
  cfg: { slowThresholdMs: number },
): Promise<DecodeResult<T>> {
  if (!breaker.canRequest()) {
    return { ok: false, reason: "circuit_open" };
  }
  breaker.beforeRequest();
  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.recordSuccess();
    return { ok: true, data };
  } catch (err) {
    clearTimeout(timer);
    breaker.recordFailure();
    const timedOut =
      controller.signal.aborted &&
      Date.now() - started >= cfg.slowThresholdMs - 50;
    return {
      ok: false,
      reason: timedOut ? "upstream_slow" : "upstream",
    };
  }
}

Gate every form submit on canRequest() before disabling inputs or starting a spinner. When the circuit is open, return immediately with circuit_open so sibling forms stay interactive.

UX that does not stall the form

Prefer:

Instant "decode temporarily unavailable -- upstream is slow" when open
Disable only the submit that would call NHTSA; keep paste/clear/help controls alive
Optional stale last-good decode for that VIN, labeled "cached earlier; live refresh paused"

Avoid:

A global page-level spinner held by one hung fetch
Mapping circuit_open or upstream_slow to "invalid VIN"
Silent retries that re-queue the same hung call behind the open circuit

Keep reason codes separate (CIRCUIT_OPEN vs UPSTREAM_SLOW vs VIN_INVALID) so support and status copy stay accurate.

Quick checks

import assert from "node:assert/strict";

const breaker = new LatencyCircuitBreaker({
  slowThresholdMs: 50,
  failureThreshold: 2,
  cooldownMs: 60_000,
  halfOpenMaxProbes: 1,
});

async function hang(_signal: AbortSignal): Promise<never> {
  await new Promise(() => {});
  throw new Error("unreachable");
}

const a = await decodeWithLatencyBreaker(breaker, hang, {
  slowThresholdMs: 50,
});
assert.equal(a.ok, false);
if (!a.ok) assert.equal(a.reason, "upstream_slow");

const b = await decodeWithLatencyBreaker(breaker, hang, {
  slowThresholdMs: 50,
});
assert.equal(b.ok, false);

assert.equal(breaker.canRequest(), false);
const blocked = await decodeWithLatencyBreaker(breaker, hang, {
  slowThresholdMs: 50,
});
assert.deepEqual(blocked, { ok: false, reason: "circuit_open" });

Review rule: form submit handlers must short-circuit on open before awaiting upstream. Never let one slow call own the only concurrency slot without a budget.

Takeaway

One slow NHTSA call should not freeze every VIN form. Budget each decode, count timeouts as failures, open the circuit before the queue piles up, and fail fast with an honest "temporarily unavailable" state. Layer latency breakers with validation and single-flight, and free VIN decode stays responsive when the public API merely crawls instead of crashing.

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