Setup CollectionSearchExtension and FreeTextAdvancedExtension

CHANGES.md

@@ -3,6 +3,51 @@
 [Unreleased](https://github.com/crim-ca/stac-app/tree/master)
 ------------------------------------------------------------------------------------------------------------------
 
+# Changed
+
+- Add `CollectionSearchExtension` base class to support the `pgstac` `collection_search` operator 
+  for `GET /collections` request.
+
+  _**NOTE**_: <br>
+  Because this extension relies on a specific SQL function `collection_search` and its adjusted feature
+  for parameter `q`, [`pgstac>=0.9.2`](https://stac-utils.github.io/pgstac/release-notes/#v092) is required. This
+  means the underlying PostgreSQL version **MUST** be migrated to 17.
+
+  _**NOTE**_: <br>
+  The `CollectionSearchPostExtension` is *purposely* omitted as it would conflict with the `Transaction` extension
+  that both uses the same `POST /collections` endpoint for search and collection creation respectively.
+
+- Extended search parameters using `FreeTextAdvancedExtension` to allow
+  free-form `q` parameter text search of the collection or its items
+  across `description`, `title`, `keywords`.
+
+  The ["advanced"](https://github.com/stac-api-extensions/freetext-search?tab=readme-ov-file#advanced) portion of
+  the extension allows additional operators such as `OR`, `AND`, `+`, `-` and `()` within the text search to form
+  complex search criteria.
+
+  To ease user experience, ["basic"](https://github.com/stac-api-extensions/freetext-search?tab=readme-ov-file#basic)
+  free-text search is also supported seamlessly, to allow simpler queries. Normally, both extensions would conflict
+  between each other using the same `q` parameter, but little additional logic makes it possible to support both.
+
+  Enabled requests using `q`:
+
+    - `POST /search` with `{"q": ["term", "other"]}` (basic free-text search form)
+    - `POST /search` with `{"q": "term OR other"}` (advanced free-text search form)
+    - `GET /search?q=term,other`
+    - `GET /search?q=term OR other`
+    - `GET /collections?q=term,other`
+    - `GET /collections?q=term OR other`
+    - `GET /collections/{collectionId}/items?q=term,other`
+    - `GET /collections/{collectionId}/items?q=term OR other`
+
+  For the same `Transaction` extension reason as above, `POST` cannot be used elsewhere than on `/search` endpoint.
+
+- Extended search parameters using `FreeTextAdvancedExtension` to allow
+
+- Enabled `Settings(validate_extensions=True)` when configuring the `StacAPI` application.
+  This ensures that, when a STAC Collection or Item is POST'ed to the API, all the `stac_extensions` that it declares
+  will also be validated against their respective schemas, rather than limiting itself only to core STAC definitions.
+
 # Fixed
 
 - Fix breaking PG connection setting when using ``stac-fastapi>=6``.

requirements.txt

@@ -1,3 +1,3 @@
-stac-fastapi.api==5.2.0
-stac-fastapi.pgstac==5.0.2
-uvicorn==0.34.2
+stac-fastapi.api==6.0.0
+stac-fastapi.pgstac[validation]==6.0.0
+uvicorn==0.35.0

src/stac_app.py

@@ -1,83 +1,190 @@
 """FastAPI application using PGStac."""
 
-# Based on stac-fastapi/stac_fastapi/pgstac/stac_fastapi/pgstac/app.py
+# Based on https://github.com/stac-utils/stac-fastapi-pgstac/blob/main/stac_fastapi/pgstac/app.py
 import logging
 import os
 import time
-from typing import Optional, Type, cast
+from typing import Annotated, Optional, Type, Union, cast
 
 import asyncpg
 from buildpg import render
 from fastapi import APIRouter, HTTPException, Request, Response
 from fastapi.responses import ORJSONResponse
 from packaging.version import Version
+from pydantic import BaseModel, Field
+from pydantic.functional_serializers import PlainSerializer
 from stac_fastapi.api.app import StacApi
 from stac_fastapi.api.models import (
     ItemCollectionUri,
     create_get_request_model,
     create_post_request_model,
-    create_request_model,
 )
 from stac_fastapi.api.version import __version__ as stac_fastapi_version
 from stac_fastapi.extensions.core import (
+    CollectionSearchFilterExtension,
     FieldsExtension,
     FilterExtension,
+    ItemCollectionFilterExtension,
     PaginationExtension,
     QueryExtension,
     SortExtension,
     TokenPaginationExtension,
     TransactionExtension,
 )
+from stac_fastapi.extensions.core.collection_search import CollectionSearchExtension
+from stac_fastapi.extensions.core.fields import FieldsConformanceClasses
+from stac_fastapi.extensions.core.free_text import FreeTextAdvancedExtension, FreeTextConformanceClasses
+from stac_fastapi.extensions.core.query import QueryConformanceClasses
+from stac_fastapi.extensions.core.sort import SortConformanceClasses
 from stac_fastapi.pgstac.config import Settings
 from stac_fastapi.pgstac.core import CoreCrudClient
 from stac_fastapi.pgstac.db import close_db_connection, connect_to_db
 from stac_fastapi.pgstac.extensions.filter import FiltersClient
 from stac_fastapi.pgstac.transactions import TransactionsClient
 from stac_fastapi.pgstac.types.search import PgstacSearch
-from stac_fastapi.types.search import APIRequest
+from stac_fastapi.types.search import APIRequest, BaseSearchGetRequest, BaseSearchPostRequest
 
 # hijack uvicorn's logger (otherwise log messages won't be visible)
 logger = logging.getLogger("uvicorn.error")
 
-settings = Settings()
+settings = Settings(validate_extensions=True)
 settings.openapi_url = os.environ.get("OPENAPI_URL", "/api")
 settings.docs_url = os.environ.get("DOCS_URL", "/api.html")
 
-items_get_request_model = cast(
-    Type[APIRequest],
-    create_request_model(
-        "ItemCollectionURI",
-        base_model=ItemCollectionUri,
-        mixins=[TokenPaginationExtension().GET],
+
+class FreeTextCombinedExtensionPostRequest(BaseModel):
+    """Free-text Extension POST request model allowing for either Basic or Advanced formats."""
+
+    q: Annotated[
+        Optional[Union[str, list[str]]],
+        PlainSerializer(
+            lambda x: " OR ".join(x) if isinstance(x, list) else x,
+            return_type=str,
+            when_used="json",
+        ),
+    ] = Field(
+        None,
+        description=(
+            "Parameter to perform free-text queries against STAC metadata. "
+            "Basic free-text search is performed when using an array of words. "
+            "Advanced free-text search is performed when using a string containing the expression."
+        ),
+    )
+
+
+class FreeTextCombinedExtension(FreeTextAdvancedExtension):
+    """Free-Text Search extension that allows simultaneous use of Basic and Advanced formats."""
+
+    # POST needs override to deal with basic:list[str] vs advanced:str
+    # GET uses 'q: str' for both basic and advanced
+    POST = FreeTextCombinedExtensionPostRequest
+
+
+# /search
+search_extensions = [
+    QueryExtension(),
+    SortExtension(),
+    FieldsExtension(),
+    FreeTextCombinedExtension(
+        conformance_classes=[
+            # both basic/advanced are handled simultaneously with the same query parameters and their respective formats
+            # however, only one of the extension class is added explicitly to avoid parameter conflict when loading the API
+            FreeTextConformanceClasses.SEARCH,
+            FreeTextConformanceClasses.SEARCH_ADVANCED,
+        ]
     ),
+    FilterExtension(client=FiltersClient()),
+    PaginationExtension(),
+]
+search_get_request_model = cast(
+    Union[Type[APIRequest], Type[BaseSearchGetRequest]], create_get_request_model(search_extensions)
+)
+search_post_request_model = cast(
+    Union[Type[APIRequest], Type[BaseSearchPostRequest]],
+    create_post_request_model(search_extensions, base_model=PgstacSearch),
 )
 
-extensions = [
+# object creation/update/delete operations
+transaction_extensions = [
     TransactionExtension(
         client=TransactionsClient(),
         settings=settings,
         response_class=ORJSONResponse,
     ),
-    QueryExtension(),
-    SortExtension(),
-    FieldsExtension(),
-    FilterExtension(client=FiltersClient()),
+]
+
+# /collections
+collection_base_extensions = [
+    QueryExtension(conformance_classes=[QueryConformanceClasses.COLLECTIONS]),
+    SortExtension(conformance_classes=[SortConformanceClasses.COLLECTIONS]),
+    FieldsExtension(conformance_classes=[FieldsConformanceClasses.COLLECTIONS]),
+    FreeTextAdvancedExtension(
+        conformance_classes=[
+            # both basic/advanced are handled simultaneously with the same query parameters and their respective formats
+            # however, only one of the extension class is added explicitly to avoid parameter conflict when loading the API
+            FreeTextConformanceClasses.COLLECTIONS,
+            FreeTextConformanceClasses.COLLECTIONS_ADVANCED,
+        ]
+    ),
+    TokenPaginationExtension(),
+]
+# NOTE:
+#   Using only the 'GET /collections' for search, since 'POST /collections' search
+#   would conflict with Transaction extension to create/update/delete collections.
+collection_search_extension = CollectionSearchExtension.from_extensions(
+    collection_base_extensions
+    + [
+        CollectionSearchFilterExtension(client=FiltersClient()),
+    ],
+)
+# collection_search_extension = CollectionSearchPostExtension.from_extensions(  # GET + POST
+#     collection_base_extensions,
+#     client=CollectionSearchPostClient(),
+#     settings=settings,
+# )
+collections_get_request_model = cast(
+    Union[Type[APIRequest], Type[CollectionSearchExtension]], collection_search_extension.GET
+)
+collection_extensions = collection_base_extensions + [collection_search_extension]
+
+# /collections/{collectionID}/items
+items_extensions = [
+    QueryExtension(conformance_classes=[QueryConformanceClasses.ITEMS]),
+    SortExtension(conformance_classes=[SortConformanceClasses.ITEMS]),
+    FieldsExtension(conformance_classes=[FieldsConformanceClasses.ITEMS]),
+    FreeTextAdvancedExtension(
+        conformance_classes=[
+            # both basic/advanced are handled simultaneously with the same query parameters and their respective formats
+            # however, only one of the extension class is added explicitly to avoid parameter conflict when loading the API
+            FreeTextConformanceClasses.ITEMS,
+            FreeTextConformanceClasses.ITEMS_ADVANCED,
+        ]
+    ),
+    ItemCollectionFilterExtension(client=FiltersClient()),
     TokenPaginationExtension(),
-    PaginationExtension(),
 ]
+items_get_request_model = cast(
+    Type[APIRequest],
+    create_get_request_model(
+        extensions=items_extensions,
+        base_model=ItemCollectionUri,
+    ),
+)
+
+app_extensions = search_extensions + transaction_extensions + collection_extensions + items_extensions
 
-post_request_model = create_post_request_model(extensions, base_model=PgstacSearch)
 router_prefix = os.environ.get("ROUTER_PREFIX")
 router_prefix_str = router_prefix.rstrip("/") if router_prefix else ""
 
 THIS_DIR = os.path.dirname(os.path.abspath(__file__))
 
 api = StacApi(
     settings=settings,
-    extensions=extensions,
-    client=CoreCrudClient(pgstac_search_model=post_request_model),
-    search_get_request_model=create_get_request_model(extensions),
-    search_post_request_model=post_request_model,
+    extensions=app_extensions,
+    client=CoreCrudClient(pgstac_search_model=search_post_request_model),
+    search_get_request_model=search_get_request_model,
+    search_post_request_model=search_post_request_model,
+    collections_get_request_model=collections_get_request_model,
     items_get_request_model=items_get_request_model,
     response_class=ORJSONResponse,
     title=(os.getenv("STAC_FASTAPI_TITLE") or "Data Analytics for Canadian Climate Services STAC API"),