Skip to content

Commit 5d87e83

Browse files
raphael-goetzraphael-goetz
committed
docs: added dev and installation guide
1 parent 13a38ae commit 5d87e83

2 files changed

Lines changed: 169 additions & 84 deletions

File tree

‎docs/dev.md‎

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

‎docs/installation.mdx‎

Lines changed: 9 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -85,96 +85,21 @@ Taurus configuration is split into shared variables and mode-specific variables.
8585
| `MODE` | Runtime mode. `static` loads local flows. `dynamic` enables dynamic synchronization with Sagittarius. | `static` |
8686
| `ENVIRONMENT` | Runtime environment (`development`, `staging`, `production`). | `development` |
8787
| `NATS_URL` | URL of the NATS instance Aquila connects to. | `nats://localhost:4222` |
88-
| `AQUILA_URL` | URL of the NATS instance Aquila connects to. | `nats://localhost:4222` |
89-
| `AQUILA_TOKEN` | URL of the NATS instance Aquila connects to. | `nats://localhost:4222` |
90-
91-
| `GRPC_HOST` | Hostname for the Aquila gRPC server. | `127.0.0.1` |
92-
| `GRPC_PORT` | Port for the Aquila gRPC server. | `8081` |
88+
| `AQUILA_URL` | URL of the Aquila instance . | `nats://localhost:4222` |
89+
| `AQUILA_TOKEN` | Token to authenticate agains Aquila. | `nats://localhost:4222` |
90+
| `GRPC_HOST` | Hostname for the Taurus gRPC server. | `127.0.0.1` |
91+
| `GRPC_PORT` | Port for the Taurus gRPC server. | `50051` |
9392
| `WITH_HEALTH_SERVICE` | Enables the gRPC health service when set to `true`. | `false` |
94-
| `DEFINITIONS` | Path to the JSON service-configuration file used for runtime/action authorization and default action configs. | `./service.configuration.json` |
95-
| `ADAPTER_STATUS_UPDATE_INTERVAL_SECONDS` | Seconds a runtime serivce will be marked as `not_responding` when no hearbeat was recieved. | `15s` |
96-
| `RUNTIME_STATUS_STOPPED_AFTER_NOT_RESPONDING_SECS` | Seconds a runtime serivce will be marked as `stopped` when no hearbeat was recieved. | `30s` |
97-
| `RUNTIME_STATUS_MONITOR_INTERVAL_SECS` | Interval in which the heartbeat of the services will be flagged/checked. | `3s` |
98-
99-
### Static Mode
100-
101-
Set `MODE=static` to load flows from a local JSON file and insert them into the NATS KV store on startup.
102-
103-
| Name | Description | Default |
104-
|----------------------|-----------------------------------------------|---------------------|
105-
| `FLOW_FALLBACK_PATH` | Path to the flow JSON file loaded at startup. | `./flowExport.json` |
10693

10794
### Dynamic Mode
10895

109-
Set `MODE=hybrid` to keep flows synchronized from Sagittarius.
96+
Set `MODE=dynamic` when the IDE is required/needed.
11097

11198
| Name | Description | Default |
11299
|-------------------|-----------------------------------------------------------------------------------|--------------------------|
113-
| `SAGITTARIUS_URL` | URL of the Sagittarius instance Aquila connects to for flow and action updates. | `http://localhost:50051` |
114-
| `RUNTIME_TOKEN` | Token used by Aquila to authenticate with Sagittarius. | `default_session_token` |
100+
| `AQUILA_URL` | URL of the Aquila instance. | `http://localhost:50051` |
101+
| `AQUILA_TOKEN` | Token used by Taurus to authenticate with Aquila. | `token` |
102+
| `DEFINITIONS` | Path to the runtime definition modules. | `./definitions` |
103+
| `RUNTIME_STATUS_UPDATE_INTERVAL_SECONDS` | Interval (in seconds) of updating the current runtime status. | `30s` |
115104

116-
---
117-
118-
## Service Configuration File
119-
120-
To authorize services like `Taurus`, `Draco`, or an `Action`, they must be declared in Aquila's service configuration file.
121-
122-
`SERVICE_CONFIG_PATH` points to a JSON file that defines:
123-
124-
- Allowed runtime tokens
125-
- Allowed action tokens
126-
- Optional default action configurations
127-
128-
This file is loaded on startup. If the file is missing or invalid, Aquila starts with an empty service configuration.
129-
130-
Default:
131-
132-
```json
133-
{
134-
"actions": [],
135-
"runtimes": [
136-
{
137-
"identifier": "taurus",
138-
"token": "HsCEzbCuaUtUGSCrvwsSbJSlS2HH6TrW0ZeEKUZGTiOH8vPEZxyAEOx974Ku72l4"
139-
},
140-
{
141-
"identifier": "draco-rest",
142-
"token": "SBO3dRKmhszmGH6KxpgKoYGp0gBfgWqV6WEiKtMxldyeWiYLqJx6vwLuVLKRhu8H"
143-
},
144-
{
145-
"identifier": "draco-cron",
146-
"token": "VuTFgCj1PO6yr8smk43XLmeTUtlyKa2wjA0zvmz7WZDtgfXC62Ypd1b8fjJl8HvI"
147-
}
148-
]
149-
}
150-
```
151105

152-
You can add as many runtimes as needed.
153-
To add an `Action`, add an entry under `actions`.
154-
To provide default Action-level config, add `configs` entries for that action.
155-
156-
```json
157-
{
158-
"actions": [
159-
{
160-
"token": "action_token",
161-
"identifier": "discord",
162-
"configs": [
163-
{
164-
"project_id": 1,
165-
"configs": [
166-
{
167-
"identifier": "send_message",
168-
"value": {
169-
"channel_id": "123456789012345678",
170-
"content": "Hello from bot"
171-
}
172-
}
173-
]
174-
}
175-
]
176-
}
177-
],
178-
"runtimes": []
179-
}
180-
```

0 commit comments

Comments
 (0)