Middleware Stack

Aside from the actual communication with the upstream STAC API, the majority of the proxy's functionality occurs within a chain of middlewares. Each request passes through this chain, wherein each middleware performs a specific task. The middleware chain is ordered from last added (first to run) to first added (last to run).

Tip

If you want to apply just the middleware onto your existing FastAPI application, you can do this with configure_app rather than setting up a separate proxy application.

Important

The order of middleware execution is critical. For example, RemoveRootPathMiddleware must run before EnforceAuthMiddleware so that authentication decisions are made on the correct path after root path removal.

1. CompressionMiddleware

   • Enabled if: ENABLE_COMPRESSION is enabled
   • Handles response compression
   • Reduces response size for better performance

2. RemoveRootPathMiddleware

   • Enabled if: ROOT_PATH is configured
   • Removes the application root path from incoming requests
   • Ensures requests are properly routed to upstream API

3. ProcessLinksMiddleware

   • Enabled if: ROOT_PATH is set or UPSTREAM_URL path is not "/"
   • Updates links in JSON responses to handle root path and upstream URL path differences
   • Removes upstream URL path from links and adds root path if configured

4. EnforceAuthMiddleware

   • Enabled if: Always active (core authentication middleware)
   • Handles authentication and authorization
   • Configurable public/private endpoints via PUBLIC_ENDPOINTS and PRIVATE_ENDPOINTS
   • OIDC integration via OIDC_DISCOVERY_INTERNAL_URL
   • JWT audience validation via ALLOWED_JWT_AUDIENCES
   • Places auth token payload in request state

5. AddProcessTimeHeaderMiddleware

   • Enabled if: Always active (monitoring middleware)
   • Adds processing time headers to responses
   • Useful for monitoring and debugging

6. Cql2BuildFilterMiddleware

   • Enabled if: ITEMS_FILTER_CLS or COLLECTIONS_FILTER_CLS is configured
   • Builds CQL2 filters based on request context/state
   • Places CQL2 expression in request state

7. Cql2RewriteLinksFilterMiddleware

   • Enabled if: ITEMS_FILTER_CLS or COLLECTIONS_FILTER_CLS is configured
   • Rewrites filter parameters in response links to remove applied filters
   • Ensures links in responses show the original filter state

8. Cql2ApplyFilterQueryStringMiddleware

   • Enabled if: ITEMS_FILTER_CLS or COLLECTIONS_FILTER_CLS is configured
   • Retrieves CQL2 expression from request state
   • Augments GET requests with CQL2 filter by appending to querystring

9. Cql2ApplyFilterBodyMiddleware

   • Enabled if: ITEMS_FILTER_CLS or COLLECTIONS_FILTER_CLS is configured
   • Retrieves CQL2 expression from request state
   • Augments POST/PUT/PATCH requests with CQL2 filter by modifying body

10. Cql2ValidateResponseBodyMiddleware

    • Enabled if: ITEMS_FILTER_CLS or COLLECTIONS_FILTER_CLS is configured
    • Retrieves CQL2 expression from request state
    • Validates response against CQL2 filter for non-filterable endpoints

11. OpenApiMiddleware

    • Enabled if: OPENAPI_SPEC_ENDPOINT is set
    • Modifies OpenAPI specification based on endpoint configuration, adding security requirements
    • Configurable via OPENAPI_AUTH_SCHEME_NAME and OPENAPI_AUTH_SCHEME_OVERRIDE

12. AuthenticationExtensionMiddleware

    • Enabled if: ENABLE_AUTHENTICATION_EXTENSION is enabled
    • Adds authentication extension information to STAC responses
    • Annotates links with authentication requirements based on PUBLIC_ENDPOINTS and PRIVATE_ENDPOINTS