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
@@ -67,6 +67,99 @@ cancels the underlying gRPC stream. Canceling or timing out a Java client call
 only stops the client from waiting; it does not abort an in-flight MXAccess COM
 call on the worker STA.

+## Galaxy Repository Browse
+
+The Galaxy Repository service is a separate metadata-only gRPC service exposed
+by the gateway. It lets clients enumerate the deployed Galaxy object hierarchy
+and the dynamic attributes on each object so they know which tag references to
+subscribe to via the MXAccess Gateway service. It uses the same API-key auth as
+the gateway and requires the `metadata:read` scope.
+
+`GalaxyRepositoryClient` mirrors the `MxGatewayClient` pattern (caller-managed
+or owned channel, `MxGatewayClientOptions`, blocking + async variants). Three
+RPCs are exposed:
+
+```java
+MxGatewayClientOptions options = MxGatewayClientOptions.builder()
+        .endpoint("localhost:5000")
+        .apiKey(System.getenv("MXGATEWAY_API_KEY"))
+        .plaintext(true)
+        .build();
+
+try (GalaxyRepositoryClient galaxy = GalaxyRepositoryClient.connect(options)) {
+    boolean ok = galaxy.testConnection();
+    Optional<Instant> lastDeploy = galaxy.getLastDeployTime();
+    List<GalaxyObject> hierarchy = galaxy.discoverHierarchy();
+}
+```
+
+`getLastDeployTime` returns `Optional.empty()` when the server reports
+`present=false`. `discoverHierarchy` returns the generated `GalaxyObject` proto
+messages directly so callers can read all fields (including the nested
+`GalaxyAttribute` list) without an extra DTO layer.
+
+The CLI exposes matching subcommands: `galaxy-test`, `galaxy-deploy-time`,
+`galaxy-discover`, and `galaxy-watch`. They take the same `--endpoint`,
+`--api-key-env`, `--plaintext`, `--ca-file`, `--server-name-override`,
+`--timeout`, and `--json` options as the gateway commands.
+
+```powershell
+gradle :mxgateway-cli:run --args="galaxy-test --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+gradle :mxgateway-cli:run --args="galaxy-deploy-time --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+gradle :mxgateway-cli:run --args="galaxy-discover --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+```
+
+### Watching deploy events
+
+`GalaxyRepository.WatchDeployEvents` is a server-streaming RPC: the gateway
+sends a bootstrap `DeployEvent` immediately on subscribe and then one event
+each time it observes a new `galaxy.time_of_last_deploy`. The `sequence` field
+is monotonic per server start; gaps mean the per-subscriber buffer dropped
+older events because the consumer was too slow.
+
+The client exposes both an iterator-style adaptor over the async stub and an
+observer-callback variant. Both honour the channel-level `streamTimeout`.
+
+```java
+try (GalaxyRepositoryClient galaxy = GalaxyRepositoryClient.connect(options);
+        DeployEventStream events = galaxy.watchDeployEvents(/* lastSeenDeployTime */ null)) {
+    while (events.hasNext()) {
+        DeployEvent event = events.next();
+        // event.getSequence(), event.getObservedAt(),
+        // event.getTimeOfLastDeploy() / getTimeOfLastDeployPresent(),
+        // event.getObjectCount(), event.getAttributeCount()
+    }
+}
+```
+
+Pass an `Instant` for `lastSeenDeployTime` to suppress the bootstrap event when
+the cached deploy time matches what the caller already has. `DeployEventStream`
+implements `Iterator<DeployEvent>` and `AutoCloseable`; closing it cancels the
+underlying gRPC call.
+
+For callback delivery (e.g. when the consumer wants to drive a queue or
+reactive pipeline), use the async variant:
+
+```java
+DeployEventSubscription subscription = galaxy.watchDeployEventsAsync(
+        lastSeen,
+        new StreamObserver<>() {
+            @Override public void onNext(DeployEvent value) { /* ... */ }
+            @Override public void onError(Throwable t) { /* ... */ }
+            @Override public void onCompleted() { /* ... */ }
+        });
+// later:
+subscription.cancel(); // or subscription.close()
+```
+
+The matching CLI subcommand streams events until cancelled (Ctrl+C) and prints
+one line per event in text mode or one JSON object per event with `--json`:
+
+```powershell
+gradle :mxgateway-cli:run --args="galaxy-watch --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+gradle :mxgateway-cli:run --args="galaxy-watch --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --last-seen-deploy-time 2026-04-28T18:30:00Z --limit 5"
+```
+
 ## CLI Usage

 Run the CLI through Gradle: