Skip to content

Commit 2d15512

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

File tree

1 file changed

+66
-24
lines changed

1 file changed

+66
-24
lines changed

‎docs/architecture/middleware-stack.md‎

Lines changed: 66 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,81 @@
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`][starlette_cramjam.middleware.CompressionMiddleware]**
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+
- Handles response compression when [`ENABLE_COMPRESSION`](configuration.md#enable_compression) is enabled
14+
- Reduces response size for better performance
1615

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

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
18+
- Removes the application root path from incoming requests
19+
- Ensures requests are properly routed to upstream API
20+
- Only active if [`ROOT_PATH`](configuration.md#root_path) is configured
2121

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

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
24+
- Updates links in JSON responses to handle root path and upstream URL path differences
25+
- Removes upstream URL path from links and adds root path if configured
26+
- Only active if [`ROOT_PATH`](configuration.md#root_path) is set or `upstream_url.path != "/"`
2627

27-
4. **[`Cql2ValidateResponseBodyMiddleware`][stac_auth_proxy.middleware.Cql2ValidateResponseBodyMiddleware]**
28+
4. **[`EnforceAuthMiddleware`][stac_auth_proxy.middleware.EnforceAuthMiddleware]**
2829

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
30+
- Handles authentication and authorization
31+
- Configurable public/private endpoints via [`PUBLIC_ENDPOINTS`](configuration.md#public_endpoints) and [`PRIVATE_ENDPOINTS`](configuration.md#private_endpoints)
32+
- OIDC integration via [`OIDC_DISCOVERY_INTERNAL_URL`](configuration.md#oidc_discovery_internal_url)
33+
- JWT audience validation via [`ALLOWED_JWT_AUDIENCES`](configuration.md#allowed_jwt_audiences)
34+
- Places auth token payload in request state
3135

32-
5. **[`OpenApiMiddleware`][stac_auth_proxy.middleware.OpenApiMiddleware]**
36+
5. **[`AddProcessTimeHeaderMiddleware`][stac_auth_proxy.middleware.AddProcessTimeHeaderMiddleware]**
3337

34-
- Modifies OpenAPI specification based on endpoint configuration, adding security requirements
35-
- Only active if `openapi_spec_endpoint` is configured
38+
- Adds processing time headers to responses
39+
- Useful for monitoring and debugging
3640

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

0 commit comments

Comments
 (0)