reinhardt-urls 0.2.2

//! URL resolver trait for type-safe URL generation.
//!
//! This module provides the `UrlResolver` trait, the foundation for
//! compile-time type-safe URL resolution. View macros (`#[get]`, `#[post]`,
//! etc.) generate extension traits with blanket implementations that add
//! named accessor methods to any `UrlResolver` implementor.
//!
//! # Architecture
//!
//! ```text
//! #[get("/login/", name = "auth_login")]
//!     ↓ (inventory registration)
//! UrlReverser::from_global().reverse("server:auth:login", &HashMap::new())
//! ```
//!
//! # Usage
//!
//! ```rust,ignore
//! let reverser = UrlReverser::from_global();
//! let login_url = reverser.reverse("server:auth:login", &HashMap::new())?;
//! let detail_url = reverser.reverse_with("server:clusters:retrieve", &[("id", "x")])?;
//! ```

/// Base trait for type-safe URL resolution.
///
/// Implementors provide URL lookup by route name and parameters.
/// Extension traits generated by view macros (`#[get]`, `#[post]`, etc.)
/// use this as a supertrait to add named accessor methods via blanket impls.
///
/// # Example
///
/// ```rust
/// use reinhardt_urls::routers::resolver::UrlResolver;
///
/// struct MyResolver;
///
/// impl UrlResolver for MyResolver {
///     fn resolve_url(&self, name: &str, params: &[(&str, &str)]) -> String {
///         format!("/{}/", name)
///     }
/// }
///
/// let resolver = MyResolver;
/// assert_eq!(resolver.resolve_url("home", &[]), "/home/");
/// ```
pub trait UrlResolver {
	/// Resolve a URL by route name and parameters.
	///
	/// # Panics
	///
	/// Implementations should panic if the route name is not registered.
	fn resolve_url(&self, name: &str, params: &[(&str, &str)]) -> String;

	/// Non-panicking variant of `resolve_url`. Default returns `None`.
	///
	/// Override in implementations that have a route-lookup table to probe
	/// candidate namespaces without panicking.
	///
	/// Refs Issue #4507.
	fn try_resolve_url(&self, _name: &str, _params: &[(&str, &str)]) -> Option<String> {
		None
	}
}

/// Trait for resolving client-side (frontend) URLs by route name.
///
/// This is the client-side counterpart to [`UrlResolver`]. While `UrlResolver`
/// resolves server-side API/backend routes, `ClientUrlResolver` resolves
/// frontend routes registered via `ClientRouter`.
///
/// # Panics
///
/// Implementations should panic if the route name is not found, consistent
/// with [`UrlResolver::resolve_url()`].
///
/// # Example
///
/// ```rust
/// use reinhardt_urls::routers::resolver::ClientUrlResolver;
///
/// struct MyClientResolver;
///
/// impl ClientUrlResolver for MyClientResolver {
///     fn resolve_client_url(&self, name: &str, params: &[(&str, &str)]) -> String {
///         format!("/client/{}/", name)
///     }
/// }
///
/// let resolver = MyClientResolver;
/// assert_eq!(resolver.resolve_client_url("home", &[]), "/client/home/");
/// ```
pub trait ClientUrlResolver {
	/// Resolve a client-side URL by route name and parameters.
	fn resolve_client_url(&self, name: &str, params: &[(&str, &str)]) -> String;
}

// `StreamingTopicResolver` is defined canonically in `reinhardt-streaming`
// and re-exported from `crate::routers` (see routers.rs) to keep a single
// source of truth. The `#[producer]`/`#[consumer]` macros implement the
// `reinhardt-streaming` trait directly.

/// Trait for resolving WebSocket endpoint URLs by route name.
///
/// Parallel to [`UrlResolver`] for HTTP routes. Extension traits generated by
/// `#[websocket]` use this as a supertrait to add named accessor methods via
/// blanket impls.
///
/// # Panics
///
/// Implementations should panic if the route name is not registered.
///
/// # Example
///
/// ```rust
/// use reinhardt_urls::routers::resolver::WebSocketUrlResolver;
///
/// struct MyWsResolver;
///
/// impl WebSocketUrlResolver for MyWsResolver {
///     fn resolve_ws_url(&self, name: &str, params: &[(&str, &str)]) -> String {
///         format!("/ws/{}/", name)
///     }
/// }
///
/// let resolver = MyWsResolver;
/// assert_eq!(resolver.resolve_ws_url("chat", &[]), "/ws/chat/");
/// ```
pub trait WebSocketUrlResolver {
	/// Resolve a WebSocket URL by route name and path parameters.
	fn resolve_ws_url(&self, name: &str, params: &[(&str, &str)]) -> String;
}

#[cfg(test)]
mod ws_resolver_tests {
	use super::*;
	use rstest::rstest;

	struct MockWsResolver;
	impl WebSocketUrlResolver for MockWsResolver {
		fn resolve_ws_url(&self, name: &str, params: &[(&str, &str)]) -> String {
			let suffix = params.iter().map(|(_, v)| *v).collect::<Vec<_>>().join("/");
			if suffix.is_empty() {
				format!("/ws/{}/", name)
			} else {
				format!("/ws/{}/{}/", name, suffix)
			}
		}
	}

	#[rstest]
	fn test_websocket_url_resolver_trait() {
		// Arrange
		let resolver = MockWsResolver;
		// Act
		let url = resolver.resolve_ws_url("chat_ws", &[("room_id", "42")]);
		// Assert
		assert_eq!(url, "/ws/chat_ws/42/");
	}

	#[rstest]
	fn test_websocket_url_resolver_no_params() {
		// Arrange
		let resolver = MockWsResolver;
		// Act
		let url = resolver.resolve_ws_url("notif_ws", &[]);
		// Assert
		assert_eq!(url, "/ws/notif_ws/");
	}
}