rhailib/README.md

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 "circles"), optionally wait for results, and handle timeouts.

3. Rhai Worker (src/worker): This executable component listens to one or more Redis queues ("circles") 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_client submits a Rhai script to a specific Redis list (e.g., rhai:queue:my_circle). 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_circle, 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_client 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_client 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.

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.
• Running background computations.
• Customizing application behavior without recompilation.