feat: declare every protocol method's direction and enforce it in the router; add the zero-trust design [CI]

Methods, roles and binary channels are declared in one table per plane (node and peer). RpcRouter checks direction, kind and role when handlers are registered, when messages arrive (fleet_protocol_violation, disconnect after repeated violations) and before sending. NodeConnection is split by responsibility.
2026-10-07 16:17:02 +08:00
1 parent ee22309e65
commit 1ff847e45a
@@ -13,6 +13,8 @@ public static class FleetErrors
    public static readonly ErrorCode Unauthorized = new("fleet_unauthorized");
    public static readonly ErrorCode Forbidden = new("fleet_forbidden");
    public static readonly ErrorCode Unsupported = new("fleet_unsupported");
+    /// <summary>方法没有声明、方向不对、类型不对或角色不允许：对方违反了协议。</summary>
+    public static readonly ErrorCode ProtocolViolation = new("fleet_protocol_violation");
    public static readonly ErrorCode InvalidParams = new("fleet_invalid_params");
    public static readonly ErrorCode NotFound = new("fleet_not_found");
    public static readonly ErrorCode Internal = new("fleet_internal");
@@ -105,6 +105,9 @@ public sealed class FleetLink

    public RpcSession<LinkContext>? CurrentSession => _session;

+    /// <summary>入站方法的路由器（只读，测试用它核对声明表和实际注册的处理函数）。</summary>
+    public RpcRouter<LinkContext> Router => _router;
+
    /// <summary>被服务端撤销或禁用：不会再重连。</summary>
    public bool Revoked => _stopped;

@@ -15,6 +15,31 @@ public static class FleetMethods
    public const string Revoked = "fleet.revoked";
 }

+/// <summary>
+/// 框架自己的方法声明，两个平面各一份。认证和握手阶段由连接代码直接处理的（<c>Inline</c>）不经过路由器。
+/// 同一个方法名在两个平面里可以有不同的发起方：<c>fleet.state.sync</c> 在节点面是服务端发给节点，在对等面是 Agent 发给 Probe。
+/// </summary>
+public static class FleetMethodTable
+{
+    public static readonly MethodTable Table = new(
+    [
+        // 节点面
+        MethodSpec.Notification(FleetMethods.Challenge, RpcSide.Server).AsInline(),
+        MethodSpec.Request(FleetMethods.Auth, RpcSide.Node).AsInline(),
+        MethodSpec.Request(FleetMethods.Hello, RpcSide.Node).AsInline(),
+        MethodSpec.Notification(FleetMethods.Heartbeat, RpcSide.Node).AsInline(),
+        MethodSpec.Request(FleetMethods.StateSync, RpcSide.Server),
+        MethodSpec.Notification(FleetMethods.OutboxAck, RpcSide.Server),
+        MethodSpec.Notification(FleetMethods.Revoked, RpcSide.Server),
+
+        // 对等面
+        MethodSpec.Notification(PeerMethods.Challenge, RpcSide.Listener).AsInline(),
+        MethodSpec.Request(PeerMethods.Auth, RpcSide.Dialer).AsInline(),
+        MethodSpec.Request(FleetMethods.StateSync, RpcSide.Listener),
+        MethodSpec.Notification(FleetMethods.OutboxAck, RpcSide.Listener),
+    ]);
+}
+
 /// <summary>二进制通道：0–15 保留给框架，产品从 16 开始。</summary>
 public static class FleetChannels
 {
@@ -0,0 +1,120 @@
+namespace Fleet.Rpc;
+
+/// <summary>连接的哪一侧。节点面：服务端和节点；对等面：拨号方（Probe）和监听方（Agent）。</summary>
+public enum RpcSide
+{
+    Server,
+    Node,
+    Dialer,
+    Listener,
+}
+
+public enum RpcPlane
+{
+    Node,
+    Peer,
+}
+
+public enum MethodKind
+{
+    Request,
+    Notification,
+}
+
+public static class RpcSides
+{
+    public static RpcPlane PlaneOf(RpcSide side) => side is RpcSide.Server or RpcSide.Node ? RpcPlane.Node : RpcPlane.Peer;
+
+    public static RpcSide Opposite(RpcSide side) => side switch
+    {
+        RpcSide.Server => RpcSide.Node,
+        RpcSide.Node => RpcSide.Server,
+        RpcSide.Dialer => RpcSide.Listener,
+        _ => RpcSide.Dialer,
+    };
+}
+
+/// <summary>
+/// 一个方法的声明：<b>只有 <see cref="From"/> 能发起它</b>（不存在双向方法），类型是请求还是通知，哪些节点角色可以参与。
+/// <see cref="Inline"/> 表示它在认证或握手阶段由连接代码直接处理，不经过路由器。
+/// </summary>
+public sealed record MethodSpec(string Name, RpcSide From, MethodKind Kind, IReadOnlyList<string>? Roles = null, bool Inline = false)
+{
+    public RpcPlane Plane => RpcSides.PlaneOf(From);
+
+    /// <summary>接收方。</summary>
+    public RpcSide To => RpcSides.Opposite(From);
+
+    public bool AllowsRole(string? role) => Roles is null || (role is not null && Roles.Contains(role));
+
+    public static MethodSpec Request(string name, RpcSide from, params string[] roles) => new(name, from, MethodKind.Request, roles.Length == 0 ? null : roles);
+
+    public static MethodSpec Notification(string name, RpcSide from, params string[] roles) => new(name, from, MethodKind.Notification, roles.Length == 0 ? null : roles);
+
+    public MethodSpec AsInline() => this with { Inline = true };
+}
+
+/// <summary>二进制通道的声明：谁能发、哪些角色可以发。通道 0–15 保留给框架，产品从 16 开始。</summary>
+public sealed record ChannelSpec(byte Channel, RpcSide From, IReadOnlyList<string>? Roles = null)
+{
+    public RpcPlane Plane => RpcSides.PlaneOf(From);
+
+    public bool AllowsRole(string? role) => Roles is null || (role is not null && Roles.Contains(role));
+}
+
+/// <summary>
+/// 协议方法和二进制通道的声明表，单一真源。路由器用它在注册时拒绝方向、类型、角色不符的处理函数，
+/// 在收发时拒绝没有声明或不该由对方发起的方法。同一个方法名在不同平面里可以有不同的发起方，所以按（平面，名字）查找。
+/// </summary>
+public sealed class MethodTable
+{
+    private readonly Dictionary<(RpcPlane, string), MethodSpec> _methods = [];
+    private readonly Dictionary<(RpcPlane, byte), ChannelSpec> _channels = [];
+
+    public MethodTable(IEnumerable<MethodSpec> methods, IEnumerable<ChannelSpec>? channels = null)
+    {
+        foreach (MethodSpec spec in methods)
+        {
+            if (!_methods.TryAdd((spec.Plane, spec.Name), spec))
+            {
+                throw new ArgumentException($"method {spec.Name} is declared twice in the {spec.Plane} plane");
+            }
+        }
+
+        foreach (ChannelSpec spec in channels ?? [])
+        {
+            if (!_channels.TryAdd((spec.Plane, spec.Channel), spec))
+            {
+                throw new ArgumentException($"channel {spec.Channel} is declared twice in the {spec.Plane} plane");
+            }
+        }
+    }
+
+    public IEnumerable<MethodSpec> Methods => _methods.Values;
+
+    public IEnumerable<ChannelSpec> Channels => _channels.Values;
+
+    public MethodSpec? Find(RpcPlane plane, string method) => _methods.GetValueOrDefault((plane, method));
+
+    public ChannelSpec? FindChannel(RpcPlane plane, byte channel) => _channels.GetValueOrDefault((plane, channel));
+
+    /// <summary>合并多张表（框架的加产品的）。</summary>
+    public static MethodTable Combine(params MethodTable[] tables) =>
+        new(tables.SelectMany(t => t.Methods), tables.SelectMany(t => t.Channels));
+
+    /// <summary>
+    /// 对账：<paramref name="receiver"/> 这一侧、<paramref name="role"/> 这个角色应该处理、但没有注册处理函数的方法
+    /// （认证阶段直接处理的 <see cref="MethodSpec.Inline"/> 方法除外）。<paramref name="role"/> 为空表示不限角色（服务端要处理所有角色发来的）。
+    /// </summary>
+    public IReadOnlyList<string> MissingHandlers(RpcSide receiver, string? role, IEnumerable<string> registered)
+    {
+        HashSet<string> have = [.. registered];
+        return
+        [
+            .. Methods
+                .Where(m => m.To == receiver && !m.Inline && (role is null || m.AllowsRole(role)) && !have.Contains(m.Name))
+                .Select(m => m.Name)
+                .Order(StringComparer.Ordinal),
+        ];
+    }
+}
@@ -4,7 +4,17 @@ using Fleet.Core;

 namespace Fleet.Rpc;

-/// <summary>方法路由，与传输方式无关。<typeparamref name="TContext"/> 由传输层提供（例如调用方节点）。</summary>
+/// <summary>对端违反了协议：方法没有声明、方向不对、请求和通知用反了、或者角色不允许。</summary>
+public readonly record struct RpcViolation(string Method, string Reason);
+
+/// <summary>一次分发的结果：要回的响应（通知为空），以及对端有没有违规。</summary>
+public readonly record struct RpcDispatch(RpcMessage? Response, RpcViolation? Violation);
+
+/// <summary>
+/// 方法路由，与传输方式无关，也是协议方向的<b>唯一卡口</b>：节点和服务端、Probe 和 Agent 的入站分发都经过这里。
+/// <typeparamref name="TContext"/> 由传输层提供（例如调用方节点）。路由器知道自己在连接的哪一侧（<see cref="Side"/>）和声明表，
+/// 注册处理函数时核对方向、类型和角色，分发时拒绝没有声明或不该由对方发起的方法，发送时核对自己有没有资格发起。
+/// </summary>
 public sealed class RpcRouter<TContext>
 {
    private delegate ValueTask<Result<JsonElement?>> Route(TContext context, JsonElement? parameters, CancellationToken ct);
@@ -13,12 +23,28 @@ public sealed class RpcRouter<TContext>

    private readonly Dictionary<string, Route> _routes = new(StringComparer.Ordinal);
    private readonly Action<string, Exception>? _onUnhandled;
+    private readonly string? _localRole;
+    private readonly Func<TContext, string?>? _callerRole;

-    public RpcRouter(Action<string, Exception>? onUnhandled = null)
+    /// <param name="side">本路由器在连接的哪一侧。</param>
+    /// <param name="table">方法声明表。</param>
+    /// <param name="localRole">本节点的角色（节点侧和对等面用）：声明限定了角色的方法，角色不符就不能注册。</param>
+    /// <param name="callerRole">从调用上下文取出对端的角色（服务端用）：声明限定了角色的方法，角色不符就拒绝。</param>
+    public RpcRouter(RpcSide side, MethodTable table, string? localRole = null, Func<TContext, string?>? callerRole = null, Action<string, Exception>? onUnhandled = null)
    {
+        Side = side;
+        Table = table;
+        _localRole = localRole;
+        _callerRole = callerRole;
        _onUnhandled = onUnhandled;
    }

+    public RpcSide Side { get; }
+
+    public MethodTable Table { get; }
+
+    private RpcPlane Plane => RpcSides.PlaneOf(Side);
+
    public bool Has(string method) => _routes.ContainsKey(method);

    public IReadOnlyCollection<string> Methods => _routes.Keys;
@@ -29,6 +55,7 @@ public sealed class RpcRouter<TContext>
        JsonTypeInfo<TResult> resultInfo,
        Func<TContext, TParams, CancellationToken, ValueTask<Result<TResult>>> handler)
    {
+        Declare(method, MethodKind.Request);
        _routes[method] = async (context, raw, ct) =>
        {
            if (!TryDeserialize(raw, paramsInfo, out TParams? p))
@@ -49,6 +76,7 @@ public sealed class RpcRouter<TContext>
        JsonTypeInfo<TParams> paramsInfo,
        Func<TContext, TParams, CancellationToken, ValueTask> handler)
    {
+        Declare(method, MethodKind.Notification);
        _routes[method] = async (context, raw, ct) =>
        {
            if (!TryDeserialize(raw, paramsInfo, out TParams? p))
@@ -66,12 +94,26 @@ public sealed class RpcRouter<TContext>
    /// 处理一条请求或通知。请求返回响应；通知返回 null（失败时只丢弃）。
    /// 处理函数里的异常属于程序缺陷：在这个边界捕获，回复 internal 错误，并交给 <c>onUnhandled</c> 记录。
    /// </summary>
-    public async ValueTask<RpcMessage?> DispatchAsync(TContext context, RpcMessage message, CancellationToken ct)
+    public async ValueTask<RpcMessage?> DispatchAsync(TContext context, RpcMessage message, CancellationToken ct) =>
+        (await DispatchCheckedAsync(context, message, ct)).Response;
+
+    /// <summary>
+    /// 先核对声明（方向、类型、角色），再分发。违规的消息不会到达处理函数，返回的结果里带 <see cref="RpcViolation"/>，
+    /// 由会话决定怎么办（计数、超过上限就断开连接）。声明过、方向对、但这一侧没有处理函数的方法不算违规，只是不支持。
+    /// </summary>
+    public async ValueTask<RpcDispatch> DispatchCheckedAsync(TContext context, RpcMessage message, CancellationToken ct)
    {
        string method = message.Method ?? "";
+        if (Check(context, message) is { } violation)
+        {
+            return new RpcDispatch(
+                message.Id is null ? null : RpcMessage.Failure(message.Id, new FleetError(FleetErrors.ProtocolViolation, violation.Reason)),
+                violation);
+        }
+
        if (!_routes.TryGetValue(method, out Route? route))
        {
-            return message.Id is null ? null : RpcMessage.Failure(message.Id, new FleetError(FleetErrors.Unsupported, $"unknown method {method}"));
+            return new RpcDispatch(message.Id is null ? null : RpcMessage.Failure(message.Id, new FleetError(FleetErrors.Unsupported, $"unknown method {method}")), null);
        }

        Result<JsonElement?> result;
@@ -91,12 +133,90 @@ public sealed class RpcRouter<TContext>

        if (message.Id is null)
        {
-            return null;
+            return new RpcDispatch(null, null);
        }

-        return result.TryGet(out JsonElement? value, out FleetError? error)
-            ? new RpcMessage { Id = message.Id, Result = value ?? s_emptyObject }
-            : RpcMessage.Failure(message.Id, error);
+        return new RpcDispatch(
+            result.TryGet(out JsonElement? value, out FleetError? error)
+                ? new RpcMessage { Id = message.Id, Result = value ?? s_emptyObject }
+                : RpcMessage.Failure(message.Id, error),
+            null);
+    }
+
+    /// <summary>入站检查：这条消息是不是对方有资格发起的、类型对不对、对方的角色允不允许。</summary>
+    public RpcViolation? Check(TContext context, RpcMessage message)
+    {
+        string method = message.Method ?? "";
+        MethodSpec? spec = Table.Find(Plane, method);
+        if (spec is null)
+        {
+            return new RpcViolation(method, $"method {method} is not declared");
+        }
+
+        if (spec.To != Side)
+        {
+            return new RpcViolation(method, $"{method} cannot be initiated by the {RpcSides.Opposite(Side)} side");
+        }
+
+        MethodKind kind = message.Id is null ? MethodKind.Notification : MethodKind.Request;
+        if (spec.Kind != kind)
+        {
+            return new RpcViolation(method, $"{method} is a {spec.Kind.ToString().ToLowerInvariant()}");
+        }
+
+        if (_callerRole is not null && !spec.AllowsRole(_callerRole(context)))
+        {
+            return new RpcViolation(method, $"{method} is not allowed for this node role");
+        }
+
+        return null;
+    }
+
+    /// <summary>
+    /// 发送前检查：本侧有没有资格发起这个方法、类型对不对、对端的角色允不允许（服务端发给节点时传入节点的角色）。
+    /// 违反是程序缺陷，抛 <see cref="InvalidOperationException"/>。
+    /// </summary>
+    public void CheckSend(string method, MethodKind kind, string? peerRole = null)
+    {
+        MethodSpec? spec = Table.Find(Plane, method);
+        if (spec is null)
+        {
+            throw new InvalidOperationException($"method {method} is not declared");
+        }
+
+        if (spec.From != Side)
+        {
+            throw new InvalidOperationException($"{method} cannot be initiated by the {Side} side");
+        }
+
+        if (spec.Kind != kind)
+        {
+            throw new InvalidOperationException($"{method} is a {spec.Kind.ToString().ToLowerInvariant()}");
+        }
+
+        if (peerRole is not null && !spec.AllowsRole(peerRole))
+        {
+            throw new InvalidOperationException($"{method} cannot be sent to a {peerRole}");
+        }
+    }
+
+    private void Declare(string method, MethodKind kind)
+    {
+        MethodSpec spec = Table.Find(Plane, method) ?? throw new InvalidOperationException($"method {method} is not declared in the method table");
+        if (spec.To != Side)
+        {
+            throw new InvalidOperationException($"{method} is initiated by the {spec.From} side and cannot be handled on the {Side} side");
+        }
+
+        if (spec.Kind != kind)
+        {
+            throw new InvalidOperationException($"{method} is declared as a {spec.Kind.ToString().ToLowerInvariant()}");
+        }
+
+        if (_localRole is not null && !spec.AllowsRole(_localRole))
+        {
+            throw new InvalidOperationException($"{method} is not for the {_localRole} role");
+        }
    }

    private static bool TryDeserialize<T>(JsonElement? raw, JsonTypeInfo<T> info, [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] out T? value)
@@ -34,6 +34,9 @@ public sealed class RpcSessionOptions

    /// <summary>待处理的入站请求上限；超过时接收循环等待（背压）。</summary>
    public int InboundQueue { get; set; } = 256;
+
+    /// <summary>对端违反协议（方法没有声明、方向、类型或角色不对）的次数上限；超过就断开会话。</summary>
+    public int MaxViolations { get; set; } = 20;
 }

 /// <summary>
@@ -53,6 +56,8 @@ public sealed class RpcSession<TContext> : IAsyncDisposable
    private readonly CancellationTokenSource _stop = new();
    private long _nextId;
    private long _lastReceive;
+    private int _violations;
+    private bool _violated;

    public RpcSession(IRpcTransport transport, RpcRouter<TContext> router, TContext context, TimeProvider time, RpcSessionOptions? options = null)
    {
@@ -81,7 +86,7 @@ public sealed class RpcSession<TContext> : IAsyncDisposable
            while (!linked.IsCancellationRequested)
            {
                RpcFrame? frame = await _transport.ReceiveAsync(linked.Token);
-                if (frame is null)
+                if (frame is null || Volatile.Read(ref _violated))
                {
                    return;
                }
@@ -184,8 +189,16 @@ public sealed class RpcSession<TContext> : IAsyncDisposable
    public ValueTask NotifyAsync<TParams>(string method, TParams parameters, JsonTypeInfo<TParams> paramsInfo, CancellationToken ct) =>
        SendAsync(RpcMessage.Notification(method, parameters, paramsInfo), ct);

-    public ValueTask SendAsync(RpcMessage message, CancellationToken ct) =>
-        _transport.SendAsync(new RpcFrame(FrameKind.Text, JsonSerializer.SerializeToUtf8Bytes(message, FleetRpcContext.Default.RpcMessage)), ct);
+    public ValueTask SendAsync(RpcMessage message, CancellationToken ct)
+    {
+        if (message.Method is not null)
+        {
+            // 请求和通知只能发本侧有资格发起的方法（响应没有方法名，不检查）
+            _router.CheckSend(message.Method, message.Id is null ? MethodKind.Notification : MethodKind.Request);
+        }
+
+        return _transport.SendAsync(new RpcFrame(FrameKind.Text, JsonSerializer.SerializeToUtf8Bytes(message, FleetRpcContext.Default.RpcMessage)), ct);
+    }

    public ValueTask SendBinaryAsync(ReadOnlyMemory<byte> frame, CancellationToken ct) =>
        _transport.SendAsync(new RpcFrame(FrameKind.Binary, frame), ct);
@@ -205,10 +218,18 @@ public sealed class RpcSession<TContext> : IAsyncDisposable
        {
            await foreach (RpcMessage message in _inbound.Reader.ReadAllAsync(ct))
            {
-                RpcMessage? response = await _router.DispatchAsync(_context, message, ct);
-                if (response is not null)
+                RpcDispatch outcome = await _router.DispatchCheckedAsync(_context, message, ct);
+                if (outcome.Response is not null)
                {
-                    await SendAsync(response, ct);
+                    await SendAsync(outcome.Response, ct);
+                }
+
+                if (outcome.Violation is not null && ++_violations > _options.MaxViolations)
+                {
+                    // 只关闭传输，不取消接收：接收循环在下一次读到帧或对端确认关闭时正常结束
+                    Volatile.Write(ref _violated, true);
+                    await _transport.CloseAsync("protocol violations", CancellationToken.None);
+                    return;
                }
            }
        }
@@ -12,4 +12,7 @@ public sealed class FleetServerOptions
    public TimeSpan HeartbeatTimeout { get; set; } = TimeSpan.FromSeconds(45);

    public TimeSpan RequestTimeout { get; set; } = TimeSpan.FromSeconds(15);
+
+    /// <summary>节点违反协议（方法没有声明、方向、类型或角色不对）的次数上限；超过就断开这条连接。</summary>
+    public int MaxViolations { get; set; } = 20;
 }
@@ -33,6 +33,7 @@ public sealed class FleetLinkHost : IFleetConnections, IStateNotifier
        Inboxes = inboxes.ToDictionary(i => i.Channel);
        Sinks = [.. sinks];
        Router = router.Inner;
+        RoleOf = router.RoleOf;
    }

    internal IFleetStore Store { get; }
@@ -51,6 +52,8 @@ public sealed class FleetLinkHost : IFleetConnections, IStateNotifier

    internal RpcRouter<NodeCallContext> Router { get; }

+    internal Func<NodeRecord, string?>? RoleOf { get; }
+
    public IReadOnlyCollection<NodeId> OnlineNodes => [.. _connections.Keys];

    public bool IsOnline(NodeId node) => _connections.ContainsKey(node);
@@ -161,10 +164,18 @@ public sealed class FleetLinkHost : IFleetConnections, IStateNotifier
 /// <summary>产品注册的 RPC 方法路由。</summary>
 public sealed class FleetRouter
 {
-    public FleetRouter(RpcRouter<NodeCallContext> inner)
+    public FleetRouter(RpcRouter<NodeCallContext> inner, Func<NodeRecord, string?>? roleOf)
    {
        Inner = inner;
+        RoleOf = roleOf;
    }

    internal RpcRouter<NodeCallContext> Inner { get; }
+
+    internal Func<NodeRecord, string?>? RoleOf { get; }
+
+    /// <summary>已注册的入站方法名（只读，测试用它核对声明表）。</summary>
+    public IReadOnlyCollection<string> Methods => Inner.Methods;
+
+    public MethodTable Table => Inner.Table;
 }
@@ -19,6 +19,9 @@ internal static partial class FleetLog
    [LoggerMessage(Level = LogLevel.Warning, Message = "state push failed node={Node} type={Type} err={Err}")]
    public static partial void StatePushFailed(ILogger logger, string node, string type, string err);

+    [LoggerMessage(Level = LogLevel.Warning, Message = "protocol violation node={Node} method={Method} reason={Reason}")]
+    public static partial void ProtocolViolation(ILogger logger, string node, string method, string reason);
+
    [LoggerMessage(Level = LogLevel.Error, Message = "unhandled error in handler method={Method}")]
    public static partial void HandlerFailed(ILogger logger, Exception exception, string method);

@@ -12,6 +12,8 @@ namespace Fleet.Server;
 public sealed class FleetServerBuilder
 {
    private readonly List<Action<RpcRouter<NodeCallContext>, IServiceProvider>> _routeConfigurators = [];
+    private MethodTable? _methods;
+    private Func<NodeRecord, string?>? _roleOf;

    internal FleetServerBuilder(IServiceCollection services)
    {
@@ -22,6 +24,21 @@ public sealed class FleetServerBuilder

    internal IReadOnlyList<Action<RpcRouter<NodeCallContext>, IServiceProvider>> RouteConfigurators => _routeConfigurators;

+    internal MethodTable Methods => _methods ?? throw new InvalidOperationException("call WithMethods(...) when adding the Fleet server: the method table is required");
+
+    internal Func<NodeRecord, string?>? RoleOf => _roleOf;
+
+    /// <summary>
+    /// 方法声明表（框架的加产品的，见 <see cref="MethodTable.Combine"/>）和节点的角色解析（例如按节点 ID 前缀区分 Agent 和 Probe）。必须设置：
+    /// 路由器据此核对每个处理函数的方向、类型和角色，并拒绝没有声明或不该由节点发起的方法。
+    /// </summary>
+    public FleetServerBuilder WithMethods(MethodTable methods, Func<NodeRecord, string?> roleOf)
+    {
+        _methods = methods;
+        _roleOf = roleOf;
+        return this;
+    }
+
    public FleetServerBuilder AddState<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] TProvider>()
        where TProvider : class, IStateProvider
    {
@@ -71,13 +88,18 @@ public static class FleetServerExtensions
        services.AddSingleton(provider =>
        {
            ILogger logger = provider.GetRequiredService<ILoggerFactory>().CreateLogger("Fleet.Rpc");
-            var router = new RpcRouter<NodeCallContext>((method, ex) => FleetLog.HandlerFailed(logger, ex, method));
+            Func<NodeRecord, string?>? roleOf = builder.RoleOf;
+            var router = new RpcRouter<NodeCallContext>(
+                RpcSide.Server,
+                builder.Methods,
+                callerRole: roleOf is null ? null : context => roleOf(context.Node),
+                onUnhandled: (method, ex) => FleetLog.HandlerFailed(logger, ex, method));
            foreach (Action<RpcRouter<NodeCallContext>, IServiceProvider> configurator in builder.RouteConfigurators)
            {
                configurator(router, provider);
            }

-            return new FleetRouter(router);
+            return new FleetRouter(router, roleOf);
        });
        services.AddSingleton(provider => new FleetLinkHost(
            provider.GetRequiredService<IFleetStore>(),
@@ -0,0 +1,98 @@
+using System.Net.WebSockets;
+using System.Security.Cryptography;
+using System.Text.Json;
+using Fleet.Core;
+using Fleet.Identity;
+using Fleet.Rpc;
+
+namespace Fleet.Server;
+
+/// <summary>认证：挑战、签名校验、拒绝。</summary>
+internal sealed partial class NodeConnection
+{
+    private async Task<bool> AuthenticateAsync(CancellationToken ct)
+    {
+        string nonce = Convert.ToBase64String(RandomNumberGenerator.GetBytes(32));
+        long expiresAtMs = _host.Time.GetUtcNow().Add(_host.Options.ChallengeTtl).ToUnixTimeMilliseconds();
+        await SendAsync(
+            RpcMessage.Notification(FleetMethods.Challenge, new ChallengeParams { Nonce = nonce, ExpiresAtMs = expiresAtMs }, FleetRpcContext.Default.ChallengeParams),
+            ct);
+
+        using var timeout = new CancellationTokenSource(s_authTimeout, _host.Time);
+        using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource(ct, timeout.Token);
+        Frame? frame;
+        try
+        {
+            frame = await ReceiveFrameAsync(linked.Token);
+        }
+        catch (OperationCanceledException) when (!ct.IsCancellationRequested)
+        {
+            await RejectAsync(null, "auth timeout", ct);
+            return false;
+        }
+
+        if (frame is not { IsText: true } || !TryParse(frame.Data, out RpcMessage? message) || message.Method != FleetMethods.Auth || message.Id is null)
+        {
+            await RejectAsync(null, "expected fleet.auth", ct);
+            return false;
+        }
+
+        AuthParams? auth = null;
+        try
+        {
+            auth = message.Params?.Deserialize(FleetRpcContext.Default.AuthParams);
+        }
+        catch (JsonException)
+        {
+            // 按缺失处理
+        }
+
+        NodeRecord? node = auth is null ? null : await _host.Store.GetNodeAsync(new NodeId(auth.NodeId), ct);
+        bool signatureOk = node is not null
+            && _host.Time.GetUtcNow().ToUnixTimeMilliseconds() <= expiresAtMs
+            && TryDecode(auth!.Signature, out byte[] signature)
+            && NodeIdentity.Verify(node.PublicKey, signature, SignaturePurpose.Auth, auth.NodeId, nonce);
+        if (!signatureOk)
+        {
+            // 节点不存在与签名错误返回同样的错误，不泄露节点是否存在。
+            await RejectAsync(message.Id, "authentication failed", ct);
+            return false;
+        }
+
+        _node = node;
+        if (node!.Status == NodeStatus.Disabled)
+        {
+            await SendAsync(RpcMessage.Failure(message.Id, new FleetError(FleetErrors.NodeDisabled, "node is disabled")), ct);
+            await RevokeAsync("disabled", ct);
+            return false;
+        }
+
+        _session = new NodeSessionInfo(node.Id, _host.Time.GetUtcNow().ToUnixTimeMilliseconds(), node.NodeVersion, [], null);
+        await SendAsync(
+            RpcMessage.Success(message.Id.Value, new AuthResult { Status = StatusName(node.Status) }, FleetRpcContext.Default.AuthResult),
+            ct);
+        return true;
+    }
+
+    private async Task RejectAsync(long? id, string reason, CancellationToken ct)
+    {
+        FleetLog.AuthRejected(_host.Logger, reason);
+        _closeReason ??= reason;
+        if (id is not null)
+        {
+            await SendAsync(RpcMessage.Failure(id, new FleetError(FleetErrors.Unauthorized, "authentication failed")), ct);
+        }
+
+        if (_socket.State == WebSocketState.Open)
+        {
+            try
+            {
+                await _socket.CloseOutputAsync(WebSocketCloseStatus.PolicyViolation, "unauthorized", ct);
+            }
+            catch (WebSocketException)
+            {
+                // 对端已经断开
+            }
+        }
+    }
+}
@@ -0,0 +1,240 @@
+using System.Text.Json;
+using Fleet.Core;
+using Fleet.Rpc;
+
+namespace Fleet.Server;
+
+/// <summary>接收：读帧、分发消息、hello、心跳、二进制通道（收件箱）。</summary>
+internal sealed partial class NodeConnection
+{
+    private async Task ReceiveLoopAsync(CancellationToken ct)
+    {
+        while (!ct.IsCancellationRequested)
+        {
+            using var idle = new CancellationTokenSource(_host.Options.HeartbeatTimeout, _host.Time);
+            using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource(ct, idle.Token);
+            Frame? frame;
+            try
+            {
+                frame = await ReceiveFrameAsync(linked.Token);
+            }
+            catch (OperationCanceledException) when (idle.IsCancellationRequested && !ct.IsCancellationRequested)
+            {
+                _closeReason ??= "heartbeat timeout";
+                return;
+            }
+
+            if (frame is null)
+            {
+                _closeReason ??= "closed by peer";
+                return;
+            }
+
+            if (frame.IsText)
+            {
+                if (TryParse(frame.Data, out RpcMessage? message))
+                {
+                    await HandleMessageAsync(message, ct);
+                }
+            }
+            else
+            {
+                await HandleBinaryAsync(frame.Data, ct);
+            }
+        }
+    }
+
+    private async Task HandleMessageAsync(RpcMessage message, CancellationToken ct)
+    {
+        if (message.IsResponse)
+        {
+            if (_pending.TryGetValue(message.Id!.Value, out TaskCompletionSource<RpcMessage>? waiter))
+            {
+                waiter.TrySetResult(message);
+            }
+
+            return;
+        }
+
+        switch (message.Method)
+        {
+            case FleetMethods.Hello:
+                await HandleHelloAsync(message, ct);
+                return;
+            case FleetMethods.Heartbeat:
+                await HandleHeartbeatAsync(message, ct);
+                return;
+        }
+
+        if (_node!.Status != NodeStatus.Active)
+        {
+            if (message.Id is not null)
+            {
+                await SendAsync(RpcMessage.Failure(message.Id, new FleetError(FleetErrors.NodePending, "node is not approved yet")), ct);
+            }
+
+            return;
+        }
+
+        var context = new NodeCallContext(_node, _session!, _host);
+        RpcDispatch outcome;
+        try
+        {
+            outcome = await _host.Router.DispatchCheckedAsync(context, message, ct);
+        }
+        catch (OperationCanceledException) when (ct.IsCancellationRequested)
+        {
+            throw;
+        }
+
+        if (outcome.Response is not null)
+        {
+            await SendAsync(outcome.Response, ct);
+        }
+
+        await NoteViolationAsync(outcome.Violation);
+    }
+
+    /// <summary>记录节点的违规；超过上限就断开这条连接。</summary>
+    private async Task NoteViolationAsync(RpcViolation? violation)
+    {
+        if (violation is not { } v)
+        {
+            return;
+        }
+
+        FleetLog.ProtocolViolation(_host.Logger, _node!.Id.Value, v.Method, v.Reason);
+        if (++_violations > _host.Options.MaxViolations)
+        {
+            await CloseAsync("protocol violations");
+        }
+    }
+
+    private async Task HandleHelloAsync(RpcMessage message, CancellationToken ct)
+    {
+        HelloParams? hello = null;
+        try
+        {
+            hello = message.Params?.Deserialize(FleetRpcContext.Default.HelloParams);
+        }
+        catch (JsonException)
+        {
+            // 按缺失处理
+        }
+
+        if (hello is null)
+        {
+            if (message.Id is not null)
+            {
+                await SendAsync(RpcMessage.Failure(message.Id, new FleetError(FleetErrors.InvalidParams, "invalid hello")), ct);
+            }
+
+            return;
+        }
+
+        long nowMs = _host.Time.GetUtcNow().ToUnixTimeMilliseconds();
+        _session = _session! with
+        {
+            NodeVersion = hello.NodeVersion,
+            Capabilities = hello.Capabilities,
+            HelloMetaJson = hello.Meta?.GetRawText(),
+        };
+        _node = _node! with { NodeVersion = hello.NodeVersion };
+        _helloDone = true;
+
+        await UpdatePresenceAsync(online: true, ct);
+        await FireAsync(NodeEventKind.Hello, ct, hello);
+
+        if (message.Id is not null)
+        {
+            await SendAsync(
+                RpcMessage.Success(
+                    message.Id.Value,
+                    new HelloResult { ServerTimeMs = nowMs, ClockOffsetMs = hello.NowUtcMs - nowMs },
+                    FleetRpcContext.Default.HelloResult),
+                ct);
+        }
+
+        SignalStateChanged();
+    }
+
+    private async Task HandleHeartbeatAsync(RpcMessage message, CancellationToken ct)
+    {
+        JsonElement? extra = null;
+        try
+        {
+            extra = message.Params?.Deserialize(FleetRpcContext.Default.HeartbeatParams)?.Extra;
+        }
+        catch (JsonException)
+        {
+            // 忽略格式不正确的附加字段
+        }
+
+        long now = _host.Time.GetTimestamp();
+        if (_host.Time.GetElapsedTime(Interlocked.Read(ref _lastPresenceTicks), now) >= s_presenceRefresh)
+        {
+            await UpdatePresenceAsync(online: true, ct);
+        }
+
+        await FireAsync(NodeEventKind.Heartbeat, ct, hello: null, extra);
+        if (message.Id is not null)
+        {
+            await SendAsync(new RpcMessage { Id = message.Id, Result = JsonSerializer.SerializeToElement(new EmptyObject(), FleetEmptyObject.Info) }, ct);
+        }
+    }
+
+    private async Task HandleBinaryAsync(byte[] data, CancellationToken ct)
+    {
+        if (_node!.Status != NodeStatus.Active || !OutboxFrame.TryParse(data, out byte channel, out Guid msgId, out ReadOnlyMemory<byte> payload))
+        {
+            return;
+        }
+
+        // 通道也要声明：节点只能往声明过、并且允许它的角色使用的通道发
+        ChannelSpec? spec = _host.Router.Table.FindChannel(RpcPlane.Node, channel);
+        if (spec is null || spec.From != RpcSide.Node || !spec.AllowsRole(_host.RoleOf?.Invoke(_node)))
+        {
+            await NoteViolationAsync(new RpcViolation($"channel {channel}", $"channel {channel} is not declared for this node"));
+            return;
+        }
+
+        if (!_host.Inboxes.TryGetValue(channel, out IInbox? inbox))
+        {
+            return;
+        }
+
+        InboxOutcome outcome;
+        try
+        {
+            outcome = await inbox.HandleAsync(_node, msgId, payload, ct);
+        }
+        catch (OperationCanceledException) when (ct.IsCancellationRequested)
+        {
+            throw;
+        }
+        catch (Exception ex)
+        {
+            // 没有持久化就不确认，节点会重发。
+            FleetLog.InboxFailed(_host.Logger, ex, _node.Id.Value, channel);
+            return;
+        }
+
+        if (outcome == InboxOutcome.Rejected)
+        {
+            return;
+        }
+
+        var ack = new OutboxAckParams();
+        string id = msgId.ToString();
+        if (outcome == InboxOutcome.Duplicate)
+        {
+            ack.Duplicates.Add(id);
+        }
+        else
+        {
+            ack.Ids.Add(id);
+        }
+
+        await SendAsync(RpcMessage.Notification(FleetMethods.OutboxAck, ack, FleetRpcContext.Default.OutboxAckParams), ct);
+    }
+}
@@ -0,0 +1,120 @@
+using System.Net.WebSockets;
+using System.Text.Json;
+using Fleet.Core;
+using Fleet.Rpc;
+
+namespace Fleet.Server;
+
+/// <summary>发给节点：关闭、吊销、发送一条消息、发起请求并等响应。</summary>
+internal sealed partial class NodeConnection
+{
+    /// <summary>
+    /// 服务端发起的关闭：发送 Close 帧，等对端确认之后接收循环自然结束。
+    /// 注意不能直接取消接收的令牌——取消 <c>ReceiveAsync</c> 会中止整个 WebSocket，对端拿不到关闭原因；取消只作为超时兜底。
+    /// </summary>
+    public async ValueTask CloseAsync(string reason)
+    {
+        _closeReason ??= reason;
+        try
+        {
+            await _sendLock.WaitAsync(CancellationToken.None);
+        }
+        catch (ObjectDisposedException)
+        {
+            return;
+        }
+
+        try
+        {
+            if (_socket.State == WebSocketState.Open)
+            {
+                await _socket.CloseOutputAsync(WebSocketCloseStatus.NormalClosure, reason, CancellationToken.None);
+            }
+        }
+        catch (WebSocketException)
+        {
+            // 对端已经断开
+        }
+        finally
+        {
+            _sendLock.Release();
+        }
+
+        _lifetime.CancelAfter(s_closeTimeout);
+    }
+
+    public async ValueTask RevokeAsync(string reason, CancellationToken ct)
+    {
+        await SendAsync(RpcMessage.Notification(FleetMethods.Revoked, new RevokedParams { Reason = reason }, FleetRpcContext.Default.RevokedParams), ct);
+        await CloseAsync(reason);
+    }
+
+    public async ValueTask<bool> SendAsync(RpcMessage message, CancellationToken ct)
+    {
+        if (message.Method is not null)
+        {
+            // 服务端只能发自己有资格发起的方法，并且对端的角色要允许（响应没有方法名，不检查）
+            string? peerRole = _node is null ? null : _host.RoleOf?.Invoke(_node);
+            _host.Router.CheckSend(message.Method, message.Id is null ? MethodKind.Notification : MethodKind.Request, peerRole);
+        }
+
+        byte[] bytes = JsonSerializer.SerializeToUtf8Bytes(message, FleetRpcContext.Default.RpcMessage);
+        try
+        {
+            await _sendLock.WaitAsync(ct);
+        }
+        catch (ObjectDisposedException)
+        {
+            return false;
+        }
+
+        try
+        {
+            if (_socket.State != WebSocketState.Open)
+            {
+                return false;
+            }
+
+            await _socket.SendAsync(bytes, WebSocketMessageType.Text, endOfMessage: true, ct);
+            return true;
+        }
+        catch (WebSocketException)
+        {
+            return false;
+        }
+        finally
+        {
+            _sendLock.Release();
+        }
+    }
+
+    public async ValueTask<Result<JsonElement>> RequestAsync(string method, JsonElement parameters, CancellationToken ct)
+    {
+        long id = Interlocked.Increment(ref _nextRequestId);
+        var waiter = new TaskCompletionSource<RpcMessage>(TaskCreationOptions.RunContinuationsAsynchronously);
+        _pending[id] = waiter;
+        try
+        {
+            var request = new RpcMessage { Id = id, Method = method, Params = parameters };
+            if (!await SendAsync(request, ct))
+            {
+                return Result<JsonElement>.Fail(FleetErrors.NodeOffline, "node is not connected");
+            }
+
+            using var timeout = new CancellationTokenSource(_host.Options.RequestTimeout, _host.Time);
+            using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource(ct, timeout.Token);
+            RpcMessage response = await waiter.Task.WaitAsync(linked.Token);
+            return response.Error is not null
+                ? Result<JsonElement>.Fail(response.Error.ToFleetError())
+                : Result<JsonElement>.Ok(response.Result ?? default);
+        }
+        catch (OperationCanceledException) when (!ct.IsCancellationRequested)
+        {
+            return Result<JsonElement>.Fail(FleetErrors.Timeout, $"{method} timed out");
+        }
+        finally
+        {
+            _pending.TryRemove(id, out _);
+        }
+    }
+}
@@ -0,0 +1,123 @@
+using System.Text.Json;
+using Fleet.Core;
+using Fleet.Rpc;
+
+namespace Fleet.Server;
+
+/// <summary>状态：期望状态推送、在线状态、节点事件。</summary>
+internal sealed partial class NodeConnection
+{
+    public void SignalStateChanged() => _stateSignal.Writer.TryWrite(true);
+
+
+    private async Task StatePushLoopAsync(CancellationToken ct)
+    {
+        while (await _stateSignal.Reader.WaitToReadAsync(ct))
+        {
+            _stateSignal.Reader.TryRead(out _);
+            bool complete = await PushStateAsync(ct);
+            if (!complete)
+            {
+                await Task.Delay(s_statePushRetry, _host.Time, ct);
+                SignalStateChanged();
+            }
+        }
+    }
+
+    private async Task<bool> PushStateAsync(CancellationToken ct)
+    {
+        NodeRecord? fresh = await _host.Store.GetNodeAsync(_node!.Id, ct);
+        if (fresh is null)
+        {
+            return true;
+        }
+
+        _node = fresh with { NodeVersion = _node.NodeVersion ?? fresh.NodeVersion };
+        if (fresh.Status == NodeStatus.Disabled)
+        {
+            await RevokeAsync("disabled", ct);
+            return true;
+        }
+
+        if (fresh.Status != NodeStatus.Active || !_helloDone)
+        {
+            // pending 不下发状态；还没有 hello 的连接等 hello 之后再推送。
+            return true;
+        }
+
+        bool complete = true;
+        foreach (IStateProvider provider in _host.StateProviders)
+        {
+            StateDocument? document = await provider.GetAsync(_node, ct);
+            if (document is null || (_lastPushedVersion.TryGetValue(provider.Type, out long last) && last == document.Version))
+            {
+                continue;
+            }
+
+            Result<JsonElement> raw = await RequestAsync(
+                FleetMethods.StateSync,
+                JsonSerializer.SerializeToElement(
+                    new StateSyncParams { Type = provider.Type, Version = document.Version, Doc = document.Doc },
+                    FleetRpcContext.Default.StateSyncParams),
+                ct);
+            if (!raw.TryGet(out JsonElement value, out FleetError? error))
+            {
+                FleetLog.StatePushFailed(_host.Logger, _node.Id.Value, provider.Type, error.Code.Value);
+                complete = false;
+                continue;
+            }
+
+            StateSyncResult? result = null;
+            try
+            {
+                result = value.Deserialize(FleetRpcContext.Default.StateSyncResult);
+            }
+            catch (JsonException)
+            {
+                // 按缺失处理
+            }
+
+            if (result is null)
+            {
+                complete = false;
+                continue;
+            }
+
+            _lastPushedVersion[provider.Type] = document.Version;
+            await provider.OnAppliedAsync(_node, document.Version, result, ct);
+        }
+
+        return complete;
+    }
+
+
+    private async Task UpdatePresenceAsync(bool online, CancellationToken ct)
+    {
+        Interlocked.Exchange(ref _lastPresenceTicks, _host.Time.GetTimestamp());
+        await _host.Store.UpdatePresenceAsync(
+            _node!.Id,
+            new Presence(online, _host.Time.GetUtcNow().ToUnixTimeMilliseconds(), _session?.NodeVersion, _session?.Capabilities ?? [], _session?.HelloMetaJson),
+            ct);
+    }
+
+    private async Task FireAsync(NodeEventKind kind, CancellationToken ct, HelloParams? hello = null, JsonElement? extra = null)
+    {
+        var nodeEvent = new NodeEvent(kind, _node!, _host.Time.GetUtcNow().ToUnixTimeMilliseconds(), hello, extra);
+        foreach (INodeEventSink sink in _host.Sinks)
+        {
+            try
+            {
+                await sink.OnEventAsync(nodeEvent, ct);
+            }
+            catch (OperationCanceledException) when (ct.IsCancellationRequested)
+            {
+                throw;
+            }
+            catch (Exception ex)
+            {
+                // 产品的事件处理失败不能影响连接。
+                FleetLog.SinkFailed(_host.Logger, ex, kind.ToString(), _node!.Id.Value);
+            }
+        }
+    }
+}
@@ -0,0 +1,85 @@
+using System.Buffers;
+using System.Net.WebSockets;
+using System.Text.Json;
+using Fleet.Rpc;
+
+namespace Fleet.Server;
+
+/// <summary>线上的帧：WebSocket 收帧、解析、状态名。</summary>
+internal sealed partial class NodeConnection
+{
+    private async ValueTask<Frame?> ReceiveFrameAsync(CancellationToken ct)
+    {
+        var writer = new ArrayBufferWriter<byte>(1024);
+        while (true)
+        {
+            Memory<byte> buffer = writer.GetMemory(4096);
+            ValueWebSocketReceiveResult result = await _socket.ReceiveAsync(buffer, ct);
+            if (result.MessageType == WebSocketMessageType.Close)
+            {
+                return null;
+            }
+
+            writer.Advance(result.Count);
+            if (writer.WrittenCount > _host.Options.MaxFrameBytes)
+            {
+                _closeReason ??= "frame too large";
+                await _socket.CloseOutputAsync(WebSocketCloseStatus.MessageTooBig, "frame too large", CancellationToken.None);
+                return null;
+            }
+
+            if (result.EndOfMessage)
+            {
+                return new Frame(result.MessageType == WebSocketMessageType.Text, writer.WrittenSpan.ToArray());
+            }
+        }
+    }
+
+    private static bool TryParse(byte[] data, [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] out RpcMessage? message)
+    {
+        try
+        {
+            message = JsonSerializer.Deserialize(data, FleetRpcContext.Default.RpcMessage);
+            return message is not null;
+        }
+        catch (JsonException)
+        {
+            message = null;
+            return false;
+        }
+    }
+
+    private static bool TryDecode(string text, out byte[] data)
+    {
+        try
+        {
+            data = Convert.FromBase64String(text);
+            return true;
+        }
+        catch (FormatException)
+        {
+            data = [];
+            return false;
+        }
+    }
+
+    private static string StatusName(NodeStatus status) => status switch
+    {
+        NodeStatus.Active => "active",
+        NodeStatus.Pending => "pending",
+        _ => "disabled",
+    };
+
+    private sealed record Frame(bool IsText, byte[] Data);
+}
+
+
+[System.Text.Json.Serialization.JsonSerializable(typeof(EmptyObject))]
+internal sealed partial class FleetEmptyObjectContext : System.Text.Json.Serialization.JsonSerializerContext;
+
+internal sealed class EmptyObject;
+
+internal static class FleetEmptyObject
+{
+    public static System.Text.Json.Serialization.Metadata.JsonTypeInfo<EmptyObject> Info => FleetEmptyObjectContext.Default.EmptyObject;
+}
@@ -1,11 +1,7 @@
-using System.Buffers;
 using System.Collections.Concurrent;
 using System.Net.WebSockets;
-using System.Security.Cryptography;
 using System.Threading.Channels;
-using System.Text.Json;
 using Fleet.Core;
-using Fleet.Identity;
 using Fleet.Rpc;

 namespace Fleet.Server;
@@ -14,7 +10,7 @@ namespace Fleet.Server;
 /// 一个节点的 WebSocket 会话：挑战 → 签名认证 → hello → 状态推送 / 收件箱 / 产品 RPC。
 /// 收到的消息按顺序处理，所以产品的处理函数不能等待“向同一个节点发起的请求”，否则会死锁。
 /// </summary>
-internal sealed class NodeConnection : IDisposable
+internal sealed partial class NodeConnection : IDisposable
 {
    private static readonly TimeSpan s_authTimeout = TimeSpan.FromSeconds(15);
    private static readonly TimeSpan s_presenceRefresh = TimeSpan.FromSeconds(60);
@@ -34,6 +30,7 @@ internal sealed class NodeConnection : IDisposable
    private NodeSessionInfo? _session;
    private string? _closeReason;
    private bool _helloDone;
+    private int _violations;

    public NodeConnection(FleetLinkHost host, WebSocket socket)
    {
@@ -140,590 +137,4 @@ internal sealed class NodeConnection : IDisposable
        _lifetime.Dispose();
        _sendLock.Dispose();
    }
-
-    public void SignalStateChanged() => _stateSignal.Writer.TryWrite(true);
-
-    /// <summary>
-    /// 服务端发起的关闭：发送 Close 帧，等对端确认之后接收循环自然结束。
-    /// 注意不能直接取消接收的令牌——取消 <c>ReceiveAsync</c> 会中止整个 WebSocket，对端拿不到关闭原因；取消只作为超时兜底。
-    /// </summary>
-    public async ValueTask CloseAsync(string reason)
-    {
-        _closeReason ??= reason;
-        try
-        {
-            await _sendLock.WaitAsync(CancellationToken.None);
-        }
-        catch (ObjectDisposedException)
-        {
-            return;
-        }
-
-        try
-        {
-            if (_socket.State == WebSocketState.Open)
-            {
-                await _socket.CloseOutputAsync(WebSocketCloseStatus.NormalClosure, reason, CancellationToken.None);
-            }
-        }
-        catch (WebSocketException)
-        {
-            // 对端已经断开
-        }
-        finally
-        {
-            _sendLock.Release();
-        }
-
-        _lifetime.CancelAfter(s_closeTimeout);
-    }
-
-    public async ValueTask RevokeAsync(string reason, CancellationToken ct)
-    {
-        await SendAsync(RpcMessage.Notification(FleetMethods.Revoked, new RevokedParams { Reason = reason }, FleetRpcContext.Default.RevokedParams), ct);
-        await CloseAsync(reason);
-    }
-
-    public async ValueTask<bool> SendAsync(RpcMessage message, CancellationToken ct)
-    {
-        byte[] bytes = JsonSerializer.SerializeToUtf8Bytes(message, FleetRpcContext.Default.RpcMessage);
-        try
-        {
-            await _sendLock.WaitAsync(ct);
-        }
-        catch (ObjectDisposedException)
-        {
-            return false;
-        }
-
-        try
-        {
-            if (_socket.State != WebSocketState.Open)
-            {
-                return false;
-            }
-
-            await _socket.SendAsync(bytes, WebSocketMessageType.Text, endOfMessage: true, ct);
-            return true;
-        }
-        catch (WebSocketException)
-        {
-            return false;
-        }
-        finally
-        {
-            _sendLock.Release();
-        }
-    }
-
-    public async ValueTask<Result<JsonElement>> RequestAsync(string method, JsonElement parameters, CancellationToken ct)
-    {
-        long id = Interlocked.Increment(ref _nextRequestId);
-        var waiter = new TaskCompletionSource<RpcMessage>(TaskCreationOptions.RunContinuationsAsynchronously);
-        _pending[id] = waiter;
-        try
-        {
-            var request = new RpcMessage { Id = id, Method = method, Params = parameters };
-            if (!await SendAsync(request, ct))
-            {
-                return Result<JsonElement>.Fail(FleetErrors.NodeOffline, "node is not connected");
-            }
-
-            using var timeout = new CancellationTokenSource(_host.Options.RequestTimeout, _host.Time);
-            using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource(ct, timeout.Token);
-            RpcMessage response = await waiter.Task.WaitAsync(linked.Token);
-            return response.Error is not null
-                ? Result<JsonElement>.Fail(response.Error.ToFleetError())
-                : Result<JsonElement>.Ok(response.Result ?? default);
-        }
-        catch (OperationCanceledException) when (!ct.IsCancellationRequested)
-        {
-            return Result<JsonElement>.Fail(FleetErrors.Timeout, $"{method} timed out");
-        }
-        finally
-        {
-            _pending.TryRemove(id, out _);
-        }
-    }
-
-    // ───────────────────────── 认证 ─────────────────────────
-
-    private async Task<bool> AuthenticateAsync(CancellationToken ct)
-    {
-        string nonce = Convert.ToBase64String(RandomNumberGenerator.GetBytes(32));
-        long expiresAtMs = _host.Time.GetUtcNow().Add(_host.Options.ChallengeTtl).ToUnixTimeMilliseconds();
-        await SendAsync(
-            RpcMessage.Notification(FleetMethods.Challenge, new ChallengeParams { Nonce = nonce, ExpiresAtMs = expiresAtMs }, FleetRpcContext.Default.ChallengeParams),
-            ct);
-
-        using var timeout = new CancellationTokenSource(s_authTimeout, _host.Time);
-        using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource(ct, timeout.Token);
-        Frame? frame;
-        try
-        {
-            frame = await ReceiveFrameAsync(linked.Token);
-        }
-        catch (OperationCanceledException) when (!ct.IsCancellationRequested)
-        {
-            await RejectAsync(null, "auth timeout", ct);
-            return false;
-        }
-
-        if (frame is not { IsText: true } || !TryParse(frame.Data, out RpcMessage? message) || message.Method != FleetMethods.Auth || message.Id is null)
-        {
-            await RejectAsync(null, "expected fleet.auth", ct);
-            return false;
-        }
-
-        AuthParams? auth = null;
-        try
-        {
-            auth = message.Params?.Deserialize(FleetRpcContext.Default.AuthParams);
-        }
-        catch (JsonException)
-        {
-            // 按缺失处理
-        }
-
-        NodeRecord? node = auth is null ? null : await _host.Store.GetNodeAsync(new NodeId(auth.NodeId), ct);
-        bool signatureOk = node is not null
-            && _host.Time.GetUtcNow().ToUnixTimeMilliseconds() <= expiresAtMs
-            && TryDecode(auth!.Signature, out byte[] signature)
-            && NodeIdentity.Verify(node.PublicKey, signature, SignaturePurpose.Auth, auth.NodeId, nonce);
-        if (!signatureOk)
-        {
-            // 节点不存在与签名错误返回同样的错误，不泄露节点是否存在。
-            await RejectAsync(message.Id, "authentication failed", ct);
-            return false;
-        }
-
-        _node = node;
-        if (node!.Status == NodeStatus.Disabled)
-        {
-            await SendAsync(RpcMessage.Failure(message.Id, new FleetError(FleetErrors.NodeDisabled, "node is disabled")), ct);
-            await RevokeAsync("disabled", ct);
-            return false;
-        }
-
-        _session = new NodeSessionInfo(node.Id, _host.Time.GetUtcNow().ToUnixTimeMilliseconds(), node.NodeVersion, [], null);
-        await SendAsync(
-            RpcMessage.Success(message.Id.Value, new AuthResult { Status = StatusName(node.Status) }, FleetRpcContext.Default.AuthResult),
-            ct);
-        return true;
-    }
-
-    private async Task RejectAsync(long? id, string reason, CancellationToken ct)
-    {
-        FleetLog.AuthRejected(_host.Logger, reason);
-        _closeReason ??= reason;
-        if (id is not null)
-        {
-            await SendAsync(RpcMessage.Failure(id, new FleetError(FleetErrors.Unauthorized, "authentication failed")), ct);
-        }
-
-        if (_socket.State == WebSocketState.Open)
-        {
-            try
-            {
-                await _socket.CloseOutputAsync(WebSocketCloseStatus.PolicyViolation, "unauthorized", ct);
-            }
-            catch (WebSocketException)
-            {
-                // 对端已经断开
-            }
-        }
-    }
-
-    // ───────────────────────── 接收循环 ─────────────────────────
-
-    private async Task ReceiveLoopAsync(CancellationToken ct)
-    {
-        while (!ct.IsCancellationRequested)
-        {
-            using var idle = new CancellationTokenSource(_host.Options.HeartbeatTimeout, _host.Time);
-            using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource(ct, idle.Token);
-            Frame? frame;
-            try
-            {
-                frame = await ReceiveFrameAsync(linked.Token);
-            }
-            catch (OperationCanceledException) when (idle.IsCancellationRequested && !ct.IsCancellationRequested)
-            {
-                _closeReason ??= "heartbeat timeout";
-                return;
-            }
-
-            if (frame is null)
-            {
-                _closeReason ??= "closed by peer";
-                return;
-            }
-
-            if (frame.IsText)
-            {
-                if (TryParse(frame.Data, out RpcMessage? message))
-                {
-                    await HandleMessageAsync(message, ct);
-                }
-            }
-            else
-            {
-                await HandleBinaryAsync(frame.Data, ct);
-            }
-        }
-    }
-
-    private async Task HandleMessageAsync(RpcMessage message, CancellationToken ct)
-    {
-        if (message.IsResponse)
-        {
-            if (_pending.TryGetValue(message.Id!.Value, out TaskCompletionSource<RpcMessage>? waiter))
-            {
-                waiter.TrySetResult(message);
-            }
-
-            return;
-        }
-
-        switch (message.Method)
-        {
-            case FleetMethods.Hello:
-                await HandleHelloAsync(message, ct);
-                return;
-            case FleetMethods.Heartbeat:
-                await HandleHeartbeatAsync(message, ct);
-                return;
-        }
-
-        if (_node!.Status != NodeStatus.Active)
-        {
-            if (message.Id is not null)
-            {
-                await SendAsync(RpcMessage.Failure(message.Id, new FleetError(FleetErrors.NodePending, "node is not approved yet")), ct);
-            }
-
-            return;
-        }
-
-        var context = new NodeCallContext(_node, _session!, _host);
-        RpcMessage? response;
-        try
-        {
-            response = await _host.Router.DispatchAsync(context, message, ct);
-        }
-        catch (OperationCanceledException) when (ct.IsCancellationRequested)
-        {
-            throw;
-        }
-
-        if (response is not null)
-        {
-            await SendAsync(response, ct);
-        }
-    }
-
-    private async Task HandleHelloAsync(RpcMessage message, CancellationToken ct)
-    {
-        HelloParams? hello = null;
-        try
-        {
-            hello = message.Params?.Deserialize(FleetRpcContext.Default.HelloParams);
-        }
-        catch (JsonException)
-        {
-            // 按缺失处理
-        }
-
-        if (hello is null)
-        {
-            if (message.Id is not null)
-            {
-                await SendAsync(RpcMessage.Failure(message.Id, new FleetError(FleetErrors.InvalidParams, "invalid hello")), ct);
-            }
-
-            return;
-        }
-
-        long nowMs = _host.Time.GetUtcNow().ToUnixTimeMilliseconds();
-        _session = _session! with
-        {
-            NodeVersion = hello.NodeVersion,
-            Capabilities = hello.Capabilities,
-            HelloMetaJson = hello.Meta?.GetRawText(),
-        };
-        _node = _node! with { NodeVersion = hello.NodeVersion };
-        _helloDone = true;
-
-        await UpdatePresenceAsync(online: true, ct);
-        await FireAsync(NodeEventKind.Hello, ct, hello);
-
-        if (message.Id is not null)
-        {
-            await SendAsync(
-                RpcMessage.Success(
-                    message.Id.Value,
-                    new HelloResult { ServerTimeMs = nowMs, ClockOffsetMs = hello.NowUtcMs - nowMs },
-                    FleetRpcContext.Default.HelloResult),
-                ct);
-        }
-
-        SignalStateChanged();
-    }
-
-    private async Task HandleHeartbeatAsync(RpcMessage message, CancellationToken ct)
-    {
-        JsonElement? extra = null;
-        try
-        {
-            extra = message.Params?.Deserialize(FleetRpcContext.Default.HeartbeatParams)?.Extra;
-        }
-        catch (JsonException)
-        {
-            // 忽略格式不正确的附加字段
-        }
-
-        long now = _host.Time.GetTimestamp();
-        if (_host.Time.GetElapsedTime(Interlocked.Read(ref _lastPresenceTicks), now) >= s_presenceRefresh)
-        {
-            await UpdatePresenceAsync(online: true, ct);
-        }
-
-        await FireAsync(NodeEventKind.Heartbeat, ct, hello: null, extra);
-        if (message.Id is not null)
-        {
-            await SendAsync(new RpcMessage { Id = message.Id, Result = JsonSerializer.SerializeToElement(new EmptyObject(), FleetEmptyObject.Info) }, ct);
-        }
-    }
-
-    private async Task HandleBinaryAsync(byte[] data, CancellationToken ct)
-    {
-        if (_node!.Status != NodeStatus.Active
-            || !OutboxFrame.TryParse(data, out byte channel, out Guid msgId, out ReadOnlyMemory<byte> payload)
-            || !_host.Inboxes.TryGetValue(channel, out IInbox? inbox))
-        {
-            return;
-        }
-
-        InboxOutcome outcome;
-        try
-        {
-            outcome = await inbox.HandleAsync(_node, msgId, payload, ct);
-        }
-        catch (OperationCanceledException) when (ct.IsCancellationRequested)
-        {
-            throw;
-        }
-        catch (Exception ex)
-        {
-            // 没有持久化就不确认，节点会重发。
-            FleetLog.InboxFailed(_host.Logger, ex, _node.Id.Value, channel);
-            return;
-        }
-
-        if (outcome == InboxOutcome.Rejected)
-        {
-            return;
-        }
-
-        var ack = new OutboxAckParams();
-        string id = msgId.ToString();
-        if (outcome == InboxOutcome.Duplicate)
-        {
-            ack.Duplicates.Add(id);
-        }
-        else
-        {
-            ack.Ids.Add(id);
-        }
-
-        await SendAsync(RpcMessage.Notification(FleetMethods.OutboxAck, ack, FleetRpcContext.Default.OutboxAckParams), ct);
-    }
-
-    // ───────────────────────── 状态推送 ─────────────────────────
-
-    private async Task StatePushLoopAsync(CancellationToken ct)
-    {
-        while (await _stateSignal.Reader.WaitToReadAsync(ct))
-        {
-            _stateSignal.Reader.TryRead(out _);
-            bool complete = await PushStateAsync(ct);
-            if (!complete)
-            {
-                await Task.Delay(s_statePushRetry, _host.Time, ct);
-                SignalStateChanged();
-            }
-        }
-    }
-
-    private async Task<bool> PushStateAsync(CancellationToken ct)
-    {
-        NodeRecord? fresh = await _host.Store.GetNodeAsync(_node!.Id, ct);
-        if (fresh is null)
-        {
-            return true;
-        }
-
-        _node = fresh with { NodeVersion = _node.NodeVersion ?? fresh.NodeVersion };
-        if (fresh.Status == NodeStatus.Disabled)
-        {
-            await RevokeAsync("disabled", ct);
-            return true;
-        }
-
-        if (fresh.Status != NodeStatus.Active || !_helloDone)
-        {
-            // pending 不下发状态；还没有 hello 的连接等 hello 之后再推送。
-            return true;
-        }
-
-        bool complete = true;
-        foreach (IStateProvider provider in _host.StateProviders)
-        {
-            StateDocument? document = await provider.GetAsync(_node, ct);
-            if (document is null || (_lastPushedVersion.TryGetValue(provider.Type, out long last) && last == document.Version))
-            {
-                continue;
-            }
-
-            Result<JsonElement> raw = await RequestAsync(
-                FleetMethods.StateSync,
-                JsonSerializer.SerializeToElement(
-                    new StateSyncParams { Type = provider.Type, Version = document.Version, Doc = document.Doc },
-                    FleetRpcContext.Default.StateSyncParams),
-                ct);
-            if (!raw.TryGet(out JsonElement value, out FleetError? error))
-            {
-                FleetLog.StatePushFailed(_host.Logger, _node.Id.Value, provider.Type, error.Code.Value);
-                complete = false;
-                continue;
-            }
-
-            StateSyncResult? result = null;
-            try
-            {
-                result = value.Deserialize(FleetRpcContext.Default.StateSyncResult);
-            }
-            catch (JsonException)
-            {
-                // 按缺失处理
-            }
-
-            if (result is null)
-            {
-                complete = false;
-                continue;
-            }
-
-            _lastPushedVersion[provider.Type] = document.Version;
-            await provider.OnAppliedAsync(_node, document.Version, result, ct);
-        }
-
-        return complete;
-    }
-
-    // ───────────────────────── 帮助方法 ─────────────────────────
-
-    private async Task UpdatePresenceAsync(bool online, CancellationToken ct)
-    {
-        Interlocked.Exchange(ref _lastPresenceTicks, _host.Time.GetTimestamp());
-        await _host.Store.UpdatePresenceAsync(
-            _node!.Id,
-            new Presence(online, _host.Time.GetUtcNow().ToUnixTimeMilliseconds(), _session?.NodeVersion, _session?.Capabilities ?? [], _session?.HelloMetaJson),
-            ct);
-    }
-
-    private async Task FireAsync(NodeEventKind kind, CancellationToken ct, HelloParams? hello = null, JsonElement? extra = null)
-    {
-        var nodeEvent = new NodeEvent(kind, _node!, _host.Time.GetUtcNow().ToUnixTimeMilliseconds(), hello, extra);
-        foreach (INodeEventSink sink in _host.Sinks)
-        {
-            try
-            {
-                await sink.OnEventAsync(nodeEvent, ct);
-            }
-            catch (OperationCanceledException) when (ct.IsCancellationRequested)
-            {
-                throw;
-            }
-            catch (Exception ex)
-            {
-                // 产品的事件处理失败不能影响连接。
-                FleetLog.SinkFailed(_host.Logger, ex, kind.ToString(), _node!.Id.Value);
-            }
-        }
-    }
-
-    private async ValueTask<Frame?> ReceiveFrameAsync(CancellationToken ct)
-    {
-        var writer = new ArrayBufferWriter<byte>(1024);
-        while (true)
-        {
-            Memory<byte> buffer = writer.GetMemory(4096);
-            ValueWebSocketReceiveResult result = await _socket.ReceiveAsync(buffer, ct);
-            if (result.MessageType == WebSocketMessageType.Close)
-            {
-                return null;
-            }
-
-            writer.Advance(result.Count);
-            if (writer.WrittenCount > _host.Options.MaxFrameBytes)
-            {
-                _closeReason ??= "frame too large";
-                await _socket.CloseOutputAsync(WebSocketCloseStatus.MessageTooBig, "frame too large", CancellationToken.None);
-                return null;
-            }
-
-            if (result.EndOfMessage)
-            {
-                return new Frame(result.MessageType == WebSocketMessageType.Text, writer.WrittenSpan.ToArray());
-            }
-        }
-    }
-
-    private static bool TryParse(byte[] data, [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] out RpcMessage? message)
-    {
-        try
-        {
-            message = JsonSerializer.Deserialize(data, FleetRpcContext.Default.RpcMessage);
-            return message is not null;
-        }
-        catch (JsonException)
-        {
-            message = null;
-            return false;
-        }
-    }
-
-    private static bool TryDecode(string text, out byte[] data)
-    {
-        try
-        {
-            data = Convert.FromBase64String(text);
-            return true;
-        }
-        catch (FormatException)
-        {
-            data = [];
-            return false;
-        }
-    }
-
-    private static string StatusName(NodeStatus status) => status switch
-    {
-        NodeStatus.Active => "active",
-        NodeStatus.Pending => "pending",
-        _ => "disabled",
-    };
-
-    private sealed record Frame(bool IsText, byte[] Data);
-}
-
-[System.Text.Json.Serialization.JsonSerializable(typeof(EmptyObject))]
-internal sealed partial class FleetEmptyObjectContext : System.Text.Json.Serialization.JsonSerializerContext;
-
-internal sealed class EmptyObject;
-
-internal static class FleetEmptyObject
-{
-    public static System.Text.Json.Serialization.Metadata.JsonTypeInfo<EmptyObject> Info => FleetEmptyObjectContext.Default.EmptyObject;
 }