Skip to content

Commit 06b51cb

Browse files
alukachalukach
committed
docs: enhance middleware stack documentation with detailed descriptions and execution order
1 parent 9cea266 commit 06b51cb

File tree

2 files changed

+73
-25
lines changed

2 files changed

+73
-25
lines changed

‎Makefile‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.PHONY: help test test-coverage test-fast lint format clean install dev-install
1+
.PHONY: help test test-coverage test-fast lint format clean install dev-install docs
22

33
help: ## Show this help message
44
@echo "Available commands:"
@@ -71,3 +71,7 @@ ci: ## Run CI checks locally
7171
--cov-fail-under=85 \
7272
-v
7373
@echo "✅ CI checks completed!"
74+
75+
docs: ## Serve documentation locally
76+
uv sync --extra docs
77+
DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib uv run mkdocs serve

‎docs/architecture/middleware-stack.md‎

Lines changed: 68 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,83 @@
11
# Middleware Stack
22

3-
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:
3+
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).
44

5-
1. **[`EnforceAuthMiddleware`][stac_auth_proxy.middleware.EnforceAuthMiddleware]**
5+
> [!TIP]
6+
> If you want to apply just the middleware onto your existing FastAPI application, you can do this with [`configure_app`][stac_auth_proxy.configure_app] rather than setting up a separate proxy application.
67
7-
- Handles authentication and authorization
8-
- Configurable public/private endpoints
9-
- OIDC integration
10-
- Places auth token payload in request state
8+
> [!IMPORTANT]
9+
> 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.
1110
12-
1. **[`Cql2BuildFilterMiddleware`][stac_auth_proxy.middleware.Cql2BuildFilterMiddleware]**
11+
1. **[`CompressionMiddleware`](https://github.com/developmentseed/starlette-cramjam)**
1312

14-
- Builds CQL2 filters based on request context/state
15-
- Places [CQL2 expression](http://developmentseed.org/cql2-rs/latest/python/#cql2.Expr) in request state
13+
- **Enabled if:** [`ENABLE_COMPRESSION`](../../user-guide/configuration#enable_compression) is enabled
14+
- Handles response compression
15+
- Reduces response size for better performance
1616

17-
2. **[`Cql2ApplyFilterQueryStringMiddleware`][stac_auth_proxy.middleware.Cql2ApplyFilterQueryStringMiddleware]**
17+
2. **[`RemoveRootPathMiddleware`][stac_auth_proxy.middleware.RemoveRootPathMiddleware]**
1818

19-
- Retrieves [CQL2 expression](http://developmentseed.org/cql2-rs/latest/python/#cql2.Expr) from request state
20-
- Augments `GET` requests with CQL2 filter by appending to querystring
19+
- **Enabled if:** [`ROOT_PATH`](../../user-guide/configuration#root_path) is configured
20+
- Removes the application root path from incoming requests
21+
- Ensures requests are properly routed to upstream API
2122

22-
3. **[`Cql2ApplyFilterBodyMiddleware`][stac_auth_proxy.middleware.Cql2ApplyFilterBodyMiddleware]**
23+
3. **[`ProcessLinksMiddleware`][stac_auth_proxy.middleware.ProcessLinksMiddleware]**
2324

24-
- Retrieves [CQL2 expression](http://developmentseed.org/cql2-rs/latest/python/#cql2.Expr) from request state
25-
- Augments `` POST`/`PUT`/`PATCH `` requests with CQL2 filter by modifying body
25+
- **Enabled if:** [`ROOT_PATH`](../../user-guide/configuration#root_path) is set or [`UPSTREAM_URL`](../../user-guide/configuration#upstream_url) path is not `"/"`
26+
- Updates links in JSON responses to handle root path and upstream URL path differences
27+
- Removes upstream URL path from links and adds root path if configured
2628

27-
4. **[`Cql2ValidateResponseBodyMiddleware`][stac_auth_proxy.middleware.Cql2ValidateResponseBodyMiddleware]**
29+
4. **[`EnforceAuthMiddleware`][stac_auth_proxy.middleware.EnforceAuthMiddleware]**
2830

29-
- Retrieves [CQL2 expression](http://developmentseed.org/cql2-rs/latest/python/#cql2.Expr) from request state
30-
- Validates response against CQL2 filter for non-filterable endpoints
31+
- **Enabled if:** Always active (core authentication middleware)
32+
- Handles authentication and authorization
33+
- Configurable public/private endpoints via [`PUBLIC_ENDPOINTS`](../../user-guide/configuration#public_endpoints) and [`PRIVATE_ENDPOINTS`](../../user-guide/configuration#private_endpoints)
34+
- OIDC integration via [`OIDC_DISCOVERY_INTERNAL_URL`](../../user-guide/configuration#oidc_discovery_internal_url)
35+
- JWT audience validation via [`ALLOWED_JWT_AUDIENCES`](../../user-guide/configuration#allowed_jwt_audiences)
36+
- Places auth token payload in request state
3137

32-
5. **[`OpenApiMiddleware`][stac_auth_proxy.middleware.OpenApiMiddleware]**
38+
5. **[`AddProcessTimeHeaderMiddleware`][stac_auth_proxy.middleware.AddProcessTimeHeaderMiddleware]**
3339

34-
- Modifies OpenAPI specification based on endpoint configuration, adding security requirements
35-
- Only active if `openapi_spec_endpoint` is configured
40+
- **Enabled if:** Always active (monitoring middleware)
41+
- Adds processing time headers to responses
42+
- Useful for monitoring and debugging
3643

37-
6. **[`AddProcessTimeHeaderMiddleware`][stac_auth_proxy.middleware.AddProcessTimeHeaderMiddleware]**
38-
- Adds processing time headers
39-
- Useful for monitoring/debugging
44+
6. **[`Cql2BuildFilterMiddleware`][stac_auth_proxy.middleware.Cql2BuildFilterMiddleware]**
45+
46+
- **Enabled if:** [`ITEMS_FILTER_CLS`](../../user-guide/configuration#items_filter_cls) or [`COLLECTIONS_FILTER_CLS`](../../user-guide/configuration#collections_filter_cls) is configured
47+
- Builds CQL2 filters based on request context/state
48+
- Places [CQL2 expression](http://developmentseed.org/cql2-rs/latest/python/#cql2.Expr) in request state
49+
50+
7. **[`Cql2RewriteLinksFilterMiddleware`][stac_auth_proxy.middleware.Cql2RewriteLinksFilterMiddleware]**
51+
52+
- **Enabled if:** [`ITEMS_FILTER_CLS`](../../user-guide/configuration#items_filter_cls) or [`COLLECTIONS_FILTER_CLS`](../../user-guide/configuration#collections_filter_cls) is configured
53+
- Rewrites filter parameters in response links to remove applied filters
54+
- Ensures links in responses show the original filter state
55+
56+
8. **[`Cql2ApplyFilterQueryStringMiddleware`][stac_auth_proxy.middleware.Cql2ApplyFilterQueryStringMiddleware]**
57+
58+
- **Enabled if:** [`ITEMS_FILTER_CLS`](../../user-guide/configuration#items_filter_cls) or [`COLLECTIONS_FILTER_CLS`](../../user-guide/configuration#collections_filter_cls) is configured
59+
- Retrieves [CQL2 expression](http://developmentseed.org/cql2-rs/latest/python/#cql2.Expr) from request state
60+
- Augments `GET` requests with CQL2 filter by appending to querystring
61+
62+
9. **[`Cql2ApplyFilterBodyMiddleware`][stac_auth_proxy.middleware.Cql2ApplyFilterBodyMiddleware]**
63+
64+
- **Enabled if:** [`ITEMS_FILTER_CLS`](../../user-guide/configuration#items_filter_cls) or [`COLLECTIONS_FILTER_CLS`](../../user-guide/configuration#collections_filter_cls) is configured
65+
- Retrieves [CQL2 expression](http://developmentseed.org/cql2-rs/latest/python/#cql2.Expr) from request state
66+
- Augments `POST`/`PUT`/`PATCH` requests with CQL2 filter by modifying body
67+
68+
10. **[`Cql2ValidateResponseBodyMiddleware`][stac_auth_proxy.middleware.Cql2ValidateResponseBodyMiddleware]**
69+
70+
- **Enabled if:** [`ITEMS_FILTER_CLS`](../../user-guide/configuration#items_filter_cls) or [`COLLECTIONS_FILTER_CLS`](../../user-guide/configuration#collections_filter_cls) is configured
71+
- Retrieves [CQL2 expression](http://developmentseed.org/cql2-rs/latest/python/#cql2.Expr) from request state
72+
- Validates response against CQL2 filter for non-filterable endpoints
73+
74+
11. **[`OpenApiMiddleware`][stac_auth_proxy.middleware.OpenApiMiddleware]**
75+
76+
- **Enabled if:** [`OPENAPI_SPEC_ENDPOINT`](../../user-guide/configuration#openapi_spec_endpoint) is set
77+
- Modifies OpenAPI specification based on endpoint configuration, adding security requirements
78+
- Configurable via [`OPENAPI_AUTH_SCHEME_NAME`](../../user-guide/configuration#openapi_auth_scheme_name) and [`OPENAPI_AUTH_SCHEME_OVERRIDE`](../../user-guide/configuration#openapi_auth_scheme_override)
79+
80+
12. **[`AuthenticationExtensionMiddleware`][stac_auth_proxy.middleware.AuthenticationExtensionMiddleware]**
81+
- **Enabled if:** [`ENABLE_AUTHENTICATION_EXTENSION`](../../user-guide/configuration#enable_authentication_extension) is enabled
82+
- Adds authentication extension information to STAC responses
83+
- Annotates links with authentication requirements based on [`PUBLIC_ENDPOINTS`](../../user-guide/configuration#public_endpoints) and [`PRIVATE_ENDPOINTS`](../../user-guide/configuration#private_endpoints)

0 commit comments

Comments
 (0)