Merge branch 'main' into patch/remove-defaults-in-openapi-schema

Author: gadomski

CHANGES.md

@@ -6,6 +6,10 @@
 
 - Remove defaults in OpenAPI schemas
 
+### Added
+
+- add `enable_direct_response` settings to by-pass Pydantic validation and FastAPI serialization for responses
+
 ## [5.1.1] - 2025-03-17
 
 ### Fixed
@@ -373,7 +377,7 @@ Full changelog: https://stac-utils.github.io/stac-fastapi/migrations/v3.0.0/#cha
 ### Added
 
 * Nginx service as second docker-compose stack to demonstrate proxy ([#503](https://github.com/stac-utils/stac-fastapi/pull/503))
-* Validation checks in CI using [stac-api-validator](github.com/stac-utils/stac-api-validator) ([#508](https://github.com/stac-utils/stac-fastapi/pull/508))
+* Validation checks in CI using [stac-api-validator](https://github.com/stac-utils/stac-api-validator) ([#508](https://github.com/stac-utils/stac-fastapi/pull/508))
 * Required links to the sqlalchemy ItemCollection endpoint ([#508](https://github.com/stac-utils/stac-fastapi/pull/508))
 * Publication of docker images to GHCR ([#525](https://github.com/stac-utils/stac-fastapi/pull/525))
 

Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.11-slim as base
+FROM python:3.12-slim AS base
 
 # Any python libraries that require system libraries to be installed will likely
 # need the following packages in order to build
@@ -10,12 +10,13 @@ RUN apt-get update && \
 
 ENV CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
 
-FROM base as builder
+FROM base AS builder
 
 WORKDIR /app
 
 COPY . /app
 
-RUN python -m pip install -e ./stac_fastapi/types[dev] && \
-    python -m pip install -e ./stac_fastapi/api[dev] && \
-    python -m pip install -e ./stac_fastapi/extensions[dev]
+RUN python -m pip install \
+    -e ./stac_fastapi/types[dev] \
+    -e ./stac_fastapi/api[dev] \
+    -e ./stac_fastapi/extensions[dev]

Dockerfile.docs

@@ -1,7 +1,9 @@
-FROM python:3.11-slim
+FROM python:3.12-slim
 
 # build-essential is required to build a wheel for ciso8601
-RUN apt update && apt install -y build-essential
+RUN apt update && apt install -y build-essential && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
 
 RUN python -m pip install --upgrade pip
 

Makefile

@@ -11,12 +11,12 @@ install:
 
 .PHONY: docs-image
 docs-image:
-	docker compose -f docker-compose.docs.yml \
+	docker compose -f compose.docs.yml \
 		build
 
 .PHONY: docs
 docs: docs-image
-	docker compose -f docker-compose.docs.yml \
+	docker compose -f compose.docs.yml \
 		run docs
 
 .PHONY: test

README.md

@@ -1,7 +1,7 @@
 <!-- markdownlint-disable MD033 MD041 -->
 
 <p align="center">
-  <img src="https://github.com/radiantearth/stac-site/raw/master/images/logo/stac-030-long.png" width=400>
+  <img src="https://github.com/radiantearth/stac-site/raw/master/images/logo/stac-030-long.png" width=400 alt="SpatioTemporal Asset Catalog (STAC) logo">
   <p align="center">FastAPI implemention of the STAC API spec.</p>
 </p>
 <p align="center">
@@ -21,25 +21,35 @@
 
 ---
 
-Python library for building a STAC compliant FastAPI application.  The project is split up into several namespace
-packages:
+Python library for building a STAC-compliant FastAPI application.  
 
-| Package |  Description | Version
-| ------- |------------- | -------
-[**stac_fastapi.api**](https://github.com/stac-utils/stac-fastapi/tree/main/stac_fastapi/api) | An API layer which enforces the [stac-api-spec](https://github.com/radiantearth/stac-api-spec). | [![stac-fastapi.api](https://img.shields.io/pypi/v/stac-fastapi.api?color=%2334D058&label=pypi)](https://pypi.org/project/stac-fastapi.api)
-[**stac_fastapi.extensions**](https://github.com/stac-utils/stac-fastapi/tree/main/stac_fastapi/extensions) | Abstract base classes for [STAC API extensions](https://github.com/radiantearth/stac-api-spec/blob/master/extensions.md) and third-party extensions. | [![stac-fastapi.extensions](https://img.shields.io/pypi/v/stac-fastapi.extensions?color=%2334D058&label=pypi)](https://pypi.org/project/stac-fastapi.extensions)
-[**stac_fastapi.types**](https://github.com/stac-utils/stac-fastapi/tree/main/stac_fastapi/types) | Shared types and abstract base classes used by the library. | [![stac-fastapi.types](https://img.shields.io/pypi/v/stac-fastapi.types?color=%2334D058&label=pypi)](https://pypi.org/project/stac-fastapi.types)
+`stac-fastapi` was initially developed by [arturo-ai](https://github.com/arturo-ai).
+
+The project contains several namespace packages:
+
+| Package |  Description | Version |
+| ------- |------------- | ------- |
+| [**stac_fastapi.api**](https://github.com/stac-utils/stac-fastapi/tree/main/stac_fastapi/api) | An API layer which enforces the [stac-api-spec](https://github.com/radiantearth/stac-api-spec). | [![stac-fastapi.api](https://img.shields.io/pypi/v/stac-fastapi.api?color=%2334D058&label=pypi)](https://pypi.org/project/stac-fastapi.api) |
+| [**stac_fastapi.extensions**](https://github.com/stac-utils/stac-fastapi/tree/main/stac_fastapi/extensions) | Abstract base classes for [STAC API extensions](https://github.com/radiantearth/stac-api-spec/blob/master/extensions.md) and third-party extensions. | [![stac-fastapi.extensions](https://img.shields.io/pypi/v/stac-fastapi.extensions?color=%2334D058&label=pypi)](https://pypi.org/project/stac-fastapi.extensions) |
+| [**stac_fastapi.types**](https://github.com/stac-utils/stac-fastapi/tree/main/stac_fastapi/types) | Shared types and abstract base classes used by the library. | [![stac-fastapi.types](https://img.shields.io/pypi/v/stac-fastapi.types?color=%2334D058&label=pypi)](https://pypi.org/project/stac-fastapi.types) |
 
 #### Backends
 
-Backends are hosted in their own repositories:
+In addition to the packages in this repository, a server implemention will also require the selection of a backend to
+connect with a database for STAC metadata storage. There are several different backend options, and each has their own
+repository.
 
-- [stac-fastapi-pgstac](https://github.com/stac-utils/stac-fastapi-pgstac): Postgres backend implementation with [PgSTAC](https://github.com/stac-utils/pgstac).
-- [stac-fastapi-elasticsearch](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch): Backend implementation with [Elasticsearch](https://github.com/elastic/elasticsearch).
-- [stac-fastapi-sqlalchemy](https://github.com/stac-utils/stac-fastapi-sqlalchemy): Postgres backend implementation with [sqlalchemy](https://www.sqlalchemy.org/).
+The two most widely-used and supported backends are:
 
-`stac-fastapi` was initially developed by [arturo-ai](https://github.com/arturo-ai).
+- [stac-fastapi-pgstac](https://github.com/stac-utils/stac-fastapi-pgstac): [PostgreSQL](https://github.com/postgres/postgres) + [PostGIS](https://github.com/postgis/postgis) via [PgSTAC](https://github.com/stac-utils/pgstac).
+- [stac-fastapi-elasticsearch-opensearch](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch): [Elasticsearch](https://github.com/elastic/elasticsearch) or [OpenSearch](https://github.com/opensearch-project/OpenSearch)
 
+Other implementations include:
+
+- [stac-fastapi-mongo](https://github.com/Healy-Hyperspatial/stac-fastapi-mongo): [MongoDB](https://github.com/mongodb/mongo)
+- [stac-fastapi-geoparquet)](https://github.com/stac-utils/stac-fastapi-geoparquet): [GeoParquet](https://geoparquet.org) via [stacrs](https://github.com/stac-utils/stacrs) (experimental)
+- [stac-fastapi-duckdb](https://github.com/Healy-Hyperspatial/stac-fastapi-duckdb): [DuckDB](https://github.com/duckdb/duckdb) (experimental)
+- [stac-fastapi-sqlalchemy](https://github.com/stac-utils/stac-fastapi-sqlalchemy): [PostgreSQL](https://github.com/postgres/postgres) + [PostGIS](https://github.com/postgis/postgis) via [SQLAlchemy](https://www.sqlalchemy.org/) (abandoned in favor of stac-fastapi-pgstac)
 
 ## Response Model Validation
 
@@ -51,16 +61,13 @@ To turn on response validation, set `ENABLE_RESPONSE_MODELS` to `True`. Either a
 
 With the introduction of Pydantic 2, the extra [time it takes to validate models became negatable](https://github.com/stac-utils/stac-fastapi/pull/625#issuecomment-2045824578). While `ENABLE_RESPONSE_MODELS` still defaults to `False` there should be no penalty for users to turn on this feature but users discretion is advised.
 
-
 ## Installation
 
 ```bash
 # Install from PyPI
 python -m pip install stac-fastapi.types stac-fastapi.api stac-fastapi.extensions
 
 # Install a backend of your choice
-python -m pip install stac-fastapi.sqlalchemy
-# or
 python -m pip install stac-fastapi.pgstac
 ```
 
@@ -71,14 +78,18 @@ Other backends may be available from other sources, search [PyPI](https://pypi.o
 Install the packages in editable mode:
 
 ```shell
-python -m pip install -e \
-  'stac_fastapi/types[dev]' \
-  'stac_fastapi/api[dev]' \
-  'stac_fastapi/extensions[dev]'
+python -m pip install \
+  -e 'stac_fastapi/types[dev]' \
+  -e 'stac_fastapi/api[dev]' \
+  -e 'stac_fastapi/extensions[dev]'
 ```
 
 To run the tests:
 
 ```shell
 python -m pytest
 ```
+
+## Releasing
+
+See [RELEASING.md](./RELEASING.md).

docker-compose.docs.yml renamed to compose.docs.yml

@@ -2,6 +2,14 @@
 
 This page contains a few 'tips and tricks' for getting **stac-fastapi** working in various situations.
 
+## Avoid FastAPI (slow) serialization
+
+When not using Pydantic validation for responses, FastAPI will still use a complex (slow) [serialization process](https://github.com/fastapi/fastapi/discussions/8165).
+
+Starting with stac-fastapi `5.2.0`, we've added `ENABLE_DIRECT_RESPONSE` option to by-pass the default FastAPI serialization by wrapping the endpoint responses into `starlette.Response` classes.
+
+Ref: https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/issues/347
+
 ## Application Middlewares
 
 By default the `StacApi` class will enable 3 Middlewares (`BrotliMiddleware`, `CORSMiddleware` and `ProxyHeaderMiddleware`). You may want to overwrite the defaults configuration by editing your backend's `app.py`:

docs/src/tips-and-tricks.md

@@ -25,7 +25,12 @@
     ItemUri,
 )
 from stac_fastapi.api.openapi import update_openapi
-from stac_fastapi.api.routes import Scope, add_route_dependencies, create_async_endpoint
+from stac_fastapi.api.routes import (
+    Scope,
+    add_direct_response,
+    add_route_dependencies,
+    create_async_endpoint,
+)
 from stac_fastapi.types.config import ApiSettings, Settings
 from stac_fastapi.types.core import AsyncBaseCoreClient, BaseCoreClient
 from stac_fastapi.types.extension import ApiExtension
@@ -368,7 +373,7 @@ async def ping():
         self.app.include_router(mgmt_router, tags=["Liveliness/Readiness"])
 
     def add_route_dependencies(
-        self, scopes: List[Scope], dependencies=List[Depends]
+        self, scopes: List[Scope], dependencies: List[Depends]
     ) -> None:
         """Add custom dependencies to routes.
 
@@ -425,3 +430,6 @@ def __attrs_post_init__(self) -> None:
         # customize route dependencies
         for scopes, dependencies in self.route_dependencies:
             self.add_route_dependencies(scopes=scopes, dependencies=dependencies)
+
+        if self.app.state.settings.enable_direct_response:
+            add_direct_response(self.app)

stac_fastapi/api/stac_fastapi/api/app.py

@@ -5,13 +5,15 @@
 import inspect
 from typing import Any, Callable, Dict, List, Optional, Type, TypedDict, Union
 
-from fastapi import Depends, params
-from fastapi.dependencies.utils import get_parameterless_sub_dependant
+from fastapi import Depends, FastAPI, params
+from fastapi.datastructures import DefaultPlaceholder
+from fastapi.dependencies.utils import get_dependant, get_parameterless_sub_dependant
+from fastapi.routing import APIRoute
 from pydantic import BaseModel
 from starlette.concurrency import run_in_threadpool
 from starlette.requests import Request
 from starlette.responses import Response
-from starlette.routing import BaseRoute, Match
+from starlette.routing import BaseRoute, Match, request_response
 from starlette.status import HTTP_204_NO_CONTENT
 
 from stac_fastapi.api.models import APIRequest
@@ -86,7 +88,7 @@ class Scope(TypedDict, total=False):
 
 
 def add_route_dependencies(
-    routes: List[BaseRoute], scopes: List[Scope], dependencies=List[params.Depends]
+    routes: List[BaseRoute], scopes: List[Scope], dependencies: List[params.Depends]
 ) -> None:
     """Add dependencies to routes.
 
@@ -131,3 +133,33 @@ def add_route_dependencies(
             # https://github.com/tiangolo/fastapi/blob/58ab733f19846b4875c5b79bfb1f4d1cb7f4823f/fastapi/applications.py#L337-L360
             # https://github.com/tiangolo/fastapi/blob/58ab733f19846b4875c5b79bfb1f4d1cb7f4823f/fastapi/routing.py#L677-L678
             route.dependencies.extend(dependencies)
+
+
+def add_direct_response(app: FastAPI) -> None:
+    """
+    Setup FastAPI application's endpoints to return Response Object directly, avoiding
+    Pydantic validation and FastAPI (slow) serialization.
+
+    ref: https://gist.github.com/Zaczero/00f3a2679ebc0a25eb938ed82bc63553
+    """
+
+    def wrap_endpoint(endpoint: Callable, cls: Type[Response]):
+        @functools.wraps(endpoint)
+        async def wrapper(*args, **kwargs):
+            content = await endpoint(*args, **kwargs)
+            return content if isinstance(content, Response) else cls(content)
+
+        return wrapper
+
+    for route in app.routes:
+        if not isinstance(route, APIRoute):
+            continue
+
+        response_class = route.response_class
+        if isinstance(response_class, DefaultPlaceholder):
+            response_class = response_class.value
+
+        if issubclass(response_class, Response):
+            route.endpoint = wrap_endpoint(route.endpoint, response_class)
+            route.dependant = get_dependant(path=route.path_format, call=route.endpoint)
+            route.app = request_response(route.get_route_handler())

stac_fastapi/api/stac_fastapi/api/routes.py

@@ -108,6 +108,31 @@ def get_item(self, item_id: str, collection_id: str, **kwargs) -> stac.Item:
         assert item.status_code == 200, item.text
 
 
+def test_client_response_by_pass(TestCoreClient, item_dict):
+    """Check with `enable_direct_response` option."""
+
+    class InValidResponseClient(TestCoreClient):
+        def get_item(self, item_id: str, collection_id: str, **kwargs) -> stac.Item:
+            item_dict.pop("bbox", None)
+            item_dict.pop("geometry", None)
+            return item_dict
+
+    test_app = app.StacApi(
+        settings=ApiSettings(
+            enable_response_models=False,
+            enable_direct_response=True,
+        ),
+        client=InValidResponseClient(),
+    )
+
+    with TestClient(test_app.app) as client:
+        item = client.get("/collections/test/items/test")
+
+    assert item.json()
+    assert item.status_code == 200
+    assert item.headers["content-type"] == "application/geo+json"
+
+
 def test_client_openapi(TestCoreClient):
     """Test if response models are all documented with OpenAPI."""