[NomenAK]

What

Add a shared loopback-server readiness gate to selfFetchModels to eliminate 17× boot-time fetch failure bursts, plus force IPv4 for the scheduler's outbound URL.

Why

At container boot, ModelSync fires concurrent HTTP self-fetches against http://localhost:20128 for every provider connection (17 in our deployment) before the in-process HTTP server is fully accepting connections. The single-attempt contract produced a noisy 17-warning burst on every boot.

Two compounding root causes:

1. Boot race: the in-process HTTP listener takes longer than ~2s to accept after container start. All 17 connections retry independently and exhaust their retries.
2. IPv4/IPv6 ambiguity: localhost resolves to ::1 (IPv6) in our Docker network, but Next.js binds IPv4 only — even after retry, all self-fetches ECONNREFUSED.

How

Commit 1 (readiness gate):

• New ensureLoopbackServerReady(opts) — module-level shared promise. The first caller polls until any HTTP response (any status ≥ 200, including 404 = server alive) succeeds; all subsequent callers await the same promise.
• selfFetchModels(connectionId, opts) now awaits ensureLoopbackServerReady() before firing the model fetch. Exactly 1 probe runs per process regardless of caller count.
• Test helpers __resetLoopbackReadinessForTests() and skipReadinessGate?: boolean option for unit isolation.

Commit 2 (IPv4 + polish):

• modelSyncScheduler.ts:25: http://localhost:${dashboardPort} → http://127.0.0.1:${dashboardPort} — defense in depth mirroring the route-level safeOrigin guard.
• JSDoc on SelfFetchWithRetryOptions.maxRetries: "Default: 5" → "Default: 3" (synced with the actual default after readiness gate was added).

8 new tests in tests/unit/api/sync-models-readiness.test.ts: concurrent-callers share one probe, fallback after maxRetries, HTTP 4xx not retried (definitive), HTTP 5xx not retried, gate timeout, etc.

Notes

The readiness probe targets /api/providers/__readiness_probe__/models because any HTTP status confirms the server is dispatching (even 404). Happy to revise the probe endpoint if you have a /health or similar.

[gemini-code-assist]

Code Review

This pull request introduces a shared loopback readiness gate to optimize boot-time self-fetches, preventing retry amplification by serializing readiness probes. It also updates selfFetchWithRetry to use this gate and enforces consistent use of IPv4 (127.0.0.1) for loopback connections. Feedback identified a hardcoded port in the readiness probe that should be dynamic, a discrepancy between the retry documentation and actual implementation, and a test case that fails to account for the updated default retry count.

[gemini-code-assist]

The port 20128 is hardcoded here, but the application port is configurable (e.g., via the PORT environment variable). If the server runs on a different port, this readiness probe will target the wrong address and likely time out. It should use the dynamic port, similar to the logic used in fetchProviderModelsForSync.

Suggested change

	const res = await f("http://127.0.0.1:20128/api/providers/__readiness_probe__/models", {
	const port = process.env.PORT || "20128";
	const res = await f(`http://127.0.0.1:${port}/api/providers/__readiness_probe__/models`, {

[NomenAK]

Done in b60a2c1 — probe URL now uses process.env.OMNIROUTE_PORT || process.env.PORT || "20128", matching the pattern in src/lib/runtime/ports.ts and fetchProviderModelsForSync below. Thanks for catching that — we hardcoded 20128 in the initial draft and forgot to thread it through.

[gemini-code-assist]

There is a discrepancy between this docstring and the actual implementation. The docstring states that HTTP 5xx responses should be retried and 4xx should "fall back", but the code in selfFetchWithRetry (lines 286-290) and the unit tests indicate that any HTTP response returns immediately. Please align the documentation with the intended behavior.

[NomenAK]

Done in b60a2c1 — synced the docstring to match the implementation. You were right that the prior text ("5xx retry, 4xx fall back") didn't reflect the code, which returns ANY HTTP response (2xx/4xx/5xx) as-is and only retries on network-level failures. The retry-contract block now says exactly that.

[gemini-code-assist]

The default maxRetries was changed from 5 to 3 in the implementation, but this test still expects 5 retries (total 6 calls). This will cause the test to fail. The assertions and comments should be updated to reflect the new default of 3 attempts (total 4 calls).

  // selfFetchWithRetry default maxRetries=3: all 3 attempts throw, then in-process
  // fallback fires (which triggers the upstream bltcy.ai fetch). So fetchCalls
  // contains 3 self-fetch URLs followed by 1 upstream URL.
  const selfFetchUrl = `http://localhost/api/providers/${connection.id}/models?refresh=true`;
  assert.equal(
    fetchCalls.slice(0, 3).every((u) => u === selfFetchUrl),
    true,
    "first 3 calls should be self-fetch retries"
  );
  assert.equal(fetchCalls[3], "https://api.bltcy.ai/v1/models", "4th call should be upstream");
  assert.equal(fetchCalls.length, 4, "should have exactly 3 retries + 1 upstream call");

[NomenAK]

Done in b60a2c1. The test required three coordinated fixes: (1) retry count 3 not 5, (2) URL expectation updated to http://127.0.0.1:${PORT}/... since the route now forces IPv4 origin (not http://localhost), and (3) the mock fetch now handles the readiness-probe URL and we call __resetLoopbackReadinessForTests() so the gate state doesn't leak between tests. Verified locally — the test passes in ~720ms now.

[diegosouzapw]

Thanks @NomenAK! Your contribution has been integrated into release/v3.8.0 and will ship in the upcoming release.

The PR branch was synced with the latest release/v3.8.0 (no conflicts — the previously UNKNOWN mergeable state was simply stale, the merge itself was trivial) and squash-merged. The shared loopback readiness gate + IPv4 force is a much cleaner solution than just hoping the self-fetch finds the listener ready.

Reviewed and merged via the /review-prs-cc workflow.