Code
Search code…
Latest commit message
Reviewed-on: #2
DaRelay
Tiny, dependency-free pub/sub for Valkey/Redis. Lets your Minecraft servers and proxies talk to each other. Java 8+, works on Paper/Spigot, Velocity, BungeeCord, Fabric and Forge.
1. Connect
Call once when your plugin/mod starts:
DaRelayListener relay = DaRelayListener.connect("host", 6379, "user", "password", true); // true = TLS
2. Listen
public class MyListener implements RelayListener {
@RelaySub(channel = "mc:proxy")
public void onMessage(RelayEvent e) {
System.out.println(e.getChannel() + " -> " + e.getMessage());
}
}
relay.registerListener(new MyListener());
Listeners run on DaRelay's own thread. On Paper/Spigot, Fabric or Forge, switch to the main thread before touching the game (e.g.
Bukkit.getScheduler().runTask(plugin, () -> ...)).
3. Send
From anywhere, on any server:
DaRelaySender.sendAsync("mc:proxy", "MyMessage");
4. Shut down
When your plugin/mod stops:
relay.shutdown();
This waits up to 2 seconds so messages you just passed to sendAsync (a "server stopping"
notice, for example) still go out.
Good to know
- Messages are not stored. A message reaches the servers that are connected at that moment. A server that is restarting or reconnecting misses it, and nothing is sent again later.
- Reconnecting is automatic. The listener pings Valkey every 15 s. If nothing comes back for
45 s it reconnects (waiting 1 s, then up to 30 s between attempts) and subscribes again.
relay.isConnected()tells you whether it is connected right now. - Failed sends are logged.
sendAsyncwrites a warning when a message can't be sent. It also returns aCompletableFuture<Long>(the number of servers that received the message) if you want to react yourself.DaRelaySender.send(...)does the same on the calling thread and throws on failure. - Queues are limited. Up to 10,000 messages may wait to be sent, and up to 10,000 received messages may wait for your listeners. Beyond that, new ones are dropped with a warning.
- Registering twice is harmless. The same listener object is only registered once, and
relay.unregisterListener(listener)removes it again.
Bundling
Shade DaRelay into your jar and relocate it, so your plugin gets its own copy and its own connection even if another plugin or mod on the same server uses DaRelay too:
// build.gradle.kts, with the Shadow plugin
tasks.shadowJar {
relocate("de.frzy.darelay", "com.example.myplugin.darelay")
}
Without relocation two mods can end up sharing one copy. connect then throws an
IllegalStateException if their settings differ, instead of quietly using the wrong server.
Security
Everyone who can log in to Valkey can publish to the channels their user may access, and a message does not say who sent it. Treat incoming messages like any other network input, and don't run their text as commands.
Give every server its own Valkey user that is limited to your channels:
ACL SETUSER lobby on >a-long-password resetchannels &mc:* -@all +subscribe +unsubscribe +publish +ping
If the user may not use one of your channels, DaRelay logs that once and keeps the other channels working.
With tls = true the server certificate and host name are always checked. Optional JVM flags:
| Flag | Meaning |
|---|---|
-Ddarelay.caFile=/path/ca.crt |
Trust this CA certificate (PEM), for servers with a private CA |
-Ddarelay.keyStore=/path/client.p12 |
Client certificate (PKCS12), needed unless Valkey runs with tls-auth-clients no |
-Ddarelay.keyStorePasswordFile=/path/pass.txt |
File holding the password of the client certificate |
-Ddarelay.keyStorePassword=... |
The password itself. Simpler, but visible in the process list (ps) |
-Ddarelay.trustAll=true |
Accept any certificate. Development only; logs a warning |
A single message may be at most 64 MB; anything larger from the server closes the connection.
Examples
Paper / Spigot
public final class MyPlugin extends JavaPlugin {
private DaRelayListener relay;
@Override
public void onEnable() {
relay = DaRelayListener.connect("host", 6379, "user", "password", true);
relay.registerListener(new MyListener(this));
DaRelaySender.sendAsync("mc:proxy", "Server started");
}
@Override
public void onDisable() {
relay.shutdown();
}
}
public class MyListener implements RelayListener {
private final JavaPlugin plugin;
public MyListener(JavaPlugin plugin) { this.plugin = plugin; }
@RelaySub(channel = "mc:proxy")
public void onMessage(RelayEvent e) {
Bukkit.getScheduler().runTask(plugin, () -> Bukkit.broadcastMessage(e.getMessage()));
}
}
Velocity
@Plugin(id = "myplugin", name = "MyPlugin", version = "1.0.0")
public final class MyPlugin {
private final ProxyServer proxy;
private DaRelayListener relay;
@Inject
public MyPlugin(ProxyServer proxy) {
this.proxy = proxy;
}
@Subscribe
public void onInit(ProxyInitializeEvent e) {
relay = DaRelayListener.connect("host", 6379, "user", "password", true);
relay.registerListener(new MyListener(proxy));
}
@Subscribe
public void onShutdown(ProxyShutdownEvent e) {
relay.shutdown();
}
}
public class MyListener implements RelayListener {
private final ProxyServer proxy;
public MyListener(ProxyServer proxy) { this.proxy = proxy; }
@RelaySub(channel = "mc:proxy")
public void onMessage(RelayEvent e) {
// Velocity is thread-safe, no thread switch needed
proxy.sendMessage(Component.text(e.getMessage()));
}
}
Fabric (Yarn mappings)
public final class MyMod implements ModInitializer {
private DaRelayListener relay;
@Override
public void onInitialize() {
ServerLifecycleEvents.SERVER_STARTED.register(server -> {
relay = DaRelayListener.connect("host", 6379, "user", "password", true);
relay.registerListener(new MyListener(server));
});
ServerLifecycleEvents.SERVER_STOPPING.register(server -> relay.shutdown());
}
}
public class MyListener implements RelayListener {
private final MinecraftServer server;
public MyListener(MinecraftServer server) { this.server = server; }
@RelaySub(channel = "mc:proxy")
public void onMessage(RelayEvent e) {
server.execute(() ->
server.getPlayerManager().broadcast(Text.literal(e.getMessage()), false));
}
}
Forge
@Mod("mymod")
public final class MyMod {
private DaRelayListener relay;
public MyMod() {
MinecraftForge.EVENT_BUS.register(this);
}
@SubscribeEvent
public void onServerStarted(ServerStartedEvent e) {
relay = DaRelayListener.connect("host", 6379, "user", "password", true);
relay.registerListener(new MyListener(e.getServer()));
}
@SubscribeEvent
public void onServerStopping(ServerStoppingEvent e) {
relay.shutdown();
}
}
public class MyListener implements RelayListener {
private final MinecraftServer server;
public MyListener(MinecraftServer server) { this.server = server; }
@RelaySub(channel = "mc:proxy")
public void onMessage(RelayEvent e) {
server.execute(() ->
server.getPlayerList().broadcastSystemMessage(Component.literal(e.getMessage()), false));
}
}
NeoForge
@Mod("mymod")
public final class MyMod {
private DaRelayListener relay;
public MyMod(IEventBus modBus) {
NeoForge.EVENT_BUS.register(this);
}
@SubscribeEvent
public void onServerStarted(ServerStartedEvent e) {
relay = DaRelayListener.connect("host", 6379, "user", "password", true);
relay.registerListener(new MyListener(e.getServer()));
}
@SubscribeEvent
public void onServerStopping(ServerStoppingEvent e) {
relay.shutdown();
}
}
The listener is the same as in the Forge example.