move rhailib to herolib

2025-08-21 14:32:24 +02:00
parent aab2b6f128
commit aa0248ef17
121 changed files with 16412 additions and 0 deletions
--- a/rhailib/docs/DISPATCHER_FLOW_ARCHITECTURE.md
+++ b/rhailib/docs/DISPATCHER_FLOW_ARCHITECTURE.md
@@ -0,0 +1,367 @@
+# Dispatcher-Based Event-Driven Flow Architecture
+
+## Overview
+
+This document describes the implementation of a non-blocking, event-driven flow architecture for Rhai payment functions using the existing RhaiDispatcher. The system transforms blocking API calls into fire-and-continue patterns where HTTP requests spawn background threads that dispatch new Rhai scripts based on API responses.
+
+## Architecture Principles
+
+### 1. **Non-Blocking API Calls**
+- All payment functions (e.g., `create_payment_intent()`) return immediately
+- HTTP requests happen in background threads
+- No blocking of the main Rhai engine thread
+
+### 2. **Self-Dispatching Pattern**
+- Worker dispatches scripts to itself
+- Same `worker_id` and `context_id` maintained
+- `caller_id` changes to reflect the API response source
+
+### 3. **Generic Request/Response Flow**
+- Request functions: `new_..._request` pattern
+- Response scripts: `new_..._response` pattern
+- Consistent naming across all API operations
+
+## Flow Architecture
+
+```mermaid
+graph TD
+    A[main.rhai] --> B[create_payment_intent]
+    B --> C[HTTP Thread Spawned]
+    B --> D[Return Immediately]
+    C --> E[Stripe API Call]
+    E --> F{API Response}
+    F -->|Success| G[Dispatch: new_create_payment_intent_response]
+    F -->|Error| H[Dispatch: new_create_payment_intent_error]
+    G --> I[Response Script Execution]
+    H --> J[Error Script Execution]
+```
+
+## Implementation Components
+
+### 1. **FlowManager**
+
+```rust
+use rhai_dispatcher::{RhaiDispatcher, RhaiDispatcherBuilder, RhaiDispatcherError};
+use std::sync::{Arc, Mutex};
+
+pub struct FlowManager {
+    dispatcher: RhaiDispatcher,
+    worker_id: String,
+    context_id: String,
+}
+
+#[derive(Debug)]
+pub enum FlowError {
+    DispatcherError(RhaiDispatcherError),
+    ConfigurationError(String),
+}
+
+impl From<RhaiDispatcherError> for FlowError {
+    fn from(err: RhaiDispatcherError) -> Self {
+        FlowError::DispatcherError(err)
+    }
+}
+
+impl FlowManager {
+    pub fn new(worker_id: String, context_id: String) -> Result<Self, FlowError> {
+        let dispatcher = RhaiDispatcherBuilder::new()
+            .caller_id("stripe") // API responses come from Stripe
+            .worker_id(&worker_id)
+            .context_id(&context_id)
+            .redis_url("redis://127.0.0.1/")
+            .build()?;
+            
+        Ok(Self {
+            dispatcher,
+            worker_id,
+            context_id,
+        })
+    }
+    
+    pub async fn dispatch_response_script(&self, script_name: &str, data: &str) -> Result<(), FlowError> {
+        let script_content = format!(
+            r#"
+            // Auto-generated response script for {}
+            let response_data = `{}`;
+            let parsed_data = parse_json(response_data);
+            
+            // Include the response script
+            eval_file("flows/{}.rhai");
+            "#,
+            script_name,
+            data.replace('`', r#"\`"#),
+            script_name
+        );
+        
+        self.dispatcher
+            .new_play_request()
+            .worker_id(&self.worker_id)
+            .context_id(&self.context_id)
+            .script(&script_content)
+            .submit()
+            .await?;
+            
+        Ok(())
+    }
+    
+    pub async fn dispatch_error_script(&self, script_name: &str, error: &str) -> Result<(), FlowError> {
+        let script_content = format!(
+            r#"
+            // Auto-generated error script for {}
+            let error_data = `{}`;
+            let parsed_error = parse_json(error_data);
+            
+            // Include the error script
+            eval_file("flows/{}.rhai");
+            "#,
+            script_name,
+            error.replace('`', r#"\`"#),
+            script_name
+        );
+        
+        self.dispatcher
+            .new_play_request()
+            .worker_id(&self.worker_id)
+            .context_id(&self.context_id)
+            .script(&script_content)
+            .submit()
+            .await?;
+            
+        Ok(())
+    }
+}
+
+// Global flow manager instance
+static FLOW_MANAGER: Mutex<Option<FlowManager>> = Mutex::new(None);
+
+pub fn initialize_flow_manager(worker_id: String, context_id: String) -> Result<(), FlowError> {
+    let manager = FlowManager::new(worker_id, context_id)?;
+    let mut global_manager = FLOW_MANAGER.lock().unwrap();
+    *global_manager = Some(manager);
+    Ok(())
+}
+
+pub fn get_flow_manager() -> Result<FlowManager, FlowError> {
+    let global_manager = FLOW_MANAGER.lock().unwrap();
+    global_manager.as_ref()
+        .ok_or_else(|| FlowError::ConfigurationError("Flow manager not initialized".to_string()))
+        .map(|manager| FlowManager {
+            dispatcher: manager.dispatcher.clone(), // Assuming Clone is implemented
+            worker_id: manager.worker_id.clone(),
+            context_id: manager.context_id.clone(),
+        })
+}
+```
+
+### 2. **Non-Blocking Payment Functions**
+
+```rust
+// Transform blocking function into non-blocking
+#[rhai_fn(name = "create", return_raw)]
+pub fn create_payment_intent(intent: &mut RhaiPaymentIntent) -> Result<String, Box<EvalAltResult>> {
+    let form_data = prepare_payment_intent_data(intent);
+    
+    // Get flow manager
+    let flow_manager = get_flow_manager()
+        .map_err(|e| format!("Flow manager error: {:?}", e))?;
+    
+    // Spawn background thread for HTTP request
+    let stripe_config = get_stripe_config()?;
+    thread::spawn(move || {
+        let rt = Runtime::new().expect("Failed to create runtime");
+        rt.block_on(async {
+            match make_stripe_request(&stripe_config, "payment_intents", &form_data).await {
+                Ok(response) => {
+                    if let Err(e) = flow_manager.dispatch_response_script(
+                        "new_create_payment_intent_response",
+                        &response
+                    ).await {
+                        eprintln!("Failed to dispatch response: {:?}", e);
+                    }
+                }
+                Err(error) => {
+                    if let Err(e) = flow_manager.dispatch_error_script(
+                        "new_create_payment_intent_error", 
+                        &error
+                    ).await {
+                        eprintln!("Failed to dispatch error: {:?}", e);
+                    }
+                }
+            }
+        });
+    });
+    
+    // Return immediately with confirmation
+    Ok("payment_intent_request_dispatched".to_string())
+}
+
+// Generic async HTTP request function
+async fn make_stripe_request(
+    config: &StripeConfig, 
+    endpoint: &str, 
+    form_data: &HashMap<String, String>
+) -> Result<String, String> {
+    let url = format!("{}/{}", STRIPE_API_BASE, endpoint);
+    
+    let response = config.client
+        .post(&url)
+        .basic_auth(&config.secret_key, None::<&str>)
+        .form(form_data)
+        .send()
+        .await
+        .map_err(|e| format!("HTTP request failed: {}", e))?;
+    
+    let response_text = response.text().await
+        .map_err(|e| format!("Failed to read response: {}", e))?;
+    
+    let json: serde_json::Value = serde_json::from_str(&response_text)
+        .map_err(|e| format!("Failed to parse JSON: {}", e))?;
+    
+    if json.get("error").is_some() {
+        Err(response_text)
+    } else {
+        Ok(response_text)
+    }
+}
+```
+
+### 3. **Flow Script Templates**
+
+#### Success Response Script
+```rhai
+// flows/new_create_payment_intent_response.rhai
+let payment_intent_id = parsed_data.id;
+let status = parsed_data.status;
+
+print(`✅ Payment Intent Created: ${payment_intent_id}`);
+print(`Status: ${status}`);
+
+// Continue the flow based on status
+if status == "requires_payment_method" {
+    print("Payment method required - ready for frontend");
+    // Could dispatch another flow here
+} else if status == "succeeded" {
+    print("Payment completed successfully!");
+    // Dispatch success notification flow
+}
+
+// Store the payment intent ID for later use
+set_context("payment_intent_id", payment_intent_id);
+set_context("payment_status", status);
+```
+
+#### Error Response Script
+```rhai
+// flows/new_create_payment_intent_error.rhai
+let error_type = parsed_error.error.type;
+let error_message = parsed_error.error.message;
+
+print(`❌ Payment Intent Error: ${error_type}`);
+print(`Message: ${error_message}`);
+
+// Handle different error types
+if error_type == "card_error" {
+    print("Card was declined - notify user");
+    // Dispatch user notification flow
+} else if error_type == "rate_limit_error" {
+    print("Rate limited - retry later");
+    // Dispatch retry flow
+} else {
+    print("Unknown error - log for investigation");
+    // Dispatch error logging flow
+}
+
+// Store error details for debugging
+set_context("last_error_type", error_type);
+set_context("last_error_message", error_message);
+```
+
+### 4. **Configuration and Initialization**
+
+```rust
+// Add to payment module initialization
+#[rhai_fn(name = "init_flows", return_raw)]
+pub fn init_flows(worker_id: String, context_id: String) -> Result<String, Box<EvalAltResult>> {
+    initialize_flow_manager(worker_id, context_id)
+        .map_err(|e| format!("Failed to initialize flow manager: {:?}", e))?;
+    
+    Ok("Flow manager initialized successfully".to_string())
+}
+```
+
+## Usage Examples
+
+### 1. **Basic Payment Flow**
+
+```rhai
+// main.rhai
+init_flows("worker-1", "context-123");
+configure_stripe("sk_test_...");
+
+let payment_intent = new_payment_intent()
+    .amount(2000)
+    .currency("usd")
+    .customer("cus_customer123");
+
+// This returns immediately, HTTP happens in background
+let result = payment_intent.create();
+print(`Request dispatched: ${result}`);
+
+// Script ends here, but flow continues in background
+```
+
+### 2. **Chained Flow Example**
+
+```rhai
+// flows/new_create_payment_intent_response.rhai
+let payment_intent_id = parsed_data.id;
+
+if parsed_data.status == "requires_payment_method" {
+    // Chain to next operation
+    let subscription = new_subscription()
+        .customer(get_context("customer_id"))
+        .add_price("price_monthly");
+    
+    // This will trigger new_create_subscription_response flow
+    subscription.create();
+}
+```
+
+## Benefits
+
+### 1. **Non-Blocking Execution**
+- Main Rhai script never blocks on HTTP requests
+- Multiple API calls can happen concurrently
+- Engine remains responsive for other scripts
+
+### 2. **Event-Driven Architecture**
+- Clear separation between request and response handling
+- Easy to add new flow steps
+- Composable and chainable operations
+
+### 3. **Error Handling**
+- Dedicated error flows for each operation
+- Contextual error information preserved
+- Retry and recovery patterns possible
+
+### 4. **Scalability**
+- Each HTTP request runs in its own thread
+- No shared state between concurrent operations
+- Redis-based dispatch scales horizontally
+
+## Implementation Checklist
+
+- [ ] Implement FlowManager with RhaiDispatcher integration
+- [ ] Convert all payment functions to non-blocking pattern
+- [ ] Create flow script templates for all operations
+- [ ] Add flow initialization functions
+- [ ] Test with example payment flows
+- [ ] Update documentation and examples
+
+## Migration Path
+
+1. **Phase 1**: Implement FlowManager and basic infrastructure
+2. **Phase 2**: Convert payment_intent functions to non-blocking
+3. **Phase 3**: Convert remaining payment functions (products, prices, subscriptions, coupons)
+4. **Phase 4**: Create comprehensive flow script library
+5. **Phase 5**: Add advanced features (retries, timeouts, monitoring)