Getting Started

[package]
name = "hello-motore"
version = "0.1.0"
edition = "2024"

[dependencies]
motore = { version = "0"}

# Motore depends on tokio, and we also need a tokio runtime to execute the main function
tokio = { version = "1", features = ["full"] }

/*
 * Motore: A Tower-inspired asynchronous middleware abstraction library for Rust
 *
 * Core Concepts:
 * 1. `Service`: Represents an asynchronous service (Request -> Response).
 * 2. `Layer`: Represents middleware that wraps a `Service` and returns a new `Service`.
 * 3. `Cx`: A mutable context that is passed through the entire call chain. You can use it to pass data throughout the call chain (such as database connections, tracing spans, user information, etc.). This is a major feature of Motore and one of the main differences from Tower.
 */

// -----------------------------------------------------------------------------
// 1. Implement a `Service`
// -----------------------------------------------------------------------------

// First, let's define a context
#[derive(Debug, Clone)]
struct MyContext {
    request_id: u32,
    processing_steps: u32, // Example: a writable context state
}

use motore::service::Service;
use std::convert::Infallible; 

// This is our "string to uppercase" service
struct ToUppercaseService;

// --- Implement the Service trait for ToUppercaseService ---
impl Service<MyContext, String> for ToUppercaseService {
    type Response = String;
    type Error = Infallible; // Infallible means this service will never fail

    async fn call(&self, cx: &mut MyContext, req: String) -> Result<Self::Response, Self::Error> {
        // --- Demonstrate modifying &mut Cx ---
        cx.processing_steps += 1;
        
        println!("[ToUppercaseService] handling req id: {}, step: {}", cx.request_id, cx.processing_steps);
        let res = Ok(req.to_uppercase());
        println!("[ToUppercaseService] responding req id: {}, step: {}", cx.request_id, cx.processing_steps);
        res
    }
}


// -----------------------------------------------------------------------------
// 2. Implement a `Layer`
// -----------------------------------------------------------------------------

// `Layer` (from `motore/src/layer/mod.rs`) is a factory
// that takes an inner service `S` and returns a new, wrapped service `Self::Service`.
/*
pub trait Layer<S> {
    /// The new Service type returned after wrapping
    type Service;

    /// Wraps the inner service S into a new service Self::Service
    fn layer(self, inner: S) -> Self::Service;
}
*/

// --- Implement a `Layer` (logging middleware) ---

// This is the standard pattern for a Layer: "two structs"
// 1. `LogLayer`: The Layer itself (the factory)
#[derive(Clone)]
struct LogLayer {
    target: &'static str,
}

// 2. `LogService<S>`: The new Service returned by the Layer (the wrapper)
#[derive(Clone)]
struct LogService<S> {
    inner: S, // The inner service
    target: &'static str,
}

use motore::layer::Layer;
// Implement the Layer trait for LogLayer
impl<S> Layer<S> for LogLayer {
    type Service = LogService<S>;

    fn layer(self, inner: S) -> Self::Service {
        // Return the new, wrapped Service
        LogService {
            inner,
            target: self.target,
        }
    }
}

impl<Cx, Req, S> Service<Cx, Req> for LogService<S>
where
    // `S` must also be a Service and satisfy constraints like Send/Sync
    S: Service<Cx, Req> + Send + Sync,
    Cx: Send + 'static,
    Req: Send + 'static,
{
    // The response and error types are usually the same as the inner service
    type Response = S::Response;
    type Error = S::Error;

    async fn call(&self, cx: &mut Cx, req: Req) -> Result<Self::Response, Self::Error> {
        // Execute logic before calling the inner service
        println!("[LogLayer] target: {}, enter", self.target);
        
        // Call the inner service
        let result = self.inner.call(cx, req).await;

        // Execute logic after the inner service returns
        match &result {
            Ok(_) => println!("[LogLayer] target: {}, exit (Ok)", self.target),
            Err(_) => println!("[LogLayer] target: {}, exit (Err)", self.target),
        }
        
        result
    }
}

// -----------------------------------------------------------------------------
// 3. Extended Knowledge: How `async fn call` works
// -----------------------------------------------------------------------------

// The core `Service` trait in `motore` (defined in motore/src/service/mod.rs)
// is actually defined like this:
/*
pub trait Service<Cx, Request> {
    /// The response type returned when the service processes successfully
    type Response;
    /// The error type returned when the service fails to process
    type Error;

    /// Core method: process the request and return the response asynchronously
    ///
    /// Note this signature! It is *not* `async fn`.
    /// It is a regular function that returns `impl Future`.
    /// This syntax is known as "Return Position `impl Trait` in Trait" (RPITIT).
    fn call(
        &self,
        cx: &mut Cx,
        req: Request,
    ) -> impl std::future::Future<Output = Result<Self::Response, Self::Error>> + Send;
}
*/

// You might have noticed:
// Why does the `Service` trait require the signature `fn call(...) -> impl Future`,
// but what we wrote (in ToUppercaseService and LogService) was `async fn call`?
// These two signatures are different, so why does it compile?

// The answer is the `async fn in trait` (AFIT) feature.

// With the AFIT feature, `async fn` in a trait is actually "syntactic sugar"
// for `fn ... -> impl Future`.

// When the Rust compiler sees you trying to implement a trait
// that expects `fn call(...) -> impl Future` with `async fn call`,
// it automatically performs this "syntactic sugar" conversion (the process is called desugaring).

// **In summary:**
// 1. Motore's `Service` trait is defined using RPITIT (`fn ... -> impl Future`).
// 2. Rust's AFIT feature allows us to implement this trait directly using `async fn`.
// 3. When writing services and middleware, we get both the convenience of `async/await` and the zero-cost abstractions of `impl Trait`.


// -----------------------------------------------------------------------------
// 4. Assembling Services and Middleware with `ServiceBuilder`
// -----------------------------------------------------------------------------

// `ServiceBuilder` (from `motore/src/builder.rs`)
// allows you to stack multiple Layers onto a Service.

use motore::builder::ServiceBuilder;
use std::time::Duration;
use motore::timeout::TimeoutLayer; // A Layer that comes with Motore

async fn run_builder() {
    // 1. Create a ServiceBuilder
    let builder = ServiceBuilder::new()
        // 2. Add Layers.
        //    Request execution order: top to bottom
        //    Response execution order: bottom to top
        .layer(LogLayer { target: "Outer" })
        .layer(TimeoutLayer::new(Some(Duration::from_secs(1))))
        .layer(LogLayer { target: "Inner" });

    // 3. Apply the Layer stack to an "innermost" service
    //    Here we use `ToUppercaseService` as the core business service
    let service = builder.service(ToUppercaseService);

    // 4. Prepare the context and request
    //    Note: processing_steps starts at 0
    let mut cx = MyContext { request_id: 42, processing_steps: 0 };
    let req = "hello motore".to_string();

    // 5. Call it!
    let res = service.call(&mut cx, req).await;

    println!("\nFinal response: {:?}", res);
    
    /*
     * Expected output:
     *
     * [LogLayer] target: Outer, enter
     * [LogLayer] target: Inner, enter
     * [ToUppercaseService] handling req id: 42, step: 1     <-- step becomes 1
     * [ToUppercaseService] responding req id: 42, step: 1
     * [LogLayer] target: Inner, exit (Ok)
     * [LogLayer] target: Outer, exit (Ok)
     *
     * Final response: Ok("HELLO MOTORE")
     */

     // Finally, the original cx has been modified
     println!("Final context steps: {}", cx.processing_steps); // Will print 1
}

// Fun fact: `ServiceBuilder` also implements the `Layer` trait, which means
// you can nest one `ServiceBuilder` inside another `ServiceBuilder`'s `layer` method:
// --- Suppose we have a bunch of middleware ---
// struct LogLayer;
// struct TimeoutLayer;
// struct AuthLayer;
// struct MetricsLayer;
// struct MyCoreService;
//
// 1. We can create a reusable "authentication" middleware stack
// let auth_stack = ServiceBuilder::new()
//     .layer(MetricsLayer)
//     .layer(AuthLayer);
//
// 2. Now, `auth_stack` is a `ServiceBuilder<...>`
//    Since `ServiceBuilder` implements `Layer`,
//    we can use the entire `auth_stack` as a single `Layer`!
//
// 3. Use `auth_stack` in our main `ServiceBuilder`
// let final_service = ServiceBuilder::new()
//     .layer(LogLayer)
//     .layer(auth_stack) // <-- This step works precisely because `ServiceBuilder` implements `Layer`
//     .layer(TimeoutLayer)
//     .service(MyCoreService);

// -----------------------------------------------------------------------------
// 5. Helper Utility: `service_fn`
// -----------------------------------------------------------------------------

// Sometimes you don't want to create a new struct for a simple service.
// `motore/src/service/service_fn.rs` provides `service_fn`, which can directly convert a compliant function into a `Service`.

use motore::service::service_fn;

async fn my_handler_func(cx: &mut MyContext, req: String) -> Result<String, Infallible> {
    // --- Demonstrate modifying &mut Cx ---
    cx.processing_steps += 10;

    println!("[service_fn] handling req id: {}, step: {}", cx.request_id, cx.processing_steps);
    Ok(req.to_lowercase())
}


#[tokio::main]
async fn main() {
    println!("\n--- Example 1: Running `run_builder` ---");

    run_builder().await;

    println!("\n--- Example 2: Running `service_fn` (standalone) ---");

    // `service_fn` can convert a function or closure that matches the `async fn(&mut Cx, Req) -> Result<Res, Err>` signature
    // directly into a `Service`.
    let fn_service = service_fn(my_handler_func);

    // Let's run it to prove it works
    let mut cx1 = MyContext { request_id: 101, processing_steps: 0 };
    let res1 = fn_service.call(&mut cx1, "HELLO WORLD".to_string()).await;
    // Check the modified context
    println!("service_fn response: {:?}, context steps: {}", res1, cx1.processing_steps); // prints 10


    println!("\n--- Example 3: Running `service_fn` (in a Builder) ---");

    // You can also use it in a ServiceBuilder:
    let service_from_fn = ServiceBuilder::new()
        .layer(LogLayer { target: "ServiceFn" })
        .service_fn(my_handler_func); // shorthand for .service(service_fn(my_handler_func))

    // Run it
    let mut cx2 = MyContext { request_id: 202, processing_steps: 0 };
    let res2 = service_from_fn.call(&mut cx2, "ANOTHER EXAMPLE".to_string()).await;
    // Check the modified context
    println!("service_from_fn response: {:?}, context steps: {}", res2, cx2.processing_steps); // prints 10
}