5 KiB
ADR-012: SearXNGSearcher.Close Cancels In-Flight Searches
Status: Accepted Date: 2026-06-07
Context
SearXNGSearcher.Close() previously only released idle HTTP connections owned
by the searcher. Active Search() calls could continue until their caller
context, HTTP timeout, retry loop, or upstream response completed.
That behavior made shutdown ambiguous: closing a searcher did not provide a
direct way to stop work already in progress, and retry backoff could continue
after the searcher had been closed. A first implementation used a stored
context.Context and context.CancelFunc on SearXNGSearcher, but that
introduced two problems:
- The production struct stored a context, which violates the repository's
containedctxlint policy. - Tests and other internal code sometimes construct
SearXNGSearcherliterals directly. Those literals could leave the stored context nil and make cancellation hooks fragile.
Decision
SearXNGSearcher owns an internal done chan struct{} plus sync.Once for
shutdown signaling.
NewSearXNGSearcherinitializesdone.Close()closesdoneonce and still closes idle connections only for owned transports.Search()derives a per-call context from the caller context and cancels it whendonecloses.- Search attempts, retry decisions, and retry backoff waits all use the derived search context.
Rationale
- Close has an observable shutdown contract. After
Close()is called, in-flight searches should stop instead of waiting for upstream completion. - Caller cancellation still wins normally. Each
Search()still starts from the caller-provided context; the searcher close signal is an additional cancellation source. - No stored context fields. A plain channel avoids the
containedctxlint issue and keeps the shutdown state independent from request contexts. - Idempotent close.
sync.Oncekeeps repeatedClose()calls safe.
Consequences
Close()now cancels active searches. Callers may observecontext.Canceledfrom aSearch()that was in flight when the searcher was closed.- Retry and empty-response backoff paths now stop promptly after
Close(). - Tests that construct
SearXNGSearcherdirectly and callSearch()must initializedone, or useNewSearXNGSearcher/ shared test helpers. Close()remains safe for searchers using a shared default client because it still closes idle transport connections only when the searcher owns the transport.
Amendment (2026-07-20): Context-Based Close Lifecycle
Background
During implementation, the done channel design was replaced with a context-based
approach that the codebase now uses:
SearXNGSearcherowns a lifecyclecontext.Contextandcontext.CancelFunccreated byNewSearXNGSearcher(searcher.go:38-39,132).Close()callssearcherCancelexactly once viasync.Once(searcher.go:185).- Each
Search()derives a per-call context and usescontext.AfterFuncto propagate searcher closure to in-flight searches without a dedicated watcher goroutine (searcher.go:292-303). - Retry backoff uses
retryWaitwhich respects context cancellation, so close during backoff returns immediately.
Why the change supersedes the original decision
- No per-search goroutine overhead.
context.AfterFuncregisters a callback that runs in a goroutine only when the lifecycle context is actually canceled — zero cost in the happy path. - Familiar Go idiom. Context cancellation is the standard way to signal shutdown, making the design more recognizable to contributors.
- Simpler ownership. The lifecycle context is created once at construction
and canceled once at close; there is no channel to initialize, select on, or
guard against double-close outside of
sync.Once.
Containedctx suppression
The SearXNGSearcher struct carries //nolint:containedctx because the lifecycle
context represents object lifecycle, not request-scoped data. The stored
searcherCtx is analogous to the ctx field in exec.Command or sql.DB — an
architectural invariant initialized at construction and unchanged for the life of
the value. The narrow suppression is intentional and acceptable.
Constructor invariant
Production and integration code must construct SearXNGSearcher through
NewSearXNGSearcher, which initializes the lifecycle context. Tests that exercise
Search or Close also use the canonical constructor with a custom HTTP client;
internal white-box tests may adjust a narrow retry-control seam after construction
to keep timing deterministic. Direct struct literals in internal tests are
permitted only when they do not call lifecycle-dependent methods, or when a
defensive nil guard deliberately exercises that case (see searchContext).
External contract preserved
Closeremains idempotent (backed bysync.Once).Closecancels in-flight searches and retry backoff waits.Closestill releases idle HTTP connections only for owned transports.- No behavior change was introduced to update this ADR.