diff --git a/docs/Guides/dev.md b/docs/Guides/dev.md deleted file mode 100644 index 6218721..0000000 --- a/docs/Guides/dev.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Aquila Development Guide ---- - -Follow this guide to develop Aquila. - -## Requirements - -To contribute to Aquila's development, you need the following expertise and tools: - -- **Rust Knowledge**: Proficient in Rust programming, including complex abstractions and performance optimizations. -- **Experience with gRPC**: Familiarity with building and consuming gRPC services. -- **NATS**: Understand Pub/Sub and JetStream. - ---- - -## Setting Up a Local Development Environment - -1. **Install Rust and Cargo** - Install the latest versions of Rust and its package manager, Cargo. Use [Rustup](https://rustup.rs/) for an easy installation. -2. **Set Up Local NATS Instance** - - Install NATS on your local machine or use the Dockerimage. - - Ensure its running and accessible for Aquila. - - Activate JetStream - - For any help refer to the [NATS documentation](https://docs.nats.io/running-a-nats-service/introduction/installation) - ---- - -## Additional Notes - -- Ensure all dependencies are compatible with the version of Aquila you are working on. -- Use the provided `.env` file as a reference for setting up your environment variables. - ---- diff --git a/docs/Guides/setup.md b/docs/Guides/setup.md deleted file mode 100644 index 63348c1..0000000 --- a/docs/Guides/setup.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Aquila Setup Guide ---- - -Follow this guide to set up Aquila. - -## Setup Options - -### Using Docker - -1. **Pull the Docker Image** - Pull the latest Docker image from ``. -2. **Configure Environment Variables** - Set up the necessary environment variables in a `.env` file (see [Environment Variables](#environment-variables) - section). -3. **Start the Application** - Run the Docker container using the appropriate command. - -### Manual Installation - -1. **Download the Latest Binary** - Download the latest Aquila binary from . -2. **Set Up Environment Variables** - Configure the `.env` file in the root folder with the required settings. -3. **Ensure Required Service Is Running** - - **NATS**: - - Ensure a NATS instance is reachable. - - Activate JetStream - - For any help refer to the [NATS documentation](https://docs.nats.io/running-a-nats-service/introduction/installation) - - **Sagittarius**: Ensure a Sagittarius instance is reachable. -4. **Start the Application** - Execute the binary to start Aquila. - ---- - -## Environment Variables - -Below is a list of required environment variables for configuring Aquila: - -| Name | Description | Default | -|-----------------------|------------------------------------------------------------------------------------------------------------------------------------|---------------| -| `MODE` | Specifies the application mode. `Static`: Startup using a flow file & `Dynamic`: Startup and continuously update from Sagittarius. | `static` | -| `ENVIRONMENT` | Defines the application environment for logging and debugging (e.g., `development`, `production`). | `developemnt` | -| `NATS_URL` | The URL of the NATS instance Aquila connects to. | `flow_store` | -| `NATS_BUCKET` | The name of the bucket Aquila uses to store flows. | | -| `SAGITTARIUS_URL` | The URL of the Sagittarius instance Aquila communicates with. | | -| `FLOW_FALLBACK_PATH` | Path to the flow file used for static configuration in `Static` mode. | | -| `RUNTIME_TOKEN` | A runtime token for authenticated communication between Aquila and Sagittarius. | | -| `GRPC_HOST` | Hostname for the Aquila instance. | | -| `GRPC_PORT` | gRPC Port for the Aquila instance. | | -| `WITH_HEALTH_SERVICE` | If activated Aquila will start with the gRPC-health-service for monitoring. | `false` | - ---- - -### Notes - -- Ensure that all required services (NATS, Sagittarius) are properly configured and accessible before - starting Aquila. -- If using Docker, remember to map necessary ports and volumes based on your deployment requirements. - ---- diff --git a/docs/dev.md b/docs/dev.md new file mode 100644 index 0000000..daeec71 --- /dev/null +++ b/docs/dev.md @@ -0,0 +1,127 @@ +--- +title: Aquila Development Guide +--- + +Use this guide to understand Aquila's runtime architecture and choose the right development mode. + +## Requirements + +To contribute to Aquila, you should be familiar with: + +- **[Rust](https://rust-lang.org/)** +- **[gRPC](https://grpc.io)** +- **[NATS](https://nats.io)** + +--- + +## Runtime Infrastructure Overview + +For a working runtime, the following services are required: + +- Aquila acts as the gateway between the IDE layer and the execution layer. + - Keeps runtime definitions up to date + - Keeps the latest flows available in the runtime + - Handles authentication and node execution for actions +- Draco is the runtime flow trigger (for example HTTP requests and cron jobs) +- Taurus is the runtime execution engine +- Actions are Taurus add-ons that extend runtime functionality +- Sagittarius persists definitions and flows +- NATS provides queueing for flow execution and KV storage for flows + +```mermaid +graph TD + +%% === Middle Layer === +Sagittarius["`**Sagittarius** +Persists flows, users, and related runtime metadata. +Acts as a middle layer between frontend services and the execution block.`"] + +Actions["`**Actions** +Acts as runtime add-ons. Can execute single nodes or send flow groups to the execution layer.`"] + +%% === Runtime / Execution Block === +subgraph ExecutionBlock["Runtime Block"] + Aquila["`**Aquila** + Gateway to the execution block. Keeps execution state updated and informs Sagittarius +about service state changes (for example DataTypes, FlowTypes, and RuntimeDefinitions).`"] + + Draco["`**Draco** + Protocol handler (for example an HTTP server). Accepts requests and triggers flow execution.`"] + + Taurus["`**Taurus** + Flow runtime engine. Executes functions and parameters defined in flows.`"] + + NATS[(NATS)] +end + +%% === Connections === +Sagittarius --> Aquila +Actions --> Aquila + +Draco --> Aquila +Taurus --> Aquila +Draco --> NATS +Taurus --> NATS +Aquila --> NATS +``` + +## Static vs Dynamic Mode + +Static and dynamic are runtime-level operating modes, not Aquila-only concepts. +In static mode, the runtime is standalone and does not depend on Sagittarius. +In dynamic mode, Aquila maintains an active connection to Sagittarius to keep runtime data synchronized. + +### Dynamic + +In dynamic mode, the runtime follows the first diagram above: Aquila stays connected to Sagittarius. + +Reasons to run dynamic mode: + +- Flows are updated frequently and should be synchronized automatically +- You expect continuous growth in flow count + +### Static + +In static mode, Sagittarius is not part of the runtime path. Flows and runtime configuration are loaded from local files. + +Reasons to run static mode: + +- Runtime needs to be standalone +- No flow updates are needed anymore +- Infrastructure resources are constrained and should be dedicated to execution + +Infrastructure for static mode: + +```mermaid +graph TD + +%% === Middle Layer === +Actions["`**Actions** +Acts as runtime add-ons. Can execute single nodes or send flow groups to the execution layer.`"] + +%% === Runtime / Execution Block === +subgraph ExecutionBlock["Runtime Block"] + Aquila["`**Aquila** + Gateway to the execution block.`"] + + Draco["`**Draco** + Protocol handler (for example an HTTP server). Accepts requests and triggers flow execution.`"] + + Taurus["`**Taurus** + Flow runtime engine. Executes functions and parameters defined in flows.`"] + + NATS[(NATS)] +end + +%% === Connections === +Actions --> Aquila + +Draco --> Aquila +Taurus --> Aquila +Draco --> NATS +Taurus --> NATS +Aquila --> NATS +``` + +> In static mode, flow data and service authorization are loaded from local +files (for example `FLOW_FALLBACK_PATH` and `SERVICE_CONFIG_PATH`) before runtime execution starts. diff --git a/docs/index.mdx b/docs/index.mdx index 334b0ec..a593940 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -1,17 +1,20 @@ --- -title: Welcome to the Documentation for Aquila -description: Find out how Aquila works +title: Welcome to Aquila Documentation +description: Learn how Aquila works and how to build with it template: splash --- ## What is Aquila? -Aquila is a service running inside the execution block. It acts as the gateway to external services. -Any request that needs to enter or exit the execution environment is routed through Aquila. +Aquila runs inside the execution block and serves as the gateway for external runtime communication. +Requests entering or leaving the execution environment are routed through Aquila. -Aquila keeps internal workflows updated so the execution service knows what’s happening. -It communicates with actions to receive their configurations, structures, and much more. +Aquila keeps flows and runtime definitions synchronized so execution services stay current. +It also communicates with Actions to receive configuration, schema, and related metadata updates. --- -Refer to the guides if you want to work on or with Aquila. +If you want to work on or with Aquila, start here: + +- **[Setup Guide](installation.mdx)**: install and configure Aquila for local or containerized use. +- **[Development Guide](dev.md)**: runtime architecture diff --git a/docs/installation.mdx b/docs/installation.mdx new file mode 100644 index 0000000..17a9a54 --- /dev/null +++ b/docs/installation.mdx @@ -0,0 +1,175 @@ +--- +title: Aquila Installation Guide +--- + +import {Step, Steps} from 'fumadocs-ui/components/steps'; + +Use this guide to install and configure Aquila. + +## Setup Options + +### Using Docker Compose + +Use Docker Compose to run Aquila and related services. +If you are developing Aquila locally, make sure the Aquila 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 Aquila 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 Aquila** + +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) + +**Sagittarius**: + +- Required for dynamic mode (`MODE=hybrid`) +- Ensure the configured endpoint is reachable + + + + + +#### **Start Aquila** + +Run: + +```bash +cargo run +``` + + + + +--- + +## Environment Variables + +Aquila configuration is split into shared variables and mode-specific variables. + +### Common (Static + Dynamic) + +| Name | Description | Default | +|-----------------------|--------------------------------------------------------------------------------------------------------------|---------------------------------| +| `MODE` | Runtime mode. `static` loads local flows. `hybrid` enables dynamic synchronization with Sagittarius. | `static` | +| `ENVIRONMENT` | Runtime environment (`development`, `staging`, `production`). | `development` | +| `NATS_URL` | URL of the NATS instance Aquila connects to. | `nats://localhost:4222` | +| `NATS_BUCKET` | Name of the NATS KV bucket used to store flows. | `flow_store` | +| `GRPC_HOST` | Hostname for the Aquila gRPC server. | `127.0.0.1` | +| `GRPC_PORT` | Port for the Aquila gRPC server. | `8081` | +| `WITH_HEALTH_SERVICE` | Enables the gRPC health service when set to `true`. | `false` | +| `SERVICE_CONFIG_PATH` | Path to the JSON service-configuration file used for runtime/action authorization and default action configs. | `./service.configuration.json` | + +### Static Mode + +Set `MODE=static` to load flows from a local JSON file and insert them into the NATS KV store on startup. + +| Name | Description | Default | +|----------------------|-----------------------------------------------|---------------------| +| `FLOW_FALLBACK_PATH` | Path to the flow JSON file loaded at startup. | `./flowExport.json` | + +### Dynamic Mode + +Set `MODE=hybrid` to keep flows synchronized from Sagittarius. + +| Name | Description | Default | +|-------------------|-----------------------------------------------------------------------------------|--------------------------| +| `SAGITTARIUS_URL` | URL of the Sagittarius instance Aquila connects to for flow and action updates. | `http://localhost:50051` | +| `RUNTIME_TOKEN` | Token used by Aquila to authenticate with Sagittarius. | `default_session_token` | + +--- + +## Service Configuration File + +To authorize services like `Taurus`, `Draco`, or an `Action`, they must be declared in Aquila's service configuration file. + +`SERVICE_CONFIG_PATH` points to a JSON file that defines: + +- Allowed runtime tokens +- Allowed action tokens +- Optional default action configurations + +This file is loaded on startup. If the file is missing or invalid, Aquila starts with an empty service configuration. + +Default: + +```json +{ + "actions": [], + "runtimes": [ + { + "identifier": "taurus", + "token": "HsCEzbCuaUtUGSCrvwsSbJSlS2HH6TrW0ZeEKUZGTiOH8vPEZxyAEOx974Ku72l4" + }, + { + "identifier": "draco-rest", + "token": "SBO3dRKmhszmGH6KxpgKoYGp0gBfgWqV6WEiKtMxldyeWiYLqJx6vwLuVLKRhu8H" + }, + { + "identifier": "draco-cron", + "token": "VuTFgCj1PO6yr8smk43XLmeTUtlyKa2wjA0zvmz7WZDtgfXC62Ypd1b8fjJl8HvI" + } + ] +} +``` + +You can add as many runtimes as needed. +To add an `Action`, add an entry under `actions`. +To provide default Action-level config, add `configs` entries for that action. + +```json +{ + "actions": [ + { + "token": "action_token", + "identifier": "discord", + "configs": [ + { + "project_id": 1, + "configs": [ + { + "identifier": "send_message", + "value": { + "channel_id": "123456789012345678", + "content": "Hello from bot" + } + } + ] + } + ] + } + ], + "runtimes": [] +} +``` diff --git a/service.configuration.json b/service.configuration.json index f7107f1..983476f 100644 --- a/service.configuration.json +++ b/service.configuration.json @@ -1,30 +1,17 @@ { - "actions": [ + "actions": [], + "runtimes": [ { - "token": "token", - "identifier": "discord", - "configs": [ - { - "project_id": 1, - "configs": [ - { - "identifier": "send_message", - "value": { - "channel_id": "123456789012345678", - "content": "Hello from bot" - } - }, - { - "identifier": "assign_role", - "value": { - "guild_id": "987654321098765432", - "user_id": "111111111111111111", - "role_id": "222222222222222222" - } - } - ] - } - ] + "identifier": "taurus", + "token": "HsCEzbCuaUtUGSCrvwsSbJSlS2HH6TrW0ZeEKUZGTiOH8vPEZxyAEOx974Ku72l4" + }, + { + "identifier": "draco-rest", + "token": "SBO3dRKmhszmGH6KxpgKoYGp0gBfgWqV6WEiKtMxldyeWiYLqJx6vwLuVLKRhu8H" + }, + { + "identifier": "draco-cron", + "token": "VuTFgCj1PO6yr8smk43XLmeTUtlyKa2wjA0zvmz7WZDtgfXC62Ypd1b8fjJl8HvI" } ] } diff --git a/src/sagittarius/retry.rs b/src/sagittarius/retry.rs index c2613da..f9c0a50 100644 --- a/src/sagittarius/retry.rs +++ b/src/sagittarius/retry.rs @@ -37,6 +37,8 @@ pub async fn create_channel_with_retry( match channel.connect().await { Ok(ch) => { + ready.store(true, Ordering::SeqCst); + log::info!("Successfully connected to `{}` using `{}`", channel_name, url); return ch; } Err(err) => {