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
@@ -0,0 +1,132 @@
+package com.dohertylan.mxgateway.client;
+
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest;
+import io.grpc.Status;
+import io.grpc.StatusRuntimeException;
+import io.grpc.stub.ClientCallStreamObserver;
+import io.grpc.stub.ClientResponseObserver;
+import java.util.Iterator;
+import java.util.NoSuchElementException;
+import java.util.Objects;
+import java.util.concurrent.ArrayBlockingQueue;
+import java.util.concurrent.BlockingQueue;
+
+/**
+ * Iterator-style adaptor over the {@code WatchDeployEvents} server-streaming
+ * RPC. Mirrors {@link MxEventStream}: events arrive on a background gRPC thread
+ * and are buffered in a bounded blocking queue; the iterator drains them.
+ * Closing the stream cancels the underlying gRPC call.
+ */
+public final class DeployEventStream implements Iterator<DeployEvent>, AutoCloseable {
+    private static final Object END = new Object();
+
+    private final BlockingQueue<Object> queue;
+    private volatile ClientCallStreamObserver<WatchDeployEventsRequest> requestStream;
+    private volatile boolean closed;
+    private Object next;
+
+    DeployEventStream(int capacity) {
+        queue = new ArrayBlockingQueue<>(capacity);
+    }
+
+    ClientResponseObserver<WatchDeployEventsRequest, DeployEvent> observer() {
+        return new ClientResponseObserver<>() {
+            @Override
+            public void beforeStart(ClientCallStreamObserver<WatchDeployEventsRequest> requestStream) {
+                DeployEventStream.this.requestStream = requestStream;
+            }
+
+            @Override
+            public void onNext(DeployEvent value) {
+                offer(value);
+            }
+
+            @Override
+            public void onError(Throwable error) {
+                if (Status.fromThrowable(error).getCode() == Status.Code.CANCELLED && closed) {
+                    offer(END);
+                    return;
+                }
+                offer(error);
+            }
+
+            @Override
+            public void onCompleted() {
+                offer(END);
+            }
+        };
+    }
+
+    @Override
+    public boolean hasNext() {
+        if (next == END) {
+            return false;
+        }
+        if (next == null) {
+            next = take();
+        }
+        if (next instanceof RuntimeException runtimeException) {
+            next = END;
+            throw runtimeException;
+        }
+        if (next instanceof Throwable throwable) {
+            next = END;
+            throw new MxGatewayException(
+                    "galaxy watch deploy events failed: " + throwable.getMessage(), throwable);
+        }
+        return next != END;
+    }
+
+    @Override
+    public DeployEvent next() {
+        if (!hasNext()) {
+            throw new NoSuchElementException();
+        }
+        Object value = next;
+        next = null;
+        return (DeployEvent) value;
+    }
+
+    @Override
+    public void close() {
+        closed = true;
+        ClientCallStreamObserver<WatchDeployEventsRequest> stream = requestStream;
+        if (stream != null) {
+            stream.cancel("client cancelled deploy event stream", null);
+        }
+        offer(END);
+    }
+
+    private Object take() {
+        while (true) {
+            try {
+                return queue.take();
+            } catch (InterruptedException error) {
+                Thread.currentThread().interrupt();
+                return new StatusRuntimeException(
+                        Status.CANCELLED.withDescription("interrupted while reading deploy events"));
+            }
+        }
+    }
+
+    private void offer(Object value) {
+        Objects.requireNonNull(value, "value");
+        if (value == END) {
+            if (!queue.offer(value)) {
+                queue.clear();
+                queue.offer(value);
+            }
+            return;
+        }
+        if (!queue.offer(value)) {
+            ClientCallStreamObserver<WatchDeployEventsRequest> stream = requestStream;
+            if (stream != null) {
+                stream.cancel("client deploy event stream queue overflowed", null);
+            }
+            queue.clear();
+            queue.offer(new MxGatewayException("galaxy watch deploy events queue overflowed"));
+            queue.offer(END);
+        }
+    }
+}
@@ -0,0 +1,60 @@
+package com.dohertylan.mxgateway.client;
+
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest;
+import io.grpc.stub.ClientCallStreamObserver;
+import io.grpc.stub.ClientResponseObserver;
+import io.grpc.stub.StreamObserver;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicReference;
+
+/**
+ * Cancellable handle returned by the async {@code watchDeployEvents} variant.
+ * Mirrors {@link MxGatewayEventSubscription} but for the Galaxy Repository
+ * deploy-event stream.
+ */
+public final class DeployEventSubscription implements AutoCloseable {
+    private final AtomicReference<ClientCallStreamObserver<WatchDeployEventsRequest>> requestStream =
+            new AtomicReference<>();
+    private final AtomicBoolean cancelled = new AtomicBoolean();
+
+    ClientResponseObserver<WatchDeployEventsRequest, DeployEvent> wrap(StreamObserver<DeployEvent> observer) {
+        return new ClientResponseObserver<>() {
+            @Override
+            public void beforeStart(ClientCallStreamObserver<WatchDeployEventsRequest> stream) {
+                requestStream.set(stream);
+                if (cancelled.get()) {
+                    stream.cancel("client cancelled deploy event stream", null);
+                }
+            }
+
+            @Override
+            public void onNext(DeployEvent value) {
+                observer.onNext(value);
+            }
+
+            @Override
+            public void onError(Throwable error) {
+                observer.onError(error);
+            }
+
+            @Override
+            public void onCompleted() {
+                observer.onCompleted();
+            }
+        };
+    }
+
+    public void cancel() {
+        cancelled.set(true);
+        ClientCallStreamObserver<WatchDeployEventsRequest> stream = requestStream.get();
+        if (stream != null) {
+            stream.cancel("client cancelled deploy event stream", null);
+        }
+    }
+
+    @Override
+    public void close() {
+        cancel();
+    }
+}
@@ -0,0 +1,288 @@
+package com.dohertylan.mxgateway.client;
+
+import com.google.common.util.concurrent.FutureCallback;
+import com.google.common.util.concurrent.Futures;
+import com.google.common.util.concurrent.MoreExecutors;
+import galaxy_repository.v1.GalaxyRepositoryGrpc;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.GalaxyObject;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeReply;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeRequest;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionReply;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionRequest;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest;
+import com.google.protobuf.Timestamp;
+import io.grpc.Channel;
+import io.grpc.ClientInterceptors;
+import io.grpc.ManagedChannel;
+import io.grpc.netty.shaded.io.grpc.netty.GrpcSslContexts;
+import io.grpc.netty.shaded.io.grpc.netty.NettyChannelBuilder;
+import io.grpc.stub.StreamObserver;
+import java.time.Instant;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.TimeUnit;
+import javax.net.ssl.SSLException;
+
+/**
+ * Thin wrapper around the generated {@link GalaxyRepositoryGrpc} stubs that
+ * exposes the three metadata-only RPCs of the Galaxy Repository service in
+ * idiomatic Java types. Mirrors the constructor and option-handling style of
+ * {@link MxGatewayClient}.
+ */
+public final class GalaxyRepositoryClient implements AutoCloseable {
+    private final ManagedChannel ownedChannel;
+    private final MxGatewayClientOptions options;
+    private final GalaxyRepositoryGrpc.GalaxyRepositoryBlockingStub blockingStub;
+    private final GalaxyRepositoryGrpc.GalaxyRepositoryFutureStub futureStub;
+    private final GalaxyRepositoryGrpc.GalaxyRepositoryStub asyncStub;
+
+    private GalaxyRepositoryClient(ManagedChannel channel, MxGatewayClientOptions options) {
+        this.ownedChannel = channel;
+        this.options = options;
+        Channel intercepted = ClientInterceptors.intercept(channel, new MxGatewayAuthInterceptor(options.apiKey()));
+        blockingStub = GalaxyRepositoryGrpc.newBlockingStub(intercepted);
+        futureStub = GalaxyRepositoryGrpc.newFutureStub(intercepted);
+        asyncStub = GalaxyRepositoryGrpc.newStub(intercepted);
+    }
+
+    /**
+     * Construct a client over a caller-managed {@link Channel}. The caller owns
+     * channel lifecycle; {@link #close()} is a no-op for this constructor.
+     */
+    public GalaxyRepositoryClient(Channel channel, MxGatewayClientOptions options) {
+        this.ownedChannel = null;
+        this.options = Objects.requireNonNull(options, "options");
+        Channel intercepted = ClientInterceptors.intercept(channel, new MxGatewayAuthInterceptor(options.apiKey()));
+        blockingStub = GalaxyRepositoryGrpc.newBlockingStub(intercepted);
+        futureStub = GalaxyRepositoryGrpc.newFutureStub(intercepted);
+        asyncStub = GalaxyRepositoryGrpc.newStub(intercepted);
+    }
+
+    /** Build a new client and own its channel; close shuts the channel down. */
+    public static GalaxyRepositoryClient connect(MxGatewayClientOptions options) {
+        return new GalaxyRepositoryClient(createChannel(options), options);
+    }
+
+    public GalaxyRepositoryGrpc.GalaxyRepositoryBlockingStub rawBlockingStub() {
+        return withDeadline(blockingStub);
+    }
+
+    public GalaxyRepositoryGrpc.GalaxyRepositoryFutureStub rawFutureStub() {
+        return withDeadline(futureStub);
+    }
+
+    public GalaxyRepositoryGrpc.GalaxyRepositoryStub rawAsyncStub() {
+        return asyncStub;
+    }
+
+    /**
+     * Invoke the {@code TestConnection} RPC and return the {@code ok} flag.
+     */
+    public boolean testConnection() {
+        try {
+            TestConnectionReply reply = rawBlockingStub().testConnection(TestConnectionRequest.getDefaultInstance());
+            return reply.getOk();
+        } catch (RuntimeException error) {
+            if (error instanceof MxGatewayException) {
+                throw error;
+            }
+            throw MxGatewayErrors.fromGrpc("galaxy test connection", error);
+        }
+    }
+
+    public CompletableFuture<Boolean> testConnectionAsync() {
+        return toCompletable(rawFutureStub().testConnection(TestConnectionRequest.getDefaultInstance()))
+                .thenApply(TestConnectionReply::getOk);
+    }
+
+    /**
+     * Invoke the {@code GetLastDeployTime} RPC. Returns {@link Optional#empty()}
+     * when the server reports {@code present=false}.
+     */
+    public Optional<Instant> getLastDeployTime() {
+        try {
+            GetLastDeployTimeReply reply =
+                    rawBlockingStub().getLastDeployTime(GetLastDeployTimeRequest.getDefaultInstance());
+            return mapDeployTime(reply);
+        } catch (RuntimeException error) {
+            if (error instanceof MxGatewayException) {
+                throw error;
+            }
+            throw MxGatewayErrors.fromGrpc("galaxy get last deploy time", error);
+        }
+    }
+
+    public CompletableFuture<Optional<Instant>> getLastDeployTimeAsync() {
+        return toCompletable(rawFutureStub().getLastDeployTime(GetLastDeployTimeRequest.getDefaultInstance()))
+                .thenApply(GalaxyRepositoryClient::mapDeployTime);
+    }
+
+    /**
+     * Invoke the {@code DiscoverHierarchy} RPC and return the generated
+     * {@link GalaxyObject} messages directly. Callers can read every field of
+     * the proto message without an extra DTO layer.
+     */
+    public List<GalaxyObject> discoverHierarchy() {
+        try {
+            DiscoverHierarchyReply reply =
+                    rawBlockingStub().discoverHierarchy(DiscoverHierarchyRequest.getDefaultInstance());
+            return reply.getObjectsList();
+        } catch (RuntimeException error) {
+            if (error instanceof MxGatewayException) {
+                throw error;
+            }
+            throw MxGatewayErrors.fromGrpc("galaxy discover hierarchy", error);
+        }
+    }
+
+    public CompletableFuture<List<GalaxyObject>> discoverHierarchyAsync() {
+        return toCompletable(rawFutureStub().discoverHierarchy(DiscoverHierarchyRequest.getDefaultInstance()))
+                .thenApply(DiscoverHierarchyReply::getObjectsList);
+    }
+
+    /**
+     * Subscribe to {@code WatchDeployEvents} via the async stub and consume
+     * results through a blocking iterator. Closing the returned stream cancels
+     * the underlying gRPC call.
+     *
+     * @param lastSeenDeployTime optional. When non-null, the bootstrap event is
+     *     suppressed if the cached deploy time matches.
+     */
+    public DeployEventStream watchDeployEvents(Instant lastSeenDeployTime) {
+        DeployEventStream stream = new DeployEventStream(16);
+        withStreamDeadline(rawAsyncStub()).watchDeployEvents(buildWatchRequest(lastSeenDeployTime), stream.observer());
+        return stream;
+    }
+
+    /**
+     * Iterator-style alias for {@link #watchDeployEvents(Instant)} matching the
+     * task-spec signature.
+     */
+    public Iterator<DeployEvent> watchDeployEventsIterator(Instant lastSeenDeployTime) {
+        return watchDeployEvents(lastSeenDeployTime);
+    }
+
+    /**
+     * Subscribe to {@code WatchDeployEvents} via the async stub, dispatching
+     * each event to {@code observer}. The returned subscription is cancellable
+     * and {@link AutoCloseable}.
+     */
+    public DeployEventSubscription watchDeployEventsAsync(
+            Instant lastSeenDeployTime, StreamObserver<DeployEvent> observer) {
+        Objects.requireNonNull(observer, "observer");
+        DeployEventSubscription subscription = new DeployEventSubscription();
+        withStreamDeadline(rawAsyncStub())
+                .watchDeployEvents(buildWatchRequest(lastSeenDeployTime), subscription.wrap(observer));
+        return subscription;
+    }
+
+    private static WatchDeployEventsRequest buildWatchRequest(Instant lastSeenDeployTime) {
+        WatchDeployEventsRequest.Builder builder = WatchDeployEventsRequest.newBuilder();
+        if (lastSeenDeployTime != null) {
+            builder.setLastSeenDeployTime(Timestamp.newBuilder()
+                    .setSeconds(lastSeenDeployTime.getEpochSecond())
+                    .setNanos(lastSeenDeployTime.getNano())
+                    .build());
+        }
+        return builder.build();
+    }
+
+    private <T extends io.grpc.stub.AbstractStub<T>> T withStreamDeadline(T stub) {
+        if (options.streamTimeout() == null || options.streamTimeout().isNegative()) {
+            return stub;
+        }
+        return stub.withDeadlineAfter(options.streamTimeout().toNanos(), TimeUnit.NANOSECONDS);
+    }
+
+    @Override
+    public void close() {
+        if (ownedChannel != null) {
+            ownedChannel.shutdown();
+        }
+    }
+
+    public void closeAndAwaitTermination() throws InterruptedException {
+        if (ownedChannel != null) {
+            ownedChannel.shutdown();
+            if (!ownedChannel.awaitTermination(options.connectTimeout().toMillis(), TimeUnit.MILLISECONDS)) {
+                ownedChannel.shutdownNow();
+            }
+        }
+    }
+
+    private static Optional<Instant> mapDeployTime(GetLastDeployTimeReply reply) {
+        if (!reply.getPresent()) {
+            return Optional.empty();
+        }
+        Timestamp ts = reply.getTimeOfLastDeploy();
+        return Optional.of(Instant.ofEpochSecond(ts.getSeconds(), ts.getNanos()));
+    }
+
+    private static ManagedChannel createChannel(MxGatewayClientOptions options) {
+        NettyChannelBuilder builder = NettyChannelBuilder.forTarget(options.endpoint())
+                .maxInboundMessageSize(16 * 1024 * 1024);
+        if (!options.connectTimeout().isNegative()) {
+            builder.withOption(
+                    io.grpc.netty.shaded.io.netty.channel.ChannelOption.CONNECT_TIMEOUT_MILLIS,
+                    Math.toIntExact(options.connectTimeout().toMillis()));
+        }
+        if (options.plaintext()) {
+            builder.usePlaintext();
+        } else if (options.caCertificatePath() != null) {
+            try {
+                builder.sslContext(GrpcSslContexts.forClient()
+                        .trustManager(options.caCertificatePath().toFile())
+                        .build());
+            } catch (SSLException error) {
+                throw new MxGatewayException("failed to configure galaxy repository TLS", error);
+            }
+        } else {
+            builder.useTransportSecurity();
+        }
+        if (!options.serverNameOverride().isBlank()) {
+            builder.overrideAuthority(options.serverNameOverride());
+        }
+        return builder.build();
+    }
+
+    private <T extends io.grpc.stub.AbstractStub<T>> T withDeadline(T stub) {
+        if (options.callTimeout().isNegative()) {
+            return stub;
+        }
+        return stub.withDeadlineAfter(options.callTimeout().toNanos(), TimeUnit.NANOSECONDS);
+    }
+
+    private static <T> CompletableFuture<T> toCompletable(com.google.common.util.concurrent.ListenableFuture<T> source) {
+        CompletableFuture<T> target = new CompletableFuture<>();
+        Futures.addCallback(
+                source,
+                new FutureCallback<>() {
+                    @Override
+                    public void onSuccess(T result) {
+                        target.complete(result);
+                    }
+
+                    @Override
+                    public void onFailure(Throwable error) {
+                        if (error instanceof RuntimeException runtimeException) {
+                            target.completeExceptionally(MxGatewayErrors.fromGrpc("galaxy async call", runtimeException));
+                            return;
+                        }
+                        target.completeExceptionally(error);
+                    }
+                },
+                MoreExecutors.directExecutor());
+        target.whenComplete((ignoredResult, ignoredError) -> {
+            if (target.isCancelled()) {
+                source.cancel(true);
+            }
+        });
+        return target;
+    }
+}
@@ -0,0 +1,327 @@
+package com.dohertylan.mxgateway.client;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import com.google.protobuf.Timestamp;
+import galaxy_repository.v1.GalaxyRepositoryGrpc;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DeployEvent;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyReply;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.DiscoverHierarchyRequest;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.GalaxyAttribute;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.GalaxyObject;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeReply;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.GetLastDeployTimeRequest;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionReply;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.TestConnectionRequest;
+import galaxy_repository.v1.GalaxyRepositoryOuterClass.WatchDeployEventsRequest;
+import io.grpc.ManagedChannel;
+import io.grpc.Metadata;
+import io.grpc.Server;
+import io.grpc.ServerCall;
+import io.grpc.ServerCallHandler;
+import io.grpc.ServerInterceptor;
+import io.grpc.inprocess.InProcessChannelBuilder;
+import io.grpc.inprocess.InProcessServerBuilder;
+import io.grpc.stub.StreamObserver;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.List;
+import java.util.Optional;
+import java.util.UUID;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicReference;
+import org.junit.jupiter.api.Test;
+
+final class GalaxyRepositoryClientTests {
+    @Test
+    void testConnectionReturnsOkAndSendsAuthMetadata() throws Exception {
+        AtomicReference<String> authorization = new AtomicReference<>();
+        TestService service = new TestService() {
+            @Override
+            public void testConnection(
+                    TestConnectionRequest request, StreamObserver<TestConnectionReply> responseObserver) {
+                responseObserver.onNext(TestConnectionReply.newBuilder().setOk(true).build());
+                responseObserver.onCompleted();
+            }
+        };
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, authorization);
+                GalaxyRepositoryClient client = g.client("mxgw_galaxy_secret")) {
+            assertTrue(client.testConnection());
+            assertEquals("Bearer mxgw_galaxy_secret", authorization.get());
+        }
+    }
+
+    @Test
+    void getLastDeployTimeReturnsEmptyWhenPresentFalse() throws Exception {
+        TestService service = new TestService() {
+            @Override
+            public void getLastDeployTime(
+                    GetLastDeployTimeRequest request, StreamObserver<GetLastDeployTimeReply> responseObserver) {
+                responseObserver.onNext(
+                        GetLastDeployTimeReply.newBuilder().setPresent(false).build());
+                responseObserver.onCompleted();
+            }
+        };
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            Optional<Instant> result = client.getLastDeployTime();
+            assertFalse(result.isPresent());
+        }
+    }
+
+    @Test
+    void getLastDeployTimeReturnsInstantWhenPresent() throws Exception {
+        Timestamp expected = Timestamp.newBuilder().setSeconds(1_700_000_000L).setNanos(123_000_000).build();
+        TestService service = new TestService() {
+            @Override
+            public void getLastDeployTime(
+                    GetLastDeployTimeRequest request, StreamObserver<GetLastDeployTimeReply> responseObserver) {
+                responseObserver.onNext(GetLastDeployTimeReply.newBuilder()
+                        .setPresent(true)
+                        .setTimeOfLastDeploy(expected)
+                        .build());
+                responseObserver.onCompleted();
+            }
+        };
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            Optional<Instant> result = client.getLastDeployTime();
+            assertTrue(result.isPresent());
+            assertEquals(Instant.ofEpochSecond(1_700_000_000L, 123_000_000), result.get());
+        }
+    }
+
+    @Test
+    void discoverHierarchyReturnsObjectsAndAttributes() throws Exception {
+        AtomicReference<DiscoverHierarchyRequest> seenRequest = new AtomicReference<>();
+        TestService service = new TestService() {
+            @Override
+            public void discoverHierarchy(
+                    DiscoverHierarchyRequest request, StreamObserver<DiscoverHierarchyReply> responseObserver) {
+                seenRequest.set(request);
+                responseObserver.onNext(DiscoverHierarchyReply.newBuilder()
+                        .addObjects(GalaxyObject.newBuilder()
+                                .setGobjectId(7)
+                                .setTagName("Pump_001")
+                                .setContainedName("Pump")
+                                .setBrowseName("Pump")
+                                .setParentGobjectId(1)
+                                .setIsArea(false)
+                                .setCategoryId(3)
+                                .setHostedByGobjectId(0)
+                                .addTemplateChain("$Pump")
+                                .addAttributes(GalaxyAttribute.newBuilder()
+                                        .setAttributeName("Speed")
+                                        .setFullTagReference("Pump_001.Speed")
+                                        .setMxDataType(5)
+                                        .setDataTypeName("MxFloat")
+                                        .setIsArray(false)
+                                        .setIsHistorized(true)))
+                        .build());
+                responseObserver.onCompleted();
+            }
+        };
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            List<GalaxyObject> objects = client.discoverHierarchy();
+            assertEquals(1, objects.size());
+            GalaxyObject only = objects.get(0);
+            assertEquals(7, only.getGobjectId());
+            assertEquals("Pump_001", only.getTagName());
+            assertEquals(1, only.getAttributesCount());
+            assertEquals("Pump_001.Speed", only.getAttributes(0).getFullTagReference());
+            assertTrue(only.getAttributes(0).getIsHistorized());
+        }
+    }
+
+    @Test
+    void watchDeployEventsReceivesEventsInOrder() throws Exception {
+        DeployEvent first = DeployEvent.newBuilder()
+                .setSequence(1)
+                .setObservedAt(Timestamp.newBuilder().setSeconds(1_700_000_000L).build())
+                .setTimeOfLastDeploy(Timestamp.newBuilder().setSeconds(1_699_999_000L).build())
+                .setTimeOfLastDeployPresent(true)
+                .setObjectCount(42)
+                .setAttributeCount(123)
+                .build();
+        DeployEvent second = DeployEvent.newBuilder()
+                .setSequence(2)
+                .setObservedAt(Timestamp.newBuilder().setSeconds(1_700_000_100L).build())
+                .setTimeOfLastDeployPresent(false)
+                .setObjectCount(43)
+                .setAttributeCount(125)
+                .build();
+
+        TestService service = new TestService() {
+            @Override
+            public void watchDeployEvents(
+                    WatchDeployEventsRequest request, StreamObserver<DeployEvent> responseObserver) {
+                responseObserver.onNext(first);
+                responseObserver.onNext(second);
+                responseObserver.onCompleted();
+            }
+        };
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            try (DeployEventStream stream = client.watchDeployEvents(null)) {
+                assertTrue(stream.hasNext());
+                DeployEvent event1 = stream.next();
+                assertEquals(1L, event1.getSequence());
+                assertEquals(42, event1.getObjectCount());
+                assertTrue(event1.getTimeOfLastDeployPresent());
+
+                assertTrue(stream.hasNext());
+                DeployEvent event2 = stream.next();
+                assertEquals(2L, event2.getSequence());
+                assertFalse(event2.getTimeOfLastDeployPresent());
+
+                assertFalse(stream.hasNext());
+            }
+        }
+    }
+
+    @Test
+    void watchDeployEventsPropagatesLastSeenDeployTime() throws Exception {
+        AtomicReference<WatchDeployEventsRequest> seen = new AtomicReference<>();
+        Instant lastSeen = Instant.ofEpochSecond(1_700_000_000L, 250_000_000);
+
+        TestService service = new TestService() {
+            @Override
+            public void watchDeployEvents(
+                    WatchDeployEventsRequest request, StreamObserver<DeployEvent> responseObserver) {
+                seen.set(request);
+                responseObserver.onCompleted();
+            }
+        };
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            try (DeployEventStream stream = client.watchDeployEvents(lastSeen)) {
+                assertFalse(stream.hasNext());
+            }
+        }
+
+        WatchDeployEventsRequest request = seen.get();
+        assertNotNull(request);
+        Timestamp expected = request.getLastSeenDeployTime();
+        assertEquals(lastSeen.getEpochSecond(), expected.getSeconds());
+        assertEquals(lastSeen.getNano(), expected.getNanos());
+    }
+
+    @Test
+    void watchDeployEventsClientCancellationTearsDownCleanly() throws Exception {
+        CountDownLatch cancelObserved = new CountDownLatch(1);
+
+        TestService service = new TestService() {
+            @Override
+            public void watchDeployEvents(
+                    WatchDeployEventsRequest request, StreamObserver<DeployEvent> responseObserver) {
+                io.grpc.stub.ServerCallStreamObserver<DeployEvent> serverObserver =
+                        (io.grpc.stub.ServerCallStreamObserver<DeployEvent>) responseObserver;
+                serverObserver.setOnCancelHandler(cancelObserved::countDown);
+
+                DeployEvent bootstrap = DeployEvent.newBuilder()
+                        .setSequence(1)
+                        .setObservedAt(Timestamp.newBuilder().setSeconds(1L).build())
+                        .build();
+                responseObserver.onNext(bootstrap);
+                // Server holds the stream open; cancellation must come from the client.
+            }
+        };
+
+        try (InProcessGalaxy g = InProcessGalaxy.start(service, new AtomicReference<>());
+                GalaxyRepositoryClient client = g.client("")) {
+            DeployEventStream stream = client.watchDeployEvents(null);
+            assertTrue(stream.hasNext());
+            assertEquals(1L, stream.next().getSequence());
+
+            stream.close();
+            assertTrue(
+                    cancelObserved.await(5, TimeUnit.SECONDS),
+                    "server should observe client-side cancellation");
+            assertFalse(stream.hasNext());
+        }
+    }
+
+    private abstract static class TestService extends GalaxyRepositoryGrpc.GalaxyRepositoryImplBase {
+        @Override
+        public void testConnection(
+                TestConnectionRequest request, StreamObserver<TestConnectionReply> responseObserver) {
+            responseObserver.onNext(TestConnectionReply.newBuilder().setOk(true).build());
+            responseObserver.onCompleted();
+        }
+
+        @Override
+        public void getLastDeployTime(
+                GetLastDeployTimeRequest request, StreamObserver<GetLastDeployTimeReply> responseObserver) {
+            responseObserver.onNext(GetLastDeployTimeReply.newBuilder().setPresent(false).build());
+            responseObserver.onCompleted();
+        }
+
+        @Override
+        public void discoverHierarchy(
+                DiscoverHierarchyRequest request, StreamObserver<DiscoverHierarchyReply> responseObserver) {
+            responseObserver.onNext(DiscoverHierarchyReply.getDefaultInstance());
+            responseObserver.onCompleted();
+        }
+
+        @Override
+        public void watchDeployEvents(
+                WatchDeployEventsRequest request, StreamObserver<DeployEvent> responseObserver) {
+            responseObserver.onCompleted();
+        }
+    }
+
+    private record InProcessGalaxy(Server server, ManagedChannel channel) implements AutoCloseable {
+        static InProcessGalaxy start(
+                GalaxyRepositoryGrpc.GalaxyRepositoryImplBase service, AtomicReference<String> authorization)
+                throws Exception {
+            String serverName = "mxgw-galaxy-java-" + UUID.randomUUID();
+            ServerInterceptor interceptor = new ServerInterceptor() {
+                @Override
+                public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
+                        ServerCall<ReqT, RespT> call,
+                        Metadata headers,
+                        ServerCallHandler<ReqT, RespT> next) {
+                    authorization.set(headers.get(MxGatewayAuthInterceptor.AUTHORIZATION_HEADER));
+                    return next.startCall(call, headers);
+                }
+            };
+            Server server = InProcessServerBuilder.forName(serverName)
+                    .directExecutor()
+                    .addService(io.grpc.ServerInterceptors.intercept(service, interceptor))
+                    .build()
+                    .start();
+            ManagedChannel channel = InProcessChannelBuilder.forName(serverName)
+                    .directExecutor()
+                    .build();
+            return new InProcessGalaxy(server, channel);
+        }
+
+        GalaxyRepositoryClient client(String apiKey) {
+            return new GalaxyRepositoryClient(
+                    channel,
+                    MxGatewayClientOptions.builder()
+                            .endpoint("in-process")
+                            .apiKey(apiKey)
+                            .plaintext(true)
+                            .callTimeout(Duration.ofSeconds(5))
+                            .build());
+        }
+
+        @Override
+        public void close() {
+            channel.shutdownNow();
+            server.shutdownNow();
+        }
+    }
+}