pdk-classy 1.9.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,
    },
};

#[cfg(not(feature = "experimental_websocket"))]
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, Done> FilterBuilder<Sf, (), (), 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, (), 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,
        }
    }

    /// 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, Done, WsUp, WsDown> FilterBuilder<Sf, (), (), 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, (), 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,
        }
    }

    /// 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,
        }
    }
}

#[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, Req, Res, Done, WsUp, WsDown> FilterBuilder<Sf, Req, Res, Done, WsUp, WsDown>
where
    Sf: CreateHandler,
{
    /// Adds an upstream (client→server) WebSocket frame handler.
    pub fn on_upgrade_upstream<WsUpHnd, I>(
        self,
        websocket_upstream: WsUpHnd,
    ) -> FilterBuilder<Sf, Req, Res, Done, WsUpHnd::Handler, WsDown>
    where
        WsUpHnd: crate::handler::IntoHandler<
            crate::extract::context::UpgradeUpstreamContext<Sf::State>,
            I,
            Output = Result<(), crate::BoxError>,
        >,
    {
        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.
    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 = Result<(), crate::BoxError>,
        >,
    {
        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(),
        }
    }
}