searxng-mcp-go/docs/adr/006-unresponsive-engines-debug-only.md
XLion 7c60300b48
docs: fix documentation inaccuracies across 7 files
- #218: Correct --language CLI help from [default: auto] to [default: ""]
- #219: Unify pageno default semantics in MCP_TOOLS.md table
- #220: Add 'Fetch metadata header' to Sec-Fetch-Dest/Site purpose rows
- #221: Replace pipe-violating echo | commands with → pseudo-flow notation
- #223: Clarify unresponsive_engines logged at debug level (slog.Debug)
- #224: Warn about http:// SEARXNG_URL triggering non-suppressible warning
- #225: Remove misleading PR #78 reference in centralization_drift_test.go

Closes #218, #219, #220, #221, #223, #224, #225
2026-06-11 02:23:03 +08:00

28 lines
1.9 KiB
Markdown

# ADR-006: Expose `unresponsive_engines` Only in Debug Mode
Date: 2026-04-19
Status: Accepted
## Context
SearXNG's JSON response includes an `unresponsive_engines` field listing engines that failed to respond (e.g., rate-limited, CAPTCHA, connection errors). During code review, it was identified that `SearchResponse` does not model this field.
## Decision
**Expose `unresponsive_engines` in the response, but only when debug mode is enabled.**
In normal output (CLI and MCP), the field is omitted. When `--debug` or `DEBUG=1` is set, the field is included in JSON output and logged at debug level in CLI stderr output.
## Rationale
1. **SearXNG's nature**: SearXNG's core purpose is reverse-engineering search engine interfaces. It inherently calls multiple engines simultaneously, and engine breakage (rate-limiting, CAPTCHA, API changes) is an expected and routine occurrence — not a user-caused problem.
2. **Not user-responsibility**: When an engine becomes unresponsive, the fault lies with SearXNG's engine adapter (outdated scraping logic, missing CAPTCHA bypass, etc.), not with the user's query or configuration. There is no actionable step for the end user.
3. **Useful for troubleshooting, not for end users**: Regular users and AI agents do not need to know which engines failed. This is diagnostic information for SearXNG operators and developers.
4. **Debug mode is the right filter**: Debug mode already shows HTTP request/response details. Including engine failures here is consistent with the debug UX.
## Consequences
- `SearchResponse` gains an `UnresponsiveEngines` field with `json:",omitempty"` tag.
- Search response normalization and output formatting conditionally include/exclude the field based on debug mode.
- CLI debug output logs unresponsive engines at slog.Debug level (visible only with `--debug` or `DEBUG=1`).
- MCP JSON output includes the field only when debug is active.