// ==========================================================================================
// GameFrameX 组织及其衍生项目的版权、商标、专利及其他相关权利
// GameFrameX organization and its derivative projects' copyrights, trademarks, patents, and related rights
// 均受中华人民共和国及相关国际法律法规保护。
// are protected by the laws of the People's Republic of China and relevant international regulations.
// 使用本项目须严格遵守相应法律法规与开源许可证之规定。
// Usage of this project must strictly comply with applicable laws, regulations, and open-source licenses.
// 本项目采用 Apache License 2.0 单协议分发,
// This project is licensed solely under the Apache License 2.0,
// 完整许可证文本请参见源代码根目录下的 LICENSE 文件。
// please refer to the LICENSE file in the root directory of the source code for the full license text.
// 禁止利用本项目实施任何危害国家安全、破坏社会秩序、
// It is prohibited to use this project to engage in any activities that endanger national security, disrupt social order,
// 侵犯他人合法权益等法律法规所禁止的行为!
// or infringe upon the legitimate rights and interests of others as prohibited by laws and regulations!
// 因基于本项目二次开发所产生的一切法律纠纷与责任,
// Any legal disputes or liabilities arising from secondary development based on this project
// 本组织与贡献者概不承担。
// shall be borne solely by the developer; the project organization and contributors assume no responsibility.
// GitHub 仓库:https://github.com/GameFrameX
// GitHub Repository: https://github.com/GameFrameX
// Gitee 仓库:https://gitee.com/GameFrameX
// Gitee Repository: https://gitee.com/GameFrameX
// CNB 仓库:https://cnb.cool/GameFrameX
// CNB Repository: https://cnb.cool/GameFrameX
// 官方文档:https://gameframex.doc.alianblank.com/
// Official Documentation: https://gameframex.doc.alianblank.com/
// ==========================================================================================
using System.Text.Json;
using GameFrameX.Capability.Hosting.Abstractions;
using GameFrameX.Capability.Hosting.AdminApi;
using GameFrameX.Capability.Hosting.Core;
using GameFrameX.Capability.Online.Abstractions;
using GameFrameX.Capability.Online.Abstractions.Contracts;
using GameFrameX.Capability.Online.Assets;
using GameFrameX.Capability.Online.Foundation.Identity;
using GameFrameX.Capability.Online.Foundation.Storage;
using GameFrameX.Capability.Online.Operations.HotfixRollback;
using GameFrameX.Capability.Online.Persistence.Assets;
using GameFrameX.Capability.Online.Persistence.Identity;
using GameFrameX.Capability.Online.Persistence.Social;
using GameFrameX.Capability.Online.Persistence.Storage;
using GameFrameX.Capability.Online.Match;
using GameFrameX.Capability.Online.Persistence.Match;
using GameFrameX.Foundation.Localization.Core;
using GameFrameX.Foundation.Logger;
using GameFrameX.Launcher.Online;
using GameFrameX.Localization;
using GameFrameX.Capability.Online.Social;
namespace GameFrameX.Launcher.Composition;
///
/// 运行时组合根协调器(实例形态,取代退役的静态 OnlineCapabilityCompositionRoot):
/// 为每个 Role 经 组装「早晚宿主模块 + (启用时)online 能力族」的统一运行时,
/// 并承载进程级族互斥闸与组合者登记(原静态字段迁实例)。
///
///
/// The runtime composition-root coordinator (an instance shape, replacing the retired static
/// OnlineCapabilityCompositionRoot): composes, per role and through ,
/// the unified runtime of "early/late host modules + (when enabled) the online capability family", and
/// carries the process-level family mutual-exclusion gate and the composer registration (the former
/// static fields migrated onto this instance). 维护约束(红线):
/// ① 组合根唯一——一切装配经 (机制内 CapabilityHostBuilder 定序),
/// 本类只做族判定、Options 组装与宿主模块声明,不自带启停定序;
/// ② 同族进程内单例——多 Role 进程首个 EnableRoles 命中的 Role 携带族模块组合,其余命中 Role
/// 只装配宿主模块(互斥闸),族的停止随组合者 Role 的运行时停机(逆序停机下组合者最后停);
/// ③ 双闸全关 / 配置段缺席 / Role 未命中时走无族组合(宿主模块 only,零族装配零族日志——现状等价);
/// ④ admin-only 形态(EnableRuntime=false 且 EnableAdminApi=true)经独立的族运行时承载
/// (仅管理面),其启动点在宿主运行时启动之后(管理面模块注册面不依赖旧栈),停止先于宿主运行时。
/// Red lines: a single composition root — every assembly goes through
/// (ordered by the mechanism's CapabilityHostBuilder), this class only decides family inclusion,
/// builds options and declares host modules with no ordering of its own; one family composition per
/// process; the family-less path for disabled/unmatched roles keeps zero family assembly and zero family
/// logging; the admin-only shape rides a separate family runtime started after the host runtime and
/// stopped before it.
///
internal sealed class RuntimeCompositionRoot
{
///
/// 族组合互斥闸(0 = 未组合 / 组合失败已复位,1 = 有 Role 正在组合或已完成组合)。
///
private int _familyComposed;
///
/// 族组合者 Role 名(ServerType;未组合为 null)。族的停止只归组合者 Role。
///
private string _composerServerType;
///
/// admin-only 形态的族运行时(仅管理面;未组合为 null)。
///
private CapabilityRuntime _adminOnlyFamilyRuntime;
///
/// 组装并启动一个 Role 的统一运行时:判定族启用形态 → 组装(宿主模块恒在)→ 启动。
///
/// 宿主回调面(启动模板实例)。
/// 本 Role 的组合产物(停机由调用方持有并驱动)。
public async Task ComposeAndStartAsync(ILegacyRuntimeHostOwner owner)
{
var setting = owner.Setting;
var online = setting.Online;
var familyRequested = online != null && IsRoleEnabled(online, setting.ServerType) && (online.EnableRuntime || online.EnableAdminApi);
if (familyRequested && online.EnableRuntime)
{
// 同族进程内单例:首个命中 Role 携带族模块组合,后续命中 Role 只装配宿主模块。
if (System.Threading.Interlocked.CompareExchange(ref _familyComposed, 1, 0) != 0)
{
return await ComposeAndStartHostRuntimeAsync(setting, owner);
}
CapabilityRuntime runtime = null;
try
{
var options = BuildFamilyCompositionOptions(setting, enableRuntime: true);
AddHostModules(options, owner);
runtime = CapabilityComposition.Compose(new OnlineCapabilityFamily(), options);
_composerServerType = setting.ServerType;
await runtime.StartAsync();
return runtime;
}
catch
{
await StopFailedRuntimeAsync(runtime);
_composerServerType = null;
System.Threading.Volatile.Write(ref _familyComposed, 0);
throw;
}
}
if (familyRequested)
{
// admin-only 形态:宿主运行时承载旧栈;族运行时仅承载管理面(模块注册即可用,不激活),
// 启动于宿主运行时之后——管理面查询到达时旧栈已就绪。
var hostRuntime = await ComposeAndStartHostRuntimeAsync(setting, owner);
if (System.Threading.Interlocked.CompareExchange(ref _familyComposed, 1, 0) != 0)
{
return hostRuntime;
}
// admin-only 族运行时(仅管理面)。启动失败 = 组合失败:尽力停止已启动部分、复位族闸后重抛
//(宿主运行时一并停机,不留无法回收的监听/调度残骸——调用方模板的失败补齐路径完成收尾)。
_composerServerType = setting.ServerType;
try
{
var adminOptions = BuildFamilyCompositionOptions(setting, enableRuntime: false);
_adminOnlyFamilyRuntime = CapabilityComposition.Compose(new OnlineCapabilityFamily(), adminOptions);
await _adminOnlyFamilyRuntime.StartAsync();
return hostRuntime;
}
catch
{
await StopFailedRuntimeAsync(_adminOnlyFamilyRuntime);
_adminOnlyFamilyRuntime = null;
_composerServerType = null;
System.Threading.Volatile.Write(ref _familyComposed, 0);
await StopFailedRuntimeAsync(hostRuntime);
throw;
}
}
// 族未启用(配置段缺席 / Role 未命中 / 双闸全关):无族组合承载旧栈,零族装配零族日志(现状等价)。
return await ComposeAndStartHostRuntimeAsync(setting, owner);
}
///
/// 摘取 admin-only 族运行时(仅组合者 Role 匹配;摘取后由调用方停机——先于宿主运行时停机)。
///
/// 调用方 Role 名(ServerType)。
/// admin-only 族运行时;非组合者 / 未组合 / 已摘取时为 null。
public CapabilityRuntime DetachAdminOnlyFamilyRuntime(string serverType)
{
if (_adminOnlyFamilyRuntime == null || !string.Equals(_composerServerType, serverType, System.StringComparison.Ordinal))
{
return null;
}
var runtime = _adminOnlyFamilyRuntime;
_adminOnlyFamilyRuntime = null;
return runtime;
}
///
/// 组装并启动无族宿主运行时(早晚宿主模块 only;无族组合不渲染装配报告——旧栈步骤自身有日志,现状等价)。
///
/// 当前 Role 的应用配置。
/// 宿主回调面。
/// 宿主组合产物。
private static async Task ComposeAndStartHostRuntimeAsync(AppSetting setting, ILegacyRuntimeHostOwner owner)
{
var options = new CapabilityCompositionOptions(default(JsonElement), new LogHelperCapabilityAssemblyLog())
{
EnableRuntime = true,
// 无族形态无能力模块消费作用域三元组;机制要求合法值(>0),未配置段回落 1 占位。
HostOptions = BuildHostOptions(setting),
};
AddHostModules(options, owner);
CapabilityRuntime runtime = null;
try
{
runtime = CapabilityComposition.Compose(options);
await runtime.StartAsync();
return runtime;
}
catch
{
await StopFailedRuntimeAsync(runtime);
throw;
}
}
///
/// 构造宿主选项(作用域单键化 D4 后仅 ServerId,未配置(<=0)回落 1 占位——宿主模块不消费作用域,仅满足机制合法性校验)。
///
/// 当前 Role 的应用配置。
/// 宿主选项。
private static CapabilityHostOptions BuildHostOptions(AppSetting setting)
{
return new CapabilityHostOptions
{
ServerId = setting.ServerId > 0 ? setting.ServerId : 1,
};
}
///
/// 声明早晚宿主模块(早段承载 DB/发现/组件/热更;晚段承载监听/ServiceOnline/屏障/Active)。
///
/// 组合选项。
/// 宿主回调面。
private static void AddHostModules(CapabilityCompositionOptions options, ILegacyRuntimeHostOwner owner)
{
options.AddHostModule(new LegacyRuntimeHostModule(owner), CapabilityHostModulePhase.BeforeCapabilities);
options.AddHostModule(new LegacyNetworkListenerHostModule(owner), CapabilityHostModulePhase.AfterCapabilities);
}
///
/// 组合失败路径的尽力停止:撤回已启动部分,停止自身的异常只记日志,不得覆盖触发回滚的原异常。
///
/// 已创建的运行时(可能为 null)。
private static async Task StopFailedRuntimeAsync(CapabilityRuntime runtime)
{
if (runtime == null)
{
return;
}
try
{
await runtime.StopAsync();
}
catch (System.Exception stopException)
{
LogHelper.Error(stopException.ToString());
}
}
///
/// 构造 Online 族组合选项(族配置段 JSON + 双闸 + 作用域三元组 + 能力过滤器 + 管理面 + 宿主 Override 面)——
/// 等价迁移自退役的静态组合根。
///
/// 当前 Role 的应用配置。
/// 业务运行面闸(admin-only 形态传 false)。
/// 族组合选项。
private static CapabilityCompositionOptions BuildFamilyCompositionOptions(AppSetting setting, bool enableRuntime)
{
var online = setting.Online;
var options = new CapabilityCompositionOptions(BuildFamilyConfigurationSection(setting), new LogHelperCapabilityAssemblyLog())
{
EnableRuntime = enableRuntime,
HostOptions = new CapabilityHostOptions
{
ServerId = setting.ServerId,
},
Filter = new CapabilityAssemblyFilter(online.Capabilities, online.Disable),
};
if (online.EnableAdminApi)
{
options.UseAdminApi(adminOptions =>
{
adminOptions.AdminPort = setting.OnlineAdminPort;
adminOptions.AdminApiPrefix = setting.OnlineAdminApiPrefix;
});
}
// 宿主扩展点(Override 注入,来源 = 宿主组合根):Hotfix 版本切换执行器、玩家目录与回滚状态日志。
// 类型实参必须显式写成契约接口:描述符表按类型键索引,省略时推断为具型,模块的 RequireHostService<契约> 找不到覆盖。
options.Override(new HotfixManagerRollbackExecutor(setting));
options.Override(new HostPlayerDirectory());
options.Override(new LogHelperHotfixRollbackLog());
// GameDb 一级 store 覆盖(Online.UseGameDbStores 三态):true 预置五个持久化适配器(业务库已就绪由宿主模块早段保证);
// 未声明(null)= 无声降级防护位——启用族但未声明存储模式时告警(不 fail-fast,保护既有无键部署),随后保持 InMemory 默认。
if (online.UseGameDbStores == true)
{
options.Override(new GameDbOnlineIdentityStore());
options.Override(new GameDbOnlinePlayerStorageStore());
options.Override(new GameDbOnlineAssetStore());
options.Override(new GameDbOnlineAssetTransactionStore());
options.Override(new GameDbOnlineFriendStore());
var matchSettlementStore = new GameDbOnlineMatchSettlementStore();
options.Override(matchSettlementStore);
options.Override(matchSettlementStore);
}
else if (OnlineCapabilityStoreModePolicy.ShouldWarnStoreModeUndeclared(online))
{
LogHelper.Warning(LocalizationService.GetString(Localization.Keys.Capability.OnlineModule.UseGameDbStoresUndeclared, setting.ServerType));
}
return options;
}
///
/// 判定 EnableRoles(缺省 ["Game"])是否命中本 Role。
///
/// Online 配置段。
/// 本 Role 名(ServerType)。
/// 命中返回 true。
private static bool IsRoleEnabled(OnlineCapabilityOptions online, string serverType)
{
var enableRoles = online.GetEffectiveEnableRoles();
for (var index = 0; index < enableRoles.Count; index++)
{
if (string.Equals(enableRoles[index], serverType, System.StringComparison.Ordinal))
{
return true;
}
}
return false;
}
///
/// 重建族配置段原始 JSON(族级键 + Settings 节点):族脊柱包读取 ServerId 落授权作用域(单键化 D4),
/// 机制 Options 绑定器读取 Settings.<能力Id> 做能力级参数覆盖。
///
/// 当前 Role 的应用配置。
/// 族配置段 JSON 节点。
private static JsonElement BuildFamilyConfigurationSection(AppSetting setting)
{
var online = setting.Online;
var section = new Dictionary
{
["ServerId"] = setting.ServerId,
["EnableRuntime"] = online.EnableRuntime,
["EnableAdminApi"] = online.EnableAdminApi,
["UseGameDbStores"] = online.UseGameDbStores,
["Settings"] = online.Settings.ValueKind == JsonValueKind.Undefined || online.Settings.ValueKind == JsonValueKind.Null ? new Dictionary() : online.Settings,
};
return JsonSerializer.SerializeToElement(section);
}
}