feat(search): add GET /search/facets.json — context-aware facet values API (#12980)

Co-authored-by: RayBB <RayBB@users.noreply.github.com>

Author: mekarpeles

openlibrary/fastapi/search.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import os
 from collections.abc import Mapping
 from typing import Annotated, Any, Literal, Self
 
@@ -37,6 +38,28 @@
 
 router = APIRouter()
 
+# Facet fields exposed by /search/facets.json — mirrors WorkSearchScheme.facet_fields
+FacetField = Literal[
+    "author_facet",
+    "first_publish_year",
+    "has_fulltext",
+    "language",
+    "person_facet",
+    "place_facet",
+    "public_scan_b",
+    "publisher_facet",
+    "subject_facet",
+    "time_facet",
+]
+
+# process_facet_counts renames author_facet → author_key internally; map back so
+# the response key always matches the caller's requested field name.
+_FACET_INTERNAL_RENAME = {"author_key": "author_facet"}
+
+# Whether to expose internal-only endpoints in the OpenAPI schema.
+# Only shown when running with LOCAL_DEV set (e.g. docker compose).
+SHOW_INTERNAL_IN_SCHEMA = os.getenv("LOCAL_DEV") is not None
+
 
 class PublicQueryOptions(BaseModel):
     """
@@ -141,6 +164,14 @@ def selected_query(self) -> dict[str, Any]:
             return q
 
 
+class FacetValue(BaseModel):
+    """A single facet option returned by /search/facets.json."""
+
+    value: str = Field(description="Filter value to pass back to /search.json (e.g. 'eng', 'OL9A')")
+    label: str = Field(description="Human-readable display label — differs from value for author_facet")
+    count: int = Field(description="Number of matching works")
+
+
 class SearchResponse(BaseModel):
     """The response from a (books) search query."""
 
@@ -348,3 +379,51 @@ async def search_authors_json(
         doc["key"] = doc["key"].split("/")[-1]
 
     return raw_resp
+
+
+@router.get(
+    "/search/facets.json",
+    tags=["internal"],
+    include_in_schema=SHOW_INTERNAL_IN_SCHEMA,
+    response_model=dict[str, list[FacetValue]],
+)
+async def search_facets_json(
+    request: Request,
+    params: Annotated[PublicQueryOptions, Depends()],
+    field: Annotated[
+        list[FacetField],
+        Query(min_length=1, description="Facet field(s) to return. Repeat for multiple."),
+    ],
+    solr_internals_params: Annotated[SolrInternalsParams | None, Depends(SolrInternalsParams.from_request)] = None,
+) -> dict[str, list[FacetValue]]:
+    """
+    Returns context-aware facet values for one or more search facet fields.
+
+    Queries Solr with rows=0 alongside the current search params, returning only
+    values with count > 0, ordered by count descending. Designed to power the
+    OlSelectPopover components in the search results filter bar (PR #12949).
+
+    Example: GET /search/facets.json?field=language&field=subject_facet&q=lord+of+the+rings
+    """
+    search_response = await run_solr_query_async(
+        WorkSearchScheme(lang=request.state.lang),
+        params.model_dump(exclude_none=True),
+        rows=0,
+        page=1,
+        facet=list(field),
+        highlight=False,
+        request_label="BOOK_SEARCH_FACETS",
+        solr_internals_params=solr_internals_params,
+    )
+
+    result: dict[str, list[FacetValue]] = {f: [] for f in field}
+    if search_response.facet_counts:
+        for facet_field, values in search_response.facet_counts.items():
+            output_key = _FACET_INTERNAL_RENAME.get(facet_field, facet_field)
+            if output_key not in result:
+                continue
+            # values are (filter_value, display_label, count) tuples; label differs
+            # from value for author_facet (name vs OL key) and "Name|key" subject fields.
+            result[output_key] = [FacetValue(value=value, label=label, count=count) for value, label, count in values if count > 0]
+
+    return result

openlibrary/tests/fastapi/conftest.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """Shared pytest fixtures for FastAPI and API contract tests."""
 
 from unittest.mock import patch
@@ -148,6 +150,44 @@ def _default_search_response():
     }
 
 
+@pytest.fixture
+def mock_run_solr_query_async():
+    """Mock run_solr_query_async to avoid actual Solr calls.
+
+    Used by FastAPI search/facets endpoint tests.
+    Returns a SearchResponse with sample facet_counts.
+    """
+    with patch("openlibrary.fastapi.search.run_solr_query_async", autospec=True) as mock:
+        mock.return_value = _default_facets_response()
+        yield mock
+
+
+def _default_facets_response():
+    """Default mock SearchResponse for facets tests."""
+    return SearchResponse(
+        # process_facet_counts renames author_facet → author_key in this dict
+        facet_counts={
+            "language": [
+                ("eng", "English", 665),
+                ("deu", "German", 32),
+                ("spa", "Spanish", 18),
+                ("lat", "Latin", 0),  # zero-count entry — should be filtered out
+            ],
+            "author_key": [
+                ("OL9A", "J.R.R. Tolkien", 123),
+            ],
+            "subject_facet": [
+                ("Fantasy", "Fantasy", 89),
+            ],
+        },
+        sort="",
+        docs=[],
+        num_found=0,
+        raw_resp={"response": {"docs": []}},
+        solr_select="mock",
+    )
+
+
 def _default_subjects_response():
     """Default mock response for subjects search."""
 

openlibrary/tests/fastapi/test_search.py

@@ -1,11 +1,14 @@
+from __future__ import annotations
+
 """Basic tests for the FastAPI search endpoint."""
 
 import json
+from typing import get_args
 from urllib.parse import urlencode
 
 import pytest
 
-from openlibrary.fastapi.search import PublicQueryOptions
+from openlibrary.fastapi.search import FacetField, PublicQueryOptions
 from openlibrary.plugins.worksearch.code import WorkSearchScheme
 
 
@@ -391,3 +394,69 @@ def test_debug_openapi_structure(self, client):
 
         # This test always passes - it's just for debug output
         assert True
+
+
+class TestSearchFacetsEndpoint:
+    """Tests for the /search/facets.json endpoint."""
+
+    def test_requires_field_param(self, fastapi_client, mock_run_solr_query_async):
+        response = fastapi_client.get("/search/facets.json?q=tolkien")
+        # FastAPI enforces required + min_length=1 on `field`, returns 422 when absent
+        assert response.status_code == 422
+        detail = response.json()["detail"]
+        assert any("field" in err["loc"] for err in detail)
+
+    def test_rejects_invalid_field(self, fastapi_client, mock_run_solr_query_async):
+        response = fastapi_client.get("/search/facets.json?field=notafield&q=tolkien")
+        # FastAPI validates FacetField Literal and returns 422 for unknown values
+        assert response.status_code == 422
+        detail = response.json()["detail"]
+        assert any(err.get("input") == "notafield" for err in detail)
+
+    def test_returns_facet_values_for_single_field(self, fastapi_client, mock_run_solr_query_async):
+        response = fastapi_client.get("/search/facets.json?field=language&q=lord+of+the+rings")
+        assert response.status_code == 200
+        data = response.json()
+        assert "language" in data
+        values = data["language"]
+        assert len(values) > 0
+        assert all("value" in v and "count" in v and "label" in v for v in values)
+        assert values[0] == {"value": "eng", "label": "English", "count": 665}
+
+    def test_filters_zero_count_values(self, fastapi_client, mock_run_solr_query_async):
+        response = fastapi_client.get("/search/facets.json?field=language&q=tolkien")
+        assert response.status_code == 200
+        data = response.json()
+        # "Latin" (code "lat") has count=0 in the mock — must not appear
+        assert not any(v["value"] == "lat" for v in data["language"])
+        assert all(v["count"] > 0 for v in data["language"])
+
+    def test_returns_multiple_fields(self, fastapi_client, mock_run_solr_query_async):
+        response = fastapi_client.get("/search/facets.json?field=language&field=subject_facet&q=tolkien")
+        assert response.status_code == 200
+        data = response.json()
+        assert "language" in data
+        assert "subject_facet" in data
+
+    def test_author_facet_key_maps_to_author_facet(self, fastapi_client, mock_run_solr_query_async):
+        """Response key should be 'author_facet' even though Solr returns 'author_key' internally."""
+        response = fastapi_client.get("/search/facets.json?field=author_facet&q=tolkien")
+        assert response.status_code == 200
+        data = response.json()
+        assert "author_facet" in data
+        assert "author_key" not in data
+        assert data["author_facet"] == [{"value": "OL9A", "label": "J.R.R. Tolkien", "count": 123}]
+
+    def test_empty_query_returns_valid_response(self, fastapi_client, mock_run_solr_query_async):
+        """No q param should still return a valid (unfiltered) facet list."""
+        response = fastapi_client.get("/search/facets.json?field=language")
+        assert response.status_code == 200
+        assert "language" in response.json()
+
+    def test_facet_field_literal_matches_scheme(self):
+        """FacetField Literal must stay in sync with WorkSearchScheme.facet_fields.
+
+        Guards against drift: if a facet field is added/removed upstream, this
+        fails so the endpoint doesn't silently 422 on (or miss) it.
+        """
+        assert set(get_args(FacetField)) == WorkSearchScheme.facet_fields