rhailib: Distributed Rhai Scripting for HeroModels

rhailib provides a robust infrastructure for executing Rhai scripts in a distributed manner, primarily designed to integrate with and extend the HeroModels ecosystem. It allows for dynamic scripting capabilities, offloading computation, and enabling flexible automation.

Overview

The rhailib system is composed of three main components working together, leveraging Redis for task queuing and state management:

1. Rhai Engine (src/engine): This crate is the core of the scripting capability. It provides a Rhai engine pre-configured with various HeroModels modules (e.g., Calendar, Flow, Legal). Scripts executed within this engine can interact directly with HeroModels data and logic. The engine is utilized by the rhai_worker to process tasks.

2. Rhai Client (src/client): This crate offers an interface for applications to submit Rhai scripts as tasks to the distributed execution system. Clients can send scripts to named Redis queues (referred to as "contexts"), optionally wait for results, and handle timeouts.

3. Rhai Worker (src/worker): This executable component listens to one or more Redis queues ("contexts") for incoming tasks. When a task (a Rhai script) is received, the worker fetches its details, uses the rhai_engine to execute the script, and then updates the task's status and results back into Redis. Multiple worker instances can be deployed to scale script execution.

Architecture & Workflow

The typical workflow is as follows:

1. Task Submission: An application using rhai_dispatcher submits a Rhai script to a specific Redis list (e.g., rhai:queue:my_context). Task details, including the script and status, are stored in a Redis hash.
2. Task Consumption: A rhai_worker instance, configured to listen to rhai:queue:my_context, picks up the task ID from the queue using a blocking pop operation.
3. Script Execution: The worker retrieves the script from Redis and executes it using an instance of the rhai_engine. This engine provides the necessary HeroModels context for the script.
4. Result Storage: Upon completion (or error), the worker updates the task's status (e.g., completed, failed) and stores any return value or error message in the corresponding Redis hash.
5. Result Retrieval (Optional): The rhai_dispatcher can poll the Redis hash for the task's status and retrieve the results once available.

This architecture allows for:

• Asynchronous script execution.
• Scalable processing of Rhai scripts by running multiple workers.
• Decoupling of script submission from execution.

Project Structure

The core components are organized as separate crates within the src/ directory:

• src/client/: Contains the rhai_dispatcher library.
• src/engine/: Contains the rhai_engine library.
• src/worker/: Contains the rhai_worker library and its executable.

Each of these directories contains its own README.md file with more detailed information about its specific functionality, setup, and usage.

Getting Started

To work with this project:

1. Ensure you have Rust and Cargo installed.
2. A running Redis instance is required for the client and worker components to communicate.
3. Explore the individual README files in src/client/, src/worker/, and src/engine/ for detailed instructions on building, configuring, and running each component.

You can typically build all components using:

cargo build --workspace

Or build and run specific examples or binaries as detailed in their respective READMEs.

Async API Integration

rhailib includes a powerful async architecture that enables Rhai scripts to perform HTTP API calls despite Rhai's synchronous nature. This allows scripts to integrate with external services like Stripe, payment processors, and other REST/GraphQL APIs.

Key Features

• Async HTTP Support: Make API calls from synchronous Rhai scripts
• Multi-threaded Architecture: Uses MPSC channels to bridge sync/async execution
• Built-in Stripe Integration: Complete payment processing capabilities
• Builder Pattern APIs: Fluent, chainable API for creating complex objects
• Error Handling: Graceful error handling with try/catch support
• Environment Configuration: Secure credential management via environment variables

Quick Example

// Configure API client
configure_stripe(STRIPE_API_KEY);

// Create a product with pricing
let product = new_product()
    .name("Premium Software License")
    .description("Professional software solution")
    .metadata("category", "software");

let product_id = product.create();

// Create subscription pricing
let monthly_price = new_price()
    .amount(2999)  // $29.99 in cents
    .currency("usd")
    .product(product_id)
    .recurring("month");

let price_id = monthly_price.create();

// Create a subscription
let subscription = new_subscription()
    .customer("cus_customer_id")
    .add_price(price_id)
    .trial_days(14)
    .create();

Documentation

• Async Architecture Guide: Detailed technical documentation of the async architecture, including design decisions, thread safety, and extensibility patterns.
• API Integration Guide: Practical guide with examples for integrating external APIs, error handling patterns, and best practices.

Purpose

rhailib aims to provide a flexible and powerful way to extend applications with custom logic written in Rhai, executed in a controlled and scalable environment. This is particularly useful for tasks such as:

• Implementing dynamic business rules.
• Automating processes with external API integration.
• Running background computations.
• Processing payments and subscriptions.
• Customizing application behavior without recompilation.
• Integrating with third-party services (Stripe, webhooks, etc.).