{"record":{"id":"2a04f1b8ef68d043","repo":"JuliusBrussee/caveman","slug":"code","errorCode":null,"errorMessage":"code","messagePattern":"code","errorType":"error_code","errorClass":"MiddlewareError","httpStatus":null,"severity":"error","filePath":"packages/sdk/typescript/src/middleware/runtime.ts","lineNumber":310,"sourceCode":"  }\n\n  close(): void { this.lifetime.abort(new MiddlewareError('closed')); this.capsCache.value = null; }\n\n  /** Native adapters use this when their installed framework is untested.\n   * No content or network request is sent. Strict mode remains explicit. */\n  decline(reason: 'unsupported_version'): Optimization {\n    if (this.mode === 'off') return { status: 'off', reason: 'disabled', replacements: [], plan: null, request: null, cacheContinuity: 'off' };\n    return this.bypass(reason);\n  }\n\n  /** Header controls are restricted to an explicitly configured, discovered runtime origin. */\n  isRuntimeOrigin(url: string): boolean {\n    try { return this.capsCache.value !== null && new URL(url).origin === this.endpoint; } catch { return false; }\n  }\n\n  private bypass(code: string, diagnostic = true): Optimization {\n    if (diagnostic) { try { this.options.onDiagnostic?.({ code, cacheContinuity: 'unavailable' }); } catch { /* sink cannot break requests */ } }\n    if (this.options.strict && diagnostic) throw new MiddlewareError(code);\n    return { status: 'bypassed', reason: code, replacements: [], plan: null, request: null, cacheContinuity: 'unavailable' };\n  }\n\n  private async http(path: string, body: string | undefined, timeoutMs: number, signal?: AbortSignal): Promise<unknown> {\n    const deadline = new AbortController();\n    const timer = setTimeout(() => deadline.abort(new MiddlewareError('deadline')),Math.max(1,Math.ceil(timeoutMs)));\n    try {\n      return await this.exchange(path,body,AbortSignal.any([this.lifetime.signal,deadline.signal,...(signal ? [signal] : [])]));\n    } finally { clearTimeout(timer); }\n  }\n\n  private async exchange(path: string, body: string | undefined, combined: AbortSignal): Promise<unknown> {\n    combined.throwIfAborted();\n    const headers: Record<string,string> = { 'Content-Type': 'application/json' };\n    if (this.options.token) headers['Authorization'] = `Bearer ${this.options.token}`;\n    const receipt = path === 'receipts';\n    if (receipt ? this.receiptFetchesPending >= 1 : this.fetchesPending >= 16) throw new MiddlewareError('capacity');\n    if (receipt) this.receiptFetchesPending++; else this.fetchesPending++;","sourceCodeStart":292,"sourceCodeEnd":328,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/sdk/typescript/src/middleware/runtime.ts#L292-L328","documentation":"bypass() is the internal escape hatch the runtime uses when it cannot optimize (circuit open, capacity, payload limits, deadline, etc.). Normally it returns a nonthrowing { status: 'bypassed', reason: code } result and emits an onDiagnostic callback; however, when options.strict is true it instead throws MiddlewareError(code), turning every bypass condition into a hard error with the bypass reason as the error code.","triggerScenarios":"Any bypass path (circuit_open, capacity, payload_limit, deadline, invalid_scope, etc.) reached while the runtime was constructed with strict: true; the thrown message is 'Caveman middleware: <reason>'.","commonSituations":"Running with strict mode enabled in production to surface compression failures loudly, then hitting routine conditions like an open circuit after runtime failures; mixing a strict-configured runtime with a flaky runtime server.","solutions":["Disable strict mode if bypasses should degrade gracefully (default behavior)","Catch MiddlewareError and inspect .code to handle specific bypass reasons","Fix the underlying bypass cause (e.g. raise limits, restore runtime availability) so the bypass stops occurring"],"exampleFix":"// before\nconst runtime = createMiddlewareRuntime({ strict: true }); // throws on any bypass\n// after\nconst runtime = createMiddlewareRuntime({}); // bypasses return status:'bypassed' instead\ntry { await runtime.optimize(opts); } catch (e) { if (e instanceof MiddlewareError) console.warn(e.code); }","handlingStrategy":"try-catch","validationCode":"if (strictMode && !canTolerateHardFailures) throw new Error('strict mode will throw on any bypass');","typeGuard":null,"tryCatchPattern":"try { await runtime.optimize(req); } catch (e) { if (e instanceof MiddlewareError) { switch (e.code) { case 'circuit_open': case 'capacity': case 'payload_limit': /* degrade gracefully */ } } else throw e; }","preventionTips":["Use strict: true only in CI or staging where you want loud failures","Handle all known bypass codes when strict is enabled","Wire onDiagnostic to logs even in strict mode for root cause"],"tags":["configuration","strict-mode","typescript"],"backgroundTag":"invalid-config-value","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}