From a648e784ceb799b6689511e3f96e49a2801c837e Mon Sep 17 00:00:00 2001 From: gramps Date: Fri, 10 Apr 2026 18:11:44 -0700 Subject: [PATCH] docs: add prerequisites section, fix project structure and status table - Add Prerequisites section: Rust, RabbitMQ, MongoDB, MariaDB, Apache+PHP - Document Apache+PHP as required for observer tool with install commands - Explain rationale: observer must be independent of BEDS binary - Update project structure tree to reflect unified dispatcher + new modules - Fix status table: reflect completed dispatcher, template registry, retry/DLQ, resident runtime, logger store, dispatch traits; mark PHP observer as Next --- README.md | 76 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 60 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 385dc65..48684ca 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,38 @@ This is not a greenfield project. The architecture is proven. The Rust rewrite e --- +## Prerequisites + +These services must be installed and running before BEDS will start: + +| Dependency | Purpose | Notes | +|---|---|---| +| [Rust (stable)](https://rustup.rs) | Build toolchain | `rustup update stable` | +| [RabbitMQ](https://www.rabbitmq.com/docs/install-debian) | AMQP broker | Management plugin recommended: `rabbitmq-plugins enable rabbitmq_management` | +| [MongoDB](https://www.mongodb.com/docs/manual/installation/) | Logger store (`msLogs`) | Tested against 6.x / 7.x | +| [MariaDB](https://mariadb.org/download/) | Primary relational store | Tested against 10.x / 11.x | +| [Apache + PHP](https://httpd.apache.org) | Observer tool (`log_dumper`) | See below | + +### Observer Tool — Apache + PHP + +The log observer (`utilities/log_dumper/`) is a standalone PHP/Apache application, intentionally **independent of the BEDS binary**. When BEDS is crashing, you still need a working observer. A Rust binary compiled from the same project is useless in that scenario. + +```bash +# Debian/Ubuntu +apt install apache2 php libapache2-mod-php php-mongodb +systemctl enable apache2 +``` + +Once installed, copy or symlink `utilities/log_dumper/` into your Apache docroot: + +```bash +ln -s /path/to/rustybeds/utilities/log_dumper /var/www/html/beds-logs +``` + +The observer requires only a running MongoDB instance — no BEDS process needed. + +--- + ## Architecture BEDS is **AMQP-first**. No component in the application layer ever touches a database directly. Every data operation flows through a message broker. This is not a constraint — it is the product. @@ -84,17 +116,20 @@ Every node runs the same binary. Configuration determines what it does. ``` rustybeds/ ├── src/ +│ ├── bin/ +│ │ └── log_dumper.rs # (deprecated — replaced by utilities/log_dumper/) +│ ├── brokers/ +│ │ ├── mod.rs # Pool manager — spawn_dispatcher_pool() +│ │ ├── dispatcher.rs # Unified AMQP consumer task (replaces r/w_broker) +│ │ ├── logger_store.rs # MongoDB logger persistence + chain fetch +│ │ ├── payload.rs # BrokerPayload — AMQP message envelope struct +│ │ └── error.rs # BrokerError type │ ├── config/ │ │ ├── mod.rs # Loader — load() and load_from() for testability │ │ └── structs.rs # Typed config structs (serde Deserialize) -│ ├── brokers/ -│ │ ├── mod.rs # Pool manager — spawn_r/w_broker_pool() -│ │ ├── error.rs # BrokerError type -│ │ ├── payload.rs # BrokerPayload — AMQP message body struct -│ │ ├── r_broker.rs # rBroker task — rec.read consume loop -│ │ └── w_broker.rs # wBroker task — rec.write consume loop │ ├── core/ -│ │ └── mod.rs # NamasteCore trait — unified CRUD interface (stub) +│ │ ├── mod.rs # NamasteCore trait — unified CRUD interface +│ │ └── dispatch.rs # Dispatch boundary traits: DomainClass, SchemaLayer, BaseIoAdapter │ ├── services/ │ │ ├── mod.rs # Groups external service transport modules │ │ ├── amqp/ @@ -105,9 +140,11 @@ rustybeds/ │ │ │ └── mod.rs # validate_all() — TCP reachability │ │ └── mariadb/ │ │ └── mod.rs # validate_all() — master/secondary pattern +│ ├── template_registry/ +│ │ └── mod.rs # REC template registry — load, validate, runtime snapshot │ ├── lib.rs # Public API surface for integration test harness -│ ├── logging.rs # tracing + journald init -│ └── main.rs # async ipl() sequence + #[tokio::main] main() +│ ├── logging.rs # tracing + journald + console mirror init +│ └── main.rs # IPL sequence + resident runtime loop + coordinated shutdown ├── config/ │ ├── beds.toml # Base config — checked in, no credentials │ ├── env_dev.toml # Dev overrides — gitignored @@ -116,8 +153,10 @@ rustybeds/ ├── templates/ │ ├── example_rec.toml # Canonical self-documenting REC template │ └── mst_logger_rec.toml # Logger collection template (msLogs) +├── utilities/ +│ └── log_dumper/ # Standalone PHP/Apache observer (independent of BEDS) ├── tests/ -│ ├── broker_pool_test.rs # rBroker + wBroker pool integration tests +│ ├── broker_pool_test.rs # Dispatcher pool integration tests │ ├── common/mod.rs # Shared test helpers — load_test_config() │ └── fixtures/ │ └── beds_test.toml # Canonical test config fixture @@ -158,13 +197,18 @@ The `config` crate deep-merges these at startup. Only keys present in the env fi | Unit test scaffolding + config fixture pattern | Done | | MongoDB reachability validation | Done | | MariaDB reachability validation | Done | -| rBroker pool (Tokio tasks, queue declare, consume loop) | Done | -| wBroker pool (Tokio tasks, queue declare, consume loop) | Done | -| BrokerPayload — AMQP message body struct | Done | -| NamasteCore trait (stub) | Done | -| Factory dispatch | Next | +| Unified dispatcher pool (replaces r/w broker split) | Done | +| BrokerPayload — AMQP message envelope struct | Done | +| REC template registry (load, validate, runtime snapshot) | Done | +| Retry / DLQ queue topology | Done | +| Resident runtime loop + coordinated shutdown command | Done | +| MongoDB logger store — IPL persistence + chain fetch | Done | +| Dispatch boundary traits (DomainClass, SchemaLayer, BaseIoAdapter) | Done | +| Observer tool (PHP/Apache log_dumper) | Next | +| RegistryDispatchResolver — class instantiation | Next | | Database adapters (MariaDB, MongoDB) | Planned | -| AMQP publish / consume (full round-trip) | Planned | +| Broker task supervision / respawn | Planned | +| Config schema validation at startup | Planned | | AI database object generation | Phase 2 | ---