Public
Watch 1
Fork 0
You've already forked DaRelay

Latest commit message

DaGermanGuy
Merge pull request 'Limit reply sizes, warn on trustAll, support a key store password file' (#2) from fixes into master
All checks were successful
ci/woodpecker/push/build Pipeline was successful
ci/woodpecker/tag/release Pipeline was successful
d9cd21d 2026-11-16 14:37:26 +00:00 7 commits
2026-11-15 21:47:54 +01:00
2026-11-15 21:46:32 +01:00
2026-11-15 21:44:14 +01:00

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. sendAsync writes a warning when a message can't be sent. It also returns a CompletableFuture<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.