// ==========================================================================================
// 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 and 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.Collections.Concurrent;
using System.Diagnostics;
using System.Net.Sockets;
using GameFrameX.Foundation.Localization.Core;
namespace GameFrameX.Network.RemoteMessaging.Composition;
///
/// 统一远程消息调用客户端。串联服务解析、连接管理、编解码、请求匹配、拦截器、重试、熔断和健康探测。
///
///
/// Unified remote message call client. Orchestrates service resolution, connection management, encoding/decoding, request-response matching, interceptors, retry, circuit breaking, and health probing.
///
internal sealed class RemoteMessageClient : IRemoteMessageClient, IDisposable
{
private readonly ConcurrentDictionary _connections = new();
private readonly ICircuitBreaker _circuitBreaker;
private readonly IEndpointHealthEvaluator _healthEvaluator;
private readonly IRemoteCallInterceptor[] _interceptors;
private readonly IMessageCodec _messageCodec;
private readonly IRequestResponseMatcher _requestResponseMatcher;
private readonly IRetryPolicy _retryPolicy;
private readonly ITransportProtocolAdapter _transportProtocolAdapter;
private readonly int _handshakeTimeoutMs;
private int _closed;
///
/// 初始化统一远程消息调用客户端。
///
///
/// Initializes the unified remote message call client.
///
/// 传输协议适配器 / Transport protocol adapter
/// 消息编解码器 / Message codec
/// 请求-响应匹配器 / Request-response matcher
/// 远程调用拦截器数组 / Array of remote call interceptors
/// 重试策略(可为 null) / Retry policy (can be null)
/// 熔断器 / Circuit breaker
/// 端点健康评估器:调用前按服务名取健康评分,评分 ≤ 0 时直接判定服务不可用(请求 / 单向发送 / 可用性查询均短路);调用成功标记健康、失败标记不可用 / Endpoint health evaluator: the per-service health score is checked before each call, and a score ≤ 0 short-circuits requests, one-way sends and availability queries as unavailable; successful calls mark the endpoint healthy and failures mark it unavailable
/// 协议版本握手超时(毫秒),≤ 0 时取默认 2000ms;超时后若未启用节点间鉴权则按旧版本协议(Legacy)放行并告警,启用鉴权时按连接失败处理 / Protocol version handshake timeout in milliseconds; values ≤ 0 fall back to the 2000 ms default. On timeout the connection is admitted as the legacy protocol version with a warning when inter-node authentication is disabled, and treated as a connection failure when it is enabled
public RemoteMessageClient(
ITransportProtocolAdapter transportProtocolAdapter,
IMessageCodec messageCodec,
IRequestResponseMatcher requestResponseMatcher,
IRemoteCallInterceptor[] interceptors,
IRetryPolicy retryPolicy,
ICircuitBreaker circuitBreaker,
IEndpointHealthEvaluator healthEvaluator,
int handshakeTimeoutMs)
{
_transportProtocolAdapter = transportProtocolAdapter;
_messageCodec = messageCodec;
_requestResponseMatcher = requestResponseMatcher ?? throw new ArgumentNullException(nameof(requestResponseMatcher));
_interceptors = interceptors ?? Array.Empty();
_retryPolicy = retryPolicy;
_circuitBreaker = circuitBreaker;
_healthEvaluator = healthEvaluator;
_handshakeTimeoutMs = handshakeTimeoutMs > 0 ? handshakeTimeoutMs : 2000;
}
///
/// 发送请求并等待响应(使用默认超时)。
///
///
/// Sends a request and waits for a response (using default timeout).
///
/// 响应消息类型 / The response message type
/// 目标服务名 / The target service name
/// 请求消息对象 / The request message object
/// 响应消息对象;超时或失败时返回 null / The response message object; returns null on timeout or failure
public Task CallAsync(
string serviceName,
MessageObject requestMessage)
where TResponse : class, IResponseMessage
{
return CallAsync(serviceName, requestMessage, RemoteCallContext.DefaultTimeoutMs);
}
///
/// 发送请求并等待响应(使用默认超时,支持取消)。
///
///
/// Sends a request and waits for a response (using default timeout, with cancellation support).
///
/// 响应消息类型 / The response message type
/// 目标服务名 / The target service name
/// 请求消息对象 / The request message object
/// 取消令牌 / The cancellation token
/// 响应消息对象;超时或失败时返回 null / The response message object; returns null on timeout or failure
public Task CallAsync(
string serviceName,
MessageObject requestMessage,
CancellationToken cancellationToken)
where TResponse : class, IResponseMessage
{
return CallAsync(serviceName, requestMessage, RemoteCallContext.DefaultTimeoutMs, cancellationToken);
}
///
/// 发送请求并等待响应(指定超时)。
///
///
/// Sends a request and waits for a response (with specified timeout).
///
/// 响应消息类型 / The response message type
/// 目标服务名 / The target service name
/// 请求消息对象 / The request message object
/// 超时毫秒数 / The timeout duration in milliseconds
/// 取消令牌 / The cancellation token
/// 响应消息对象;超时或失败时返回 null / The response message object; returns null on timeout or failure
public async Task CallAsync(
string serviceName,
MessageObject requestMessage,
int timeoutMs,
CancellationToken cancellationToken = default)
where TResponse : class, IResponseMessage
{
var context = RemoteCallContext.Create(serviceName, timeoutMs, cancellationToken);
var result = await CallWithResultAsync(context, requestMessage);
return result.Response;
}
///
/// 发送请求并返回结构化结果(使用默认超时)。
///
///
/// Sends a request and returns a structured result (using default timeout).
///
/// 响应消息类型 / The response message type
/// 目标服务名 / The target service name
/// 请求消息对象 / The request message object
/// 结构化调用结果 / The structured call result
public Task> CallWithResultAsync(
string serviceName,
MessageObject requestMessage)
where TResponse : class, IResponseMessage
{
var context = RemoteCallContext.Create(serviceName);
return CallWithResultAsync(context, requestMessage);
}
///
/// 发送请求并返回结构化结果(指定超时)。
///
///
/// Sends a request and returns a structured result (with specified timeout).
///
/// 响应消息类型 / The response message type
/// 目标服务名 / The target service name
/// 请求消息对象 / The request message object
/// 超时毫秒数 / The timeout duration in milliseconds
/// 结构化调用结果 / The structured call result
public Task> CallWithResultAsync(
string serviceName,
MessageObject requestMessage,
int timeoutMs)
where TResponse : class, IResponseMessage
{
var context = RemoteCallContext.Create(serviceName, timeoutMs);
return CallWithResultAsync(context, requestMessage);
}
///
/// 发送请求并返回结构化结果(指定超时和取消令牌)。
///
///
/// Sends a request and returns a structured result (with specified timeout and cancellation token).
///
/// 响应消息类型 / The response message type
/// 目标服务名 / The target service name
/// 请求消息对象 / The request message object
/// 超时毫秒数 / The timeout duration in milliseconds
/// 取消令牌 / The cancellation token
/// 结构化调用结果 / The structured call result
public Task> CallWithResultAsync(
string serviceName,
MessageObject requestMessage,
int timeoutMs,
CancellationToken cancellationToken)
where TResponse : class, IResponseMessage
{
var context = RemoteCallContext.Create(serviceName, timeoutMs, cancellationToken);
return CallWithResultAsync(context, requestMessage);
}
///
/// 发送幂等请求并返回结构化结果(自动启用重试)。适用于读操作和查询接口。
///
///
/// Sends an idempotent request and returns a structured result (retry automatically enabled). Suitable for read operations and query interfaces.
///
/// 响应消息类型 / The response message type
/// 目标服务名 / The target service name
/// 请求消息对象 / The request message object
/// 超时毫秒数 / The timeout duration in milliseconds
/// 最大重试次数 / Maximum retry count
/// 取消令牌 / The cancellation token
/// 结构化调用结果 / The structured call result
public Task> CallWithRetryAsync(
string serviceName,
MessageObject requestMessage,
int timeoutMs = RemoteCallContext.DefaultTimeoutMs,
int maxRetryCount = RemoteCallContext.DefaultMaxRetryCount,
CancellationToken cancellationToken = default)
where TResponse : class, IResponseMessage
{
var context = RemoteCallContext.CreateIdempotent(serviceName, timeoutMs, maxRetryCount, cancellationToken);
return CallWithResultAsync(context, requestMessage);
}
///
/// 发送非幂等请求并返回结构化结果(禁用重试)。适用于写操作和状态变更接口。
///
///
/// Sends a non-idempotent request and returns a structured result (retry disabled). Suitable for write operations and state-changing interfaces.
///
/// 响应消息类型 / The response message type
/// 目标服务名 / The target service name
/// 请求消息对象 / The request message object
/// 超时毫秒数 / The timeout duration in milliseconds
/// 取消令牌 / The cancellation token
/// 结构化调用结果 / The structured call result
public Task> CallWithoutRetryAsync(
string serviceName,
MessageObject requestMessage,
int timeoutMs = RemoteCallContext.DefaultTimeoutMs,
CancellationToken cancellationToken = default)
where TResponse : class, IResponseMessage
{
var context = RemoteCallContext.CreateNonIdempotent(serviceName, timeoutMs, cancellationToken);
return CallWithResultAsync(context, requestMessage);
}
///
/// 发送请求并返回结构化结果(携带环境参数)。环境参数可通过拦截器读取,用于日志记录、链路追踪等。
///
///
/// Sends a request and returns a structured result (with environment parameters). Environment parameters can be read by interceptors for logging, tracing, etc.
///
/// 响应消息类型 / The response message type
/// 目标服务名 / The target service name
/// 请求消息对象 / The request message object
/// 环境参数字典(如 ServerId、PlayerId 等) / Environment parameter dictionary (e.g., ServerId, PlayerId)
/// 超时毫秒数 / The timeout duration in milliseconds
/// 取消令牌 / The cancellation token
/// 结构化调用结果 / The structured call result
public Task> CallWithMetadataAsync(
string serviceName,
MessageObject requestMessage,
Dictionary metadata,
int timeoutMs = RemoteCallContext.DefaultTimeoutMs,
CancellationToken cancellationToken = default)
where TResponse : class, IResponseMessage
{
var context = RemoteCallContext.CreateWithMetadata(serviceName, metadata, timeoutMs, cancellationToken);
return CallWithResultAsync(context, requestMessage);
}
///
/// 发送请求并返回结构化结果(包含状态码、耗时、重试信息)。
///
///
/// Sends a request and returns a structured result containing status code, elapsed time, and retry information.
///
/// 响应消息类型 / The response message type
/// 调用上下文(含超时、重试策略、追踪信息) / The call context (including timeout, retry strategy, and tracing info)
/// 请求消息对象 / The request message object
/// 结构化调用结果 / The structured call result
public async Task> CallWithResultAsync(
RemoteCallContext context,
MessageObject requestMessage)
where TResponse : class, IResponseMessage
{
var stopwatch = Stopwatch.StartNew();
var attemptCount = 0;
while (true)
{
attemptCount++;
stopwatch.Restart();
_requestResponseMatcher?.CleanupExpired();
var preconditionFailure = CheckPreconditions(context, stopwatch);
if (preconditionFailure != null)
{
return preconditionFailure;
}
var attempt = await ExecuteAttemptAsync(context, requestMessage, stopwatch, attemptCount);
if (attempt.ShouldRetry)
{
await Task.Delay(_retryPolicy.GetRetryDelayMs(attemptCount));
continue;
}
return attempt.Result;
}
}
///
/// 执行调用前置检查(熔断器、端点健康评分)。
///
///
/// Performs pre-call checks (circuit breaker, endpoint health score). Returns a failure result, or null when the call may proceed.
///
/// 响应消息类型 / The response message type
/// 调用上下文 / The call context
/// 计时器 / The elapsed-time stopwatch
/// 失败结果;通过检查时返回 null / A failure result; null when the call may proceed
private RemoteCallResult CheckPreconditions(RemoteCallContext context, Stopwatch stopwatch)
where TResponse : class, IResponseMessage
{
// 熔断 / 健康统计键 = RemoteServiceTarget.ToString():ServerType 级为 "Social",实例级为 "Social/2001"
//(实例级失败只隔离该实例;指标 / 日志拦截器仍按 context.ServiceName 聚合,该差异是有意的)。
var targetKey = ToTarget(context).ToString();
// 熔断检查
if (!_circuitBreaker.IsAllowed(targetKey))
{
return RemoteCallResult.Fail(
RemoteStatusCode.CircuitOpen,
$"Circuit breaker is open for service: {targetKey}",
stopwatch.ElapsedMilliseconds,
context.TraceId);
}
// 健康探测检查
var healthScore = _healthEvaluator.GetHealthScore(targetKey);
if (healthScore <= 0)
{
return RemoteCallResult.Fail(
RemoteStatusCode.ServiceUnavailable,
$"Service health score is {healthScore}, considered unavailable: {targetKey}",
stopwatch.ElapsedMilliseconds,
context.TraceId);
}
return null;
}
///
/// 执行一次请求尝试(拦截器、协议检查、信号量临界区、编码写入与响应匹配),并返回是否应重试。
///
///
/// Performs a single request attempt (interceptors, protocol check, semaphore critical section, encoding/write, response matching). Returns the result and whether the caller should retry.
///
/// 响应消息类型 / The response message type
/// 调用上下文 / The call context
/// 请求消息对象 / The request message object
/// 计时器 / The elapsed-time stopwatch
/// 当前尝试序号(从 1 起)/ The current attempt number (1-based)
/// 本次尝试的结果与是否应重试 / The attempt result and whether the caller should retry
private async Task<(RemoteCallResult Result, bool ShouldRetry)> ExecuteAttemptAsync(
RemoteCallContext context, MessageObject requestMessage, Stopwatch stopwatch, int attemptCount)
where TResponse : class, IResponseMessage
{
Stream stream = null;
var target = ToTarget(context);
var targetKey = target.ToString();
try
{
await RunBeforeInterceptorsAsync(context, requestMessage);
stream = await _transportProtocolAdapter.GetOrCreateStreamAsync(target, context.CancellationToken);
if (stream == null)
{
RecordFailures(targetKey, "Failed to create connection");
return (
RemoteCallResult.Fail(
RemoteStatusCode.ConnectionFailed,
"Failed to create connection",
stopwatch.ElapsedMilliseconds,
context.TraceId),
false);
}
var connection = GetOrCreateConnection(stream);
// 连接级协议版本握手(每连接单飞一次):拒绝抛 ProtocolVersionMismatchException,混布超时回落旧版本
await EnsureHandshakeAsync(connection, targetKey);
var requestUniqueId = _requestResponseMatcher.RegisterPendingRequest(context.TimeoutMs);
PrepareRequestMessage(requestMessage, requestUniqueId);
using (var requestBuffer = _messageCodec.Encode(requestMessage))
{
// 写入门控按连接独立:同一连接上的并发写串行化,不同连接完全并行
await connection.WriteAsync(requestBuffer.Memory, context.CancellationToken);
}
// 响应由该连接的接收泵经请求-响应匹配器投递,等待方不再内联占用连接读取
return (await WaitForResponseAsync(connection, requestUniqueId, context, requestMessage, stopwatch, attemptCount), false);
}
catch (RemoteEndpointNotFoundException endpointNotFoundException)
{
stopwatch.Stop();
// EndpointNotFound 表示「本次未解析到端点」(冷启动窗口 / 实例下线),请求未离开发送进程,
// 不是端点健康信号:不计入熔断与健康评分(避免冷启动把健康中的 ServerType 拉黑),维持不可重试。
await RunExceptionInterceptorsAsync(context, requestMessage, endpointNotFoundException, stopwatch.ElapsedMilliseconds);
return (
RemoteCallResult.Fail(
RemoteStatusCode.EndpointNotFound,
"Failed to resolve service endpoint",
stopwatch.ElapsedMilliseconds,
context.TraceId),
false);
}
catch (OperationCanceledException)
{
stopwatch.Stop();
var cancellation = ToCancellationOutcome(context);
RecordFailures(targetKey, cancellation.errorMessage);
await RunExceptionInterceptorsAsync(context, requestMessage, new TimeoutException(cancellation.errorMessage), stopwatch.ElapsedMilliseconds);
return (
RemoteCallResult.Fail(cancellation.statusCode, cancellation.errorMessage, stopwatch.ElapsedMilliseconds, context.TraceId),
ShouldRetry(context, cancellation.statusCode, attemptCount));
}
catch (GameFrameX.Network.RemoteMessaging.Versioning.ProtocolVersionMismatchException versionMismatch)
{
stopwatch.Stop();
// 拒绝即断连:失效该连接避免半开复用(服务端回拒绝包后亦已关闭会话)
if (stream != null)
{
_transportProtocolAdapter.Invalidate(stream);
}
RecordFailures(targetKey, versionMismatch.Message);
await RunExceptionInterceptorsAsync(context, requestMessage, versionMismatch, stopwatch.ElapsedMilliseconds);
return (
RemoteCallResult.Fail(
RemoteStatusCode.ProtocolVersionIncompatible,
versionMismatch.Message,
stopwatch.ElapsedMilliseconds,
context.TraceId),
false);
}
catch (Exception ex)
{
stopwatch.Stop();
// 连接级异常仅失效当前连接(池内其余连接与其它 endpoint 不受影响);
// 非连接类异常(编码失败、协议协商等)交由熔断/健康评分/重试处理,不破坏共享连接面
if (stream != null && IsConnectionException(ex))
{
_transportProtocolAdapter.Invalidate(stream);
}
RecordFailures(targetKey, ex.Message);
await RunExceptionInterceptorsAsync(context, requestMessage, ex, stopwatch.ElapsedMilliseconds);
var statusCode = IsConnectionException(ex) ? RemoteStatusCode.ConnectionFailed : RemoteStatusCode.UnknownError;
return (
RemoteCallResult.Fail(statusCode, ex.Message, stopwatch.ElapsedMilliseconds, context.TraceId),
ShouldRetry(context, statusCode, attemptCount));
}
}
///
/// 在超时窗口内等待请求-响应匹配器投递的响应(响应由连接接收泵解码并路由)。
///
///
/// Waits within the timeout window for the response delivered by the request-response matcher
/// (responses are decoded and routed by the connection receive pump).
///
/// 响应消息类型 / The response message type
/// 连接上下文 / The connection context
/// 请求唯一 ID / The unique ID of the request
/// 调用上下文 / The call context
/// 请求消息对象 / The request message object
/// 计时器 / The elapsed-time stopwatch
/// 当前尝试序号(从 1 起)/ The current attempt number (1-based)
/// 匹配到的响应结果 / The matched response result
private async Task> WaitForResponseAsync(
ConnectionContext connection, int requestUniqueId, RemoteCallContext context, MessageObject requestMessage, Stopwatch stopwatch, int attemptCount)
where TResponse : class, IResponseMessage
{
var targetKey = ToTarget(context).ToString();
connection.TrackPending(requestUniqueId);
try
{
MessageObject responseMessage;
using (var timeoutCts = CancellationTokenSource.CreateLinkedTokenSource(context.CancellationToken))
{
timeoutCts.CancelAfter(context.TimeoutMs);
responseMessage = await _requestResponseMatcher.WaitResponseAsync(requestUniqueId, timeoutCts.Token);
}
stopwatch.Stop();
if (responseMessage == null)
{
// 挂起条目丢失(连接死亡竞态):按连接关闭处理
RecordFailures(targetKey, "Connection closed during response");
return RemoteCallResult.Fail(
RemoteStatusCode.ConnectionClosed,
"Connection closed during response",
stopwatch.ElapsedMilliseconds,
context.TraceId);
}
if (responseMessage is not TResponse typedResponse)
{
return RemoteCallResult.Fail(
RemoteStatusCode.UnexpectedResponse,
"Response type mismatch",
stopwatch.ElapsedMilliseconds,
context.TraceId);
}
RecordSuccess(targetKey);
await RunAfterInterceptorsAsync(context, requestMessage, responseMessage, stopwatch.ElapsedMilliseconds);
return RemoteCallResult.Ok(typedResponse, stopwatch.ElapsedMilliseconds, context.TraceId, attemptCount - 1);
}
finally
{
connection.UntrackPending(requestUniqueId);
}
}
///
/// 获取或创建指定流的连接上下文。首次见到某条连接时启动其专属接收泵。
///
///
/// Gets or creates the connection context for the given stream. A dedicated receive pump is started
/// the first time a connection is seen.
///
/// 传输流 / The transport stream
/// 连接上下文 / The connection context
private ConnectionContext GetOrCreateConnection(Stream stream)
{
return _connections.GetOrAdd(stream, addedStream =>
{
var connection = new ConnectionContext(addedStream, _requestResponseMatcher);
var receivePumpTask = RunReceivePumpAsync(connection);
connection.AttachReceivePumpTask(receivePumpTask);
// faulted 泵的异常在 continuation 中被观察(含读取 Exception),消除 UnobservedTaskException;
// 泵内 generic catch 不再记 Error(见 RunReceivePumpAsync),避免双份错误日志
receivePumpTask.ContinueWith(
faulted => LogHelper.Error(faulted.Exception, LocalizationService.GetString(Localization.Keys.RemoteMessaging.ClientModule.ReceivePumpFaulted)),
TaskContinuationOptions.OnlyOnFaulted);
return connection;
});
}
///
/// 确保连接完成协议版本握手(每连接单飞一次)。major 不符抛 ;
/// 握手超时按旧版本节点放行(混布窗口兼容,告警一次)。
///
///
/// Ensures the connection has completed the protocol version handshake (single-flight per
/// connection). A major mismatch throws ;
/// a handshake timeout falls back to the legacy peer version (mixed-window compatibility, one warning).
///
/// 连接上下文 / The connection context
/// 目标服务名(用于告警) / The target service name (for warning logs)
private async Task EnsureHandshakeAsync(ConnectionContext connection, string serviceName)
{
await connection.GetOrStartHandshakeAsync(() => PerformHandshakeAsync(connection, serviceName));
}
///
/// 执行一次协议版本握手:发送本端版本 → 等待响应 → major 比对。
///
///
/// Performs one protocol version handshake: send the local version, await the reply,
/// and compare majors.
///
/// 连接上下文 / The connection context
/// 目标服务名 / The target service name
private async Task PerformHandshakeAsync(ConnectionContext connection, string serviceName)
{
var local = GameFrameX.Network.RemoteMessaging.Versioning.RemoteMessagingProtocolVersion.Current;
var request = new GameFrameX.Network.RemoteMessaging.Versioning.ReqProtocolVersionNegotiation
{
Major = local.Major,
Minor = local.Minor,
};
// 节点间鉴权:共享密钥已配置时附带每连接随机 nonce 与 HMAC 凭据;
// 未配置时保持无凭据字段(与旧版本节点线缆逐字节等价)
if (GameFrameX.Network.RemoteMessaging.Versioning.InterNodeAuthentication.IsEnabled)
{
request.Nonce = GameFrameX.Network.RemoteMessaging.Versioning.InterNodeAuthentication.CreateNonce();
request.AuthCredential = GameFrameX.Network.RemoteMessaging.Versioning.InterNodeAuthentication.ComputeCredential(request.Nonce, local.Major, local.Minor);
}
var requestUniqueId = _requestResponseMatcher.RegisterPendingRequest(_handshakeTimeoutMs);
PrepareRequestMessage(request, requestUniqueId);
connection.TrackPending(requestUniqueId);
try
{
using (var requestBuffer = _messageCodec.Encode(request))
{
// 握手帧与业务帧共用写入门控与 14 字节编解码帧(传输无关)
await connection.WriteAsync(requestBuffer.Memory, CancellationToken.None);
}
MessageObject response;
using (var handshakeCts = new CancellationTokenSource(_handshakeTimeoutMs))
{
response = await _requestResponseMatcher.WaitResponseAsync(requestUniqueId, handshakeCts.Token);
}
if (response is GameFrameX.Network.RemoteMessaging.Versioning.RespProtocolVersionNegotiation handshakeResponse)
{
var remote = new GameFrameX.Network.RemoteMessaging.Versioning.ProtocolVersion(handshakeResponse.Major, handshakeResponse.Minor);
if (!handshakeResponse.Accepted || remote.Major != local.Major)
{
// Localization: RemoteMessaging.Versioning.HandshakeRejected - 协议版本握手被拒绝:本端 {0},远端 {1}。连接已关闭(跨 major 混布禁止)。
throw new GameFrameX.Network.RemoteMessaging.Versioning.ProtocolVersionMismatchException(
LocalizationService.GetString(Localization.Keys.RemoteMessaging.Versioning.HandshakeRejected, local, remote),
local,
remote);
}
return;
}
if (response == null)
{
// 挂起条目丢失(连接死亡竞态):按连接关闭处理,由外层既有异常路径失效重试
throw new IOException(LocalizationService.GetString(Localization.Keys.RemoteMessaging.ClientModule.ConnectionClosed));
}
// 对握手唯一 ID 返回了非握手响应:协议异常,按不兼容拒绝(避免误放行)
throw new GameFrameX.Network.RemoteMessaging.Versioning.ProtocolVersionMismatchException(
LocalizationService.GetString(Localization.Keys.RemoteMessaging.Versioning.HandshakeRejected, local, new GameFrameX.Network.RemoteMessaging.Versioning.ProtocolVersion(0, 0)),
local,
new GameFrameX.Network.RemoteMessaging.Versioning.ProtocolVersion(0, 0));
}
catch (OperationCanceledException)
{
if (GameFrameX.Network.RemoteMessaging.Versioning.InterNodeAuthentication.IsEnabled)
{
// 鉴权启用时超时不再回落旧版本——回落是可利用的降级面(丢弃握手响应即可绕过凭据协商),
// 按连接失败处理,由外层既有异常路径失效重试
// Localization: RemoteMessaging.Versioning.HandshakeAuthTimeoutFailClosed - 服务 '{0}' 的协议版本握手在 {1}ms 后超时;节点间鉴权已启用,不回落旧版本,按连接失败处理。
throw new IOException(LocalizationService.GetString(
Localization.Keys.RemoteMessaging.Versioning.HandshakeAuthTimeoutFailClosed,
serviceName,
_handshakeTimeoutMs));
}
// 混布窗口:旧节点不识别握手消息 ID(丢帧不回包),超时按旧版本放行并告警(每连接一次)
// Localization: RemoteMessaging.Versioning.HandshakeLegacyFallback - 服务 '{0}' 的协议版本握手在 {1}ms 后超时;按旧版本节点({2})放行。该告警仅滚动升级窗口内属预期,全量升级完成后应消失。
LogHelper.Warning(LocalizationService.GetString(
Localization.Keys.RemoteMessaging.Versioning.HandshakeLegacyFallback,
serviceName,
_handshakeTimeoutMs,
GameFrameX.Network.RemoteMessaging.Versioning.RemoteMessagingProtocolVersion.Legacy));
}
finally
{
connection.UntrackPending(requestUniqueId);
}
}
///
/// 连接接收泵:持续解码该连接上的响应帧并经请求-响应匹配器投递给等待方。
/// 泵退出(连接关闭或解码异常)时精准失效该连接,并快速失败其上全部挂起请求。
///
///
/// Connection receive pump: continuously decodes response frames on the connection and delivers them
/// to waiters via the request-response matcher. When the pump exits (connection closed or decode failure),
/// the connection is invalidated precisely and all its pending requests fail fast.
///
/// 连接上下文 / The connection context
private async Task RunReceivePumpAsync(ConnectionContext connection)
{
try
{
while (true)
{
var message = await _messageCodec.DecodeAsync(connection.Stream, CancellationToken.None);
if (message == null)
{
break;
}
_requestResponseMatcher.TryComplete(message.UniqueId, message);
}
}
catch (Exception exception) when (exception is IOException || exception is SocketException || exception is ObjectDisposedException || exception is OperationCanceledException)
{
// 连接级失败(对端关闭 / 网络异常 / 关闭竞态 / 取消):按连接死亡处理(finally 已精准失效并快速失败挂起请求,
// 受影响调用的指标经既有链路上报:FailAllPending → 等待方异常 → 调用方拦截器 OnException)
}
catch (Exception exception) when (exception is InvalidDataException || exception is NotSupportedException)
{
// 解码/协议失败(帧损坏、未注册压缩算法):连接死亡处理 + 连接级可见性(不吞异常)
// Localization: RemoteMessaging.ClientModule.ReceivePumpDecodeFailure - 连接接收泵解码失败(帧损坏或协议异常),连接已按死亡处理并快速失败挂起请求
LogHelper.Warning(exception, LocalizationService.GetString(Localization.Keys.RemoteMessaging.ClientModule.ReceivePumpDecodeFailure));
}
catch (Exception)
{
// 未分类异常(如 OOM)不吞:向上抛出——泵任务 fault,由 GetOrCreateConnection 挂的
// OnlyOnFaulted continuation 记录(RemoteMessaging.Client.ReceivePumpFaulted)并观察异常,
// 不再落入 TaskScheduler.UnobservedTaskException
throw;
}
finally
{
connection.MarkDead();
_connections.TryRemove(connection.Stream, out _);
_transportProtocolAdapter.Invalidate(connection.Stream);
connection.FailAllPending(new IOException(LocalizationService.GetString(Localization.Keys.RemoteMessaging.ClientModule.ConnectionClosed)));
}
}
///
/// 连接上下文:封装单条连接的写入门控与该连接上的挂起请求追踪。
///
///
/// Connection context: encapsulates the write gate of a single connection and tracking of its pending requests.
///
private sealed class ConnectionContext
{
private readonly SemaphoreSlim _writeGate = new(1, 1);
private readonly object _handshakeLock = new();
private Task _receivePumpTask = Task.CompletedTask;
private Task _handshakeTask;
private readonly IRequestResponseMatcher _matcher;
private readonly ConcurrentDictionary _pendingUniqueIds = new();
private volatile bool _dead;
public ConnectionContext(Stream stream, IRequestResponseMatcher matcher)
{
Stream = stream;
_matcher = matcher;
}
public Stream Stream { get; }
///
/// 获取或启动本连接的单飞握手任务:首个调用者执行握手,并发调用者等待同一任务结果。
///
///
/// Gets or starts this connection's single-flight handshake task: the first caller performs
/// the handshake while concurrent callers await the same task's outcome.
///
public Task GetOrStartHandshakeAsync(Func starter)
{
lock (_handshakeLock)
{
// 单飞:GetOrAdd 工厂竞态与并发首调用都收敛到同一个握手任务,握手帧每连接恰发一次
_handshakeTask ??= starter();
return _handshakeTask;
}
}
///
/// 保存该连接的接收泵任务(在 GetOrAdd 工厂内、连接对外可见前调用,无竞态),供关闭收口等待泵退出。
///
///
/// Stores this connection's receive pump task (called inside the GetOrAdd factory before the
/// connection becomes visible, so there is no race) so shutdown can await the pump's exit.
///
/// 接收泵任务 / The receive pump task
public void AttachReceivePumpTask(Task receivePumpTask)
{
_receivePumpTask = receivePumpTask;
}
///
/// 获取该连接的接收泵任务(未启动泵的占位连接为已完成任务)。
///
///
/// Gets this connection's receive pump task (a completed task for placeholder connections
/// whose pump has not started).
///
public Task ReceivePumpTask
{
get { return _receivePumpTask; }
}
///
/// 向连接写入一个完整帧。同一连接上的并发写经写入门控串行化,帧间不交错。
///
///
/// Writes one complete frame to the connection. Concurrent writes on the same connection are
/// serialized through the write gate so frames never interleave.
///
/// 已编码帧缓冲 / The encoded frame buffer
/// 取消令牌 / The cancellation token
public async Task WriteAsync(ReadOnlyMemory buffer, CancellationToken cancellationToken)
{
if (_dead)
{
throw new IOException(LocalizationService.GetString(Localization.Keys.RemoteMessaging.ClientModule.ConnectionClosed));
}
await _writeGate.WaitAsync(cancellationToken);
try
{
await Stream.WriteAsync(buffer, cancellationToken);
}
finally
{
_writeGate.Release();
}
}
public void TrackPending(int uniqueId)
{
_pendingUniqueIds[uniqueId] = 0;
}
public void UntrackPending(int uniqueId)
{
_pendingUniqueIds.TryRemove(uniqueId, out _);
}
public void MarkDead()
{
_dead = true;
}
///
/// 以连接关闭异常快速失败该连接上全部挂起请求(等待方立即收到可重试的连接级错误)。
///
///
/// Fails all pending requests on this connection fast with a connection-closed exception
/// (waiters immediately receive a retryable connection-level error).
///
/// 失败原因异常 / The failure exception
public void FailAllPending(Exception exception)
{
foreach (var uniqueId in _pendingUniqueIds.Keys)
{
if (_pendingUniqueIds.TryRemove(uniqueId, out _))
{
_matcher.TryFail(uniqueId, exception);
}
}
}
}
///
/// 将取消异常映射为状态码与错误消息(区分主动取消与超时)。
///
///
/// Maps a cancellation exception to a status code and error message (distinguishing explicit cancellation from timeout).
///
/// 调用上下文 / The call context
/// 状态码与错误消息 / The status code and error message
private static (RemoteStatusCode statusCode, string errorMessage) ToCancellationOutcome(RemoteCallContext context)
{
if (context.CancellationToken.IsCancellationRequested)
{
return (RemoteStatusCode.Cancelled, "Request was cancelled");
}
return (RemoteStatusCode.Timeout, $"Request timed out after {context.TimeoutMs}ms");
}
///
/// 单向发送消息,不等待响应(ServerType 级确定性选择)。
///
///
/// Sends a message one-way without waiting for a response (a deterministic
/// ServerType-level selection).
///
/// 目标服务名 / The target service name
/// 请求消息对象 / The request message object
/// 发送超时毫秒数 / The send timeout duration in milliseconds
/// 取消令牌 / The cancellation token
public Task SendOneWayAsync(
string serviceName,
MessageObject requestMessage,
int timeoutMs = RemoteCallContext.DefaultTimeoutMs,
CancellationToken cancellationToken = default)
{
return SendOneWayAsync(RemoteCallContext.Create(serviceName, timeoutMs, cancellationToken), requestMessage);
}
///
/// 单向发送消息,不等待响应(完整上下文版本,可携带 直达实例)。
///
///
/// Sends a message one-way without waiting for a response (the full-context version, which
/// can carry to reach a specific instance).
///
/// 调用上下文 / The call context
/// 请求消息对象 / The request message object
public async Task SendOneWayAsync(RemoteCallContext context, MessageObject requestMessage)
{
ArgumentNullException.ThrowIfNull(context);
var target = ToTarget(context);
var targetKey = target.ToString();
if (!_circuitBreaker.IsAllowed(targetKey))
{
// Localization: RemoteMessaging.Client.SendOneWayCircuitBreakerOpen - SendOneWayAsync: 熔断器已打开, Service: {0}
LogHelper.Warning(LocalizationService.GetString(Localization.Keys.RemoteMessaging.ClientModule.SendOneWayCircuitBreakerOpen, targetKey));
return;
}
var healthScore = _healthEvaluator.GetHealthScore(targetKey);
if (healthScore <= 0)
{
// Localization: RemoteMessaging.Client.SendOneWayHealthScoreLow - SendOneWayAsync: 服务健康评分过低, Service: {0}, Score: {1}
LogHelper.Warning(LocalizationService.GetString(Localization.Keys.RemoteMessaging.ClientModule.SendOneWayHealthScoreLow, targetKey, healthScore));
return;
}
Stream stream = null;
try
{
await RunBeforeInterceptorsAsync(context, requestMessage);
stream = await _transportProtocolAdapter.GetOrCreateStreamAsync(target, context.CancellationToken);
if (stream == null)
{
RecordFailures(targetKey, "SendOneWayAsync: Failed to create connection");
return;
}
var connection = GetOrCreateConnection(stream);
// 连接级协议版本握手(与 RPC 路径同一单飞门);拒绝时按单向发送口径记告警并放弃本次发送
try
{
await EnsureHandshakeAsync(connection, targetKey);
}
catch (GameFrameX.Network.RemoteMessaging.Versioning.ProtocolVersionMismatchException versionMismatch)
{
_transportProtocolAdapter.Invalidate(stream);
RecordFailures(targetKey, versionMismatch.Message);
// Localization: RemoteMessaging.Versioning.HandshakeRejected - 协议版本握手被拒绝:本端 {0},远端 {1}。连接已关闭(跨 major 混布禁止)。
LogHelper.Warning(LocalizationService.GetString(Localization.Keys.RemoteMessaging.Versioning.HandshakeRejected, versionMismatch.Local, versionMismatch.Remote));
return;
}
var requestUniqueId = _requestResponseMatcher.RegisterPendingRequest(context.TimeoutMs);
PrepareRequestMessage(requestMessage, requestUniqueId);
using (var requestBuffer = _messageCodec.Encode(requestMessage))
{
await connection.WriteAsync(requestBuffer.Memory, context.CancellationToken);
RecordSuccess(targetKey);
await RunAfterInterceptorsAsync(context, requestMessage, null, 0);
}
}
catch (OperationCanceledException)
{
RecordFailures(targetKey, context.CancellationToken.IsCancellationRequested ? "SendOneWayAsync cancelled" : "SendOneWayAsync timed out");
}
catch (RemoteEndpointNotFoundException)
{
// EndpointNotFound 不计入熔断与健康评分(与 CallWithResultAsync 路径同一定案:本次未解析到端点不是端点健康信号)。
// EndpointNotFound never counts toward the circuit breaker or health score (same ruling as the CallWithResultAsync path).
}
catch (Exception ex)
{
// 与 RPC 路径同一定案:连接级异常仅失效当前连接,非连接类异常交由熔断/健康评分处理,不清共享连接池
if (stream != null && IsConnectionException(ex))
{
_transportProtocolAdapter.Invalidate(stream);
}
RecordFailures(targetKey, $"SendOneWayAsync error: {ex.Message}");
}
}
///
/// 检查目标服务是否可用。
///
///
/// Checks whether the target service is available.
///
/// 目标服务名 / The target service name
/// 服务是否可用 / Whether the service is available
public Task IsServiceAvailableAsync(string serviceName)
{
if (!_circuitBreaker.IsAllowed(serviceName))
{
return Task.FromResult(false);
}
var healthScore = _healthEvaluator.GetHealthScore(serviceName);
if (healthScore <= 0)
{
return Task.FromResult(false);
}
return Task.FromResult(_transportProtocolAdapter.IsServiceAvailable(new RemoteServiceTarget(serviceName)));
}
///
/// 由调用上下文构建结构化端点目标(ServerType = ServiceName,InstanceId = TargetInstanceId)。
///
///
/// Builds the structured endpoint target from the call context (ServerType = ServiceName,
/// InstanceId = TargetInstanceId).
///
/// 调用上下文 / The call context
/// 结构化端点目标 / The structured endpoint target
private static RemoteServiceTarget ToTarget(RemoteCallContext context)
{
return new RemoteServiceTarget(context.ServiceName, context.TargetInstanceId);
}
private void RecordSuccess(string serviceName)
{
_circuitBreaker.RecordSuccess(serviceName);
_healthEvaluator.MarkHealthy(serviceName);
}
private void RecordFailures(string serviceName, string reason)
{
_circuitBreaker.RecordFailure(serviceName);
_healthEvaluator.MarkUnavailable(serviceName, reason);
}
private bool ShouldRetry(RemoteCallContext context, RemoteStatusCode statusCode, int attemptCount)
{
return _retryPolicy != null && _retryPolicy.ShouldRetry(context, statusCode, attemptCount);
}
private static bool IsConnectionException(Exception ex)
{
return ex is IOException || ex is SocketException || ex is ObjectDisposedException;
}
private async Task RunBeforeInterceptorsAsync(RemoteCallContext context, MessageObject request)
{
foreach (var interceptor in _interceptors)
{
await interceptor.OnBeforeCallAsync(context, request);
}
}
private async Task RunAfterInterceptorsAsync(RemoteCallContext context, MessageObject request, MessageObject response, long elapsedMs)
{
foreach (var interceptor in _interceptors)
{
await interceptor.OnAfterCallAsync(context, request, response, elapsedMs);
}
}
private async Task RunExceptionInterceptorsAsync(RemoteCallContext context, MessageObject request, Exception exception, long elapsedMs)
{
foreach (var interceptor in _interceptors)
{
try
{
await interceptor.OnExceptionAsync(context, request, exception, elapsedMs);
}
catch (Exception ex)
{
// Localization: RemoteMessaging.Client.InterceptorOnExceptionFailed - 拦截器 OnExceptionAsync 失败
LogHelper.Error(ex, LocalizationService.GetString(Localization.Keys.RemoteMessaging.ClientModule.InterceptorOnExceptionFailed));
}
}
}
///
/// 准备请求消息的元数据(消息ID、唯一ID)。
///
///
/// Prepares request message metadata (message ID, unique ID).
///
private static void PrepareRequestMessage(MessageObject message, int uniqueId)
{
MessageProtoHelper.SetMessageId(message);
message.SetUniqueId(uniqueId);
}
///
/// 关闭客户端:对全部连接快速失败挂起请求、失效传输层,并在超时内等待接收泵退出。
/// 幂等(首次调用生效,后续调用直接返回)。
///
///
/// Closes the client: fails all pending requests fast across every connection, invalidates the
/// transport layer, and awaits receive pump exit within a timeout. Idempotent (the first call
/// wins; subsequent calls return immediately).
///
public async Task CloseAsync()
{
if (Interlocked.Exchange(ref _closed, 1) != 0)
{
return;
}
var pumpTasks = new List();
foreach (var connection in _connections.Values)
{
connection.MarkDead();
// FailAllPending 与泵 finally 的调用可重入(TryRemove 语义):等待方立即收到可重试的连接级错误
connection.FailAllPending(new IOException(LocalizationService.GetString(Localization.Keys.RemoteMessaging.ClientModule.ConnectionClosed)));
pumpTasks.Add(connection.ReceivePumpTask);
}
_connections.Clear();
_transportProtocolAdapter.Invalidate();
// 等泵退出(泵 finally 会做同样的失效与快速失败,超时吞掉不阻塞关闭方)
var allPumps = Task.WhenAll(pumpTasks);
var timeout = Task.Delay(500);
var completed = await Task.WhenAny(allPumps, timeout).ConfigureAwait(false);
if (completed == allPumps)
{
// 泵任务可能 faulted(未分类异常):在此观察一次,避免本次等待本身引入未观察异常
try
{
await allPumps.ConfigureAwait(false);
}
catch (Exception)
{
// 已由 OnlyOnFaulted continuation 记录,此处仅观察
}
}
}
///
/// 同步关闭客户端(委托 ,最多等待 500ms,超时不再阻塞调用方)。
///
///
/// Synchronously closes the client (delegates to with a 500 ms cap;
/// a timeout no longer blocks the caller).
///
public void Dispose()
{
try
{
CloseAsync().Wait(500);
}
catch (Exception)
{
// 关闭路径异常不向 Dispose 调用方抛出(挂起请求已快速失败,残余连接由泵 finally 收口)
}
}
}