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

93 lines
4.8 KiB
Markdown

# 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.