Add Galaxy repository API and clients

2026-04-29 07:27:00 -04:00
parent 047d875fe6
commit 133c83029b
103 changed files with 22788 additions and 39 deletions
@@ -99,6 +99,76 @@ preserving the raw message for parity diagnostics. Command replies whose
 protocol status is not `PROTOCOL_STATUS_CODE_OK` become `Error::Command` and
 retain the raw `MxCommandReply`.

+## Galaxy Repository browse
+
+The Galaxy Repository service exposes a read-only browse over the AVEVA System
+Platform Galaxy Repository (ZB SQL database). It uses the same API-key auth as
+the gateway service but requires the `metadata:read` scope on the server.
+
+[`GalaxyClient`](src/galaxy.rs) wraps the generated Galaxy bindings the same
+way [`GatewayClient`](src/client.rs) wraps the gateway bindings:
+
+```rust
+let mut galaxy = GalaxyClient::connect(
+    ClientOptions::new("http://localhost:5000")
+        .with_api_key(ApiKey::new(api_key)),
+).await?;
+
+let ok = galaxy.test_connection().await?;
+let last_deploy = galaxy.get_last_deploy_time().await?; // Option<prost_types::Timestamp>
+let objects = galaxy.discover_hierarchy().await?;       // Vec<GalaxyObject>
+```
+
+`get_last_deploy_time` returns `None` when the server reports
+`present = false`. `discover_hierarchy` returns the generated
+`GalaxyObject` proto type (re-exported via
+`mxgateway_client::generated::galaxy_repository::v1`) with all attributes
+attached.
+
+The CLI ships matching subcommands under `galaxy`:
+
+```powershell
+cargo run -p mxgw-cli -- galaxy test-connection --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
+cargo run -p mxgw-cli -- galaxy last-deploy-time --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
+cargo run -p mxgw-cli -- galaxy discover-hierarchy --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
+```
+
+### Watching deploy events
+
+`watch_deploy_events` opens the `WatchDeployEvents` server stream. The
+server emits a bootstrap [`DeployEvent`](src/galaxy.rs) describing the
+current cache state on subscribe, then one event each time the cached
+`galaxy.time_of_last_deploy` changes. `sequence` is monotonic per server
+start; gaps signal that the per-subscriber buffer dropped older events.
+Pass `last_seen_deploy_time` to suppress the bootstrap event when the
+client's cached deploy time matches the server's.
+
+```rust
+use futures_util::StreamExt;
+
+let mut stream = galaxy.watch_deploy_events(None).await?;
+while let Some(event) = stream.next().await {
+    let event = event?;
+    println!(
+        "seq={} objects={} attributes={}",
+        event.sequence, event.object_count, event.attribute_count,
+    );
+}
+// Drop the stream to cancel the gRPC call.
+```
+
+The matching CLI subcommand prints one line per event (`--json` switches to
+one JSON object per event). `--last-seen-deploy-time` accepts an RFC3339
+timestamp and is forwarded to the server. `--max-events` (default 0 = no
+cap) lets you stop after a fixed number of events; otherwise the command
+runs until the stream ends or `Ctrl+C` is pressed.
+
+```powershell
+cargo run -p mxgw-cli -- galaxy watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY
+cargo run -p mxgw-cli -- galaxy watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
+cargo run -p mxgw-cli -- galaxy watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --last-seen-deploy-time 2026-04-28T15:30:00Z
+```
+
 ## Integration Checks

 Run live checks only when a gateway and MXAccess-backed worker are available: