* docs: align documentation with code behavior (issues #547-#551) - INSTALL.md: drop SEARXNG_MAX_RETRIES=-1 from the unparsable-value example list; cross-reference the hard-error semantic path - PROMPT_INJECTION_SAFETY.md: mark Option A (warning header + warning field) as implemented, referencing #448 and #50 - MCP_TESTING.md: E2E binary is built once into a package-level cache, not per test; e2eMCPEnv lives in e2e_helper_test.go; goroutine-leak guard is suite-wide, not stress-file-specific - e2e-tests.md: fix workflow line citations (:87, :104) - verification.md: drop misleading '(except E2E)' qualifier; narrow the E2E-workflow coverage claim for exit-code tests - test-server.md: add missing test-server-pid-helper recipe row - .env.example: document SEARXNG_ALLOW_GET_FALLBACK opt-in - MCP_TOOLS.md: include 'failed to execute search request' segment in the network-failure error format - OUTPUT_FORMAT.md: sync Example 1 count line with the (showing N) format - adr/014: suppression was relocated to searchWithRetries, not removed - CONTEXT.md: note empty-text answers are dropped before the engine gate * docs: address review findings on doc accuracy (P2 items) - INSTALL.md: SEARXNG_MAX_RETRIES format is an integer in the range 0-20, not 'non-negative integer' — -1 parses and is rejected by SetMaxRetries, so the old wording conflated syntax and semantics - MCP_TESTING.md: example and E2E_MCP_BINARY section no longer claim a per-test build; list e2e_mockserver_test.go among the ungated CLI tests that build per-test via buildTestBinary - CONTEXT.md: dedup description notes the early return when no non-empty infobox text exists (original answers returned unchanged) * docs: fix remaining dedup and E2E_MCP_BINARY wording (P2) - CONTEXT.md: example dialogue no longer claims non-DuckDuckGo answers are never touched; empty answers are dropped before the engine check when dedup runs, matching the Search Behavior entry - test-server.md, verification.md: E2E_MCP_BINARY skips the MCP E2E package-level build, not the ungated CLI per-test builds * docs: scope dedup pass-through claim to non-empty answers SEARXNG_ANSWER_DEDUP.md and the DeduplicateAnswers doc comment both claimed non-DuckDuckGo answers always pass through. In fact, when dedup runs (non-empty infobox content exists), empty-text answers are dropped before the engine gate; only non-empty non-DuckDuckGo answers pass through. Aligns both with the implementation in deduplicate.go. * docs: fix dedup algorithm order in SEARXNG_ANSWER_DEDUP.md Document the empty-text filter running before the engine gate (matching deduplicate.go) and add the early-return precondition; sync the Edge Cases table so retain behavior is scoped to non-empty answers. * docs: qualify empty-answer drop with early-return precondition SEARXNG_ANSWER_DEDUP.md edge-case row and the deduplicateAnswers wrapper comment both stated empty-text answers are always filtered. When no non-empty infobox exists the implementation early-returns the original answers unchanged; scope the drop to dedup runs only.
4.8 KiB
ADR-014: Retry Outcome Enum
Status: Accepted Date: 2026-06-12
Context
The Search() retry loop had two separate ShouldRetry calls with different
semantics: one for errors and HTTP status codes (passing the real error), and
one for empty responses that passed a bare errEmptyResponse sentinel to
ShouldRetry. This worked only because isRetryableError returned true for
any non-*SearXNGError error — a load-bearing property that was undocumented,
untested, and fragile.
The retry strategy's ShouldRetry inspected resp and err directly, making
it impossible to express "empty response, should retry" without faking an error.
Issue #240 proposed replacing this with an explicit Outcome enum.
Issue #247 documented the fragility: errEmptyResponse must remain a bare
errors.New or the retry silently breaks. This is a maintenance trap.
Decision
Original decision (2026-06-12)
Introduce an Outcome enum type with four values — OutcomeSuccess,
OutcomeRetry, OutcomeEmptyRetry, OutcomeAbort — and a pure
classifyOutcome function that determines the outcome from
(ctx, attempt, maxRetries, resp, err, isEmpty).
Changes:
ShouldRetrynow acceptsoutcome Outcomeinstead ofresp *http.Responseanderr error. The strategy is purely outcome-driven.isRetryableErroris removed;classifyOutcomereplaces its logic.errEmptyResponseis renamed toerrSearchEmptyResults(last-error path only; no longer used for retry decisions).- The
//nolint:gocognit,cyclop,gocyclosuppression onSearch()is relocated to the extractedsearchWithRetriesloop, which still carries the retry orchestration complexity that needs it. - Three helpers (
searchContext,wrapSearchError,classifyAttempt) are extracted to keepSearch()focused on orchestration.
Extension (2026-07-13): OutcomeEmptyExhausted
The original design treated empty responses on the final attempt as
OutcomeSuccess, returning a successful SearchResponse with zero results
and only logging a slog.Warn. This was a vestige of the pre-ADR-014 era
where errEmptyResponse could not be the final return value.
Issue #475 identified the contradiction between the documented error path
("search returned empty results after all retries") and the actual success
response. The behaviour was corrected by adding a fifth outcome value,
OutcomeEmptyExhausted, that causes the retry loop to return a wrapped
errSearchEmptyResults error instead of silently succeeding.
Changes:
- Adds
OutcomeEmptyExhaustedto theOutcomeenum. classifyOutcomereturnsOutcomeEmptyExhaustedwhenisEmpty && attempt >= maxRetries(empty response with no retries remaining).ShouldRetrytreatsOutcomeEmptyExhaustedas non-retryable (returnsfalse), consistent with its final-attempt semantics.Search()handlesOutcomeEmptyExhaustedafterOutcomeSuccess. The two values are mutually exclusive (a response cannot be both exhausted and successful), so the check order is just a convention.errSearchEmptyResultsis promoted from internal tracking error to the actual terminal error returned to callers.- The
slog.Warn("search returned empty after exhausting retries")log is removed; the error itself communicates the exhausted-retries condition.
Consequences
- Explicit contract. The empty-response retry path no longer relies on an
accidental property of
errors.As. The retry decision is visible in theOutcomeswitch. - Simpler Search loop. Single
ShouldRetrycall instead of two. No fake error, no duplicated wait/continue logic. - New exported type.
Outcomeis exported fromsearxngpackage. Five values:OutcomeSuccess,OutcomeRetry,OutcomeEmptyRetry,OutcomeAbort,OutcomeEmptyExhausted. - Backward compatible behavior. Retry behaviour is preserved for all
existing scenarios: plain network errors retry,
SearXNGErrordoes not, retryable status codes (429, 5xx except 501) retry, empty responses retry on non-final attempts, non-retryable status codes abort. 501 is excluded from retryable 5xx because it is a deterministic method-rejection: when GET fallback is disabled, retrying sends the same POST to the same rejection. - Non-backward compatible terminal behaviour. The original decision returned an empty success response when all retries were exhausted on an empty SearXNG reply. This extension changes that to a terminal error. MCP callers now receive an error instead of a zero-result success. E2E tests that relied on the old success-with-empty contract have been updated to expect the error or to tolerate empty results via the warning-summary path.
- Resolves #247. The fragile
errEmptyResponsesentinel is no longer used for retry decisions.