pdk-classy 1.10.0

// Copyright (c) 2026, Salesforce, Inc.,
// All rights reserved.
// For full license text, see the LICENSE.txt file

use crate::{
    handler::{Handler, IntoHandler},
    hl::{
        bootstrap::{DualFilter, RequestFilter},
        context::{RequestContext, ResponseContext},
        state::{CreateHandler, DoneHandler, EmptyCreateHandler},
        IntoFlow,
    },
};

use crate::hl::bootstrap::ResponseFilter;

#[cfg(feature = "experimental_websocket")]
use crate::hl::bootstrap::WebSocketFilter;

/// Builder for constructing HTTP request/response filters with optional WebSocket support.
///
/// Provides a fluent API to configure:
/// - State factory (`on_create`)
/// - Request handler (`on_request`)
/// - Response handler (`on_response`)
/// - Cleanup handler (`on_done`)
/// - WebSocket upstream handler (`on_upgrade_upstream`)
/// - WebSocket downstream handler (`on_upgrade_downstream`)
#[cfg(feature = "experimental_websocket")]
pub struct FilterBuilder<
    Sf = EmptyCreateHandler,
    Req = (),
    Res = (),
    Done = (),
    WsUp = (),
    WsDown = (),
> {
    state_factory: Sf,
    request_filter: Req,
    response_filter: Res,
    done_handler: Done,
    websocket_upstream: WsUp,
    websocket_downstream: WsDown,
}

/// Builder for constructing HTTP request/response filters.
///
/// Provides a fluent API to configure:
/// - State factory (`on_create`)
/// - Request handler (`on_request`)
/// - Response handler (`on_response`)
/// - Cleanup handler (`on_done`)
#[cfg(not(feature = "experimental_websocket"))]
pub struct FilterBuilder<Sf = EmptyCreateHandler, Req = (), Res = (), Done = ()> {
    state_factory: Sf,
    request_filter: Req,
    response_filter: Res,
    done_handler: Done,
}

impl FilterBuilder {
    /// Creates a new `FilterBuilder` with default empty handlers.
    pub fn new() -> Self {
        Self {
            state_factory: EmptyCreateHandler,
            request_filter: (),
            response_filter: (),
            done_handler: (),
            #[cfg(feature = "experimental_websocket")]
            websocket_upstream: (),
            #[cfg(feature = "experimental_websocket")]
            websocket_downstream: (),
        }
    }

    /// Sets the state factory for creating per-request state.
    ///
    /// The factory is called once per HTTP request to initialize state that will be
    /// accessible in request/response handlers and the done handler.
    #[cfg(not(feature = "experimental_websocket"))]
    pub fn on_create<Sf: CreateHandler>(self, state_factory: Sf) -> FilterBuilder<Sf, (), (), ()> {
        FilterBuilder {
            state_factory,
            request_filter: self.request_filter,
            response_filter: self.response_filter,
            done_handler: self.done_handler,
        }
    }

    /// Sets the state factory for creating per-request state.
    ///
    /// The factory is called once per HTTP request to initialize state that will be
    /// accessible in request/response handlers, done handler, and WebSocket handlers.
    #[cfg(feature = "experimental_websocket")]
    pub fn on_create<Sf: CreateHandler>(
        self,
        state_factory: Sf,
    ) -> FilterBuilder<Sf, (), (), (), (), ()> {
        FilterBuilder {
            state_factory,
            request_filter: self.request_filter,
            response_filter: self.response_filter,
            done_handler: self.done_handler,
            websocket_upstream: self.websocket_upstream,
            websocket_downstream: self.websocket_downstream,
        }
    }
}

impl Default for FilterBuilder {
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(not(feature = "experimental_websocket"))]
impl<Sf, Res, Done> FilterBuilder<Sf, (), Res, Done>
where
    Sf: CreateHandler,
{
    /// Sets the request handler.
    ///
    /// The handler is called for each HTTP request and can modify request headers,
    /// body, or return early responses.
    pub fn on_request<I, Req>(
        self,
        request_filter: Req,
    ) -> FilterBuilder<Sf, Req::Handler, Res, Done>
    where
        Req: IntoHandler<RequestContext<Sf::State>, I>,
    {
        FilterBuilder {
            state_factory: self.state_factory,
            request_filter: request_filter.into_handler(),
            response_filter: self.response_filter,
            done_handler: self.done_handler,
        }
    }
}

#[cfg(not(feature = "experimental_websocket"))]
impl<Sf, Done> FilterBuilder<Sf, (), (), Done>
where
    Sf: CreateHandler,
{
    /// Sets the response handler.
    ///
    /// The handler is called for each HTTP response and can modify response headers
    /// or body.
    pub fn on_response<I, Res>(
        self,
        response_filter: Res,
    ) -> FilterBuilder<Sf, (), Res::Handler, Done>
    where
        Res: IntoHandler<ResponseContext<(), Sf::State>, I, Output = ()>,
    {
        FilterBuilder {
            state_factory: self.state_factory,
            request_filter: self.request_filter,
            response_filter: response_filter.into_handler(),
            done_handler: self.done_handler,
        }
    }
}

#[cfg(feature = "experimental_websocket")]
impl<Sf, Res, Done, WsUp, WsDown> FilterBuilder<Sf, (), Res, Done, WsUp, WsDown>
where
    Sf: CreateHandler,
{
    /// Sets the done handler for a response-only filter.
    pub fn on_done<D>(self, done_handler: D) -> FilterBuilder<Sf, (), Res, D, WsUp, WsDown>
    where
        D: DoneHandler<Sf::State>,
    {
        FilterBuilder {
            state_factory: self.state_factory,
            request_filter: self.request_filter,
            response_filter: self.response_filter,
            done_handler,
            websocket_upstream: self.websocket_upstream,
            websocket_downstream: self.websocket_downstream,
        }
    }
}

#[cfg(feature = "experimental_websocket")]
impl<Sf, Res, Done, WsUp, WsDown> FilterBuilder<Sf, (), Res, Done, WsUp, WsDown>
where
    Sf: CreateHandler,
{
    /// Sets the request handler.
    ///
    /// The handler is called for each HTTP request and can modify request headers,
    /// body, or return early responses.
    pub fn on_request<I, Req>(
        self,
        request_filter: Req,
    ) -> FilterBuilder<Sf, Req::Handler, Res, Done, WsUp, WsDown>
    where
        Req: IntoHandler<RequestContext<Sf::State>, I>,
    {
        FilterBuilder {
            state_factory: self.state_factory,
            request_filter: request_filter.into_handler(),
            response_filter: self.response_filter,
            done_handler: self.done_handler,
            websocket_upstream: self.websocket_upstream,
            websocket_downstream: self.websocket_downstream,
        }
    }
}

#[cfg(feature = "experimental_websocket")]
impl<Sf, Done, WsUp, WsDown> FilterBuilder<Sf, (), (), Done, WsUp, WsDown>
where
    Sf: CreateHandler,
{
    /// Sets the response handler.
    ///
    /// The handler is called for each HTTP response and can modify response headers
    /// or body.
    pub fn on_response<I, Res>(
        self,
        response_filter: Res,
    ) -> FilterBuilder<Sf, (), Res::Handler, Done, WsUp, WsDown>
    where
        Res: IntoHandler<ResponseContext<(), Sf::State>, I, Output = ()>,
    {
        FilterBuilder {
            state_factory: self.state_factory,
            request_filter: self.request_filter,
            response_filter: response_filter.into_handler(),
            done_handler: self.done_handler,
            websocket_upstream: self.websocket_upstream,
            websocket_downstream: self.websocket_downstream,
        }
    }
}

#[cfg(not(feature = "experimental_websocket"))]
impl<Sf, Req, Done> FilterBuilder<Sf, Req, (), Done>
where
    Sf: CreateHandler,
    Req: Handler<RequestContext<Sf::State>, Output: IntoFlow>,
{
    /// Sets the response handler (when request handler is already set).
    ///
    /// The handler is called after the request handler and can access request data
    /// produced by the request handler.
    pub fn on_response<I, Res>(
        self,
        response_filter: Res,
    ) -> FilterBuilder<Sf, Req, Res::Handler, Done>
    where
        Res: IntoHandler<
            ResponseContext<<Req::Output as IntoFlow>::RequestData, Sf::State>,
            I,
            Output: IntoFlow,
        >,
    {
        FilterBuilder {
            state_factory: self.state_factory,
            request_filter: self.request_filter,
            response_filter: response_filter.into_handler(),
            done_handler: self.done_handler,
        }
    }
}

#[cfg(feature = "experimental_websocket")]
impl<Sf, Req, Done, WsUp, WsDown> FilterBuilder<Sf, Req, (), Done, WsUp, WsDown>
where
    Sf: CreateHandler,
    Req: Handler<RequestContext<Sf::State>, Output: IntoFlow>,
{
    /// Sets the response handler (when request handler is already set).
    ///
    /// The handler is called after the request handler and can access request data
    /// produced by the request handler.
    pub fn on_response<I, Res>(
        self,
        response_filter: Res,
    ) -> FilterBuilder<Sf, Req, Res::Handler, Done, WsUp, WsDown>
    where
        Res: IntoHandler<
            ResponseContext<<Req::Output as IntoFlow>::RequestData, Sf::State>,
            I,
            Output: IntoFlow,
        >,
    {
        FilterBuilder {
            state_factory: self.state_factory,
            request_filter: self.request_filter,
            response_filter: response_filter.into_handler(),
            done_handler: self.done_handler,
            websocket_upstream: self.websocket_upstream,
            websocket_downstream: self.websocket_downstream,
        }
    }

    /// Sets the done handler called when the HTTP exchange completes.
    ///
    /// The handler receives the state and can perform cleanup operations like
    /// releasing resources or logging. Called after both request and response processing.
    pub fn on_done<D>(self, done_handler: D) -> FilterBuilder<Sf, Req, (), D, WsUp, WsDown>
    where
        D: DoneHandler<Sf::State>,
    {
        FilterBuilder {
            state_factory: self.state_factory,
            request_filter: self.request_filter,
            response_filter: self.response_filter,
            done_handler,
            websocket_upstream: self.websocket_upstream,
            websocket_downstream: self.websocket_downstream,
        }
    }
}

#[cfg(not(feature = "experimental_websocket"))]
impl<Sf, Req, Done> FilterBuilder<Sf, Req, (), Done>
where
    Req: Handler<RequestContext<Sf::State>>,
    Sf: CreateHandler,
{
    /// Builds a request-only filter.
    ///
    /// Creates a filter that processes HTTP requests but does not modify responses.
    pub fn build(self) -> RequestFilter<Req, Sf, Done> {
        RequestFilter {
            request_handler: self.request_filter,
            state_factory: self.state_factory,
            done_handler: self.done_handler,
        }
    }

    /// Sets the done handler for a request-only filter.
    ///
    /// The handler receives the state and can perform cleanup operations like
    /// releasing resources or logging.
    pub fn on_done<D>(self, done_handler: D) -> FilterBuilder<Sf, Req, (), D>
    where
        D: DoneHandler<Sf::State>,
    {
        FilterBuilder {
            state_factory: self.state_factory,
            request_filter: self.request_filter,
            response_filter: self.response_filter,
            done_handler,
        }
    }
}

#[cfg(not(feature = "experimental_websocket"))]
impl<Sf, Res, Done> FilterBuilder<Sf, (), Res, Done>
where
    Sf: CreateHandler,
{
    /// Sets the done handler for a response-only filter.
    pub fn on_done<D>(self, done_handler: D) -> FilterBuilder<Sf, (), Res, D>
    where
        D: DoneHandler<Sf::State>,
    {
        FilterBuilder {
            state_factory: self.state_factory,
            request_filter: self.request_filter,
            response_filter: self.response_filter,
            done_handler,
        }
    }
}

#[cfg(not(feature = "experimental_websocket"))]
impl<Sf, Res, Done> FilterBuilder<Sf, (), Res, Done>
where
    Res: Handler<ResponseContext<(), Sf::State>>,
    Sf: CreateHandler,
{
    /// Builds a response-only filter.
    ///
    /// Creates a filter that processes HTTP responses but does not modify requests.
    pub fn build(self) -> ResponseFilter<Res, Sf, Done> {
        ResponseFilter {
            response_handler: self.response_filter,
            state_factory: self.state_factory,
            done_handler: self.done_handler,
        }
    }
}

#[cfg(not(feature = "experimental_websocket"))]
impl<Sf, Req, Res, Done> FilterBuilder<Sf, Req, Res, Done>
where
    Req: Handler<RequestContext<Sf::State>, Output: IntoFlow>,
    Res: Handler<ResponseContext<<Req::Output as IntoFlow>::RequestData, Sf::State>>,
    Sf: CreateHandler,
{
    /// Builds a dual filter that processes both requests and responses.
    ///
    /// Creates a filter that can modify both the HTTP request and response in a single pass.
    pub fn build(self) -> DualFilter<Req, Res, Sf, Done> {
        DualFilter {
            request_handler: self.request_filter,
            response_handler: self.response_filter,
            state_factory: self.state_factory,
            done_handler: self.done_handler,
        }
    }
}

#[cfg(feature = "experimental_websocket")]
impl<Sf, Req, Done, WsUp, WsDown> FilterBuilder<Sf, Req, (), Done, WsUp, WsDown>
where
    Req: Handler<RequestContext<Sf::State>, Output: IntoFlow>,
    Sf: CreateHandler,
{
    /// Builds a request-only filter with WebSocket support.
    pub fn build(self) -> WebSocketFilter<RequestFilter<Req, Sf, Done>, Sf, WsUp, WsDown> {
        let base_filter = RequestFilter {
            request_handler: self.request_filter,
            state_factory: self.state_factory,
            done_handler: self.done_handler,
        };
        WebSocketFilter {
            base_filter,
            websocket_upstream: self.websocket_upstream,
            websocket_downstream: self.websocket_downstream,
            _sf: std::marker::PhantomData,
        }
    }
}

#[cfg(feature = "experimental_websocket")]
impl<Sf, Req, Res, Done, WsUp, WsDown> FilterBuilder<Sf, Req, Res, Done, WsUp, WsDown>
where
    Req: Handler<RequestContext<Sf::State>, Output: IntoFlow>,
    Res: Handler<ResponseContext<<Req::Output as IntoFlow>::RequestData, Sf::State>>,
    Sf: CreateHandler,
{
    /// Builds a dual filter with WebSocket support.
    ///
    /// Creates a filter that processes both HTTP requests and responses,
    /// and can handle WebSocket upgrades.
    pub fn build(self) -> WebSocketFilter<DualFilter<Req, Res, Sf, Done>, Sf, WsUp, WsDown> {
        let base_filter = DualFilter {
            request_handler: self.request_filter,
            response_handler: self.response_filter,
            state_factory: self.state_factory,
            done_handler: self.done_handler,
        };
        WebSocketFilter {
            base_filter,
            websocket_upstream: self.websocket_upstream,
            websocket_downstream: self.websocket_downstream,
            _sf: std::marker::PhantomData,
        }
    }
}

#[cfg(not(feature = "experimental_websocket"))]
impl<Sf, Req, Res, Done> FilterBuilder<Sf, Req, Res, Done>
where
    Req: Handler<RequestContext<Sf::State>, Output: IntoFlow>,
    Res: Handler<ResponseContext<<Req::Output as IntoFlow>::RequestData, Sf::State>>,
    Sf: CreateHandler,
{
    /// Sets the done handler called when the HTTP exchange completes.
    ///
    /// The handler receives the state and can perform cleanup operations like
    /// releasing resources or logging. Called after both request and response processing.
    pub fn on_done<D>(self, done_handler: D) -> FilterBuilder<Sf, Req, Res, D>
    where
        D: DoneHandler<Sf::State>,
    {
        FilterBuilder {
            state_factory: self.state_factory,
            request_filter: self.request_filter,
            response_filter: self.response_filter,
            done_handler,
        }
    }
}

#[cfg(feature = "experimental_websocket")]
impl<Sf, Req, Res, Done, WsUp, WsDown> FilterBuilder<Sf, Req, Res, Done, WsUp, WsDown>
where
    Req: Handler<RequestContext<Sf::State>, Output: IntoFlow>,
    Res: Handler<ResponseContext<<Req::Output as IntoFlow>::RequestData, Sf::State>>,
    Sf: CreateHandler,
{
    /// Sets the done handler called when the HTTP exchange completes.
    ///
    /// The handler receives the state and can perform cleanup operations like
    /// releasing resources or logging. Called after both request and response processing.
    pub fn on_done<D>(self, done_handler: D) -> FilterBuilder<Sf, Req, Res, D, WsUp, WsDown>
    where
        D: DoneHandler<Sf::State>,
    {
        FilterBuilder {
            state_factory: self.state_factory,
            request_filter: self.request_filter,
            response_filter: self.response_filter,
            done_handler,
            websocket_upstream: self.websocket_upstream,
            websocket_downstream: self.websocket_downstream,
        }
    }
}

#[cfg(feature = "experimental_websocket")]
impl<Sf, Res, Done, WsUp, WsDown> FilterBuilder<Sf, (), Res, Done, WsUp, WsDown>
where
    Res: Handler<ResponseContext<(), Sf::State>>,
    Sf: CreateHandler,
{
    /// Builds a response-only filter with WebSocket support.
    ///
    /// Creates a filter that processes HTTP responses but does not modify requests,
    /// while retaining any configured WebSocket upgrade handlers.
    pub fn build(self) -> WebSocketFilter<ResponseFilter<Res, Sf, Done>, Sf, WsUp, WsDown> {
        let base_filter = ResponseFilter {
            response_handler: self.response_filter,
            state_factory: self.state_factory,
            done_handler: self.done_handler,
        };
        WebSocketFilter {
            base_filter,
            websocket_upstream: self.websocket_upstream,
            websocket_downstream: self.websocket_downstream,
            _sf: std::marker::PhantomData,
        }
    }
}

#[cfg(feature = "experimental_websocket")]
impl<Sf, Req, Res, Done, WsUp, WsDown> FilterBuilder<Sf, Req, Res, Done, WsUp, WsDown>
where
    Sf: CreateHandler,
{
    /// Adds an upstream (client→server) WebSocket frame handler.
    ///
    /// The handler may return `()` (its frame loop runs until it completes) or a
    /// `Result<(), E>` (returning `Err` ends the loop; the error is logged and the
    /// connection is left to close on its own — see the `WebSocketFilter` `Handler` impl).
    pub fn on_upgrade_upstream<WsUpHnd, I>(
        self,
        websocket_upstream: WsUpHnd,
    ) -> FilterBuilder<Sf, Req, Res, Done, WsUpHnd::Handler, WsDown>
    where
        WsUpHnd: IntoHandler<
            crate::extract::context::UpgradeUpstreamContext<Sf::State>,
            I,
            Output: crate::handler::IntoHandlerResult,
        >,
    {
        FilterBuilder {
            state_factory: self.state_factory,
            request_filter: self.request_filter,
            response_filter: self.response_filter,
            done_handler: self.done_handler,
            websocket_upstream: websocket_upstream.into_handler(),
            websocket_downstream: self.websocket_downstream,
        }
    }

    /// Adds a downstream (server→client) WebSocket frame handler.
    ///
    /// The handler may return `()` (its frame loop runs until it completes) or a
    /// `Result<(), E>` (returning `Err` ends the loop; the error is logged and the
    /// connection is left to close on its own — see the `WebSocketFilter` `Handler` impl).
    pub fn on_upgrade_downstream<WsDownHnd, I>(
        self,
        websocket_downstream: WsDownHnd,
    ) -> FilterBuilder<Sf, Req, Res, Done, WsUp, WsDownHnd::Handler>
    where
        WsDownHnd: crate::handler::IntoHandler<
            crate::extract::context::UpgradeDownstreamContext<Sf::State>,
            I,
            Output: crate::handler::IntoHandlerResult,
        >,
    {
        FilterBuilder {
            state_factory: self.state_factory,
            request_filter: self.request_filter,
            response_filter: self.response_filter,
            done_handler: self.done_handler,
            websocket_upstream: self.websocket_upstream,
            websocket_downstream: websocket_downstream.into_handler(),
        }
    }
}

#[cfg(all(test, not(feature = "experimental_websocket")))]
mod builder_state_tests {
    use super::*;
    use crate::hl::flow::Flow;

    // C1: on_done reachable on a request-only builder (the `(X, e)` state).
    #[test]
    fn request_only_on_done_builds() {
        let _filter = FilterBuilder::new()
            .on_request(|| async { Flow::Continue(()) })
            .on_done(|_s: ()| {})
            .build();
    }

    // on_done reachable on a response-only builder (the `(e, X)` state).
    #[test]
    fn response_only_on_done_builds() {
        let _filter = FilterBuilder::new()
            .on_response(|| async {})
            .on_done(|_s: ()| {})
            .build();
    }

    // Regression: forms that compile today still compile.
    #[test]
    fn existing_forms_still_build() {
        let _req = FilterBuilder::new()
            .on_request(|| async { Flow::Continue(()) })
            .build();
        let _res = FilterBuilder::new().on_response(|| async {}).build();
        let _dual = FilterBuilder::new()
            .on_request(|| async { Flow::Continue(()) })
            .on_response(|| async {})
            .build();
    }

    // on_request remains reachable after on_response when the
    // request handler produces no request data (RequestData = ()).
    #[test]
    fn on_request_after_on_response_builds() {
        let _filter = FilterBuilder::new()
            .on_response(|| async {})
            .on_request(|| async { Flow::Continue(()) })
            .build();
    }
}

#[cfg(all(test, feature = "experimental_websocket"))]
mod builder_state_tests {
    use super::*;
    use crate::hl::flow::Flow;
    use crate::hl::state::State;

    struct TestState;

    // C1 (WS-compiled crate): on_done reachable on a request-only builder.
    #[test]
    fn request_only_on_done_builds() {
        let _filter = FilterBuilder::new()
            .on_request(|| async { Flow::Continue(()) })
            .on_done(|_s: ()| {})
            .build();
    }

    // C2: on_done reachable on the empty-both builder (covered by the
    // generic-`Res` response-only impl, since `Res = ()`).
    #[test]
    fn empty_both_on_done_reachable() {
        let _builder = FilterBuilder::new().on_done(|_s: ()| {});
    }

    // on_done reachable on a response-only builder.
    #[test]
    fn response_only_on_done_builds() {
        let _filter = FilterBuilder::new()
            .on_response(|| async {})
            .on_done(|_s: ()| {})
            .build();
    }

    // C4: a response-only build with upgrade handlers must yield a
    // `WebSocketFilter` that retains those handlers (not a bare `ResponseFilter`).
    #[test]
    fn response_only_build_retains_upgrade_handlers() {
        let filter = FilterBuilder::new()
            .on_response(|| async {})
            .on_upgrade_upstream(|| async {})
            .on_upgrade_downstream(|| async {})
            .build();

        // Type assertion: the built value is a WebSocketFilter wrapping a
        // ResponseFilter, with non-`()` upgrade-handler slots.
        fn assert_ws<Base, Sf, WsUp, WsDown>(_f: &WebSocketFilter<Base, Sf, WsUp, WsDown>) {}
        assert_ws(&filter);
    }

    // Regression: forms that compile today still compile.
    #[test]
    fn existing_forms_still_build() {
        let _req = FilterBuilder::new()
            .on_request(|| async { Flow::Continue(()) })
            .build();
        let _dual = FilterBuilder::new()
            .on_request(|| async { Flow::Continue(()) })
            .on_response(|| async {})
            .build();
    }

    // on_request remains reachable after on_response when the
    // request handler produces no request data (RequestData = ()).
    #[test]
    fn on_request_after_on_response_builds() {
        let _filter = FilterBuilder::new()
            .on_response(|| async {})
            .on_request(|| async { Flow::Continue(()) })
            .build();
    }

    // Which handler combinations can be built, exhaustively.
    //
    // There are 6 optional handler slots (on_create, on_request, on_response,
    // on_upgrade_upstream, on_upgrade_downstream, on_done), so 2^6 = 64 possible
    // combinations.
    //
    //   CAN combine (48): any combination that sets on_request and/or on_response.
    //     The other 4 slots (on_create, both on_upgrade_*, on_done) are then free to
    //     be present or absent in any mix. The matrix below builds all 48 — every one
    //     compiling proves the combination is valid.
    //
    //   CANNOT combine (16): any combination with NEITHER on_request NOR on_response.
    //     `build()` has no impl for that shape, so a WebSocket-only or empty filter
    //     does not compile. These 16 are intentionally absent from the matrix (there
    //     is no HTTP entry point to attach the filter to).
    //
    // Bodies are no-arg and state-agnostic, so they compile whether on_create supplies
    // `TestState` or the state is `()`; `State<TestState>` extraction is covered by the
    // standalone tests below.
    //
    // Ordering constraints (each slot may be set at most once):
    //   - on_create must come first (only the fresh builder exposes it).
    //   - on_request / on_response: either order. request-then-response lets the
    //     response see the request data; response-then-request only builds when the
    //     request produces no data (covered by `on_request_after_on_response_builds`).
    //   - on_upgrade_upstream / on_upgrade_downstream / on_done: orthogonal, any order.
    // The matrix chains one valid order (create -> request -> response -> upstream ->
    // downstream -> done); it varies WHICH slots are set, not their order.

    // Expands one combo (6 Y/N flags) into a chained `.build()`. Per slot: Y appends
    // the method, N skips it, threading the builder through an `($acc:expr)`.
    macro_rules! bm_chain {
        // on_create
        (Y, $rq:tt, $rs:tt, $up:tt, $dn:tt, $do:tt) => {
            bm_chain!(@req (FilterBuilder::new().on_create(|| TestState)), $rq, $rs, $up, $dn, $do)
        };
        (N, $rq:tt, $rs:tt, $up:tt, $dn:tt, $do:tt) => {
            bm_chain!(@req (FilterBuilder::new()), $rq, $rs, $up, $dn, $do)
        };

        // on_request
        (@req ($acc:expr), Y, $rs:tt, $up:tt, $dn:tt, $do:tt) => {
            bm_chain!(@res ($acc.on_request(|| async { Flow::Continue(()) })), $rs, $up, $dn, $do)
        };
        (@req ($acc:expr), N, $rs:tt, $up:tt, $dn:tt, $do:tt) => {
            bm_chain!(@res ($acc), $rs, $up, $dn, $do)
        };

        // on_response
        (@res ($acc:expr), Y, $up:tt, $dn:tt, $do:tt) => {
            bm_chain!(@up ($acc.on_response(|| async {})), $up, $dn, $do)
        };
        (@res ($acc:expr), N, $up:tt, $dn:tt, $do:tt) => {
            bm_chain!(@up ($acc), $up, $dn, $do)
        };

        // on_upgrade_upstream
        (@up ($acc:expr), Y, $dn:tt, $do:tt) => {
            bm_chain!(@down ($acc.on_upgrade_upstream(|| async {})), $dn, $do)
        };
        (@up ($acc:expr), N, $dn:tt, $do:tt) => {
            bm_chain!(@down ($acc), $dn, $do)
        };

        // on_upgrade_downstream
        (@down ($acc:expr), Y, $do:tt) => {
            bm_chain!(@done ($acc.on_upgrade_downstream(|| async {})), $do)
        };
        (@down ($acc:expr), N, $do:tt) => {
            bm_chain!(@done ($acc), $do)
        };

        // on_done (terminator: emits `.build()`).
        (@done ($acc:expr), Y) => {
            $acc.on_done(|_a| {}).build()
        };
        (@done ($acc:expr), N) => {
            $acc.build()
        };
    }

    // Emits one `#[test] fn` per table entry.
    macro_rules! builder_matrix {
        ($( $name:ident : $c:tt $rq:tt $rs:tt $up:tt $dn:tt $do:tt ; )*) => {
            $(
                #[test]
                fn $name() {
                    let _f = bm_chain!($c, $rq, $rs, $up, $dn, $do);
                }
            )*
        };
    }

    // 48 valid combos. Columns: create request response upstream downstream done.
    builder_matrix! {
        res:                          N N Y N N N;
        res_done:                     N N Y N N Y;
        res_down:                     N N Y N Y N;
        res_down_done:                N N Y N Y Y;
        res_up:                       N N Y Y N N;
        res_up_done:                  N N Y Y N Y;
        res_up_down:                  N N Y Y Y N;
        res_up_down_done:             N N Y Y Y Y;
        req:                          N Y N N N N;
        req_done:                     N Y N N N Y;
        req_down:                     N Y N N Y N;
        req_down_done:                N Y N N Y Y;
        req_up:                       N Y N Y N N;
        req_up_done:                  N Y N Y N Y;
        req_up_down:                  N Y N Y Y N;
        req_up_down_done:             N Y N Y Y Y;
        req_res:                      N Y Y N N N;
        req_res_done:                 N Y Y N N Y;
        req_res_down:                 N Y Y N Y N;
        req_res_down_done:            N Y Y N Y Y;
        req_res_up:                   N Y Y Y N N;
        req_res_up_done:              N Y Y Y N Y;
        req_res_up_down:              N Y Y Y Y N;
        req_res_up_down_done:         N Y Y Y Y Y;
        create_res:                   Y N Y N N N;
        create_res_done:              Y N Y N N Y;
        create_res_down:              Y N Y N Y N;
        create_res_down_done:         Y N Y N Y Y;
        create_res_up:                Y N Y Y N N;
        create_res_up_done:           Y N Y Y N Y;
        create_res_up_down:           Y N Y Y Y N;
        create_res_up_down_done:      Y N Y Y Y Y;
        create_req:                   Y Y N N N N;
        create_req_done:              Y Y N N N Y;
        create_req_down:              Y Y N N Y N;
        create_req_down_done:         Y Y N N Y Y;
        create_req_up:                Y Y N Y N N;
        create_req_up_done:           Y Y N Y N Y;
        create_req_up_down:           Y Y N Y Y N;
        create_req_up_down_done:      Y Y N Y Y Y;
        create_req_res:               Y Y Y N N N;
        create_req_res_done:          Y Y Y N N Y;
        create_req_res_down:          Y Y Y N Y N;
        create_req_res_down_done:     Y Y Y N Y Y;
        create_req_res_up:            Y Y Y Y N N;
        create_req_res_up_done:       Y Y Y Y N Y;
        create_req_res_up_down:       Y Y Y Y Y N;
        create_req_res_up_down_done:  Y Y Y Y Y Y;
    }

    // Cover `State<TestState>` extraction in each handler slot (the matrix uses
    // no-arg bodies). Build-compile only.
    #[test]
    fn state_extracted_in_request_and_response() {
        let _f = FilterBuilder::new()
            .on_create(|| TestState)
            .on_request(|State(_s): State<TestState>| async { Flow::Continue(()) })
            .on_response(|State(_s): State<TestState>| async {})
            .build();
    }

    #[test]
    fn state_extracted_in_upgrade_handlers() {
        let _f = FilterBuilder::new()
            .on_create(|| TestState)
            .on_response(|| async {})
            .on_upgrade_upstream(|State(_s): State<TestState>| async {})
            .on_upgrade_downstream(|State(_s): State<TestState>| async {})
            .build();
    }
}