Package top.wcpe.beacon.agent.api

Interface Messaging

public interface Messaging

跨服消息中间件门面（FR-26；传输层现行决策见 ADR-0063，取代 ADR-0016 的 Redis 数据面直连）： 对③层业务插件暴露与内容无关的通用传输。

四种模式：定向发送、请求-响应（RPC）、主题发布订阅、按玩家所在服寻址；外加按类型收消息。 中间件只搬运、不理解业务语义；匹配 / 对战 / 存储 / 排行等游戏功能由业务插件自行实现。

软依赖 + 降级：模块未开启或控制面不可达时 isAvailable() 为 false， 发送类方法抛 IllegalStateException；业务插件应先判 isAvailable() 再用，优雅降级。

线程：发送类方法可在任意线程调用（内部仅编码 + 投递）。收到消息的 handler 在中间件后台线程 触发（绝不在 MC 主线程）；handler 若要碰 Bukkit/Bungee API，需自行切回平台线程。

payload 为「泛型树」：Map<String,Object> / List<Object> / 字符串 / 数字 / 布尔 / null， 经 JSON 往返。演进遵循「只增不改」（可加可选字段，不删/不改已有字段）。

Method Summary

Modifier and Type	Method	Description
CompletableFuture<Object>	call(String targetServerId, String type, Object payload)	请求-响应（RPC）：发请求并立即返回 Future，目标回信后完成；超时则 Future 异常完成 （TimeoutException）。
boolean	isAvailable()	模块是否可用（已启用且控制面可达）。业务侧据此优雅降级。
ListenerHandle	on(String type, MessageHandler handler)	注册按消息类型分发的处理器（收消息入口）。同 type 重复注册以最后一次为准。
void	publish(String topic, Object payload)	主题发布（可丢广播，FR-180 / ADR-0065）：向发送者 namespace 当前全部在线服 fan-out 一条广播 （含发送者自身），topic 落 msg_type，接收方按 subscribe(java.lang.String, top.wcpe.beacon.agent.api.TopicHandler) 注册的同名处理器分发。
default void	publish(String topic, Object payload, String zone)	主题发布 · zone 级定向（FR-180 重载，接口只增不改、守二进制兼容）：只向发送者 namespace 内指定 zone 的当前在线服 fan-out；其余语义同 publish(String, Object)（可丢、不补投、不出信任边界）。
void	send(String targetServerId, String type, Object payload)	定向发送（fire-and-forget，在线尽力送达）：经控制面单跳中转投给目标服。
boolean	sendToPlayer(String playerName, String type, Object payload)	按玩家寻址：解析玩家当前所在服后定向发送（依赖 beacon-proxy 维护的玩家名册）。
ListenerHandle	subscribe(String topic, TopicHandler handler)	主题订阅（FR-180 / ADR-0065）：登记本地按 topic 分发的处理器，接收经 publish(java.lang.String, java.lang.Object) 广播到本服的该主题消息。 与 on(java.lang.String, top.wcpe.beacon.agent.api.MessageHandler) 的定向消息分发表相互隔离、互不干扰。

Method Details

isAvailable

boolean isAvailable()

模块是否可用（已启用且控制面可达）。业务侧据此优雅降级。

send

void send(String targetServerId,
 String type,
 Object payload)

定向发送（fire-and-forget，在线尽力送达）：经控制面单跳中转投给目标服。

不做离线补投（ADR-0063 决策 3）：目标离线即失败、无人取走则 TTL 到期即弃， 控制面不持久化待投。业务侧如需幂等，请按消息携带的标识自行去重。

Parameters:

targetServerId - 目标子服 serverId

type - 业务消息类型（目标按 on(java.lang.String, top.wcpe.beacon.agent.api.MessageHandler) 注册的同名处理器分发）

payload - 业务负载（泛型树）

Throws:

IllegalStateException - 模块不可用

call

CompletableFuture<Object> call(String targetServerId,
 String type,
 Object payload)

请求-响应（RPC）：发请求并立即返回 Future，目标回信后完成；超时则 Future 异常完成 （TimeoutException）。

Returns:

完成值为目标返回的 payload（泛型树）

Throws:

IllegalStateException - 模块不可用

publish

void publish(String topic,
 Object payload)

主题发布（可丢广播，FR-180 / ADR-0065）：向发送者 namespace 当前全部在线服 fan-out 一条广播 （含发送者自身），topic 落 msg_type，接收方按 subscribe(java.lang.String, top.wcpe.beacon.agent.api.TopicHandler) 注册的同名处理器分发。

可丢语义：只投当前在线服，离线不补投；要可靠送达请用 send(java.lang.String, java.lang.String, java.lang.Object) / call(java.lang.String, java.lang.String, java.lang.Object)。 广播不跨 namespace，不出信任边界。

Parameters:

topic - 主题名（落 msg_type，接收方据此路由订阅处理器）

payload - 业务负载（泛型树）

Throws:

IllegalStateException - 模块不可用

publish

default void publish(String topic,
 Object payload,
 String zone)

主题发布 · zone 级定向（FR-180 重载，接口只增不改、守二进制兼容）：只向发送者 namespace 内指定 zone 的当前在线服 fan-out；其余语义同 publish(String, Object)（可丢、不补投、不出信任边界）。

默认实现忽略 zone 退化为全 namespace 广播（保证既有实现零改动仍可编译）； core 门面已覆盖此方法、按 zone 定向。

Parameters:

topic - 主题名

payload - 业务负载（泛型树）

zone - 目标 zone；null 等价于 publish(String, Object)（全 namespace 广播）

Throws:

IllegalStateException - 模块不可用

subscribe

ListenerHandle subscribe(String topic,
 TopicHandler handler)

主题订阅（FR-180 / ADR-0065）：登记本地按 topic 分发的处理器，接收经 publish(java.lang.String, java.lang.Object) 广播到本服的该主题消息。 与 on(java.lang.String, top.wcpe.beacon.agent.api.MessageHandler) 的定向消息分发表相互隔离、互不干扰。

Returns:

可注销句柄（ListenerHandle.remove() 后取消订阅）

Throws:

IllegalStateException - 模块不可用

sendToPlayer

boolean sendToPlayer(String playerName,
 String type,
 Object payload)

按玩家寻址：解析玩家当前所在服后定向发送（依赖 beacon-proxy 维护的玩家名册）。

Returns:

true=已解析并投递；false=名册无此玩家（找不到目标兜底，调用方可重试 / 丢弃）

Throws:

IllegalStateException - 模块不可用 / 未配置玩家位置解析

on

ListenerHandle on(String type,
 MessageHandler handler)

注册按消息类型分发的处理器（收消息入口）。同 type 重复注册以最后一次为准。

若收到的是 RPC 请求，可在处理器内经 IncomingMessage.reply(Object) 回信。

Returns:

可注销句柄