EnderRealmMessageRelay

轻量级 WebSocket 消息中继服务：为 Minecraft 多代理（BungeeCord）网络设计的跨服消息同步方案。 频道订阅 + 扇出模型，纯内存、无持久化，服务端与 Java 客户端开箱即用。

A lightweight WebSocket message relay hub for cross-server message sync in Minecraft multi-proxy (BungeeCord) networks. Channel subscribe + fanout model, in-memory only, zero persistence. Ships with a zero-framework Java client.

特性 / Features

• 频道订阅 + 扇出：客户端订阅频道，发布者发一条消息即可送达全部订阅者 / Channel subscribe & fanout: one publish, delivered to all subscribers of the channel
• 租期续订：订阅带 TTL，客户端自动续订，死连接自然过期清理 / Subscriptions carry a TTL lease; clients renew automatically and dead connections expire naturally
• 认证与发布白名单：共享令牌握手，可发布频道由握手声明，防止越权广播 / Shared-token handshake with a publish-channel whitelist, preventing unauthorized broadcasts
• 回声抑制：发布者不会收到自己发布的消息 / Publishers never receive their own messages
• 自动重连：Java 客户端内置指数退避重连，重连后自动恢复订阅 / The Java client has built-in exponential-backoff reconnection and restores subscriptions after reconnect
• 零持久化：纯内存扇出，无数据库依赖，消息发完即弃 / In-memory fanout only, no database, messages are fire-and-forget by design
• 轻量级：服务端 Netty + Gson，客户端纯 JDK（java.net.http.WebSocket），无任何框架 / Server: Netty + Gson. Client: pure JDK, no framework dependencies

架构 / Architecture

┌──────────┐   ┌──────────┐   ┌──────────┐       发布者可以是任意端点：
│ 子服 A   │   │ 子服 B   │   │ 后端服务  │       Paper 服务器、BungeeCord 代理、
│ (Paper)  │   │ (Paper)  │   │ (任意)   │       管理后端、运维工具
└────┬─────┘   └────┬─────┘   └────┬─────┘
     │ WebSocket    │              │
     └──────────────┼──────────────┘
                    ▼
          ┌───────────────────┐
          │  MessageRelayHub  │  频道订阅表 + 扇出（纯内存）
          │  (relay-server)   │  认证 / 白名单 / TTL 清扫
          └───────────────────┘

典型用法：大厅聊天同步（所有 lobby 子服订阅同一频道）、全服广播（所有子服订阅广播频道）、 管理员消息（仅管理端可发布的频道）。

Typical use cases: lobby chat sync (all lobby servers subscribe to one channel), global broadcast (all servers subscribe to a broadcast channel), admin-only messages (channels only the admin backend is allowed to publish).

快速开始 / Quick Start

服务端 / Server

# 构建可执行包
./gradlew :relay-server:shadowJar

# 运行（首次启动自动生成 config.yml，设置 relay.auth-token 后重启）
java -jar relay-server/build/libs/relay-server.jar

或使用 Docker：

docker build -t enderrealm-message-relay relay-server
docker run -p 6500:6500 -v "$PWD/config.yml:/app/config.yml" enderrealm-message-relay

客户端 / Client

// 构建客户端：声明名称、地址、令牌与可发布频道
MessageRelayClient client = MessageRelayClient.builder()
        .name("lobby-1")
        .uri("ws://127.0.0.1:6500")
        .token("your-token")
        .publishChannel("er:chat:lobby")
        .build();

// 订阅频道（自动续订 + 断线自动重连恢复）
client.subscribe("er:chat:lobby", new MessageListener() {
    @Override
    public void onMessage(String from, String channel, String data) {
        System.out.println("[" + from + "] " + data);
    }
});

client.connect();

// 发布消息（仅白名单内的频道）
client.publish("er:chat:lobby", "hello 跨服").join();

协议 / Protocol

完整的协议规范见 protocol.md（中英双语）。 Full protocol specification: protocol.md.

构建 / Build

• JDK 21，Gradle 8.5（仓库自带 wrapper）
• 模块：relay-protocol（协议模型与编解码）、relay-server（服务端）、relay-client（客户端）
• 测试：./gradlew build 运行全部单元与集成测试

许可证 / License

Apache License 2.0