fix: validate time range support for explicit engines

[sawork1987]

Summary

• validate time_range against each explicitly selected engine's live /config capability
• reject incompatible or unknown engine capabilities before sending a misleading search request
• keep requests without explicit engines unchanged
• document the fail-closed behavior in the tool schema

Problem

SearXNG intentionally skips an engine when a request supplies time_range but that engine reports time_range_support=false. With one explicitly selected engine, for example:

engines=github&time_range=year

SearXNG does not run the GitHub engine and returns an ordinary empty result without an unresponsive-engine error. The adapter currently forwards this parameter combination unchanged, so callers cannot distinguish "no matching repositories" from "the selected engine was skipped".

Behavior

• explicit engines all report time_range_support=true: search runs unchanged
• any explicit engine reports false or omits the capability: request fails before search with an actionable explanation
• /config unavailable: request fails rather than presenting an unchecked empty result
• no explicit engines, or no time_range: existing behavior remains unchanged

The adapter does not silently remove time_range and does not rewrite the query into engine-specific syntax.

Verification

• full test suite: 708/708 passed
• TypeScript build passed
• git diff --check passed
• regression tests verify unsupported, supported, unavailable, and unknown capability paths

🤖 Generated with Claude Code

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 28 complexity · 14 duplication

Metric	Results
Complexity	28
Duplication	14

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[Copilot]

Pull request overview

This PR prevents misleading “empty result” responses when callers explicitly select engines together with time_range by validating each selected engine’s time-range capability via the SearXNG /config endpoint and failing closed when support can’t be confirmed.

Changes:

• Adds a pre-search validation step that checks time_range_support for explicitly selected engines and rejects incompatible/unknown capability combinations.
• Extends instance capability discovery with getEngineTimeRangeSupport() to classify requested engines as supported/unsupported/unknown.
• Updates tool schema documentation and adds unit/regression coverage for supported, unsupported, and /config-unavailable paths.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/types.ts	Documents the new fail-closed behavior in the tool and time_range parameter descriptions.
src/search.ts	Adds validateTimeRangeSupport() and enforces it before executing searches when engines + time_range are provided.
src/instance-info.ts	Introduces engine-specific time_range_support capability resolution from aggregated /config data.
tests/unit/types.test.ts	Verifies schema/description text reflects the new validation behavior.
tests/unit/search.test.ts	Adds regression tests for supported/unsupported engines and /config unavailable behavior.
tests/unit/instance-info.test.ts	Adds unit test for getEngineTimeRangeSupport() classification behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ihor-sokoliuk]

Thanks for the contribution. I reviewed the exact current head (16232ca) and the completed AI review. Copilot’s one inline finding is valid and matches the blocking correctness issue.

Before this can be considered ready for another review, please:

1. Make the multi-instance check fail closed. getEngineTimeRangeSupport() currently evaluates only result.configs and ignores result.failures whenever at least one /config request succeeds. In failover or fan-out mode, that can accept the request even though another instance that may serve it never confirmed time-range support. Require confirmation from every possible serving instance, or bind validation to the exact instance set that will execute the search.
2. Add regression coverage for partial capability discovery: at least one instance reports time_range_support=true while another configured instance’s /config request fails. Cover the applicable failover and fan-out behavior and prove that no search is sent through an unverified instance.
3. Update the public README documentation for searxng_web_search—particularly engines and time_range—so it describes the new fail-closed rule and its multi-instance behavior. The current README still says engine values are forwarded when /config is unavailable.
4. Push the fixes together, reply to the inline AI-review thread with the commit and verification evidence, and let me know when the new exact-head checks have completed for re-review.

All checks on the current head are green, but they do not exercise the partial-/config multi-instance case above. This is a fix-first review note, not an approval or merge decision.

[ihor-sokoliuk]

@sawork1987 Thanks again for contributing this. The changes requested in the existing review are still needed before the PR can move forward, particularly the fail-closed multi-instance handling, regression coverage, and README update.
Please push the requested changes within the next seven days, or leave a brief comment if you need more time. If I don’t receive an update, I’ll close the PR to keep the review queue manageable. I’ll preserve the underlying work in the project backlog as the appropriate bug or feature item, so the idea and context aren’t lost.
I’ll be happy to review a consolidated update once it’s ready.

[sawork1987]

Pushed consolidated update in commit 4c896e7.

Implemented the requested fail-closed multi-instance handling: when any configured instance fails /config discovery, explicit engines + time_range validation classifies all selected engines as unknown and rejects before /search.

Added regression coverage for:

• partial /config failure classification;
• rejection before search, asserting no /search request is sent.

Updated README with the multi-instance capability requirement and failure behavior.

Verification:

• instance-info: 24/24 passed;
• search: 122/122 passed;
• TypeScript build passed;
• git diff --check passed;
• npm audit: 0 vulnerabilities.

The full suite has one unrelated pre-existing failure in the proxy test NO_PROXY lowercase env var; all tests covering this PR pass. Ready for re-review.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[ihor-sokoliuk]

Awesome PR! Thanks for your contribution!