simplejrpc 0.1.0

Unix-socket JSON-RPC 2.0 SDK with middleware, config, and validation
Documentation
//! Middleware traits and onion chain (compatible with Go `RPCMiddleware`).
//!
//! - **Request** phase runs middlewares **in registration order**.
//! - **Response** phase runs them in **reverse** order.
//!
//! Attach middlewares via [`crate::ServerBuilder::with_middleware`].
//!
//! # Examples
//!
//! ```
//! use async_trait::async_trait;
//! use simplejrpc::middleware::{Middleware, MiddlewareChain};
//! use simplejrpc::{AppResponse, Request};
//! use serde_json::json;
//! use std::sync::Arc;
//!
//! struct Trace;
//!
//! #[async_trait]
//! impl Middleware for Trace {
//!     async fn process_request(&self, req: &mut Request) {
//!         req.set_extension("traced", json!(true));
//!     }
//!     async fn process_response(&self, resp: AppResponse) -> simplejrpc::Result<AppResponse> {
//!         Ok(resp.with_close(0))
//!     }
//! }
//!
//! let mut chain = MiddlewareChain::new();
//! chain.push(Arc::new(Trace));
//! assert_eq!(chain.len(), 1);
//! assert!(!chain.is_empty());
//! ```

use std::sync::Arc;

use async_trait::async_trait;

use crate::error::Result;
use crate::response::AppResponse;
use crate::server::Request;

/// Middleware hook pair (request + response).
///
/// Default implementations are no-ops so you can override only what you need.
///
/// # Examples
///
/// See the [module-level example](crate::middleware).
#[async_trait]
pub trait Middleware: Send + Sync {
    /// Called before the method handler (forward order).
    ///
    /// Typical uses: auth, tracing ids, language negotiation.
    async fn process_request(&self, _req: &mut Request) {}

    /// Called after the method handler (reverse order).
    ///
    /// Typical uses: metrics, response rewriting, force `meta.close`.
    async fn process_response(&self, resp: AppResponse) -> Result<AppResponse> {
        Ok(resp)
    }
}

/// Runnable middleware list (override `run_*` on a wrapper if needed).
///
/// Named `*Ops` (not `*View`) because [`Self::run_request`] **mutates** the
/// [`Request`] and [`Self::run_response`] may rewrite the envelope.
///
/// Default implementations walk [`Self::middlewares`] in onion order
/// (request forward, response reverse). Override to short-circuit, reverse,
/// or inject policy.
///
/// # Examples
///
/// Skip the chain when an extension flag is set:
///
/// ```
/// use async_trait::async_trait;
/// use simplejrpc::middleware::{MiddlewareChain, MiddlewareChainOps};
/// use simplejrpc::{AppResponse, Request};
/// use serde_json::json;
/// use std::sync::Arc;
///
/// struct Gate(MiddlewareChain);
///
/// #[async_trait]
/// impl MiddlewareChainOps for Gate {
///     fn middlewares(&self) -> &[Arc<dyn simplejrpc::middleware::Middleware>] {
///         MiddlewareChainOps::middlewares(&self.0)
///     }
///
///     async fn run_request(&self, req: &mut Request) {
///         if req.extension("skip_mw").and_then(|v| v.as_bool()) == Some(true) {
///             return;
///         }
///         MiddlewareChainOps::run_request(&self.0, req).await;
///     }
/// }
///
/// # async fn demo() {
/// let g = Gate(MiddlewareChain::new());
/// let mut req = Request::new("m", json!({}), json!(1));
/// req.set_extension("skip_mw", json!(true));
/// MiddlewareChainOps::run_request(&g, &mut req).await;
/// # }
/// ```
#[async_trait]
pub trait MiddlewareChainOps: Send + Sync {
    /// Middleware list in **registration** order.
    fn middlewares(&self) -> &[Arc<dyn Middleware>];

    /// Number of middlewares (`middlewares().len()`).
    fn len(&self) -> usize {
        self.middlewares().len()
    }

    /// Whether the chain has no middlewares.
    fn is_empty(&self) -> bool {
        self.middlewares().is_empty()
    }

    /// Run request hooks **forward** (registration order).
    ///
    /// Each middleware may mutate [`Request`] extensions / params. There is no
    /// short-circuit in the default implementation.
    async fn run_request(&self, req: &mut Request) {
        for mw in self.middlewares() {
            mw.process_request(req).await;
        }
    }

    /// Run response hooks **reverse** (last registered runs first).
    ///
    /// # Errors
    ///
    /// Propagates the first [`Err`] from [`Middleware::process_response`].
    async fn run_response(&self, mut resp: AppResponse) -> Result<AppResponse> {
        for mw in self.middlewares().iter().rev() {
            resp = mw.process_response(resp).await?;
        }
        Ok(resp)
    }
}

/// Mutable access for building or rewriting a pipeline.
///
/// # Examples
///
/// ```
/// use async_trait::async_trait;
/// use simplejrpc::middleware::{Middleware, MiddlewareChain, MiddlewareChainMut};
/// use std::sync::Arc;
///
/// struct Nop;
/// #[async_trait]
/// impl Middleware for Nop {}
///
/// let mut c = MiddlewareChain::new();
/// MiddlewareChainMut::push(&mut c, Arc::new(Nop));
/// assert_eq!(c.len(), 1);
/// MiddlewareChainMut::clear(&mut c);
/// assert!(c.is_empty());
/// ```
pub trait MiddlewareChainMut: MiddlewareChainOps {
    /// Append a middleware.
    fn push(&mut self, mw: Arc<dyn Middleware>);

    /// Remove all middlewares.
    fn clear(&mut self) {
        self.middlewares_mut().clear();
    }

    /// Mutable access to the underlying list.
    fn middlewares_mut(&mut self) -> &mut Vec<Arc<dyn Middleware>>;
}

/// Ordered middleware pipeline used by [`crate::Server`].
///
/// Implements [`MiddlewareChainOps`] / [`MiddlewareChainMut`].
///
/// # Examples
///
/// ```
/// use simplejrpc::middleware::MiddlewareChain;
/// let chain = MiddlewareChain::new();
/// assert!(chain.is_empty());
/// ```
#[derive(Default, Clone)]
pub struct MiddlewareChain {
    items: Vec<Arc<dyn Middleware>>,
}

impl MiddlewareChain {
    /// Create an empty chain.
    ///
    /// # Examples
    ///
    /// ```
    /// use simplejrpc::middleware::MiddlewareChain;
    /// assert!(MiddlewareChain::new().is_empty());
    /// ```
    pub fn new() -> Self {
        Self::default()
    }

    /// Build from an existing list (registration order).
    ///
    /// # Examples
    ///
    /// ```
    /// use simplejrpc::middleware::MiddlewareChain;
    /// let c = MiddlewareChain::from_items(Vec::new());
    /// assert!(c.is_empty());
    /// ```
    pub fn from_items(items: Vec<Arc<dyn Middleware>>) -> Self {
        Self { items }
    }

    /// Consume into the underlying list.
    ///
    /// # Examples
    ///
    /// ```
    /// use simplejrpc::middleware::MiddlewareChain;
    /// let items = MiddlewareChain::new().into_items();
    /// assert!(items.is_empty());
    /// ```
    pub fn into_items(self) -> Vec<Arc<dyn Middleware>> {
        self.items
    }

    /// Append a middleware (runs later on request, earlier on response).
    ///
    /// # Examples
    ///
    /// ```
    /// use async_trait::async_trait;
    /// use simplejrpc::middleware::{Middleware, MiddlewareChain};
    /// use std::sync::Arc;
    ///
    /// struct Nop;
    /// #[async_trait]
    /// impl Middleware for Nop {}
    ///
    /// let mut c = MiddlewareChain::new();
    /// c.push(Arc::new(Nop));
    /// assert_eq!(c.len(), 1);
    /// ```
    pub fn push(&mut self, mw: Arc<dyn Middleware>) {
        MiddlewareChainMut::push(self, mw)
    }

    /// Remove all middlewares.
    ///
    /// # Examples
    ///
    /// ```
    /// use async_trait::async_trait;
    /// use simplejrpc::middleware::{Middleware, MiddlewareChain};
    /// use std::sync::Arc;
    ///
    /// struct Nop;
    /// #[async_trait]
    /// impl Middleware for Nop {}
    ///
    /// let mut c = MiddlewareChain::new();
    /// c.push(Arc::new(Nop));
    /// c.clear();
    /// assert!(c.is_empty());
    /// ```
    pub fn clear(&mut self) {
        MiddlewareChainMut::clear(self)
    }

    /// Number of middlewares in the chain.
    ///
    /// # Examples
    ///
    /// ```
    /// use simplejrpc::middleware::MiddlewareChain;
    /// assert_eq!(MiddlewareChain::new().len(), 0);
    /// ```
    pub fn len(&self) -> usize {
        MiddlewareChainOps::len(self)
    }

    /// Whether the chain has no middlewares.
    ///
    /// # Examples
    ///
    /// ```
    /// use simplejrpc::middleware::MiddlewareChain;
    /// assert!(MiddlewareChain::new().is_empty());
    /// ```
    pub fn is_empty(&self) -> bool {
        MiddlewareChainOps::is_empty(self)
    }

    /// Run request hooks forward (registration order).
    ///
    /// # Examples
    ///
    /// ```
    /// # async fn demo() {
    /// use simplejrpc::middleware::MiddlewareChain;
    /// use simplejrpc::Request;
    /// use serde_json::json;
    /// let chain = MiddlewareChain::new();
    /// let mut req = Request::new("m", json!({}), json!(1));
    /// chain.run_request(&mut req).await;
    /// # }
    /// ```
    pub async fn run_request(&self, req: &mut Request) {
        MiddlewareChainOps::run_request(self, req).await
    }

    /// Run response hooks in reverse registration order.
    ///
    /// # Examples
    ///
    /// ```
    /// # async fn demo() -> simplejrpc::Result<()> {
    /// use simplejrpc::middleware::MiddlewareChain;
    /// use simplejrpc::AppResponse;
    /// use serde_json::json;
    /// let out = MiddlewareChain::new()
    ///     .run_response(AppResponse::ok(json!(null)))
    ///     .await?;
    /// assert_eq!(out.code, 200);
    /// # Ok(())
    /// # }
    /// ```
    pub async fn run_response(&self, resp: AppResponse) -> Result<AppResponse> {
        MiddlewareChainOps::run_response(self, resp).await
    }
}

#[async_trait]
impl MiddlewareChainOps for MiddlewareChain {
    fn middlewares(&self) -> &[Arc<dyn Middleware>] {
        &self.items
    }
}

impl MiddlewareChainMut for MiddlewareChain {
    fn push(&mut self, mw: Arc<dyn Middleware>) {
        self.items.push(mw);
    }

    fn middlewares_mut(&mut self) -> &mut Vec<Arc<dyn Middleware>> {
        &mut self.items
    }
}