Global API Middleware for Failure Notification with Query Batching 20260415

Global API Middleware for Failure Notification with Query Batching 20260415

Summary

Implements a global API error handling strategy and query batching optimization for waste search filters. Silent CORS/network failures are now surfaced as toast notifications. Three separate code table queries are batched into a single parallel request, reducing React effect executions and improving filter load performance.

Related Issues

• #725

Goals

• Eliminate silent API failures by implementing global error notification middleware
• Surface CORS, network, and backend errors to users via toast notifications
• Batch independent queries to reduce React context overhead and improve performance
• Establish a reusable middleware pattern for consistent error handling across all API calls
• Enable fine-grained notification routing through metadata tracking

Changes

Structural Changes

• Implemented failureNotificationMiddleware as new global API middleware in src/config/api/failureNotificationMiddleware.ts
• Added MIDDLEWARE field to APIConfig type to support composable middleware
• Batched three separate useCodesQuery calls into single useWasteSearchFilterOptionsQueries hook using useQueries
• Extracted notificationTarget metadata parameter into query keys for proper cache key differentiation
• Established middleware registration pattern in BackendApiConfig

Performance Improvements

• Reduced HTTP requests by batching three independent code table queries into a single parallel batch
• Eliminated redundant React effect executions for waste search filter loading
• Improved cache efficiency by including notificationTarget in query keys for proper cache separation

API / Data Flow Changes

• Added meta parameter support to all service methods: CodesService, ForestClientService, SearchService
• Added ApiMiddleware type with request, response, and failure handlers
• Middleware merging in request.ts combines config-level MIDDLEWARE with request-level middleware
• Global middleware registered in BackendApiConfig applies to all API calls

UI / UX Adjustments

• Global toast notifications for unhandled API failures
• Inline error notifications for scoped requests via notificationTarget metadata
• Updated WasteSearchFilters component to use batched hook
• Error details from RFC 7807 ProblemDetails properly formatted and displayed

Cleanup and Simplification

• Removed individual useCodesQuery calls in favor of batched useWasteSearchFilterOptionsQueries
• Consolidated error handling patterns through middleware instead of component-level try-catch

Bug Fixes

• Silent failures on CORS errors are now surfaced as toast notifications
• Network unreachability errors no longer go unnoticed
• Backend error details (ProblemDetails) are properly formatted and displayed to users

Impact

• User Experience: Users now receive immediate feedback when API calls fail due to network, CORS, or backend issues
• Maintainability: Centralized error handling through middleware reduces code duplication and improves consistency
• Reliability: All API failures are now captured and reported; silent failures eliminated
• Performance: Query batching reduces React context call overhead and improves filter load performance
• Testability: Middleware can be tested independently; query batching simplifies mock setup

Affected Components

• WasteSearchFilters
• Reference data loading across waste search

Test Coverage

• Unit Tests: 133 passing (includes CORS failure scenarios)
• E2E Tests: 131 passing, 35 skipped (verified with VITE_MOCK_AUTH=true)
• Type Safety: No ESLint warnings or TypeScript compilation errors

Files Changed

New:

• src/config/api/failureNotificationMiddleware.ts
• src/config/api/failureNotificationMiddleware.unit.test.ts

Modified:

• src/config/api/types.ts
• src/config/api/request.ts
• src/config/react-query/hooks.ts
• src/config/react-query/queryKeys.ts
• src/services/APIs.ts
• src/services/codes.service.ts
• src/services/forestclient.service.ts
• src/services/search.service.ts
• src/components/waste/WasteSearch/WasteSearchFilters/useWasteSearchFilterOptions.ts
• src/components/waste/WasteSearch/WasteSearchFilters/useWasteSearchFilterOptions.unit.test.tsx
• src/components/waste/WasteSearch/WasteSearchTable/index.unit.test.tsx

Follow-up Work

• Monitor error notification frequency to tune thresholds if needed
• Consider extending middleware pattern to other error scenarios (rate limiting, timeout handling)
• Review other query hook consumers to identify additional batching opportunities
• Add architectural documentation on middleware patterns
• Create reusable middleware templates for common scenarios