feat: add production-readiness features (CORS, cache, health check, structured errors, request logging, graceful shutdown)

[Sai-Prashanth123]

Summary

This PR adds 6 production-readiness features to make OpenSERP more robust, observable, and frontend-friendly.

Changes

1. CORS Middleware (core/middleware.go)

• Configurable Access-Control-Allow-Origin/Methods/Headers headers
• Handles preflight OPTIONS requests automatically
• Enabled by default, configurable via --cors flag or cors: in config

2. Structured JSON Error Responses (core/middleware.go)

• All API errors now return consistent JSON: {"error": "...", "code": 503, "message": "..."}
• Replaces plain-text error responses for proper API consumption

3. Request Logging Middleware (core/middleware.go)

• Logs every request with method, path, status code, latency, client IP
• Uses WARN for 4xx, ERROR for 5xx status codes
• Includes search query text for search endpoints

4. /health Endpoint (core/server.go)

• Returns server status, uptime, engine initialization status, and system metrics (goroutines, memory, Go version)
• Returns HTTP 503 if any engine is not initialized (degraded state)
• Added HEALTHCHECK directive to Dockerfile for container orchestration

5. In-Memory Response Cache (core/cache.go)

• Thread-safe cache with configurable TTL (default: 5 min) and max size (default: 1000)
• Automatic background eviction of expired entries every 60s
• X-Cache: HIT/MISS response header for transparency
• GET /cache/stats endpoint for monitoring
• Reduces search engine hits, lowering ban/captcha risk

6. Graceful Shutdown (main.go)

• Handles SIGINT/SIGTERM signals for clean exit
• Prevents orphaned browser processes on Ctrl+C or docker stop

New Config Options

Option	CLI Flag	Default	Description
cache_ttl	--cache_ttl	300	Cache TTL in seconds (0 = disabled)
cache_max_size	--cache_max_size	1000	Max cached responses
cors	--cors	true	Enable CORS headers

Files Changed (10 files, +634 lines)

File	Type
core/middleware.go	New — CORS, JSON errors, request logging
core/cache.go	New — TTL cache with eviction
core/cache_test.go	New — 6 cache unit tests
core/middleware_test.go	New — Middleware unit tests
core/server.go	Modified — Health endpoint, cache integration, middleware wiring
cmd/root.go	Modified — New config fields + CLI flags
cmd/serve.go	Modified — Pass ServerOptions with cache/CORS settings
config.yaml	Modified — New config keys with defaults
Dockerfile	Modified — Added HEALTHCHECK
main.go	Modified — Signal handling

Backward Compatibility

All changes are fully backward-compatible:

• Cache is enabled by default but can be disabled with cache_ttl: 0
• CORS is enabled by default but can be disabled with --cors=false
• Existing API endpoints and response formats are unchanged
• New endpoints (/health, /cache/stats) are additive only

[karust]

Thanks for the PR! I like the direction overall, and there are several useful additions here

Good ideas:

• CORS support is useful for browser-based clients
• caching identical requests can reduce repeated scraping pressure
• healthcheck and stats endpoints are useful for Docker/ops visibility

One product-level question:

• Should dedicated engine endpoints like /google/search or /bing/search fall back to a different engine at all? That may be surprising for users who explicitly want results from a specific engine. Fallback feels more appropriate for mega/* or for an explicitly enabled resilient mode.

A few suggestions:

• move cache and resilience into separate sections in config.yaml instead of adding many flat app flags
• make resilience optional
• if resilience stays, let users configure fallback engines explicitly for more control
• make cache optional as well, or disable it when cache_max_size=0

There are also a few issues I think should be fixed before merge:

1. fallback results are cached under the requested engine key, not the actual serving engine. Example: first /google/search fails over to Yandex and returns X-Fallback-Engine: yandex, X-Cache: MISS; second /google/search returns X-Cache: HIT, but now there is no indication the cached result actually came from Yandex
2. search requests still appear to be allowed during circuit-breaker open / half-open flow in ways that don’t match the intended behavior, and retry_in stats do not seem to reflect new failures correctly
3. rate limits via engine.GetRateLimiter() do not seem to be applied inside the resilient searcher
4. proxy rotation is configured, but the proxy pool does not seem to be used in actual resilient searches
5. /health returns HTTP 503 for a merely degraded state, which could cause unnecessary container restarts if only one engine is failing

I’m going to leave this open for now rather than merge it in the current form.
If you’d like to continue with it, I’d be happy to review another revision.

[karust]

Thanks again for PR and the amount of groundwork you put into it.

I went through the ideas and implementation in detail and ported/reworked the useful parts into the current codebase in a way that better matches OpenSERP’s direction and config model. The 0.6.0 release now includes the production-readiness improvements that were explored here, including health checks, cache/resilience work, proxy/runtime improvements, and related server wiring.

I’m closing this PR because the final implementation landed through a different integration/rework path rather than by merging this branch directly, but your work absolutely helped shape the release. Credit is also included in the 0.6.0 changelog.

Thanks for the contribution.