Skip to content

Commit 89fc641

Browse files
raphael-goetzraphael-goetz
authored
Merge pull request #192 from code0-tech/#122-setup-telescopium
setup telescopium
2 parents 16a7cdb + 9941d9f commit 89fc641

8 files changed

Lines changed: 323 additions & 16 deletions

File tree

‎.env-example‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,13 @@
11
ENVIRONMENT='development'
22
MODE='dynamic'
3+
34
NATS_URL='nats://localhost:4222'
4-
AQUILA_URL='http://localhost:8080'
5+
AQUILA_URL='http://localhost:50051'
6+
AQUILA_TOKEN='token'
7+
58
WITH_HEALTH_SERVICE=false
69
GRPC_HOST='127.0.0.1'
710
GRPC_PORT=50051
8-
DEFINITIONS='./definitions'
11+
12+
DEFINITIONS='./definitions'
13+
RUNTIME_STATUS_UPDATE_INTERVAL_SECONDS=30

‎README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Taurus
2+
The heart of the execution block - the runtime itself
3+
4+
- Executes flows and handles test executions
5+
- Requests single node executions from Actions
6+
- Serves the standard CodeZero library
7+
8+
## Used Technologies
9+
10+
[Rust](https://www.rust-lang.org/) x [Tonic](https://docs.rs/tonic/latest/tonic/)
11+
12+
## Contribute / Setup
13+
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.

‎crates/taurus/src/app/mod.rs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -135,12 +135,12 @@ async fn setup_dynamic_services_if_needed(
135135
.await;
136136
}
137137

138-
let runtime_status_heartbeat_task = if config.adapter_status_update_interval_seconds > 0 {
138+
let runtime_status_heartbeat_task = if config.runtime_status_update_interval_seconds > 0 {
139139
let status_service = runtime_status_service
140140
.as_ref()
141141
.expect("runtime status service should exist in dynamic mode")
142142
.clone();
143-
let update_interval_seconds = config.adapter_status_update_interval_seconds;
143+
let update_interval_seconds = config.runtime_status_update_interval_seconds;
144144

145145
let handle = tokio::spawn(async move {
146146
let mut interval = tokio::time::interval(Duration::from_secs(update_interval_seconds));

‎crates/taurus/src/config/mod.rs‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,18 @@
11
use code0_flow::flow_config::env_with_default;
2+
use code0_flow::flow_config::environment::Environment;
23
use code0_flow::flow_config::mode::Mode;
34

45
/// Struct for all relevant `Taurus` startup configurations
56
pub struct Config {
6-
/// Aquila mode
7+
pub environment: Environment,
8+
/// Taurus mode
79
///
810
/// Options:
911
/// `static` (default)
10-
/// `hybrid`
12+
/// `dynamic`
1113
pub mode: Mode,
1214

15+
/// URL to the NATS service
1316
pub nats_url: String,
1417

1518
pub aquila_url: String,
@@ -26,16 +29,17 @@ pub struct Config {
2629

2730
/// Runtime status heartbeat interval in seconds while Taurus is running.
2831
/// Set to 0 to disable periodic heartbeat updates.
29-
pub adapter_status_update_interval_seconds: u64,
32+
pub runtime_status_update_interval_seconds: u64,
3033
}
3134

32-
/// Implementation for all relevant `Aquila` startup configurations
35+
/// Implementation for all relevant `Taurus` startup configurations
3336
///
3437
/// Behavior:
3538
/// Searches for the env. file at root level. Filename: `.env`
3639
impl Config {
3740
pub fn new() -> Self {
3841
Config {
42+
environment: env_with_default("ENVIRONMENT", Environment::Development),
3943
mode: env_with_default("MODE", Mode::DYNAMIC),
4044
nats_url: env_with_default("NATS_URL", String::from("nats://localhost:4222")),
4145
aquila_url: env_with_default("AQUILA_URL", String::from("http://localhost:50051")),
@@ -44,8 +48,8 @@ impl Config {
4448
grpc_host: env_with_default("GRPC_HOST", "127.0.0.1".to_string()),
4549
grpc_port: env_with_default("GRPC_PORT", 50051),
4650
definitions: env_with_default("DEFINITIONS", String::from("./definitions")),
47-
adapter_status_update_interval_seconds: env_with_default(
48-
"ADAPTER_STATUS_UPDATE_INTERVAL_SECONDS",
51+
runtime_status_update_interval_seconds: env_with_default(
52+
"RUNTIME_STATUS_UPDATE_INTERVAL_SECONDS",
4953
30_u64,
5054
),
5155
}

‎docs/dev.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
title: Taurus Development Guide
3+
---
4+
5+
This guide is for contributors working on Taurus itself.
6+
It documents how Taurus is structured, how execution flows through the runtime, and how to run and test changes locally.
7+
8+
## What Taurus Does
9+
10+
Taurus is the execution runtime in the CodeZero execution block.
11+
12+
- Consumes flow execution requests from NATS (`execution.*`)
13+
- Executes flow graphs via `taurus-core::runtime::engine::ExecutionEngine`
14+
- Emits lifecycle events to NATS (`runtime.emitter.<execution_id>`)
15+
- Delegates remote nodes to external services over NATS (`action.<service>.<execution_id>`)
16+
- Reports runtime status and usage to Aquila in dynamic mode
17+
18+
## Workspace Layout
19+
20+
| Path | Purpose |
21+
| --- | --- |
22+
| `crates/taurus` | Main runtime binary (startup, config, NATS worker, dynamic integrations) |
23+
| `crates/taurus-core` | Execution engine, compiler, runtime functions, errors, tracing |
24+
| `crates/taurus-provider` | Transport adapters (NATS emitter + NATS remote runtime) |
25+
| `crates/taurus-manual` | Manual CLI executor for running a single validation flow file |
26+
| `crates/taurus-tests` | Local execution-suite runner for JSON flow fixtures under `flows/` |
27+
| `flows/` | Example/validation flow cases used by `taurus-tests` |
28+
29+
## Runtime Flow
30+
31+
```mermaid
32+
graph TD
33+
NATS[NATS]
34+
Taurus[Taurus Runtime
35+
crates/taurus]
36+
Core[ExecutionEngine
37+
crates/taurus-core]
38+
Emitter[Runtime Emitter
39+
crates/taurus-provider]
40+
Remote[Remote Runtime Adapter
41+
crates/taurus-provider]
42+
Service[Remote Service / Action Runtime]
43+
Aquila[Aquila gRPC APIs
44+
dynamic mode only]
45+
46+
NATS -->|execution.*| Taurus
47+
Taurus --> Core
48+
Core --> Emitter
49+
Emitter -->|runtime.emitter.<execution_id>| NATS
50+
Core --> Remote
51+
Remote -->|action.<service>.<execution_id>| NATS
52+
NATS --> Service
53+
Taurus -->|runtime status + usage| Aquila
54+
```
55+
56+
### Execution details
57+
58+
1. Taurus subscribes to queue subject `execution.*` with queue group `taurus`.
59+
2. Incoming payload is decoded as `tucana::shared::ExecutionFlow`.
60+
3. `ExecutionEngine::execute_flow_with_execution_id(...)` compiles and executes nodes.
61+
4. Local nodes run handlers from the built-in function registry.
62+
5. Non-local `definition_source` values are executed remotely via `RemoteRuntime`.
63+
6. Lifecycle events are emitted as `starting`, `ongoing`, `finished`, or `failed`.
64+
65+
## Runtime Modes
66+
67+
Taurus mode is controlled by `MODE`.
68+
69+
### `dynamic`
70+
71+
`dynamic` enables control-plane integrations:
72+
73+
- Sends definitions to Aquila (retry loop until success)
74+
- Starts runtime status reporting (including heartbeat)
75+
- Sends runtime usage updates after each flow run
76+
77+
### `static`
78+
79+
`static` disables those control-plane interactions.
80+
81+
- Taurus still executes flows from NATS
82+
- No definition push
83+
- No runtime status updates
84+
- No runtime usage updates
85+
86+
## Environment Variables
87+
88+
Defaults are defined in `crates/taurus/src/config/mod.rs`.
89+
90+
| Name | Description | Default |
91+
| --- | --- | --- |
92+
| `ENVIRONMENT` | Running env | `development` |
93+
| `MODE` | Runtime mode (`dynamic` or `static`) | `dynamic` |
94+
| `NATS_URL` | NATS connection URL | `nats://localhost:4222` |
95+
| `AQUILA_URL` | Aquila gRPC endpoint (used in dynamic mode) | `http://localhost:50051` |
96+
| `AQUILA_TOKEN` | Auth token for Aquila runtime APIs | `token` |
97+
| `WITH_HEALTH_SERVICE` | Enables gRPC health server | `false` |
98+
| `GRPC_HOST` | Health server host | `127.0.0.1` |
99+
| `GRPC_PORT` | Health server port | `50051` |
100+
| `DEFINITIONS` | Path sent to `FlowUpdateService` for definition sync | `./definitions` |
101+
| `RUNTIME_STATUS_UPDATE_INTERVAL_SECONDS` | Heartbeat interval in dynamic mode (`0` disables heartbeat) | `30` |
102+
103+
## Local Development
104+
105+
### 1. Start dependencies
106+
107+
At minimum, start a reachable NATS instance at `NATS_URL`.
108+
109+
### 2. Configure environment
110+
111+
Create `.env` in the repository root (you can copy from `.env-example` and extend it).
112+
113+
### 3. Run Taurus
114+
115+
```bash
116+
cargo run -p taurus
117+
```
118+
119+
### 4. Run the execution suite
120+
121+
```bash
122+
cargo run -p tests
123+
```
124+
125+
This executes all JSON files in `./flows` and compares runtime outputs.
126+
127+
### 5. Run one flow manually
128+
129+
```bash
130+
cargo run -p manual -- --path ./flows/01_return_object.json --index 0 --nats-url nats://127.0.0.1:4222
131+
```
132+
133+
This is useful when debugging one case or remote-execution behavior.
134+
135+
## Testing
136+
137+
- Core unit/integration tests:
138+
139+
```bash
140+
cargo test -p taurus-core
141+
```
142+
143+
- Full workspace checks (recommended before merge):
144+
145+
```bash
146+
cargo test
147+
```
148+
149+
## Extending Taurus
150+
151+
### Add or modify built-in functions
152+
153+
- Implement handler logic in `crates/taurus-core/src/runtime/functions/*`
154+
- Register function IDs via the `FUNCTIONS` arrays
155+
- Registration is aggregated through `ALL_FUNCTION_SETS` in `runtime/functions/mod.rs`
156+
157+
### Remote execution routing rule
158+
159+
In the compiler, a node is treated as local when `definition_source` is:
160+
161+
- empty
162+
- `taurus`
163+
- prefixed with `draco`
164+
165+
Any other source is routed as remote execution to that service name.

crates/taurus-core/src/ERROR_CODES.md renamed to docs/errors.md

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
1-
# Taurus Runtime Error Codes
1+
---
2+
title: Taurus Error Table
3+
---
4+
5+
## Taurus Runtime Error Codes
26

37
This document is the canonical catalog for runtime error codes emitted by Taurus runtime crates (`taurus-core` and `taurus-provider`).
48

59
## Code Format
610

711
- `T-STD-XXXXX`: Errors originating inside standard function implementations under `runtime/functions/*`.
8-
- `T-CORE-XXXXXX`: Errors originating from core runtime infrastructure (`engine`, `handler`, type conversion, app-layer mapping).
12+
- `T-CORE-XXXXXX`: Errors originating from core runtime infrastructure.
913
- `T-PROV-XXXXXX`: Errors originating from provider integrations (transport adapters, remote runtime connectors).
1014

1115
## Code Table
@@ -37,4 +41,6 @@ This document is the canonical catalog for runtime error codes emitted by Taurus
3741

3842
## Provider Note
3943

40-
`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.
44+
`taurus-provider` can also forward remote service errors with service-owned codes (for example
45+
codes returned inside Aquila `ExecutionResult::Error`). Those are intentionally preserved instead of remapped,
46+
so they are not enumerated as static Taurus provider codes here.

‎docs/index.mdx‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,18 @@
11
---
2-
title: Welcome to the Documentation for Taurus
3-
description: Find out how the execution works
2+
title: Welcome to Taurus Documentation
3+
description: Learn how Taurus works and how to build with it
44
template: splash
55
---
66

7-
Taurus executes Flows.
7+
## What is Taurus?
8+
9+
Taurus runs inside the execution block and serves as the runtime itself.
10+
It handles flow execution requests and requests single node executions from Actions.
11+
12+
---
13+
14+
If you want to work on or with Taurus, start here:
15+
16+
- **[Setup Guide](installation.mdx)**: install and configure Taurus for local or containerized use, with Aquila required for dynamic mode.
17+
- **[Development Guide](dev.md)**: runtime architecture.
18+
- **[Error Table](errors.md)**: table of possible runtime errors.

0 commit comments

Comments
 (0)