searxng-mcp-go/docs/adr/014-retry-outcome-enum.md
XLion 1afa9612c3
docs: align documentation with code behavior (issues #547-#551) (#554)
* 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.
2026-08-11 05:20:47 +08:00

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:

  • ShouldRetry now accepts outcome Outcome instead of resp *http.Response and err error. The strategy is purely outcome-driven.
  • isRetryableError is removed; classifyOutcome replaces its logic.
  • errEmptyResponse is renamed to errSearchEmptyResults (last-error path only; no longer used for retry decisions).
  • The //nolint:gocognit,cyclop,gocyclo suppression on Search() is relocated to the extracted searchWithRetries loop, which still carries the retry orchestration complexity that needs it.
  • Three helpers (searchContext, wrapSearchError, classifyAttempt) are extracted to keep Search() 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 OutcomeEmptyExhausted to the Outcome enum.
  • classifyOutcome returns OutcomeEmptyExhausted when isEmpty && attempt >= maxRetries (empty response with no retries remaining).
  • ShouldRetry treats OutcomeEmptyExhausted as non-retryable (returns false), consistent with its final-attempt semantics.
  • Search() handles OutcomeEmptyExhausted after OutcomeSuccess. The two values are mutually exclusive (a response cannot be both exhausted and successful), so the check order is just a convention.
  • errSearchEmptyResults is 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 the Outcome switch.
  • Simpler Search loop. Single ShouldRetry call instead of two. No fake error, no duplicated wait/continue logic.
  • New exported type. Outcome is exported from searxng package. Five values: OutcomeSuccess, OutcomeRetry, OutcomeEmptyRetry, OutcomeAbort, OutcomeEmptyExhausted.
  • Backward compatible behavior. Retry behaviour is preserved for all existing scenarios: plain network errors retry, SearXNGError does 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 errEmptyResponse sentinel is no longer used for retry decisions.