feat(runtime): track node lifecycle and QUIC link state

backend/fleet/src/Fleet.Link/FleetLink.cs

@@ -58,6 +58,9 @@ public sealed class FleetLinkOptions
     /// <summary>附加到 <c>fleet.heartbeat</c> 的进程内计数（不能包含主机信息）。</summary>
     public Func<JsonElement?>? HeartbeatExtra { get; init; }
 
+    /// <summary>Optional reason for an orderly client shutdown, so the server can distinguish updates from service stops.</summary>
+    public Func<string>? ShutdownReason { get; init; }
+
     public TimeSpan HeartbeatInterval { get; init; } = TimeSpan.FromSeconds(10);
 
     public int MaxFrameBytes { get; init; } = 16 << 20;
@@ -181,7 +184,8 @@ public sealed class FleetLink
         _secure = transport.Secure;
 
         var session = new RpcSession<LinkContext>(transport, _router, new LinkContext(this), _time);
-        using CancellationTokenSource sessionCts = CancellationTokenSource.CreateLinkedTokenSource(ct);
+        // Keep the active WebSocket receive alive until the planned shutdown marker and Close frame have been sent.
+        using var sessionCts = new CancellationTokenSource();
         Task run = session.RunAsync(sessionCts.Token);
         try
         {
@@ -192,7 +196,7 @@ public sealed class FleetLink
                 NowUtcMs = _time.GetUtcNow().ToUnixTimeMilliseconds(),
                 Meta = _options.HelloMeta?.Invoke(),
             };
-            Result<HelloResult> helloResult = await session.RequestAsync(FleetMethods.Hello, hello, FleetRpcContext.Default.HelloParams, FleetRpcContext.Default.HelloResult, sessionCts.Token);
+            Result<HelloResult> helloResult = await session.RequestAsync(FleetMethods.Hello, hello, FleetRpcContext.Default.HelloParams, FleetRpcContext.Default.HelloResult, ct);
             if (!helloResult.IsSuccess)
             {
                 return "hello failed: " + helloResult.Error.Code;
@@ -208,7 +212,23 @@ public sealed class FleetLink
                 await OnConnected(session, sessionCts.Token);
             }
 
-            Task finished = await Task.WhenAny(run, pump, heartbeat);
+            Task cancellation = Task.Delay(Timeout.Infinite, ct);
+            Task finished = await Task.WhenAny(run, pump, heartbeat, cancellation);
+            if (ct.IsCancellationRequested)
+            {
+                try
+                {
+                    using var closeTimeout = new CancellationTokenSource(TimeSpan.FromSeconds(1), _time);
+                    string reason = _options.ShutdownReason?.Invoke() ?? "stopping";
+                    await session.NotifyAsync(FleetMethods.Stopping, new StoppingParams { Reason = reason }, FleetRpcContext.Default.StoppingParams, closeTimeout.Token);
+                    await session.CloseAsync(reason, closeTimeout.Token);
+                }
+                catch (Exception ex) when (ex is OperationCanceledException or WebSocketException or IOException or ObjectDisposedException or InvalidOperationException)
+                {
+                    // The socket may already be gone; shutdown must still complete.
+                }
+            }
+
             await sessionCts.CancelAsync();
             await Task.WhenAll(Quiet(run), Quiet(pump), Quiet(heartbeat));
             return finished == run ? "closed by server" : "link task failed";