An AI-powered search engine with a generative UI
TypeScript generative-aigenerative-uinextjsollamareactsearxngshadcn-uitailwindcsstavilytypescriptupstashvercel-ai-sdk
fix(search): fall back after recoverable provider failures (#989)
Sushant Tiwari50ae26bfda2e
diff --git a/lib/tools/__tests__/search-fallback.test.ts b/lib/tools/__tests__/search-fallback.test.tsnew file mode 100644index 00000000..31332b92--- /dev/null+++ b/lib/tools/__tests__/search-fallback.test.ts@@ -0,0 +1,174 @@+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'++const mocks = vi.hoisted(() => ({+ braveSearch: vi.fn(),+ createSearchProvider: vi.fn(),+ tavilySearch: vi.fn()+}))++vi.mock('@/lib/tools/search/providers', () => ({+ createSearchProvider: mocks.createSearchProvider,+ DEFAULT_PROVIDER: 'tavily'+}))++import { createSearchTool } from '@/lib/tools/search'++const fallbackResult = {+ results: [+ {+ title: 'Fallback result',+ content: 'Fallback content',+ url: 'https://example.com/result'+ }+ ],+ images: [],+ query: 'current events',+ number_of_results: 1+}++function executeGeneralSearch(searchDepth = 'basic') {+ const result = createSearchTool('openai:gpt-4o-mini').execute?.(+ {+ query: 'current events',+ type: 'general',+ content_types: ['web'],+ max_results: 10,+ search_depth: searchDepth,+ include_domains: [],+ exclude_domains: []+ },+ { toolCallId: 'search-call', messages: [], context: {} }+ )++ return (result as AsyncIterable<unknown>)[Symbol.asyncIterator]()+}++describe('general search provider fallback', () => {+ beforeEach(() => {+ vi.stubEnv('BRAVE_SEARCH_API_KEY', 'test-key')+ vi.stubEnv('SEARCH_API', 'tavily')+ mocks.createSearchProvider.mockImplementation(provider => ({+ search: provider === 'brave' ? mocks.braveSearch : mocks.tavilySearch+ }))+ mocks.tavilySearch.mockResolvedValue(fallbackResult)+ vi.spyOn(console, 'log').mockImplementation(() => undefined)+ vi.spyOn(console, 'error').mockImplementation(() => undefined)+ })++ afterEach(() => {+ vi.unstubAllEnvs()+ vi.restoreAllMocks()+ vi.clearAllMocks()+ })++ it('uses the optimized provider after the general provider is rate limited', async () => {+ mocks.braveSearch.mockRejectedValue(+ Object.assign(new Error('Brave search failed: HTTP 429'), { status: 429 })+ )+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)+ const iterator = executeGeneralSearch()++ await iterator.next()+ const complete = await iterator.next()++ expect(complete.value).toMatchObject({+ state: 'complete',+ results: fallbackResult.results,+ toolCallId: 'search-call',+ provider: 'tavily',+ fallback: {+ from: 'brave',+ to: 'tavily',+ reason: { type: 'http', status: 429 }+ }+ })+ expect(mocks.braveSearch).toHaveBeenCalledOnce()+ expect(mocks.tavilySearch).toHaveBeenCalledOnce()+ expect(warn).toHaveBeenCalledWith(+ '[Search] dedicated general search provider brave failed with HTTP 429; using optimized search provider: tavily'+ )+ })++ it('uses the optimized provider after a transport failure', async () => {+ mocks.braveSearch.mockRejectedValue(new TypeError('fetch failed'))+ vi.spyOn(console, 'warn').mockImplementation(() => undefined)+ const iterator = executeGeneralSearch()++ await iterator.next()+ const complete = await iterator.next()++ expect(mocks.tavilySearch).toHaveBeenCalledOnce()+ expect(complete.value).toMatchObject({+ provider: 'tavily',+ fallback: {+ from: 'brave',+ to: 'tavily',+ reason: { type: 'transport' }+ }+ })+ })++ it('logs a recoverable HTTP status found on a nested cause', async () => {+ const cause = Object.assign(new Error('upstream unavailable'), {+ status: 503+ })+ mocks.braveSearch.mockRejectedValue(new Error('search failed', { cause }))+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)+ const iterator = executeGeneralSearch()++ await iterator.next()+ await iterator.next()++ expect(warn).toHaveBeenCalledWith(+ '[Search] dedicated general search provider brave failed with HTTP 503; using optimized search provider: tavily'+ )+ })++ it('normalizes an empty search depth to basic', async () => {+ mocks.braveSearch.mockResolvedValue(fallbackResult)+ const iterator = executeGeneralSearch('')++ await iterator.next()+ await iterator.next()++ expect(mocks.braveSearch).toHaveBeenCalledWith(+ 'current events',+ 10,+ 'basic',+ [],+ [],+ expect.any(Object)+ )+ })++ it('does not fall back for a client error', async () => {+ mocks.braveSearch.mockRejectedValue(+ Object.assign(new Error('Brave search failed: HTTP 400'), { status: 400 })+ )+ const iterator = executeGeneralSearch()++ await iterator.next()++ await expect(iterator.next()).rejects.toMatchObject({+ name: 'ToolFailureError',+ status: 400+ })+ expect(mocks.tavilySearch).not.toHaveBeenCalled()+ })++ it('does not retry the same provider as a fallback', async () => {+ vi.stubEnv('SEARCH_API', 'brave')+ mocks.braveSearch.mockRejectedValue(+ Object.assign(new Error('Brave search failed: HTTP 429'), { status: 429 })+ )+ const iterator = executeGeneralSearch()++ await iterator.next()++ await expect(iterator.next()).rejects.toMatchObject({+ name: 'ToolFailureError',+ status: 429+ })+ expect(mocks.braveSearch).toHaveBeenCalledOnce()+ })+})diff --git a/lib/tools/__tests__/search-to-model-output.test.ts b/lib/tools/__tests__/search-to-model-output.test.tsindex d6f02d67..06ed07c1 100644--- a/lib/tools/__tests__/search-to-model-output.test.ts+++ b/lib/tools/__tests__/search-to-model-output.test.ts@@ -23,7 +23,13 @@ describe('search tool toModelOutput', () => {1: { title: 'A', url: 'https://a.test', content: 'alpha' },2: { title: 'B', url: 'https://b.test', content: 'beta' }},- toolCallId: 'call_123'+ toolCallId: 'call_123',+ provider: 'tavily',+ fallback: {+ from: 'brave',+ to: 'tavily',+ reason: { type: 'http', status: 429 }+ }}const getModelValue = async (output: unknown) => {@@ -44,6 +50,13 @@ describe('search tool toModelOutput', () => {expect(value).not.toHaveProperty('state')})+ it('keeps trace metadata out of the model output', async () => {+ const value = await getModelValue(fullOutput)++ expect(value).not.toHaveProperty('provider')+ expect(value).not.toHaveProperty('fallback')+ })+it('preserves the fields the model needs to answer and to cite', async () => {const value = await getModelValue(fullOutput)@@ -69,6 +82,8 @@ describe('search tool toModelOutput', () => {expect(fullOutput).toHaveProperty('citationMap')expect(fullOutput).toHaveProperty('state')+ expect(fullOutput).toHaveProperty('provider')+ expect(fullOutput).toHaveProperty('fallback')})it('handles non-object output defensively', async () => {diff --git a/lib/tools/search.ts b/lib/tools/search.tsindex e3098727..f5196b75 100644--- a/lib/tools/search.ts+++ b/lib/tools/search.ts@@ -15,6 +15,30 @@ import {DEFAULT_PROVIDER,SearchProviderType} from './search/providers'+import {+ classifyRecoverableSearchError,+ RecoverableSearchFailure+} from './search/providers/recoverable-error'++function getOptimizedSearchProviderType(): SearchProviderType {+ return (process.env.SEARCH_API as SearchProviderType) || DEFAULT_PROVIDER+}++function getEffectiveSearchDepth(+ provider: SearchProviderType,+ requestedDepth: 'basic' | 'advanced'+): 'basic' | 'advanced' {+ return provider === 'searxng' &&+ process.env.SEARXNG_DEFAULT_DEPTH === 'advanced'+ ? 'advanced'+ : requestedDepth || 'basic'+}++function describeRecoverableSearchFailure(+ failure: RecoverableSearchFailure+): string {+ return failure.type === 'http' ? `HTTP ${failure.status}` : 'transport error'+}/*** Creates a search tool with the appropriate schema for the given model.@@ -51,41 +75,52 @@ export function createSearchTool(fullModel: string) {// Use the original query as is - any provider-specific handling will be done in the providerconst filledQuery = querylet searchResult: SearchResults+ let servedBySearchAPI: SearchProviderType+ let fallback:+ | {+ from: SearchProviderType+ to: SearchProviderType+ reason: RecoverableSearchFailure+ }+ | undefined++ const optimizedSearchAPI = getOptimizedSearchProviderType()// Determine which provider to use based on type+ let generalSearchAPI: SearchProviderType | null = nulllet searchAPI: SearchProviderTypeif (type === 'general') {// Try to use dedicated general search providerconst generalProvider = getGeneralSearchProviderType()if (generalProvider) {+ generalSearchAPI = generalProvidersearchAPI = generalProvider} else {// Fallback to primary provider (optimized search provider)- searchAPI =- (process.env.SEARCH_API as SearchProviderType) || DEFAULT_PROVIDER+ searchAPI = optimizedSearchAPIconsole.log(`[Search] type="general" requested but no dedicated provider available, using optimized search provider: ${searchAPI}`)}} else {// For 'optimized', use the configured provider- searchAPI =- (process.env.SEARCH_API as SearchProviderType) || DEFAULT_PROVIDER+ searchAPI = optimizedSearchAPI}- const effectiveSearchDepthForAPI =- searchAPI === 'searxng' &&- process.env.SEARXNG_DEFAULT_DEPTH === 'advanced'- ? 'advanced'- : effectiveSearchDepth || 'basic'+ const searchWithProvider = async (+ provider: SearchProviderType+ ): Promise<SearchResults> => {+ const effectiveSearchDepthForAPI = getEffectiveSearchDepth(+ provider,+ effectiveSearchDepth+ )- console.log(- `Using search API: ${searchAPI}, Type: ${type}, Search Depth: ${effectiveSearchDepthForAPI}`- )+ console.log(+ `Using search API: ${provider}, Type: ${type}, Search Depth: ${effectiveSearchDepthForAPI}`+ )- try {if (- searchAPI === 'searxng' &&+ provider === 'searxng' &&effectiveSearchDepthForAPI === 'advanced') {// Get the base URL using the centralized utility function@@ -107,40 +142,69 @@ export function createSearchTool(fullModel: string) {`Advanced search API error: ${response.status} ${response.statusText}`)}- searchResult = await response.json()- } else {- // Use the provider factory to get the appropriate search provider- const searchProvider = createSearchProvider(searchAPI)-- // Pass content_types only for Brave provider- if (searchAPI === 'brave') {- searchResult = await searchProvider.search(- filledQuery,- effectiveMaxResults,- effectiveSearchDepthForAPI,- include_domains,- exclude_domains,- {- type: type as 'general' | 'optimized',- content_types: content_types as Array<- 'web' | 'video' | 'image' | 'news'- >- }- )- } else {- searchResult = await searchProvider.search(- filledQuery,- effectiveMaxResults,- effectiveSearchDepthForAPI,- include_domains,- exclude_domains- )- }+ return response.json()}++ // Use the provider factory to get the appropriate search provider+ const searchProvider = createSearchProvider(provider)++ // Pass content_types only for Brave provider+ if (provider === 'brave') {+ return searchProvider.search(+ filledQuery,+ effectiveMaxResults,+ effectiveSearchDepthForAPI,+ include_domains,+ exclude_domains,+ {+ type: type as 'general' | 'optimized',+ content_types: content_types as Array<+ 'web' | 'video' | 'image' | 'news'+ >+ }+ )+ }++ return searchProvider.search(+ filledQuery,+ effectiveMaxResults,+ effectiveSearchDepthForAPI,+ include_domains,+ exclude_domains+ )+ }++ try {+ searchResult = await searchWithProvider(searchAPI)+ servedBySearchAPI = searchAPI} catch (error) {- console.error('Search API error:', error)- // Re-throw the error to let AI SDK handle it properly- throw new ToolFailureError('search', error)+ const recoverableFailure = classifyRecoverableSearchError(error)+ if (+ generalSearchAPI !== null &&+ generalSearchAPI !== optimizedSearchAPI &&+ recoverableFailure !== null+ ) {+ console.warn(+ `[Search] dedicated general search provider ${generalSearchAPI} failed with ${describeRecoverableSearchFailure(recoverableFailure)}; using optimized search provider: ${optimizedSearchAPI}`+ )++ try {+ searchResult = await searchWithProvider(optimizedSearchAPI)+ servedBySearchAPI = optimizedSearchAPI+ fallback = {+ from: generalSearchAPI,+ to: optimizedSearchAPI,+ reason: recoverableFailure+ }+ } catch (fallbackError) {+ console.error('Search fallback API error:', fallbackError)+ throw new ToolFailureError('search', fallbackError)+ }+ } else {+ console.error('Search API error:', error)+ // Re-throw the error to let AI SDK handle it properly+ throw new ToolFailureError('search', error)+ }}// No citationMap is attached: it fully duplicated `results`@@ -163,15 +227,17 @@ export function createSearchTool(fullModel: string) {// Yield final results with complete stateyield {state: 'complete' as const,- ...searchResult+ ...searchResult,+ provider: servedBySearchAPI,+ ...(fallback ? { fallback } : {})}},// Trim the model-facing tool result: citationMap fully duplicates- // `results` (dropped defensively for older persisted output) and state is- // a streaming marker. images MUST stay — getImageSpecPrompt instructs the- // model to embed URLs verbatim from this array. toolCallId MUST stay: the- // prompt cites as [number](#toolCallId), so the model reads the id from- // here.+ // `results` (dropped defensively for older persisted output), state is a+ // streaming marker, and provider/fallback are trace diagnostics. images+ // MUST stay — getImageSpecPrompt instructs the model to embed URLs verbatim+ // from this array. toolCallId MUST stay: the prompt cites as+ // [number](#toolCallId), so the model reads the id from here.toModelOutput: ({ output }) => {if (!output || typeof output !== 'object') {return { type: 'json', value: (output ?? null) as JSONValue }@@ -181,6 +247,8 @@ export function createSearchTool(fullModel: string) {}delete modelView.citationMapdelete modelView.state+ delete modelView.provider+ delete modelView.fallbackreturn { type: 'json', value: modelView as JSONValue }}})diff --git a/lib/tools/search/providers/__tests__/recoverable-error.test.ts b/lib/tools/search/providers/__tests__/recoverable-error.test.tsnew file mode 100644index 00000000..cd0c3369--- /dev/null+++ b/lib/tools/search/providers/__tests__/recoverable-error.test.ts@@ -0,0 +1,53 @@+import { describe, expect, it } from 'vitest'++import { classifyRecoverableSearchError } from '../recoverable-error'++describe('classifyRecoverableSearchError', () => {+ it.each([408, 429, 500, 503])(+ 'accepts recoverable HTTP status %i',+ status => {+ expect(+ classifyRecoverableSearchError(+ Object.assign(new Error('failed'), { status })+ )+ ).toEqual({ type: 'http', status })+ }+ )++ it.each([400, 401, 403, 404, 422])(+ 'rejects client HTTP status %i',+ status => {+ expect(+ classifyRecoverableSearchError(+ Object.assign(new Error('failed'), { status })+ )+ ).toBeNull()+ }+ )++ it('classifies a network failure through its cause', () => {+ const cause = Object.assign(new Error('connection reset'), {+ code: 'ECONNRESET'+ })++ expect(+ classifyRecoverableSearchError(new TypeError('fetch failed', { cause }))+ ).toEqual({ type: 'transport' })+ })++ it('preserves an HTTP status found on a nested cause', () => {+ const cause = Object.assign(new Error('upstream unavailable'), {+ status: 503+ })++ expect(+ classifyRecoverableSearchError(new Error('failed', { cause }))+ ).toEqual({ type: 'http', status: 503 })+ })++ it('does not treat an arbitrary provider exception as recoverable', () => {+ expect(+ classifyRecoverableSearchError(new Error('Invalid query options'))+ ).toBeNull()+ })+})diff --git a/lib/tools/search/providers/recoverable-error.ts b/lib/tools/search/providers/recoverable-error.tsnew file mode 100644index 00000000..6471d5b5--- /dev/null+++ b/lib/tools/search/providers/recoverable-error.ts@@ -0,0 +1,101 @@+const RECOVERABLE_NETWORK_CODES = new Set([+ 'EAI_AGAIN',+ 'ECONNREFUSED',+ 'ECONNRESET',+ 'EHOSTUNREACH',+ 'ENETUNREACH',+ 'ENOTFOUND',+ 'ETIMEDOUT',+ 'UND_ERR_CONNECT_TIMEOUT',+ 'UND_ERR_HEADERS_TIMEOUT',+ 'UND_ERR_SOCKET'+])++function getNumericProperty(+ error: unknown,+ property: 'status' | 'statusCode'+): number | undefined {+ if (typeof error !== 'object' || error === null) return undefined++ const value = (error as Record<string, unknown>)[property]+ return typeof value === 'number' && Number.isFinite(value) ? value : undefined+}++function getStringProperty(+ error: unknown,+ property: 'code' | 'message' | 'name'+): string | undefined {+ if (typeof error !== 'object' || error === null) return undefined++ const value = (error as Record<string, unknown>)[property]+ return typeof value === 'string' ? value : undefined+}++function getCause(error: unknown): unknown {+ if (typeof error !== 'object' || error === null) return undefined+ return (error as { cause?: unknown }).cause+}++export type RecoverableSearchFailure =+ | { type: 'http'; status: number }+ | { type: 'transport' }++function getErrorChain(error: unknown): unknown[] {+ const chain: unknown[] = []+ const visited = new Set<unknown>()+ let current = error++ while (current !== undefined && !visited.has(current)) {+ visited.add(current)+ chain.push(current)+ current = getCause(current)+ }++ return chain+}++/**+ * General search can safely retry another provider only when the failure is+ * upstream and temporary. Client errors remain terminal because another+ * provider should not be used to reinterpret a malformed request.+ */+export function classifyRecoverableSearchError(+ error: unknown+): RecoverableSearchFailure | null {+ const errorChain = getErrorChain(error)++ // Prefer a numeric HTTP status anywhere in the cause chain. This keeps the+ // fallback decision and its trace metadata based on the same signal.+ for (const current of errorChain) {+ const status =+ getNumericProperty(current, 'status') ??+ getNumericProperty(current, 'statusCode')+ if (status !== undefined) {+ return status === 408 || status === 429 || (status >= 500 && status < 600)+ ? { type: 'http', status }+ : null+ }+ }++ for (const current of errorChain) {+ const code = getStringProperty(current, 'code')+ if (code && RECOVERABLE_NETWORK_CODES.has(code)) {+ return { type: 'transport' }+ }++ const name = getStringProperty(current, 'name')+ if (name === 'TimeoutError') return { type: 'transport' }++ const message = getStringProperty(current, 'message')+ if (+ message &&+ /failed to fetch|fetch failed|network (?:error|request failed)|timed? out/i.test(+ message+ )+ ) {+ return { type: 'transport' }+ }+ }++ return null+}