diff --git a/.env-example b/.env-example index c6307e4..6ee67d5 100644 --- a/.env-example +++ b/.env-example @@ -1,8 +1,13 @@ ENVIRONMENT='development' MODE='dynamic' + NATS_URL='nats://localhost:4222' -AQUILA_URL='http://localhost:8080' +AQUILA_URL='http://localhost:50051' +AQUILA_TOKEN='token' + WITH_HEALTH_SERVICE=false GRPC_HOST='127.0.0.1' GRPC_PORT=50051 -DEFINITIONS='./definitions' \ No newline at end of file + +DEFINITIONS='./definitions' +RUNTIME_STATUS_UPDATE_INTERVAL_SECONDS=30 diff --git a/README.md b/README.md new file mode 100644 index 0000000..0ef7fca --- /dev/null +++ b/README.md @@ -0,0 +1,13 @@ +# Taurus +The heart of the execution block - the runtime itself + +- Executes flows and handles test executions +- Requests single node executions from Actions +- Serves the standard CodeZero library + +## Used Technologies + +[Rust](https://www.rust-lang.org/) x [Tonic](https://docs.rs/tonic/latest/tonic/) + +## Contribute / Setup +Read the [Installation Guide](https://docs.code0.tech/taurus/installation/) if you want to deploy a Taurus instance or see the [Development Guide](https://docs.code0.tech/taurus/dev/) if you want to contribute. diff --git a/crates/taurus/src/app/mod.rs b/crates/taurus/src/app/mod.rs index c794a89..93491ca 100644 --- a/crates/taurus/src/app/mod.rs +++ b/crates/taurus/src/app/mod.rs @@ -135,12 +135,12 @@ async fn setup_dynamic_services_if_needed( .await; } - let runtime_status_heartbeat_task = if config.adapter_status_update_interval_seconds > 0 { + let runtime_status_heartbeat_task = if config.runtime_status_update_interval_seconds > 0 { let status_service = runtime_status_service .as_ref() .expect("runtime status service should exist in dynamic mode") .clone(); - let update_interval_seconds = config.adapter_status_update_interval_seconds; + let update_interval_seconds = config.runtime_status_update_interval_seconds; let handle = tokio::spawn(async move { let mut interval = tokio::time::interval(Duration::from_secs(update_interval_seconds)); diff --git a/crates/taurus/src/config/mod.rs b/crates/taurus/src/config/mod.rs index dd9e550..d0e83a7 100644 --- a/crates/taurus/src/config/mod.rs +++ b/crates/taurus/src/config/mod.rs @@ -1,15 +1,18 @@ use code0_flow::flow_config::env_with_default; +use code0_flow::flow_config::environment::Environment; use code0_flow::flow_config::mode::Mode; /// Struct for all relevant `Taurus` startup configurations pub struct Config { - /// Aquila mode + pub environment: Environment, + /// Taurus mode /// /// Options: /// `static` (default) - /// `hybrid` + /// `dynamic` pub mode: Mode, + /// URL to the NATS service pub nats_url: String, pub aquila_url: String, @@ -26,16 +29,17 @@ pub struct Config { /// Runtime status heartbeat interval in seconds while Taurus is running. /// Set to 0 to disable periodic heartbeat updates. - pub adapter_status_update_interval_seconds: u64, + pub runtime_status_update_interval_seconds: u64, } -/// Implementation for all relevant `Aquila` startup configurations +/// Implementation for all relevant `Taurus` startup configurations /// /// Behavior: /// Searches for the env. file at root level. Filename: `.env` impl Config { pub fn new() -> Self { Config { + environment: env_with_default("ENVIRONMENT", Environment::Development), mode: env_with_default("MODE", Mode::DYNAMIC), nats_url: env_with_default("NATS_URL", String::from("nats://localhost:4222")), aquila_url: env_with_default("AQUILA_URL", String::from("http://localhost:50051")), @@ -44,8 +48,8 @@ impl Config { grpc_host: env_with_default("GRPC_HOST", "127.0.0.1".to_string()), grpc_port: env_with_default("GRPC_PORT", 50051), definitions: env_with_default("DEFINITIONS", String::from("./definitions")), - adapter_status_update_interval_seconds: env_with_default( - "ADAPTER_STATUS_UPDATE_INTERVAL_SECONDS", + runtime_status_update_interval_seconds: env_with_default( + "RUNTIME_STATUS_UPDATE_INTERVAL_SECONDS", 30_u64, ), } diff --git a/docs/dev.md b/docs/dev.md new file mode 100644 index 0000000..9290963 --- /dev/null +++ b/docs/dev.md @@ -0,0 +1,165 @@ +--- +title: Taurus Development Guide +--- + +This guide is for contributors working on Taurus itself. +It documents how Taurus is structured, how execution flows through the runtime, and how to run and test changes locally. + +## What Taurus Does + +Taurus is the execution runtime in the CodeZero execution block. + +- Consumes flow execution requests from NATS (`execution.*`) +- Executes flow graphs via `taurus-core::runtime::engine::ExecutionEngine` +- Emits lifecycle events to NATS (`runtime.emitter.`) +- Delegates remote nodes to external services over NATS (`action..`) +- Reports runtime status and usage to Aquila in dynamic mode + +## Workspace Layout + +| Path | Purpose | +| --- | --- | +| `crates/taurus` | Main runtime binary (startup, config, NATS worker, dynamic integrations) | +| `crates/taurus-core` | Execution engine, compiler, runtime functions, errors, tracing | +| `crates/taurus-provider` | Transport adapters (NATS emitter + NATS remote runtime) | +| `crates/taurus-manual` | Manual CLI executor for running a single validation flow file | +| `crates/taurus-tests` | Local execution-suite runner for JSON flow fixtures under `flows/` | +| `flows/` | Example/validation flow cases used by `taurus-tests` | + +## Runtime Flow + +```mermaid +graph TD + NATS[NATS] + Taurus[Taurus Runtime + crates/taurus] + Core[ExecutionEngine + crates/taurus-core] + Emitter[Runtime Emitter + crates/taurus-provider] + Remote[Remote Runtime Adapter + crates/taurus-provider] + Service[Remote Service / Action Runtime] + Aquila[Aquila gRPC APIs + dynamic mode only] + + NATS -->|execution.*| Taurus + Taurus --> Core + Core --> Emitter + Emitter -->|runtime.emitter.| NATS + Core --> Remote + Remote -->|action..| NATS + NATS --> Service + Taurus -->|runtime status + usage| Aquila +``` + +### Execution details + +1. Taurus subscribes to queue subject `execution.*` with queue group `taurus`. +2. Incoming payload is decoded as `tucana::shared::ExecutionFlow`. +3. `ExecutionEngine::execute_flow_with_execution_id(...)` compiles and executes nodes. +4. Local nodes run handlers from the built-in function registry. +5. Non-local `definition_source` values are executed remotely via `RemoteRuntime`. +6. Lifecycle events are emitted as `starting`, `ongoing`, `finished`, or `failed`. + +## Runtime Modes + +Taurus mode is controlled by `MODE`. + +### `dynamic` + +`dynamic` enables control-plane integrations: + +- Sends definitions to Aquila (retry loop until success) +- Starts runtime status reporting (including heartbeat) +- Sends runtime usage updates after each flow run + +### `static` + +`static` disables those control-plane interactions. + +- Taurus still executes flows from NATS +- No definition push +- No runtime status updates +- No runtime usage updates + +## Environment Variables + +Defaults are defined in `crates/taurus/src/config/mod.rs`. + +| Name | Description | Default | +| --- | --- | --- | +| `ENVIRONMENT` | Running env | `development` | +| `MODE` | Runtime mode (`dynamic` or `static`) | `dynamic` | +| `NATS_URL` | NATS connection URL | `nats://localhost:4222` | +| `AQUILA_URL` | Aquila gRPC endpoint (used in dynamic mode) | `http://localhost:50051` | +| `AQUILA_TOKEN` | Auth token for Aquila runtime APIs | `token` | +| `WITH_HEALTH_SERVICE` | Enables gRPC health server | `false` | +| `GRPC_HOST` | Health server host | `127.0.0.1` | +| `GRPC_PORT` | Health server port | `50051` | +| `DEFINITIONS` | Path sent to `FlowUpdateService` for definition sync | `./definitions` | +| `RUNTIME_STATUS_UPDATE_INTERVAL_SECONDS` | Heartbeat interval in dynamic mode (`0` disables heartbeat) | `30` | + +## Local Development + +### 1. Start dependencies + +At minimum, start a reachable NATS instance at `NATS_URL`. + +### 2. Configure environment + +Create `.env` in the repository root (you can copy from `.env-example` and extend it). + +### 3. Run Taurus + +```bash +cargo run -p taurus +``` + +### 4. Run the execution suite + +```bash +cargo run -p tests +``` + +This executes all JSON files in `./flows` and compares runtime outputs. + +### 5. Run one flow manually + +```bash +cargo run -p manual -- --path ./flows/01_return_object.json --index 0 --nats-url nats://127.0.0.1:4222 +``` + +This is useful when debugging one case or remote-execution behavior. + +## Testing + +- Core unit/integration tests: + +```bash +cargo test -p taurus-core +``` + +- Full workspace checks (recommended before merge): + +```bash +cargo test +``` + +## Extending Taurus + +### Add or modify built-in functions + +- Implement handler logic in `crates/taurus-core/src/runtime/functions/*` +- Register function IDs via the `FUNCTIONS` arrays +- Registration is aggregated through `ALL_FUNCTION_SETS` in `runtime/functions/mod.rs` + +### Remote execution routing rule + +In the compiler, a node is treated as local when `definition_source` is: + +- empty +- `taurus` +- prefixed with `draco` + +Any other source is routed as remote execution to that service name. diff --git a/crates/taurus-core/src/ERROR_CODES.md b/docs/errors.md similarity index 94% rename from crates/taurus-core/src/ERROR_CODES.md rename to docs/errors.md index 0a3550b..6355d41 100644 --- a/crates/taurus-core/src/ERROR_CODES.md +++ b/docs/errors.md @@ -1,11 +1,15 @@ -# Taurus Runtime Error Codes +--- +title: Taurus Error Table +--- + +## Taurus Runtime Error Codes This document is the canonical catalog for runtime error codes emitted by Taurus runtime crates (`taurus-core` and `taurus-provider`). ## Code Format - `T-STD-XXXXX`: Errors originating inside standard function implementations under `runtime/functions/*`. -- `T-CORE-XXXXXX`: Errors originating from core runtime infrastructure (`engine`, `handler`, type conversion, app-layer mapping). +- `T-CORE-XXXXXX`: Errors originating from core runtime infrastructure. - `T-PROV-XXXXXX`: Errors originating from provider integrations (transport adapters, remote runtime connectors). ## Code Table @@ -37,4 +41,6 @@ This document is the canonical catalog for runtime error codes emitted by Taurus ## Provider Note -`taurus-provider` can also forward remote service errors with service-owned codes (for example codes returned inside Aquila `ExecutionResult::Error`). Those are intentionally preserved instead of remapped, so they are not enumerated as static Taurus provider codes here. +`taurus-provider` can also forward remote service errors with service-owned codes (for example +codes returned inside Aquila `ExecutionResult::Error`). Those are intentionally preserved instead of remapped, +so they are not enumerated as static Taurus provider codes here. diff --git a/docs/index.mdx b/docs/index.mdx index 4b1e4c9..569fd17 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -1,7 +1,18 @@ --- -title: Welcome to the Documentation for Taurus -description: Find out how the execution works +title: Welcome to Taurus Documentation +description: Learn how Taurus works and how to build with it template: splash --- -Taurus executes Flows. +## What is Taurus? + +Taurus runs inside the execution block and serves as the runtime itself. +It handles flow execution requests and requests single node executions from Actions. + +--- + +If you want to work on or with Taurus, start here: + +- **[Setup Guide](installation.mdx)**: install and configure Taurus for local or containerized use, with Aquila required for dynamic mode. +- **[Development Guide](dev.md)**: runtime architecture. +- **[Error Table](errors.md)**: table of possible runtime errors. diff --git a/docs/installation.mdx b/docs/installation.mdx new file mode 100644 index 0000000..d6d4bef --- /dev/null +++ b/docs/installation.mdx @@ -0,0 +1,103 @@ +--- +title: Taurus Installation Guide +--- + +import {Step, Steps} from 'fumadocs-ui/components/steps'; + +Use this guide to install and configure Taurus. + +## Setup Options + +### Using Docker Compose + +Use Docker Compose to run Taurus and related services. +If you are developing Taurus locally, make sure the Taurus container is stopped to avoid port conflicts. +If your compose setup supports profiles, you can set `COMPOSE_PROFILES=ide` to run only +IDE-related services and start Taurus manually. + +### Virtual Development Environment (Preferred) + +Use the shared environment setup from the main platform docs: + +- [Visit Setup Guide](https://docs.code0.tech/general/install/) + +### Manual Installation + + + + + +#### **Clone Taurus** + +Clone this repository to your local machine. + + + + + +#### **Set up environment variables** + +Configure `.env` in the project root with the required settings. +You can use `.env-example` as a starting point. + + + + + +#### **Ensure required services are running** + +**NATS**: + +- Ensure a NATS instance is reachable +- Enable JetStream +- See [NATS installation docs](https://docs.nats.io/running-a-nats-service/introduction/installation) + +**Aquila**: + +- Required for dynamic mode (`MODE=dynamic`) +- Ensure the configured endpoint is reachable + + + + + +#### **Start Taurus** + +Run: + +```bash +cargo run -p taurus +``` + + + + +--- + +## Environment Variables + +Taurus configuration is split into shared variables and mode-specific variables. + +### Common (Static + Dynamic) + +| Name | Description | Default | +|-----------------------|--------------------------------------------------------------------------------------------------------------|---------------------------------| +| `MODE` | Runtime mode. `static` loads local flows. `dynamic` enables dynamic synchronization with Sagittarius. | `static` | +| `ENVIRONMENT` | Runtime environment (`development`, `staging`, `production`). | `development` | +| `NATS_URL` | URL of the NATS instance Taurus connects to. | `nats://localhost:4222` | +| `AQUILA_URL` | URL of the Aquila instance . | `nats://localhost:4222` | +| `AQUILA_TOKEN` | Token to authenticate agains Aquila. | `nats://localhost:4222` | +| `GRPC_HOST` | Hostname for the Taurus gRPC server. | `127.0.0.1` | +| `GRPC_PORT` | Port for the Taurus gRPC server. | `50051` | +| `WITH_HEALTH_SERVICE` | Enables the gRPC health service when set to `true`. | `false` | + +### Dynamic Mode + +Set `MODE=dynamic` when the IDE is required/needed. + +| Name | Description | Default | +|-------------------|-----------------------------------------------------------------------------------|--------------------------| +| `AQUILA_URL` | URL of the Aquila instance. | `http://localhost:50051` | +| `AQUILA_TOKEN` | Token used by Taurus to authenticate with Aquila. | `token` | +| `DEFINITIONS` | Path to the runtime definition modules. | `./definitions` | +| `RUNTIME_STATUS_UPDATE_INTERVAL_SECONDS` | Interval (in seconds) of updating the current runtime status. | `30s` |