Allow proxying the new server management protocol added in 1.21.9 through the Exaroton API

Author: JulianVennen

.github/workflows/release.yml

@@ -33,6 +33,7 @@ jobs:
           JRELEASER_MAVENCENTRAL_TOKEN: ${{ secrets.SONATYPE_OSSRH_PASSWORD }}
           EXAROTON_API_TOKEN: ${{ secrets.EXAROTON_API_KEY }}
           EXAROTON_TEST_SERVER: "WgvSsfR8ZizUO1RQ"
+          EXAROTON_TEST_SERVER_NAME: "tests4ET"
           EXAROTON_TEST_POOL: "N2t9gWOMpzRL37FI"
         run: ./gradlew clean publish jreleaserDeploy -Prelease=${{ github.ref_name }}
 

.github/workflows/test.yml

@@ -26,4 +26,5 @@ jobs:
         env:
           EXAROTON_API_TOKEN: ${{ secrets.EXAROTON_API_KEY }}
           EXAROTON_TEST_SERVER: "WgvSsfR8ZizUO1RQ"
+          EXAROTON_TEST_SERVER_NAME: "tests4ET"
           EXAROTON_TEST_POOL: "N2t9gWOMpzRL37FI"

CHANGELOG.md

@@ -1,3 +1,9 @@
+# 2.4.0
+## New Features
+- Allow proxying the new server management protocol added in 1.21.9 through the Exaroton API
+
+---
+
 # 2.3.0
 ## New Features
 - Add Endpoint to extend automatic server shutdown timer

build.gradle

@@ -31,6 +31,10 @@ dependencies {
 }
 
 test {
+    def trustStorePath = System.getenv('JAVA_TRUSTSTORE')
+    if (trustStorePath) {
+        jvmArgs "-Djavax.net.ssl.trustStore=${trustStorePath}"
+    }
     useJUnitPlatform()
     testLogging {
         events "passed", "skipped", "failed"

src/main/java/com/exaroton/api/ExarotonClient.java

@@ -40,7 +40,7 @@ public class ExarotonClient {
     /**
      * API host
      */
-    private final String host = "api.exaroton.com";
+    private String host = "api.exaroton.com";
 
     /**
      * API base path
@@ -99,6 +99,15 @@ public ExarotonClient setUserAgent(String userAgent) {
         return this;
     }
 
+    @ApiStatus.Internal
+    public void setHost(String host) {
+        if (host == null || host.isBlank()) {
+            throw new IllegalArgumentException("No host specified");
+        }
+
+        this.host = host;
+    }
+
     /**
      * @return API host
      */

src/main/java/com/exaroton/api/server/Server.java

@@ -7,6 +7,7 @@
 import com.exaroton.api.ws.stream.*;
 import com.exaroton.api.ws.subscriber.*;
 import com.google.gson.Gson;
+import com.google.gson.JsonElement;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -578,6 +579,41 @@ public void removeTickSubscriber(@NotNull TickSubscriber subscriber) {
         this.subscribe().removeStreamSubscriber(TickStream.class, subscriber);
     }
 
+    /**
+     * Subscribe to server management notifications
+     * @param subscriber management notification handler
+     */
+    @ApiStatus.AvailableSince("2.4.0")
+    public void addServerManagementNotificationSubscriber(@NotNull ManagementNotificationSubscriber subscriber) {
+        this.subscribe().addStreamSubscriber(ServerManagementStream.class, subscriber);
+    }
+
+    /**
+     * Unsubscribe from server management notifications
+     * @param subscriber management notification handler
+     */
+    @ApiStatus.AvailableSince("2.4.0")
+    public void removeServerManagementNotificationSubscriber(@NotNull ManagementNotificationSubscriber subscriber) {
+        if (this.webSocket == null) {
+            return;
+        }
+
+        this.subscribe().removeStreamSubscriber(ServerManagementStream.class, subscriber);
+    }
+
+    /**
+     * Send a server management request. This requires the management server to be online. It also automatically
+     * subscribes to the management stream if not already done. This means you have to manually unsubscribe using
+     * {@link WebSocketConnection#unsubscribe(StreamType)}} if you want to close the connection.
+     * @param method name of the method to call
+     * @param params arguments for the method (can be null)
+     * @return future that completes with the result of the request
+     */
+    @ApiStatus.AvailableSince("2.4.0")
+    public CompletableFuture<JsonElement> sendServerManagementRequest(@NotNull String method, @Nullable JsonElement params) {
+        return this.subscribe().getOrCreateStream(ServerManagementStream.class).sendRequest(method, params);
+    }
+
     /**
      * Get the current WebSocketConnection. A new connection will be created automatically if a subscriber is added.
      * @return web socket connection or null

src/main/java/com/exaroton/api/ws/WebSocketConnection.java

@@ -206,7 +206,8 @@ public CompletableFuture<Void> waitForReady() {
         return readyFuture;
     }
 
-    private <T extends Stream<?>> @NotNull T getOrCreateStream(Class<T> clazz) {
+    @ApiStatus.Internal
+    public <T extends Stream<?>> @NotNull T getOrCreateStream(Class<T> clazz) {
         synchronized (streams) {
             @SuppressWarnings("unchecked") T stream = (T) this.streams.computeIfAbsent(clazz, this::createAndStartStream);
             return stream;

src/main/java/com/exaroton/api/ws/stream/ServerManagementStream.java

@@ -0,0 +1,86 @@
+package com.exaroton.api.ws.stream;
+
+import com.exaroton.api.server.ServerStatus;
+import com.exaroton.api.ws.WebSocketConnection;
+import com.exaroton.api.ws.subscriber.ManagementNotificationSubscriber;
+import com.google.gson.Gson;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.*;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ConcurrentHashMap;
+
+@ApiStatus.Internal
+public final class ServerManagementStream extends Stream<ManagementNotificationSubscriber> {
+    private final Map<UUID, CompletableFuture<JsonElement>> waitingForResponse = new ConcurrentHashMap<>();
+
+    public ServerManagementStream(@NotNull WebSocketConnection ws, @NotNull Gson gson) {
+        super(ws, gson);
+    }
+
+    @Override
+    public StreamType getType() {
+        return StreamType.MANAGEMENT;
+    }
+
+    @Override
+    protected void onDataMessage(String type, JsonObject message) {
+        var data = message.getAsJsonObject("data");
+        switch (type) {
+            case "notification":
+                for (ManagementNotificationSubscriber subscriber : getSubscribers()) {
+                    subscriber.handleNotification(data.get("name").getAsString(), data.get("data"));
+                }
+                break;
+            case "response":
+                var id = UUID.fromString(data.get("id").getAsString());
+                var future = waitingForResponse.remove(id);
+                if (future != null) {
+                    future.complete(data.get("data"));
+                }
+                break;
+        }
+    }
+
+    @Override
+    protected Set<ServerStatus> getStartableStatuses() {
+        return Set.of(ServerStatus.ONLINE);
+    }
+
+    @Override
+    public boolean hasNoSubscribers() {
+        return false;
+    }
+
+    public CompletableFuture<JsonElement> sendRequest(@NotNull String method, @Nullable JsonElement params) {
+        return this.shouldBeStarted().thenCompose(shouldStart -> {
+            if (!shouldStart) {
+                throw new IllegalStateException("The management stream is not active.");
+            }
+
+            var future = new CompletableFuture<JsonElement>();
+            var id = UUID.randomUUID();
+            waitingForResponse.put(id, future);
+            var item = new Request(id, method, params);
+            this.sendWhenStarted(messageData("request", item));
+            return future;
+        });
+    }
+
+    @SuppressWarnings({"FieldCanBeLocal", "unused"})
+    private static final class Request {
+        private final UUID id;
+        private final String method;
+        private final JsonElement params;
+
+        public Request(UUID id, String method, JsonElement params) {
+            this.id = id;
+            this.method = method;
+            this.params = params;
+        }
+    }
+}

src/main/java/com/exaroton/api/ws/stream/Stream.java

@@ -11,6 +11,7 @@
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Objects;
+import java.util.Set;
 import java.util.concurrent.CompletableFuture;
 
 @ApiStatus.Internal
@@ -19,7 +20,7 @@ public abstract class Stream<T> {
     /**
      * Has this stream been started?
      */
-    private boolean started;
+    protected boolean started;
 
     /**
      * Should this stream be started when the server is ready?
@@ -196,7 +197,11 @@ protected CompletableFuture<Boolean> shouldBeStarted() {
             return CompletableFuture.completedFuture(false);
         }
 
-        return ws.serverHasStatus(
+        return ws.serverHasStatus(this.getStartableStatuses());
+    }
+
+    protected Set<ServerStatus> getStartableStatuses() {
+        return Set.of(
                 ServerStatus.ONLINE,
                 ServerStatus.STARTING,
                 ServerStatus.STOPPING,

src/main/java/com/exaroton/api/ws/stream/StreamType.java

@@ -15,7 +15,8 @@ public enum StreamType {
     STATUS("status", ServerStatusStream.class, ServerStatusStream::new),
     STATS("stats", StatsStream.class, StatsStream::new),
     TICK("tick", TickStream.class, TickStream::new),
-    ;
+    @ApiStatus.AvailableSince("2.4.0")
+    MANAGEMENT("management", ServerManagementStream.class, ServerManagementStream::new);
 
     private final String name;
     private final Class<? extends Stream<?>> streamClass;