enable direct response env variable

Author: jonhealy1

CHANGELOG.md

@@ -16,14 +16,15 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ## [v4.0.0a2] - 2025-04-20
 
 ### Added
-- Enabled `enable_direct_response` to improve response performance by bypassing FastAPI's jsonable_encoder and Pydantic serialization when returning Response objects. This change significantly improves performance for large search responses, as profiled in [this issue](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/issues/347) [#359](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/359)
+- Added support for high-performance direct response mode for both Elasticsearch and Opensearch backends, controlled by the `ENABLE_DIRECT_RESPONSE` environment variable. When enabled (`ENABLE_DIRECT_RESPONSE=true`), endpoints return Starlette Response objects directly, bypassing FastAPI's jsonable_encoder and Pydantic serialization for significantly improved performance on large search responses. **Note:** In this mode, all FastAPI dependencies (including authentication, custom status codes, and validation) are disabled for all routes. Default is `false` for safety. A warning is logged at startup if enabled. See [issue #347](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/issues/347) and [PR #359](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/359).
 
 ### Changed
 - Updated test suite to use `httpx.ASGITransport(app=...)` for FastAPI app testing (removes deprecation warning). [#359](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/359)
 - Updated stac-fastapi parent libraries to 5.2.0. [#359](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/359)
 - Migrated Elasticsearch index template creation from legacy `put_template` to composable `put_index_template` API in `database_logic.py`. This resolves deprecation warnings and ensures compatibility with Elasticsearch 7.x and 8.x. [#359](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/359)
 - Updated all Pydantic models to use `ConfigDict` instead of class-based `Config` for Pydantic v2 compatibility. This resolves deprecation warnings and prepares for Pydantic v3. [#359](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/359)
 - Migrated all Pydantic `@root_validator` validators to `@model_validator` for Pydantic v2 compatibility. [#359](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/359)
+- Migrated startup event handling from deprecated `@app.on_event("startup")` to FastAPI's recommended lifespan context manager. This removes deprecation warnings and ensures compatibility with future FastAPI versions. [#359](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/359)
 
 ### Fixed
 

README.md

@@ -32,7 +32,13 @@
 
 ### Performance Note
 
-The `enable_direct_response` option is provided by the stac-fastapi core library (introduced in stac-fastapi 5.2.0) and is available in this project starting from v4.0.0. When enabled, it allows endpoints to return Starlette Response objects directly, bypassing FastAPI's default serialization for improved performance.
+The `enable_direct_response` option is provided by the stac-fastapi core library (introduced in stac-fastapi 5.2.0) and is available in this project starting from v4.0.0.
+
+**You can now control this setting via the `ENABLE_DIRECT_RESPONSE` environment variable.**
+
+When enabled (`ENABLE_DIRECT_RESPONSE=true`), endpoints return Starlette Response objects directly, bypassing FastAPI's default serialization for improved performance. **However, all FastAPI dependencies (including authentication, custom status codes, and validation) are disabled for all routes.**
+
+This mode is best suited for public or read-only APIs where authentication and custom logic are not required. Default is `false` for safety.
 
 See: [issue #347](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/issues/347)
 
@@ -80,6 +86,7 @@ file named `.env` in the same directory you run Docker Compose from:
 ```shell
 ELASTICSEARCH_VERSION=7.17.1
 OPENSEARCH_VERSION=2.11.0
+ENABLE_DIRECT_RESPONSE=false
 ```
 The most recent Elasticsearch 7.x versions should also work. See the [opensearch-py docs](https://github.com/opensearch-project/opensearch-py/blob/main/COMPATIBILITY.md) for compatibility information.
 
@@ -104,7 +111,8 @@ You can customize additional settings in your `.env` file:
 | `RELOAD`                     | Enable auto-reload for development.                                                  | `true`                   | Optional                                                                                    |
 | `STAC_FASTAPI_RATE_LIMIT`    | API rate limit per client.                                                           | `200/minute`             | Optional                                                                                    |
 | `BACKEND`                    | Tests-related variable                                                               | `elasticsearch` or `opensearch` based on the backend | Optional                                                                                    |
-| `ELASTICSEARCH_VERSION`      | ElasticSearch version                                                                | `7.17.1`                 | Optional                                                                                    |
+| `ELASTICSEARCH_VERSION`          | Version of Elasticsearch to use.                                                         | N/A                      | Optional                                                                                    |
+| `ENABLE_DIRECT_RESPONSE`         | Enable direct response for maximum performance (disables all FastAPI dependencies, including authentication, custom status codes, and validation) | `false`                  | Optional                                                                                    |
 | `OPENSEARCH_VERSION`         | OpenSearch version                                                                   | `2.11.0`                 | Optional                                                                                    |
 
 > [!NOTE]

stac_fastapi/elasticsearch/stac_fastapi/elasticsearch/config.py

@@ -1,5 +1,6 @@
 """API configuration."""
 
+import logging
 import os
 import ssl
 from typing import Any, Dict, Set
@@ -71,28 +72,50 @@ def _es_config() -> Dict[str, Any]:
 
 
 class ElasticsearchSettings(ApiSettings, ApiBaseSettings):
-    """API settings."""
+    """
+    API settings.
+
+    Set enable_direct_response via the ENABLE_DIRECT_RESPONSE environment variable.
+    If enabled, all API routes use direct response for maximum performance, but ALL FastAPI dependencies (including authentication, custom status codes, and validation) are disabled.
+    Default is False for safety.
+    """
 
-    # Fields which are defined by STAC but not included in the database model
     forbidden_fields: Set[str] = _forbidden_fields
     indexed_fields: Set[str] = {"datetime"}
     enable_response_models: bool = False
-    enable_direct_response: bool = True
+    enable_direct_response: bool = (
+        os.getenv("ENABLE_DIRECT_RESPONSE", "false").lower() == "true"
+    )
 
     @property
     def create_client(self):
         """Create es client."""
         return Elasticsearch(**_es_config())
 
 
+# Warn at import if direct response is enabled
+if ElasticsearchSettings.enable_direct_response:
+    logging.basicConfig(level=logging.WARNING)
+    logging.warning(
+        "ENABLE_DIRECT_RESPONSE is True: All FastAPI dependencies (including authentication) are DISABLED for all routes!"
+    )
+
+
 class AsyncElasticsearchSettings(ApiSettings, ApiBaseSettings):
-    """API settings."""
+    """
+    API settings.
+
+    Set enable_direct_response via the ENABLE_DIRECT_RESPONSE environment variable.
+    If enabled, all API routes use direct response for maximum performance, but ALL FastAPI dependencies (including authentication, custom status codes, and validation) are disabled.
+    Default is False for safety.
+    """
 
-    # Fields which are defined by STAC but not included in the database model
     forbidden_fields: Set[str] = _forbidden_fields
     indexed_fields: Set[str] = {"datetime"}
     enable_response_models: bool = False
-    enable_direct_response: bool = True
+    enable_direct_response: bool = (
+        os.getenv("ENABLE_DIRECT_RESPONSE", "false").lower() == "true"
+    )
 
     @property
     def create_client(self):

stac_fastapi/opensearch/stac_fastapi/opensearch/config.py

@@ -1,4 +1,5 @@
 """API configuration."""
+import logging
 import os
 import ssl
 from typing import Any, Dict, Set
@@ -69,28 +70,50 @@ def _es_config() -> Dict[str, Any]:
 
 
 class OpensearchSettings(ApiSettings, ApiBaseSettings):
-    """API settings."""
+    """
+    API settings.
+
+    Set enable_direct_response via the ENABLE_DIRECT_RESPONSE environment variable.
+    If enabled, all API routes use direct response for maximum performance, but ALL FastAPI dependencies (including authentication, custom status codes, and validation) are disabled.
+    Default is False for safety.
+    """
 
-    # Fields which are defined by STAC but not included in the database model
     forbidden_fields: Set[str] = _forbidden_fields
     indexed_fields: Set[str] = {"datetime"}
     enable_response_models: bool = False
-    enable_direct_response: bool = True
+    enable_direct_response: bool = (
+        os.getenv("ENABLE_DIRECT_RESPONSE", "false").lower() == "true"
+    )
 
     @property
     def create_client(self):
         """Create es client."""
         return OpenSearch(**_es_config())
 
 
+# Warn at import if direct response is enabled
+if OpensearchSettings.enable_direct_response:
+    logging.basicConfig(level=logging.WARNING)
+    logging.warning(
+        "ENABLE_DIRECT_RESPONSE is True: All FastAPI dependencies (including authentication) are DISABLED for all routes!"
+    )
+
+
 class AsyncOpensearchSettings(ApiSettings, ApiBaseSettings):
-    """API settings."""
+    """
+    API settings.
+
+    Set enable_direct_response via the ENABLE_DIRECT_RESPONSE environment variable.
+    If enabled, all API routes use direct response for maximum performance, but ALL FastAPI dependencies (including authentication, custom status codes, and validation) are disabled.
+    Default is False for safety.
+    """
 
-    # Fields which are defined by STAC but not included in the database model
     forbidden_fields: Set[str] = _forbidden_fields
     indexed_fields: Set[str] = {"datetime"}
     enable_response_models: bool = False
-    enable_direct_response: bool = True
+    enable_direct_response: bool = (
+        os.getenv("ENABLE_DIRECT_RESPONSE", "false").lower() == "true"
+    )
 
     @property
     def create_client(self):