feat: allow before_request and after_request handlers to accept a parent argument

[charles-dyfis-net]

…to wrap or override the handler from an enclosing scope.

At present, this is a proposal / discussion piece rather than a contribution submitted as ready-to-merge.

Description

Presently, hooks at an inner layer replace those at outer layers. In many use cases, this is unsuitable: If the router handling all /tenants/{tenant:uuid} requests performs a lookup and authentication, then a router mounted under it will still want that same authentication even if it adds additional common code as well.

This PR proposes a change to allow child handlers to wrap parent handlers. Where previously one might write:

def tenant_router_pre_request(request: litestar.Request):
    if (tenant := request.path_params.get("tenant")) is not None:
        structlog.contextvars.bind_contextvars(tenant=str(tenant))
    # author needs to know that the parent app's pre_request was this specific other function
    return await root_app_pre_request(request)

...we can instead write:

def tenant_router_pre_request(request: litestar.Request, /, *, parent: Optional[BeforeRequestHookHandler]):
    if (tenant := request.path_params.get("tenant")) is not None:
        structlog.contextvars.bind_contextvars(tenant=str(tenant))
    return (await parent(request)) if parent is not None else None

...and let litestar do the work of populating parent as/when appropriate.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.35%. Comparing base (a38c6c1) to head (2a5aeb4).
Report is 5 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3748   +/-   ##
=======================================
  Coverage   98.35%   98.35%           
=======================================
  Files         331      331           
  Lines       15275    15289   +14     
  Branches     2445     2447    +2     
=======================================
+ Hits        15023    15037   +14     
  Misses        112      112           
  Partials      140      140           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[charles-dyfis-net]

With test coverage added and passing, removing from draft.

(Having discussed with @provinzkraut, I understand that this isn't likely to be merged in its current form -- we can do better in 3.0 by building a list of hooks as we do guards, and pre-3.0 this change is considered to break compatibility guarantees -- but I did want to get this into a less-broken state before being done with it, even as a conversation piece).

[github-actions]

Documentation preview will be available shortly at https://litestar-org.github.io/litestar-docs-preview/3748