Expose Headers Config

[hsngerami]

Feature Description

Add support for configuring the expose_headers parameter in archipy's CORS middleware configuration to allow browsers to access custom response headers.

Problem Statement

I'm always frustrated when my frontend application cannot read custom headers returned by the API (like X-Total-Count, X-Request-ID, or Content-Range) because archipy's CORS configuration doesn't support the expose_headers parameter. Currently, the [setup_cors method in app_utils.py:160-167]

Proposed Solution

Add a new configuration parameter CORS_MIDDLEWARE_EXPOSE_HEADERS (list of strings) to the FastAPI configuration that gets passed to Starlette's CORSMiddleware as the expose_headers argument. This would allow developers to specify which response headers should be accessible to browser JavaScript.

Use Cases

Describe specific use cases where this feature would be valuable:

1. When a developer needs to implement pagination and the API returns total count in an X-Total-Count header that the frontend needs to read
2. In situations where request tracking is implemented using X-Request-ID or X-Correlation-ID headers that need to be logged on the client side
3. For integrations with rate-limited APIs that return X-RateLimit-Remaining and X-RateLimit-Reset headers that clients need to monitor
4. When serving downloadable content with Content-Disposition headers that the frontend needs to access for proper file naming
5. For APIs returning custom metadata headers like X-Content-Version or X-Resource-Status that clients need to process

The proposed solution is better because it maintains consistency with archipy's existing CORS configuration pattern while providing explicit, secure control over exposed headers.

Implementation Ideas

Config Model (add to FastAPI config):

CORS_MIDDLEWARE_EXPOSE_HEADERS: list[str] = []  # Default to empty list

Middleware Setup (modify app_utils.py:160-167):

origins = [str(origin).strip("/") for origin in config.FASTAPI.CORS_MIDDLEWARE_ALLOW_ORIGINS]
app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=config.FASTAPI.CORS_MIDDLEWARE_ALLOW_CREDENTIALS,
    allow_methods=config.FASTAPI.CORS_MIDDLEWARE_ALLOW_METHODS,
    allow_headers=config.FASTAPI.CORS_MIDDLEWARE_ALLOW_HEADERS,
    expose_headers=config.FASTAPI.CORS_MIDDLEWARE_EXPOSE_HEADERS,  # Add this line
)

Usage Example:

# In .env or config
CORS_MIDDLEWARE_EXPOSE_HEADERS=["X-Total-Count", "X-Request-ID", "Content-Range"]

Additional Context

The expose_headers parameter is a standard feature of Starlette's CORSMiddleware (which FastAPI uses) but is currently not exposed through archipy's configuration. According to the Starlette CORS documentation, this parameter controls which headers are included in the Access-Control-Expose-Headers response header.

Example from Starlette docs:

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    expose_headers=["X-Custom-Header"],  # This parameter exists but archipy doesn't use it
)

This is a common requirement in modern web applications where APIs communicate metadata through headers, and it's already supported by the underlying middleware—it just needs to be wired up in archipy's configuration.

Would you be willing to help implement this feature?

• Yes, I'd be interested in contributing code
• Yes, I'd be interested in testing
• Yes, I'd be interested in documenting
• No, I'm just suggesting the feature