feat: config-based hrefs (#48)

- Closes #46 
- Resolves path relative to the config file
- Includes a switch to using [lifespan
state](https://github.com/Kludex/fastapi-tips?tab=readme-ov-file#6-use-lifespan-state-instead-of-appstate)
- Refactors to add a factory function which makes testing easier

Author: gadomski

data/config.toml

@@ -0,0 +1 @@
+hrefs = ["naip.parquet"]

pyproject.toml

@@ -8,16 +8,15 @@ dependencies = [
     "attr>=0.3.2",
     "fastapi>=0.115.6",
     "geojson-pydantic>=1.2.0",
+    "pydantic>=2.10.4",
     "stac-fastapi-api>=3.0.5",
     "stac-fastapi-extensions>=3.0.5",
     "stac-fastapi-types>=3.0.5",
     "stacrs>=0.4.0",
 ]
 
 [project.optional-dependencies]
-lambda = [
-    "mangum==0.19.0",
-]
+lambda = ["mangum==0.19.0"]
 
 [dependency-groups]
 dev = [
@@ -40,13 +39,8 @@ deploy = [
 
 [tool.mypy]
 strict = true
-files = [
-    "src/**/*.py",
-    "infrastructure/**/*.py"
-]
-exclude = [
-    "infrastructure/aws/cdk.out/.*"
-]
+files = ["src/**/*.py", "infrastructure/**/*.py"]
+exclude = ["infrastructure/aws/cdk.out/.*"]
 plugins = "pydantic.mypy"
 
 [[tool.mypy.overrides]]

src/stac_fastapi/geoparquet/__init__.py

@@ -0,0 +1,113 @@
+import tomllib
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any, AsyncIterator, TypedDict
+
+from fastapi import FastAPI
+from stacrs import DuckdbClient
+
+import stac_fastapi.api.models
+from stac_fastapi.api.app import StacApi
+from stac_fastapi.extensions.core.pagination import OffsetPaginationExtension
+
+from .client import Client
+from .search import SearchGetRequest, SearchPostRequest
+from .settings import Settings, StacFastapiGeoparquetSettings
+
+GetSearchRequestModel = stac_fastapi.api.models.create_request_model(
+    model_name="SearchGetRequest",
+    base_model=SearchGetRequest,
+    mixins=[OffsetPaginationExtension().GET],
+    request_type="GET",
+)
+PostSearchRequestModel = stac_fastapi.api.models.create_request_model(
+    model_name="SearchPostRequest",
+    base_model=SearchPostRequest,
+    mixins=[OffsetPaginationExtension().POST],
+    request_type="POST",
+)
+
+
+class State(TypedDict):
+    """Application state."""
+
+    client: DuckdbClient
+    """The DuckDB client.
+    
+    It's just an in-memory DuckDB connection with the spatial extension enabled.
+    """
+
+    collections: dict[str, dict[str, Any]]
+    """A mapping of collection id to collection."""
+
+    hrefs: dict[str, str]
+    """A mapping of collection id to geoparquet href."""
+
+
+def create_api(settings: Settings | None = None) -> StacApi:
+    if settings is None:
+        settings = Settings()
+
+    if settings.stac_fastapi_geoparquet_href.endswith(".toml"):
+        with open(settings.stac_fastapi_geoparquet_href, "rb") as f:
+            data = tomllib.load(f)
+        stac_fastapi_geoparquet_settings = StacFastapiGeoparquetSettings.model_validate(
+            data
+        )
+        config_directory = Path(settings.stac_fastapi_geoparquet_href).parent
+        hrefs = []
+        for href in stac_fastapi_geoparquet_settings.hrefs:
+            if Path(href).is_absolute():
+                hrefs.append(href)
+            else:
+                hrefs.append(str(config_directory.joinpath(href).resolve()))
+    else:
+        hrefs = [settings.stac_fastapi_geoparquet_href]
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[State]:
+        client = DuckdbClient()
+        collections = dict()
+        href_dict = dict()
+        for href in hrefs:
+            for collection in client.get_collections(href):
+                if collection["id"] in collections:
+                    raise ValueError(
+                        "cannot have two items in the same collection in different "
+                        "geoparquet files"
+                    )
+                else:
+                    collections[collection["id"]] = collection
+                href_dict[collection["id"]] = href
+        yield {
+            "client": client,
+            "collections": collections,
+            "hrefs": href_dict,
+        }
+
+    api = StacApi(
+        settings=Settings(
+            stac_fastapi_landing_id="stac-fastapi-geoparquet",
+            stac_fastapi_title="stac-geoparquet-geoparquet",
+            stac_fastapi_description="A stac-fastapi server backend by stac-geoparquet",
+        ),
+        client=Client(),
+        app=FastAPI(
+            lifespan=lifespan,
+            openapi_url=settings.openapi_url,
+            docs_url=settings.docs_url,
+            redoc_url=settings.docs_url,
+        ),
+        search_get_request_model=GetSearchRequestModel,
+        search_post_request_model=PostSearchRequestModel,
+    )
+    return api
+
+
+__all__ = [
+    "create_api",
+    "Settings",
+    "SearchGetRequest",
+    "SearchPostRequest",
+    "Client",
+]

src/stac_fastapi/geoparquet/client.py

@@ -1,10 +1,11 @@
 import copy
 import json
 import urllib.parse
-from typing import Any
+from typing import Any, cast
 
 from fastapi import HTTPException
 from pydantic import ValidationError
+from stacrs import DuckdbClient
 from starlette.requests import Request
 
 from stac_fastapi.api.models import BaseSearchPostRequest
@@ -18,9 +19,10 @@ class Client(AsyncBaseCoreClient):  # type: ignore
     """A stac-fastapi-geoparquet client."""
 
     async def all_collections(self, *, request: Request, **kwargs: Any) -> Collections:
+        collections = cast(dict[str, dict[str, Any]], request.state.collections)
         return Collections(
             collections=[
-                collection_with_links(c, request) for c in request.app.state.collections
+                collection_with_links(c, request) for c in collections.values()
             ],
             links=[
                 {
@@ -39,25 +41,29 @@ async def all_collections(self, *, request: Request, **kwargs: Any) -> Collectio
     async def get_collection(
         self, *, request: Request, collection_id: str, **kwargs: Any
     ) -> Collection:
-        if collection := next(
-            (c for c in request.app.state.collections if c["id"] == collection_id), None
-        ):
+        collections = cast(dict[str, dict[str, Any]], request.state.collections)
+        if collection := collections.get(collection_id):
             return collection_with_links(collection, request)
         else:
             raise NotFoundError(f"Collection does not exist: {collection_id}")
 
     async def get_item(
         self, *, request: Request, item_id: str, collection_id: str, **kwargs: Any
     ) -> Item:
-        item_collection = request.app.state.client.search(
-            request.app.state.href, ids=[item_id], collections=[collection_id], **kwargs
-        )
-        if len(item_collection["features"]) == 1:
-            return Item(**item_collection["features"][0])
-        else:
-            raise NotFoundError(
-                f"Item does not exist: {item_id} in collection {collection_id}"
+        client = cast(DuckdbClient, request.state.client)
+        hrefs = cast(dict[str, str], request.state.hrefs)
+        if href := hrefs.get(collection_id):
+            item_collection = client.search(
+                href, ids=[item_id], collections=[collection_id], **kwargs
             )
+            if len(item_collection["features"]) == 1:
+                return Item(**item_collection["features"][0])
+            else:
+                raise NotFoundError(
+                    f"Item does not exist: {item_id} in collection {collection_id}"
+                )
+        else:
+            raise NotFoundError(f"Collection does not exist: {collection_id}")
 
     async def get_search(
         self,
@@ -157,10 +163,30 @@ async def search(
         search: BaseSearchPostRequest,
         **kwargs: Any,
     ) -> ItemCollection:
+        client = cast(DuckdbClient, request.state.client)
+        hrefs = cast(dict[str, str], request.state.hrefs)
+
+        hrefs_to_search = set()
+        if search.collections:
+            for collection in search.collections:
+                if href := hrefs.get(collection):
+                    hrefs_to_search.add(href)
+        else:
+            hrefs_to_search.update(hrefs.values())
+
+        if len(hrefs) > 1:
+            raise ValidationError(
+                "Cannot search multiple geoparquet files (don't know how to page)"
+            )
+        elif len(hrefs) == 0:
+            return ItemCollection()
+        else:
+            href = hrefs_to_search.pop()
+
         search_dict = search.model_dump(exclude_none=True)
         search_dict.update(**kwargs)
-        item_collection = request.app.state.client.search(
-            request.app.state.href,
+        item_collection = client.search(
+            href,
             **search_dict,
         )
         num_items = len(item_collection["features"])

src/stac_fastapi/geoparquet/main.py

@@ -1,58 +1,4 @@
-from collections.abc import AsyncIterator
-from contextlib import asynccontextmanager
+from stac_fastapi.geoparquet import create_api
 
-from fastapi import FastAPI
-from stacrs import DuckdbClient
-
-import stac_fastapi.api.models
-from stac_fastapi.api.app import StacApi
-from stac_fastapi.extensions.core.pagination import OffsetPaginationExtension
-
-from .client import Client
-from .search import SearchGetRequest, SearchPostRequest
-from .settings import Settings
-
-settings = Settings()
-
-
-GetSearchRequestModel = stac_fastapi.api.models.create_request_model(
-    model_name="SearchGetRequest",
-    base_model=SearchGetRequest,
-    mixins=[OffsetPaginationExtension().GET],
-    request_type="GET",
-)
-PostSearchRequestModel = stac_fastapi.api.models.create_request_model(
-    model_name="SearchPostRequest",
-    base_model=SearchPostRequest,
-    mixins=[OffsetPaginationExtension().POST],
-    request_type="POST",
-)
-
-
-@asynccontextmanager
-async def lifespan(app: FastAPI) -> AsyncIterator[None]:
-    client = DuckdbClient()
-    collections = client.get_collections(settings.stac_fastapi_geoparquet_href)
-    app.state.href = settings.stac_fastapi_geoparquet_href
-    app.state.collections = collections
-    app.state.client = client
-    yield
-
-
-api = StacApi(
-    settings=Settings(
-        stac_fastapi_landing_id="stac-fastapi-geoparquet",
-        stac_fastapi_title="stac-geoparquet-geoparquet",
-        stac_fastapi_description="A stac-fastapi server backend by stac-geoparquet",
-    ),
-    client=Client(),
-    app=FastAPI(
-        lifespan=lifespan,
-        openapi_url=settings.openapi_url,
-        docs_url=settings.docs_url,
-        redoc_url=settings.docs_url,
-    ),
-    search_get_request_model=GetSearchRequestModel,
-    search_post_request_model=PostSearchRequestModel,
-)
+api = create_api()
 app = api.app

src/stac_fastapi/geoparquet/settings.py

@@ -1,7 +1,17 @@
+from pydantic import BaseModel
+
 from stac_fastapi.types.config import ApiSettings
 
 
 class Settings(ApiSettings):  # type: ignore
     """stac-fastapi-geoparquet settings"""
 
     stac_fastapi_geoparquet_href: str
+    """This can either be the href of a single geoparquet file, or the href of a TOML
+    configuration file.
+    """
+
+
+class StacFastapiGeoparquetSettings(BaseModel):
+    hrefs: list[str]
+    """Geoparquet hrefs"""

tests/conftest.py

@@ -3,13 +3,18 @@
 
 import pytest
 from fastapi.testclient import TestClient
+from pytest import FixtureRequest
 
-import stac_fastapi.geoparquet.main
+import stac_fastapi.geoparquet
+from stac_fastapi.geoparquet import Settings
 
-naip_items = Path(__file__).parents[1] / "data" / "naip.parquet"
+geoparquet_file = Path(__file__).parents[1] / "data" / "naip.parquet"
+toml_file = Path(__file__).parents[1] / "data" / "config.toml"
 
 
-@pytest.fixture()
-async def client() -> AsyncIterator[TestClient]:
-    with TestClient(stac_fastapi.geoparquet.main.app) as client:
+@pytest.fixture(params=[geoparquet_file, toml_file])
+async def client(request: FixtureRequest) -> AsyncIterator[TestClient]:
+    settings = Settings(stac_fastapi_geoparquet_href=str(request.param))
+    api = stac_fastapi.geoparquet.create_api(settings)
+    with TestClient(api.app) as client:
         yield client