程序包 top.wcpe.beacon.agent.api

接口 BeaconScheduling

public interface BeaconScheduling
本机调度 / 健康门面（FR-148）：业务插件取调度候选与健康事实的唯一入口。

业务插件禁止直连 Beacon HTTP（直连不作为契约、随时可变）；HTTP / JSON 实现只存在于 agent 适配器 （[ADR-0005] 延续），本接口不暴露任何传输细节，对业务插件只读——无改配置 / 改 zone 旁路。

降级语义（fail-static）：控制面不可用时——acquireCandidate(java.lang.String) 走本地快照决策照常返回； candidatesInZone(java.lang.String) / healthOf(java.lang.String) 继续供给最后快照（含 agent 重启后落盘恢复）；一切方法 不抛因控制面不可达导致的异常、不阻塞玩家进服链路；控制面恢复后自动切回在线决策并补报降级期决策。

  • 方法详细资料

    • acquireCandidate

      CompletableFuture<ScheduleResult> acquireCandidate(String zone)
      在指定小区内取一台可调度候选。

      异步返回（内部走独立线程，绝不阻塞调用线程与 MC 主线程）；控制面不可用时自动降级为本地快照决策， future 仍正常完成（fail-static，不因控制面不可达异常完成）。等价于 acquireCandidate(zone, null)。

      参数:
      zone - 目标小区名（namespace 内唯一）
      返回:
      决策结果 future；ScheduleResult.chosen() 为 null 表示本次未取到候选

    • acquireCandidate

      CompletableFuture<ScheduleResult> acquireCandidate(String zone, String purpose)
      在指定小区内取一台可调度候选，并携带业务用途说明。
      参数:
      zone - 目标小区名
      purpose - 业务用途说明（可空，如 lobby-transfer），随决策记录入库供排查
      返回:
      决策结果 future

    • candidatesInZone

      List<CandidateView> candidatesInZone(String zone)
      列出指定小区当前候选快照（本地缓存，O(1) 读，可在主线程调用）。

      非实时，最长滞后一个刷新周期；缓存未覆盖该小区时返回空列表（非 null）。

    • healthOf

      HealthView healthOf(String serverId)
      查询某台服务器的健康视图（本地候选缓存快照）。
      返回:
      缓存未覆盖该服时返回 null

    • selfHealth

      HealthView selfHealth()
      查询本服自身健康视图（随每次指标上报响应刷新，约 5s 新鲜度）。
      返回:
      从未上报成功时返回 null

    • dataSource

      DataSourceState dataSource()
      当前数据来源状态与快照年龄。