//! # Router Module
//!
//! This module provides the core traits and types for the routing system in Moonbeam.
//!
//! It includes:
//! - `RouteHandler`: A trait for types that can handle HTTP requests within a router.
//! - `PathParams`: A wrapper for extracting named path parameters from the URL.
//! - `FromParams`: A trait for converting raw path parameters into strongly-typed values.
//!
//! The routing system is designed to be used with the `#[route]` and `router!` macros
//! provided by the `moonbeam` crate (via `moonbeam-attributes`).

mod path_params;
pub use path_params::{FromParams, PathParams};
mod extractors;

use crate::{
	http::{Request, Response},
	server::task::Spawner,
};
use std::future::Future;

/// Trait implemented by route handlers generated by the `#[route]` macro.
///
/// This trait defines the interface for handling requests with support for:
/// - Path parameters (e.g., `/users/:id`)
/// - Rest parameters (e.g., `/static/*path`)
/// - Application state injection
/// - Async argument extraction via `FromRequest`
///
/// Implementations of this trait are typically generated automatically by the `#[route]` macro.
/// While the trait's `call` method returns a concrete `Response`, the `#[route]` macro
/// allows the decorated function to return any type that implements `Into<Response>`.
#[cfg_attr(docsrs, doc(cfg(feature = "router")))]
pub trait RouteHandler<State> {
	/// Handles an incoming HTTP request.
	///
	/// # Arguments
	///
	/// * `req` - The incoming HTTP request.
	/// * `params` - A slice of path parameter values extracted from the URL.
	/// * `spawner` - A spawner for asynchronous task execution.
	/// * `state` - A reference to the application state.
	fn call<'buf, 'state: 'exec, 'exec>(
		&self,
		req: Request<'_, 'buf>,
		params: &[&'buf str],
		spawner: Spawner<'exec>,
		state: &'state State,
	) -> impl Future<Output = Response>;
}
