feat(hermes): progressive migration proxy (#494)

* feat: add HTTP proxy component for temporary endpoint mirroring

* feat: add document API v2 endpoint and enhance proxy documentation

- Add /api/gateway/v2/document/index endpoint mirroring
- Enhance documentation with comprehensive testing examples
- Update testing section to match test_parity.sh patterns
- Distill documentation while maintaining technical accuracy

* refactor: replace string matching with regex patterns in HTTP proxy

Replace verbose string constants and manual path matching with regex patterns for cleaner, more maintainable routing logic. Patterns are compiled once at startup for performance.

* docs(http-proxy): add missing v1 document endpoint to mirrored endpoints list

The documentation was missing  from the currently
mirrored endpoints section, though it exists in the code implementation.

* refactor: evolve HTTP proxy from mirror to configurable router

- Rename mirror terminology to external routing for clarity
- Update documentation to reflect long-term vision of configurable proxy
- Add TODOs for future configuration system features
- Expand route patterns to handle subpaths and parameters
- Improve code organization and maintainability

* ci dict

* ci fmt

* ci

* Update hermes/apps/athena/modules/http-proxy/Cargo.toml

Co-authored-by: Rafał Chabowski <[email protected]>

* Refactor HTTP proxy routing with RegexSet and update CI to v3.5.11

- Replace individual regex compilation with unified RegexSet for better performance
- Introduce RouteAction enum for cleaner routing logic
- Remove duplicate static regex declarations causing compile errors
- Update catalyst-ci version from v3.5.10 to v3.5.11 across all Earthfiles
- Clean up dictionary and improve code formatting

---------

Co-authored-by: Steven Johnson <[email protected]>
Co-authored-by: Rafał Chabowski <[email protected]>

Author: 3 people

.config/dictionaries/project.dic

@@ -16,7 +16,6 @@ bootstrapper
 BROTLI
 cantopen
 cardano
-catfact
 cbor
 cbork
 cdylib
@@ -238,3 +237,14 @@ xpub
 yamux
 yoroi
 zstack
+reqwest
+projectcatalyst
+yamux
+justfile
+sandboxing
+rustup
+rollouts
+subpaths
+reloadable
+asat
+

hermes/Earthfile

@@ -1,6 +1,6 @@
 VERSION 0.8
 
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/rust:v3.5.10 AS rust-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/rust:v3.5.11 AS rust-ci
 #IMPORT github.com/input-output-hk/catalyst-ci/earthly/rust:feat/disallow-debug-format AS rust-ci
 
 # Use when debugging cat-ci locally.

hermes/apps/athena/modules/http-proxy/Cargo.toml

@@ -9,4 +9,5 @@ crate-type = ["cdylib"]
 [dependencies]
 wit-bindgen = "0.43.0"
 serde = { version = "1.0", features = ["derive"] }
-tracing = "*"
+tracing = "0.1.41"
+regex = "1.10"

hermes/apps/athena/modules/http-proxy/src/lib.rs

@@ -1,137 +1,233 @@
-//! # HTTP Proxy Component - Hermes WASM Module Example
-//! 
-//! **This is a toy example** showing basic HTTP routing in Hermes. Real applications
-//! would add authentication, error handling, configuration, and security features.
-//! 
-//! ## Key Patterns Demonstrated
-//! - HTTP request routing with pattern matching
-//! - Direct HTTP responses vs internal redirects  
-//! - Structured logging with appropriate levels
-//! - WASM component structure for Hermes
-//! 
-//! ## Production Extensions
-//! Real applications could build on this to create:
-//! - API gateways routing to microservices
-//! - Load balancers with backend selection
-//! - Content management systems
-//! - Authentication/authorization layers
-
-// Allow everything since this is generated code.
+//! HTTP Proxy Module - Configurable Request Router
+//!
+//! ## Vision
+//! This module is designed to be a fully configurable HTTP proxy system that can:
+//! - Route requests to different backends based on configurable rules
+//! - Support multiple routing strategies (path-based, header-based, etc.)
+//! - Handle load balancing and failover scenarios
+//! - Provide middleware capabilities for request/response transformation
+//! - Offer dynamic configuration updates without restarts
+//!
+//! ## Current State
+//! At present, the module serves as a temporary bridge to external Cat Voices endpoints
+//! while native implementations are under development. The current focus is on:
+//! - Maintaining API compatibility during the transition period
+//! - Ensuring reliable request forwarding to external services
+//! - Providing seamless user experience while backend services migrate
+//!
+//! ## Roadmap
+//! As native implementations are completed, this module will evolve into a sophisticated
+//! proxy system capable of routing between multiple backends, supporting A/B testing,
+//! gradual rollouts, and advanced traffic management scenarios.
+
 #[allow(clippy::all, unused)]
 mod hermes;
 mod stub;
 
-use crate::hermes::exports::hermes::http_gateway::event::{HttpGatewayResponse};
-use crate::hermes::hermes::binary::api::Bstr;
+use crate::hermes::exports::hermes::http_gateway::event::HttpGatewayResponse;
 use crate::hermes::exports::hermes::http_gateway::event::HttpResponse;
+use crate::hermes::hermes::binary::api::Bstr;
+
+use regex::RegexSet;
+use std::sync::OnceLock;
+
+/// What to do when a route pattern matches
+#[derive(Debug, Clone, Copy)]
+enum RouteAction {
+    External, // Forward to Cat Voices
+    Static,   // Serve natively
+}
+
+/// Compiled patterns for efficient matching
+static ROUTE_MATCHER: OnceLock<(RegexSet, Vec<RouteAction>)> = OnceLock::new();
+
+/// External Cat Voices host for temporary external routing
+/// TODO: Make this configurable via environment variables or config file
+const EXTERNAL_HOST: &str = "https://app.dev.projectcatalyst.io";
+
+/// Route patterns that should be forwarded to external Cat Voices system
+/// TODO: Convert to configurable rules engine supporting dynamic pattern updates
+const EXTERNAL_ROUTE_PATTERNS: &[&str] = &[
+    r"^/api/gateway/v1/config/frontend$",
+    r"^/api/gateway/v1/cardano/assets/.+$",
+    r"^/api/gateway/v1/rbac/registration.*$",
+    r"^/api/gateway/v1/document.*$",
+    r"^/api/gateway/v2/document.*$", //  can handle subpaths and query parameters
+];
+
+/// Regex pattern for static content (handled natively)
+/// TODO: Make static content patterns configurable
+const STATIC_PATTERN: &str = r"^/static/.+$";
 
-/// Simple HTTP proxy component for demonstration purposes.
+/// HTTP proxy component providing configurable request routing.
+///
+/// Currently serves as a temporary bridge to external Cat Voices endpoints
+/// while native implementations are developed. The long-term vision is to
+/// evolve this into a full-featured configurable proxy supporting:
+/// - Dynamic backend selection
+/// - Load balancing strategies  
+/// - Circuit breakers and health checks
+/// - Request/response middleware chains
+/// - A/B testing and canary deployments
 struct HttpProxyComponent;
 
+/// Initialize all route patterns as a single RegexSet
+fn init_route_matcher() -> &'static (RegexSet, Vec<RouteAction>) {
+    ROUTE_MATCHER.get_or_init(|| {
+        let mut patterns = Vec::new();
+        let mut actions = Vec::new();
+
+        // External routes (redirect to Cat Voices)
+        for pattern in EXTERNAL_ROUTE_PATTERNS {
+            patterns.push(*pattern);
+            actions.push(RouteAction::External);
+        }
+
+        // Static content (serve natively)
+        patterns.push(STATIC_PATTERN);
+        actions.push(RouteAction::Static);
+
+        // Compile all patterns together for performance
+        let regex_set = RegexSet::new(&patterns).unwrap_or_else(|e| {
+            log_warn(&format!("Failed to compile patterns: {}", e));
+            RegexSet::empty()
+        });
+
+        (regex_set, actions)
+    })
+}
+
+/// Get the action for a given path
+fn get_route_action(path: &str) -> Option<RouteAction> {
+    let (regex_set, actions) = init_route_matcher();
+    regex_set.matches(path).iter().next().map(|i| actions[i])
+}
+
+/// Check if path should route externally
+fn should_route_externally(path: &str) -> bool {
+    matches!(get_route_action(path), Some(RouteAction::External))
+}
+
+/// Check if path is static content
+fn is_static_content(path: &str) -> bool {
+    matches!(get_route_action(path), Some(RouteAction::Static))
+}
+
+/// Creates an external route redirect response
+/// Currently redirects to Cat Voices - will become configurable backend selection
+fn create_external_redirect(path: &str) -> HttpGatewayResponse {
+    log_debug(&format!("Routing externally to Cat Voices: {}", path));
+    HttpGatewayResponse::InternalRedirect(format!("{}{}", EXTERNAL_HOST, path))
+}
+
+/// Creates a static content response (native handling)
+/// TODO: Integrate with configurable static content serving middleware
+fn create_static_response(path: &str) -> HttpGatewayResponse {
+    log_debug(&format!("Serving static content natively: {}", path));
+    HttpGatewayResponse::Http(HttpResponse {
+        code: 200,
+        headers: vec![("content-type".to_string(), vec!["text/plain".to_string()])],
+        body: Bstr::from(format!("Static file content for: {}", path)),
+    })
+}
+
+/// Creates a 404 not found response
+/// TODO: Make error responses configurable (custom error pages, etc.)
+fn create_not_found_response(
+    method: &str,
+    path: &str,
+) -> HttpGatewayResponse {
+    log_warn(&format!(
+        "Route not found (no native implementation or external routing configured): {} {}",
+        method, path
+    ));
+    HttpGatewayResponse::Http(HttpResponse {
+        code: 404,
+        headers: vec![("content-type".to_string(), vec!["text/html".to_string()])],
+        body: Bstr::from("<html><body><h1>404 - Page Not Found</h1></body></html>"),
+    })
+}
+
+/// Logs an info message
+fn log_info(message: &str) {
+    hermes::hermes::logging::api::log(
+        hermes::hermes::logging::api::Level::Info,
+        Some("http-proxy"),
+        None,
+        None,
+        None,
+        None,
+        message,
+        None,
+    );
+}
+
+/// Logs a debug message
+fn log_debug(message: &str) {
+    hermes::hermes::logging::api::log(
+        hermes::hermes::logging::api::Level::Debug,
+        Some("http-proxy"),
+        None,
+        None,
+        None,
+        None,
+        message,
+        None,
+    );
+}
+
+/// Logs a warning message
+fn log_warn(message: &str) {
+    hermes::hermes::logging::api::log(
+        hermes::hermes::logging::api::Level::Warn,
+        Some("http-proxy"),
+        None,
+        None,
+        None,
+        None,
+        message,
+        None,
+    );
+}
+
+/// Formats the response type for logging
+fn format_response_type(response: &HttpGatewayResponse) -> String {
+    match response {
+        HttpGatewayResponse::Http(resp) => format!("HTTP {}", resp.code),
+        HttpGatewayResponse::InternalRedirect(_) => {
+            "EXTERNAL_REDIRECT (temporary bridge)".to_string()
+        },
+    }
+}
+
 impl hermes::exports::hermes::http_gateway::event::Guest for HttpProxyComponent {
-    /// Handle HTTP requests and return responses or redirects.
-    /// 
-    /// Production systems would add: request validation, authentication,
-    /// caching, error handling, and security headers.
+    /// Routes HTTP requests through configurable proxy logic.
+    ///
+    /// Current implementation provides temporary bridging to external Cat Voices
+    /// endpoints while native implementations are developed. Future versions will
+    /// support sophisticated routing rules, backend selection, and middleware chains.
     fn reply(
         _body: Vec<u8>,
         _headers: hermes::exports::hermes::http_gateway::event::Headers,
         path: String,
         method: String,
     ) -> Option<HttpGatewayResponse> {
-        hermes::hermes::logging::api::log(
-            hermes::hermes::logging::api::Level::Info,
-            Some("http-proxy"),
-            None,
-            None,
-            None,
-            None,
-            format!("Processing HTTP request: {} {}", method, path).as_str(),
-            None,
-        );
-
-        let response = match path.as_str() {
-            "/api" | "/api/index" => {
-                hermes::hermes::logging::api::log(
-                    hermes::hermes::logging::api::Level::Debug,
-                    Some("http-proxy"),
-                    None,
-                    None,
-                    None,
-                    None,
-                    "Serving homepage content",
-                    None,
-                );
-                HttpGatewayResponse::Http(HttpResponse {
-                    code: 200,
-                    headers: vec![("content-type".to_string(), vec!["text/html".to_string()])],
-                    body: Bstr::from("<html><body><h1>Welcome to the homepage</h1></body></html>"),
-                })
-            },
-            "/api/dashboard" => {
-                hermes::hermes::logging::api::log(
-                    hermes::hermes::logging::api::Level::Debug,
-                    Some("http-proxy"),
-                    None,
-                    None,
-                    None,
-                    None,
-                    "Redirecting to external API: https://catfact.ninja/fact",
-                    None,
-                );
-                HttpGatewayResponse::InternalRedirect("https://catfact.ninja/fact".to_string())
-            },
-            path if path.starts_with("/static/") => {
-                hermes::hermes::logging::api::log(
-                    hermes::hermes::logging::api::Level::Debug,
-                    Some("http-proxy"),
-                    None,
-                    None,
-                    None,
-                    None,
-                    format!("Serving static content for: {}", path).as_str(),
-                    None,
-                );
-                HttpGatewayResponse::Http(HttpResponse {
-                    code: 200,
-                    headers: vec![("content-type".to_string(), vec!["text/plain".to_string()])],
-                    body: Bstr::from(format!("Static file content for: {}", path)),
-                })
-            },
-            _ => {
-                hermes::hermes::logging::api::log(
-                    hermes::hermes::logging::api::Level::Warn,
-                    Some("http-proxy"),
-                    None,
-                    None,
-                    None,
-                    None,
-                    format!("Route not found: {} {}", method, path).as_str(),
-                    None,
-                );
-                HttpGatewayResponse::Http(HttpResponse {
-                    code: 404,
-                    headers: vec![("content-type".to_string(), vec!["text/html".to_string()])],
-                    body: Bstr::from("<html><body><h1>404 - Page Not Found</h1></body></html>"),
-                })
-            },
+        log_info(&format!("Processing HTTP request: {} {}", method, path));
+
+        let response = if should_route_externally(&path) {
+            create_external_redirect(&path)
+        } else if is_static_content(&path) {
+            create_static_response(&path)
+        } else {
+            create_not_found_response(&method, &path)
         };
 
-        hermes::hermes::logging::api::log(
-            hermes::hermes::logging::api::Level::Info,
-            Some("http-proxy"),
-            None,
-            None,
-            None,
-            None,
-            format!("Request completed: {} {} -> {}", method, path, 
-                match &response {
-                    HttpGatewayResponse::Http(resp) => format!("HTTP {}", resp.code),
-                    HttpGatewayResponse::InternalRedirect(_) => "REDIRECT".to_string(),
-                }
-            ).as_str(),
-            None,
-        );
+        log_info(&format!(
+            "Request completed: {} {} -> {}",
+            method,
+            path,
+            format_response_type(&response)
+        ));
 
         Some(response)
     }