web api plugin

Author: rfresh2

README.md

@@ -1,64 +1,69 @@
-# ZenithProxy Example Plugin
+# ZenithProxy Web API Plugin
 
-[ZenithProxy](https://github.com/rfresh2/ZenithProxy) is a Minecraft proxy and bot.
+Runs a local web server that lets you interact with the ZenithProxy instance.
 
-This repository is an example core plugin for ZenithProxy, allowing you to add custom modules and commands.
+# Commands
 
-## Installing Plugins
+## `webApi`
 
-Plugins are only supported on the `java` ZenithProxy release channel (i.e. not `linux`).
+* `webApi on/off` -> default: on
+* `webApi port <port>` -> default: 8080
+* `webApi auth <token>`
 
-Place plugin jars in the `plugins` folder inside the same folder as the ZenithProxy launcher.
+# HTTP API
 
-Restart ZenithProxy to load plugins. Loading plugins after launch or hot reloading is not supported.
+## Authorization
 
-## Creating Plugins
+All HTTP requests must have an `Authorization` header.
 
-Use this repository as a template to create your own plugin repository.
+A default auth token is generated on first launch.
 
-### Plugin Structure
+Or it can be set with the `webApi auth <token>` command.
 
-Each plugin needs a main class that implements `ZenithProxyPlugin` and is annotated with `@Plugin`.
+## POST `/command`
 
-Plugin metadata like its unique id, version, and supported MC versions is defined in the `@Plugin` annotation.
+### Request Body
 
-[See example](https://github.com/rfresh2/ZenithProxyExamplePlugin/blob/1.21.0/src/main/java/org/example/ExamplePlugin.java)
+```json
+{
+  "command": "status"
+}
+```
 
-### Plugin API
+### Response
 
-The `ZenithProxyPlugin` interface requires you to implement an `onLoad` method.
+```json
+{
+   "embed": "\nZenithProxy 0.0.0 - Unknown\n\nStatus\nDisconnected\nConnected Player\nNone\nOnline For\nNot Online!\nHealth\n20.0\nDimension\nNone\nPing\n0ms\nProxy IP\nlocalhost\nServer\nconnect.2b2t.org:25565\nPriority Queue\nno [unbanned]\nSpectators\non\n2b2t Queue\nPriority: 15 [00:25:49]\nRegular: 688 [07:49:27]\nCoordinates\n||[0, 0, 0]||\nAutoUpdate\non",
+   "embedComponent": "{\"color\":\"#E91E63\",\"extra\":[\"\\n\",{\"bold\":true,\"text\":\"ZenithProxy 0.0.0 - Unknown\"},\"\\n\",\"\\n\",{\"bold\":true,\"extra\":[\"\\n\"],\"text\":\"Status\"},{\"extra\":[\"Disconnected\"],\"text\":\"\"},\"\\n\",{\"bold\":true,\"extra\":[\"\\n\"],\"text\":\"Connected Player\"},{\"extra\":[\"None\"],\"text\":\"\"},\"\\n\",{\"bold\":true,\"extra\":[\"\\n\"],\"text\":\"Online For\"},{\"extra\":[\"Not Online!\"],\"text\":\"\"},\"\\n\",{\"bold\":true,\"extra\":[\"\\n\"],\"text\":\"Health\"},{\"extra\":[\"20.0\"],\"text\":\"\"},\"\\n\",{\"bold\":true,\"extra\":[\"\\n\"],\"text\":\"Dimension\"},{\"extra\":[\"None\"],\"text\":\"\"},\"\\n\",{\"bold\":true,\"extra\":[\"\\n\"],\"text\":\"Ping\"},{\"extra\":[\"0ms\"],\"text\":\"\"},\"\\n\",{\"bold\":true,\"extra\":[\"\\n\"],\"text\":\"Proxy IP\"},{\"extra\":[\"localhost\"],\"text\":\"\"},\"\\n\",{\"bold\":true,\"extra\":[\"\\n\"],\"text\":\"Server\"},{\"extra\":[\"connect.2b2t.org:25565\"],\"text\":\"\"},\"\\n\",{\"bold\":true,\"extra\":[\"\\n\"],\"text\":\"Priority Queue\"},{\"extra\":[\"no [unbanned]\"],\"text\":\"\"},\"\\n\",{\"bold\":true,\"extra\":[\"\\n\"],\"text\":\"Spectators\"},{\"extra\":[\"on\"],\"text\":\"\"},\"\\n\",{\"bold\":true,\"extra\":[\"\\n\"],\"text\":\"2b2t Queue\"},{\"extra\":[\"Priority: 15 [00:25:49]\\nRegular: 688 [07:49:27]\"],\"text\":\"\"},\"\\n\",{\"bold\":true,\"extra\":[\"\\n\"],\"text\":\"Coordinates\"},{\"extra\":[\"||[0, 0, 0]||\"],\"text\":\"\"},\"\\n\",{\"bold\":true,\"extra\":[\"\\n\"],\"text\":\"AutoUpdate\"},{\"extra\":[\"on\"],\"text\":\"\"}],\"text\":\"\"}",
+   "multiLineOutput": []
+}
+```
 
-This method provides a `PluginAPI` object that you can use to register modules, commands, and config files.
+The `embedComponent` can be parsed back from json with [Kyori Adventure](https://docs.advntr.dev/getting-started.html)
+```java
+Component c = GsonComponentSerializer.gson().deserialize(embedComponent);
+```
 
-`Module` and `Command` classes are implemented the same as in the ZenithProxy source code.
+### Example
 
-I recommend looking at existing modules and commands for examples.
+```bash
+curl --location 'http://localhost:8080/command' \
+--header 'Authorization: c05598ed-d123-4e8f-9aa7-40c11e657f23' \
+--header 'Content-Type: application/json' \
+--data '{"command":"status"}'
+```
 
-* [Module](https://github.com/rfresh2/ZenithProxy/tree/1.21.0/src/main/java/com/zenith/module)
-* [Command](https://github.com/rfresh2/ZenithProxy/tree/1.21.0/src/main/java/com/zenith/command)
+# FAQ
 
-### Building Plugins
+## How do I call the API from the public internet?
 
-Execute the Gradle `build` task: `./gradlew build` - or double-click the task in Intellij
+Depends on where and how you are hosting the ZenithProxy instance.
 
-The built plugin jar will be in the `build/libs` directory.
+It's the same as accessing the ZenithProxy MC server from the public internet.
 
-### Testing Plugins
+So if you had to change firewall settings, port forwarding, or set up tunneling you'd do the same for the web API's port.
 
-Execute the `run` task: `./gradlew run` - or double-click the task in Intellij
+## I'm running multiple ZenithProxy instance on the same server, can they all have web APIs?
 
-This will run ZenithProxy with your plugin loaded in the `run` directory.
-
-### New Plugin Checklist
-
-1. Edit `gradle.properties`:
-   - `plugin_name` - Name of your plugin, used in the plugin jar name (e.g. `ExamplePlugin`)
-   - `maven_group` - Java package for your project (e.g. `com.github.rfresh2`)
-1. Move files to your new corresponding package / maven group:
-   - Example: `src/main/java/org/example` -> `src/main/java/com/github/rfresh2`
-   - First create the new package in `src/main/java`. Then click and drag original subpackages/classes to your new one
-   - Do this with Intellij to avoid manually editing all the source files
-   - You must also move folders/package for the `src/main/templates` folder
-   - Also make sure to update the package import at the very top of `BuiltConstants.java`, it will not be done automatically
-1. Edit `ExamplePlugin.java`, or remove it and create a new main class
-   - Make sure to update the `@Plugin` annotation
+Yes, but each needs to be configured to use a different port: `webApi port <port>`

build.gradle.kts

@@ -15,6 +15,7 @@ zenithProxyPlugin {
 }
 
 repositories {
+    mavenLocal()
     maven("https://maven.2b2t.vc/releases") {
         description = "ZenithProxy Releases and Dependencies"
     }
@@ -25,4 +26,19 @@ repositories {
 
 dependencies {
     zenithProxy("com.zenith:ZenithProxy:$mc-SNAPSHOT")
+    shade("io.javalin:javalin:6.6.0")
+}
+
+tasks {
+    shadowJar {
+        val shadowPackage = "dev.zenith.web.shadow"
+        relocate("io.javalin", "$shadowPackage.javalin")
+        relocate("jakarta.servlet", "$shadowPackage.jakarta.servlet")
+        relocate("kotlin", "$shadowPackage.kotlin")
+        relocate("org.eclipse", "$shadowPackage.org.eclipse")
+        exclude("org/slf4j/**")
+        exclude("org/jetbrains/**")
+        exclude("META-INF/maven/**")
+        // todo: transform service files? seems to work fine without them for now
+    }
 }

gradle.properties

@@ -1,7 +1,7 @@
 plugin_version=1.0.0
-plugin_name=ZenithProxyExamplePlugin
+plugin_name=ZenithProxyWebAPI
 mc=1.21.0
-maven_group=org.example
+maven_group=dev.zenith.web
 
 org.gradle.configuration-cache=true
 org.gradle.parallel=true

src/main/java/dev/zenith/web/WebAPICommandSource.java

@@ -0,0 +1,25 @@
+package dev.zenith.web;
+
+import com.zenith.command.api.CommandContext;
+import com.zenith.command.api.CommandOutputHelper;
+import com.zenith.command.api.CommandSource;
+import com.zenith.discord.Embed;
+
+public class WebAPICommandSource extends CommandSource {
+    public static final WebAPICommandSource INSTANCE = new WebAPICommandSource();
+    public WebAPICommandSource() {
+        super("WebAPI", () -> "");
+    }
+
+    @Override
+    public boolean validateAccountOwner(final CommandContext ctx) {
+        ctx.getEmbed()
+            .description("Web API is not authorized to execute this command!");
+        return false;
+    }
+
+    @Override
+    public void logEmbed(final CommandContext commandContext, final Embed embed) {
+        CommandOutputHelper.logEmbedOutputToTerminal(embed);
+    }
+}

src/main/java/dev/zenith/web/WebAPIConfig.java

@@ -0,0 +1,9 @@
+package dev.zenith.web;
+
+import java.util.UUID;
+
+public class WebAPIConfig {
+    public boolean enabled = true;
+    public int port = 8080;
+    public String authToken = UUID.randomUUID().toString();
+}

src/main/java/dev/zenith/web/WebApiPlugin.java

@@ -0,0 +1,32 @@
+package dev.zenith.web;
+
+import com.zenith.plugin.api.Plugin;
+import com.zenith.plugin.api.PluginAPI;
+import com.zenith.plugin.api.ZenithProxyPlugin;
+import dev.zenith.web.command.WebAPICommand;
+import net.kyori.adventure.text.logger.slf4j.ComponentLogger;
+
+@Plugin(
+    id = "web-api",
+    version = BuildConstants.VERSION,
+    description = "Web API for ZenithProxy",
+    url = "https://github.com/rfresh2/ZenithProxyWebAPI",
+    authors = {"rfresh2"},
+    mcVersions = {"1.21.0"}
+)
+public class WebApiPlugin implements ZenithProxyPlugin {
+    public static WebAPIConfig PLUGIN_CONFIG;
+    public static ComponentLogger LOG;
+    public static WebServer SERVER;
+
+    @Override
+    public void onLoad(PluginAPI pluginAPI) {
+        LOG = pluginAPI.getLogger();
+        PLUGIN_CONFIG = pluginAPI.registerConfig("web-api", WebAPIConfig.class);
+        SERVER = new WebServer();
+        if (PLUGIN_CONFIG.enabled) {
+            SERVER.start();
+        }
+        pluginAPI.registerCommand(new WebAPICommand());
+    }
+}

src/main/java/dev/zenith/web/WebServer.java

@@ -0,0 +1,84 @@
+package dev.zenith.web;
+
+import com.zenith.Globals;
+import com.zenith.command.api.CommandContext;
+import com.zenith.discord.EmbedSerializer;
+import com.zenith.util.ComponentSerializer;
+import dev.zenith.web.model.AuthErrorResponse;
+import dev.zenith.web.model.CommandRequest;
+import dev.zenith.web.model.CommandResponse;
+import io.javalin.Javalin;
+
+import java.util.List;
+
+import static dev.zenith.web.WebApiPlugin.LOG;
+import static dev.zenith.web.WebApiPlugin.PLUGIN_CONFIG;
+
+public class WebServer {
+    private Javalin server;
+
+    public synchronized void start() {
+        if (server != null) {
+            stop();
+        }
+        initialize();
+        server.start(PLUGIN_CONFIG.port);
+        LOG.info("Web API started on port {}", PLUGIN_CONFIG.port);
+        LOG.info("Auth token: {}", PLUGIN_CONFIG.authToken);
+    }
+
+    public synchronized void stop() {
+        if (server != null) {
+            server.stop();
+            server = null;
+            LOG.info("Web API stopped");
+        }
+    }
+
+    public synchronized boolean isRunning() {
+        return server != null && server.jettyServer().started();
+    }
+
+    private void initialize() {
+        server = Javalin.create(config -> {
+                config.useVirtualThreads = true;
+                config.http.defaultContentType = "application/json";
+            })
+            .beforeMatched(ctx -> {
+                var authHeaderValue = ctx.header("Authorization");
+                if (authHeaderValue != null) {
+                    var expectedHeaderValue = PLUGIN_CONFIG.authToken;
+                    if (authHeaderValue.equals(expectedHeaderValue)) {
+                        // ok
+                        return;
+                    }
+                }
+                String reason = authHeaderValue == null
+                    ? "Authorization header missing"
+                    : "Invalid auth token";
+                ctx.json(new AuthErrorResponse(reason));
+                ctx.status(401);
+                ctx.skipRemainingHandlers();
+                LOG.warn("Denied request from {}: {}", ctx.ip(), reason);
+            })
+            .post("/command", ctx -> {
+                var req = ctx.bodyAsClass(CommandRequest.class);
+                var command = req.command();
+                var context = CommandContext.create(command, WebAPICommandSource.INSTANCE);
+                LOG.info("{} executed command: {}", ctx.ip(), command);
+                Globals.COMMAND.execute(context);
+                context.getSource().logEmbed(context, context.getEmbed());
+                String embedResponse = null;
+                String embedResponseComponent = null;
+                List<String> multiLineResponse = context.getMultiLineOutput();
+                if (context.getEmbed().isTitlePresent()) {
+                    var embedComponent = EmbedSerializer.serialize(context.getEmbed());
+                    var embedString = ComponentSerializer.serializePlain(embedComponent);
+                    embedResponse = embedString;
+                    embedResponseComponent = ComponentSerializer.serializeJson(embedComponent);
+                }
+                ctx.json(new CommandResponse(embedResponse, embedResponseComponent, multiLineResponse));
+                ctx.status(200);
+            });
+    }
+}

src/main/java/dev/zenith/web/command/WebAPICommand.java

@@ -0,0 +1,72 @@
+package dev.zenith.web.command;
+
+import com.mojang.brigadier.builder.LiteralArgumentBuilder;
+import com.zenith.command.api.Command;
+import com.zenith.command.api.CommandCategory;
+import com.zenith.command.api.CommandContext;
+import com.zenith.command.api.CommandUsage;
+import com.zenith.discord.Embed;
+
+import static com.mojang.brigadier.arguments.IntegerArgumentType.getInteger;
+import static com.mojang.brigadier.arguments.IntegerArgumentType.integer;
+import static com.zenith.command.brigadier.CustomStringArgumentType.getString;
+import static com.zenith.command.brigadier.CustomStringArgumentType.wordWithChars;
+import static com.zenith.command.brigadier.ToggleArgumentType.getToggle;
+import static com.zenith.command.brigadier.ToggleArgumentType.toggle;
+import static dev.zenith.web.WebApiPlugin.PLUGIN_CONFIG;
+import static dev.zenith.web.WebApiPlugin.SERVER;
+
+public class WebAPICommand extends Command {
+    @Override
+    public CommandUsage commandUsage() {
+        return CommandUsage.builder()
+            .name("webapi")
+            .category(CommandCategory.MODULE)
+            .description("""
+                Manages the HTTP web API for interacting with this ZenithProxy instance.
+                """)
+            .usageLines(
+                "on/off",
+                "port <port>",
+                "auth <token>"
+            )
+            .build();
+    }
+
+    @Override
+    public LiteralArgumentBuilder<CommandContext> register() {
+        return command("webapi").requires(Command::validateAccountOwner)
+            .then(argument("toggle", toggle()).executes(c -> {
+                PLUGIN_CONFIG.enabled = getToggle(c, "toggle");
+                if (PLUGIN_CONFIG.enabled) {
+                    SERVER.start();
+                } else {
+                    SERVER.stop();
+                }
+                c.getSource().getEmbed()
+                    .title("Web API " + toggleStrCaps(PLUGIN_CONFIG.enabled));
+            }))
+            .then(literal("port").then(argument("portArg", integer(1, 65535)).executes(c -> {
+                PLUGIN_CONFIG.port = getInteger(c, "portArg");
+                if (PLUGIN_CONFIG.enabled) {
+                    SERVER.start();
+                }
+                c.getSource().getEmbed()
+                    .title("Port Set");
+            })))
+            .then(literal("auth").then(argument("token", wordWithChars()).executes(c -> {
+                PLUGIN_CONFIG.authToken = getString(c, "token");
+                c.getSource().getEmbed()
+                    .title("Auth Token Set");
+            })));
+    }
+
+    @Override
+    public void defaultEmbed(Embed embed) {
+        embed
+            .addField("Web API", SERVER.isRunning() ? "Running" : "Stopped")
+            .addField("Port", PLUGIN_CONFIG.port)
+            .addField("Auth Token", PLUGIN_CONFIG.authToken)
+            .primaryColor();
+    }
+}

src/main/java/dev/zenith/web/model/AuthErrorResponse.java

@@ -0,0 +1,5 @@
+package dev.zenith.web.model;
+
+public record AuthErrorResponse(
+    String reason
+) { }

src/main/java/dev/zenith/web/model/CommandRequest.java

@@ -0,0 +1,5 @@
+package dev.zenith.web.model;
+
+public record CommandRequest(
+    String command
+) { }